@gobing-ai/ts-runtime 0.1.0

package/dist/process-executor.d.ts

@@ -0,0 +1,41 @@
+export type OutputPolicy = {
+    mode: 'buffered';
+} | {
+    mode: 'stream';
+    isTTY?: boolean;
+};
+export interface ProcessExecutorConfig {
+    defaultTimeout?: number;
+    defaultMaxOutput?: number;
+    output?: OutputPolicy;
+}
+export interface ProcessOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeout?: number;
+    /** Maximum output buffer size in bytes (maps to execa `maxBuffer`). */
+    maxOutput?: number;
+    label?: string;
+    rejectOnError?: boolean;
+    forceBuffered?: boolean;
+}
+export interface ProcessResult {
+    command: string;
+    args: string[];
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    signal?: string;
+    durationMs: number;
+}
+export interface ProcessExecutor {
+    run(options: ProcessOptions): Promise<ProcessResult>;
+}
+export declare class NodeProcessExecutor implements ProcessExecutor {
+    private readonly config;
+    constructor(config?: ProcessExecutorConfig);
+    run(options: ProcessOptions): Promise<ProcessResult>;
+}
+//# sourceMappingURL=process-executor.d.ts.map

package/dist/process-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-executor.d.ts","sourceRoot":"","sources":["../src/process-executor.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,qBAAqB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC5B,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACxD;AAED,qBAAa,mBAAoB,YAAW,eAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,qBAA0B;IAEzD,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CA2C7D"}

package/dist/process-executor.js

@@ -0,0 +1,70 @@
+import { isatty } from 'node:tty';
+import { execa } from 'execa';
+export class NodeProcessExecutor {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    async run(options) {
+        const args = options.args ?? [];
+        const execaOptions = buildExecaOptions({
+            cwd: options.cwd,
+            env: options.env,
+            timeout: options.timeout ?? this.config.defaultTimeout,
+            maxOutput: options.maxOutput ?? this.config.defaultMaxOutput,
+            rejectOnError: options.rejectOnError ?? false,
+            outputPolicy: this.config.output,
+            forceBuffered: options.forceBuffered ?? false,
+        });
+        try {
+            const result = await execa(options.command, args, execaOptions);
+            return {
+                command: options.command,
+                args,
+                exitCode: result.exitCode ?? null,
+                stdout: asString(result.stdout),
+                stderr: asString(result.stderr),
+                ...(result.signalDescription !== undefined ? { signal: result.signalDescription } : {}),
+                durationMs: result.durationMs,
+            };
+        }
+        catch (error) {
+            if (options.rejectOnError)
+                throw error;
+            const failed = error;
+            return {
+                command: options.command,
+                args,
+                exitCode: failed.exitCode ?? null,
+                stdout: asString(failed.stdout),
+                stderr: asString(failed.stderr),
+                ...(failed.signalDescription !== undefined ? { signal: failed.signalDescription } : {}),
+                durationMs: failed.durationMs ?? 0,
+            };
+        }
+    }
+}
+function buildExecaOptions(opts) {
+    const canStream = !opts.forceBuffered &&
+        opts.outputPolicy?.mode === 'stream' &&
+        (opts.outputPolicy.isTTY ?? process.stdout.isTTY ?? isatty(1));
+    return {
+        reject: opts.rejectOnError,
+        stdin: 'ignore',
+        stripFinalNewline: true,
+        ...(canStream ? { stdout: ['inherit', 'pipe'], stderr: ['inherit', 'pipe'] } : { all: true }),
+        ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        ...(opts.env !== undefined ? { env: opts.env } : {}),
+        ...(opts.timeout !== undefined ? { timeout: opts.timeout } : {}),
+        ...(opts.maxOutput !== undefined ? { maxBuffer: opts.maxOutput } : {}),
+    };
+}
+function asString(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value instanceof Uint8Array)
+        return new TextDecoder().decode(value);
+    if (Array.isArray(value))
+        return value.map(String).join('');
+    return '';
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import type { Config } from './config';
+import type { RuntimeContext } from './context';
+import type { FileSystem } from './fs';
+export type RuntimeName = 'node-bun' | 'cloudflare-workers' | 'test';
+export interface RuntimeCapabilities {
+    readonly hasFilesystem: boolean;
+    readonly hasProcessExecution: boolean;
+    readonly hasPersistentStorage: boolean;
+}
+export interface LoadConfigOptions {
+    overrides?: Partial<Config>;
+    envBindings?: Record<string, unknown>;
+}
+export interface RuntimeFactory {
+    readonly runtimeName: RuntimeName;
+    readonly capabilities: RuntimeCapabilities;
+    createFileSystem(): FileSystem;
+    loadConfig(options?: LoadConfigOptions): Promise<Config>;
+    createContext?(options?: {
+        scope?: string;
+    }): RuntimeContext;
+}
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+    baggage?: Record<string, string>;
+    attributes?: Record<string, string | number | boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,oBAAoB,GAAG,MAAM,CAAC;AAErE,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,gBAAgB,IAAI,UAAU,CAAC;IAC/B,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,aAAa,CAAC,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC;CAChE;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CAC1D"}

