j-templates 7.0.97 → 7.0.98

package/{Store → lib/Store}/Tree/observableScope.d.ts

@@ -115,6 +115,9 @@ export declare function PeekScope<T>(callback: () => T | Promise<T>, idOverride?
 export declare namespace ObservableScope {
     /**
      * Creates a new observable scope from a value function.
+     * The scope auto-tracks the reactive dependencies the valueFunction reads. If it reads no
+     * reactive dependencies, `Create` returns a static scope that does not emit on `Update` — use
+     * `Basic` for a manually-updatable scope whose value doesn't derive from reactive state.
      * @template T The type of value returned by the function.
      * @param valueFunction Function that returns the scope's value. Can be async.
      * @returns A new observable scope.
@@ -122,9 +125,26 @@ export declare namespace ObservableScope {
     function Create<T>(valueFunction: {
         (): T | Promise<T>;
     }): IObservableScope<T>;
+    /**
+     * Creates a greedy observable scope that batches updates via the microtask queue.
+     * Unlike `Create`, a greedy scope does not emit immediately on change — updates are coalesced
+     * and emitted on the next microtask. Used by `@Watch` for batched side effects.
+     * @template T The type of value returned by the function.
+     * @param valueFunction Function that returns the scope's value. Can be async.
+     * @returns A new greedy observable scope.
+     */
     function Gated<T>(valueFunction: {
         (): T | Promise<T>;
     }): IObservableScope<T>;
+    /**
+     * Creates a lightweight basic scope that stores a value directly without a proxy.
+     * Used by `@Value` for primitives. Basic scopes do not automatically track dependencies —
+     * after creation, `ObservableScope.Update` must be called for the scope to emit. They also do
+     * not cache a value internally: the valueFunction is invoked on every read.
+     * @template T The type of value stored in the scope.
+     * @param valueFunction Function that returns the scope's value.
+     * @returns A new basic observable scope.
+     */
     function Basic<T>(valueFunction: {
         (): T;
     }): IBasicObservableScope<T>;
@@ -167,6 +187,13 @@ export declare namespace ObservableScope {
      * @param callback The callback function to remove.
      */
     function Unwatch<T>(scope: IObservableScope<T>, callback: (scope: IObservableScope<T>) => void): void;
+    /**
+     * Registers a callback to be invoked when the scope's value is updated.
+     * Only applies to dynamic scopes; no-op for static scopes.
+     * @template T The type of value stored in the scope.
+     * @param scope The scope to monitor for updates.
+     * @param callback Function invoked with the last value and the scope on each update.
+     */
     function OnUpdated<T>(scope: IObservableScope<T>, callback: {
         (lastValue: T, scope: IObservableScope<T>): void;
     }): void;
@@ -180,6 +207,8 @@ export declare namespace ObservableScope {
     }): void;
     /**
      * Marks a scope as dirty, triggering recomputation on next access or batch.
+     * No-op for static scopes (created when a `Create` valueFunction reads no reactive
+     * dependencies) — they never emit. Use `Basic` for scopes you drive manually with `Update`.
      * @param scope The scope to mark for update.
      */
     function Update(scope: IObservableScope<any> | IBasicObservableScope<any>): void;

package/{Store → lib/Store}/Tree/observableScope.js

@@ -538,6 +538,9 @@ var ObservableScope;
 (function (ObservableScope) {
     /**
      * Creates a new observable scope from a value function.
+     * The scope auto-tracks the reactive dependencies the valueFunction reads. If it reads no
+     * reactive dependencies, `Create` returns a static scope that does not emit on `Update` — use
+     * `Basic` for a manually-updatable scope whose value doesn't derive from reactive state.
      * @template T The type of value returned by the function.
      * @param valueFunction Function that returns the scope's value. Can be async.
      * @returns A new observable scope.
@@ -546,10 +549,27 @@ var ObservableScope;
         return ExecuteFunction(valueFunction, false);
     }
     ObservableScope.Create = Create;
+    /**
+     * Creates a greedy observable scope that batches updates via the microtask queue.
+     * Unlike `Create`, a greedy scope does not emit immediately on change — updates are coalesced
+     * and emitted on the next microtask. Used by `@Watch` for batched side effects.
+     * @template T The type of value returned by the function.
+     * @param valueFunction Function that returns the scope's value. Can be async.
+     * @returns A new greedy observable scope.
+     */
     function Gated(valueFunction) {
         return ExecuteFunction(valueFunction, true);
     }
     ObservableScope.Gated = Gated;
+    /**
+     * Creates a lightweight basic scope that stores a value directly without a proxy.
+     * Used by `@Value` for primitives. Basic scopes do not automatically track dependencies —
+     * after creation, `ObservableScope.Update` must be called for the scope to emit. They also do
+     * not cache a value internally: the valueFunction is invoked on every read.
+     * @template T The type of value stored in the scope.
+     * @param valueFunction Function that returns the scope's value.
+     * @returns A new basic observable scope.
+     */
     function Basic(valueFunction) {
         return CreateBasicScope(valueFunction);
     }
@@ -620,6 +640,13 @@ var ObservableScope;
         emitter_1.Emitter.Remove(scope.emitter, callback);
     }
     ObservableScope.Unwatch = Unwatch;
+    /**
+     * Registers a callback to be invoked when the scope's value is updated.
+     * Only applies to dynamic scopes; no-op for static scopes.
+     * @template T The type of value stored in the scope.
+     * @param scope The scope to monitor for updates.
+     * @param callback Function invoked with the last value and the scope on each update.
+     */
     function OnUpdated(scope, callback) {
         if (scope.type !== "dynamic")
             return;
@@ -639,6 +666,8 @@ var ObservableScope;
     ObservableScope.OnDestroyed = OnDestroyed;
     /**
      * Marks a scope as dirty, triggering recomputation on next access or batch.
+     * No-op for static scopes (created when a `Create` valueFunction reads no reactive
+     * dependencies) — they never emit. Use `Basic` for scopes you drive manually with `Update`.
      * @param scope The scope to mark for update.
      */
     function Update(scope) {

package/lib/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "j-templates",
+  "version": "7.0.98",
+  "description": "j-templates",
+  "license": "MIT",
+  "repository": "https://github.com/TypesInCode/jTemplates",
+  "author": "Jay Landrum",
+  "keywords": [
+    ""
+  ],
+  "main": "./index.js",
+  "typings": "./index.d.ts"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "j-templates",
-  "version": "7.0.97",
+  "version": "7.0.98",
   "description": "j-templates",
   "license": "MIT",
   "repository": "https://github.com/TypesInCode/jTemplates",
@@ -8,6 +8,31 @@
   "keywords": [
     ""
   ],
-  "main": "./index.js",
-  "typings": "./index.d.ts"
+  "files": [
+    "lib"
+  ],
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "scripts": {
+    "clean": "rimraf lib",
+    "build": "npm run buildquick && node ./tools/copy-package-json.js",
+    "buildquick": "npm run clean && echo Using TypeScript && tsc --version && tsc --pretty",
+    "builddocs": "typedoc --out docs src/index.ts src/DOM/index.ts src/Utils/index.ts src/Store/index.ts && touch docs/.nojekyll",
+    "test": "vitest run",
+    "test_watch": "vitest --ui"
+  },
+  "devDependencies": {
+    "@fission-ai/openspec": "^1.1.1",
+    "@types/node": "^25.2.0",
+    "@vitest/ui": "^4.1.5",
+    "fs-extra": "^11.3.3",
+    "jsdom": "^27.4.0",
+    "rimraf": "^6.1.2",
+    "typedoc": "^0.28.16",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=4.0.0"
+  }
 }

package/Store/Tree/observableNode.d.ts

@@ -1,43 +0,0 @@
-import { JsonDiffResult } from "../../Utils/json";
-export declare namespace ObservableNode {
-    /**
-     * Unwraps an observable node to get the raw underlying value.
-     * Recursively unwraps nested objects and arrays.
-     * @template T The type of value to unwrap.
-     * @param value The value to unwrap, which may be an observable node or plain value.
-     * @returns The unwrapped raw value without proxy wrappers.
-     */
-    function Unwrap<T>(value: T): T;
-    function Clone<T>(value: T): T;
-    /**
-     * Creates an observable node from a plain value.
-     * Wraps the value in a proxy that tracks changes and enables reactive updates.
-     * @template T The type of value to wrap.
-     * @param value The plain value (object, array, or primitive) to make observable.
-     * @returns A proxied version of the value that emits change events.
-     */
-    function Create<T>(value: T): T;
-    /**
-     * Marks an observable node or its property as changed, triggering reactive updates.
-     * Used internally to notify dependencies that a value has been modified.
-     * @param value The observable node to touch.
-     * @param prop Optional property name or index to touch a specific nested property.
-     */
-    function Update(value: unknown, prop?: string | number | symbol): void;
-    function Apply(rootNode: any, update: any): void;
-    /**
-     * Applies a JSON diff result to an observable node, efficiently updating only changed properties.
-     * Optimizes nested object updates by computing paths incrementally and touching modified properties.
-     * @param rootNode The observable node to apply the diff to.
-     * @param diffResult The diff result from JsonDiff containing path-value pairs of changes.
-     */
-    function ApplyDiff(rootNode: any, diffResult: JsonDiffResult): void;
-    /**
-     * Creates a factory function for making values observable with optional aliasing.
-     * The alias function transforms values before creating the observable proxy,
-     * useful for read-only views or value transformations.
-     * @param alias Optional function to transform values before making them observable.
-     * @returns A function that creates observable nodes from plain values.
-     */
-    function CreateFactory(alias?: (value: any) => any | undefined): <T>(value: T) => T;
-}