@logtape/logtape 0.11.0 → 0.12.0-dev.181

package/dist/config.js

@@ -0,0 +1,241 @@
+import { toFilter } from "./filter.js";
+import { LoggerImpl } from "./logger.js";
+import { getConsoleSink } from "./sink.js";
+
+//#region config.ts
+/**
+* The current configuration, if any.  Otherwise, `null`.
+*/
+let currentConfig = null;
+/**
+* Strong references to the loggers.
+* This is to prevent the loggers from being garbage collected so that their
+* sinks and filters are not removed.
+*/
+const strongRefs = /* @__PURE__ */ new Set();
+/**
+* Disposables to dispose when resetting the configuration.
+*/
+const disposables = /* @__PURE__ */ new Set();
+/**
+* Async disposables to dispose when resetting the configuration.
+*/
+const asyncDisposables = /* @__PURE__ */ new Set();
+/**
+* Check if a config is for the meta logger.
+*/
+function isLoggerConfigMeta(cfg) {
+	return cfg.category.length === 0 || cfg.category.length === 1 && cfg.category[0] === "logtape" || cfg.category.length === 2 && cfg.category[0] === "logtape" && cfg.category[1] === "meta";
+}
+/**
+* Configure the loggers with the specified configuration.
+*
+* Note that if the given sinks or filters are disposable, they will be
+* disposed when the configuration is reset, or when the process exits.
+*
+* @example
+* ```typescript
+* await configure({
+*   sinks: {
+*     console: getConsoleSink(),
+*   },
+*   filters: {
+*     slow: (log) =>
+*       "duration" in log.properties &&
+*       log.properties.duration as number > 1000,
+*   },
+*   loggers: [
+*     {
+*       category: "my-app",
+*       sinks: ["console"],
+*       level: "info",
+*     },
+*     {
+*       category: ["my-app", "sql"],
+*       filters: ["slow"],
+*       level: "debug",
+*     },
+*     {
+*       category: "logtape",
+*       sinks: ["console"],
+*       level: "error",
+*     },
+*   ],
+* });
+* ```
+*
+* @param config The configuration.
+*/
+async function configure(config) {
+	if (currentConfig != null && !config.reset) throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+	await reset();
+	try {
+		configureInternal(config, true);
+	} catch (e) {
+		if (e instanceof ConfigError) await reset();
+		throw e;
+	}
+}
+/**
+* Configure sync loggers with the specified configuration.
+*
+* Note that if the given sinks or filters are disposable, they will be
+* disposed when the configuration is reset, or when the process exits.
+*
+* Also note that passing async sinks or filters will throw. If
+* necessary use {@link resetSync} or {@link disposeSync}.
+*
+* @example
+* ```typescript
+* configureSync({
+*   sinks: {
+*     console: getConsoleSink(),
+*   },
+*   loggers: [
+*     {
+*       category: "my-app",
+*       sinks: ["console"],
+*       level: "info",
+*     },
+*     {
+*       category: "logtape",
+*       sinks: ["console"],
+*       level: "error",
+*     },
+*   ],
+* });
+* ```
+*
+* @param config The configuration.
+* @since 0.9.0
+*/
+function configureSync(config) {
+	if (currentConfig != null && !config.reset) throw new ConfigError("Already configured; if you want to reset, turn on the reset flag.");
+	if (asyncDisposables.size > 0) throw new ConfigError("Previously configured async disposables are still active. Use configure() instead or explicitly dispose them using dispose().");
+	resetSync();
+	try {
+		configureInternal(config, false);
+	} catch (e) {
+		if (e instanceof ConfigError) resetSync();
+		throw e;
+	}
+}
+function configureInternal(config, allowAsync) {
+	currentConfig = config;
+	let metaConfigured = false;
+	let levelUsed = false;
+	const configuredCategories = /* @__PURE__ */ new Set();
+	for (const cfg of config.loggers) {
+		if (isLoggerConfigMeta(cfg)) metaConfigured = true;
+		const categoryKey = Array.isArray(cfg.category) ? JSON.stringify(cfg.category) : JSON.stringify([cfg.category]);
+		if (configuredCategories.has(categoryKey)) throw new ConfigError(`Duplicate logger configuration for category: ${categoryKey}. Each category can only be configured once.`);
+		configuredCategories.add(categoryKey);
+		const logger = LoggerImpl.getLogger(cfg.category);
+		for (const sinkId of cfg.sinks ?? []) {
+			const sink = config.sinks[sinkId];
+			if (!sink) throw new ConfigError(`Sink not found: ${sinkId}.`);
+			logger.sinks.push(sink);
+		}
+		logger.parentSinks = cfg.parentSinks ?? "inherit";
+		if (cfg.lowestLevel !== void 0) logger.lowestLevel = cfg.lowestLevel;
+		if (cfg.level !== void 0) {
+			levelUsed = true;
+			logger.filters.push(toFilter(cfg.level));
+		}
+		for (const filterId of cfg.filters ?? []) {
+			const filter = config.filters?.[filterId];
+			if (filter === void 0) throw new ConfigError(`Filter not found: ${filterId}.`);
+			logger.filters.push(toFilter(filter));
+		}
+		strongRefs.add(logger);
+	}
+	LoggerImpl.getLogger().contextLocalStorage = config.contextLocalStorage;
+	for (const sink of Object.values(config.sinks)) {
+		if (Symbol.asyncDispose in sink) if (allowAsync) asyncDisposables.add(sink);
+		else throw new ConfigError("Async disposables cannot be used with configureSync().");
+		if (Symbol.dispose in sink) disposables.add(sink);
+	}
+	for (const filter of Object.values(config.filters ?? {})) {
+		if (filter == null || typeof filter === "string") continue;
+		if (Symbol.asyncDispose in filter) if (allowAsync) asyncDisposables.add(filter);
+		else throw new ConfigError("Async disposables cannot be used with configureSync().");
+		if (Symbol.dispose in filter) disposables.add(filter);
+	}
+	if ("process" in globalThis && !("Deno" in globalThis)) process.on("exit", allowAsync ? dispose : disposeSync);
+	else addEventListener("unload", allowAsync ? dispose : disposeSync);
+	const meta = LoggerImpl.getLogger(["logtape", "meta"]);
+	if (!metaConfigured) meta.sinks.push(getConsoleSink());
+	meta.info("LogTape loggers are configured.  Note that LogTape itself uses the meta logger, which has category {metaLoggerCategory}.  The meta logger purposes to log internal errors such as sink exceptions.  If you are seeing this message, the meta logger is automatically configured.  It's recommended to configure the meta logger with a separate sink so that you can easily notice if logging itself fails or is misconfigured.  To turn off this message, configure the meta logger with higher log levels than {dismissLevel}.  See also <https://logtape.org/manual/categories#meta-logger>.", {
+		metaLoggerCategory: ["logtape", "meta"],
+		dismissLevel: "info"
+	});
+	if (levelUsed) meta.warn("The level option is deprecated in favor of lowestLevel option.  Please update your configuration.  See also <https://logtape.org/manual/levels#configuring-severity-levels>.");
+}
+/**
+* Get the current configuration, if any.  Otherwise, `null`.
+* @returns The current configuration, if any.  Otherwise, `null`.
+*/
+function getConfig() {
+	return currentConfig;
+}
+/**
+* Reset the configuration.  Mostly for testing purposes.
+*/
+async function reset() {
+	await dispose();
+	resetInternal();
+}
+/**
+* Reset the configuration.  Mostly for testing purposes. Will not clear async
+* sinks, only use with sync sinks. Use {@link reset} if you have async sinks.
+* @since 0.9.0
+*/
+function resetSync() {
+	disposeSync();
+	resetInternal();
+}
+function resetInternal() {
+	const rootLogger = LoggerImpl.getLogger([]);
+	rootLogger.resetDescendants();
+	delete rootLogger.contextLocalStorage;
+	strongRefs.clear();
+	currentConfig = null;
+}
+/**
+* Dispose of the disposables.
+*/
+async function dispose() {
+	disposeSync();
+	const promises = [];
+	for (const disposable of asyncDisposables) {
+		promises.push(disposable[Symbol.asyncDispose]());
+		asyncDisposables.delete(disposable);
+	}
+	await Promise.all(promises);
+}
+/**
+* Dispose of the sync disposables. Async disposables will be untouched,
+* use {@link dispose} if you have async sinks.
+* @since 0.9.0
+*/
+function disposeSync() {
+	for (const disposable of disposables) disposable[Symbol.dispose]();
+	disposables.clear();
+}
+/**
+* A configuration error.
+*/
+var ConfigError = class extends Error {
+	/**
+	* Constructs a new configuration error.
+	* @param message The error message.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "ConfigureError";
+	}
+};
+
+//#endregion
+export { ConfigError, configure, configureSync, dispose, disposeSync, getConfig, reset, resetSync };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["currentConfig: Config<string, string> | null","strongRefs: Set<LoggerImpl>","disposables: Set<Disposable>","asyncDisposables: Set<AsyncDisposable>","cfg: LoggerConfig<TSinkId, TFilterId>","config: Config<TSinkId, TFilterId>","allowAsync: boolean","promises: PromiseLike<void>[]","message: string"],"sources":["../config.ts"],"sourcesContent":["import type { ContextLocalStorage } from \"./context.ts\";\nimport { type FilterLike, toFilter } from \"./filter.ts\";\nimport type { LogLevel } from \"./level.ts\";\nimport { LoggerImpl } from \"./logger.ts\";\nimport { getConsoleSink, type Sink } from \"./sink.ts\";\n\n/**\n * A configuration for the loggers.\n */\nexport interface Config<TSinkId extends string, TFilterId extends string> {\n  /**\n   * The sinks to use.  The keys are the sink identifiers, and the values are\n   * {@link Sink}s.\n   */\n  sinks: Record<TSinkId, Sink>;\n  /**\n   * The filters to use.  The keys are the filter identifiers, and the values\n   * are either {@link Filter}s or {@link LogLevel}s.\n   */\n  filters?: Record<TFilterId, FilterLike>;\n\n  /**\n   * The loggers to configure.\n   */\n  loggers: LoggerConfig<TSinkId, TFilterId>[];\n\n  /**\n   * The context-local storage to use for implicit contexts.\n   * @since 0.7.0\n   */\n  contextLocalStorage?: ContextLocalStorage<Record<string, unknown>>;\n\n  /**\n   * Whether to reset the configuration before applying this one.\n   */\n  reset?: boolean;\n}\n\n/**\n * A logger configuration.\n */\nexport interface LoggerConfig<\n  TSinkId extends string,\n  TFilterId extends string,\n> {\n  /**\n   * The category of the logger.  If a string, it is equivalent to an array\n   * with one element.\n   */\n  category: string | string[];\n\n  /**\n   * The sink identifiers to use.\n   */\n  sinks?: TSinkId[];\n\n  /**\n   * Whether to inherit the parent's sinks.  If `inherit`, the parent's sinks\n   * are used along with the specified sinks.  If `override`, the parent's\n   * sinks are not used, and only the specified sinks are used.\n   *\n   * The default is `inherit`.\n   * @default `\"inherit\"\n   * @since 0.6.0\n   */\n  parentSinks?: \"inherit\" | \"override\";\n\n  /**\n   * The filter identifiers to use.\n   */\n  filters?: TFilterId[];\n\n  /**\n   * The log level to filter by.  If `null`, the logger will reject all\n   * records.\n   * @deprecated Use `filters` instead for backward compatibility, or use\n   *             `lowestLevel` for less-misleading behavior.\n   */\n  level?: LogLevel | null;\n\n  /**\n   * The lowest log level to accept.  If `null`, the logger will reject all\n   * records.\n   * @since 0.8.0\n   */\n  lowestLevel?: LogLevel | null;\n}\n\n/**\n * The current configuration, if any.  Otherwise, `null`.\n */\nlet currentConfig: Config<string, string> | null = null;\n\n/**\n * Strong references to the loggers.\n * This is to prevent the loggers from being garbage collected so that their\n * sinks and filters are not removed.\n */\nconst strongRefs: Set<LoggerImpl> = new Set();\n\n/**\n * Disposables to dispose when resetting the configuration.\n */\nconst disposables: Set<Disposable> = new Set();\n\n/**\n * Async disposables to dispose when resetting the configuration.\n */\nconst asyncDisposables: Set<AsyncDisposable> = new Set();\n\n/**\n * Check if a config is for the meta logger.\n */\nfunction isLoggerConfigMeta<TSinkId extends string, TFilterId extends string>(\n  cfg: LoggerConfig<TSinkId, TFilterId>,\n): boolean {\n  return cfg.category.length === 0 ||\n    (cfg.category.length === 1 && cfg.category[0] === \"logtape\") ||\n    (cfg.category.length === 2 &&\n      cfg.category[0] === \"logtape\" &&\n      cfg.category[1] === \"meta\");\n}\n\n/**\n * Configure the loggers with the specified configuration.\n *\n * Note that if the given sinks or filters are disposable, they will be\n * disposed when the configuration is reset, or when the process exits.\n *\n * @example\n * ```typescript\n * await configure({\n *   sinks: {\n *     console: getConsoleSink(),\n *   },\n *   filters: {\n *     slow: (log) =>\n *       \"duration\" in log.properties &&\n *       log.properties.duration as number > 1000,\n *   },\n *   loggers: [\n *     {\n *       category: \"my-app\",\n *       sinks: [\"console\"],\n *       level: \"info\",\n *     },\n *     {\n *       category: [\"my-app\", \"sql\"],\n *       filters: [\"slow\"],\n *       level: \"debug\",\n *     },\n *     {\n *       category: \"logtape\",\n *       sinks: [\"console\"],\n *       level: \"error\",\n *     },\n *   ],\n * });\n * ```\n *\n * @param config The configuration.\n */\nexport async function configure<\n  TSinkId extends string,\n  TFilterId extends string,\n>(config: Config<TSinkId, TFilterId>): Promise<void> {\n  if (currentConfig != null && !config.reset) {\n    throw new ConfigError(\n      \"Already configured; if you want to reset, turn on the reset flag.\",\n    );\n  }\n  await reset();\n  try {\n    configureInternal(config, true);\n  } catch (e) {\n    if (e instanceof ConfigError) await reset();\n    throw e;\n  }\n}\n\n/**\n * Configure sync loggers with the specified configuration.\n *\n * Note that if the given sinks or filters are disposable, they will be\n * disposed when the configuration is reset, or when the process exits.\n *\n * Also note that passing async sinks or filters will throw. If\n * necessary use {@link resetSync} or {@link disposeSync}.\n *\n * @example\n * ```typescript\n * configureSync({\n *   sinks: {\n *     console: getConsoleSink(),\n *   },\n *   loggers: [\n *     {\n *       category: \"my-app\",\n *       sinks: [\"console\"],\n *       level: \"info\",\n *     },\n *     {\n *       category: \"logtape\",\n *       sinks: [\"console\"],\n *       level: \"error\",\n *     },\n *   ],\n * });\n * ```\n *\n * @param config The configuration.\n * @since 0.9.0\n */\nexport function configureSync<TSinkId extends string, TFilterId extends string>(\n  config: Config<TSinkId, TFilterId>,\n): void {\n  if (currentConfig != null && !config.reset) {\n    throw new ConfigError(\n      \"Already configured; if you want to reset, turn on the reset flag.\",\n    );\n  }\n  if (asyncDisposables.size > 0) {\n    throw new ConfigError(\n      \"Previously configured async disposables are still active. \" +\n        \"Use configure() instead or explicitly dispose them using dispose().\",\n    );\n  }\n  resetSync();\n  try {\n    configureInternal(config, false);\n  } catch (e) {\n    if (e instanceof ConfigError) resetSync();\n    throw e;\n  }\n}\n\nfunction configureInternal<\n  TSinkId extends string,\n  TFilterId extends string,\n>(config: Config<TSinkId, TFilterId>, allowAsync: boolean): void {\n  currentConfig = config;\n\n  let metaConfigured = false;\n  let levelUsed = false;\n  const configuredCategories = new Set<string>();\n\n  for (const cfg of config.loggers) {\n    if (isLoggerConfigMeta(cfg)) {\n      metaConfigured = true;\n    }\n\n    // Check for duplicate logger categories\n    const categoryKey = Array.isArray(cfg.category)\n      ? JSON.stringify(cfg.category)\n      : JSON.stringify([cfg.category]);\n    if (configuredCategories.has(categoryKey)) {\n      throw new ConfigError(\n        `Duplicate logger configuration for category: ${categoryKey}. ` +\n          `Each category can only be configured once.`,\n      );\n    }\n    configuredCategories.add(categoryKey);\n\n    const logger = LoggerImpl.getLogger(cfg.category);\n    for (const sinkId of cfg.sinks ?? []) {\n      const sink = config.sinks[sinkId];\n      if (!sink) {\n        throw new ConfigError(`Sink not found: ${sinkId}.`);\n      }\n      logger.sinks.push(sink);\n    }\n    logger.parentSinks = cfg.parentSinks ?? \"inherit\";\n    if (cfg.lowestLevel !== undefined) {\n      logger.lowestLevel = cfg.lowestLevel;\n    }\n    if (cfg.level !== undefined) {\n      levelUsed = true;\n      logger.filters.push(toFilter(cfg.level));\n    }\n    for (const filterId of cfg.filters ?? []) {\n      const filter = config.filters?.[filterId];\n      if (filter === undefined) {\n        throw new ConfigError(`Filter not found: ${filterId}.`);\n      }\n      logger.filters.push(toFilter(filter));\n    }\n    strongRefs.add(logger);\n  }\n\n  LoggerImpl.getLogger().contextLocalStorage = config.contextLocalStorage;\n\n  for (const sink of Object.values<Sink>(config.sinks)) {\n    if (Symbol.asyncDispose in sink) {\n      if (allowAsync) asyncDisposables.add(sink as AsyncDisposable);\n      else {\n        throw new ConfigError(\n          \"Async disposables cannot be used with configureSync().\",\n        );\n      }\n    }\n    if (Symbol.dispose in sink) disposables.add(sink as Disposable);\n  }\n\n  for (const filter of Object.values<FilterLike>(config.filters ?? {})) {\n    if (filter == null || typeof filter === \"string\") continue;\n    if (Symbol.asyncDispose in filter) {\n      if (allowAsync) asyncDisposables.add(filter as AsyncDisposable);\n      else {\n        throw new ConfigError(\n          \"Async disposables cannot be used with configureSync().\",\n        );\n      }\n    }\n    if (Symbol.dispose in filter) disposables.add(filter as Disposable);\n  }\n\n  if (\"process\" in globalThis && !(\"Deno\" in globalThis)) {\n    // @ts-ignore: It's fine to use process in Node\n    // deno-lint-ignore no-process-global\n    process.on(\"exit\", allowAsync ? dispose : disposeSync);\n  } else {\n    // @ts-ignore: It's fine to addEventListener() on the browser/Deno\n    addEventListener(\"unload\", allowAsync ? dispose : disposeSync);\n  }\n  const meta = LoggerImpl.getLogger([\"logtape\", \"meta\"]);\n  if (!metaConfigured) {\n    meta.sinks.push(getConsoleSink());\n  }\n\n  meta.info(\n    \"LogTape loggers are configured.  Note that LogTape itself uses the meta \" +\n      \"logger, which has category {metaLoggerCategory}.  The meta logger \" +\n      \"purposes to log internal errors such as sink exceptions.  If you \" +\n      \"are seeing this message, the meta logger is automatically configured.  \" +\n      \"It's recommended to configure the meta logger with a separate sink \" +\n      \"so that you can easily notice if logging itself fails or is \" +\n      \"misconfigured.  To turn off this message, configure the meta logger \" +\n      \"with higher log levels than {dismissLevel}.  See also \" +\n      \"<https://logtape.org/manual/categories#meta-logger>.\",\n    { metaLoggerCategory: [\"logtape\", \"meta\"], dismissLevel: \"info\" },\n  );\n\n  if (levelUsed) {\n    meta.warn(\n      \"The level option is deprecated in favor of lowestLevel option.  \" +\n        \"Please update your configuration.  See also \" +\n        \"<https://logtape.org/manual/levels#configuring-severity-levels>.\",\n    );\n  }\n}\n\n/**\n * Get the current configuration, if any.  Otherwise, `null`.\n * @returns The current configuration, if any.  Otherwise, `null`.\n */\nexport function getConfig(): Config<string, string> | null {\n  return currentConfig;\n}\n\n/**\n * Reset the configuration.  Mostly for testing purposes.\n */\nexport async function reset(): Promise<void> {\n  await dispose();\n  resetInternal();\n}\n\n/**\n * Reset the configuration.  Mostly for testing purposes. Will not clear async\n * sinks, only use with sync sinks. Use {@link reset} if you have async sinks.\n * @since 0.9.0\n */\nexport function resetSync(): void {\n  disposeSync();\n  resetInternal();\n}\n\nfunction resetInternal(): void {\n  const rootLogger = LoggerImpl.getLogger([]);\n  rootLogger.resetDescendants();\n  delete rootLogger.contextLocalStorage;\n  strongRefs.clear();\n  currentConfig = null;\n}\n\n/**\n * Dispose of the disposables.\n */\nexport async function dispose(): Promise<void> {\n  disposeSync();\n  const promises: PromiseLike<void>[] = [];\n  for (const disposable of asyncDisposables) {\n    promises.push(disposable[Symbol.asyncDispose]());\n    asyncDisposables.delete(disposable);\n  }\n  await Promise.all(promises);\n}\n\n/**\n * Dispose of the sync disposables. Async disposables will be untouched,\n * use {@link dispose} if you have async sinks.\n * @since 0.9.0\n */\nexport function disposeSync(): void {\n  for (const disposable of disposables) disposable[Symbol.dispose]();\n  disposables.clear();\n}\n\n/**\n * A configuration error.\n */\nexport class ConfigError extends Error {\n  /**\n   * Constructs a new configuration error.\n   * @param message The error message.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"ConfigureError\";\n  }\n}\n"],"mappings":"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"}

