@holz/log-collector 0.8.0-rc.1

package/README.md

@@ -0,0 +1,75 @@
+# `@holz/log-collector`
+
+Supports replacing the global logging destination for all loggers in your app.
+
+## Purpose
+
+Let's say you're building an app, and your app uses libraries that manage logs with Holz. Your app uploads logs to a central logging backend and you want to include logs from some of those libraries. That's where `@holz/log-collector` comes in.
+
+On startup you set a global log collector. Libraries detect this automatically and **replace** their log destination with whatever you provide. Now you control all logs and can selectively upload to your backend.
+
+Other use cases:
+
+- **Central Log Files:** Redirect all server logs to a file, including logs from specific libraries.
+- **External Debuggers:** Depending on your environment, it may be useful to view logs in a separate application like [OTel Desktop Viewer](https://github.com/CtrlSpice/otel-desktop-viewer) or [DebugView](https://docs.microsoft.com/en-us/sysinternals/downloads/debugview). A log collector can act as the central exporter.
+- **Interactive TUIs:** Renderers like [Ink](https://github.com/vadimdemedes/ink) expect control of the screen. Logs can damage rendering. A solution might redirect logs to a file stream or a custom logs window.
+- **Patching Broken Logs:** If an unexpected input starts throwing errors, you have the ability to patch it without making upstream changes.
+
+## Usage in Apps
+
+Set a global log collector as soon as the app starts. This is typically done in the main entry file of your app.
+
+```typescript
+import { setGlobalLogCollector } from '@holz/log-collector';
+
+setGlobalLogCollector({
+  // Called for every log in your app so long as `condition` returns true.
+  processor: (log) => {
+    // ...
+  },
+
+  // [Optional] Decide which logs to collect. Defaults to all logs.
+  condition: (log) => log.origin[0] === 'some-library',
+});
+```
+
+- **processor:** Called for every log so long as `condition` returns true. The signature is a Holz plugin, which means you can pass your app's log pipeline verbatim (whatever you passed to `createLogger`).
+- **condition:** A function that decides which logs to collect. By default it captures everything. If it returns `false`, logs are sent to their original destination.
+
+---
+
+To remove a global log collector and restore defaults, call `unsetGlobalLogCollector`:
+
+```typescript
+import { unsetGlobalLogCollector } from '@holz/log-collector';
+
+unsetGlobalLogCollector();
+```
+
+This is primarily used in tests.
+
+## Usage in Libraries
+
+> [!NOTE]
+> This plugin is included by default with `@holz/logger`.
+
+This should be the **first plugin** in your log pipeline.
+
+```typescript
+import { createLogCollector } from '@holz/log-collector';
+import { createLogger } from '@holz/core';
+
+const logger = createLogger(
+  createLogCollector({
+    fallback: (log) => {
+      // Default log backend. Called if no global log collector is set.
+    },
+  }),
+);
+```
+
+- **fallback:** Called if no global log collector is set, or if `condition` returns false. This is the default log backend. The signature is a Holz plugin.
+
+The expectation is the collector captures logs before any side effects happen, such as logging to the console or sending to a file.
+
+Be aware that `logger.withMiddleware(...)` runs before the default logging backend, so take care to avoid side effects in those handlers.

package/dist/holz-log-collector.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=()=>!0,s=({processor:t,condition:o=n})=>{e[c]={processor:t,condition:o}},r=()=>{delete e[c]},e=globalThis,c=Symbol.for("@holz/log-collector"),a=t=>o=>{const l=e[c];l!=null&&l.condition(o)?l.processor(o):t.fallback(o)};exports.createLogCollector=a;exports.setGlobalLogCollector=s;exports.unsetGlobalLogCollector=r;

package/dist/holz-log-collector.d.ts

@@ -0,0 +1,37 @@
+import { Log } from '@holz/core';
+import { LogProcessor } from '@holz/core';
+
+declare interface Config {
+    fallback: LogProcessor;
+}
+
+/**
+ * Redirects logs to a global collector if one is configured. This is designed
+ * with apps in mind, which may want to aggregate logs from multiple sources.
+ */
+export declare const createLogCollector: (config: Config) => LogProcessor;
+
+declare interface InterceptorConfig {
+    /** Plugin handling all logs captured by the interceptor. */
+    processor: LogProcessor;
+    /**
+     * Only capture logs matching this function. Return `false` to use the
+     * default log destination. Defaults to capture all logs.
+     */
+    condition?: (log: Log) => boolean;
+}
+
+/**
+ * Overrides the default log destination for all loggers in the app. Call this
+ * early on startup. If logs are sent before registering the collector, they
+ * will be lost.
+ */
+export declare const setGlobalLogCollector: ({ processor, condition: match, }: InterceptorConfig) => void;
+
+/**
+ * Remove the global log collector restoring defaults. Safe to call regardless
+ * of whether one is set.
+ */
+export declare const unsetGlobalLogCollector: () => void;
+
+export { }

package/dist/holz-log-collector.js

@@ -0,0 +1,16 @@
+const n = () => !0, s = ({
+  processor: t,
+  condition: o = n
+}) => {
+  c[e] = { processor: t, condition: o };
+}, r = () => {
+  delete c[e];
+}, c = globalThis, e = Symbol.for("@holz/log-collector"), i = (t) => (o) => {
+  const l = c[e];
+  l != null && l.condition(o) ? l.processor(o) : t.fallback(o);
+};
+export {
+  i as createLogCollector,
+  s as setGlobalLogCollector,
+  r as unsetGlobalLogCollector
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@holz/log-collector",
+  "version": "0.8.0-rc.1",
+  "description": "Send all logs to a central collector",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PsychoLlama/holz",
+    "directory": "packages/holz-log-collector"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/holz-log-collector.d.ts",
+      "require": "./dist/holz-log-collector.cjs",
+      "import": "./dist/holz-log-collector.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Jesse Gibson",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "holz",
+    "collector",
+    "interceptor",
+    "aggregator"
+  ],
+  "scripts": {
+    "prepack": "vite build",
+    "test:unit": "vitest --color --passWithNoTests",
+    "test:types": "tsc"
+  },
+  "peerDependencies": {
+    "@holz/core": "^0.8.0-rc.2"
+  },
+  "devDependencies": {
+    "@holz/core": "^0.8.0-rc.2",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.8",
+    "typescript": "^5.8.2",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.0.8"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/__snapshots__/json-backend.test.ts.snap

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`JSON backend > prints the logs to the writable stream 1`] = `
+"{"level":"debug","time":"2020-06-15T12:00:00.000Z","msg":"shout"}
+{"level":"info","time":"2020-06-15T12:00:00.000Z","msg":"normal"}
+{"level":"warn","time":"2020-06-15T12:00:00.000Z","msg":"hmmmm"}
+{"level":"error","time":"2020-06-15T12:00:00.000Z","msg":"oh no"}
+"
+`;

package/src/__tests__/log-collector.test.ts

@@ -0,0 +1,76 @@
+import { createLogger, level } from '@holz/core';
+import {
+  createLogCollector,
+  unsetGlobalLogCollector,
+  setGlobalLogCollector,
+} from '../index';
+
+const CURRENT_TIME = new Date('2010-10-01T00:00:00Z').getTime();
+
+vi.setSystemTime(CURRENT_TIME);
+
+describe('log collector', () => {
+  afterEach(() => {
+    unsetGlobalLogCollector();
+  });
+
+  describe('createLogInterceptor', () => {
+    it('sends logs to the default backend', () => {
+      const fallback = vi.fn();
+      const logger = createLogger(createLogCollector({ fallback }));
+
+      logger.info('test message');
+      expect(fallback).toHaveBeenCalledOnce();
+      expect(fallback).toHaveBeenCalledWith({
+        timestamp: CURRENT_TIME,
+        message: 'test message',
+        level: level.info,
+        origin: [],
+        context: {},
+      });
+    });
+
+    it('sends logs to the interceptor if defined', () => {
+      const interceptor = vi.fn();
+      const fallback = vi.fn();
+      const logger = createLogger(createLogCollector({ fallback }));
+
+      setGlobalLogCollector({
+        processor: interceptor,
+      });
+
+      logger.info('test message');
+      expect(fallback).not.toHaveBeenCalled();
+      expect(interceptor).toHaveBeenCalledOnce();
+      expect(interceptor).toHaveBeenCalledWith({
+        timestamp: CURRENT_TIME,
+        message: 'test message',
+        level: level.info,
+        origin: [],
+        context: {},
+      });
+    });
+
+    it('uses the default backend if the interceptor does not match', () => {
+      const interceptor = vi.fn();
+      const fallback = vi.fn();
+      const logger = createLogger(createLogCollector({ fallback }));
+
+      setGlobalLogCollector({
+        processor: interceptor,
+        condition: () => false,
+      });
+
+      logger.info('test message');
+      expect(interceptor).not.toHaveBeenCalled();
+      expect(fallback).toHaveBeenCalledOnce();
+      expect(fallback).toHaveBeenCalledWith({
+        timestamp: CURRENT_TIME,
+        message: 'test message',
+        level: level.info,
+        origin: [],
+        context: {},
+      });
+    });
+  });
+});

package/src/global.ts

@@ -0,0 +1,45 @@
+import type { Log, LogProcessor } from '@holz/core';
+
+const MATCH_ALL = () => true;
+
+/**
+ * Overrides the default log destination for all loggers in the app. Call this
+ * early on startup. If logs are sent before registering the collector, they
+ * will be lost.
+ */
+export const setGlobalLogCollector = ({
+  processor,
+  condition: match = MATCH_ALL,
+}: InterceptorConfig) => {
+  globalScope[COLLECTOR_SYMBOL] = { processor, condition: match };
+};
+
+/**
+ * Remove the global log collector restoring defaults. Safe to call regardless
+ * of whether one is set.
+ */
+export const unsetGlobalLogCollector = () => {
+  delete globalScope[COLLECTOR_SYMBOL];
+};
+
+interface InterceptorConfig {
+  /** Plugin handling all logs captured by the interceptor. */
+  processor: LogProcessor;
+
+  /**
+   * Only capture logs matching this function. Return `false` to use the
+   * default log destination. Defaults to capture all logs.
+   */
+  condition?: (log: Log) => boolean;
+}
+
+// As of 2025-04-12 there is no way to declare a symbol on `globalThis`.
+export const globalScope = globalThis as unknown as GlobalContext;
+
+// Stored in the global scope. Uses the symbol registry in case multiple
+// versions of Holz are loaded in the same context.
+export const COLLECTOR_SYMBOL = Symbol.for('@holz/log-collector');
+
+interface GlobalContext {
+  [COLLECTOR_SYMBOL]?: Required<InterceptorConfig>;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createLogCollector } from './log-collector';
+export { setGlobalLogCollector, unsetGlobalLogCollector } from './global';

package/src/log-collector.ts

@@ -0,0 +1,22 @@
+import type { LogProcessor } from '@holz/core';
+import { globalScope, COLLECTOR_SYMBOL } from './global';
+
+/**
+ * Redirects logs to a global collector if one is configured. This is designed
+ * with apps in mind, which may want to aggregate logs from multiple sources.
+ */
+export const createLogCollector =
+  (config: Config): LogProcessor =>
+  (log) => {
+    const collector = globalScope[COLLECTOR_SYMBOL];
+
+    if (collector?.condition(log)) {
+      collector.processor(log);
+    } else {
+      config.fallback(log);
+    }
+  };
+
+export interface Config {
+  fallback: LogProcessor;
+}