@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/config/objectCrud.js

@@ -9,173 +9,180 @@ import { readonly } from "vue";
  */
 
 /**
- * @typedef {{[key:string]: any}} TargetArgs
+ * @typedef {{[key:string]: any}} TargetArgs - Implementation-specific arguments passed through to the CRUD handlers, such as endpoint identifiers.
  */
 
 /**
- * Additional arguments that can be passed to CRUD handlers.
- *
- * @typedef {{[key:string]: any}} AdditionalCrudArgs
+ * @typedef {{[key:string]: any}} AdditionalCrudArgs - Additional arguments that can be passed to CRUD handlers.
  */
 
 /**
- * Defines the CRUD-related handlers and additional utilities provided by the object instance.
- *
- * @typedef {object} ObjectTargetProperties
+ * @typedef {object} ObjectTargetProperties - Defines the CRUD-related handlers and additional utilities provided by the object instance.
  * @property {TargetArgs} args - The arguments to be passed to the crud handlers.
  */
 
 /**
- * @typedef {object} ObjectTargetOption
+ * @typedef {object} ObjectTargetOption - Optional target arguments passed through to the object CRUD handlers.
  * @property {TargetArgs} [target={}] - The arguments to be passed to the crud handlers.
  */
 
 /**
- * @typedef {object} CreateArgsRaw
+ * @typedef {object} CreateArgsRaw - Raw arguments for an object create operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {{[key:string]: any}} object - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} object - The new object to create; it carries no primary key yet.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {CreateArgsRaw & AdditionalCrudArgs} CreateArgs
+ * @typedef {CreateArgsRaw & AdditionalCrudArgs} CreateArgs - Arguments for an object create operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} RetrieveArgsRaw
+ * @typedef {object} RetrieveArgsRaw - Raw arguments for an object retrieve operation before run-tracking and additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {RetrieveArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalCrudArgs} RetrieveArgs
+ * @typedef {RetrieveArgsRaw & Partial<import('../use/cancellableIntent.js').CommonRunTracking> & AdditionalCrudArgs} RetrieveArgs - Arguments for an object retrieve operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} UpdateArgsRaw
+ * @typedef {object} UpdateArgsRaw - Raw arguments for an object update operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {import('../use/objectInstance.js').ExistingCrudObject} object - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {import('../use/objectInstance.js').ExistingCrudObject} object - The complete object to update; its primary key rides inside it, at `object[pkKey]`.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {string} pkKey - The key name of the primary key.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {UpdateArgsRaw & AdditionalCrudArgs} UpdateArgs
+ * @typedef {UpdateArgsRaw & AdditionalCrudArgs} UpdateArgs - Arguments for an object update operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} DeleteArgsRaw
+ * @typedef {object} DeleteArgsRaw - Raw arguments for an object delete operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {DeleteArgsRaw & AdditionalCrudArgs} DeleteArgs
+ * @typedef {DeleteArgsRaw & AdditionalCrudArgs} DeleteArgs - Arguments for an object delete operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} PartialArgsRaw
+ * @typedef {object} PartialArgsRaw - Raw arguments for an object patch (partial update) operation before additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} partialObject - The data to be acted upon.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {{[key:string]: any}} partialObject - The changed fields only.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 /**
- * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs
+ * @typedef {PartialArgsRaw & AdditionalCrudArgs} PartialArgs - Arguments for an object patch (partial update) operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @typedef {object} ObjectExecuteActionArgsRaw
- * @property {import('../config/objectCrud.js').TargetArgs} target - The arguments to be passed to the crud handlers.
- * @property {string} pk - The id of the objects to be acted upon.
+ * @typedef {object} ObjectExecuteActionArgsRaw - Raw arguments for a single-object execute-action operation before additional CRUD arguments are merged in.
+ * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
+ * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
  * @property {string} action - The action to execute.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {ObjectExecuteActionArgsRaw & AdditionalCrudArgs} ObjectExecuteActionArgs
+ * @typedef {ObjectExecuteActionArgsRaw & AdditionalCrudArgs} ObjectExecuteActionArgs - Arguments for a single-object execute-action operation, combining the raw arguments with any additional CRUD arguments.
  */
 
 /**
- * @callback CrudSubscribeCallback
+ * @callback CrudSubscribeCallback - Callback invoked with the changed object and the action (create, update, or delete) when a subscribed object changes.
  * @param {import('../use/objectInstance.js').ExistingCrudObject} data - The data to be passed to the callback.
  * @param {"delete"|"update"|"create"} action - The action that was performed.
  */
 
 /**
- * @typedef {object} ObjectSubscribeArgsRaw
+ * @typedef {object} ObjectSubscribeArgsRaw - Raw arguments for a single-object subscribe operation before run-tracking and additional CRUD arguments are merged in.
  * @property {TargetArgs} target - The arguments to be passed to the crud handlers.
  * @property {import('./commonCrud.js').Pk} pk - The pk of the object to be acted upon.
  * @property {string} pkKey - The key name of the primary key.
- * @property {{[key:string]: any}} params - The arguments to be passed to the retrieve function.
+ * @property {{[key:string]: any}} params - Your listing or retrieval arguments, passed through to the crud handlers.
  * @property {CrudSubscribeCallback} callback - The callback to be called when the object is updated.
- * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A ref to indicate if the request was cancelled.
+ * @property {Readonly<import('vue').Ref<boolean>>} isCancelled - A readonly ref that becomes true once the request is cancelled.
  */
 
 /**
- * @typedef {ObjectSubscribeArgsRaw & import('../use/cancellableIntent.js').CommonRunTracking & AdditionalCrudArgs} ObjectSubscribeArgs
+ * @typedef {ObjectSubscribeArgsRaw & import('../use/cancellableIntent.js').CommonRunTracking & AdditionalCrudArgs} ObjectSubscribeArgs - Arguments for a single-object subscribe operation, combining the raw arguments with run-tracking and any additional CRUD arguments.
  */
 
 /**
- * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string>} CrudResponse
+ * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object>} CrudResponse -
+ *  The value returned by an object CRUD handler whose resolved value becomes the record: create, retrieve, update, and
+ *  patch. A possibly-cancellable promise resolving to the complete record. The instance mirrors the resolved value
+ *  into `state.object`, so a partial record drops the fields it omits, and a resolved value that is not an object (a
+ *  bare primary key string, for instance) fails the assignment and is stored in `state.error`.
  */
 
 /**
- * @callback CrudCreateFn
+ * @typedef {import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|void>} CrudCompletionResponse -
+ *  The value returned by an object CRUD handler whose resolved value is ignored: delete, and executeAction. A
+ *  possibly-cancellable promise whose resolution signals success and nothing more, so it may resolve a record, a
+ *  primary key string, or nothing at all.
+ */
+
+/**
+ * @callback CrudCreateFn - Signature for the handler that creates an object in the backing store.
  * @param {CreateArgs} args - The arguments to be passed to the create function.
- * @returns {CrudResponse} - The response data from the create function.
+ * @returns {CrudResponse} - A promise resolving the created record in full.
  */
 
 /**
- * @callback CrudRetrieveFn
+ * @callback CrudRetrieveFn - Signature for the handler that retrieves an object from the backing store.
  * @param {RetrieveArgs} args - The arguments to be passed to the retrieve function.
- * @returns {CrudResponse} - The response data from the retrieve function.
+ * @returns {CrudResponse} - A promise resolving the retrieved record in full.
  */
 
 /**
- * @callback CrudUpdateFn
+ * @callback CrudUpdateFn - Signature for the handler that updates an object in the backing store.
  * @param {UpdateArgs} args - The arguments to be passed to the update function.
- * @returns {CrudResponse} - The response data from the update function.
+ * @returns {CrudResponse} - A promise resolving the updated record in full.
  */
 
 /**
- * @callback CrudPatchFn
+ * @callback CrudPatchFn - Signature for the handler that partially updates (patches) an object in the backing store.
  * @param {PartialArgs} args - The arguments to be passed to the patch function.
- * @returns {CrudResponse} - The response data from the patch function.
+ * @returns {CrudResponse} - A promise resolving the patched record in full, not just the changed fields.
  */
 
 /**
- * @callback CrudDeleteFn
+ * @callback CrudDeleteFn - Signature for the handler that deletes an object from the backing store.
  * @param {DeleteArgs} args - The arguments to be passed to the delete function.
- * @returns {CrudResponse} - The response data from the delete function.
+ * @returns {CrudCompletionResponse} - A promise whose resolution means the delete succeeded; its value is ignored.
  */
 
 /**
- * @callback CrudObjectExecuteActionFn
+ * @callback CrudObjectExecuteActionFn - Signature for the handler that executes an action on a single object in the backing store.
  * @param {ObjectExecuteActionArgs} args - The arguments to be passed to the executeAction function.
- * @returns {CrudResponse} - The response data from the delete function.
+ * @returns {CrudCompletionResponse} - A promise whose resolution means the action succeeded; its value is ignored, and
+ *  `objectInstance.executeAction` resolves `true`.
  */
 
 /**
- * @callback CrudObjectSubscribeFn
+ * @callback CrudObjectSubscribeFn - Signature for the handler that subscribes to changes on a single object in the backing store.
  * @param {ObjectSubscribeArgs} args - The arguments to be passed to the subscribe function.
  * @returns {import('../utils/cancellablePromise.js').CancellablePromise<void>} - The cancellable promise.
  */
 
 /**
- * Defines the CRUD-related handlers and additional utilities provided by the object instance.
- *
- * @typedef {object} ObjectCrudHandlers
+ * @typedef {object} ObjectCrudHandlers - Defines the CRUD-related handlers and additional utilities provided by the object instance.
  * @property {CrudCreateFn} [create] - A function to be used instead of the default crud create function.
  * @property {CrudRetrieveFn} [retrieve] - A function to be used instead of the default crud retrieve function.
  * @property {CrudUpdateFn} [update] - A function to be used instead of the default crud update function.
@@ -187,9 +194,7 @@ import { readonly } from "vue";
  */
 
 /**
- * The CRUD arguments.
- *
- * @typedef {ObjectTargetProperties & ObjectCrudHandlers} ObjectTarget
+ * @typedef {ObjectTargetProperties & ObjectCrudHandlers} ObjectTarget - The CRUD arguments.
  *
  */
 

