@praxisjs/decorators 0.4.3 → 0.6.0

package/src/create-class-decorator.ts

@@ -0,0 +1,61 @@
+import type { RootComponent } from "@praxisjs/core/internal";
+
+export interface ClassEnhancement {
+  onMount?(): void;
+  onUnmount?(): void;
+  render?(
+    originalRender: () => Node | Node[] | null,
+  ): Node | Node[] | null;
+}
+
+export abstract class ClassBehavior {
+  abstract create(instance: RootComponent): ClassEnhancement;
+
+  /**
+   * Called once after the enhanced class is created.
+   * Use this to set static properties on the class constructor itself.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  initialize?(_Enhanced: new (...args: any[]) => unknown, _original: new (...args: any[]) => unknown): void;
+}
+
+export function createClassDecorator(behavior: ClassBehavior) {
+  return function <
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    T extends new (...args: any[]) => RootComponent<Record<string, any>>,
+  >(constructor: T, _context: ClassDecoratorContext): T {
+    const Enhanced = class extends constructor {
+      private readonly _enh: ClassEnhancement = behavior.create(
+        this as unknown as RootComponent,
+      );
+
+      onMount() {
+        super.onMount?.();
+        this._enh.onMount?.();
+      }
+
+      onUnmount() {
+        super.onUnmount?.();
+        this._enh.onUnmount?.();
+      }
+
+      render(...args: unknown[]): Node | Node[] | null {
+        const originalRender = () =>
+          (constructor.prototype as { render: (...a: unknown[]) => Node | Node[] | null }).render.apply(this, args);
+        if (this._enh.render) {
+          return this._enh.render(originalRender);
+        }
+        return originalRender();
+      }
+    };
+
+    // If the original class has no render, remove the wrapper so instances see `undefined`.
+    if (typeof (constructor.prototype as { render?: unknown }).render !== "function") {
+      delete (Enhanced.prototype as { render?: unknown }).render;
+    }
+
+    Object.defineProperty(Enhanced, "name", { value: constructor.name });
+    behavior.initialize?.(Enhanced, constructor);
+    return Enhanced as unknown as T;
+  };
+}

package/src/create-field-decorator.ts

@@ -0,0 +1,66 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface FieldBinding {
+  /** Replaces the decorated property. If absent, the original property is left untouched. */
+  descriptor?: PropertyDescriptor;
+  /** Extra properties to define on the instance (e.g. companion properties like `nameHistory`). */
+  additional?: Record<string, PropertyDescriptor>;
+  onMount?: () => void;
+  onUnmount?: () => void;
+}
+
+export interface FieldBehavior {
+  bind(
+    instance: StatefulComponent,
+    name: string,
+    initialValue: unknown,
+  ): FieldBinding;
+}
+
+export function createFieldDecorator(behavior: FieldBehavior) {
+  return function (
+    _value: undefined,
+    context: ClassFieldDecoratorContext<StatefulComponent>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      const instance = this as StatefulComponent & Record<string, unknown>;
+      const name = context.name as string;
+      const initialValue = instance[name];
+
+      const { descriptor, additional, onMount, onUnmount } = behavior.bind(
+        instance,
+        name,
+        initialValue,
+      );
+
+      if (descriptor) {
+        Reflect.deleteProperty(instance, name);
+        Object.defineProperty(instance, name, {
+          enumerable: true,
+          configurable: true,
+          ...descriptor,
+        });
+      }
+
+      for (const [key, desc] of Object.entries(additional ?? {})) {
+        Object.defineProperty(instance, key, {
+          configurable: true,
+          ...desc,
+        });
+      }
+
+      if (onMount ?? onUnmount) {
+        const prevMount = instance.onMount?.bind(instance);
+        const prevUnmount = instance.onUnmount?.bind(instance);
+        instance.onMount = () => {
+          prevMount?.();
+          onMount?.();
+        };
+        instance.onUnmount = () => {
+          prevUnmount?.();
+          onUnmount?.();
+        };
+      }
+    });
+  };
+}

package/src/create-getter-decorator.ts

