sloplog 0.0.3

package/dist/collectors/index.d.ts

@@ -0,0 +1,102 @@
+import type { WideEventBase, EventPartial } from '../index.js';
+/**
+ * Options passed to collectors when flushing an event
+ */
+export interface FlushOptions {
+    /**
+     * If true, the event should always be sampled/collected regardless of sampling rules.
+     * This is set when any partial with alwaysSample=true is attached to the event.
+     */
+    alwaysSample: boolean;
+}
+/**
+ * Collectors
+ * Adapts the log to some format and flushes to an external service.
+ * Partials may be singular objects or arrays for repeatable partials.
+ */
+export interface LogCollectorClient {
+    flush(event: WideEventBase, partials: Map<string, EventPartial<string> | EventPartial<string>[]>, options: FlushOptions): Promise<void>;
+}
+/** Type alias for partial values (singular or array) */
+type PartialValue = EventPartial<string> | EventPartial<string>[];
+/**
+ * Simple collector to log the event to stdout/console
+ */
+export declare class StdioCollector implements LogCollectorClient {
+    flush(eventBase: WideEventBase, partials: Map<string, PartialValue>, _options: FlushOptions): Promise<void>;
+}
+/**
+ * Create a collector that logs events to stdout/console.
+ */
+export declare function stdioCollector(): StdioCollector;
+/**
+ * Composes multiple collectors together, flushing to all of them in parallel
+ */
+export declare class CompositeCollector implements LogCollectorClient {
+    private collectors;
+    constructor(collectors: LogCollectorClient[]);
+    flush(event: WideEventBase, partials: Map<string, PartialValue>, options: FlushOptions): Promise<void>;
+}
+/**
+ * Create a collector that flushes to multiple collectors in parallel.
+ */
+export declare function compositeCollector(collectors: LogCollectorClient[]): CompositeCollector;
+/**
+ * Filter function type for FilteredCollector
+ */
+export type EventFilter = (event: WideEventBase, partials: Map<string, PartialValue>, options: FlushOptions) => boolean;
+/**
+ * Wraps a collector and only flushes events that pass the filter function.
+ * Note: Events with alwaysSample=true bypass the filter by default.
+ */
+export declare class FilteredCollector implements LogCollectorClient {
+    private collector;
+    private filter;
+    constructor(collector: LogCollectorClient, filter: EventFilter);
+    flush(event: WideEventBase, partials: Map<string, PartialValue>, options: FlushOptions): Promise<void>;
+}
+/**
+ * Create a collector that filters events before flushing.
+ */
+export declare function filteredCollector(collector: LogCollectorClient, filter: EventFilter): FilteredCollector;
+/**
+ * Options for FileCollector
+ */
+export interface FileCollectorOptions {
+    /** Number of events to buffer before flushing to disk (default: 10) */
+    bufferSize?: number;
+    /** Maximum time in ms to wait before flushing buffer (default: 5000) */
+    flushIntervalMs?: number;
+}
+/**
+ * Filesystem interface for FileCollector (allows injection for testing)
+ */
+export interface FileSystem {
+    appendFile(path: string, data: string): Promise<void>;
+}
+/**
+ * Collector that writes events to a file with buffering
+ */
+export declare class FileCollector implements LogCollectorClient {
+    private filePath;
+    private fs;
+    private buffer;
+    private bufferSize;
+    private flushIntervalMs;
+    private flushTimer;
+    constructor(filePath: string, fs: FileSystem, options?: FileCollectorOptions);
+    flush(event: WideEventBase, partials: Map<string, PartialValue>, _options: FlushOptions): Promise<void>;
+    /**
+     * Flush the buffer to disk
+     */
+    flushBuffer(): Promise<void>;
+    /**
+     * Force flush any remaining buffered events (call on shutdown)
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a collector that writes events to a file with buffering.
+ */
+export declare function fileCollector(filePath: string, fs: FileSystem, options?: FileCollectorOptions): FileCollector;
+export {};

package/dist/collectors/index.js

@@ -0,0 +1,127 @@
+/**
+ * Simple collector to log the event to stdout/console
+ */
+export class StdioCollector {
+    async flush(eventBase, partials, _options) {
+        const partialsObj = {};
+        for (const [key, value] of partials) {
+            partialsObj[key] = value;
+        }
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify({
+            ...eventBase,
+            ...partialsObj,
+        }));
+    }
+}
+/**
+ * Create a collector that logs events to stdout/console.
+ */
+export function stdioCollector() {
+    return new StdioCollector();
+}
+/**
+ * Composes multiple collectors together, flushing to all of them in parallel
+ */
+export class CompositeCollector {
+    collectors;
+    constructor(collectors) {
+        this.collectors = collectors;
+    }
+    async flush(event, partials, options) {
+        await Promise.all(this.collectors.map((c) => c.flush(event, partials, options)));
+    }
+}
+/**
+ * Create a collector that flushes to multiple collectors in parallel.
+ */
+export function compositeCollector(collectors) {
+    return new CompositeCollector(collectors);
+}
+/**
+ * Wraps a collector and only flushes events that pass the filter function.
+ * Note: Events with alwaysSample=true bypass the filter by default.
+ */
+export class FilteredCollector {
+    collector;
+    filter;
+    constructor(collector, filter) {
+        this.collector = collector;
+        this.filter = filter;
+    }
+    async flush(event, partials, options) {
+        // Always-sample events bypass the filter
+        if (options.alwaysSample || this.filter(event, partials, options)) {
+            await this.collector.flush(event, partials, options);
+        }
+    }
+}
+/**
+ * Create a collector that filters events before flushing.
+ */
+export function filteredCollector(collector, filter) {
+    return new FilteredCollector(collector, filter);
+}
+/**
+ * Collector that writes events to a file with buffering
+ */
+export class FileCollector {
+    filePath;
+    fs;
+    buffer = [];
+    bufferSize;
+    flushIntervalMs;
+    flushTimer = null;
+    constructor(filePath, fs, options = {}) {
+        this.filePath = filePath;
+        this.fs = fs;
+        this.bufferSize = options.bufferSize ?? 10;
+        this.flushIntervalMs = options.flushIntervalMs ?? 5000;
+    }
+    async flush(event, partials, _options) {
+        const partialsObj = {};
+        for (const [key, value] of partials) {
+            partialsObj[key] = value;
+        }
+        const line = JSON.stringify({
+            ...event,
+            ...partialsObj,
+        }) + '\n';
+        this.buffer.push(line);
+        // Start flush timer if not already running
+        if (!this.flushTimer) {
+            this.flushTimer = setTimeout(() => this.flushBuffer(), this.flushIntervalMs);
+        }
+        // Flush immediately if buffer is full
+        if (this.buffer.length >= this.bufferSize) {
+            await this.flushBuffer();
+        }
+    }
+    /**
+     * Flush the buffer to disk
+     */
+    async flushBuffer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.buffer.length === 0) {
+            return;
+        }
+        const data = this.buffer.join('');
+        this.buffer = [];
+        await this.fs.appendFile(this.filePath, data);
+    }
+    /**
+     * Force flush any remaining buffered events (call on shutdown)
+     */
+    async close() {
+        await this.flushBuffer();
+    }
+}
+/**
+ * Create a collector that writes events to a file with buffering.
+ */
+export function fileCollector(filePath, fs, options = {}) {
+    return new FileCollector(filePath, fs, options);
+}

