@gobing-ai/ts-infra 0.1.0

package/dist/scheduler/factory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Scheduler factory — selects adapter based on runtime.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+export declare function setSchedulerAdapter(adapter: SchedulerAdapter): void;
+/** Reset the scheduler adapter singleton. For testing. */
+export declare function resetSchedulerAdapter(): void;
+export declare function getSchedulerAdapter(): SchedulerAdapter | undefined;
+/**
+ * Initialize the scheduler adapter and register cron entries.
+ *
+ * MUST be called before `adapter.start()`. If the adapter is already
+ * running, newly registered entries will NOT be started until the next
+ * `start()` call.
+ *
+ * Returns the configured adapter (defaults to noop if none set).
+ */
+export declare function initScheduler(cronEntries?: Array<[string, ScheduledAction]>): SchedulerAdapter;
+//# sourceMappingURL=factory.d.ts.map

package/dist/scheduler/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/scheduler/factory.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIjE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAEnE;AAED,0DAA0D;AAC1D,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,GAAG,gBAAgB,CAa9F"}

package/dist/scheduler/factory.js

@@ -0,0 +1,45 @@
+let runtimeAdapter;
+export function setSchedulerAdapter(adapter) {
+    runtimeAdapter = adapter;
+}
+/** Reset the scheduler adapter singleton. For testing. */
+export function resetSchedulerAdapter() {
+    runtimeAdapter = undefined;
+}
+export function getSchedulerAdapter() {
+    return runtimeAdapter;
+}
+/**
+ * Initialize the scheduler adapter and register cron entries.
+ *
+ * MUST be called before `adapter.start()`. If the adapter is already
+ * running, newly registered entries will NOT be started until the next
+ * `start()` call.
+ *
+ * Returns the configured adapter (defaults to noop if none set).
+ */
+export function initScheduler(cronEntries) {
+    // Default: create a noop adapter. Apps inject their own via setSchedulerAdapter.
+    if (!runtimeAdapter) {
+        runtimeAdapter = createNoopScheduler();
+    }
+    if (cronEntries) {
+        for (const [cron, action] of cronEntries) {
+            runtimeAdapter.register(cron, action);
+        }
+    }
+    return runtimeAdapter;
+}
+function createNoopScheduler() {
+    return {
+        register() {
+            /* noop */
+        },
+        start() {
+            return Promise.resolve();
+        },
+        stop() {
+            return Promise.resolve();
+        },
+    };
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,6 @@
+export { CloudflareSchedulerAdapter } from './cloudflare';
+export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory';
+export { NodeSchedulerAdapter } from './node';
+export { NoopSchedulerAdapter } from './noop';
+export type { ScheduledAction, SchedulerAdapter } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scheduler/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/scheduler/index.js

@@ -0,0 +1,4 @@
+export { CloudflareSchedulerAdapter } from './cloudflare.js';
+export { getSchedulerAdapter, initScheduler, resetSchedulerAdapter, setSchedulerAdapter } from './factory.js';
+export { NodeSchedulerAdapter } from './node.js';
+export { NoopSchedulerAdapter } from './noop.js';

package/dist/scheduler/node.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Node.js scheduler adapter using a simple setInterval-based approach.
+ * No external cron library dependency — cron expressions are parsed minimally.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+export declare class NodeSchedulerAdapter implements SchedulerAdapter {
+    private readonly entries;
+    private running;
+    constructor();
+    register(cron: string, action: ScheduledAction): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private startEntry;
+    private _onScheduledTick;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/scheduler/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/scheduler/node.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA6BjE,qBAAa,oBAAqB,YAAW,gBAAgB;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,OAAO,CAAS;;IAIxB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAU/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,OAAO,CAAC,UAAU;YAOJ,gBAAgB;CAOjC"}

package/dist/scheduler/node.js

@@ -0,0 +1,63 @@
+/** Simple helper to parse cron-like interval strings into milliseconds. */
+function parseInterval(cron) {
+    // Support simple patterns: "* * * * *" (every minute), "*/5 * * * *" (every 5 min)
+    // Also support direct ms strings like "60000"
+    const num = Number(cron);
+    if (!Number.isNaN(num))
+        return num;
+    const parts = cron.trim().split(/\s+/);
+    if (parts.length === 5 && parts[0] === '*') {
+        return 60_000; // every minute default
+    }
+    // */N pattern
+    const match = parts[0]?.match(/^\*\/(\d+)$/);
+    if (match) {
+        return Number(match[1]) * 60_000;
+    }
+    return 60_000; // fallback: every minute
+}
+export class NodeSchedulerAdapter {
+    entries = [];
+    running = false;
+    constructor() { }
+    register(cron, action) {
+        this.entries.push({ cron, action });
+        if (this.running) {
+            const last = this.entries[this.entries.length - 1];
+            if (last) {
+                this.startEntry(last);
+            }
+        }
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        for (const entry of this.entries) {
+            this.startEntry(entry);
+        }
+    }
+    async stop() {
+        this.running = false;
+        for (const entry of this.entries) {
+            if (entry.timer) {
+                clearInterval(entry.timer);
+                entry.timer = undefined;
+            }
+        }
+    }
+    startEntry(entry) {
+        if (entry.timer)
+            return;
+        const interval = parseInterval(entry.cron);
+        entry.timer = setInterval(this._onScheduledTick.bind(this, entry), interval);
+    }
+    async _onScheduledTick(entry) {
+        try {
+            await entry.action();
+        }
+        catch {
+            // Swallow — scheduler errors should not crash the process
+        }
+    }
+}

package/dist/scheduler/noop.d.ts

@@ -0,0 +1,11 @@
+/**
+ * No-op scheduler adapter for testing and environments without scheduling.
+ */
+import type { ScheduledAction, SchedulerAdapter } from './types';
+export declare class NoopSchedulerAdapter implements SchedulerAdapter {
+    constructor();
+    register(_cron: string, _action: ScheduledAction): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=noop.d.ts.map

package/dist/scheduler/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../src/scheduler/noop.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEjE,qBAAa,oBAAqB,YAAW,gBAAgB;;IAGzD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAIjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG9B"}

package/dist/scheduler/noop.js

@@ -0,0 +1,12 @@
+export class NoopSchedulerAdapter {
+    constructor() { }
+    register(_cron, _action) {
+        // noop
+    }
+    async start() {
+        // noop
+    }
+    async stop() {
+        // noop
+    }
+}

package/dist/scheduler/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Scheduler types and interface.
+ */
+/** Signature for scheduled action handlers. */
+export type ScheduledAction = () => Promise<void>;
+/** Abstract scheduler interface — implementations for Node (node-cron) and Cloudflare. */
+export interface SchedulerAdapter {
+    register(cron: string, action: ScheduledAction): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/scheduler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB"}

package/dist/scheduler/types.js

@@ -0,0 +1,3 @@
+/**
+ * Scheduler types and interface.
+ */

package/dist/telemetry/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Telemetry configuration interface.
+ */
+export interface TelemetryConfig {
+    /** Master switch — when false, all tracing degrades to no-ops. */
+    enabled: boolean;
+    /** Logical service name emitted on every span. */
+    serviceName: string;
+    /** Deployment environment (development, staging, production). */
+    environment: string;
+    /** OTLP exporter endpoint (e.g. `http://localhost:4318/v1/traces`). */
+    exporterEndpoint?: string | undefined;
+    /** Export protocol — only `http` is supported in v1. */
+    exporterProtocol: 'http';
+    /**
+     * Debug-only DB statement capture.
+     *
+     * When true, DB spans may include sanitized SQL text in a `db.statement`
+     * attribute. SQL text is redacted — parameter values, literals, and
+     * identifiers are stripped before capture.
+     *
+     * Default: `false`. Controlled by `OTEL_DB_STATEMENT_DEBUG` env var.
+     */
+    dbStatementDebug: boolean;
+}
+/**
+ * Partial telemetry config from the centralized config system.
+ */
+export interface TelemetryConfigPartial {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    environment?: string | undefined;
+    exporterEndpoint?: string | undefined;
+    dbStatementDebug?: boolean | undefined;
+    /** Deployment environment fallback (from app.env). */
+    appEnv?: string | undefined;
+}
+/**
+ * Resolve the full telemetry config by merging a partial override with defaults.
+ */
+export declare function getTelemetryConfig(configPartial?: TelemetryConfigPartial): TelemetryConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/telemetry/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/telemetry/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AASD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,GAAE,sBAA2B,GAAG,eAAe,CAY9F"}

package/dist/telemetry/config.js

@@ -0,0 +1,24 @@
+/**
+ * Telemetry configuration interface.
+ */
+const DEFAULTS = {
+    enabled: true,
+    serviceName: 'ts-libs',
+    environment: 'development',
+    exporterProtocol: 'http',
+};
+/**
+ * Resolve the full telemetry config by merging a partial override with defaults.
+ */
+export function getTelemetryConfig(configPartial = {}) {
+    const enabled = configPartial.enabled ?? DEFAULTS.enabled;
+    const serviceName = configPartial.serviceName ?? DEFAULTS.serviceName;
+    return {
+        enabled,
+        serviceName,
+        environment: configPartial.environment ?? configPartial.appEnv ?? DEFAULTS.environment,
+        exporterEndpoint: configPartial.exporterEndpoint,
+        exporterProtocol: DEFAULTS.exporterProtocol,
+        dbStatementDebug: configPartial.dbStatementDebug ?? false,
+    };
+}

package/dist/telemetry/db-sanitize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SQL sanitization for debug-mode DB statement capture.
+ *
+ * Strips parameter values, string literals, numeric literals, and
+ * identifier-specific data from SQL text before it is attached to spans.
+ */
+/**
+ * Redact string literals and numeric literals from SQL text.
+ */
+export declare function sanitizeSql(sql: string): string;
+/**
+ * Extract the SQL operation keyword (SELECT, INSERT, UPDATE, DELETE, etc.)
+ */
+export declare function extractSqlOperation(sql: string): string | undefined;
+//# sourceMappingURL=db-sanitize.d.ts.map

package/dist/telemetry/db-sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-sanitize.d.ts","sourceRoot":"","sources":["../../src/telemetry/db-sanitize.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA4D/C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE"}

package/dist/telemetry/db-sanitize.js

@@ -0,0 +1,72 @@
+/**
+ * SQL sanitization for debug-mode DB statement capture.
+ *
+ * Strips parameter values, string literals, numeric literals, and
+ * identifier-specific data from SQL text before it is attached to spans.
+ */
+/**
+ * Redact string literals and numeric literals from SQL text.
+ */
+export function sanitizeSql(sql) {
+    let result = '';
+    let i = 0;
+    const len = sql.length;
+    while (i < len) {
+        const code = sql.charCodeAt(i);
+        // Quote characters: ' (39) or " (34)
+        if (code === 39 || code === 34) {
+            const quote = code;
+            i++;
+            while (i < len) {
+                if (sql.charCodeAt(i) === quote) {
+                    if (sql.charCodeAt(i + 1) === quote) {
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            result += '?';
+            continue;
+        }
+        // Numeric literal
+        if (code >= 48 && code <= 57) {
+            const prev = result.length > 0 ? result.charCodeAt(result.length - 1) : 0;
+            const isIdentifierContinuation = (prev >= 65 && prev <= 90) || (prev >= 97 && prev <= 122) || prev === 95 || (prev >= 48 && prev <= 57);
+            if (!isIdentifierContinuation) {
+                while (i < len) {
+                    const c = sql.charCodeAt(i);
+                    if (c < 48 || c > 57)
+                        break;
+                    i++;
+                }
+                if (i < len && sql.charCodeAt(i) === 46 && i + 1 < len) {
+                    const next = sql.charCodeAt(i + 1);
+                    if (next >= 48 && next <= 57) {
+                        i++;
+                        while (i < len) {
+                            const c = sql.charCodeAt(i);
+                            if (c < 48 || c > 57)
+                                break;
+                            i++;
+                        }
+                    }
+                }
+                result += '?';
+                continue;
+            }
+        }
+        result += sql[i] ?? '';
+        i++;
+    }
+    return result;
+}
+/**
+ * Extract the SQL operation keyword (SELECT, INSERT, UPDATE, DELETE, etc.)
+ */
+export function extractSqlOperation(sql) {
+    const match = sql.trim().match(/^\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|PRAGMA)\b/i);
+    return match?.[1]?.toUpperCase();
+}

package/dist/telemetry/index.d.ts

@@ -0,0 +1,7 @@
+export { getTelemetryConfig, type TelemetryConfig, type TelemetryConfigPartial } from './config';
+export { extractSqlOperation, sanitizeSql } from './db-sanitize';
+export { type Counter, getDbOperationDuration, getDbOperationErrors, getDbOperationTotal, getEventbusEmitsTotal, getEventbusErrorsTotal, getHttpClientRequestDuration, getHttpClientRequestErrors, getHttpClientRequestTotal, getHttpServerRequestDuration, getHttpServerRequestErrors, getHttpServerRequestTotal, getQueueJobCompletedTotal, getQueueJobEnqueuedTotal, getQueueJobFailedTotal, getQueueJobProcessingDuration, getSchedulerJobDuration, getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal, type Histogram, initMetrics, shutdownMetrics, } from './metrics';
+export { getTracer, initTelemetry, isTelemetryEnabled, shutdownTelemetry } from './sdk';
+export type { Span, SpanOptions, Tracer } from './tracing';
+export { addSpanAttributes, addSpanEvent, getActiveSpan, traceAsync, traceSync, withSpan } from './tracing';
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACjG,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EACH,KAAK,OAAO,EACZ,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,KAAK,SAAS,EACd,WAAW,EACX,eAAe,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AACxF,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,5 @@
+export { getTelemetryConfig } from './config.js';
+export { extractSqlOperation, sanitizeSql } from './db-sanitize.js';
+export { getDbOperationDuration, getDbOperationErrors, getDbOperationTotal, getEventbusEmitsTotal, getEventbusErrorsTotal, getHttpClientRequestDuration, getHttpClientRequestErrors, getHttpClientRequestTotal, getHttpServerRequestDuration, getHttpServerRequestErrors, getHttpServerRequestTotal, getQueueJobCompletedTotal, getQueueJobEnqueuedTotal, getQueueJobFailedTotal, getQueueJobProcessingDuration, getSchedulerJobDuration, getSchedulerJobExecutedTotal, getSchedulerJobFailedTotal, initMetrics, shutdownMetrics, } from './metrics.js';
+export { getTracer, initTelemetry, isTelemetryEnabled, shutdownTelemetry } from './sdk.js';
+export { addSpanAttributes, addSpanEvent, getActiveSpan, traceAsync, traceSync, withSpan } from './tracing.js';

package/dist/telemetry/metrics.d.ts

@@ -0,0 +1,32 @@
+/**
+ * OpenTelemetry metrics — lazy-initialized instruments.
+ * All degrade to no-ops when telemetry is disabled.
+ */
+import { type Counter, type Histogram } from '@opentelemetry/api';
+import type { MeterProvider } from '@opentelemetry/sdk-metrics';
+export type { Counter, Histogram } from '@opentelemetry/api';
+import type { TelemetryConfig } from './config';
+export declare function isMetricsInitialized(): boolean;
+export declare function getMeterProvider(): MeterProvider;
+export declare function getHttpServerRequestTotal(): Counter;
+export declare function getHttpServerRequestDuration(): Histogram;
+export declare function getHttpServerRequestErrors(): Counter;
+export declare function getHttpClientRequestTotal(): Counter;
+export declare function getHttpClientRequestDuration(): Histogram;
+export declare function getHttpClientRequestErrors(): Counter;
+export declare function getDbOperationTotal(): Counter;
+export declare function getDbOperationDuration(): Histogram;
+export declare function getDbOperationErrors(): Counter;
+export declare function getEventbusEmitsTotal(): Counter;
+export declare function getEventbusErrorsTotal(): Counter;
+export declare function getQueueJobEnqueuedTotal(): Counter;
+export declare function getQueueJobCompletedTotal(): Counter;
+export declare function getQueueJobFailedTotal(): Counter;
+export declare function getQueueJobProcessingDuration(): Histogram;
+export declare function getSchedulerJobExecutedTotal(): Counter;
+export declare function getSchedulerJobDuration(): Histogram;
+export declare function getSchedulerJobFailedTotal(): Counter;
+export declare function initMetrics(_config?: Partial<TelemetryConfig>): void;
+export declare function shutdownMetrics(): Promise<void>;
+export declare function _resetMetrics(): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/telemetry/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/telemetry/metrics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,SAAS,EAAW,MAAM,oBAAoB,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAKhD,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AA6BD,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,4BAA4B,IAAI,SAAS,CAExD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,4BAA4B,IAAI,SAAS,CAExD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED,wBAAgB,sBAAsB,IAAI,SAAS,CAElD;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAID,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAID,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED,wBAAgB,yBAAyB,IAAI,OAAO,CAEnD;AAED,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,wBAAgB,6BAA6B,IAAI,SAAS,CAEzD;AAID,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED,wBAAgB,uBAAuB,IAAI,SAAS,CAEnD;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAID,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAGpE;AAED,wBAAgB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAG/C;AAED,wBAAgB,aAAa,IAAI,IAAI,CAMpC"}

package/dist/telemetry/metrics.js

@@ -0,0 +1,109 @@
+/**
+ * OpenTelemetry metrics — lazy-initialized instruments.
+ * All degrade to no-ops when telemetry is disabled.
+ */
+import { metrics } from '@opentelemetry/api';
+let meterProvider;
+let metricsInitialized = false;
+export function isMetricsInitialized() {
+    return metricsInitialized;
+}
+export function getMeterProvider() {
+    return meterProvider ?? metrics.getMeterProvider();
+}
+const METER_NAME = '@gobing-ai/ts-infra';
+const METER_VERSION = '0.1.0';
+function getMeter() {
+    return getMeterProvider().getMeter(METER_NAME, METER_VERSION);
+}
+// ── Instrument cache ────────────────────────────────────────────────
+const instruments = {};
+function getOrCreateCounter(key, name, description, unit = '{operation}') {
+    if (!instruments[key]) {
+        instruments[key] = getMeter().createCounter(name, { description, unit });
+    }
+    return instruments[key];
+}
+function getOrCreateHistogram(key, name, description, unit = 'ms') {
+    if (!instruments[key]) {
+        instruments[key] = getMeter().createHistogram(name, { description, unit });
+    }
+    return instruments[key];
+}
+// ── HTTP server ─────────────────────────────────────────────────────
+export function getHttpServerRequestTotal() {
+    return getOrCreateCounter('httpSrvReq', 'http.server.request.total', 'Total inbound HTTP requests', '{request}');
+}
+export function getHttpServerRequestDuration() {
+    return getOrCreateHistogram('httpSrvDur', 'http.server.request.duration', 'Inbound HTTP request duration');
+}
+export function getHttpServerRequestErrors() {
+    return getOrCreateCounter('httpSrvErr', 'http.server.request.errors', 'Inbound HTTP 5xx errors', '{error}');
+}
+// ── HTTP client ─────────────────────────────────────────────────────
+export function getHttpClientRequestTotal() {
+    return getOrCreateCounter('httpCliReq', 'http.client.request.total', 'Total outbound HTTP requests', '{request}');
+}
+export function getHttpClientRequestDuration() {
+    return getOrCreateHistogram('httpCliDur', 'http.client.request.duration', 'Outbound HTTP request duration');
+}
+export function getHttpClientRequestErrors() {
+    return getOrCreateCounter('httpCliErr', 'http.client.request.errors', 'Outbound HTTP errors', '{error}');
+}
+// ── DB ──────────────────────────────────────────────────────────────
+export function getDbOperationTotal() {
+    return getOrCreateCounter('dbOpTotal', 'db.client.operation.total', 'Total DB operations', '{operation}');
+}
+export function getDbOperationDuration() {
+    return getOrCreateHistogram('dbOpDur', 'db.client.operation.duration', 'DB operation duration');
+}
+export function getDbOperationErrors() {
+    return getOrCreateCounter('dbOpErr', 'db.client.operation.errors', 'DB operation errors', '{error}');
+}
+// ── Event bus ───────────────────────────────────────────────────────
+export function getEventbusEmitsTotal() {
+    return getOrCreateCounter('ebEmit', 'eventbus.emits.total', 'Total event bus emits', '{emit}');
+}
+export function getEventbusErrorsTotal() {
+    return getOrCreateCounter('ebErr', 'eventbus.errors.total', 'Event bus errors', '{error}');
+}
+// ── Queue ───────────────────────────────────────────────────────────
+export function getQueueJobEnqueuedTotal() {
+    return getOrCreateCounter('qEnq', 'queue.jobs.enqueued', 'Total jobs enqueued', '{job}');
+}
+export function getQueueJobCompletedTotal() {
+    return getOrCreateCounter('qComp', 'queue.jobs.completed', 'Total jobs completed', '{job}');
+}
+export function getQueueJobFailedTotal() {
+    return getOrCreateCounter('qFail', 'queue.jobs.failed', 'Total jobs failed', '{job}');
+}
+export function getQueueJobProcessingDuration() {
+    return getOrCreateHistogram('qProcDur', 'queue.jobs.processing_duration', 'Job processing duration');
+}
+// ── Scheduler ───────────────────────────────────────────────────────
+export function getSchedulerJobExecutedTotal() {
+    return getOrCreateCounter('schedExec', 'scheduler.jobs.executed', 'Total scheduled job executions', '{execution}');
+}
+export function getSchedulerJobDuration() {
+    return getOrCreateHistogram('schedDur', 'scheduler.jobs.duration', 'Scheduled job duration');
+}
+export function getSchedulerJobFailedTotal() {
+    return getOrCreateCounter('schedFail', 'scheduler.jobs.failed', 'Failed scheduled jobs', '{failure}');
+}
+// ── Lifecycle ───────────────────────────────────────────────────────
+export function initMetrics(_config) {
+    if (metricsInitialized)
+        return;
+    metricsInitialized = true;
+}
+export function shutdownMetrics() {
+    metricsInitialized = false;
+    return Promise.resolve();
+}
+export function _resetMetrics() {
+    for (const key of Object.keys(instruments)) {
+        instruments[key] = undefined;
+    }
+    metricsInitialized = false;
+    metrics.disable();
+}

package/dist/telemetry/sdk.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenTelemetry SDK initialisation and tracer provider management.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import type { TelemetryConfig } from './config';
+export declare function getResolvedConfig(): TelemetryConfig;
+export declare function initTelemetry(config?: Partial<TelemetryConfig>): void;
+export declare function shutdownTelemetry(): Promise<void>;
+export declare function getTracer(): Tracer;
+export declare function isTelemetryEnabled(): boolean;
+export declare function _resetTelemetry(): void;
+export { context, propagation, trace } from '@opentelemetry/api';
+//# sourceMappingURL=sdk.d.ts.map

package/dist/telemetry/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../src/telemetry/sdk.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,KAAK,MAAM,EAAS,MAAM,oBAAoB,CAAC;AAExD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAShD,wBAAgB,iBAAiB,IAAI,eAAe,CAEnD;AAED,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAarE;AAED,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAWtC;AAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/telemetry/sdk.js

@@ -0,0 +1,54 @@
+/**
+ * OpenTelemetry SDK initialisation and tracer provider management.
+ */
+import { trace } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { getTelemetryConfig } from './config.js';
+let tracerProvider;
+let telemetryInitialized = false;
+let resolvedConfig = getTelemetryConfig();
+const DEFAULT_TRACER = trace.getTracer('@gobing-ai/ts-infra', '0.1.0');
+export function getResolvedConfig() {
+    return resolvedConfig;
+}
+export function initTelemetry(config) {
+    if (telemetryInitialized)
+        return;
+    resolvedConfig = { ...getTelemetryConfig(), ...config };
+    if (!resolvedConfig.enabled) {
+        telemetryInitialized = true;
+        return;
+    }
+    tracerProvider = new NodeTracerProvider();
+    tracerProvider.register();
+    telemetryInitialized = true;
+}
+export async function shutdownTelemetry() {
+    if (!tracerProvider) {
+        telemetryInitialized = false;
+        return;
+    }
+    await tracerProvider.shutdown();
+    tracerProvider = undefined;
+    telemetryInitialized = false;
+}
+export function getTracer() {
+    return tracerProvider?.getTracer('@gobing-ai/ts-infra', '0.1.0') ?? DEFAULT_TRACER;
+}
+export function isTelemetryEnabled() {
+    return telemetryInitialized && resolvedConfig.enabled;
+}
+export function _resetTelemetry() {
+    if (tracerProvider) {
+        try {
+            tracerProvider.shutdown();
+        }
+        catch {
+            /* swallow */
+        }
+        tracerProvider = undefined;
+    }
+    telemetryInitialized = false;
+    resolvedConfig = getTelemetryConfig();
+}
+export { context, propagation, trace } from '@opentelemetry/api';

package/dist/telemetry/tracing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * High-level tracing helpers for application code.
+ */
+import { type Span, type SpanOptions, type Tracer } from '@opentelemetry/api';
+export declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, options?: SpanOptions, tracer?: Tracer): Promise<T>;
+export declare function traceSync<T>(name: string, fn: (span: Span) => T, options?: SpanOptions, tracer?: Tracer): T;
+export declare function addSpanAttributes(attributes: Record<string, string | number | boolean>): void;
+export declare function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+export declare function getActiveSpan(): Span | undefined;
+export declare function withSpan<T>(span: Span, fn: () => T): T;
+export type { Span, SpanOptions, Tracer } from '@opentelemetry/api';
+export { context, propagation, trace } from './sdk';
+//# sourceMappingURL=tracing.d.ts.map