first

.dockerignore

+# compiled output
+/dist
+/node_modules
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+/data
+/output
+/config.yaml
+
+.git*
+Dockerfile
+.dockerignore
+/tests

.eslintignore

+webpack.config.js
+dist/*
+build/*
+*.js

.eslintrc.js

+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.json',
+    tsconfigRootDir : __dirname, 
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint/eslint-plugin'],
+  extends: [
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended',
+  ],
+  root: true,
+  env: {
+    node: true,
+    jest: true,
+  },
+  ignorePatterns: ['.eslintrc.js'],
+  rules: {
+    '@typescript-eslint/interface-name-prefix': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off',
+  },
+};

.gitignore

+# compiled output
+/dist
+/node_modules
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+/data
+/output
+/config.yaml

.gitlab-ci.docker.yml

+stages:
+  - build
+  - deploy
+variables:
+  GIT_DEPTH: "1"
+
+before_script:
+  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+
+.build-image:
+  stage: build
+  script:
+    - docker build --pull -t $TARGET_IMAGE .
+    - docker push $TARGET_IMAGE
+
+build-x86:
+  extends: .build-image
+  tags:
+    - docker
+  variables:
+    TARGET_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-x86
+
+build-arm:
+  extends: .build-image
+  tags:
+    - docker-arm
+  variables:
+    TARGET_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-arm
+
+.deploy:
+  stage: deploy
+  tags:
+    - docker
+  script:
+    - docker pull $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-x86
+    - docker pull $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-arm
+    - docker manifest create $TARGET_IMAGE --amend $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-x86 --amend
+      $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG-arm
+    - docker manifest push $TARGET_IMAGE
+
+deploy_latest:
+  extends: .deploy
+  variables:
+    TARGET_IMAGE: $CI_REGISTRY_IMAGE:latest
+  only:
+    - master
+
+deploy_branch:
+  extends: .deploy
+  variables:
+    TARGET_IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG

.gitlab-ci.upload.yml

+stages:
+  - install
+  - build
+  - deploy
+
+variables:
+  GIT_DEPTH: "1"
+
+npm_ci:
+  stage: install
+  tags:
+    - linux
+  script:
+    - npm ci
+  artifacts:
+    paths:
+      - node_modules
+
+.build_base:
+  stage: build
+  tags:
+    - linux
+  dependencies:
+    - npm_ci
+
+build:
+  extends: .build_base
+  script: npm run build
+  artifacts:
+    paths:
+      - dist/
+
+upload_to_minio:
+  stage: deploy
+  dependencies:
+    - build
+  tags:
+    - linux
+  script:
+    - aws s3 --endpoint=https://minio.momobako.com:9000 sync --delete dist/ s3://nanahira/path
+  only:
+    - master

.gitlab-ci.yml

+stages:
+  - install
+  - build
+  - deploy
+
+variables:
+  GIT_DEPTH: "1"
+
+npm_ci:
+  stage: install
+  tags:
+    - linux
+  script:
+    - npm ci
+  artifacts:
+    paths:
+      - node_modules
+
+.build_base:
+  stage: build
+  tags:
+    - linux
+  dependencies:
+    - npm_ci
+
+build:
+  extends:
+    - .build_base
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+
+unit-test:
+  extends:
+    - .build_base
+  script:
+    - npm run test
+
+deploy_npm:
+  stage: deploy
+  dependencies:
+    - build
+  tags:
+    - linux
+  script:
+    - apt update;apt -y install coreutils
+    - echo $NPMRC | base64 --decode > ~/.npmrc
+    - npm publish . --access public && curl -X PUT "https://registry-direct.npmmirror.com/$(cat package.json | jq '.name' | sed 's/\"//g')/sync?sync_upstream=true" || true
+  only:
+    - master

.npmignore

+/install-npm.sh
+.git*
+/data
+/output
+/config.yaml
+.idea
+.dockerignore
+Dockerfile
+/src
+/coverage
+/tests
+/dist/tests

.prettierrc

+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}
\ No newline at end of file

Dockerfile

+FROM node:lts-trixie-slim as base
+LABEL Author="Nanahira <nanahira@momobako.com>"
+
+RUN apt update && apt -y install python3 build-essential && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* /var/log/*
+WORKDIR /usr/src/app
+COPY ./package*.json ./
+
+FROM base as builder
+RUN npm ci && npm cache clean --force
+COPY . ./
+RUN npm run build
+
+FROM base
+ENV NODE_ENV production
+RUN npm ci && npm cache clean --force
+COPY --from=builder /usr/src/app/dist ./dist
+
+CMD [ "npm", "start" ]

LICENSE

+The MIT License (MIT)
+
+Copyright (c) 2021 Nanahira
+
+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.
+

README.md

+# nfkit
+
+Common kits
\ No newline at end of file

index.ts

+export * from './src/workflow';

install-npm.sh

+#!/bin/bash
+
+npm i --save-exact --save-dev eslint@8.22.0
+npm install --save-dev \
+	@types/node \
+	typescript \
+	'@typescript-eslint/eslint-plugin@^6.0.0' \
+	'@typescript-eslint/parser@^6.0.0 '\
+	'eslint-config-prettier@^9.0.0' \
+	'eslint-plugin-prettier@^5.0.0' \
+	prettier \
+	jest \
+	@types/jest \
+	ts-jest \
+	rimraf

package.json

+{
+  "name": "nfkit",
+  "description": "Common kits",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "lint": "eslint --fix .",
+    "compile:cjs": "esbuild index.ts --outfile=dist/index.cjs --bundle --sourcemap --platform=node --target=es2019 --external:js-base64",
+    "compile:esm": "esbuild index.ts --outfile=dist/index.mjs --bundle --sourcemap --platform=neutral --target=esnext --external:js-base64",
+    "compile:types": "tsc --emitDeclarationOnly --declaration",
+    "build": "rimraf dist && npm run compile:cjs && npm run compile:esm && npm run compile:types",
+    "test": "jest --passWithNoTests",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://code.moenext.com/nanahira/nfkit.git"
+  },
+  "author": "Nanahira <nanahira@momobako.com>",
+  "license": "MIT",
+  "keywords": [],
+  "bugs": {
+    "url": "https://code.moenext.com/nanahira/nfkit/issues"
+  },
+  "homepage": "https://code.moenext.com/nanahira/nfkit",
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "tests",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.9.1",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "esbuild": "^0.25.11",
+    "esbuild-register": "^3.6.0",
+    "eslint": "8.22.0",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3"
+  }
+}

src/workflow.ts

+// ========== 类型工具 ==========
+type AwaitedLike<T> = T extends Promise<infer R> ? R : T;
+type AnyFn = (...args: any[]) => any;
+
+type Chain<T> = Promise<AwaitedLike<T>> &
+  (T extends AnyFn
+    ? (...a: Parameters<T>) => Chain<AwaitedLike<ReturnType<T>>>
+    : {}) & {
+    [K in keyof T]: T[K] extends (...a: infer A) => infer R
+      ? (...a: A) => Chain<AwaitedLike<R>>
+      : Chain<AwaitedLike<T[K]>>;
+  };
+
+// ========== 核心：不可变节点 ==========
+class Node {
+  private memo?: Promise<any>;
+  constructor(
+    private readonly source: any, // 只有根节点有意义；子节点可复用根的 source
+    private readonly parent: Node | null, // 前缀
+    private readonly op: ((x: any) => any) | null, // 从 parent 结果到本节点结果的变换
+  ) {}
+
+  run(): Promise<any> {
+    if (!this.memo) {
+      this.memo = (async () => {
+        if (!this.parent) {
+          // 根：把 source 解一次即可
+          return await this.source;
+        }
+        // 先拿到父节点结果（会记忆化）
+        const base = await this.parent.run();
+        // 应用本节点的变换（允许返回同步或异步）
+        return this.op ? this.op(base) : base;
+      })();
+    }
+    return this.memo;
+  }
+
+  // 工厂：衍生子节点（分叉 = 复用同一个 parent）
+  child(op: (x: any) => any): Node {
+    return new Node(this.source, this, op);
+  }
+
+  // 拿到“相同节点”的句柄（显式 fork）
+  fork(): Node {
+    return new Node(this.source, this.parent, this.op);
+  }
+}
+
+// ========== 对外 API：workflow ==========
+export function workflow<T>(source: T | Promise<T>): Chain<T> {
+  const root = new Node(source, null, null);
+  return makeProxy<T>(root) as any;
+}
+
+// ========== 代理层：把 Node 暴露成链式 API ==========
+function makeProxy<T>(node: Node): Chain<T> {
+  const runOnce = () => node.run(); // 记忆化在 Node 内部
+
+  const rootHandler: ProxyHandler<any> = {
+    get(_t, prop) {
+      // 结束信号：所有 then/catch/finally 复用同一个 Promise
+      if (prop === 'then')
+        return (res: any, rej?: any) => runOnce().then(res, rej);
+      if (prop === 'catch') return (rej: any) => runOnce().catch(rej);
+      if (prop === 'finally') return (fin: any) => runOnce().finally(fin);
+
+      // 访问一个属性：生成一个“Get”子节点，但不执行
+      return linkProxy(prop);
+    },
+    // 支持对“当前值”直接二次调用： foo()()
+    apply(_t, _this, argArray) {
+      const child = node.child((cur: any) => {
+        if (typeof cur !== 'function')
+          throw new TypeError('Current value is not callable');
+        return cur(...argArray);
+      });
+      return makeProxy<any>(child);
+    },
+  };
+
+  const linkProxy = (prop: PropertyKey) =>
+    new Proxy(function () {}, {
+      // 把 “.foo(…args)” 记录为 Call
+      apply(_t, _this, argArray) {
+        const child = node.child((cur: any) => {
+          const fn = (cur as any)[prop];
+          if (typeof fn !== 'function') {
+            throw new TypeError(`${String(prop)} is not a function`);
+          }
+          return fn.apply(cur, argArray);
+        });
+        return makeProxy<any>(child);
+      },
+      // 把 “.bar” 记录为 Get；继续深入时在这个 Get 的结果上再处理
+      get(_t, next) {
+        if (next === 'then')
+          return (r: any, j?: any) =>
+            node
+              .child((cur: any) => (cur as any)[prop])
+              .run()
+              .then(r, j);
+        if (next === 'catch')
+          return (rej: any) =>
+            node
+              .child((cur: any) => (cur as any)[prop])
+              .run()
+              .catch(rej);
+        if (next === 'finally')
+          return (fin: any) =>
+            node
+              .child((cur: any) => (cur as any)[prop])
+              .run()
+              .finally(fin);
+
+        const child = node.child((cur: any) => (cur as any)[prop]);
+        return (makeProxy as any)(child)[next];
+      },
+    });
+
+  return new Proxy(function () {}, rootHandler) as any;
+}

tests/workflow.spec.ts

+import { workflow } from '../src/workflow';
+
+const sleep = (ms: number) => new Promise((res) => setTimeout(res, ms));
+
+describe('workflow – basics', () => {
+  it('mixes async + sync + property + invoke (() ) correctly', async () => {
+    class A {
+      value = 42;
+
+      async foo() {
+        await sleep(5);
+        this.value += 42; // 84
+        return this;
+      }
+
+      bar() {
+        this.value += 10; // 94
+        return this;
+      }
+
+      baz() {
+        // 返回可调用：再调用一次时把 value+15 然后返回 this
+        return () => {
+          this.value += 15; // 109
+          return this;
+        };
+      }
+    }
+
+    const a = new A();
+    const result = workflow(a).foo().bar().baz()().value;
+    await expect(result).resolves.toBe(109);
+  });
+
+  it('property-only terminal await works', async () => {
+    class A {
+      value = 7;
+    }
+    const a = new A();
+    const result = workflow(a).value;
+    await expect(result).resolves.toBe(7);
+  });
+
+  it('throws when invoking a non-function value', async () => {
+    class A {
+      value = 123;
+    }
+    const a = new A();
+    // @ts-expect-error intentional wrong call
+    await expect(workflow(a).value()).rejects.toThrow(TypeError);
+  });
+
+  it('throws when calling a non-existing method', async () => {
+    class A {
+      ok() {
+        return 1;
+      }
+    }
+    const a: any = new A();
+    // @ts-expect-error intentional wrong call
+    await expect(workflow(a).noSuchMethod()).rejects.toThrow();
+  });
+
+  it('preserves "this" binding', async () => {
+    class C {
+      x = 1;
+      inc(by = 1) {
+        this.x += by;
+        return this;
+      }
+      async incAsync(by = 1) {
+        await sleep(1);
+        this.x += by;
+        return this;
+      }
+    }
+    const c = new C();
+    await workflow(c).inc(2).incAsync(3);
+    expect(c.x).toBe(1 + 2 + 3);
+  });
+});
+
+describe('workflow – memoization of execution (multi then/catch/finally)', () => {
+  it('executes only once even with multiple then()', async () => {
+    const calls: string[] = [];
+    class A {
+      async foo() {
+        calls.push('foo');
+        await sleep(2);
+        return this;
+      }
+      bar() {
+        calls.push('bar');
+        return this;
+      }
+    }
+    const chain = workflow(new A()).foo().bar();
+
+    const p1 = chain.then((v) => v);
+    const p2 = chain.then((v) => v);
+    const [r1, r2] = await Promise.all([p1, p2]); // 不应重复执行链
+
+    expect(r1).toBe(r2);
+    expect(calls.join(',')).toBe('foo,bar'); // 各一步只一次
+  });
+
+  it('catch/finally also reuse the same promise', async () => {
+    const steps: string[] = [];
+    class A {
+      async bad() {
+        steps.push('bad');
+        await sleep(1);
+        throw new Error('boom');
+      }
+    }
+    const chain = workflow(new A()).bad();
+
+    const p1 = chain.catch(() => {
+      steps.push('c1');
+      return 'C1';
+    });
+    const p2 = chain.finally(() => {
+      steps.push('f1');
+    });
+
+    const [r1] = await Promise.allSettled([p1, p2]);
+    // bad 只执行一次；catch/finally 都被触发
+    expect(steps).toEqual(['bad', 'c1', 'f1']);
+    expect(r1.status).toBe('fulfilled');
+  });
+});
+
+describe('workflow – function value invocation foo()()', () => {
+  it('supports invoking current value (invoke step)', async () => {
+    class F {
+      n = 0;
+      makeAdder(start: number) {
+        this.n += start; // 先加 start
+        return (inc: number) => {
+          // 再可调用一次
+          this.n += inc;
+          return this;
+        };
+      }
+    }
+    const f = new F();
+    await workflow(f).makeAdder(5)(7);
+    expect(f.n).toBe(12);
+  });
+});
+
+describe('workflow – branching / prefix reuse', () => {
+  it('reuses prefix (like connected client) and branches run independently', async () => {
+    const log: string[] = [];
+
+    class Client {
+      connects = 0;
+      qs = 0;
+      gets = 0;
+      posts = 0;
+
+      async connect() {
+        this.connects++;
+        log.push('connect');
+        await sleep(3);
+        return this;
+      }
+      query() {
+        this.qs++;
+        log.push('query');
+        return this;
+      }
+      async get() {
+        this.gets++;
+        log.push('get');
+        await sleep(1);
+        return 'GET';
+      }
+      async post() {
+        this.posts++;
+        log.push('post');
+        await sleep(1);
+        return 'POST';
+      }
+    }
+
+    const client = workflow(new Client()).connect();
+
+    // 两个分支从同一前缀出发
+    const p1 = client.query().get();
+    const p2 = client.post();
+
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).toBe('GET');
+    expect(r2).toBe('POST');
+
+    // 前缀 connect 只跑一次；各分支自己的步骤各一次
+    expect(log.filter((x) => x === 'connect').length).toBe(1);
+    expect(log.filter((x) => x === 'query').length).toBe(1);
+    expect(log.filter((x) => x === 'get').length).toBe(1);
+    expect(log.filter((x) => x === 'post').length).toBe(1);
+  });
+
+  it('parallel awaits still reuse the same prefix result', async () => {
+    const counts = { connect: 0, get: 0, post: 0 };
+    class Client {
+      async connect() {
+        counts.connect++;
+        await sleep(2);
+        return this;
+      }
+      async get() {
+        counts.get++;
+        await sleep(1);
+        return 1;
+      }
+      async post() {
+        counts.post++;
+        await sleep(1);
+        return 2;
+      }
+    }
+    const client = workflow(new Client()).connect();
+    const [a, b] = await Promise.all([client.get(), client.post()]);
+    expect(a + b).toBe(3);
+    expect(counts).toEqual({ connect: 1, get: 1, post: 1 });
+  });
+});
+
+describe('workflow – property chains', () => {
+  it('handles deep property then method: .bar.baz(2,3)', async () => {
+    class B {
+      bazCalls = 0;
+      baz(u: number, v: number) {
+        this.bazCalls++;
+        return u + v;
+      }
+    }
+    class A {
+      bar = new B();
+    }
+
+    const sum = await workflow(new A()).bar.baz(4, 5);
+    expect(sum).toBe(9);
+  });
+
+  it('deep property terminal await returns value', async () => {
+    class A {
+      cfg = { feature: { enabled: true as boolean } };
+    }
+    const result = await workflow(new A()).cfg.feature.enabled;
+    await expect(result).resolves.toBe(true);
+  });
+});
+
+describe('workflow – error propagation', () => {
+  it('propagates thrown sync errors', async () => {
+    class A {
+      bad() {
+        throw new Error('sync boom');
+      }
+    }
+    await expect(workflow(new A()).bad()).rejects.toThrow('sync boom');
+  });
+
+  it('propagates rejected async errors', async () => {
+    class A {
+      async bad() {
+        await sleep(1);
+        throw new Error('async boom');
+      }
+    }
+    await expect(workflow(new A()).bad()).rejects.toThrow('async boom');
+  });
+});
+
+describe('workflow – order and once-only semantics in longer chains', () => {
+  it('runs steps in strict order and exactly once each', async () => {
+    const order: string[] = [];
+    class A {
+      async a() {
+        order.push('a');
+        await sleep(1);
+        return this;
+      }
+      b() {
+        order.push('b');
+        return this;
+      }
+      async c() {
+        order.push('c');
+        await sleep(1);
+        return this;
+      }
+      d() {
+        order.push('d');
+        return 123;
+      }
+    }
+
+    const chain = workflow(new A()).a().b().c().d();
+    const p1 = chain.then((x) => x);
+    const p2 = chain.then((x) => x);
+    const [r1, r2] = await Promise.all([p1, p2]);
+
+    expect(r1).toBe(123);
+    expect(r2).toBe(123);
+    expect(order).toEqual(['a', 'b', 'c', 'd']); // 没有重复
+  });
+});
+
+describe('workflow – Promise combinators interop', () => {
+  class Client {
+    counts = { connect: 0, get: 0, fail: 0 };
+
+    async connect() {
+      this.counts.connect++;
+      await sleep(5);
+      return this;
+    }
+    async get(val: any, ms = 10) {
+      this.counts.get++;
+      await sleep(ms);
+      return val;
+    }
+    async fail(msg = 'boom', ms = 10) {
+      this.counts.fail++;
+      await sleep(ms);
+      throw new Error(msg);
+    }
+  }
+
+  it('works with Promise.all: parallel branches reuse prefix once', async () => {
+    const c = new Client();
+    const client = workflow(c).connect();
+
+    const [a, b, cval] = await Promise.all([
+      client.get(1, 15), // 慢一些
+      client.get(2, 5), // 快一些
+      client.get(3, 10),
+    ]);
+
+    expect([a, b, cval]).toEqual([1, 2, 3]);
+    expect(c.counts).toEqual({ connect: 1, get: 3, fail: 0 }); // 前缀 connect 只执行一次
+  });
+
+  it('works with Promise.allSettled: successes and failures settle together', async () => {
+    const c = new Client();
+    const client = workflow(c).connect();
+
+    const settled = await Promise.allSettled([
+      client.get('ok-1', 5),
+      client.fail('bad-1', 8),
+      client.get('ok-2', 2),
+      client.fail('bad-2', 1),
+    ]);
+
+    // 校验形状和顺序
+    expect(settled.map((s) => s.status)).toEqual([
+      'fulfilled',
+      'rejected',
+      'fulfilled',
+      'rejected',
+    ]);
+    const msgs = settled.map(
+      (s) => (s as any).reason?.message ?? (s as any).value,
+    );
+    expect(msgs).toEqual(['ok-1', 'bad-1', 'ok-2', 'bad-2']);
+
+    expect(c.counts.connect).toBe(1); // 前缀仍只连一次
+    expect(c.counts.get).toBe(2);
+    expect(c.counts.fail).toBe(2);
+  });
+
+  it('works with Promise.any: resolves to first fulfilled value even if others reject', async () => {
+    const c = new Client();
+    const client = workflow(c).connect();
+
+    // 一个快速 reject，一个稍慢 resolve，一个更慢 reject
+    const val = await Promise.any([
+      client.fail('bad-fast', 2),
+      client.get('good', 5),
+      client.fail('bad-slow', 20),
+    ]);
+
+    expect(val).toBe('good');
+    expect(c.counts.connect).toBe(1);
+  });
+
+  it('Promise.any rejects with AggregateError only if all reject', async () => {
+    const c = new Client();
+    const client = workflow(c).connect();
+
+    await expect(
+      Promise.any([
+        client.fail('e1', 3),
+        client.fail('e2', 1),
+        client.fail('e3', 2),
+      ]),
+    ).rejects.toHaveProperty('errors'); // AggregateError.errors 存在
+  });
+
+  it('works with Promise.race: resolves/rejects with first settled branch', async () => {
+    const c = new Client();
+    const client = workflow(c).connect();
+
+    // 先测试最快 resolve 赢
+    const r1 = await Promise.race([
+      client.get('win', 3),
+      client.get('lose', 10),
+      client.fail('should-not-win', 2_000),
+    ]);
+    expect(r1).toBe('win');
+
+    // 再测试最快 reject 赢
+    await expect(
+      Promise.race([client.fail('first-error', 4), client.get('slow-ok', 20)]),
+    ).rejects.toThrow('first-error');
+
+    expect(c.counts.connect).toBe(1); // 两次 race 都复用同一前缀
+  });
+
+  it('combinators do not cause duplicate execution on the same branch (memoized)', async () => {
+    const c = new Client();
+    const branch = workflow(c).connect().get('once', 5);
+
+    const [x, y, z] = await Promise.all([branch, branch, branch]);
+    expect(x).toBe('once');
+    expect(y).toBe('once');
+    expect(z).toBe('once');
+
+    // connect 一次；get 这条分支只计算一次
+    expect(c.counts.connect).toBe(1);
+    expect(c.counts.get).toBe(1);
+  });
+});

tsconfig.json

+{
+	"compilerOptions": {
+		"outDir": "dist",
+		"module": "commonjs",
+		"target": "es2021",
+		"esModuleInterop": true,
+		"emitDecoratorMetadata": true,
+		"experimentalDecorators": true,
+		"declaration": true,
+		"sourceMap": true
+	},
+	"compileOnSave": true,
+	"allowJs": true,
+	"include": [
+		"*.ts",
+		"src/**/*.ts",
+		"test/**/*.ts",
+		"tests/**/*.ts"
+	]
+}