sloplog 0.0.3

package/dist/originator/index.js

@@ -0,0 +1,217 @@
+/**
+ * Originator module - functions for creating originators from various sources
+ */
+/**
+ * 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;
+}
+/** Header name for propagating originator ID across services */
+export const ORIGINATOR_HEADER = 'x-sloplog-originator';
+/** Header name for propagating trace ID across services */
+export const TRACE_ID_HEADER = 'x-sloplog-trace-id';
+/**
+ * Create headers for propagating tracing context to downstream services
+ */
+export function tracingHeaders(context) {
+    return {
+        [TRACE_ID_HEADER]: context.traceId,
+        [ORIGINATOR_HEADER]: context.originatorId,
+    };
+}
+/**
+ * Extract tracing context from incoming request headers
+ * Returns null if no tracing headers are present
+ */
+export function extractTracingContext(headers) {
+    // Case-insensitive header lookup for trace ID
+    let traceIdValue;
+    let originatorIdValue;
+    for (const [key, value] of Object.entries(headers)) {
+        const lowerKey = key.toLowerCase();
+        if (lowerKey === TRACE_ID_HEADER.toLowerCase()) {
+            traceIdValue = Array.isArray(value) ? value[0] : value;
+        }
+        else if (lowerKey === ORIGINATOR_HEADER.toLowerCase()) {
+            originatorIdValue = Array.isArray(value) ? value[0] : value;
+        }
+    }
+    if (!traceIdValue || !originatorIdValue) {
+        return null;
+    }
+    return {
+        traceId: traceIdValue,
+        originatorId: originatorIdValue,
+    };
+}
+/** Placeholder for redacted values */
+const REDACTED = '[REDACTED]';
+/** Headers that should be redacted (case-insensitive) */
+const SENSITIVE_HEADERS = new Set([
+    'authorization',
+    'x-api-key',
+    'x-auth-token',
+    'cookie',
+    'set-cookie',
+]);
+/** Query parameters that should be redacted (case-insensitive) */
+const SENSITIVE_QUERY_PARAMS = new Set([
+    'code',
+    'token',
+    'access_token',
+    'refresh_token',
+    'api_key',
+    'apikey',
+    'secret',
+    'password',
+]);
+/**
+ * Redact sensitive headers from a headers object
+ */
+function redactHeaders(headers) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (SENSITIVE_HEADERS.has(key.toLowerCase())) {
+            redacted[key] = REDACTED;
+        }
+        else {
+            redacted[key] = value;
+        }
+    }
+    return redacted;
+}
+/**
+ * Redact sensitive query parameters from a query string
+ */
+function redactQueryString(query) {
+    if (!query)
+        return query;
+    const params = new URLSearchParams(query);
+    const redactedParams = new URLSearchParams();
+    for (const [key, value] of params.entries()) {
+        if (SENSITIVE_QUERY_PARAMS.has(key.toLowerCase())) {
+            redactedParams.set(key, REDACTED);
+        }
+        else {
+            redactedParams.set(key, value);
+        }
+    }
+    const result = redactedParams.toString();
+    return result || undefined;
+}
+/**
+ * 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 function httpOriginator(request, options = {}) {
+    const url = new URL(request.url);
+    const headers = {};
+    request.headers.forEach((value, key) => {
+        headers[key.toLowerCase()] = value;
+    });
+    // Check for incoming tracing context
+    const tracingContext = extractTracingContext(headers);
+    // Redact sensitive data
+    const redactedHeaders = redactHeaders(headers);
+    const query = url.search ? url.search.slice(1) : undefined;
+    const redactedQuery = redactQueryString(query);
+    // Determine parentId: explicit option > tracing context > undefined
+    const parentId = options.parentId ?? tracingContext?.originatorId;
+    const originator = {
+        originatorId: options.originatorId || `orig_${nanoId()}`,
+        type: 'http',
+        timestamp: Date.now(),
+        ...(parentId && { parentId }),
+        method: request.method.toUpperCase(),
+        path: url.pathname,
+        query: redactedQuery,
+        headers: redactedHeaders,
+        host: url.host,
+        userAgent: headers['user-agent'],
+        contentType: headers['content-type'],
+        contentLength: headers['content-length'] ? parseInt(headers['content-length'], 10) : undefined,
+    };
+    return {
+        originator,
+        // Use incoming traceId if present, otherwise generate a new one
+        traceId: tracingContext?.traceId || `trace_${nanoId()}`,
+    };
+}
+/**
+ * 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 function nodeHttpOriginator(request, options = {}) {
+    const headers = {};
+    for (const [key, value] of Object.entries(request.headers)) {
+        if (value) {
+            headers[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+        }
+    }
+    // Parse URL
+    const urlStr = request.url || '/';
+    const host = headers['host'] || 'localhost';
+    let path = urlStr;
+    let query;
+    const queryIndex = urlStr.indexOf('?');
+    if (queryIndex !== -1) {
+        path = urlStr.slice(0, queryIndex);
+        query = urlStr.slice(queryIndex + 1);
+    }
+    // Check for incoming tracing context
+    const tracingContext = extractTracingContext(headers);
+    // Get client IP (check x-forwarded-for for proxied requests)
+    const clientIp = headers['x-forwarded-for']?.split(',')[0].trim() || request.socket?.remoteAddress;
+    // Redact sensitive data
+    const redactedHeaders = redactHeaders(headers);
+    const redactedQuery = redactQueryString(query);
+    // Determine parentId: explicit option > tracing context > undefined
+    const parentId = options.parentId ?? tracingContext?.originatorId;
+    const originator = {
+        originatorId: options.originatorId || `orig_${nanoId()}`,
+        type: 'http',
+        timestamp: Date.now(),
+        ...(parentId && { parentId }),
+        method: (request.method?.toUpperCase() || 'GET'),
+        path,
+        query: redactedQuery,
+        headers: redactedHeaders,
+        host,
+        clientIp,
+        userAgent: headers['user-agent'],
+        contentType: headers['content-type'],
+        contentLength: headers['content-length'] ? parseInt(headers['content-length'], 10) : undefined,
+        httpVersion: request.httpVersion,
+    };
+    return {
+        originator,
+        // Use incoming traceId if present, otherwise generate a new one
+        traceId: tracingContext?.traceId || `trace_${nanoId()}`,
+    };
+}
+/**
+ * Create a cron originator for scheduled tasks
+ */
+export function cronOriginator(cron, jobName, options = {}) {
+    return {
+        originatorId: `orig_${nanoId()}`,
+        type: 'cron',
+        timestamp: Date.now(),
+        ...(options.parentId && { parentId: options.parentId }),
+        cron,
+        jobName,
+        scheduledTime: Date.now(),
+    };
+}

