@holz/core 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased

package/dist/holz-core.js

@@ -0,0 +1,69 @@
+var t = /* @__PURE__ */ ((s) => (s.Error = "error", s.Warn = "warn", s.Info = "info", s.Debug = "debug", s))(t || {});
+class e {
+  constructor(r, o) {
+    this.processor = r, this.origin = o;
+  }
+  static create(r) {
+    return new e(r, []);
+  }
+  /** Extend the logger to attach a class or module name to logs. */
+  namespace(r) {
+    return new e(this.processor, this.origin.concat(r));
+  }
+  /** Log a frequent and verbose progress update. */
+  debug(r, o) {
+    this.forwardLog(t.Debug, r, o);
+  }
+  /** Log a high-level progress update. */
+  info(r, o) {
+    this.forwardLog(t.Info, r, o);
+  }
+  /** Log something concerning. */
+  warn(r, o) {
+    this.forwardLog(t.Warn, r, o);
+  }
+  /** Log a critical failure. */
+  error(r, o) {
+    this.forwardLog(t.Error, r, o);
+  }
+  forwardLog(r, o, c = {}) {
+    this.processor.processLog({
+      message: o,
+      level: r,
+      origin: this.origin,
+      context: c
+    });
+  }
+}
+const a = e.create;
+class i {
+  constructor(r) {
+    this.processors = r;
+  }
+  processLog(r) {
+    this.processors.forEach((o) => {
+      o.processLog(r);
+    });
+  }
+}
+function h(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 g(s, r) {
+  return new n(s, r);
+}
+export {
+  t as LogLevel,
+  h as combine,
+  a as createLogger,
+  g as filter
+};
+//# sourceMappingURL=holz-core.js.map

package/dist/holz-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"holz-core.js","sources":["../src/types.ts","../src/logger.ts","../src/operators/combine.ts","../src/operators/filter.ts"],"sourcesContent":["/**\n * A logger is made up of log processors. These processors take structured\n * logs and do something with them. Examples are logging backends (console,\n * file, uploads) and operators (filtering, transforming, aggregating).\n */\nexport interface LogProcessor {\n  /** Do something with a log message. */\n  processLog(log: Log): void;\n}\n\n/** A log message where variables are carried as structured data. */\nexport interface Log {\n  /** The verbatim log message. Should not contain interpolated data. */\n  readonly message: string;\n\n  /** Log severity. */\n  readonly level: LogLevel;\n\n  /**\n   * Where the log message originated. Usually starts with a library or app name,\n   * followed by something more specific.\n   *\n   * @example ['logger-library', 'ConsoleBackend']\n   */\n  readonly origin: ReadonlyArray<string>;\n\n  /**\n   * Key-value pairs that provide additional context for the log message. If\n   * you're tempted to interpolate data into the message, consider using log\n   * context instead.\n   *\n   * These values must be JSON serializable.\n   *\n   * Because it's easy to accidentally include unsuitable log context (e.g.\n   * redux state, PII) nested objects are not allowed. The restriction doesn't\n   * make it impossible, but it makes it harder to miss during code review.\n   *\n   * @example { userId: 123, reason: 'disconnect' }\n   */\n  readonly context: LogContext;\n}\n\nexport enum LogLevel {\n  /** Something critical failed and we can't continue. */\n  Error = 'error',\n\n  /** Something is concerning, but we can keep going. */\n  Warn = 'warn',\n\n  /** High-level progress updates. */\n  Info = 'info',\n\n  /** Extremely verbose progress updates (usually hidden). */\n  Debug = 'debug',\n}\n\nexport type LogContext = Record<\n  string,\n  JsonPrimitive | ReadonlyArray<JsonPrimitive>\n>;\n\ntype JsonPrimitive = string | number | boolean | null | undefined;\n","import type { LogProcessor, LogContext } from './types';\nimport { LogLevel } from './types';\n\nclass Logger {\n  static create(backend: LogProcessor): Logger {\n    return new Logger(backend, []);\n  }\n\n  private constructor(\n    private processor: LogProcessor,\n    private origin: ReadonlyArray<string>\n  ) {\n    // empty\n  }\n\n  /** Extend the logger to attach a class or module name to logs. */\n  namespace(owner: string): Logger {\n    return new Logger(this.processor, this.origin.concat(owner));\n  }\n\n  /** Log a frequent and verbose progress update. */\n  debug(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Debug, message, context);\n  }\n\n  /** Log a high-level progress update. */\n  info(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Info, message, context);\n  }\n\n  /** Log something concerning. */\n  warn(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Warn, message, context);\n  }\n\n  /** Log a critical failure. */\n  error(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Error, message, context);\n  }\n\n  private forwardLog(\n    level: LogLevel,\n    message: string,\n    context: LogContext = {}\n  ) {\n    this.processor.processLog({\n      message,\n      level,\n      origin: this.origin,\n      context,\n    });\n  }\n}\n\nexport const createLogger = Logger.create;\n","import type { Log, LogProcessor } from '../types';\n\nclass CombinedLogProcessor implements LogProcessor {\n  constructor(private processors: Array<LogProcessor>) {\n    // empty\n  }\n\n  processLog(log: Log) {\n    this.processors.forEach((processor) => {\n      processor.processLog(log);\n    });\n  }\n}\n\n/**\n * Combine several log processors into a single log processor. Each one is\n * called in sequence. Useful for sending a single log to multiple log\n * destinations.\n */\nexport default function combine(processors: Array<LogProcessor>): LogProcessor {\n  return new CombinedLogProcessor(processors);\n}\n","import type { Log, LogProcessor } from '../types';\n\nclass LogFilter implements LogProcessor {\n  constructor(\n    private predicate: (log: Log) => boolean,\n    private processor: LogProcessor\n  ) {}\n\n  processLog(log: Log) {\n    if (this.predicate(log)) {\n      this.processor.processLog(log);\n    }\n  }\n}\n\n/**\n * Filter logs based on a filter function. If the function returns true, the\n * log is kept and forwarded onto the next processor, otherwise it is\n * discarded.\n */\nexport default function filter(\n  /** Returns `true` to forward the log. */\n  predicate: (log: Log) => boolean,\n  /** Where to send the log if it passes the filter. */\n  processor: LogProcessor\n): LogProcessor {\n  return new LogFilter(predicate, processor);\n}\n"],"names":["LogLevel","Logger","processor","origin","backend","owner","message","context","level","createLogger","CombinedLogProcessor","processors","log","combine","LogFilter","predicate","filter"],"mappings":"AA0CY,IAAAA,sBAAAA,OAEVA,EAAA,QAAQ,SAGRA,EAAA,OAAO,QAGPA,EAAA,OAAO,QAGPA,EAAA,QAAQ,SAXEA,IAAAA,KAAA,CAAA,CAAA;ACvCZ,MAAMC,EAAO;AAAA,EAKH,YACEC,GACAC,GACR;AAFQ,SAAA,YAAAD,GACA,KAAA,SAAAC;AAAA,EAGV;AAAA,EATA,OAAO,OAAOC,GAA+B;AAC3C,WAAO,IAAIH,EAAOG,GAAS,CAAA,CAAE;AAAA,EAC/B;AAAA;AAAA,EAUA,UAAUC,GAAuB;AACxB,WAAA,IAAIJ,EAAO,KAAK,WAAW,KAAK,OAAO,OAAOI,CAAK,CAAC;AAAA,EAC7D;AAAA;AAAA,EAGA,MAAMC,GAAiBC,GAAsB;AAC3C,SAAK,WAAWP,EAAS,OAAOM,GAASC,CAAO;AAAA,EAClD;AAAA;AAAA,EAGA,KAAKD,GAAiBC,GAAsB;AAC1C,SAAK,WAAWP,EAAS,MAAMM,GAASC,CAAO;AAAA,EACjD;AAAA;AAAA,EAGA,KAAKD,GAAiBC,GAAsB;AAC1C,SAAK,WAAWP,EAAS,MAAMM,GAASC,CAAO;AAAA,EACjD;AAAA;AAAA,EAGA,MAAMD,GAAiBC,GAAsB;AAC3C,SAAK,WAAWP,EAAS,OAAOM,GAASC,CAAO;AAAA,EAClD;AAAA,EAEQ,WACNC,GACAF,GACAC,IAAsB,CAAA,GACtB;AACA,SAAK,UAAU,WAAW;AAAA,MACxB,SAAAD;AAAA,MACA,OAAAE;AAAA,MACA,QAAQ,KAAK;AAAA,MACb,SAAAD;AAAA,IAAA,CACD;AAAA,EACH;AACF;AAEO,MAAME,IAAeR,EAAO;ACpDnC,MAAMS,EAA6C;AAAA,EACjD,YAAoBC,GAAiC;AAAjC,SAAA,aAAAA;AAAA,EAEpB;AAAA,EAEA,WAAWC,GAAU;AACd,SAAA,WAAW,QAAQ,CAACV,MAAc;AACrC,MAAAA,EAAU,WAAWU,CAAG;AAAA,IAAA,CACzB;AAAA,EACH;AACF;AAOA,SAAwBC,EAAQF,GAA+C;AACtE,SAAA,IAAID,EAAqBC,CAAU;AAC5C;ACnBA,MAAMG,EAAkC;AAAA,EACtC,YACUC,GACAb,GACR;AAFQ,SAAA,YAAAa,GACA,KAAA,YAAAb;AAAA,EACP;AAAA,EAEH,WAAWU,GAAU;AACf,IAAA,KAAK,UAAUA,CAAG,KACf,KAAA,UAAU,WAAWA,CAAG;AAAA,EAEjC;AACF;AAOwB,SAAAI,EAEtBD,GAEAb,GACc;AACP,SAAA,IAAIY,EAAUC,GAAWb,CAAS;AAC3C;"}

