@holz/core 0.5.0 → 0.7.0-rc.1

package/README.md

@@ -0,0 +1,115 @@
+# `@holz/core`
+
+`@holz/core` is a flexible and extensible logging library for TypeScript applications. It provides a simple but powerful interface for logging progress updates and errors with varying levels of severity.
+
+## Usage
+
+Here is an example of how to create a logger and use it to log a message:
+
+```typescript
+import { createLogger } from '@holz/core';
+
+const logger = createLogger((log) => {
+  console.log(`[${log.level}]`, log.message);
+});
+
+logger.info('Hello, world!');
+```
+
+This will log a message with the info level to the console.
+
+```
+[info] Hello, world!
+```
+
+## Logger Interface
+
+The `Logger` class is the core of the library. It provides a set of methods for logging messages with different levels of severity. Each method takes a message and an optional context object.
+
+You can also use the `namespace` method to create a new logger with a specific owner, such as a class or module. This makes it easier to identify the origin of log messages.
+
+## Log Levels
+
+The library provides four log levels:
+
+- `LogLevel.Debug`: Extremely verbose progress updates (usually hidden).
+- `LogLevel.Info`: High-level progress updates.
+- `LogLevel.Warn`: Something is concerning, but we can keep going.
+- `LogLevel.Error`: Something critical failed and we can't continue.
+
+You can use these levels to indicate the severity of a log message. The severity levels can be configured to perform actions based on the level of severity of the log messages.
+
+## Log Structure
+
+Every log message processed by Holz follows a specific structure defined by the `Log` interface. Understanding this structure is crucial for effective logging and log processing.
+
+A `Log` object contains the following properties:
+
+- `message`: The verbatim log message. This property should not contain any interpolated data.
+- `level`: The severity of the log message, expressed as a member of the `LogLevel` enum. The available log levels are, in increasing order of severity: `Debug`, `Info`, `Warn`, `Error`.
+- `origin`: The source of the log message. This property is an array of strings that typically identifies the library, module, or component that generated the log message, followed by more specific information. This property can be used to filter and group log messages based on their origin.
+- `context`: A dictionary of key-value pairs that provides additional context for the log message. The values in this object must be JSON serializable. Because it's easy to accidentally include unsuitable log context, such as PII or deeply nested objects, the use of nested objects in the context is discouraged.
+
+Here is an example of a log message expressed as a `Log` object:
+
+```typescript
+{
+  message: 'Connection to database established.',
+  level: LogLevel.Info,
+  origin: ['my-app', 'database-connection'],
+  context: {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    database: 'my_database',
+  },
+};
+```
+
+In this example, the log message describes a successful connection to a database, with additional context about the database host, port, user, and name.
+
+## Log Processors
+
+In Holz, a `LogProcessor` function is responsible for processing log messages. The `createLogger` function takes this function as an argument. A `LogProcessor` is a plain function that takes a `Log` object, which contains the message, level, origin, and context of the log.
+
+Holz provides a set of off-the-shelf plugins for logging to various destinations, filtering, formatting, and more. You can also write your own plugins to suit your specific needs. These plugins can be combined into a `LogProcessor` function using the utility function `combine()`, allowing you to send a single log to multiple destinations.
+
+Holz's plugin system is designed to be flexible and extensible. If none of the provided plugins meet your needs, you can easily create your own plugin and still build on plugins from the rest of the ecosystem. Check out the [`@holz/logger`](https://github.com/PsychoLlama/holz/tree/main/packages/holz-logger) package for a bundled example of Holz's logging plugins.
+
+## Utilities
+
+In addition to the core `Logger` class, `@holz/core` provides some utility processors that you can use to extend the functionality of your logging solution. These processors are optional and can be combined with each other or with third-party processors as needed.
+
+### `combine`
+
+The `combine` processor takes an array of log processors and returns a single log processor that forwards each log to all of the input processors. This is useful when you want to send a single log to multiple log destinations.
+
+```typescript
+import { combine } from '@holz/core';
+import {
+  consoleBackend,
+  fileBackend,
+  logUploadService,
+} from './custom-processors';
+
+const logger = createLogger(
+  combine([consoleBackend, fileBackend, logUploadService])
+);
+```
+
+### `filter`
+
+The `filter` processor takes a filter function and another log processor as input. If the filter function returns `true` for a log, it is forwarded to the second processor. If the filter function returns `false`, the log is discarded. This is useful when you want to selectively forward logs based on some criteria.
+
+```typescript
+import { filter } from '@holz/core';
+
+const debugLogFilter = filter(
+  (log) => log.level !== LogLevel.Debug,
+  consoleProcessor
+);
+
+const logger = createLogger(debugLogFilter);
+```
+
+Note that you can chain multiple filter processors together to create more complex filters.

