@gobing-ai/ts-runtime

中文文档
0.7.1发布于 2026/10/25Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 5149

@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.

原始使用文档
文档目录16 节
  1. Overview
  2. Architecture
  3. How It Works
  4. 1. Runtime selection
  5. 2. Service registration
  6. 3. Configuration
  7. 4. Structured config + JSON-schema validation
  8. 5. Path utilities
  9. 6. Extension core ( @gobing-ai/ts-runtime/extension )
  10. 7. File system abstraction
  11. 8. Database adapter ( createDbAdapter )
  12. 9. Graceful disposal
  13. Basic setup (Node/Bun)
  14. Cloudflare Workers
  15. Config with env interpolation
  16. SpanContext (for telemetry)

@gobing-ai/ts-runtime

Runtime abstraction layer — platform detection, file system, process execution, configuration, context management, path utilities, and a shared plugin/capability core. Works on Node.js, Bun, and Cloudflare Workers through a factory pattern that auto-detects the runtime.

ts-runtime decouples application code from platform specifics. Instead of importing node:fs or node:child_process directly, consumers use interfaces (FileSystem, ProcessExecutor) resolved by loadRuntimeFactory() at startup. The factory auto-detects the platform and wires the correct implementations — createNodeFileSystem (real node:fs) for Node/Bun, createCfFileSystem (stub) for Workers. Node filesystem modules are loaded lazily, so importing the package remains safe for Worker bundles.

Overview

Key abstractions:

ConceptInterfaceBun/Node implCloudflare impl
Runtime factoryRuntimeFactory → loadRuntimeFactory()nodeBunFactorycloudflareWorkersFactory
File systemFileSystemcreateNodeFileSystem() (sync node:fs)createCfFileSystem() (stub)
Process executionProcessExecutor (interface)NodeProcessExecutor — run() via execa, runStreaming() via Bun.spawnthrows
Process registryProcessRegistry (optional)InMemoryProcessRegistry / createInMemoryProcessRegistry() — list + subscribe all spawnsn/a (no process exec)
SQL databasecreateDbAdapter(config) → DbAdapterBun SQLite via @gobing-ai/ts-db (optional peer)throws D1NotConfiguredError (D1 round pending)
ConfigurationConfig (Zod schema)YAML + env varsCONFIG_YAML blob + env vars
ContextRuntimeContextservice locatorservice locator
Path utilitiesSEP, basenamePath, dirnamePath, joinPath, resolvePath, relativePath, …runtime-portable (zero node:*)runtime-portable (zero node:*)
Schema validationloadStructuredConfigJSON-Schema + YAMLJSON-Schema + YAML
Extension core (./extension)CapabilityRegistry, loadExtensionModulestrust-gated module loading—
Bun SQLite boundary (./bun-sqlite)Database re-exportbun:sqliteunavailable
TracingSpanContext{ traceId, spanId }{ traceId, spanId }

Architecture

