@fluixi/reactive 1.0.0-alpha.82 → 1.0.0-alpha.84

package/dist/lib/signal/api.d.ts

@@ -1,3 +1,4 @@
+import { type Context, type Owner } from './graph/runtime.js';
 import type { Accessor, Setter, SignalOptions } from './signal.js';
 /** A writable reactive value: call it to read, `.set()` to write. */
 export type SignalHandle<T> = Accessor<T> & {
@@ -5,9 +6,218 @@ export type SignalHandle<T> = Accessor<T> & {
 };
 /** A derived value. Read-only, so it is just the accessor. */
 export type MemoHandle<T> = Accessor<T>;
+/**
+ * A writable reactive value.
+ *
+ * The returned function *is* the accessor, with `set` hung off it, so it passes
+ * anywhere an accessor is expected and a read is an ordinary call. Reading inside a
+ * tracked scope subscribes that scope; reading outside one does not.
+ *
+ * `options.equals` decides what counts as a change and defaults to `===`. A write that
+ * compares equal notifies nobody, which is how a reflect loop or a feedback cycle
+ * terminates.
+ *
+ * @example
+ * ```ts
+ * const count = signal(0);
+ * count();                        // 0
+ * count.set(1);                   // write a value
+ * count.set((n) => n + 1);        // or derive from the previous one
+ * ```
+ *
+ * @example A function value has to be wrapped, because a bare function is read as an
+ * updater and called:
+ * ```ts
+ * const handler = signal<() => void>(() => {});
+ * handler.set(() => myCallback);  // stores myCallback
+ * handler.set(myCallback);        // calls myCallback and stores what it returned
+ * ```
+ *
+ * @example Deep values compare by identity unless told otherwise:
+ * ```ts
+ * const point = signal({ x: 0 }, { equals: (a, b) => a.x === b.x });
+ * ```
+ */
 export declare function signal<T>(value: T, options?: SignalOptions<T>): SignalHandle<T>;
 export declare function signal<T = undefined>(): SignalHandle<T | undefined>;
+/**
+ * A derived value, computed once per change and cached.
+ *
+ * Lazy and pull-based: the function does not run until something reads the memo, and
+ * then not again until one of its own dependencies changes. That is the difference from
+ * {@link computed}, which exists to do work rather than to hold a value.
+ *
+ * `prev` is the previous result, which makes an accumulator cheap without a second
+ * signal to hold it.
+ *
+ * @example
+ * ```ts
+ * const first = signal('Ada');
+ * const last = signal('Lovelace');
+ * const full = memo(() => `${first()} ${last()}`);
+ * full();                         // 'Ada Lovelace', computed now
+ * full();                         // cached, the function did not run again
+ * ```
+ *
+ * @example Reading the previous value:
+ * ```ts
+ * const high = memo((prev = 0) => Math.max(prev, reading()), 0);
+ * ```
+ */
 export declare function memo<T>(fn: (prev?: T) => T, value?: T, options?: SignalOptions<T>): MemoHandle<T>;
-/** Run `fn` and re-run it when anything it read changes. Returns its disposer. */
+/**
+ * Run `fn` now, and again whenever anything it read changes.
+ *
+ * Dependencies are collected by reading, not declared, so they are whatever the last
+ * run actually touched. A branch not taken subscribes to nothing, and a read behind a
+ * condition comes and goes with it.
+ *
+ * Eager. It runs once on creation and again as soon as a dependency is written, in the
+ * same task as the write. `batch` is what coalesces a group of writes into one run.
+ *
+ * Teardown goes through `onCleanup`, which runs before the next execution and once more
+ * on disposal. A returned function is **not** teardown: the return value is carried
+ * forward as the next call's `prev`, so returning a disposer silently leaks it. The
+ * effect is owned by the enclosing {@link root}, so disposing that disposes this.
+ *
+ * @example
+ * ```ts
+ * const query = signal('');
+ * effect(() => console.log('searching', query()));
+ * ```
+ *
+ * @example Teardown between runs, via onCleanup rather than a return:
+ * ```ts
+ * effect(() => {
+ *   const id = setInterval(tick, delay());
+ *   onCleanup(() => clearInterval(id));
+ * });
+ * ```
+ *
+ * @example Writing a signal an effect reads re-triggers it. Break the cycle with
+ * `untrack`, or make the write compare equal:
+ * ```ts
+ * effect(() => save(untrack(() => draft())));
+ * ```
+ *
+ * @returns Its disposer, for an effect created outside a root.
+ */
 export declare function effect<T>(fn: (prev?: T) => T | (() => void), value?: T): () => void;
+/**
+ * The rest of the `create` prefix, dropped.
+ *
+ * Each one calls through to the long name with the same arguments. Both spellings stay
+ * and mix freely; the graph does not know which was written.
+ *
+ * `onCleanup`, `getOwner` and `runWithOwner` keep their names. The rule here is losing
+ * a `create` that adds nothing, and none of those three has one; `cleanup` would also
+ * lose the sense that it registers a callback rather than performing one now.
+ */
+/**
+ * An owner scope with an explicit disposer.
+ *
+ * Every signal, memo, effect and nested scope created while `fn` runs belongs to this
+ * one, and `dispose()` takes all of them down together. Without an owner an effect has
+ * nothing to tear it down, which is the usual source of a leak.
+ *
+ * A root created inside another root is attached to it, so disposal is recursive. To
+ * detach deliberately, create the root where no owner is current.
+ *
+ * @example
+ * ```ts
+ * const stop = root((dispose) => {
+ *   effect(() => render(state()));
+ *   onCleanup(() => detachListeners());
+ *   return dispose;
+ * });
+ * stop();                         // effect and cleanup both run
+ * ```
+ *
+ * @returns Whatever `fn` returns. Return the disposer when the caller needs it.
+ */
+export declare function root<T>(fn: (dispose: () => void) => T): T;
+/**
+ * The effect form `@fluixi/dom` wires its bindings with.
+ *
+ * Timing is identical to {@link effect} in this runtime: both are eager, and both
+ * re-run in the task that wrote their dependency. The render-versus-commit distinction
+ * the name suggests is a DOM-layer concern, not a graph one, so do not reach for this
+ * expecting different scheduling.
+ *
+ * What differs is that it is not reported to devtools. Every DOM binding goes through
+ * here, and a graph carrying one node per text node is not a graph anyone reads.
+ *
+ * @example
+ * ```ts
+ * renderEffect(() => el.setAttribute('aria-expanded', String(open())));
+ * ```
+ */
+export declare function renderEffect<T>(fn: (prev?: T) => T | (() => void), value?: T): () => void;
+/**
+ * A tracked computation whose result nobody reads.
+ *
+ * Eager where {@link memo} is lazy. A memo that nothing reads never runs at all, so a
+ * memo written for its side effect silently does nothing; this is the form for work
+ * that has to happen on every change.
+ *
+ * Timing matches {@link effect}, and so does ordering: they run in creation order, not
+ * in two phases. A `computed` that writes a signal an effect reads has to be created
+ * first for the effect to see the settled value.
+ *
+ * @example
+ * ```ts
+ * computed(() => {
+ *   valid.set(email().includes('@'));   // derive into another signal
+ * });
+ * ```
+ *
+ * @example `prev` threads the last result through, with no signal to hold it:
+ * ```ts
+ * computed((runs = 0) => {
+ *   void query();
+ *   return runs + 1;
+ * }, 0);
+ * ```
+ */
+export declare function computed<T>(fn: (prev?: T) => T, value?: T): void;
+/**
+ * A context key: a value passed down an owner tree instead of through props.
+ *
+ * Lookup walks owners, not the DOM, so a consumer sees whatever provider encloses it
+ * reactively. A consumer with no provider above it gets `defaultValue`, which is why
+ * supplying one is usually better than handling undefined everywhere.
+ *
+ * Pass `name`. Unnamed, the key is a bare symbol and a devtools panel has nothing to
+ * label the node with.
+ *
+ * @example
+ * ```ts
+ * const Theme = context<'light' | 'dark'>('light', 'theme');
+ *
+ * // provider side, as a component
+ * Theme.Provider({ value: 'dark', children: () => renderPage() });
+ *
+ * // consumer side, anywhere below it
+ * const theme = useContext(Theme);   // 'dark' here, 'light' with no provider
+ * ```
+ */
+export declare function context<T>(defaultValue?: T, name?: string): Context<T>;
+/**
+ * A child scope of `parent`, created without entering it.
+ *
+ * Low level, and rarely the right tool. {@link root} both creates a scope and makes it
+ * current, which is what almost all code wants. This hands back an owner to hold and
+ * enter later with `runWithOwner`, for a scope whose lifetime does not match the call
+ * that created it: a cached subtree, or one list row among many.
+ *
+ * Disposing `parent` disposes this, since it is attached on creation.
+ *
+ * @example
+ * ```ts
+ * const scope = childOwner(getOwner());
+ * // later, and possibly from another task
+ * runWithOwner(scope, () => effect(() => paint(row())));
+ * ```
+ */
+export declare function childOwner(parent: Owner | null): Owner;
 //# sourceMappingURL=api.d.ts.map

package/dist/lib/signal/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/signal/api.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,qEAAqE;AACrE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAE/D,8DAA8D;AAC9D,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;AAExC,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AACjF,wBAAgB,MAAM,CAAC,CAAC,GAAG,SAAS,KAAK,YAAY,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAMrE,wBAAgB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEjG;AAED,kFAAkF;AAClF,wBAAgB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAEnF"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/signal/api.ts"],"names":[],"mappings":"AAiCA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,KAAK,EACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,qEAAqE;AACrE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AAE/D,8DAA8D;AAC9D,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AACjF,wBAAgB,MAAM,CAAC,CAAC,GAAG,SAAS,KAAK,YAAY,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAMrE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAEjG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAEnF;AAED;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,CAEzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAEzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAEtE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,GAAG,KAAK,CAEtD"}

