@arrai-innovations/reactive-helpers 22.0.0 → 22.1.0

package/use/objectCalculated.js

@@ -16,15 +16,17 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
 /**
  * @typedef {{
  *     [ruleKey: string]: (object: any, relatedObject: any) => any
- * }} ObjectCalculatedRules - The object calculated state keys.
+ * }} ObjectCalculatedRules - Rules for calculating values from the managed object, keyed by rule name. Each rule is used
+ *  as a computed body and receives exactly two arguments: the managed object and its related objects (the latter only
+ *  populated when a useObjectRelated sits upstream).
  */
 
 /**
  * @typedef {object} ObjectCalculatedRawState - The raw state for object calculated.
  * @property {ObjectCalculatedRules} calculatedObjectRules - The calculated object rules.
  * @property {{
- *     [ruleKey: string]: import('vue').ComputedRef<any>
- * }} calculatedObject - The calculated object.
+ *     [ruleKey: string]: any
+ * }} calculatedObject - The calculated values, by rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the calculated value and never carry a `.value`.
  * @property {boolean} calculatedObjectWatchRunning - Whether the calculated object watch is running.
  * @property {boolean} parentStateObjectWatchRunning - Whether the parent state object watch is running.
  * @property {boolean} calculatedRunning - Whether the calculated is running.
@@ -125,7 +127,7 @@ export function useObjectCalculateds(objectCalculatedArgs) {
  * ```vue
  * <script setup>
  * import { useObjectCalculated, useObjectSubscription } from "@arrai-innovations/reactive-helpers";
- * import { ref, reactive } from "vue";
+ * import { reactive } from "vue";
  *
  * const objectSubscriptionProps = reactive({
  *     // whatever object subscription props you need to work with your crud implementation
@@ -134,21 +136,21 @@ export function useObjectCalculateds(objectCalculatedArgs) {
  *     pk: '1',
  *     pkKey: 'id',
  *     intendToRetrieve: true,
- * };
- * const objectSubscription = useObjectSubscription(objectSubscriptionProps);
+ * });
+ * const objectSubscription = useObjectSubscription({ props: objectSubscriptionProps });
  * const objectCalculatedProps = reactive({
  *     parentState: objectSubscription.state,
  *     calculatedObjectRules: {
- *         someRule: (object, relatedObject, calculatedObjects) => {
- *            // some complex calculation, relatedObjects would be assuming there was a listRelated between the two
- *            // calculatedObjects would be the other calculated objects in the list
- *            // including yourself, so try not to create circular dependencies
+ *         someRule: (object, relatedObject) => {
+ *            // some complex calculation. relatedObject holds the managed object's related objects, and is
+ *            // only populated when a useObjectRelated sits between the object and this composable.
  *            // this is used as a computed body.
  *            return object.someProperty + object.someOtherProperty;
  *          },
- *         ...
+ *         // ...further rules
  *      },
  *  });
+ * const objectCalculated = useObjectCalculated(objectCalculatedProps);
  * </script>
  * <template>
  * <div>

package/use/objectInstance.js

@@ -2,7 +2,7 @@ import { defaultObjectCrud, getObjectCrud } from "../config/objectCrud.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { useLoadingError } from "./loadingError.js";
 import { reactive, readonly, ref } from "vue";
-import { CancellablePromise, wrapMaybeCancellable } from "../utils/cancellablePromise.js";
+import { wrapMaybeCancellable } from "../utils/cancellablePromise.js";
 import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
 
 /**
@@ -56,7 +56,8 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  * @property {import('vue').Ref<string|undefined>} pkKey - The pk key of the object.
  * @property {import('vue').Ref<{[key:string]: any}>} params - The arguments to be passed to the retrieve function.
  * @property {import('vue').Reactive<CrudObject>} object - The object.
- * @property {boolean} deleted - Whether the object is deleted.
+ * @property {boolean} deleted - Whether the object was deleted by the delete action or a subscription delete
+ *  event. Cleared when a later create, retrieve, update, or patch repopulates the object, and by `clear()`.
  */
 
 /**
@@ -280,6 +281,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                 createPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -329,13 +331,14 @@ export function useObjectInstance({ props, handlers = {} }) {
             } catch (error) {
                 loadingError.setError(error);
                 loadingError.clearLoading();
-                return CancellablePromise.resolve(false);
+                return Promise.resolve(false);
             }
 
             promises.retrieve = wrapMaybeCancellable(
                 retrievePromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -382,6 +385,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                 updatePromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -469,6 +473,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                 patchPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
@@ -533,6 +538,7 @@ export function useObjectInstance({ props, handlers = {} }) {
         clear: () => {
             loadingError.clearError();
             assignReactiveObject(state.object, {});
+            state.deleted = false;
         },
     };
     return instance;

package/use/objectRelated.js

@@ -21,9 +21,10 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, unref, watch } f
 // todo: pkKey is misnamed, it should be fkKey... this will be a major breaking change.
 /**
  * @typedef {object} ObjectRelatedRule - The rule for defining relationships for the managed object to other collections of objects.
- * @property {string} pkKey - The key in the managed object that corresponds to the key in the related object.
+ * @property {string} [pkKey] - The key in the managed object that corresponds to the key in the related object.
+ *  Defaults to the rule's own key when omitted.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The related objects, indexed by the key in the related object.
- * @property {string[]} order - The order of the related objects, if the related objects are an array.
+ * @property {string[]} [order] - The order of the related objects, if the related objects are an array.
  */
 
 /**
@@ -38,8 +39,8 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, unref, watch } f
  * @typedef {object} ObjectRelatedRawState - The raw reactive state of the object related composable, holding its rules, computed relations, and running flags.
  * @property {ObjectRelatedRawRules} relatedObjectRules - The rules for defining relationships for the managed object to other collections of objects.
  * @property {{
- *     [rule: string]: import('vue').ComputedRef<any>,
- * }} relatedObject - The related objects, indexed by the key in the related object.
+ *     [rule: string]: any,
+ * }} relatedObject - The related objects, by rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a `.value`.
  * @property {boolean} relatedObjectWatchRunning - Whether the related object watch is running.
  * @property {boolean} parentStateObjectWatchRunning - Whether the parent state object watch is running.
  * @property {boolean} relatedRunning - Whether the related objects are loading.
@@ -178,7 +179,7 @@ export function useObjectRelateds(objectRelatedArgs) {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },

package/use/objectSubscription.js

@@ -123,7 +123,7 @@ export function useObjectSubscriptions(subscriptionArgs) {
  * ```
  * <script setup>
  * import { useObjectSubscription } from "@arrai-innovations/reactive-helpers";
- * import { reactive, ref, toRef } from "vue";
+ * import { reactive, toRef } from "vue";
  *
  * const pkKey = "id";
  * const props = defineProps({
@@ -142,11 +142,12 @@ export function useObjectSubscriptions(subscriptionArgs) {
  *     params: {
  *         fields: ['foo', 'bar'],
  *     },
- *     intendToRetrieve: false,
- *     intendToSubscribe: false,
+ *     intendToRetrieve: true,
+ *     intendToSubscribe: true,
+ * });
+ * const objectSubscription = useObjectSubscription({
+ *     props: objectSubscriptionProps,
  * });
- * objectSubscriptionProps.intendToRetrieve = objectSubscriptionProps.intendToSubscribe = computed(()=> !!props.pk);
- * const objectSubscription = useObjectSubscription(objectSubscriptionProps);
  * </script>
  * <template>
  *     <div v-if="objectSubscription.state.loading">Loading...</div>
@@ -230,6 +231,7 @@ export function useObjectSubscription({ objectInstance, props, handlers }) {
                     assignReactiveObject(objectInstance.state.object, {});
                 } else {
                     assignReactiveObject(objectInstance.state.object, data);
+                    state.deleted = false;
                 }
             };
             const parentState = objectInstance.state;

package/use/proxyLoadingError.js

@@ -44,5 +44,8 @@ export function asWatchableLoadingError(source) {
     return {
         ...asWatchableLoading(unwrappedRefs),
         ...asWatchableError(unwrappedRefs),
+        // Preserve clearError: for a separate-state source it lives on the source
+        // itself, not on state, so extracting state above would otherwise drop it.
+        clearError: unwrappedSource.clearError,
     };
 }

package/utils/cancellableFetch.js

@@ -1,4 +1,4 @@
-import { CancellablePromise } from "./cancellablePromise.js";
+import { makeCancellable } from "./cancellablePromise.js";
 
 /**
  * A wrapper around fetch that adds cancellation via AbortController and returns a CancellablePromise.
@@ -7,7 +7,7 @@ import { CancellablePromise } from "./cancellablePromise.js";
  * @param {RequestInfo} input - The URL or Request object to fetch.
  * @param {RequestInit} init - The options for the fetch request.
  * @param {(response: Response) => Promise<T>} transform - A function to transform the response.
- * @returns {CancellablePromise<T>} A cancellable promise that resolves to the transformed response.
+ * @returns {import("./cancellablePromise.js").CancellablePromise<T>} A cancellable promise that resolves to the transformed response.
  */
 export function cancellableFetch(input, init, transform) {
     const controller = new AbortController();
@@ -35,7 +35,7 @@ export function cancellableFetch(input, init, transform) {
             cleanupExternalSignal();
         });
 
