@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/use/object.js

@@ -14,48 +14,38 @@ import { effectScope, shallowReactive, shallowReadonly, toRef } from "vue";
  */
 
 /**
- * Defines the raw reactive properties that can be passed to an object instance.
- *
  * @typedef {(
  *     import('./objectInstance.js').ObjectInstanceRawProps &
  *     import('./objectSubscription.js').ObjectSubscriptionRawProps &
  *     import('./objectRelated.js').ObjectRelatedRawProps &
  *     import('./objectCalculated.js').ObjectCalculatedRawProps
- * )} ObjectManagerRawProps
+ * )} ObjectManagerRawProps - Defines the raw reactive properties that can be passed to an object instance.
  */
 
 /**
- * Defines the reactive properties that can be passed to an object instance.
- *
- * @typedef {import('vue').UnwrapNestedRefs<ObjectManagerRawProps>} ObjectManagerProps
+ * @typedef {import('vue').UnwrapNestedRefs<ObjectManagerRawProps>} ObjectManagerProps - Defines the reactive properties that can be passed to an object instance.
  */
 
 /**
- * Defines the non-reactive handlers that can be passed to an object instance.
- *
- * @typedef {object} ObjectManagerOptions
+ * @typedef {object} ObjectManagerOptions - Defines the non-reactive handlers that can be passed to an object instance.
  * @property {ObjectManagerProps} props - The reactive properties to be passed to the object instance.
  * @property {import('../config/objectCrud.js').ObjectCrudHandlers} handlers - The non-reactive handlers to be passed to the object instance.
  */
 
 /**
- * Defines the managed object, containing the managed object instance, subscription, related objects, and calculated objects.
- *
  * @typedef {{
  *     objectInstance: import('./objectInstance.js').ObjectInstance,
  *     objectSubscription: import('./objectSubscription.js').ObjectSubscription,
  *     objectRelated: import('./objectRelated.js').ObjectRelated,
  *     objectCalculated: import('./objectCalculated.js').ObjectCalculated,
- * }} ObjectManaged
+ * }} ObjectManaged - Defines the managed object, containing the managed object instance, subscription, related objects, and calculated objects.
  */
 
 /**
- * Defines the functions provided by the object manager.
- *
  * @typedef {(
  *     import('./objectInstance.js').ObjectInstanceFunctions
  *     & import('./objectSubscription.js').ObjectSubscriptionFunctions
- * )} ObjectManagerFunctions
+ * )} ObjectManagerFunctions - Defines the functions provided by the object manager.
  * @property {Function} clearError - Clears the error state of the managed subscription and instance.
  * @property {Function} clear - Clears the managed instance & any error state.
  */