package/dist/lib/signal/api.js

@@ -1,31 +1,226 @@
 /**
- * The short reactive API: `signal`, `memo`, `effect`.
+ * The short reactive API: the `create` prefix dropped, where dropping it loses nothing.
+ *
+ *   signal  memo  effect  root  renderEffect  computed  context  childOwner
  *
  *   const count = signal(0);
  *   count();          // read
  *   count.set(1);     // write
  *
- * `signal` is `createSignal` with the setter attached to the accessor instead of handed
- * back beside it. The function IS that accessor, so a read is the same call it always
- * was, `count` passes anywhere an accessor is expected, and only the write changes
- * spelling. `memo` is `createMemo` under a shorter name — a derived value has nothing to
- * set, so there is nothing to attach.
+ * `signal` is `createSignal` with the setter attached to the accessor rather than handed
+ * back beside it. The returned function is the accessor itself, so a read is the call it
+ * always was and `count` still passes anywhere an accessor is expected. Only the write
+ * changes spelling. `memo` is `createMemo` renamed and no more than that: a derived value
+ * has nothing to set, so there is nothing to attach.
+ *
+ * The rule across the API is to read a thing the way its shape implies. A call for a
+ * value, a property for an object (see `store`), and `.set()` to write.
  *
- * The rule across the API: read it the way its shape implies — a call for a value, a
- * property for an object (see `store`) — and `.set()` writes.
+ * The long names are unchanged and the two spellings are one primitive, so they mix
+ * freely. `onCleanup`, `getOwner` and `runWithOwner` are not here: they have no `create`
+ * to drop, and `cleanup` would read as performing one rather than registering one.
  *
- * `createSignal` and friends are unchanged; the two forms are one primitive and mix
- * freely.
+ * Two of these names promise scheduling they do not deliver, which the per-function
+ * docs say outright: `renderEffect` has the same timing as `effect`, and `computed` runs
+ * in creation order alongside it rather than in an earlier phase.
  */
