@praxisjs/decorators 1.6.1 → 2.0.0

package/src/properties/history.ts

@@ -1,43 +1,44 @@
-import type { StatefulComponent } from "@praxisjs/core";
 import { type HistoryElement, history } from "@praxisjs/core/internal";
 import type { Signal } from "@praxisjs/shared";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
+import { addLifecycleHooks } from "../lifecycle";
 
 export type HistoryOf<C, K extends keyof C> = HistoryElement<C[K]>;
 
-export function History(fieldName: string, limit = 50) {
-  return createFieldDecorator({
-    bind(instance: StatefulComponent, _name: string) {
-      const inst = instance as unknown as Record<string, unknown>;
-      let h: HistoryElement<unknown> | undefined;
-
-      const source = () => inst[fieldName];
+function createHistory(host: FieldHost, fieldName: string, limit: number): HistoryElement<unknown> {
+  const h = history((() => host[fieldName]) as Signal<unknown>, limit);
+  const undo = h.undo.bind(h);
+  const redo = h.redo.bind(h);
+  h.undo = () => {
+    const prev = h.values()[h.values().length - 2];
+    if (prev === undefined) return;
+    undo();
+    host[fieldName] = prev;
+  };
+  h.redo = () => {
+    redo();
+    host[fieldName] = h.current();
+  };
+  return h;
+}
 
-      return {
-        descriptor: {
-          get(): HistoryElement<unknown> {
-            if (!h) {
-              const hInst = history(source as Signal<unknown>, limit);
-              const _undo = hInst.undo.bind(hInst);
-              const _redo = hInst.redo.bind(hInst);
-              hInst.undo = () => {
-                const prev = hInst.values()[hInst.values().length - 2];
-                if (prev === undefined) return;
-                _undo();
-                inst[fieldName] = prev;
-              };
-              hInst.redo = () => {
-                _redo();
-                inst[fieldName] = hInst.current();
-              };
-              h = hInst;
-            }
-            return h;
-          },
-          enumerable: false,
+export function History(fieldName: string, limit = 50): FieldDecorator {
+  return sharedField((name) => {
+    const slot = Symbol(`praxis.history.${name}`);
+    // The tracking effect would otherwise keep recording a source that outlives the component.
+    const destroy = (instance: object) => { ((instance as FieldHost)[slot] as HistoryElement<unknown> | undefined)?.destroy(); };
+    return {
+      descriptor: {
+        enumerable: false,
+        // Created on first read, so an instance whose history is never read records nothing.
+        get(this: FieldHost) {
+          return (this[slot] ??= createHistory(this, fieldName, limit));
         },
-      };
-    },
+      },
+      init(instance) {
+        addLifecycleHooks(instance, undefined, destroy);
+      },
+    };
   });
 }

package/src/properties/index.ts

@@ -10,3 +10,4 @@ export { Resource, invalidateResource, type ResourceInstance, type ResourceOptio
 export { Synced } from "./synced";
 export { DeepState } from "./deep-state";
 export { Ref, createRef } from "./ref";
+export { Selector, type SelectorOptions } from "./selector";

package/src/properties/persisted.ts

@@ -1,43 +1,57 @@
-import { persistedSignal, type PersistedSignalOptions } from "@praxisjs/core/internal";
-import type { Signal } from "@praxisjs/shared";
+import {
+  persistedSignal,
+  type PersistedSignal,
+  type PersistedSignalOptions,
+} from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
+import { addLifecycleHooks } from "../lifecycle";
 
-const signalMap = new WeakMap<object, Map<string, Signal<unknown>>>();
+// Fields of one instance that persist under the same key share one signal. Only read while the
+// instance is built; each field then reads its signal from its own slot.
+const SIGNALS: unique symbol = Symbol("praxis.persistedSignals");
+
+interface PersistedHost {
+  [SIGNALS]?: Map<string, PersistedSignal<unknown>>;
+}
 
 function getOrCreateSignal<T>(
-  instance: object,
+  instance: PersistedHost,
   storageKey: string,
   initialValue: T,
   options: PersistedSignalOptions<T>,
-): Signal<T> {
-  if (!signalMap.has(instance)) signalMap.set(instance, new Map());
-  const map = signalMap.get(instance) as Map<string, Signal<unknown>>;
-  if (!map.has(storageKey)) {
-    map.set(
-      storageKey,
-      persistedSignal(storageKey, initialValue, options) as Signal<unknown>,
-    );
+): PersistedSignal<T> {
+  const map = (instance[SIGNALS] ??= new Map<string, PersistedSignal<unknown>>());
+  let sig = map.get(storageKey);
+  if (!sig) {
+    sig = persistedSignal(storageKey, initialValue, options) as PersistedSignal<unknown>;
+    map.set(storageKey, sig);
   }
-  return map.get(storageKey) as Signal<T>;
+  return sig as PersistedSignal<T>;
 }
 
 export function Persisted<T>(
   key?: string,
   options: PersistedSignalOptions<T> = {},
-) {
-  return createFieldDecorator({
-    bind(instance, name, initialValue) {
-      const storageKey = key ?? name;
-      getOrCreateSignal(instance, storageKey, initialValue as T, options);
-      return {
-        descriptor: {
-          get: () =>
-            getOrCreateSignal(instance, storageKey, undefined as T, options)(),
-          set: (value: T) =>
-            { getOrCreateSignal(instance, storageKey, undefined as T, options).set(value); },
+): FieldDecorator {
+  return sharedField((name) => {
+    const slot = Symbol(`praxis.persisted.${name}`);
+    const storageKey = key ?? name;
+    // Without this every mounted instance would leave a window "storage" listener behind.
+    const close = (instance: object) => { ((instance as FieldHost)[slot] as PersistedSignal<T>).close(); };
+    return {
+      descriptor: {
+        get(this: FieldHost) {
+          return (this[slot] as PersistedSignal<T>)();
+        },
+        set(this: FieldHost, value: T) {
+          (this[slot] as PersistedSignal<T>).set(value);
         },
-      };
-    },
+      },
+      init(instance, initialValue) {
+        instance[slot] = getOrCreateSignal(instance, storageKey, initialValue as T, options);
+        addLifecycleHooks(instance, undefined, close);
+      },
+    };
   });
 }

package/src/properties/prop.ts

@@ -1,31 +1,39 @@
+import type { StatefulComponent } from "@praxisjs/core";
 import {
   getComponentDefault,
   getComponentRawProp,
   setComponentDefault,
 } from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { addClaimableInitializer, assertFieldContext } from "../field";
 
 export function Prop() {
-  return createFieldDecorator({
-    bind(instance, name, initialValue) {
-      setComponentDefault(instance, name, initialValue);
-      return {
-        descriptor: {
-          get() {
-            const fromParent = getComponentRawProp(instance, name);
-            if (fromParent !== undefined) {
-              return typeof fromParent === "function"
-                ? (fromParent as () => unknown)()
-                : fromParent;
-            }
-            return getComponentDefault(instance, name);
-          },
-          set(value: unknown) {
-            setComponentDefault(instance, name, value);
-          },
-        },
-      };
-    },
-  });
+  return function <This extends StatefulComponent, Value = unknown>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<This, Value>,
+  ): void {
+    assertFieldContext(context, "@Prop()");
+    const name = context.name as string;
+    // Shared by every instance, like @State's accessors.
+    const descriptor: PropertyDescriptor = {
+      enumerable: true,
+      configurable: true,
+      get(this: object) {
+        const fromParent = getComponentRawProp(this, name);
+        if (fromParent !== undefined) {
+          return typeof fromParent === "function"
+            ? (fromParent as () => unknown)()
+            : fromParent;
+        }
+        return getComponentDefault(this, name);
+      },
+      set(this: object, value: unknown) {
+        setComponentDefault(this, name, value);
+      },
+    };
+    addClaimableInitializer(context, function (value) {
+      setComponentDefault(this, name, value);
+      Object.defineProperty(this, name, descriptor);
+    });
+  };
 }

package/src/properties/ref.ts

@@ -1,11 +1,10 @@
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
 
 export type Ref<T extends Element = Element> = ((el: T | null) => void) & {
   current: T | null;
 };
 
 /** Creates a standalone ref object for use outside of class fields (e.g. module-level or passed to @Lazy). */
- 
 export function createRef<T extends Element = Element>(): Ref<T> {
   function refFn(el: T | null): void {
     (refFn as Ref<T>).current = el;
@@ -15,13 +14,16 @@ export function createRef<T extends Element = Element>(): Ref<T> {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-export function Ref<T extends Element = Element>() {
-  return createFieldDecorator({
-    bind(_instance, _name, _initialValue) {
-      const ref = createRef<T>();
-      return {
-        descriptor: { get: () => ref },
-      };
-    },
+export function Ref<T extends Element = Element>(): FieldDecorator {
+  return sharedField((name) => {
+    const ref = Symbol(`praxis.ref.${name}`);
+    return {
+      descriptor: {
+        // Created on first read: a ref that is never handed to an element costs nothing.
+        get(this: FieldHost) {
+          return (this[ref] ??= createRef<T>());
+        },
+      },
+    };
   });
 }

package/src/properties/resource.ts

@@ -4,7 +4,8 @@ import {
   type ResourceOptions,
 } from "@praxisjs/core/internal";
 
-import { createFieldDecorator, type FieldBinding } from "../create-field-decorator";
+import { type FieldHost, sharedField } from "../field";
+import { addLifecycleHooks } from "../lifecycle";
 
 export { invalidateResource } from "@praxisjs/core/internal";
 export type { ResourceInstance, ResourceOptions };
@@ -30,22 +31,26 @@ export function Resource<T>(
   fetcher: (() => Promise<T>) | ((self: any) => Promise<T>),
   options: ResourceOptions<T> = {},
 ): FieldDecoratorReturn {
-  return createFieldDecorator({
-    bind(instance, _name, _initialValue): FieldBinding {
-      const bound =
-        fetcher.length > 0
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          ? () => (fetcher as (self: any) => Promise<T>)(instance)
-          : (fetcher as () => Promise<T>);
-      const r = resource(bound, options);
-      return {
-        descriptor: {
-          get(): ResourceInstance<T> { return r; },
-          // eslint-disable-next-line @typescript-eslint/no-empty-function
-          set(): void {},
+  return sharedField((name) => {
+    const slot = Symbol(`praxis.resource.${name}`);
+    const destroy = (instance: object) => { ((instance as FieldHost)[slot] as ResourceInstance<T>).destroy(); };
+    return {
+      descriptor: {
+        get(this: FieldHost): ResourceInstance<T> {
+          return this[slot] as ResourceInstance<T>;
         },
-        onUnmount() { r.destroy(); },
-      };
-    },
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        set(): void {},
+      },
+      init(instance) {
+        const bound =
+          fetcher.length > 0
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ? () => (fetcher as (self: any) => Promise<T>)(instance)
+            : (fetcher as () => Promise<T>);
+        instance[slot] = resource(bound, options);
+        addLifecycleHooks(instance, undefined, destroy);
+      },
+    };
   }) as unknown as FieldDecoratorReturn;
 }

package/src/properties/selector.ts

@@ -0,0 +1,45 @@
+import { selector, type Selector as SelectorFn, type SelectorEquals } from "@praxisjs/core/internal";
+import type { Computed } from "@praxisjs/shared";
+import { isComputed } from "@praxisjs/shared/internal";
+
+import { type FieldHost, sharedField } from "../field";
+
+export type Selector<K> = SelectorFn<K>;
+
+export interface SelectorOptions<K, T> {
+  /**
+   * Decides whether `key` is selected for the source value `value`. Defaults to a strict
+   * comparison (SameValueZero), which notifies only the previous and next keys; a custom function
+   * is evaluated against every key in use whenever the source changes.
+   */
+  equals?: SelectorEquals<K, T>;
+}
+
+function createSelector<K, T>(host: FieldHost, source: string, equals: SelectorEquals<K, T> | undefined): SelectorFn<K> {
+  const read = () => {
+    const raw = host[source];
+    return (isComputed(raw) ? (raw as Computed<unknown>)() : raw) as T;
+  };
+  return equals ? selector(read, equals) : (selector(read) as unknown as SelectorFn<K>);
+}
+
+export function Selector<const Name extends string, K = unknown, T = unknown>(
+  source: Name,
+  options: SelectorOptions<K, T> = {},
+) {
+  const decorator = sharedField<object>((name) => {
+    const slot = Symbol(`praxis.selector.${name}`);
+    return {
+      descriptor: {
+        // Created on first read, so the source field may be declared after this one.
+        get(this: FieldHost) {
+          return (this[slot] ??= createSelector(this, source, options.equals));
+        },
+      },
+    };
+  });
+  return decorator as <This extends Record<Name, unknown>, Value extends Selector<never>>(
+    value: undefined,
+    context: ClassFieldDecoratorContext<This, Value>,
+  ) => void;
+}

package/src/properties/slot.ts

@@ -1,6 +1,11 @@
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
 
-const slotsMap = new WeakMap<object, Map<string, unknown[]>>();
+// On the instance rather than in a WeakMap: every slot field read goes through here.
+const SLOTS: unique symbol = Symbol("praxis.slots");
+
+interface SlotHost {
+  [SLOTS]?: Map<string, unknown[]>;
+}
 
 function resolveSlots(children: unknown): Map<string, unknown[]> {
   const slots = new Map<string, unknown[]>();
@@ -18,8 +23,9 @@ function resolveSlots(children: unknown): Map<string, unknown[]> {
       const slotName = child.getAttribute("slot");
       if (slotName) {
         child.removeAttribute("slot");
-        if (!slots.has(slotName)) slots.set(slotName, []);
-        (slots.get(slotName) as unknown[]).push(child);
+        let named = slots.get(slotName);
+        if (!named) slots.set(slotName, (named = []));
+        named.push(child);
         continue;
       }
     }
@@ -30,29 +36,29 @@ function resolveSlots(children: unknown): Map<string, unknown[]> {
 }
 
 export function initSlots(instance: object, children: unknown): void {
-  slotsMap.set(instance, resolveSlots(children));
+  (instance as SlotHost)[SLOTS] = resolveSlots(children);
 }
 
 export function getSlot(instance: object, name: string): unknown[] {
-  return slotsMap.get(instance)?.get(name) ?? [];
+  return (instance as SlotHost)[SLOTS]?.get(name) ?? [];
 }
 
-export function Slot(name?: string) {
-  return createFieldDecorator({
-    bind(instance, propName, _initialValue) {
-      const slotName = name ?? (propName === "default" ? "default" : propName);
-      return {
-        descriptor: {
-          get: () => getSlot(instance, slotName),
-          set: (_value: unknown) => {
-            if (process.env.NODE_ENV !== "production") {
-              console.warn(
-                `[Slot] "${propName}" is a slot and cannot be assigned directly. Slots are filled by the parent component.`,
-              );
-            }
-          },
+export function Slot(name?: string): FieldDecorator {
+  return sharedField((propName) => {
+    const slotName = name ?? propName;
+    return {
+      descriptor: {
+        get(this: FieldHost) {
+          return getSlot(this, slotName);
+        },
+        set(_value: unknown) {
+          if (process.env.NODE_ENV !== "production") {
+            console.warn(
+              `[Slot] "${propName}" is a slot and cannot be assigned directly. Slots are filled by the parent component.`,
+            );
+          }
         },
-      };
-    },
+      },
+    };
   });
 }

package/src/properties/state.ts

@@ -1,22 +1,38 @@
-import { markStateDirty, signal } from "@praxisjs/core/internal";
+import { markStateDirty, readSignal, SignalNode, writeSignal } from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { addClaimableInitializer, assertFieldContext } from "../field";
 
 import type { ReactiveHost } from "../reactive-host";
 
+type StateHost = Record<PropertyKey, unknown>;
+
 export function State() {
-  return createFieldDecorator<ReactiveHost>({
-    bind(instance, _name, initialValue) {
-      const sig = signal(initialValue);
-      return {
-        descriptor: {
-          get: () => sig(),
-          set: (value: unknown) => {
-            markStateDirty(instance);
-            sig.set(value);
-          },
-        },
-      };
-    },
-  });
+  return function <This extends ReactiveHost, Value = unknown>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<This, Value>,
+  ): void {
+    assertFieldContext(context, "@State()");
+    const name = context.name;
+    // One accessor pair per decorated field, shared by every instance: per-instance closures would
+    // give each instance its own hidden class, turning every field read into a megamorphic access.
+    // It stays an own property of each instance, so decorators stacked above @State (and custom ones
+    // built with createFieldDecorator) find and wrap it, and a Proxy around the instance works.
+    const node = Symbol(`praxis.state.${String(name)}`);
+    const descriptor: PropertyDescriptor = {
+      enumerable: true,
+      configurable: true,
+      get(this: StateHost) {
+        return readSignal(this[node] as SignalNode);
+      },
+      set(this: StateHost, value: unknown) {
+        markStateDirty(this);
+        writeSignal(this[node] as SignalNode, value);
+      },
+    };
+    addClaimableInitializer(context, function (value) {
+      const instance = this as unknown as StateHost;
+      instance[node] = new SignalNode(value);
+      Object.defineProperty(instance, name, descriptor);
+    });
+  };
 }

package/src/properties/synced.ts

@@ -1,28 +1,40 @@
 import { syncedSignal, type SyncedSignal } from "@praxisjs/core/internal";
 
-import { createFieldDecorator } from "../create-field-decorator";
+import { type FieldDecorator, type FieldHost, sharedField } from "../field";
+import { addLifecycleHooks } from "../lifecycle";
 
-const signalMap = new WeakMap<object, Map<string, SyncedSignal<unknown>>>();
+// Fields of one instance synced over the same channel share one signal. Only read while the
+// instance is built; each field then reads its signal from its own slot.
+const SIGNALS: unique symbol = Symbol("praxis.syncedSignals");
 
-export function Synced(channelName?: string) {
-  return createFieldDecorator({
-    bind(instance, name, initialValue) {
-      const key = channelName ?? name;
-
-      if (!signalMap.has(instance)) signalMap.set(instance, new Map());
-      const map = signalMap.get(instance) as Map<string, SyncedSignal<unknown>>;
-      if (!map.has(key)) map.set(key, syncedSignal(key, initialValue));
-      const sig = map.get(key) as SyncedSignal<unknown>;
+interface SyncedHost {
+  [SIGNALS]?: Map<string, SyncedSignal<unknown>>;
+}
 
-      return {
-        descriptor: {
-          get: () => sig(),
-          set: (value: unknown) => { sig.set(value); },
+export function Synced(channelName?: string): FieldDecorator {
+  return sharedField((name) => {
+    const slot = Symbol(`praxis.synced.${name}`);
+    const key = channelName ?? name;
+    const close = (instance: object) => { ((instance as FieldHost)[slot] as SyncedSignal<unknown>).close(); };
+    return {
+      descriptor: {
+        get(this: FieldHost) {
+          return (this[slot] as SyncedSignal<unknown>)();
         },
-        onUnmount() {
-          sig.close();
+        set(this: FieldHost, value: unknown) {
+          (this[slot] as SyncedSignal<unknown>).set(value);
         },
-      };
-    },
+      },
+      init(instance, initialValue) {
+        const map = ((instance as SyncedHost)[SIGNALS] ??= new Map<string, SyncedSignal<unknown>>());
+        let sig = map.get(key);
+        if (!sig) {
+          sig = syncedSignal(key, initialValue);
+          map.set(key, sig);
+        }
+        instance[slot] = sig;
+        addLifecycleHooks(instance, undefined, close);
+      },
+    };
   });
 }