@praxisjs/decorators 1.7.0 → 2.0.1

package/src/events/emit.ts

@@ -1,31 +1,25 @@
 import type { StatefulComponent } from "@praxisjs/core";
 
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 import { readProp } from "./helper";
 
 export function Emit(propName: string) {
-  return createMethodDecorator({
-    wrap(original, instance) {
-      const comp = instance as StatefulComponent;
-      return (...args: unknown[]) => {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const result = original.apply(instance, args);
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    return sharedMethod(context, value, function (this: StatefulComponent, ...args: unknown[]): unknown {
+      const result = value.apply(this, args) as unknown;
 
-        const callback = readProp(comp, propName);
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        if (typeof callback !== "function") return result;
+      const callback = readProp(this, propName);
+      if (typeof callback !== "function") return result;
 
-        if (result !== undefined) {
-          (callback as (v: unknown) => void)(result);
-        } else if (args.length > 0) {
-          (callback as (...a: unknown[]) => void)(...args);
-        } else {
-          (callback as () => void)();
-        }
+      if (result !== undefined) {
+        (callback as (v: unknown) => void)(result);
+      } else if (args.length > 0) {
+        (callback as (...a: unknown[]) => void)(...args);
+      } else {
+        (callback as () => void)();
+      }
 
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return result;
-      };
-    },
-  });
+      return result;
+    });
+  };
 }

package/src/events/on-command.ts

@@ -1,29 +1,28 @@
+import type { StatefulComponent } from "@praxisjs/core";
 
