@holz/core 0.8.3-rc.154 → 0.8.3-rc.155

package/dist/{src/types.d.ts → holz-core.d.ts}

@@ -1,116 +1,152 @@
-/**
- * A logger is made up of log processors. These processors take structured
- * logs and do something with them. Examples are logging backends (console,
- * file, uploads) and operators (filtering, transforming, aggregating).
- */
-export interface LogProcessor {
-    /** Do something with a log message. */
-    (log: Log): unknown;
-}
-/** A log message where variables are carried as structured data. */
-export interface Log {
-    /** Unix timestamp. Includes milliseconds. */
-    readonly timestamp: number;
-    /** The verbatim log message. Should not contain interpolated data. */
-    readonly message: string;
-    /** Log severity. One of `levels.*`. */
-    readonly level: LogLevel;
-    /**
-     * Where the log message originated. Usually starts with a library or app name,
-     * followed by something more specific.
-     *
-     * @example ['logger-library', 'ConsoleBackend']
-     */
-    readonly origin: ReadonlyArray<string>;
-    /**
-     * Key-value pairs that provide additional context for the log message. If
-     * you're tempted to interpolate data into the message, consider using log
-     * context instead.
-     *
-     * These values must be JSON serializable.
-     *
-     * Because it's easy to accidentally include unsuitable log context (e.g.
-     * redux state, PII) nested objects are not allowed. The restriction doesn't
-     * make it impossible, but it makes it harder to miss during code review.
-     *
-     * @example { userId: 123, reason: 'disconnect' }
-     */
-    readonly context: LogContext;
-}
-export declare const level: {
-    /** A critical failure happened and the program must exit. */
-    readonly fatal: 60;
-    /** Something failed, but we can keep going. */
-    readonly error: 50;
-    /** Cause for concern, but we can keep going. */
-    readonly warn: 40;
-    /** High-level progress updates. */
-    readonly info: 30;
-    /** Verbose update about events or control flow (usually hidden). */
-    readonly debug: 20;
-    /** Extremely detailed progress updates (usually hidden). */
-    readonly trace: 10;
-};
-export type LogLevel = (typeof level)[keyof typeof level];
-type JsonPrimitive = string | number | boolean | null | undefined;
-export interface JsonContext {
-    [key: string]: JsonPrimitive | ReadonlyArray<JsonPrimitive>;
-}
-/**
- * Custom values allowed in log context. These values don't have to be JSON.
- * The most common case is errors, which support richer error tracking in
- * backends that support it.
- *
- * This is part of the public API. Backends may use declaration merging to
- * extend the standard attributes. It's recommended to use symbols as keys for
- * custom features, but not required.
- */
-export interface CustomContext {
-    /**
-     * Error instance associated with the log message. This supports error
-     * tracking and shows prominently in visual backends like TTY output.
-     */
-    error: Error;
-}
-/**
- * A type narrowing constraint designed for generic constraints. Controls
- * what fields are allowed in `log.context`, sourcing from `CustomContext`
- * first, then falling back to any JSON value.
- */
-export type StrictContext<Input> = {
-    [Key in keyof Input]: Key extends keyof CustomContext ? CustomContext[Key] : JsonPrimitive | ReadonlyArray<JsonPrimitive>;
-};
-/**
- * A more general type expected by logging backends. Supports type narrowing,
- * so if a known field exists, it will be used instead of the generic JSON
- * type.
- */
-export type LogContext = Partial<CustomContext> & JsonContext;
-/**
- * This is the public API which generates and sends `Log` events through the
- * user-defined processing pipeline.
- */
-export interface Logger {
-    readonly owner: ReadonlyArray<string>;
-    /** Extend the logger to attach a class or module name to logs. */
-    namespace: (owner: string) => Logger;
-    /**
-     * Create a new logger which runs all logs through a middleware function.
-     * Useful for adding default context, doing ad-hoc filtering, or
-     * registering plugins. Only applies to this logger and its descendants.
-     */
-    withMiddleware: (middleware: (next: LogProcessor) => LogProcessor) => Logger;
-    /** Log a verbose and frequent update. */
-    trace: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-    /** Log a frequent and verbose progress update. */
-    debug: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-    /** Log a high-level progress update. */
-    info: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-    /** Log something concerning. */
-    warn: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-    /** Log a failure. */
-    error: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-    /** Log a catastrophic failure. */
-    fatal: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
-}
-export {};
+/**
+ * Combine several log processors into a single log processor. Each one is
+ * called in sequence. Useful for sending a single log to multiple log
+ * destinations.
+ */
+export declare const combine: (processors: Array<LogProcessor>) => LogProcessor;
+
+/**
+ * Create a new logger. The processor is up to you. There are plugins for
+ * filtering, formatting, combining multiple processors together, and more.
+ *
+ * If you wish to use more than one processor, `combine(...)` them first.
+ */
+export declare const createLogger: (processor: LogProcessor) => Logger;
+
+/**
+ * Custom values allowed in log context. These values don't have to be JSON.
+ * The most common case is errors, which support richer error tracking in
+ * backends that support it.
+ *
+ * This is part of the public API. Backends may use declaration merging to
+ * extend the standard attributes. It's recommended to use symbols as keys for
+ * custom features, but not required.
+ */
+export declare interface CustomContext {
+    /**
+     * Error instance associated with the log message. This supports error
+     * tracking and shows prominently in visual backends like TTY output.
+     */
+    error: Error;
+}
+
+/**
+ * Filter logs based on a filter function. If the function returns true, the
+ * log is kept and forwarded onto the next processor, otherwise it is
+ * discarded.
+ */
+export declare const filter: (
+/** Returns `true` to forward the log. */
+predicate: (log: Log) => boolean, 
+/** Where to send the log if it passes the filter. */
+processor: LogProcessor) => LogProcessor;
+
+declare interface JsonContext {
+    [key: string]: JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+}
+
+declare type JsonPrimitive = string | number | boolean | null | undefined;
+
+export declare const level: {
+    /** A critical failure happened and the program must exit. */
+    readonly fatal: 60;
+    /** Something failed, but we can keep going. */
+    readonly error: 50;
+    /** Cause for concern, but we can keep going. */
+    readonly warn: 40;
+    /** High-level progress updates. */
+    readonly info: 30;
+    /** Verbose update about events or control flow (usually hidden). */
+    readonly debug: 20;
+    /** Extremely detailed progress updates (usually hidden). */
+    readonly trace: 10;
+};
+
+/** A log message where variables are carried as structured data. */
+export declare interface Log {
+    /** Unix timestamp. Includes milliseconds. */
+    readonly timestamp: number;
+    /** The verbatim log message. Should not contain interpolated data. */
+    readonly message: string;
+    /** Log severity. One of `levels.*`. */
+    readonly level: LogLevel;
+    /**
+     * Where the log message originated. Usually starts with a library or app name,
+     * followed by something more specific.
+     *
+     * @example ['logger-library', 'ConsoleBackend']
+     */
+    readonly origin: ReadonlyArray<string>;
+    /**
+     * Key-value pairs that provide additional context for the log message. If
+     * you're tempted to interpolate data into the message, consider using log
+     * context instead.
+     *
+     * These values must be JSON serializable.
+     *
+     * Because it's easy to accidentally include unsuitable log context (e.g.
+     * redux state, PII) nested objects are not allowed. The restriction doesn't
+     * make it impossible, but it makes it harder to miss during code review.
+     *
+     * @example { userId: 123, reason: 'disconnect' }
+     */
+    readonly context: LogContext;
+}
+
+/**
+ * A more general type expected by logging backends. Supports type narrowing,
+ * so if a known field exists, it will be used instead of the generic JSON
+ * type.
+ */
+export declare type LogContext = Partial<CustomContext> & JsonContext;
+
+/**
+ * This is the public API which generates and sends `Log` events through the
+ * user-defined processing pipeline.
+ */
+export declare interface Logger {
+    readonly owner: ReadonlyArray<string>;
+    /** Extend the logger to attach a class or module name to logs. */
+    namespace: (owner: string) => Logger;
+    /**
+     * Create a new logger which runs all logs through a middleware function.
+     * Useful for adding default context, doing ad-hoc filtering, or
+     * registering plugins. Only applies to this logger and its descendants.
+     */
+    withMiddleware: (middleware: (next: LogProcessor) => LogProcessor) => Logger;
+    /** Log a verbose and frequent update. */
+    trace: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a frequent and verbose progress update. */
+    debug: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a high-level progress update. */
+    info: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log something concerning. */
+    warn: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a failure. */
+    error: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+    /** Log a catastrophic failure. */
+    fatal: <Context extends StrictContext<Context>>(message: string, context?: Context) => void;
+}
+
+export declare type LogLevel = (typeof level)[keyof typeof level];
+
+/**
+ * A logger is made up of log processors. These processors take structured
+ * logs and do something with them. Examples are logging backends (console,
+ * file, uploads) and operators (filtering, transforming, aggregating).
+ */
+export declare interface LogProcessor {
+    /** Do something with a log message. */
+    (log: Log): unknown;
+}
+
+/**
+ * A type narrowing constraint designed for generic constraints. Controls
+ * what fields are allowed in `log.context`, sourcing from `CustomContext`
+ * first, then falling back to any JSON value.
+ */
+declare type StrictContext<Input> = {
+    [Key in keyof Input]: Key extends keyof CustomContext ? CustomContext[Key] : JsonPrimitive | ReadonlyArray<JsonPrimitive>;
+};
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/core",
-  "version": "0.8.3-rc.154+3f5148e",
+  "version": "0.8.3-rc.155+ca9302f",
   "description": "A structured and composable logger",
   "type": "module",
   "repository": {
@@ -35,6 +35,7 @@
     "test:types": "tsc"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.58.8",
     "@vitest/coverage-v8": "^4.0.0",
     "typescript": "^6.0.0",
     "vite": "^8.0.0",
@@ -42,5 +43,5 @@
     "vite-tsconfig-paths": "^6.0.0",
     "vitest": "^4.0.0"
   },