classDiagram
    class RuntimeFactory {
        <<interface>>
        +string runtimeName
        +createFileSystem() FileSystem
        +createProcessExecutor() ProcessExecutor
        +loadConfig() Promise~Config~
        +createDbAdapter(config) Promise~DbAdapter~
    }

    class nodeBunFactory {
        +createFileSystem() createNodeFileSystem()
        +createProcessExecutor() ProcessExecutor
        +loadConfig() Promise~Config~
        +createDbAdapter() Promise~DbAdapter~
    }

    class cloudflareWorkersFactory {
        +createFileSystem() createCfFileSystem()
        +createProcessExecutor() never
        +loadConfig() Promise~Config~
        +createDbAdapter() never
    }

    class FileSystem {
        <<interface>>
        +exists(path) boolean~|~Promise~boolean~
        +readFile(path) string~|~Promise~string~
        +writeFile(path, content) void~|~Promise~void~
        +ensureDir(path) void~|~Promise~void~
        +readDir(path) string[]~|~Promise~string[]~
        +deleteFile(path) void~|~Promise~void~
        +stat(path) FileStat~|~null~|~Promise~FileStat|~
        +resolve(...segments) string
        +getProjectRoot() string
        +readFileStream(path) AsyncIterable<string>▀optional (ADR-021)
        +realPath(path) string▀optional (ADR-022)
    }

    class createNodeFileSystem {
        +readFile(path) string
        +writeFile(path, content) void
        +exists(path) boolean
        +ensureDir(path) void
        +stat(path) FileStat | null
        +getProjectRoot() string
        +readFileStream(path) AsyncIterable<string>
        +realPath(path) string
    }

    class createCfFileSystem {
        +readFile(path) never
        +writeFile(path, content) never
        +exists(path) false
        +ensureDir(path) void
        +stat(path) null
        +getProjectRoot() '/bundle'
    }

    class ProcessExecutor {
        <<interface>>
        +run(options) Promise~ProcessResult~
        +runStreaming(options) PipeProcess
    }

    class NodeProcessExecutor {
        +run(options) Promise~ProcessResult~
        +runStreaming(options) PipeProcess
    }

    class ProcessRegistry {
        <<interface>>
        +listExecutions(filter?) ProcessExecution[]
        +getExecution(id) ProcessExecution?
        +subscribe(listener) unsub
        +begin(input) string
        +update(id, patch) void
        +complete(id, update?) void
        +clear() void
    }

    class InMemoryProcessRegistry {
        +listExecutions(filter?) ProcessExecution[]
        +begin(input) string
        +complete(id, update?) void
    }

    class PipeProcess {
        <<interface>>
        +pid number?
        +stdout ReadableStream?
        +stderr ReadableStream?
        +exited Promise~number?~
        +writeStdin(input) void
        +endStdin() void
        +kill(signal?) void
    }

    class RuntimeContext {
        +RuntimeScope scope
        +RuntimeName runtimeName
        +RuntimeCapabilities capabilities
        +register(key, service) void
        +get(key) T | undefined
        +require(key) T
        +has(key) boolean
        +dispose() Promise~void~
    }

    class Config {
        +AppConfig app
        +DatabaseConfig database
        +LoggingConfig logging
    }

    class SpanContext {
        <<interface>>
        +string traceId
        +string spanId
        +Record~string,string~ baggage?
        +Record~string,string|number|boolean~ attributes?
    }

    RuntimeFactory <|.. nodeBunFactory : implements
    RuntimeFactory <|.. cloudflareWorkersFactory : implements
    FileSystem <|.. createNodeFileSystem : implements
    FileSystem <|.. createCfFileSystem : implements
    ProcessExecutor --> PipeProcess : creates
    ProcessExecutor <|.. NodeProcessExecutor : implements
    ProcessRegistry <|.. InMemoryProcessRegistry : implements
    NodeProcessExecutor ..> ProcessRegistry : optional registry
    nodeBunFactory --> createNodeFileSystem : creates
    nodeBunFactory --> NodeProcessExecutor : creates
    cloudflareWorkersFactory --> createCfFileSystem : creates
    RuntimeContext --> FileSystem : "fileSystem"
    RuntimeContext --> Config : "config"
    RuntimeContext --> ProcessExecutor : "processExecutor"

How It Works

1. Runtime selection

loadRuntimeFactory() auto-detects the platform and returns a factory that creates the correct FileSystem, ProcessExecutor, and Config. Use createRuntimeContextFromFactory() to wire everything automatically:

import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';

const ctx = await createRuntimeContextFromFactory();
// ctx.runtimeName → 'node-bun' (auto-detected)
// ctx.capabilities → { hasFilesystem: true, hasProcessExecution: true }
// ctx.require('fileSystem') → canonical FileSystem (createNodeFileSystem)
// ctx.require('config') → Config from config.yaml

