j-templates 7.0.65 → 7.0.67

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 {};