-import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
+import { lifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 import { readProp } from "./helper";
 
 import type { Command } from "./command";
 
 export function OnCommand(propName: string) {
-  return createLifecycleMethodDecorator({
-    register(callback, instance) {
-      const command = readProp(instance, propName) as Command<unknown> | undefined;
+  return lifecycleMethodDecorator<StatefulComponent>((instance, method) => {
+    const command = readProp(instance, propName) as Command<unknown> | undefined;
 
-      if (!command) {
-        console.warn(
-          `[OnCommand] prop "${propName}" was not provided to ${(instance.constructor as { name?: string }).name ?? "unknown"}`,
-        );
-        return;
-      }
+    if (!command) {
+      console.warn(
+        `[OnCommand] prop "${propName}" was not provided to ${(instance.constructor as { name?: string }).name ?? "unknown"}`,
+      );
+      return;
+    }
 
-      if (typeof command.subscribe !== "function") {
-        console.warn(
-          `[OnCommand] prop "${propName}" is not a valid Command in ${(instance.constructor as { name?: string }).name ?? "unknown"}`,
-        );
-        return;
-      }
+    if (typeof command.subscribe !== "function") {
+      console.warn(
+        `[OnCommand] prop "${propName}" is not a valid Command in ${(instance.constructor as { name?: string }).name ?? "unknown"}`,
+      );
+      return;
+    }
 
-      return command.subscribe((...args: unknown[]) => { callback(...args); });
-    },
+    return command.subscribe((...args: unknown[]) => { method.apply(instance, args); });
   });
 }

package/src/field.ts

@@ -0,0 +1,116 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+/**
+ * The signature of a field decorator: usable on fields of classes extending `Base` whose type is
+ * assignable to `Value`, so TypeScript rejects `@Clamp() name = ''` for a number-only decorator.
+ */
+export type FieldDecorator<Base = StatefulComponent, Value = unknown> = <This extends Base, V extends Value = Value>(
+  value: undefined,
+  context: ClassFieldDecoratorContext<This, V>,
+) => void;
+
+export type FieldHost = Record<PropertyKey, unknown>;
+
+const KIND_NAMES: Record<DecoratorContext["kind"], string> = {
+  class: "classes",
+  method: "methods",
+  getter: "getters",
+  setter: "setters",
+  field: "class fields",
+  accessor: "accessors",
+};
+
+export function describeValue(value: unknown): string {
+  if (typeof value === "function") return "a function";
+  if (typeof value === "object" && value !== null) return "an object";
+  return String(value as string | number | bigint | boolean | symbol | null | undefined);
+}
+
+/**
+ * Throws when a decorator built for one kind of member is applied to another, naming the member,
+ * e.g. `@Confirm() decorates methods only, not the field "title".`
+ */
+export function assertMemberKind(
+  context: { readonly kind: DecoratorContext["kind"]; readonly name: string | symbol | undefined },
+  kind: DecoratorContext["kind"],
+  decorator: string,
+): void {
+  // A context without a kind was built by hand (decorators called directly in tests), not by a
+  // decorator application, which always has one.
+  if (context.kind === kind || (context.kind as string | undefined) === undefined) return;
+  throw new TypeError(
+    `${decorator} decorates ${KIND_NAMES[kind]} only, not the ${context.kind} "${String(context.name)}".`,
+  );
+}
+
+/**
+ * Throws when a field decorator is applied to anything but a plain class field. Above all an
+ * `accessor`: the decorator would install its property on the instance, shadowing the accessor,
+ * and decorators stacked on the same member would wrap the wrong thing.
+ */
+export function assertFieldContext(context: DecoratorContext, decorator = "This field decorator"): void {
+  if (context.kind === "field") return;
+  const member = String(context.name);
+  throw new TypeError(
+    context.kind === "accessor"
+      ? `${decorator} decorates plain class fields only: remove \`accessor\` from "${member}".`
+      : `${decorator} decorates class fields only, not the ${context.kind} "${member}".`,
+  );
+}
+
+/**
+ * Lets the decorator lowering of `@praxisjs/vite-plugin` define a decorated field through its
+ * innermost decorator: an initializer added with `addClaimableInitializer` carries a `claim`
+ * function under this key, which installs the decorator's property directly with the field's
+ * initial value. The field is then never defined as a data property first, which in V8 would turn
+ * every instance into a slow dictionary-mode object when the accessor replaces it. Without the
+ * plugin (or under another decorator in the innermost position), the field is defined as usual and
+ * the initializer runs as an ordinary one.
+ */
+export const CLAIM = Symbol.for("praxisjs.field.claim");
+
+/**
+ * Registers `claim` as the field's initializer: run as an ordinary extra initializer, it reads the
+ * value from the data property the field was defined with; the lowering can call it with the
+ * value instead (see CLAIM).
+ */
+export function addClaimableInitializer<This, Value>(
+  context: ClassFieldDecoratorContext<This, Value>,
+  claim: (this: This, value: Value) => void,
+): void {
+  const name = context.name;
+  const init = function (this: This) {
+    claim.call(this, (this as FieldHost)[name] as Value);
+  } as ((this: This) => void) & { [CLAIM]?: typeof claim };
+  init[CLAIM] = claim;
+  context.addInitializer(init);
+}
+
+export interface SharedField {
+  /** Installed on every instance in place of the field. */
+  descriptor: PropertyDescriptor;
+  /** Runs per instance before the descriptor is installed, with the field's initial value. */
+  init?: (instance: FieldHost, initialValue: unknown) => void;
+}
+
+/**
+ * Builds a field decorator whose accessors are created once per decorated field (by `setup`, at
+ * class definition) and shared by every instance, which keeps its own state in symbol slots: all
+ * instances share one hidden class and building one allocates no closures.
+ */
+export function sharedField<Base = StatefulComponent>(
+  setup: (name: string) => SharedField,
+): FieldDecorator<Base> {
+  return function (_value, context) {
+    assertFieldContext(context);
+    const name = context.name as string;
+    const { descriptor, init } = setup(name);
+    descriptor.enumerable ??= true;
+    descriptor.configurable ??= true;
+    addClaimableInitializer(context, function (value) {
+      const instance = this as unknown as FieldHost;
+      init?.(instance, value);
+      Object.defineProperty(instance, name, descriptor);
+    });
+  };
+}

package/src/functions/bind.ts

@@ -1,7 +1,7 @@
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export function Bind() {
-  return createMethodDecorator({
-    wrap: (original, instance) => original.bind(instance),
-  });
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    return sharedMethod(context, value);
+  };
 }

package/src/functions/debounce.ts

@@ -1,29 +1,31 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { addLifecycleHooks } from "../lifecycle";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
-import { createMethodDecorator } from "../create-method-decorator";
+type Timer = ReturnType<typeof setTimeout>;
 
 export function Debounce(ms: number) {
-  return createMethodDecorator({
-    wrap(original, instance, _name) {
-      let timer: ReturnType<typeof setTimeout> | undefined;
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    // undefined: never called. null: called, nothing pending.
+    const timer = Symbol(`praxis.debounce.${String(context.name)}`);
+    type Host = Record<symbol, Timer | null | undefined>;
 
-      const comp = instance as StatefulComponent;
-      const prevUnmount = comp.onUnmount?.bind(comp);
-      comp.onUnmount = function (this: StatefulComponent) {
-        prevUnmount?.call(this);
-        if (timer !== undefined) {
-          clearTimeout(timer);
-          timer = undefined;
-        }
-      };
+    function cancel(instance: object): void {
+      const pending = (instance as Host)[timer];
+      if (pending != null) {
+        clearTimeout(pending);
+        (instance as Host)[timer] = null;
+      }
+    }
 
-      return (...args: unknown[]) => {
-        if (timer !== undefined) clearTimeout(timer);
-        timer = setTimeout(() => {
-          timer = undefined;
-          original.apply(instance, args);
-        }, ms);
-      };
-    },
-  });
+    return sharedMethod(context, value, function (this: Host, ...args: unknown[]): void {
+      const pending = this[timer];
+      // Only an instance that has called the method can have a timer to cancel on unmount.
+      if (pending === undefined) addLifecycleHooks(this, undefined, cancel);
+      else if (pending !== null) clearTimeout(pending);
+      this[timer] = setTimeout(() => {
+        this[timer] = null;
+        value.apply(this, args);
+      }, ms);
+    });
+  };
 }

package/src/functions/log.ts

@@ -1,4 +1,4 @@
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export interface LogOptions {
   level?: "log" | "warn" | "error" | "debug";
@@ -17,49 +17,47 @@ export function Log(options: LogOptions = {}) {
     devOnly = true,
   } = options;
 
-  return createMethodDecorator({
-    wrap(original, instance, name) {
-      return (...args: unknown[]) => {
-        if (
-          devOnly &&
-          typeof process !== "undefined" &&
-          process.env.NODE_ENV === "production"
-        ) {
-          return original.apply(instance, args) as unknown;
-        }
-
-        const className =
-          (instance.constructor as { name?: string }).name ?? "Unknown";
-        const label = `[${className}.${name}]`;
-        const logger = console[level].bind(console);
-
-        if (logArgs) logger(`${label} args:`, args);
-
-        const start = time ? performance.now() : 0;
-        const output: unknown = original.apply(instance, args) as unknown;
-
-        if (output instanceof Promise) {
-          return (output as Promise<unknown>)
-            .then((resolved) => {
-              const elapsed = time
-                ? ` (${(performance.now() - start).toFixed(2)}ms)`
-                : "";
-              if (result) logger(`${label} resolved:`, resolved, elapsed);
-              return resolved;
-            })
-            .catch((e: unknown) => {
-              logger(`${label} rejected:`, e);
-              throw e;
-            });
-        }
-
-        const elapsed = time
-          ? ` (${(performance.now() - start).toFixed(2)}ms)`
-          : "";
-        if (result) logger(`${label} returned:`, output, elapsed);
-
-        return output;
-      };
-    },
-  });
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    const name = String(context.name);
+    return sharedMethod(context, value, function (this: object, ...args: unknown[]): unknown {
+      if (
+        devOnly &&
+        typeof process !== "undefined" &&
+        process.env.NODE_ENV === "production"
+      ) {
+        return value.apply(this, args) as unknown;
+      }
+
+      const className =
+        (this.constructor as { name?: string }).name ?? "Unknown";
+      const label = `[${className}.${name}]`;
+
+      if (logArgs) console[level](`${label} args:`, args);
+
+      const start = time ? performance.now() : 0;
+      const output: unknown = value.apply(this, args) as unknown;
+
+      if (output instanceof Promise) {
+        return (output as Promise<unknown>)
+          .then((resolved) => {
+            const elapsed = time
+              ? ` (${(performance.now() - start).toFixed(2)}ms)`
+              : "";
+            if (result) console[level](`${label} resolved:`, resolved, elapsed);
+            return resolved;
+          })
+          .catch((e: unknown) => {
+            console[level](`${label} rejected:`, e);
+            throw e;
+          });
+      }
+
+      const elapsed = time
+        ? ` (${(performance.now() - start).toFixed(2)}ms)`
+        : "";
+      if (result) console[level](`${label} returned:`, output, elapsed);
+
+      return output;
+    });
+  };
 }

