diff --git a/docs.md b/docs.md index b4a914d..ca7ce48 100644 --- a/docs.md +++ b/docs.md @@ -46,22 +46,21 @@ export { selectors } // These selectors can be called in mapStateToProps() like so: // selectors.user(state) => { name: 'test' } // selectors.username(state) => 'test' - - -* ``` -Returns **[Function][11]** A function that can be used to create state selectors. +Returns **SliceSelector** A function that can be used to create state selectors. ## setState A helper function for creating simple "setter" reducers. Given a path, it sets the state at that path to the payload of an action. +Type: [Function][11] + ### Parameters -* `path` **[String][10]** Path to the part of the state that will be set -* `transform` **[Function][11]** A function with arguments `(action, state, slice)` that can be used to transform the value that will be set. `slice` is the data, if any, that already exists in the state at `path`. The default transform function simply returns the action's payload. To set the state to a constant value, simply pass the value in place of the transform function. +* `path` **[string][10]** Path to the part of the state that will be set +* `transform` **StateTransform?** A function with arguments `(action, state, slice)` that can be used to transform the value that will be set. `slice` is the data, if any, that already exists in the state at `path`. The default transform function simply returns the action's payload. To set the state to a constant value, simply pass the value in place of the transform function. ### Examples @@ -79,20 +78,18 @@ const reducer = handleActions({ [doubleExistingCount]: setState('count', (action, state, count) => count * 2) [resetCount]: setState('count', 0) }) - -* ``` -Returns **[Function][11]** A function that can be used in a reducer to handle an action. - ## unsetState A helper function for creating simple reducers that "unset" a piece of state. Given a path, it calls lodash [unset ][12] on the state at that path. +Type: [Function][11] + ### Parameters -* `path` **[String][10]** Path to the part of state to unset +* `path` **[string][10]** Path to the part of state to unset ### Examples @@ -105,8 +102,6 @@ const clearCount = createAction('CLEAR_COUNT') const reducer = handleActions({ [clearCount]: unsetState('count'), }) - -* ``` Returns **[Function][11]** A function that can be used in a reducer to handle an action. diff --git a/package.json b/package.json index 5cd3c22..fa16852 100644 --- a/package.json +++ b/package.json @@ -5,14 +5,15 @@ "main": "lib/index.js", "scripts": { "start": "yarn install && yarn run build:development", - "build": "mkdir -p lib && babel src --out-dir lib --no-comments --minified", + "build": "mkdir -p lib && babel src --out-dir lib --no-comments --minified && yarn run types", "build:development": "mkdir -p lib && babel src --watch --out-dir lib", "clean": "rm -rf lib", "docs": "documentation build src/index.js -f md -o docs.md", "lint": "eslint src --max-warnings=0", "prepublishOnly": "yarn run lint", "test": "jest --coverage", - "prepare": "husky install && yarn run clean && yarn run build" + "prepare": "husky install && yarn run clean && yarn run build", + "types": "tsc" }, "repository": "launchpadlab/lp-redux-utils", "homepage": "https://github.com/launchpadlab/lp-redux-utils", @@ -30,6 +31,7 @@ "LICENSE.md", "lib/" ], + "types": "lib/types", "devDependencies": { "@babel/cli": "^7.22.9", "@babel/core": "^7.22.9", @@ -39,7 +41,8 @@ "eslint": "^8.0.0", "husky": "^8.0.0", "jest": "^29.0.0", - "redux": "^4.0.0" + "redux": "^4.0.0", + "typescript": "^5.1.6" }, "dependencies": { "lodash": "^4.17.4" diff --git a/src/index.js b/src/index.js index 1bb4b01..29e2bd2 100644 --- a/src/index.js +++ b/src/index.js @@ -1,3 +1,3 @@ -export selectorForSlice from './selectorForSlice' -export setState from './setState' -export unsetState from './unsetState' \ No newline at end of file +export { default as selectorForSlice } from './selectorForSlice' +export { default as setState } from './setState' +export { default as unsetState } from './unsetState' \ No newline at end of file diff --git a/src/selectorForSlice.js b/src/selectorForSlice.js index 86dd6f5..dbf5695 100644 --- a/src/selectorForSlice.js +++ b/src/selectorForSlice.js @@ -5,8 +5,7 @@ import { getOr } from 'lodash/fp' * Given the path of a certain state slice, returns a function that can be used to create state selectors (helpful for `mapStateToProps()`). * * @param {String} slicePath - Path to slice of state. - * @returns {Function} - A function that can be used to create state selectors. - * + * @returns {SliceSelector} A function that can be used to create state selectors. * * @example * @@ -34,8 +33,7 @@ import { getOr } from 'lodash/fp' * // selectors.user(state) => { name: 'test' } * // selectors.username(state) => 'test' * - * -**/ + */ export default function selectorForSlice (slicePath) { return function createSelector (path, defaultValue) { @@ -44,3 +42,11 @@ export default function selectorForSlice (slicePath) { } } } + +/** + * @ignore + * @callback SliceSelector + * @param {string} path - A relative path + * @param {any=} defaultValue - A default value + * @returns {(state:object) => any} The value at the slice's nested path (`slicePath.path`) or the default value provided + */ diff --git a/src/setState.js b/src/setState.js index 18e5ad6..2adae7c 100644 --- a/src/setState.js +++ b/src/setState.js @@ -3,20 +3,20 @@ import { set, get } from 'lodash/fp' /** * - * A helper function for creating simple "setter" reducers. + * A helper function for creating simple "setter" reducers. * Given a path, it sets the state at that path to the payload of an action. * * @name setState - * @type Function - * @param {String} path - Path to the part of the state that will be set - * @param {Function} transform - A function with arguments `(action, state, slice)` that can be used to transform the value that will be set. `slice` is the data, if any, that already exists in the state at `path`. The default transform function simply returns the action's payload. To set the state to a constant value, simply pass the value in place of the transform function. - * @returns {Function} - A function that can be used in a reducer to handle an action. + * @type {Function} + * @param {string} path - Path to the part of the state that will be set + * @param {StateTransform} [transform=] - A function with arguments `(action, state, slice)` that can be used to transform the value that will be set. `slice` is the data, if any, that already exists in the state at `path`. The default transform function simply returns the action's payload. To set the state to a constant value, simply pass the value in place of the transform function. + * @returns {(state:any, action:Action) => any } A function that can be used in a reducer to handle an action. * * @example * * import { setState } from 'lp-redux-utils' * import { createAction, handleActions } from 'redux-actions' - * + * * const setCount = createAction('SET_COUNT') * const setCountInverse = createAction('SET_COUNT_INVERSE') * const doubleExistingCount = createAction('DOUBLE_EXISTING_COUNT') @@ -28,12 +28,7 @@ import { set, get } from 'lodash/fp' * [resetCount]: setState('count', 0) * }) * -**/ - -function defaultTransform (action) { - return get('payload', action) -} - + */ function setState (path, transform=defaultTransform) { return function reducer (state, action) { const slice = get(path, state) @@ -42,4 +37,24 @@ function setState (path, transform=defaultTransform) { } } +function defaultTransform (action) { + return get('payload', action) +} + +/** + * @ignore + * @callback StateTransform + * @param {Action} action - The action dispatched to the store + * @param {any} state - The current Redux store state + * @param {any} slice - The data, if any, that already exists in the state at `path` + * @returns {any} The value to set in the path + */ + +/** + * @ignore + * @typedef Action + * @property {string} type - The action type + * @property {any=} payload - Additional data provided with the action + */ + export default setState \ No newline at end of file diff --git a/src/unsetState.js b/src/unsetState.js index a2f9673..1bc151d 100644 --- a/src/unsetState.js +++ b/src/unsetState.js @@ -1,27 +1,25 @@ import { unset } from 'lodash/fp' /** - * * A helper function for creating simple reducers that "unset" a piece of state. * Given a path, it calls lodash {@link https://lodash.com/docs/#unset|unset } on the state at that path. * * @name unsetState - * @type Function - * @param {String} path - Path to the part of state to unset - * @returns {Function} - A function that can be used in a reducer to handle an action. + * @type {Function} + * @param {string} path - Path to the part of state to unset + * @returns {Function} A function that can be used in a reducer to handle an action. * * @example * * import { unsetState } from 'lp-redux-utils' * import { createAction, handleActions } from 'redux-actions' - * + * * const clearCount = createAction('CLEAR_COUNT') * * const reducer = handleActions({ * [clearCount]: unsetState('count'), * }) - * -**/ + */ function unsetState (path) { return function reducer (state) { diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..2aed394 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,12 @@ +{ + "include": ["src"], + "exclude": ["lib", "node_modules"], + "compilerOptions": { + "declaration": true, + "emitDeclarationOnly": true, + "allowJs": true, + "outDir": "lib/types", + "declarationMap": true, + "skipLibCheck": true + } +} \ No newline at end of file diff --git a/yarn.lock b/yarn.lock index d9db8a3..68fbf42 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5644,6 +5644,11 @@ typed-array-length@^1.0.4: for-each "^0.3.3" is-typed-array "^1.1.9" +typescript@^5.1.6: + version "5.2.2" + resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.2.2.tgz#5ebb5e5a5b75f085f22bc3f8460fba308310fa78" + integrity sha512-mI4WrpHsbCIcwT9cF4FZvr80QUeKvsUsUvKDoR+X/7XHQH98xYD8YHZg7ANtz2GtZt/CBq2QJ0thkGJMHfqc1w== + unbox-primitive@^1.0.2: version "1.0.2" resolved "https://registry.yarnpkg.com/unbox-primitive/-/unbox-primitive-1.0.2.tgz#29032021057d5e6cdbd08c5129c226dff8ed6f9e"