-  "gitHead": "3f5148eb94bb1d7200d4b4993c95ea30db76b0c4"
+  "gitHead": "ca9302f8b1709bb57058eb0dc73af0ed2021ddfd"
 }

package/dist/src/__tests__/logger.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/__tests__/operators.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/index.d.ts

@@ -1,4 +0,0 @@
-export { combine, filter } from './operators';
-export { createLogger } from './logger';
-export { level } from './types';
-export type { LogProcessor, LogContext, Log, CustomContext, Logger, LogLevel, } from './types';

package/dist/src/logger.d.ts

@@ -1,8 +0,0 @@
-import { LogProcessor, Logger } from './types';
-/**
- * Create a new logger. The processor is up to you. There are plugins for
- * filtering, formatting, combining multiple processors together, and more.
- *
- * If you wish to use more than one processor, `combine(...)` them first.
- */
-export declare const createLogger: (processor: LogProcessor) => Logger;

package/dist/src/operators.d.ts

@@ -1,17 +0,0 @@
-import { Log, LogProcessor } from './types';
-/**
- * Combine several log processors into a single log processor. Each one is
- * called in sequence. Useful for sending a single log to multiple log
- * destinations.
- */
-export declare const combine: (processors: Array<LogProcessor>) => LogProcessor;
-/**
- * Filter logs based on a filter function. If the function returns true, the
- * log is kept and forwarded onto the next processor, otherwise it is
- * discarded.
- */
-export declare const filter: (
-/** Returns `true` to forward the log. */
-predicate: (log: Log) => boolean, 
-/** Where to send the log if it passes the filter. */
-processor: LogProcessor) => LogProcessor;