package/dist/context.cjs

@@ -0,0 +1,30 @@
+const require_logger = require('./logger.cjs');
+
+//#region context.ts
+/**
+* Runs a callback with the given implicit context.  Every single log record
+* in the callback will have the given context.
+*
+* If no `contextLocalStorage` is configured, this function does nothing and
+* just returns the return value of the callback.  It also logs a warning to
+* the `["logtape", "meta"]` logger in this case.
+* @param context The context to inject.
+* @param callback The callback to run.
+* @returns The return value of the callback.
+* @since 0.7.0
+*/
+function withContext(context, callback) {
+	const rootLogger = require_logger.LoggerImpl.getLogger();
+	if (rootLogger.contextLocalStorage == null) {
+		require_logger.LoggerImpl.getLogger(["logtape", "meta"]).warn("Context-local storage is not configured.  Specify contextLocalStorage option in the configure() function.");
+		return callback();
+	}
+	const parentContext = rootLogger.contextLocalStorage.getStore() ?? {};
+	return rootLogger.contextLocalStorage.run({
+		...parentContext,
+		...context
+	}, callback);
+}
+
+//#endregion
+exports.withContext = withContext;

package/dist/context.d.cts

@@ -0,0 +1,39 @@
+//#region context.d.ts
+/**
+ * A generic interface for a context-local storage.  It resembles
+ * the {@link AsyncLocalStorage} API from Node.js.
+ * @typeParam T The type of the context-local store.
+ * @since 0.7.0
+ */
+interface ContextLocalStorage<T> {
+  /**
+   * Runs a callback with the given store as the context-local store.
+   * @param store The store to use as the context-local store.
+   * @param callback The callback to run.
+   * @returns The return value of the callback.
+   */
+  run<R>(store: T, callback: () => R): R;
+  /**
+   * Returns the current context-local store.
+   * @returns The current context-local store, or `undefined` if there is no
+   *          store.
+   */
+  getStore(): T | undefined;
+}
+/**
+ * Runs a callback with the given implicit context.  Every single log record
+ * in the callback will have the given context.
+ *
+ * If no `contextLocalStorage` is configured, this function does nothing and
+ * just returns the return value of the callback.  It also logs a warning to
+ * the `["logtape", "meta"]` logger in this case.
+ * @param context The context to inject.
+ * @param callback The callback to run.
+ * @returns The return value of the callback.
+ * @since 0.7.0
+ */
+declare function withContext<T>(context: Record<string, unknown>, callback: () => T): T;
+//# sourceMappingURL=context.d.ts.map
+//#endregion
+export { ContextLocalStorage, withContext };
+//# sourceMappingURL=context.d.cts.map

