✨ [node] 新增了acontext

Gaubee · Gaubee · commit 67c76e2b7784 · 2025-07-24T17:36:01.000+08:00
diff --git a/node/deno.json b/node/deno.json
@@ -1,7 +1,8 @@
 {
   "name": "@gaubee/node",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "exports": {
+    "./acontext": "./src/acontext/acontext.ts",
     "./env": "./src/env.ts",
     "./path": "./src/path.ts",
     "./promise": "./src/promise.ts",
diff --git a/node/src/acontext/acontext.ts b/node/src/acontext/acontext.ts
@@ -0,0 +1,104 @@
+import { type AsyncContextStorage, createAsyncContextStorage } from "./async-context.ts";
+
+export type ReadonlyAcontext<T> = {
+  readonly name: string;
+  get(): T;
+  getOrNull(): T | null;
+  getOrElse<TElse>(else_fn: () => TElse): T | TElse;
+};
+
+export type Acontext<T> = ReadonlyAcontext<T> & {
+  readonly default?: () => T;
+  readonly storage: AsyncContextStorage<{ value: T }>;
+  run<R>(value: T, cb: () => Promise<R>): Promise<R>;
+  asReadonly(): ReadonlyAcontext<T>;
+};
+
+export const createAcontext = <T extends unknown>(name: string, default_fn?: Acontext<T>["default"]): Acontext<T> => {
+  const storage = createAsyncContextStorage<{ value: T }>();
+
+  const handle: Acontext<T> = {
+    storage: storage,
+    default: default_fn,
+    name: name,
+    getOrElse: (else_fn) => {
+      const item = storage.getStore();
+      if (item == null) {
+        return default_fn ? default_fn() : else_fn();
+      }
+      return item?.value;
+    },
+
+    get: () => {
+      return handle.getOrElse(() => {
+        throw new Error(`No factory registered for capability handle: ${name}`);
+      });
+    },
+    getOrNull: () => {
+      return handle.getOrElse(() => null);
+    },
+    run: (value, cb) => {
+      return storage.run({ value }, cb);
+    },
+
+    asReadonly: () => {
+      return {
+        name: handle.name,
+        get: handle.get,
+        getOrNull: handle.getOrNull,
+        getOrElse: handle.getOrElse,
+      };
+    },
+  };
+
+  return handle;
+};
+
+type AContextValue<T> = T extends Acontext<infer R> ? R : never;
+
+type AContextsValues<T extends Array<any>> = T extends []
+  ? []
+  : T extends [infer Head, ...infer Tail]
+    ? [AContextValue<Head>, ...AContextsValues<Tail>]
+    : T extends Array<infer Head>
+      ? AContextValue<Head>[]
+      : never;
+
+export const useAcontexts = <const ACS extends Array<Acontext<any>>>(ctxs: ACS) => {
+  return <R extends unknown>(values: AContextsValues<ACS>, run: () => Promise<R>) => {
+    // 递归的内部辅助函数
+    const runner = async (index: number): Promise<R> => {
+      // 基本情况：如果所有上下文都已应用，则执行最终的 run 函数
+      if (index >= ctxs.length) {
+        return run();
+      }
+
+      // 获取当前的 Acontext 和要设置的值
+      const context = ctxs[index];
+      const value = values[index];
+
+      // 递归步骤：在当前上下文中运行，并递归调用 runner 处理下一个上下文
+      return context.run(value, () => runner(index + 1));
+    };
+
+    // 从第一个上下文开始启动递归
+    return runner(0);
+  };
+};
+
+export class AcontextMap {
+  #map = new Map<Acontext<any>, any>();
+  set<T extends Acontext<unknown>>(context: T, value: AContextValue<T>) {
+    this.#map.set(context, value);
+    return this;
+  }
+  get<T>(context: Acontext<T>) {
+    return this.#map.get(context);
+  }
+  has(context: Acontext<any>) {
+    return this.#map.has(context);
+  }
+  run<T>(runner: () => Promise<T>) {
+    return useAcontexts([...this.#map.keys()])([...this.#map.values()], runner);
+  }
+}
diff --git a/node/src/acontext/async-context.ts b/node/src/acontext/async-context.ts
@@ -0,0 +1,71 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * 异步上下文存储的通用接口，对齐 TC39 proposal-async-context。
+ * 这层抽象允许我们在不同 JS 运行时之间切换实现。
+ */
+export interface AsyncContextStorage<T> {
+  /**
+   * 创建并进入一个新的异步上下文。
+   * @param store 上下文中要存储的数据
+   * @param callback 在此上下文中执行的函数
+   */
+  run<R>(store: T, callback: () => R): R;
+
+  /**
+   * 获取当前异步上下文中的数据。
+   * @returns 如果在上下文中，则返回存储的数据；否则返回 undefined。
+   */
+  getStore(): T | undefined;
+}
+
+/**
+ * 基于 Node.js 原生 AsyncLocalStorage 的实现。
+ */
+class NodeAsyncContextStorage<T> implements AsyncContextStorage<T> {
+  private readonly als: AsyncLocalStorage<T>;
+
+  constructor() {
+    this.als = new AsyncLocalStorage<T>();
+  }
+
+  run<R>(store: T, callback: () => R): R {
+    return this.als.run(store, callback);
+  }
+
+  getStore(): T | undefined {
+    return this.als.getStore();
+  }
+}
+
+/**
+ * 一个简单的 Polyfill，用于不支持 AsyncLocalStorage 的环境。
+ * 注意：这个 Polyfill 不支持跨异步任务的上下文传递，主要用于简化测试或基础场景。
+ */
+class FallbackAsyncContextStorage<T> implements AsyncContextStorage<T> {
+  private currentStore: T | undefined = undefined;
+
+  run<R>(store: T, callback: () => R): R {
+    const previousStore = this.currentStore;
+    this.currentStore = store;
+    try {
+      return callback();
+    } finally {
+      this.currentStore = previousStore;
+    }
+  }
+
+  getStore(): T | undefined {
+    return this.currentStore;
+  }
+}
+
+export const createAsyncContextStorage = <T,>(): AsyncContextStorage<T> => {
+  // 优先使用 Node.js 的原生实现
+  if (typeof AsyncLocalStorage === "function") {
+    return new NodeAsyncContextStorage<T>();
+  }
+  // 否则使用备用方案
+  console.warn("AsyncLocalStorage is not available. Falling back to a simple polyfill. Concurrency issues may occur.");
+  return new FallbackAsyncContextStorage<T>();
+};
diff --git a/node/src/mod.ts b/node/src/mod.ts
@@ -1,3 +1,4 @@
+export * from "./acontext/acontext.ts";
 export * from "./env.ts";
 export * from "./path.ts";
 export * from "./promise.ts";
