@logtape/file 0.9.0-dev.1

package/types/logtape/logger.d.ts

@@ -0,0 +1,423 @@
+import type { ContextLocalStorage } from "./context.js";
+import type { Filter } from "./filter.js";
+import { type LogLevel } from "./level.js";
+import type { LogRecord } from "./record.js";
+import type { Sink } from "./sink.js";
+/**
+ * A logger interface.  It provides methods to log messages at different
+ * severity levels.
+ *
+ * ```typescript
+ * const logger = getLogger("category");
+ * logger.debug `A debug message with ${value}.`;
+ * logger.info `An info message with ${value}.`;
+ * logger.warn `A warning message with ${value}.`;
+ * logger.error `An error message with ${value}.`;
+ * logger.fatal `A fatal error message with ${value}.`;
+ * ```
+ */
+export interface Logger {
+    /**
+     * The category of the logger.  It is an array of strings.
+     */
+    readonly category: readonly string[];
+    /**
+     * The logger with the supercategory of the current logger.  If the current
+     * logger is the root logger, this is `null`.
+     */
+    readonly parent: Logger | null;
+    /**
+     * Get a child logger with the given subcategory.
+     *
+     * ```typescript
+     * const logger = getLogger("category");
+     * const subLogger = logger.getChild("sub-category");
+     * ```
+     *
+     * The above code is equivalent to:
+     *
+     * ```typescript
+     * const logger = getLogger("category");
+     * const subLogger = getLogger(["category", "sub-category"]);
+     * ```
+     *
+     * @param subcategory The subcategory.
+     * @returns The child logger.
+     */
+    getChild(subcategory: string | readonly [string] | readonly [string, ...string[]]): Logger;
+    /**
+     * Get a logger with contextual properties.  This is useful for
+     * log multiple messages with the shared set of properties.
+     *
+     * ```typescript
+     * const logger = getLogger("category");
+     * const ctx = logger.with({ foo: 123, bar: "abc" });
+     * ctx.info("A message with {foo} and {bar}.");
+     * ctx.warn("Another message with {foo}, {bar}, and {baz}.", { baz: true });
+     * ```
+     *
+     * The above code is equivalent to:
+     *
+     * ```typescript
+     * const logger = getLogger("category");
+     * logger.info("A message with {foo} and {bar}.", { foo: 123, bar: "abc" });
+     * logger.warn(
+     *   "Another message with {foo}, {bar}, and {baz}.",
+     *   { foo: 123, bar: "abc", baz: true },
+     * );
+     * ```
+     *
+     * @param properties
+     * @returns
+     * @since 0.5.0
+     */
+    with(properties: Record<string, unknown>): Logger;
+    /**
+     * Log a debug message.  Use this as a template string prefix.
+     *
+     * ```typescript
+     * logger.debug `A debug message with ${value}.`;
+     * ```
+     *
+     * @param message The message template strings array.
+     * @param values The message template values.
+     */
+    debug(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+    /**
+     * Log a debug message with properties.
+     *
+     * ```typescript
+     * logger.debug('A debug message with {value}.', { value });
+     * ```
+     *
+     * If the properties are expensive to compute, you can pass a callback that
+     * returns the properties:
+     *
+     * ```typescript
+     * logger.debug(
+     *   'A debug message with {value}.',
+     *   () => ({ value: expensiveComputation() })
+     * );
+     * ```
+     *
+     * @param message The message template.  Placeholders to be replaced with
+     *                `values` are indicated by keys in curly braces (e.g.,
+     *                `{value}`).
+     * @param properties The values to replace placeholders with.  For lazy
+     *                   evaluation, this can be a callback that returns the
+     *                   properties.
+     */
+    debug(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+    /**
+     * Lazily log a debug message.  Use this when the message values are expensive
+     * to compute and should only be computed if the message is actually logged.
+     *
+     * ```typescript
+     * logger.debug(l => l`A debug message with ${expensiveValue()}.`);
+     * ```
+     *
+     * @param callback A callback that returns the message template prefix.
+     * @throws {TypeError} If no log record was made inside the callback.
+     */
+    debug(callback: LogCallback): void;
+    /**
+     * Log an informational message.  Use this as a template string prefix.
+     *
+     * ```typescript
+     * logger.info `An info message with ${value}.`;
+     * ```
+     *
+     * @param message The message template strings array.
+     * @param values The message template values.
+     */
+    info(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+    /**
+     * Log an informational message with properties.
+     *
+     * ```typescript
+     * logger.info('An info message with {value}.', { value });
+     * ```
+     *
+     * If the properties are expensive to compute, you can pass a callback that
+     * returns the properties:
+     *
+     * ```typescript
+     * logger.info(
+     *   'An info message with {value}.',
+     *   () => ({ value: expensiveComputation() })
+     * );
+     * ```
+     *
+     * @param message The message template.  Placeholders to be replaced with
+     *                `values` are indicated by keys in curly braces (e.g.,
+     *                `{value}`).
+     * @param properties The values to replace placeholders with.  For lazy
+     *                   evaluation, this can be a callback that returns the
+     *                   properties.
+     */
+    info(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+    /**
+     * Lazily log an informational message.  Use this when the message values are
+     * expensive to compute and should only be computed if the message is actually
+     * logged.
+     *
+     * ```typescript
+     * logger.info(l => l`An info message with ${expensiveValue()}.`);
+     * ```
+     *
+     * @param callback A callback that returns the message template prefix.
+     * @throws {TypeError} If no log record was made inside the callback.
+     */
+    info(callback: LogCallback): void;
+    /**
+     * Log a warning message.  Use this as a template string prefix.
+     *
+     * ```typescript
+     * logger.warn `A warning message with ${value}.`;
+     * ```
+     *
+     * @param message The message template strings array.
+     * @param values The message template values.
+     */
+    warn(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+    /**
+     * Log a warning message with properties.
+     *
+     * ```typescript
+     * logger.warn('A warning message with {value}.', { value });
+     * ```
+     *
+     * If the properties are expensive to compute, you can pass a callback that
+     * returns the properties:
+     *
+     * ```typescript
+     * logger.warn(
+     *   'A warning message with {value}.',
+     *   () => ({ value: expensiveComputation() })
+     * );
+     * ```
+     *
+     * @param message The message template.  Placeholders to be replaced with
+     *                `values` are indicated by keys in curly braces (e.g.,
+     *                `{value}`).
+     * @param properties The values to replace placeholders with.  For lazy
+     *                   evaluation, this can be a callback that returns the
+     *                   properties.
+     */
+    warn(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+    /**
+     * Lazily log a warning message.  Use this when the message values are
+     * expensive to compute and should only be computed if the message is actually
+     * logged.
+     *
+     * ```typescript
+     * logger.warn(l => l`A warning message with ${expensiveValue()}.`);
+     * ```
+     *
+     * @param callback A callback that returns the message template prefix.
+     * @throws {TypeError} If no log record was made inside the callback.
+     */
+    warn(callback: LogCallback): void;
+    /**
+     * Log an error message.  Use this as a template string prefix.
+     *
+     * ```typescript
+     * logger.error `An error message with ${value}.`;
+     * ```
+     *
+     * @param message The message template strings array.
+     * @param values The message template values.
+     */
+    error(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+    /**
+     * Log an error message with properties.
+     *
+     * ```typescript
+     * logger.warn('An error message with {value}.', { value });
+     * ```
+     *
+     * If the properties are expensive to compute, you can pass a callback that
+     * returns the properties:
+     *
+     * ```typescript
+     * logger.error(
+     *   'An error message with {value}.',
+     *   () => ({ value: expensiveComputation() })
+     * );
+     * ```
+     *
+     * @param message The message template.  Placeholders to be replaced with
+     *                `values` are indicated by keys in curly braces (e.g.,
+     *                `{value}`).
+     * @param properties The values to replace placeholders with.  For lazy
+     *                   evaluation, this can be a callback that returns the
+     *                   properties.
+     */
+    error(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+    /**
+     * Lazily log an error message.  Use this when the message values are
+     * expensive to compute and should only be computed if the message is actually
+     * logged.
+     *
+     * ```typescript
+     * logger.error(l => l`An error message with ${expensiveValue()}.`);
+     * ```
+     *
+     * @param callback A callback that returns the message template prefix.
+     * @throws {TypeError} If no log record was made inside the callback.
+     */
+    error(callback: LogCallback): void;
+    /**
+     * Log a fatal error message.  Use this as a template string prefix.
+     *
+     * ```typescript
+     * logger.fatal `A fatal error message with ${value}.`;
+     * ```
+     *
+     * @param message The message template strings array.
+     * @param values The message template values.
+     */
+    fatal(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+    /**
+     * Log a fatal error message with properties.
+     *
+     * ```typescript
+     * logger.warn('A fatal error message with {value}.', { value });
+     * ```
+     *
+     * If the properties are expensive to compute, you can pass a callback that
+     * returns the properties:
+     *
+     * ```typescript
+     * logger.fatal(
+     *   'A fatal error message with {value}.',
+     *   () => ({ value: expensiveComputation() })
+     * );
+     * ```
+     *
+     * @param message The message template.  Placeholders to be replaced with
+     *                `values` are indicated by keys in curly braces (e.g.,
+     *                `{value}`).
+     * @param properties The values to replace placeholders with.  For lazy
+     *                   evaluation, this can be a callback that returns the
+     *                   properties.
+     */
+    fatal(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+    /**
+     * Lazily log a fatal error message.  Use this when the message values are
+     * expensive to compute and should only be computed if the message is actually
+     * logged.
+     *
+     * ```typescript
+     * logger.fatal(l => l`A fatal error message with ${expensiveValue()}.`);
+     * ```
+     *
+     * @param callback A callback that returns the message template prefix.
+     * @throws {TypeError} If no log record was made inside the callback.
+     */
+    fatal(callback: LogCallback): void;
+}
+/**
+ * A logging callback function.  It is used to defer the computation of a
+ * message template until it is actually logged.
+ * @param prefix The message template prefix.
+ * @returns The rendered message array.
+ */
+export type LogCallback = (prefix: LogTemplatePrefix) => unknown[];
+/**
+ * A logging template prefix function.  It is used to log a message in
+ * a {@link LogCallback} function.
+ * @param message The message template strings array.
+ * @param values The message template values.
+ * @returns The rendered message array.
+ */
+export type LogTemplatePrefix = (message: TemplateStringsArray, ...values: unknown[]) => unknown[];
+/**
+ * Get a logger with the given category.
+ *
+ * ```typescript
+ * const logger = getLogger(["my-app"]);
+ * ```
+ *
+ * @param category The category of the logger.  It can be a string or an array
+ *                 of strings.  If it is a string, it is equivalent to an array
+ *                 with a single element.
+ * @returns The logger.
+ */
+export declare function getLogger(category?: string | readonly string[]): Logger;
+/**
+ * A logger implementation.  Do not use this directly; use {@link getLogger}
+ * instead.  This class is exported for testing purposes.
+ */
+export declare class LoggerImpl implements Logger {
+    readonly parent: LoggerImpl | null;
+    readonly children: Record<string, LoggerImpl | WeakRef<LoggerImpl>>;
+    readonly category: readonly string[];
+    readonly sinks: Sink[];
+    parentSinks: "inherit" | "override";
+    readonly filters: Filter[];
+    lowestLevel: LogLevel | null;
+    contextLocalStorage?: ContextLocalStorage<Record<string, unknown>>;
+    static getLogger(category?: string | readonly string[]): LoggerImpl;
+    private constructor();
+    getChild(subcategory: string | readonly [string] | readonly [string, ...(readonly string[])]): LoggerImpl;
+    /**
+     * Reset the logger.  This removes all sinks and filters from the logger.
+     */
+    reset(): void;
+    /**
+     * Reset the logger and all its descendants.  This removes all sinks and
+     * filters from the logger and all its descendants.
+     */
+    resetDescendants(): void;
+    with(properties: Record<string, unknown>): Logger;
+    filter(record: LogRecord): boolean;
+    getSinks(level: LogLevel): Iterable<Sink>;
+    emit(record: LogRecord, bypassSinks?: Set<Sink>): void;
+    log(level: LogLevel, rawMessage: string, properties: Record<string, unknown> | (() => Record<string, unknown>), bypassSinks?: Set<Sink>): void;
+    logLazily(level: LogLevel, callback: LogCallback, properties?: Record<string, unknown>): void;
+    logTemplate(level: LogLevel, messageTemplate: TemplateStringsArray, values: unknown[], properties?: Record<string, unknown>): void;
+    debug(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    info(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    warn(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    error(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    fatal(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+}
+/**
+ * A logger implementation with contextual properties.  Do not use this
+ * directly; use {@link Logger.with} instead.  This class is exported
+ * for testing purposes.
+ */
+export declare class LoggerCtx implements Logger {
+    logger: LoggerImpl;
+    properties: Record<string, unknown>;
+    constructor(logger: LoggerImpl, properties: Record<string, unknown>);
+    get category(): readonly string[];
+    get parent(): Logger | null;
+    getChild(subcategory: string | readonly [string] | readonly [string, ...string[]]): Logger;
+    with(properties: Record<string, unknown>): Logger;
+    log(level: LogLevel, message: string, properties: Record<string, unknown> | (() => Record<string, unknown>), bypassSinks?: Set<Sink>): void;
+    logLazily(level: LogLevel, callback: LogCallback): void;
+    logTemplate(level: LogLevel, messageTemplate: TemplateStringsArray, values: unknown[]): void;
+    debug(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    info(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    warn(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    error(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+    fatal(message: TemplateStringsArray | string | LogCallback, ...values: unknown[]): void;
+}
+/**
+ * Parse a message template into a message template array and a values array.
+ * @param template The message template.
+ * @param properties The values to replace placeholders with.
+ * @returns The message template array and the values array.
+ */
+export declare function parseMessageTemplate(template: string, properties: Record<string, unknown>): readonly unknown[];
+/**
+ * Render a message template with values.
+ * @param template The message template.
+ * @param values The message template values.
+ * @returns The message template values interleaved between the substitution
+ *          values.
+ */
+export declare function renderMessage(template: TemplateStringsArray, values: readonly unknown[]): unknown[];
+//# sourceMappingURL=logger.d.ts.map

package/types/logtape/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logtape/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CACN,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACvE,MAAM,CAAC;IAEV;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;IAElD;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAE1E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrE,IAAI,CAAC;IAER;;;;;;;;;;OAUG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrE,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAElC;;;;;;;;;OASG;IACH,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrE,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAElC;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAE1E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrE,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAEnC;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,CAAC;IAE1E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,KAAK,CACH,OAAO,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACrE,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,iBAAiB,KAAK,OAAO,EAAE,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,oBAAoB,EAC7B,GAAG,MAAM,EAAE,OAAO,EAAE,KACjB,OAAO,EAAE,CAAC;AAEf;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,QAAQ,GAAE,MAAM,GAAG,SAAS,MAAM,EAAO,GAAG,MAAM,CAE3E;AAcD;;;GAGG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;IACvB,WAAW,EAAE,SAAS,GAAG,UAAU,CAAa;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,QAAQ,GAAG,IAAI,CAAW;IACvC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEnE,MAAM,CAAC,SAAS,CAAC,QAAQ,GAAE,MAAM,GAAG,SAAS,MAAM,EAAO,GAAG,UAAU;IAevE,OAAO;IAQP,QAAQ,CACN,WAAW,EACP,MAAM,GACN,SAAS,CAAC,MAAM,CAAC,GACjB,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC,GAC5C,UAAU;IAoBb;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAQxB,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAIjD,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO;IAQjC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC;IAY1C,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI;IAyBtD,GAAG,CACD,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrE,WAAW,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GACtB,IAAI;IAqCP,SAAS,CACP,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,WAAW,EACrB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,IAAI;IA6BP,WAAW,CACT,KAAK,EAAE,QAAQ,EACf,eAAe,EAAE,oBAAoB,EACrC,MAAM,EAAE,OAAO,EAAE,EACjB,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACvC,IAAI;IAaP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,IAAI,CACF,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,IAAI,CACF,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAcP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;CASR;AAED;;;;GAIG;AACH,qBAAa,SAAU,YAAW,MAAM;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAExB,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKnE,IAAI,QAAQ,IAAI,SAAS,MAAM,EAAE,CAEhC;IAED,IAAI,MAAM,IAAI,MAAM,GAAG,IAAI,CAE1B;IAED,QAAQ,CACN,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACvE,MAAM;IAIT,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAIjD,GAAG,CACD,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACrE,WAAW,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,GACtB,IAAI;IAcP,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI;IAIvD,WAAW,CACT,KAAK,EAAE,QAAQ,EACf,eAAe,EAAE,oBAAoB,EACrC,MAAM,EAAE,OAAO,EAAE,GAChB,IAAI;IAIP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,IAAI,CACF,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,IAAI,CACF,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAcP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;IAUP,KAAK,CACH,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,WAAW,EACpD,GAAG,MAAM,EAAE,OAAO,EAAE,GACnB,IAAI;CASR;AAOD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS,OAAO,EAAE,CAoCpB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,OAAO,EAAE,CAOX"}

package/types/logtape/mod.d.ts

@@ -0,0 +1,9 @@
+export { type Config, ConfigError, configure, configureSync, dispose, disposeSync, getConfig, type LoggerConfig, reset, resetSync, } from "./config.js";
+export { type ContextLocalStorage, withContext } from "./context.js";
+export { type Filter, type FilterLike, getLevelFilter, toFilter, } from "./filter.js";
+export { type AnsiColor, ansiColorFormatter, type AnsiColorFormatterOptions, type AnsiStyle, type ConsoleFormatter, defaultConsoleFormatter, defaultTextFormatter, type FormattedValues, getAnsiColorFormatter, getTextFormatter, type TextFormatter, type TextFormatterOptions, } from "./formatter.js";
+export { compareLogLevel, isLogLevel, type LogLevel, parseLogLevel, } from "./level.js";
+export { getLogger, type Logger } from "./logger.js";
+export type { LogRecord } from "./record.js";
+export { type ConsoleSinkOptions, getConsoleSink, getStreamSink, type Sink, type StreamSinkOptions, withFilter, } from "./sink.js";
+//# sourceMappingURL=mod.d.ts.map

package/types/logtape/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/logtape/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,WAAW,EACX,SAAS,EACT,aAAa,EACb,OAAO,EACP,WAAW,EACX,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,EACL,SAAS,GACV,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,mBAAmB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,EACL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,cAAc,EACd,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,SAAS,EACd,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,eAAe,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,eAAe,EACf,UAAU,EACV,KAAK,QAAQ,EACb,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,KAAK,kBAAkB,EACvB,cAAc,EACd,aAAa,EACb,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,UAAU,GACX,MAAM,WAAW,CAAC"}

package/types/logtape/nodeUtil.d.ts

@@ -0,0 +1,3 @@
+import util from "node:util";
+export default util;
+//# sourceMappingURL=nodeUtil.d.ts.map

package/types/logtape/nodeUtil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeUtil.d.ts","sourceRoot":"","sources":["../../src/logtape/nodeUtil.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,eAAe,IAAI,CAAC"}

package/types/logtape/record.d.ts

@@ -0,0 +1,44 @@
+import type { LogLevel } from "./level.js";
+/**
+ * A log record.
+ */
+export interface LogRecord {
+    /**
+     * The category of the logger that produced the log record.
+     */
+    readonly category: readonly string[];
+    /**
+     * The log level.
+     */
+    readonly level: LogLevel;
+    /**
+     * The log message.  This is the result of substituting the message template
+     * with the values.  The number of elements in this array is always odd,
+     * with the message template values interleaved between the substitution
+     * values.
+     */
+    readonly message: readonly unknown[];
+    /**
+     * The raw log message.  This is the original message template without any
+     * further processing.  It can be either:
+     *
+     * - A string without any substitutions if the log record was created with
+     *   a method call syntax, e.g., "Hello, {name}!" for
+     *   `logger.info("Hello, {name}!", { name })`.
+     * - A template string array if the log record was created with a tagged
+     *   template literal syntax, e.g., `["Hello, ", "!"]` for
+     *   ``logger.info`Hello, ${name}!```.
+     *
+     * @since 0.6.0
+     */
+    readonly rawMessage: string | TemplateStringsArray;
+    /**
+     * The timestamp of the log record in milliseconds since the Unix epoch.
+     */
+    readonly timestamp: number;
+    /**
+     * The extra properties of the log record.
+     */
+    readonly properties: Record<string, unknown>;
+}
+//# sourceMappingURL=record.d.ts.map

package/types/logtape/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/logtape/record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAErC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAEzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IAErC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,oBAAoB,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9C"}

package/types/logtape/sink.d.ts

@@ -0,0 +1,108 @@
+import { type FilterLike } from "./filter.js";
+import { type ConsoleFormatter, type TextFormatter } from "./formatter.js";
+import type { LogLevel } from "./level.js";
+import type { LogRecord } from "./record.js";
+/**
+ * A sink is a function that accepts a log record and prints it somewhere.
+ * Thrown exceptions will be suppressed and then logged to the meta logger,
+ * a {@link Logger} with the category `["logtape", "meta"]`.  (In that case,
+ * the meta log record will not be passed to the sink to avoid infinite
+ * recursion.)
+ *
+ * @param record The log record to sink.
+ */
+export type Sink = (record: LogRecord) => void;
+/**
+ * Turns a sink into a filtered sink.  The returned sink only logs records that
+ * pass the filter.
+ *
+ * @example Filter a console sink to only log records with the info level
+ * ```typescript
+ * const sink = withFilter(getConsoleSink(), "info");
+ * ```
+ *
+ * @param sink A sink to be filtered.
+ * @param filter A filter to apply to the sink.  It can be either a filter
+ *               function or a {@link LogLevel} string.
+ * @returns A sink that only logs records that pass the filter.
+ */
+export declare function withFilter(sink: Sink, filter: FilterLike): Sink;
+/**
+ * Options for the {@link getStreamSink} function.
+ */
+export interface StreamSinkOptions {
+    /**
+     * The text formatter to use.  Defaults to {@link defaultTextFormatter}.
+     */
+    formatter?: TextFormatter;
+    /**
+     * The text encoder to use.  Defaults to an instance of {@link TextEncoder}.
+     */
+    encoder?: {
+        encode(text: string): Uint8Array;
+    };
+}
+/**
+ * A factory that returns a sink that writes to a {@link WritableStream}.
+ *
+ * Note that the `stream` is of Web Streams API, which is different from
+ * Node.js streams.  You can convert a Node.js stream to a Web Streams API
+ * stream using [`stream.Writable.toWeb()`] method.
+ *
+ * [`stream.Writable.toWeb()`]: https://nodejs.org/api/stream.html#streamwritabletowebstreamwritable
+ *
+ * @example Sink to the standard error in Deno
+ * ```typescript
+ * const stderrSink = getStreamSink(Deno.stderr.writable);
+ * ```
+ *
+ * @example Sink to the standard error in Node.js
+ * ```typescript
+ * import stream from "node:stream";
+ * const stderrSink = getStreamSink(stream.Writable.toWeb(process.stderr));
+ * ```
+ *
+ * @param stream The stream to write to.
+ * @param options The options for the sink.
+ * @returns A sink that writes to the stream.
+ */
+export declare function getStreamSink(stream: WritableStream, options?: StreamSinkOptions): Sink & AsyncDisposable;
+type ConsoleMethod = "debug" | "info" | "log" | "warn" | "error";
+/**
+ * Options for the {@link getConsoleSink} function.
+ */
+export interface ConsoleSinkOptions {
+    /**
+     * The console formatter or text formatter to use.
+     * Defaults to {@link defaultConsoleFormatter}.
+     */
+    formatter?: ConsoleFormatter | TextFormatter;
+    /**
+     * The mapping from log levels to console methods.  Defaults to:
+     *
+     * ```typescript
+     * {
+     *   debug: "debug",
+     *   info: "info",
+     *   warning: "warn",
+     *   error: "error",
+     *   fatal: "error",
+     * }
+     * ```
+     * @since 0.9.0
+     */
+    levelMap?: Record<LogLevel, ConsoleMethod>;
+    /**
+     * The console to log to.  Defaults to {@link console}.
+     */
+    console?: Console;
+}
+/**
+ * A console sink factory that returns a sink that logs to the console.
+ *
+ * @param options The options for the sink.
+ * @returns A sink that logs to the console.
+ */
+export declare function getConsoleSink(options?: ConsoleSinkOptions): Sink;
+export {};
+//# sourceMappingURL=sink.d.ts.map

package/types/logtape/sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/logtape/sink.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAY,MAAM,aAAa,CAAC;AACxD,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAK/D;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAE1B;;OAEG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,iBAAsB,GAC9B,IAAI,GAAG,eAAe,CAgBxB;AAED,KAAK,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAAC;IAE7C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAE3C;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAwBrE"}