@zakkster/lite-signal-decorators 0.1.0 → 0.2.0-preview.1

package/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [0.2.0-preview.1] - 2026-08-26
+
+The full runtime surface. Exports grow from 8 to 11. Published on the `preview`
+tag; a stable 0.2.0 remains user-gated.
+
+### Added
+
+- `reactiveEffect` -- `@reactiveEffect m()` (bare) / `@reactiveEffect({ scheduler })`
+  (factory): a method that auto-runs as an effect once the instance is wired
+  (after every field and every derived). The auto-effect tracks its reads; the
+  public method is a leak-guarded manual entry -- a call inside a foreign tracking
+  scope is untracked, so it records zero stray dependencies (0004 D-4b). Self-
+  dispose from inside an owned effect is allowed with pinned semantics (0004
+  D-4d): the current run completes, later decorated-member touches throw
+  `ReactiveDisposedError`, no re-runs follow, conservation is exact.
+- `batched` -- `@batched m()` (bare) / `@batched()` (factory): runs the method
+  body inside one engine batch, coalescing its writes into a single flush.
+  Action-grade (one call per user intent), not a per-frame path: it allocates a
+  thunk + rest-array per call by design and is excluded from the zero-GC hot-path
+  gates.
+- `defineReactive(Class, spec)` -- the buildless twin of the decorators (0005).
+  `spec` is `{ signals, deriveds, effects, host }`; it installs the members on
+  `Class.prototype` and wraps the class through the SAME wiring core the
+  decorators use (shared by function identity, not merely behaviorally alike).
+  Consumers without a Stage-3 transpiler get the complete feature set.
+- `@reactiveHost({ registry })` -- an optional `registry` from lite-signal
+  `createRegistry()` isolates the whole host chain. Every engine call routes
+  through the bound registry, closing the cross-registry dispose trap (the
+  default `dispose` is a silent no-op across registries). One registry per chain:
+  a heterogeneous chain or an invalid (duck-check-failing) registry is a named
+  throw.
+
+### Changed
+
+- `@reactiveHost` unknown options now report the standard unknown-option
+  did-you-mean over `["registry"]` (the 0.1.0 "takes no options" message is
+  retired) -- `registry` is now a valid option.
+- The duplicate-key error wording now names both causes: subclass redeclaration
+  OR two stacked package decorators on one member.
+- Internal error-string refactor (housekeeping): the package prefix is hoisted to
+  one `ERR` const and cold message building uses template literals; prewired
+  handles build their message once and share it. Message text is byte-identical
+  to 0.1.0 except the two changes above. Hot accessor bodies are untouched.
+- `VERSION` is `"0.2.0-preview.1"`.
+
+### Fixed
+
+- Manual-call identity guard (D-4e): calling a `@reactiveEffect` or `@batched`
+  method on a foreign, primitive, null, or cross-class receiver (e.g. via
+  `Class.prototype.m.call(...)`) now throws a named error instead of running the
+  body against the wrong instance. Uses byKey identity, so a subclass instance
+  calling a base-declared method still passes. Cold manual-call path only.
+- Frozen-instance dispose refusal (D-2g): `disposeReactive` (and `using`) now
+  refuses a frozen instance up front with a named error, atomically -- previously
+  it half-disposed (tore down boxes) then threw a raw `TypeError`, leaving
+  disposed boxes behind live-looking slots. `Object.seal`/`preventExtensions`
+  remain fine.
+
+### Notes
+
+- `@batched` per-call cost, measured by the committed cold-process probe
+  (`spikes/batched-cost.mjs`, K=10 cold processes, node 26.3.1, Apple M4 Pro,
+  lite-signal 1.5.0): the decorated method 22.12 ns/op vs raw `batch(fn)`
+  15.25 vs the plain unbatched method 11.67 (median-of-medians; 0 major GC in
+  every lane). The ~7 ns over raw is the guarded rest-array + thunk (risk R8).
+  Action-grade, not a per-frame path; never in the zero-GC torture gates.
+
 ## [0.1.0] - 2026-08-26
 
 Initial release -- the decorator core.
