@arrai-innovations/reactive-helpers 22.0.0 → 22.1.0

package/types/use/combineClasses.d.ts

@@ -14,7 +14,7 @@
  * @example
  * ```vue
  * <script setup>
- * import { useCombineClasses } from "@vueda/use/combineClasses.js";
+ * import { useCombineClasses } from "@arrai-innovations/reactive-helpers";
  * import { ref } from "vue";
  * const myClasses = useCombineClasses(
  *     "class1",

package/types/use/listCalculated.d.ts

@@ -14,16 +14,16 @@
  *             [rule: string]: any,
  *         },
  *         calculatedObjects: {
- *             [rule: string]: import('vue').ComputedRef<any>,
+ *             [rule: string]: any,
  *         }
  *     ) => any,
- * }}  ListCalculatedRules - Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change.
+ * }}  ListCalculatedRules - Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change. Each entry of the third argument is backed by a computed, but it is read through a reactive proxy that unwraps it, so a rule reads `calculatedObjects.otherRule` directly and never `.value`.
  */
 /**
  * The raw state for a list calculated.
  *
  * @typedef {object} ListCalculatedRawState - The raw state for a list calculated property.
- * @property {{[pk: import('../config/commonCrud.js').Pk]: {[rule: string]: import('vue').ComputedRef<any>}}} calculatedObjects - The calculated objects.
+ * @property {{[pk: import('../config/commonCrud.js').Pk]: {[rule: string]: any}}} calculatedObjects - The calculated objects, by object pk and then 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 {ListCalculatedRules} calculatedObjectsRules - The rules for the calculated objects.
  * @property {boolean} calculatedObjectsParentStateObjectsWatchRunning - Whether the parent state objects watch is running.
  * @property {boolean} calculatedObjectsWatchRunning - Whether the calculated objects watch is running.
@@ -54,7 +54,7 @@
 /**
  * The options to create a list calculated composition function.
  *
- * @typedef {object} ListCalculatedOptions - Options to configure the behavior of the list calculated properties.
+ * @typedef {object} ListCalculatedOptions - Options to configure the behaviour of the list calculated properties.
  * @property {ListCalculatedParentState} parentState - The parent state that interacts with the calculated objects.
  * @property {import('vue').Ref<ListCalculatedRules>} calculatedObjectsRules - A reactive reference to rules used for dynamic calculations
  *  within list objects. Proper setup of this reference ensures that updates are managed reactively, including deep
@@ -93,7 +93,7 @@ export function useListCalculateds(listCalculatedArgs: {
  * ```vue
  * <script setup>
  * import { useListSubscription, useListCalculated } from "@arrai-innovations/reactive-helpers";