package/dist/context.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.cts","names":[],"sources":["../context.ts"],"sourcesContent":[],"mappings":";;AAQA;;;;;AAcc,UAdG,mBAcH,CAAA,CAAA,CAAA,CAAA;EAAC;AAef;;;;;EAGI,GAAA,CAAA,CAAA,CAAA,CAAA,KAAA,EAzBY,CAyBZ,EAAA,QAAA,EAAA,GAAA,GAzB+B,CAyB/B,CAAA,EAzBmC,CAyBnC;;;;;;cAlBU;;;;;;;;;;;;;;iBAeE,wBACL,yCACO,IACf"}

package/dist/context.d.ts

@@ -0,0 +1,39 @@
+//#region context.d.ts
+/**
+ * A generic interface for a context-local storage.  It resembles
+ * the {@link AsyncLocalStorage} API from Node.js.
+ * @typeParam T The type of the context-local store.
+ * @since 0.7.0
+ */
+interface ContextLocalStorage<T> {
+  /**
+   * Runs a callback with the given store as the context-local store.
+   * @param store The store to use as the context-local store.
+   * @param callback The callback to run.
+   * @returns The return value of the callback.
+   */
+  run<R>(store: T, callback: () => R): R;
+  /**
+   * Returns the current context-local store.
+   * @returns The current context-local store, or `undefined` if there is no
+   *          store.
+   */
+  getStore(): T | undefined;
+}
+/**
+ * Runs a callback with the given implicit context.  Every single log record
+ * in the callback will have the given context.
+ *
+ * If no `contextLocalStorage` is configured, this function does nothing and
+ * just returns the return value of the callback.  It also logs a warning to
+ * the `["logtape", "meta"]` logger in this case.
+ * @param context The context to inject.
+ * @param callback The callback to run.
+ * @returns The return value of the callback.
+ * @since 0.7.0
+ */
+declare function withContext<T>(context: Record<string, unknown>, callback: () => T): T;
+//# sourceMappingURL=context.d.ts.map
+//#endregion
+export { ContextLocalStorage, withContext };
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","names":[],"sources":["../context.ts"],"sourcesContent":[],"mappings":";;AAQA;;;;;AAcc,UAdG,mBAcH,CAAA,CAAA,CAAA,CAAA;EAAC;AAef;;;;;EAGI,GAAA,CAAA,CAAA,CAAA,CAAA,KAAA,EAzBY,CAyBZ,EAAA,QAAA,EAAA,GAAA,GAzB+B,CAyB/B,CAAA,EAzBmC,CAyBnC;;;;;;cAlBU;;;;;;;;;;;;;;iBAeE,wBACL,yCACO,IACf"}

