@praxisjs/decorators 1.6.1 → 2.0.0

package/src/functions/watch.ts

@@ -1,9 +1,9 @@
 import type { StatefulComponent } from "@praxisjs/core";
-import { effect, batch } from "@praxisjs/core/internal";
+import { batch, createEffect } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 import { isComputed } from "@praxisjs/shared/internal";
 
-import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
+import { lifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 
 type BaseComponentKeys = keyof StatefulComponent;
 
@@ -58,43 +58,44 @@ export function Watch<
 >(...propNames: ValidateKeys<T, Keys>) {
   const props = propNames as unknown as string[];
 
-  return createLifecycleMethodDecorator<T>({
-    register(callback, instance) {
+  if (props.length === 1) {
+    const key = props[0];
+    return lifecycleMethodDecorator<T>((instance, method) => {
       const inst = instance as T & Record<string, unknown>;
+      let oldVal = readValue(inst, key);
+      return createEffect(() => {
+        const newVal = readValue(inst, key);
+        if (!Object.is(newVal, oldVal)) {
+          method.call(inst, newVal, oldVal);
+          oldVal = newVal;
+        }
+      });
+    });
+  }
 
-      if (props.length === 1) {
-        let oldVal = readValue(inst, props[0]);
-        return effect(() => {
-          const newVal = readValue(inst, props[0]);
-          if (!Object.is(newVal, oldVal)) {
-            callback(newVal, oldVal);
-            oldVal = newVal;
-          }
-        });
-      }
-
-      const read = () =>
-        Object.fromEntries(props.map((p) => [p, readValue(inst, p)]));
-      let oldVals = read();
-      let latestVals = oldVals;
-      let scheduled = false;
-      return effect(() => {
-        const newVals = read();
-        if (props.some((p) => !Object.is(newVals[p], oldVals[p]))) {
-          latestVals = newVals;
-          if (!scheduled) {
-            scheduled = true;
-            const prevVals = oldVals;
-            queueMicrotask(() => {
-              scheduled = false;
-              oldVals = latestVals;
-              batch(() => {
-                callback(latestVals, prevVals);
-              });
+  return lifecycleMethodDecorator<T>((instance, method) => {
+    const inst = instance as T & Record<string, unknown>;
+    const read = () =>
+      Object.fromEntries(props.map((p) => [p, readValue(inst, p)]));
+    let oldVals = read();
+    let latestVals = oldVals;
+    let scheduled = false;
+    return createEffect(() => {
+      const newVals = read();
+      if (props.some((p) => !Object.is(newVals[p], oldVals[p]))) {
+        latestVals = newVals;
+        if (!scheduled) {
+          scheduled = true;
+          const prevVals = oldVals;
+          queueMicrotask(() => {
+            scheduled = false;
+            oldVals = latestVals;
+            batch(() => {
+              method.call(inst, latestVals, prevVals);
             });
-          }
+          });
         }
-      });
-    },
+      }
+    });
   });
 }

package/src/functions/when.ts

@@ -1,8 +1,8 @@
-import { effect } from "@praxisjs/core/internal";
+import { createEffect } from "@praxisjs/core/internal";
 import type { Computed, Signal } from "@praxisjs/shared";
 import { isComputed, isSignal } from "@praxisjs/shared/internal";
 
-import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
+import { lifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 
 /** Read the current value of a property, unwrapping Signal or Computed if needed. */
 function readProp(instance: Record<string, unknown>, key: string): unknown {
@@ -16,26 +16,24 @@ export function When<T = unknown>(
   propName: string,
   condition?: (value: NonNullable<T>) => boolean,
 ) {
-  return createLifecycleMethodDecorator({
-    register(callback, instance) {
-      const inst = instance as unknown as Record<string, unknown>;
-      let fired = false;
+  return lifecycleMethodDecorator<object>((instance, method) => {
+    const inst = instance as Record<string, unknown>;
+    let fired = false;
 
-      return effect(() => {
-        if (fired) return;
-        // Reading via readProp subscribes this effect to the underlying signal,
-        // whether the property is a raw Signal/Computed or an @State getter.
-        const val = readProp(inst, propName) as T;
+    return createEffect(() => {
+      if (fired) return;
+      // Reading via readProp subscribes this effect to the underlying signal,
+      // whether the property is a raw Signal/Computed or an @State getter.
+      const val = readProp(inst, propName) as T;
 
-        const meetsCondition = condition
-          ? val != null && condition(val)
-          : val != null && Boolean(val);
+      const meetsCondition = condition
+        ? val != null && condition(val)
+        : val != null && Boolean(val);
 
-        if (meetsCondition) {
-          fired = true;
-          callback(val as NonNullable<T>);
-        }
-      });
-    },
+      if (meetsCondition) {
+        fired = true;
+        method.call(inst, val as NonNullable<T>);
+      }
+    });
   });
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export { Component, Lazy } from "./component";
 export {
   Memo,
+  type MemoOptions,
   Bind,
   Log,
   Once,
@@ -33,12 +34,17 @@ export {
   DeepState,
   Ref,
   createRef,
+  Selector,
+  type SelectorOptions,
 } from "./properties";
 export { Command, createCommand, Emit, OnCommand } from "./events";
+export { addClaimableInitializer, assertFieldContext, type FieldDecorator } from "./field";
 export {
   createFieldDecorator,
   type FieldBehavior,
   type FieldBinding,
+  type FieldSetup,
+  type SharedFieldBehavior,
 } from "./create-field-decorator";
 export { reactiveHostType, type ReactiveHost } from "./reactive-host";
 export {
@@ -49,6 +55,9 @@ export {
 export {
   createMethodDecorator,
   type MethodBehavior,
+  type MethodDecorator,
+  type MethodSetup,
+  type SharedMethodBehavior,
 } from "./create-method-decorator";
 export {
   createLifecycleMethodDecorator,
@@ -57,14 +66,13 @@ export {
 export {
   createGetterDecorator,
   type GetterBehavior,
+  type GetterDecorator,
+  type GetterSetup,
+  type SharedGetterBehavior,
   createWritableGetterDecorator,
   type WritableGetterBehavior,
   type WritableGetterBinding,
+  type SharedWritableGetterBehavior,
   createGetterObserverDecorator,
   type GetterObserverBehavior,
 } from "./create-getter-decorator";
-export {
-  createAccessorDecorator,
-  type AccessorBehavior,
-  type AccessorBinding,
-} from "./create-accessor-decorator";

package/src/lifecycle.ts

@@ -0,0 +1,74 @@
+import { disposeEffect, type EffectNode } from "@praxisjs/core/internal";
+
+export type LifecycleHook = (instance: object) => void;
+
+export interface LifecycleHost {
+  onMount?: ((this: object) => void) | undefined;
+  onUnmount?: ((this: object) => void) | undefined;
+}
+
+/** What a mount registration leaves to undo on unmount: a stop function or an effect to dispose. */
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type
+export type LifecycleCleanup = (() => void) | EffectNode | undefined | void;
+
+/**
+ * Runs `mount` / `unmount` (called with the instance) after the instance's current `onMount` /
+ * `onUnmount`, and so after the hooks added before them. Calling `instance.onMount()` by hand runs
+ * them too.
+ *
+ * The previous hooks are called with `this` rather than bound to the instance: two closures per
+ * hook pair are all this allocates.
+ */
+export function addLifecycleHooks(
+  object: object,
+  mount: LifecycleHook | undefined,
+  unmount: LifecycleHook | undefined,
+): void {
+  const instance = object as LifecycleHost;
+  const prevMount = instance.onMount;
+  const prevUnmount = instance.onUnmount;
+  instance.onMount = function (this: object) {
+    prevMount?.call(this);
+    mount?.(this);
+  };
+  instance.onUnmount = function (this: object) {
+    prevUnmount?.call(this);
+    unmount?.(this);
+  };
+}
+
+function stop(cleanup: LifecycleCleanup): void {
+  if (typeof cleanup === "function") cleanup();
+  else if (cleanup != null) disposeEffect(cleanup);
+}
+
+/**
+ * Calls `start(instance, arg)` on every mount and undoes what it returned on unmount. Like
+ * `addLifecycleHooks`, it chains onto the instance's hooks with two closures and no bound
+ * functions; the cleanup lives in their shared scope.
+ */
+export function addMountRegistration<T extends object, A>(
+  object: T,
+  start: (instance: T, arg: A) => LifecycleCleanup,
+  arg: A,
+): void {
+  const instance = object as LifecycleHost;
+  const prevMount = instance.onMount;
+  const prevUnmount = instance.onUnmount;
+  let cleanup: LifecycleCleanup;
+  instance.onMount = function (this: object) {
+    prevMount?.call(this);
+    // A second onMount() without an onUnmount() in between would otherwise leak the first
+    // registration, which nothing could stop anymore.
+    const previous = cleanup;
+    cleanup = undefined;
+    stop(previous);
+    cleanup = start(this as T, arg);
+  };
+  instance.onUnmount = function (this: object) {
+    prevUnmount?.call(this);
+    const previous = cleanup;
+    cleanup = undefined;
+    stop(previous);
+  };
+}

package/src/properties/compose.ts

@@ -1,6 +1,7 @@
-import type { StatefulComponent, Composable } from "@praxisjs/core";
+import type { Composable } from "@praxisjs/core";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
+import { addLifecycleHooks } from "../lifecycle";
 
 interface ComposeFactory { __isComposeFactory: true; resolve: (instance: object) => unknown }
 
@@ -43,24 +44,36 @@ export function Compose(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   ComposableClass: new (...args: any[]) => Composable,
   ...ctorArgs: unknown[]
-) {
-  return createFieldDecorator({
-    bind(instance: StatefulComponent, _name: string, _initialValue: unknown) {
-      const resolvedArgs = ctorArgs.map((arg) => {
-        if (isFactory(arg)) return arg.resolve(instance);
-        if (typeof arg !== "string") return arg;
-        const prop = (instance as unknown as Record<string, unknown>)[arg];
-        return prop !== undefined ? prop : arg;
-      });
-
-      const composable = new ComposableClass(...resolvedArgs);
-      const view = buildView(composable.setup());
+): FieldDecorator {
+  return sharedField((name) => {
+    const composableSlot = Symbol(`praxis.composable.${name}`);
+    const viewSlot = Symbol(`praxis.compose.${name}`);
+    const composableOf = (instance: object) => (instance as FieldHost)[composableSlot] as Composable;
+    const mount = (instance: object) => { composableOf(instance).onMount?.(); };
+    const unmount = (instance: object) => { composableOf(instance).onUnmount?.(); };
+    return {
+      descriptor: {
+        get(this: FieldHost) {
+          return this[viewSlot];
+        },
+      },
+      init(instance) {
+        const resolvedArgs = ctorArgs.map((arg) => {
+          if (isFactory(arg)) return arg.resolve(instance);
+          if (typeof arg !== "string") return arg;
+          const prop = instance[arg];
+          return prop !== undefined ? prop : arg;
+        });
 
-      return {
-        descriptor: { get: () => view },
-        onMount: composable.onMount?.bind(composable),
-        onUnmount: composable.onUnmount?.bind(composable),
-      };
-    },
+        const composable = new ComposableClass(...resolvedArgs);
+        instance[composableSlot] = composable;
+        instance[viewSlot] = buildView(composable.setup());
+        const hasMount = typeof composable.onMount === "function";
+        const hasUnmount = typeof composable.onUnmount === "function";
+        if (hasMount || hasUnmount) {
+          addLifecycleHooks(instance, hasMount ? mount : undefined, hasUnmount ? unmount : undefined);
+        }
+      },
+    };
   });
 }

package/src/properties/computed.ts

@@ -1,55 +1,45 @@
-import { computed } from "@praxisjs/core/internal";
+import { ComputedNode, readComputed } from "@praxisjs/core/internal";
 
-import { createAccessorDecorator } from "../create-accessor-decorator";
-import { createWritableGetterDecorator } from "../create-getter-decorator";
+import { createGetterDecorator, type GetterDecorator } from "../create-getter-decorator";
 
-export interface ComputedOptions<T = unknown> {
-  get?: (this: object) => T;
-  set?: (this: object, value: T) => void;
+export interface ComputedOptions {
+  /**
+   * Handles writes to the property. A `set` accessor declared next to the getter in the class
+   * does the same, and TypeScript sees it.
+   */
+  set?(this: object, value: unknown): void;
 }
 
-// Accessor form — @Computed({ get, set }) on an `accessor` field.
-// TypeScript sees the accessor as writable; no cast needed when assigning.
-// The `Owner` generic is inferred from the `this` type of the provided functions.
-export function Computed<T, Owner extends object = object>(options: {
-  get: (this: Owner) => T;
-  set: (this: Owner, value: T) => void;
-}): <This extends object>(
-  target: ClassAccessorDecoratorTarget<This, T>,
-  context: ClassAccessorDecoratorContext<This, T>,
-) => ClassAccessorDecoratorResult<This, T>;
+type Host = Record<symbol, ComputedNode | undefined>;
 
-// Getter form — @Computed() or @Computed({ set }) on a `get` accessor.
-export function Computed(options?: {
-  set?: (this: object, value: unknown) => void;
-}): <This, R>(
-  target: (this: This) => R,
-  context: ClassGetterDecoratorContext<This, R>,
-) => (this: This) => R;
-
-export function Computed<T = unknown>(options?: ComputedOptions<T>): unknown {
-  const optionsGet = options?.get as ((this: object) => unknown) | undefined;
-  const optionsSet = options?.set as ((this: object, value: unknown) => void) | undefined;
-
-  if (optionsGet) {
-    return createAccessorDecorator({
-      bind(instance, _name, _initialValue) {
-        const c = computed(() => optionsGet.call(instance));
-        return {
-          get: c,
-          set: optionsSet ? (value) => { optionsSet.call(instance, value); } : undefined,
-        };
-      },
-    });
-  }
+// Kept out of the getter: a closure created inside it would make every read allocate a context.
+function computedFor<T>(instance: T, getter: (this: T) => unknown): ComputedNode {
+  return new ComputedNode(() => getter.call(instance));
+}
 
-  return createWritableGetterDecorator({
-    bind(instance, _name, original) {
-      const c = computed(() => original.call(instance));
+/**
+ * Caches a getter as a reactive computed. A `set` accessor declared next to the getter makes the
+ * property writable.
+ */
+export function Computed(options?: ComputedOptions): GetterDecorator {
+  // eslint-disable-next-line @typescript-eslint/unbound-method -- installed on the class, which calls it with the instance as `this`
+  const set = options?.set;
+  return createGetterDecorator<Host>({
+    label: "@Computed()",
+    setup(original, context) {
+      const node = Symbol(`praxis.computed.${String(context.name)}`);
       return {
-        get: c,
-        set: optionsSet ? (value) => { optionsSet.call(instance, value); } : undefined,
+        // Shared by every instance; the computed itself is only created the first time it is read,
+        // so a getter that a component never reads costs nothing beyond its slot.
+        get(this: Host) {
+          return readComputed((this[node] ??= computedFor(this, original)));
+        },
+        set,
+        init(instance) {
+          // The slot is created up front so every instance keeps the same shape.
+          instance[node] = undefined;
+        },
       };
     },
-  });
+  }) as GetterDecorator;
 }

package/src/properties/deep-state.ts

@@ -1,62 +1,77 @@
-import { markStateDirty, signal } from "@praxisjs/core/internal";
+import { markStateDirty, readSignal, SignalNode, writeSignal } from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
 
 import type { ReactiveHost } from "../reactive-host";
 
-function deepProxy<T extends object>(target: T, notify: () => void): T {
-  return new Proxy(target, {
-    get(obj, key, receiver) {
-      const val: unknown = Reflect.get(obj, key, receiver);
-      if (val !== null && typeof val === "object") {
-        return deepProxy(val, notify);
-      }
-      return val;
-    },
-    set(obj, key, value) {
-      const result = Reflect.set(obj, key, value);
-      notify();
-      return result;
-    },
-    deleteProperty(obj, key) {
-      const result = Reflect.deleteProperty(obj, key);
-      notify();
-      return result;
-    },
-  });
+// One per decorated field per instance. It is also the handler of every proxy it hands out, so
+// proxying a nested object allocates only the Proxy itself.
+class DeepStateCell implements ProxyHandler<object> {
+  readonly version = new SignalNode(0);
+  // One proxy per raw object: repeated reads return the same reference (so `a.b === a.b` and
+  // identity comparisons in effects hold) and don't allocate a new Proxy on every access.
+  private proxies: WeakMap<object, object> | undefined = undefined;
+  current: unknown;
+
+  constructor(private readonly host: object, value: unknown) {
+    this.current = this.wrap(value);
+  }
+
+  wrap(value: unknown): unknown {
+    if (value === null || typeof value !== "object") return value;
+    const proxies = (this.proxies ??= new WeakMap());
+    let proxy = proxies.get(value);
+    if (proxy === undefined) {
+      proxy = new Proxy(value, this);
+      proxies.set(value, proxy);
+    }
+    return proxy;
+  }
+
+  changed(): void {
+    markStateDirty(this.host);
+    writeSignal(this.version, this.version.value + 1);
+  }
+
+  get(obj: object, key: string | symbol, receiver: unknown): unknown {
+    return this.wrap(Reflect.get(obj, key, receiver));
+  }
+
+  set(obj: object, key: string | symbol, value: unknown): boolean {
+    const had = Object.hasOwn(obj, key);
+    const prev: unknown = Reflect.get(obj, key);
+    const result = Reflect.set(obj, key, value);
+    if (!had || !Object.is(prev, value)) this.changed();
+    return result;
+  }
+
+  deleteProperty(obj: object, key: string | symbol): boolean {
+    const had = Object.hasOwn(obj, key);
+    const result = Reflect.deleteProperty(obj, key);
+    if (had) this.changed();
+    return result;
+  }
 }
 
-export function DeepState() {
-  return createFieldDecorator<ReactiveHost>({
-    bind(instance, _name, initialValue) {
-      const version = signal(0);
-      let current = initialValue;
-      let proxy =
-        current !== null && typeof current === "object"
-          ? deepProxy(current, notify)
-          : current;
-
-      function notify() {
-        markStateDirty(instance);
-        version.update((v) => v + 1);
-      }
-
-      return {
-        descriptor: {
-          get() {
-            version();
-            return proxy;
-          },
-          set(value: unknown) {
-            current = value;
-            proxy =
-              value !== null && typeof value === "object"
-                ? deepProxy(value, notify)
-                : value;
-            notify();
-          },
+export function DeepState(): FieldDecorator<ReactiveHost> {
+  return sharedField<ReactiveHost>((name) => {
+    const slot = Symbol(`praxis.deepState.${name}`);
+    return {
+      descriptor: {
+        get(this: FieldHost) {
+          const cell = this[slot] as DeepStateCell;
+          readSignal(cell.version);
+          return cell.current;
+        },
+        set(this: FieldHost, value: unknown) {
+          const cell = this[slot] as DeepStateCell;
+          cell.current = cell.wrap(value);
+          cell.changed();
         },
-      };
-    },
+      },
+      init(instance, initialValue) {
+        instance[slot] = new DeepStateCell(instance, initialValue);
+      },
+    };
   });
 }

package/src/properties/function-prop.ts

@@ -4,34 +4,32 @@ import {
   setComponentDefault,
 } from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
 
-export function FunctionProp() {
-  return createFieldDecorator({
-    bind(instance, name, initialValue) {
+export function FunctionProp(): FieldDecorator {
+  return sharedField((name) => ({
+    descriptor: {
+      get(this: FieldHost) {
+        const fromParent = getComponentRawProp(this, name);
+        if (fromParent !== undefined) {
+          if (
+            process.env.NODE_ENV !== "production" &&
+            typeof fromParent !== "function"
+          ) {
+            console.warn(
+              `[FunctionProp] "${name}" received a non-function value (${typeof fromParent}). @FunctionProp() expects a function.`,
+            );
+          }
+          return fromParent;
+        }
+        return getComponentDefault(this, name);
+      },
+      set(this: FieldHost, value: unknown) {
+        setComponentDefault(this, name, value);
+      },
+    },
+    init(instance, initialValue) {
       setComponentDefault(instance, name, initialValue);
-      return {
-        descriptor: {
-          get() {
-            const fromParent = getComponentRawProp(instance, name);
-            if (fromParent !== undefined) {
-              if (
-                process.env.NODE_ENV !== "production" &&
-                typeof fromParent !== "function"
-              ) {
-                console.warn(
-                  `[FunctionProp] "${name}" received a non-function value (${typeof fromParent}). @FunctionProp() expects a function.`,
-                );
-              }
-              return fromParent;
-            }
-            return getComponentDefault(instance, name);
-          },
-          set(value: unknown) {
-            setComponentDefault(instance, name, value);
-          },
-        },
-      };
     },
-  });
+  }));
 }