@@ -0,0 +1,52 @@
+export interface GetterBehavior {
+  /**
+   * Given the original getter and the current instance, returns a function
+   * that produces the getter value. Called on every property access.
+   */
+  wrap(
+    original: (this: object) => unknown,
+    instance: object,
+  ): () => unknown;
+}
+
+export function createGetterDecorator(behavior: GetterBehavior) {
+  return function <This, T>(
+    target: (this: This) => T,
+    _context: ClassGetterDecoratorContext<This, T>,
+  ): (this: This) => T {
+    return function (this: This): T {
+      return behavior.wrap(
+        target as (this: object) => unknown,
+        this as object,
+      )() as T;
+    };
+  };
+}
+
+export interface GetterObserverBehavior {
+  /**
+   * Called once per instance when the class is initialized.
+   * Use this to set up observation side-effects on the getter without
+   * changing its return value (e.g. tracking changes for devtools).
+   */
+  observe(
+    getter: (this: object) => unknown,
+    instance: object,
+    name: string,
+  ): void;
+}
+
+export function createGetterObserverDecorator(behavior: GetterObserverBehavior) {
+  return function <This, T>(
+    target: (this: This) => T,
+    context: ClassGetterDecoratorContext<This, T>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      behavior.observe(
+        target as (this: object) => unknown,
+        this as object,
+        context.name as string,
+      );
+    });
+  };
+}

package/src/create-lifecycle-method-decorator.ts

@@ -0,0 +1,38 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface LifecycleMethodBehavior<
+  T extends StatefulComponent = StatefulComponent,
+> {
+  register(
+    callback: (...args: unknown[]) => void,
+    instance: T,
+  ): (() => void) | undefined;
+}
+
+export function createLifecycleMethodDecorator<
+  T extends StatefulComponent = StatefulComponent,
+>(behavior: LifecycleMethodBehavior<T>) {
+  return function (
+    value: (this: T, ...args: unknown[]) => void,
+    _context: ClassMethodDecoratorContext<T>,
+  ): void {
+    _context.addInitializer(function (this: unknown) {
+      const instance = this as T;
+      const prevMount = instance.onMount?.bind(instance);
+      const prevUnmount = instance.onUnmount?.bind(instance);
+      let cleanup: (() => void) | undefined;
+
+      instance.onMount = function (this: T) {
+        prevMount?.call(this);
+        const result = behavior.register(value.bind(this), this);
+        if (result) cleanup = result;
+      };
+
+      instance.onUnmount = function (this: T) {
+        prevUnmount?.call(this);
+        cleanup?.();
+        cleanup = undefined;
+      };
+    });
+  };
+}

package/src/create-method-decorator.ts

@@ -0,0 +1,26 @@
+import type { StatefulComponent } from "@praxisjs/core";
+
+export interface MethodBehavior {
+  wrap(
+    original: (...args: unknown[]) => unknown,
+    instance: object,
+    name: string,
+  ): (...args: unknown[]) => unknown;
+}
+
+export function createMethodDecorator(behavior: MethodBehavior) {
+  return function (
+    value: (this: object, ...args: unknown[]) => unknown,
+    context: ClassMethodDecoratorContext<StatefulComponent>,
+  ): void {
+    context.addInitializer(function (this: unknown) {
+      const instance = this as object;
+      const name = context.name as string;
+      Object.defineProperty(instance, name, {
+        value: behavior.wrap(value, instance, name),
+        configurable: true,
+        writable: true,
+      });
+    });
+  };
+}

package/src/events/emit.ts

@@ -1,42 +1,31 @@
 import type { StatefulComponent } from "@praxisjs/core";
 
+import { createMethodDecorator } from "../create-method-decorator";
 import { readProp } from "./helper";
 
 export function Emit(propName: string) {
-  return function (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    value: (this: StatefulComponent, ...args: any[]) => any,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    const wrapped = function (
-      this: StatefulComponent,
-      ...args: unknown[]
-    ): unknown {
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-      const result = value.apply(this, args);
+  return createMethodDecorator({
+    wrap(original, instance) {
+      const comp = instance as StatefulComponent;
+      return (...args: unknown[]) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any
+        const result = original.apply(instance, args) as any;
 
-      const callback = readProp(this, propName);
-      if (typeof callback !== "function") return result;
+        const callback = readProp(comp, propName);
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        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)();
+        }
 
-      return result;
-    };
-
-    context.addInitializer(function (this: unknown) {
-      const name = context.name as string;
-      const bound = wrapped.bind(this as StatefulComponent);
-      Object.defineProperty(this as object, name, {
-        value: bound,
-        configurable: true,
-        writable: true,
-      });
-    });
-  };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        return result;
+      };
+    },
+  });
 }

