@arrai-innovations/reactive-helpers 18.0.0 → 18.0.2

package/types/use/objectCalculated.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Helper function to create multiple object calculateds instances.
+ *
+ * @param {{
+ *     [key: string]: ObjectCalculatedOptions
+ * }} objectCalculatedArgs - Options for each object calculated to create.
+ * @returns {{
+ *    [key: string]: ObjectCalculated
+ * }} - The created object calculated instances by key.
+ */
+export function useObjectCalculateds(objectCalculatedArgs: {
+    [key: string]: ObjectCalculatedOptions;
+}): {
+    [key: string]: ObjectCalculated;
+};
+/**
+ * Vue Composition API composable function for object calculated.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useObjectCalculated, useObjectSubscription } from "@arrai-innovations/reactive-helpers";
+ * import { ref, reactive } from "vue";
+ *
+ * const objectSubscriptionProps = reactive({
+ *     // whatever object subscription props you need to work with your crud implementation
+ *     crudArgs: {},
+ *     retrieveArgs: {},
+ *     pk: '1',
+ *     pkKey: 'id',
+ *     intendToRetrieve: true,
+ * };
+ * const objectSubscription = useObjectSubscription(objectSubscriptionProps);
+ * const objectCalculatedProps = reactive({
+ *     parentState: objectSubscription.state,
+ *     calculatedObjectRules: {
+ *         someRule: (object, relatedObject, calculatedObjects) => {
+ *            // some complex calculation, relatedObjects would be assuming there was a listRelated between the two
+ *            // calculatedObjects would be the other calculated objects in the list
+ *            // including yourself, so try not to create circular dependencies
+ *            // this is used as a computed body.
+ *            return object.someProperty + object.someOtherProperty;
+ *          },
+ *         ...
+ *      },
+ *  });
+ * </script>
+ * <template>
+ * <div>
+ *     <!-- the reactive result of the calculation, based on the fn passed in, turned into a computed -->
+ *     <p>{{ objectCalculated.state.calculatedObject.someRule }}</p>
+ * </div>
+ * </template>
+ * ```
+ *
+ * @param {ObjectCalculatedOptions} options - The object calculated options.
+ * @returns {ObjectCalculated} - The object calculated instance.
+ */
+export function useObjectCalculated({ parentState, calculatedObjectRules }: ObjectCalculatedOptions): ObjectCalculated;
+/**
+ * Vue Composition API composable function for object calculated.
+ *
+ * @module use/objectCalculated.js
+ */
+/**
+ * The object calculated state keys.
+ *
+ * @typedef {{
+ *     [ruleKey: string]: (object: any, relatedObject: any) => any
+ * }} ObjectCalculatedRules
+ */
+/**
+ * @typedef {object} ObjectCalculatedRawState - The raw state for object calculated.
+ * @property {ObjectCalculatedRules} calculatedObjectRules - The calculated object rules.
+ * @property {{
+ *     [ruleKey: string]: import('vue').ComputedRef<any>
+ * }} calculatedObject - The calculated object.
+ * @property {boolean} calculatedObjectWatchRunning - Whether the calculated object watch is running.
+ * @property {boolean} parentStateObjectWatchRunning - Whether the parent state object watch is running.
+ * @property {boolean} calculatedRunning - Whether the calculated is running.
+ * @property {import('vue').Ref<boolean>} running - Whether the object calculated is running.
+ */
+/**
+ *
+ *
+ * @typedef {(
+ *     import('./objectInstance.js').ObjectInstanceRawState &
+ *     Partial<import('./objectSubscription.js').ObjectSubscriptionRawState> &
+ *     Partial<import('./objectRelated.js').ObjectRelatedRawState>
+ * )} ObjectCalculatedParentRawState
+ */
+/**
+ *
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<(
+ *     ObjectCalculatedParentRawState
+ * )>} ObjectCalculatedParentState - The object calculated options.
+ */
+/**
+ * The state for object calculated.
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<
+ *   ObjectCalculatedParentRawState &
+ *   ObjectCalculatedRawState
+ * >} ObjectCalculatedState
+ */
+/**
+ * The properties for object calculated.
+ *
+ * @typedef {object} ObjectCalculatedProperties
+ * @property {ObjectCalculatedParentState} parentState - The parent state.
+ * @property {ObjectCalculatedState} state - The object calculated state.
+ * @property {import('./watchesRunning.js').WatchesRunning} watchesRunning - The watches running rules.
+ * @property {import('vue').EffectScope} effectScope - The effect scope.
+ */
+/**
+ * The object calculated instance.
+ *
+ * @typedef {ObjectCalculatedProperties} ObjectCalculated
+ */
+/**
+ *
+ *
+ * @typedef {object} ObjectCalculatedRawProps
+ * @property {import('vue').Ref<ObjectCalculatedRules>} calculatedObjectRules - The calculated object rules.
+ */
+/**
+ *
+ * @typedef {({
+ *     parentState: ObjectCalculatedParentState,
+ * } & ObjectCalculatedRawProps)} ObjectCalculatedOptions
+ */
+export const objectCalculatedStateKeys: string[];
+export const objectCalculatedFunctions: any[];
+/**
+ * The object calculated state keys.
+ */
+export type ObjectCalculatedRules = {
+    [ruleKey: string]: (object: any, relatedObject: any) => any;
+};
+/**
+ * - The raw state for object calculated.
+ */
+export type ObjectCalculatedRawState = {
+    /**
+     * - The calculated object rules.
+     */
+    calculatedObjectRules: ObjectCalculatedRules;
+    /**
+     * - The calculated object.
+     */
+    calculatedObject: {
+        [ruleKey: string]: import("vue").ComputedRef<any>;
+    };
+    /**
+     * - Whether the calculated object watch is running.
+     */
+    calculatedObjectWatchRunning: boolean;
+    /**
+     * - Whether the parent state object watch is running.
+     */
+    parentStateObjectWatchRunning: boolean;
+    /**
+     * - Whether the calculated is running.
+     */
+    calculatedRunning: boolean;
+    /**
+     * - Whether the object calculated is running.
+     */
+    running: import("vue").Ref<boolean>;
+};
+export type ObjectCalculatedParentRawState = (import("./objectInstance.js").ObjectInstanceRawState & Partial<import("./objectSubscription.js").ObjectSubscriptionRawState> & Partial<import("./objectRelated.js").ObjectRelatedRawState>);
+/**
+ * - The object calculated options.
+ */
+export type ObjectCalculatedParentState = import("vue").UnwrapNestedRefs<(ObjectCalculatedParentRawState)>;
+/**
+ * The state for object calculated.
+ */
+export type ObjectCalculatedState = import("vue").UnwrapNestedRefs<ObjectCalculatedParentRawState & ObjectCalculatedRawState>;
+/**
+ * The properties for object calculated.
+ */
+export type ObjectCalculatedProperties = {
+    /**
+     * - The parent state.
+     */
+    parentState: ObjectCalculatedParentState;
+    /**
+     * - The object calculated state.
+     */
+    state: ObjectCalculatedState;
+    /**
+     * - The watches running rules.
+     */
+    watchesRunning: import("./watchesRunning.js").WatchesRunning;
+    /**
+     * - The effect scope.
+     */
+    effectScope: import("vue").EffectScope;
+};
+/**
+ * The object calculated instance.
+ */
+export type ObjectCalculated = ObjectCalculatedProperties;
+export type ObjectCalculatedRawProps = {
+    /**
+     * - The calculated object rules.
+     */
+    calculatedObjectRules: import("vue").Ref<ObjectCalculatedRules>;
+};
+export type ObjectCalculatedOptions = ({
+    parentState: ObjectCalculatedParentState;
+} & ObjectCalculatedRawProps);
+//# sourceMappingURL=objectCalculated.d.ts.map

