@gobing-ai/ts-infra 0.3.3 → 0.3.5

package/dist/application-node.js

@@ -0,0 +1,245 @@
+/**
+ * Node/Bun convenience bootstrap for `@gobing-ai/ts-infra`.
+ *
+ * Composes the portable `runApplication` with runtime-specific wiring:
+ * - YAML config loading via `@gobing-ai/ts-runtime`
+ * - Application-specific config validation with caller-provided validator
+ * - File log sink via `node:fs`
+ * - Bun SQLite DB adapter creation from config
+ * - Optional Node OTel exporter initialization
+ * - Optional Node scheduler adapter
+ *
+ * This subpath may import runtime-specific adapters. The portable bootstrap
+ * subpath (`@gobing-ai/ts-infra/application`) must not.
+ *
+ * @module application-node
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createDbAdapter } from '@gobing-ai/ts-db';
+import { interpolateTree, parseYamlObject } from '@gobing-ai/ts-runtime';
+import { runApplication } from './application/index.js';
+import { NodeSchedulerAdapter } from './scheduler-node.js';
+import { initNodeTelemetry, shutdownNodeTelemetry } from './telemetry/otel-node.js';
+// ── Errors ────────────────────────────────────────────────────────────────
+/** Error thrown when application config validation fails. Includes file path and section name. */
+export class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+// ── Config validation helper ──────────────────────────────────────────────
+/**
+ * Validate a raw config section using the caller-provided validator.
+ * Supports structural `safeParse`, `validate()`, `parse()`, and bare function forms.
+ */
+function validateAppConfig(validator, raw, section, filePath) {
+    if (typeof validator === 'object' && 'safeParse' in validator) {
+        const result = validator.safeParse(raw);
+        if (!result.success) {
+            const details = result.errors?.map((e) => `${e.path}: ${e.message}`).join('; ') ?? 'unknown error';
+            throw new ConfigValidationError(`Application config validation failed in section "${section}"` +
+                (filePath ? ` (file: ${filePath})` : '') +
+                `: ${details}`);
+        }
+        return result.data;
+    }
+    if (typeof validator === 'function') {
+        return validator(raw);
+    }
+    if (typeof validator === 'object' && 'validate' in validator) {
+        return validator.validate(raw);
+    }
+    if (typeof validator === 'object' && 'parse' in validator) {
+        return validator.parse(raw);
+    }
+    throw new ConfigValidationError(`Unsupported validator shape for section "${section}"`);
+}
+// ── File sink helper ──────────────────────────────────────────────────────
+function createFileSink(filePath) {
+    return (line) => {
+        try {
+            mkdirSync(dirname(filePath), { recursive: true });
+            appendFileSync(filePath, line);
+        }
+        catch {
+            // Best-effort — don't crash on log write failure
+        }
+    };
+}
+function loadYamlConfig(loader, fileContent) {
+    const bootstrapSection = loader.bootstrapSection ?? 'bootstrap';
+    let raw;
+    if (fileContent !== undefined) {
+        raw = parseYamlObject(fileContent);
+    }
+    else if (loader.overrides) {
+        raw = { ...loader.overrides };
+    }
+    else {
+        raw = {};
+    }
+    // Interpolate environment variables (Node/Bun only)
+    raw = interpolateTree(raw);
+    // Extract bootstrap section
+    const bootstrapSection_ = raw[bootstrapSection];
+    const bootstrapConfig = typeof bootstrapSection_ === 'object' && bootstrapSection_ !== null
+        ? bootstrapSection_
+        : {};
+    // Extract app config section
+    let appConfig;
+    if (loader.appConfig) {
+        const appSection = loader.appSection;
+        const appRaw = appSection
+            ? raw[appSection]
+            : (() => {
+                // Default: full remaining object minus bootstrap section
+                const remaining = {};
+                for (const [key, value] of Object.entries(raw)) {
+                    if (key !== bootstrapSection) {
+                        remaining[key] = value;
+                    }
+                }
+                return remaining;
+            })();
+        appConfig = validateAppConfig(loader.appConfig, appRaw, appSection ?? '*', loader.configFile);
+    }
+    return { bootstrapConfig, appConfig };
+}
+// ── Public API ────────────────────────────────────────────────────────────
+/**
+ * Node/Bun convenience application bootstrap.
+ *
+ * Extends the portable `runApplication` with:
+ * - YAML config file loading with section splitting
+ * - Application-specific config validation
+ * - File log sink creation from `logging.filePath`
+ * - Bun SQLite DB adapter creation when `database.enabled` + `database.driver`
+ * - Optional Node OTel telemetry exporter
+ * - Optional Node scheduler adapter
+ *
+ * @example
+ * ```ts
+ * import { runNodeApplication } from '@gobing-ai/ts-infra/application-node';
+ *
+ * await runNodeApplication({
+ *     configLoader: {
+ *         configFile: 'config/app.yaml',
+ *         bootstrapSection: 'bootstrap',
+ *         appSection: 'billing',
+ *         appConfig: {
+ *             safeParse(raw) {
+ *                 return billingSchema.safeParse(raw);
+ *             },
+ *         },
+ *     },
+ *     async start(app) {
+ *         app.logger.info('started');
+ *     },
+ * });
+ * ```
+ */
+export async function runNodeApplication(options) {
+    let nodeTelemetryInitialized = false;
+    // ── Load config ─────────────────────────────────────────────────────
+    let loadedAppConfig;
+    let yamlBootstrap = {};
+    if (options.configLoader?.configFile) {
+        const fileContent = readFileSync(options.configLoader.configFile, 'utf-8');
+        const loaded = loadYamlConfig(options.configLoader, fileContent);
+        yamlBootstrap = loaded.bootstrapConfig;
+        loadedAppConfig = loaded.appConfig;
+    }
+    else if (options.configLoader) {
+        const loaded = loadYamlConfig(options.configLoader, undefined);
+        yamlBootstrap = loaded.bootstrapConfig;
+        loadedAppConfig = loaded.appConfig;
+    }
+    // ── Resolve bootstrap config from YAML + inline options ────────────
+    // YAML loads as Record<string, unknown>; bridge into typed options.
+    // Inline options (options.config) take precedence over YAML sections.
+    const yamlLog = yamlBootstrap.logging;
+    const yamlTel = yamlBootstrap.telemetry;
+    const yamlSched = yamlBootstrap.scheduler;
+    const databaseOpts = (yamlBootstrap.database ?? {});
+    const loggingOpts = {
+        ...yamlLog,
+        ...options.config?.logging,
+    };
+    const telemetryOpts = {
+        ...yamlTel,
+        ...options.config?.telemetry,
+    };
+    const schedulerOpts = {
+        ...yamlSched,
+        ...options.config?.scheduler,
+    };
+    // File sink from logging.filePath
+    const logFilePath = yamlBootstrap.logging?.filePath;
+    const loggingConfig = typeof logFilePath === 'string' ? { ...loggingOpts, fileSink: createFileSink(logFilePath) } : loggingOpts;
+    // ── Node OTel telemetry ─────────────────────────────────────────────
+    const rawTel = { ...telemetryOpts };
+    if (rawTel.enabled !== false && rawTel.endpoint) {
+        initNodeTelemetry({
+            serviceName: rawTel.serviceName ?? 'ts-libs',
+            endpoint: rawTel.endpoint,
+            headers: rawTel.headers,
+        });
+        nodeTelemetryInitialized = true;
+    }
+    // ── DB adapter ──────────────────────────────────────────────────────
+    let dbAdapter = options.services?.db;
+    if (!dbAdapter && databaseOpts.enabled === true) {
+        const driver = databaseOpts.driver;
+        if (driver === 'bun-sqlite') {
+            const adapter = await createDbAdapter({
+                driver: 'bun-sqlite',
+                url: databaseOpts.url,
+            });
+            dbAdapter = adapter;
+        }
+        else {
+            throw new ConfigValidationError(`database.enabled is true but driver ${driver ? `"${driver}"` : 'is missing'} is not supported ` +
+                `(expected "bun-sqlite"). Provide a supported driver or inject a DbAdapter via services.db.`);
+        }
+    }
+    // ── Scheduler adapter ───────────────────────────────────────────────
+    const schedulerConfig = {};
+    const rawSched = { ...schedulerOpts };
+    if (rawSched.enabled === true) {
+        schedulerConfig.enabled = true;
+        schedulerConfig.autoStart = schedulerOpts.autoStart;
+        // Use Node scheduler adapter by default in this subpath
+        schedulerConfig.adapter = new NodeSchedulerAdapter();
+    }
+    // ── Delegate to portable runApplication ─────────────────────────────
+    const app = await runApplication({
+        config: {
+            ...options.config,
+            logging: loggingConfig,
+            telemetry: telemetryOpts,
+            scheduler: schedulerConfig,
+        },
+        appConfig: loadedAppConfig,
+        services: {
+            ...options.services,
+            ...(dbAdapter ? { db: dbAdapter } : {}),
+        },
+        start: options.start,
+        stop: options.stop,
+    });
+    // ── Compose a handle with Node-specific cleanup on stop ─────────────
+    const originalStop = app.stop.bind(app);
+    return {
+        ...app,
+        stop: async (reason) => {
+            await originalStop(reason);
+            // Node-specific cleanup (after portable shutdown):
+            // 5. Shut down Node telemetry exporter
+            if (nodeTelemetryInitialized) {
+                await shutdownNodeTelemetry();
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-infra",
-    "version": "0.3.3",
+    "version": "0.3.5",
     "description": "@gobing-ai/ts-infra — Infrastructure backbone: event bus, job queue, scheduler, telemetry, API client, and logging.",
     "keywords": [
         "typescript",
@@ -47,6 +47,14 @@
         "./scheduler-node": {
             "types": "./dist/scheduler-node.d.ts",
             "import": "./dist/scheduler-node.js"
+        },
+        "./application": {
+            "types": "./dist/application/index.d.ts",
+            "import": "./dist/application/index.js"
+        },
+        "./application-node": {
+            "types": "./dist/application-node.d.ts",
+            "import": "./dist/application-node.js"
         }
     },
     "files": [
@@ -69,7 +77,8 @@
         "@logtape/logtape": "^2.0.0"
     },
     "peerDependencies": {
-        "@gobing-ai/ts-db": "^0.3.3",
+        "@gobing-ai/ts-db": "^0.3.5",
+        "@gobing-ai/ts-runtime": "^0.3.5",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",
         "@opentelemetry/sdk-metrics": "^2.0.0",
@@ -82,6 +91,9 @@
         "@gobing-ai/ts-db": {
             "optional": true
         },
+        "@gobing-ai/ts-runtime": {
+            "optional": true
+        },
         "@opentelemetry/sdk-trace-node": {
             "optional": true
         },
@@ -99,7 +111,8 @@
         }
     },
     "devDependencies": {
-        "@gobing-ai/ts-db": "^0.3.3",
+        "@gobing-ai/ts-db": "^0.3.5",
+        "@gobing-ai/ts-runtime": "^0.3.5",
         "@types/bun": "1.3.14",
         "@opentelemetry/api": "^1.9.0",
         "@opentelemetry/sdk-trace-node": "^2.0.0",

package/src/application/index.ts

@@ -0,0 +1,278 @@
+/**
+ * Portable `runApplication` — DI bootstrap over existing ts-infra primitives.
+ *
+ * Orchestrates logger, telemetry, event bus, (optional) DB adapter, and
+ * (optional) scheduler into a deterministic startup/shutdown lifecycle.
+ * The portable subpath never opens files, creates DB connections, or wires
+ * runtime-specific exporters — those are injected or handled by the
+ * Node/Bun convenience subpath.
+ *
+ * @module application
+ */
+
+import { attachDefaultObservers, createLifecycleBus } from '../event-bus/default-observers';
+import { EventBus } from '../event-bus/event-bus';
+import type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+import type { InfraEvents } from '../events';
+import { getLogger, initializeLogger, type Logger } from '../logger';
+import { initScheduler, setSchedulerAdapter } from '../scheduler/factory';
+import type { SchedulerAdapter } from '../scheduler/types';
+import { initTelemetry, shutdownTelemetry } from '../telemetry/sdk';
+import type {
+    ApplicationBootstrapConfig,
+    ApplicationBootstrapOptions,
+    ApplicationRuntime,
+    ApplicationStopReason,
+    DbAdapterLike,
+} from './types';
+
+// ── Internal runtime state ────────────────────────────────────────────────
+
+interface RuntimeState<TAppConfig, TEvents extends EventMap> {
+    app: ApplicationRuntime<TAppConfig, TEvents> | undefined;
+    userStop?: (app: ApplicationRuntime<TAppConfig, TEvents>, reason: ApplicationStopReason) => Promise<void> | void;
+    schedulerAdapter?: SchedulerAdapter;
+    schedulerStarted: boolean;
+    loggerInitialized: boolean;
+    telemetryInitialized: boolean;
+    stopped: boolean;
+}
+
+// ── Shutdown (deterministic reverse order per R5) ─────────────────────────
+
+async function performShutdown<TAppConfig, TEvents extends EventMap>(
+    state: RuntimeState<TAppConfig, TEvents>,
+    reason: ApplicationStopReason,
+): Promise<void> {
+    if (state.stopped) return;
+    state.stopped = true;
+
+    const app = state.app;
+    if (!app) return;
+
+    // 1. User stop callback
+    if (state.userStop) {
+        await state.userStop(app, reason);
+    }
+
+    // 2. Stop scheduler
+    if (state.schedulerStarted && state.schedulerAdapter) {
+        await state.schedulerAdapter.stop().catch(() => {});
+        state.schedulerStarted = false;
+    }
+
+    // 3. Close DB adapter
+    if (app.db) {
+        try {
+            app.db.close();
+        } catch {
+            /* best-effort */
+        }
+    }
+
+    // 4. Shutdown telemetry
+    if (state.telemetryInitialized) {
+        await shutdownTelemetry();
+        state.telemetryInitialized = false;
+    }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+/**
+ * Portable application bootstrap.
+ *
+ * Orchestrates logger, telemetry, events, optional DB, and optional scheduler.
+ * Accepts injected dependencies; never opens files, reads config from disk,
+ * or wires runtime-specific exporters.
+ *
+ * Startup order (deterministic, per R5):
+ * 1. Resolve bootstrap config + app config
+ * 2. Initialize logger
+ * 3. Initialize telemetry
+ * 4. Create lifecycle bus + application EventBus
+ * 5. Register DB adapter (injected only)
+ * 6. Initialize scheduler + register entries
+ * 7. Call user `start(app)` callback
+ * 8. Start scheduler if `autoStart`
+ *
+ * Shutdown order (reverse, per R5):
+ * 1. User `stop(app, reason)` callback
+ * 2. Stop scheduler
+ * 3. Close DB adapter
+ * 4. Shut down telemetry
+ *
+ * If any startup step fails, already-started services are cleaned up in reverse
+ * order before rethrowing. `stop()` is idempotent.
+ *
+ * @example
+ * ```ts
+ * import { runApplication } from '@gobing-ai/ts-infra/application';
+ *
+ * const app = await runApplication({
+ *     config: { logging: { level: 'debug' } },
+ *     async start(app) {
+ *         app.logger.info('started');
+ *     },
+ * });
+ * ```
+ */
+export async function runApplication<TAppConfig = unknown, TEvents extends EventMap = InfraEvents>(
+    options: ApplicationBootstrapOptions<TAppConfig, TEvents>,
+): Promise<ApplicationRuntime<TAppConfig, TEvents>> {
+    // ── Resolve config ─────────────────────────────────────────────────
+
+    const logOpts = options.config?.logging;
+    const loggingConfig: ApplicationBootstrapConfig['logging'] = {
+        enabled: logOpts?.enabled ?? true,
+        level: logOpts?.level ?? 'info',
+        console: logOpts?.console ?? true,
+        json: logOpts?.json ?? true,
+        ...(logOpts?.fileSink ? { fileSink: logOpts.fileSink } : {}),
+    };
+
+    const telOpts = options.config?.telemetry;
+    const telemetryConfig: ApplicationBootstrapConfig['telemetry'] = {
+        enabled: telOpts?.enabled ?? true,
+        serviceName: telOpts?.serviceName ?? 'ts-libs',
+        environment: telOpts?.environment ?? 'development',
+        dbStatementDebug: telOpts?.dbStatementDebug ?? false,
+    };
+
+    const schedOpts = options.config?.scheduler;
+    const schedulerConfig: ApplicationBootstrapConfig['scheduler'] = {
+        enabled: schedOpts?.enabled ?? false,
+        autoStart: schedOpts?.autoStart ?? true,
+    };
+
+    const eventsEnabled = options.config?.events?.enabled ?? true;
+    const eventsLifecycle = options.config?.events?.lifecycle ?? true;
+    const eventsDefaultObservers = options.config?.events?.defaultObservers ?? true;
+
+    const state: RuntimeState<TAppConfig, TEvents> = {
+        app: undefined,
+        userStop: options.stop,
+        schedulerAdapter: undefined,
+        schedulerStarted: false,
+        loggerInitialized: false,
+        telemetryInitialized: false,
+        stopped: false,
+    };
+
+    try {
+        // ── 1. Initialize logger ────────────────────────────────────────
+        let logger: Logger;
+        if (options.services?.logger) {
+            logger = options.services.logger;
+        } else if (loggingConfig.enabled) {
+            await initializeLogger({
+                level: loggingConfig.level,
+                console: loggingConfig.console,
+                fileSink: loggingConfig.fileSink,
+                json: loggingConfig.json,
+            });
+            logger = getLogger('bootstrap');
+        } else {
+            logger = getLogger('bootstrap');
+        }
+
+        // ── 2. Initialize telemetry ────────────────────────────────────
+        if (telemetryConfig.enabled) {
+            initTelemetry({
+                enabled: telemetryConfig.enabled,
+                serviceName: telemetryConfig.serviceName,
+                environment: telemetryConfig.environment,
+                dbStatementDebug: telemetryConfig.dbStatementDebug,
+            });
+            state.telemetryInitialized = true;
+        }
+
+        // ── 3. Create lifecycle bus + EventBus ─────────────────────────
+        const lifecycleBus =
+            eventsEnabled && eventsLifecycle ? (options.services?.lifecycleBus ?? createLifecycleBus()) : undefined;
+
+        if (lifecycleBus && eventsDefaultObservers) {
+            attachDefaultObservers(lifecycleBus);
+        }
+
+        const events = options.services?.events
+            ? options.services.events
+            : new EventBus<TEvents>({ lifecycleBus: lifecycleBus as EventBus<BusLifecycleEvents> | undefined });
+
+        // ── 4. Database (injected only) ────────────────────────────────
+        const db: DbAdapterLike | undefined = options.services?.db;
+
+        // ── 5. Scheduler ───────────────────────────────────────────────
+        let scheduler: SchedulerAdapter | undefined;
+        if (schedulerConfig.enabled) {
+            const adapter = options.services?.scheduler ?? schedOpts?.adapter;
+            if (adapter) {
+                setSchedulerAdapter(adapter);
+            }
+            scheduler = initScheduler(schedOpts?.entries);
+            state.schedulerAdapter = scheduler;
+        }
+
+        // ── Build resolved config ──────────────────────────────────────
+        const resolvedConfig: ApplicationBootstrapConfig = {
+            logging: loggingConfig,
+            events: { enabled: eventsEnabled, lifecycle: eventsLifecycle, defaultObservers: eventsDefaultObservers },
+            telemetry: telemetryConfig,
+            scheduler: schedulerConfig,
+        };
+
+        // ── Build runtime handle ───────────────────────────────────────
+        const app: ApplicationRuntime<TAppConfig, TEvents> = {
+            config: resolvedConfig,
+            appConfig: options.appConfig as TAppConfig,
+            logger,
+            events,
+            lifecycleBus,
+            db,
+            scheduler,
+            stop: (reason?: ApplicationStopReason) => performShutdown(state, reason ?? 'manual'),
+        };
+        state.app = app;
+
+        // ── 6. User start callback ─────────────────────────────────────
+        await options.start(app);
+
+        // ── 7. Start scheduler ─────────────────────────────────────────
+        if (schedulerConfig.enabled && schedulerConfig.autoStart && scheduler) {
+            await scheduler.start();
+            state.schedulerStarted = true;
+        }
+
+        return app;
+    } catch (error) {
+        // Reverse-order cleanup of services this bootstrap owns.
+        // Scheduler: start() is the last async op before return; if it throws,
+        // schedulerStarted is still false, so there is nothing started to stop.
+        // DB: injected by the caller (portable bootstrap never creates one), so
+        // its lifecycle is caller-owned and not closed here.
+        // Telemetry: owned by the bootstrap — shut it down if it was initialized.
+        if (state.telemetryInitialized) {
+            await shutdownTelemetry();
+        }
+        throw error;
+    }
+}
+
+export type { BusLifecycleEvents, EventMap } from '../event-bus/types';
+export type { InfraEvents } from '../events';
+// Re-export types
+export type {
+    ApplicationBootstrapConfig,
+    ApplicationBootstrapOptions,
+    ApplicationConfigLoader,
+    ApplicationConfigValidator,
+    ApplicationRuntime,
+    ApplicationServices,
+    ApplicationStopReason,
+    ConfigValidationResult,
+    DbAdapterLike,
+    EventsOptions,
+    LoggingOptions,
+    SchedulerOptions,
+    TelemetryOptions,
+} from './types';