j-templates 9.0.1 → 10.0.0

package/Utils/decorators.js

@@ -5,7 +5,6 @@
  * @module Utils/Decorators
  * @see ObservableScope
  * @see ObservableNode
- * @see StoreAsync
  * @see StoreSync
  * @see Component
  *
@@ -20,7 +19,6 @@
  * | arrays (User[], Todo[])   | @State  | Array mutations tracked       |
  * | getters only (expensive)  | @Computed | Cached + object reuse via Store |
  * | getters only (simple)     | @Scope  | Cached, but new reference on update |
- * | getters only (sync, StoreAsync) | @ComputedAsync | Sync getter, StoreAsync caching + object reuse |
  * | async functions (direct scope) | ObservableScope.Create(async) | Direct async, new reference, initial null |
  * | subscribe to changes      | @Watch  | Calls method when scope value changes |
  * | dependency injection      | @Inject | Gets value from component injector |
@@ -58,7 +56,6 @@
  */
 import { ObservableScope, PeekCallback, } from "../Store/Tree/observableScope";
 import { ObservableNode } from "../Store/Tree/observableNode";
-import { StoreAsync } from "../Store";
 /**
  * WeakMap for storing node instances and their associated properties.
  * @private
@@ -122,27 +119,6 @@ function GetDestroyArrayForPrototype(prototype, create = true) {
     }
     return array;
 }
-function CreateStoreScope(getter, store, defaultValue) {
-    const getterScope = ObservableScope.Gated(function () {
-        const value = getter();
-        return ObservableNode.Clone(value);
-    });
-    ObservableScope.Watch(getterScope, (scope) => {
-        const data = ObservableScope.Peek(scope);
-        store.Write(data, "root");
-    });
-    const data = ObservableScope.Peek(getterScope);
-    store.Write(data, "root");
-    const propertyScope = ObservableScope.Create(() => {
-        return store.Get("root", defaultValue);
-    });
-    ObservableScope.OnDestroyed(propertyScope, function () {
-        ObservableScope.Destroy(getterScope);
-        if (store instanceof StoreAsync)
-            store.Destroy();
-    });
-    return propertyScope;
-}
 /**
  * Creates an observable scope that exposes a getter's value through a persistent
  * observable node, preserving the value's object identity across updates.
@@ -281,10 +257,8 @@ function CreateNodeScope(getter) {
  * - Use @Scope() for simple computations where object identity doesn't matter
  * - The diff computation overhead is justified when you need object reuse
  * @see {@link Scope} for simple getter-based reactive properties (caches but new reference)
- * @see {@link ComputedAsync} for async computed properties
  * @see {@link ObservableNode.Apply} for how diffs are applied in-place to maintain object identity
  * @see {@link ObservableScope} for the Gated scope mechanism (batched updates)
- * @see {@link StoreSync} for the store-backed variant used by @ComputedAsync
  */
 export function Computed() {
     return function (target, propertyKey, descriptor) {
@@ -320,134 +294,6 @@ function ComputedDecorator(target, prop, descriptor) {
         },
     };
 }