- * import { reactive, toRef } from "vue";
+ * import { reactive } from "vue";
  *
  * const listSubscriptionProps = reactive({
  *     // whatever props you need to get the list to work with your crud implementation
@@ -102,14 +102,15 @@ export function useListCalculateds(listCalculatedArgs: {
  *     pkKey: "pk",
  *     intendToList: true,
  * });
- * const listSubscription = useListSubscription(listSubscriptionProps);
+ * const listSubscription = useListSubscription({ props: listSubscriptionProps });
  * const listCalculatedProps = reactive({
  *     parentState: listSubscription.state,
- *     computedObjectsRules: {
- *         someRule: (object, relatedObjects, 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
+ *     calculatedObjectsRules: {
+ *         someRule: (object, relatedObject, calculatedObjects) => {
+ *            // some complex calculation. relatedObject holds this object's related objects, and is only
+ *            // populated when a useListRelated sits between the list and this composable.
+ *            // calculatedObjects holds the other calculated values for this same object,
+ *            // including this rule, so try not to create circular dependencies.
  *            // this is used as a computed body.
  *            return object.someProperty + object.someOtherProperty;
  *         }
@@ -119,12 +120,12 @@ export function useListCalculateds(listCalculatedArgs: {
  * </script>
  * <template>
  *     <ul>
- *         <!-- reactive list of objects, re-retrieving the list as someListFilter changes. -->
- *         <li v-for="obj in listInstance.state.objectsInOrder">
+ *         <!-- reactive list of objects, kept current by the configured subscription function. -->
+ *         <li v-for="obj in listSubscription.state.objectsInOrder">
  *             {{ obj }}
  *             <div>
- *                 <!-- the computed object or objects based on the rule -->
- *                 {{ listCalculated.state.computedObjects[obj.pk].someRule }}
+ *                 <!-- the calculated value for this object, based on the rule -->
+ *                 {{ listCalculated.state.calculatedObjects[obj.pk].someRule }}
  *             </div>
  *         </li>
  *     </ul>
@@ -139,13 +140,13 @@ export function useListCalculateds(listCalculatedArgs: {
  */
 export function useListCalculated({ parentState, calculatedObjectsRules }: ListCalculatedOptions): ListCalculated;
 /**
- * Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change.
+ * Defines rules for dynamically calculating new properties for objects in a list. Each rule is a function that takes an object from the list, optionally its related objects, and previously calculated properties to compute a new property. These functions are reactive and re-evaluate when underlying dependencies change. Each entry of the third argument is backed by a computed, but it is read through a reactive proxy that unwraps it, so a rule reads `calculatedObjects.otherRule` directly and never `.value`.
  */
 export type ListCalculatedRules = {
     [rule: string]: (object: import("../use/objectInstance.js").ExistingCrudObject, relatedObject: {
         [rule: string]: any;
     }, calculatedObjects: {
-        [rule: string]: import("vue").ComputedRef<any>;
+        [rule: string]: any;
     }) => any;
 };
 /**
@@ -153,11 +154,11 @@ export type ListCalculatedRules = {
  */
 export type ListCalculatedRawState = {
     /**
-     * The calculated objects.
+     * The calculated objects, by object pk and then 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`.
      */
     calculatedObjects: {
         [pk: import("../config/commonCrud.js").Pk]: {
-            [rule: string]: import("vue").ComputedRef<any>;
+            [rule: string]: any;
         };
     };
     /**
@@ -194,7 +195,7 @@ export type ListCalculatedState = import("vue").UnwrapNestedRefs<ListCalculatedP
  */
 export type ListCalculatedParentState = import("vue").UnwrapNestedRefs<(import("./listInstance.js").ListInstanceRawState & Partial<import("./listSubscription.js").ListSubscriptionRawState> & Partial<import("./listRelated.js").ListRelatedRawState>)>;
 /**
- * Options to configure the behavior of the list calculated properties.
+ * Options to configure the behaviour of the list calculated properties.
  */
 export type ListCalculatedOptions = {
     /**

package/types/use/listInstance.d.ts

@@ -54,6 +54,7 @@
  * @property {object} params - Arguments passed to the server for listing operations.
  * @property {ObjectsMap} objectsMap - The map of objects stored by their pks.
  * @property {ObjectsByPk} objects - The list objects stored by their pks.
+ * @property {number} objectsVersion - Increments when the set of object keys changes.
  * @property {ListOrder} order - The order of objects in the list.
  * @property {ObjectsInOrder} objectsInOrder - The objects in the order specified by the list.
  * @property {import('vue').ShallowReactive<PaginateInfo>} paginateInfo - Pagination information for the list.
@@ -166,7 +167,7 @@ export function useListInstances(listInstanceArgs: {
  * ```
  *
  * @param {ListInstanceOptions} options - Specifies the configuration options for creating a list instance, including
- *  properties for CRUD operations and UI behaviors like page persistence.
+ *  properties for CRUD operations and UI behaviours like page persistence.
  * @returns {ListInstance} The list instance.
  * @throws {ListInstanceError} If the props are missing.
  */
@@ -319,6 +320,10 @@ export type ListInstanceRawMyState = {
      * The list objects stored by their pks.
      */
     objects: ObjectsByPk;
+    /**
+     * Increments when the set of object keys changes.
+     */
+    objectsVersion: number;
     /**
      * The order of objects in the list.
      */

package/types/use/listRelated.d.ts

@@ -6,8 +6,8 @@
  */
 /**
  * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
- * @property {string} pkKey - Specifies the foreign key used to link objects across lists. Planned to be renamed to
- *  'fkKey' to better reflect its usage.
+ * @property {string} [pkKey] - Specifies the foreign key used to link objects across lists. Defaults to the rule's
+ *  own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.
  */
@@ -20,20 +20,20 @@
  * @typedef {object} ListRelatedRawState - Represents the internal state used by the list related composition function. It manages and computes the relationships between objects based on specified rules, providing real-time updates to related objects as the parent state changes.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} relatedObjects - Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
+ * }} relatedObjects - The related objects, by object pk and then 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 {ListRelatedRules} relatedObjectsRules - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<[object, string]>,
  *     },
- * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+ * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so `.value` is not used.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} fkForPkAndRule - Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.
+ * }} fkForPkAndRule - The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.
  * @property {boolean} relatedObjectsParentStateObjectsWatchRunning - Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
  * @property {boolean} relatedObjectsWatchRunning - Indicates if watches on the related objects themselves are active, managing updates efficiently.
  * @property {boolean} relatedRunning - Signals whether any computations related to object relationships are currently in progress.
@@ -163,10 +163,10 @@ export function useListRelated({ parentState, relatedObjectsRules }: ListRelated
  */
 export type ListRelatedRule = {
     /**
-     * Specifies the foreign key used to link objects across lists. Planned to be renamed to
-     * 'fkKey' to better reflect its usage.
+     * Specifies the foreign key used to link objects across lists. Defaults to the rule's
+     * own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
      */
-    pkKey: string;
+    pkKey?: string;
     /**
      * Specifies the order in which related objects should be sorted, if applicable.
      */
@@ -187,11 +187,11 @@ export type ListRelatedRules = {
  */
 export type ListRelatedRawState = {
     /**
-     * Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
+     * The related objects, by object pk and then 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`.
      */
     relatedObjects: {
         [pk: import("../config/commonCrud.js").Pk]: {
-            [rule: string]: import("vue").ComputedRef<any>;
+            [rule: string]: any;
         };
     };
     /**
@@ -199,7 +199,7 @@ export type ListRelatedRawState = {
      */
     relatedObjectsRules: ListRelatedRules;
     /**
-     * Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+     * Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so `.value` is not used.
      */
     objAndKeyForPkAndRule: {
         [pk: import("../config/commonCrud.js").Pk]: {
@@ -207,11 +207,11 @@ export type ListRelatedRawState = {
         };
     };
     /**
-     * Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.
+     * The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.
      */
     fkForPkAndRule: {
         [pk: import("../config/commonCrud.js").Pk]: {
-            [rule: string]: import("vue").ComputedRef<any>;
+            [rule: string]: any;
         };
     };
     /**

package/types/use/listSort.d.ts

@@ -1,6 +1,6 @@
 /**
  * Sets default configuration options for all list sorting operations within the application. This function allows
- * global settings to be specified that affect the behavior of sorting operations unless overridden by specific
+ * global settings to be specified that affect the behaviour of sorting operations unless overridden by specific
  * instance configurations.
  *
  * @param {object} options - Configuration options to set as defaults for list sorting.
@@ -22,6 +22,7 @@ export function setListSortDefaultOptions({ sortThrottleWait }: {
  * @typedef {object} ListSortRawState - Represents the raw state used by the list sorting functionality. Includes all configurations and state necessary to manage sorting operations within a Vue application.
  * @property {OrderByRule[]} orderByRules - Current sorting rules applied to the list.
  * @property {boolean[]} orderByDesc - Flags indicating whether each sort criterion is in descending order.
+ * @property {import('vue').ComputedRef<boolean|undefined>} running - Whether the sort is settling a pending reorder, combined with the upstream running state so it propagates through the composed list state. True from when a new order is computed until the throttled reorder lands.
  */
 /**
  *
@@ -136,6 +137,10 @@ export type ListSortRawState = {
      * Flags indicating whether each sort criterion is in descending order.
      */
     orderByDesc: boolean[];
+    /**
+     * Whether the sort is settling a pending reorder, combined with the upstream running state so it propagates through the composed list state. True from when a new order is computed until the throttled reorder lands.
+     */
+    running: import("vue").ComputedRef<boolean | undefined>;
 };
 /**
  * The raw, pre-unwrapped parent state consumed by the list sort mixin, aggregating the upstream list composable states.

package/types/use/listSubscription.d.ts

@@ -16,7 +16,9 @@
  * @typedef {import('vue').Reactive<ListSubscriptionRawState>} ListSubscriptionState - A reactive object that manages a list of objects, as returned by `useListInstance`.
  */
 /**
- * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListSubscriptionFunctions - The methods available on a list subscription.
+ * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError"> & {
+ *     stop: () => void
+ * }} ListSubscriptionFunctions - The methods available on a list subscription.
  */
 /**
  * @typedef {{
@@ -151,7 +153,9 @@ export type ListSubscriptionState = import("vue").Reactive<ListSubscriptionRawSt
 /**
  * The methods available on a list subscription.
  */
-export type ListSubscriptionFunctions = Pick<import("./loadingError.js").LoadingErrorStatus, "clearError">;
+export type ListSubscriptionFunctions = Pick<import("./loadingError.js").LoadingErrorStatus, "clearError"> & {
+    stop: () => void;
+};
 /**
  * The context (state, list instance, and loading/error status) bound to the shared list subscription functions.
  */

package/types/use/objectCalculated.d.ts

@@ -20,7 +20,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
@@ -29,21 +29,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>
@@ -65,14 +65,16 @@ export function useObjectCalculated({ parentState, calculatedObjectRules }: Obje
 /**
  * @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.
@@ -126,7 +128,9 @@ export const objectCalculatedStateKeys: string[];
 /** @internal */
 export const objectCalculatedFunctions: any[];
 /**
- * The object calculated state keys.
+ * 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).
  */
 export type ObjectCalculatedRules = {
     [ruleKey: string]: (object: any, relatedObject: any) => any;
@@ -140,10 +144,10 @@ export type ObjectCalculatedRawState = {
      */
     calculatedObjectRules: ObjectCalculatedRules;
     /**
-     * The calculated object.
+     * 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`.
      */
     calculatedObject: {
-        [ruleKey: string]: import("vue").ComputedRef<any>;
+        [ruleKey: string]: any;
     };
     /**
      * Whether the calculated object watch is running.

package/types/use/objectInstance.d.ts

@@ -106,7 +106,8 @@ export function useObjectInstance({ props, handlers }: ObjectInstanceOptions): O
  * @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()`.
  */
 /**
  * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState - The raw state of the object instance.
@@ -275,7 +276,8 @@ export type ObjectInstanceRawMyState = {
      */
     object: import("vue").Reactive<CrudObject>;
     /**
-     * Whether the object is 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()`.
      */
     deleted: boolean;
 };

package/types/use/objectRelated.d.ts

@@ -83,7 +83,7 @@ export function useObjectRelateds(objectRelatedArgs: {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },
@@ -115,9 +115,10 @@ export function useObjectRelated({ parentState, relatedObjectRules }: ObjectRela
  */
 /**
  * @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.
  */
 /**
  * @typedef {{
@@ -130,8 +131,8 @@ export function useObjectRelated({ parentState, relatedObjectRules }: ObjectRela
  * @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.
@@ -204,8 +205,9 @@ export type ObjectRelatedOptions = {
 export type ObjectRelatedRule = {
     /**
      * The key in the managed object that corresponds to the key in the related object.
+     * Defaults to the rule's own key when omitted.
      */
-    pkKey: string;
+    pkKey?: string;
     /**
      * The related objects, indexed by the key in the related object.
      */
@@ -213,7 +215,7 @@ export type ObjectRelatedRule = {
     /**
      * The order of the related objects, if the related objects are an array.
      */
-    order: string[];
+    order?: string[];
 };
 /**
  * The rules for defining relationships for the managed object to other collections of objects.
@@ -230,10 +232,10 @@ export type ObjectRelatedRawState = {
      */
     relatedObjectRules: ObjectRelatedRawRules;
     /**
-     * The related objects, indexed by the key in the related object.
+     * 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`.
      */
     relatedObject: {
-        [rule: string]: import("vue").ComputedRef<any>;
+        [rule: string]: any;
     };
     /**
      * Whether the related object watch is running.

package/types/use/objectSubscription.d.ts

@@ -66,7 +66,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({
@@ -85,11 +85,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>

package/types/utils/cancellableFetch.d.ts

@@ -5,7 +5,6 @@
  * @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<T>(input: RequestInfo, init: RequestInit, transform: (response: Response) => Promise<T>): CancellablePromise<T>;
-import { CancellablePromise } from "./cancellablePromise.js";
+export function cancellableFetch<T>(input: RequestInfo, init: RequestInit, transform: (response: Response) => Promise<T>): import("./cancellablePromise.js").CancellablePromise<T>;

package/types/utils/cancellablePromise.d.ts

@@ -1,12 +1,33 @@
 /**
- * Wraps a promise and optionally adds a cancel method if provided.
+ * A Promise that can be cancelled.
  *
  * @template T
- * @param {Promise<T>} inner - The inner promise to wrap.
- * @param {((reason?: any) => Promise<void> | void)=} cancel - Optional cancel function.
- * @returns {MaybeCancellablePromise<T>} The wrapped promise with an optional cancel method.
+ * @typedef {Promise<T> & { cancel: (reason?: any) => Promise<void> | void }} CancellablePromise - A promise augmented with a cancel method to abort the pending operation.
+ */
+/**
+ * A possibly cancellable promise.
+ *
+ * @template T
+ * @typedef {Promise<T> & { cancel?: (reason?: any) => Promise<void> | void }} MaybeCancellablePromise - A promise that may optionally carry a cancel method to abort the pending operation.
+ */
+/**
+ * Adds a cancel method to a promise.
+ *
+ * @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 makeCancellable<T>(promise: Promise<T>, cancel: (reason?: any) => (Promise<void> | void)): CancellablePromise<T>;
+/**
+ * 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 wrapMaybeCancellable<T>(inner: Promise<T>, cancel?: ((reason?: any) => Promise<void> | void) | undefined): MaybeCancellablePromise<T>;
 export function CancellablePromise<T>(promise: Promise<T>, cancel: (reason?: any) => (Promise<void> | void)): CancellablePromise<T>;
 /**
  * A promise augmented with a cancel method to abort the pending operation.
@@ -18,6 +39,8 @@ export namespace CancellablePromise {
     /**
      * 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.
      */
@@ -25,12 +48,23 @@ export namespace CancellablePromise {
     /**
      * 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.
      */
     function resolve<T_1>(value: T_1): MaybeCancellablePromise<T_1>;
 }
+/**
+ * Wraps a promise and optionally adds a cancel method if provided.
+ *
+ * @template T
+ * @param {Promise<T>} inner - The inner promise to wrap.
+ * @param {((reason?: any) => Promise<void> | void)=} cancel - Optional cancel function.
+ * @returns {MaybeCancellablePromise<T>} The wrapped promise with an optional cancel method.
+ */
+export function wrapMaybeCancellable<T>(inner: Promise<T>, cancel?: ((reason?: any) => Promise<void> | void) | undefined): MaybeCancellablePromise<T>;
 /**
  * A promise that may optionally carry a cancel method to abort the pending operation.
  */

package/types/utils/getFakePk.d.ts

@@ -1,6 +1,6 @@
 /**
- * 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.

package/use/cancellableIntent.js

@@ -98,12 +98,19 @@ export class CancellableIntentError extends Error {
 /**
  * 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.
+ *
+ * If the watch arguments change again before the promise resolves, the in-flight promise is cancelled only when it
+ * carries a `cancel` method (a `MaybeCancellablePromise`); a plain promise is left to run to completion. That
+ * distinction is visible through the composables built on this one. `useObjectSubscription` calls
+ * `objectInstance.retrieve()` again for the new key, and that call returns the promise already in flight for the
+ * previous key, so the stale record is assigned and the new key is never fetched. `useListSubscription` guards its
+ * list intent on the list's own loading state, so the superseded run is left to finish and the list is then listed
+ * again with the current arguments.
  *
  * @example
  * ```vue
  * <script setup>
- * import { useCancellableIntent } from "@vueda/use/cancellableIntent.js";
+ * import { useCancellableIntent } from "@arrai-innovations/reactive-helpers";
  * import { ref, computed, onMounted, onUnmounted } from "vue";
  *
  * const myValue = ref(0);

package/use/combineClasses.js

@@ -32,7 +32,7 @@ const isRefOrReactive = (v) => isRef(v) || isReactive(v);
  * @example
  * ```vue
  * <script setup>
- * import { useCombineClasses } from "@vueda/use/combineClasses.js";
+ * import { useCombineClasses } from "@arrai-innovations/reactive-helpers";
  * import { ref } from "vue";
  * const myClasses = useCombineClasses(
  *     "class1",