For manual control or synchronous code, createRuntimeContext() is still available (deprecated — kept for backward compatibility):

import { createRuntimeContext } from '@gobing-ai/ts-runtime';

const ctx = createRuntimeContext({
    runtimeName: 'node-bun',
    capabilities: { hasFilesystem: true, hasProcessExecution: true, hasPersistentStorage: true },
});

2. Service registration

Services are registered into RuntimeContext and accessed by key:

ctx.register('db', drizzleAdapter);
ctx.register('cache', redisClient);

const db = ctx.require('db'); // throws if missing
const cache = ctx.get('cache'); // undefined if missing

3. Configuration

Config is loaded from YAML with environment variable interpolation and Zod validation:

# config.yaml
app:
  name: my-app
  env: ${APP_ENV}
  port: ${PORT}
database:
  url: ${DATABASE_URL}
logging:
  level: debug
import { buildConfigFromYaml } from '@gobing-ai/ts-runtime';

const yaml = await fs.readFile('config.yaml');
const config = buildConfigFromYaml(yaml, {
    overrides: { app: { port: 8080 } },
});
// config.app.port === 8080 (overridden)
// config.logging.level === 'debug' (from YAML)

4. Structured config + JSON-schema validation

loadStructuredConfig reads a .json/.yaml file and — if it declares a top-level $schema — validates it against that schema before returning. This powers schema-checked rule and workflow files in ts-rule-engine and ts-dual-workflow-engine.

import { loadStructuredConfig } from '@gobing-ai/ts-runtime';

const config = await loadStructuredConfig('rules.yaml'); // validates against its $schema, throws on violation
const raw = await loadStructuredConfig('rules.yaml', { validateSchema: false }); // skip validation

A StructuredConfigSchemaError (with a violations array of { path, message }) is thrown on any schema violation.

$schema reference styles

There are three ways a config file can name its schema. Prefer the bundled package specifier — it is the most secure and performant default:

StyleExampleResolutionNotes
Package specifier (recommended)$schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"Resolved through node_modules via the module resolver, then read from diskNo network, no path guessing; survives hoisting/pnpm/monorepo layouts. Schemas ship in each package's schemas/ (declared in files). Quote the value — YAML treats a leading @ as reserved.
Relative path$schema: ./schemas/rule-file.schema.jsonResolved against the config file's directoryFine for repo-local schemas; brittle if the config moves.
Remote URL$schema: https://json-schema.org/.../rule-file.schema.jsonFetched over HTTP(S) — off by defaultSSRF/DoS surface for third-party configs. Opt in with both { allowRemote: true } and a fetch implementation — there is no built-in fetch; the caller owns timeout/credentials.
// Bundled package schema (default path — no extra options needed):
//   $schema: "@gobing-ai/ts-rule-engine/schemas/rule-file.schema.json"
await loadStructuredConfig('rules.yaml');

// Remote schema is refused unless BOTH flags are present:
await loadStructuredConfig('rules.yaml', { allowRemote: true, fetch: myFetch }); // caller-supplied fetch
// { allowRemote: true } alone -> refused (no built-in fetch)
// { fetch: myFetch } alone     -> refused (no explicit opt-in)

Security: remote schema fetching is disabled by default. Resolving a bundled schema from node_modules keeps validation entirely local — no outbound request, no dependency on a schema host's availability, and no chance for a malicious config to point validation at an internal URL.

5. Path utilities

Runtime-portable path math that avoids node:path so the same logic works on Cloudflare Workers (ADR-008). All functions use POSIX-style separators; Windows drive paths are normalized and treated as absolute.

import {
    SEP, basenamePath, dirnamePath, isAbsolutePath,
    joinPath, normalizeSeparators, relativePath, resolvePath,
    getProcessCwd,
} from '@gobing-ai/ts-runtime';

