@praxisjs/decorators 0.4.1 → 0.4.2

package/src/__tests__/functions.test.ts

@@ -0,0 +1,342 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { Bind } from "../functions/bind";
+import { Debounce } from "../functions/debounce";
+import { Log } from "../functions/log";
+import { Once } from "../functions/once";
+import { Retry } from "../functions/retry";
+import { Throttle } from "../functions/throttle";
+
+// Helpers to simulate TC39 decorator context
+function mockMethodContext(name: string) {
+  const initializers: Array<(this: object) => void> = [];
+  const ctx = {
+    name,
+    kind: "method" as const,
+    addInitializer(fn: (this: object) => void) {
+      initializers.push(fn);
+    },
+    runInitializers(instance: object) {
+      initializers.forEach((fn) => { fn.call(instance); });
+    },
+  };
+  return ctx;
+}
+
+// ── Once ─────────────────────────────────────────────────────────────────────
+
+describe("Once", () => {
+  it("only calls the original function once", () => {
+    const original = vi.fn(() => 42);
+    const ctx = mockMethodContext("doSomething");
+    const wrapped = Once()(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    expect(wrapped.call(obj)).toBe(42);
+    expect(wrapped.call(obj)).toBe(42);
+    expect(original).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns the same result on subsequent calls", () => {
+    let counter = 0;
+    const original = () => ++counter;
+    const ctx = mockMethodContext("inc");
+    const wrapped = Once()(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    wrapped.call(obj);
+    wrapped.call(obj);
+    wrapped.call(obj);
+    expect(counter).toBe(1);
+  });
+
+  it("is per-instance — different instances call independently", () => {
+    const original = vi.fn(() => "result");
+    const ctx = mockMethodContext("fn");
+    const wrapped = Once()(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    const a = {};
+    const b = {};
+    wrapped.call(a);
+    wrapped.call(b);
+    expect(original).toHaveBeenCalledTimes(2);
+  });
+});
+
+// ── Retry ─────────────────────────────────────────────────────────────────────
+
+describe("Retry", () => {
+  it("returns result if the first attempt succeeds", async () => {
+    const original = vi.fn(async () => "ok");
+    const ctx = mockMethodContext("fetch");
+    const wrapped = Retry(3)(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    const result = await wrapped.call({});
+    expect(result).toBe("ok");
+    expect(original).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries and succeeds on a later attempt", async () => {
+    let attempt = 0;
+    const original = vi.fn(async () => {
+      attempt++;
+      if (attempt < 3) throw new Error("fail");
+      return "success";
+    });
+    const ctx = mockMethodContext("call");
+    const wrapped = Retry(3)(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    const result = await wrapped.call({});
+    expect(result).toBe("success");
+    expect(original).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws after exhausting all attempts", async () => {
+    const original = vi.fn(async () => {
+      throw new Error("always fails");
+    });
+    const ctx = mockMethodContext("bad");
+    const wrapped = Retry(3)(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    await expect(wrapped.call({})).rejects.toThrow("always fails");
+    expect(original).toHaveBeenCalledTimes(3);
+  });
+
+  it("applies delay+backoff between retries", async () => {
+    vi.useFakeTimers();
+    const original = vi.fn(async () => { throw new Error("fail"); });
+    const ctx = mockMethodContext("delayed");
+    const wrapped = Retry(3, { delay: 100, backoff: 2 })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+    const p = wrapped.call({});
+    const rejection = expect(p).rejects.toThrow("fail");
+    await vi.runAllTimersAsync();
+    await rejection;
+    expect(original).toHaveBeenCalledTimes(3);
+    vi.useRealTimers();
+  });
+
+  it("calls onRetry callback for each failed attempt (except last)", async () => {
+    const onRetry = vi.fn();
+    const original = vi.fn(async () => {
+      throw new Error("err");
+    });
+    const ctx = mockMethodContext("op");
+    const wrapped = Retry(3, { onRetry })(original, ctx as unknown as ClassMethodDecoratorContext);
+
+    await expect(wrapped.call({})).rejects.toThrow();
+    expect(onRetry).toHaveBeenCalledTimes(2); // attempts 1 and 2, not the last
+  });
+});
+
+// ── Log ──────────────────────────────────────────────────────────────────────
+
+describe("Log", () => {
+  it("calls the original function and returns its value", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const original = vi.fn(() => 99);
+    const ctx = mockMethodContext("myMethod");
+    const wrapped = Log({ args: false, result: false })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+
+    class Dummy {}
+    const result = wrapped.call(new Dummy());
+    expect(result).toBe(99);
+    spy.mockRestore();
+  });
+
+  it("logs args when args=true", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const original = vi.fn((x: unknown) => x);
+    const ctx = mockMethodContext("greet");
+    const wrapped = Log({ args: true, result: false })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+
+    class Foo {}
+    wrapped.call(new Foo(), "hello");
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("args:"), ["hello"]);
+    spy.mockRestore();
+  });
+
+  it("does not log in production when devOnly=true", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const original = vi.fn(() => "value");
+    const ctx = mockMethodContext("prod");
+    const wrapped = Log({ devOnly: true })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+
+    const prevEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "production";
+
+    class App {}
+    wrapped.call(new App());
+    expect(spy).not.toHaveBeenCalled();
+
+    process.env.NODE_ENV = prevEnv;
+    spy.mockRestore();
+  });
+
+  it("handles async functions — logs resolved value", async () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const original = vi.fn(async () => "async-result");
+    const ctx = mockMethodContext("load");
+    const wrapped = Log({ args: false, result: true })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+
+    class Svc {}
+    await wrapped.call(new Svc());
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining("resolved:"),
+      "async-result",
+      expect.any(String),
+    );
+    spy.mockRestore();
+  });
+
+  it("handles async rejection — logs rejected value and re-throws", async () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const original = vi.fn(async () => { throw new Error("async-error"); });
+    const ctx = mockMethodContext("failing");
+    const wrapped = Log({ args: false, result: true })(
+      original,
+      ctx as unknown as ClassMethodDecoratorContext,
+    );
+    class Svc {}
+    await expect(wrapped.call(new Svc())).rejects.toThrow("async-error");
+    expect(spy).toHaveBeenCalledWith(
+      expect.stringContaining("rejected:"),
+      expect.any(Error),
+    );
+    spy.mockRestore();
+  });
+});
+
+// ── Bind ─────────────────────────────────────────────────────────────────────
+
+describe("Bind", () => {
+  it("binds method to the instance so 'this' is preserved", () => {
+    class Counter {
+      value = 10;
+      getValue() {
+        return this.value;
+      }
+    }
+    const ctx = mockMethodContext("getValue");
+    Bind()(Counter.prototype.getValue, ctx as unknown as ClassMethodDecoratorContext);
+
+    const c = new Counter();
+    ctx.runInitializers(c);
+
+    const detached = (c as unknown as Record<string, () => number>).getValue;
+    expect(detached()).toBe(10);
+  });
+});
+
+// ── Debounce ─────────────────────────────────────────────────────────────────
+
+describe("Debounce", () => {
+  it("defers execution until after the wait period", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const ctx = mockMethodContext("search");
+    Debounce(100)(fn, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => void>).search;
+
+    method("a");
+    method("b");
+    method("c");
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledWith("c");
+    vi.useRealTimers();
+  });
+
+  it("resets the timer on each call", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const ctx = mockMethodContext("onInput");
+    Debounce(50)(fn, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => void>).onInput;
+
+    method("x");
+    vi.advanceTimersByTime(30);
+    method("y");
+    vi.advanceTimersByTime(30); // 30ms since last call — not enough
+    expect(fn).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(20); // now 50ms since "y"
+    expect(fn).toHaveBeenCalledOnce();
+    vi.useRealTimers();
+  });
+});
+
+// ── Throttle ─────────────────────────────────────────────────────────────────
+
+describe("Throttle", () => {
+  it("executes the first call immediately", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn(() => "first");
+    const ctx = mockMethodContext("save");
+    Throttle(100)(fn, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => void>).save;
+
+    method();
+    expect(fn).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
+
+  it("ignores calls within the throttle window", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const ctx = mockMethodContext("scroll");
+    Throttle(100)(fn, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => void>).scroll;
+
+    method();
+    method();
+    method();
+    expect(fn).toHaveBeenCalledTimes(1);
+    vi.useRealTimers();
+  });
+
+  it("allows a new call after the window expires", () => {
+    vi.useFakeTimers();
+    const fn = vi.fn();
+    const ctx = mockMethodContext("resize");
+    Throttle(100)(fn, ctx as unknown as ClassMethodDecoratorContext);
+
+    const obj = {};
+    ctx.runInitializers(obj);
+    const method = (obj as Record<string, (...a: unknown[]) => void>).resize;
+
+    method();
+    vi.advanceTimersByTime(100);
+    method();
+    expect(fn).toHaveBeenCalledTimes(2);
+    vi.useRealTimers();
+  });
+});

