@dougongjs/reactive 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Dougong contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,12 @@
+# @dougongjs/reactive
+
+零依赖的响应式原语：`signal` / `computed` / `batch` / `observe`。
+
+与 `@dougongjs/core` 互不依赖——`observe()` 是一个作用在结构化 `ObservationOwner` 上的自由函数，因此可以驱动 Core 的 Lifetime，而 Core 不需要知道它存在。
+
+- 文档站：https://tangerg.github.io/dougong/
+- 仓库：https://github.com/Tangerg/dougong
+
+> 早期开发阶段（0.0.x），当前不承诺向后兼容。需要 Node.js >= 22 或等价的 ES2024 宿主。
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { Readable } from './protocol';
+export type { Disposable, Readable } from './protocol';
+declare const dougongSignal: unique symbol;
+/** A reactive node created by Dougong and safe to compose with computed(). */
+export interface ReadonlySignal<T> extends Readable<T> {
+    readonly [dougongSignal]: true;
+}
+export interface Signal<T> extends ReadonlySignal<T> {
+    set(value: T): void;
+}
+export { observe, type ObservationLifetime, type ObservationOwner, type ObservationTask, type Observer, } from './observe';
+export declare function batch<T>(callback: () => T): T;
+export declare function signal<T>(initialValue: T): Signal<T>;
+export declare function computed<T>(calculate: () => T): ReadonlySignal<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGvD,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,CAAC,MAAM,aAAa,EAAE,OAAO,MAAM,CAAC;AAE3C,8EAA8E;AAC9E,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,MAAM,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAC;IAClD,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACrB;AAED,OAAO,EACL,OAAO,EACP,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,QAAQ,GACd,MAAM,WAAW,CAAC;AAyFnB,wBAAgB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CA4B7C;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAkCpD;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAGjE"}

package/dist/index.js

