signalium 2.4.0 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,206 @@
 # signalium
 
+## 3.0.1
+
+### Patch Changes
+
+- d4658b4: Fix `registerCustomSnapshot` to apply to subclasses of the registered class. Previously, a handler registered on a base class was only invoked for direct instances of that class — subclass instances bypassed it because the resolver did an exact-prototype lookup. Custom snapshot registrations now use a non-enumerable symbol on the class prototype, so JS prototype lookup naturally walks the chain and subclasses inherit their ancestor's handler. Subclasses can still override by registering their own handler. The public API is unchanged.
+
+## 3.0.0
+
+### Major Changes
+
+- 97a1d00: Add async component support with Suspense + RSC/SSR integration.
+
+  - `component(async (props) => { await ... })` on the client: the Signalium Babel preset
+    rewrites the async body to a generator, and a synchronous replay driver throws pending
+    thenables for `<Suspense>` while re-injecting settled values on replay. Reactive reads
+    inside the component participate in the signal graph like any other `compute`.
+  - New `signalium/react` `react-server` export condition: in RSC bundles, `component()`
+    returns a real `async function` (for generator authoring) or a thin sync wrapper, with
+    no React hook imports — safe for the server module graph.
+  - New `signalium/react/server` entry exposing `setupRscRequestScope()`, which installs a
+    per-request `SignalScope` via `React.cache` so server-side `reactive()` / `task()` /
+    `relay()` don't leak across requests.
+  - New core API `setRequestScopeGetter(get)` that frameworks/tests can use to supply a
+    per-request scope; consulted by `getCurrentScope` after `CURRENT_SCOPE` and the current
+    consumer's scope.
+  - Babel async transform now tracks `component` imported from `signalium/react` alongside
+    `reactive` / `reactiveMethod` / `relay` / `task`, so `component(async ...)` is rewritten
+    to a generator without extra configuration.
+
+  Breaking: `react` peer dependency is now `>=19.0.0` (required for `React.cache` and
+  React 19's thenable handling in `<Suspense>`).
+
+- 9fa0d88: `ReactivePromise<T>` is now the discriminated union by default.
+
+  The exported `ReactivePromise<T>` _type_ is now
+  `PendingReactivePromise<T> | ReadyReactivePromise<T>` — the same shape that was
+  previously named `DiscriminatedReactivePromise<T>`. This means `if (p.isReady)`
+  narrows `p.value` to `T` (no `| undefined`) directly, with no extra type
+  gymnastics.
+
+  The exported `ReactivePromise` _value_ (the class for `instanceof`, `new`, and
+  the static methods `all` / `race` / `any` / `allSettled` / `resolve` / `reject`
+  / `withResolvers`, plus the identifier emitted by the Babel preset's promise
+  methods transform) is unchanged at runtime. It's now typed as a constructor
+  interface (the same pattern lib.es5.d.ts uses for the global `Promise`), so:
+
+  - `new ReactivePromise<T>()` returns `ReactivePromise<T>` (the union)
+  - `value instanceof ReactivePromise` narrows to the union
+  - `ReactivePromise.resolve(x)`, `.all([...])`, etc. return the union
+
+  ### Breaking changes
+
+  - `DiscriminatedReactivePromise<T>` is removed. Replace every reference with
+    `ReactivePromise<T>`. The two types are now identical, so the migration is a
+    rename.
+  - The previous wide `ReactivePromise<T>` interface (with `value: T | undefined`
+    and `isReady: boolean`) is no longer exported. If you had code that explicitly
+    asked for that wide shape, switch to discriminating on `isReady` (or accept
+    `PendingReactivePromise<T>` / `ReadyReactivePromise<T>` directly).
+
+  ### Why
+
+  The previous split between a non-discriminated `ReactivePromise<T>` (the class
+  instance type) and a separate `DiscriminatedReactivePromise<T>` union (what
+  `useReactive`, `relay()`, async `reactive()`, etc. actually returned) was a
+  frequent source of confusion. The names suggested they were different shapes
+  when in practice users almost always wanted the discriminated form. Merging
+  them removes a footgun and matches the runtime behavior.
+
+- 46facb0: `useReactive` is now thunk-only and deep-by-default.
+
+  ### New API surface
+
+  - `useReactive(() => expr)` — deep-by-default. Returns a structurally-shared
+    snapshot of the reactive value, so referential equality at the React boundary
+    Just Works (memoized children keep the same props when unchanged subtrees are
+    re-read). This is the behavior of the old `useReactiveDeep`.
+  - `useReactiveShallow(() => expr)` — new named export. Minimal wrapper:
+    returns the reactive value by reference without any structural cloning or
+    `ReactivePromise` entanglement. Re-renders only when the underlying
+    `ReactiveSignal` itself re-runs (e.g. the thunk produces a new reference).
+    Use it when you need to preserve class identity on a synchronously-changing
+    value. If you need promise state transitions at the React boundary, use
+    `useReactive` — its structural snapshot reads the promise's flags and
+    automatically re-renders on each transition.
+  - `useReactiveDeep(() => expr)` — kept as a deprecated alias that forwards to
+    `useReactive` and logs a one-time `console.warn` in dev. Will be removed in
+    the next major.
+
+  ### Breaking changes
+
+  - The non-thunk overloads are removed:
+    - `useReactive(signal)` → `useReactive(() => signal.value)`
+    - `useReactive(promise)` → `useReactive(() => promise)` for a plain
+      snapshot that updates on every promise state transition.
+    - `useReactive(reactiveFn, arg1, arg2)` → `useReactive(() => reactiveFn(arg1, arg2))`
+    - `useReactiveDeep(reactiveFn, arg1)` → `useReactive(() => reactiveFn(arg1))`
+  - Calling `useReactive` / `useReactiveShallow` / `useReactiveDeep` inside a
+    reactive function (e.g. inside `reactive(...)` or a `component()` render
+    body) now throws in dev (the guard is tree-shaken from production builds).
+    These hooks are the bridge from plain React components into the signal
+    graph — inside reactive code you should call your signals and
+    `reactive()`-returned functions directly, since the surrounding compute
+    already participates in the graph. This replaces the previous behavior of
+    silently forking and invoking the thunk.
+  - The internal `addListener` on `ReactiveSignal` no longer schedules an
+    initial pull when the signal is registered as a suspended listener. This
+    fixes a case where a component mounted inside a suspended provider would
+    render twice on mount.
+
+  ### Recommended migration
+
+  1. Land this version and enable (or keep) the Signalium Babel preset. The
+     preset wraps thunks in `useCallback(fn, [captures])` so identity stays
+     stable across renders and the same `ReactiveSignal` is reused.
+  2. Rewrite `useReactive(signal)` / `useReactive(fn, ...args)` call sites as
+     thunks. A safe blanket replacement is `useReactive(() => oldArg)` /
+     `useReactive(() => oldFn(...oldArgs))`.
+  3. If you were relying on `ReactivePromise` class identity (e.g. `instanceof`
+     checks or passing through `React.memo` by reference), switch those sites to
+     `useReactiveShallow`.
+  4. Rename `useReactiveDeep` call sites to `useReactive` at your leisure — they
+     behave identically but the old name will be removed in the next major.
+
+  ### Philosophy
+
+  `useReactive` is the bridge from plain React components into the signal graph.
+  Every call site is a hook, so there's per-render bookkeeping overhead. Prefer
+  `component(fn)` (from `signalium/react`) for components that are meaningfully
+  reactive — the whole render body becomes one `ReactiveSignal`'s `compute`,
+  which avoids the hook overhead entirely.
+
+- 5031ce1: Switch to native `WeakRef` for scope-cached signals, remove suspension from the core graph, and introduce `PauseSignalsProvider`.
+
+  ### Native WeakRef GC
+
+  `SignalScope` now stores signals as `WeakRef` entries instead of strong references with manual GC sweeps. Signals stay alive as long as something holds a strong reference (the `deps` chain, a React component closure, a local variable, etc.). When nothing references a signal, the JS garbage collector reclaims it naturally.
+
+  Removed:
+
+  - The `WeakRef` polyfill (`weakref.ts`) — environments without native `WeakRef` are no longer supported.
+  - The manual GC sweep system (`markForGc`, `removeFromGc`, `sweepGc`, `gcCandidates`, `scheduleGcSweep`, `scheduleIdleCallback`).
+  - `reset()` on `ReactiveSignal` — signals are no longer eagerly torn down on unwatch. Their value and dep graph are preserved for reuse if re-watched before GC collects them.
+
+  ### Suspension removed from core
+
+  The core signal graph has zero suspension concepts. Removed:
+
+  - `suspendCount` field and `_isSuspended` getter on `ReactiveSignal`
+  - `setSuspended()` method and `isSuspendedListener` flag
+  - `watchSuspendedSignal`, `unwatchSuspendedSignal`, `suspendSignal`, `resumeSignal`
+  - The `parentIsSuspended` parameter on `watchSignal` / `unwatchSignal`
+  - The `isSuspending` branch in `deactivateSignal`
+
+  ### `PauseSignalsProvider` (replaces `SuspendSignalsProvider`)
+
+  `SuspendSignalsProvider` is replaced by `PauseSignalsProvider` to avoid confusion with React Suspense.
+
+  `PauseSignalsProvider` uses a stable `PauseSignalsManager` context (not a changing boolean), so toggling the `value` prop does not re-render descendants. React hooks register their signals during render; the manager calls `watchSignal` / `unwatchSignal` directly to pause and resume the signal graph. Signals mounted inside an already-paused provider skip activation entirely.
+
+  ### Breaking changes
+
+  - `SuspendSignalsProvider` → `PauseSignalsProvider`
+  - `useSignalsSuspended()` is removed from the public API.
+  - `setSuspended()` is removed from the `Watcher` interface.
+  - Environments without native `WeakRef` are no longer supported.
+
+### Minor Changes
+
+- 500514d: Remove the implicit `console.error('[signalium] Unhandled async error...')`
+  that fired whenever a `ReactivePromise` (including `relay()` and `task()`)
+  transitioned to a rejected state.
+
+  The log was misleading in practice: it ran synchronously inside `_setError`,
+  before any reactive consumer or async `component()` had a chance to react. So
+  it printed "Unhandled" for rejections that were in fact handled — declaratively
+  via `isRejected` / `error` reads, by `await` in an async `component()` (which
+  re-throws into a React error boundary), or by an explicit `.catch()` on the
+  `ReactivePromise` surface. There's no general definition of "handled" in a
+  reactive graph, so any single heuristic was going to mislabel some path.
+
+  Rejected `ReactivePromise`s are now silent at the library layer. Existing
+  ways to observe a rejection are unchanged:
+
+  - Read `isRejected` / `error` on the `ReactivePromise` (or its
+    `useReactive` snapshot) and branch in your reactive code.
+  - `await` / `yield` the `ReactivePromise` from an async `component()`; the
+    replay driver throws `error` into the nearest React error boundary on
+    rejection (and throws a thenable for `<Suspense>` while pending).
+  - `.catch()` / `.then(null, fn)` on the `ReactivePromise` — it still
+    implements the `Promise` surface.
+
+  A first-class global hook for unhandled reactive rejections is intentionally
+  deferred: defining "handled" in a way that doesn't mislabel the cases above
+  needs more design and isn't required for v3.
+
+  If you were relying on the log for debugging, attach your own logging in a
+  declarative branch (e.g. inside a `reactive()` that reads `isRejected` /
+  `error`) or rethrow from an async `component()` so the error reaches a React
+  error boundary.
+
 ## 2.4.0
 
 ### Minor Changes

package/dist/cjs/development/component-shared-Cug2Y5YZ.js

@@ -0,0 +1,33 @@
+"use strict";
+const debug = require("./debug-C46WDxhL.js");
+function isGeneratorFunction(fn) {
+  return typeof fn === "function" && fn.constructor?.name === "GeneratorFunction";
+}
+function isAsyncFunctionWithoutTransform(fn) {
+  return typeof fn === "function" && fn.constructor?.name === "AsyncFunction";
+}
+function createServerAsyncComponentWrapper(fn) {
+  return async function(props) {
+    const scope = debug.getCurrentScope();
+    const owned = debug.createReactiveSignal({ compute: () => null, equals: () => true, isRelay: false, tracer: void 0 }, [], void 0, scope);
+    return debug.generatorResultToPromiseWithConsumer(fn(props), owned);
+  };
+}
+function createServerSyncComponentWrapper(fn) {
+  return function(props) {
+    const scope = debug.getCurrentScope();
+    const owned = debug.createReactiveSignal({ compute: () => null, equals: () => true, isRelay: false, tracer: void 0 }, [], void 0, scope);
+    const prevConsumer = debug.getCurrentConsumer();
+    try {
+      debug.setCurrentConsumer(owned);
+      return fn(props);
+    } finally {
+      debug.setCurrentConsumer(prevConsumer);
+    }
+  };
+}
+exports.createServerAsyncComponentWrapper = createServerAsyncComponentWrapper;
+exports.createServerSyncComponentWrapper = createServerSyncComponentWrapper;
+exports.isAsyncFunctionWithoutTransform = isAsyncFunctionWithoutTransform;
+exports.isGeneratorFunction = isGeneratorFunction;
+//# sourceMappingURL=component-shared-Cug2Y5YZ.js.map

package/dist/cjs/development/component-shared-Cug2Y5YZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-shared-Cug2Y5YZ.js","sources":["../../../.tsc-out/react/component-shared.js"],"sourcesContent":["import { getCurrentConsumer, setCurrentConsumer } from '../internals/consumer.js';\nimport { getCurrentScope } from '../internals/contexts.js';\nimport { createReactiveSignal } from '../internals/reactive.js';\nimport { generatorResultToPromiseWithConsumer } from '../internals/generators.js';\nexport function isGeneratorFunction(fn) {\n    return (typeof fn === 'function' && fn.constructor?.name === 'GeneratorFunction');\n}\nexport function isAsyncFunctionWithoutTransform(fn) {\n    return typeof fn === 'function' && fn.constructor?.name === 'AsyncFunction';\n}\n/**\n * Wrap a Babel-transformed async generator in a real `async function` that drives it\n * with {@link generatorResultToPromiseWithConsumer}. Used on the server (RSC + SSR)\n * where hooks-based Suspense replay is not appropriate.\n */\nexport function createServerAsyncComponentWrapper(fn) {\n    return async function (props) {\n        const scope = getCurrentScope();\n        const owned = createReactiveSignal({ compute: () => null, equals: () => true, isRelay: false, tracer: undefined }, [], undefined, scope);\n        return generatorResultToPromiseWithConsumer(fn(props), owned);\n    };\n}\n/**\n * Wrap a sync render function with consumer/scope tracking. Used by the server\n * `component()` for non-generator definitions.\n */\nexport function createServerSyncComponentWrapper(fn) {\n    return function (props) {\n        const scope = getCurrentScope();\n        const owned = createReactiveSignal({ compute: () => null, equals: () => true, isRelay: false, tracer: undefined }, [], undefined, scope);\n        const prevConsumer = getCurrentConsumer();\n        try {\n            setCurrentConsumer(owned);\n            return fn(props);\n        }\n        finally {\n            setCurrentConsumer(prevConsumer);\n        }\n    };\n}\n"],"names":["getCurrentScope","createReactiveSignal","generatorResultToPromiseWithConsumer","getCurrentConsumer","setCurrentConsumer"],"mappings":";;AAIO,SAAS,oBAAoB,IAAI;AACpC,SAAQ,OAAO,OAAO,cAAc,GAAG,aAAa,SAAS;AACjE;AACO,SAAS,gCAAgC,IAAI;AAChD,SAAO,OAAO,OAAO,cAAc,GAAG,aAAa,SAAS;AAChE;AAMO,SAAS,kCAAkC,IAAI;AAClD,SAAO,eAAgB,OAAO;AAC1B,UAAM,QAAQA,MAAAA,gBAAe;AAC7B,UAAM,QAAQC,MAAAA,qBAAqB,EAAE,SAAS,MAAM,MAAM,QAAQ,MAAM,MAAM,SAAS,OAAO,QAAQ,OAAS,GAAI,CAAA,GAAI,QAAW,KAAK;AACvI,WAAOC,2CAAqC,GAAG,KAAK,GAAG,KAAK;AAAA,EAChE;AACJ;AAKO,SAAS,iCAAiC,IAAI;AACjD,SAAO,SAAU,OAAO;AACpB,UAAM,QAAQF,MAAAA,gBAAe;AAC7B,UAAM,QAAQC,MAAAA,qBAAqB,EAAE,SAAS,MAAM,MAAM,QAAQ,MAAM,MAAM,SAAS,OAAO,QAAQ,OAAS,GAAI,CAAA,GAAI,QAAW,KAAK;AACvI,UAAM,eAAeE,MAAAA,mBAAkB;AACvC,QAAI;AACAC,YAAAA,mBAAmB,KAAK;AACxB,aAAO,GAAG,KAAK;AAAA,IACnB,UACR;AACYA,YAAAA,mBAAmB,YAAY;AAAA,IACnC;AAAA,EACJ;AACJ;;;;;"}