package/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@gobing-ai/ts-runtime",
+    "version": "0.1.0",
+    "description": "@gobing-ai/ts-runtime — Runtime abstractions for Bun, Node, and Cloudflare Workers.",
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/fix-dist-esm-extensions.ts dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "npm publish --access public"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-utils": "^0.1.0",
+        "execa": "^9.5.0",
+        "yaml": "^2.7.0",
+        "zod": "^4.1.0"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/config.ts

@@ -0,0 +1,169 @@
+import { parse as parseYaml } from 'yaml';
+import { type ZodIssue, z } from 'zod';
+
+export const configSchema = z.object({
+    app: z
+        .object({
+            name: z.string().default('app'),
+            env: z.enum(['development', 'staging', 'production', 'test']).default('development'),
+            port: z.number().int().positive().default(3000),
+        })
+        .default({ name: 'app', env: 'development', port: 3000 }),
+    database: z
+        .object({
+            url: z.string().default(':memory:'),
+        })
+        .default({ url: ':memory:' }),
+    logging: z
+        .object({
+            level: z.enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal']).default('info'),
+            console: z.boolean().default(true),
+            file: z.boolean().default(false),
+            filePath: z.string().optional(),
+            json: z.boolean().default(false),
+        })
+        .default({ level: 'info', console: true, file: false, json: false }),
+});
+
+export type Config = z.output<typeof configSchema>;
+
+const ENV_INTERPOLATION_RE = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+
+export class ConfigLoadError extends Error {
+    readonly issues: ZodIssue[];
+
+    constructor(message: string, issues: ZodIssue[] = []) {
+        super(message);
+        this.name = 'ConfigLoadError';
+        this.issues = issues;
+    }
+}
+
+export function getNodeEnv(): string {
+    return process.env.NODE_ENV ?? 'development';
+}
+
+export function isTestEnv(): boolean {
+    return getNodeEnv() === 'test';
+}
+
+export function getDatabaseUrl(): string | undefined {
+    return process.env.DATABASE_URL;
+}
+
+export function interpolateEnv(value: string): string {
+    return value.replace(ENV_INTERPOLATION_RE, (_match, name: string) => process.env[name] ?? `\${${name}}`);
+}
+
+export function interpolateTree(value: unknown): unknown {
+    if (typeof value === 'string') return interpolateEnv(value);
+    if (Array.isArray(value)) return value.map(interpolateTree);
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, interpolateTree(child)]));
+    }
+    return value;
+}
+
+export function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = deepMerge(result[key] as Record<string, unknown>, value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+export function flattenKeys(obj: Record<string, unknown>, prefix = ''): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(obj)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (isPlainObject(value)) {
+            Object.assign(result, flattenKeys(value, fullKey));
+        } else {
+            result[fullKey] = JSON.stringify(value);
+        }
+    }
+    return result;
+}
+
+export function deFlattenKeys(entries: Record<string, string>): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [key, rawValue] of Object.entries(entries)) {
+        const parts = key.split('.');
+        let current = result;
+        for (const part of parts.slice(0, -1)) {
+            if (!isPlainObject(current[part])) current[part] = {};
+            current = current[part] as Record<string, unknown>;
+        }
+
+        const last = parts.at(-1);
+        if (last === undefined) continue;
+        current[last] = parseConfigValue(rawValue);
+    }
+    return result;
+}
+
+export function buildConfigFromObject(
+    raw: Record<string, unknown>,
+    options: { overrides?: Partial<Config> } = {},
+): Config {
+    const interpolated = interpolateTree(raw) as Record<string, unknown>;
+    const merged = options.overrides
+        ? deepMerge(interpolated, options.overrides as unknown as Record<string, unknown>)
+        : interpolated;
+    const result = configSchema.safeParse(merged);
+    if (!result.success) {
+        throw new ConfigLoadError('Config validation failed', result.error.issues);
+    }
+    return deepFreeze(result.data);
+}
+
+export function parseConfigYaml(yamlText: string): Record<string, unknown> {
+    try {
+        const parsed = parseYaml(yamlText);
+        if (parsed === null || parsed === undefined) return {};
+        if (!isPlainObject(parsed)) {
+            throw new ConfigLoadError('Config YAML must parse to an object');
+        }
+        return parsed;
+    } catch (error) {
+        if (error instanceof ConfigLoadError) throw error;
+        throw new ConfigLoadError(`Config YAML parsing failed: ${(error as Error).message}`);
+    }
+}
+
+export function buildConfigFromYaml(yamlText: string, options: { overrides?: Partial<Config> } = {}): Config {
+    return buildConfigFromObject(parseConfigYaml(yamlText), options);
+}
+
+function parseConfigValue(value: string): unknown {
+    try {
+        return JSON.parse(value);
+    } catch {
+        return value;
+    }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function deepFreeze<T extends Record<string, unknown>>(obj: T): T {
+    Object.freeze(obj);
+    for (const value of Object.values(obj)) {
+        if (Array.isArray(value)) {
+            Object.freeze(value);
+            for (const item of value) {
+                if (isPlainObject(item) && !Object.isFrozen(item)) {
+                    deepFreeze(item as Record<string, unknown>);
+                }
+            }
+        } else if (isPlainObject(value) && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+    return obj;
+}

package/src/context.ts

@@ -0,0 +1,97 @@
+import type { Config } from './config';
+import { buildConfigFromObject } from './config';
+import type { FileSystem } from './fs';
+import { getFs } from './fs';
+import type { RuntimeCapabilities, RuntimeFactory, RuntimeName } from './types';
+
+export type RuntimeScope = 'process' | 'server-request' | 'scheduled-event' | 'test';
+
+export interface RuntimeServiceMap {
+    config: Config;
+    fileSystem: FileSystem;
+    [serviceName: string]: unknown;
+}
+
+export interface RuntimeContextOptions<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
+    scope?: RuntimeScope;
+    runtimeName?: RuntimeName;
+    capabilities?: RuntimeCapabilities;
+    services?: Partial<TServices>;
+    factory?: RuntimeFactory;
+}
+
+export class RuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap> {
+    readonly scope: RuntimeScope;
+    readonly runtimeName: RuntimeName;
+    readonly capabilities: RuntimeCapabilities;
+    readonly services = new Map<keyof TServices, TServices[keyof TServices]>();
+
+    constructor(options: RuntimeContextOptions<TServices> = {}) {
+        this.scope = options.scope ?? 'process';
+        this.runtimeName = options.runtimeName ?? options.factory?.runtimeName ?? 'node-bun';
+        this.capabilities =
+            options.capabilities ??
+            options.factory?.capabilities ??
+            ({
+                hasFilesystem: true,
+                hasProcessExecution: true,
+                hasPersistentStorage: true,
+            } satisfies RuntimeCapabilities);
+
+        this.register('config', (options.services?.config ?? buildConfigFromObject({})) as TServices['config']);
+        this.register('fileSystem', (options.services?.fileSystem ?? getFs()) as TServices['fileSystem']);
+
+        for (const [key, value] of Object.entries(options.services ?? {})) {
+            if (value !== undefined) {
+                this.register(key as keyof TServices, value as TServices[keyof TServices]);
+            }
+        }
+    }
+
+    register<K extends keyof TServices>(key: K, service: TServices[K]): this {
+        this.services.set(key, service);
+        return this;
+    }
+
+    get<K extends keyof TServices>(key: K): TServices[K] | undefined {
+        return this.services.get(key) as TServices[K] | undefined;
+    }
+
+    require<K extends keyof TServices>(key: K): TServices[K] {
+        const service = this.get(key);
+        if (service === undefined) {
+            throw new Error(`Runtime service "${String(key)}" is unavailable for runtime ${this.runtimeName}.`);
+        }
+        return service;
+    }
+
+    has<K extends keyof TServices>(key: K): boolean {
+        return this.services.has(key);
+    }
+
+    async dispose(): Promise<void> {
+        const errors: Error[] = [];
+        for (const service of this.services.values()) {
+            if (isDisposable(service)) {
+                try {
+                    await service.dispose();
+                } catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+        }
+        if (errors.length > 0) {
+            throw new Error(`Failed to dispose some services:\n${errors.map((e) => `- ${e.message}`).join('\n')}`);
+        }
+    }
+}
+
+function isDisposable(value: unknown): value is { dispose(): void | Promise<void> } {
+    return typeof value === 'object' && value !== null && 'dispose' in value && typeof value.dispose === 'function';
+}
+
+export function createRuntimeContext<TServices extends RuntimeServiceMap = RuntimeServiceMap>(
+    options: RuntimeContextOptions<TServices> = {},
+): RuntimeContext<TServices> {
+    return new RuntimeContext<TServices>(options);
+}