j-templates 7.0.65 → 7.0.67

package/Store/Store/storeAsync.js

@@ -6,12 +6,59 @@ const json_1 = require("../../Utils/json");
 const diffAsync_1 = require("../Diff/diffAsync");
 const observableNode_1 = require("../Tree/observableNode");
 const store_1 = require("./store");
+/**
+ * StoreAsync class extends the base Store class to provide asynchronous data management operations.
+ * This class handles writing, patching, pushing, and splicing data in an asynchronous manner.
+ *
+ * StoreAsync is designed to work with observable data structures, allowing for efficient updates
+ * and notifications when data changes. It is particularly useful for scenarios where asynchronous
+ * operations are preferred or required, such as handling large datasets or performing complex diffs
+ * without blocking the main thread.
+ *
+ * @example
+ * // Creating a StoreAsync instance
+ * const store = new StoreAsync();
+ *
+ * // Writing data to the store asynchronously
+ * await store.Write({ name: "John", age: 30 }, "user");
+ *
+ * // Patching existing data asynchronously
+ * await store.Patch("user", { age: 31 });
+ *
+ * // Pushing data into an array asynchronously
+ * await store.Push("user.array", { id: 1 }, { id: 2 });
+ *
+ * // Splicing an array asynchronously
+ * const deletedItems = await store.Splice("user.array", 0, 1, { id: 3 });
+ *
+ * // Cleaning up resources
+ * store.Destroy();
+ *
+ * @see Store
+ * @see StoreSync
+ * @see DiffAsync
+ */
 class StoreAsync extends store_1.Store {
+    /**
+     * Creates an instance of StoreAsync.
+     * @param keyFunc Optional function to generate a key for a given data value.
+     */
     constructor(keyFunc) {
         super(keyFunc);
+        /**
+         * The async queue instance used to manage asynchronous operations in a non-blocking manner.
+         * @private
+         */
         this.queue = new asyncQueue_1.AsyncQueue();
         this.diff = new diffAsync_1.DiffAsync(keyFunc);
     }
+    /**
+     * Writes data to the store asynchronously.
+     * This method ensures that write operations are queued and executed in a non-blocking manner.
+     * @param data The data to be written. Can be of any type.
+     * @param key Optional key for the data. If not provided, the keyFunc will be used to generate a key.
+     * @throws Will throw an error if no key is provided for the data.
+     */
     async Write(data, key) {
         await this.queue.Next(async () => {
             key = key || this.keyFunc?.(data);
@@ -21,6 +68,13 @@ class StoreAsync extends store_1.Store {
             this.UpdateRootMap(diffResult);
         });
     }
+    /**
+     * Patches an existing value in the store with new data asynchronously.
+     * This method ensures that patch operations are queued and executed in a non-blocking manner.
+     * @param key The key of the value to be patched.
+     * @param patch The patch data to be merged with the existing value.
+     * @throws Will throw an error if the value to be patched is undefined.
+     */
     async Patch(key, patch) {
         await this.queue.Next(async () => {
             const value = this.Get(key);
@@ -32,6 +86,12 @@ class StoreAsync extends store_1.Store {
             this.UpdateRootMap(diffResult);
         });
     }
+    /**
+     * Pushes data into an array stored at the specified key asynchronously.
+     * This method ensures that push operations are queued and executed in a non-blocking manner.
+     * @param key The key of the array where data will be pushed.
+     * @param data The data items to be pushed into the array.
+     */
     async Push(key, ...data) {
         await this.queue.Next(async () => {
             const arr = this.Get(key);
@@ -45,6 +105,16 @@ class StoreAsync extends store_1.Store {
             this.UpdateRootMap(diffResult);
         });
     }
+    /**
+     * Splices an array stored at the specified key with new data asynchronously.
+     * This method ensures that splice operations are queued and executed in a non-blocking manner.
+     * It modifies the array by deleting elements and inserting new ones at the specified position.
+     * @param key The key of the array to be spliced.
+     * @param start The position at which to start changing the array.
+     * @param deleteCount Optional number of elements to delete. If not provided, all elements from start to end will be deleted.
+     * @param items Optional elements to insert into the array.
+     * @returns The array of deleted elements.
+     */
     async Splice(key, start, deleteCount, ...items) {
         return await this.queue.Next(async () => {
             const arr = this.Get(key);
@@ -56,6 +126,10 @@ class StoreAsync extends store_1.Store {
             return spliceResult;
         });
     }
+    /**
+     * Destroys the StoreAsync instance, stopping the async queue and cleaning up the diff instance.
+     * This method should be called when the instance is no longer needed to free up resources.
+     */
     Destroy() {
         this.queue.Stop();
         this.diff.Destroy();

package/Store/Store/storeSync.d.ts

@@ -1,9 +1,71 @@
 import { Store } from "./store";
+/**
+ * StoreSync class extends the base Store class to provide synchronous data management operations.
+ * This class handles writing, patching, pushing, and splicing data in a synchronous manner.
+ *
+ * StoreSync is designed to work with observable data structures, allowing for efficient updates
+ * and notifications when data changes. It is particularly useful for scenarios where synchronous
+ * operations are preferred or required.
+ *
+ * @example
+ * // Creating a StoreSync instance
+ * const store = new StoreSync();
+ *
+ * // Writing data to the store
+ * store.Write({ name: "John", age: 30 }, "user");
+ *
+ * // Patching existing data
+ * store.Patch("user", { age: 31 });
+ *
+ * // Pushing data into an array
+ * store.Push("user.array", { id: 1 }, { id: 2 });
+ *
+ * // Splicing an array
+ * const deletedItems = store.Splice("user.array", 0, 1, { id: 3 });
+ *
+ * @see Store
+ * @see StoreAsync
+ * @see DiffSync
+ */
 export declare class StoreSync extends Store {
+    /**
+     * The diff instance used to compute differences between current and new data states.
+     * @private
+     */
     private diff;
+    /**
+     * Creates an instance of StoreSync.
+     * @param keyFunc Optional function to generate a key for a given data value.
+     */
     constructor(keyFunc?: (value: any) => string | undefined);
+    /**
+     * Writes data to the store synchronously.
+     * @param data The data to be written. Can be of any type.
+     * @param key Optional key for the data. If not provided, the keyFunc will be used to generate a key.
+     * @throws Will throw an error if no key is provided for the data.
+     */
     Write(data: unknown, key?: string): void;
+    /**
+     * Patches an existing value in the store with new data synchronously.
+     * @param key The key of the value to be patched.
+     * @param patch The patch data to be merged with the existing value.
+     * @throws Will throw an error if the value to be patched is undefined.
+     */
     Patch(key: string, patch: unknown): void;
+    /**
+     * Pushes data into an array stored at the specified key synchronously.
+     * @param key The key of the array where data will be pushed.
+     * @param data The data items to be pushed into the array.
+     */
     Push(key: string, ...data: unknown[]): void;
+    /**
+     * Splices an array stored at the specified key with new data synchronously.
+     * This method modifies the array by deleting elements and inserting new ones at the specified position.
+     * @param key The key of the array to be spliced.
+     * @param start The position at which to start changing the array.
+     * @param deleteCount Optional number of elements to delete. If not provided, all elements from start to end will be deleted.
+     * @param items Optional elements to insert into the array.
+     * @returns The array of deleted elements.
+     */
     Splice(key: string, start: number, deleteCount?: number, ...items: unknown[]): any[];
 }

package/Store/Store/storeSync.js

@@ -5,11 +5,49 @@ const json_1 = require("../../Utils/json");
 const diffSync_1 = require("../Diff/diffSync");
 const observableNode_1 = require("../Tree/observableNode");
 const store_1 = require("./store");
+/**
+ * StoreSync class extends the base Store class to provide synchronous data management operations.
+ * This class handles writing, patching, pushing, and splicing data in a synchronous manner.
+ *
+ * StoreSync is designed to work with observable data structures, allowing for efficient updates
+ * and notifications when data changes. It is particularly useful for scenarios where synchronous
+ * operations are preferred or required.
+ *
+ * @example
+ * // Creating a StoreSync instance
+ * const store = new StoreSync();
+ *
+ * // Writing data to the store
+ * store.Write({ name: "John", age: 30 }, "user");
+ *
+ * // Patching existing data
+ * store.Patch("user", { age: 31 });
+ *
+ * // Pushing data into an array
+ * store.Push("user.array", { id: 1 }, { id: 2 });
+ *
+ * // Splicing an array
+ * const deletedItems = store.Splice("user.array", 0, 1, { id: 3 });
+ *
+ * @see Store
+ * @see StoreAsync
+ * @see DiffSync
+ */
 class StoreSync extends store_1.Store {
+    /**
+     * Creates an instance of StoreSync.
+     * @param keyFunc Optional function to generate a key for a given data value.
+     */
     constructor(keyFunc) {
         super(keyFunc);
         this.diff = new diffSync_1.DiffSync(keyFunc);
     }
+    /**
+     * Writes data to the store synchronously.
+     * @param data The data to be written. Can be of any type.
+     * @param key Optional key for the data. If not provided, the keyFunc will be used to generate a key.
+     * @throws Will throw an error if no key is provided for the data.
+     */
     Write(data, key) {
         data = (0, json_1.JsonDeepClone)(data);
         key = key || this.keyFunc?.(data);
@@ -18,6 +56,12 @@ class StoreSync extends store_1.Store {
         const diffResult = this.diff.DiffPath(key, data);
         this.UpdateRootMap(diffResult);
     }
+    /**
+     * Patches an existing value in the store with new data synchronously.
+     * @param key The key of the value to be patched.
+     * @param patch The patch data to be merged with the existing value.
+     * @throws Will throw an error if the value to be patched is undefined.
+     */
     Patch(key, patch) {
         const value = this.Get(key);
         if (value === undefined)
@@ -27,6 +71,11 @@ class StoreSync extends store_1.Store {
         const diffResult = this.diff.DiffPath(key, mergedJson);
         this.UpdateRootMap(diffResult);
     }
+    /**
+     * Pushes data into an array stored at the specified key synchronously.
+     * @param key The key of the array where data will be pushed.
+     * @param data The data items to be pushed into the array.
+     */
     Push(key, ...data) {
         const arr = this.Get(key);
         const batch = data.map(function (d, i) {
@@ -38,6 +87,15 @@ class StoreSync extends store_1.Store {
         const diffResult = this.diff.DiffBatch(batch);
         this.UpdateRootMap(diffResult);
     }
+    /**
+     * Splices an array stored at the specified key with new data synchronously.
+     * This method modifies the array by deleting elements and inserting new ones at the specified position.
+     * @param key The key of the array to be spliced.
+     * @param start The position at which to start changing the array.
+     * @param deleteCount Optional number of elements to delete. If not provided, all elements from start to end will be deleted.
+     * @param items Optional elements to insert into the array.
+     * @returns The array of deleted elements.
+     */
     Splice(key, start, deleteCount, ...items) {
         const arr = this.Get(key);
         const arrValue = arr[observableNode_1.GET_OBSERVABLE_VALUE];

package/Store/Tree/observableNode.d.ts

@@ -4,6 +4,7 @@ export declare const GET_OBSERVABLE_VALUE = "____getObservableValue";
 export declare const GET_TO_JSON = "toJSON";
 export declare namespace ObservableNode {
     function BypassProxy(value: boolean): void;
+    function Unwrap<T>(value: T): T;
     function Create<T>(value: T): T;
     function Touch(value: unknown, prop?: string | number): void;
     function ApplyDiff(rootNode: any, diffResult: JsonDiffResult): void;

package/Store/Tree/observableNode.js

@@ -87,7 +87,7 @@ function CreateProxyFactory(alias) {
     const ToJson = alias !== undefined ? ToJsonCopy : ToJsonDefault;
     const readOnly = alias !== undefined;
     function CreateArrayProxy(value) {
-        const scope = observableScope_1.ObservableScope.Create(() => value);
+        const scope = observableScope_1.ObservableScope.Create(() => value, false, true);
         const proxy = new Proxy(value, {
             get: ArrayProxyGetter,
             set: ArrayProxySetter,
@@ -235,7 +235,7 @@ function CreateProxyFactory(alias) {
         leafScopes[prop] ??= observableScope_1.ObservableScope.Create(function () {
             const value = parent[prop];
             return CreateProxyFromValue(value);
-        });
+        }, false, true);
         return observableScope_1.ObservableScope.Value(leafScopes[prop]);
     }
     function CreateProxyFromValue(value) {
@@ -268,6 +268,10 @@ var ObservableNode;
         bypassProxy = value;
     }
     ObservableNode.BypassProxy = BypassProxy;
+    function Unwrap(value) {
+        return UnwrapProxy(value);
+    }
+    ObservableNode.Unwrap = Unwrap;
     function Create(value) {
         return DefaultCreateProxy(value);
     }

package/Store/Tree/observableScope.d.ts

@@ -1,64 +1,39 @@
 import { Emitter, EmitterCallback } from "../../Utils/emitter";
-import { IDestroyable } from "../../Utils/utils.types";
-export declare class ObservableScopeValue<T> {
-    protected scope: IObservableScope<T>;
-    get Value(): T;
-    constructor(scope: IObservableScope<T>);
-}
-export declare class ObservableScopeWrapper<T> extends ObservableScopeValue<T> implements IDestroyable {
-    private scopeEmitter;
-    constructor(scope: IObservableScope<T>);
-    Scope<O>(callback: {
-        (parent: T): O;
-    }): ObservableScope<O>;
-    Watch(callback: {
-        (scope: ObservableScopeValue<T>): void;
-    }): void;
-    Unwatch(callback: {
-        (scope: ObservableScopeValue<T>): void;
-    }): void;
-    Destroy(): void;
-}
-export declare class ObservableScope<T> extends ObservableScopeWrapper<T> {
-    constructor(getFunction: {
-        (): T | Promise<T>;
-    });
+interface IStaticObservableScope<T> {
+    type: "static";
+    value: T;
 }
-export interface IObservableScope<T> extends IDestroyable {
-    getFunction: {
-        (): T;
-    };
-    setCallback: EmitterCallback;
+interface IDynamicObservableScope<T> {
+    type: "dynamic";
     async: boolean;
-    value: T;
-    promise: Promise<T> | null;
+    greedy: boolean;
     dirty: boolean;
+    destroyed: boolean;
+    getFunction: () => Promise<T> | T;
+    setCallback: EmitterCallback;
+    value: T;
     emitter: Emitter;
     emitters: (Emitter | null)[];
+    onDestroyed: Emitter | null;
     calcScopes: {
         [id: string]: IObservableScope<unknown> | null;
     } | null;
-    calc: boolean;
-    onDestroyed: Emitter | null;
-    destroyed: boolean;
 }
-export declare function CalcScope<T>(callback: () => T, idOverride?: string): unknown;
+export type IObservableScope<T> = IStaticObservableScope<T> | IDynamicObservableScope<T>;
+export declare function CalcScope<T>(callback: () => T, idOverride?: string): T;
 export declare namespace ObservableScope {
     function Create<T>(valueFunction: {
         (): T | Promise<T>;
-    }, calc?: boolean): IObservableScope<T>;
-    function CreateIf<T>(valueFunction: {
-        (): T | Promise<T>;
-    }): [T, IObservableScope<T> | null];
+    }, greedy?: boolean, force?: boolean): IObservableScope<T>;
     function Register(emitter: Emitter): void;
-    function Init<T>(scope: IObservableScope<T>): void;
     function Peek<T>(scope: IObservableScope<T>): T;
     function Value<T>(scope: IObservableScope<T>): T;
     function Touch<T>(scope: IObservableScope<T>): void;
     function Watch<T>(scope: IObservableScope<T>, callback: EmitterCallback<[IObservableScope<T>]>): void;
-    function Unwatch<T>(scope: IObservableScope<T>, callback: EmitterCallback<[IObservableScope<T> | ObservableScopeValue<T>]>): void;
+    function Unwatch<T>(scope: IObservableScope<T>, callback: EmitterCallback<[IObservableScope<T>]>): void;
     function OnDestroyed(scope: IObservableScope<unknown>, callback: EmitterCallback): void;
     function Update(scope: IObservableScope<any>): void;
     function Destroy<T>(scope: IObservableScope<T>): void;
     function DestroyAll(scopes: IObservableScope<unknown>[]): void;
 }
+export {};