package/dist/collectors/sentry.d.ts

@@ -0,0 +1,46 @@
+import type { WideEventBase, EventPartial } from '../index.js';
+import type { LogCollectorClient, FlushOptions } from './index.js';
+/** Type alias for partial values (singular or array) */
+type PartialValue = EventPartial<string> | EventPartial<string>[];
+export type SentryLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export interface SentryLogger {
+    log?: (level: SentryLogLevel, message: string, attributes?: Record<string, unknown>) => void;
+    trace?: (message: string, attributes?: Record<string, unknown>) => void;
+    debug?: (message: string, attributes?: Record<string, unknown>) => void;
+    info?: (message: string, attributes?: Record<string, unknown>) => void;
+    warn?: (message: string, attributes?: Record<string, unknown>) => void;
+    error?: (message: string, attributes?: Record<string, unknown>) => void;
+    fatal?: (message: string, attributes?: Record<string, unknown>) => void;
+}
+/**
+ * Options for SentryCollector
+ */
+export interface SentryCollectorOptions {
+    /**
+     * Sentry logger instance (e.g. Sentry.logger). Requires the Sentry logger
+     * integration to be configured during Sentry.init().
+     */
+    logger: SentryLogger;
+    /** Default log level for events (default: "info") */
+    level?: SentryLogLevel;
+    /** Optional function to derive log level per event */
+    levelSelector?: (event: WideEventBase, partials: Map<string, PartialValue>, options: FlushOptions) => SentryLogLevel;
+    /** Log message to use (default: "wide-event") */
+    message?: string;
+}
+/**
+ * Collector that sends events to Sentry Logs via the Sentry logger API
+ */
+export declare class SentryCollector implements LogCollectorClient {
+    private logger;
+    private defaultLevel;
+    private levelSelector?;
+    private message;
+    constructor(options: SentryCollectorOptions);
+    flush(event: WideEventBase, partials: Map<string, PartialValue>, options: FlushOptions): Promise<void>;
+}
+/**
+ * Create a collector that sends events via the Sentry logger.
+ */
+export declare function sentryCollector(options: SentryCollectorOptions): SentryCollector;
+export {};

