@arrai-innovations/reactive-helpers 11.4.2 → 13.0.0

package/.husky/pre-commit

@@ -2,4 +2,3 @@
 . "$(dirname "$0")/_/husky.sh"
 
 npx --no-install lint-staged
-npm run docs

package/.idea/codeStyles/codeStyleConfig.xml

@@ -0,0 +1,5 @@
+<component name="ProjectCodeStyleConfiguration">
+  <state>
+    <option name="PREFERRED_PROJECT_CODE_STYLE" value="Default (3)" />
+  </state>
+</component>

package/.prettierignore

@@ -2,3 +2,4 @@ node_modules
 package.json
 package-lock.json
 coverage
+docs

package/README.md

@@ -14,7 +14,7 @@ Vue.js 3 utility composition functions to help manipulate objects and lists.
 - [Install](#install)
 - [Usage](#usage)
   - [Import](#import)
-  - [JSDocs](#jsdocs)
+  - [Documentation](#documentation)
   - [List](#list)
     - [Instance](#instance)
     - [Subscription](#subscription)
@@ -55,11 +55,9 @@ import { useListInstance } from "@arrai-innovations/reactive-helpers/use/listIns
 import { useObjectInstance } from "@arrai-innovations/reactive-helpers/use";
 ```
 
-See the [JSDocs](./docs.md) for list of available modules and imports.
+### Documentation
 
-### JSDocs
-
-[View the JSDocs](./docs.md)
+See the [generated documentation](./docs/README.md) for list of available modules and imports.
 
 ### List
 
@@ -587,7 +585,10 @@ setObjectCrud({
 ```js
 // similar to list, but for a single object.
 import {
-    useObjectInstance, useObjectSubscription, useObjectRelated, useObjectCalculated
+    useObjectInstance,
+    useObjectSubscription,
+    useObjectRelated,
+    useObjectCalculated,
 } from "@arrai-innovations/reactive-helpers";
 
 const contactObject = useObjectInstance({
@@ -599,12 +600,12 @@ const contactObject = useObjectInstance({
             fields: ["id", "has_name", "lexical_name", "organization", "phone"],
         },
         id: contactId,
-    }
+    },
 });
 console.log(contactObject.state.object);
 const contactSubscription = useObjectSubscription({
     objectInstance: contactObject,
-})
+});
 // or
 const contactSubscription = useObjectSubscription({
     props: {
@@ -615,7 +616,7 @@ const contactSubscription = useObjectSubscription({
             fields: ["id", "has_name", "lexical_name", "organization", "phone"],
         },
         id: contactId,
-    }
+    },
 });
 console.log(contactSubscription.state.object);
 const organizations = useList({
@@ -626,7 +627,7 @@ const organizations = useList({
         retrieveArgs: {
             fields: ["id", "name"],
         },
-    }
+    },
 });
 await organizations.list();
 const contactRelated = useObjectRelated({

package/config/listCrud.js

@@ -9,6 +9,24 @@ const defaultCrud = {
     subscribe: undefined,
 };
 
+/**
+ * @typedef {object} ListCrudFunctions
+ * @property {Function} [list] - The list function to get a list of items.
+ * @property {Function} [subscribe] - The subscribe function to get a subscription to a list of items.
+ */
+
+/**
+ * @typedef {object} ListCrudArgs
+ * @property {object} [args={}] - The default arguments for the crud functions.
+ */
+
+/**
+ * Set the list and subscribe functions for the default crud.
+ *
+ * @param {ListCrudFunctions & Partial<ListCrudArgs>} options - The options for the default crud.
+ * @throws {Error} - If unknown keys are passed.
+ * @returns {void}
+ */
 export const setListCrud = ({ list, subscribe, args = {}, ...rest }) => {
     defaultCrud.list = list;
     defaultCrud.subscribe = subscribe;
@@ -18,6 +36,16 @@ export const setListCrud = ({ list, subscribe, args = {}, ...rest }) => {
     }
 };
 
+/**
+ * Get the previously set list and subscribe functions for the default crud.
+ *
+ * @param {import("vue").UnwrapNestedRefs<ListCrudFunctions & ListCrudArgs>} reactiveCrud - The reactive crud object, which will be mutated.
+ * @param {object} options - The options for the default crud.
+ * @param {import("vue").UnwrapNestedRefs<{
+ *     crudArgs: object|undefined,
+ * }>} [options.props] - The props to set for the crud.
+ * @param {ListCrudFunctions & ListCrudArgs} [options.functions] - The functions to set for the crud.
+ */
 export const getListCrud = (reactiveCrud, { props, functions } = {}) => {
     // don't mutate the default crud
     Object.assign(reactiveCrud, cloneDeep(defaultCrud));
@@ -27,7 +55,10 @@ export const getListCrud = (reactiveCrud, { props, functions } = {}) => {
     if (functions) {
         for (const [key, value] of Object.entries(functions)) {
             if (isFunction(value) && key in reactiveCrud) {
-                reactiveCrud[key] = isReactive(functions) ? toRef(functions, key) : value;
+                reactiveCrud[key] = isReactive(functions)
+                    ? // @ts-ignore - this is a valid key...
+                      toRef(functions, key)
+                    : value;
             } else {
                 throw Error(`Invalid function "${key}" for getListCrud: invalid key or not a function.`);
             }

package/config/objectCrud.js

@@ -13,6 +13,38 @@ const defaultCrud = {
     subscribe: undefined,
 };
 
+/**
+ * Defines the CRUD-related functions and additional utilities provided by the object instance.
+ *
+ * @typedef {object} ObjectCrudArgsProperties
+ * @property {object} [args={}] - The arguments to be passed to the crud functions.
+ */
+
+/**
+ * Defines the CRUD-related functions and additional utilities provided by the object instance.
+ *
+ * @typedef {object} ObjectCrudFunctions
+ * @property {Function} [create] - A function to be used instead of the default crud create function.
+ * @property {Function} [retrieve] - A function to be used instead of the default crud retrieve function.
+ * @property {Function} [update] - A function to be used instead of the default crud update function.
+ * @property {Function} [delete] - A function to be used instead of the default crud delete function.
+ * @property {Function} [patch] - A function to be used instead of the default crud patch function.
+ * @property {Function} [subscribe] - A function to be used instead of the default crud subscribe function.
+ */
+
+/**
+ * The CRUD arguments.
+ *
+ * @typedef {ObjectCrudArgsProperties & ObjectCrudFunctions} ObjectCrudArgs
+ *
+ */
+
+/**
+ * Set the object crud functions.
+ *
+ * @param {ObjectCrudArgs} options - The options for the object crud functions.
+ * @throws {Error} - if unknown keys are passed.
+ */
 export const setObjectCrud = ({ retrieve, create, update, patch, delete: deleteFn, subscribe, args = {}, ...rest }) => {
     defaultCrud.retrieve = retrieve;
     defaultCrud.create = create;
@@ -27,6 +59,17 @@ export const setObjectCrud = ({ retrieve, create, update, patch, delete: deleteF
     }
 };
 
+/**
+ * Get the previously set object crud functions.
+ *
+ * @param {import("vue").UnwrapNestedRefs<object>} reactiveCrud - The reactive object you want to add the resulting crud to.
+ * @param {object} options - The options for the reactive crud object.
+ * @param {import("vue").UnwrapNestedRefs<{
+ *     crudArgs: ObjectCrudArgsProperties|undefined,
+ * }>} [options.props] - The props with any passed crudArgs.
+ * @param {ObjectCrudFunctions} [options.functions] - Any functions to override the default crud functions.
+ * @throws {Error} - If an invalid function is passed, or if the function is not a function.
+ */
 export const getObjectCrud = (reactiveCrud, { props, functions } = {}) => {
     // don't mutate the default crud
     Object.assign(reactiveCrud, cloneDeep(defaultCrud));
@@ -36,7 +79,10 @@ export const getObjectCrud = (reactiveCrud, { props, functions } = {}) => {
     if (functions) {
         for (const [key, value] of Object.entries(functions)) {
             if (isFunction(value) && key in reactiveCrud) {
-                reactiveCrud[key] = isReactive(functions) ? toRef(functions, key) : value;
+                reactiveCrud[key] = isReactive(functions)
+                    ? // @ts-ignore - key is a keyof ObjectCrudFunctions...
+                      toRef(functions, key)
+                    : value;
             } else {
                 throw Error(`Invalid function "${key}" for getObjectCrud: invalid key or not a function.`);
             }

package/docs/README.md

@@ -0,0 +1,43 @@
+**@arrai-innovations/reactive-helpers** • **Docs**
+
+***
+
+# @arrai-innovations/reactive-helpers
+
+## Modules
+
+- [config/listCrud](config/listCrud.md)
+- [config/objectCrud](config/objectCrud.md)
+- [use/cancellableIntent](use/cancellableIntent.md)
+- [use/combineClasses](use/combineClasses.md)
+- [use/list](use/list.md)
+- [use/listCalculated](use/listCalculated.md)
+- [use/listFilter](use/listFilter.md)
+- [use/listInstance](use/listInstance.md)
+- [use/listKeys](use/listKeys.md)
+- [use/listRelated](use/listRelated.md)
+- [use/listSearch](use/listSearch.md)
+- [use/listSort](use/listSort.md)
+- [use/listSubscription](use/listSubscription.md)
+- [use/loadingError](use/loadingError.md)
+- [use/object](use/object.md)
+- [use/objectCalculated](use/objectCalculated.md)
+- [use/objectInstance](use/objectInstance.md)
+- [use/objectRelated](use/objectRelated.md)
+- [use/objectSubscription](use/objectSubscription.md)
+- [use/paginatedListInstance](use/paginatedListInstance.md)
+- [use/search](use/search.md)
+- [use/watchesRunning](use/watchesRunning.md)
+- [utils/assignReactiveObject](utils/assignReactiveObject.md)
+- [utils/classes](utils/classes.md)
+- [utils/compact](utils/compact.md)
+- [utils/deleteKey](utils/deleteKey.md)
+- [utils/flattenPaths](utils/flattenPaths.md)
+- [utils/getFakeId](utils/getFakeId.md)
+- [utils/keyDiff](utils/keyDiff.md)
+- [utils/loadingCombine](utils/loadingCombine.md)
+- [utils/proxyRunning](utils/proxyRunning.md)
+- [utils/relatedCalculatedHelpers](utils/relatedCalculatedHelpers.md)
+- [utils/set](utils/set.md)
+- [utils/transformWalk](utils/transformWalk.md)
+- [utils/watches](utils/watches.md)

package/docs/config/listCrud.md

@@ -0,0 +1,97 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / config/listCrud
+
+# config/listCrud
+
+## Interfaces
+
+### ListCrudArgs
+
+#### Properties
+
+##### args
+
+> **args**: `any`
+
+The default arguments for the crud functions.
+
+***
+
+### ListCrudFunctions
+
+#### Properties
+
+##### list
+
+> **list**: `Function`
+
+The list function to get a list of items.
+
+##### subscribe
+
+> **subscribe**: `Function`
+
+The subscribe function to get a subscription to a list of items.
+
+## Functions
+
+### getListCrud()
+
+> **getListCrud**(`reactiveCrud`, `options`): `void`
+
+Get the previously set list and subscribe functions for the default crud.
+
+#### Parameters
+
+• **reactiveCrud**
+
+The reactive crud object, which will be mutated.
+
+• **reactiveCrud.args**: `any`
+
+The default arguments for the crud functions.
+
+• **reactiveCrud.list**: `Function`
+
+The list function to get a list of items.
+
+• **reactiveCrud.subscribe**: `Function`
+
+The subscribe function to get a subscription to a list of items.
+
+• **options** = `{}`
+
+The options for the default crud.
+
+• **options.functions**: [`ListCrudFunctions`](listCrud.md#listcrudfunctions) & [`ListCrudArgs`](listCrud.md#listcrudargs)
+
+The functions to set for the crud.
+
+• **options.props**
+
+The props to set for the crud.
+
+• **options.props.crudArgs**: `any`
+
+#### Returns
+
+`void`
+
+***
+
+### setListCrud()
+
+> **setListCrud**(`options`): `void`
+
+#### Parameters
+
+• **options**: [`ListCrudFunctions`](listCrud.md#listcrudfunctions) & `Partial`\<[`ListCrudArgs`](listCrud.md#listcrudargs)\>
+
+The options for the default crud.
+
+#### Returns
+
+`void`

package/docs/config/objectCrud.md

@@ -0,0 +1,123 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / config/objectCrud
+
+# config/objectCrud
+
+## Interfaces
+
+### ObjectCrudArgsProperties
+
+#### Properties
+
+##### args
+
+> **args**: `any`
+
+The arguments to be passed to the crud functions.
+
+***
+
+### ObjectCrudFunctions
+
+#### Properties
+
+##### create
+
+> **create**: `Function`
+
+A function to be used instead of the default crud create function.
+
+##### delete
+
+> **delete**: `Function`
+
+A function to be used instead of the default crud delete function.
+
+##### patch
+
+> **patch**: `Function`
+
+A function to be used instead of the default crud patch function.
+
+##### retrieve
+
+> **retrieve**: `Function`
+
+A function to be used instead of the default crud retrieve function.
+
+##### subscribe
+
+> **subscribe**: `Function`
+
+A function to be used instead of the default crud subscribe function.
+
+##### update
+
+> **update**: `Function`
+
+A function to be used instead of the default crud update function.
+
+## Type Aliases
+
+### ObjectCrudArgs
+
+> **ObjectCrudArgs**\<\>: [`ObjectCrudArgsProperties`](objectCrud.md#objectcrudargsproperties) & [`ObjectCrudFunctions`](objectCrud.md#objectcrudfunctions)
+
+#### Type Parameters
+
+## Functions
+
+### getObjectCrud()
+
+> **getObjectCrud**(`reactiveCrud`, `options`): `void`
+
+Get the previously set object crud functions.
+
+#### Parameters
+
+• **reactiveCrud**: `any`
+
+The reactive object you want to add the resulting crud to.
+
+• **options** = `{}`
+
+The options for the reactive crud object.
+
+• **options.functions**: [`ObjectCrudFunctions`](objectCrud.md#objectcrudfunctions)
+
+Any functions to override the default crud functions.
+
+• **options.props**
+
+The props with any passed crudArgs.
+
+• **options.props.crudArgs**
+
+• **options.props.crudArgs.args**: `any`
+
+The arguments to be passed to the crud functions.
+
+#### Returns
+
+`void`
+
+***
+
+### setObjectCrud()
+
+> **setObjectCrud**(`options`): `void`
+
+Set the object crud functions.
+
+#### Parameters
+
+• **options**: [`ObjectCrudArgs`](objectCrud.md#objectcrudargs)
+
+The options for the object crud functions.
+
+#### Returns
+
+`void`

package/docs/use/cancellableIntent.md

@@ -0,0 +1,163 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / use/cancellableIntent
+
+# use/cancellableIntent
+
+## Interfaces
+
+### CancellableIntent
+
+The instance of the cancellable intent.
+
+#### Properties
+
+##### cancel
+
+> **cancel**: `Function`
+
+Cancel the cancellable intent.
+
+##### guardArguments
+
+> **guardArguments**: `any`
+
+The guard arguments.
+
+##### state
+
+> **state**: `any`
+
+The state of the cancellable intent.
+
+##### stop
+
+> **stop**: `Function`
+
+Stop the cancellable intent.
+
+##### watchArguments
+
+> **watchArguments**: `any`
+
+The watch arguments.
+
+***
+
+### CancellableIntentOptions
+
+The options for the cancellable intent.
+
+#### Properties
+
+##### awaitableWithCancel()
+
+> **awaitableWithCancel**: () => [`CancellablePromise`](cancellableIntent.md#cancellablepromise)
+
+The function that returns a promise that can be cancelled.
+
+###### Returns
+
+[`CancellablePromise`](cancellableIntent.md#cancellablepromise)
+
+##### clearActiveOnResolved
+
+> **clearActiveOnResolved**: `boolean`
+
+Whether to clear the active state when the promise resolves.
+
+##### guardArguments
+
+> **guardArguments**: `any`
+
+The reactive object to watch for truthiness before running the intent.
+
+##### watchArguments
+
+> **watchArguments**: `any`
+
+The reactive object to watch for changes.
+
+## Type Aliases
+
+### CancellableIntentState
+
+> **CancellableIntentState**\<\>: `UnwrapNestedRefs`
+
+The state of the cancellable intent.
+
+#### Type Parameters
+
+***
+
+### CancellablePromise
+
+> **CancellablePromise**\<\>: `Promise`\<`any`\> & `object`
+
+#### Type declaration
+
+##### cancel()
+
+> **cancel**: () => `Promise`\<`void`\> \| `void`
+
+###### Returns
+
+`Promise`\<`void`\> \| `void`
+
+#### Type Parameters
+
+## Functions
+
+### useCancellableIntent()
+
+> **useCancellableIntent**(`options`): [`CancellableIntent`](cancellableIntent.md#cancellableintent)
+
+Calls your awaitable function with the arguments you pass in when the watch arguments change and are all truthy.
+Watch arguments should be a reactive object.
+If the promise is not resolved before the watch arguments change again, the previous promise is cancelled.
+
+#### Parameters
+
+• **options**: [`CancellableIntentOptions`](cancellableIntent.md#cancellableintentoptions)
+
+The options for the cancellable intent.
+
+#### Returns
+
+[`CancellableIntent`](cancellableIntent.md#cancellableintent)
+
+- The instance of the cancellable intent.
+
+#### Example
+
+```vue
+<script setup>
+import { useCancellableIntent } from "@vueda/use/cancellableIntent.js";
+import { ref, computed, onMounted, onUnmounted } from "vue";
+
+const myValue = ref(0);
+const myOtherValue = ref(0);
+
+const myIntent = useCancellableIntent({
+  awaitableWithCancel: async () => {
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    console.log("resolved");
+    return true;
+  },
+  watchArguments: { myValue, myOtherValue },
+  guardArguments: { myValue: computed(() => myValue.value > 0) },
+  clearActiveOnResolved: true,
+});
+
+onMounted(() => {
+  setTimeout(() => {
+    myValue.value = 1;
+    myOtherValue.value = 1;
+  }, 500);
+});
+
+onUnmounted(() => myIntent.stop());
+</script>
+```

package/docs/use/combineClasses.md

@@ -0,0 +1,52 @@
+[**@arrai-innovations/reactive-helpers**](../README.md) • **Docs**
+
+***
+
+[@arrai-innovations/reactive-helpers](../README.md) / use/combineClasses
+
+# use/combineClasses
+
+## Functions
+
+### useCombineClasses()
+
+> **useCombineClasses**(...`classes`): `Ref`\<[`CombinedClasses`](../utils/classes.md#combinedclasses)\>
+
+Normalize various ways of specifying CSS classes into an object for use in Vue.js with reactivity. If refs are
+ present, the resulting object will be a ref containing an array of objects to preserve order of operations in
+ reactive contexts.
+
+#### Parameters
+
+• ...**classes**: (`string` \| `string`[] \| `object` \| `Ref`\<`string` \| `string`[]\>)[]
+
+A mixed array containing multiple ways of specifying CSS classes.
+
+#### Returns
+
+`Ref`\<[`CombinedClasses`](../utils/classes.md#combinedclasses)\>
+
+- A ref
+ containing an object or array of objects containing CSS classes. Arrays are used if refs are present, to
+ preserve order of operations in reactive contexts.
+
+#### Example
+
+```vue
+<script setup>
+import { useCombineClasses } from "@vueda/use/combineClasses.js";
+import { ref } from "vue";
+const myClasses = useCombineClasses(
+    "class1",
+    ["class2", "class3"],
+    { class4: true, class5: false },
+    ref("class6"),
+    ref(["class7", "class8"]),
+    ref({ class9: true, class10: false }),
+);
+// myClasses.value = [
+//     { class1: true, class2: true, class3: true, class4: true, class5: false },
+//     { class6: true, class7: true, class8: true, class9: true, class10: false }
+// ]
+</script>
+```