@ubercode/chronicler 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,427 @@
+/**
+ * Global constants used throughout Chronicler
+ */
+/**
+ * Log level priority mapping
+ * Lower numbers = higher priority/severity
+ */
+declare const LOG_LEVELS: {
+    readonly fatal: 0;
+    readonly critical: 1;
+    readonly alert: 2;
+    readonly error: 3;
+    readonly warn: 4;
+    readonly audit: 5;
+    readonly info: 6;
+    readonly debug: 7;
+    readonly trace: 8;
+};
+/**
+ * Union of all valid log level names, derived from {@link LOG_LEVELS}.
+ */
+type LogLevel = keyof typeof LOG_LEVELS;
+
+/**
+ * Field type definitions with compile-time type safety
+ */
+/**
+ * Field builder with compile-time type inference
+ */
+interface FieldBuilder<T extends string, R extends boolean> {
+    readonly _type: T;
+    readonly _required: R;
+    readonly _doc: string | undefined;
+}
+/**
+ * Field builder with optional marker
+ */
+interface OptionalFieldBuilder<T extends string> extends FieldBuilder<T, false> {
+    readonly doc: (description: string) => OptionalFieldBuilder<T>;
+}
+/**
+ * Field builder with required marker (default)
+ */
+interface RequiredFieldBuilder<T extends string> extends FieldBuilder<T, true> {
+    readonly optional: () => OptionalFieldBuilder<T>;
+    readonly doc: (description: string) => RequiredFieldBuilder<T>;
+}
+/**
+ * Field type builders — use these to define fields in events.
+ *
+ * @example
+ * ```typescript
+ * const event = defineEvent({
+ *   key: 'user.created',
+ *   level: 'info',
+ *   message: 'User created',
+ *   fields: {
+ *     userId: field.string().doc('User ID'),
+ *     age: field.number().optional().doc('User age'),
+ *     isActive: field.boolean(),
+ *     error: field.error().optional(),
+ *   },
+ * });
+ * ```
+ */
+declare const field: {
+    readonly string: () => RequiredFieldBuilder<"string">;
+    readonly number: () => RequiredFieldBuilder<"number">;
+    readonly boolean: () => RequiredFieldBuilder<"boolean">;
+    readonly error: () => RequiredFieldBuilder<"error">;
+};
+/**
+ * Utility type to simplify intersections
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Infer the TypeScript type from a field builder
+ */
+type InferFieldType<F> = F extends FieldBuilder<infer T, boolean> ? T extends 'string' ? string : T extends 'number' ? number : T extends 'boolean' ? boolean : T extends 'error' ? Error | string : never : never;
+/**
+ * Build required fields object
+ */
+type BuildRequired<F extends Record<string, FieldBuilder<string, boolean>>> = {
+    [K in keyof F as F[K]['_required'] extends true ? K : never]: InferFieldType<F[K]>;
+};
+/**
+ * Build optional fields object
+ */
+type BuildOptional<F extends Record<string, FieldBuilder<string, boolean>>> = {
+    [K in keyof F as F[K]['_required'] extends false ? K : never]?: InferFieldType<F[K]>;
+};
+/**
+ * Infer complete field types from field builders
+ * Required fields become required properties, optional fields become optional
+ */
+type InferFields<F extends Record<string, FieldBuilder<string, boolean>>> = Simplify<BuildRequired<F> & BuildOptional<F>>;
+
+/**
+ * Event definition with compile-time type safety
+ */
+interface EventDefinition<Key extends string = string, Fields extends Record<string, FieldBuilder<string, boolean>> = Record<string, FieldBuilder<string, boolean>>> {
+    readonly key: Key;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly doc?: string;
+    readonly fields?: Fields;
+}
+/**
+ * Helper to extract field types from an event definition
+ */
+type EventFields<E> = E extends EventDefinition<string, infer F> ? F extends Record<string, FieldBuilder<string, boolean>> ? InferFields<F> : Record<string, never> : never;
+type EventRecord = Record<string, EventDefinition<string, Record<string, FieldBuilder<string, boolean>>>>;
+interface SystemEventGroup {
+    readonly key: string;
+    readonly type: 'system';
+    readonly doc?: string;
+    readonly events?: EventRecord;
+    readonly groups?: Record<string, SystemEventGroup | CorrelationEventGroup>;
+}
+interface CorrelationEventGroup {
+    readonly key: string;
+    readonly type: 'correlation';
+    readonly doc?: string;
+    readonly timeout?: number;
+    readonly events?: EventRecord;
+    readonly groups?: Record<string, SystemEventGroup | CorrelationEventGroup>;
+}
+/** Field definitions for auto-generated correlation lifecycle events. */
+declare const correlationAutoFields: {
+    start: {};
+    complete: {
+        duration: OptionalFieldBuilder<"number">;
+    };
+    fail: {
+        duration: OptionalFieldBuilder<"number">;
+        error: OptionalFieldBuilder<"error">;
+    };
+    timeout: {};
+};
+type CorrelationAutoEvents = {
+    [Key in keyof typeof correlationAutoFields]: EventDefinition<string, (typeof correlationAutoFields)[Key]>;
+};
+type WithAutoEvents<Event extends EventRecord | undefined> = (Event extends EventRecord ? Event : Record<never, EventDefinition<string, Record<string, FieldBuilder<string, boolean>>>>) & CorrelationAutoEvents;
+/**
+ * Define an event with compile-time type safety.
+ *
+ * `as const` is **not required** — `defineEvent` uses TypeScript `const` generic
+ * parameters (TS 5.0+), so literal types and field builders are narrowed automatically.
+ * You may still add `as const` if you prefer, but it has no effect.
+ *
+ * @example
+ * ```typescript
+ * const userCreated = defineEvent({
+ *   key: 'user.created',
+ *   level: 'info',
+ *   message: 'User created',
+ *   doc: 'Emitted when a new user is created',
+ *   fields: {
+ *     userId: field.string().doc('User ID'),
+ *     email: field.string(),
+ *     age: field.number().optional(),
+ *   },
+ * });
+ * ```
+ *
+ * @param event - Event definition with key, level, message, optional doc and fields
+ * @returns The same event definition, typed for compile-time inference
+ * @throws {Error} If the event key does not match the required dotted camelCase format
+ */
+declare const defineEvent: <const Key extends string, const Fields extends Record<string, FieldBuilder<string, boolean>>>(event: EventDefinition<Key, Fields>) => EventDefinition<Key, Fields>;
+/**
+ * Define a system or correlation event group for organizational purposes.
+ *
+ * Groups provide a namespace hierarchy for events. For correlation groups,
+ * prefer {@link defineCorrelationGroup} which adds automatic lifecycle events.
+ *
+ * @param group - Event group definition (system or correlation)
+ * @returns The same group definition, typed for compile-time inference
+ */
+declare const defineEventGroup: <Group extends SystemEventGroup | CorrelationEventGroup>(group: Group) => Group;
+/**
+ * Define a correlation event group with automatic lifecycle events
+ *
+ * **What is a correlation group?**
+ * A correlation represents a logical unit of work with a defined lifecycle
+ * (start, complete, timeout). Common examples: HTTP requests, batch jobs, workflows.
+ *
+ * **Automatic events added:**
+ * - `{key}.start` - Emitted when startCorrelation() is called
+ * - `{key}.complete` - Emitted when complete() is called (includes duration)
+ * - `{key}.fail` - Emitted when fail() is called (includes duration and error)
+ * - `{key}.timeout` - Emitted if no activity within timeout period
+ *
+ * **Timeout behavior:**
+ * - Defaults to 5 minutes (300,000ms) if not specified
+ * - Timer resets on ANY activity (log events, fork creation)
+ * - Set to 0 to disable timeout
+ *
+ * **Type safety:**
+ * TypeScript will infer all event keys and field types. The return type
+ * includes both your events and the auto-generated lifecycle events.
+ *
+ * @param group - Correlation group definition
+ * @returns Normalized group with auto-events and default timeout
+ *
+ * @example
+ * ```typescript
+ * const requestGroup = defineCorrelationGroup({
+ *   key: 'api.request',
+ *   doc: 'HTTP request lifecycle',
+ *   timeout: 30_000, // 30 seconds
+ *   events: {
+ *     validated: defineEvent({
+ *       key: 'api.request.validated',
+ *       level: 'debug',
+ *       message: 'Request validated',
+ *       doc: 'Validation passed',
+ *     }),
+ *     processed: defineEvent({
+ *       key: 'api.request.processed',
+ *       level: 'info',
+ *       message: 'Request processed',
+ *       doc: 'Processing complete',
+ *       fields: { statusCode: { type: 'number', required: true } },
+ *     }),
+ *   },
+ * });
+ *
+ * // Auto-events available:
+ * // - requestGroup.events.start
+ * // - requestGroup.events.complete
+ * // - requestGroup.events.timeout
+ * // - requestGroup.events.validated (your event)
+ * // - requestGroup.events.processed (your event)
+ * ```
+ */
+declare const defineCorrelationGroup: <Group extends CorrelationEventGroup>(group: Group) => Omit<Group, "events" | "timeout"> & {
+    events: WithAutoEvents<Group["events"]>;
+    timeout: number;
+};
+
+interface ValidationMetadata {
+    readonly missingFields?: string[];
+    readonly typeErrors?: string[];
+    readonly invalidValues?: string[];
+    readonly unknownFields?: string[];
+}
+
+interface LogPayload {
+    readonly eventKey: string;
+    readonly fields: Record<string, unknown>;
+    readonly correlationId: string;
+    readonly forkId: string;
+    readonly metadata: Record<string, unknown>;
+    readonly timestamp: string;
+    readonly _validation?: ValidationMetadata;
+}
+type LogBackend = Record<LogLevel, (message: string, payload: LogPayload) => void>;
+/**
+ * Create a zero-config backend that logs to the console.
+ *
+ * Maps each of the 9 Chronicler levels to the appropriate `console` method:
+ * fatal/critical/alert/error → `console.error`, warn → `console.warn`,
+ * audit/info → `console.info`, debug/trace → `console.debug`.
+ *
+ * @returns A fully populated LogBackend using console methods for all levels
+ */
+declare const createConsoleBackend: () => LogBackend;
+/**
+ * Create a backend from a partial set of handlers.
+ *
+ * For each missing level, the fallback chain is tried in order (e.g. `fatal` →
+ * `critical` → `error` → `warn` → `info`). If no fallback is provided either,
+ * the corresponding `console` method is used.
+ *
+ * @param partial - Partial backend with handlers for a subset of log levels
+ * @returns A fully populated LogBackend with fallbacks applied for missing levels
+ */
+declare const createBackend: (partial: Partial<LogBackend>) => LogBackend;
+/**
+ * A routing rule that pairs a backend with an optional filter.
+ *
+ * When `filter` is omitted the backend receives all events.
+ * When provided, the backend only receives events for which `filter` returns `true`.
+ */
+interface BackendRoute {
+    readonly backend: LogBackend;
+    readonly filter?: (level: LogLevel, payload: LogPayload) => boolean;
+}
+/**
+ * Create a backend that routes events to multiple backends based on filter rules.
+ *
+ * Each route pairs a backend with an optional filter function. Events are
+ * dispatched to every route whose filter matches (or to all routes without a
+ * filter). This enables splitting logs into separate streams — for example,
+ * maintenance/debug logs to stdout and audit events to a dedicated store.
+ *
+ * @param routes - One or more backend routes with optional filters
+ * @returns A single LogBackend that fans out to the matching routes
+ * @throws {Error} If no routes are provided
+ *
+ * @example
+ * ```typescript
+ * const router = createRouterBackend([
+ *   { backend: consoleBackend, filter: (level, payload) => !payload.eventKey.startsWith('audit.') },
+ *   { backend: auditBackend,   filter: (level, payload) => payload.eventKey.startsWith('audit.') },
+ * ]);
+ *
+ * const chronicle = createChronicle({ backend: router, metadata: { appName: 'my-app' } });
+ * ```
+ */
+declare const createRouterBackend: (routes: BackendRoute[]) => LogBackend;
+
+type ContextValue = string | number | boolean | null;
+type ContextRecord = Record<string, ContextValue>;
+interface ContextCollisionDetail {
+    readonly key: string;
+    readonly existingValue: ContextValue;
+    readonly attemptedValue: ContextValue;
+}
+interface ContextValidationResult {
+    readonly reserved: string[];
+    readonly collisionDetails: ContextCollisionDetail[];
+    readonly dropped: string[];
+}
+
+interface ChroniclerLimits {
+    readonly maxContextKeys?: number;
+    /**
+     * Maximum fork nesting depth. A depth of N means N levels of nesting
+     * from root (e.g. depth 3 allows root → child → grandchild → great-grandchild).
+     * Defaults to {@link DEFAULT_MAX_FORK_DEPTH}.
+     */
+    readonly maxForkDepth?: number;
+    readonly maxActiveCorrelations?: number;
+}
+interface ChroniclerConfig {
+    readonly backend?: LogBackend;
+    readonly metadata: ContextRecord;
+    readonly correlationIdGenerator?: () => string;
+    readonly limits?: ChroniclerLimits;
+    /**
+     * When `true`, throws a `ChroniclerError` with code `FIELD_VALIDATION`
+     * for field validation errors (missing required fields, type mismatches).
+     * Useful for CI/CD enforcement. Defaults to `false`.
+     */
+    readonly strict?: boolean;
+    /**
+     * Minimum log level to emit. Events below this level are silently dropped.
+     * Uses priority ordering: fatal(0) > critical(1) > ... > trace(8).
+     * Defaults to `'trace'` (all events emitted).
+     */
+    readonly minLevel?: LogLevel;
+}
+interface Chronicler {
+    /** Emit a typed event. Fields are validated against the event definition. */
+    event<E extends EventDefinition>(event: E, fields: EventFields<E>): void;
+    /**
+     * Untyped escape hatch — log at any level without a pre-defined event.
+     * Useful for incremental adoption or ad-hoc debugging.
+     */
+    log(level: LogLevel, message: string, fields?: Record<string, unknown>): void;
+    /** Add key-value context that is attached to all subsequent events. */
+    addContext(context: ContextRecord): ContextValidationResult;
+    /** Start a correlation — a logical unit of work with lifecycle events. */
+    startCorrelation(group: CorrelationEventGroup, metadata?: ContextRecord): CorrelationChronicle;
+    /** Create an isolated child chronicle that inherits context. */
+    fork(context?: ContextRecord): Chronicler;
+}
+/**
+ * A correlation represents a logical unit of work with a defined lifecycle.
+ *
+ * Unlike a root Chronicler, a correlation:
+ * - Has a single shared correlation ID for all events
+ * - Has lifecycle events (start, complete, fail, timeout)
+ * - Can timeout if not completed within the configured duration
+ * - Cannot start nested correlations (use fork() for parallel work within a correlation)
+ */
+interface CorrelationChronicle {
+    /** Emit a typed event within this correlation. */
+    event<E extends EventDefinition>(event: E, fields: EventFields<E>): void;
+    /**
+     * Untyped escape hatch — log at any level without a pre-defined event.
+     * Useful for incremental adoption or ad-hoc debugging.
+     */
+    log(level: LogLevel, message: string, fields?: Record<string, unknown>): void;
+    /** Add key-value context that is attached to all subsequent events. */
+    addContext(context: ContextRecord): ContextValidationResult;
+    /** Create an isolated child chronicle that inherits context. */
+    fork(context?: ContextRecord): Chronicler;
+    /** Mark the correlation as successfully completed. Emits the `.complete` event. */
+    complete(fields?: Record<string, unknown>): void;
+    /** Mark the correlation as failed. Emits the `.fail` event at error level. */
+    fail(error?: unknown, fields?: Record<string, unknown>): void;
+    /** Mark the correlation as timed out. Called automatically by the timer. */
+    timeout(): void;
+}
+/**
+ * Create a root Chronicler instance.
+ *
+ * This is the main entry point for the library. The returned `Chronicler`
+ * can log events, add context, start correlations, and create forks.
+ *
+ * @param config - Chronicler configuration with optional backend, metadata, and optional correlation settings
+ * @returns A configured `Chronicler` instance
+ * @throws {ChroniclerError} `UNSUPPORTED_LOG_LEVEL` if the backend is missing required methods
+ * @throws {ChroniclerError} `RESERVED_FIELD` if `config.metadata` contains reserved field names
+ */
+declare const createChronicle: (config: ChroniclerConfig) => Chronicler;
+
+type ChroniclerErrorCode = 'UNSUPPORTED_LOG_LEVEL' | 'RESERVED_FIELD' | 'BACKEND_METHOD' | 'FORK_DEPTH_EXCEEDED' | 'CORRELATION_LIMIT_EXCEEDED' | 'FIELD_VALIDATION';
+/**
+ * Typed error class for Chronicler configuration and runtime failures.
+ * Uses a discriminator `code` to identify the specific error category.
+ */
+declare class ChroniclerError extends Error {
+    readonly code: ChroniclerErrorCode;
+    /**
+     * @param code - Machine-readable error category discriminator
+     * @param message - Human-readable description of the error
+     */
+    constructor(code: ChroniclerErrorCode, message: string);
+}
+
+export { type BackendRoute, type Chronicler, type ChroniclerConfig, ChroniclerError, type ChroniclerErrorCode, type ChroniclerLimits, type ContextCollisionDetail, type ContextRecord, type ContextValidationResult, type CorrelationChronicle, type CorrelationEventGroup, type EventDefinition, type EventFields, type FieldBuilder, type InferFieldType, type InferFields, type LogBackend, type LogLevel, type LogPayload, type SystemEventGroup, createBackend, createChronicle, createConsoleBackend, createRouterBackend, defineCorrelationGroup, defineEvent, defineEventGroup, field };