@wcstack/signals

Which core? #

wcstack ships two reactive cores that drive the same wc-bindable I/O nodes. Pick the one that matches where your logic lives.

wcstackには同じwc-bindableタグ群を駆動する2つのリアクティブコアがある。ロジックの置き場所で選ぶ。

The reactive core #

import { signal, computed, effect } from "@wcstack/signals";

const count = signal(0);
const doubled = computed(() => count.get() * 2);

effect(() => {
  console.log(`count=${count.peek()}, doubled=${doubled.get()}`);
});

count.set(1); // effect re-runs → "count=1, doubled=2"

Scheduling model

Pull-validated three-color marking: a write marks direct observers dirty and transitive ones check. Effects run coalesced on a microtask; a computed that returns an equal value does not propagate downstream.

書き込みは直接の観測者をdirty、間接をcheckにマーク。エフェクトはマイクロタスクで合流実行。等値のcomputedは下流に伝播しない。

Async resources #

resource() — one value, switchMap semantics

Returns { value, loading, error, dispose }. The source(args, signal) receives an AbortSignal; when the reactive args change, the in-flight run is aborted and restarted.

argsが変わると実行中のリクエストは中断されて再実行(switchMap)。

import { signal, resource } from "@wcstack/signals";

const id = signal(1);
const user = resource(
  async (userId, signal) =>
    (await fetch(`/api/users/${userId}`, { signal })).json(),
  { args: () => id.get() },
);

id.set(2); // aborts the in-flight request, starts fresh

streamResource() — continuous flows, folded

Folds async iterables and ReadableStreams into a reactive value. Returns { value, status, error, dispose } with status one of "idle" | "active" | "done" | "error". The tag-side counterpart is $streams in <wcs-state>.

非同期イテラブルやReadableStreamをリアクティブな値に畳み込む。タグ側の対応物が<wcs-state>の$streams。

import { streamResource } from "@wcstack/signals";

const log = streamResource(
  (args, signal) => openLogStream(signal),
  {
    fold: (acc, chunk) => [...(acc ?? []), chunk],
    initial: [],
  },
);
// log.value / log.status / log.error

The DOM layer #

Imported from @wcstack/signals/dom (which re-exports the core). h(tag, props, ...children) builds real DOM once; function or signal props and children wire targeted effects — only that binding updates. No VDOM reconciler ships.

h()は本物のDOMを一度だけ構築。関数/シグナルのprops・childrenが対象限定のエフェクトを張り、その箇所だけが更新される。VDOMなし。

A reactive custom element

import { signal, computed, h, SignalsElement } from "@wcstack/signals/dom";

class SignalCounter extends SignalsElement {
  count = signal(0);
  doubled = computed(() => this.count.get() * 2);

  render() {
    return h("div", { class: "counter" },
      h("button", { onClick: () => this.count.set(this.count.peek() - 1) }, "−"),
      h("output", null, () => String(this.count.get())),
      h("button", { onClick: () => this.count.set(this.count.peek() + 1) }, "+"),
      h("span", { class: "muted" }, () => `×2 = ${this.doubled.get()}`),
    );
  }
}
customElements.define("signal-counter", SignalCounter);

Keyed lists: For / Index #

For(list, each, options?) reconciles by key — rows are reused and moved when items shuffle. Index(list, each) keys by position — each slot's row is stable, the item arrives as a getter. Bare reactive children rebuild wholly; use these for lists.

Forはキーで照合し行を再利用・移動。Indexは位置で照合し、要素はゲッターで届く。素のリアクティブchildは全再構築されるため、リストには必ずこれらを使う。

import { signal, h, For, Index } from "@wcstack/signals/dom";

const todos = signal([{ id: 1, text: "a" }, { id: 2, text: "b" }]);

// For — keyed by id; each(item, index: () => number)
h("ul", null,
  For(todos, (t, index) => h("li", null, () => `${index()}: ${t.text}`),
    { key: (t) => t.id }),
);

// Index — position-keyed; each(item: () => T, index: number)
const nums = signal([10, 20, 30]);
h("ul", null,
  Index(nums, (n) => h("li", null, () => String(n() * 2))),
);

JSX (opt-in) #

h has the classic JSX factory shape — no JSX ships by default, but transpilation is one config away. Reactive bits stay thunks or signals ({() => count.get()}). Not implemented: ref, context, controlled inputs, and the key attribute — use For / Index for keyed lists.

