@bindtty/signal 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,51 @@
+# @bindtty/signal
+
+BindTTY 响应式内核。提供 signal、computed、effect 与订阅清理，供 runtime binding 与 widget 内部状态使用。
+
+## API
+
+```ts
+import { createSignal, computed, effect } from "@bindtty/signal";
+
+const count = createSignal(0);
+const label = computed(() => `Count: ${count.get()}`);
+
+effect(() => {
+  console.log(label.get());
+});
+
+count.set(1);
+count.subscribe((value) => { /* ... */ });
+```
+
+- `createSignal(initial)` — 可写 signal
+- `computed(fn)` — 派生只读 signal
+- `effect(fn)` — 副作用，返回 dispose
+- `ReadableSignal.subscribe(listener)` — binding 层建立订阅
+
+## Counter 示例
+
+```ts
+import { createSignal, computed } from "@bindtty/signal";
+
+class CounterVM {
+  count = createSignal(0);
+  countLabel = computed(() => `Count: ${this.count.get()}`);
+  inc = () => this.count.set(this.count.get() + 1);
+}
+```
+
+View 中绑定 `vm.countLabel`，signal 更新后由 runtime binding 驱动局部 repaint，无需整树重渲染。
+
+## 单实例要求
+
+`@bindtty/signal` 在模块内维护 `computationStack` 与订阅图，**全应用只能有一份物理拷贝**。若应用与 `@bindtty/widgets` 各解析到不同版本的 signal，computed 与 binding 可能异常。
+
+- 推荐从 `bindtty` 导入（re-export 同源 signal）
+- 若单独安装本包，版本须与 `bindtty` / `@bindtty/widgets` 的 peer 声明一致
+- 检查：`npm ls @bindtty/signal` 应只有一棵树、一个版本
+
+## 文档
+
+- [doc/architecture/ROADMAP.md](../../doc/architecture/ROADMAP.md) — 实现计划
+- [doc/architecture/DESIGN.md](../../doc/architecture/DESIGN.md) — MVVM binding 模型

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type Dispose = () => void;
+export type SignalListener<T> = (value: T, previousValue: T) => void;
+export type EffectCleanup = void | Dispose;
+export interface ReadableSignal<T> {
+    get(): T;
+    subscribe(listener: SignalListener<T>): Dispose;
+}
+export interface Signal<T> extends ReadableSignal<T> {
+    set(value: T): void;
+}
+export declare function createSignal<T>(initialValue: T): Signal<T>;
+export declare function computed<T>(derive: () => T): ReadableSignal<T>;
+export declare function effect(runEffect: () => EffectCleanup): Dispose;

package/dist/index.js

