likec4 1.48.0 → 1.49.0

package/dist/_chunks/libs/@logtape/logtape.d.mts

@@ -0,0 +1,741 @@
+//#region ../../node_modules/.pnpm/@logtape+logtape@1.3.7/node_modules/@logtape/logtape/dist/level.d.ts
+//#region src/level.d.ts
+declare const logLevels: readonly ["trace", "debug", "info", "warning", "error", "fatal"];
+/**
+ * The severity level of a {@link LogRecord}.
+ */
+type LogLevel = typeof logLevels[number];
+/**
+ * Lists all available log levels with the order of their severity.
+ * The `"trace"` level goes first, and the `"fatal"` level goes last.
+ * @returns A new copy of the array of log levels.
+ * @since 1.0.0
+ */
+//#endregion
+//#region ../../node_modules/.pnpm/@logtape+logtape@1.3.7/node_modules/@logtape/logtape/dist/record.d.ts
+//#region src/record.d.ts
+/**
+ * A log record.
+ */
+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
+//#endregion
+//#endregion
+//#region ../../node_modules/.pnpm/@logtape+logtape@1.3.7/node_modules/@logtape/logtape/dist/logger.d.ts
+//#region src/logger.d.ts
+/**
+ * A logger interface.  It provides methods to log messages at different
+ * severity levels.
+ *
+ * ```typescript
+ * const logger = getLogger("category");
+ * logger.trace `A trace message with ${value}`
+ * 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}.`;
+ * ```
+ */
+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 trace message.  Use this as a template string prefix.
+   *
+   * ```typescript
+   * logger.trace `A trace message with ${value}.`;
+   * ```
+   *
+   * @param message The message template strings array.
+   * @param values The message template values.
+   * @since 0.12.0
+   */
+  trace(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+  /**
+   * Log a trace message with properties.
+   *
+   * ```typescript
+   * logger.trace('A trace message with {value}.', { value });
+   * ```
+   *
+   * If the properties are expensive to compute, you can pass a callback that
+   * returns the properties:
+   *
+   * ```typescript
+   * logger.trace(
+   *   'A trace 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.
+   * @since 0.12.0
+   */
+  trace(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+  /**
+   * Log a trace values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.trace({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.trace('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.trace('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.12.0
+   */
+  trace(properties: Record<string, unknown>): void;
+  /**
+   * Lazily log a trace message.  Use this when the message values are expensive
+   * to compute and should only be computed if the message is actually logged.
+   *
+   * ```typescript
+   * logger.trace(l => l`A trace message with ${expensiveValue()}.`);
+   * ```
+   *
+   * @param callback A callback that returns the message template prefix.
+   * @throws {TypeError} If no log record was made inside the callback.
+   * @since 0.12.0
+   */
+  trace(callback: LogCallback): void;
+  /**
+   * 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;
+  /**
+   * Log a debug values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.debug({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.debug('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.debug('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.11.0
+   */
+  debug(properties: 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;
+  /**
+   * Log an informational values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.info({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.info('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.info('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.11.0
+   */
+  info(properties: 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;
+  /**
+   * Log a warning values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.warn({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.warn('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.warn('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.11.0
+   */
+  warn(properties: 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 a warning message.  Use this as a template string prefix.
+   *
+   * ```typescript
+   * logger.warning `A warning message with ${value}.`;
+   * ```
+   *
+   * @param message The message template strings array.
+   * @param values The message template values.
+   * @since 0.12.0
+   */
+  warning(message: TemplateStringsArray, ...values: readonly unknown[]): void;
+  /**
+   * Log a warning message with properties.
+   *
+   * ```typescript
+   * logger.warning('A warning message with {value}.', { value });
+   * ```
+   *
+   * If the properties are expensive to compute, you can pass a callback that
+   * returns the properties:
+   *
+   * ```typescript
+   * logger.warning(
+   *   '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.
+   * @since 0.12.0
+   */
+  warning(message: string, properties?: Record<string, unknown> | (() => Record<string, unknown>)): void;
+  /**
+   * Log a warning values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.warning({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.warning('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.warning('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.12.0
+   */
+  warning(properties: 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.warning(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.
+   * @since 0.12.0
+   */
+  warning(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;
+  /**
+   * Log an error values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.error({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.error('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.error('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.11.0
+   */
+  error(properties: 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;
+  /**
+   * Log a fatal error values with no message.  This is useful when you
+   * want to log properties without a message, e.g., when you want to log
+   * the context of a request or an operation.
+   *
+   * ```typescript
+   * logger.fatal({ method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * Note that this is a shorthand for:
+   *
+   * ```typescript
+   * logger.fatal('{*}', { method: 'GET', url: '/api/v1/resource' });
+   * ```
+   *
+   * If the properties are expensive to compute, you cannot use this shorthand
+   * and should use the following syntax instead:
+   *
+   * ```typescript
+   * logger.fatal('{*}', () => ({
+   *   method: expensiveMethod(),
+   *   url: expensiveUrl(),
+   * }));
+   * ```
+   *
+   * @param properties The values to log.  Note that this does not take
+   *                   a callback.
+   * @since 0.11.0
+   */
+  fatal(properties: 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;
+  /**
+   * Emits a log record with custom fields while using this logger's
+   * category.
+   *
+   * This is a low-level API for integration scenarios where you need full
+   * control over the log record, particularly for preserving timestamps
+   * from external systems.
+   *
+   * ```typescript
+   * const logger = getLogger(["my-app", "integration"]);
+   *
+   * // Emit a log with a custom timestamp
+   * logger.emit({
+   *   timestamp: kafkaLog.originalTimestamp,
+   *   level: "info",
+   *   message: [kafkaLog.message],
+   *   rawMessage: kafkaLog.message,
+   *   properties: {
+   *     source: "kafka",
+   *     partition: kafkaLog.partition,
+   *     offset: kafkaLog.offset,
+   *   },
+   * });
+   * ```
+   *
+   * @param record Log record without category field (category comes from
+   *               the logger instance)
+   * @since 1.1.0
+   */
+  emit(record: Omit<LogRecord, "category">): 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.
+ */
+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.
+ */
+type LogTemplatePrefix = (message: TemplateStringsArray, ...values: unknown[]) => unknown[];
+/**
+ * A function type for logging methods in the {@link Logger} interface.
+ * @since 1.0.0
+ */
+//#endregion
+export { Logger as t };