@logtape/logtape 1.4.0-dev.468 → 2.0.0-dev.470

package/dist/logger.d.ts

@@ -3,6 +3,50 @@ import { LogRecord } from "./record.js";
 
 //#region src/logger.d.ts
 
+/**
+ * Symbol to identify lazy values.
+ */
+declare const lazySymbol: unique symbol;
+/**
+ * A lazy value that is evaluated at logging time.
+ *
+ * @typeParam T The type of the value.
+ * @since 2.0.0
+ */
+interface Lazy<T> {
+  readonly [lazySymbol]: true;
+  readonly getter: () => T;
+}
+/**
+ * Checks if a value is a lazy value.
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a lazy value, `false` otherwise.
+ * @since 2.0.0
+ */
+declare function isLazy(value: unknown): value is Lazy<unknown>;
+/**
+ * Creates a lazy value that is evaluated at logging time.
+ *
+ * This is useful for logging contextual properties that may change over time,
+ * such as the current user or request context.
+ *
+ * @example
+ * ```typescript
+ * let currentUser: string | null = null;
+ * const logger = getLogger("app").with({ user: lazy(() => currentUser) });
+ *
+ * logger.info("User action");  // logs with user: null
+ * currentUser = "alice";
+ * logger.info("User action");  // logs with user: "alice"
+ * ```
+ *
+ * @typeParam T The type of the value.
+ * @param getter A function that returns the value.
+ * @returns A lazy value.
+ * @since 2.0.0
+ */
+declare function lazy<T>(getter: () => T): Lazy<T>;
 /**
  * A logger interface.  It provides methods to log messages at different
  * severity levels.
@@ -128,7 +172,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   trace(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -227,7 +271,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   debug(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -325,7 +369,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   info(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -386,7 +430,7 @@ interface Logger {
    * in the message template instead.
    *
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warn(error: Error): void;
   /**
@@ -398,7 +442,7 @@ interface Logger {
    *
    * @param message The message.
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warn(message: string, error: Error): void;
   /**
@@ -454,7 +498,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warn(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -515,7 +559,7 @@ interface Logger {
    * in the message template instead.
    *
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warning(error: Error): void;
   /**
@@ -527,7 +571,7 @@ interface Logger {
    *
    * @param message The message.
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warning(message: string, error: Error): void;
   /**
@@ -585,7 +629,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   warning(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -647,7 +691,7 @@ interface Logger {
    * in the message template instead.
    *
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   error(error: Error): void;
   /**
@@ -659,7 +703,7 @@ interface Logger {
    *
    * @param message The message.
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   error(message: string, error: Error): void;
   /**
@@ -715,7 +759,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   error(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -776,7 +820,7 @@ interface Logger {
    * in the message template instead.
    *
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   fatal(error: Error): void;
   /**
@@ -788,7 +832,7 @@ interface Logger {
    *
    * @param message The message.
    * @param error The error to log.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   fatal(message: string, error: Error): void;
   /**
@@ -844,7 +888,7 @@ interface Logger {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   fatal(message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -938,7 +982,7 @@ interface Logger {
    * @param level The log level to check.
    * @returns `true` if a message of the given level would be logged,
    *          `false` otherwise.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   isEnabledFor(level: LogLevel): boolean;
 }
@@ -985,7 +1029,7 @@ interface LogMethod {
    *                `{value}`).
    * @param properties An async callback that returns the properties.
    * @returns A promise that resolves when the log is written.
-   * @since 1.4.0
+   * @since 2.0.0
    */
   (message: string, properties: () => Promise<Record<string, unknown>>): Promise<void>;
   /**
@@ -1019,5 +1063,5 @@ declare function getLogger(category?: string | readonly string[]): Logger;
  * instead.  This class is exported for testing purposes.
  */
 //#endregion