@@ -0,0 +1,340 @@
+function d(e, t) {
+  if (b(e))
+    throw Promise.resolve(e).catch(() => {
+    }), new TypeError(t);
+}
+function b(e) {
+  return e === null || typeof e != "object" && typeof e != "function" ? !1 : typeof e.then == "function";
+}
+class E {
+  #i;
+  #t;
+  #r;
+  #h;
+  #n;
+  #e = { present: !1 };
+  #o = !1;
+  #s = "active";
+  #a;
+  #c;
+  #u;
+  constructor(t, s, i) {
+    this.#i = t, this.#t = s, this.#r = i;
+  }
+  start() {
+    const t = this.#t.get(), s = this.#i.lifetime("observation");
+    l(s), this.#n = s;
+    const i = this.#t.subscribe(() => this.#w());
+    v(i, "Readable.subscribe()"), this.#h = i, this.#l(t, s), this.#e = { present: !0, value: t };
+    const n = this.#i.spawn((r) => this.#y(r));
+    T(n), this.#a = n, n.result.then(
+      () => this.#v(n),
+      () => this.#v(n)
+    );
+  }
+  dispose() {
+    if (this.#u) return this.#u;
+    const t = Promise.withResolvers();
+    return this.#u = t.promise, this.#s = "disposed", this.#c?.(), this.#f().then(t.resolve, t.reject), t.promise;
+  }
+  async #f() {
+    const t = [];
+    if (await c(this.#b(), t), await c(this.#O(), t), await c(this.#p(), t), t.length === 1) throw t[0];
+    if (t.length > 1) throw new AggregateError(t, "Observation cleanup failed");
+  }
+  #w() {
+    this.#s === "active" && (this.#o = !0, this.#c?.());
+  }
+  async #y(t) {
+    try {
+      for (; this.#s === "active" && !t.aborted; )
+        for (await this.#m(t); this.#s === "active" && !t.aborted && this.#o; )
+          this.#o = !1, await this.#g();
+    } catch (s) {
+      if (this.#s === "stopped") throw s;
+      await this.#d([s], "Observation stopped after a replacement failed");
+    }
+  }
+  #m(t) {
+    return this.#o || this.#s !== "active" || t.aborted ? Promise.resolve() : new Promise((s) => {
+      const i = () => {
+        t.removeEventListener("abort", i), this.#c === i && (this.#c = void 0), s();
+      };
+      this.#c = i, t.addEventListener("abort", i, { once: !0 }), (this.#o || this.#s !== "active" || t.aborted) && i();
+    });
+  }
+  async #g() {
+    if (this.#s !== "active") return;
+    const t = this.#t.get();
+    if (this.#e.present && Object.is(t, this.#e.value)) return;
+    const s = this.#p();
+    if (s)
+      try {
+        await s.dispose();
+      } catch (n) {
+        return this.#d(
+          [n],
+          "Observation stopped because the previous lifetime could not be disposed"
+        );
+      }
+    if (this.#e = { present: !1 }, this.#s !== "active") return;
+    const i = this.#i.lifetime("observation");
+    l(i);
+    try {
+      this.#l(t, i);
+    } catch (n) {
+      try {
+        await i.dispose();
+      } catch (r) {
+        return this.#d(
+          [n, r],
+          "Observation callback failed and its resources could not be cleaned up"
+        );
+      }
+      throw n;
+    }
+    this.#n = i, this.#e = { present: !0, value: t };
+  }
+  #l(t, s) {
+    const i = this.#r(t, s);
+    d(i, "Observers must be synchronous; use lifetime.spawn() for async work");
+  }
+  #b() {
+    const t = this.#h;
+    return this.#h = void 0, t;
+  }
+  #p() {
+    const t = this.#n;
+    return this.#n = void 0, t;
+  }
+  #O() {
+    const t = this.#a;
+    return this.#a = void 0, t;
+  }
+  #v(t) {
+    this.#a === t && (this.#a = void 0);
+  }
+  async #d(t, s) {
+    throw this.#s = "stopped", this.#c?.(), await c(this.#b(), t), await c(this.#p(), t), t.length === 1 ? t[0] : new AggregateError(t, s);
+  }
+}
+function j(e, t, s) {
+  if (!t || typeof t.get != "function" || typeof t.subscribe != "function")
+    throw new TypeError("observe() expects a readable source");
+  if (typeof s != "function") throw new TypeError("Observer must be a function");
+  if (!e || typeof e.cleanup != "function" || typeof e.lifetime != "function" || typeof e.spawn != "function")
+    throw new TypeError("observe() expects an observation owner");
+  const i = new E(e, t, s), n = e.cleanup(() => i.dispose());
+  v(n, "ObservationOwner.cleanup()");
+  try {
+    return i.start(), n;
+  } catch (r) {
+    throw i.dispose().catch(() => {
+    }), r;
+  }
+}
+function v(e, t) {
+  if (!e || typeof e.dispose != "function")
+    throw new TypeError(`${t} must return a Disposable`);
+}
+function l(e) {
+  if (!e || typeof e.dispose != "function" || typeof e.cleanup != "function" || typeof e.lifetime != "function" || typeof e.spawn != "function")
+    throw new TypeError("ObservationOwner.lifetime() must return an ObservationLifetime");
+}
+function T(e) {
+  if (!e || typeof e.dispose != "function" || !b(e.result))
+    throw new TypeError("ObservationOwner.spawn() must return an ObservationTask");
+}
+async function c(e, t) {
+  if (e)
+    try {
+      await e.dispose();
+    } catch (s) {
+      t.push(s);
+    }
+}
+let u = 0, a, f;
+const p = /* @__PURE__ */ new WeakMap();
+function w(e) {
+  return new S(e);
+}
+class S {
+  #i;
+  constructor(t) {
+    this.#i = t, Object.freeze(this);
+  }
+  dispose() {
+    const t = this.#i;
+    this.#i = void 0, t?.();
+  }
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+}
+function z() {
+  const e = [];
+  for (; a?.size; ) {
+    const t = a;
+    a = /* @__PURE__ */ new Set(), m(t, e);
+  }
+  a = void 0, g(e);
+}
+function y(e) {
+  if (u) {
+    const s = a ??= /* @__PURE__ */ new Set();
+    for (const i of e) s.add(i);
+    return;
+  }
+  const t = [];
+  m([...e], t), g(t);
+}
+function m(e, t) {
+  for (const s of e)
+    try {
+      s();
+    } catch (i) {
+      t.push(i);
+    }
+}
+function g(e) {
+  if (e.length === 1) throw e[0];
+  if (e.length > 1)
+    throw new AggregateError(e, "Reactive subscribers failed");
+}
+function O(e) {
+  f?.(e);
+}
+function C(e) {
+  if (typeof e != "function") throw new TypeError("batch() expects a function");
+  u++;
+  let t;
+  try {
+    const s = e();
+    d(s, "Reactive batches must be synchronous"), t = { ok: !0, value: s };
+  } catch (s) {
+    t = { ok: !1, error: s };
+  } finally {
+    u--;
+  }
+  if (!u)
+    try {
+      z();
+    } catch (s) {
+      t = t.ok ? { ok: !1, error: s } : { ok: !1, error: new AggregateError([t.error, s], "Reactive batch failed") };
+    }
+  if (!t.ok) throw t.error;
+  return t.value;
+}
+function D(e) {
+  let t = e, s = 0;
+  const i = /* @__PURE__ */ new Set(), n = {
+    get() {
+      return O(n), t;
+    },
+    set(r) {
+      Object.is(t, r) || (t = r, s++, y(i));
+    },
+    subscribe(r) {
+      return k(r), i.add(r), w(() => i.delete(r));
+    }
+  };
+  return p.set(n, {
+    get version() {
+      return s;
+    },
+    refresh() {
+    }
+  }), Object.freeze(n);
+}
+function R(e) {
+  if (typeof e != "function") throw new TypeError("computed() expects a function");
+  return new L(e).view;
+}
+class L {
+  #i;
+  #t = /* @__PURE__ */ new Set();
+  #r = /* @__PURE__ */ new Map();
+  #h = { phase: "uninitialized" };
+  #n = !1;
+  #e = !0;
+  #o = 0;
+  view;
+  constructor(t) {
+    this.#i = t, this.view = Object.freeze({
+      get: () => this.#s(),
+      subscribe: (s) => this.#a(s)
+    }), p.set(this.view, this);
+  }
+  get version() {
+    return this.#o;
+  }
+  refresh() {
+    this.#f();
+  }
+  #s() {
+    return O(this.view), this.#f();
+  }
+  #a(t) {
+    k(t);
+    const s = this.#t.size === 0;
+    if (this.#t.add(t), s)
+      try {
+        this.#e = !0, this.#f();
+      } catch (i) {
+        throw this.#t.delete(t), this.#t.size || this.#u(), i;
+      }
+    return w(() => {
+      this.#t.delete(t), this.#t.size || this.#u();
+    });
+  }
+  #c = () => {
+    this.#e || (this.#e = !0, y(this.#t));
+  };
+  #u() {
+    for (const t of this.#r.values())
+      t.subscription?.dispose(), t.subscription = void 0;
+  }
+  #f() {
+    const t = this.#h;
+    if (t.phase === "cached" && !this.#e) {
+      for (const r of this.#r.values())
+        if (r.node.refresh(), r.version !== r.node.version) {
+          this.#e = !0;
+          break;
+        }
+      if (!this.#e) return t.value;
+    }
+    if (this.#n) throw new TypeError("Circular computed signal");
+    const s = /* @__PURE__ */ new Set(), i = f;
+    this.#n = !0, f = (r) => s.add(r);
+    let n;
+    try {
+      n = this.#i(), d(n, "Computed signal calculations must be synchronous");
+    } finally {
+      f = i, this.#n = !1;
+    }
+    for (const [r, o] of this.#r)
+      s.has(r) || (o.subscription?.dispose(), this.#r.delete(r));
+    for (const r of s) {
+      const o = p.get(r);
+      if (!o) continue;
+      const h = this.#r.get(r) ?? {
+        node: o,
+        version: o.version,
+        subscription: void 0
+      };
+      h.version = o.version, this.#t.size && !h.subscription && (h.subscription = r.subscribe(this.#c)), this.#r.set(r, h);
+    }
+    return (t.phase === "uninitialized" || !Object.is(t.value, n)) && this.#o++, this.#h = { phase: "cached", value: n }, this.#e = !1, n;
+  }
+}
+function k(e) {
+  if (typeof e != "function")
+    throw new TypeError("Signal subscriber must be a function");
+}
+export {
+  C as batch,
+  R as computed,
+  j as observe,
+  D as signal
+};

package/dist/observe.d.ts

@@ -0,0 +1,21 @@
+import { Disposable, Readable } from './protocol';
+export interface ObservationTask<T = void> extends Disposable {
+    readonly result: Promise<T>;
+}
+export interface ObservationLifetime extends Disposable {
+    cleanup(dispose: () => unknown): Disposable;
+    lifetime(label: string): ObservationLifetime;
+    spawn<T>(task: (signal: AbortSignal) => T | PromiseLike<T>): ObservationTask<T>;
+}
+export interface ObservationOwner<Child extends ObservationLifetime = ObservationLifetime> {
+    cleanup(dispose: () => unknown): Disposable;
+    lifetime(label: string): Child;
+    spawn<T>(task: (signal: AbortSignal) => T | PromiseLike<T>): ObservationTask<T>;
+}
+export type Observer<T, Child extends ObservationLifetime> = (value: T, lifetime: Child) => void;
+/**
+ * Lifetime-aware synchronization built only from the public source and
+ * Lifetime protocols. It is a reactive-layer combinator, not a Core hook.
+ */
+export declare function observe<T, Child extends ObservationLifetime>(owner: ObservationOwner<Child>, source: Readable<T>, observer: Observer<T, Child>): Disposable;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGvD,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,IAAI,CAAE,SAAQ,UAAU;IAC3D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,OAAO,CAAC,OAAO,EAAE,MAAM,OAAO,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAAC;IAC7C,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,gBAAgB,CAAC,KAAK,SAAS,mBAAmB,GAAG,mBAAmB;IACvF,OAAO,CAAC,OAAO,EAAE,MAAM,OAAO,GAAG,UAAU,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;IAC/B,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;CACjF;AAED,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,KAAK,SAAS,mBAAmB,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,KAAK,IAAI,CAAC;AA+KjG;;;GAGG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,SAAS,mBAAmB,EAC1D,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC9B,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,EACnB,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,KAAK,CAAC,GAC3B,UAAU,CA0BZ"}

package/dist/protocol.d.ts

@@ -0,0 +1,11 @@
+export interface Disposable {
+    dispose(): void | Promise<void>;
+    [Symbol.dispose]?(): void;
+    [Symbol.asyncDispose]?(): Promise<void>;
+}
+/** Structural observable protocol shared by signals, extensions and diagnostics. */
+export interface Readable<T> {
+    get(): T;
+    subscribe(listener: () => void): Disposable;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC;IAC1B,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED,oFAAoF;AACpF,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,GAAG,IAAI,CAAC,CAAC;IACT,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,UAAU,CAAC;CAC7C"}

package/dist/sync-result.d.ts

@@ -0,0 +1,3 @@
+export declare function assertSynchronous(value: unknown, message: string): void;
+export declare function isThenable(value: unknown): value is PromiseLike<unknown>;
+//# sourceMappingURL=sync-result.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync-result.d.ts","sourceRoot":"","sources":["../src/sync-result.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQvE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAGxE"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dougongjs/reactive",
+  "version": "0.0.1",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "description": "Zero-dependency signal, computed, batch and observe primitives.",
+  "license": "MIT",
+  "author": "Dougong contributors",
+  "homepage": "https://tangerg.github.io/dougong/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tangerg/dougong.git",
+    "directory": "packages/reactive"
+  },
+  "bugs": {
+    "url": "https://github.com/Tangerg/dougong/issues"
+  },
+  "keywords": [
+    "plugin",
+    "plugin-system",
+    "dependency-injection",
+    "lifetime",
+    "service-container",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}