package/src/functions/memo.ts

@@ -1,7 +1,7 @@
 import { computed } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 const objectIdMap = new WeakMap<object, number>();
 let objectIdCounter = 0;
@@ -13,21 +13,23 @@ function objectIdentityKey(obj: object): string {
   return `__obj_${String(objectIdMap.get(obj))}__`;
 }
 
+function serializeArg(a: unknown): string {
+  if (a === null || typeof a === "object") {
+    try {
+      return JSON.stringify(a);
+    } catch {
+      return objectIdentityKey(a as object);
+    }
+  }
+  if (typeof a === "symbol") return a.toString();
+  return String(a as string | number | boolean | bigint | undefined);
+}
+
 function serializeArgs(args: unknown[]) {
   if (args.length === 0) return "__no_args__";
-  return args
-    .map((a) => {
-      if (a === null || typeof a === "object") {
-        try {
-          return JSON.stringify(a);
-        } catch {
-          return objectIdentityKey(a as object);
-        }
-      }
-      if (typeof a === "symbol") return a.toString();
-      return String(a as string | number | boolean | bigint | undefined);
-    })
-    .join("|");
+  // The common single-argument call skips the intermediate array and join.
+  if (args.length === 1) return serializeArg(args[0]);
+  return args.map(serializeArg).join("|");
 }
 
 export interface MemoOptions {
@@ -45,28 +47,28 @@ type Disposable = Computed<unknown> & { dispose(): void };
 export function Memo(options: MemoOptions = {}) {
   const { max = DEFAULT_MAX } = options;
 
-  return createMethodDecorator({
-    wrap(original, instance, _name) {
-      const cache = new Map<string, Computed<unknown>>();
-      return (...args: unknown[]) => {
-        const key = serializeArgs(args);
-        let memoized = cache.get(key);
-        if (memoized) {
-          // Re-insert so Map order tracks recency.
-          cache.delete(key);
-          cache.set(key, memoized);
-        } else {
-          memoized = computed(() => original.apply(instance, args) as unknown);
-          cache.set(key, memoized);
-          if (cache.size > max) {
-            const [oldestKey, oldest] = cache.entries().next().value as [string, Computed<unknown>];
-            cache.delete(oldestKey);
-            // Releases the entry's hold on the signals it read; a no-op if a binding still uses it.
-            (oldest as Disposable).dispose();
-          }
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    const caches = Symbol(`praxis.memo.${String(context.name)}`);
+    type Host = Record<symbol, Map<string, Computed<unknown>> | undefined>;
+    return sharedMethod(context, value, function (this: Host, ...args: unknown[]): unknown {
+      const cache = (this[caches] ??= new Map<string, Computed<unknown>>());
+      const key = serializeArgs(args);
+      let memoized = cache.get(key);
+      if (memoized) {
+        // Re-insert so Map order tracks recency.
+        cache.delete(key);
+        cache.set(key, memoized);
+      } else {
+        memoized = computed(() => value.apply(this, args) as unknown);
+        cache.set(key, memoized);
+        if (cache.size > max) {
+          const [oldestKey, oldest] = cache.entries().next().value as [string, Computed<unknown>];
+          cache.delete(oldestKey);
+          // Releases the entry's hold on the signals it read; a no-op if a binding still uses it.
+          (oldest as Disposable).dispose();
         }
-        return memoized();
-      };
-    },
-  });
+      }
+      return memoized();
+    });
+  };
 }

package/src/functions/once.ts

@@ -1,16 +1,13 @@
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export function Once() {
-  return createMethodDecorator({
-    wrap(original, instance) {
-      let called = false;
-      let result: unknown;
-      return (...args: unknown[]) => {
-        if (called) return result;
-        result = original.apply(instance, args);
-        called = true;
-        return result;
-      };
-    },
-  });
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    const result = Symbol(`praxis.once.${String(context.name)}`);
+    type Host = Record<symbol, unknown>;
+    return sharedMethod(context, value, function (this: Host, ...args: unknown[]): unknown {
+      if (result in this) return this[result];
+      // Stored only once the call returns, so a call that throws can be retried.
+      return (this[result] = value.apply(this, args));
+    });
+  };
 }

