@praxisjs/decorators 0.4.3 → 0.5.0

package/src/functions/throttle.ts

@@ -1,29 +1,15 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { createMethodDecorator } from "../create-method-decorator";
 
 export function Throttle(ms: number) {
-  const lastRun = new WeakMap<object, number>();
-
-  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[]) => {
+  return createMethodDecorator({
+    wrap(original, instance) {
+      let last = 0;
+      return (...args: unknown[]) => {
         const now = Date.now();
-        const last = lastRun.get(instance) ?? 0;
-
         if (now - last < ms) return;
-
-        lastRun.set(instance, now);
-        return value.apply(instance, args);
+        last = now;
+        return original.apply(instance, args);
       };
-      Object.defineProperty(instance, name, {
-        value: bound,
-        configurable: true,
-        writable: true,
-      });
-    });
-  };
+    },
+  });
 }

package/src/functions/watch.ts

@@ -3,6 +3,8 @@ import { effect } from "@praxisjs/core/internal";
 import type { Computed } from "@praxisjs/shared";
 import { isComputed } from "@praxisjs/shared/internal";
 
+import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
+
 type BaseComponentKeys = keyof StatefulComponent;
 
 type WatchableKeys<T> = {
@@ -54,51 +56,33 @@ export function Watch<
   T extends StatefulComponent,
   const Keys extends ReadonlyArray<WatchableKeys<T>>,
 >(...propNames: ValidateKeys<T, Keys>) {
-  return function (
-    value: (this: T, ...args: unknown[]) => void,
-    context: ClassMethodDecoratorContext<T>,
-  ): void {
-    const props = propNames as unknown as string[];
+  const props = propNames as unknown as string[];
 
-    context.addInitializer(function (this: unknown) {
-      const instance = this as T & Record<string, unknown>;
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      const originalOnMount = instance.onMount;
-      // eslint-disable-next-line @typescript-eslint/unbound-method
-      const originalOnUnmount = instance.onUnmount;
-      let stopEffect: (() => void) | undefined;
+  return createLifecycleMethodDecorator<T>({
+    register(callback, instance) {
+      const inst = instance as T & Record<string, unknown>;
 
-      instance.onMount = function (this: T & Record<string, unknown>) {
-        originalOnMount?.call(this);
+      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;
+          }
+        });
+      }
 
-        if (props.length === 1) {
-          let oldVal = readValue(this, props[0]);
-          stopEffect = effect(() => {
-            const newVal = readValue(this, props[0]);
-            if (!Object.is(newVal, oldVal)) {
-              value.call(this as T, newVal, oldVal);
-              oldVal = newVal;
-            }
-          });
-        } else {
-          const read = () =>
-            Object.fromEntries(props.map((p) => [p, readValue(this, p)]));
-          let oldVals = read();
-          stopEffect = effect(() => {
-            const newVals = read();
-            if (props.some((p) => !Object.is(newVals[p], oldVals[p]))) {
-              value.call(this as T, newVals, oldVals);
-              oldVals = newVals;
-            }
-          });
+      const read = () =>
+        Object.fromEntries(props.map((p) => [p, readValue(inst, p)]));
+      let oldVals = read();
+      return effect(() => {
+        const newVals = read();
+        if (props.some((p) => !Object.is(newVals[p], oldVals[p]))) {
+          callback(newVals, oldVals);
+          oldVals = newVals;
         }
-      };
-
-      instance.onUnmount = function (this: T) {
-        originalOnUnmount?.call(this);
-        stopEffect?.();
-        stopEffect = undefined;
-      };
-    });
-  };
+      });
+    },
+  });
 }

package/src/functions/when.ts

@@ -1,42 +1,17 @@
-import type { StatefulComponent } from "@praxisjs/core";
 import { when } from "@praxisjs/core/internal";
 import type { Computed, Signal } from "@praxisjs/shared";
 import { isComputed } from "@praxisjs/shared/internal";
 