package/src/events/on-command.ts

@@ -1,54 +1,29 @@
-import type { StatefulComponent } from "@praxisjs/core";
 
+import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 import { readProp } from "./helper";
 
 import type { Command } from "./command";
 
 export function OnCommand(propName: string) {
-  return function (
-    value: (this: StatefulComponent, ...args: unknown[]) => void,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    const cleanups = new WeakMap<object, () => void>();
-
-    context.addInitializer(function (this: unknown) {
-      const instance = this as StatefulComponent;
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      const originalOnMount = instance.onMount;
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      const originalOnUnmount = instance.onUnmount;
-
-      instance.onMount = function (this: StatefulComponent) {
-        originalOnMount?.call(this);
-
-        const command = readProp(this, propName) as Command<unknown> | undefined;
-
-        if (!command) {
-          console.warn(
-            `[OnCommand] prop "${propName}" was not provided to ${this.constructor.name}`,
-          );
-          return;
-        }
-
-        if (typeof command.subscribe !== "function") {
-          console.warn(
-            `[OnCommand] prop "${propName}" is not a valid Command in ${this.constructor.name}`,
-          );
-          return;
-        }
-
-        const bound = value.bind(this);
-        const unsub = command.subscribe((...args: unknown[]) => {
-          bound(...args);
-        });
-        cleanups.set(this, unsub);
-      };
-
-      instance.onUnmount = function (this: StatefulComponent) {
-        originalOnUnmount?.call(this);
-        cleanups.get(this)?.();
-        cleanups.delete(this);
-      };
-    });
-  };
+  return createLifecycleMethodDecorator({
+    register(callback, instance) {
+      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 (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); });
+    },
+  });
 }

package/src/functions/bind.ts

@@ -1,18 +1,7 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { createMethodDecorator } from "../create-method-decorator";
 
 export function Bind() {
-  return function (
-    value: (this: object, ...args: unknown[]) => unknown,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const name = context.name as string;
-      const bound = value.bind(this as object);
-      Object.defineProperty(this as object, name, {
-        value: bound,
-        configurable: true,
-        writable: true,
-      });
-    });
-  };
+  return createMethodDecorator({
+    wrap: (original, instance) => original.bind(instance),
+  });
 }

package/src/functions/debounce.ts

@@ -1,31 +1,29 @@
 import type { StatefulComponent } from "@praxisjs/core";
 
+import { createMethodDecorator } from "../create-method-decorator";
+
 export function Debounce(ms: number) {
-  const timers = new WeakMap<object, ReturnType<typeof setTimeout>>();
+  return createMethodDecorator({
+    wrap(original, instance, _name) {
+      let timer: ReturnType<typeof setTimeout> | undefined;
 
-  return function (
-    value: (this: object, ...args: unknown[]) => unknown,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const instance = this as object;
-      const name = context.name as string;
-      const bound = (...args: unknown[]) => {
-        const existing = timers.get(instance);
-        if (existing !== undefined) clearTimeout(existing);
+      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;
+        }
+      };
 
-        const timer = setTimeout(() => {
-          timers.delete(instance);
-          value.apply(instance, args);
+      return (...args: unknown[]) => {
+        if (timer !== undefined) clearTimeout(timer);
+        timer = setTimeout(() => {
+          timer = undefined;
+          original.apply(instance, args);
         }, ms);
-
-        timers.set(instance, timer);
       };
-      Object.defineProperty(instance, name, {
-        value: bound,
-        configurable: true,
-        writable: true,
-      });
-    });
-  };
+    },
+  });
 }

package/src/functions/index.ts

@@ -6,4 +6,5 @@ export { Retry } from "./retry";
 export { Debounce } from "./debounce";
 export { Throttle } from "./throttle";
 export { When } from "./when";
+export { Until } from "./until";
 export { Watch, type WatchVal, type WatchVals } from "./watch";

package/src/functions/log.ts

