Merge bf0993c into 9b4a01e

.eslintrc.js

@@ -13,6 +13,7 @@ module.exports = {
         "import/resolver": "@tophat/eslint-import-resolver-require",
         "jsdoc": {
             "preferredTypes": {
+                "*": "Any",
                 "array": "Array",
                 "boolean": "Boolean",
                 "date": "Date",
@@ -49,6 +50,7 @@ module.exports = {
             "error", {
                 "definedTypes": [
                     "Action",
+                    "Any",
                     "GeneratorFunction"
                 ]
             }

package.json

@@ -49,10 +49,10 @@
         "test": "gulp test"
     },
     "sideEffects": false,
-    "version": "0.1.1-beta.1",
+    "version": "0.1.1-beta.2",
     "dependencies": {
         "@babel/runtime-corejs3": "^7.16.5",
-        "@cgnal/utils": "^0.1.4",
+        "@cgnal/utils": "^0.1.5",
         "core-js": "^3.19.3",
         "lamb": "^0.60.0",
         "redux-actions": "^2.6.5",
@@ -66,7 +66,7 @@
         "del": "^6.0.0",
         "docdash": "^1.2.0",
         "eslint-plugin-import": "^2.25.3",
-        "eslint-plugin-jsdoc": "^37.2.0",
+        "eslint-plugin-jsdoc": "^37.2.3",
         "gulp": "^4.0.2",
         "gulp-eslint-new": "^1.1.0",
         "gulp-jest": "^4.0.4",

src/actions/__tests__/createHttpFailureAction.spec.js

@@ -2,15 +2,27 @@ import { createHttpFailureAction } from "../index";
 
 describe("createHttpFailureAction", () => {
     it("should build an action creator that uses its second argument to set the `originalAction` key of its metadata", () => {
-        const fakeMeta = { b: 2 };
-        const fakePayload = { a: 1 };
-        const errorAction = {
-            meta: { originalAction: fakeMeta },
-            payload: fakePayload,
-            type: "SOME_TYPE"
-        };
-        const creator = createHttpFailureAction(errorAction.type);
+        const originalAction = { type: "ORIGINAL_ACTION" };
+        const error = new Error("some message");
+        const createErrorAction = createHttpFailureAction("API_CALL_KO");
 
-        expect(creator(fakePayload, fakeMeta)).toStrictEqual(errorAction);
+        expect(createErrorAction(error, originalAction)).toStrictEqual({
+            error: true,
+            meta: { originalAction },
+            payload: error,
+            type: "API_CALL_KO"
+        });
+    });
+
+    it("should set an `undefined` original action property if the creator doesn't receive one", () => {
+        const error = new Error("some message");
+        const createErrorAction = createHttpFailureAction("API_CALL_KO");
+
+        expect(createErrorAction(error)).toStrictEqual({
+            error: true,
+            meta: { originalAction: void 0 },
+            payload: error,
+            type: "API_CALL_KO"
+        });
     });
 });

src/actions/__tests__/createHttpSuccessAction.spec.js

@@ -17,4 +17,20 @@ describe("createHttpSuccessAction", () => {
 
         expect(creator(fakeResponse, fakeOriginalAction)).toStrictEqual(successAction);
     });
+
+    it("should set an `undefined` original action property if the creator doesn't receive one", () => {
+        const fakeResponse = {
+            body: { a: 1 },
+            status: 200
+        };
+        const successAction = {
+            meta: { originalAction: void 0, response: fakeResponse },
+            payload: fakeResponse.body,
+            type: "SOME_SUCCESS_TYPE"
+        };
+
+        const creator = createHttpSuccessAction(successAction.type);
+
+        expect(creator(fakeResponse)).toStrictEqual(successAction);
+    });
 });

src/actions/createActionWithSource.js

@@ -7,11 +7,25 @@ import { putInKey } from "@cgnal/utils/object";
  * Builds an action creator that accepts an {@link Action}
  * as the second optional parameter that will be
  * put in the `sourceAction` property of the metadata.
+ * @example
+ * const payload = [1, 2, 3];
+ * const sourceAction = { type: "SOURCE_ACTION" };
+ * const createSomeAction = createActionWithSource("SOME_ACTION");
+ *
+ * createSomeAction(payload, sourceAction) // =>
+ * // {
+ * //     meta: {
+ * //         sourceAction: { type: "SOURCE_ACTION" }
+ * //     },
+ * //     payload: [1, 2, 3],
+ * //     type: "SOME_ACTION"
+ * // }
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.19
  * @function
  * @param {String} type
- * @returns {Function}  The action creator: <code>(*, {@link Action}?) => {@link Action}</code>
+ * @returns {Function}  The action creator: <code>(Any, {@link Action}?) => {@link Action}</code>
  */
 const createActionWithSource = type => createAction(
     type,

src/actions/createEmptyAction.js

@@ -5,6 +5,11 @@ import { nullary } from "@cgnal/utils/function";
 /**
  * Builds an action creator to make a [flux standard action]{@link https://github.com/acdlite/flux-standard-action}
  * without any payload or metadata.
+ * @example
+ * const createSomeAction = createEmptyAction("SOME_ACTION");
+ *
+ * createSomeAction([1, 2, 3]) // => { type: "SOME_ACTION" }
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.12
  * @function

src/actions/createHttpFailureAction.js

@@ -11,12 +11,37 @@ import { putInKey } from "@cgnal/utils/object";
  * second parameter.<br/>
  * The resulting action will have an additional <code>meta</code> property, which
  * will be an object with a single key <code>originalAction</code>.
+ * @example
+ * const originalAction = { type: "ORIGINAL_ACTION" };
+ * const failure = new Error("some message");
+ * const createErrorAction = createHttpFailureAction("API_CALL_KO");
+ *
+ * createErrorAction(failure, originalAction) // =>
+ * // {
+ * //     error: true,
+ * //     meta: {
+ * //         originalAction: { type: "ORIGINAL_ACTION" }
+ * //     },
+ * //     payload: Error, // the "failure" error above
+ * //     type: "API_CALL_KO"
+ * // }
+ *
+ * createErrorAction(failure) // =>
+ * // {
+ * //     error: true,
+ * //     meta: {
+ * //         originalAction: undefined
+ * //     },
+ * //     payload: Error, // the "failure" error above
+ * //     type: "API_CALL_KO"
+ * // }
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.1
  * @function
  * @param {String} type The action type
  * @returns {Function} The action creator:
- * <code>(payload: Error, originalAction: {@link Action}) => {@link Action}</code>
+ * <code>(Error, {@link Action}?) => {@link Action}</code>
  */
 const createHttpFailureAction = type => createAction(
     type,

src/actions/createHttpSuccessAction.js

@@ -7,11 +7,32 @@ import { createAction } from "redux-actions";
  * The action creator expects a successful HTTP Response and will put its body in the action payload.<br/>
  * The metadata will be an object with the complete Response in the <code>response</code> property,
  * and the original action in the <code>originalAction</code> one.
+ * @example
+ * const originalAction = { type: "ORIGINAL_ACTION" };
+ * const response = {
+ *     body: [1, 2, 3],
+ *     status: 200
+ * };
+ * const createSuccessAction = createHttpSuccessAction("API_CALL_OK");
+ *
+ * createSuccessAction(response, originalAction) // =>
+ * // {
+ * //     meta: {
+ * //         originalAction: { type: "ORIGINAL_ACTION" },
+ * //         response: {
+ * //             body: [1, 2, 3],
+ * //             status: 200
+ * //         }
+ * //     },
+ * //     payload: [1, 2, 3],
+ * //     type: "API_CALL_OK"
+ * // }
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.7
  * @function
  * @param {String} type The action type
- * @returns {Function} The action creator: <code>Response => {@link Action}</code>
+ * @returns {Function} The action creator: <code>(Response, {@link Action}?) => {@link Action}</code>
  */
 const createHttpSuccessAction = type => createAction(
     type,

src/actions/getPayloadAsArray.js

@@ -1,6 +1,14 @@
 /**
  * Returns the payload of the received Action wrapped
  * in a one element array.
+ * @example
+ * const action = {
+ *     payload: { value: 1 },
+ *     type: "SOME_TYPE"
+ * };
+ *
+ * getPayloadAsArray(action) => // [{ value : 1 }]
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.19
  * @param {Action} action

src/actions/isHttpUnauthorizedAction.js

@@ -3,6 +3,28 @@ import * as _ from "lamb";
 /**
  * Checks if the received action contains
  * an unauthorized HTTP error (401)
+ * @example
+ * const fake401Error = { status: 401 };
+ * const fake500Error = { status: 500 };
+ * const action1 = {
+ *     error: true,
+ *     payload: fake401Error,
+ *     type: "API_CALL_KO"
+ * };
+ * const action2 = {
+ *     payload: fake401Error,
+ *     type: "API_CALL_KO"
+ * };
+ * const action3 = {
+ *     error: true,
+ *     payload: fake500Error,
+ *     type: "API_CALL_KO"
+ * };
+ *
+ * isHttpUnauthorizedAction(action1) // => true
+ * isHttpUnauthorizedAction(action2) // => false
+ * isHttpUnauthorizedAction(action3) // => false
+ *
  * @memberof module:@cgnal/redux/actions
  * @since 0.0.19
  * @function

src/reducers/combine.js

@@ -3,6 +3,18 @@ import * as _ from "lamb";
 /**
  * Accepts a list of function meant to act on the same portion
  * of a state, and combines them to produce a new state.
+ * @example
+ * const state = {
+ *     counter: 0,
+ *     values: [1, 2]
+ * };
+ * const incrementCounter = state => ({ ...state, counter: state.counter + 1 });
+ * const addValue = (state, action) => ({ ...state, values: state.values.concat(action.payload) });
+ * const action = { payload: 3, type: "ADD_VALUE" };
+ * const combinedUpdate = combine([incrementCounter, addValue]);
+ *
+ * combinedUpdate(state, action) // => { counter: 1, values: [1, 2, 3] }
+ *
  * @memberof module:@cgnal/redux/reducers
  * @since 0.0.20
  * @function

src/reducers/handleHttpFailure.js

@@ -4,7 +4,37 @@ import * as _ from "lamb";
  * Utility function to handle a common case of change
  * in the store when a HTTP requests completes successfully.
  * Resets loading path to `false` and sets a data path with
- * the HTTP result, optionally using a transformer function.
+ * the HTTP result, optionally using a transformer function.<br/>
+ * Path strings are paths supplied to Lamb's {@link https://ascartabelli.github.io/lamb/module-lamb.html#setPathIn|setPathIn},
+ * implying that a dot is used as a separator (e.g. `"view.isLoading"`).
+ * @example
+ * const state = {
+ *     data: [],
+ *     error: null,
+ *     isLoading: true
+ * };
+ * const action = {
+ *     error: true,
+ *     payload: new Error("some error"),
+ *     meta: {
+ *         originalAction: { type: "DATA_GET" }
+ *     },
+ *     type: "DATA_GET_KO"
+ * };
+ * const handler = handleHttpFailure(); // using default values
+ *
+ * handler(state, action) // =>
+ * // {
+ * //     data: [],
+ * //     error: {
+ * //         message: "Error during the HTTP request.",
+ * //         originalAction: { type: "DATA_GET" },
+ * //         originalError: Error, // the above action's payload
+ * //         title: "HTTP Error"
+ * //     },
+ * //     isLoading: false
+ * // }
+ *
  * @memberof module:@cgnal/redux/reducers
  * @since 0.0.20
  * @function

src/reducers/handleHttpStart.js

@@ -11,7 +11,30 @@ const safeSetPath = _.condition(
 /**
  * Utility function to handle a common case of change
  * in the store when a HTTP requests starts.
- * Resets an error path and set a loading path to `true`.
+ * Resets an error path and set a loading path to `true`.<br/>
+ * Path strings are paths supplied to Lamb's {@link https://ascartabelli.github.io/lamb/module-lamb.html#setPathIn|setPathIn},
+ * implying that a dot is used as a separator (e.g. `"view.isLoading"`).
+ * @example
+ * const state = {
+ *     data: [],
+ *     error: {
+ *         message: "Error during the HTTP request.",
+ *         originalAction: { type: "DATA_GET" },
+ *         originalError: new Error("some message")
+ *         title: "HTTP Error"
+ *     },
+ *     isLoading: false
+ * };
+ * const action = { type: "DATA_GET" };
+ * const handler = handleHttpStart(); // using default values
+ *
+ * // handler(state, action) // =>
+ * // {
+ * //     data: [],
+ * //     error: null,
+ * //     isLoading: true
+ * // }
+ *
  * @memberof module:@cgnal/redux/reducers
  * @since 0.0.20
  * @function