hはクラシックJSXファクトリ形。リアクティブな箇所はサンク/シグナルのまま書く。ref・context・key属性は非対応(リストはFor/Index)。

// tsconfig.json
{
  "compilerOptions": {
    "jsx": "react",
    "jsxFactory": "h",
    "jsxFragmentFactory": "Fragment"
  }
}

import { h, Fragment, signal, render } from "@wcstack/signals/dom";

const count = signal(0);
const view = (
  <button onClick={() => count.set(count.peek() + 1)}>
    count: {() => count.get()}
  </button>
);
render(view, document.body);

Binding I/O nodes: bindNode #

bindNode(target, descriptor?) bridges any wc-bindable element — all 30+ wcstack I/O nodes — into signals. IO is the node, reactivity is the core: the element has no signal awareness.

bindNodeがwc-bindable要素をシグナルに橋渡しする。要素側はシグナルを一切知らない。

nodeSource(bound, run, { abort? }) wraps a node as a resource source, wiring the resource's AbortSignal to the node's cancel command (default "abort").

Example: a search UI over <wcs-fetch>

import { signal, computed, effect, createRoot, bindNode, h, render, For }
  from "@wcstack/signals/dom";

const bound = bindNode(fetchEl);
const query = signal("");
const people = computed(() => bound.signals.value.get() ?? []);

createRoot(() => {
  effect(() => {
    const q = query.get().trim();
    bound.set("url", q ? `/api/people?q=${encodeURIComponent(q)}` : "/api/people");
  });

  render(
    h("div", null,
      h("input", { type: "search", onInput: (e) => query.set(e.target.value) }),
      h("p", null, () => bound.signals.loading.get() ? "Loading…"
        : `${people.get().length} result(s)`),
      h("ul", null, For(() => people.get(),
        (p) => h("li", null, p.name), { key: (p) => p.id })),
    ),
    document.getElementById("search-app"),
  );
});

Typed NodeShape

import { bindNode, NodeShape } from "@wcstack/signals";

interface FetchShape extends NodeShape {
  signals:  { value: Person[]; loading: boolean };
  inputs:   { url: string };
  commands: { fetch: (url: string) => Promise<Person[]>; abort: () => void };
}

const bound = bindNode<FetchShape>(fetchEl, FetchCore.wcBindable);
bound.signals.value.get();       // ReadSignal<Person[]>
bound.set("url", "/api/people"); // string enforced
bound.command("fetch", "/api");

Error handling #

• Isolated, never swallowed: an exception thrown from an effect body or a computed refresh during a flush is handed to globalThis.reportError (dispatching the window error event) or console.error. It is never re-thrown into unrelated code — and never silently dropped.
• Direct reads still throw: isolation applies only to the scheduled drain; get() / peek() propagate to the caller.
• Runaway-cycle guard: the only throw that escapes a flush is overflowing the hard iteration cap (MAX_FLUSH_ITERATIONS) — the signature of an effect writing a tracked signal with an ever-changing value.
• DisposedError: mutating BoundNode methods throw after dispose(). Detect with the brand-based, realm-safe isDisposedError(err).

try {
  bound.command("abort");
} catch (err) {
  if (!isDisposedError(err)) throw err;
}

Development mode #

Set globalThis.__WCS_DEV__ = true before your code runs to enable diagnostics:

コード実行前に__WCS_DEV__を有効にすると診断が出る。

Stability & support #

Within v1.x, stable APIs keep backward compatibility; evolving APIs may adjust in minor releases.

Browser support & SSR

• Language target: ES2022 — Chrome/Edge 94+, Firefox 90+, Safari 16.4+.
• Required runtime features: queueMicrotask, AbortController, WeakMap / WeakSet; ReadableStream + async iteration for streamResource only.
• Non-DOM safe: the . entry is fully non-DOM; ./dom evaluates without a DOM (SSR pre-pass safe) but its DOM-touching surface needs DOM globals when used — createSignalsElement() gives a clear error otherwise.
• Not in v1: SSR hydration, deep reactivity, stream backpressure.

コアは非DOM環境で完全動作。./domエントリの評価自体はSSRセーフ。v1にはSSRハイドレーション・深いリアクティビティ・バックプレッシャはない。

Install

npm install @wcstack/signals

Entry points: @wcstack/signals (core, resources, adapter) and @wcstack/signals/dom (h, render, Fragment, For, Index, SignalsElement, plus re-exported core).