j-templates 7.0.65 → 7.0.66

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/observableScope.d.ts

@@ -42,14 +42,14 @@ export interface IObservableScope<T> extends IDestroyable {
     onDestroyed: Emitter | null;
     destroyed: boolean;
 }
-export declare function CalcScope<T>(callback: () => T, idOverride?: string): unknown;
+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): [T, IObservableScope<T> | null];
     function Register(emitter: Emitter): void;
     function Init<T>(scope: IObservableScope<T>): void;
     function Peek<T>(scope: IObservableScope<T>): T;

package/Store/Tree/observableScope.js

@@ -65,14 +65,14 @@ function WatchScope(scope) {
     watchState = parent;
     return value;
 }
-function WatchFunction(func) {
+function WatchFunction(func, greedy) {
     const parent = watchState;
     watchState = [[], null, null];
     const async = (0, functions_1.IsAsync)(func);
     const result = func();
     let scope = null;
     if (watchState[0].length > 0 || async) {
-        scope = ObservableScope.Create(func);
+        scope = ObservableScope.Create(func, greedy);
         UpdateEmitters(scope, watchState[0]);
         scope.calcScopes = watchState[2];
         UpdateValue(scope, result);
@@ -118,8 +118,8 @@ function CalcScope(callback, idOverride) {
         return scope;
     }
     ObservableScope.Create = Create;
-    function CreateIf(valueFunction) {
-        return WatchFunction(valueFunction);
+    function CreateIf(valueFunction, greedy = false) {
+        return WatchFunction(valueFunction, greedy);
     }
     ObservableScope.CreateIf = CreateIf;
     function Register(emitter) {

package/Utils/animation.d.ts

@@ -1,8 +1,14 @@
 import { IDestroyable } from "./utils.types";
+/**
+ * Supported animation functions.
+ */
 export declare enum AnimationType {
     Linear = 0,
     EaseIn = 1
 }
+/**
+ * Class for handling interpolation for basic animations.
+ */
 export declare class Animation implements IDestroyable {
     private type;
     private running;
@@ -13,16 +19,53 @@ export declare class Animation implements IDestroyable {
     private animationDuration;
     private animationUpdate;
     private animationRun;
+    /**
+     * Is the animation currently running.
+     */
     get Running(): boolean;
+    /**
+     * The starting value of the current animation.
+     */
     get Start(): number;
+    /**
+     * The ending value of the current animation.
+     */
     get End(): number;
+    /**
+     * Is this animation enabled.
+     */
     get Enabled(): boolean;
+    /**
+     * @param type Interpolation function
+     * @param duration The duration of the Animation
+     * @param update Callback invoked during the animation with the next value
+     */
     constructor(type: AnimationType, duration: number, update: {
         (next: number): void;
     });
+    /**
+     * Start an animation. Calls the passed `update` callback for each animation frame
+     * with interpolated values based on the passed `AnimationType`.
+     *
+     * @param start initial animation value
+     * @param end ending animation value
+     * @returns Promise<void> that resolves once the animation is complete
+     */
     Animate(start: number, end: number): Promise<void>;
+    /**
+     * Disables the Animation. Cancels the animation if it is running.
+     */
     Disable(): void;
+    /**
+     * Enables the Animation.
+     */
     Enable(): void;
+    /**
+     * Cancels the Animation if it is running by clearing any sheduled timeout events.
+     */
     Cancel(): void;
+    /**
+     * IDestroyable. Cancels the animation.
+     */
     Destroy(): void;
 }

package/Utils/animation.js

@@ -20,24 +20,47 @@ var StepFunctions;
     }
     StepFunctions.Linear = Linear;
 })(StepFunctions || (StepFunctions = {}));
+/**
+ * Supported animation functions.
+ */
 var AnimationType;
 (function (AnimationType) {
     AnimationType[AnimationType["Linear"] = 0] = "Linear";
     AnimationType[AnimationType["EaseIn"] = 1] = "EaseIn";
 })(AnimationType || (exports.AnimationType = AnimationType = {}));
+/**
+ * Class for handling interpolation for basic animations.
+ */
 class Animation {
+    /**
+     * Is the animation currently running.
+     */
     get Running() {
         return this.running;
     }
+    /**
+     * The starting value of the current animation.
+     */
     get Start() {
         return this.start;
     }
+    /**
+     * The ending value of the current animation.
+     */
     get End() {
         return this.end;
     }
+    /**
+     * Is this animation enabled.
+     */
     get Enabled() {
         return this.enabled;
     }
+    /**
+     * @param type Interpolation function
+     * @param duration The duration of the Animation
+     * @param update Callback invoked during the animation with the next value
+     */
     constructor(type, duration, update) {
         this.animationStart = 0;
         this.animationRun = null;
@@ -49,13 +72,23 @@ class Animation {
         this.animationDuration = duration;
         this.animationUpdate = nodeConfig_1.NodeConfig.wrapPriorityUpdates(update);
     }
+    /**
+     * Start an animation. Calls the passed `update` callback for each animation frame
+     * with interpolated values based on the passed `AnimationType`.
+     *
+     * @param start initial animation value
+     * @param end ending animation value
+     * @returns Promise<void> that resolves once the animation is complete
+     */
     Animate(start, end) {
         if (!this.enabled)
             return;
+        this.Cancel();
         const diff = end - start;
-        if (diff === 0)
+        if (diff === 0) {
+            this.animationUpdate(end);
             return;
-        this.Cancel();
+        }
         this.animationStart = Date.now();
         this.running = true;
         this.start = start;
@@ -63,8 +96,10 @@ class Animation {
         return new Promise((resolve) => {
             const stepFunc = StepFunctions[AnimationType[this.type]];
             const animationRun = () => {
-                if (this.animationRun !== animationRun)
+                if (this.animationRun !== animationRun) {
+                    resolve();
                     return;
+                }
                 const percent = stepFunc(this.animationStart, this.animationDuration);
                 const step = percent * diff;
                 const next = this.start + step;
@@ -81,19 +116,31 @@ class Animation {
             this.Cancel();
         });
     }
+    /**
+     * Disables the Animation. Cancels the animation if it is running.
+     */
     Disable() {
         this.Cancel();
         this.enabled = false;
     }
+    /**
+     * Enables the Animation.
+     */
     Enable() {
         this.enabled = true;
     }
+    /**
+     * Cancels the Animation if it is running by clearing any sheduled timeout events.
+     */
     Cancel() {
         this.running = false;
         this.start = null;
         this.end = null;
         this.animationRun = null;
     }
+    /**
+     * IDestroyable. Cancels the animation.
+     */
     Destroy() {
         this.Disable();
     }

package/Utils/array.d.ts

@@ -1,5 +1,53 @@
+/**
+ * Removes all null values from an array starting from a specified index.
+ * This function modifies the array in-place by shifting non-null elements
+ * to fill the gaps left by removed null values, then truncating the array.
+ *
+ * @param array - The array from which to remove null values. Can contain mixed types including null.
+ * @param startIndex - The index to start removing null values from (default: 0).
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, null, 2, null, 3, null, 4];
+ * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
+ *
+ * const arr2 = [null, null, 1, null, 2];
+ * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
+ * ```
+ */
 export declare function RemoveNulls(array: (unknown | null)[], startIndex?: number): void;
 export declare function ArrayDiff(source: any[], target: any[]): boolean;
+/**
+ * Reconciles two sorted arrays by applying add and remove operations to transition
+ * from the left array to the right array. Elements are compared based on their first
+ * element (index 0) which must be a number.
+ *
+ * This function efficiently handles the process of updating a sorted collection by:
+ * - Removing elements that exist in the left array but not in the right array
+ * - Adding elements that exist in the right array but not in the left array
+ *
+ * @template T - A tuple type where the first element is a number (T extends [number])
+ * @param left - The initial sorted array of tuples
+ * @param right - The target sorted array of tuples
+ * @param add - Callback function to handle adding elements
+ * @param remove - Callback function to handle removing elements
+ *
+ * @example
+ * ```typescript
+ * const left = [[1, 'a'], [3, 'c']];
+ * const right = [[2, 'b'], [3, 'c'], [4, 'd']];
+ * const added: number[] = [];
+ * const removed: number[] = [];
+ *
+ * ReconcileSortedEmitters(
+ *   left,
+ *   right,
+ *   (value) => added.push(value[0]),
+ *   (value) => removed.push(value[0])
+ * );
+ * // Adds [2, 4] and removes [1]
+ * ```
+ */
 export declare function ReconcileSortedEmitters<T extends [number]>(left: T[], right: T[], add: (value: T) => void, remove: (value: T) => void): void;
 export declare function InsertionSortTuples<T extends [number, ...any[]]>(arr: T[]): T[];
 export declare function ReconcileSortedArrays<T>(left: T[], right: T[], add: (value: T) => void, remove: (value: T) => void): void;

package/Utils/array.js

@@ -5,6 +5,23 @@ exports.ArrayDiff = ArrayDiff;
 exports.ReconcileSortedEmitters = ReconcileSortedEmitters;
 exports.InsertionSortTuples = InsertionSortTuples;
 exports.ReconcileSortedArrays = ReconcileSortedArrays;
+/**
+ * Removes all null values from an array starting from a specified index.
+ * This function modifies the array in-place by shifting non-null elements
+ * to fill the gaps left by removed null values, then truncating the array.
+ *
+ * @param array - The array from which to remove null values. Can contain mixed types including null.
+ * @param startIndex - The index to start removing null values from (default: 0).
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, null, 2, null, 3, null, 4];
+ * RemoveNulls(arr); // Removes all null values, result: [1, 2, 3, 4]
+ *
+ * const arr2 = [null, null, 1, null, 2];
+ * RemoveNulls(arr2, 2); // Starts from index 2, result: [null, null, 1, 2]
+ * ```
+ */
 function RemoveNulls(array, startIndex = 0) {
     let nullIndex = startIndex;
     for (; nullIndex < array.length && array[nullIndex] !== null; nullIndex++) { }
@@ -27,6 +44,37 @@ function ArrayDiff(source, target) {
     for (; x < source.length && source[x] === target[x]; x++) { }
     return x < source.length;
 }
+/**
+ * Reconciles two sorted arrays by applying add and remove operations to transition
+ * from the left array to the right array. Elements are compared based on their first
+ * element (index 0) which must be a number.
+ *
+ * This function efficiently handles the process of updating a sorted collection by:
+ * - Removing elements that exist in the left array but not in the right array
+ * - Adding elements that exist in the right array but not in the left array
+ *
+ * @template T - A tuple type where the first element is a number (T extends [number])
+ * @param left - The initial sorted array of tuples
+ * @param right - The target sorted array of tuples
+ * @param add - Callback function to handle adding elements
+ * @param remove - Callback function to handle removing elements
+ *
+ * @example
+ * ```typescript
+ * const left = [[1, 'a'], [3, 'c']];
+ * const right = [[2, 'b'], [3, 'c'], [4, 'd']];
+ * const added: number[] = [];
+ * const removed: number[] = [];
+ *
+ * ReconcileSortedEmitters(
+ *   left,
+ *   right,
+ *   (value) => added.push(value[0]),
+ *   (value) => removed.push(value[0])
+ * );
+ * // Adds [2, 4] and removes [1]
+ * ```
+ */
 function ReconcileSortedEmitters(left, right, add, remove) {
     let leftIndex = 0;
     let rightIndex = 0;
@@ -53,13 +101,21 @@ function ReconcileSortedEmitters(left, right, add, remove) {
 }
 function InsertionSortTuples(arr) {
     const n = arr.length;
+    // Start from the second element (index 1) as the first element (index 0)
+    // is trivially sorted by itself.
     for (let i = 1; i < n; i++) {
+        // Pick up the current element to be inserted
         const currentItem = arr[i];
+        // This is the index of the last element in the sorted sub-array
         let j = i - 1;
+        // Move elements of the sorted sub-array that are greater than currentItem,
+        // to one position ahead of their current position.
+        // We compare using the first element of the tuples (currentItem[0]).
         while (j >= 0 && arr[j][0] > currentItem[0]) {
             arr[j + 1] = arr[j];
             j--;
         }
+        // Place the currentItem in its correct position in the sorted sub-array
         arr[j + 1] = currentItem;
     }
     return arr;

package/Utils/decorators.d.ts

@@ -1,17 +1,152 @@
+/**
+ * This module provides decorators for managing state, computed values, and dependency injection in components.
+ * These decorators are designed to work with observable data structures, allowing for efficient updates and notifications.
+ *
+ * @module Utils/Decorators
+ * @see ObservableScope
+ * @see ObservableNode
+ * @see StoreAsync
+ * @see StoreSync
+ * @see Component
+ */
 import { IDestroyable } from "./utils.types";
-import { Component } from "../Node/component";
+import { Injector } from "./injector";
+/**
+ * Computed decorator factory for creating synchronous computed properties.
+ * A computed property is derived from other properties and automatically updates when its dependencies change.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @Computed({ count: 0 })
+ *   get myComputed(): { count: number } {
+ *     return { count: this.myStateValue };
+ *   }
+ * }
+ *
+ * @param defaultValue The default value to be used if the computed property is not defined.
+ * @returns A property decorator that can be applied to a getter method.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ * @remarks The computed value is backed by a StoreSync instance, which caches the latest result of the getter. When any of the getter's dependencies change, the StoreSync is updated and the computed property reflects the new value synchronously. The provided `defaultValue` is returned until the first evaluation completes.
+ */
 export declare function Computed<T extends WeakKey, K extends keyof T, V extends T[K]>(defaultValue: V): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * ComputedAsync decorator factory for creating asynchronous computed properties.
+ * A computed property is derived from other properties and automatically updates when its dependencies change.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @ComputedAsync({ items: [] })
+ *   get myAsyncComputed(): { items: any[] } {
+ *     return { items: this.myStateValue };
+ *   }
+ * }
+ *
+ * @param defaultValue The default value to be used if the computed property is not defined.
+ * @returns A property decorator that can be applied to a getter method.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ * @remarks The computed value is backed by a StoreAsync instance, which caches the result of the asynchronous getter. When dependencies change, the StoreAsync updates and the computed property resolves to the latest value. The provided `defaultValue` is returned until the async computation completes.
+ */
 export declare function ComputedAsync<T extends WeakKey, K extends keyof T, V extends T[K]>(defaultValue: V): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * State decorator factory for creating state properties.
+ * A state property is a reactive value that can be read and written synchronously.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @State()
+ *   myState: { count: number } = { count: 0 };
+ * }
+ *
+ * @returns A property decorator that can be applied to a property.
+ * @remarks The State decorator creates an ObservableNode to store the value. Updates to the property automatically notify any watchers of dependent scopes, making it ideal for mutable complex data structures that need to trigger reactivity.
+ */
 export declare function State(): any;
+/**
+ * Value decorator factory for creating value properties.
+ * A value property is a reactive value that can be read and written synchronously.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @Value()
+ *   myValue: string = "Hello";
+ * }
+ *
+ * @returns A property decorator that can be applied to a property.
+ * @remarks The Value decorator lazily creates a scoped ObservableScope whose getter returns the stored value. The setter updates the stored value and invokes ObservableScope.Update on the scope, causing any dependent computed or scope decorators to re-evaluate.
+ */
 export declare function Value(): any;
+/**
+ * Scope decorator factory for creating scope properties.
+ * A scope property is a reactive value that can be read and written synchronously.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @Scope()
+ *   get myScopeValue(): string {
+ *     return this.myStateValue + "!";
+ *   }
+ * }
+ *
+ * @returns A property decorator that can be applied to a getter method.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ */
 export declare function Scope(): typeof ScopeDecorator;
+/**
+ * Scope decorator implementation for creating scope properties.
+ * @private
+ * @param target The target object.
+ * @param propertyKey The property key.
+ * @param descriptor The property descriptor.
+ * @returns A property descriptor that replaces the original descriptor with a scope implementation.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ */
 declare function ScopeDecorator<T, K extends string>(target: T, propertyKey: K, descriptor: PropertyDescriptor): PropertyDescriptor;
-export declare function Inject<I, T extends Component<any, any, any>>(type: {
-    new (...args: Array<any>): I;
-}): (target: T, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+export declare function Watch<S extends (instance: T) => any, T extends Record<K, (value: ReturnType<S>) => any>, K extends string>(scope: S): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => void;
+type ConstructorToken<I> = {
+    new (...args: any[]): I;
+} | (abstract new (...args: any[]) => I);
+/**
+ * Inject decorator factory for creating dependency-injected properties.
+ * An injected property is automatically provided by the framework's dependency injection system.
+ *
+ * @example
+ * class MyComponent extends Component {
+ *   @Inject(Token)
+ *   property: ServiceForToken;
+ * }
+ *
+ * // Setting the value in the class definition
+ * class MyComponent extends Component {
+ *   @Inject(Token)
+ *   property: ServiceForToken = new ServiceForToken();
+ * }
+ *
+ * @param type The constructor type of the dependency to be injected.
+ * @returns A property decorator that can be applied to a property.
+ */
+export declare function Inject<I, T extends Record<K, I> & {
+    Injector: Injector;
+}, K extends string>(type: ConstructorToken<I>): (target: T, propertyKey: K, descriptor?: PropertyDescriptor) => void;
+/**
+ * Destroy decorator factory for marking a property to be destroyed when the component is destroyed.
+ * @example
+ * class MyComponent extends Component {
+ *   @Destroy()
+ *   timer: Timer;
+ * }
+ */
 export declare function Destroy(): typeof DestroyDecorator;
+export declare namespace Bound {
+    function All<T extends WeakKey>(value: T): void;
+}
+/**
+ * Utility to destroy all observable scopes and invoke destroy on marked properties of an instance.
+ * @param value The instance to clean up.
+ * @example
+ * Destroy.All(this);
+ */
 export declare namespace Destroy {
-    function All<T extends WeakKey, K>(value: T): void;
+    function All<T extends WeakKey>(value: T): void;
 }
 declare function DestroyDecorator<T extends Record<K, IDestroyable>, K extends string>(target: T, propertyKey: K): any;
 export {};