package/dist/holz-core.umd.cjs

@@ -0,0 +1,2 @@
+(function(t,s){typeof exports=="object"&&typeof module<"u"?s(exports):typeof define=="function"&&define.amd?define(["exports"],s):(t=typeof globalThis<"u"?globalThis:t||self,s(t["holz-core"]={}))})(this,function(t){"use strict";var s=(e=>(e.Error="error",e.Warn="warn",e.Info="info",e.Debug="debug",e))(s||{});class i{constructor(r,o){this.processor=r,this.origin=o}static create(r){return new i(r,[])}namespace(r){return new i(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,d={}){this.processor.processLog({message:o,level:r,origin:this.origin,context:d})}}const n=i.create;class c{constructor(r){this.processors=r}processLog(r){this.processors.forEach(o=>{o.processLog(r)})}}function f(e){return new c(e)}class a{constructor(r,o){this.predicate=r,this.processor=o}processLog(r){this.predicate(r)&&this.processor.processLog(r)}}function u(e,r){return new a(e,r)}t.LogLevel=s,t.combine=f,t.createLogger=n,t.filter=u,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})});
+//# sourceMappingURL=holz-core.umd.cjs.map

package/dist/holz-core.umd.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"holz-core.umd.cjs","sources":["../src/types.ts","../src/logger.ts","../src/operators/combine.ts","../src/operators/filter.ts"],"sourcesContent":["/**\n * A logger is made up of log processors. These processors take structured\n * logs and do something with them. Examples are logging backends (console,\n * file, uploads) and operators (filtering, transforming, aggregating).\n */\nexport interface LogProcessor {\n  /** Do something with a log message. */\n  processLog(log: Log): void;\n}\n\n/** A log message where variables are carried as structured data. */\nexport interface Log {\n  /** The verbatim log message. Should not contain interpolated data. */\n  readonly message: string;\n\n  /** Log severity. */\n  readonly level: LogLevel;\n\n  /**\n   * Where the log message originated. Usually starts with a library or app name,\n   * followed by something more specific.\n   *\n   * @example ['logger-library', 'ConsoleBackend']\n   */\n  readonly origin: ReadonlyArray<string>;\n\n  /**\n   * Key-value pairs that provide additional context for the log message. If\n   * you're tempted to interpolate data into the message, consider using log\n   * context instead.\n   *\n   * These values must be JSON serializable.\n   *\n   * Because it's easy to accidentally include unsuitable log context (e.g.\n   * redux state, PII) nested objects are not allowed. The restriction doesn't\n   * make it impossible, but it makes it harder to miss during code review.\n   *\n   * @example { userId: 123, reason: 'disconnect' }\n   */\n  readonly context: LogContext;\n}\n\nexport enum LogLevel {\n  /** Something critical failed and we can't continue. */\n  Error = 'error',\n\n  /** Something is concerning, but we can keep going. */\n  Warn = 'warn',\n\n  /** High-level progress updates. */\n  Info = 'info',\n\n  /** Extremely verbose progress updates (usually hidden). */\n  Debug = 'debug',\n}\n\nexport type LogContext = Record<\n  string,\n  JsonPrimitive | ReadonlyArray<JsonPrimitive>\n>;\n\ntype JsonPrimitive = string | number | boolean | null | undefined;\n","import type { LogProcessor, LogContext } from './types';\nimport { LogLevel } from './types';\n\nclass Logger {\n  static create(backend: LogProcessor): Logger {\n    return new Logger(backend, []);\n  }\n\n  private constructor(\n    private processor: LogProcessor,\n    private origin: ReadonlyArray<string>\n  ) {\n    // empty\n  }\n\n  /** Extend the logger to attach a class or module name to logs. */\n  namespace(owner: string): Logger {\n    return new Logger(this.processor, this.origin.concat(owner));\n  }\n\n  /** Log a frequent and verbose progress update. */\n  debug(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Debug, message, context);\n  }\n\n  /** Log a high-level progress update. */\n  info(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Info, message, context);\n  }\n\n  /** Log something concerning. */\n  warn(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Warn, message, context);\n  }\n\n  /** Log a critical failure. */\n  error(message: string, context?: LogContext) {\n    this.forwardLog(LogLevel.Error, message, context);\n  }\n\n  private forwardLog(\n    level: LogLevel,\n    message: string,\n    context: LogContext = {}\n  ) {\n    this.processor.processLog({\n      message,\n      level,\n      origin: this.origin,\n      context,\n    });\n  }\n}\n\nexport const createLogger = Logger.create;\n","import type { Log, LogProcessor } from '../types';\n\nclass CombinedLogProcessor implements LogProcessor {\n  constructor(private processors: Array<LogProcessor>) {\n    // empty\n  }\n\n  processLog(log: Log) {\n    this.processors.forEach((processor) => {\n      processor.processLog(log);\n    });\n  }\n}\n\n/**\n * Combine several log processors into a single log processor. Each one is\n * called in sequence. Useful for sending a single log to multiple log\n * destinations.\n */\nexport default function combine(processors: Array<LogProcessor>): LogProcessor {\n  return new CombinedLogProcessor(processors);\n}\n","import type { Log, LogProcessor } from '../types';\n\nclass LogFilter implements LogProcessor {\n  constructor(\n    private predicate: (log: Log) => boolean,\n    private processor: LogProcessor\n  ) {}\n\n  processLog(log: Log) {\n    if (this.predicate(log)) {\n      this.processor.processLog(log);\n    }\n  }\n}\n\n/**\n * Filter logs based on a filter function. If the function returns true, the\n * log is kept and forwarded onto the next processor, otherwise it is\n * discarded.\n */\nexport default function filter(\n  /** Returns `true` to forward the log. */\n  predicate: (log: Log) => boolean,\n  /** Where to send the log if it passes the filter. */\n  processor: LogProcessor\n): LogProcessor {\n  return new LogFilter(predicate, processor);\n}\n"],"names":["LogLevel","Logger","processor","origin","backend","owner","message","context","level","createLogger","CombinedLogProcessor","processors","log","combine","LogFilter","predicate","filter"],"mappings":"oOA0CY,IAAAA,GAAAA,IAEVA,EAAA,MAAQ,QAGRA,EAAA,KAAO,OAGPA,EAAA,KAAO,OAGPA,EAAA,MAAQ,QAXEA,IAAAA,GAAA,CAAA,CAAA,ECvCZ,MAAMC,CAAO,CAKH,YACEC,EACAC,EACR,CAFQ,KAAA,UAAAD,EACA,KAAA,OAAAC,CAGV,CATA,OAAO,OAAOC,EAA+B,CAC3C,OAAO,IAAIH,EAAOG,EAAS,CAAA,CAAE,CAC/B,CAUA,UAAUC,EAAuB,CACxB,OAAA,IAAIJ,EAAO,KAAK,UAAW,KAAK,OAAO,OAAOI,CAAK,CAAC,CAC7D,CAGA,MAAMC,EAAiBC,EAAsB,CAC3C,KAAK,WAAWP,EAAS,MAAOM,EAASC,CAAO,CAClD,CAGA,KAAKD,EAAiBC,EAAsB,CAC1C,KAAK,WAAWP,EAAS,KAAMM,EAASC,CAAO,CACjD,CAGA,KAAKD,EAAiBC,EAAsB,CAC1C,KAAK,WAAWP,EAAS,KAAMM,EAASC,CAAO,CACjD,CAGA,MAAMD,EAAiBC,EAAsB,CAC3C,KAAK,WAAWP,EAAS,MAAOM,EAASC,CAAO,CAClD,CAEQ,WACNC,EACAF,EACAC,EAAsB,CAAA,EACtB,CACA,KAAK,UAAU,WAAW,CACxB,QAAAD,EACA,MAAAE,EACA,OAAQ,KAAK,OACb,QAAAD,CAAA,CACD,CACH,CACF,CAEa,MAAAE,EAAeR,EAAO,OCpDnC,MAAMS,CAA6C,CACjD,YAAoBC,EAAiC,CAAjC,KAAA,WAAAA,CAEpB,CAEA,WAAWC,EAAU,CACd,KAAA,WAAW,QAASV,GAAc,CACrCA,EAAU,WAAWU,CAAG,CAAA,CACzB,CACH,CACF,CAOA,SAAwBC,EAAQF,EAA+C,CACtE,OAAA,IAAID,EAAqBC,CAAU,CAC5C,CCnBA,MAAMG,CAAkC,CACtC,YACUC,EACAb,EACR,CAFQ,KAAA,UAAAa,EACA,KAAA,UAAAb,CACP,CAEH,WAAWU,EAAU,CACf,KAAK,UAAUA,CAAG,GACf,KAAA,UAAU,WAAWA,CAAG,CAEjC,CACF,CAOwB,SAAAI,EAEtBD,EAEAb,EACc,CACP,OAAA,IAAIY,EAAUC,EAAWb,CAAS,CAC3C"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@holz/core",
+  "version": "0.0.0",
+  "description": "A structured and composable logger",
+  "type": "module",
+  "main": "./dist/holz-core.umd.cjs",
+  "module": "./dist/holz-core.js",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PsychoLlama/holz",
+    "directory": "packages/holz-core"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/holz-core.umd.cjs",
+      "import": "./dist/holz-core.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Jesse Gibson",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "structured",
+    "composable",
+    "logger"
+  ],
+  "scripts": {
+    "prepare": "vite build --sourcemap",
+    "test:unit": "vitest --color --passWithNoTests",
+    "test:coverage": "run test:unit --coverage"
+  },
+  "devDependencies": {
+    "@vitest/coverage-c8": "0.28.5",
+    "vite": "^4.0.0",
+    "vitest": "^0.28.5"
+  }
+}