package/dist/holz-core.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var t=(o=>(o.Error="error",o.Warn="warn",o.Info="info",o.Debug="debug",o))(t||{});function i(o){return r=>o.forEach(e=>e(r))}function a(o,r){return e=>{o(e)&&r(e)}}class n{constructor(r,e){this.processor=r,this.owner=e,Object.defineProperty(this,"processor",{configurable:!1,enumerable:!1})}static create(r){return new n(r,[])}namespace(r){return new n(this.processor,this.owner.concat(r))}debug(r,e){this.forwardLog(t.Debug,r,e)}info(r,e){this.forwardLog(t.Info,r,e)}warn(r,e){this.forwardLog(t.Warn,r,e)}error(r,e){this.forwardLog(t.Error,r,e)}forwardLog(r,e,s={}){this.processor({message:e,level:r,origin:this.owner,context:s})}}const c=n.create;exports.LogLevel=t;exports.combine=i;exports.createLogger=c;exports.filter=a;
+"use strict";var a=Object.defineProperty;var c=(o,r,e)=>r in o?a(o,r,{enumerable:!0,configurable:!0,writable:!0,value:e}):o[r]=e;var i=(o,r,e)=>c(o,typeof r!="symbol"?r+"":r,e);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});var t=(o=>(o.Error="error",o.Warn="warn",o.Info="info",o.Debug="debug",o))(t||{});function f(o){return r=>o.forEach(e=>e(r))}function u(o,r){return e=>{o(e)&&r(e)}}class s{constructor(r,e){i(this,"debug",(r,e)=>{this.forwardLog(t.Debug,r,e)});i(this,"info",(r,e)=>{this.forwardLog(t.Info,r,e)});i(this,"warn",(r,e)=>{this.forwardLog(t.Warn,r,e)});i(this,"error",(r,e)=>{this.forwardLog(t.Error,r,e)});this.processor=r,this.owner=e;const n={configurable:!1,enumerable:!1};Object.defineProperties(this,{processor:n,debug:n,info:n,warn:n,error:n})}namespace(r){return new s(this.processor,this.owner.concat(r))}forwardLog(r,e,n={}){this.processor({message:e,level:r,origin:this.owner,context:n})}}const g=o=>new s(o,[]);exports.LogLevel=t;exports.combine=f;exports.createLogger=g;exports.filter=u;

