@holz/core 0.2.0 → 0.6.0

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

package/dist/holz-core.js

@@ -1,9 +1,30 @@
-var e = /* @__PURE__ */ ((s) => (s.Error = "error", s.Warn = "warn", s.Info = "info", s.Debug = "debug", s))(e || {});
-class t {
-  constructor(r, o) {
-    this.processor = r, this.origin = o, Object.defineProperty(this, "processor", {
-      configurable: !1,
-      enumerable: !1
+var i = /* @__PURE__ */ ((o) => (o.Error = "error", o.Warn = "warn", o.Info = "info", o.Debug = "debug", o))(i || {});
+function c(o) {
+  return (r) => o.forEach((e) => e(r));
+}
+function f(o, r) {
+  return (e) => {
+    o(e) && r(e);
+  };
+}
+class a {
+  constructor(r, e) {
+    this.processor = r, this.owner = e, this.debug = (n, s) => {
+      this.forwardLog(i.Debug, n, s);
+    }, this.info = (n, s) => {
+      this.forwardLog(i.Info, n, s);
+    }, this.warn = (n, s) => {
+      this.forwardLog(i.Warn, n, s);
+    }, this.error = (n, s) => {
+      this.forwardLog(i.Error, n, s);
+    };
+    const t = { configurable: !1, enumerable: !1 };
+    Object.defineProperties(this, {
+      processor: t,
+      debug: t,
+      info: t,
+      warn: t,
+      error: t
     });
   }
   /**
@@ -13,65 +34,25 @@ class t {
    * If you wish to use more than one processor, `combine(...)` them first.
    */
   static create(r) {
-    return new t(r, []);
+    return new a(r, []);
   }
   /** Extend the logger to attach a class or module name to logs. */
   namespace(r) {
-    return new t(this.processor, this.origin.concat(r));
-  }
-  /** Log a frequent and verbose progress update. */
-  debug(r, o) {
-    this.forwardLog(e.Debug, r, o);
-  }
-  /** Log a high-level progress update. */
-  info(r, o) {
-    this.forwardLog(e.Info, r, o);
+    return new a(this.processor, this.owner.concat(r));
   }
-  /** Log something concerning. */
-  warn(r, o) {
-    this.forwardLog(e.Warn, r, o);
-  }
-  /** Log a critical failure. */
-  error(r, o) {
-    this.forwardLog(e.Error, r, o);
-  }
-  forwardLog(r, o, c = {}) {
-    this.processor.processLog({
-      message: o,
+  forwardLog(r, e, t = {}) {
+    this.processor({
+      message: e,
       level: r,
-      origin: this.origin,
-      context: c
+      origin: this.owner,
+      context: t
     });
   }
 }
-const a = t.create;
-class i {
-  constructor(r) {
-    this.processors = r;
-  }
-  processLog(r) {
-    this.processors.forEach((o) => {
-      o.processLog(r);
-    });
-  }
-}
-function f(s) {
-  return new i(s);
-}
-class n {
-  constructor(r, o) {
-    this.predicate = r, this.processor = o;
-  }
-  processLog(r) {
-    this.predicate(r) && this.processor.processLog(r);
-  }
-}
-function h(s, r) {
-  return new n(s, r);
-}
+const h = a.create;
 export {
-  e as LogLevel,
-  f as combine,
-  a as createLogger,
-  h as filter
+  i as LogLevel,
+  c as combine,
+  h as createLogger,
+  f as filter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/core",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "A structured and composable logger",
   "type": "module",
   "main": "./dist/holz-core.cjs",
@@ -38,8 +38,8 @@
     "test:types": "tsc"
   },
   "devDependencies": {
-    "@vitest/coverage-c8": "0.28.5",
-    "typescript": "4.9.5",
+    "@vitest/coverage-c8": "^0.28.5",
+    "typescript": "^4.9.5",
     "vite": "^4.0.0",
     "vitest": "^0.28.5"
   }

package/src/__tests__/logger.test.ts

@@ -1,16 +1,15 @@
-import TestBackend from '../backends/test';
 import { createLogger } from '../logger';
 import { LogLevel } from '../types';
 
 describe('Logger', () => {
   it('sends structured logs to the log processor', () => {
-    const backend = new TestBackend();
+    const backend = vi.fn();
     const logger = createLogger(backend);
 
     logger.info('Hello world', { audience: 'testers' });
 
-    expect(backend.processLog).toHaveBeenCalledOnce();
-    expect(backend.processLog).toHaveBeenCalledWith({
+    expect(backend).toHaveBeenCalledOnce();
+    expect(backend).toHaveBeenCalledWith({
       message: 'Hello world',
       level: 'info',
       origin: [],
@@ -24,11 +23,11 @@ describe('Logger', () => {
     [LogLevel.Warn, 'There are irregularities in the pension fund', {}],
     [LogLevel.Error, 'Leadership has taken a dive', { windows: 'open' }],
   ])('correctly processes %s log messages', (level, message, context) => {
-    const backend = new TestBackend();
+    const backend = vi.fn();
     const logger = createLogger(backend);
 
     logger[level](message, context);
-    expect(backend.processLog).toHaveBeenCalledWith({
+    expect(backend).toHaveBeenCalledWith({
       message,
       level,
       context,
@@ -36,17 +35,30 @@ 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 = new TestBackend();
+      const backend = vi.fn();
       const logger = createLogger(backend)
         .namespace('signaling')
         .namespace('socket');
 
       logger.info('opening socket');
 
-      expect(backend.processLog).toHaveBeenCalledOnce();
-      expect(backend.processLog).toHaveBeenCalledWith({
+      expect(backend).toHaveBeenCalledOnce();
+      expect(backend).toHaveBeenCalledWith({
         message: 'opening socket',
         level: 'info',
         origin: ['signaling', 'socket'],

package/src/__tests__/operators.test.ts

@@ -0,0 +1,48 @@
+import { createLogger } from '../logger';
+import { combine, filter } from '../operators';
+import { LogLevel } from '../types';
+
+describe('operators', () => {
+  describe('combine', () => {
+    it('combines several log processors backends into one', () => {
+      const b1 = vi.fn();
+      const b2 = vi.fn();
+      const backend = combine([b1, b2]);
+      const logger = createLogger(backend);
+
+      logger.info('tee message');
+
+      expect(b1).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'tee message' })
+      );
+
+      expect(b2).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'tee message' })
+      );
+    });
+
+    it('works even if you provide no logging backend', () => {
+      const backend = combine([]);
+      const logger = createLogger(backend);
+
+      expect(() => logger.info('no backend')).not.toThrow();
+    });
+  });
+
+  describe('filter', () => {
+    it('filters out logs that do not match the predicate', () => {
+      const backend = vi.fn();
+      const logger = createLogger(
+        filter((log) => log.level !== LogLevel.Debug, backend)
+      );
+
+      logger.info('keep me');
+      logger.debug('discard');
+
+      expect(backend).toHaveBeenCalledOnce();
+      expect(backend).toHaveBeenCalledWith(
+        expect.objectContaining({ message: 'keep me' })
+      );
+    });
+  });
+});

package/src/index.ts

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

package/src/logger.ts

@@ -14,49 +14,53 @@ class Logger {
 
   private constructor(
     private processor: LogProcessor,
-    readonly origin: 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,
     });
   }
 
   /** Extend the logger to attach a class or module name to logs. */
   namespace(owner: string): Logger {
-    return new Logger(this.processor, this.origin.concat(owner));
+    return new Logger(this.processor, this.owner.concat(owner));
   }
 
   /** 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 = {}
   ) {
-    this.processor.processLog({
+    this.processor({
       message,
       level,
-      origin: this.origin,
+      origin: this.owner,
       context,
     });
   }

package/src/operators.ts

@@ -0,0 +1,28 @@
+import type { 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 function combine(processors: Array<LogProcessor>): LogProcessor {
+  return (log: Log) => processors.forEach((processor) => processor(log));
+}
+
+/**
+ * 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 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 {
+  return (log: Log) => {
+    if (predicate(log)) {
+      processor(log);
+    }
+  };
+}

package/src/types.ts

@@ -5,7 +5,7 @@
  */
 export interface LogProcessor {
   /** Do something with a log message. */
-  processLog(log: Log): void;
+  (log: Log): void;
 }
 
 /** A log message where variables are carried as structured data. */

package/src/backends/test.ts

@@ -1,5 +0,0 @@
-import type { LogProcessor } from '../types';
-
-export default class TestBackend implements LogProcessor {
-  processLog = vi.fn();
-}

package/src/operators/__tests__/combine.test.ts

@@ -1,29 +0,0 @@
-import TestBackend from '../../backends/test';
-import { createLogger } from '../../logger';
-import combine from '../combine';
-
-describe('combine operator', () => {
-  it('combines several log processors backends into one', () => {
-    const b1 = new TestBackend();
-    const b2 = new TestBackend();
-    const backend = combine([b1, b2]);
-    const logger = createLogger(backend);
-
-    logger.info('tee message');
-
-    expect(b1.processLog).toHaveBeenCalledWith(
-      expect.objectContaining({ message: 'tee message' })
-    );
-
-    expect(b2.processLog).toHaveBeenCalledWith(
-      expect.objectContaining({ message: 'tee message' })
-    );
-  });
-
-  it('works even if you provide no logging backend', () => {
-    const backend = combine([]);
-    const logger = createLogger(backend);
-
-    expect(() => logger.info('no backend')).not.toThrow();
-  });
-});

package/src/operators/__tests__/filter.test.ts

@@ -1,21 +0,0 @@
-import TestBackend from '../../backends/test';
-import { createLogger } from '../../logger';
-import { LogLevel } from '../../types';
-import filter from '../filter';
-
-describe('filter operator', () => {
-  it('filters out logs that do not match the predicate', () => {
-    const backend = new TestBackend();
-    const logger = createLogger(
-      filter((log) => log.level !== LogLevel.Debug, backend)
-    );
-
-    logger.info('keep me');
-    logger.debug('discard');
-
-    expect(backend.processLog).toHaveBeenCalledOnce();
-    expect(backend.processLog).toHaveBeenCalledWith(
-      expect.objectContaining({ message: 'keep me' })
-    );
-  });
-});

package/src/operators/combine.ts

@@ -1,22 +0,0 @@
-import type { Log, LogProcessor } from '../types';
-
-class CombinedLogProcessor implements LogProcessor {
-  constructor(private processors: Array<LogProcessor>) {
-    // empty
-  }
-
-  processLog(log: Log) {
-    this.processors.forEach((processor) => {
-      processor.processLog(log);
-    });
-  }
-}
-
-/**
- * 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 default function combine(processors: Array<LogProcessor>): LogProcessor {
-  return new CombinedLogProcessor(processors);
-}

package/src/operators/filter.ts

@@ -1,28 +0,0 @@
-import type { Log, LogProcessor } from '../types';
-
-class LogFilter implements LogProcessor {
-  constructor(
-    private predicate: (log: Log) => boolean,
-    private processor: LogProcessor
-  ) {}
-
-  processLog(log: Log) {
-    if (this.predicate(log)) {
-      this.processor.processLog(log);
-    }
-  }
-}
-
-/**
- * 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 default 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 {
-  return new LogFilter(predicate, processor);
-}