logquill 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -1,3 +1,209 @@
-declare const VERSION = "0.1.0";
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    TRACE = 5,
+    DEBUG = 10,
+    INFO = 20,
+    WARN = 30,
+    ERROR = 40,
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
 
-export { VERSION };
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    timestamp: string;
+    level: string;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+declare const DEFAULT_REDACTED_KEYS: readonly string[];
+interface RedactPluginOptions {
+    keys?: readonly string[];
+    replacement?: string;
+}
+/** Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder. */
+declare class RedactPlugin implements Plugin {
+    private readonly keys;
+    readonly replacement: string;
+    constructor(options?: RedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+interface SamplingPluginOptions {
+    rng?: () => number;
+}
+/** Keeps roughly `rate` of records (0.0-1.0), dropping the rest. */
+declare class SamplingPlugin implements Plugin {
+    readonly rate: number;
+    private readonly rng;
+    constructor(rate: number, options?: SamplingPluginOptions);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    format(record: LogRecord): string;
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    readonly formatted: string[];
+    readonly records: LogRecord[];
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+/** The subset of `console` this transport needs — swap in a fake for tests. */
+interface ConsoleLike {
+    log(message: string): void;
+    error(message: string): void;
+}
+interface ConsoleTransportOptions {
+    formatter?: Formatter;
+    colorize?: boolean;
+    console?: ConsoleLike;
+}
+/**
+ * Writes to `console.log`, routing ERROR/FATAL to `console.error`, colorized by
+ * level. Uses the global `console` rather than Node's `process.stdout`/`stderr`
+ * so this transport works unmodified in a browser bundle.
+ */
+declare class ConsoleTransport extends Transport {
+    colorize: boolean;
+    private readonly out;
+    constructor(options?: ConsoleTransportOptions);
+    write(formatted: string, record: LogRecord): void;
+    private applyColor;
+}
+
+interface FileTransportOptions {
+    formatter?: Formatter;
+    maxBytes?: number;
+    backupCount?: number;
+}
+/** Appends formatted records to a file, rotating when it exceeds `maxBytes`. */
+declare class FileTransport extends Transport {
+    readonly path: string;
+    readonly maxBytes: number;
+    readonly backupCount: number;
+    private fd;
+    constructor(path: string, options?: FileTransportOptions);
+    write(formatted: string): void;
+    private rotate;
+    close(): void;
+}
+
+/** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
+type Sender = (url: string, batch: readonly string[]) => Promise<void> | void;
+interface HTTPTransportOptions {
+    formatter?: Formatter;
+    batchSize?: number;
+    sender?: Sender;
+}
+/**
+ * Batches formatted records and POSTs them as newline-delimited JSON via `fetch`.
+ * Pass `sender` to swap in a fake for tests, or a different backend.
+ */
+declare class HTTPTransport extends Transport {
+    readonly url: string;
+    readonly batchSize: number;
+    private readonly sender;
+    private batch;
+    constructor(url: string, options?: HTTPTransportOptions);
+    write(formatted: string): void;
+    /** Send the current batch now, even if it hasn't reached `batchSize`. */
+    flush(): void;
+    close(): void;
+}
+
+interface LoggerOptions {
+    level?: LevelInput;
+    transports?: Transport[];
+    plugins?: Plugin[];
+    meta?: Record<string, unknown>;
+}
+declare class Logger {
+    readonly name: string;
+    readonly transports: Transport[];
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    constructor(name: string, options?: LoggerOptions);
+    get level(): Level;
+    setLevel(level: LevelInput): void;
+    /** Register a plugin. Returns `this` so calls can be chained. */
+    use(plugin: Plugin): this;
+    /** Close every attached transport. Call on shutdown to flush buffered writes. */
+    close(): void;
+    /** A logger scoped under this one, inheriting its level, transports, and plugins. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+}
+
+declare const VERSION = "0.1.2";
+
+export { CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_REDACTED_KEYS, FileTransport, type FileTransportOptions, type Formatter, HTTPTransport, type HTTPTransportOptions, JSONFormatter, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type Plugin, RedactPlugin, type RedactPluginOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };

package/dist/index.d.ts

@@ -1,3 +1,209 @@
-declare const VERSION = "0.1.0";
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    TRACE = 5,
+    DEBUG = 10,
+    INFO = 20,
+    WARN = 30,
+    ERROR = 40,
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
 
-export { VERSION };
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    timestamp: string;
+    level: string;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+
+/**
+ * Injects fixed key/value pairs into every record's `meta`.
+ * A value already present in a record's own `meta` wins over the fixed context.
+ */
+declare class ContextPlugin implements Plugin {
+    readonly context: Record<string, unknown>;
+    constructor(context: Record<string, unknown>);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+declare const DEFAULT_REDACTED_KEYS: readonly string[];
+interface RedactPluginOptions {
+    keys?: readonly string[];
+    replacement?: string;
+}
+/** Replaces sensitive `meta` values, matched by key (case-insensitive), with a placeholder. */
+declare class RedactPlugin implements Plugin {
+    private readonly keys;
+    readonly replacement: string;
+    constructor(options?: RedactPluginOptions);
+    beforeLog(record: LogRecord): LogRecord;
+}
+
+interface SamplingPluginOptions {
+    rng?: () => number;
+}
+/** Keeps roughly `rate` of records (0.0-1.0), dropping the rest. */
+declare class SamplingPlugin implements Plugin {
+    readonly rate: number;
+    private readonly rng;
+    constructor(rate: number, options?: SamplingPluginOptions);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    format(record: LogRecord): string;
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    readonly formatted: string[];
+    readonly records: LogRecord[];
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+/** The subset of `console` this transport needs — swap in a fake for tests. */
+interface ConsoleLike {
+    log(message: string): void;
+    error(message: string): void;
+}
+interface ConsoleTransportOptions {
+    formatter?: Formatter;
+    colorize?: boolean;
+    console?: ConsoleLike;
+}
+/**
+ * Writes to `console.log`, routing ERROR/FATAL to `console.error`, colorized by
+ * level. Uses the global `console` rather than Node's `process.stdout`/`stderr`
+ * so this transport works unmodified in a browser bundle.
+ */
+declare class ConsoleTransport extends Transport {
+    colorize: boolean;
+    private readonly out;
+    constructor(options?: ConsoleTransportOptions);
+    write(formatted: string, record: LogRecord): void;
+    private applyColor;
+}
+
+interface FileTransportOptions {
+    formatter?: Formatter;
+    maxBytes?: number;
+    backupCount?: number;
+}
+/** Appends formatted records to a file, rotating when it exceeds `maxBytes`. */
+declare class FileTransport extends Transport {
+    readonly path: string;
+    readonly maxBytes: number;
+    readonly backupCount: number;
+    private fd;
+    constructor(path: string, options?: FileTransportOptions);
+    write(formatted: string): void;
+    private rotate;
+    close(): void;
+}
+
+/** Sends one batch of formatted lines to `url`. Swap in a fake for tests. */
+type Sender = (url: string, batch: readonly string[]) => Promise<void> | void;
+interface HTTPTransportOptions {
+    formatter?: Formatter;
+    batchSize?: number;
+    sender?: Sender;
+}
+/**
+ * Batches formatted records and POSTs them as newline-delimited JSON via `fetch`.
+ * Pass `sender` to swap in a fake for tests, or a different backend.
+ */
+declare class HTTPTransport extends Transport {
+    readonly url: string;
+    readonly batchSize: number;
+    private readonly sender;
+    private batch;
+    constructor(url: string, options?: HTTPTransportOptions);
+    write(formatted: string): void;
+    /** Send the current batch now, even if it hasn't reached `batchSize`. */
+    flush(): void;
+    close(): void;
+}
+
+interface LoggerOptions {
+    level?: LevelInput;
+    transports?: Transport[];
+    plugins?: Plugin[];
+    meta?: Record<string, unknown>;
+}
+declare class Logger {
+    readonly name: string;
+    readonly transports: Transport[];
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    constructor(name: string, options?: LoggerOptions);
+    get level(): Level;
+    setLevel(level: LevelInput): void;
+    /** Register a plugin. Returns `this` so calls can be chained. */
+    use(plugin: Plugin): this;
+    /** Close every attached transport. Call on shutdown to flush buffered writes. */
+    close(): void;
+    /** A logger scoped under this one, inheriting its level, transports, and plugins. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+}
+
+declare const VERSION = "0.1.2";
+
+export { CollectingTransport, type ConsoleLike, ConsoleTransport, type ConsoleTransportOptions, ContextPlugin, DEFAULT_REDACTED_KEYS, FileTransport, type FileTransportOptions, type Formatter, HTTPTransport, type HTTPTransportOptions, JSONFormatter, Level, type LevelInput, type LogRecord, Logger, type LoggerOptions, type Plugin, RedactPlugin, type RedactPluginOptions, SamplingPlugin, type SamplingPluginOptions, type Sender, Transport, VERSION, createRecord, levelName, parseLevel, utcTimestamp };