/** * vapor-chamber - minimal signal abstraction. * * Standalone module with NO module-load side effects. Imported by transports, * plugins, form - modules that need a `signal` API but should not drag the * full Vue feature-detection registry from `chamber.ts` into ESM consumer * bundles. * * Detection / fallback chain (first match wins on each `signal()` call): * 1. `configureSignal(fn)` - explicit override; `chamber.ts` pushes Vue's * `shallowRef()` here once its async dynamic import resolves (shallow because * the library replaces signal values wholesale and never mutates nested * fields - skipping ref()'s deep-Proxy wrap on object/array values). * 2. Plain `{ value }` object - zero-overhead fallback for non-Vue, non-reactive * contexts. For push-pull reactivity without Vue, call * `configureAlienSignals` from `vapor-chamber/alien-signals` once at boot. * * Consumers needing full Vue auto-detection (async probe, Vapor detection, * lifecycle hooks) import from `chamber.ts`, which calls into this module. */ import { DEV } from './dev'; import { _report } from './report'; /** * A cell: `value`. An interface, so an entry that wires a reactive backing * extends it with its cell's type: `vapor-chamber/vapor` wires `shallowRef` at * import and declares `Signal` a Vue `ShallowRef`, so a template * unwraps it. A named interface stays `Signal` in every emitted * declaration, so a consumer without that entry never reads `vue`. * Types only. tests/vapor-signal-types.test-d.ts. */ export interface Signal { value: T } export type CreateSignal = (initial: T) => Signal; /** Count of signals created as plain `{ value }` objects (no reactive backing). * Used to warn when a reactive backing arrives AFTER signals were already * handed out - those early signals stay plain forever (silent semantics gap). */ let _plainCreations = 0; let _raceWarned = false; const fallbackSignal: CreateSignal = (initial: T): Signal => { _plainCreations++; // Plain until a backing is wired; typed as the backing's cell, as signal() is. return { value: initial } as Signal; }; let _signalFn: CreateSignal = fallbackSignal; /** * Configure the signal factory. Called once by `chamber.ts` after its async * Vue probe completes; also available to consumers who want a custom signal * implementation. * * Dev note: if any signals were created BEFORE this call resolved a reactive * backing, those signals are plain `{ value }` objects forever - writes to them * will not trigger Vue reactivity, while signals created after this call will. * A one-shot dev warning fires in that case; to guarantee a uniform backing, * `await waitForVueDetection()` before the first `signal()` call. * * @example * import { ref } from 'vue'; * import { configureSignal } from 'vapor-chamber'; * configureSignal(ref); */ export function configureSignal(fn: CreateSignal): void { _signalFn = fn; if ( _plainCreations > 0 && !_raceWarned && DEV ) { _raceWarned = true; _report('warn', 'core:unexpected:signal', `${_plainCreations} signal(s) were created before a ` + 'reactive backing was configured (Vue detection is async). Those early signals ' + 'are plain { value } objects - writes to them will NOT trigger reactivity, while ' + 'signals created from now on will. If you need reactive signals at module-init ' + 'time, `await waitForVueDetection()` (from vapor-chamber) before creating them. ' + 'Harmless if those early signals are never consumed reactively. Logged once.' ); } } export const signal: CreateSignal = (initial: T) => _signalFn(initial);