@justscale/core 0.1.0

package/dist/core/logger.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Observability System
+ *
+ * Provides logging, context propagation, and extensibility hooks for
+ * OpenTelemetry, Datadog, or other observability platforms.
+ *
+ * Features:
+ * - Async context propagation via AsyncLocalStorage
+ * - Instrumentation hooks for traces, metrics, custom integrations
+ * - Structured logging with attributes
+ * - Automatic request context (requestId, route, etc.)
+ */
+/**
+ * Context data that propagates through the async tree.
+ * Used by loggers, traces, and metrics.
+ *
+ * Standard fields (set automatically by the framework):
+ * - requestId: Unique ID for the current request
+ * - route: Route name being handled
+ * - method: HTTP method
+ * - path: Request path
+ *
+ * Observability vendors (OpenTelemetry, Datadog, etc.) typically add their
+ * own fields like traceId, spanId via the string or symbol index signatures.
+ *
+ * You can add custom fields via runWithContext or logger.withContext.
+ */
+export interface ObservabilityContext {
+    /** Unique request identifier */
+    requestId?: string;
+    /** Custom string-keyed data */
+    [key: string]: unknown;
+    /** Private data (symbol keys avoid naming conflicts between vendors) */
+    [key: symbol]: unknown;
+}
+/**
+ * Get the current observability context.
+ * Returns an empty object if no context is set.
+ */
+export declare function getContext(): ObservabilityContext;
+/**
+ * Capture the current context for later use in span linking.
+ * Use this when you need to link a new async tree back to the current one.
+ *
+ * @example Event publishing with trace linking
+ * ```typescript
+ * // In HTTP handler - capture context before publishing event
+ * const sourceContext = captureContext("caused_by");
+ *
+ * // Publish event with the captured context
+ * await eventBus.publish("order.created", {
+ *   orderId: "123",
+ *   _traceContext: sourceContext, // Pass along for linking
+ * });
+ *
+ * // In event handler - use captured context to link spans
+ * await runInScopeAsync(
+ *   {
+ *     type: "handler",
+ *     name: "order.created",
+ *     links: [event._traceContext], // Links back to HTTP request span
+ *   },
+ *   {},
+ *   async () => { ... }
+ * );
+ * ```
+ */
+export declare function captureContext(relationship?: LinkedContext['relationship']): LinkedContext;
+/**
+ * Run a function with additional context.
+ * The context is merged with any existing context and propagates
+ * through the entire async tree.
+ *
+ * @example
+ * ```typescript
+ * // Add user context after authentication
+ * runWithContext({ userId: user.id, tenantId: user.tenantId }, async () => {
+ *   // All logs, traces, metrics in this tree include userId + tenantId
+ *   await processRequest();
+ * });
+ * ```
+ */
+export declare function runWithContext<T>(context: ObservabilityContext, fn: () => T): T;
+/**
+ * Enter a context scope using the `using` keyword.
+ * The context is merged with existing context and automatically
+ * restored when the scope exits.
+ *
+ * @example
+ * ```typescript
+ * // Add user context after authentication
+ * using _ = withContext({ userId: user.id, tenantId: user.tenantId });
+ * // All logs, traces, metrics include userId + tenantId
+ * await processRequest();
+ * // Context automatically restored when scope exits
+ * ```
+ *
+ * @example Nested contexts
+ * ```typescript
+ * using _ = withContext({ requestId: "req-123" });
+ * logger.info("Starting"); // has requestId
+ *
+ * {
+ *   using _ = withContext({ userId: "user-456" });
+ *   logger.info("Processing"); // has requestId AND userId
+ * }
+ *
+ * logger.info("Done"); // only has requestId
+ * ```
+ */
+export declare function withContext(context: ObservabilityContext): Disposable;
+/** Log levels (trace is most verbose, error is least) */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/** Current minimum log level. Read cheap, no allocation. */
+export declare function getMinLogLevel(): LogLevel;
+/** Override the minimum log level at runtime. Takes effect on the next log call. */
+export declare function setMinLogLevel(level: LogLevel): void;
+/**
+ * A captured trace context that can be used to link spans across async boundaries.
+ * Used when a new scope is spawned from another (e.g., event handler triggered by HTTP request).
+ */
+export interface LinkedContext {
+    /** The observability context from the originating scope */
+    context: ObservabilityContext;
+    /** Relationship type for the link */
+    relationship?: 'caused_by' | 'follows_from' | 'related';
+}
+/**
+ * Information about the current scope (request, handler, etc.)
+ */
+export interface ScopeInfo {
+    /** Type of scope */
+    type: 'request' | 'middleware' | 'guard' | 'handler' | 'custom';
+    /** Name of the scope (route name, middleware name, etc.) */
+    name: string;
+    /** Additional attributes */
+    attributes?: Record<string, unknown>;
+    /**
+     * Links to related contexts from other async trees.
+     * Used for distributed tracing when a scope is spawned from another
+     * (e.g., event handler triggered by an HTTP request).
+     */
+    links?: LinkedContext[];
+}
+/**
+ * Instrumentation interface for observability extensions.
+ *
+ * Implement this to integrate with any observability system:
+ * metrics, tracing (OpenTelemetry, Datadog), custom logging, etc.
+ *
+ * @example Simple metrics instrumentation
+ * ```typescript
+ * const metricsInstrumentation: Instrumentation = {
+ *   name: "metrics",
+ *
+ *   onScopeEnd(context, info, error) {
+ *     if (info.type === "request") {
+ *       metrics.increment("http.requests.total", {
+ *         route: info.name,
+ *         status: error ? "error" : "success",
+ *       });
+ *     }
+ *   },
+ * };
+ *
+ * registerInstrumentation(metricsInstrumentation);
+ * ```
+ *
+ * @example OpenTelemetry integration (see @justscale/feature-otel)
+ * ```typescript
+ * import { otelFeature } from "@justscale/feature-otel";
+ *
+ * // Add to your app features for automatic tracing
+ * const app = createStandaloneApp({
+ *   features: [otelFeature({ serviceName: "my-api" })],
+ * });
+ * ```
+ */
+export interface Instrumentation {
+    /** Unique name for this instrumentation */
+    name: string;
+    /**
+     * Called when a new scope starts (request, middleware, etc.)
+     * Can return modified context to add trace IDs, span references, etc.
+     */
+    onScopeStart?(context: ObservabilityContext, info: ScopeInfo): ObservabilityContext | void;
+    /**
+     * Called when a scope ends.
+     * Use this to end spans, record metrics, etc.
+     */
+    onScopeEnd?(context: ObservabilityContext, info: ScopeInfo, error?: Error): void;
+    /**
+     * Called on each log statement.
+     * Use this to forward logs to external systems or add to trace spans.
+     */
+    onLog?(level: LogLevel, message: string, attributes: Record<string, unknown>, context: ObservabilityContext): void;
+}
+/**
+ * Register an instrumentation for observability hooks.
+ *
+ * @example
+ * ```typescript
+ * registerInstrumentation({
+ *   name: "custom-metrics",
+ *   onScopeEnd(context, info) {
+ *     if (info.type === "request") {
+ *       metrics.recordRequestDuration(info.name, Date.now() - context.startTime);
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export declare function registerInstrumentation(instrumentation: Instrumentation): void;
+/**
+ * Remove a registered instrumentation by name.
+ */
+export declare function unregisterInstrumentation(name: string): boolean;
+/**
+ * Get all registered instrumentations (for testing).
+ */
+export declare function getInstrumentations(): readonly Instrumentation[];
+/**
+ * Run a function within a named scope.
+ * Notifies all instrumentations and handles errors properly.
+ *
+ * @internal Used by app.ts for request/middleware/handler scopes
+ */
+export declare function runInScope<T>(info: ScopeInfo, baseContext: ObservabilityContext, fn: () => T): T;
+/**
+ * Async version of runInScope.
+ * @internal
+ */
+export declare function runInScopeAsync<T>(info: ScopeInfo, baseContext: ObservabilityContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Log attributes for structured logging.
+ */
+export type LogAttributes = Record<string, unknown>;
+/**
+ * Abstract Logger - use as DI token. Built-in service automatically
+ * available to all services and handlers.
+ */
+export declare abstract class Logger {
+    abstract trace(message: string, attributes?: LogAttributes): void;
+    abstract debug(message: string, attributes?: LogAttributes): void;
+    abstract info(message: string, attributes?: LogAttributes): void;
+    abstract warn(message: string, attributes?: LogAttributes): void;
+    abstract error(message: string, attributes?: LogAttributes): void;
+    abstract child(name: string): Logger;
+    withContext<T>(context: ObservabilityContext, fn: () => T): T;
+}
+/**
+ * Factory for creating Logger instances with context.
+ * Implement this to use a custom logger (Pino, Winston, etc.)
+ */
+export interface LoggerFactory {
+    create(name: string): Logger;
+}
+export declare class ConsoleLogger extends Logger {
+    private readonly name;
+    constructor(name: string);
+    private log;
+    trace(message: string, attributes?: LogAttributes): void;
+    debug(message: string, attributes?: LogAttributes): void;
+    info(message: string, attributes?: LogAttributes): void;
+    warn(message: string, attributes?: LogAttributes): void;
+    error(message: string, attributes?: LogAttributes): void;
+    child(childName: string): Logger;
+}
+/**
+ * Default logger factory using ConsoleLogger.
+ */
+export declare class ConsoleLoggerFactory implements LoggerFactory {
+    create(name: string): Logger;
+}
+/**
+ * Symbol to identify Logger as a built-in service.
+ * Used by Container to detect and special-case Logger resolution.
+ */
+export declare const LOGGER_TOKEN: unique symbol;
+/** @internal */
+export declare function isLoggerToken(token: unknown): token is typeof Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}