package/dist/collectors/sentry.js

@@ -0,0 +1,45 @@
+/**
+ * Collector that sends events to Sentry Logs via the Sentry logger API
+ */
+export class SentryCollector {
+    logger;
+    defaultLevel;
+    levelSelector;
+    message;
+    constructor(options) {
+        this.logger = options.logger;
+        this.defaultLevel = options.level ?? 'info';
+        this.levelSelector = options.levelSelector;
+        this.message = options.message ?? 'wide-event';
+    }
+    async flush(event, partials, options) {
+        const partialsObj = {};
+        for (const [key, value] of partials) {
+            partialsObj[key] = value;
+        }
+        const attributes = {
+            ...event,
+            ...partialsObj,
+        };
+        const level = this.levelSelector
+            ? this.levelSelector(event, partials, options)
+            : this.defaultLevel;
+        const loggerMethod = (level === 'trace' && this.logger.trace) ||
+            (level === 'debug' && this.logger.debug) ||
+            (level === 'info' && this.logger.info) ||
+            (level === 'warn' && this.logger.warn) ||
+            (level === 'error' && this.logger.error) ||
+            (level === 'fatal' && this.logger.fatal);
+        if (loggerMethod) {
+            loggerMethod(this.message, attributes);
+            return;
+        }
+        this.logger.log?.(level, this.message, attributes);
+    }
+}
+/**
+ * Create a collector that sends events via the Sentry logger.
+ */
+export function sentryCollector(options) {
+    return new SentryCollector(options);
+}

package/dist/collectors/stdio.d.ts

@@ -0,0 +1 @@
+export { StdioCollector, stdioCollector } from './index.js';

package/dist/collectors/stdio.js

@@ -0,0 +1 @@
+export { StdioCollector, stdioCollector } from './index.js';

package/dist/generated/partials.d.ts

@@ -0,0 +1,40 @@
+import type { EventPartial } from '../index';
+export interface UserPartial extends EventPartial<'user'> {
+    type: 'user';
+    userId: string;
+    subscriptionLevel: string;
+    dateJoined: number;
+}
+export interface SessionPartial extends EventPartial<'session'> {
+    type: 'session';
+    sessionId: string;
+    messages: number;
+    startedAt: number;
+}
+export interface ErrorPartial extends EventPartial<'error'> {
+    type: 'error';
+    message: string;
+    stack?: string;
+    code?: number;
+}
+export interface ResponsePartial extends EventPartial<'response'> {
+    type: 'response';
+    statusCode: number;
+    durationMs: number;
+    contentLength?: number;
+}
+export interface DbQueryPartial extends EventPartial<'db_query'> {
+    type: 'db_query';
+    query: string;
+    durationMs: number;
+    rowCount?: number;
+    error?: string;
+}
+export type GeneratedRegistry = {
+    user: UserPartial;
+    session: SessionPartial;
+    error: ErrorPartial;
+    response: ResponsePartial;
+    db_query: DbQueryPartial;
+};
+export type PartialName = 'user' | 'session' | 'error' | 'response' | 'db_query';

package/dist/generated/partials.js

@@ -0,0 +1,3 @@
+// Auto-generated by wevt codegen - DO NOT EDIT
+// Source: schema/partials.ts
+export {};