@@ -64,9 +54,7 @@ import { effectScope, shallowReactive, shallowReadonly, toRef } from "vue";
 // & import('./objectCalculated.js').ObjectCalculatedFunctions
 
 /**
- * Defines the properties available on an object manager.
- *
- * @typedef {object} ObjectManagerProperties
+ * @typedef {object} ObjectManagerProperties - Defines the properties available on an object manager.
  * @property {ObjectManaged} managed - The managed object.
  * @property {import('./objectCalculated.js').ObjectCalculatedState} state - The state of the managed object.
  * @property {() => void} stop - Stop the effect scope of the managed object.
@@ -74,7 +62,7 @@ import { effectScope, shallowReactive, shallowReadonly, toRef } from "vue";
 
 /**
  *
- * @typedef {ObjectManagerProperties & ObjectManagerFunctions} ObjectManager
+ * @typedef {ObjectManagerProperties & ObjectManagerFunctions} ObjectManager - The fully managed object returned by useObject, combining its properties and functions.
  */
 
 /**
@@ -128,7 +116,7 @@ function mergeFns(source) {
  * ```
  * <script setup>
  * import { useObject } from "@arrai-innovations/reactive-helpers";
- * import { reactive, ref, toRef } from "vue";
+ * import { computed, reactive, toRef } from "vue";
  *
  * const someObjectsSource = reactive({
  *     objects: {
@@ -171,25 +159,24 @@ function mergeFns(source) {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },
  *     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 objects matched by relatedObjectRules above,
+ *             // keyed by rule name.
  *             // this is used as a computed body.
  *             return object.foo + object.name;
  *         },
- *         ...
+ *         // ...further rules
  *     },
  *     intendToRetrieve: false,
  *     intendToSubscribe: false,
  * });
  * objectProps.intendToRetrieve = objectProps.intendToSubscribe = computed(()=> !!props.pk);
- * const objectManager = useObject(objectProps);
+ * const objectManager = useObject({ props: objectProps });
  * // objectManager.state.object comes back from the server (via configured crud retrieve function)
  * // { id: 2, name: 'two', foo: 'bar', some_objects_id: 2, some_objects_list_ids: ['1','2','3'] }
  * </script>

package/use/objectCalculated.js

@@ -14,19 +14,19 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  */
 
 /**
- * The object calculated state keys.
- *
  * @typedef {{
  *     [ruleKey: string]: (object: any, relatedObject: any) => any
- * }} ObjectCalculatedRules
+ * }} 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.
@@ -40,7 +40,7 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  *     import('./objectInstance.js').ObjectInstanceRawState &
  *     Partial<import('./objectSubscription.js').ObjectSubscriptionRawState> &
  *     Partial<import('./objectRelated.js').ObjectRelatedRawState>
- * )} ObjectCalculatedParentRawState
+ * )} ObjectCalculatedParentRawState - The raw, pre-unwrapped parent state consumed by the object calculated mixin, aggregating the upstream object composable states.
  */
 
 /**
@@ -52,18 +52,14 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  */
 
 /**
- * The state for object calculated.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *   ObjectCalculatedParentRawState &
  *   ObjectCalculatedRawState
- * >} ObjectCalculatedState
+ * >} ObjectCalculatedState - The state for object calculated.
  */
 
 /**
- * The properties for object calculated.
- *
- * @typedef {object} ObjectCalculatedProperties
+ * @typedef {object} ObjectCalculatedProperties - The properties for object calculated.
  * @property {ObjectCalculatedParentState} parentState - The parent state.
  * @property {ObjectCalculatedState} state - The object calculated state.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
@@ -72,15 +68,13 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
 // if we provided functions, we would add a typedef and mix them into ObjectCalculated
 
 /**
- * The object calculated instance.
- *
- * @typedef {ObjectCalculatedProperties} ObjectCalculated
+ * @typedef {ObjectCalculatedProperties} ObjectCalculated - The object calculated instance.
  */
 
 /**
  *
  *
- * @typedef {object} ObjectCalculatedRawProps
+ * @typedef {object} ObjectCalculatedRawProps - The consumer-supplied props for the object calculated composable, namely the calculated-object rules ref.
  * @property {import('vue').Ref<ObjectCalculatedRules>} calculatedObjectRules - The calculated object rules.
  */
 
@@ -88,9 +82,10 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  *
  * @typedef {({
  *     parentState: ObjectCalculatedParentState,
- * } & ObjectCalculatedRawProps)} ObjectCalculatedOptions
+ * } & ObjectCalculatedRawProps)} ObjectCalculatedOptions - The options used to create an object calculated instance (the parent state plus the calculated-object rules).
  */
 
