@arrai-innovations/reactive-helpers 21.1.2 → 22.1.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/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,15 +1,36 @@
 /**
- * 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 {(() => 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.
  */
-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>;
 /**
- * A Promise that can be cancelled.
+ * 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 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.
  */
 export type CancellablePromise<T> = Promise<T> & {
     cancel: (reason?: any) => Promise<void> | void;
@@ -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,6 +48,8 @@ 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.
@@ -32,7 +57,16 @@ export namespace CancellablePromise {
     function resolve<T_1>(value: T_1): MaybeCancellablePromise<T_1>;
 }
 /**
- * A possibly cancellable promise.
+ * 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.
  */
 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/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/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.
@@ -102,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);
@@ -184,7 +187,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 +234,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 +248,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 +337,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).
  */
 
 /**
@@ -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",

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 */