@@ -1,4 +1,4 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { createMethodDecorator } from "../create-method-decorator";
 
 export interface LogOptions {
   level?: "log" | "warn" | "error" | "debug";
@@ -17,52 +17,49 @@ export function Log(options: LogOptions = {}) {
     devOnly = true,
   } = options;
 
-  return function (
-    value: (this: object, ...args: unknown[]) => unknown,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): (this: object, ...args: unknown[]) => unknown {
-    const methodKey = context.name as string;
+  return createMethodDecorator({
+    wrap(original, instance, name) {
+      return (...args: unknown[]) => {
+        if (
+          devOnly &&
+          typeof process !== "undefined" &&
+          process.env.NODE_ENV === "production"
+        ) {
+          return original.apply(instance, args);
+        }
 
-    return function (this: object, ...args: unknown[]) {
-      if (
-        devOnly &&
-        typeof process !== "undefined" &&
-        process.env.NODE_ENV === "production"
-      ) {
-        return value.apply(this, args);
-      }
+        const className =
+          (instance.constructor as { name?: string }).name ?? "Unknown";
+        const label = `[${className}.${name}]`;
+        const logger = console[level].bind(console);
 
-      const className =
-        (this.constructor as { name?: string }).name ?? "Unknown";
-      const label = `[${className}.${methodKey}]`;
-      const logger = console[level].bind(console);
+        if (logArgs) logger(`${label} args:`, args);
 
-      if (logArgs) logger(`${label} args:`, args);
+        const start = time ? performance.now() : 0;
+        const output = original.apply(instance, args);
 
-      const start = time ? performance.now() : 0;
-      const output = value.apply(this, args);
+        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;
+            });
+        }
 
-      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);
 
-      const elapsed = time
-        ? ` (${(performance.now() - start).toFixed(2)}ms)`
-        : "";
-      if (result) logger(`${label} returned:`, output, elapsed);
-
-      return output;
-    };
-  };
+        return output;
+      };
+    },
+  });
 }

package/src/functions/memo.ts

@@ -1,44 +1,29 @@
-import type { StatefulComponent } from "@praxisjs/core";
 import { computed } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 
-const instanceCache = new WeakMap<
-  object,
-  Map<string, Map<string, Computed<unknown>>>
->();
+import { createMethodDecorator } from "../create-method-decorator";
 
-function getCache(
-  instance: object,
-  methodName: string,
-  argKey: string,
-  factory: () => unknown,
-): Computed<unknown> {
-  let methodMap = instanceCache.get(instance);
-  if (!methodMap) {
-    methodMap = new Map();
-    instanceCache.set(instance, methodMap);
-  }
-
-  let argMap = methodMap.get(methodName);
-  if (!argMap) {
-    argMap = new Map();
-    methodMap.set(methodName, argMap);
-  }
+const objectIdMap = new WeakMap<object, number>();
+let objectIdCounter = 0;
 
-  let cached = argMap.get(argKey);
-  if (!cached) {
-    cached = computed(factory);
-    argMap.set(argKey, cached);
+function objectIdentityKey(obj: object): string {
+  if (!objectIdMap.has(obj)) {
+    objectIdMap.set(obj, ++objectIdCounter);
   }
-
-  return cached;
+  return `__obj_${String(objectIdMap.get(obj))}__`;
 }
 
 function serializeArgs(args: unknown[]) {
   if (args.length === 0) return "__no_args__";
   return args
     .map((a) => {
-      if (a === null || typeof a === "object") return JSON.stringify(a);
+      if (a === null || typeof a === "object") {
+        try {
+          return JSON.stringify(a);
+        } catch {
+          return a === null ? "null" : objectIdentityKey(a);
+        }
+      }
       if (typeof a === "symbol") return a.toString();
       return String(a as string | number | boolean | bigint | undefined);
     })
@@ -46,17 +31,18 @@ function serializeArgs(args: unknown[]) {
 }
 
 export function Memo() {
-  return function (
-    value: (this: object, ...args: unknown[]) => unknown,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): (this: object, ...args: unknown[]) => unknown {
-    const methodName = context.name as string;
-    return function (this: object, ...args: unknown[]) {
-      const argKey = serializeArgs(args);
-      const memoized = getCache(this, methodName, argKey, () =>
-        value.apply(this, args),
-      );
-      return memoized();
-    };
-  };
+  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) {
+          memoized = computed(() => original.apply(instance, args));
+          cache.set(key, memoized);
+        }
+        return memoized();
+      };
+    },
+  });
 }