@logtape/file 0.9.0-dev.1

package/types/logtape/formatter.d.ts

@@ -0,0 +1,260 @@
+import type { LogLevel } from "./level.js";
+import type { LogRecord } from "./record.js";
+/**
+ * A text formatter is a function that accepts a log record and returns
+ * a string.
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record.
+ */
+export type TextFormatter = (record: LogRecord) => string;
+/**
+ * The formatted values for a log record.
+ * @since 0.6.0
+ */
+export interface FormattedValues {
+    /**
+     * The formatted timestamp.
+     */
+    timestamp: string;
+    /**
+     * The formatted log level.
+     */
+    level: string;
+    /**
+     * The formatted category.
+     */
+    category: string;
+    /**
+     * The formatted message.
+     */
+    message: string;
+    /**
+     * The unformatted log record.
+     */
+    record: LogRecord;
+}
+/**
+ * The various options for the built-in text formatters.
+ * @since 0.6.0
+ */
+export interface TextFormatterOptions {
+    /**
+     * The timestamp format.  This can be one of the following:
+     *
+     * - `"date-time-timezone"`: The date and time with the full timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000 +00:00"`).
+     * - `"date-time-tz"`: The date and time with the short timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000 +00"`).
+     * - `"date-time"`: The date and time without the timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000"`).
+     * - `"time-timezone"`: The time with the full timezone offset but without
+     *   the date (e.g., `"22:13:20.000 +00:00"`).
+     * - `"time-tz"`: The time with the short timezone offset but without the date
+     *   (e.g., `"22:13:20.000 +00"`).
+     * - `"time"`: The time without the date or timezone offset
+     *   (e.g., `"22:13:20.000"`).
+     * - `"date"`: The date without the time or timezone offset
+     *   (e.g., `"2023-11-14"`).
+     * - `"rfc3339"`: The date and time in RFC 3339 format
+     *   (e.g., `"2023-11-14T22:13:20.000Z"`).
+     *
+     * Alternatively, this can be a function that accepts a timestamp and returns
+     * a string.
+     *
+     * The default is `"date-time-timezone"`.
+     */
+    timestamp?: "date-time-timezone" | "date-time-tz" | "date-time" | "time-timezone" | "time-tz" | "time" | "date" | "rfc3339" | ((ts: number) => string);
+    /**
+     * The log level format.  This can be one of the following:
+     *
+     * - `"ABBR"`: The log level abbreviation in uppercase (e.g., `"INF"`).
+     * - `"FULL"`: The full log level name in uppercase (e.g., `"INFO"`).
+     * - `"L"`: The first letter of the log level in uppercase (e.g., `"I"`).
+     * - `"abbr"`: The log level abbreviation in lowercase (e.g., `"inf"`).
+     * - `"full"`: The full log level name in lowercase (e.g., `"info"`).
+     * - `"l"`: The first letter of the log level in lowercase (e.g., `"i"`).
+     *
+     * Alternatively, this can be a function that accepts a log level and returns
+     * a string.
+     *
+     * The default is `"ABBR"`.
+     */
+    level?: "ABBR" | "FULL" | "L" | "abbr" | "full" | "l" | ((level: LogLevel) => string);
+    /**
+     * The separator between category names.  For example, if the separator is
+     * `"·"`, the category `["a", "b", "c"]` will be formatted as `"a·b·c"`.
+     * The default separator is `"·"`.
+     *
+     * If this is a function, it will be called with the category array and
+     * should return a string, which will be used for rendering the category.
+     */
+    category?: string | ((category: readonly string[]) => string);
+    /**
+     * The format of the embedded values.
+     *
+     * A function that renders a value to a string.  This function is used to
+     * render the values in the log record.  The default is [`util.inspect()`] in
+     * Node.js/Bun and [`Deno.inspect()`] in Deno.
+     *
+     * [`util.inspect()`]: https://nodejs.org/api/util.html#utilinspectobject-options
+     * [`Deno.inspect()`]: https://docs.deno.com/api/deno/~/Deno.inspect
+     * @param value The value to render.
+     * @returns The string representation of the value.
+     */
+    value?: (value: unknown) => string;
+    /**
+     * How those formatted parts are concatenated.
+     *
+     * A function that formats the log record.  This function is called with the
+     * formatted values and should return a string.  Note that the formatted
+     * *should not* include a newline character at the end.
+     *
+     * By default, this is a function that formats the log record as follows:
+     *
+     * ```
+     * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
+     * ```
+     * @param values The formatted values.
+     * @returns The formatted log record.
+     */
+    format?: (values: FormattedValues) => string;
+}
+/**
+ * Get a text formatter with the specified options.  Although it's flexible
+ * enough to create a custom formatter, if you want more control, you can
+ * create a custom formatter that satisfies the {@link TextFormatter} type
+ * instead.
+ *
+ * For more information on the options, see {@link TextFormatterOptions}.
+ *
+ * By default, the formatter formats log records as follows:
+ *
+ * ```
+ * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
+ * ```
+ * @param options The options for the text formatter.
+ * @returns The text formatter.
+ * @since 0.6.0
+ */
+export declare function getTextFormatter(options?: TextFormatterOptions): TextFormatter;
+/**
+ * The default text formatter.  This formatter formats log records as follows:
+ *
+ * ```
+ * 2023-11-14 22:13:20.000 +00:00 [INF] category·subcategory: Hello, world!
+ * ```
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record.
+ */
+export declare const defaultTextFormatter: TextFormatter;
+/**
+ * The ANSI colors.  These can be used to colorize text in the console.
+ * @since 0.6.0
+ */
+export type AnsiColor = "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white";
+/**
+ * The ANSI text styles.
+ * @since 0.6.0
+ */
+export type AnsiStyle = "bold" | "dim" | "italic" | "underline" | "strikethrough";
+/**
+ * The various options for the ANSI color formatter.
+ * @since 0.6.0
+ */
+export interface AnsiColorFormatterOptions extends TextFormatterOptions {
+    /**
+     * The timestamp format.  This can be one of the following:
+     *
+     * - `"date-time-timezone"`: The date and time with the full timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000 +00:00"`).
+     * - `"date-time-tz"`: The date and time with the short timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000 +00"`).
+     * - `"date-time"`: The date and time without the timezone offset
+     *   (e.g., `"2023-11-14 22:13:20.000"`).
+     * - `"time-timezone"`: The time with the full timezone offset but without
+     *   the date (e.g., `"22:13:20.000 +00:00"`).
+     * - `"time-tz"`: The time with the short timezone offset but without the date
+     *   (e.g., `"22:13:20.000 +00"`).
+     * - `"time"`: The time without the date or timezone offset
+     *   (e.g., `"22:13:20.000"`).
+     * - `"date"`: The date without the time or timezone offset
+     *   (e.g., `"2023-11-14"`).
+     * - `"rfc3339"`: The date and time in RFC 3339 format
+     *   (e.g., `"2023-11-14T22:13:20.000Z"`).
+     *
+     * Alternatively, this can be a function that accepts a timestamp and returns
+     * a string.
+     *
+     * The default is `"date-time-tz"`.
+     */
+    timestamp?: "date-time-timezone" | "date-time-tz" | "date-time" | "time-timezone" | "time-tz" | "time" | "date" | "rfc3339" | ((ts: number) => string);
+    /**
+     * The ANSI style for the timestamp.  `"dim"` is used by default.
+     */
+    timestampStyle?: AnsiStyle | null;
+    /**
+     * The ANSI color for the timestamp.  No color is used by default.
+     */
+    timestampColor?: AnsiColor | null;
+    /**
+     * The ANSI style for the log level.  `"bold"` is used by default.
+     */
+    levelStyle?: AnsiStyle | null;
+    /**
+     * The ANSI colors for the log levels.  The default colors are as follows:
+     *
+     * - `"debug"`: `"blue"`
+     * - `"info"`: `"green"`
+     * - `"warning"`: `"yellow"`
+     * - `"error"`: `"red"`
+     * - `"fatal"`: `"magenta"`
+     */
+    levelColors?: Record<LogLevel, AnsiColor | null>;
+    /**
+     * The ANSI style for the category.  `"dim"` is used by default.
+     */
+    categoryStyle?: AnsiStyle | null;
+    /**
+     * The ANSI color for the category.  No color is used by default.
+     */
+    categoryColor?: AnsiColor | null;
+}
+/**
+ * Get an ANSI color formatter with the specified options.
+ *
+ * ![A preview of an ANSI color formatter.](https://i.imgur.com/I8LlBUf.png)
+ * @param option The options for the ANSI color formatter.
+ * @returns The ANSI color formatter.
+ * @since 0.6.0
+ */
+export declare function getAnsiColorFormatter(options?: AnsiColorFormatterOptions): TextFormatter;
+/**
+ * A text formatter that uses ANSI colors to format log records.
+ *
+ * ![A preview of ansiColorFormatter.](https://i.imgur.com/I8LlBUf.png)
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record.
+ * @since 0.5.0
+ */
+export declare const ansiColorFormatter: TextFormatter;
+/**
+ * A console formatter is a function that accepts a log record and returns
+ * an array of arguments to pass to {@link console.log}.
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record, as an array of arguments for
+ *          {@link console.log}.
+ */
+export type ConsoleFormatter = (record: LogRecord) => readonly unknown[];
+/**
+ * The default console formatter.
+ *
+ * @param record The log record to format.
+ * @returns The formatted log record, as an array of arguments for
+ *          {@link console.log}.
+ */
+export declare function defaultConsoleFormatter(record: LogRecord): readonly unknown[];
+//# sourceMappingURL=formatter.d.ts.map

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

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