package/dist/context.js

@@ -0,0 +1,31 @@
+import { LoggerImpl } from "./logger.js";
+
+//#region context.ts
+/**
+* Runs a callback with the given implicit context.  Every single log record
+* in the callback will have the given context.
+*
+* If no `contextLocalStorage` is configured, this function does nothing and
+* just returns the return value of the callback.  It also logs a warning to
+* the `["logtape", "meta"]` logger in this case.
+* @param context The context to inject.
+* @param callback The callback to run.
+* @returns The return value of the callback.
+* @since 0.7.0
+*/
+function withContext(context, callback) {
+	const rootLogger = LoggerImpl.getLogger();
+	if (rootLogger.contextLocalStorage == null) {
+		LoggerImpl.getLogger(["logtape", "meta"]).warn("Context-local storage is not configured.  Specify contextLocalStorage option in the configure() function.");
+		return callback();
+	}
+	const parentContext = rootLogger.contextLocalStorage.getStore() ?? {};
+	return rootLogger.contextLocalStorage.run({
+		...parentContext,
+		...context
+	}, callback);
+}
+
+//#endregion
+export { withContext };
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","names":["context: Record<string, unknown>","callback: () => T"],"sources":["../context.ts"],"sourcesContent":["import { LoggerImpl } from \"./logger.ts\";\n\n/**\n * A generic interface for a context-local storage.  It resembles\n * the {@link AsyncLocalStorage} API from Node.js.\n * @typeParam T The type of the context-local store.\n * @since 0.7.0\n */\nexport interface ContextLocalStorage<T> {\n  /**\n   * Runs a callback with the given store as the context-local store.\n   * @param store The store to use as the context-local store.\n   * @param callback The callback to run.\n   * @returns The return value of the callback.\n   */\n  run<R>(store: T, callback: () => R): R;\n\n  /**\n   * Returns the current context-local store.\n   * @returns The current context-local store, or `undefined` if there is no\n   *          store.\n   */\n  getStore(): T | undefined;\n}\n\n/**\n * Runs a callback with the given implicit context.  Every single log record\n * in the callback will have the given context.\n *\n * If no `contextLocalStorage` is configured, this function does nothing and\n * just returns the return value of the callback.  It also logs a warning to\n * the `[\"logtape\", \"meta\"]` logger in this case.\n * @param context The context to inject.\n * @param callback The callback to run.\n * @returns The return value of the callback.\n * @since 0.7.0\n */\nexport function withContext<T>(\n  context: Record<string, unknown>,\n  callback: () => T,\n): T {\n  const rootLogger = LoggerImpl.getLogger();\n  if (rootLogger.contextLocalStorage == null) {\n    LoggerImpl.getLogger([\"logtape\", \"meta\"]).warn(\n      \"Context-local storage is not configured.  \" +\n        \"Specify contextLocalStorage option in the configure() function.\",\n    );\n    return callback();\n  }\n  const parentContext = rootLogger.contextLocalStorage.getStore() ?? {};\n  return rootLogger.contextLocalStorage.run(\n    { ...parentContext, ...context },\n    callback,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;AAqCA,SAAgB,YACdA,SACAC,UACG;CACH,MAAM,aAAa,WAAW,WAAW;AACzC,KAAI,WAAW,uBAAuB,MAAM;AAC1C,aAAW,UAAU,CAAC,WAAW,MAAO,EAAC,CAAC,KACxC,4GAED;AACD,SAAO,UAAU;CAClB;CACD,MAAM,gBAAgB,WAAW,oBAAoB,UAAU,IAAI,CAAE;AACrE,QAAO,WAAW,oBAAoB,IACpC;EAAE,GAAG;EAAe,GAAG;CAAS,GAChC,SACD;AACF"}