package/src/functions/retry.ts

@@ -1,4 +1,4 @@
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export interface RetryOptions {
   delay?: number;
@@ -9,29 +9,27 @@ export interface RetryOptions {
 export function Retry(maxAttempts: number, options: RetryOptions = {}) {
   const { delay = 0, backoff = 1, onRetry } = options;
 
-  return createMethodDecorator({
-    wrap(original, instance) {
-      return async (...args: unknown[]) => {
-        let lastError: Error = new Error("Unknown error");
-        let currentDelay = delay;
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    return sharedMethod(context, value, async function (this: unknown, ...args: unknown[]): Promise<unknown> {
+      let lastError: Error = new Error("Unknown error");
+      let currentDelay = delay;
 
-        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-          try {
-            return await (original.apply(instance, args) as Promise<unknown>);
-          } catch (e: unknown) {
-            lastError = e instanceof Error ? e : new Error(String(e));
-            if (attempt === maxAttempts) break;
-            onRetry?.(lastError, attempt);
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          return await (value.apply(this, args) as Promise<unknown>);
+        } catch (e: unknown) {
+          lastError = e instanceof Error ? e : new Error(String(e));
+          if (attempt === maxAttempts) break;
+          onRetry?.(lastError, attempt);
 
-            if (currentDelay > 0) {
-              await new Promise((res) => setTimeout(res, currentDelay));
-              currentDelay = Math.round(currentDelay * backoff);
-            }
+          if (currentDelay > 0) {
+            await new Promise((res) => setTimeout(res, currentDelay));
+            currentDelay = Math.round(currentDelay * backoff);
           }
         }
+      }
 
-        throw lastError;
-      };
-    },
-  });
+      throw lastError;
+    });
+  };
 }

