j-templates 7.0.64 → 7.0.66

package/Utils/decorators.js

@@ -1,38 +1,140 @@
 "use strict";
+/**
+ * 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
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bound = void 0;
 exports.Computed = Computed;
 exports.ComputedAsync = ComputedAsync;
 exports.State = State;
 exports.Value = Value;
 exports.Scope = Scope;
+exports.Watch = Watch;
 exports.Inject = Inject;
 exports.Destroy = Destroy;
+// import { Component } from "../Node/component";
 const observableScope_1 = require("../Store/Tree/observableScope");
+// import { ElementNodeRefTypes } from "../Node/nodeRef.types";
 const observableNode_1 = require("../Store/Tree/observableNode");
 const Store_1 = require("../Store");
+/**
+ * WeakMap for storing node instances and their associated properties.
+ * @private
+ */
 const nodeInstanceMap = new WeakMap();
+/**
+ * WeakMap for storing scope instances and their associated properties.
+ * @private
+ */
 const scopeInstanceMap = new WeakMap();
+const boundPrototypeMap = new WeakMap();
+/**
+ * WeakMap for storing arrays of properties that need to be destroyed for each prototype.
+ * @private
+ */
 const destroyPrototypeMap = new WeakMap();
+/**
+ * Retrieves the node map for a given instance.
+ * If the map does not exist, it creates a new one and associates it with the instance.
+ * @private
+ * @param instance The instance for which to retrieve the node map.
+ * @returns The node map associated with the instance.
+ */
 function GetNodeMapForInstance(instance) {
     const map = nodeInstanceMap.get(instance) ?? {};
     nodeInstanceMap.set(instance, map);
     return map;
 }
+/**
+ * Retrieves the scope map for a given instance.
+ * If the map does not exist, it creates a new one and associates it with the instance.
+ * @private
+ * @param instance The instance for which to retrieve the scope map.
+ * @returns The scope map associated with the instance.
+ */
 function GetScopeMapForInstance(instance) {
     const map = scopeInstanceMap.get(instance) ?? {};
     scopeInstanceMap.set(instance, map);
     return map;
 }
-function GetDestroyArrayForPrototype(prototype) {
-    const array = destroyPrototypeMap.get(prototype) ?? [];
-    destroyPrototypeMap.set(prototype, array);
+function GetBoundArrayForPrototype(prototype, create = true) {
+    let array = boundPrototypeMap.get(prototype);
+    if (create) {
+        array ??= [];
+        boundPrototypeMap.set(prototype, array);
+    }
     return array;
 }
+/**
+ * Retrieves the destroy array for a given prototype.
+ * If the array does not exist, it creates a new one and associates it with the prototype.
+ * @private
+ * @param prototype The prototype for which to retrieve the destroy array.
+ * @returns The array of properties to be destroyed for the prototype.
+ */
+function GetDestroyArrayForPrototype(prototype, create = true) {
+    let array = destroyPrototypeMap.get(prototype);
+    if (create) {
+        array ??= [];
+        destroyPrototypeMap.set(prototype, array);
+    }
+    return array;
+}
+function CreateComputedScope(getter, defaultValue, store) {
+    const getterScope = observableScope_1.ObservableScope.Create(getter, true);
+    observableScope_1.ObservableScope.Watch(getterScope, (scope) => {
+        const data = observableScope_1.ObservableScope.Value(scope);
+        store.Write(data, "root");
+    });
+    observableScope_1.ObservableScope.Init(getterScope);
+    const propertyScope = observableScope_1.ObservableScope.Create(() => store.Get("root", defaultValue));
+    observableScope_1.ObservableScope.OnDestroyed(propertyScope, function () {
+        observableScope_1.ObservableScope.Destroy(getterScope);
+        if (store instanceof Store_1.StoreAsync)
+            store.Destroy();
+    });
+    return propertyScope;
+}
+/**
+ * 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.
+ */
 function Computed(defaultValue) {
     return function (target, propertyKey, descriptor) {
         return ComputedDecorator(target, propertyKey, descriptor, defaultValue);
     };
 }
+/**
+ * Computed decorator implementation for creating synchronous computed properties.
+ * @private
+ * @param target The target object.
+ * @param prop The property key.
+ * @param descriptor The property descriptor.
+ * @param defaultValue The default value to be used if the computed property is not defined.
+ * @returns A property descriptor that replaces the original descriptor with a computed implementation.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ */
 function ComputedDecorator(target, prop, descriptor, defaultValue) {
     const propertyKey = prop;
     if (!(descriptor && descriptor.get))
@@ -46,28 +148,45 @@ function ComputedDecorator(target, prop, descriptor, defaultValue) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const getterScope = observableScope_1.ObservableScope.Create(async () => getter.call(this));
-                const syncStore = new Store_1.StoreSync();
-                observableScope_1.ObservableScope.Watch(getterScope, (scope) => {
-                    const data = observableScope_1.ObservableScope.Value(scope);
-                    syncStore.Write(data, "root");
-                });
-                observableScope_1.ObservableScope.Init(getterScope);
-                const propertyScope = observableScope_1.ObservableScope.Create(() => syncStore.Get("root", defaultValue));
-                observableScope_1.ObservableScope.OnDestroyed(propertyScope, function () {
-                    observableScope_1.ObservableScope.Destroy(getterScope);
-                });
+                const propertyScope = CreateComputedScope(getter.bind(this), undefined, new Store_1.StoreSync());
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);
         },
     };
 }