-import { createEffect, createMemo, createSignal } from './graph/compat.js';
+import { createComputed, createEffect, createMemo, createRenderEffect, createSignal, } from './graph/compat.js';
+import { createChildOwner, createContext, createRoot, } from './graph/runtime.js';
 export function signal(value, options) {
     const [read, write] = createSignal(value, options);
     return Object.assign(read, { set: write });
 }
+/**
+ * A derived value, computed once per change and cached.
+ *
+ * Lazy and pull-based: the function does not run until something reads the memo, and
+ * then not again until one of its own dependencies changes. That is the difference from
+ * {@link computed}, which exists to do work rather than to hold a value.
+ *
+ * `prev` is the previous result, which makes an accumulator cheap without a second
+ * signal to hold it.
+ *
+ * @example
+ * ```ts
+ * const first = signal('Ada');
+ * const last = signal('Lovelace');
+ * const full = memo(() => `${first()} ${last()}`);
+ * full();                         // 'Ada Lovelace', computed now
+ * full();                         // cached, the function did not run again
+ * ```
+ *
+ * @example Reading the previous value:
+ * ```ts
+ * const high = memo((prev = 0) => Math.max(prev, reading()), 0);
+ * ```
+ */
 export function memo(fn, value, options) {
     return createMemo(fn, value, options);
 }