normalizeSeparators('C:\\Users\\x\\file');  // 'C:/Users/x/file'
SEP;                                          // '/' on POSIX, '\\' on Windows
isAbsolutePath('/abs');                       // true
dirnamePath('/a/b/c.ts');                     // '/a/b'
basenamePath('/a/b/c.ts');                    // 'c.ts'
basenamePath('/a/b/c.ts', '.ts');            // 'c'
joinPath('/a', 'b', 'c');                     // '/a/b/c'
resolvePath('/a/b', '../c');                  // '/a/c'
relativePath('/a/x', '/a/y');                 // '../y'
getProcessCwd();                              // process.cwd() or '/' on Workers

6. Extension core (@gobing-ai/ts-runtime/extension)

The ./extension subpath exposes a generic, domain-agnostic extension/capability core used by both ts-rule-engine and ts-dual-workflow-engine (ADR-010). It shares the mechanism — a typed registry with origin metadata, a trust-gated extension loader, and a path guard — without knowing anything about evaluators, resolvers, actions, or guards. Each engine owns its domain-specific kinds, schemas, error types, and override semantics.

Capability registry

import { CapabilityRegistry } from '@gobing-ai/ts-runtime/extension';

interface Widget { execute(): void; }
const registry = new CapabilityRegistry<Widget>('widget');

// Register built-ins and extensions with origin metadata.
registry.register('core', coreWidget, 'builtin');
registry.register('ext',  extWidget,  'extension');   // default

registry.has('core');          // true
registry.list();               // ['core', 'ext']          (insertion order)
registry.get('core').execute(); // ok
registry.get('missing');        // throws: Unknown widget: missing

// Introspect origin without throwing.
registry.getEntry('core')?.origin;   // 'builtin'
registry.entries();                   // [['core', { capability, origin: 'builtin' }], ...]

Extension loading (trust-gated)

Extension modules are arbitrary code — the loader is disabled by default and fails closed:

import { loadExtensionModules, type ExtensionRef } from '@gobing-ai/ts-runtime/extension';

const refs: ExtensionRef<'actions'>[] = [{
    kind: 'actions',
    path: './ext/slack.ts',
    baseDir: '/abs/path/to/configs',
    sourceName: 'my-config',
}];

// Throws before any import: "declares actions extension … but extensions are disabled"
await loadExtensionModules(refs, { moduleLoader: (p) => import(p) }, register);

// Explicitly opt in.
await loadExtensionModules(refs, {
    allowExtensions: true,
    moduleLoader: (p) => import(p),
}, (ref, extension) => {
    // Engine-provided callback — the loader never chooses a target registry.
    myHost.actions.register(extension.name, extension, 'extension');
});

The loader validates both the default export and the named extension export. Invalid modules throw with source name, kind, and path context. moduleLoader is required — the shared core has no ambient import() capability of its own.

Path guard

assertRelativeExtensionPath rejects absolute paths and .. traversal at load time, independent of any engine's zod schema (defense in depth):

import { assertRelativeExtensionPath } from '@gobing-ai/ts-runtime/extension';

assertRelativeExtensionPath('./ext/my.ts');    // ok
assertRelativeExtensionPath('/etc/evil.ts');   // throws: must be relative
assertRelativeExtensionPath('../escape.ts');   // throws: must not contain ".."

The string-level guard does not resolve symlinks — a symlink inside baseDir that points outside passes the check. For symlink-safe confinement (ADR-022), supply a realPath canonicalizer to LoadExtensionsOptions:

import { loadExtensionModules } from '@gobing-ai/ts-runtime/extension';
import { createNodeFileSystem } from '@gobing-ai/ts-runtime';

const fs = createNodeFileSystem('/abs/path');
await loadExtensionModules(refs, {
    allowExtensions: true,
    moduleLoader: (p) => import(p),
    realPath: fs.realPath,  // enables symlink confinement check
}, register);

When realPath is provided, the loader canonicalizes both the resolved path and baseDir, rejecting symlinks that escape the declaring directory. When absent (e.g. CF Workers), the check is skipped.