package/dist/filter.cjs

@@ -0,0 +1,32 @@
+
+//#region filter.ts
+/**
+* Converts a {@link FilterLike} value to an actual {@link Filter}.
+*
+* @param filter The filter-like value to convert.
+* @returns The actual filter.
+*/
+function toFilter(filter) {
+	if (typeof filter === "function") return filter;
+	return getLevelFilter(filter);
+}
+/**
+* Returns a filter that accepts log records with the specified level.
+*
+* @param level The level to filter by.  If `null`, the filter will reject all
+*              records.
+* @returns The filter.
+*/
+function getLevelFilter(level) {
+	if (level == null) return () => false;
+	if (level === "fatal") return (record) => record.level === "fatal";
+	else if (level === "error") return (record) => record.level === "fatal" || record.level === "error";
+	else if (level === "warning") return (record) => record.level === "fatal" || record.level === "error" || record.level === "warning";
+	else if (level === "info") return (record) => record.level === "fatal" || record.level === "error" || record.level === "warning" || record.level === "info";
+	else if (level === "debug") return () => true;
+	throw new TypeError(`Invalid log level: ${level}.`);
+}
+
+//#endregion
+exports.getLevelFilter = getLevelFilter;
+exports.toFilter = toFilter;

package/dist/filter.d.cts