+/** @internal */
 export const objectCalculatedStateKeys = [
     "calculatedObject",
     "calculatedObjectRules",
@@ -100,6 +95,7 @@ export const objectCalculatedStateKeys = [
     // "running",
 ];
 
+/** @internal */
 export const objectCalculatedFunctions = [];
 
 /**
@@ -131,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
@@ -140,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";
 
 /**
@@ -12,34 +12,25 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * The object being managed by the instance. It must include a primary key field as identifying property, matching
- * the name provided to the object/list's `pkKey` value, which is not known statically.
- *
- * @typedef {{[key: string]: any}} ExistingCrudObject
+ * @typedef {{[key: string]: any}} ExistingCrudObject - The object being managed by the instance. It must include a primary key field as identifying property, matching the name provided to the object/list's `pkKey` value, which is not known statically.
  */
 
 /**
- * The object you would like an object instance to create for you.
- *
- * @typedef {{[key: string]: any}} NewCrudObject
+ * @typedef {{[key: string]: any}} NewCrudObject - The object you would like an object instance to create for you.
  */
 
 /**
- * @typedef {ExistingCrudObject|NewCrudObject} CrudObject
+ * @typedef {ExistingCrudObject|NewCrudObject} CrudObject - An object managed by an object instance, either an existing object or a new object to be created.
  */
 
 /**
- * Arguments to be passed to the object instance.
- *
- * @typedef {object} ObjectInstanceOptions
+ * @typedef {object} ObjectInstanceOptions - Arguments to be passed to the object instance.
  * @property {import('vue').UnwrapNestedRefs<ObjectInstanceRawProps>} props - The reactive configuration object.
  * @property {import('../config/objectCrud.js').ObjectCrudHandlers} [handlers] - An object of custom crud handlers to use instead of the defaults.
  */
 
 /**
- * Reactive arguments to be passed to the object instance.
- *
- * @typedef {object} ObjectInstanceRawProps
+ * @typedef {object} ObjectInstanceRawProps - Reactive arguments to be passed to the object instance.
  * @property {import('../config/commonCrud.js').PkInput} [pk] - The pk of the object, optional to support creating new objects.
  * @property {string} pkKey - The pk key of the object.
  * @property {object} params - The arguments to be passed to the retrieve function.
@@ -47,7 +38,7 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * @typedef {object} ObjectInstanceRawStateCrud
+ * @typedef {object} ObjectInstanceRawStateCrud - The raw CRUD handlers and target args stored in an object instance's reactive state.
  * @property {import('vue').Reactive<import('../config/objectCrud.js').TargetArgs|{}>} args - The arguments to be passed to the crud handlers.
  * @property {import('../config/objectCrud.js').CrudCreateFn} create - The create function.
  * @property {import('../config/objectCrud.js').CrudRetrieveFn} retrieve - The retrieve function.
@@ -59,42 +50,34 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * The raw state of the object instance.
- *
- * @typedef {object} ObjectInstanceRawMyState
+ * @typedef {object} ObjectInstanceRawMyState - The raw state of the object instance.
  * @property {import('vue').Reactive<ObjectInstanceRawStateCrud>} crud - The crud handlers.
  * @property {import('vue').Ref<import('../config/commonCrud.js').Pk|undefined>} pk - The pk of the object.
  * @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()`.
  */
 
 /**
- * The raw state of the object instance.
- *
- * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState
+ * @typedef {ObjectInstanceRawMyState & import('./loadingError.js').LoadingErrorProperties} ObjectInstanceRawState - The raw state of the object instance.
  */
 
 /**
- * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
- * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
- *
- * @typedef {import('vue').Reactive<ObjectInstanceRawState>} ObjectInstanceState
+ * @typedef {import('vue').Reactive<ObjectInstanceRawState>} ObjectInstanceState - Manages a reactive state of an object including its CRUD status, loading states, and any operational errors. Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
  */
 
-/** @typedef {{ object: NewCrudObject }} ObjectInstanceCreateArgs */
-/** @typedef {{ object: ExistingCrudObject }} ObjectInstanceUpdateArgs */
-/** @typedef {{ partialObject: ExistingCrudObject }} ObjectInstancePatchArgs */
+/** @typedef {{ object: NewCrudObject }} ObjectInstanceCreateArgs - The argument shape for an object instance's create operation, carrying the new object to create. */
+/** @typedef {{ object: ExistingCrudObject }} ObjectInstanceUpdateArgs - The argument shape for an object instance's update operation, carrying the existing object to update. */
+/** @typedef {{ partialObject: ExistingCrudObject }} ObjectInstancePatchArgs - The argument shape for an object instance's patch operation, carrying the partial object to apply. */
 
 /**
- * @typedef {{[key:string]: any}} AdditionalArgs
+ * @typedef {{[key:string]: any}} AdditionalArgs - Arbitrary extra arguments forwarded through to an object instance's CRUD operations.
  */
 
 /**
- * The functions available on the object instance.
- *
- * @typedef {object} ObjectInstanceMyFunctions
+ * @typedef {object} ObjectInstanceMyFunctions - The functions available on the object instance.
  * @property {(args: ObjectInstanceCreateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} create - Called to turn the current object into a new object on the server.
  * @property {(args?: Partial<import('./cancellableIntent.js').CommonRunTracking> & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} retrieve - Called to retrieve the current object by pk from the server.
  * @property {(args: ObjectInstanceUpdateArgs & AdditionalArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} update - Called to update the current object on the server.
@@ -105,25 +88,19 @@ import { pkRefIfReactive, refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * The functions available on the object instance, including the ability to clear LoadingError errors.
- *
  * @typedef {(
  *     import('./error.js').ErrorReadOnlyFunctions &
  *     ObjectInstanceMyFunctions
- * )} ObjectInstanceFunctions
+ * )} ObjectInstanceFunctions - The functions available on the object instance, including the ability to clear LoadingError errors.
  */
 
 /**
- * The properties of the object instance.
- *
- * @typedef {object} ObjectInstanceProperties
+ * @typedef {object} ObjectInstanceProperties - The properties of the object instance.
  * @property {ObjectInstanceState} state - The state of the object instance.
  */
 
 /**
- * The instance of the object instance.
- *
- * @typedef {ObjectInstanceFunctions & ObjectInstanceProperties} ObjectInstance
+ * @typedef {ObjectInstanceFunctions & ObjectInstanceProperties} ObjectInstance - The instance of the object instance.
  */
 
 /**
@@ -144,6 +121,7 @@ export class ObjectError extends Error {
     }
 }
 
+/** @internal */
 export const objectInstanceStateKeys = [
     "crud",
     "pk",
@@ -156,6 +134,7 @@ export const objectInstanceStateKeys = [
     "deleted",
 ];
 
+/** @internal */
 export const objectInstanceFunctions = [
     "create",
     "retrieve",
@@ -302,10 +281,14 @@ export function useObjectInstance({ props, handlers = {} }) {
                 createPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -348,17 +331,21 @@ 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) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -398,10 +385,14 @@ export function useObjectInstance({ props, handlers = {} }) {
                 updatePromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -425,11 +416,13 @@ export function useObjectInstance({ props, handlers = {} }) {
             }
             loadingError.setLoading();
             loadingError.clearError();
+            const isCancelled = ref(false);
             const deletePromise = state.crud.delete({
                 ...args,
                 target: state.crud.args,
                 pk: state.pk,
                 pkKey: state.pkKey,
+                isCancelled: readonly(isCancelled),
             });
             return wrapMaybeCancellable(
                 deletePromise
@@ -439,7 +432,10 @@ export function useObjectInstance({ props, handlers = {} }) {
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -447,6 +443,7 @@ export function useObjectInstance({ props, handlers = {} }) {
                     }),
                 deletePromise.cancel
                     ? async (/** @type {any} */ reason) => {
+                          isCancelled.value = true;
                           await deletePromise.cancel?.(reason);
                           loadingError.clearLoading();
                       }
@@ -476,10 +473,14 @@ export function useObjectInstance({ props, handlers = {} }) {
                 patchPromise
                     .then((/** @type {ExistingCrudObject} */ object) => {
                         assignReactiveObject(state.object, object);
+                        state.deleted = false;
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -515,7 +516,10 @@ export function useObjectInstance({ props, handlers = {} }) {
                         return true;
                     })
                     .catch((/** @type {Error} */ error) => {
-                        loadingError.setError(error);
+                        // A deliberate cancellation rejects with the cancel reason; that is not an error.
+                        if (!isCancelled.value) {
+                            loadingError.setError(error);
+                        }
                         return false;
                     })
                     .finally(() => {
@@ -534,6 +538,7 @@ export function useObjectInstance({ props, handlers = {} }) {
         clear: () => {
             loadingError.clearError();
             assignReactiveObject(state.object, {});
+            state.deleted = false;
         },
     };
     return instance;

package/use/objectRelated.js

@@ -20,30 +20,27 @@ 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.
 /**
- * The rule for defining relationships for the managed object to other collections of objects.
- *
- * @typedef {object} ObjectRelatedRule
- * @property {string} pkKey - The key in the managed object that corresponds to the key in the related object.
+ * @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.
+ *  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.
  */
 
 /**
- * The rules for defining relationships for the managed object to other collections of objects.
- *
  * @typedef {{
  *     [rule: string]: ObjectRelatedRule,
- * }} ObjectRelatedRawRules
+ * }} ObjectRelatedRawRules - The rules for defining relationships for the managed object to other collections of objects.
  */
 
 /**
  *
  *
- * @typedef {object} ObjectRelatedRawState
+ * @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.
@@ -56,13 +53,13 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, unref, watch } f
  * @typedef {(
  *    import('./objectInstance.js').ObjectInstanceRawState &
  *    Partial<import('./objectSubscription.js').ObjectSubscriptionRawState>
- * )} ObjectRelatedParentRawState
+ * )} ObjectRelatedParentRawState - The raw, pre-unwrapped parent state consumed by the object related mixin (object instance plus optional subscription state).
  */
 
 /**
  *
  *
- * @typedef {import('vue').UnwrapNestedRefs<ObjectRelatedParentRawState>} ObjectRelatedParentState
+ * @typedef {import('vue').UnwrapNestedRefs<ObjectRelatedParentRawState>} ObjectRelatedParentState - The unwrapped reactive parent state consumed by the object related mixin.
  */
 
 /**
@@ -71,9 +68,10 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, unref, watch } f
  * @typedef {import('vue').UnwrapNestedRefs<(
  *     ObjectRelatedParentRawState &
  *     ObjectRelatedRawState
- * )>} ObjectRelatedState
+ * )>} ObjectRelatedState - The unwrapped reactive state of the object related composable, combining the parent state with its own related state.
  */
 
+/** @internal */
 export const objectRelatedStateKeys = [
     "relatedObject",
     "relatedObjectRules",
@@ -83,10 +81,11 @@ export const objectRelatedStateKeys = [
     "running",
 ];
 
+/** @internal */
 export const objectRelatedFunctions = [];
 
 /**
- * @typedef {object} ObjectRelatedProperties
+ * @typedef {object} ObjectRelatedProperties - The members (state, parentState, stop) contributed by the object related composable.
  * @property {ObjectRelatedState} state - The state of the object related instance.
  * @property {ObjectRelatedParentState} parentState - The parent state.
  * @property {() => void} stop - Stops all effects of the object related instance.
@@ -96,27 +95,22 @@ export const objectRelatedFunctions = [];
 // if we provided functions, we would add a typedef and mix them into ObjectRelated
 
 /**
- * An instance of an object related reactive object.
- *
- * @typedef {ObjectRelatedProperties} ObjectRelated
+ * @typedef {ObjectRelatedProperties} ObjectRelated - An instance of an object related reactive object.
  */
 
 /**
- * Non-parent state options for useObjectRelated.
- *
- * @typedef {object} ObjectRelatedRawProps
+ * @typedef {object} ObjectRelatedRawProps - Non-parent state options for useObjectRelated.
  * @property {import('vue').Ref<ObjectRelatedRawRules>} relatedObjectRules - The rules for defining relationships for the managed object to other collections of objects.
  */
 
 /**
- * Options for useObjectRelated.
- *
  * @typedef {{
  *     parentState: ObjectRelatedParentState,
- * } & ObjectRelatedRawProps} ObjectRelatedOptions
+ * } & ObjectRelatedRawProps} ObjectRelatedOptions - Options for useObjectRelated.
  */
 
 /**
+ * Creates multiple object related instances keyed by name from a map of options.
  *
  * @param {{
  *     [key: string]: ObjectRelatedOptions
@@ -185,7 +179,7 @@ export function useObjectRelateds(objectRelatedArgs) {
  *             order: ['3','1','2'],
  *         },
  *         secondOrder: {
- *             pkKey: 'relatedObject.secondOrderId',
+ *             pkKey: 'relatedItem.firstOrder.secondOrderId',
  *             objects: someOtherObjectsSource.objects,
  *         },
  *     },