@arrai-innovations/reactive-helpers 21.1.2 → 22.0.0

package/types/use/list.d.ts

@@ -30,81 +30,84 @@ export function useList({ props, handlers, searchThrottle, sortThrottleWait, sea
  */
 export type ListRawProps = {
     /**
-     * - The arguments to pass to the registered list crud handlers, related to the list itself.
+     * The arguments to pass to the registered list crud handlers, related to the list itself.
      */
     params: object;
     /**
-     * - The primary key for the list items.
+     * The primary key for the list items.
      */
     pkKey: string;
     /**
-     * - General arguments to pass to the registered list crud handlers, often related to endpoints.
+     * General arguments to pass to the registered list crud handlers, often related to endpoints.
      */
     target: object;
     /**
-     * - Indicates whether the list should be fetched immediately.
+     * Indicates whether the list should be fetched immediately.
      */
     intendToList: boolean;
     /**
-     * - Indicates whether changes to the list should be subscribed to.
+     * Indicates whether changes to the list should be subscribed to.
      */
     intendToSubscribe: boolean;
     /**
-     * - Defines rules for associating related objects with list items.
+     * Defines rules for associating related objects with list items.
      */
     relatedObjectsRules: import("./listRelated.js").ListRelatedRules;
     /**
-     * - Defines rules for dynamically calculating properties of list items.
+     * Defines rules for dynamically calculating properties of list items.
      */
     calculatedObjectsRules: import("./listCalculated.js").ListCalculatedRules;
     /**
-     * - Function or rule to determine if an item should be included based on inclusion criteria.
+     * Function or rule to determine if an item should be included based on inclusion criteria.
      */
     allowedFilter: import("./listFilter.js").ListFilterAllowedFilter;
     /**
-     * - Function or rule to determine if an item should be excluded based on exclusion criteria.
+     * Function or rule to determine if an item should be excluded based on exclusion criteria.
      */
     excludedFilter: import("./listFilter.js").ListFilterExcludedFilter;
     /**
-     * - Defines the properties and conditions used to filter the list via text search.
+     * Defines the properties and conditions used to filter the list via text search.
      */
     textSearchRules: import("./listSearch.js").TextSearchRules;
     /**
-     * - Current text query used for filtering the list.
+     * Current text query used for filtering the list.
      */
     textSearchValue: string;
     /**
-     * - FlexSearch document configuration options for advanced searching capabilities.
+     * FlexSearch document configuration options for advanced searching capabilities.
      */
     customDocumentOptions: object;
     /**
-     * - Additional search options for FlexSearch.
+     * Additional search options for FlexSearch.
      */
     customSearchOptions: object;
     /**
-     * - Sorting rules that define the order of list items.
+     * Sorting rules that define the order of list items.
      */
     orderByRules: import("./listSort.js").OrderByRule[];
 };
+/**
+ * The configuration options used to create a fully managed list via useList.
+ */
 export type ListOptions = {
     /**
-     * - The properties for configuring the list.
+     * The properties for configuring the list.
      */
     props: ListRawProps;
     /**
-     * - Additional handlers to be included in the list manager.
+     * Additional handlers to be included in the list manager.
      */
     handlers?: import("../config/listCrud.js").ListCrudHandlers;
     /**
-     * - The throttle time for text search.
+     * The throttle time for text search.
      */
     searchThrottle?: number;
     /**
-     * - The throttle time for sorting.
+     * The throttle time for sorting.
      */
     sortThrottleWait?: number;
     /**
-     * - Indicates whether all items should be shown when the search query is empty.
+     * Indicates whether all items should be shown when the search query is empty.
      */
     searchShowAllWhenEmpty?: boolean;
 };
@@ -125,25 +128,23 @@ export type ListManaged = {
  */
 export type ListFunctions = (import("./listInstance.js").ListInstanceFunctions & import("./listSubscription.js").ListSubscriptionFunctions);
 /**
- * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks,
- * and scoped effects.
+ * Encapsulates properties relevant to the overall management of list-related hooks, including state, direct access to hooks, and scoped effects.
  */
 export type ListManagerProperties = {
     /**
-     * - A readonly reference to the managed list hooks.
+     * A readonly reference to the managed list hooks.
      */
     managed: ListManaged;
     /**
-     * - Represents the final reactive state in the list processing chain.
+     * Represents the final reactive state in the list processing chain.
      */
     state: import("./listSort.js").ListSortState;
     /**
-     * - A function to stop the effect scope and clean up resources.
+     * A function to stop the effect scope and clean up resources.
      */
     stop: () => void;
 };
 /**
- * Combines functionality and properties to represent a fully managed list instance,
- * orchestrating various functionalities such as sorting, searching, filtering, and state management.
+ * Combines functionality and properties to represent a fully managed list instance, orchestrating various functionalities such as sorting, searching, filtering, and state management.
  */
 export type ListManager = ListFunctions & ListManagerProperties;

package/types/use/listCalculated.d.ts

@@ -7,10 +7,6 @@
  * @module use/listCalculated.js
  */
 /**
- * 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,
@@ -21,7 +17,7 @@
  *             [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.
  */
 /**
  * The raw state for a list calculated.
@@ -36,31 +32,24 @@
  * @private
  */
 /**
- * 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.
  */
 /**
  * The options to create a list calculated composition function.
@@ -72,17 +61,13 @@
  *  property changes.
  */
 /**
- * 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.
  */
 /**
- * The instance of `useListCalculated`.
- *
- * @typedef {ListCalculatedProperties} ListCalculated
+ * @typedef {ListCalculatedProperties} ListCalculated - The instance of `useListCalculated`.
  */
 /**
  * A composable function to create multiple list calculated objects.
@@ -154,9 +139,7 @@ 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.
  */
 export type ListCalculatedRules = {
     [rule: string]: (object: import("../use/objectInstance.js").ExistingCrudObject, relatedObject: {
@@ -166,11 +149,11 @@ export type ListCalculatedRules = {
     }) => any;
 };
 /**
- * - The raw state for a list calculated property.
+ * The raw state for a list calculated property.
  */
 export type ListCalculatedRawState = {
     /**
-     * - The calculated objects.
+     * The calculated objects.
      */
     calculatedObjects: {
         [pk: import("../config/commonCrud.js").Pk]: {
@@ -178,23 +161,23 @@ export type ListCalculatedRawState = {
         };
     };
     /**
-     * - The rules for the calculated objects.
+     * The rules for the calculated objects.
      */
     calculatedObjectsRules: ListCalculatedRules;
     /**
-     * - Whether the parent state objects watch is running.
+     * Whether the parent state objects watch is running.
      */
     calculatedObjectsParentStateObjectsWatchRunning: boolean;
     /**
-     * - Whether the calculated objects watch is running.
+     * Whether the calculated objects watch is running.
      */
     calculatedObjectsWatchRunning: boolean;
     /**
-     * - Whether the calculated properties are running.
+     * Whether the calculated properties are running.
      */
     calculatedRunning: import("vue").ComputedRef<boolean>;
     /**
-     * - Whether the list is running.
+     * Whether the list is running.
      */
     running: import("vue").ComputedRef<boolean>;
 };
@@ -207,20 +190,19 @@ export type ListCalculatedParentRawState = (import("./listInstance.js").ListInst
  */
 export type ListCalculatedState = import("vue").UnwrapNestedRefs<ListCalculatedParentRawState & ListCalculatedRawState>;
 /**
- * Represents a combined reactive state that includes properties from list related,
- *  subscription, and instance modules.
+ * Represents a combined reactive state that includes properties from list related, subscription, and instance modules.
  */
 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 behavior of the list calculated properties.
  */
 export type ListCalculatedOptions = {
     /**
-     * - The parent state that interacts with the calculated objects.
+     * The parent state that interacts with the calculated objects.
      */
     parentState: ListCalculatedParentState;
     /**
-     * - A reactive reference to rules used for dynamic calculations
+     * 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
      * property changes.
      */
@@ -231,15 +213,15 @@ export type ListCalculatedOptions = {
  */
 export type ListCalculatedProperties = {
     /**
-     * - The state for the list calculated property.
+     * The state for the list calculated property.
      */
     state: ListCalculatedState;
     /**
-     * - The parent state object.
+     * The parent state object.
      */
     parentState: ListCalculatedParentState;
     /**
-     * - Stops composition's effects and cleans up resources.
+     * Stops composition's effects and cleans up resources.
      */
     stop: () => void;
 };

package/types/use/listFilter.d.ts

@@ -7,7 +7,7 @@
  * @module use/listFilter.js
  */
 /**
- * @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.
  */
 /**
  * @typedef {Function} ListFilterAllowedFilter - A function that returns true if an item should be included.
@@ -16,10 +16,7 @@
  * @typedef {Function} ListFilterExcludedFilter - A function that returns true if an item should be excluded.
  */
 /**
- * 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.
  */
@@ -31,43 +28,33 @@
  *     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.
  */
 /**
- * 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.
  *
  */
 /**
@@ -113,29 +100,34 @@ export function useListFilters(listFilterArgs: {
  * @returns {ListFilter} A fully configured list filter instance, providing reactive filtered results.
  */
 export function useListFilter({ parentState, allowedFilter, excludedFilter }: ListFilterOptions): ListFilter;
+/**
+ * An array of Vue refs to the list's existing objects in their current order.
+ */
 export type ObjectsInOrderRefs = import("vue").Ref<import("../use/objectInstance.js").ExistingCrudObject>[];
 /**
- * - A function that returns true if an item should be included.
+ * A function that returns true if an item should be included.
  */
 export type ListFilterAllowedFilter = Function;
 /**
- * - A function that returns true if an item should be excluded.
+ * A function that returns true if an item should be excluded.
  */
 export type ListFilterExcludedFilter = Function;
 /**
- * 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.
+ * 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.
  */
 export type ListFilterRawState = {
     /**
-     * - Function to determine if an item should be included based on custom logic.
+     * Function to determine if an item should be included based on custom logic.
      */
     allowedFilter?: ListFilterAllowedFilter;
     /**
-     * - Function to determine if an item should be excluded based on custom logic.
+     * Function to determine if an item should be excluded based on custom logic.
      */
     excludedFilter?: ListFilterExcludedFilter;
 };
+/**
+ * The raw, pre-unwrapped parent state consumed by the list filter mixin, aggregating the upstream list composable states.
+ */
 export type ListFilterParentRawState = (import("./listInstance.js").ListInstanceRawState & Partial<import("./listSubscription.js").ListSubscriptionRawState> & Partial<import("./listRelated.js").ListRelatedRawState> & Partial<import("./listCalculated.js").ListCalculatedRawState>);
 /**
  * The parent state for a list filter.
@@ -150,15 +142,15 @@ export type ListFilterState = import("vue").UnwrapNestedRefs<ListFilterParentRaw
  */
 export type ListFilterOptions = {
     /**
-     * - The parent state.
+     * The parent state.
      */
     parentState: ListFilterParentState;
     /**
-     * - A function that returns true if an item should be included, which can be reactive.
+     * A function that returns true if an item should be included, which can be reactive.
      */
     allowedFilter?: import("vue").Ref<Function> | Function;
     /**
-     * - A function that returns true if an item should be excluded, which can be reactive.
+     * A function that returns true if an item should be excluded, which can be reactive.
      */
     excludedFilter?: import("vue").Ref<Function> | Function;
 };
@@ -167,15 +159,15 @@ export type ListFilterOptions = {
  */
 export type ListFilterProperties = {
     /**
-     * - The reactive state managing the filter logic and results.
+     * The reactive state managing the filter logic and results.
      */
     state: ListFilterState;
     /**
-     * - The state of the list being filtered.
+     * The state of the list being filtered.
      */
     parentState: ListFilterParentState;
     /**
-     * - A function to stop the effect scope and clean up resources.
+     * A function to stop the effect scope and clean up resources.
      */
     stop: () => void;
 };