-export function When(propName: string) {
-  return function (
-    value: (this: StatefulComponent, val: unknown) => void,
-    context: ClassMethodDecoratorContext<StatefulComponent>,
-  ): void {
-    const cancels = 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 raw = (this as unknown as Record<string, unknown>)[propName];
-        const source = isComputed(raw)
-          ? (raw as Computed<unknown>)
-          : (raw as Signal<unknown>);
+import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 
-        const cancel = when(source, (val) => {
-          value.call(this, val);
-        });
-
-        cancels.set(this, cancel);
-      };
-
-      instance.onUnmount = function (this: StatefulComponent) {
-        originalOnUnmount?.call(this);
-        cancels.get(this)?.();
-        cancels.delete(this);
-      };
-    });
-  };
+export function When(propName: string) {
+  return createLifecycleMethodDecorator({
+    register(callback, instance) {
+      const raw = (instance as unknown as Record<string, unknown>)[propName];
+      const source = isComputed(raw)
+        ? (raw as Computed<unknown>)
+        : (raw as Signal<unknown>);
+      return when(source, (val) => { callback(val); });
+    },
+  });
 }

package/src/index.ts

@@ -21,5 +21,33 @@ export {
   initSlots,
   History,
   type WithHistory,
+  Compose,
+  Resource,
+  type ResourceInstance,
+  type ResourceOptions,
 } from "./properties";
 export { type Command, createCommand, Emit, OnCommand } from "./events";
+export {
+  createFieldDecorator,
+  type FieldBehavior,
+  type FieldBinding,
+} from "./create-field-decorator";
+export {
+  createClassDecorator,
+  ClassBehavior,
+  type ClassEnhancement,
+} from "./create-class-decorator";
+export {
+  createMethodDecorator,
+  type MethodBehavior,
+} from "./create-method-decorator";
+export {
+  createLifecycleMethodDecorator,
+  type LifecycleMethodBehavior,
+} from "./create-lifecycle-method-decorator";
+export {
+  createGetterDecorator,
+  type GetterBehavior,
+  createGetterObserverDecorator,
+  type GetterObserverBehavior,
+} from "./create-getter-decorator";

package/src/properties/compose.ts

@@ -0,0 +1,53 @@
+import type { StatefulComponent, Composable } from "@praxisjs/core";
+
+import { createFieldDecorator } from "../create-field-decorator";
+
+function isReactive(
+  value: unknown,
+): value is () => unknown {
+  return (
+    typeof value === "function" &&
+    ("__isSignal" in (value as object) || "__isComputed" in (value as object))
+  );
+}
+
+function buildView(bindings: Record<string, unknown>): object {
+  const view: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(bindings)) {
+    if (isReactive(value)) {
+      Object.defineProperty(view, key, {
+        get: () => (value as () => unknown)(),
+        enumerable: true,
+        configurable: true,
+      });
+    } else {
+      view[key] = value;
+    }
+  }
+  return view;
+}
+
+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) =>
+        typeof arg === "string"
+          ? (instance as unknown as Record<string, unknown>)[arg]
+          : arg,
+      );
+
+      const composable = new ComposableClass(...resolvedArgs);
+      const view = buildView(composable.setup());
+
+      return {
+        descriptor: { get: () => view },
+        onMount: composable.onMount?.bind(composable),
+        onUnmount: composable.onUnmount?.bind(composable),
+      };
+    },
+  });
+}

package/src/properties/computed.ts

@@ -1,20 +1,18 @@
-import type { StatefulComponent } from "@praxisjs/core";
 import { computed } from "@praxisjs/core/internal";
 
+import { createGetterDecorator } from "../create-getter-decorator";
+
 export function Computed() {
-  return function <This extends StatefulComponent, T>(
-    target: (this: This) => T,
-    _context: ClassGetterDecoratorContext<This, T>,
-  ): (this: This) => T {
-    const computedMap = new WeakMap<object, () => T>();
+  const cache = new WeakMap<object, () => unknown>();
 
-    return function (this: This): T {
-      let c = computedMap.get(this);
+  return createGetterDecorator({
+    wrap(original, instance) {
+      let c = cache.get(instance);
       if (!c) {
-        c = computed(() => target.call(this));
-        computedMap.set(this, c);
+        c = computed(() => original.call(instance));
+        cache.set(instance, c);
       }
-      return c();
-    };
-  };
+      return c;
+    },
+  });
 }

package/src/properties/history.ts