-/** Run `fn` and re-run it when anything it read changes. Returns its disposer. */
+/**
+ * Run `fn` now, and again whenever anything it read changes.
+ *
+ * Dependencies are collected by reading, not declared, so they are whatever the last
+ * run actually touched. A branch not taken subscribes to nothing, and a read behind a
+ * condition comes and goes with it.
+ *
+ * Eager. It runs once on creation and again as soon as a dependency is written, in the
+ * same task as the write. `batch` is what coalesces a group of writes into one run.
+ *
+ * Teardown goes through `onCleanup`, which runs before the next execution and once more
+ * on disposal. A returned function is **not** teardown: the return value is carried
+ * forward as the next call's `prev`, so returning a disposer silently leaks it. The
+ * effect is owned by the enclosing {@link root}, so disposing that disposes this.
+ *
+ * @example
+ * ```ts
+ * const query = signal('');
+ * effect(() => console.log('searching', query()));
+ * ```
+ *
+ * @example Teardown between runs, via onCleanup rather than a return:
+ * ```ts
+ * effect(() => {
+ *   const id = setInterval(tick, delay());
+ *   onCleanup(() => clearInterval(id));
+ * });
+ * ```
+ *
+ * @example Writing a signal an effect reads re-triggers it. Break the cycle with
+ * `untrack`, or make the write compare equal:
+ * ```ts
+ * effect(() => save(untrack(() => draft())));
+ * ```
+ *
+ * @returns Its disposer, for an effect created outside a root.
+ */
 export function effect(fn, value) {
     return createEffect(fn, value);
 }