@@ -0,0 +1,37 @@
+import { LogLevel } from "./level.cjs";
+import { LogRecord } from "./record.cjs";
+
+//#region filter.d.ts
+
+/**
+ * A filter is a function that accepts a log record and returns `true` if the
+ * record should be passed to the sink.
+ *
+ * @param record The log record to filter.
+ * @returns `true` if the record should be passed to the sink.
+ */
+type Filter = (record: LogRecord) => boolean;
+/**
+ * A filter-like value is either a {@link Filter} or a {@link LogLevel}.
+ * `null` is also allowed to represent a filter that rejects all records.
+ */
+type FilterLike = Filter | LogLevel | null;
+/**
+ * Converts a {@link FilterLike} value to an actual {@link Filter}.
+ *
+ * @param filter The filter-like value to convert.
+ * @returns The actual filter.
+ */
+declare function toFilter(filter: FilterLike): Filter;
+/**
+ * Returns a filter that accepts log records with the specified level.
+ *
+ * @param level The level to filter by.  If `null`, the filter will reject all
+ *              records.
+ * @returns The filter.
+ */
+declare function getLevelFilter(level: LogLevel | null): Filter;
+//# sourceMappingURL=filter.d.ts.map
+//#endregion
+export { Filter, FilterLike, getLevelFilter, toFilter };
+//# sourceMappingURL=filter.d.cts.map