package/src/__tests__/logger.test.ts

@@ -0,0 +1,57 @@
+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 logger = createLogger(backend);
+
+    logger.info('Hello world', { audience: 'testers' });
+
+    expect(backend.processLog).toHaveBeenCalledOnce();
+    expect(backend.processLog).toHaveBeenCalledWith({
+      message: 'Hello world',
+      level: 'info',
+      origin: [],
+      context: { audience: 'testers' },
+    });
+  });
+
+  it.each([
+    [LogLevel.Debug, 'Look, a dead fly', { urgency: 'high' }],
+    [LogLevel.Info, 'I am not a window cleaner!', { state: 'panic' }],
+    [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 logger = createLogger(backend);
+
+    logger[level](message, context);
+    expect(backend.processLog).toHaveBeenCalledWith({
+      message,
+      level,
+      context,
+      origin: [],
+    });
+  });
+
+  describe('namespace', () => {
+    it('extends the origin of the logger', () => {
+      const backend = new TestBackend();
+      const logger = createLogger(backend)
+        .namespace('signaling')
+        .namespace('socket');
+
+      logger.info('opening socket');
+
+      expect(backend.processLog).toHaveBeenCalledOnce();
+      expect(backend.processLog).toHaveBeenCalledWith({
+        message: 'opening socket',
+        level: 'info',
+        origin: ['signaling', 'socket'],
+        context: {},
+      });
+    });
+  });
+});