-export { LogMethod, Logger, getLogger };
+export { Lazy, LogMethod, Logger, getLogger, isLazy, lazy };
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","names":[],"sources":["../src/logger.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AA4OiB,UApNA,MAAA,CAoNA;EAAM;;;EAwBM,SACxB,QAAA,EAAA,SAAA,MAAA,EAAA;EAAO;;;;EAoFW,SAA2B,MAAA,EAvT/B,MAuT+B,GAAA,IAAA;EAAM;;;;;;;;;;;;;;;;;;EAiQjB,QA6BtB,CAAA,WAAA,EAAA,MAAA,GAAA,SAAA,CAAA,MAAA,CAAA,GAAA,SAAA,CAAA,MAAA,EAAA,GAAA,MAAA,EAAA,CAAA,CAAA,EA/jBZ,MA+jBY;EAAM;;;;;;;;;;;;;;;;;;;;;;;;;;EAmWM,IA+BT,CAAA,UAAA,EAr6BD,MAq6BC,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,EAr6ByB,MAq6BzB;EAAS;;AAsBC;AAS9B;AASA;AASA;;;;;;EAoCoC,KAAd,CAAA,OAAA,EA7+BL,oBA6+BK,EAAA,GAAA,MAAA,EAAA,SAAA,OAAA,EAAA,CAAA,EAAA,IAAA;EAAO;;;AAeL;AAexB;;;;;;;;;;;;;;;;;;;;;sCA9+BiB,iCAAiC;;;;;;;;;;;;;;;;;;;;2CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+Be;;;;;;;;;;;;;kBAcF;;;;;;;;;;;iBAYD;;;;;;;;;;;;;;;;;;;;;;;;;sCA4BA,iCAAiC;;;;;;;;;;;;;;;;;;;;2CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+Be;;;;;;;;;;;;kBAaF;;;;;;;;;;;gBAYF;;;;;;;;;;;;;;;;;;;;;;;;;qCA4BC,iCAAiC;;;;;;;;;;;;;;;;;;;;0CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA+Bc;;;;;;;;;;;;;iBAcF;;;;;;;;;;;;;;;;;;cAmBH;;;;;;;;;;;;+BAaiB;;;;;;;;;;;gBAYf;;;;;;;;;;;;;;;;;;;;;;;;;qCA4BC,iCAAiC;;;;;;;;;;;;;;;;;;;;0CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBA+Bc;;;;;;;;;;;;;iBAcF;;;;;;;;;;;;;;;;;;iBAmBA;;;;;;;;;;;;kCAaiB;;;;;;;;;;;;mBAaf;;;;;;;;;;;;;;;;;;;;;;;;;;wCA6BF,iCAAiC;;;;;;;;;;;;;;;;;;;;6CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBA+BiB;;;;;;;;;;;;;;oBAeF;;;;;;;;;;;;;;;;;;eAmBL;;;;;;;;;;;;gCAaiB;;;;;;;;;;;iBAYf;;;;;;;;;;;;;;;;;;;;;;;;;sCA4BA,iCAAiC;;;;;;;;;;;;;;;;;;;;2CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+Be;;;;;;;;;;;;;kBAcF;;;;;;;;;;;;;;;;;;eAmBH;;;;;;;;;;;;gCAaiB;;;;;;;;;;;iBAYf;;;;;;;;;;;;;;;;;;;;;;;;;sCA4BA,iCAAiC;;;;;;;;;;;;;;;;;;;;2CAwB5B,QAAQ,2BACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBA+Be;;;;;;;;;;;;;kBAcF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eA+BH,KAAK;;;;;;;;;;;;;;;;;;;;;sBAsBE;;;;;;;;KASV,WAAA,YAAuB;;;;;;;;KASvB,iBAAA,aACD;;;;;UAQM,SAAA;;;;;;YAOJ;;;;;;;;;;iCAeI,iCAAiC;;;;;;;;;;sCAc5B,QAAQ,2BACzB;;;;;;eAOU;;;;;;aAOF;;;;;;;;;;;;;;iBAeG,SAAA,yCAAsD"}
+{"version":3,"file":"logger.d.ts","names":[],"sources":["../src/logger.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/logger.js

@@ -3,6 +3,61 @@ import { compareLogLevel } from "./level.js";
 
 //#region src/logger.ts
 /**
+* Symbol to identify lazy values.
+*/
+const lazySymbol = Symbol.for("logtape.lazy");
+/**
+* Checks if a value is a lazy value.
+*
+* @param value The value to check.
+* @returns `true` if the value is a lazy value, `false` otherwise.
+* @since 2.0.0
+*/
+function isLazy(value) {
+	return value != null && typeof value === "object" && lazySymbol in value && value[lazySymbol] === true;
+}
+/**
+* Creates a lazy value that is evaluated at logging time.
+*
+* This is useful for logging contextual properties that may change over time,
+* such as the current user or request context.
+*
+* @example
+* ```typescript
+* let currentUser: string | null = null;
+* const logger = getLogger("app").with({ user: lazy(() => currentUser) });
+*
+* logger.info("User action");  // logs with user: null
+* currentUser = "alice";
+* logger.info("User action");  // logs with user: "alice"
+* ```
+*
+* @typeParam T The type of the value.
+* @param getter A function that returns the value.
+* @returns A lazy value.
+* @since 2.0.0
+*/
+function lazy(getter) {
+	return {
+		[lazySymbol]: true,
+		getter
+	};
+}
+/**
+* Resolves lazy values in a properties object.
+*
+* @param properties The properties object with potential lazy values.
+* @returns A new object with all lazy values resolved.
+*/
+function resolveProperties(properties) {
+	const resolved = {};
+	for (const key in properties) {
+		const value = properties[key];
+		resolved[key] = isLazy(value) ? value.getter() : value;
+	}
+	return resolved;
+}
+/**
 * Get a logger with the given category.
 *
 * ```typescript
@@ -417,27 +472,28 @@ var LoggerCtx = class LoggerCtx {
 		});
 	}
 	log(level, message, properties, bypassSinks) {
-		this.logger.log(level, message, typeof properties === "function" ? () => ({
-			...this.properties,
+		const contextProps = this.properties;
+		this.logger.log(level, message, typeof properties === "function" ? () => resolveProperties({
+			...contextProps,
 			...properties()
-		}) : {
-			...this.properties,
+		}) : () => resolveProperties({
+			...contextProps,
 			...properties
-		}, bypassSinks);
+		}), bypassSinks);
 	}
 	logLazily(level, callback) {
-		this.logger.logLazily(level, callback, this.properties);
+		this.logger.logLazily(level, callback, resolveProperties(this.properties));
 	}
 	logTemplate(level, messageTemplate, values) {
-		this.logger.logTemplate(level, messageTemplate, values, this.properties);
+		this.logger.logTemplate(level, messageTemplate, values, resolveProperties(this.properties));
 	}
 	emit(record) {
 		const recordWithContext = {
 			...record,
-			properties: {
+			properties: resolveProperties({
 				...this.properties,
 				...record.properties
-			}
+			})
 		};
 		this.logger.emit(recordWithContext);
 	}
@@ -908,5 +964,5 @@ function renderMessage(template, values) {
 }
 
 //#endregion
-export { LoggerImpl, getLogger };
+export { LoggerImpl, getLogger, isLazy, lazy };
 //# sourceMappingURL=logger.js.map