+/**
+ * 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.
+ */
 function ComputedAsync(defaultValue) {
     return function (target, propertyKey, descriptor) {
         return ComputedAsyncDecorator(target, propertyKey, descriptor, defaultValue);
     };
 }
+/**
+ * ComputedAsync decorator implementation for creating asynchronous computed properties.
+ * @private
+ * @param target The target object.
+ * @param prop The property key.
+ * @param descriptor The property descriptor.
+ * @param defaultValue The default value to be used if the computed property is not defined.
+ * @returns A property descriptor that replaces the original descriptor with a computed implementation.
+ * @throws Will throw an error if the property is not a getter or if it has a setter.
+ */
 function ComputedAsyncDecorator(target, prop, descriptor, defaultValue) {
     const propertyKey = prop;
     if (!(descriptor && descriptor.get))
@@ -81,26 +200,36 @@ function ComputedAsyncDecorator(target, prop, descriptor, defaultValue) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const getterScope = observableScope_1.ObservableScope.Create(() => getter.call(this));
-                const asyncStore = new Store_1.StoreAsync();
-                observableScope_1.ObservableScope.Watch(getterScope, (scope) => {
-                    asyncStore.Write(observableScope_1.ObservableScope.Value(scope), "root");
-                });
-                observableScope_1.ObservableScope.Init(getterScope);
-                const propertyScope = observableScope_1.ObservableScope.Create(() => asyncStore.Get("root", defaultValue));
-                observableScope_1.ObservableScope.OnDestroyed(propertyScope, function () {
-                    observableScope_1.ObservableScope.Destroy(getterScope);
-                    asyncStore.Destroy();
-                });
+                const propertyScope = CreateComputedScope(getter.bind(this), defaultValue, new Store_1.StoreAsync());
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);
         },
     };
 }
+/**
+ * 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.
+ */
 function State() {
     return StateDecorator;
 }
+/**
+ * State decorator implementation for creating state properties.
+ * @private
+ * @param target The target object.
+ * @param propertyKey The property key.
+ * @returns A property descriptor that replaces the original descriptor with a state implementation.
+ */
 function StateDecorator(target, propertyKey) {
     return {
         configurable: false,
@@ -119,14 +248,40 @@ function StateDecorator(target, propertyKey) {
         },
     };
 }
