@holz/core 0.8.0 → 0.8.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Jesse Gibson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/core",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "A structured and composable logger",
   "type": "module",
   "repository": {
@@ -22,8 +22,7 @@
   "license": "MIT",
   "sideEffects": false,
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "keywords": [
     "structured",
@@ -42,5 +41,6 @@
     "vite-plugin-dts": "^4.5.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.0.8"
-  }
-}
+  },
+  "gitHead": "f099a09cd01834de9bc1714908183cbb7b828c85"
+}

package/src/__tests__/logger.test.ts

@@ -1,121 +0,0 @@
-import { createLogger } from '../logger';
-import { level } from '../index';
-
-const SYSTEM_TIME = new Date('2020-06-15T12:30:00Z').getTime();
-
-vi.setSystemTime(SYSTEM_TIME);
-
-describe('Logger', () => {
-  it('sends structured logs to the log processor', () => {
-    const backend = vi.fn();
-    const logger = createLogger(backend);
-
-    logger.info('Hello world', { audience: 'testers' });
-
-    expect(backend).toHaveBeenCalledOnce();
-    expect(backend).toHaveBeenCalledWith({
-      timestamp: SYSTEM_TIME,
-      message: 'Hello world',
-      level: level.info,
-      origin: [],
-      context: { audience: 'testers' },
-    });
-  });
-
-  it.each([
-    ['trace' as const, 'Look, a dead fly', { urgency: 'high?' }],
-    ['debug' as const, 'Made in Britain', { condition: 'fire' }],
-    ['info' as const, 'I am not a window cleaner!', { state: 'panic' }],
-    ['warn' as const, 'There are irregularities in the pension fund', {}],
-    ['error' as const, 'Have you tried turning it off and on again?', {}],
-    ['fatal' as const, 'Leadership has taken a dive', { windows: 'open' }],
-  ])('correctly processes %s log messages', (method, message, context) => {
-    const backend = vi.fn();
-    const logger = createLogger(backend);
-
-    logger[method](message, context);
-    expect(backend).toHaveBeenCalledWith({
-      timestamp: SYSTEM_TIME,
-      message,
-      level: level[method],
-      context,
-      origin: [],
-    });
-  });
-
-  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();
-      const logger = createLogger(backend)
-        .namespace('signaling')
-        .namespace('socket');
-
-      logger.info('opening socket');
-
-      expect(backend).toHaveBeenCalledOnce();
-      expect(backend).toHaveBeenCalledWith({
-        timestamp: SYSTEM_TIME,
-        message: 'opening socket',
-        level: level.info,
-        origin: ['signaling', 'socket'],
-        context: {},
-      });
-    });
-  });
-
-  describe('withMiddleware', () => {
-    it('allows middleware to be added', () => {
-      const backend = vi.fn();
-      const logger = createLogger(backend).withMiddleware((next) => (log) => {
-        next({ ...log, message: 'replaced' });
-      });
-
-      logger.info('original message');
-      expect(backend).toHaveBeenCalledOnce();
-      expect(backend).toHaveBeenCalledWith({
-        timestamp: SYSTEM_TIME,
-        message: 'replaced',
-        level: level.info,
-        origin: [],
-        context: {},
-      });
-    });
-
-    it('inherits middleware from parent loggers', () => {
-      const backend = vi.fn();
-      const logger = createLogger(backend)
-        .withMiddleware((next) => (log) => {
-          log.context.parent = true;
-          next(log);
-        })
-        .namespace('child')
-        .withMiddleware((next) => (log) => {
-          log.context.child = true;
-          next(log);
-        });
-
-      logger.info('original message');
-      expect(backend).toHaveBeenCalledOnce();
-      expect(backend).toHaveBeenCalledWith({
-        timestamp: SYSTEM_TIME,
-        message: 'original message',
-        level: level.info,
-        origin: ['child'],
-        context: { parent: true, child: true },
-      });
-    });
-  });
-});

package/src/__tests__/operators.test.ts

@@ -1,48 +0,0 @@
-import { createLogger } from '../logger';
-import { combine, filter } from '../operators';
-import { level } 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 !== level.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,11 +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/src/logger.ts

@@ -1,63 +0,0 @@
-import {
-  level,
-  type LogContext,
-  type LogLevel,
-  type LogProcessor,
-  type StrictContext,
-  type Logger,
-} from './types';
-
-const createNamespacedLogger = (
-  processor: LogProcessor,
-  namespace: ReadonlyArray<string>,
-): Logger => {
-  const createAndSendLog = <Context extends StrictContext<Context>>(
-    level: LogLevel,
-    message: string,
-    context: Context = {} as Context,
-  ) => {
-    processor({
-      timestamp: Date.now(),
-      message,
-      level,
-      origin: namespace,
-      context: context as LogContext,
-    });
-  };
-
-  const logger: Logger = {
-    owner: namespace,
-    trace: createAndSendLog.bind(null, level.trace),
-    debug: createAndSendLog.bind(null, level.debug),
-    info: createAndSendLog.bind(null, level.info),
-    warn: createAndSendLog.bind(null, level.warn),
-    error: createAndSendLog.bind(null, level.error),
-    fatal: createAndSendLog.bind(null, level.fatal),
-    namespace: (child: string) =>
-      createNamespacedLogger(processor, namespace.concat(child)),
-    withMiddleware: (middleware) =>
-      createNamespacedLogger(middleware(processor), namespace),
-  };
-
-  // Non-enumerable to keep the repl clean.
-  const hidden = { configurable: false, enumerable: false };
-  return Object.defineProperties(logger, {
-    withMiddleware: hidden,
-    namespace: hidden,
-    trace: hidden,
-    debug: hidden,
-    info: hidden,
-    warn: hidden,
-    error: hidden,
-    fatal: hidden,
-  });
-};
-
-/**
- * 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 =>
-  createNamespacedLogger(processor, []);

package/src/operators.ts

@@ -1,29 +0,0 @@
-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 const combine =
-  (processors: Array<LogProcessor>): LogProcessor =>
-  (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 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 =>
-  (log: Log) => {
-    if (predicate(log)) {
-      processor(log);
-    }
-  };

package/src/types.ts

@@ -1,161 +0,0 @@
-/**
- * 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 const level = {
-  /** A critical failure happened and the program must exit. */
-  fatal: 60,
-
-  /** Something failed, but we can keep going. */
-  error: 50,
-
-  /** Cause for concern, but we can keep going. */
-  warn: 40,
-
-  /** High-level progress updates. */
-  info: 30,
-
-  /** Verbose update about events or control flow (usually hidden). */
-  debug: 20,
-
-  /** Extremely detailed progress updates (usually hidden). */
-  trace: 10,
-} as const;
-
-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;
-}