-/**
- * ComputedAsync decorator factory for creating synchronous computed properties with StoreAsync caching.
- * A computed property is derived from other properties and automatically updates when its dependencies change.
- *
- * IMPORTANT: Despite the name, @ComputedAsync expects a SYNC getter, NOT an async function.
- * The "Async" refers to the internal StoreAsync caching mechanism, not the getter signature.
- *
- * Use @ComputedAsync when you need synchronous caching with StoreAsync backend.
- * For direct async operations (no object reuse), use ObservableScope.Create(async () => ...) instead.
- *
- * @example
- * ```typescript
- * // ✅ Good: Synchronous getter with StoreAsync caching
- * @Value()
- * userId: string = "123";
- *
- * @ComputedAsync(null)
- * get userData(): User | null {
- *   // Sync getter - returns value directly
- *   return getUserSync(this.userId);
- * }
- * ```
- *
- * @example
- * ```typescript
- * // ❌ WRONG - Do NOT use async keyword or return Promise
- * @Value()
- * userId: string = "123";
- *
- * @ComputedAsync(null)
- * async getUser(): Promise<User> {  // ERROR: getter must be synchronous!
- *   return await fetch(`/api/users/${this.userId}`);
- * }
- *
- * // ✅ CORRECT - Use ObservableScope.Create for direct async operations
- * import { ObservableScope } from "j-templates/Store";
- *
- * @Value()
- * userId: string = "123";
- *
- * private userDataScope = ObservableScope.Create(async () => {
- *   return await fetch(`/api/users/${this.userId}`);  // Async supported here!
- * });
- *
- * get userData(): User | null {
- *   return ObservableScope.Value(this.userDataScope);  // null while loading
- * }
- * ```
- *
- * @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 @ComputedAsync decorator uses StoreAsync for caching. The getter must be a synchronous function.
- * Unlike @Computed which uses StoreSync, @ComputedAsync uses StoreAsync internally for caching.
- *
- * **Initialization**: @ComputedAsync uses lazy initialization - the scopes are created on first access:
- * ```typescript
- * @ComputedAsync(null)
- * get userData(): User | null {
- *   return getUserSync(this.userId);
- * }
- *
- * // Scope created here, on first access:
- * const user = this.userData;
- * ```
- *
- * **Caching**: Like @Computed, @ComputedAsync caches the result and maintains object identity
- * through diff-based updates. The getter only runs when dependencies change.
- *
- * **Object Reuse**: Like @Computed, the result maintains its identity across updates.
- * Only changed properties are modified in-place, preserving object references.
- *
- * **Key difference from @Computed**: Uses StoreAsync instead of StoreSync for caching.
- * Both use synchronous getters and provide object identity preservation.
- *
- * **Comparison**:
- * | Aspect | @Scope | @Computed | @ComputedAsync | scope(async) + @Scope |
- * |--------|--------|-----------|----------------|----------------------|
- * | Caches value | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes (memoized) |
- * | Getter type | Sync | Sync | Sync | Async supported |
- * | Object identity | ❌ New | ✅ Same | ✅ Same | ❌ New |
- * | Store backend | Single scope | StoreSync | StoreAsync | Direct scope |
- * | Initial value | First access | First access | defaultValue | Promise |
- * | Best for | Simple sync, async | Complex sync | StoreAsync sync | Component async ops |
- *
- * @see {@link Computed} for synchronous computed properties with StoreSync caching
- * @see {@link Scope} for simple getter-based reactive properties (caches, new reference)
- * @see {@link StoreAsync} for async store implementation
- * @see {@link ObservableScope.Create} for async function support
- */
-export 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))
-        throw "Computed decorator requires a getter";
-    if (descriptor && descriptor.set)
-        throw "Computed decorator does not support setters";
-    const getter = descriptor.get;
-    return {
-        configurable: false,
-        enumerable: true,
-        get: function () {
-            const scopeMap = GetScopeMapForInstance(this);
-            if (scopeMap[propertyKey] === undefined) {
-                const worker = new Worker(new URL("../Store/Diff/defaultDiffTreeWorker.js", import.meta.url), { type: "module" });
-                const storeAsync = new StoreAsync(worker);
-                const propertyScope = CreateStoreScope(getter.bind(this), storeAsync, defaultValue);
-                scopeMap[propertyKey] = [propertyScope, undefined];
-            }
-            return ObservableScope.Value(scopeMap[propertyKey][0]);
-        },
-    };
-}
 /**
  * State decorator factory for creating reactive properties backed by ObservableNode proxies.
  *
@@ -749,7 +595,6 @@ function ValueDecorator(target, propertyKey) {
  * | Best for | Primitives, cheap ops, async ops | Complex objects, expensive ops |
  *
  * @see {@link Computed} for cached computed properties with object reuse
- * @see {@link ComputedAsync} for sync getters with StoreAsync backend
  * @see {@link ObservableNode.Apply} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
  * @see {@link scope} for inline computed scopes within @Scope
@@ -1118,7 +963,6 @@ export var Bound;
      * - All @Value-decorated property scopes
      * - All @Scope-decorated property scopes
      * - All @Computed-decorated property scopes (both getter and property scopes)
-     * - All @ComputedAsync-decorated property scopes (including StoreAsync)
      * - All @Destroy-marked properties (calls .Destroy() method)
      * - All @Watch subscriptions (via scope destruction)
      *

package/Utils/index.d.ts

@@ -2,3 +2,5 @@ export * from "./decorators";
 export * from "./animation";
 export { Injector } from "./injector";
 export { IDestroyable } from "./utils.types";
+export { SubscriptionManager } from "./subscriptionManager";
+export type { KeyFilter, ISubscriptionMatch } from "./subscriptionManager";

package/Utils/index.js

@@ -1,3 +1,4 @@
 export * from "./decorators";
 export * from "./animation";
 export { Injector } from "./injector";
+export { SubscriptionManager } from "./subscriptionManager";

package/Utils/subscriptionManager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A key filter: exact keys, and patterns ending in `*` that match every key starting with the text
+ * before it (`task_*` matches `task_1`). Undefined matches every key; an empty array matches none.
+ */
+export type KeyFilter = readonly string[] | undefined;
+/** A subscription that matched some changed keys, and the keys it matched */
+export interface ISubscriptionMatch<S> {
+    id: number;
+    subscription: S;
+    keys: string[];
+}
+/**
+ * Subscriptions to keys, for any use: it matches keys to subscriptions and counts who holds a
+ * key, and knows nothing about what a key's value is or how it's delivered.
+ *
+ * - **Exact keys hold a key; patterns don't.** `SubscriberCount(key)` counts the subscriptions
+ *   naming the key exactly, and `OnReleased` reports when the last of them ends. A pattern
+ *   subscription matches keys without holding them, or a `whatif_*` subscriber would keep every key.
+ * - **Groups end together.** A subscription can name a group (to a host, a channel), and
+ *   `Disconnect(group)` ends every subscription in it.
+ * - Callbacks run synchronously, inside the call that caused them.
+ *
+ * @template S What a subscription carries, e.g. its callback and form.
+ */
+export declare class SubscriptionManager<S> {
+    private entries;
+    private nextId;
+    /** Exact key -> the subscriptions naming it */
+    private counts;
+    private groups;
+    private released;
+    /**
+     * Adds a subscription.
+     * @param keys The keys it matches, see `KeyFilter`.
+     * @param subscription What the subscription carries.
+     * @param options `group`: the group `Disconnect` ends it with.
+     * @returns Its id.
+     */
+    Subscribe(keys: KeyFilter, subscription: S, options?: {
+        group?: unknown;
+    }): number;
+    /**
+     * Ends a subscription. Each exact key it was the last to name is released.
+     * @returns Whether it existed.
+     */
+    Unsubscribe(id: number): boolean;
+    /** Ends every subscription in a group */
+    Disconnect(group: unknown): void;
+    /** Whether a subscription exists */
+    Has(id: number): boolean;
+    /** What a subscription carries, or undefined when it doesn't exist */
+    Get(id: number): S | undefined;
+    /**
+     * The keys a subscription matches, in the order given.
+     * @returns The keys, or an empty array when the subscription doesn't exist.
+     */
+    MatchingKeys(id: number, keys: Iterable<string>): string[];
+    /**
+     * Each subscription that matches any of the keys, with the keys it matches, in subscription
+     * order. Subscriptions that match none are left out.
+     */
+    Matching(keys: Iterable<string>): ISubscriptionMatch<S>[];
+    /**
+     * Whether a subscription matches every key, with no filter, so a caller can hand it the whole
+     * of something without filtering it.
+     */
+    MatchesAll(id: number): boolean;
+    /**
+     * Calls back when a key matching a pattern loses its last exact subscription, inside the
+     * `Unsubscribe` or `Disconnect` that ended it. A key never named exactly is never released.
+     * @param pattern An exact key or a pattern ending in `*`.
+     * @returns A function that removes the callback.
+     */
+    OnReleased(pattern: string, callback: (key: string) => void): () => void;
+    /** How many subscriptions name a key exactly now; patterns don't count */
+    SubscriberCount(key: string): number;
+    private Release;
+}