+/**
+ * The rest of the `create` prefix, dropped.
+ *
+ * Each one calls through to the long name with the same arguments. Both spellings stay
+ * and mix freely; the graph does not know which was written.
+ *
+ * `onCleanup`, `getOwner` and `runWithOwner` keep their names. The rule here is losing
+ * a `create` that adds nothing, and none of those three has one; `cleanup` would also
+ * lose the sense that it registers a callback rather than performing one now.
+ */
+/**
+ * An owner scope with an explicit disposer.
+ *
+ * Every signal, memo, effect and nested scope created while `fn` runs belongs to this
+ * one, and `dispose()` takes all of them down together. Without an owner an effect has
+ * nothing to tear it down, which is the usual source of a leak.
+ *
+ * A root created inside another root is attached to it, so disposal is recursive. To
+ * detach deliberately, create the root where no owner is current.
+ *
+ * @example
+ * ```ts
+ * const stop = root((dispose) => {
+ *   effect(() => render(state()));
+ *   onCleanup(() => detachListeners());
+ *   return dispose;
+ * });
+ * stop();                         // effect and cleanup both run
+ * ```
+ *
+ * @returns Whatever `fn` returns. Return the disposer when the caller needs it.
+ */
+export function root(fn) {
+    return createRoot(fn);
+}
+/**
+ * The effect form `@fluixi/dom` wires its bindings with.
+ *
+ * Timing is identical to {@link effect} in this runtime: both are eager, and both
+ * re-run in the task that wrote their dependency. The render-versus-commit distinction
+ * the name suggests is a DOM-layer concern, not a graph one, so do not reach for this
+ * expecting different scheduling.
+ *
+ * What differs is that it is not reported to devtools. Every DOM binding goes through
+ * here, and a graph carrying one node per text node is not a graph anyone reads.
+ *
+ * @example
+ * ```ts
+ * renderEffect(() => el.setAttribute('aria-expanded', String(open())));
+ * ```
+ */
+export function renderEffect(fn, value) {
+    return createRenderEffect(fn, value);
+}
+/**
+ * A tracked computation whose result nobody reads.
+ *
+ * Eager where {@link memo} is lazy. A memo that nothing reads never runs at all, so a
+ * memo written for its side effect silently does nothing; this is the form for work
+ * that has to happen on every change.
+ *
+ * Timing matches {@link effect}, and so does ordering: they run in creation order, not
+ * in two phases. A `computed` that writes a signal an effect reads has to be created
+ * first for the effect to see the settled value.
+ *
+ * @example
+ * ```ts
+ * computed(() => {
+ *   valid.set(email().includes('@'));   // derive into another signal
+ * });
+ * ```
+ *
+ * @example `prev` threads the last result through, with no signal to hold it:
+ * ```ts
+ * computed((runs = 0) => {
+ *   void query();
+ *   return runs + 1;
+ * }, 0);
+ * ```
+ */
+export function computed(fn, value) {
+    createComputed(fn, value);
+}
+/**
+ * A context key: a value passed down an owner tree instead of through props.
+ *
+ * Lookup walks owners, not the DOM, so a consumer sees whatever provider encloses it
+ * reactively. A consumer with no provider above it gets `defaultValue`, which is why
+ * supplying one is usually better than handling undefined everywhere.
+ *
+ * Pass `name`. Unnamed, the key is a bare symbol and a devtools panel has nothing to
+ * label the node with.
+ *
+ * @example
+ * ```ts
+ * const Theme = context<'light' | 'dark'>('light', 'theme');
+ *
+ * // provider side, as a component
+ * Theme.Provider({ value: 'dark', children: () => renderPage() });
+ *
+ * // consumer side, anywhere below it
+ * const theme = useContext(Theme);   // 'dark' here, 'light' with no provider
+ * ```
+ */
+export function context(defaultValue, name) {
+    return createContext(defaultValue, name);
+}
+/**
+ * A child scope of `parent`, created without entering it.
+ *
+ * Low level, and rarely the right tool. {@link root} both creates a scope and makes it
+ * current, which is what almost all code wants. This hands back an owner to hold and
+ * enter later with `runWithOwner`, for a scope whose lifetime does not match the call
+ * that created it: a cached subtree, or one list row among many.
+ *
+ * Disposing `parent` disposes this, since it is attached on creation.
+ *
+ * @example
+ * ```ts
+ * const scope = childOwner(getOwner());
+ * // later, and possibly from another task
+ * runWithOwner(scope, () => effect(() => paint(row())));
+ * ```
+ */
+export function childOwner(parent) {
+    return createChildOwner(parent);
+}