package/src/functions/throttle.ts

@@ -1,16 +1,15 @@
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export function Throttle(ms: number) {
-  return createMethodDecorator({
-    wrap(original, instance) {
-      const clampedMs = Math.max(0, ms);
-      let last = 0;
-      return (...args: unknown[]) => {
-        const now = Date.now();
-        if (now - last < clampedMs) return;
-        last = now;
-        return original.apply(instance, args) as unknown;
-      };
-    },
-  });
+  const clampedMs = Math.max(0, ms);
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    const last = Symbol(`praxis.throttle.${String(context.name)}`);
+    type Host = Record<symbol, number | undefined>;
+    return sharedMethod(context, value, function (this: Host, ...args: unknown[]): unknown {
+      const now = Date.now();
+      if (now - (this[last] ?? 0) < clampedMs) return;
+      this[last] = now;
+      return value.apply(this, args);
+    });
+  };
 }

package/src/functions/until.ts

@@ -1,19 +1,19 @@
-import { until } from "@praxisjs/core/internal";
+import { computed, until } from "@praxisjs/core/internal";
 import type { Computed, Signal } from "@praxisjs/shared";
-import { isComputed } from "@praxisjs/shared/internal";
+import { isReactive } from "@praxisjs/shared/internal";
 
-import { createMethodDecorator } from "../create-method-decorator";
+import { type AnyMethod, type MethodContext, sharedMethod } from "../shared-method";
 
 export function Until(propName: string) {
-  return createMethodDecorator({
-    wrap(_original, instance) {
-      return () => {
-        const raw = (instance as Record<string, unknown>)[propName];
-        const source = isComputed(raw)
-          ? (raw as Computed<unknown>)
-          : (raw as Signal<unknown>);
-        return until(source);
-      };
-    },
-  });
+  return function (value: AnyMethod, context: MethodContext): AnyMethod {
+    return sharedMethod(context, value, function (this: Record<string, unknown>) {
+      const raw = this[propName];
+      // A @State/@Prop field reads as its plain value; reading it inside a computed tracks its signal.
+      const source =
+        isReactive(raw)
+          ? (raw as Signal<unknown> | Computed<unknown>)
+          : computed(() => this[propName]);
+      return until(source);
+    });
+  };
 }