+/**
+ * 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.
+ */
 function Value() {
     return ValueDecorator;
 }
+/**
+ * Creates a value scope for a given tuple.
+ * @private
+ * @param tuple The tuple containing the scope and value.
+ * @returns An observable scope created from the tuple's value.
+ */
 function CreateValueScope(tuple) {
     return observableScope_1.ObservableScope.Create(function () {
         return tuple[1];
     });
 }
+/**
+ * Value decorator implementation for creating value properties.
+ * @private
+ * @param target The target object.
+ * @param propertyKey The property key.
+ * @returns A property descriptor that replaces the original descriptor with a value implementation.
+ */
 function ValueDecorator(target, propertyKey) {
     return {
         configurable: false,
@@ -146,9 +301,33 @@ function ValueDecorator(target, propertyKey) {
         },
     };
 }
+/**
+ * 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.
+ */
 function Scope() {
     return 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.
+ */
 function ScopeDecorator(target, propertyKey, descriptor) {
     if (!(descriptor && descriptor.get))
         throw "Scope decorator requires a getter";
@@ -168,6 +347,51 @@ function ScopeDecorator(target, propertyKey, descriptor) {
         },
     };
 }
+function Watch(scope) {
+    return function (target, propertyKey, descriptor) {
+        return WatchDecorator(target, propertyKey, descriptor, scope);
+    };
+}
+function WatchDecorator(target, propertyKey, descriptor, scopeFunction) {
+    if (!descriptor || typeof descriptor.value !== "function")
+        throw "Watch decorator requires a function";
+    function bindWatch(instance) {
+        function scopeFunctionWrapper() {
+            return scopeFunction(instance);
+        }
+        const [value, scope] = observableScope_1.ObservableScope.CreateIf(scopeFunctionWrapper, true);
+        if (scope) {
+            const propertyMap = GetScopeMapForInstance(this);
+            propertyMap[propertyKey] = [scope, undefined];
+            observableScope_1.ObservableScope.Watch(scope, function (scope) {
+                instance[propertyKey](observableScope_1.ObservableScope.Value(scope));
+            });
+        }
+        instance[propertyKey](value);
+        return instance;
+    }
+    const boundArray = GetBoundArrayForPrototype(target);
+    boundArray.push(bindWatch);
+}
+/**
+ * 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.
+ */
 function Inject(type) {
     return function () {
         return InjectDecorator(type);
@@ -185,9 +409,32 @@ function InjectDecorator(type) {
         },
     };
 }
+/**
+ * Destroy decorator factory for marking a property to be destroyed when the component is destroyed.
+ * @example
+ * class MyComponent extends Component {
+ *   @Destroy()
+ *   timer: Timer;
+ * }
+ */
 function Destroy() {
     return DestroyDecorator;
 }