package/package.json

@@ -1,91 +1,105 @@
 {
-    "name": "@arrai-innovations/reactive-helpers",
-    "version": "21.1.2",
-    "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
-    "main": "index.js",
-    "type": "module",
-    "types": "types/index.d.ts",
-    "exports": {
-        ".": {
-            "import": "./index.js",
-            "types": "./types/index.d.ts"
-        }
-    },
-    "files": [
-        "index.js",
-        "README.md",
-        "use/",
-        "utils/",
-        "config/",
-        "types/"
-    ],
-    "directories": {
-        "use": "use",
-        "utils": "utils",
-        "tests": "tests"
-    },
-    "scripts": {
-        "test": "npx --no-install vitest",
-        "eslint": "npx --no-install eslint --fix index.js config/**/*.js tests/**/*.js use/**/*.js utils/**/*.js",
-        "prettier": "npx --no-install prettier --write .",
-        "coverage": "npm test -- run --coverage=true",
-        "prepare": "npx --no-install husky",
-        "docs": "node make_type_doc.js",
-        "docs:check": "node check_type_doc.js",
-        "docs:clean": "node clean_type_doc.js",
-        "types": "node make_types.js",
-        "types:check": "node check_types.js"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/arrai-innovations/reactive-helpers.git"
-    },
-    "author": "Arrai Innovations Inc. <developers@arrai.com>",
-    "license": "UNLICENSED",
-    "bugs": {
-        "url": "https://github.com/arrai-innovations/reactive-helpers/issues"
-    },
-    "homepage": "https://github.com/arrai-innovations/reactive-helpers#readme",
-    "devDependencies": {
-        "@arrai-innovations/commitlint-config": "^2.0.0",
-        "@commitlint/cli": "^19.4.0",
-        "@godaddy/dmd": "^1.0.4",
-        "@trivago/prettier-plugin-sort-imports": "^5.2.1",
-        "@types/browser-util-inspect": "^0.2.4",
-        "@types/lodash-es": "^4.17.12",
-        "@typescript-eslint/eslint-plugin": "^7.18.0",
-        "@typescript-eslint/parser": "^7.18.0",
-        "@vitest/coverage-istanbul": "^3.1.4",
-        "@vitest/coverage-v8": "^3.1.4",
-        "@vue/compiler-sfc": "^3.4.37",
-        "@vue/eslint-config-prettier": "^9.0.0",
-        "@vue/test-utils": "^2.3.2",
-        "doctoc": "^2.1.0",
-        "eslint": "^8.56.0",
-        "eslint-plugin-jsdoc": "^48.11.0",
-        "eslint-plugin-vitest": "~0.5.4",
-        "eslint-plugin-vitest-globals": "^1.3.1",
-        "eslint-plugin-vue": "^9.27.0",
-        "flush-promises": "^1.0.2",
-        "globals": "^16.0.0",
-        "husky": "^9.1.7",
-        "jsdom": "^26.0.0",
-        "lint-staged": "^15.2.8",
-        "prettier": "^3.3.3",
-        "typedoc": "^0.28.15",
-        "typedoc-plugin-markdown": "^4.9.0",
-        "typescript": "^5.5.4",
-        "vitest": "^3.1.2"
-    },
-    "dependencies": {
-        "@jcoreio/async-throttle": "^1.6.0",
-        "browser-util-inspect": "^0.2.0",
-        "flexsearch": "0.7.21",
-        "vue-deepunref": "^1.0.1"
-    },
-    "peerDependencies": {
-        "@vueuse/core": "^13.0.0",
-        "lodash-es": "^4.17.23",
-        "vue": "^3.5.13"
+  "name": "@arrai-innovations/reactive-helpers",
+  "version": "22.1.0",
+  "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
+  "main": "index.js",
+  "type": "module",
+  "types": "types/index.d.ts",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./types/index.d.ts"
     }
-}
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "use/",
+    "utils/",
+    "config/",
+    "types/"
+  ],
+  "directories": {
+    "use": "use",
+    "utils": "utils",
+    "tests": "tests"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arrai-innovations/reactive-helpers.git"
+  },
+  "author": "Arrai Innovations Inc. <developers@arrai.com>",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/arrai-innovations/reactive-helpers/issues"
+  },
+  "homepage": "https://github.com/arrai-innovations/reactive-helpers#readme",
+  "devDependencies": {
+    "@arrai-innovations/commitlint-config": "^2.1.0",
+    "@commitlint/cli": "^19.8.1",
+    "@eslint/js": "9.39.4",
+    "@godaddy/dmd": "^1.0.4",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/browser-util-inspect": "^0.2.4",
+    "@types/lodash-es": "^4.17.12",
+    "@vitest/coverage-istanbul": "^4.1.9",
+    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/eslint-plugin": "^1.6.20",
+    "@vue/compiler-sfc": "^3.5.38",
+    "@vue/eslint-config-prettier": "^10.2.0",
+    "@vue/test-utils": "^2.4.11",
+    "doctoc": "^2.5.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^63.0.6",
+    "eslint-plugin-no-autofix": "^2.1.0",
+    "eslint-plugin-vue": "^10.9.2",
+    "flush-promises": "^1.0.2",
+    "globals": "^16.5.0",
+    "jsdom": "^26.1.0",
+    "lefthook": "^1.13.6",
+    "prettier": "^3.8.4",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vitepress": "^1.6.4",
+    "vitest": "^4.1.9",
+    "vue-eslint-parser": "^10.4.1"
+  },
+  "dependencies": {
+    "@jcoreio/async-throttle": "^1.7.0",
+    "browser-util-inspect": "^0.2.0",
+    "flexsearch": "0.7.21",
+    "vue-deepunref": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@vueuse/core": "^13.0.0",
+    "lodash-es": "^4.17.23",
+    "vue": "^3.5.13"
+  },
+  "scripts": {
+    "benchmark": "vitest bench --run",
+    "benchmark:list": "vitest bench --run tests/benchmarks/listPush.bench.js",
+    "benchmark:list:ci": "vitest bench --run tests/benchmarks/listPush.bench.js --outputJson benchmark-results/list-push.json",
+    "benchmark:check": "node check_benchmark.js",
+    "benchmark:layers": "vitest bench --run tests/benchmarks/listLayers.bench.js",
+    "benchmark:stream": "vitest bench --run tests/benchmarks/listStream.bench.js",
+    "test": "vitest",
+    "eslint": "eslint --fix index.js config/**/*.js tests/**/*.js use/**/*.js utils/**/*.js",
+    "prettier": "prettier --write .",
+    "coverage": "vitest run --coverage=true",
+    "docs": "node make_type_doc.js",
+    "docs:check": "node check_type_doc.js",
+    "docs:clean": "node clean_type_doc.js",
+    "docs:site:dev": "vitepress dev docs",
+    "docs:site:build": "vitepress build docs",
+    "docs:site:preview": "vitepress preview docs",
+    "types": "node make_types.js",
+    "types:check": "node check_types.js"
+  }
+}