package/types/use/objectCalculated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectCalculated.d.ts","sourceRoot":"","sources":["../../use/objectCalculated.js"],"names":[],"mappings":"AA2GA;;;;;;;;;GASG;AACH,2DAPW;IACV,CAAO,GAAG,EAAE,MAAM,GAAG,uBAAuB,CAAA;CACzC,GACS;IACZ,CAAM,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CACjC,CAYH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,4EAHW,uBAAuB,GACrB,gBAAgB,CA4G5B;AA3QD;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AAIH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;GAKG;AAEH,iDAOE;AAEF,8CAA4C;;;;oCArF/B;IACZ,CAAO,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,KAAK,GAAG,CAAA;CAC9D;;;;;;;;2BAKU,qBAAqB;;;;sBACrB;QACb,CAAO,OAAO,EAAE,MAAM,GAAG,OAAO,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAA;KACpD;;;;kCACU,OAAO;;;;mCACP,OAAO;;;;uBACP,OAAO;;;;aACP,OAAO,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;;6CAM3B,CACZ,OAAa,qBAAqB,EAAE,sBAAsB,GACpD,OAAO,CAAC,OAAO,yBAAyB,EAAE,0BAA0B,CAAC,GACrE,OAAO,CAAC,OAAO,oBAAoB,EAAE,qBAAqB,CAAC,CAC9D;;;;0CAMS,OAAO,KAAK,EAAE,gBAAgB,CAAC,CACrC,8BAA8B,CACjC,CAAC;;;;oCAMQ,OAAO,KAAK,EAAE,gBAAgB,CACtC,8BAA8B,GAC9B,wBAAwB,CACzB;;;;;;;;iBAOU,2BAA2B;;;;WAC3B,qBAAqB;;;;oBACrB,OAAO,qBAAqB,EAAE,cAAc;;;;iBAC5C,OAAO,KAAK,EAAE,WAAW;;;;;+BAQ1B,0BAA0B;;;;;2BAOzB,OAAO,KAAK,EAAE,GAAG,CAAC,qBAAqB,CAAC;;sCAKzC,CAAC;IACP,WAAW,EAAE,2BAA2B,CAAC;CAC5C,GAAG,wBAAwB,CAAC"}

