sloplog 0.0.3

package/dist/codegen.js

@@ -0,0 +1,500 @@
+/**
+ * Code generation utilities for sloplog partials
+ *
+ * Generates TypeScript, Python, and JSON Schema from partial definitions
+ */
+function getZodFieldInfo(zodType) {
+    let current = zodType;
+    let isOptional = false;
+    let isArray = false;
+    let description;
+    // Zod v4 uses _def.type instead of _def.typeName
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getDefType = (t) => t._def.type || t._def.typeName;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getDescription = (t) => t._def.description;
+    description = getDescription(current);
+    // Unwrap optional
+    if (getDefType(current) === 'optional') {
+        isOptional = true;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        current = current._def.innerType;
+        description = description ?? getDescription(current);
+    }
+    // Unwrap array
+    if (getDefType(current) === 'array') {
+        isArray = true;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        current = current._def.element;
+        description = description ?? getDescription(current);
+    }
+    // Get base type
+    let baseType;
+    const defType = getDefType(current);
+    let enumValues;
+    switch (defType) {
+        case 'string':
+            baseType = 'string';
+            break;
+        case 'number':
+            baseType = 'number';
+            break;
+        case 'boolean':
+            baseType = 'boolean';
+            break;
+        case 'enum': {
+            baseType = 'string';
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const def = current._def;
+            const values = def.values ?? def.options;
+            if (Array.isArray(values)) {
+                enumValues = values.filter((value) => typeof value === 'string');
+            }
+            else if (def.entries && typeof def.entries === 'object') {
+                enumValues = Object.values(def.entries).filter((value) => typeof value === 'string');
+            }
+            break;
+        }
+        case 'nativeEnum': {
+            baseType = 'string';
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const values = current._def.values;
+            if (values && typeof values === 'object') {
+                enumValues = Object.values(values).filter((value) => typeof value === 'string');
+            }
+            break;
+        }
+        default:
+            throw new Error(`Unsupported Zod type: ${defType}`);
+    }
+    return { baseType, isArray, isOptional, enumValues, description };
+}
+/**
+ * Get the shape entries from a Zod schema, filtering out internal properties
+ */
+function getSchemaEntries(schema) {
+    const shape = schema.shape;
+    return Object.entries(shape).filter(([_key, value]) => {
+        // Filter out non-Zod entries and internal properties
+        return value && typeof value === 'object' && '_def' in value;
+    });
+}
+function getPartialDescription(def) {
+    return def.options.description;
+}
+/**
+ * Convert a partial schema to JSON Schema
+ */
+function partialToJsonSchema(def) {
+    const properties = {
+        type: { const: def.name },
+    };
+    const required = ['type'];
+    const description = getPartialDescription(def);
+    for (const [fieldName, zodType] of getSchemaEntries(def.schema)) {
+        const { baseType, isArray, isOptional, enumValues, description: fieldDescription, } = getZodFieldInfo(zodType);
+        const jsonType = baseType === 'number' ? 'number' : baseType;
+        if (isArray) {
+            const items = { type: jsonType };
+            if (enumValues && enumValues.length > 0) {
+                items.enum = enumValues;
+            }
+            properties[fieldName] = {
+                type: 'array',
+                items,
+            };
+        }
+        else {
+            const fieldSchema = { type: jsonType };
+            if (enumValues && enumValues.length > 0) {
+                fieldSchema.enum = enumValues;
+            }
+            properties[fieldName] = fieldSchema;
+        }
+        if (fieldDescription) {
+            properties[fieldName].description = fieldDescription;
+        }
+        if (!isOptional) {
+            required.push(fieldName);
+        }
+    }
+    return {
+        type: 'object',
+        properties,
+        required,
+        additionalProperties: false,
+        ...(description ? { description } : {}),
+    };
+}
+/**
+ * Generate full JSON Schema for a registry
+ */
+export function generateJsonSchema(reg) {
+    const definitions = {};
+    const metadata = {};
+    for (const partial of reg.partials) {
+        definitions[partial.name] = partialToJsonSchema(partial);
+        metadata[partial.name] = {
+            repeatable: partial.options.repeatable ?? false,
+            alwaysSample: partial.options.alwaysSample ?? false,
+        };
+    }
+    // Generate registry schema showing the structure of a wide event log
+    const registryProperties = {};
+    for (const partial of reg.partials) {
+        const isRepeatable = partial.options.repeatable ?? false;
+        if (isRepeatable) {
+            registryProperties[partial.name] = {
+                type: 'array',
+                items: { $ref: `#/definitions/${partial.name}` },
+            };
+        }
+        else {
+            registryProperties[partial.name] = {
+                $ref: `#/definitions/${partial.name}`,
+            };
+        }
+    }
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: 'sloplog-partials',
+        definitions,
+        metadata,
+        registry: {
+            type: 'object',
+            description: 'Structure of partial fields in a wide event log',
+            properties: registryProperties,
+            additionalProperties: false,
+        },
+    };
+}
+/**
+ * Convert string to PascalCase
+ */
+function pascalCase(str) {
+    return str
+        .split(/[-_]/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join('');
+}
+/**
+ * Convert camelCase to snake_case
+ */
+function toSnakeCase(str) {
+    return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+/**
+ * Generate TypeScript types for a registry
+ */
+export function generateTypeScript(reg) {
+    const lines = [
+        '// Auto-generated by sloplog codegen - DO NOT EDIT',
+        '// Source: sloplog registry',
+        '',
+        'import type { EventPartial, PartialMetadata } from "../index"',
+        '',
+    ];
+    for (const partial of reg.partials) {
+        const interfaceName = pascalCase(partial.name) + 'Partial';
+        const partialDescription = getPartialDescription(partial);
+        if (partialDescription) {
+            lines.push(`/** ${partialDescription} */`);
+        }
+        lines.push(`export interface ${interfaceName} extends EventPartial<"${partial.name}"> {`);
+        lines.push(`    type: "${partial.name}"`);
+        for (const [fieldName, zodType] of getSchemaEntries(partial.schema)) {
+            const { baseType, isArray, isOptional, enumValues, description: fieldDescription, } = getZodFieldInfo(zodType);
+            const enumType = enumValues?.length
+                ? enumValues.map((value) => JSON.stringify(value)).join(' | ')
+                : baseType;
+            const needsParens = isArray && enumValues && enumValues.length > 1;
+            const fullType = isArray ? (needsParens ? `(${enumType})[]` : `${enumType}[]`) : enumType;
+            const optionalMarker = isOptional ? '?' : '';
+            if (fieldDescription) {
+                lines.push(`    /** ${fieldDescription} */`);
+            }
+            lines.push(`    ${fieldName}${optionalMarker}: ${fullType}`);
+        }
+        lines.push('}');
+        lines.push('');
+    }
+    // Generate the registry type - repeatable partials become arrays
+    lines.push('// Registry type combining all partials');
+    lines.push('// Repeatable partials are typed as arrays');
+    lines.push('export type GeneratedRegistry = {');
+    for (const partial of reg.partials) {
+        const interfaceName = pascalCase(partial.name) + 'Partial';
+        const isRepeatable = partial.options.repeatable ?? false;
+        const registryType = isRepeatable ? `${interfaceName}[]` : interfaceName;
+        lines.push(`    ${partial.name}: ${registryType}`);
+    }
+    lines.push('}');
+    lines.push('');
+    // Export partial names as a union
+    const partialNames = reg.partials.map((p) => `"${p.name}"`).join(' | ');
+    lines.push(`export type PartialName = ${partialNames || 'never'}`);
+    lines.push('');
+    // Export repeatable partial names
+    const repeatableNames = reg.partials
+        .filter((p) => p.options.repeatable)
+        .map((p) => `"${p.name}"`)
+        .join(' | ');
+    lines.push(`export type RepeatablePartialName = ${repeatableNames || 'never'}`);
+    lines.push('');
+    // Export alwaysSample partial names
+    const alwaysSampleNames = reg.partials
+        .filter((p) => p.options.alwaysSample)
+        .map((p) => `"${p.name}"`)
+        .join(' | ');
+    lines.push(`export type AlwaysSamplePartialName = ${alwaysSampleNames || 'never'}`);
+    lines.push('');
+    // Generate partial metadata constant for runtime use
+    lines.push('// Runtime metadata for partials');
+    lines.push('export const partialMetadata: Map<string, PartialMetadata> = new Map([');
+    for (const partial of reg.partials) {
+        const repeatable = partial.options.repeatable ?? false;
+        const alwaysSample = partial.options.alwaysSample ?? false;
+        lines.push(`    ["${partial.name}", { repeatable: ${repeatable}, alwaysSample: ${alwaysSample} }],`);
+    }
+    lines.push(']);');
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Convert Zod type to Python type annotation
+ */
+function zodFieldInfoToPython(info) {
+    const { baseType, isArray, enumValues } = info;
+    if (enumValues && enumValues.length > 0) {
+        const literalType = `Literal[${enumValues.map((v) => JSON.stringify(v)).join(', ')}]`;
+        return {
+            type: isArray ? `list[${literalType}]` : literalType,
+            needsLiteral: true,
+        };
+    }
+    let pyType;
+    switch (baseType) {
+        case 'string':
+            pyType = 'str';
+            break;
+        case 'number':
+            pyType = 'float';
+            break;
+        case 'boolean':
+            pyType = 'bool';
+            break;
+    }
+    return { type: isArray ? `list[${pyType}]` : pyType, needsLiteral: false };
+}
+/**
+ * Generate Python TypedDicts for a registry
+ */
+export function generatePython(reg) {
+    const typingImports = ['TypedDict'];
+    const needsLiteral = reg.partials.some((partial) => getSchemaEntries(partial.schema).some(([, zodType]) => getZodFieldInfo(zodType).enumValues?.length));
+    if (needsLiteral) {
+        typingImports.push('Literal');
+    }
+    if (reg.partials.length > 0) {
+        typingImports.push('Union');
+    }
+    else {
+        typingImports.push('Never');
+    }
+    const lines = [
+        '# Auto-generated by sloplog codegen - DO NOT EDIT',
+        '# Source: sloplog registry',
+        '',
+        `from typing import ${typingImports.join(', ')}`,
+        '',
+    ];
+    for (const partial of reg.partials) {
+        const className = pascalCase(partial.name) + 'Partial';
+        const entries = getSchemaEntries(partial.schema);
+        const partialDescription = getPartialDescription(partial);
+        const hasOptional = entries.some(([_, zodType]) => getZodFieldInfo(zodType).isOptional);
+        if (hasOptional) {
+            const requiredFields = entries.filter(([_, zodType]) => !getZodFieldInfo(zodType).isOptional);
+            const optionalFields = entries.filter(([_, zodType]) => getZodFieldInfo(zodType).isOptional);
+            if (requiredFields.length > 0) {
+                lines.push(`class _${className}Required(TypedDict):`);
+                lines.push(`    """Required fields for ${partial.name} partial"""`);
+                lines.push(`    type: str  # Literal["${partial.name}"]`);
+                for (const [fieldName, zodType] of requiredFields) {
+                    const info = getZodFieldInfo(zodType);
+                    const { type: pyType } = zodFieldInfoToPython(info);
+                    if (info.description) {
+                        lines.push(`    # ${info.description}`);
+                    }
+                    lines.push(`    ${toSnakeCase(fieldName)}: ${pyType}`);
+                }
+                lines.push('');
+                lines.push(`class ${className}(_${className}Required, total=False):`);
+                lines.push(`    """${partialDescription ?? `${pascalCase(partial.name)} event partial`}"""`);
+                for (const [fieldName, zodType] of optionalFields) {
+                    const info = getZodFieldInfo(zodType);
+                    const { type: pyType } = zodFieldInfoToPython(info);
+                    if (info.description) {
+                        lines.push(`    # ${info.description}`);
+                    }
+                    lines.push(`    ${toSnakeCase(fieldName)}: ${pyType}`);
+                }
+            }
+            else {
+                lines.push(`class ${className}(TypedDict, total=False):`);
+                lines.push(`    """${partialDescription ?? `${pascalCase(partial.name)} event partial`}"""`);
+                lines.push(`    type: str  # Literal["${partial.name}"] - required`);
+                for (const [fieldName, zodType] of optionalFields) {
+                    const info = getZodFieldInfo(zodType);
+                    const { type: pyType } = zodFieldInfoToPython(info);
+                    if (info.description) {
+                        lines.push(`    # ${info.description}`);
+                    }
+                    lines.push(`    ${toSnakeCase(fieldName)}: ${pyType}`);
+                }
+            }
+        }
+        else {
+            lines.push(`class ${className}(TypedDict):`);
+            lines.push(`    """${partialDescription ?? `${pascalCase(partial.name)} event partial`}"""`);
+            lines.push(`    type: str  # Literal["${partial.name}"]`);
+            for (const [fieldName, zodType] of entries) {
+                const info = getZodFieldInfo(zodType);
+                const { type: pyType } = zodFieldInfoToPython(info);
+                if (info.description) {
+                    lines.push(`    # ${info.description}`);
+                }
+                lines.push(`    ${toSnakeCase(fieldName)}: ${pyType}`);
+            }
+        }
+        lines.push('');
+    }
+    // Generate union type for all partials
+    const partialTypes = reg.partials.map((p) => pascalCase(p.name) + 'Partial');
+    lines.push('# Union of all partial types');
+    if (partialTypes.length > 0) {
+        lines.push(`GeneratedPartial = Union[${partialTypes.join(', ')}]`);
+    }
+    else {
+        lines.push('GeneratedPartial = Never');
+    }
+    lines.push('');
+    // Generate registry type - repeatable partials become lists
+    lines.push('# Registry mapping partial names to their types');
+    lines.push('# Repeatable partials are typed as lists');
+    lines.push('class GeneratedRegistry(TypedDict):');
+    lines.push('    """Type-safe registry of all event partials"""');
+    for (const partial of reg.partials) {
+        const className = pascalCase(partial.name) + 'Partial';
+        const isRepeatable = partial.options.repeatable ?? false;
+        const registryType = isRepeatable ? `list[${className}]` : className;
+        lines.push(`    ${partial.name}: ${registryType}`);
+    }
+    lines.push('');
+    // Generate PartialMetadata TypedDict
+    lines.push('class PartialMetadata(TypedDict):');
+    lines.push('    """Metadata about a partial type"""');
+    lines.push('    repeatable: bool');
+    lines.push('    always_sample: bool');
+    lines.push('');
+    // Generate partial metadata dict for runtime use
+    lines.push('# Runtime metadata for partials');
+    lines.push('PARTIAL_METADATA: dict[str, PartialMetadata] = {');
+    for (const partial of reg.partials) {
+        const repeatable = partial.options.repeatable ?? false;
+        const alwaysSample = partial.options.alwaysSample ?? false;
+        lines.push(`    "${partial.name}": {"repeatable": ${repeatable ? 'True' : 'False'}, "always_sample": ${alwaysSample ? 'True' : 'False'}},`);
+    }
+    lines.push('}');
+    lines.push('');
+    // Export list
+    lines.push('__all__ = [');
+    for (const partial of reg.partials) {
+        lines.push(`    "${pascalCase(partial.name)}Partial",`);
+    }
+    lines.push('    "GeneratedPartial",');
+    lines.push('    "GeneratedRegistry",');
+    lines.push('    "PartialMetadata",');
+    lines.push('    "PARTIAL_METADATA",');
+    lines.push(']');
+    lines.push('');
+    return lines.join('\n');
+}
+function resolveOutputs(outputs) {
+    const defaults = { python: 'sloplog.py', jsonschema: 'sloplog.json' };
+    if (!outputs) {
+        return defaults;
+    }
+    if (Array.isArray(outputs)) {
+        return {
+            python: outputs.includes('python') ? defaults.python : undefined,
+            jsonschema: outputs.includes('jsonschema') ? defaults.jsonschema : undefined,
+        };
+    }
+    const resolved = {};
+    if (outputs.python !== undefined) {
+        resolved.python = outputs.python === false ? undefined : (outputs.python ?? defaults.python);
+    }
+    if (outputs.jsonschema !== undefined) {
+        resolved.jsonschema =
+            outputs.jsonschema === false ? undefined : (outputs.jsonschema ?? defaults.jsonschema);
+    }
+    return resolved;
+}
+function isRegistry(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    return Array.isArray(value.partials);
+}
+async function loadRegistry(registry, resolvePath, pathToFileURL) {
+    if (typeof registry !== 'string') {
+        if (isRegistry(registry)) {
+            return registry;
+        }
+        throw new Error('sloplog registry must include a partials array');
+    }
+    const registryPath = resolvePath(registry);
+    const module = await import(pathToFileURL(registryPath).href);
+    const resolved = (module.default || module.registry);
+    if (!resolved || !isRegistry(resolved)) {
+        throw new Error('sloplog registry file must export a registry created with registry()');
+    }
+    return resolved;
+}
+/**
+ * Generate outputs from a sloplog registry (Python + JSON schema).
+ */
+export async function config(config) {
+    const [{ mkdir, writeFile }, pathModule, urlModule] = await Promise.all([
+        import('node:fs/promises'),
+        import('node:path'),
+        import('node:url'),
+    ]);
+    const { resolve, dirname, isAbsolute } = pathModule;
+    const { pathToFileURL } = urlModule;
+    const registry = await loadRegistry(config.registry, resolve, pathToFileURL);
+    const outDir = resolve(config.outDir ?? './generated');
+    const outputs = resolveOutputs(config.outputs);
+    const result = {};
+    if (outputs.python) {
+        const code = generatePython(registry);
+        const outputPath = isAbsolute(outputs.python)
+            ? outputs.python
+            : resolve(outDir, outputs.python);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, `${code}\n`, 'utf8');
+        result.python = { path: outputPath, code };
+    }
+    if (outputs.jsonschema) {
+        const schema = generateJsonSchema(registry);
+        const code = `${JSON.stringify(schema, null, 2)}\n`;
+        const outputPath = isAbsolute(outputs.jsonschema)
+            ? outputs.jsonschema
+            : resolve(outDir, outputs.jsonschema);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, code, 'utf8');
+        result.jsonschema = { path: outputPath, code };
+    }
+    return result;
+}

package/dist/collectors/betterstack.d.ts

@@ -0,0 +1,47 @@
+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>[];
+/**
+ * Options for BetterStackCollector
+ */
+export interface BetterStackCollectorOptions {
+    /** BetterStack source token */
+    sourceToken: string;
+    /** Ingesting host (default: "in.logs.betterstack.com") */
+    host?: string;
+    /** Number of events to buffer before flushing (default: 10) */
+    bufferSize?: number;
+    /** Maximum time in ms to wait before flushing buffer (default: 5000) */
+    flushIntervalMs?: number;
+    /** Custom fetch implementation (for testing or custom environments) */
+    fetch?: typeof fetch;
+}
+/**
+ * Collector that sends events to BetterStack Logs via HTTP API
+ * https://betterstack.com/docs/logs/ingesting-data/http/logs/
+ */
+export declare class BetterStackCollector implements LogCollectorClient {
+    private buffer;
+    private bufferSize;
+    private flushIntervalMs;
+    private flushTimer;
+    private sourceToken;
+    private host;
+    private fetchFn;
+    constructor(options: BetterStackCollectorOptions);
+    flush(event: WideEventBase, partials: Map<string, PartialValue>, _options: FlushOptions): Promise<void>;
+    /**
+     * Flush the buffer to BetterStack
+     */
+    flushBuffer(): Promise<void>;
+    /**
+     * Force flush any remaining buffered events (call on shutdown)
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a collector that sends events to BetterStack Logs.
+ */
+export declare function betterStackCollector(options: BetterStackCollectorOptions): BetterStackCollector;
+export {};

package/dist/collectors/betterstack.js

@@ -0,0 +1,74 @@
+/**
+ * Collector that sends events to BetterStack Logs via HTTP API
+ * https://betterstack.com/docs/logs/ingesting-data/http/logs/
+ */
+export class BetterStackCollector {
+    buffer = [];
+    bufferSize;
+    flushIntervalMs;
+    flushTimer = null;
+    sourceToken;
+    host;
+    fetchFn;
+    constructor(options) {
+        this.sourceToken = options.sourceToken;
+        this.host = options.host ?? 'in.logs.betterstack.com';
+        this.bufferSize = options.bufferSize ?? 10;
+        this.flushIntervalMs = options.flushIntervalMs ?? 5000;
+        this.fetchFn = options.fetch ?? fetch;
+    }
+    async flush(event, partials, _options) {
+        const partialsObj = {};
+        for (const [key, value] of partials) {
+            partialsObj[key] = value;
+        }
+        const logEntry = {
+            dt: new Date().toISOString(),
+            ...event,
+            ...partialsObj,
+        };
+        this.buffer.push(logEntry);
+        // 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 BetterStack
+     */
+    async flushBuffer() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.buffer.length === 0) {
+            return;
+        }
+        const batch = this.buffer;
+        this.buffer = [];
+        await this.fetchFn(`https://${this.host}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.sourceToken}`,
+            },
+            body: JSON.stringify(batch),
+        });
+    }
+    /**
+     * Force flush any remaining buffered events (call on shutdown)
+     */
+    async close() {
+        await this.flushBuffer();
+    }
+}
+/**
+ * Create a collector that sends events to BetterStack Logs.
+ */
+export function betterStackCollector(options) {
+    return new BetterStackCollector(options);
+}

package/dist/collectors/composite.d.ts

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

package/dist/collectors/composite.js

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

package/dist/collectors/file.d.ts

@@ -0,0 +1 @@
+export { FileCollector, fileCollector, type FileCollectorOptions, type FileSystem, } from './index.js';

package/dist/collectors/file.js

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

package/dist/collectors/filtered.d.ts

@@ -0,0 +1 @@
+export { FilteredCollector, filteredCollector, type EventFilter } from './index.js';

package/dist/collectors/filtered.js

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