7. File system abstraction

Use createNodeFileSystem() for a real node:fs-backed filesystem (Node/Bun) or createCfFileSystem() for a Cloudflare Workers stub:

import { createNodeFileSystem, createCfFileSystem } from '@gobing-ai/ts-runtime';

// Node.js / Bun — real filesystem (sync node:fs)
const fs = createNodeFileSystem('/path/to/project');
const content = fs.readFile('src/index.ts');     // string
fs.writeFile('output.json', JSON.stringify(data));
fs.ensureDir('tmp/cache');                       // recursive mkdir

// Cloudflare Workers — stub (throws on mutating ops)
const cffs = createCfFileSystem();
cffs.getProjectRoot();   // '/bundle'
cffs.readFile('/x');     // throws: "use D1, KV, or R2"

Optional streaming and symlink-safe operations:

// Stream large files line-by-line (ADR-021) — Node/Bun only.
// The JSONL importer uses this to avoid buffering multi-GB files.
if (fs.readFileStream) {
  for await (const line of fs.readFileStream('data/huge.jsonl')) {
    // process one line at a time
  }
}

// Canonical path resolution for symlink-safe extension confinement (ADR-022).
// The extension loader uses this to verify that a symlink hasn't escaped baseDir.
if (fs.realPath) {
  const real = fs.realPath('/base/extensions/linked.ts');
}

Both are optional — CF Workers stubs omit them. The JSONL importer falls back to readFile + split when readFileStream is absent; the extension loader skips the symlink check when realPath is absent.

The legacy getFs() / setFileSystem() global swap, SyncFileSystem, and the old filesystem classes were removed in ADR-019. Use createNodeFileSystem(), createCfFileSystem(), or ctx.require('fileSystem') instead.

8. Database adapter (createDbAdapter)

The factory's createDbAdapter(config) opens a connected adapter satisfying the RuntimeDbAdapter contract (the runtime-facing subset of @gobing-ai/ts-db's DbAdapter) at the configured path. ts-runtime owns connection; the consumer owns schema — the returned adapter is connected but NOT migrated. The consumer composes its own migrations on top.

import { loadRuntimeFactory } from '@gobing-ai/ts-runtime';

const factory = await loadRuntimeFactory();

if (factory.capabilities.hasSqlDatabase) {
    const adapter = await factory.createDbAdapter({ url: '.spur/spur.db' });
    // adapter is connected — apply YOUR migrations here, then use DAOs.
    adapter.close();
}

On Cloudflare Workers, capabilities.hasSqlDatabase is false and createDbAdapter throws a typed D1NotConfiguredError — the method exists on the interface so consumer code is forward-compatible and needs no change when the D1 round ships.

Dependency note (optional peer): @gobing-ai/ts-db is declared as an optional peerDependency of ts-runtime (ADR-012 addendum), not a regular dependency — a regular entry would create a manifest cycle (ts-db depends on ts-runtime) and force-install ts-db (plus its drizzle-orm peer) on every consumer, including Workers bundles and apps that never touch SQL. The factory interface uses a structural RuntimeDbAdapter type (defined locally) that a ts-db DbAdapter satisfies via structural subtyping; nodeBunFactory.createDbAdapter loads ts-db via a literal dynamic import() at runtime.

Who must install it: only consumers that call nodeBunFactory.createDbAdapter on Node/Bun — install @gobing-ai/ts-db yourself (bun add @gobing-ai/ts-db). Workers consumers do not need it (capabilities.hasSqlDatabase is false; the method throws D1NotConfiguredError).

Bundling (Bun --compile / esbuild / Vite): the literal specifier keeps ts-db bundler-visible, so Bun --compile can fold it into a standalone binary. If you bundle for a different runtime, mark @gobing-ai/ts-db external to preserve the dynamic import.