-    return CancellablePromise(basePromise, async (/** @type {any} */ reason) => {
+    return makeCancellable(basePromise, async (/** @type {any} */ reason) => {
         controller.abort(reason);
         await basePromise.catch(() => {});
     });

package/utils/cancellablePromise.js

@@ -13,22 +13,37 @@
  */
 
 /**
- * Creates a cancellable promise, mostly for easy of type checking.
+ * Adds a cancel method to a promise.
  *
  * @template T
- * @param {Promise<T>} promise - The promise to be cancellable.
+ * @param {Promise<T>} promise - The promise to make cancellable.
  * @param {(reason?: any) => (Promise<void>|void)} cancel - The function to cancel the promise.
  * @returns {CancellablePromise<T>} The cancellable promise.
  */
-export const CancellablePromise = (promise, cancel) => {
+export function makeCancellable(promise, cancel) {
     const cancellablePromise = /** @type {CancellablePromise<T>} */ (promise);
     cancellablePromise.cancel = cancel;
     return cancellablePromise;
-};
+}
+
+/**
+ * Adds a cancel method to a promise.
+ *
+ * @deprecated Use {@link makeCancellable} instead.
+ * @template T
+ * @param {Promise<T>} promise - The promise to make cancellable.
+ * @param {(reason?: any) => (Promise<void>|void)} cancel - The function to cancel the promise.
+ * @returns {CancellablePromise<T>} The cancellable promise.
+ */
+export function CancellablePromise(promise, cancel) {
+    return makeCancellable(promise, cancel);
+}
 
 /**
  * Creates a rejected 'cancellable' promise.
  *
+ * @deprecated Use `Promise.reject` directly; a plain rejected promise already
+ *  satisfies {@link MaybeCancellablePromise}.
  * @param {any} reason - The reason for the rejection.
  * @returns {MaybeCancellablePromise<never>} A rejected 'cancellable' promise.
  */
@@ -39,6 +54,8 @@ CancellablePromise.reject = (reason) => {
 /**
  * Creates a resolved 'cancellable' promise.
  *
+ * @deprecated Use `Promise.resolve` directly; a plain resolved promise already
+ *  satisfies {@link MaybeCancellablePromise}.
  * @template T
  * @param {T} value - The value to resolve the promise with.
  * @returns {MaybeCancellablePromise<T>} A resolved 'cancellable' promise.

package/utils/getFakePk.js

@@ -3,8 +3,8 @@ import isMap from "lodash-es/isMap.js";
 import isSet from "lodash-es/isSet.js";
 
 /**
- * Get a fake pk that is not in the array, set, map, or object. The fake pk is negative number, so they can be
- * differentiated from real ids. They are returned as strings, as javascript object property keys are always strings.
+ * Get a random safe integer at or below zero and return it as a string. A candidate is redrawn when its numeric value
+ * exists in an array field, Set, or Map, or when its string property key exists in an object.
  *
  * @param {Array|Set|Map|object} arraySetMapOrObject - The array, set, map, or object to check for the fake pk.
  *  An array is assumed to be an array of objects.