package/dist/holz-core.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 function 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;
+
+/**
+ * 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 function 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 type JsonPrimitive = string | number | boolean | null | undefined;
+
+/** A log message where variables are carried as structured data. */
+export declare interface Log {
+    /** The verbatim log message. Should not contain interpolated data. */
+    readonly message: string;
+    /** Log severity. */
+    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 type LogContext = Record<string, JsonPrimitive | ReadonlyArray<JsonPrimitive>>;
+
+export declare class Logger {
+    private processor;
+    readonly owner: ReadonlyArray<string>;
+    constructor(processor: LogProcessor, owner: ReadonlyArray<string>);
+    /** Extend the logger to attach a class or module name to logs. */
+    namespace(owner: string): Logger;
+    /** Log a frequent and verbose progress update. */
+    debug: (message: string, context?: LogContext) => void;
+    /** Log a high-level progress update. */
+    info: (message: string, context?: LogContext) => void;
+    /** Log something concerning. */
+    warn: (message: string, context?: LogContext) => void;
+    /** Log a critical failure. */
+    error: (message: string, context?: LogContext) => void;
+    private forwardLog;
+}
+
+export declare enum LogLevel {
+    /** Something critical failed and we can't continue. */
+    Error = "error",
+    /** Something is concerning, but we can keep going. */
+    Warn = "warn",
+    /** High-level progress updates. */
+    Info = "info",
+    /** Extremely verbose progress updates (usually hidden). */
+    Debug = "debug"
+}
+
+/**
+ * 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): void;
+}
+
+export { }

package/dist/holz-core.js

@@ -1,61 +1,60 @@
-var n = /* @__PURE__ */ ((e) => (e.Error = "error", e.Warn = "warn", e.Info = "info", e.Debug = "debug", e))(n || {});
-function a(e) {
+var a = Object.defineProperty;
+var c = (e, r, o) => r in e ? a(e, r, { enumerable: !0, configurable: !0, writable: !0, value: o }) : e[r] = o;
+var s = (e, r, o) => c(e, typeof r != "symbol" ? r + "" : r, o);
+var t = /* @__PURE__ */ ((e) => (e.Error = "error", e.Warn = "warn", e.Info = "info", e.Debug = "debug", e))(t || {});
+function u(e) {
   return (r) => e.forEach((o) => o(r));
 }
-function i(e, r) {
+function h(e, r) {
   return (o) => {
     e(o) && r(o);
   };
 }
-class t {
+class i {
   constructor(r, o) {
-    this.processor = r, this.owner = o, Object.defineProperty(this, "processor", {
-      configurable: !1,
-      enumerable: !1
+    /** Log a frequent and verbose progress update. */
+    s(this, "debug", (r, o) => {
+      this.forwardLog(t.Debug, r, o);
+    });
+    /** Log a high-level progress update. */
+    s(this, "info", (r, o) => {
+      this.forwardLog(t.Info, r, o);
+    });
+    /** Log something concerning. */
+    s(this, "warn", (r, o) => {
+      this.forwardLog(t.Warn, r, o);
+    });
+    /** Log a critical failure. */
+    s(this, "error", (r, o) => {
+      this.forwardLog(t.Error, r, o);
+    });
+    this.processor = r, this.owner = o;
+    const n = { configurable: !1, enumerable: !1 };
+    Object.defineProperties(this, {
+      processor: n,
+      debug: n,
+      info: n,
+      warn: n,
+      error: n
     });
-  }
-  /**
-   * 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.
-   */
-  static create(r) {
-    return new t(r, []);
   }
   /** Extend the logger to attach a class or module name to logs. */
   namespace(r) {
-    return new t(this.processor, this.owner.concat(r));
-  }
-  /** Log a frequent and verbose progress update. */
-  debug(r, o) {
-    this.forwardLog(n.Debug, r, o);
-  }
-  /** Log a high-level progress update. */
-  info(r, o) {
-    this.forwardLog(n.Info, r, o);
-  }
-  /** Log something concerning. */
-  warn(r, o) {
-    this.forwardLog(n.Warn, r, o);
-  }
-  /** Log a critical failure. */
-  error(r, o) {
-    this.forwardLog(n.Error, r, o);
+    return new i(this.processor, this.owner.concat(r));
   }
-  forwardLog(r, o, s = {}) {
+  forwardLog(r, o, n = {}) {
     this.processor({
       message: o,
       level: r,
       origin: this.owner,
-      context: s
+      context: n
     });
   }
 }
-const c = t.create;
+const w = (e) => new i(e, []);
 export {
-  n as LogLevel,
-  a as combine,
-  c as createLogger,
-  i as filter
+  t as LogLevel,
+  u as combine,
+  w as createLogger,
+  h as filter
 };

package/package.json

@@ -1,11 +1,8 @@
 {
   "name": "@holz/core",
-  "version": "0.5.0",
+  "version": "0.7.0-rc.1",
   "description": "A structured and composable logger",
   "type": "module",
-  "main": "./dist/holz-core.cjs",
-  "module": "./dist/holz-core.js",
-  "types": "./src/index.ts",
   "repository": {
     "type": "git",
     "url": "https://github.com/PsychoLlama/holz",
@@ -13,6 +10,7 @@
   },
   "exports": {
     ".": {
+      "types": "./dist/holz-core.d.ts",
       "require": "./dist/holz-core.cjs",
       "import": "./dist/holz-core.js"
     }
@@ -38,9 +36,12 @@
     "test:types": "tsc"
   },
   "devDependencies": {
-    "@vitest/coverage-c8": "^0.28.5",
-    "typescript": "^4.9.5",
-    "vite": "^4.0.0",
-    "vitest": "^0.28.5"
-  }
+    "@vitest/coverage-v8": "^3.0.8",
+    "typescript": "^5.0.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.8"
+  },
+  "stableVersion": "0.6.0"
 }

package/src/__tests__/logger.test.ts

@@ -35,6 +35,19 @@ describe('Logger', () => {
     });
   });
 
+  it('binds the log methods to the logger', () => {
+    const backend = vi.fn();
+    const logger = createLogger(backend);
+
+    const { debug, info, warn, error } = logger;
+    debug('Debugging message');
+    info('Informative message');
+    warn('Warning message');
+    error('Error message');
+
+    expect(backend).toHaveBeenCalledTimes(4);
+  });
+
   describe('namespace', () => {
     it('extends the origin of the logger', () => {
       const backend = vi.fn();

package/src/__tests__/operators.test.ts

@@ -13,11 +13,11 @@ describe('operators', () => {
       logger.info('tee message');
 
       expect(b1).toHaveBeenCalledWith(
-        expect.objectContaining({ message: 'tee message' })
+        expect.objectContaining({ message: 'tee message' }),
       );
 
       expect(b2).toHaveBeenCalledWith(
-        expect.objectContaining({ message: 'tee message' })
+        expect.objectContaining({ message: 'tee message' }),
       );
     });
 
@@ -33,7 +33,7 @@ describe('operators', () => {
     it('filters out logs that do not match the predicate', () => {
       const backend = vi.fn();
       const logger = createLogger(
-        filter((log) => log.level !== LogLevel.Debug, backend)
+        filter((log) => log.level !== LogLevel.Debug, backend),
       );
 
       logger.info('keep me');
@@ -41,7 +41,7 @@ describe('operators', () => {
 
       expect(backend).toHaveBeenCalledOnce();
       expect(backend).toHaveBeenCalledWith(
-        expect.objectContaining({ message: 'keep me' })
+        expect.objectContaining({ message: 'keep me' }),
       );
     });
   });

package/src/index.ts

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

package/src/logger.ts

@@ -2,24 +2,18 @@ import type { LogProcessor, LogContext } from './types';
 import { LogLevel } from './types';
 
 class Logger {
-  /**
-   * 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.
-   */
-  static create(processor: LogProcessor): Logger {
-    return new Logger(processor, []);
-  }
-
-  private constructor(
+  constructor(
     private processor: LogProcessor,
-    readonly owner: ReadonlyArray<string>
+    readonly owner: ReadonlyArray<string>,
   ) {
-    // Non-enumerable to keep the repls clean.
-    Object.defineProperty(this, 'processor', {
-      configurable: false,
-      enumerable: false,
+    // Non-enumerable to keep the repl clean.
+    const hidden = { configurable: false, enumerable: false };
+    Object.defineProperties(this, {
+      processor: hidden,
+      debug: hidden,
+      info: hidden,
+      warn: hidden,
+      error: hidden,
     });
   }
 
@@ -29,29 +23,29 @@ class Logger {
   }
 
   /** Log a frequent and verbose progress update. */
-  debug(message: string, context?: LogContext) {
+  debug = (message: string, context?: LogContext) => {
     this.forwardLog(LogLevel.Debug, message, context);
-  }
+  };
 
   /** Log a high-level progress update. */
-  info(message: string, context?: LogContext) {
+  info = (message: string, context?: LogContext) => {
     this.forwardLog(LogLevel.Info, message, context);
-  }
+  };
 
   /** Log something concerning. */
-  warn(message: string, context?: LogContext) {
+  warn = (message: string, context?: LogContext) => {
     this.forwardLog(LogLevel.Warn, message, context);
-  }
+  };
 
   /** Log a critical failure. */
-  error(message: string, context?: LogContext) {
+  error = (message: string, context?: LogContext) => {
     this.forwardLog(LogLevel.Error, message, context);
-  }
+  };
 
   private forwardLog(
     level: LogLevel,
     message: string,
-    context: LogContext = {}
+    context: LogContext = {},
   ) {
     this.processor({
       message,
@@ -62,4 +56,13 @@ class Logger {
   }
 }
 
-export const createLogger = Logger.create;
+/**
+ * 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 const createLogger = (processor: LogProcessor): Logger =>
+  new Logger(processor, []);
+
+export type { Logger };

package/src/operators.ts

@@ -18,7 +18,7 @@ export function filter(
   /** Returns `true` to forward the log. */
   predicate: (log: Log) => boolean,
   /** Where to send the log if it passes the filter. */
-  processor: LogProcessor
+  processor: LogProcessor,
 ): LogProcessor {
   return (log: Log) => {
     if (predicate(log)) {