@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

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