package/types/logtape/level.d.ts

@@ -0,0 +1,32 @@
+declare const logLevels: readonly ["debug", "info", "warning", "error", "fatal"];
+/**
+ * The severity level of a {@link LogRecord}.
+ */
+export type LogLevel = typeof logLevels[number];
+/**
+ * Parses a log level from a string.
+ *
+ * @param level The log level as a string.  This is case-insensitive.
+ * @returns The log level.
+ * @throws {TypeError} If the log level is invalid.
+ */
+export declare function parseLogLevel(level: string): LogLevel;
+/**
+ * Checks if a string is a valid log level.  This function can be used as
+ * as a type guard to narrow the type of a string to a {@link LogLevel}.
+ *
+ * @param level The log level as a string.  This is case-sensitive.
+ * @returns `true` if the string is a valid log level.
+ */
+export declare function isLogLevel(level: string): level is LogLevel;
+/**
+ * Compares two log levels.
+ * @param a The first log level.
+ * @param b The second log level.
+ * @returns A negative number if `a` is less than `b`, a positive number if `a`
+ *          is greater than `b`, or zero if they are equal.
+ * @since 0.8.0
+ */
+export declare function compareLogLevel(a: LogLevel, b: LogLevel): number;
+export {};
+//# sourceMappingURL=level.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"level.d.ts","sourceRoot":"","sources":["../../src/logtape/level.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,SAAS,yDAA0D,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAYrD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAW3D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAUhE"}