@@ -2,52 +2,53 @@ 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";
+
 export type WithHistory<T, K extends keyof T> = Record<
   `${string & K}History`,
   HistoryElement<T[K]>
 >;
 
 export function History(limit = 50) {
-  return function (
-    _value: undefined,
-    context: ClassFieldDecoratorContext<StatefulComponent>,
-  ): void {
-    const histories = new WeakMap<object, HistoryElement<unknown>>();
-
-    context.addInitializer(function (this: unknown) {
-      const instance = this as Record<string, unknown>;
-      const propertyKey = context.name as string;
-      const historyKey = `${propertyKey}History`;
-
-      Object.defineProperty(instance, historyKey, {
-        get(this: Record<string, unknown>): HistoryElement<unknown> {
-          if (!histories.has(this)) {
-            const source = () => this[propertyKey];
-
-            const h = history(source 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();
-              this[propertyKey] = prev;
-            };
-
-            h.redo = () => {
-              _redo();
-              this[propertyKey] = h.current();
-            };
-
-            histories.set(this, h);
-          }
-          return histories.get(this) as HistoryElement<unknown>;
+  return createFieldDecorator({
+    bind(instance: StatefulComponent, name: string, _initialValue: unknown) {
+      const historyKey = `${name}History`;
+      const inst = instance as unknown as Record<string, unknown>;
+      let h: HistoryElement<unknown> | undefined;
+
+      return {
+        // descriptor omitted — @History does not replace the original field
+        additional: {
+          [historyKey]: {
+            get(): HistoryElement<unknown> {
+              if (!h) {
+                const source = () => inst[name];
+                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[name] = prev;
+                };
+
+                hInst.redo = () => {
+                  _redo();
+                  inst[name] = hInst.current();
+                };
+
+                h = hInst;
+              }
+              return h;
+            },
+            enumerable: false,
+            configurable: true,
+          },
         },
-        enumerable: false,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  });
 }

package/src/properties/index.ts

@@ -4,3 +4,5 @@ export { Computed } from "./computed";
 export { Persisted } from "./persisted";
 export { Slot, initSlots } from "./slot";
 export { History, type WithHistory } from "./history";
+export { Compose } from "./compose";
+export { Resource, type ResourceInstance, type ResourceOptions } from "./resource";

package/src/properties/persisted.ts

@@ -1,19 +1,9 @@
-import type { StatefulComponent } from "@praxisjs/core";
-import {
-  persistedSignal,
-  type PersistedSignalOptions,
-} from "@praxisjs/core/internal";
+import { persistedSignal, type PersistedSignalOptions } from "@praxisjs/core/internal";
 import type { Signal } from "@praxisjs/shared";
 
-const signalMap = new WeakMap<object, Map<string, Signal<unknown>>>();
-const initMap = new WeakMap<object, Set<string>>();
+import { createFieldDecorator } from "../create-field-decorator";
 
-function markInitialized(instance: object, propKey: string): void {
-  if (!initMap.has(instance)) {
-    initMap.set(instance, new Set());
-  }
-  (initMap.get(instance) as Set<string>).add(propKey);
-}
+const signalMap = new WeakMap<object, Map<string, Signal<unknown>>>();
 
 function getOrCreateSignal<T>(
   instance: object,
@@ -21,18 +11,14 @@ function getOrCreateSignal<T>(
   initialValue: T,
   options: PersistedSignalOptions<T>,
 ): Signal<T> {
-  if (!signalMap.has(instance)) {
-    signalMap.set(instance, new Map());
-  }
+  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>,
     );
   }
-
   return map.get(storageKey) as Signal<T>;
 }
 
@@ -40,45 +26,18 @@ export function Persisted<T>(
   key?: string,
   options: PersistedSignalOptions<T> = {},
 ) {
-  return function (
-    _value: undefined,
-    context: ClassFieldDecoratorContext<StatefulComponent>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const instance = this as object;
-      const propertyKey = context.name as string;
-      const storageKey = key ?? propertyKey;
-      const initialValue = (instance as Record<string, unknown>)[
-        propertyKey
-      ] as T;
-
-      Reflect.deleteProperty(instance, propertyKey);
-
-      markInitialized(instance, propertyKey);
-      getOrCreateSignal(instance, storageKey, initialValue, options);
-
-      Object.defineProperty(instance, propertyKey, {
-        get(): T {
-          return getOrCreateSignal<T>(
-            instance,
-            storageKey,
-            undefined as T,
-            options,
-          )();
+  return createFieldDecorator({
+    bind(instance, name, initialValue) {
+      const storageKey = key ?? name;
+      getOrCreateSignal(instance, storageKey, initialValue as T, options);
+      return {
+        descriptor: {
+          get: () =>
+            getOrCreateSignal<T>(instance, storageKey, undefined as T, options)(),
+          set: (value: T) =>
+            { getOrCreateSignal<T>(instance, storageKey, undefined as T, options).set(value); },
         },
-
-        set(value: T): void {
-          getOrCreateSignal<T>(
-            instance,
-            storageKey,
-            undefined as T,
-            options,
-          ).set(value);
-        },
-
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  });
 }

package/src/properties/prop.ts

@@ -1,35 +1,25 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { createFieldDecorator } from "../create-field-decorator";
 
 export function Prop() {
-  return function (
-    _value: undefined,
-    context: ClassFieldDecoratorContext<StatefulComponent>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const instance = this as StatefulComponent;
-      const name = context.name as string;
-      const raw = instance as unknown as Record<string, unknown>;
-      const defaultValue = raw[name];
-      Reflect.deleteProperty(raw, name);
-
-      instance._defaults[name] = defaultValue;
-
-      Object.defineProperty(instance, name, {
-        get(this: StatefulComponent) {
-          const fromParent = this._rawProps[name];
-          if (fromParent !== undefined) {
-            return typeof fromParent === "function"
-              ? (fromParent as () => unknown)()
-              : fromParent;
-          }
-          return this._defaults[name];
-        },
-        set(this: StatefulComponent, value: unknown) {
-          this._defaults[name] = value;
+  return createFieldDecorator({
+    bind(instance, name, initialValue) {
+      instance._defaults[name] = initialValue;
+      return {
+        descriptor: {
+          get() {
+            const fromParent = (instance._rawProps)[name];
+            if (fromParent !== undefined) {
+              return typeof fromParent === "function"
+                ? (fromParent as () => unknown)()
+                : fromParent;
+            }
+            return instance._defaults[name];
+          },
+          set(value: unknown) {
+            instance._defaults[name] = value;
+          },
         },
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  });
 }

package/src/properties/resource.ts

@@ -0,0 +1,34 @@
+import {
+  resource,
+  type Resource as ResourceInstance,
+  type ResourceOptions,
+} from "@praxisjs/core/internal";
+
+import { createFieldDecorator, type FieldBinding } from "../create-field-decorator";
+
+export type { ResourceInstance, ResourceOptions };
+
+/**
+ * Binds an async resource to the field. The field holds a Resource<T> object
+ * with reactive data, pending, error, and status signals, plus refetch/cancel/mutate methods.
+ *
+ * class MyComponent extends StatefulComponent {
+ *   @Resource(() => api.getUsers())
+ *   users!: ResourceInstance<User[]>;
+ *   // access: this.users.data(), this.users.pending(), this.users.refetch()
+ * }
+ */
+export function Resource<T>(fetcher: () => Promise<T>, options: ResourceOptions<T> = {}) {
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue): FieldBinding {
+      const r = resource(fetcher, options);
+      return {
+        descriptor: {
+          get(): ResourceInstance<T> { return r; },
+          // eslint-disable-next-line @typescript-eslint/no-empty-function
+          set(): void {},
+        },
+      };
+    },
+  });
+}

package/src/properties/slot.ts

@@ -1,4 +1,4 @@
-import type { StatefulComponent } from "@praxisjs/core";
+import { createFieldDecorator } from "../create-field-decorator";
 
 const slotsMap = new WeakMap<object, Map<string, unknown[]>>();
 
@@ -14,7 +14,6 @@ function resolveSlots(children: unknown): Map<string, unknown[]> {
     : [children];
 
   for (const child of arr) {
-    // Named slots via `slot` attribute on DOM elements
     if (child instanceof Element) {
       const slotName = child.getAttribute("slot");
       if (slotName) {
@@ -39,33 +38,21 @@ export function getSlot(instance: object, name: string): unknown[] {
 }
 
 export function Slot(name?: string) {
-  return function (
-    _value: undefined,
-    context: ClassFieldDecoratorContext<StatefulComponent>,
-  ): void {
-    context.addInitializer(function (this: unknown) {
-      const instance = this as StatefulComponent;
-      const propKey = context.name as string;
-      const slotName = name ?? (propKey === "default" ? "default" : propKey);
-
-      Reflect.deleteProperty(instance, propKey);
-
-      Object.defineProperty(instance, propKey, {
-        get(this: StatefulComponent): unknown[] {
-          return getSlot(this, slotName);
+  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.`,
+              );
+            }
+          },
         },
-
-        set(_value: unknown): void {
-          if (process.env.NODE_ENV !== "production") {
-            console.warn(
-              `[Slot] "${propKey}" is a slot and cannot be assigned directly. Slots are filled by the parent component.`,
-            );
-          }
-        },
-
-        enumerable: true,
-        configurable: true,
-      });
-    });
-  };
+      };
+    },
+  });
 }