@@ -36,4 +103,5 @@ Initial release -- the decorator core.
 - Torture skeleton (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`):
   retention, conservation, lifecycle, and zero-GC lanes.
 
+[0.2.0-preview.1]: https://github.com/zakkster/lite-signal-decorators/releases/tag/v0.2.0-preview.1
 [0.1.0]: https://github.com/zakkster/lite-signal-decorators/releases/tag/v0.1.0

package/SignalDecorators.d.ts

@@ -6,7 +6,13 @@
  * `SignalDecorators.js`.
  */
 
-import type { SignalBox, ComputedBox, NodeDescriptor } from "@zakkster/lite-signal";
+import type {
+    SignalBox,
+    ComputedBox,
+    NodeDescriptor,
+    Registry,
+    EffectScheduler,
+} from "@zakkster/lite-signal";
 
 // --- Options ------------------------------------------------------------------
 
@@ -22,6 +28,22 @@ export interface DerivedOptions<V> {
     equals?: (a: V, b: V) => boolean;
 }
 
+/** Options for a `@reactiveEffect` method. */
+export interface ReactiveEffectOptions {
+    /** Optional scheduler forwarded straight to the underlying `effect(fn, { scheduler })`. */
+    scheduler?: EffectScheduler;
+}
+
+/**
+ * Options for `@reactiveHost` / `defineReactive` `host`. A `registry` isolates
+ * the entire host chain on a custom lite-signal registry (one registry per
+ * chain -- a mixed chain is a named throw).
+ */
+export interface ReactiveHostOptions {
+    /** A `Registry` from lite-signal `createRegistry()`. Omit for the default registry. */
+    registry?: Registry;
+}
+
 // --- reactive -----------------------------------------------------------------
 
 /**
@@ -81,22 +103,128 @@ export function derived<V>(
 
 /**
  * `@reactiveHost` -- the single wiring site. Wraps the class so its most-derived
- * constructor builds the reactive graph (anchor + every derived) exactly once,
- * after all field initializers have run.
+ * constructor builds the reactive graph (anchor + every derived + every effect)
+ * exactly once, after all field initializers have run.
  *
- * Bare application decorates the class; the zero-key factory form
- * (`@reactiveHost()`) returns the same class decorator. No options are accepted
- * in 0.1.0.
+ * Bare application decorates the class; the factory form
+ * (`@reactiveHost({ registry })`) validates its options eagerly and returns the
+ * same class decorator. A `registry` isolates the whole host chain.
  */
 export function reactiveHost<C extends abstract new (...args: any[]) => any>(
     target: C,
     ctx: ClassDecoratorContext<C>,
 ): C;
-export function reactiveHost(): <C extends abstract new (...args: any[]) => any>(
+export function reactiveHost(
+    opts?: ReactiveHostOptions,
+): <C extends abstract new (...args: any[]) => any>(
     target: C,
     ctx: ClassDecoratorContext<C>,
 ) => C;
 
+// --- reactiveEffect -----------------------------------------------------------
+
+/**
+ * `@reactiveEffect m()` -- a method that auto-runs as an effect once the
+ * instance is wired (after every field and derived). The auto-effect tracks its
+ * reads; the public method is a leak-guarded manual entry (a call inside a
+ * foreign tracking scope is untracked, so it records no stray dependencies).
+ *
+ * Bare application decorates a `method`; the factory form
+ * (`@reactiveEffect({ scheduler })`) validates its options eagerly and returns
+ * the same method decorator.
+ */
+export function reactiveEffect<This, Args extends any[], R>(
+    value: (this: This, ...args: Args) => R,
+    ctx: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => R>,
+): (this: This, ...args: Args) => R;
+export function reactiveEffect(
+    opts?: ReactiveEffectOptions,
+): <This, Args extends any[], R>(
+    value: (this: This, ...args: Args) => R,
+    ctx: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => R>,
+) => (this: This, ...args: Args) => R;
+
+// --- batched ------------------------------------------------------------------
+
+/**
+ * `@batched m()` -- a method whose body runs inside one engine batch, so its
+ * writes flush together. Action-grade (one call per user intent), not a
+ * per-frame path.
+ *
+ * Bare application decorates a `method`; the zero-key factory form
+ * (`@batched()`) returns the same method decorator. No options in 0.2.0.
+ */
+export function batched<This, Args extends any[], R>(
+    value: (this: This, ...args: Args) => R,
+    ctx: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => R>,
+): (this: This, ...args: Args) => R;
+export function batched(): <This, Args extends any[], R>(
+    value: (this: This, ...args: Args) => R,
+    ctx: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => R>,
+) => (this: This, ...args: Args) => R;
+
+// --- defineReactive (buildless twin) ------------------------------------------
+
+/** Per-instance signal descriptor for a `defineReactive` `signals` map entry. */
+export interface SignalSpec<This = unknown, V = unknown> {
+    /** The initial value, verbatim (mutually exclusive with `init`). */
+    initial?: V;
+    /** A per-instance factory `(self) => value` (mutually exclusive with `initial`). */
+    init?: (this: This, self: This) => V;
+    /** Custom equality predicate. Default: `Object.is`. */
+    equals?: (a: V, b: V) => boolean;
+}
+
+/** Derived descriptor for a `defineReactive` `deriveds` map entry. */
+export interface DerivedSpec<This = unknown, V = unknown> {
+    /** The compute body `(self) => value`. */
+    get: (this: This, self: This) => V;
+    /** Custom equality predicate. Default: `Object.is`. */
+    equals?: (a: V, b: V) => boolean;
+}
+
+/** Effect descriptor for a `defineReactive` `effects` map entry. */
+export interface EffectSpec<This = unknown> {
+    /** The effect body `(self) => void`, run under the instance's anchor. */
+    run: (this: This, self: This) => void;
+    /** Optional scheduler forwarded to the underlying effect. */
+    scheduler?: EffectScheduler;
+}
+
+/**
+ * The `defineReactive(Class, spec)` specification. Every section is optional;
+ * unknown sections and descriptor keys are named throws.
+ */
+export interface DefineReactiveSpec<This = any> {
+    /**
+     * Reactive signals: an array of keys (each initialized to `undefined`) or a
+     * map of `key -> plain value | SignalSpec`. A bare function value is a named
+     * throw (ambiguous -- use `{ initial: fn }` or `{ init: (self) => value }`).
+     */
+    signals?: PropertyKey[] | Record<PropertyKey, unknown | SignalSpec<This>>;
+    /** Lazy deriveds: a map of `key -> (self) => value | DerivedSpec`. */
+    deriveds?: Record<PropertyKey, ((this: This, self: This) => unknown) | DerivedSpec<This>>;
+    /** Auto-effects: a map of `key -> (self) => void | EffectSpec`. */
+    effects?: Record<PropertyKey, ((this: This, self: This) => void) | EffectSpec<This>>;
+    /** Host options (registry isolation), shared with `@reactiveHost`. */
+    host?: ReactiveHostOptions;
+}
+
+/**
+ * `defineReactive(Class, spec)` -- the buildless twin of the decorators. Installs
+ * the accessors, deriveds, and effect methods declared in `spec` on
+ * `Class.prototype`, then wraps `Class` through the same host step the
+ * decorators use. Returns the wrapper class. Zero decorator syntax required.
+ *
+ * @throws for an unknown section/descriptor key, an ambiguous signal entry, an
+ *   `initial`+`init` conflict, a spec key that collides with a hand-written
+ *   member, or an invalid host registry.
+ */
+export function defineReactive<C extends new (...args: any[]) => any>(
+    Class: C,
+    spec: DefineReactiveSpec<InstanceType<C>>,
+): C;
+
 // --- Lifecycle + lookups ------------------------------------------------------
 
 /**
@@ -145,4 +273,4 @@ export class ReactiveDisposedError extends Error {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION: string;
+export const VERSION: "0.2.0-preview.1";