@dougongjs/reactive 0.8.3 → 0.10.0

package/README.md

@@ -1,91 +1,33 @@
 # @dougongjs/reactive
 
-[简体中文](#简体中文) · [English](#english)
+Independent synchronous signals and structurally owned reactive generations. No external runtime dependencies.
 
----
-
-## 简体中文
-
-**零依赖**的响应式原语：`signal` / `computed` / `batch` / `observe`。
-
-```sh
-npm install @dougongjs/reactive
-```
-
-```ts
-import { signal, computed, batch, observe } from "@dougongjs/reactive"
-
-const count = signal(0)
-const double = computed(() => count.get() * 2)
-
-batch(() => count.set(21))
-double.get()
-```
-
-`double.get()` 返回 `42`。
-
-`computed` 是惰性的，依赖动态追踪。`batch` 按订阅身份合并回调内的重复通知。三者都拒绝异步回调——同步追踪和批次边界不能跨越 `await`，与其产生静默的错误结果，不如立刻抛错。
-
-### observe：把值的变化编译成资源的重建
-
-```ts
-observe(owner, source, (value, lifetime) => {
-  const socket = new WebSocket(value)
-  lifetime.cleanup(() => socket.close())
-})
-```
-
-每次 `source` 变化：先释放上一个 `lifetime`，再用新值建一个新的。
-
-`observe()` 与 `@dougongjs/core` **互不依赖**——它是一个作用在结构化 `ObservationOwner`（提供 `cleanup` / `lifetime` / `spawn`）上的自由函数，所以能驱动 Core 的 Lifetime，而 Core 不需要知道它存在。插件的 `ctx` 恰好满足这个形状。
-
-`source` 只需满足结构化的 `Readable<T>`（`get()` + `subscribe()`）——Signal、Core 的 `ContributionView`、诊断视图，甚至你自己写的对象都可以。
-
----
-
-## English
-
-**Zero-dependency** reactive primitives: `signal` / `computed` / `batch` / `observe`.
-
-```sh
-npm install @dougongjs/reactive
-```
-
-```ts
-import { signal, computed, batch, observe } from "@dougongjs/reactive"
-
-const count = signal(0)
-const double = computed(() => count.get() * 2)
-
-batch(() => count.set(21))
-double.get()
-```
-
-`double.get()` returns `42`.
-
-`computed` is lazy with dynamic dependency tracking. `batch` coalesces repeated notifications per subscription identity. All three reject asynchronous callbacks — synchronous tracking and batch boundaries cannot survive an `await`, and throwing immediately beats producing a silently wrong result.
-
-### observe: compiling value change into resource rebuild
+Upgrading from 0.8.3? Read the [migration guide](https://tangerg.github.io/dougong/en/guide/migrating-to-0.9) and [0.9.0 release notes](https://tangerg.github.io/dougong/en/reference/release-0.9.0).
 
 ```ts
-observe(owner, source, (value, lifetime) => {
-  const socket = new WebSocket(value)
-  lifetime.cleanup(() => socket.close())
-})
+import { batch, computed, disposeSymbol, signal } from "@dougongjs/reactive";
+
+const first = signal("Dougong");
+const last = signal("Plugins");
+const title = computed(() => `${first.get()} ${last.get()}`);
+const subscription = title.subscribe(() => render(title.get()));
+batch(() => {
+  first.set("Typed");
+  last.set("Composition");
+});
+subscription[disposeSymbol]();
 ```
 
-On each change to `source`: release the previous `lifetime`, then build a new one from the new value.
+`Readable<T>` exposes `get()` and `subscribe()`. The subscription implements standard `Symbol.dispose`; callbacks notify changes without replay. `bridge(owner, readable)` adapts another module copy or implementation into the local dependency graph. Its subscription and terminal detachment belong to the supplied owner through `defer`.
 
-`observe()` and `@dougongjs/core` are **mutually independent** — it is a free function over a structural `ObservationOwner` (anything providing `cleanup` / `lifetime` / `spawn`), so it can drive Core Lifetimes without Core knowing it exists. A plugin's `ctx` happens to satisfy that shape.
+`batch`, `computed`, `subscribe` and `observe` require synchronous callbacks in both their types and runtime checks. Direct Promise results, PromiseLike results and mixed asynchronous branches are rejected, including when a caller explicitly supplies `void`. Ordinary synchronous return values remain inferred; `Observer<T, Child, Result>` can describe an explicit non-void result. Values whose type was already erased still receive the runtime check.
 
-`source` need only satisfy the structural `Readable<T>` (`get()` + `subscribe()`) — a signal, Core's `ContributionView`, a diagnostics view, or your own object.
+`observe(owner, readable, observer)` disposes the previous child before building the next one. The structural owner supplies `child`, `defer` and `spawn`; only the returned child needs `Symbol.asyncDispose`; no framework base class is required. Use `generation.spawn` for asynchronous observer work.
 
----
+`ObservationTask` describes completion only: it is not generic, and its `result` is `PromiseLike<unknown>`. The required `spawn` accepts a task returning `void | PromiseLike<void>`. Owners may provide a richer generic task API without coupling observation to their result payloads.
 
-- 文档站 / Documentation: https://tangerg.github.io/dougong/
-- 仓库 / Repository: https://github.com/Tangerg/dougong
+Results inheriting this module's realm's `Promise.prototype` select the intrinsic native protocol, including decorated local Promises and subclasses. Other results use one captured structural `then`; display tags do not select a protocol. Foreign Promises must expose a conforming public `then`. Adapt decorated foreign results in their origin realm, and box payloads there when another assimilation would change them. See the guide for the precise boundary and disposal guarantees.
 
-> 早期 0.x 开发阶段，当前不承诺向后兼容。需要 Node.js ≥ 22，或 Chrome / Edge 119、Firefox 121、Safari 17.4 及以上浏览器 / WebView。
-> Early 0.x development; no backward-compatibility promises yet. Requires Node.js ≥ 22, or Chrome / Edge 119, Firefox 121 or Safari 17.4 and later.
+ESM; <!-- runtime-baseline:start -->Node.js `^24.22.0 || >=26.10.0`, Chrome ≥ 119, Edge ≥ 119, Firefox ≥ 124, Safari ≥ 17.4<!-- runtime-baseline:end -->.
 
-MIT
+[Guide](https://tangerg.github.io/dougong/en/guide/reactive)

package/dist/abort.d.ts

@@ -0,0 +1,4 @@
+export declare function isAborted(signal: AbortSignal): boolean;
+export declare function abortReason(signal: AbortSignal): unknown;
+export declare function onAbort(signal: AbortSignal, callback: (reason: unknown) => void): () => void;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEtD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAExD;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CA6B5F"}

package/dist/async-result.d.ts

@@ -0,0 +1,10 @@
+type WithoutCallableThen<T> = T extends object ? "then" extends keyof T ? Extract<T["then"], (...arguments_: never[]) => unknown> extends never ? T : never : T : T;
+export type SynchronousResult<T> = (T & NoInfer<WithoutCallableThen<T>>) | (T & undefined);
+export interface ResolvedValue<T> {
+    readonly value: T;
+}
+export declare function resolveValue<T>(value: T | PromiseLike<T>): Promise<ResolvedValue<Awaited<T>>>;
+export declare function assertSynchronous(value: unknown, message: string): void;
+export declare function captureThenable(value: unknown): Promise<ResolvedValue<unknown>> | undefined;
+export {};
+//# sourceMappingURL=async-result.d.ts.map

package/dist/async-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-result.d.ts","sourceRoot":"","sources":["../src/async-result.ts"],"names":[],"mappings":"AAIA,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,GAC1C,MAAM,SAAS,MAAM,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,SAAS,KAAK,GACnE,CAAC,GACD,KAAK,GACP,CAAC,GACH,CAAC,CAAC;AAIN,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AAE3F,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAGpC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAUvE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CA0B3F"}

package/dist/bridge.d.ts

@@ -0,0 +1,7 @@
+import { AsyncDisposable, Readable } from './protocol.js';
+import { ReadonlySignal } from './signals.js';
+export interface BridgeOwner {
+    readonly defer: (dispose: () => unknown) => AsyncDisposable;
+}
+export declare function bridge<T>(owner: BridgeOwner, source: Readable<T>): ReadonlySignal<T>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,eAAe,EAEpB,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAU,KAAK,cAAc,EAAe,MAAM,cAAc,CAAC;AAGxE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,OAAO,KAAK,eAAe,CAAC;CAC7D;AA4ID,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAmBpF"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { batch, computed, signal, type ReadonlySignal, type Signal } from './signals';
-export type { AsyncDisposable, Disposable, Readable } from './protocol';
-export { observe, type ObservationOwner, type ObservationTask, type Observer } from './observe';
+export { batch, computed, signal, type ReadonlySignal, type Signal } from './signals.js';
+export { bridge, type BridgeOwner } from './bridge.js';
+export { asyncDisposeSymbol, disposeSymbol, type AsyncDisposable, type Disposable, type Readable, } from './protocol.js';
+export { observe, type ObservationOwner, type ObservationTask, type Observer } from './observe.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AACtF,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,QAAQ,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC"}