j-templates 7.0.81 → 7.0.82

package/Utils/decorators.d.ts

@@ -20,7 +20,8 @@
  * | 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 (async)      | @ComputedAsync | Async with caching + object reuse |
+ * | 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 |
  * | cleanup on destroy        | @Destroy| Calls .Destroy() on component teardown |
@@ -70,7 +71,7 @@ import { Injector } from "./injector";
  * @State()
  * items: TodoItem[] = [];
  *
- * @Computed([])
+ * @Computed()
  * get completedItems(): TodoItem[] {
  *   // Expensive: filters entire array, cached until items change
  *   // Result object is REUSED - only changed properties are updated
@@ -87,7 +88,7 @@ import { Injector } from "./injector";
  * @Value()
  * lastName: string = "Doe";
  *
- * @Computed("")  // Overhead: creates StoreSync, watch cycle, diff computation
+ * @Computed()  // Overhead: creates StoreSync, watch cycle, diff computation
  * get fullName(): string {
  *   return this.firstName + " " + this.lastName;  // Cheap string concat
  * }
@@ -110,7 +111,7 @@ import { Injector } from "./injector";
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
- * @Computed([])
+ * @Computed()
  * get completedItems(): TodoItem[] {
  *   return this.items.filter(i => i.completed);
  * }
@@ -154,40 +155,53 @@ import { Injector } from "./injector";
  * @see {@link ObservableNode.ApplyDiff} for how diffs are applied to maintain object identity
  * @see {@link StoreSync} for sync store implementation
  */
-export declare function Computed<T extends WeakKey, K extends keyof T, V extends T[K]>(defaultValue: V): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
+export declare function Computed<T extends WeakKey, K extends keyof T, D extends T[K]>(): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
- * ComputedAsync decorator factory for creating asynchronous computed properties with caching.
+ * 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.
  *
- * Use @ComputedAsync for expensive async operations (API calls, file reads, database queries).
+ * 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: Async operation with caching
+ * // ✅ Good: Synchronous getter with StoreAsync caching
  * @Value()
  * userId: string = "123";
  *
  * @ComputedAsync(null)
- * async getUser(): Promise<User | null> {
- *   // Expensive: API call, cached until userId changes
- *   return await fetch(`/api/users/${this.userId}`);
+ * get userData(): User | null {
+ *   // Sync getter - returns value directly
+ *   return getUserSync(this.userId);
  * }
  * ```
  *
  * @example
  * ```typescript
- * // ❌ Avoid: Simple/synchronous computation - use @Computed() instead
+ * // ❌ WRONG - Do NOT use async keyword or return Promise
  * @Value()
- * count: number = 0;
+ * userId: string = "123";
  *
- * @ComputedAsync(0)  // Overhead: async wrapper, StoreAsync
- * get doubled(): number {
- *   return this.count * 2;  // Sync operation
+ * @ComputedAsync(null)
+ * async getUser(): Promise<User> {  // ERROR: getter must be synchronous!
+ *   return await fetch(`/api/users/${this.userId}`);
  * }
  *
- * @Computed(0)  // Better: synchronous caching
- * get doubled(): number {
- *   return this.count * 2;
+ * // ✅ 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
  * }
  * ```
  *
@@ -195,44 +209,43 @@ export declare function Computed<T extends WeakKey, K extends keyof T, V extends
  * @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 async results. The getter must be
- * an async function or return a Promise. While waiting for the async operation, the defaultValue
- * is returned. When the Promise resolves, the value is cached and dependent scopes update.
+ * 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)
- * async getUser(): Promise<User> {
- *   return fetch('/api/user');
+ * get userData(): User | null {
+ *   return getUserSync(this.userId);
  * }
  *
- * // Scopes created here, on first access:
- * const user = await this.getUser;
+ * // 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 async getter only runs when dependencies change.
+ * through diff-based updates. The getter only runs when dependencies change.
  *
- * **Object Reuse**: Like @Computed, the resolved value maintains its identity across updates.
+ * **Object Reuse**: Like @Computed, the result maintains its identity across updates.
  * Only changed properties are modified in-place, preserving object references.
  *
- * **Important**: Only use this for truly async operations. For sync computations, use @Computed()
- * which has less overhead and provides synchronous values.
+ * **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 |
- * |--------|--------|-----------|----------------|
- * | Caches value | ✅ Yes | ✅ Yes | ✅ Yes |
- * | Sync/Async | Sync | Sync | Async |
- * | Object identity | ❌ New reference | ✅ Same reference | ✅ Same reference |
- * | Best for | Simple sync values | Complex sync values | Async operations |
- *
- * **Error handling**: If the async getter throws, the error is stored in the StoreAsync.
- * You can handle errors in the getter itself or by watching for changes and checking the value.
- *
- * @see {@link Computed} for synchronous computed properties with object reuse
+ * | Aspect | @Scope | @Computed | @ComputedAsync | calc(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 declare function ComputedAsync<T extends WeakKey, K extends keyof T, V extends T[K]>(defaultValue: V): (target: T, propertyKey: K, descriptor: PropertyDescriptor) => PropertyDescriptor;
 /**
@@ -389,7 +402,7 @@ export declare function Value(): any;
  *   return this.items.filter(item => item.completed).sort(...);
  * }
  *
- * @Computed([])  // Better: cached + object reuse via StoreSync
+ * @Computed()  // Better: cached + object reuse via StoreSync
  * get completedItems(): TodoItem[] {
  *   return this.items.filter(item => item.completed).sort(...);
  * }
@@ -448,6 +461,18 @@ export declare function Value(): any;
  * - Object identity matters (array/object references used in templates)
  * - You need DOM reference preservation to avoid re-renders
  *
+ * **Async pattern with @Scope**: Use `calc(async () => ...)` for async operations:
+ * ```typescript
+ * @Scope()
+ * get CurrentUser() {
+ *   return calc(async () => fetchUser(`/api/user/${this.userId}`));
+ * }
+ * ```
+ * - `calc` memoizes async operations with ID-based caching
+ * - Returns Promise initially, resolves when complete
+ * - Automatically batches updates via microtask queue
+ * - New reference on each update (no object reuse)
+ *
  * **Performance comparison**:
  * | Aspect | @Scope | @Computed |
  * |--------|--------|-----------|
@@ -455,12 +480,13 @@ export declare function Value(): any;
  * | Re-evaluates on dep change | ✅ Yes | ✅ Yes |
  * | Object identity | ❌ New reference | ✅ Same reference |
  * | Overhead | Minimal (single scope) | Higher (Store + diff) |
- * | Best for | Primitives, cheap ops | Complex objects, expensive ops |
+ * | 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 async computed properties
+ * @see {@link ComputedAsync} for sync getters with StoreAsync backend
  * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
+ * @see {@link calc} for memoized async operations within @Scope
  */
 export declare function Scope(): typeof ScopeDecorator;
 /**
@@ -739,38 +765,38 @@ export declare namespace Destroy {
      *   @Destroy()
      *   timer: Timer = new Timer();
      *
-   *   // Destroy.All(this) is called automatically in Component.Destroy()
-   *   public Destroy() {
-   *     super.Destroy();  // This calls Destroy.All(this)
-   *     // timer.Destroy() has been called, scopes are destroyed
-   *   }
-   * }
-   * ```
-   *
-   * @remarks
-   * This method performs cleanup in the following order:
-   * 1. **ObservableScope.DestroyAll()**: Destroys all scopes created by @Value, @Scope, @Computed
-   * 2. **@Destroy cleanup**: Calls .Destroy() on each property marked with @Destroy()
-   *
-   * **Timing**: Called during component destruction, after unbinding from the DOM but before
-   * the component is fully garbage collected.
-   *
-   * **Idempotent**: Safe to call multiple times - destroyed scopes are marked and ignored.
-   *
-   * **Error handling**: If any .Destroy() method throws, the error propagates. Ensure your
-   * cleanup methods are robust and handle edge cases gracefully.
-   *
-   * **What gets destroyed**:
-   * - 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)
-   *
-   * @see {@link Bound.All} for initialization counterpart
-   * @see {@link Component.Destroy} for component lifecycle
-   */
+     *   // Destroy.All(this) is called automatically in Component.Destroy()
+     *   public Destroy() {
+     *     super.Destroy();  // This calls Destroy.All(this)
+     *     // timer.Destroy() has been called, scopes are destroyed
+     *   }
+     * }
+     * ```
+     *
+     * @remarks
+     * This method performs cleanup in the following order:
+     * 1. **ObservableScope.DestroyAll()**: Destroys all scopes created by @Value, @Scope, @Computed
+     * 2. **@Destroy cleanup**: Calls .Destroy() on each property marked with @Destroy()
+     *
+     * **Timing**: Called during component destruction, after unbinding from the DOM but before
+     * the component is fully garbage collected.
+     *
+     * **Idempotent**: Safe to call multiple times - destroyed scopes are marked and ignored.
+     *
+     * **Error handling**: If any .Destroy() method throws, the error propagates. Ensure your
+     * cleanup methods are robust and handle edge cases gracefully.
+     *
+     * **What gets destroyed**:
+     * - 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)
+     *
+     * @see {@link Bound.All} for initialization counterpart
+     * @see {@link Component.Destroy} for component lifecycle
+     */
     function All<T extends WeakKey>(value: T): void;
 }
 declare function DestroyDecorator<T extends Record<K, IDestroyable>, K extends string>(target: T, propertyKey: K): any;

package/Utils/decorators.js

@@ -21,7 +21,8 @@
  * | 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 (async)      | @ComputedAsync | Async with caching + object reuse |
+ * | 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 |
  * | cleanup on destroy        | @Destroy| Calls .Destroy() on component teardown |
@@ -132,13 +133,12 @@ function GetDestroyArrayForPrototype(prototype, create = true) {
     }
     return array;
 }
-function CreateComputedScope(getter, defaultValue, store) {
+function CreateComputedScope(getter, store, defaultValue) {
     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.Init(getterScope);
     const propertyScope = observableScope_1.ObservableScope.Create(() => store.Get("root", defaultValue));
     observableScope_1.ObservableScope.OnDestroyed(propertyScope, function () {
         observableScope_1.ObservableScope.Destroy(getterScope);
@@ -160,7 +160,7 @@ function CreateComputedScope(getter, defaultValue, store) {
  * @State()
  * items: TodoItem[] = [];
  *
- * @Computed([])
+ * @Computed()
  * get completedItems(): TodoItem[] {
  *   // Expensive: filters entire array, cached until items change
  *   // Result object is REUSED - only changed properties are updated
@@ -177,7 +177,7 @@ function CreateComputedScope(getter, defaultValue, store) {
  * @Value()
  * lastName: string = "Doe";
  *
- * @Computed("")  // Overhead: creates StoreSync, watch cycle, diff computation
+ * @Computed()  // Overhead: creates StoreSync, watch cycle, diff computation
  * get fullName(): string {
  *   return this.firstName + " " + this.lastName;  // Cheap string concat
  * }
@@ -200,7 +200,7 @@ function CreateComputedScope(getter, defaultValue, store) {
  *
  * **Initialization**: @Computed uses lazy initialization - the scopes are created on first access:
  * ```typescript
- * @Computed([])
+ * @Computed()
  * get completedItems(): TodoItem[] {
  *   return this.items.filter(i => i.completed);
  * }
@@ -244,9 +244,9 @@ function CreateComputedScope(getter, defaultValue, store) {
  * @see {@link ObservableNode.ApplyDiff} for how diffs are applied to maintain object identity
  * @see {@link StoreSync} for sync store implementation
  */
-function Computed(defaultValue) {
+function Computed() {
     return function (target, propertyKey, descriptor) {
-        return ComputedDecorator(target, propertyKey, descriptor, defaultValue);
+        return ComputedDecorator(target, propertyKey, descriptor);
     };
 }
 /**
@@ -259,7 +259,7 @@ function Computed(defaultValue) {
  * @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) {
+function ComputedDecorator(target, prop, descriptor) {
     const propertyKey = prop;
     if (!(descriptor && descriptor.get))
         throw "Computed decorator requires a getter";
@@ -272,7 +272,7 @@ function ComputedDecorator(target, prop, descriptor, defaultValue) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const propertyScope = CreateComputedScope(getter.bind(this), undefined, new Store_1.StoreSync());
+                const propertyScope = CreateComputedScope(getter.bind(this), new Store_1.StoreSync());
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);
@@ -280,38 +280,51 @@ function ComputedDecorator(target, prop, descriptor, defaultValue) {
     };
 }
 /**
- * ComputedAsync decorator factory for creating asynchronous computed properties with caching.
+ * 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.
  *
- * Use @ComputedAsync for expensive async operations (API calls, file reads, database queries).
+ * 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: Async operation with caching
+ * // ✅ Good: Synchronous getter with StoreAsync caching
  * @Value()
  * userId: string = "123";
  *
  * @ComputedAsync(null)
- * async getUser(): Promise<User | null> {
- *   // Expensive: API call, cached until userId changes
- *   return await fetch(`/api/users/${this.userId}`);
+ * get userData(): User | null {
+ *   // Sync getter - returns value directly
+ *   return getUserSync(this.userId);
  * }
  * ```
  *
  * @example
  * ```typescript
- * // ❌ Avoid: Simple/synchronous computation - use @Computed() instead
+ * // ❌ WRONG - Do NOT use async keyword or return Promise
  * @Value()
- * count: number = 0;
+ * userId: string = "123";
  *
- * @ComputedAsync(0)  // Overhead: async wrapper, StoreAsync
- * get doubled(): number {
- *   return this.count * 2;  // Sync operation
+ * @ComputedAsync(null)
+ * async getUser(): Promise<User> {  // ERROR: getter must be synchronous!
+ *   return await fetch(`/api/users/${this.userId}`);
  * }
  *
- * @Computed(0)  // Better: synchronous caching
- * get doubled(): number {
- *   return this.count * 2;
+ * // ✅ 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
  * }
  * ```
  *
@@ -319,44 +332,43 @@ function ComputedDecorator(target, prop, descriptor, defaultValue) {
  * @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 async results. The getter must be
- * an async function or return a Promise. While waiting for the async operation, the defaultValue
- * is returned. When the Promise resolves, the value is cached and dependent scopes update.
+ * 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)
- * async getUser(): Promise<User> {
- *   return fetch('/api/user');
+ * get userData(): User | null {
+ *   return getUserSync(this.userId);
  * }
  *
- * // Scopes created here, on first access:
- * const user = await this.getUser;
+ * // 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 async getter only runs when dependencies change.
+ * through diff-based updates. The getter only runs when dependencies change.
  *
- * **Object Reuse**: Like @Computed, the resolved value maintains its identity across updates.
+ * **Object Reuse**: Like @Computed, the result maintains its identity across updates.
  * Only changed properties are modified in-place, preserving object references.
  *
- * **Important**: Only use this for truly async operations. For sync computations, use @Computed()
- * which has less overhead and provides synchronous values.
+ * **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 |
- * |--------|--------|-----------|----------------|
- * | Caches value | ✅ Yes | ✅ Yes | ✅ Yes |
- * | Sync/Async | Sync | Sync | Async |
- * | Object identity | ❌ New reference | ✅ Same reference | ✅ Same reference |
- * | Best for | Simple sync values | Complex sync values | Async operations |
- *
- * **Error handling**: If the async getter throws, the error is stored in the StoreAsync.
- * You can handle errors in the getter itself or by watching for changes and checking the value.
- *
- * @see {@link Computed} for synchronous computed properties with object reuse
+ * | Aspect | @Scope | @Computed | @ComputedAsync | calc(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
  */
 function ComputedAsync(defaultValue) {
     return function (target, propertyKey, descriptor) {
@@ -386,7 +398,7 @@ function ComputedAsyncDecorator(target, prop, descriptor, defaultValue) {
         get: function () {
             const scopeMap = GetScopeMapForInstance(this);
             if (scopeMap[propertyKey] === undefined) {
-                const propertyScope = CreateComputedScope(getter.bind(this), defaultValue, new Store_1.StoreAsync());
+                const propertyScope = CreateComputedScope(getter.bind(this), new Store_1.StoreAsync(), defaultValue);
                 scopeMap[propertyKey] = [propertyScope, undefined];
             }
             return observableScope_1.ObservableScope.Value(scopeMap[propertyKey][0]);
@@ -613,7 +625,7 @@ function ValueDecorator(target, propertyKey) {
  *   return this.items.filter(item => item.completed).sort(...);
  * }
  *
- * @Computed([])  // Better: cached + object reuse via StoreSync
+ * @Computed()  // Better: cached + object reuse via StoreSync
  * get completedItems(): TodoItem[] {
  *   return this.items.filter(item => item.completed).sort(...);
  * }
@@ -672,6 +684,18 @@ function ValueDecorator(target, propertyKey) {
  * - Object identity matters (array/object references used in templates)
  * - You need DOM reference preservation to avoid re-renders
  *
+ * **Async pattern with @Scope**: Use `calc(async () => ...)` for async operations:
+ * ```typescript
+ * @Scope()
+ * get CurrentUser() {
+ *   return calc(async () => fetchUser(`/api/user/${this.userId}`));
+ * }
+ * ```
+ * - `calc` memoizes async operations with ID-based caching
+ * - Returns Promise initially, resolves when complete
+ * - Automatically batches updates via microtask queue
+ * - New reference on each update (no object reuse)
+ *
  * **Performance comparison**:
  * | Aspect | @Scope | @Computed |
  * |--------|--------|-----------|
@@ -679,12 +703,13 @@ function ValueDecorator(target, propertyKey) {
  * | Re-evaluates on dep change | ✅ Yes | ✅ Yes |
  * | Object identity | ❌ New reference | ✅ Same reference |
  * | Overhead | Minimal (single scope) | Higher (Store + diff) |
- * | Best for | Primitives, cheap ops | Complex objects, expensive ops |
+ * | 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 async computed properties
+ * @see {@link ComputedAsync} for sync getters with StoreAsync backend
  * @see {@link ObservableNode.ApplyDiff} for how @Computed maintains object identity
  * @see {@link ObservableScope} for the scope-based reactivity system
+ * @see {@link calc} for memoized async operations within @Scope
  */
 function Scope() {
     return ScopeDecorator;
@@ -1025,38 +1050,38 @@ var Bound;
      *   @Destroy()
      *   timer: Timer = new Timer();
      *
-   *   // Destroy.All(this) is called automatically in Component.Destroy()
-   *   public Destroy() {
-   *     super.Destroy();  // This calls Destroy.All(this)
-   *     // timer.Destroy() has been called, scopes are destroyed
-   *   }
-   * }
-   * ```
-   *
-   * @remarks
-   * This method performs cleanup in the following order:
-   * 1. **ObservableScope.DestroyAll()**: Destroys all scopes created by @Value, @Scope, @Computed
-   * 2. **@Destroy cleanup**: Calls .Destroy() on each property marked with @Destroy()
-   *
-   * **Timing**: Called during component destruction, after unbinding from the DOM but before
-   * the component is fully garbage collected.
-   *
-   * **Idempotent**: Safe to call multiple times - destroyed scopes are marked and ignored.
-   *
-   * **Error handling**: If any .Destroy() method throws, the error propagates. Ensure your
-   * cleanup methods are robust and handle edge cases gracefully.
-   *
-   * **What gets destroyed**:
-   * - 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)
-   *
-   * @see {@link Bound.All} for initialization counterpart
-   * @see {@link Component.Destroy} for component lifecycle
-   */
+     *   // Destroy.All(this) is called automatically in Component.Destroy()
+     *   public Destroy() {
+     *     super.Destroy();  // This calls Destroy.All(this)
+     *     // timer.Destroy() has been called, scopes are destroyed
+     *   }
+     * }
+     * ```
+     *
+     * @remarks
+     * This method performs cleanup in the following order:
+     * 1. **ObservableScope.DestroyAll()**: Destroys all scopes created by @Value, @Scope, @Computed
+     * 2. **@Destroy cleanup**: Calls .Destroy() on each property marked with @Destroy()
+     *
+     * **Timing**: Called during component destruction, after unbinding from the DOM but before
+     * the component is fully garbage collected.
+     *
+     * **Idempotent**: Safe to call multiple times - destroyed scopes are marked and ignored.
+     *
+     * **Error handling**: If any .Destroy() method throws, the error propagates. Ensure your
+     * cleanup methods are robust and handle edge cases gracefully.
+     *
+     * **What gets destroyed**:
+     * - 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)
+     *
+     * @see {@link Bound.All} for initialization counterpart
+     * @see {@link Component.Destroy} for component lifecycle
+     */
     function All(value) {
         const scopeMap = scopeInstanceMap.get(value);
         if (scopeMap !== undefined) {

package/package.json

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