@praxisjs/decorators 1.1.1 → 1.3.0

package/src/__tests__/properties.test.ts

@@ -4,6 +4,8 @@ import { StatefulComponent } from "@praxisjs/core";
 import { signal, computed } from "@praxisjs/core/internal";
 
 import { createFieldDecorator } from "../create-field-decorator";
+import { createGetterDecorator } from "../create-getter-decorator";
+import { createAccessorDecorator } from "../create-accessor-decorator";
 import { Watch } from "../functions/watch";
 import { When } from "../functions/when";
 import { Compose } from "../properties/compose";
@@ -152,39 +154,243 @@ describe("Prop decorator", () => {
 
 describe("Computed decorator", () => {
   it("wraps a getter in a computed — result is memoized", () => {
-    const fn = vi.fn(function (this: { base: number }) {
-      return this.base * 2;
-    });
+    const s = signal(5);
+    const fn = vi.fn(function (this: object) { return s() * 2; });
 
-    const wrappedGetter = Computed()(fn, {} as ClassGetterDecoratorContext);
-    const instance = { base: 5 } as unknown as StatefulComponent;
+    const { ctx, run } = getterCtx("doubled");
+    Computed()(fn, ctx);
+    const instance = {} as unknown as StatefulComponent;
+    run(instance);
 
-    const result1 = wrappedGetter.call(instance);
-    const result2 = wrappedGetter.call(instance);
+    const result1 = (instance as unknown as Record<string, unknown>).doubled;
+    const result2 = (instance as unknown as Record<string, unknown>).doubled;
     expect(result1).toBe(10);
     expect(result2).toBe(10);
-    expect(fn).toHaveBeenCalledTimes(1); // lazy caching
+    expect(fn).toHaveBeenCalledTimes(1);
   });
 
   it("recomputes when underlying signal changes", () => {
     const s = signal(3);
     const getter = function (this: object) { return s() * 2; };
-    const wrapped = Computed()(getter, {} as ClassGetterDecoratorContext);
+    const { ctx, run } = getterCtx("val");
+    Computed()(getter, ctx);
     const obj = {} as unknown as StatefulComponent;
-    expect(wrapped.call(obj)).toBe(6);
+    run(obj);
+
+    expect((obj as unknown as Record<string, unknown>).val).toBe(6);
     s.set(5);
-    expect(wrapped.call(obj)).toBe(10);
+    expect((obj as unknown as Record<string, unknown>).val).toBe(10);
   });
 
   it("is per-instance — separate computed per object", () => {
     const s = signal(1);
     const getter = function (this: object) { return s(); };
-    const wrapped = Computed()(getter, {} as ClassGetterDecoratorContext);
+    const { ctx, run } = getterCtx("val");
+    Computed()(getter, ctx);
     const a = {} as unknown as StatefulComponent;
     const b = {} as unknown as StatefulComponent;
-    expect(wrapped.call(a)).toBe(1);
-    expect(wrapped.call(b)).toBe(1);
-    // Both share the same signal but have independent computed instances
+    run(a);
+    run(b);
+
+    expect((a as unknown as Record<string, unknown>).val).toBe(1);
+    expect((b as unknown as Record<string, unknown>).val).toBe(1);
+  });
+});
+
+// ── Computed (writable) ───────────────────────────────────────────────────────
+
+function getterCtx(name: string) {
+  const initializers: Array<(this: unknown) => void> = [];
+  return {
+    ctx: {
+      name,
+      kind: "getter" as const,
+      addInitializer(fn: (this: unknown) => void) {
+        initializers.push(fn);
+      },
+    } as unknown as ClassGetterDecoratorContext,
+    run(instance: unknown) {
+      initializers.forEach((fn) => { fn.call(instance); });
+    },
+  };
+}
+
+describe("Computed decorator — writable (set option)", () => {
+  it("setter is called when property is assigned", () => {
+    const written: number[] = [];
+    const { ctx, run } = getterCtx("double");
+
+    const s = signal(3);
+    const getter = function (this: object) { return s() * 2; };
+    Computed({ set: (v: unknown) => { written.push(v as number); } })(getter, ctx);
+
+    const instance = {} as unknown as StatefulComponent;
+    run(instance);
+
+    (instance as unknown as Record<string, unknown>).double = 42;
+    expect(written).toEqual([42]);
+  });
+
+  it("setter receives the component instance as this", () => {
+    let capturedThis: unknown;
+    const { ctx, run } = getterCtx("val");
+
+    const getter = function (this: object) { return 0; };
+    Computed({ set(this: unknown, _v: unknown) { capturedThis = this; } })(getter, ctx);
+
+    const instance = { id: "target" } as unknown as StatefulComponent;
+    run(instance);
+
+    (instance as unknown as Record<string, unknown>).val = 99;
+    expect(capturedThis).toBe(instance);
+  });
+
+  it("getter still returns the computed value after set option is added", () => {
+    const s = signal(5);
+    const { ctx, run } = getterCtx("doubled");
+
+    const getter = function (this: object) { return s() * 2; };
+    Computed({ set: (_v: unknown) => { /* no-op */ } })(getter, ctx);
+
+    const instance = {} as unknown as StatefulComponent;
+    run(instance);
+
+    expect((instance as unknown as Record<string, unknown>).doubled).toBe(10);
+    s.set(7);
+    expect((instance as unknown as Record<string, unknown>).doubled).toBe(14);
+  });
+
+  it("setter writes through to underlying signals, updating the getter", () => {
+    const s = signal(0);
+    const { ctx, run } = getterCtx("celsius");
+
+    const getter = function (this: object) { return s(); };
+    Computed({ set: (v: unknown) => { s.set(v as number); } })(getter, ctx);
+
+    const instance = {} as unknown as StatefulComponent;
+    run(instance);
+
+    (instance as unknown as Record<string, unknown>).celsius = 100;
+    expect((instance as unknown as Record<string, unknown>).celsius).toBe(100);
+  });
+});
+
+// ── Computed (accessor form) ──────────────────────────────────────────────────
+
+describe("Computed decorator — accessor form ({ get, set })", () => {
+  function applyAccessorDecorator<T>(
+    options: { get: (this: object) => T; set: (this: object, value: T) => void },
+    instance: object,
+  ): { get: () => T; set: (v: T) => void } {
+    const target = {
+      get(this: object) { return undefined as T; },
+      set(_v: T) { /* original */ },
+    };
+    const ctx = { kind: "accessor", name: "value" } as unknown as ClassAccessorDecoratorContext<object, T>;
+    const result = Computed(options)(target, ctx);
+    result.init!.call(instance, undefined as unknown as T);
+    return {
+      get: () => result.get!.call(instance),
+      set: (v: T) => result.set!.call(instance, v),
+    };
+  }
+
+  it("get function is wrapped in a computed — result is memoized", () => {
+    const s = signal(3);
+    const getFn = vi.fn(function (this: object) { return s() * 2; });
+    const instance = {};
+    const { get } = applyAccessorDecorator({ get: getFn, set: () => { /* no-op */ } }, instance);
+
+    expect(get()).toBe(6);
+    expect(get()).toBe(6);
+    expect(getFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("recomputes when underlying signal changes", () => {
+    const s = signal(10);
+    const instance = {};
+    const { get } = applyAccessorDecorator({
+      get(this: object) { return s() + 1; },
+      set() { /* no-op */ },
+    }, instance);
+
+    expect(get()).toBe(11);
+    s.set(20);
+    expect(get()).toBe(21);
+  });
+
+  it("set function is called when the setter is invoked", () => {
+    const written: number[] = [];
+    const instance = {};
+    const { set } = applyAccessorDecorator({
+      get(this: object) { return 0; },
+      set(_v: number) { written.push(_v); },
+    }, instance);
+
+    set(42);
+    expect(written).toEqual([42]);
+  });
+
+  it("set function receives the component instance as this", () => {
+    let capturedThis: unknown;
+    const instance = { id: "target" };
+    const { set } = applyAccessorDecorator({
+      get(this: object) { return 0; },
+      set(this: unknown) { capturedThis = this; },
+    }, instance);
+
+    set(1);
+    expect(capturedThis).toBe(instance);
+  });
+
+  it("set writes through to underlying signals, updating the getter", () => {
+    const s = signal(0);
+    const instance = {};
+    const { get, set } = applyAccessorDecorator({
+      get(this: object) { return s(); },
+      set(this: object, v: number) { s.set(v); },
+    }, instance);
+
+    set(100);
+    expect(get()).toBe(100);
+  });
+
+  it("is per-instance — separate computed per object", () => {
+    const s = signal(5);
+    const options = {
+      get(this: object) { return s() * 2; },
+      set() { /* no-op */ },
+    };
+    const a = {};
+    const b = {};
+    const decA = applyAccessorDecorator(options, a);
+    const decB = applyAccessorDecorator(options, b);
+
+    expect(decA.get()).toBe(10);
+    expect(decB.get()).toBe(10);
+    s.set(7);
+    expect(decA.get()).toBe(14);
+    expect(decB.get()).toBe(14);
+  });
+
+  it("accessor form without set — setter is a no-op", () => {
+    const s = signal(5);
+    const instance = {};
+    const target = { get() { return undefined as unknown as number; }, set() { /* original */ } };
+    const ctx = { kind: "accessor", name: "value" } as unknown as ClassAccessorDecoratorContext<object, number>;
+    // Bypass overload constraint — optionsSet is undefined at runtime
+    type AccessorDecoFactory = (opts: { get: (this: object) => number }) => (
+      t: typeof target,
+      c: typeof ctx,
+    ) => ClassAccessorDecoratorResult<object, number>;
+    const result = (Computed as unknown as AccessorDecoFactory)(
+      { get(this: object) { return s() * 2; } },
+    )(target, ctx);
+    result.init!.call(instance, 0);
+
+    expect(result.get!.call(instance)).toBe(10);
+    expect(() => { result.set!.call(instance, 99); }).not.toThrow();
+    expect(result.get!.call(instance)).toBe(10); // unchanged — no setter
   });
 });
 
@@ -549,6 +755,78 @@ describe("When decorator", () => {
     await Promise.resolve();
     expect(handler).toHaveBeenCalledTimes(1);
   });
+
+  it("fires immediately when the watched prop is a plain truthy value (non-signal)", () => {
+    const { ctx, run } = methodCtxFor("onPlain");
+    const handler = vi.fn();
+    When("plainProp")(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).plainProp = "hello";
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith("hello");
+  });
+
+  it("condition: fires when condition returns true", async () => {
+    const { ctx, run } = methodCtxFor("onHigh");
+    const handler = vi.fn();
+    When("count", (v: number) => v > 5)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).count = s;
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(3);   // condition false — should not fire
+    await Promise.resolve();
+    expect(handler).not.toHaveBeenCalled();
+
+    s.set(7);   // condition true — should fire
+    await Promise.resolve();
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(7);
+  });
+
+  it("condition: does not fire when value is truthy but condition returns false", async () => {
+    const { ctx, run } = methodCtxFor("onPositive");
+    const handler = vi.fn();
+    When("n", (v: number) => v > 100)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).n = s;
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(1);   // truthy but condition fails
+    s.set(50);  // truthy but condition fails
+    await Promise.resolve();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("condition: fires on the first value satisfying the condition, then stops", async () => {
+    const { ctx, run } = methodCtxFor("onFirst");
+    const handler = vi.fn();
+    When("v", (v: number) => v >= 10)(handler, ctx as unknown as ClassMethodDecoratorContext);
+
+    const s = signal(0);
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).v = s;
+    run(instance);
+    (instance as unknown as { onMount: () => void }).onMount?.();
+
+    s.set(10);  // first match — fires
+    await Promise.resolve();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    s.set(20);  // when() already disposed — should not fire again
+    await Promise.resolve();
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
 });
 
 // ── Prop (additional branches) ────────────────────────────────────────────────
@@ -1085,3 +1363,83 @@ describe("createFieldDecorator — additional property", () => {
     expect((instance as unknown as Record<string, unknown>).extraProp).toBe("extra");
   });
 });
+
+// ── createGetterDecorator ─────────────────────────────────────────────────────
+
+describe("createGetterDecorator", () => {
+  it("calls behavior.wrap on access and returns the wrapped value", () => {
+    const wrap = vi.fn((original: (this: object) => unknown, instance: object) => {
+      return () => (original.call(instance) as number) * 2;
+    });
+    const decorator = createGetterDecorator({ wrap });
+    const originalGetter = function (this: object) { return 5 as unknown; };
+    const ctx = { kind: "getter" } as ClassGetterDecoratorContext<object, number>;
+    const wrapped = decorator(originalGetter as (this: object) => number, ctx);
+
+    const instance = {};
+    expect(wrapped.call(instance)).toBe(10);
+    expect(wrap).toHaveBeenCalledWith(originalGetter, instance);
+  });
+
+  it("passes the correct instance as this to behavior.wrap", () => {
+    let capturedInstance: unknown;
+    const decorator = createGetterDecorator({
+      wrap(_original, instance) {
+        capturedInstance = instance;
+        return () => 0;
+      },
+    });
+    const getter = function (this: object) { return 0 as unknown; };
+    const ctx = { kind: "getter" } as ClassGetterDecoratorContext<object, number>;
+    const wrapped = decorator(getter as (this: object) => number, ctx);
+
+    const instance = { id: "test-instance" };
+    wrapped.call(instance);
+    expect(capturedInstance).toBe(instance);
+  });
+});
+
+// ── createAccessorDecorator — init ────────────────────────────────────────────
+
+describe("createAccessorDecorator — init", () => {
+  it("init stores the initial value that bind receives on first get", () => {
+    let capturedInitialValue: unknown = "NOT_SET";
+    const behavior = {
+      bind(_inst: object, _name: string | symbol, initialValue: unknown) {
+        capturedInitialValue = initialValue;
+        return { get: () => initialValue };
+      },
+    };
+    const decorator = createAccessorDecorator(behavior);
+    const target = {
+      get() { return 0; },
+      set() { /* original */ },
+    } as ClassAccessorDecoratorTarget<object, number>;
+    const ctx = { kind: "accessor", name: "val" } as unknown as ClassAccessorDecoratorContext<object, number>;
+    const result = decorator(target, ctx);
+
+    const instance = {};
+    const returned = result.init!.call(instance, 42);
+    result.get!.call(instance); // triggers bind
+    expect(returned).toBe(42);
+    expect(capturedInitialValue).toBe(42);
+  });
+
+  it("init returns the initial value unchanged", () => {
+    const behavior = {
+      bind(_inst: object, _name: string | symbol, initialValue: unknown) {
+        return { get: () => initialValue };
+      },
+    };
+    const decorator = createAccessorDecorator(behavior);
+    const target = {
+      get() { return ""; },
+      set() { /* original */ },
+    } as ClassAccessorDecoratorTarget<object, string>;
+    const ctx = { kind: "accessor", name: "s" } as unknown as ClassAccessorDecoratorContext<object, string>;
+    const result = decorator(target, ctx);
+
+    const instance = {};
+    expect(result.init!.call(instance, "hello")).toBe("hello");
+  });
+});

package/src/create-accessor-decorator.ts

@@ -0,0 +1,45 @@
+export interface AccessorBinding {
+  get: () => unknown;
+  set?: (value: unknown) => void;
+}
+
+export interface AccessorBehavior {
+  /**
+   * Called once per instance on first access. `initialValue` is the value
+   * provided by the `accessor` field initializer (e.g. `accessor count = 0`).
+   * Returns the get/set pair used by the accessor.
+   */
+  bind(instance: object, name: string | symbol, initialValue: unknown): AccessorBinding;
+}
+
+export function createAccessorDecorator(behavior: AccessorBehavior) {
+  return function <This extends object, V>(
+    _target: ClassAccessorDecoratorTarget<This, V>,
+    context: ClassAccessorDecoratorContext<This, V>,
+  ): ClassAccessorDecoratorResult<This, V> {
+    const bindings = new WeakMap<object, AccessorBinding>();
+    const initValues = new WeakMap<object, unknown>();
+
+    function getBinding(instance: object): AccessorBinding {
+      let b = bindings.get(instance);
+      if (!b) {
+        b = behavior.bind(instance, context.name, initValues.get(instance));
+        bindings.set(instance, b);
+      }
+      return b;
+    }
+
+    return {
+      init(this: This, value: V): V {
+        initValues.set(this as object, value);
+        return value;
+      },
+      get(this: This): V {
+        return getBinding(this as object).get() as V;
+      },
+      set(this: This, value: V): void {
+        getBinding(this as object).set?.(value as unknown);
+      },
+    };
+  };
+}

package/src/create-getter-decorator.ts

@@ -23,6 +23,45 @@ export function createGetterDecorator(behavior: GetterBehavior) {
   };
 }
 
+export interface WritableGetterBinding {
+  get: () => unknown;
+  set?: (value: unknown) => void;
+}
+
+export interface WritableGetterBehavior {
+  /**
+   * Called once per instance during construction. Returns the get/set pair
+   * that will be installed on the instance via `Object.defineProperty`.
+   * If `set` is omitted, the property is read-only at runtime (though TypeScript
+   * may still see a setter if one is declared in the class body).
+   */
+  bind(
+    instance: object,
+    name: string | symbol,
+    original: (this: object) => unknown,
+  ): WritableGetterBinding;
+}
+
+export function createWritableGetterDecorator(behavior: WritableGetterBehavior) {
+  return function <This, T>(
+    target: (this: This) => T,
+    context: ClassGetterDecoratorContext<This, T>,
+  ): (this: This) => T {
+    context.addInitializer(function (this: unknown) {
+      const instance = this as object;
+      const binding = behavior.bind(instance, context.name, target as (this: object) => unknown);
+      const descriptor: PropertyDescriptor = {
+        get: binding.get,
+        configurable: true,
+        enumerable: false,
+      };
+      if (binding.set !== undefined) descriptor.set = binding.set;
+      Object.defineProperty(instance, context.name, descriptor);
+    });
+    return target;
+  };
+}
+
 export interface GetterObserverBehavior {
   /**
    * Called once per instance when the class is initialized.

package/src/functions/when.ts

@@ -1,17 +1,41 @@
-import { when } from "@praxisjs/core/internal";
+import { effect } from "@praxisjs/core/internal";
 import type { Computed, Signal } from "@praxisjs/shared";
-import { isComputed } from "@praxisjs/shared/internal";
+import { isComputed, isSignal } from "@praxisjs/shared/internal";
 
 import { createLifecycleMethodDecorator } from "../create-lifecycle-method-decorator";
 
-export function When(propName: string) {
+/** Read the current value of a property, unwrapping Signal or Computed if needed. */
+function readProp(instance: Record<string, unknown>, key: string): unknown {
+  const raw = instance[key];
+  if (isComputed(raw)) return (raw as Computed<unknown>)();
+  if (isSignal(raw))   return (raw as Signal<unknown>)();
+  return raw;
+}
+
+export function When<T = unknown>(
+  propName: string,
+  condition?: (value: NonNullable<T>) => boolean,
+) {
   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); });
