@praxisjs/decorators 1.7.0 → 2.0.1

package/src/properties/history.ts

@@ -1,45 +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));
         },
-        // The tracking effect would otherwise keep recording a source that outlives the component.
-        onUnmount() { h?.destroy(); },
-      };
-    },
+      },
+      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

@@ -4,21 +4,24 @@ import {
   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, PersistedSignal<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>,
 ): PersistedSignal<T> {
-  let map = signalMap.get(instance);
-  if (!map) {
-    map = new Map();
-    signalMap.set(instance, map);
-  }
+  const map = (instance[SIGNALS] ??= new Map<string, PersistedSignal<unknown>>());
   let sig = map.get(storageKey);
   if (!sig) {
     sig = persistedSignal(storageKey, initialValue, options) as PersistedSignal<unknown>;
@@ -30,18 +33,25 @@ function getOrCreateSignal<T>(
 export function Persisted<T>(
   key?: string,
   options: PersistedSignalOptions<T> = {},
-) {
-  return createFieldDecorator({
-    bind(instance, name, initialValue) {
-      const sig = getOrCreateSignal(instance, key ?? name, initialValue as T, options);
-      return {
-        descriptor: {
-          get: () => sig(),
-          set: (value: T) => { sig.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);
         },
-        // Without this every mounted instance would leave a window "storage" listener behind.
-        onUnmount() { sig.close(); },
-      };
-    },
+      },
+      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);
+      },
+    };
   });
 }

package/src/shared-method.ts

@@ -0,0 +1,101 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyMethod = (this: any, ...args: any[]) => any;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type MethodContext = ClassMethodDecoratorContext<any, any>;
+
+// Replacements installed through sharedMethod, and the ones an outer decorator wrapped again. Only
+// read while decorating and while building the first instance of a class.
+const shared = new WeakSet<AnyMethod>();
+const superseded = new WeakSet<AnyMethod>();
+
+function isPrototype(object: object): boolean {
+  // Class prototypes own their `constructor`; instances inherit it.
+  return Object.hasOwn(object, "constructor");
+}
+
+function ownerOf(object: object, name: PropertyKey): object | null {
+  let owner: object | null = object;
+  while (owner !== null && !Object.hasOwn(owner, name)) owner = Object.getPrototypeOf(owner) as object | null;
+  return owner;
+}
+
+function defineOwnMethod(object: object, name: PropertyKey, value: unknown): void {
+  Object.defineProperty(object, name, { value, configurable: true, writable: true });
+}
+
+/**
+ * Returns `method`, the decorator's replacement for `value`, set up so that reading it from an
+ * instance returns it bound to that instance, the same function on every read: detached calls
+ * (`onClick={this.save}`) keep working. `method` is shared by every instance and keeps any
+ * per-instance state in symbol slots.
+ *
+ * Rather than defining a bound wrapper on each instance as it is built, the first instance turns
+ * the method's prototype entry into an accessor: an instance pays for its bound copy only when the
+ * method is first read from it, and nothing if it never is.
+ */
+export function sharedMethod<F extends AnyMethod>(
+  context: MethodContext,
+  value: AnyMethod,
+  method: F = value as F,
+): F {
+  if (value === method) {
+    // @Bind over a decorator that already binds: nothing left to do.
+    if (shared.has(method)) return method;
+  } else {
+    // The inner decorator's replacement now only runs through this one, which does the binding.
+    superseded.add(value);
+  }
+  shared.add(method);
+  // `this.#method` can't be read detached through a property, so there is nothing to bind.
+  if (context.private) return method;
+
+  const name = context.name;
+  let installed = false;
+  let home: object | undefined;
+
+  const accessor: PropertyDescriptor = {
+    configurable: true,
+    enumerable: false,
+    get(this: object | undefined) {
+      // Read from a prototype, or through `super.method()` from a subclass override: caching a
+      // bound copy on the instance would then shadow the override. Read with no receiver at all,
+      // as `vi.spyOn(instance, name)` does with a getter it finds on the prototype: the spy then
+      // wraps the method itself, which takes `this` from each call.
+      if (this == null || isPrototype(this) || ownerOf(this, name) !== home) return method;
+      const bound = method.bind(this);
+      defineOwnMethod(this, name, bound);
+      return bound;
+    },
+    set(this: object, next: unknown) {
+      defineOwnMethod(this, name, next);
+    },
+  };
+
+  context.addInitializer(function (this: unknown) {
+    if (installed) return;
+    const target = this as object;
+    if (superseded.has(method)) {
+      installed = true;
+      return;
+    }
+    if (!context.static) {
+      for (
+        let proto = Object.getPrototypeOf(target) as object | null;
+        proto !== null;
+        proto = Object.getPrototypeOf(proto) as object | null
+      ) {
+        if (Object.getOwnPropertyDescriptor(proto, name)?.value === method) {
+          installed = true;
+          home = proto;
+          Object.defineProperty(proto, name, accessor);
+          return;
+        }
+      }
+    }
+    // A static method (bound to its class, as before), or a decorator applied by hand whose
+    // replacement never reached a prototype: bind it on the object itself.
+    defineOwnMethod(target, name, method.bind(target));
+  });
+
+  return method;
+}

package/dist/__tests__/component.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=component.test.d.ts.map

package/dist/__tests__/component.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"component.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/component.test.ts"],"names":[],"mappings":""}