@arrai-innovations/reactive-helpers 21.1.2 → 22.0.0

package/types/use/search.d.ts

@@ -1,7 +1,5 @@
 /**
- * A reactive object for passing document options or search options to useSearch.
- *
- * @typedef {object} SearchProps
+ * @typedef {object} SearchProps - A reactive object for passing document options or search options to useSearch.
  * @property {DocumentOptions} customDocumentOptions - FlexSearch.Document options.
  * @property {SearchOptions} customSearchOptions - Search options.
  * @property {string} pkKey - The primary key field.
@@ -23,15 +21,15 @@ export function useSearch({ props, throttle }: {
  */
 export type SearchProps = {
     /**
-     * - FlexSearch.Document options.
+     * FlexSearch.Document options.
      */
     customDocumentOptions: DocumentOptions;
     /**
-     * - Search options.
+     * Search options.
      */
     customSearchOptions: SearchOptions;
     /**
-     * - The primary key field.
+     * The primary key field.
      */
     pkKey: string;
 };
@@ -40,7 +38,7 @@ export type SearchProps = {
  */
 export type SearchOptions = {
     /**
-     * - Limit of results.
+     * Limit of results.
      */
     limit: number;
 };
@@ -49,95 +47,101 @@ export type SearchOptions = {
  */
 export type DocumentOptions = {
     /**
-     * - The document field to use as an identifier. Populated from `pkKey`.
+     * The document field to use as an identifier. Populated from `pkKey`.
      */
     id: string;
     /**
-     * - The document field to use as a tag. Default is false, can be set to a string.
+     * The document field to use as a tag. Default is false, can be set to a string.
      */
     tag: boolean | string;
     /**
-     * - Fields to index. Can be a single string, an array of strings, or an array of objects specifying custom index options.
+     * Fields to index. Can be a single string, an array of strings, or an array of objects specifying custom index options.
      */
     index: string | string[] | object[];
     /**
-     * - Specifies if and what document fields to store. Can be false, a string, or an array of strings. Default is false.
+     * Specifies if and what document fields to store. Can be false, a string, or an array of strings. Default is false.
      */
     store: boolean | string | string[];
     /**
-     * - Specifies the tokenizer to use.
+     * Specifies the tokenizer to use.
      */
     tokenizer?: string;
     /**
-     * - Minimum length of a token to be indexed.
+     * Minimum length of a token to be indexed.
      */
     minLength?: number;
 };
+/**
+ * The raw reactive state of a search instance (query, results, status flags, and search options).
+ */
 export type SearchRawState = {
     /**
-     * - The search string.
+     * The search string.
      */
     search: string;
     /**
-     * - The results, where the keys are the ids of the objects that match, and the values are true.
+     * The results, where the keys are the ids of the objects that match, and the values are true.
      */
     results: object;
     /**
-     * - Whether the search has been performed.
+     * Whether the search has been performed.
      */
     searched: boolean;
     /**
-     * - Whether the search is currently running.
+     * Whether the search is currently running.
      */
     searching: boolean;
     /**
-     * - FlexSearch.Document options.
+     * FlexSearch.Document options.
      */
     customDocumentOptions: DocumentOptions;
     /**
-     * - Search options.
+     * Search options.
      */
     customSearchOptions: SearchOptions;
     /**
-     * - The number of times the search has been called.
+     * The number of times the search has been called.
      */
     called: number;
     /**
-     * - The number of times the search has been called, but has not yet returned.
+     * The number of times the search has been called, but has not yet returned.
      */
     pending: number;
     /**
-     * - Whether the search is currently running or has pending calls.
+     * Whether the search is currently running or has pending calls.
      */
     running: boolean;
 };
+/**
+ * The reactive search instance returned by useSearch, exposing its state, index mutators, event target, and stop.
+ */
 export type SearchInstance = {
     /**
-     * - The state.
+     * The state.
      */
     state: import("vue").UnwrapNestedRefs<SearchRawState>;
     /**
-     * - Add an index.
+     * Add an index.
      */
     addIndex: Function;
     /**
-     * - Update an index.
+     * Update an index.
      */
     updateIndex: Function;
     /**
-     * - Remove an index.
+     * Remove an index.
      */
     removeIndex: Function;
     /**
-     * - Clear the index.
+     * Clear the index.
      */
     clearIndex: Function;
     /**
-     * - An event target.
+     * An event target.
      */
     events: EventTarget;
     /**
-     * - Stop the effect scope.
+     * Stop the effect scope.
      */
     stop: Function;
 };

package/types/utils/assignReactiveObject.d.ts

@@ -111,4 +111,7 @@ export class AssignReactiveObjectError extends Error {
  * and refs must ultimately resolve to objects or arrays
  */
 export type ValidTargetOrSource = import("vue").Ref<object | any[]> | object | any[];
+/**
+ * The validated target and source values returned by the reactive-object assignment validator.
+ */
 export type validateTargetAndSourceResult = object;

package/types/utils/cancellablePromise.d.ts

@@ -3,13 +3,13 @@
  *
  * @template T
  * @param {Promise<T>} inner - The inner promise to wrap.
- * @param {(() => Promise<void> | void)=} cancel - Optional cancel function.
+ * @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?: (() => Promise<void> | void) | undefined): MaybeCancellablePromise<T>;
-export function CancellablePromise<T>(promise: Promise<T>, cancel: () => (Promise<void> | void)): CancellablePromise<T>;
+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 that can be cancelled.
+ * A promise augmented with a cancel method to abort the pending operation.
  */
 export type CancellablePromise<T> = Promise<T> & {
     cancel: (reason?: any) => Promise<void> | void;
@@ -32,7 +32,7 @@ export namespace CancellablePromise {
     function resolve<T_1>(value: T_1): MaybeCancellablePromise<T_1>;
 }
 /**
- * A possibly cancellable promise.
+ * A promise that may optionally carry a cancel method to abort the pending operation.
  */
 export type MaybeCancellablePromise<T> = Promise<T> & {
     cancel?: (reason?: any) => Promise<void> | void;

package/types/utils/classes.d.ts

@@ -5,12 +5,18 @@ export function combineClasses(...classes: (CombinedClassesArgument | CombinedCl
 export function stringifyClasses(...classes: (CombinedClassesArgument | CombinedClassesArgument[])[]): string;
 export function stringifyClass(cls: CombinedClassesArgument | CombinedClassesArgument[] | null | undefined): string | null | undefined;
 /**
- * - The normalized form of the CSS classes, either as a string of space-separated class names or an
+ * The normalized form of the CSS classes, either as a string of space-separated class names or an
  */
 export type CombinedClasses = (string | {
     [classnames: string]: boolean | import("vue").Ref<boolean>;
 } | {
     [classnames: string]: boolean | import("vue").Ref<boolean>;
 }[]);
+/**
+ * A boolean value or a Vue ref to a boolean.
+ */
 export type BooleanOrRef = boolean | import("vue").Ref<boolean>;
+/**
+ * A single class-specifying argument accepted by combineClasses (a string, array, set, map, object, or ref).
+ */
 export type CombinedClassesArgument = string | string[] | Set<any> | Map<any, any> | object | import("vue").Ref<any>;

package/types/utils/deepUnref.d.ts

@@ -1,5 +1,5 @@
 export function deepUnref<T>(val: T): DeepUnwrap<T> | T;
 /**
- * Recursively unwraps refs from a nested object, array, or primitive.
+ * A recursive type that unwraps Vue refs from a nested object, array, or primitive.
  */
 export type DeepUnwrap<T> = T extends import("vue").Ref<infer U> ? DeepUnwrap<U> : T extends Array<infer V> ? Array<DeepUnwrap<V>> : T extends object ? { [K in keyof T]: DeepUnwrap<T[K]>; } : T;

package/types/utils/isReactiveTyped.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Type guard reporting whether a value is a Vue reactive object.
+ *
  * @template {object} T
  * @param {T | import('vue').Reactive<T>} v - The value to check.
  * @returns {v is import('vue').Reactive<T>} - True if the value is reactive, false otherwise.

package/types/utils/keyDiff.d.ts

@@ -5,9 +5,7 @@
  * @module utils/keyDiff.js
  */
 /**
- * Result object of keyDiff and keyDiffDeep.
- *
- * @typedef {object} KeyDiffResult
+ * @typedef {object} KeyDiffResult - Result object of keyDiff and keyDiffDeep.
  * @property {Set<string>} [sameKeys] - If sameKeys option is true, return keys that are the same.
  * @property {Set<string>} [removedKeys] - If removedKeys option is true, return keys that are removed.
  * @property {Set<string>} [addedKeys] - If addedKeys option is true, return keys that are added.
@@ -48,15 +46,15 @@ export function keyDiffDeep(newObj: object, oldObj: object, options?: object): K
  */
 export type KeyDiffResult = {
     /**
-     * - If sameKeys option is true, return keys that are the same.
+     * If sameKeys option is true, return keys that are the same.
      */
     sameKeys?: Set<string>;
     /**
-     * - If removedKeys option is true, return keys that are removed.
+     * If removedKeys option is true, return keys that are removed.
      */
     removedKeys?: Set<string>;
     /**
-     * - If addedKeys option is true, return keys that are added.
+     * If addedKeys option is true, return keys that are added.
      */
     addedKeys?: Set<string>;
 };

package/types/utils/relatedCalculatedHelpers.d.ts

@@ -1,4 +1,6 @@
+/** @internal */
 export const relatedItemRegex: RegExp;
+/** @internal */
 export const calculatedItemRegex: RegExp;
 export function getObjectRelatedCalculatedByKey(obj: object, relatedObj: object, calculatedObj: object, key: string): [object, string];
 export function getObjectRelatedByKey(obj: object, relatedObj: object, key: string): [object, string];

package/types/utils/watches.d.ts

@@ -92,7 +92,7 @@ export class AwaitTimeout {
     resolve: (value: any) => void;
     reject: (reason?: any) => void;
     timeout: number;
-    timeoutId: NodeJS.Timeout;
+    timeoutId: number;
     cancelledError: AwaitTimeoutError;
     /**
      * Starts the timeout process. If the timeout duration is reached without being stopped, the promise resolves.

package/use/cancellableIntent.js

@@ -56,9 +56,7 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * The common run tracking arguments.
- *
- * @typedef {object} CommonRunTracking
+ * @typedef {object} CommonRunTracking - The common run tracking arguments.
  * @property {RunId} runId - The unique identifier for your run.
  * @property {IsCurrentRunFn} isCurrentRun - A function that checks if the current run ID matches your run ID.
  */
@@ -80,9 +78,7 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * Cancel function signature for cancellable intent.
- *
- * @typedef {Function} CancelFn
+ * @typedef {Function} CancelFn - Cancel function signature for cancellable intent.
  * @param {any} reason - The reason for cancellation.
  * @param {boolean} [forceClearActive=false] - Whether to force clear the active state.
  * @returns {Promise<void>} - A promise that resolves when the cancellation is complete.
@@ -184,7 +180,13 @@ export function useCancellableIntent({
         guardArguments: readonly(internalState.guardArguments),
     });
     let previousWatchValues = null,
-        cancelFunction = null;
+        cancelFunction = null,
+        // The run id whose in-flight promise `cancelFunction` would cancel. Paired with cancelFunction
+        // so a deliberate cancel can mark exactly which run it is tearing down.
+        cancelFunctionRunId = null;
+    // Run ids cancelled on purpose (via instance.cancel). Their promises reject with the cancel
+    // reason, which is not an error, so the run's catch handler skips setError for these.
+    const cancelledRunIds = new Set();
 
     const doIntentWatch = () => {
         loadingError.clearError();
@@ -225,8 +227,10 @@ export function useCancellableIntent({
 
         if (awaitablePromise.cancel) {
             cancelFunction = awaitablePromise.cancel.bind(awaitablePromise);
+            cancelFunctionRunId = thisRunId;
         } else {
             cancelFunction = null;
+            cancelFunctionRunId = null;
         }
         // we don't want to await this, because we want to be able to cancel it
         awaitablePromise
@@ -237,11 +241,21 @@ export function useCancellableIntent({
                 }
             })
             .catch(async (err) => {
+                // A deliberate cancellation (instance.cancel) rejects this run's promise with the
+                // cancel reason; that is the intended outcome, not an error, so don't surface it.
+                if (cancelledRunIds.delete(thisRunId)) {
+                    if (state.clearActiveOnResolved) {
+                        internalState.activeCount--;
+                    }
+                    return;
+                }
                 const cancelPromise = instance.cancel("Error in awaitableWithCancel", true);
                 loadingError.setError(err);
                 await cancelPromise;
             })
             .finally(() => {
+                // Drop any stale marker for this run (e.g. cancelled after it had already resolved).
+                cancelledRunIds.delete(thisRunId);
                 internalState.resolvingCount--;
             });
     };
@@ -316,7 +330,13 @@ export function useCancellableIntent({
         cancel: async (/** @type {any} */ reason, forceClearActive = false) => {
             if (cancelFunction) {
                 const toCancel = cancelFunction;
+                const runId = cancelFunctionRunId;
                 cancelFunction = null;
+                cancelFunctionRunId = null;
+                // Mark this run as deliberately cancelled so its rejection is not treated as an error.
+                if (runId !== null) {
+                    cancelledRunIds.add(runId);
+                }
                 if (!state.clearActiveOnResolved || forceClearActive) {
                     internalState.activeCount--;
                 }

package/use/combineClasses.js

@@ -21,7 +21,7 @@ const isRefOrReactive = (v) => isRef(v) || isReactive(v);
  *     string[] |
  *     { [key: string]: boolean | import("vue").Ref<boolean> } |
  *     import("vue").Ref<string | string[]>
- * )} CSSClasses
+ * )} CSSClasses - The accepted ways of specifying CSS classes to useCombineClasses (a string, array, class-map, or ref thereof).
  */
 
 /**

package/use/error.js

@@ -1,40 +1,36 @@
 import { readonly, ref } from "vue";
 
 /**
- * @typedef {() => void} ClearErrorFn
- * @typedef {import("vue").Ref<Error|null>} ErrorRef
- * @typedef {import("vue").Ref<boolean>} ErroredRef
- * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef
- * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef
+ * @typedef {() => void} ClearErrorFn - Signature for the function that clears the current error state.
+ * @typedef {import("vue").Ref<Error|null>} ErrorRef - A Vue ref holding the current error, or null when there is none.
+ * @typedef {import("vue").Ref<boolean>} ErroredRef - A Vue ref to the boolean indicating whether an error has occurred.
+ * @typedef {Readonly<ErrorRef>} ErrorReadonlyRef - A readonly Vue ref holding the current error, or null when there is none.
+ * @typedef {Readonly<ErroredRef>} ErroredReadonlyRef - A readonly Vue ref to the boolean indicating whether an error has occurred.
  */
 
 /**
- * @typedef {object} ErrorProperties
+ * @typedef {object} ErrorProperties - The reactive error-state members (error and errored) contributed by the useError composable.
  * @property {ErrorReadonlyRef} error - The error that occurred.
  * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
  */
 
 /**
- * @typedef {object} ErrorFunctions
+ * @typedef {object} ErrorFunctions - The error-state actions (setError, clearError) contributed by the useError composable.
  * @property {(error: Error) => void} setError - Set the error state.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 
 /**
- * Proxies can still clear errors but cannot set them directly.
- *
- * @typedef {object} ErrorReadOnlyFunctions
+ * @typedef {object} ErrorReadOnlyFunctions - Proxies can still clear errors but cannot set them directly.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 
 /**
- * @typedef {ErrorProperties & ErrorReadOnlyFunctions} ReadonlyErrorStatus
+ * @typedef {ErrorProperties & ErrorReadOnlyFunctions} ReadonlyErrorStatus - The readonly error-state API (error and errored plus clearError) exposed to consumers and proxies.
  */
 
 /**
- * The error state API.
- *
- * @typedef {ErrorProperties & ErrorFunctions} ErrorStatus
+ * @typedef {ErrorProperties & ErrorFunctions} ErrorStatus - The error state API.
  */
 
 /**

package/use/list.js

@@ -34,9 +34,7 @@ export class ListError extends Error {
 }
 
 /**
- * Defines properties for configuring the list management system.
- *
- * @typedef {object} ListRawProps
+ * @typedef {object} ListRawProps - Defines properties for configuring the list management system.
  * @property {object} params - The arguments to pass to the registered list crud handlers, related to the list itself.
  * @property {string} pkKey - The primary key for the list items.
  * @property {object} target - General arguments to pass to the registered list crud handlers, often related to endpoints.
@@ -54,7 +52,7 @@ export class ListError extends Error {
  */
 
 /**
- * @typedef {object} ListOptions
+ * @typedef {object} ListOptions - The configuration options used to create a fully managed list via useList.
  * @property {ListRawProps} props - The properties for configuring the list.
  * @property {import('../config/listCrud.js').ListCrudHandlers} [handlers] - Additional handlers to be included in the list manager.
  * @property {number} [searchThrottle] - The throttle time for text search.
@@ -63,8 +61,6 @@ export class ListError extends Error {
  */
 
 /**
- * Holds references to instances of all list-related composables, facilitating direct access and management.
- *
  * @typedef {{
  *     listInstance: import('./listInstance.js').ListInstance,
  *     listSubscription: import('./listSubscription.js').ListSubscription,
@@ -73,33 +69,25 @@ export class ListError extends Error {
  *     listFilter: import('./listFilter.js').ListFilter,
  *     listSearch: import('./listSearch.js').ListSearch,
  *     listSort: import('./listSort.js').ListSort
- * }} ListManaged
+ * }} ListManaged - Holds references to instances of all list-related composables, facilitating direct access and management.
  */
 
 /**
- * Aggregates all functions provided by various list-related composables, allowing for a unified approach to calling these methods.
- *
  * @typedef {(
  *     import('./listInstance.js').ListInstanceFunctions
  *     & import('./listSubscription.js').ListSubscriptionFunctions
- * )} ListFunctions
+ * )} ListFunctions - Aggregates all functions provided by various list-related composables, allowing for a unified approach to calling these methods.
  */
 
 /**
- * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks,
- * and scoped effects.
- *
- * @typedef {object} ListManagerProperties
+ * @typedef {object} ListManagerProperties - Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks, and scoped effects.
  * @property {ListManaged} managed - A readonly reference to the managed list hooks.
  * @property {import('./listSort.js').ListSortState} state - Represents the final reactive state in the list processing chain.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 
 /**
- * Combines functionality and properties to represent a fully managed list instance,
- * orchestrating various functionalities such as sorting, searching, filtering, and state management.
- *
- * @typedef {ListFunctions & ListManagerProperties} ListManager
+ * @typedef {ListFunctions & ListManagerProperties} ListManager - Combines functionality and properties to represent a fully managed list instance, orchestrating various functionalities such as sorting, searching, filtering, and state management.
  */
 
 /* eslint-disable jsdoc/valid-types */

package/use/listCalculated.js

@@ -14,10 +14,6 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  */
 
 /**
- * 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.
- *
  * @typedef {{
  *     [rule: string]: (
  *         object: import('../use/objectInstance.js').ExistingCrudObject,
@@ -28,7 +24,7 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  *             [rule: string]: import('vue').ComputedRef<any>,
  *         }
  *     ) => any,
- * }}  ListCalculatedRules
+ * }}  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.
  */
 
 /**
@@ -45,33 +41,26 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  */
 
 /**
- * The raw parent state for a list calculated.
- *
  * @typedef {(
  *     import('./listInstance.js').ListInstanceRawState &
  *     Partial<import('./listSubscription.js').ListSubscriptionRawState> &
  *     Partial<import('./listRelated.js').ListRelatedRawState>
- * )} ListCalculatedParentRawState
+ * )} ListCalculatedParentRawState - The raw parent state for a list calculated.
  */
 
 /**
- * The state for a list calculated property.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *     ListCalculatedParentRawState &
  *     ListCalculatedRawState
- * >} ListCalculatedState
+ * >} ListCalculatedState - The state for a list calculated property.
  */
 
 /**
- * Represents a combined reactive state that includes properties from list related,
- *  subscription, and instance modules.
- *
  * @typedef {import('vue').UnwrapNestedRefs<(
  *     import('./listInstance.js').ListInstanceRawState &
  *     Partial<import('./listSubscription.js').ListSubscriptionRawState> &
  *     Partial<import('./listRelated.js').ListRelatedRawState>
- * )>} ListCalculatedParentState
+ * )>} ListCalculatedParentState - Represents a combined reactive state that includes properties from list related, subscription, and instance modules.
  */
 
 /**
@@ -85,9 +74,7 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  */
 
 /**
- * The properties for the list computed composition function.
- *
- * @typedef {object} ListCalculatedProperties
+ * @typedef {object} ListCalculatedProperties - The properties for the list computed composition function.
  * @property {ListCalculatedState} state - The state for the list calculated property.
  * @property {ListCalculatedParentState} parentState - The parent state object.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
@@ -96,9 +83,7 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
 // if we provided functions, we would add a typedef and mix them into ListCalculated
 
 /**
- * The instance of `useListCalculated`.
- *
- * @typedef {ListCalculatedProperties} ListCalculated
+ * @typedef {ListCalculatedProperties} ListCalculated - The instance of `useListCalculated`.
  */
 
 /**
@@ -228,7 +213,7 @@ export function useListCalculated({ parentState, calculatedObjectsRules }) {
                 ));
             } else {
                 if (isEmpty(calculatedObjectsObject)) {
-                    return;
+                    continue;
                 }
                 removedRuleKeys = Object.keys(calculatedObjectsObject);
                 addedRuleKeys = [];

package/use/listFilter.js

@@ -11,7 +11,7 @@ import { computed, effectScope, isRef, reactive, toRef, toRefs, unref, watch } f
  */
 
 /**
- * @typedef {import('vue').Ref<import('../use/objectInstance.js').ExistingCrudObject>[]} ObjectsInOrderRefs
+ * @typedef {import('vue').Ref<import('../use/objectInstance.js').ExistingCrudObject>[]} ObjectsInOrderRefs - An array of Vue refs to the list's existing objects in their current order.
  */
 
 /**
@@ -23,10 +23,7 @@ import { computed, effectScope, isRef, reactive, toRef, toRefs, unref, watch } f
  */
 
 /**
- * Defines the structure of the reactive state used by the list filter. This state includes both filters and
- * the results of applying these filters to a list.
- *
- * @typedef {object} ListFilterRawState
+ * @typedef {object} ListFilterRawState - Defines the structure of the reactive state used by the list filter. This state includes both filters and the results of applying these filters to a list.
  * @property {ListFilterAllowedFilter} [allowedFilter] - Function to determine if an item should be included based on custom logic.
  * @property {ListFilterExcludedFilter} [excludedFilter] - Function to determine if an item should be excluded based on custom logic.
  */
@@ -39,39 +36,31 @@ import { computed, effectScope, isRef, reactive, toRef, toRefs, unref, watch } f
  *     Partial<import('./listSubscription.js').ListSubscriptionRawState> &
  *     Partial<import('./listRelated.js').ListRelatedRawState> &
  *     Partial<import('./listCalculated.js').ListCalculatedRawState>
- * )} ListFilterParentRawState
+ * )} ListFilterParentRawState - The raw, pre-unwrapped parent state consumed by the list filter mixin, aggregating the upstream list composable states.
  */
 
 /**
- * The parent state for a list filter.
- *
  * @typedef {import('vue').UnwrapNestedRefs<(
  *     ListFilterParentRawState
- * )>} ListFilterParentState
+ * )>} ListFilterParentState - The parent state for a list filter.
  */
 
 /**
- * Describes the combined state from various list-related composables that might interact with the list filter.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *     ListFilterParentRawState &
  *     ListFilterRawState
- * >} ListFilterState
+ * >} ListFilterState - Describes the combined state from various list-related composables that might interact with the list filter.
  */
 
 /**
- * Configuration options for initializing a list filter. Includes references to the parent state and filter functions.
- *
- * @typedef {object} ListFilterOptions
+ * @typedef {object} ListFilterOptions - Configuration options for initializing a list filter. Includes references to the parent state and filter functions.
  * @property {ListFilterParentState} parentState - The parent state.
  * @property {import('vue').Ref<Function>|Function} [allowedFilter] - A function that returns true if an item should be included, which can be reactive.
  * @property {import('vue').Ref<Function>|Function} [excludedFilter] - A function that returns true if an item should be excluded, which can be reactive.
  */
 
 /**
- * The properties of a list filter, including its state and associated Vue composition API utilities.
- *
- * @typedef {object} ListFilterProperties
+ * @typedef {object} ListFilterProperties - The properties of a list filter, including its state and associated Vue composition API utilities.
  * @property {ListFilterState} state - The reactive state managing the filter logic and results.
  * @property {ListFilterParentState} parentState - The state of the list being filtered.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
@@ -80,9 +69,7 @@ import { computed, effectScope, isRef, reactive, toRef, toRefs, unref, watch } f
 // if we provided functions, we would add a typedef and mix them into ListFilter
 
 /**
- * Represents an instance of a list filter, including its state and associated Vue composition API utilities.
- *
- * @typedef {ListFilterProperties} ListFilter
+ * @typedef {ListFilterProperties} ListFilter - Represents an instance of a list filter, including its state and associated Vue composition API utilities.
  *
  */