@vielzeug/rune 1.1.1

package/dist/types.d.ts

@@ -0,0 +1,274 @@
+export type LogType = 'debug' | 'error' | 'fatal' | 'info' | 'warn';
+export type LogLevel = LogType | 'off';
+/** Numeric priority for each level. Lower = more verbose. Exported for transport authors. */
+export declare const PRIORITY: Record<LogLevel, number>;
+/** Returns true if `level` passes the `threshold`. Returns false when `level` is 'off'. Exported for transport/middleware authors. */
+export declare function isLevelEnabled(threshold: LogLevel, level: LogLevel): boolean;
+export type Bindings = Record<string, unknown>;
+/**
+ * The structured record produced by every log call and dispatched to all transports.
+ * `data` is the merged result of pinned bindings and per-call context — transports
+ * receive a single flat object and do not need to merge anything themselves.
+ * Any `Error` instances — whether from a pinned binding (`bindings`/`withBindings()`) or
+ * per-call context — are automatically serialized to `{ message, name, stack }`.
+ * **Shallow only** — an `Error` nested inside a plain object (e.g. `{ meta: { err } }`) is left as-is;
+ * only top-level fields of `data` are checked.
+ */
+export type LogEntry = {
+    /**
+     * Merged structured data: pinned bindings overlaid with per-call context.
+     * Already shallow-copied and immutable — do not mutate.
+     */
+    data: Readonly<Bindings>;
+    level: LogType;
+    message?: string;
+    namespace: string;
+    /** Exact moment of the log call — shared across all transports for the same entry. */
+    timestamp: Date;
+};
+/**
+ * A transport receives a log entry and is responsible for its own delivery and formatting.
+ * If a transport throws, the logger catches it, reports it via a dev-only warning (wrapped in
+ * `RuneTransportError`), and continues dispatching the entry to remaining transports — a single
+ * misbehaving transport can never crash the caller of `log.info()`/etc. or block its siblings.
+ */
+export type Transport = (entry: LogEntry) => void;
+/**
+ * Middleware function that transforms or filters log entries before dispatch. Return null to drop the entry.
+ * If middleware throws, the logger catches it, reports it via a dev-only warning, and drops the entry
+ * (no transports run for it) rather than crashing the caller.
+ */
+export type LogMiddleware = (entry: LogEntry) => LogEntry | null;
+export type RemoteLogData = {
+    data?: Bindings;
+    env: 'development' | 'production';
+    level: LogType;
+    message?: string;
+    namespace?: string;
+    timestamp: string;
+};
+export type RemoteTransportOptions = {
+    /** Override the detected runtime environment. Default: auto-detected. */
+    env?: 'development' | 'production';
+    /** Remote delivery handler — receives the log type and structured payload. */
+    handler: (type: LogType, data: RemoteLogData) => void;
+    /** Minimum level to forward. Default: 'debug'. */
+    level?: LogLevel;
+    /**
+     * Called when the handler throws or rejects.
+     * The async error path is separate from any synchronous errors in the emit call stack.
+     * Default: a dev-only `console.warn` (gated by `__RUNE_PROD__`). In production builds,
+     * unhandled remote transport errors are silently swallowed — pass an explicit `onError`
+     * if you need delivery-failure observability in production.
+     */
+    onError?: (error: unknown, data: RemoteLogData) => void;
+};
+export type JsonTransportOptions = {
+    /**
+     * Custom output field names. Useful for adapting to aggregator conventions
+     * (Datadog, ELK, Loki, etc.).
+     *
+     * @example
+     * jsonTransport({ fields: { level: 'severity', time: '@timestamp', msg: 'message' } })
+     */
+    fields?: {
+        level?: string;
+        msg?: string;
+        ns?: string;
+        time?: string;
+    };
+    /** Minimum level to output. Default: 'debug'. */
+    level?: LogLevel;
+    /** Custom output function. Default: process.stdout.write. */
+    output?: (line: string) => void;
+    /**
+     * Replace circular references with `'[Circular]'` instead of throwing a TypeError.
+     * Useful in environments where log payloads may contain complex object graphs.
+     * Default: false.
+     */
+    safe?: boolean;
+};
+/** Handle returned by `batchTransport()`. Pass `handle.transport` to `createLogger({ transports })`. */
+export type BatchHandle = {
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose]: () => void;
+    /** Stop the interval timer and flush remaining entries. Call on shutdown. Idempotent. */
+    dispose: () => void;
+    /** `true` after `dispose()` has been called. */
+    readonly disposed: boolean;
+    /** Immediately flush buffered entries to the downstream handler without stopping the timer. */
+    flush: () => void;
+    /** The transport function to pass to `createLogger({ transports: [handle.transport] })`. */
+    transport: Transport;
+};
+export type BatchTransportOptions = {
+    /** Flush interval in milliseconds. Default: 5000. */
+    interval?: number;
+    /** Minimum level to buffer. Default: 'debug'. */
+    level?: LogLevel;
+    /**
+     * Hard limit on the in-memory buffer size. When the buffer exceeds this value,
+     * the oldest entries are dropped to prevent unbounded memory growth.
+     * Unlike `maxSize`, this does NOT trigger a flush — it silently drops.
+     * Default: unbounded.
+     */
+    maxBuffer?: number;
+    /** Maximum buffer size before an early flush. Default: 50. */
+    maxSize?: number;
+    /**
+     * Callback to receive flushed batches. May return a Promise — async rejections
+     * are forwarded to `onFlushError` in addition to synchronous throws.
+     */
+    onFlush: (entries: LogEntry[]) => void | Promise<void>;
+    /**
+     * Called when onFlush throws synchronously or rejects asynchronously.
+     * Allows retry/dead-letter logic. Default: silent.
+     */
+    onFlushError?: (entries: LogEntry[], error: unknown) => void;
+};
+export type PipeOptions = {
+    /**
+     * Called when one of the piped transports throws.
+     * Receives the thrown error and the log entry that triggered it.
+     * Default: silent (errors are swallowed to protect remaining transports).
+     */
+    onError?: (error: unknown, entry: LogEntry) => void;
+};
+export type SampleTransportOptions = {
+    /** Minimum level to sample. Default: 'debug'. */
+    level?: LogLevel;
+    /** Fraction of entries to forward (0–1). */
+    rate: number;
+    /** Downstream transport to receive sampled entries. */
+    transport: Transport;
+};
+export type RedactTransportOptions = {
+    /**
+     * Field names to replace at any depth in `data`.
+     * Matched by exact field name — dot-path notation (e.g. `'user.password'`) is NOT supported.
+     * A key like `'password'` will redact every field named `'password'` at any nesting level.
+     */
+    keys: string[];
+    /**
+     * Maximum object nesting depth to traverse during redaction.
+     * Objects deeper than this limit are returned as-is (not redacted).
+     * A dev-only warning is emitted when the cap is hit.
+     * Default: 20.
+     * @security In production builds, the depth warning is suppressed — deeply-nested sensitive
+     * fields beyond `maxDepth` will pass through unredacted without any indication. Ensure that
+     * sensitive payloads are not nested beyond this limit, or lower `maxDepth` as needed.
+     */
+    maxDepth?: number;
+    /** Replacement value for redacted fields. Default: '[REDACTED]'. */
+    replacement?: string;
+    /** Downstream transport to receive the redacted entry. */
+    transport: Transport;
+};
+export type RuneOptions = {
+    /** Initial pinned bindings for this logger instance. `Error` values are auto-serialized, same as per-call context. */
+    bindings?: Bindings;
+    /** Minimum log level for this logger instance. Default: 'debug'. */
+    logLevel?: LogLevel;
+    /** Middleware pipeline applied to every entry before dispatch to transports. */
+    middleware?: LogMiddleware[];
+    /**
+     * Namespace for this logger. When passed to `child()`, it is automatically
+     * dot-joined to the parent namespace (e.g. parent `'api'` + child `'auth'` → `'api.auth'`).
+     */
+    namespace?: string;
+    /**
+     * Transport pipeline. Each transport receives every entry that passes the level threshold.
+     * Default: [consoleTransport()].
+     */
+    transports?: Transport[];
+};
+/**
+ * Signature shared by all five log-level methods.
+ *
+ * - `log.info('message')` — string-only, most common.
+ * - `log.info({ ...fields }, 'message')` — structured context + optional message.
+ *   `Error` values in `fields` are automatically serialized to `{ message, name, stack }`.
+ *   Serialization is shallow only — an `Error` nested inside a nested object is left as-is.
+ * - `log.error(err, { ...fields }, 'message')` — Error first, then optional context + message.
+ *   Shorthand for the pattern where an Error is the primary subject of the log call.
+ *   The context object may be omitted entirely: `log.error(err, 'message')`.
+ *
+ * @example
+ * log.error({ err: new Error('timeout'), requestId }, 'request failed')
+ * log.error(new Error('timeout'), { requestId }, 'request failed')
+ */
+export type LogMethod = {
+    (message: string): void;
+    (error: Error, message?: string): void;
+    (error: Error, context: Bindings, message?: string): void;
+    (context: Bindings, message?: string): void;
+};
+export type Logger = {
+    /** Delegates to `dispose()`. Enables `using` declarations. */
+    [Symbol.dispose]: () => void;
+    /** Snapshot of currently pinned bindings. */
+    readonly bindings: Readonly<Bindings>;
+    /** Create a child logger with config overrides. Inherits all config and bindings by default. */
+    child: (overrides?: RuneOptions) => Logger;
+    debug: LogMethod;
+    /** `AbortSignal` aborted when `dispose()` is called. Use to tie external lifetimes to this logger. */
+    readonly disposalSignal: AbortSignal;
+    /**
+     * Marks the logger as disposed — all subsequent log calls become no-ops.
+     * Aborts `disposalSignal`. Does NOT auto-discover or dispose batch transports;
+     * hold a direct reference to `batchTransport` and call its `dispose()` on shutdown.
+     * Idempotent — safe to call multiple times.
+     */
+    dispose: () => void;
+    /** `true` after `dispose()` has been called. */
+    readonly disposed: boolean;
+    /** Returns true if entries at this level will pass the configured threshold. */
+    enabled: (type: LogLevel) => boolean;
+    error: LogMethod;
+    fatal: LogMethod;
+    /**
+     * Wrap a callback in a console group, closing it even on throw/reject.
+     * Pass a `level` to gate the group header on the configured log threshold
+     * (e.g. `level: 'debug'` suppresses the group when `logLevel` is above `'debug'`).
+     * Default: always renders (unless `logLevel` is `'off'`).
+     */
+    group: <T>(label: string, fn: () => T, level?: LogType) => T;
+    /**
+     * Same as `group`, using `console.groupCollapsed`.
+     * Pass a `level` to gate the group on the configured log threshold.
+     */
+    groupCollapsed: <T>(label: string, fn: () => T, level?: LogType) => T;
+    info: LogMethod;
+    /** Active log level for this logger instance. */
+    readonly logLevel: LogLevel;
+    /** Middleware pipeline applied before dispatch. */
+    readonly middleware: readonly LogMiddleware[];
+    /** Namespace string for this logger instance. */
+    readonly namespace: string;
+    /**
+     * Measure execution time of `fn` and emit a structured log entry.
+     * The entry message is `label`; `data` contains `{ duration_ms }` (rounded to 2 dp).
+     * When `fn` throws or rejects, `data` also includes `{ err }` with the serialized error.
+     * @param label - Human-readable description of the operation.
+     * @param fn - Synchronous or async function to time.
+     * @param level - Log level for the timing entry. Default: `'debug'`.
+     */
+    time: <T>(label: string, fn: () => T, level?: LogType) => T;
+    /** Transport pipeline for this logger instance. */
+    readonly transports: readonly Transport[];
+    /**
+     * Add a middleware function to the pipeline. Returns a **new** logger — the original is unchanged.
+     * Discarding the return value is a common mistake: always assign the result.
+     * @example
+     * const log = baseLog.use(tracingMiddleware); // ✓ keep the result
+     */
+    use: (middleware: LogMiddleware) => Logger;
+    warn: LogMethod;
+    /**
+     * Derive a child logger with additional pinned bindings.
+     * The returned logger is fully independent — disposing it does not affect the parent,
+     * and disposing the parent does not affect child loggers.
+     */
+    withBindings: (bindings: Bindings) => Logger;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,16 @@
+//#region src/types.ts
+var e = {
+	debug: 0,
+	error: 3,
+	fatal: 4,
+	info: 1,
+	off: 5,
+	warn: 2
+};
+function t(t, n) {
+	return n === "off" ? !1 : e[t] <= e[n];
+}
+//#endregion
+export { e as PRIORITY, t as isLevelEnabled };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["/* ─── Log levels ─── */\n\nexport type LogType = 'debug' | 'error' | 'fatal' | 'info' | 'warn';\nexport type LogLevel = LogType | 'off';\n\n/** Numeric priority for each level. Lower = more verbose. Exported for transport authors. */\nexport const PRIORITY: Record<LogLevel, number> = {\n  debug: 0,\n  error: 3,\n  fatal: 4,\n  info: 1,\n  off: 5,\n  warn: 2,\n};\n\n/** Returns true if `level` passes the `threshold`. Returns false when `level` is 'off'. Exported for transport/middleware authors. */\nexport function isLevelEnabled(threshold: LogLevel, level: LogLevel): boolean {\n  if (level === 'off') return false;\n\n  return PRIORITY[threshold] <= PRIORITY[level];\n}\n\n/* ─── Bindings ─── */\n\nexport type Bindings = Record<string, unknown>;\n\n/* ─── Log entry ─── */\n\n/**\n * The structured record produced by every log call and dispatched to all transports.\n * `data` is the merged result of pinned bindings and per-call context — transports\n * receive a single flat object and do not need to merge anything themselves.\n * Any `Error` instances — whether from a pinned binding (`bindings`/`withBindings()`) or\n * per-call context — are automatically serialized to `{ message, name, stack }`.\n * **Shallow only** — an `Error` nested inside a plain object (e.g. `{ meta: { err } }`) is left as-is;\n * only top-level fields of `data` are checked.\n */\nexport type LogEntry = {\n  /**\n   * Merged structured data: pinned bindings overlaid with per-call context.\n   * Already shallow-copied and immutable — do not mutate.\n   */\n  data: Readonly<Bindings>;\n  level: LogType;\n  message?: string;\n  namespace: string;\n  /** Exact moment of the log call — shared across all transports for the same entry. */\n  timestamp: Date;\n};\n\n/* ─── Transport ─── */\n\n/**\n * A transport receives a log entry and is responsible for its own delivery and formatting.\n * If a transport throws, the logger catches it, reports it via a dev-only warning (wrapped in\n * `RuneTransportError`), and continues dispatching the entry to remaining transports — a single\n * misbehaving transport can never crash the caller of `log.info()`/etc. or block its siblings.\n */\nexport type Transport = (entry: LogEntry) => void;\n\n/**\n * Middleware function that transforms or filters log entries before dispatch. Return null to drop the entry.\n * If middleware throws, the logger catches it, reports it via a dev-only warning, and drops the entry\n * (no transports run for it) rather than crashing the caller.\n */\nexport type LogMiddleware = (entry: LogEntry) => LogEntry | null;\n\n/* ─── Transport option types ─── */\n\nexport type RemoteLogData = {\n  data?: Bindings;\n  env: 'development' | 'production';\n  level: LogType;\n  message?: string;\n  namespace?: string;\n  timestamp: string;\n};\n\nexport type RemoteTransportOptions = {\n  /** Override the detected runtime environment. Default: auto-detected. */\n  env?: 'development' | 'production';\n  /** Remote delivery handler — receives the log type and structured payload. */\n  handler: (type: LogType, data: RemoteLogData) => void;\n  /** Minimum level to forward. Default: 'debug'. */\n  level?: LogLevel;\n  /**\n   * Called when the handler throws or rejects.\n   * The async error path is separate from any synchronous errors in the emit call stack.\n   * Default: a dev-only `console.warn` (gated by `__RUNE_PROD__`). In production builds,\n   * unhandled remote transport errors are silently swallowed — pass an explicit `onError`\n   * if you need delivery-failure observability in production.\n   */\n  onError?: (error: unknown, data: RemoteLogData) => void;\n};\n\nexport type JsonTransportOptions = {\n  /**\n   * Custom output field names. Useful for adapting to aggregator conventions\n   * (Datadog, ELK, Loki, etc.).\n   *\n   * @example\n   * jsonTransport({ fields: { level: 'severity', time: '@timestamp', msg: 'message' } })\n   */\n  fields?: {\n    level?: string;\n    msg?: string;\n    ns?: string;\n    time?: string;\n  };\n  /** Minimum level to output. Default: 'debug'. */\n  level?: LogLevel;\n  /** Custom output function. Default: process.stdout.write. */\n  output?: (line: string) => void;\n  /**\n   * Replace circular references with `'[Circular]'` instead of throwing a TypeError.\n   * Useful in environments where log payloads may contain complex object graphs.\n   * Default: false.\n   */\n  safe?: boolean;\n};\n\n/** Handle returned by `batchTransport()`. Pass `handle.transport` to `createLogger({ transports })`. */\nexport type BatchHandle = {\n  /** Delegates to `dispose()`. Enables `using` declarations. */\n  [Symbol.dispose]: () => void;\n  /** Stop the interval timer and flush remaining entries. Call on shutdown. Idempotent. */\n  dispose: () => void;\n  /** `true` after `dispose()` has been called. */\n  readonly disposed: boolean;\n  /** Immediately flush buffered entries to the downstream handler without stopping the timer. */\n  flush: () => void;\n  /** The transport function to pass to `createLogger({ transports: [handle.transport] })`. */\n  transport: Transport;\n};\n\nexport type BatchTransportOptions = {\n  /** Flush interval in milliseconds. Default: 5000. */\n  interval?: number;\n  /** Minimum level to buffer. Default: 'debug'. */\n  level?: LogLevel;\n  /**\n   * Hard limit on the in-memory buffer size. When the buffer exceeds this value,\n   * the oldest entries are dropped to prevent unbounded memory growth.\n   * Unlike `maxSize`, this does NOT trigger a flush — it silently drops.\n   * Default: unbounded.\n   */\n  maxBuffer?: number;\n  /** Maximum buffer size before an early flush. Default: 50. */\n  maxSize?: number;\n  /**\n   * Callback to receive flushed batches. May return a Promise — async rejections\n   * are forwarded to `onFlushError` in addition to synchronous throws.\n   */\n  onFlush: (entries: LogEntry[]) => void | Promise<void>;\n  /**\n   * Called when onFlush throws synchronously or rejects asynchronously.\n   * Allows retry/dead-letter logic. Default: silent.\n   */\n  onFlushError?: (entries: LogEntry[], error: unknown) => void;\n};\n\nexport type PipeOptions = {\n  /**\n   * Called when one of the piped transports throws.\n   * Receives the thrown error and the log entry that triggered it.\n   * Default: silent (errors are swallowed to protect remaining transports).\n   */\n  onError?: (error: unknown, entry: LogEntry) => void;\n};\n\nexport type SampleTransportOptions = {\n  /** Minimum level to sample. Default: 'debug'. */\n  level?: LogLevel;\n  /** Fraction of entries to forward (0–1). */\n  rate: number;\n  /** Downstream transport to receive sampled entries. */\n  transport: Transport;\n};\n\nexport type RedactTransportOptions = {\n  /**\n   * Field names to replace at any depth in `data`.\n   * Matched by exact field name — dot-path notation (e.g. `'user.password'`) is NOT supported.\n   * A key like `'password'` will redact every field named `'password'` at any nesting level.\n   */\n  keys: string[];\n  /**\n   * Maximum object nesting depth to traverse during redaction.\n   * Objects deeper than this limit are returned as-is (not redacted).\n   * A dev-only warning is emitted when the cap is hit.\n   * Default: 20.\n   * @security In production builds, the depth warning is suppressed — deeply-nested sensitive\n   * fields beyond `maxDepth` will pass through unredacted without any indication. Ensure that\n   * sensitive payloads are not nested beyond this limit, or lower `maxDepth` as needed.\n   */\n  maxDepth?: number;\n  /** Replacement value for redacted fields. Default: '[REDACTED]'. */\n  replacement?: string;\n  /** Downstream transport to receive the redacted entry. */\n  transport: Transport;\n};\n\n/* ─── Logger options ─── */\n\nexport type RuneOptions = {\n  /** Initial pinned bindings for this logger instance. `Error` values are auto-serialized, same as per-call context. */\n  bindings?: Bindings;\n  /** Minimum log level for this logger instance. Default: 'debug'. */\n  logLevel?: LogLevel;\n  /** Middleware pipeline applied to every entry before dispatch to transports. */\n  middleware?: LogMiddleware[];\n  /**\n   * Namespace for this logger. When passed to `child()`, it is automatically\n   * dot-joined to the parent namespace (e.g. parent `'api'` + child `'auth'` → `'api.auth'`).\n   */\n  namespace?: string;\n  /**\n   * Transport pipeline. Each transport receives every entry that passes the level threshold.\n   * Default: [consoleTransport()].\n   */\n  transports?: Transport[];\n};\n\n/* ─── Log method ─── */\n\n/**\n * Signature shared by all five log-level methods.\n *\n * - `log.info('message')` — string-only, most common.\n * - `log.info({ ...fields }, 'message')` — structured context + optional message.\n *   `Error` values in `fields` are automatically serialized to `{ message, name, stack }`.\n *   Serialization is shallow only — an `Error` nested inside a nested object is left as-is.\n * - `log.error(err, { ...fields }, 'message')` — Error first, then optional context + message.\n *   Shorthand for the pattern where an Error is the primary subject of the log call.\n *   The context object may be omitted entirely: `log.error(err, 'message')`.\n *\n * @example\n * log.error({ err: new Error('timeout'), requestId }, 'request failed')\n * log.error(new Error('timeout'), { requestId }, 'request failed')\n */\nexport type LogMethod = {\n  (message: string): void;\n  (error: Error, message?: string): void;\n  (error: Error, context: Bindings, message?: string): void;\n  (context: Bindings, message?: string): void;\n};\n\n/* ─── Logger interface ─── */\n\nexport type Logger = {\n  /** Delegates to `dispose()`. Enables `using` declarations. */\n  [Symbol.dispose]: () => void;\n  /** Snapshot of currently pinned bindings. */\n  readonly bindings: Readonly<Bindings>;\n  /** Create a child logger with config overrides. Inherits all config and bindings by default. */\n  child: (overrides?: RuneOptions) => Logger;\n  debug: LogMethod;\n  /** `AbortSignal` aborted when `dispose()` is called. Use to tie external lifetimes to this logger. */\n  readonly disposalSignal: AbortSignal;\n  /**\n   * Marks the logger as disposed — all subsequent log calls become no-ops.\n   * Aborts `disposalSignal`. Does NOT auto-discover or dispose batch transports;\n   * hold a direct reference to `batchTransport` and call its `dispose()` on shutdown.\n   * Idempotent — safe to call multiple times.\n   */\n  dispose: () => void;\n  /** `true` after `dispose()` has been called. */\n  readonly disposed: boolean;\n  /** Returns true if entries at this level will pass the configured threshold. */\n  enabled: (type: LogLevel) => boolean;\n  error: LogMethod;\n  fatal: LogMethod;\n  /**\n   * Wrap a callback in a console group, closing it even on throw/reject.\n   * Pass a `level` to gate the group header on the configured log threshold\n   * (e.g. `level: 'debug'` suppresses the group when `logLevel` is above `'debug'`).\n   * Default: always renders (unless `logLevel` is `'off'`).\n   */\n  group: <T>(label: string, fn: () => T, level?: LogType) => T;\n  /**\n   * Same as `group`, using `console.groupCollapsed`.\n   * Pass a `level` to gate the group on the configured log threshold.\n   */\n  groupCollapsed: <T>(label: string, fn: () => T, level?: LogType) => T;\n  info: LogMethod;\n  /** Active log level for this logger instance. */\n  readonly logLevel: LogLevel;\n  /** Middleware pipeline applied before dispatch. */\n  readonly middleware: readonly LogMiddleware[];\n  /** Namespace string for this logger instance. */\n  readonly namespace: string;\n  /**\n   * Measure execution time of `fn` and emit a structured log entry.\n   * The entry message is `label`; `data` contains `{ duration_ms }` (rounded to 2 dp).\n   * When `fn` throws or rejects, `data` also includes `{ err }` with the serialized error.\n   * @param label - Human-readable description of the operation.\n   * @param fn - Synchronous or async function to time.\n   * @param level - Log level for the timing entry. Default: `'debug'`.\n   */\n  time: <T>(label: string, fn: () => T, level?: LogType) => T;\n  /** Transport pipeline for this logger instance. */\n  readonly transports: readonly Transport[];\n  /**\n   * Add a middleware function to the pipeline. Returns a **new** logger — the original is unchanged.\n   * Discarding the return value is a common mistake: always assign the result.\n   * @example\n   * const log = baseLog.use(tracingMiddleware); // ✓ keep the result\n   */\n  use: (middleware: LogMiddleware) => Logger;\n  warn: LogMethod;\n  /**\n   * Derive a child logger with additional pinned bindings.\n   * The returned logger is fully independent — disposing it does not affect the parent,\n   * and disposing the parent does not affect child loggers.\n   */\n  withBindings: (bindings: Bindings) => Logger;\n};\n"],"mappings":";AAMA,IAAa,IAAqC;CAChD,OAAO;CACP,OAAO;CACP,OAAO;CACP,MAAM;CACN,KAAK;CACL,MAAM;AACR;AAGA,SAAgB,EAAe,GAAqB,GAA0B;CAG5E,OAFI,MAAU,QAAc,KAErB,EAAS,MAAc,EAAS;AACzC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vielzeug/rune",
+  "version": "1.1.1",
+  "description": "Structured logging — scoped loggers, pluggable transports, log levels, and remote log draining",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}