package/dist/partials.d.ts

@@ -0,0 +1,154 @@
+import { z, type InferPartial } from './registry.js';
+declare const error: import("./registry.js").PartialFactory<"error", {
+    message: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodNumber>;
+}, {
+    repeatable: true;
+    alwaysSample: true;
+    description: string;
+}>;
+declare const logMessage: import("./registry.js").PartialFactory<"log_message", {
+    message: z.ZodString;
+    level: z.ZodEnum<{
+        error: "error";
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        fatal: "fatal";
+    }>;
+    data: z.ZodOptional<z.ZodString>;
+}, {
+    repeatable: true;
+    description: string;
+}>;
+declare const span: import("./registry.js").PartialFactory<"span", {
+    name: z.ZodString;
+    startedAt: z.ZodNumber;
+    endedAt: z.ZodNumber;
+    durationMs: z.ZodNumber;
+}, {
+    repeatable: true;
+    description: string;
+}>;
+declare const sloplogUsageError: import("./registry.js").PartialFactory<"sloplog_usage_error", {
+    kind: z.ZodString;
+    message: z.ZodString;
+    partialType: z.ZodOptional<z.ZodString>;
+    spanName: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    count: z.ZodOptional<z.ZodNumber>;
+}, {
+    repeatable: true;
+    description: string;
+}>;
+/** Built-in partial definitions shipped with sloplog. */
+export declare const builtInPartials: {
+    error: import("./registry.js").PartialFactory<"error", {
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodNumber>;
+    }, {
+        repeatable: true;
+        alwaysSample: true;
+        description: string;
+    }>;
+    log_message: import("./registry.js").PartialFactory<"log_message", {
+        message: z.ZodString;
+        level: z.ZodEnum<{
+            error: "error";
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            fatal: "fatal";
+        }>;
+        data: z.ZodOptional<z.ZodString>;
+    }, {
+        repeatable: true;
+        description: string;
+    }>;
+    span: import("./registry.js").PartialFactory<"span", {
+        name: z.ZodString;
+        startedAt: z.ZodNumber;
+        endedAt: z.ZodNumber;
+        durationMs: z.ZodNumber;
+    }, {
+        repeatable: true;
+        description: string;
+    }>;
+    sloplog_usage_error: import("./registry.js").PartialFactory<"sloplog_usage_error", {
+        kind: z.ZodString;
+        message: z.ZodString;
+        partialType: z.ZodOptional<z.ZodString>;
+        spanName: z.ZodOptional<z.ZodString>;
+        startedAt: z.ZodOptional<z.ZodNumber>;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, {
+        repeatable: true;
+        description: string;
+    }>;
+};
+/** Registry of built-in partial definitions. */
+export declare const builtInRegistry: import("./registry.js").Registry<(import("./registry.js").PartialFactory<"error", {
+    message: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodNumber>;
+}, {
+    repeatable: true;
+    alwaysSample: true;
+    description: string;
+}> | import("./registry.js").PartialFactory<"log_message", {
+    message: z.ZodString;
+    level: z.ZodEnum<{
+        error: "error";
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        fatal: "fatal";
+    }>;
+    data: z.ZodOptional<z.ZodString>;
+}, {
+    repeatable: true;
+    description: string;
+}> | import("./registry.js").PartialFactory<"span", {
+    name: z.ZodString;
+    startedAt: z.ZodNumber;
+    endedAt: z.ZodNumber;
+    durationMs: z.ZodNumber;
+}, {
+    repeatable: true;
+    description: string;
+}> | import("./registry.js").PartialFactory<"sloplog_usage_error", {
+    kind: z.ZodString;
+    message: z.ZodString;
+    partialType: z.ZodOptional<z.ZodString>;
+    spanName: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    count: z.ZodOptional<z.ZodNumber>;
+}, {
+    repeatable: true;
+    description: string;
+}>)[]>;
+/** Runtime metadata for built-in partials (repeatable, alwaysSample). */
+export declare const builtInPartialMetadata: Map<string, import("./registry.js").PartialMetadata>;
+/** Error partial payload type. */
+export type ErrorPartial = InferPartial<typeof error>;
+/** log_message partial payload type. */
+export type LogMessagePartial = InferPartial<typeof logMessage>;
+/** span partial payload type. */
+export type SpanPartial = InferPartial<typeof span>;
+/** sloplog_usage_error partial payload type. */
+export type SloplogUsageErrorPartial = InferPartial<typeof sloplogUsageError>;
+/** Built-in partial registry shape. */
+export type BuiltInRegistry = {
+    error: ErrorPartial[];
+    log_message: LogMessagePartial[];
+    span: SpanPartial[];
+    sloplog_usage_error: SloplogUsageErrorPartial[];
+};
+/** Union of built-in partial names. */
+export type BuiltInPartialName = keyof BuiltInRegistry;
+export {};

package/dist/partials.js

@@ -0,0 +1,52 @@
+import { extractPartialMetadata, partial, registry, z } from './registry.js';
+const error = partial('error', {
+    message: z.string(),
+    stack: z.string().optional(),
+    code: z.number().optional(),
+}, {
+    repeatable: true,
+    alwaysSample: true,
+    description: 'Error details captured during event processing.',
+});
+const logMessageLevel = z
+    .enum(['trace', 'debug', 'info', 'warn', 'error', 'fatal'])
+    .describe('Log severity level for a log_message partial.');
+const logMessage = partial('log_message', {
+    message: z.string().describe('Human-readable log message.'),
+    level: logMessageLevel,
+    data: z.string().optional().describe('Optional stringified payload for the log.'),
+}, {
+    repeatable: true,
+    description: 'Lightweight log entry for ad-hoc logging. Prefer structured partials when possible.',
+});
+const span = partial('span', {
+    name: z.string().describe('Span name.'),
+    startedAt: z.number().describe('Span start time in milliseconds since epoch.'),
+    endedAt: z.number().describe('Span end time in milliseconds since epoch.'),
+    durationMs: z.number().describe('Span duration in milliseconds.'),
+}, {
+    repeatable: true,
+    description: 'Timing span emitted by WideEvent span helpers.',
+});
+const sloplogUsageError = partial('sloplog_usage_error', {
+    kind: z.string().describe('Usage error category.'),
+    message: z.string().describe('Human-readable usage error message.'),
+    partialType: z.string().optional().describe('Partial type involved in the error.'),
+    spanName: z.string().optional().describe('Span name involved in the error.'),
+    startedAt: z.number().optional().describe('Span start time in ms when relevant.'),
+    count: z.number().optional().describe('Optional count related to the error.'),
+}, {
+    repeatable: true,
+    description: 'Internal usage errors emitted by sloplog (e.g. partial overwrites or span misuse).',
+});
+/** Built-in partial definitions shipped with sloplog. */
+export const builtInPartials = {
+    error,
+    log_message: logMessage,
+    span,
+    sloplog_usage_error: sloplogUsageError,
+};
+/** Registry of built-in partial definitions. */
+export const builtInRegistry = registry([error, logMessage, span, sloplogUsageError]);
+/** Runtime metadata for built-in partials (repeatable, alwaysSample). */
+export const builtInPartialMetadata = extractPartialMetadata(builtInRegistry);

package/dist/registry.d.ts

@@ -0,0 +1,89 @@
+import { z, type ZodObject, type ZodRawShape } from 'zod';
+export { z };
+type AllowedZodPrimitive = z.ZodString | z.ZodNumber | z.ZodBoolean | z.ZodEnum<Record<string, string>>;
+type AllowedZodType = AllowedZodPrimitive | z.ZodArray<AllowedZodPrimitive> | z.ZodOptional<AllowedZodPrimitive> | z.ZodOptional<z.ZodArray<AllowedZodPrimitive>>;
+type AllowedShape = {
+    [key: string]: AllowedZodType;
+};
+/**
+ * Options for defining a partial
+ */
+export interface PartialOptions {
+    /**
+     * If true, multiple instances of this partial can be attached to a single wide event.
+     * The partial will be stored as an array in the final log.
+     * @default false
+     */
+    repeatable?: boolean;
+    /**
+     * If true, adding this partial to an event will mark the event to always be sampled.
+     * Useful for error partials or other critical events that should never be dropped.
+     * @default false
+     */
+    alwaysSample?: boolean;
+    /**
+     * Optional description used for generated docs and schemas.
+     */
+    description?: string;
+}
+export interface PartialDefinition<T extends string, S extends ZodRawShape, O extends PartialOptions = PartialOptions> {
+    /** Partial type discriminator */
+    name: T;
+    /** Zod schema for the partial payload */
+    schema: ZodObject<S>;
+    /** Repeatable and sampling behavior */
+    options: O;
+}
+export interface Registry<T extends PartialDefinition<string, ZodRawShape, PartialOptions>[]> {
+    /** List of partial definitions that make up this registry */
+    partials: T;
+}
+/**
+ * Runtime metadata about partials, extracted from the registry for use by WideEvent
+ */
+export interface PartialMetadata {
+    /** Whether this partial may appear multiple times */
+    repeatable: boolean;
+    /** Whether this partial forces alwaysSample for the event */
+    alwaysSample: boolean;
+}
+/**
+ * Callable partial definition that creates a partial payload from input data.
+ */
+export type PartialFactory<T extends string, S extends ZodRawShape, O extends PartialOptions = PartialOptions> = PartialDefinition<T, S, O> & {
+    (data: z.input<ZodObject<S>>): z.infer<ZodObject<S>> & {
+        type: T;
+    };
+};
+/**
+ * Define a partial with a name and Zod schema
+ * Only allows: z.string(), z.number(), z.boolean(), and their arrays/optionals
+ *
+ * @param name - The unique name/type discriminator for this partial
+ * @param schema - Zod schema defining the partial's fields
+ * @param options - Optional configuration for repeatable and alwaysSample behavior
+ */
+export declare function partial<T extends string, S extends AllowedShape, O extends PartialOptions = PartialOptions>(name: T, schema: S, options?: O): PartialFactory<T, S, O>;
+/**
+ * Create a registry of partials
+ */
+export declare function registry<T extends PartialDefinition<string, ZodRawShape, PartialOptions>[]>(partials: T): Registry<T>;
+/**
+ * Extract runtime metadata from a registry for use by WideEvent
+ */
+export declare function extractPartialMetadata(reg: Registry<PartialDefinition<string, ZodRawShape, PartialOptions>[]>): Map<string, PartialMetadata>;
+/**
+ * Infer the TypeScript type from a partial definition
+ */
+export type InferPartial<T extends PartialDefinition<string, ZodRawShape>> = z.infer<T['schema']> & {
+    type: T['name'];
+};
+type PartialValueFor<P extends PartialDefinition<string, ZodRawShape, PartialOptions>> = P['options'] extends {
+    repeatable: true;
+} ? InferPartial<P>[] : InferPartial<P>;
+/**
+ * Infer the registry log shape from a registry definition.
+ */
+export type RegistryType<T extends Registry<PartialDefinition<string, ZodRawShape, PartialOptions>[]>> = {
+    [P in T['partials'][number] as P['name']]: PartialValueFor<P>;
+};

package/dist/registry.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+// Re-export z for schema definitions
+export { z };
+/**
+ * Define a partial with a name and Zod schema
+ * Only allows: z.string(), z.number(), z.boolean(), and their arrays/optionals
+ *
+ * @param name - The unique name/type discriminator for this partial
+ * @param schema - Zod schema defining the partial's fields
+ * @param options - Optional configuration for repeatable and alwaysSample behavior
+ */
+export function partial(name, schema, options = {}) {
+    const objectSchema = z.object(schema);
+    const describedSchema = options.description
+        ? objectSchema.describe(options.description)
+        : objectSchema;
+    const factory = ((data) => {
+        const parsed = describedSchema.parse(data);
+        return { type: name, ...parsed };
+    });
+    Object.defineProperty(factory, 'name', { value: name, configurable: true });
+    factory.schema = describedSchema;
+    factory.options = options;
+    return factory;
+}
+/**
+ * Create a registry of partials
+ */
+export function registry(partials) {
+    return { partials };
+}
+/**
+ * Extract runtime metadata from a registry for use by WideEvent
+ */
+export function extractPartialMetadata(reg) {
+    const metadata = new Map();
+    for (const partial of reg.partials) {
+        metadata.set(partial.name, {
+            repeatable: partial.options.repeatable ?? false,
+            alwaysSample: partial.options.alwaysSample ?? false,
+        });
+    }
+    return metadata;
+}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "sloplog",
+  "version": "0.0.3",
+  "description": "A TypeScript library for constructing wide events",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./codegen": {
+      "import": "./dist/codegen.js",
+      "types": "./dist/codegen.d.ts"
+    },
+    "./partials": {
+      "import": "./dist/partials.js",
+      "types": "./dist/partials.d.ts"
+    },
+    "./collectors/stdio": {
+      "import": "./dist/collectors/stdio.js",
+      "types": "./dist/collectors/stdio.d.ts"
+    },
+    "./collectors/composite": {
+      "import": "./dist/collectors/composite.js",
+      "types": "./dist/collectors/composite.d.ts"
+    },
+    "./collectors/filtered": {
+      "import": "./dist/collectors/filtered.js",
+      "types": "./dist/collectors/filtered.d.ts"
+    },
+    "./collectors/file": {
+      "import": "./dist/collectors/file.js",
+      "types": "./dist/collectors/file.d.ts"
+    },
+    "./collectors/betterstack": {
+      "import": "./dist/collectors/betterstack.js",
+      "types": "./dist/collectors/betterstack.d.ts"
+    },
+    "./collectors/sentry": {
+      "import": "./dist/collectors/sentry.js",
+      "types": "./dist/collectors/sentry.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write '**/*.{ts,js,json,md}'",
+    "format:check": "prettier --check '**/*.{ts,js,json,md}'",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run lint && npm run format:check && npm run typecheck",
+    "prepublishOnly": "npm run check && npm run build && npm test"
+  },
+  "keywords": [
+    "wide-events",
+    "logging",
+    "observability",
+    "tracing",
+    "structured-logging"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cmsparks/sloplog.git"
+  },
+  "homepage": "https://github.com/cmsparks/sloplog#readme",
+  "bugs": {
+    "url": "https://github.com/cmsparks/sloplog/issues"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.9",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.0",
+    "pyright": "^1.1.408",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.53.1",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.5"
+  },
+  "peerDependencies": {
+    "@sentry/node": "*"
+  },
+  "peerDependenciesMeta": {
+    "@sentry/node": {
+      "optional": true
+    }
+  }
+}