+var Bound;
+(function (Bound) {
+    function All(value) {
+        const array = GetBoundArrayForPrototype(Object.getPrototypeOf(value), false);
+        for (let x = 0; array && x < array.length; x++)
+            array[x](value);
+    }
+    Bound.All = All;
+})(Bound || (exports.Bound = Bound = {}));
+/**
+ * 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);
+ */
 (function (Destroy) {
     function All(value) {
         const scopeMap = scopeInstanceMap.get(value);
@@ -196,8 +443,8 @@ function Destroy() {
             for (let x = 0; x < values.length; x++)
                 observableScope_1.ObservableScope.Destroy(values[x][0]);
         }
-        const array = GetDestroyArrayForPrototype(Object.getPrototypeOf(value));
-        for (let x = 0; x < array.length; x++)
+        const array = GetDestroyArrayForPrototype(Object.getPrototypeOf(value), false);
+        for (let x = 0; array && x < array.length; x++)
             value[array[x]].Destroy();
     }
     Destroy.All = All;

package/Utils/injector.d.ts

@@ -1,12 +1,36 @@
+/**
+ * Simple scoped dependency injection class. Manages types/instances as key/value pairs.
+ */
 export declare class Injector {
     private parent;
     private typeMap;
     constructor();
+    /**
+     * Get instance/value based on a key type. Searches for a match
+     * through all parent Injectors.
+     *
+     * @param type Key to retrieve from the Injector map
+     */
     Get<T>(type: any): T;
+    /**
+     * Set instance/value based on a key type at this scope.
+     *
+     * @param type Type key
+     * @param instance Value instance for this type key
+     */
     Set<T>(type: any, instance: T): T;
 }
 export declare namespace Injector {
+    /**
+     * Get the current Injector scope.
+     */
     function Current(): Injector;
+    /**
+     * Creates a child scope with the passed Injector instance.
+     *
+     * @param injector Injector instance for this scope
+     * @param action Callback to invoke for this scope
+     */
     function Scope<R = void, P extends any[] = []>(injector: Injector, action: {
         (...args: P): R;
     }, ...args: P): R;

package/Utils/injector.js

@@ -1,17 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Injector = void 0;
+/**
+ * Simple scoped dependency injection class. Manages types/instances as key/value pairs.
+ */
 class Injector {
     constructor() {
         this.parent = Injector.Current();
         this.typeMap = new Map();
     }
+    /**
+     * Get instance/value based on a key type. Searches for a match
+     * through all parent Injectors.
+     *
+     * @param type Key to retrieve from the Injector map
+     */
     Get(type) {
         if (this.typeMap.has(type)) {
             return this.typeMap.get(type);
         }
         return this.parent ? this.parent.Get(type) : undefined;
     }
+    /**
+     * Set instance/value based on a key type at this scope.
+     *
+     * @param type Type key
+     * @param instance Value instance for this type key
+     */
     Set(type, instance) {
         this.typeMap.set(type, instance);
         return instance;
@@ -20,10 +35,19 @@ class Injector {
 exports.Injector = Injector;
 (function (Injector) {
     var scope = null;
+    /**
+     * Get the current Injector scope.
+     */
     function Current() {
         return scope;
     }
     Injector.Current = Current;
+    /**
+     * Creates a child scope with the passed Injector instance.
+     *
+     * @param injector Injector instance for this scope
+     * @param action Callback to invoke for this scope
+     */
     function Scope(injector, action, ...args) {
         const parent = Current();
         scope = injector;

package/Utils/list.js

@@ -44,7 +44,7 @@ var List;
     }
     List.Clear = Clear;
     function Push(list, data) {
-        const node = CreateNode(data);
+        const node = CreateNode(data); // { previous: null, next: null, data: data };
         if (list.size === 0) {
             list.head = node;
             list.tail = node;
@@ -81,7 +81,7 @@ var List;
     }
     List.Pop = Pop;
     function Add(list, data) {
-        const node = CreateNode(data);
+        const node = CreateNode(data); // { previous: null, next: null, data: data };
         return AddNode(list, node);
     }
     List.Add = Add;
@@ -103,7 +103,7 @@ var List;
     function AddBefore(list, node, data) {
         if (!node)
             return List.Add(list, data);
-        const newNode = CreateNode(data);
+        const newNode = CreateNode(data); // { previous: null, next: null, data: data };
         const prevNode = node.previous;
         newNode.next = node;
         node.previous = newNode;
@@ -120,7 +120,7 @@ var List;
     function AddAfter(list, node, data) {
         if (!node)
             return List.Push(list, data);
-        const newNode = CreateNode(data);
+        const newNode = CreateNode(data); // { previous: null, next: null, data: data };
         const nextNode = node.next;
         node.next = newNode;
         newNode.previous = node;

package/Utils/router.js

@@ -0,0 +1,110 @@
+// import { ObservableScope, IObservableScope } from "../Store/Tree/observableScope";
+// import { wndw } from "../DOM/window";
+// import { Store } from "../Store";
+// export abstract class Router<T extends {}> {
+//     private routeScope: IObservableScope<string>;
+//     private initPromise: Promise<void>;
+//     protected get State() {
+//         return this.store.Root.Value;
+//     }
+//     protected get ReplaceHistory() {
+//         return false;
+//     }
+//     public get Init() {
+//         return this.initPromise;
+//     }
+//     constructor(private store: Store<T>) {
+//         this.initPromise = new Promise(async (resolve, reject) => {
+//             try{
+//                 this.routeScope = ObservableScope.Create(() => this.CreateRoutePart());
+//                 await Router.Register(this);
+//                 ObservableScope.Watch(this.routeScope, () => this.ReplaceHistory ? Router.ReplaceRoute() : Router.PushRoute());
+//                 resolve();
+//             }
+//             catch(e) {
+//                 reject(e);
+//             }
+//         })
+//     }
+//     protected abstract CreateRoutePart(): string;
+//     public abstract GetRoutePart(route: string): string;
+//     public abstract Read(routePart: string): Promise<void>;
+//     public Route() {
+//         return ObservableScope.Value(this.routeScope);
+//     }
+//     public JSON() {
+//         var state = this.State;
+//         return (state as any).toJSON ? (state as any).toJSON() : state;
+//     }
+//     public async SetState(state: Partial<T>) {
+//         await this.store.Merge(state);
+//     }
+//     public Destroy() {
+//         this.routeScope.Destroy();
+//         Router.Destroy(this);
+//     }
+// }
+// export namespace Router {
+//     var leadingSlash = /^\//;
+//     var routers = [] as Array<Router<any>>;
+//     var updateScheduled = false;
+//     export function PushRoute() {
+//         if(updateScheduled)
+//             return;
+//         updateScheduled = true;
+//         setTimeout(() => {
+//             var route = routers.map(r => r.Route()).filter(r => r).join("/");
+//             route = "/" + route;
+//             var state = routers.map(r => r.JSON());
+//             if(route === wndw.location.pathname)
+//                 wndw.history.replaceState(state, "", route);
+//             else
+//                 wndw.history.pushState(state, "", route);
+//             updateScheduled = false;
+//         }, 250);
+//     }
+//     var replaceScheduled = false;
+//     export function ReplaceRoute() {
+//         if(replaceScheduled || updateScheduled)
+//             return;
+//         replaceScheduled = true;
+//         setTimeout(() => {
+//             replaceScheduled = false;
+//             if(updateScheduled)
+//                 return;
+//             var route = routers.map(r => r.Route()).filter(r => r).join("/");
+//             route = "/" + route;        
+//             var state = routers.map(r => r.JSON());
+//             wndw.history.replaceState(state, "", route);
+//         }, 250);
+//     }
+//     export function Destroy(router: Router<any>) {
+//         var index = routers.indexOf(router);
+//         if(index >= 0) {
+//             routers.splice(index, 1);
+//             ReplaceRoute();
+//         }
+//     }
+//     export async function Register(router: Router<any>) {
+//         var index = routers.indexOf(router);
+//         if(index < 0) {
+//             var route = wndw.location.pathname.replace(leadingSlash, "");
+//             for(var x=0; x<routers.length; x++) {
+//                 route = route.replace(routers[x].GetRoutePart(route), "");
+//                 route = route.replace(leadingSlash, "");
+//             }
+//             var routePart = router.GetRoutePart(route);
+//             if(routePart)
+//                 await router.Read(routePart);
+//             routers.push(router);
+//             ReplaceRoute();
+//         }
+//     }
+//     wndw.onpopstate = function(e: PopStateEvent) {
+//         var state = e.state as Array<any>;
+//         for(var x=0; x<state.length; x++) {
+//             if(x < routers.length)
+//                 routers[x].SetState(state[x]);
+//         }
+//     }
+// }