@@ -0,0 +1,160 @@
+const computationStack = [];
+function getActiveComputation() {
+    return computationStack[computationStack.length - 1];
+}
+function cleanupDependencies(computation) {
+    // 重新运行前先解除旧依赖，否则条件分支切换后会继续响应已经不再读取的 signal。
+    for (const dependency of computation.dependencies) {
+        dependency.removeSubscriber(computation.run);
+    }
+    computation.dependencies.clear();
+}
+function trackDependency(source) {
+    const computation = getActiveComputation();
+    if (!computation || computation.disposed || computation.dependencies.has(source)) {
+        return;
+    }
+    computation.dependencies.add(source);
+    source.addSubscriber(computation.run);
+}
+function createComputation(runBody) {
+    const computation = {
+        dependencies: new Set(),
+        disposed: false,
+        run: () => {
+            if (computation.disposed) {
+                return;
+            }
+            cleanupDependencies(computation);
+            // 用栈而不是单个全局变量，是为了支持 computed/effect 嵌套执行。
+            // 栈顶永远是当前正在收集依赖的 computation。
+            computationStack.push(computation);
+            try {
+                runBody();
+            }
+            finally {
+                // 即使 runBody 抛错，也必须弹栈，否则后续 get() 会被错误地追踪到旧 computation。
+                computationStack.pop();
+            }
+        }
+    };
+    return computation;
+}
+function notifySubscribers(subscribers) {
+    // 复制一份再遍历，避免 subscriber 执行时增删订阅者导致本轮通知顺序变得不可预测。
+    for (const subscriber of [...subscribers]) {
+        subscriber();
+    }
+}
+function notifyListeners(listeners, value, previousValue) {
+    for (const listener of [...listeners]) {
+        listener(value, previousValue);
+    }
+}
+export function createSignal(initialValue) {
+    let currentValue = initialValue;
+    const subscribers = new Set();
+    const listeners = new Set();
+    const source = {
+        addSubscriber(subscriber) {
+            subscribers.add(subscriber);
+        },
+        removeSubscriber(subscriber) {
+            subscribers.delete(subscriber);
+        }
+    };
+    return {
+        get() {
+            // 如果当前处在 computed/effect 执行中，这次读取会把当前 signal 记录为依赖。
+            trackDependency(source);
+            return currentValue;
+        },
+        set(value) {
+            if (Object.is(currentValue, value)) {
+                return;
+            }
+            const previousValue = currentValue;
+            currentValue = value;
+            // 先通知响应式订阅者，让 computed/effect 重新计算；
+            // 再通知显式 subscribe(listener)，让用户拿到稳定的新旧值。
+            notifySubscribers(subscribers);
+            notifyListeners(listeners, currentValue, previousValue);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        }
+    };
+}
+export function computed(derive) {
+    let initialized = false;
+    let currentValue;
+    const subscribers = new Set();
+    const listeners = new Set();
+    const source = {
+        addSubscriber(subscriber) {
+            subscribers.add(subscriber);
+        },
+        removeSubscriber(subscriber) {
+            subscribers.delete(subscriber);
+        }
+    };
+    const computation = createComputation(() => {
+        const nextValue = derive();
+        if (initialized && Object.is(currentValue, nextValue)) {
+            return;
+        }
+        const previousValue = currentValue;
+        currentValue = nextValue;
+        const hadPreviousValue = initialized;
+        initialized = true;
+        if (hadPreviousValue) {
+            // computed 初次求值只是建立缓存和依赖，不应触发订阅者。
+            // 只有后续依赖变化且派生值真的改变时，才向下游传播。
+            notifySubscribers(subscribers);
+            notifyListeners(listeners, currentValue, previousValue);
+        }
+    });
+    // 创建 computed 时立即求值，这样它会马上收集依赖并拥有可同步读取的缓存值。
+    computation.run();
+    return {
+        get() {
+            // computed 本身也可以作为另一个 computed/effect 的依赖源。
+            trackDependency(source);
+            return currentValue;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        }
+    };
+}
+export function effect(runEffect) {
+    let cleanup;
+    const computation = createComputation(() => {
+        if (cleanup) {
+            // effect 重新运行前先清理上一次运行创建的外部资源。
+            cleanup();
+            cleanup = undefined;
+        }
+        cleanup = runEffect();
+    });
+    // effect 的语义是“立即运行一次”，并在运行期间收集依赖。
+    computation.run();
+    return () => {
+        if (computation.disposed) {
+            return;
+        }
+        computation.disposed = true;
+        cleanupDependencies(computation);
+        if (cleanup) {
+            // dispose 时也要执行最后一次 cleanup，防止事件监听、定时器等资源泄漏。
+            cleanup();
+            cleanup = undefined;
+        }
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bindtty/signal",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Signal primitives for BindTTY.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.js"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lithdoo/BindTTY.git",
+    "directory": "packages/signal"
+  },
+  "bugs": {
+    "url": "https://github.com/lithdoo/BindTTY/issues"
+  },
+  "homepage": "https://github.com/lithdoo/BindTTY/tree/main/packages/signal#readme"
+}