package/src/__tests__/memo.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from "vitest";
+
+import { Memo } from "../functions/memo";
+
+function mockCtx(name: string) {
+  return { name, kind: "method" as const } as ClassMethodDecoratorContext;
+}
+
+describe("Memo", () => {
+  it("returns the computed value", () => {
+    const fn = vi.fn((x: unknown) => (x as number) * 2);
+    const wrapped = Memo()(fn, mockCtx("double"));
+    const obj = {};
+    expect(wrapped.call(obj, 5)).toBe(10);
+  });
+
+  it("caches result for same args — calls original only once", () => {
+    const fn = vi.fn((x: unknown) => (x as number) + 1);
+    const wrapped = Memo()(fn, mockCtx("inc"));
+    const obj = {};
+    wrapped.call(obj, 3);
+    wrapped.call(obj, 3);
+    wrapped.call(obj, 3);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("computes separately for different args", () => {
+    const fn = vi.fn((x: unknown) => (x as number) * 10);
+    const wrapped = Memo()(fn, mockCtx("mul"));
+    const obj = {};
+    expect(wrapped.call(obj, 2)).toBe(20);
+    expect(wrapped.call(obj, 3)).toBe(30);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("is per-instance — different instances have separate caches", () => {
+    const fn = vi.fn(() => Math.random());
+    const wrapped = Memo()(fn, mockCtx("rand"));
+    const a = {};
+    const b = {};
+    const v1 = wrapped.call(a);
+    const v2 = wrapped.call(b);
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(v1).not.toBe(v2); // different random values per instance
+  });
+
+  it("serializes no-args calls with __no_args__ key", () => {
+    const fn = vi.fn(() => 42);
+    const wrapped = Memo()(fn, mockCtx("noop"));
+    const obj = {};
+    wrapped.call(obj);
+    wrapped.call(obj);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("serializes object args via JSON.stringify", () => {
+    const fn = vi.fn((o: unknown) => JSON.stringify(o));
+    const wrapped = Memo()(fn, mockCtx("obj"));
+    const obj = {};
+    wrapped.call(obj, { a: 1 });
+    wrapped.call(obj, { a: 1 }); // same key
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("serializes symbol args via toString()", () => {
+    const fn = vi.fn((s: unknown) => String(s));
+    const wrapped = Memo()(fn, mockCtx("sym"));
+    const obj = {};
+    const sym = Symbol("test");
+    wrapped.call(obj, sym);
+    wrapped.call(obj, sym);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/properties-browser.test.ts

@@ -0,0 +1,234 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import { StatefulComponent } from "@praxisjs/core";
+
+import { Persisted } from "../properties/persisted";
+import { Slot, initSlots, getSlot } from "../properties/slot";
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+// Helper: creates a ClassFieldDecoratorContext mock
+function fieldCtx(name: string) {
+  const initializers: Array<(this: unknown) => void> = [];
+  return {
+    ctx: {
+      name,
+      kind: "field" as const,
+      addInitializer(fn: (this: unknown) => void) {
+        initializers.push(fn);
+      },
+    } as ClassFieldDecoratorContext,
+    run(instance: unknown) {
+      initializers.forEach((fn) => { fn.call(instance); });
+    },
+  };
+}
+
+// Minimal concrete component
+class TestComponent extends StatefulComponent {
+  render() { return null; }
+}
+
+// ── Persisted ─────────────────────────────────────────────────────────────────
+
+describe("Persisted decorator", () => {
+  it("reads back the initial value when nothing is stored", () => {
+    const { ctx, run } = fieldCtx("theme");
+    Persisted<string>("theme")(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).theme = "light";
+    run(instance);
+
+    expect((instance as unknown as Record<string, unknown>).theme).toBe("light");
+  });
+
+  it("persists set value to localStorage", () => {
+    const { ctx, run } = fieldCtx("lang");
+    Persisted<string>("lang")(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).lang = "en";
+    run(instance);
+
+    (instance as unknown as Record<string, unknown>).lang = "pt";
+    expect(localStorage.getItem("lang")).toBe('"pt"');
+    expect((instance as unknown as Record<string, unknown>).lang).toBe("pt");
+  });
+
+  it("reads existing localStorage value over the initialValue", () => {
+    localStorage.setItem("color", '"red"');
+    const { ctx, run } = fieldCtx("color");
+    Persisted<string>("color")(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).color = "blue";
+    run(instance);
+
+    expect((instance as unknown as Record<string, unknown>).color).toBe("red");
+  });
+
+  it("uses the property name as storage key when no explicit key given", () => {
+    const { ctx, run } = fieldCtx("count");
+    Persisted<number>()(undefined, ctx);
+
+    const instance = new TestComponent();
+    (instance as unknown as Record<string, unknown>).count = 0;
+    run(instance);
+
+    (instance as unknown as Record<string, unknown>).count = 7;
+    expect(localStorage.getItem("count")).toBe("7");
+  });
+
+  it("returns separate values per instance", () => {
+    const { ctx: ctxA, run: runA } = fieldCtx("val");
+    Persisted<number>("valA")(undefined, ctxA);
+
+    const { ctx: ctxB, run: runB } = fieldCtx("val");
+    Persisted<number>("valB")(undefined, ctxB);
+
+    const a = new TestComponent();
+    (a as unknown as Record<string, unknown>).val = 1;
+    runA(a);
+
+    const b = new TestComponent();
+    (b as unknown as Record<string, unknown>).val = 2;
+    runB(b);
+
+    (a as unknown as Record<string, unknown>).val = 10;
+    (b as unknown as Record<string, unknown>).val = 20;
+
+    expect((a as unknown as Record<string, unknown>).val).toBe(10);
+    expect((b as unknown as Record<string, unknown>).val).toBe(20);
+  });
+});
+
+// ── Slot ──────────────────────────────────────────────────────────────────────
+
+describe("Slot decorator", () => {
+  it("returns an empty array before initSlots is called", () => {
+    const { ctx, run } = fieldCtx("default");
+    Slot()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    expect((instance as unknown as Record<string, unknown>).default).toEqual([]);
+  });
+
+  it("returns default slot children after initSlots", () => {
+    const { ctx, run } = fieldCtx("default");
+    Slot()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const el = document.createElement("span");
+    initSlots(instance, [el]);
+
+    expect((instance as unknown as Record<string, unknown>).default).toContain(el);
+  });
+
+  it("resolves named slot children", () => {
+    const { ctx, run } = fieldCtx("header");
+    Slot("header")(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const el = document.createElement("div");
+    el.setAttribute("slot", "header");
+    initSlots(instance, [el]);
+
+    const result = (instance as unknown as Record<string, unknown>).header as unknown[];
+    expect(result).toHaveLength(1);
+    expect(result[0]).toBe(el);
+  });
+
+  it("named slot element has slot attribute removed", () => {
+    const { ctx, run } = fieldCtx("footer");
+    Slot("footer")(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const el = document.createElement("div");
+    el.setAttribute("slot", "footer");
+    initSlots(instance, [el]);
+
+    expect(el.getAttribute("slot")).toBeNull();
+  });
+
+  it("warns when attempting to set a slot directly (dev mode)", () => {
+    const originalEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+
+    const { ctx, run } = fieldCtx("content");
+    Slot("content")(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    (instance as unknown as Record<string, unknown>).content = ["something"];
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("[Slot]"));
+    warn.mockRestore();
+
+    process.env.NODE_ENV = originalEnv;
+  });
+
+  it("uses property name as slot name when no name given and prop is not 'default'", () => {
+    const { ctx, run } = fieldCtx("sidebar");
+    Slot()(undefined, ctx);
+
+    const instance = new TestComponent();
+    run(instance);
+
+    const el = document.createElement("aside");
+    el.setAttribute("slot", "sidebar");
+    initSlots(instance, [el]);
+
+    const result = (instance as unknown as Record<string, unknown>).sidebar as unknown[];
+    expect(result).toHaveLength(1);
+  });
+});
+
+// ── initSlots / getSlot helpers ───────────────────────────────────────────────
+
+describe("initSlots / getSlot", () => {
+  it("splits children into named and default slots", () => {
+    const named = document.createElement("div");
+    named.setAttribute("slot", "header");
+
+    const plain = document.createElement("p");
+
+    const instance = {};
+    initSlots(instance, [named, plain]);
+
+    expect(getSlot(instance, "header")).toContain(named);
+    expect(getSlot(instance, "default")).toContain(plain);
+  });
+
+  it("handles null children gracefully", () => {
+    const instance = {};
+    initSlots(instance, null);
+    expect(getSlot(instance, "default")).toEqual([]);
+  });
+
+  it("flattens nested arrays", () => {
+    const a = document.createElement("span");
+    const b = document.createElement("span");
+    const instance = {};
+    initSlots(instance, [[a, b]]);
+    expect(getSlot(instance, "default")).toHaveLength(2);
+  });
+
+  it("returns empty array for unknown slot", () => {
+    const instance = {};
+    initSlots(instance, []);
+    expect(getSlot(instance, "nonexistent")).toEqual([]);
+  });
+});