package/src/backends/test.ts

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

package/src/index.ts

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

package/src/logger.ts

@@ -0,0 +1,55 @@
+import type { LogProcessor, LogContext } from './types';
+import { LogLevel } from './types';
+
+class Logger {
+  static create(backend: LogProcessor): Logger {
+    return new Logger(backend, []);
+  }
+
+  private constructor(
+    private processor: LogProcessor,
+    private origin: ReadonlyArray<string>
+  ) {
+    // empty
+  }
+
+  /** 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));
+  }
+
+  /** Log a frequent and verbose progress update. */
+  debug(message: string, context?: LogContext) {
+    this.forwardLog(LogLevel.Debug, message, context);
+  }
+
+  /** Log a high-level progress update. */
+  info(message: string, context?: LogContext) {
+    this.forwardLog(LogLevel.Info, message, context);
+  }
+
+  /** Log something concerning. */
+  warn(message: string, context?: LogContext) {
+    this.forwardLog(LogLevel.Warn, message, context);
+  }
+
+  /** Log a critical failure. */
+  error(message: string, context?: LogContext) {
+    this.forwardLog(LogLevel.Error, message, context);
+  }
+
+  private forwardLog(
+    level: LogLevel,
+    message: string,
+    context: LogContext = {}
+  ) {
+    this.processor.processLog({
+      message,
+      level,
+      origin: this.origin,
+      context,
+    });
+  }
+}
+
+export const createLogger = Logger.create;

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

@@ -0,0 +1,29 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,28 @@
+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);
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+/**
+ * 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. */
+  processLog(log: Log): void;
+}
+
+/** A log message where variables are carried as structured data. */
+export 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 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',
+}
+
+export type LogContext = Record<
+  string,
+  JsonPrimitive | ReadonlyArray<JsonPrimitive>
+>;
+
+type JsonPrimitive = string | number | boolean | null | undefined;