package/dist/filter.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.cts","names":[],"sources":["../filter.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AAMA;;;;AAA0C,KAN9B,MAAA,GAM8B,CAAA,MAAA,EANZ,SAMY,EAAA,GAAA,OAAA;AAQ1C;;;;AAAoD,KARxC,UAAA,GAAa,MAQ2B,GARlB,QAQkB,GAAA,IAAA;AAYpD;;;;AAA8D;;iBAZ9C,QAAA,SAAiB,aAAa;;;;;;;;iBAY9B,cAAA,QAAsB,kBAAkB"}

package/{types → dist}/filter.d.ts

@@ -1,5 +1,8 @@
-import type { LogLevel } from "./level.js";
-import type { LogRecord } from "./record.js";
+import { LogLevel } from "./level.js";
+import { LogRecord } from "./record.js";
+
+//#region filter.d.ts
+
 /**
  * A filter is a function that accepts a log record and returns `true` if the
  * record should be passed to the sink.
@@ -7,19 +10,19 @@ import type { LogRecord } from "./record.js";
  * @param record The log record to filter.
  * @returns `true` if the record should be passed to the sink.
  */
-export type Filter = (record: LogRecord) => boolean;
+type Filter = (record: LogRecord) => boolean;
 /**
  * A filter-like value is either a {@link Filter} or a {@link LogLevel}.
  * `null` is also allowed to represent a filter that rejects all records.
  */
-export type FilterLike = Filter | LogLevel | null;
+type FilterLike = Filter | LogLevel | null;
 /**
  * Converts a {@link FilterLike} value to an actual {@link Filter}.
  *
  * @param filter The filter-like value to convert.
  * @returns The actual filter.
  */
-export declare function toFilter(filter: FilterLike): Filter;
+declare function toFilter(filter: FilterLike): Filter;
 /**
  * Returns a filter that accepts log records with the specified level.
  *
@@ -27,5 +30,8 @@ export declare function toFilter(filter: FilterLike): Filter;
  *              records.
  * @returns The filter.
  */
