@cleverbrush/log 0.0.0-beta-20260424142030

package/dist/sinks/BatchingSink.d.ts

@@ -0,0 +1,45 @@
+import type { LogEvent } from '../LogEvent.js';
+import type { LogSink } from '../Sink.js';
+/**
+ * Configuration for the batching sink wrapper.
+ */
+export interface BatchingSinkOptions {
+    /** Flush after this many events. @default 100 */
+    batchSize?: number;
+    /** Flush after this many milliseconds of inactivity. @default 2000 */
+    flushInterval?: number;
+    /** Maximum buffered events before dropping. @default 50000 */
+    maxQueueSize?: number;
+    /** Maximum retry attempts for failed flushes. @default 5 */
+    maxRetries?: number;
+    /** Initial retry delay in ms (exponential backoff). @default 1000 */
+    retryDelay?: number;
+    /** Consecutive failures before circuit breaker opens. @default 3 */
+    circuitBreakerThreshold?: number;
+    /** The emit function that writes a batch to the target. */
+    emit: (batch: LogEvent[]) => Promise<void>;
+}
+/**
+ * Production-grade batching wrapper for log sinks.
+ *
+ * Provides buffering, retry with exponential backoff, and circuit
+ * breaking. All network/file sinks use this internally.
+ *
+ * @example
+ * ```ts
+ * const sink = new BatchingSink({
+ *     batchSize: 100,
+ *     flushInterval: 2000,
+ *     emit: async (batch) => {
+ *         await fetch('/logs', { method: 'POST', body: JSON.stringify(batch) });
+ *     },
+ * });
+ * ```
+ */
+export declare class BatchingSink implements LogSink {
+    #private;
+    constructor(options: BatchingSinkOptions);
+    emit(events: LogEvent[]): Promise<void>;
+    flush(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/sinks/ClickHouseSink.d.ts

@@ -0,0 +1,78 @@
+import type { LogSink } from '../Sink.js';
+/**
+ * Column mapping for the ClickHouse logs table.
+ */
+export interface ClickHouseColumnMapping {
+    timestamp?: string;
+    level?: string;
+    messageTemplate?: string;
+    renderedMessage?: string;
+    properties?: string;
+    exception?: string;
+    correlationId?: string;
+    traceId?: string;
+    spanId?: string;
+    sourceContext?: string;
+}
+/**
+ * ClickHouse sink configuration.
+ */
+export interface ClickHouseSinkOptions {
+    /** Knex-ClickHouse connection instance. */
+    connection: any;
+    /** Table name to insert into. */
+    table: string;
+    /** Events per batch. @default 1000 */
+    batchSize?: number;
+    /** Max milliseconds between flushes. @default 5000 */
+    flushInterval?: number;
+    /** Custom column mapping. */
+    columns?: ClickHouseColumnMapping;
+}
+/**
+ * Options for creating the ClickHouse logs table.
+ */
+export interface CreateLogsTableOptions {
+    /** Table engine. @default 'MergeTree' */
+    engine?: string;
+    /** Partition expression. @default "toYYYYMM(timestamp)" */
+    partitionBy?: string;
+    /** ORDER BY columns. @default ['timestamp', 'level'] */
+    orderBy?: string[];
+    /** TTL expression for automatic data expiration. */
+    ttl?: string;
+}
+/**
+ * Creates the ClickHouse logs table with a recommended schema.
+ *
+ * @param connection - knex-clickhouse connection
+ * @param tableName - name for the logs table
+ * @param options - DDL options (engine, partitioning, TTL)
+ *
+ * @example
+ * ```ts
+ * await createLogsTable(ch, 'application_logs', {
+ *     ttl: 'timestamp + INTERVAL 90 DAY',
+ * });
+ * ```
+ */
+export declare function createLogsTable(connection: any, tableName: string, options?: CreateLogsTableOptions): Promise<void>;
+/**
+ * Creates a ClickHouse sink that batch inserts log events.
+ *
+ * Ships as a separate entrypoint (`@cleverbrush/log/clickhouse`) to
+ * avoid forcing `@cleverbrush/knex-clickhouse` as a dependency.
+ *
+ * @param options - ClickHouse connection and batching configuration
+ * @returns a `LogSink` that batch inserts into ClickHouse
+ *
+ * @example
+ * ```ts
+ * const sink = clickHouseSink({
+ *     connection: ch,
+ *     table: 'application_logs',
+ *     batchSize: 1000,
+ * });
+ * ```
+ */
+export declare function clickHouseSink(options: ClickHouseSinkOptions): LogSink;

package/dist/sinks/ConsoleSink.d.ts

@@ -0,0 +1,29 @@
+import { type LogLevelName } from '../LogLevel.js';
+import type { LogSink } from '../Sink.js';
+/**
+ * Console sink configuration.
+ */
+export interface ConsoleSinkOptions {
+    /** Output mode: `'pretty'` for colored human-readable, `'json'` for CLEF. @default 'pretty' */
+    mode?: 'pretty' | 'json';
+    /** Color theme for pretty mode. @default 'dark' */
+    theme?: 'dark' | 'light' | 'none';
+    /** Minimum level for this sink. @default undefined (uses pipeline level) */
+    minimumLevel?: LogLevelName;
+}
+/**
+ * Creates a console sink for log output.
+ *
+ * Supports two modes:
+ * - `'pretty'` — colored, human-readable output (default for development)
+ * - `'json'` — CLEF JSON output (for production / container logs)
+ *
+ * @param options - console sink configuration
+ * @returns a `LogSink` that writes to stdout/stderr
+ *
+ * @example
+ * ```ts
+ * const sink = consoleSink({ theme: 'dark', minimumLevel: 'debug' });
+ * ```
+ */
+export declare function consoleSink(options?: ConsoleSinkOptions): LogSink;

package/dist/sinks/FileSink.d.ts

@@ -0,0 +1,43 @@
+import { type LogLevelName } from '../LogLevel.js';
+import type { LogSink } from '../Sink.js';
+/**
+ * File rotation configuration.
+ */
+export interface RotationOptions {
+    /** Rotation strategy. */
+    strategy: 'size' | 'time' | 'hybrid';
+    /** Time-based rotation interval (for `'time'` and `'hybrid'`). */
+    interval?: 'hourly' | 'daily';
+    /** Maximum file size in bytes before rotation (for `'size'` and `'hybrid'`). */
+    maxBytes?: number;
+    /** Number of rotated files to retain. @default 10 */
+    retainCount?: number;
+}
+/**
+ * File sink configuration.
+ */
+export interface FileSinkOptions {
+    /** Path to the log file. */
+    path: string;
+    /** Minimum level for this sink. */
+    minimumLevel?: LogLevelName;
+    /** Rotation configuration. */
+    rotation?: RotationOptions;
+}
+/**
+ * Creates a file sink that writes CLEF-formatted log events.
+ *
+ * Supports size-based, time-based, and hybrid rotation strategies.
+ *
+ * @param options - file sink configuration
+ * @returns a `LogSink` that appends to a file
+ *
+ * @example
+ * ```ts
+ * const sink = fileSink({
+ *     path: './logs/app.log',
+ *     rotation: { strategy: 'time', interval: 'daily', retainCount: 30 },
+ * });
+ * ```
+ */
+export declare function fileSink(options: FileSinkOptions): LogSink;

package/dist/sinks/SeqSink.d.ts

@@ -0,0 +1,37 @@
+import type { LogSink } from '../Sink.js';
+/**
+ * Seq sink configuration.
+ */
+export interface SeqSinkOptions {
+    /** Base URL of the Seq server (e.g. `http://localhost:5341`). */
+    serverUrl: string;
+    /** Optional API key sent as `X-Seq-ApiKey` header. */
+    apiKey?: string;
+    /** Events per batch. @default 100 */
+    batchSize?: number;
+    /** Max milliseconds between flushes. @default 2000 */
+    flushInterval?: number;
+    /** Maximum retry attempts. @default 5 */
+    maxRetries?: number;
+    /** Initial retry delay in ms. @default 1000 */
+    retryDelay?: number;
+}
+/**
+ * Creates a sink that sends log events to a Seq server via HTTP in CLEF format.
+ *
+ * Events are batched and sent to `POST {serverUrl}/ingest/clef`. The sink
+ * respects Seq's `MinimumLevelAccepted` response to dynamically reduce
+ * bandwidth when the server applies level filtering.
+ *
+ * @param options - Seq connection and batching configuration
+ * @returns a `LogSink` that batches and sends events to Seq
+ *
+ * @example
+ * ```ts
+ * const sink = seqSink({
+ *     serverUrl: 'https://seq.mycompany.com',
+ *     apiKey: process.env.SEQ_API_KEY,
+ * });
+ * ```
+ */
+export declare function seqSink(options: SeqSinkOptions): LogSink;

package/dist/sinks/createSink.d.ts

@@ -0,0 +1,35 @@
+import type { LogEvent } from '../LogEvent.js';
+import { type LogLevelName } from '../LogLevel.js';
+import type { LogSink } from '../Sink.js';
+/**
+ * Configuration for a quick custom sink.
+ */
+export interface CreateSinkOptions {
+    /** Minimum level for this sink. */
+    minimumLevel?: LogLevelName;
+    /** The emit function that writes events. */
+    emit: (events: LogEvent[]) => Promise<void>;
+    /** Optional flush function. */
+    flush?: () => Promise<void>;
+    /** Optional dispose function. */
+    dispose?: () => Promise<void>;
+}
+/**
+ * Creates a simple `LogSink` from an emit function.
+ *
+ * @param options - sink configuration with emit function
+ * @returns a `LogSink` instance
+ *
+ * @example
+ * ```ts
+ * const sink = createSink({
+ *     minimumLevel: 'error',
+ *     emit: async (events) => {
+ *         for (const event of events) {
+ *             await sendAlert(event.renderedMessage);
+ *         }
+ *     },
+ * });
+ * ```
+ */
+export declare function createSink(options: CreateSinkOptions): LogSink;

package/dist/sinks/index.d.ts

@@ -0,0 +1,5 @@
+export { BatchingSink, type BatchingSinkOptions } from './BatchingSink.js';
+export { type ConsoleSinkOptions, consoleSink } from './ConsoleSink.js';
+export { type CreateSinkOptions, createSink } from './createSink.js';
+export { type FileSinkOptions, fileSink, type RotationOptions } from './FileSink.js';
+export { type SeqSinkOptions, seqSink } from './SeqSink.js';

package/dist/useLogging.d.ts

@@ -0,0 +1,35 @@
+import type { Logger } from './Logger.js';
+import { correlationIdMiddleware } from './middleware/correlationId.js';
+import { type RequestLoggingOptions, requestLoggingMiddleware } from './middleware/requestLogging.js';
+export interface UseLoggingOptions extends RequestLoggingOptions {
+    /**
+     * Header name to echo the correlation ID back on the response.
+     * Set to `false` to suppress the response header entirely — useful
+     * when an OTel `X-Trace-Id` header already serves the traceability
+     * purpose and a second ID would confuse consumers.
+     *
+     * @default 'X-Correlation-Id'
+     */
+    correlationResponseHeader?: string | false;
+}
+/**
+ * Convenience function that returns correlation ID middleware and
+ * request logging middleware, ready to spread into `ServerBuilder.use()`.
+ *
+ * @param logger - the root logger instance
+ * @param options - request logging configuration
+ * @returns an array of middleware functions
+ *
+ * @example
+ * ```ts
+ * const server = new ServerBuilder()
+ *     .use(...useLogging(logger, {
+ *         excludePaths: ['/health'],
+ *     }))
+ *     .build();
+ * ```
+ */
+export declare function useLogging(logger: Logger, options?: UseLoggingOptions): [
+    ReturnType<typeof correlationIdMiddleware>,
+    ReturnType<typeof requestLoggingMiddleware>
+];

package/package.json

@@ -0,0 +1,69 @@
+{
+    "author": "Andrew Zolotukhin <andrew_zol@cleverbrush.com>",
+    "bugs": {
+        "url": "https://github.com/cleverbrush/framework/issues",
+        "email": "andrew_zol@cleverbrush.com"
+    },
+    "description": "Enterprise structured logging — Serilog-style message templates, CLEF serialization, production sinks",
+    "files": [
+        "dist"
+    ],
+    "homepage": "https://docs.cleverbrush.com/",
+    "keywords": [
+        "logging",
+        "structured logging",
+        "serilog",
+        "clef",
+        "cleverbrush"
+    ],
+    "license": "BSD 3-Clause",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./clickhouse": {
+            "types": "./dist/clickhouse.d.ts",
+            "import": "./dist/clickhouse.js"
+        }
+    },
+    "sideEffects": false,
+    "name": "@cleverbrush/log",
+    "readme": "https://github.com/cleverbrush/framework/tree/master/libs/log#readme",
+    "repository": {
+        "type": "git",
+        "url": "github:cleverbrush/framework"
+    },
+    "scripts": {
+        "watch": "tsc --build --watch",
+        "build": "tsup && rm -f tsconfig.build.tsbuildinfo && tsc --project tsconfig.build.json --emitDeclarationOnly",
+        "clean": "rm -rf dist tsconfig.tsbuildinfo"
+    },
+    "dependencies": {
+        "@cleverbrush/schema": "0.0.0-beta-20260424142030",
+        "@cleverbrush/async": "0.0.0-beta-20260424142030"
+    },
+    "peerDependencies": {
+        "@cleverbrush/di": "0.0.0-beta-20260424142030",
+        "@cleverbrush/server": "0.0.0-beta-20260424142030",
+        "@cleverbrush/knex-clickhouse": "0.0.0-beta-20260424142030"
+    },
+    "peerDependenciesMeta": {
+        "@cleverbrush/di": {
+            "optional": true
+        },
+        "@cleverbrush/server": {
+            "optional": true
+        },
+        "@cleverbrush/knex-clickhouse": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@types/node": "^25.4.0"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "version": "0.0.0-beta-20260424142030"
+}