Failure mode: if @gobing-ai/ts-db is absent or exports no createDbAdapter (incompatible version), createDbAdapter throws a typed DbModuleNotInstalledError (with the underlying resolution error chained as cause) instead of a raw MODULE_NOT_FOUND.

9. Graceful disposal

RuntimeContext.dispose() calls dispose() on every registered service that implements the pattern:

process.on('SIGTERM', async () => { await ctx.dispose(); process.exit(0); });


## Usage

### Install

```bash
bun add @gobing-ai/ts-runtime

Basic setup (Node/Bun)

import { createRuntimeContextFromFactory } from '@gobing-ai/ts-runtime';

const ctx = await createRuntimeContextFromFactory();
const fs = ctx.require('fileSystem');
fs.writeFile('hello.txt', 'Hello, world!');

Cloudflare Workers

import { createCfFileSystem, createRuntimeContext } from '@gobing-ai/ts-runtime';

export default {
    async fetch(request: Request, env: Env): Promise<Response> {
        const ctx = createRuntimeContext({
            runtimeName: 'cloudflare-workers',
            capabilities: { hasFilesystem: false, hasProcessExecution: false, hasPersistentStorage: false },
            services: { fileSystem: createCfFileSystem() },
        });
        // ...
    },
};

Config with env interpolation

import { buildConfigFromYaml, buildConfigFromObject } from '@gobing-ai/ts-runtime';

// From YAML file
const config = buildConfigFromYaml(yamlText);

// From plain object (programmatic config)
const config = buildConfigFromObject({
    app: { name: 'api', env: 'production', port: 3000 },
    database: { url: ':memory:' },
});

// From YAML file const config = buildConfigFromYaml(yamlText);

// From plain object (programmatic config) const config = buildConfigFromObject({ app: { name: 'api', env: 'production', port: 3000 }, database: { url: ':memory:' }, });


### Process execution

`ProcessExecutor` is the canonical interface for process execution. `NodeProcessExecutor` is the concrete implementation wrapping `execa` (buffered) and `Bun.spawn` (streaming):

```ts
import { NodeProcessExecutor, createInMemoryProcessRegistry } from '@gobing-ai/ts-runtime';

// Optional: shared registry so every run/runStreaming is listable (spur#0264 / M1).
const registry = createInMemoryProcessRegistry();
const exec = new NodeProcessExecutor({ defaultTimeout: 30_000, registry });

// Buffered — captures stdout/stderr, no throw on non-zero
const result = await exec.run({
    command: 'git',
    args: ['status', '--short'],
    cwd: '/path/to/repo',
    rejectOnError: true,
    // Optional registry metadata (defaults: run → source 'one-shot')
    label: 'git.status',
});

console.log(result.stdout);          // 'M src/index.ts\n'
console.log(`Duration: ${result.durationMs}ms`);

// Streaming — interactive subprocess with stdin control
const proc = exec.runStreaming({
    command: 'cat',
    source: 'supervisor', // tag supervised agent loops
    agentId: 'alpha-claude',
});
proc.writeStdin('hello\n');
proc.endStdin();
const exitCode = await proc.exited; // 0

// Watch list snapshot + live subscription
console.log(registry.listExecutions());
const unsub = registry.subscribe((event) => {
    if (event.type === 'started' || event.type === 'exited') {
        console.log(event.type, event.execution.id, event.execution.command);
    }
});
unsub();

rejectOnError: true throws on non-zero exits. OutputPolicy controls buffered vs streamed output. ProcessOptions supports timeout, env, cwd, maxOutput, forceBuffered, an optional synchronous onOutput({ stream, chunk, timestamp }) observer, and registry fields (source, teamId, agentId). onOutput observes live chunks while the returned ProcessResult retains the complete buffered stdout/stderr; observers must enqueue and return, and thrown observer errors are isolated from the child. Inject the same ProcessRegistry into every executor that should appear in one watch list; without a registry, behavior is unchanged.

Deadlines, cancellation, and process-group containment (Unix)