-export declare function getLevelFilter(level: LogLevel | null): Filter;
+declare function getLevelFilter(level: LogLevel | null): Filter;
+//# sourceMappingURL=filter.d.ts.map
+//#endregion
+export { Filter, FilterLike, getLevelFilter, toFilter };
 //# sourceMappingURL=filter.d.ts.map

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","names":[],"sources":["../filter.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AAMA;;;;AAA0C,KAN9B,MAAA,GAM8B,CAAA,MAAA,EANZ,SAMY,EAAA,GAAA,OAAA;AAQ1C;;;;AAAoD,KARxC,UAAA,GAAa,MAQ2B,GARlB,QAQkB,GAAA,IAAA;AAYpD;;;;AAA8D;;iBAZ9C,QAAA,SAAiB,aAAa;;;;;;;;iBAY9B,cAAA,QAAsB,kBAAkB"}

package/dist/filter.js

@@ -0,0 +1,31 @@
+//#region filter.ts
+/**
+* Converts a {@link FilterLike} value to an actual {@link Filter}.
+*
+* @param filter The filter-like value to convert.
+* @returns The actual filter.
+*/
+function toFilter(filter) {
+	if (typeof filter === "function") return filter;
+	return getLevelFilter(filter);
+}
+/**
+* Returns a filter that accepts log records with the specified level.
+*
+* @param level The level to filter by.  If `null`, the filter will reject all
+*              records.
+* @returns The filter.
+*/
+function getLevelFilter(level) {
+	if (level == null) return () => false;
+	if (level === "fatal") return (record) => record.level === "fatal";
+	else if (level === "error") return (record) => record.level === "fatal" || record.level === "error";
+	else if (level === "warning") return (record) => record.level === "fatal" || record.level === "error" || record.level === "warning";
+	else if (level === "info") return (record) => record.level === "fatal" || record.level === "error" || record.level === "warning" || record.level === "info";
+	else if (level === "debug") return () => true;
+	throw new TypeError(`Invalid log level: ${level}.`);
+}
+
+//#endregion
+export { getLevelFilter, toFilter };
+//# sourceMappingURL=filter.js.map

package/dist/filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.js","names":["filter: FilterLike","level: LogLevel | null","record: LogRecord"],"sources":["../filter.ts"],"sourcesContent":["import type { LogLevel } from \"./level.ts\";\nimport type { LogRecord } from \"./record.ts\";\n\n/**\n * A filter is a function that accepts a log record and returns `true` if the\n * record should be passed to the sink.\n *\n * @param record The log record to filter.\n * @returns `true` if the record should be passed to the sink.\n */\nexport type Filter = (record: LogRecord) => boolean;\n\n/**\n * A filter-like value is either a {@link Filter} or a {@link LogLevel}.\n * `null` is also allowed to represent a filter that rejects all records.\n */\nexport type FilterLike = Filter | LogLevel | null;\n\n/**\n * Converts a {@link FilterLike} value to an actual {@link Filter}.\n *\n * @param filter The filter-like value to convert.\n * @returns The actual filter.\n */\nexport function toFilter(filter: FilterLike): Filter {\n  if (typeof filter === \"function\") return filter;\n  return getLevelFilter(filter);\n}\n\n/**\n * Returns a filter that accepts log records with the specified level.\n *\n * @param level The level to filter by.  If `null`, the filter will reject all\n *              records.\n * @returns The filter.\n */\nexport function getLevelFilter(level: LogLevel | null): Filter {\n  if (level == null) return () => false;\n  if (level === \"fatal\") {\n    return (record: LogRecord) => record.level === \"fatal\";\n  } else if (level === \"error\") {\n    return (record: LogRecord) =>\n      record.level === \"fatal\" || record.level === \"error\";\n  } else if (level === \"warning\") {\n    return (record: LogRecord) =>\n      record.level === \"fatal\" ||\n      record.level === \"error\" ||\n      record.level === \"warning\";\n  } else if (level === \"info\") {\n    return (record: LogRecord) =>\n      record.level === \"fatal\" ||\n      record.level === \"error\" ||\n      record.level === \"warning\" ||\n      record.level === \"info\";\n  } else if (level === \"debug\") return () => true;\n  throw new TypeError(`Invalid log level: ${level}.`);\n}\n"],"mappings":";;;;;;;AAwBA,SAAgB,SAASA,QAA4B;AACnD,YAAW,WAAW,WAAY,QAAO;AACzC,QAAO,eAAe,OAAO;AAC9B;;;;;;;;AASD,SAAgB,eAAeC,OAAgC;AAC7D,KAAI,SAAS,KAAM,QAAO,MAAM;AAChC,KAAI,UAAU,QACZ,QAAO,CAACC,WAAsB,OAAO,UAAU;UACtC,UAAU,QACnB,QAAO,CAACA,WACN,OAAO,UAAU,WAAW,OAAO,UAAU;UACtC,UAAU,UACnB,QAAO,CAACA,WACN,OAAO,UAAU,WACjB,OAAO,UAAU,WACjB,OAAO,UAAU;UACV,UAAU,OACnB,QAAO,CAACA,WACN,OAAO,UAAU,WACjB,OAAO,UAAU,WACjB,OAAO,UAAU,aACjB,OAAO,UAAU;UACV,UAAU,QAAS,QAAO,MAAM;AAC3C,OAAM,IAAI,WAAW,qBAAqB,MAAM;AACjD"}