package/Utils/subscriptionManager.js

@@ -0,0 +1,162 @@
+const WILDCARD = "*";
+/**
+ * Subscriptions to keys, for any use: it matches keys to subscriptions and counts who holds a
+ * key, and knows nothing about what a key's value is or how it's delivered.
+ *
+ * - **Exact keys hold a key; patterns don't.** `SubscriberCount(key)` counts the subscriptions
+ *   naming the key exactly, and `OnReleased` reports when the last of them ends. A pattern
+ *   subscription matches keys without holding them, or a `whatif_*` subscriber would keep every key.
+ * - **Groups end together.** A subscription can name a group (to a host, a channel), and
+ *   `Disconnect(group)` ends every subscription in it.
+ * - Callbacks run synchronously, inside the call that caused them.
+ *
+ * @template S What a subscription carries, e.g. its callback and form.
+ */
+export class SubscriptionManager {
+    constructor() {
+        this.entries = new Map();
+        this.nextId = 1;
+        /** Exact key -> the subscriptions naming it */
+        this.counts = new Map();
+        this.groups = new Map();
+        this.released = [];
+    }
+    /**
+     * Adds a subscription.
+     * @param keys The keys it matches, see `KeyFilter`.
+     * @param subscription What the subscription carries.
+     * @param options `group`: the group `Disconnect` ends it with.
+     * @returns Its id.
+     */
+    Subscribe(keys, subscription, options = {}) {
+        const id = this.nextId++;
+        const entry = { subscription, all: keys === undefined, exact: new Set(), prefixes: [], group: options.group };
+        if (keys)
+            for (let x = 0; x < keys.length; x++) {
+                const key = keys[x];
+                if (key.endsWith(WILDCARD))
+                    entry.prefixes.push(key.slice(0, -1));
+                else
+                    entry.exact.add(key);
+            }
+        this.entries.set(id, entry);
+        for (const key of entry.exact)
+            this.counts.set(key, (this.counts.get(key) ?? 0) + 1);
+        if (options.group !== undefined) {
+            let ids = this.groups.get(options.group);
+            ids || this.groups.set(options.group, ids = new Set());
+            ids.add(id);
+        }
+        return id;
+    }
+    /**
+     * Ends a subscription. Each exact key it was the last to name is released.
+     * @returns Whether it existed.
+     */
+    Unsubscribe(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return false;
+        this.entries.delete(id);
+        if (entry.group !== undefined) {
+            const ids = this.groups.get(entry.group);
+            ids.delete(id);
+            ids.size === 0 && this.groups.delete(entry.group);
+        }
+        const releasedKeys = [];
+        for (const key of entry.exact) {
+            const count = this.counts.get(key) - 1;
+            if (count > 0)
+                this.counts.set(key, count);
+            else {
+                this.counts.delete(key);
+                releasedKeys.push(key);
+            }
+        }
+        for (const key of releasedKeys)
+            this.Release(key);
+        return true;
+    }
+    /** Ends every subscription in a group */
+    Disconnect(group) {
+        const ids = this.groups.get(group);
+        if (ids)
+            for (const id of Array.from(ids))
+                this.Unsubscribe(id);
+    }
+    /** Whether a subscription exists */
+    Has(id) {
+        return this.entries.has(id);
+    }
+    /** What a subscription carries, or undefined when it doesn't exist */
+    Get(id) {
+        return this.entries.get(id)?.subscription;
+    }
+    /**
+     * The keys a subscription matches, in the order given.
+     * @returns The keys, or an empty array when the subscription doesn't exist.
+     */
+    MatchingKeys(id, keys) {
+        const entry = this.entries.get(id);
+        const matched = [];
+        if (entry)
+            for (const key of keys)
+                Matches(entry, key) && matched.push(key);
+        return matched;
+    }
+    /**
+     * Each subscription that matches any of the keys, with the keys it matches, in subscription
+     * order. Subscriptions that match none are left out.
+     */
+    Matching(keys) {
+        const list = Array.isArray(keys) ? keys : Array.from(keys);
+        const matches = [];
+        for (const [id, entry] of this.entries) {
+            const matched = entry.all ? list : list.filter(key => Matches(entry, key));
+            matched.length > 0 && matches.push({ id, subscription: entry.subscription, keys: matched });
+        }
+        return matches;
+    }
+    /**
+     * Whether a subscription matches every key, with no filter, so a caller can hand it the whole
+     * of something without filtering it.
+     */
+    MatchesAll(id) {
+        return this.entries.get(id)?.all === true;
+    }
+    /**
+     * Calls back when a key matching a pattern loses its last exact subscription, inside the
+     * `Unsubscribe` or `Disconnect` that ended it. A key never named exactly is never released.
+     * @param pattern An exact key or a pattern ending in `*`.
+     * @returns A function that removes the callback.
+     */
+    OnReleased(pattern, callback) {
+        const entry = { pattern, callback };
+        this.released.push(entry);
+        return () => Remove(this.released, entry);
+    }
+    /** How many subscriptions name a key exactly now; patterns don't count */
+    SubscriberCount(key) {
+        return this.counts.get(key) ?? 0;
+    }
+    Release(key) {
+        for (const { pattern, callback } of this.released.slice())
+            if (PatternMatches(pattern, key))
+                callback(key);
+    }
+}
+function Matches(entry, key) {
+    if (entry.all || entry.exact.has(key))
+        return true;
+    for (let x = 0; x < entry.prefixes.length; x++)
+        if (key.startsWith(entry.prefixes[x]))
+            return true;
+    return false;
+}
+function PatternMatches(pattern, key) {
+    return pattern.endsWith(WILDCARD) ? key.startsWith(pattern.slice(0, -1)) : pattern === key;
+}
+function Remove(list, item) {
+    const index = list.indexOf(item);
+    index >= 0 && list.splice(index, 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "9.0.1",
+  "version": "10.0.0",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",

package/Store/Diff/diffTreeWorker.d.ts

@@ -1,6 +0,0 @@
-import { DiffTree } from "./diffTree";
-/**
- * Runs each batch of method calls a `StoreAsync` sends on the tree, then its projections, and
- * posts back the tree's `Commit()` diff for the store to apply.
- */
-export declare function ConnectWorkerToDiffTree(diffTree: DiffTree, worker: Worker): void;

package/Store/Diff/diffTreeWorker.js

@@ -1,22 +0,0 @@
-/**
- * Runs each batch of method calls a `StoreAsync` sends on the tree, then its projections, and
- * posts back the tree's `Commit()` diff for the store to apply.
- */
-export function ConnectWorkerToDiffTree(diffTree, worker) {
-    worker.onmessage = function (event) {
-        const data = event.data;
-        for (let x = 0; x < data.length; x++)
-            RunMethod(diffTree, data[x]);
-        diffTree.RunProjections();
-        worker.postMessage(diffTree.Commit());
-    };
-}
-function RunMethod(diffTree, call) {
-    const args = call.arguments;
-    switch (call.method) {
-        case "writepath": return diffTree.WritePath(args[0], args[1]);
-        case "splicepath": return diffTree.SplicePath(args[0], args[1], args[2], args[3]);
-        case "pushpath": return diffTree.PushPath(args[0], args[1]);
-        case "patchpath": return diffTree.PatchPath(args[0], args[1]);
-    }
-}

package/Store/Diff/diffTreeWriter.d.ts

@@ -1,92 +0,0 @@
-import { JsonDiffResult } from "../../Utils/json";
-import { DiffTree } from "./diffTree";
-import { IKeyFunc, IRouteDefinitions } from "./utils/diffTree.types";
-/**
- * A `DiffTree` that pushes its changes to a `PushStore` instead of answering a store's
- * requests. Use it inside a worker that produces data itself (for example, the result of a
- * computation it runs): write with the usual `DiffTree` methods, then call `Commit()` to run
- * projections and post everything since the last commit as one message.
- *
- * - Push only: don't pass a `DiffTreeWriter` to `ConnectWorkerToDiffTree`, which commits
- *   every batch itself and would post it to the wrong place.
- * - After a change fails, every later change before `Commit()` throws that same error. The
- *   changes made before the failure are already in the tree, so `Commit()` still sends them,
- *   followed by a `DIFF_TREE_ERROR` message. Projections aren't run for that batch; the next
- *   `Commit()` brings them up to date.
- * - A `PushStore` only receives the changes committed after it starts listening, so
- *   create it before the writer's first `Commit()`.
- *
- * @example
- * // engine-worker.ts
- * const tree = new DiffTreeWriter(self, undefined, { "/": { projections } });
- * tree.WritePath("results", computeResults());
- * tree.Commit();
- *
- * // main thread
- * const store = new PushStore(worker);
- *
- * @see PushStore
- */
-export declare class DiffTreeWriter extends DiffTree {
-    private worker;
-    private uncommittedError;
-    /**
-     * Creates a DiffTreeWriter.
-     * @param worker Where `Commit()` posts its messages: the worker's `self`, or a `MessagePort`.
-     *   On the same thread as the store, anything whose `postMessage` dispatches a `"message"`
-     *   event on the store's `EventTarget`. The store clones every value it applies, so it never
-     *   shares objects with the writer's tree.
-     * @param keyFunc Optional function to extract a key from objects. Pass the same key logic to
-     *   the `PushStore` that receives the changes.
-     * @param routes Optional route definitions. Projections run once per `Commit()`, after the
-     *   batch's changes.
-     */
-    constructor(worker: {
-        postMessage(message: unknown): void;
-    }, keyFunc?: IKeyFunc, routes?: IRouteDefinitions);
-    /**
-     * Not available on a DiffTreeWriter: `Commit()` runs projections once per batch, after its
-     * changes. Running them earlier would push a projection result computed from part of a batch.
-     * @throws Always.
-     */
-    RunProjections(): void;
-    /**
-     * Writes a value at a path.
-     * @throws The change's error, or an earlier uncommitted change's error.
-     */
-    WritePath(path: string, value: any): void;
-    /**
-     * Merges a patch into the current value at a path.
-     * @throws The change's error, or an earlier uncommitted change's error.
-     */
-    PatchPath(path: string, patch: any): void;
-    /**
-     * Appends items to the array at a path.
-     * @throws The change's error, or an earlier uncommitted change's error.
-     */
-    PushPath(path: string, items: unknown[]): void;
-    /**
-     * Splices the array at a path.
-     * @throws The change's error, or an earlier uncommitted change's error.
-     */
-    SplicePath(path: string, start: number, deleteCount: number, items: any[]): void;
-    /**
-     * Deletes a route, its child routes and its route instances.
-     * @throws The change's error, or an earlier uncommitted change's error.
-     */
-    DeleteRoute(routePath: string): void;
-    /**
-     * Runs projections and posts every change since the last commit as one `DIFF_TREE_EVENT`
-     * message, which a `PushStore` applies as a unit. Posts nothing when nothing changed.
-     *
-     * If a change in the batch failed, projections are skipped, the applied changes are still
-     * posted, and a `DIFF_TREE_ERROR` message follows with the error; `Commit()` itself doesn't
-     * throw, since the failed change already did. If a projection throws, the batch's changes
-     * and the error are posted the same way, then `Commit()` rethrows. Either way the next batch
-     * starts clean.
-     * @returns The diff that was posted.
-     * @throws A projection's error.
-     */
-    Commit(): JsonDiffResult;
-    private Guard;
-}