package/types/use/objectInstance.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Initializes multiple useObjectInstance instances, returning an object of them based on the keys of the instanceArgs.
+ *
+ * @param {{[key: string]: ObjectInstanceOptions}} instanceArgs  - An object of objects to be passed to useObjectInstance.
+ * @returns {{[key: string]: ObjectInstance}} - An object of useObjectInstance instances.
+ */
+export function useObjectInstances(instanceArgs: {
+    [key: string]: ObjectInstanceOptions;
+}): {
+    [key: string]: ObjectInstance;
+};
+/**
+ * Initializes an object instance to manage CRUD operations. This setup includes reactive state management
+ * and functions to perform create, retrieve, update, delete, and patch operations based on provided CRUD
+ * configurations and arguments.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useObjectInstance } from "@arrai-innovations/reactive-helpers";
+ * import { reactive, toRef } from "vue";
+ *
+ * const props = defineProps({
+ *     app: {
+ *         type: String,
+ *         required: true,
+ *     },
+ *     model: {
+ *         type: String,
+ *         required: true,
+ *     },
+ *     pk: {
+ *         type: String,
+ *         default: '',
+ *     },
+ * });
+ *
+ * const pkRef = toRef(props, 'pk');
+ * const objectInstanceProps = reactive({
+ *   pk: pkRef,
+ *   pkKey: 'id',
+ *   crudArgs: {
+ *       app: toRef(props, "app"),
+ *       model: toRef(props, "model"),
+ *   },
+ *   retrieveArgs: {},
+ * });
+ * const objectInstance = useObjectInstance(objectInstanceProps);
+ * watch(pkRef, (newValue, oldValue) => {
+ *     if (newValue !== oldValue && newValue) {
+ *         objectInstance.retrieve();
+ *     }
+ * });
+ * </script>
+ * <template>
+ *     <!-- Display the retrieved object reactively, as a valid pk is provided in props. -->
+ *     <div>{{ objectInstance.state.object }}</div>
+ * </template>
+ * ```
+ *
+ * @param {ObjectInstanceOptions} options - The options to be passed to useObjectInstance.
+ * @returns {ObjectInstance} - An object used to manage create, retrieve, update, delete, and patch operations.
+ */
+export function useObjectInstance({ props, functions }: ObjectInstanceOptions): ObjectInstance;
+/**
+ * A composition function to manage create, retrieve, update, delete, and patch operations.
+ *
+ * @module use/objectInstance.js
+ */
+/**
+ * The object being managed by the instance. Empty object is the default.
+ *
+ * @typedef {{pkKey: string, [key: string]: any}|{}} CrudObject
+ */
+/**
+ * Arguments to be passed to the object instance.
+ *
+ * @typedef {object} ObjectInstanceOptions
+ * @property {import('vue').UnwrapNestedRefs<ObjectInstanceRawProps>} props - The reactive configuration object.
+ * @property {import('../config/objectCrud.js').ObjectCrudFunctions} functions - An object of custom crud functions to use instead of the defaults.
+ */
+/**
+ * Reactive arguments to be passed to the object instance.
+ *
+ * @typedef {object} ObjectInstanceRawProps
+ * @property {string} [pk] - The pk of the object, optional to support creating new objects.
+ * @property {string} pkKey - The pk key of the object.
+ * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {import('../config/objectCrud.js').ObjectCrudArgs} crudArgs - The arguments to be passed to the crud functions.
+ */
+/**
+ * The raw state of the object instance.
+ *
+ * @typedef {object} ObjectInstanceRawState
+ * @property {import('../config/objectCrud.js').ObjectCrudArgs} crud - The crud functions.
+ * @property {string} pk - The pk of the object.
+ * @property {string} pkKey - The pk key of the object.
+ * @property {object} retrieveArgs - The arguments to be passed to the retrieve function.
+ * @property {CrudObject} object - The object.
+ * @property {Readonly<import('vue').Ref<boolean>>} loading - Whether the object is loading.
+ * @property {Readonly<import('vue').Ref<boolean>>} errored - Whether the object errored.
+ * @property {Readonly<import('vue').Ref<Error|null>>} error - The error.
+ * @property {Readonly<import('vue').Ref<boolean>>} deleted - Whether the object is deleted.
+ */
+/**
+ * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
+ * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
+ *
+ * @typedef {import('vue').UnwrapNestedRefs<ObjectInstanceRawState>} ObjectInstanceState
+ */
+/**
+ * The functions available on the object instance.
+ *
+ * @typedef {object} ObjectInstanceFunctions
+ * @property {(args: { object: object }) => Promise<boolean>} create - Called to turn the current object into a new object on the server.
+ * @property {() => Promise<boolean>} retrieve - Called to retrieve the current object by pk from the server.
+ * @property {(args: { object: CrudObject }) => Promise<boolean>} update - Called to update the current object on the server.
+ * @property {() => Promise<boolean>} delete - Called to delete the current object on the server.
+ * @property {(args: { partialObject: CrudObject }) => Promise<boolean>} patch - Called to patch the current object on the server.
+ * @property {import('./loadingError.js').ClearErrorFn} clearError - Called to clear the error state.
+ * @property {() => void} clear - Called to clear the object state.
+ */
+/**
+ * The properties of the object instance.
+ *
+ * @typedef {object} ObjectInstanceProperties
+ * @property {ObjectInstanceState} state - The state of the object instance.
+ */
+/**
+ * The instance of the object instance.
+ *
+ * @typedef {ObjectInstanceFunctions & ObjectInstanceProperties} ObjectInstance
+ */
+/**
+ * Represents an error related to CRUD operations on an object instance. This error might be thrown
+ * when there are issues such as invalid input, network failures, or permissions issues during CRUD operations.
+ */
+export class ObjectError extends Error {
+    /**
+     * Creates an instance of ObjectError.
+     *
+     * @param {string} message - The error message.
+     * @param {string} code - The error code.
+     */
+    constructor(message: string, code: string);
+    code: string;
+}
+export const objectInstanceStateKeys: string[];
+export const objectInstanceFunctions: string[];
+/**
+ * The object being managed by the instance. Empty object is the default.
+ */
+export type CrudObject = {
+    pkKey: string;
+    [key: string]: any;
+} | {};
+/**
+ * Arguments to be passed to the object instance.
+ */
+export type ObjectInstanceOptions = {
+    /**
+     * - The reactive configuration object.
+     */
+    props: import("vue").UnwrapNestedRefs<ObjectInstanceRawProps>;
+    /**
+     * - An object of custom crud functions to use instead of the defaults.
+     */
+    functions: import("../config/objectCrud.js").ObjectCrudFunctions;
+};
+/**
+ * Reactive arguments to be passed to the object instance.
+ */
+export type ObjectInstanceRawProps = {
+    /**
+     * - The pk of the object, optional to support creating new objects.
+     */
+    pk?: string;
+    /**
+     * - The pk key of the object.
+     */
+    pkKey: string;
+    /**
+     * - The arguments to be passed to the retrieve function.
+     */
+    retrieveArgs: object;
+    /**
+     * - The arguments to be passed to the crud functions.
+     */
+    crudArgs: import("../config/objectCrud.js").ObjectCrudArgs;
+};
+/**
+ * The raw state of the object instance.
+ */
+export type ObjectInstanceRawState = {
+    /**
+     * - The crud functions.
+     */
+    crud: import("../config/objectCrud.js").ObjectCrudArgs;
+    /**
+     * - The pk of the object.
+     */
+    pk: string;
+    /**
+     * - The pk key of the object.
+     */
+    pkKey: string;
+    /**
+     * - The arguments to be passed to the retrieve function.
+     */
+    retrieveArgs: object;
+    /**
+     * - The object.
+     */
+    object: CrudObject;
+    /**
+     * - Whether the object is loading.
+     */
+    loading: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * - Whether the object errored.
+     */
+    errored: Readonly<import("vue").Ref<boolean>>;
+    /**
+     * - The error.
+     */
+    error: Readonly<import("vue").Ref<Error | null>>;
+    /**
+     * - Whether the object is deleted.
+     */
+    deleted: Readonly<import("vue").Ref<boolean>>;
+};
+/**
+ * Manages a reactive state of an object including its CRUD status, loading states, and any operational errors.
+ * Reactivity ensures that any changes in state immediately reflect in the UI components that depend on this state.
+ */
+export type ObjectInstanceState = import("vue").UnwrapNestedRefs<ObjectInstanceRawState>;
+/**
+ * The functions available on the object instance.
+ */
+export type ObjectInstanceFunctions = {
+    /**
+     * - Called to turn the current object into a new object on the server.
+     */
+    create: (args: {
+        object: object;
+    }) => Promise<boolean>;
+    /**
+     * - Called to retrieve the current object by pk from the server.
+     */
+    retrieve: () => Promise<boolean>;
+    /**
+     * - Called to update the current object on the server.
+     */
+    update: (args: {
+        object: CrudObject;
+    }) => Promise<boolean>;
+    /**
+     * - Called to delete the current object on the server.
+     */
+    delete: () => Promise<boolean>;
+    /**
+     * - Called to patch the current object on the server.
+     */
+    patch: (args: {
+        partialObject: CrudObject;
+    }) => Promise<boolean>;
+    /**
+     * - Called to clear the error state.
+     */
+    clearError: import("./loadingError.js").ClearErrorFn;
+    /**
+     * - Called to clear the object state.
+     */
+    clear: () => void;
+};
+/**
+ * The properties of the object instance.
+ */
+export type ObjectInstanceProperties = {
+    /**
+     * - The state of the object instance.
+     */
+    state: ObjectInstanceState;
+};
+/**
+ * The instance of the object instance.
+ */
+export type ObjectInstance = ObjectInstanceFunctions & ObjectInstanceProperties;
+//# sourceMappingURL=objectInstance.d.ts.map