+      const inst = instance as unknown as Record<string, unknown>;
+      let fired = false;
+
+      return effect(() => {
+        if (fired) return;
+        // Reading via readProp subscribes this effect to the underlying signal,
+        // whether the property is a raw Signal/Computed or an @State getter.
+        const val = readProp(inst, propName) as T;
+
+        const meetsCondition = condition
+          ? val != null && condition(val)
+          : val != null && Boolean(val);
+
+        if (meetsCondition) {
+          fired = true;
+          callback(val as NonNullable<T>);
+        }
+      });
     },
   });
 }

package/src/index.ts

@@ -54,6 +54,14 @@ export {
 export {
   createGetterDecorator,
   type GetterBehavior,
+  createWritableGetterDecorator,
+  type WritableGetterBehavior,
+  type WritableGetterBinding,
   createGetterObserverDecorator,
   type GetterObserverBehavior,
 } from "./create-getter-decorator";
+export {
+  createAccessorDecorator,
+  type AccessorBehavior,
+  type AccessorBinding,
+} from "./create-accessor-decorator";

package/src/properties/computed.ts

@@ -1,18 +1,55 @@
 import { computed } from "@praxisjs/core/internal";
 
-import { createGetterDecorator } from "../create-getter-decorator";
+import { createAccessorDecorator } from "../create-accessor-decorator";
+import { createWritableGetterDecorator } from "../create-getter-decorator";
 
-export function Computed() {
-  const cache = new WeakMap<object, () => unknown>();
+export interface ComputedOptions<T = unknown> {
+  get?: (this: object) => T;
+  set?: (this: object, value: T) => void;
+}
+
+// Accessor form — @Computed({ get, set }) on an `accessor` field.
+// TypeScript sees the accessor as writable; no cast needed when assigning.
+// The `Owner` generic is inferred from the `this` type of the provided functions.
+export function Computed<T, Owner extends object = object>(options: {
+  get: (this: Owner) => T;
+  set: (this: Owner, value: T) => void;
+}): <This extends object>(
+  target: ClassAccessorDecoratorTarget<This, T>,
+  context: ClassAccessorDecoratorContext<This, T>,
+) => ClassAccessorDecoratorResult<This, T>;
+
+// Getter form — @Computed() or @Computed({ set }) on a `get` accessor.
+export function Computed(options?: {
+  set?: (this: object, value: unknown) => void;
+}): <This, R>(
+  target: (this: This) => R,
+  context: ClassGetterDecoratorContext<This, R>,
+) => (this: This) => R;
+
+export function Computed<T = unknown>(options?: ComputedOptions<T>): unknown {
+  const optionsGet = options?.get as ((this: object) => unknown) | undefined;
+  const optionsSet = options?.set as ((this: object, value: unknown) => void) | undefined;
+
+  if (optionsGet) {
+    return createAccessorDecorator({
+      bind(instance, _name, _initialValue) {
+        const c = computed(() => optionsGet.call(instance));
+        return {
+          get: c,
+          set: optionsSet ? (value) => { optionsSet.call(instance, value); } : undefined,
+        };
+      },
+    });
+  }
 
-  return createGetterDecorator({
-    wrap(original, instance) {
-      let c = cache.get(instance);
-      if (!c) {
-        c = computed(() => original.call(instance));
-        cache.set(instance, c);
-      }
-      return c;
+  return createWritableGetterDecorator({
+    bind(instance, _name, original) {
+      const c = computed(() => original.call(instance));
+      return {
+        get: c,
+        set: optionsSet ? (value) => { optionsSet.call(instance, value); } : undefined,
+      };
     },
   });
 }