package/dist/index.d.ts

@@ -0,0 +1,199 @@
+import type { ZodRawShape } from 'zod';
+import type { LogCollectorClient } from './collectors/index.js';
+import type { PartialMetadata, PartialDefinition, PartialOptions, Registry, RegistryType } from './registry.js';
+/** Current sloplog library version (propagated onto Service). */
+export declare const SLOPLOG_VERSION = "0.0.2";
+/**
+ * TYPES
+ */
+/**
+ * An event partial is a structured bit of data added to a wide event.
+ * Each partial has a type discriminator and arbitrary additional fields.
+ */
+export type EventPartial<K extends string = string> = {
+    type: K;
+} & Record<string, unknown>;
+type RegistryEntry<K extends string> = {
+    type: K;
+} & Record<string, unknown>;
+type RegistryShape = Record<string, EventPartial<string> | EventPartial<string>[]>;
+/**
+ * Validates that a registry maps keys to objects with matching type discriminators
+ */
+export type ValidRegistry<T> = {
+    [K in keyof T]: K extends string ? T[K] extends RegistryEntry<K> | RegistryEntry<K>[] ? T[K] : never : never;
+};
+/**
+ * A registry of event partials - defines the shape of all partials that can be logged
+ */
+export type EventPartialRegistry<T extends ValidRegistry<T>> = {
+    [K in keyof T]: T[K];
+};
+type RegistryEntryValue<T> = T extends (infer U)[] ? U : T;
+type RegistryEntries<R> = {
+    [K in keyof R]: RegistryEntryValue<R[K]>;
+}[keyof R];
+type AnyRegistry = Registry<PartialDefinition<string, ZodRawShape, PartialOptions>[]>;
+type OriginatorInput = import('./originator/index.js').Originator | import('./originator/index.js').OriginatorFromRequestResult;
+/**
+ * Service information - where an event is emitted from
+ */
+export interface Service {
+    /** Service name (required) */
+    name: string;
+    /** Service version, if available */
+    version?: string;
+    /** sloplog library version (auto-populated if omitted) */
+    sloplogVersion?: string;
+    /** sloplog language marker (auto-populated if omitted) */
+    sloplogLanguage?: string;
+    [key: string]: unknown;
+}
+/**
+ * Create a Service payload with sloplog defaults applied.
+ */
+export declare function service(details: Service): Service;
+/**
+ * The base structure of a wide event
+ */
+export interface WideEventBase {
+    /** Unique event identifier */
+    eventId: string;
+    /** Trace ID that stays constant across the entire distributed trace */
+    traceId: string;
+    /** Service metadata for the emitting service */
+    service: Service;
+    /** Originator metadata for the event */
+    originator: import('./originator/index.js').Originator;
+}
+/**
+ * The full wide event log structure including partials
+ */
+export type WideEventLog<R extends RegistryShape> = WideEventBase & Partial<R>;
+/**
+ * Allowed log levels for log_message partials and log() calls
+ */
+export type LogMessageLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+export { type Originator, type HttpOriginator, type HttpMethod, type WebSocketOriginator, type CronOriginator, type TracingContext, type HttpOriginatorOptions, type OriginatorFromRequestResult, type NodeIncomingMessage, type CronOriginatorOptions, ORIGINATOR_HEADER, TRACE_ID_HEADER, httpOriginator, nodeHttpOriginator, cronOriginator, tracingHeaders, extractTracingContext, } from './originator/index.js';
+export type { LogCollectorClient, FlushOptions } from './collectors/index.js';
+export { builtInPartials, builtInRegistry, builtInPartialMetadata } from './partials.js';
+export type { BuiltInRegistry, BuiltInPartialName, ErrorPartial, LogMessagePartial, SpanPartial, SloplogUsageErrorPartial, } from './partials.js';
+/**
+ * Options for creating a WideEvent
+ */
+export interface WideEventOptions {
+    /** Trace ID to use (for continuing an existing trace). If not provided, a new one is generated. */
+    traceId?: string;
+    /**
+     * Runtime metadata about partials. Required for proper handling of repeatable partials
+     * and alwaysSample behavior. Defaults to metadata derived from the registry.
+     */
+    partialMetadata?: Map<string, PartialMetadata>;
+}
+/**
+ * Zod-based DSL for defining wide event partials
+ * Restricted to only allow specific primitive types for cross-language compatibility
+ */
+export { z, partial, registry, extractPartialMetadata } from './registry.js';
+export type { PartialOptions, PartialDefinition, Registry, PartialMetadata, PartialFactory, InferPartial, RegistryType, } from './registry.js';
+export { generateTypeScript, generatePython, generateJsonSchema } from './codegen.js';
+export { config } from './codegen.js';
+export type { CodegenConfig, CodegenOutputs, CodegenOutputKind, CodegenResult } from './codegen.js';
+/**
+ * Core WideEvent class.
+ * Create one WideEvent per request or unit of work and add partials as you go.
+ * Use log() for structured partials or for lightweight log_message entries.
+ * @param R pass in a valid Registry type, which defines the wide event partials you may pass in
+ */
+export declare class WideEvent<R extends RegistryShape> {
+    readonly eventId: string;
+    readonly traceId: string;
+    private collector;
+    /** All partials - singular as objects, repeatable as arrays */
+    private partials;
+    private service;
+    private originator;
+    private openSpans;
+    /** Metadata about partials (repeatable, alwaysSample) */
+    private partialMetadata;
+    /** Whether this event should always be sampled */
+    private _alwaysSample;
+    /**
+     * Create a wide event
+     *
+     * @param service Service that the wide event is being emitted on
+     * @param originator Originator (i.e. request, schedule, etc) of the wide event
+     * @param collector Location to collect/flush logs to
+     * @param options Optional configuration including traceId and partialMetadata
+     */
+    constructor(service: Service, originator: import('./originator/index.js').Originator, collector: LogCollectorClient, options?: WideEventOptions);
+    /**
+     * Check if this event should always be sampled
+     */
+    get alwaysSample(): boolean;
+    /**
+     * Manually mark this event to always be sampled
+     */
+    markAlwaysSample(): void;
+    /**
+     * Add a partial to a wide event.
+     * For singular partials, this overwrites any existing partial of the same type.
+     * For repeatable partials, this appends to the array.
+     * If the partial has alwaysSample=true, the event will be marked to always be sampled.
+     * Overwriting a singular partial records a sloplog_usage_error.
+     *
+     * @param partial wide event partial to add
+     */
+    partial(partial: RegistryEntries<R>): void;
+    /**
+     * Add a partial or log message to a wide event.
+     * log(partial) is an alias for partial(partial).
+     * log(message, data, level) creates a log_message partial.
+     * Partials are always preferred over log_message for structured data.
+     * If data is provided, it is JSON stringified (string data is passed through).
+     * If level is omitted, it defaults to "info".
+     */
+    log(partial: RegistryEntries<R>): void;
+    log(message: string, data?: unknown, level?: LogMessageLevel): void;
+    /**
+     * Add an error partial from an Error or message.
+     */
+    error(error: unknown, code?: number): void;
+    private formatErrorMessage;
+    /**
+     * Time a span around a callback and emit a span partial.
+     * Unended spans are recorded as sloplog_usage_error on flush.
+     */
+    span<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * Start a span by name
+     */
+    spanStart(name: string): void;
+    /**
+     * End a span by name
+     * Ending a span that was never started records a sloplog_usage_error.
+     */
+    spanEnd(name: string): void;
+    /**
+     * Get the current state of the wide event as a log object
+     */
+    toLog(): WideEventLog<R>;
+    /**
+     * Emit the full wide log to the collector.
+     * Any usage errors (e.g. unended spans, partial overwrites) are emitted
+     * as sloplog_usage_error partials before flushing.
+     */
+    flush(): Promise<void>;
+    private addPartialInternal;
+    private appendRepeatablePartial;
+    private isRepeatableFallback;
+    private isAlwaysSampleFallback;
+    private addUsageError;
+    private recordOpenSpans;
+}
+/**
+ * Create a WideEvent instance. Prefer this factory over class construction.
+ * Provide the registry first to infer partial types and repeatable metadata.
+ * originator can be a raw Originator or the { originator, traceId } result from httpOriginator().
+ */
+export declare function wideEvent<T extends AnyRegistry>(registry: T, service: Service, originator: OriginatorInput, collector: LogCollectorClient, options?: WideEventOptions): WideEvent<RegistryType<T>>;