logquill 0.2.0 → 0.4.0

package/dist/logger-D1_THnBJ.d.cts

@@ -0,0 +1,163 @@
+/** 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;
+
+/** 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;
+}
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    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;
+}
+
+/** Options for `Logger.span()`. Any extra keys become the span's own `meta`. */
+interface SpanOptions extends Record<string, unknown> {
+    /** Adopt an id handed in from elsewhere (e.g. a framework's own run id) instead of generating one. */
+    spanId?: string;
+    /** Adopt a parent id explicitly, overriding auto-nesting from an enclosing `span()` block. */
+    parentSpanId?: string;
+}
+interface LoggerOptions {
+    level?: LevelInput;
+    transports?: Transport[];
+    plugins?: (Plugin | MiddlewareFunc)[];
+    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, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): 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;
+    /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+    thought(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+    action(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+    observation(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+    decision(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /**
+     * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+     * settling (success or throw) emits one record for the span itself
+     * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+     * inside `fn` — through any method, and through any further `await` —
+     * is automatically stamped with `meta.parentSpanId` pointing at this
+     * span, so nested/sub-agent calls reconstruct their exact nesting when
+     * sorted by `spanId`/`parentSpanId`.
+     *
+     * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+     * throws; the error itself propagates unchanged to the caller.
+     *
+     * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+     * `options` to adopt an id handed in from elsewhere (e.g. a framework
+     * adapter translating an id it already received).
+     */
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    private finishSpan;
+}
+
+export { CollectingTransport as C, type Formatter as F, JSONFormatter as J, type LogRecord as L, type MiddlewareFunc as M, type Plugin as P, type SpanOptions as S, Transport as T, Level as a, type LevelInput as b, FunctionPlugin as c, Logger as d, type LoggerOptions as e, createRecord as f, levelName as l, parseLevel as p, utcTimestamp as u };

package/dist/logger-D1_THnBJ.d.ts

@@ -0,0 +1,163 @@
+/** 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;
+
+/** 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;
+}
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    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;
+}
+
+/** Options for `Logger.span()`. Any extra keys become the span's own `meta`. */
+interface SpanOptions extends Record<string, unknown> {
+    /** Adopt an id handed in from elsewhere (e.g. a framework's own run id) instead of generating one. */
+    spanId?: string;
+    /** Adopt a parent id explicitly, overriding auto-nesting from an enclosing `span()` block. */
+    parentSpanId?: string;
+}
+interface LoggerOptions {
+    level?: LevelInput;
+    transports?: Transport[];
+    plugins?: (Plugin | MiddlewareFunc)[];
+    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, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): 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;
+    /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+    thought(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+    action(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+    observation(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+    decision(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /**
+     * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+     * settling (success or throw) emits one record for the span itself
+     * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+     * inside `fn` — through any method, and through any further `await` —
+     * is automatically stamped with `meta.parentSpanId` pointing at this
+     * span, so nested/sub-agent calls reconstruct their exact nesting when
+     * sorted by `spanId`/`parentSpanId`.
+     *
+     * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+     * throws; the error itself propagates unchanged to the caller.
+     *
+     * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+     * `options` to adopt an id handed in from elsewhere (e.g. a framework
+     * adapter translating an id it already received).
+     */
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    private finishSpan;
+}
+
+export { CollectingTransport as C, type Formatter as F, JSONFormatter as J, type LogRecord as L, type MiddlewareFunc as M, type Plugin as P, type SpanOptions as S, Transport as T, Level as a, type LevelInput as b, FunctionPlugin as c, Logger as d, type LoggerOptions as e, createRecord as f, levelName as l, parseLevel as p, utcTimestamp as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "logquill",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A logging framework with an identical mental model and JSON log shape across Node/TypeScript and Python.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.mjs",
+      "require": "./dist/langchain.cjs"
     }
   },
   "files": [
@@ -22,20 +27,25 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "pg": "^8.11.0",
-    "mysql2": "^3.9.0",
-    "mongodb": "^6.0.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.0.0",
+    "@langchain/core": "^1.0.0",
     "@aws-sdk/client-dynamodb": "^3.0.0",
-    "redis": "^4.6.0 || ^5.0.0",
-    "kafkajs": "^2.2.0",
-    "amqplib": "^0.10.0",
     "@aws-sdk/client-sqs": "^3.600.0",
-    "@google-cloud/pubsub": "^4.0.0",
-    "@aws-sdk/client-cloudwatch-logs": "^3.0.0",
     "@google-cloud/logging": "^11.0.0",
-    "applicationinsights": "^3.0.0"
+    "@google-cloud/pubsub": "^4.0.0",
+    "amqplib": "^0.10.0",
+    "applicationinsights": "^3.0.0",
+    "kafkajs": "^2.2.0",
+    "mongodb": "^6.0.0",
+    "mysql2": "^3.9.0",
+    "nodemailer": "^6.9.0",
+    "pg": "^8.11.0",
+    "redis": "^4.6.0 || ^5.0.0"
   },
   "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -71,6 +81,9 @@
     },
     "applicationinsights": {
       "optional": true
+    },
+    "nodemailer": {
+      "optional": true
     }
   },
   "repository": {
@@ -104,6 +117,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@langchain/core": "^1.2.9",
     "@types/node": "^26.4.0",
     "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^10.9.1",