sloplog 0.0.3

package/dist/index.js

@@ -0,0 +1,354 @@
+import { extractPartialMetadata } from './registry.js';
+/**
+ * Generate a nano ID for unique identifiers
+ */
+function nanoId() {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let i = 0; i < 21; i++) {
+        result += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return result;
+}
+/** Current sloplog library version (propagated onto Service). */
+export const SLOPLOG_VERSION = '0.0.2';
+/** Default language marker when Service.sloplogLanguage is not set. */
+const SLOPLOG_LANGUAGE = 'typescript';
+function isOriginatorResult(input) {
+    return (typeof input === 'object' &&
+        input !== null &&
+        'originator' in input &&
+        'traceId' in input &&
+        typeof input.traceId === 'string');
+}
+/**
+ * Create a Service payload with sloplog defaults applied.
+ */
+export function service(details) {
+    return {
+        ...details,
+        sloplogVersion: details.sloplogVersion ?? SLOPLOG_VERSION,
+        sloplogLanguage: details.sloplogLanguage ?? SLOPLOG_LANGUAGE,
+    };
+}
+// Re-export originator types and functions
+export { 
+// Constants
+ORIGINATOR_HEADER, TRACE_ID_HEADER, 
+// Functions
+httpOriginator, nodeHttpOriginator, cronOriginator, tracingHeaders, extractTracingContext, } from './originator/index.js';
+// Collectors are exposed via subpath exports (sloplog/collectors/*).
+// Re-export built-in partials registry and types
+export { builtInPartials, builtInRegistry, builtInPartialMetadata } from './partials.js';
+/**
+ * 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';
+// Re-export codegen functions
+export { generateTypeScript, generatePython, generateJsonSchema } from './codegen.js';
+export { config } 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 class WideEvent {
+    eventId;
+    traceId;
+    collector;
+    /** All partials - singular as objects, repeatable as arrays */
+    partials = new Map();
+    service;
+    originator;
+    openSpans = new Map();
+    /** Metadata about partials (repeatable, alwaysSample) */
+    partialMetadata;
+    /** Whether this event should always be sampled */
+    _alwaysSample = false;
+    /**
+     * 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, originator, collector, options = {}) {
+        this.eventId = `evt_${nanoId()}`;
+        this.traceId = options.traceId || `trace_${nanoId()}`;
+        this.service = {
+            ...service,
+            sloplogVersion: service.sloplogVersion ?? SLOPLOG_VERSION,
+            sloplogLanguage: service.sloplogLanguage ?? SLOPLOG_LANGUAGE,
+        };
+        this.originator = originator;
+        this.collector = collector;
+        this.partialMetadata = options.partialMetadata ?? new Map();
+    }
+    /**
+     * Check if this event should always be sampled
+     */
+    get alwaysSample() {
+        return this._alwaysSample;
+    }
+    /**
+     * Manually mark this event to always be sampled
+     */
+    markAlwaysSample() {
+        this._alwaysSample = true;
+    }
+    /**
+     * 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) {
+        this.addPartialInternal(partial);
+    }
+    log(arg1, arg2, arg3) {
+        if (typeof arg1 !== 'string') {
+            this.addPartialInternal(arg1);
+            return;
+        }
+        let data;
+        if (typeof arg2 === 'string') {
+            data = arg2;
+        }
+        else if (arg2 !== undefined) {
+            try {
+                data = JSON.stringify(arg2);
+            }
+            catch {
+                this.addUsageError('log_message_stringify_error', 'Failed to stringify log data');
+            }
+        }
+        const level = arg3 ?? 'info';
+        this.addPartialInternal({
+            type: 'log_message',
+            message: arg1,
+            level,
+            ...(data !== undefined ? { data } : {}),
+        });
+    }
+    /**
+     * Add an error partial from an Error or message.
+     */
+    error(error, code) {
+        if (typeof error === 'object' && error !== null) {
+            const maybePartial = error;
+            if (maybePartial.type === 'error' && typeof maybePartial.message === 'string') {
+                this.addPartialInternal(error);
+                return;
+            }
+        }
+        const payload = {
+            type: 'error',
+            message: this.formatErrorMessage(error),
+        };
+        if (error instanceof Error && error.stack) {
+            payload.stack = error.stack;
+        }
+        else if (typeof error === 'object' &&
+            error !== null &&
+            typeof error.stack === 'string') {
+            payload.stack = error.stack;
+        }
+        const errorCode = typeof code === 'number'
+            ? code
+            : typeof error === 'object' &&
+                error !== null &&
+                typeof error.code === 'number'
+                ? error.code
+                : undefined;
+        if (typeof errorCode === 'number') {
+            payload.code = errorCode;
+        }
+        this.addPartialInternal(payload);
+    }
+    formatErrorMessage(error) {
+        if (typeof error === 'string') {
+            return error;
+        }
+        if (error instanceof Error) {
+            return error.message || 'Unknown error';
+        }
+        if (typeof error === 'object' && error !== null) {
+            const maybeMessage = error.message;
+            if (typeof maybeMessage === 'string') {
+                return maybeMessage;
+            }
+            try {
+                const serialized = JSON.stringify(error);
+                return typeof serialized === 'string' ? serialized : 'Unknown error';
+            }
+            catch {
+                return 'Unknown error';
+            }
+        }
+        return String(error);
+    }
+    /**
+     * Time a span around a callback and emit a span partial.
+     * Unended spans are recorded as sloplog_usage_error on flush.
+     */
+    async span(name, fn) {
+        this.spanStart(name);
+        try {
+            return await fn();
+        }
+        finally {
+            this.spanEnd(name);
+        }
+    }
+    /**
+     * Start a span by name
+     */
+    spanStart(name) {
+        const startedAt = Date.now();
+        const existing = this.openSpans.get(name);
+        if (existing) {
+            existing.push(startedAt);
+        }
+        else {
+            this.openSpans.set(name, [startedAt]);
+        }
+    }
+    /**
+     * End a span by name
+     * Ending a span that was never started records a sloplog_usage_error.
+     */
+    spanEnd(name) {
+        const existing = this.openSpans.get(name);
+        if (!existing || existing.length === 0) {
+            this.addUsageError('span_end_without_start', `Span "${name}" ended without start`, {
+                spanName: name,
+            });
+            return;
+        }
+        const startedAt = existing.pop();
+        if (startedAt === undefined) {
+            return;
+        }
+        if (existing.length === 0) {
+            this.openSpans.delete(name);
+        }
+        const endedAt = Date.now();
+        const durationMs = endedAt - startedAt;
+        this.addPartialInternal({
+            type: 'span',
+            name,
+            startedAt,
+            endedAt,
+            durationMs,
+        });
+    }
+    /**
+     * Get the current state of the wide event as a log object
+     */
+    toLog() {
+        const result = {
+            eventId: this.eventId,
+            traceId: this.traceId,
+            service: this.service,
+            originator: this.originator,
+        };
+        for (const [key, value] of this.partials) {
+            result[key] = value;
+        }
+        return result;
+    }
+    /**
+     * 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.
+     */
+    async flush() {
+        this.recordOpenSpans();
+        await this.collector.flush({
+            eventId: this.eventId,
+            traceId: this.traceId,
+            originator: this.originator,
+            service: this.service,
+        }, this.partials, { alwaysSample: this._alwaysSample });
+    }
+    addPartialInternal(partial) {
+        const metadata = this.partialMetadata.get(partial.type);
+        const isRepeatable = metadata?.repeatable ?? this.isRepeatableFallback(partial.type);
+        if (metadata?.alwaysSample || this.isAlwaysSampleFallback(partial.type)) {
+            this._alwaysSample = true;
+        }
+        if (isRepeatable) {
+            this.appendRepeatablePartial(partial.type, partial);
+            return;
+        }
+        if (this.partials.has(partial.type)) {
+            this.addUsageError('partial_overwrite', `Partial "${partial.type}" was overwritten`, {
+                partialType: partial.type,
+            });
+        }
+        this.partials.set(partial.type, partial);
+    }
+    appendRepeatablePartial(type, partial) {
+        const existing = this.partials.get(type);
+        if (Array.isArray(existing)) {
+            existing.push(partial);
+            return;
+        }
+        if (existing) {
+            this.partials.set(type, [existing, partial]);
+            return;
+        }
+        this.partials.set(type, [partial]);
+    }
+    isRepeatableFallback(type) {
+        return (type === 'error' ||
+            type === 'log_message' ||
+            type === 'span' ||
+            type === 'sloplog_usage_error');
+    }
+    isAlwaysSampleFallback(type) {
+        return type === 'error';
+    }
+    addUsageError(kind, message, details = {}) {
+        this.appendRepeatablePartial('sloplog_usage_error', {
+            type: 'sloplog_usage_error',
+            kind,
+            message,
+            ...details,
+        });
+    }
+    recordOpenSpans() {
+        if (this.openSpans.size === 0) {
+            return;
+        }
+        for (const [name, starts] of this.openSpans) {
+            for (const startedAt of starts) {
+                this.addUsageError('span_unended', `Span "${name}" was started but never ended`, {
+                    spanName: name,
+                    startedAt,
+                });
+            }
+        }
+        this.openSpans.clear();
+    }
+}
+/**
+ * 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 function wideEvent(registry, service, originator, collector, options = {}) {
+    const resolvedOriginator = isOriginatorResult(originator) ? originator.originator : originator;
+    const traceId = options.traceId ?? (isOriginatorResult(originator) ? originator.traceId : undefined);
+    const partialMetadata = options.partialMetadata ?? extractPartialMetadata(registry);
+    return new WideEvent(service, resolvedOriginator, collector, {
+        traceId,
+        partialMetadata,
+    });
+}

package/dist/originator/index.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Originator module - functions for creating originators from various sources
+ */
+/** HTTP method types */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * Base originator interface - an external thing that triggered your service
+ * This is like a trace that can cross service boundaries
+ */
+export interface Originator {
+    /** Unique identifier for this originator chain (propagates across services) */
+    originatorId: string;
+    /** Type discriminator for the originator */
+    type: string;
+    /** Timestamp when the originator was created (Unix ms) */
+    timestamp: number;
+    /** Parent originator ID if this is a child span */
+    parentId?: string;
+    [key: string]: unknown;
+}
+/**
+ * HTTP request originator
+ */
+export interface HttpOriginator extends Originator {
+    type: 'http';
+    method: HttpMethod;
+    path: string;
+    /** Query string (without leading ?) */
+    query?: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Client IP address */
+    clientIp?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** Content type of the request */
+    contentType?: string;
+    /** Content length in bytes */
+    contentLength?: number;
+    /** HTTP protocol version (e.g., "1.1", "2") */
+    httpVersion?: string;
+    /** Host header value */
+    host?: string;
+}
+/**
+ * WebSocket message originator
+ */
+export interface WebSocketOriginator extends Originator {
+    type: 'websocket';
+    /** WebSocket session/connection ID */
+    sessionId: string;
+    /** Message source identifier */
+    source: string;
+    /** Message type (e.g., "text", "binary") */
+    messageType?: 'text' | 'binary';
+    /** Size of the message in bytes */
+    messageSize?: number;
+}
+/**
+ * Cron/scheduled task originator
+ */
+export interface CronOriginator extends Originator {
+    type: 'cron';
+    /** Cron expression (e.g., "0 0 * * *") */
+    cron: string;
+    /** Name of the scheduled job */
+    jobName?: string;
+    /** Scheduled execution time (Unix ms) */
+    scheduledTime?: number;
+}
+/** Header name for propagating originator ID across services */
+export declare const ORIGINATOR_HEADER = "x-sloplog-originator";
+/** Header name for propagating trace ID across services */
+export declare const TRACE_ID_HEADER = "x-sloplog-trace-id";
+/**
+ * Tracing context to propagate across services
+ */
+export interface TracingContext {
+    /** The trace ID (stays constant across the entire distributed trace) */
+    traceId: string;
+    /** The originator ID of the calling service (becomes parentId in the callee) */
+    originatorId: string;
+}
+/**
+ * Create headers for propagating tracing context to downstream services
+ */
+export declare function tracingHeaders(context: TracingContext): Record<string, string>;
+/**
+ * Extract tracing context from incoming request headers
+ * Returns null if no tracing headers are present
+ */
+export declare function extractTracingContext(headers: Record<string, string | string[] | undefined>): TracingContext | null;
+/**
+ * Options for creating an HTTP originator
+ */
+export interface HttpOriginatorOptions {
+    /** Override the originator ID (useful when continuing a trace) */
+    originatorId?: string;
+    /** Parent originator ID (for child originators) */
+    parentId?: string;
+}
+/**
+ * Result of creating an originator from an incoming request
+ * Contains both the originator and the extracted traceId (if any)
+ */
+export interface OriginatorFromRequestResult {
+    /** The created HTTP originator */
+    originator: HttpOriginator;
+    /** The trace ID extracted from headers, or a newly generated one */
+    traceId: string;
+}
+/**
+ * Create an HTTP originator from a Web Fetch API Request
+ * Extracts tracing context from headers if present:
+ * - traceId: extracted from x-sloplog-trace-id header, or generated if not present
+ * - parentId: set to the incoming x-sloplog-originator header value (the caller's originatorId),
+ *   or can be explicitly provided via options.parentId
+ */
+export declare function httpOriginator(request: Request, options?: HttpOriginatorOptions): OriginatorFromRequestResult;
+/**
+ * Node.js IncomingMessage-like interface
+ */
+export interface NodeIncomingMessage {
+    method?: string;
+    url?: string;
+    headers: Record<string, string | string[] | undefined>;
+    httpVersion?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+}
+/**
+ * Create an HTTP originator from a Node.js IncomingMessage (http/https/express)
+ * Extracts tracing context from headers if present:
+ * - traceId: extracted from x-sloplog-trace-id header, or generated if not present
+ * - parentId: set to the incoming x-sloplog-originator header value (the caller's originatorId),
+ *   or can be explicitly provided via options.parentId
+ */
+export declare function nodeHttpOriginator(request: NodeIncomingMessage, options?: HttpOriginatorOptions): OriginatorFromRequestResult;
+/**
+ * Options for creating a cron originator
+ */
+export interface CronOriginatorOptions {
+    /** Parent originator ID (for child originators) */
+    parentId?: string;
+}
+/**
+ * Create a cron originator for scheduled tasks
+ */
+export declare function cronOriginator(cron: string, jobName?: string, options?: CronOriginatorOptions): CronOriginator;