package/types/use/objectInstance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectInstance.d.ts","sourceRoot":"","sources":["../../use/objectInstance.js"],"names":[],"mappings":"AAmHA;;;;;GAKG;AACH,iDAHW;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAAA;CAAC,GACpC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAAA;CAAC,CAS3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wDAHW,qBAAqB,GACnB,cAAc,CAkM1B;AAjXD;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;GAGG;AACH;IACI;;;;;OAKG;IACH,qBAHW,MAAM,QACN,MAAM,EAMhB;IADG,aAAgB;CAEvB;AAED,+CAUE;AAEF,+CAAkH;;;;yBAnGrG;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAC,GAAC,EAAE;;;;;;;;WAOrC,OAAO,KAAK,EAAE,gBAAgB,CAAC,sBAAsB,CAAC;;;;eACtD,OAAO,yBAAyB,EAAE,mBAAmB;;;;;;;;;SAOrD,MAAM;;;;WACN,MAAM;;;;kBACN,MAAM;;;;cACN,OAAO,yBAAyB,EAAE,cAAc;;;;;;;;;UAOhD,OAAO,yBAAyB,EAAE,cAAc;;;;QAChD,MAAM;;;;WACN,MAAM;;;;kBACN,MAAM;;;;YACN,UAAU;;;;aACV,QAAQ,CAAC,OAAO,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;;;;aACpC,QAAQ,CAAC,OAAO,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;;;;WACpC,QAAQ,CAAC,OAAO,KAAK,EAAE,GAAG,CAAC,KAAK,GAAC,IAAI,CAAC,CAAC;;;;aACvC,QAAQ,CAAC,OAAO,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;;;;;;kCAOrC,OAAO,KAAK,EAAE,gBAAgB,CAAC,sBAAsB,CAAC;;;;;;;;YAOrD,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC;;;;cAC9C,MAAM,OAAO,CAAC,OAAO,CAAC;;;;YACtB,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC;;;;YAClD,MAAM,OAAO,CAAC,OAAO,CAAC;;;;WACtB,CAAC,IAAI,EAAE;QAAE,aAAa,EAAE,UAAU,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC;;;;gBACzD,OAAO,mBAAmB,EAAE,YAAY;;;;WACxC,MAAM,IAAI;;;;;;;;;WAOV,mBAAmB;;;;;6BAMpB,uBAAuB,GAAG,wBAAwB"}