@holz/core 0.6.0 → 0.7.0-rc.1

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||{});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;
+"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,58 +1,60 @@
-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));
+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 f(o, r) {
-  return (e) => {
-    o(e) && r(e);
+function h(e, r) {
+  return (o) => {
+    e(o) && r(o);
   };
 }
-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 };
+class i {
+  constructor(r, o) {
+    /** 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: t,
-      debug: t,
-      info: t,
-      warn: t,
-      error: t
+      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 a(r, []);
-  }
   /** Extend the logger to attach a class or module name to logs. */
   namespace(r) {
-    return new a(this.processor, this.owner.concat(r));
+    return new i(this.processor, this.owner.concat(r));
   }
-  forwardLog(r, e, t = {}) {
+  forwardLog(r, o, n = {}) {
     this.processor({
-      message: e,
+      message: o,
       level: r,
       origin: this.owner,
-      context: t
+      context: n
     });
   }
 }
-const h = a.create;
+const w = (e) => new i(e, []);
 export {
-  i as LogLevel,
-  c as combine,
-  h as createLogger,
-  f 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.6.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__/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,19 +2,9 @@ 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 repl clean.
     const hidden = { configurable: false, enumerable: false };
@@ -55,7 +45,7 @@ class Logger {
   private forwardLog(
     level: LogLevel,
     message: string,
-    context: LogContext = {}
+    context: LogContext = {},
   ) {
     this.processor({
       message,
@@ -66,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)) {