package/dist/core/logger.js

@@ -0,0 +1,368 @@
+/**
+ * Observability System
+ *
+ * Provides logging, context propagation, and extensibility hooks for
+ * OpenTelemetry, Datadog, or other observability platforms.
+ *
+ * Features:
+ * - Async context propagation via AsyncLocalStorage
+ * - Instrumentation hooks for traces, metrics, custom integrations
+ * - Structured logging with attributes
+ * - Automatic request context (requestId, route, etc.)
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Global async local storage for observability context.
+ * All loggers, traces, and metrics read from this.
+ */
+const asyncContext = new AsyncLocalStorage();
+/**
+ * Get the current observability context.
+ * Returns an empty object if no context is set.
+ */
+export function getContext() {
+    return asyncContext.getStore() ?? {};
+}
+/**
+ * Capture the current context for later use in span linking.
+ * Use this when you need to link a new async tree back to the current one.
+ *
+ * @example Event publishing with trace linking
+ * ```typescript
+ * // In HTTP handler - capture context before publishing event
+ * const sourceContext = captureContext("caused_by");
+ *
+ * // Publish event with the captured context
+ * await eventBus.publish("order.created", {
+ *   orderId: "123",
+ *   _traceContext: sourceContext, // Pass along for linking
+ * });
+ *
+ * // In event handler - use captured context to link spans
+ * await runInScopeAsync(
+ *   {
+ *     type: "handler",
+ *     name: "order.created",
+ *     links: [event._traceContext], // Links back to HTTP request span
+ *   },
+ *   {},
+ *   async () => { ... }
+ * );
+ * ```
+ */
+export function captureContext(relationship = 'caused_by') {
+    return {
+        context: { ...getContext() }, // Clone to avoid mutations
+        relationship,
+    };
+}
+/**
+ * Run a function with additional context.
+ * The context is merged with any existing context and propagates
+ * through the entire async tree.
+ *
+ * @example
+ * ```typescript
+ * // Add user context after authentication
+ * runWithContext({ userId: user.id, tenantId: user.tenantId }, async () => {
+ *   // All logs, traces, metrics in this tree include userId + tenantId
+ *   await processRequest();
+ * });
+ * ```
+ */
+export function runWithContext(context, fn) {
+    const currentContext = getContext();
+    const mergedContext = { ...currentContext, ...context };
+    // Notify instrumentations of scope start
+    const scopeInfo = { type: 'custom', name: 'context' };
+    for (const inst of instrumentations) {
+        inst.onScopeStart?.(mergedContext, scopeInfo);
+    }
+    try {
+        return asyncContext.run(mergedContext, fn);
+    }
+    finally {
+        // Notify instrumentations of scope end
+        for (const inst of instrumentations) {
+            inst.onScopeEnd?.(mergedContext, scopeInfo);
+        }
+    }
+}
+/**
+ * Enter a context scope using the `using` keyword.
+ * The context is merged with existing context and automatically
+ * restored when the scope exits.
+ *
+ * @example
+ * ```typescript
+ * // Add user context after authentication
+ * using _ = withContext({ userId: user.id, tenantId: user.tenantId });
+ * // All logs, traces, metrics include userId + tenantId
+ * await processRequest();
+ * // Context automatically restored when scope exits
+ * ```
+ *
+ * @example Nested contexts
+ * ```typescript
+ * using _ = withContext({ requestId: "req-123" });
+ * logger.info("Starting"); // has requestId
+ *
+ * {
+ *   using _ = withContext({ userId: "user-456" });
+ *   logger.info("Processing"); // has requestId AND userId
+ * }
+ *
+ * logger.info("Done"); // only has requestId
+ * ```
+ */
+export function withContext(context) {
+    const previousContext = asyncContext.getStore() ?? {};
+    const mergedContext = { ...previousContext, ...context };
+    // Notify instrumentations of scope start
+    const scopeInfo = { type: 'custom', name: 'context' };
+    for (const inst of instrumentations) {
+        inst.onScopeStart?.(mergedContext, scopeInfo);
+    }
+    // Enter the new context
+    asyncContext.enterWith(mergedContext);
+    return {
+        [Symbol.dispose]() {
+            // Notify instrumentations of scope end
+            for (const inst of instrumentations) {
+                inst.onScopeEnd?.(mergedContext, scopeInfo);
+            }
+            // Restore previous context
+            asyncContext.enterWith(previousContext);
+        },
+    };
+}
+/**
+ * Numeric order used to compare levels. `trace` is lowest (most
+ * verbose) - a log at level X is emitted when `LEVEL_ORDER[X]` is
+ * `>= LEVEL_ORDER[minLevel]`.
+ */
+const LEVEL_ORDER = {
+    trace: 0, debug: 1, info: 2, warn: 3, error: 4,
+};
+/**
+ * Process-wide minimum log level. Seeded from `JUSTSCALE_LOG_LEVEL`
+ * (`trace|debug|info|warn|error`) or `JUSTSCALE_TRACE=1` for trace.
+ */
+let minLogLevel = resolveInitialLogLevel();
+function resolveInitialLogLevel() {
+    const explicit = (process.env.JUSTSCALE_LOG_LEVEL ?? '').toLowerCase();
+    if (explicit === 'trace' || explicit === 'debug' || explicit === 'info' || explicit === 'warn' || explicit === 'error') {
+        return explicit;
+    }
+    if (process.env.JUSTSCALE_TRACE === '1' || process.env.JUSTSCALE_TRACE === 'true') {
+        return 'trace';
+    }
+    return 'info';
+}
+/** Current minimum log level. Read cheap, no allocation. */
+export function getMinLogLevel() {
+    return minLogLevel;
+}
+/** Override the minimum log level at runtime. Takes effect on the next log call. */
+export function setMinLogLevel(level) {
+    minLogLevel = level;
+}
+/** Registered instrumentations */
+const instrumentations = [];
+/**
+ * Register an instrumentation for observability hooks.
+ *
+ * @example
+ * ```typescript
+ * registerInstrumentation({
+ *   name: "custom-metrics",
+ *   onScopeEnd(context, info) {
+ *     if (info.type === "request") {
+ *       metrics.recordRequestDuration(info.name, Date.now() - context.startTime);
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export function registerInstrumentation(instrumentation) {
+    // Prevent duplicates
+    const existing = instrumentations.findIndex((i) => i.name === instrumentation.name);
+    if (existing >= 0) {
+        instrumentations[existing] = instrumentation;
+    }
+    else {
+        instrumentations.push(instrumentation);
+    }
+}
+/**
+ * Remove a registered instrumentation by name.
+ */
+export function unregisterInstrumentation(name) {
+    const index = instrumentations.findIndex((i) => i.name === name);
+    if (index >= 0) {
+        instrumentations.splice(index, 1);
+        return true;
+    }
+    return false;
+}
+/**
+ * Get all registered instrumentations (for testing).
+ */
+export function getInstrumentations() {
+    return instrumentations;
+}
+// ============================================================================
+// Scope Management (used internally by app.ts)
+// ============================================================================
+/**
+ * Run a function within a named scope.
+ * Notifies all instrumentations and handles errors properly.
+ *
+ * @internal Used by app.ts for request/middleware/handler scopes
+ */
+export function runInScope(info, baseContext, fn) {
+    let context = { ...getContext(), ...baseContext };
+    // Let instrumentations modify context (e.g., add span IDs)
+    for (const inst of instrumentations) {
+        const modified = inst.onScopeStart?.(context, info);
+        if (modified)
+            context = modified;
+    }
+    let error;
+    try {
+        return asyncContext.run(context, fn);
+    }
+    catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+        throw e;
+    }
+    finally {
+        for (const inst of instrumentations) {
+            inst.onScopeEnd?.(context, info, error);
+        }
+    }
+}
+/**
+ * Async version of runInScope.
+ * @internal
+ */
+export async function runInScopeAsync(info, baseContext, fn) {
+    let context = { ...getContext(), ...baseContext };
+    // Let instrumentations modify context (e.g., add span IDs)
+    for (const inst of instrumentations) {
+        const modified = inst.onScopeStart?.(context, info);
+        if (modified)
+            context = modified;
+    }
+    let error;
+    try {
+        return await asyncContext.run(context, fn);
+    }
+    catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+        throw e;
+    }
+    finally {
+        for (const inst of instrumentations) {
+            inst.onScopeEnd?.(context, info, error);
+        }
+    }
+}
+/**
+ * Abstract Logger - use as DI token. Built-in service automatically
+ * available to all services and handlers.
+ */
+export class Logger {
+    withContext(context, fn) {
+        return runWithContext(context, fn);
+    }
+}
+// ============================================================================
+// Default Console Logger
+// ============================================================================
+export class ConsoleLogger extends Logger {
+    name;
+    constructor(name) {
+        super();
+        this.name = name;
+    }
+    log(level, message, attributes) {
+        if (LEVEL_ORDER[level] < LEVEL_ORDER[minLogLevel]) {
+            return;
+        }
+        const ctx = getContext();
+        const timestamp = new Date().toISOString();
+        // Build context string from observability context
+        const ctxEntries = Object.entries(ctx)
+            .filter(([k]) => !k.startsWith('_')) // Skip internal fields
+            .map(([k, v]) => `${k}=${String(v)}`);
+        const ctxStr = ctxEntries.length > 0 ? ` [${ctxEntries.join(' ')}]` : '';
+        // Build attributes string
+        const attrStr = attributes
+            ? ' ' + JSON.stringify(attributes)
+            : '';
+        const formatted = `[${timestamp}] [${level.toUpperCase()}] [${this.name}]${ctxStr} ${message}${attrStr}`;
+        // Output to console
+        switch (level) {
+            case 'trace':
+                console.debug(formatted); // trace goes to debug channel
+                break;
+            case 'debug':
+                console.debug(formatted);
+                break;
+            case 'info':
+                console.info(formatted);
+                break;
+            case 'warn':
+                console.warn(formatted);
+                break;
+            case 'error':
+                console.error(formatted);
+                break;
+        }
+        // Notify instrumentations
+        for (const inst of instrumentations) {
+            inst.onLog?.(level, message, attributes ?? {}, ctx);
+        }
+    }
+    trace(message, attributes) {
+        this.log('trace', message, attributes);
+    }
+    debug(message, attributes) {
+        this.log('debug', message, attributes);
+    }
+    info(message, attributes) {
+        this.log('info', message, attributes);
+    }
+    warn(message, attributes) {
+        this.log('warn', message, attributes);
+    }
+    error(message, attributes) {
+        this.log('error', message, attributes);
+    }
+    child(childName) {
+        return new ConsoleLogger(`${this.name}:${childName}`);
+    }
+}
+/**
+ * Default logger factory using ConsoleLogger.
+ */
+export class ConsoleLoggerFactory {
+    create(name) {
+        return new ConsoleLogger(name);
+    }
+}
+// ============================================================================
+// Built-in Token Marker
+// ============================================================================
+/**
+ * Symbol to identify Logger as a built-in service.
+ * Used by Container to detect and special-case Logger resolution.
+ */
+export const LOGGER_TOKEN = Symbol('justscale:Logger');
+Logger[LOGGER_TOKEN] = true;
+/** @internal */
+export function isLoggerToken(token) {
+    return token === Logger || token?.[LOGGER_TOKEN] === true;
+}
+//# sourceMappingURL=logger.js.map

package/dist/core/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"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"}