On Unix, a finite timeout or a supplied signal puts the run under executor-owned process-group containment: the child is spawned detached as a process-group leader, the executor runs one termination sequence (group SIGTERM, a killGraceMs grace — default 5000 ms — then group SIGKILL), and escalation is driven by group liveness, never by the leader exiting first. Completion therefore reaps descendants that survive the leader while holding inherited output pipes or a SQLite write transaction, so run() completion is a containment barrier: after it resolves, no owned descendant remains (best-effort for SIGKILL-immune members — escalation gives up after a bounded settle). runStreaming keeps direct-child semantics and provides no group containment.

  • timeout: number — positive-integer deadline in ms; expiry reports outcome: 'timeout'.
  • timeout: null — unlimited; overrides a finite defaultTimeout from ProcessExecutorConfig.
  • omitted — inherits defaultTimeout (which may itself be null/unlimited).
  • timeout: 0, negative, fractional, NaN, ±Infinity, or beyond the native timer range — rejected with TypeError before spawn; killGraceMs must be a non-negative integer.
  • abort signal — reports outcome: 'cancelled'; a deadline is never a cancellation and vice versa. Deadline and abort feed one escalation path, so callers must not arm a competing watchdog over the same child.

ProcessResult.outcome ('exit' | 'timeout' | 'cancelled' | 'signal' | 'error', aliased as ProcessExitReason) states why the run ended; process.exited events carry the same reason. On Windows (and when no deadline or signal is supplied), execa's direct-child timeout and cancellation semantics apply unchanged: only the direct child is killed, and the outcome is classified from the result.

Cloudflare Workers do not expose process execution; check factory.capabilities.hasProcessExecution first.

The ProcessExecutor const (value alias for NodeProcessExecutor), BunSyncProcessExecutor, and BunPipeProcessSpawner are kept as deprecated backward-compatible wrappers. Prefer NodeProcessExecutor or nodeBunFactory.createProcessExecutor() in new code.

Deprecation status (task 0087 R7): sync callers now default to the non-deprecated NodeSyncProcessExecutor (node spawnSync) — identity.ts was migrated off the BunSyncProcessExecutor default. BunSyncProcessExecutor and BunPipeProcessSpawner remain exported-deprecated and are deleted in the next major version. The process-group containment machinery lives in src/process-group.ts (extracted from process-executor.ts, task 0087 R8 — pure move, no behavior change).

SpanContext (for telemetry)

import type { SpanContext } from '@gobing-ai/ts-runtime';

function processRequest(ctx: SpanContext) {
    console.log(`Trace: ${ctx.traceId}, Span: ${ctx.spanId}`);
}

版本与发布记录

@gobing-ai/ts-runtime 共发布 137 个版本,首次发布于 2026/05/30;过去 12 个月发布了 137 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.7.1latest2026/10/2522 天前
0.7.02026/10/2522 天前
0.6.42026/10/2423 天前
0.6.32026/10/2424 天前
0.6.22026/10/2324 天前
0.6.12026/10/2324 天前

关于 @gobing-ai/ts-runtime 的常见问题

@gobing-ai/ts-runtime 是什么?

@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.

如何安装 @gobing-ai/ts-runtime?

在项目目录运行 npm install @gobing-ai/ts-runtime,或使用 pnpm add / yarn add / bun add。

@gobing-ai/ts-runtime 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gobing-ai/ts-runtime 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gobing-ai/ts-runtime 可以商用吗?

@gobing-ai/ts-runtime 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gobing-ai/ts-runtime 的下载量有多少?

根据 npm 官方下载统计,@gobing-ai/ts-runtime 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,149 次,日均约 172 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gobing-ai/ts-runtime 还在维护吗?

最新版本 0.7.1 发布于 2026/10/25(22 天前);至今共发布 137 个版本,其中过去 12 个月发布了 137 个;首次发布于 2026/05/30。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。