@holz/env-filter 0.2.0 → 0.6.0

package/README.md

@@ -0,0 +1,62 @@
+# `@holz/env-filter`
+
+Builds on [`@holz/pattern-filter`](https://github.com/PsychoLlama/holz/tree/main/packages/holz-pattern-filter) to filter logs based on your current environment, loading the pattern from `process.env.DEBUG` or `localStorage.debug`.
+
+## Usage
+
+```typescript
+import { createEnvironmentFilter } from '@holz/env-filter';
+import { createLogger } from '@holz/core';
+
+createLogger(
+  createEnvironmentFilter({
+    processor: plugin,
+  })
+);
+```
+
+## Configuration Options
+
+`createEnvironmentFilter()` accepts the following configuration options:
+
+- `processor`: The log processor to use. Required.
+- `pattern`: The pattern to use for filtering logs. If not provided, the pattern will be loaded from the environment.
+- `defaultPattern`: The default pattern to use if no pattern is provided or detected in the environment. Default is `'*'` (all logs).
+- `localStorageKey`: The name of the key used to store the pattern in localStorage. Default is `'debug'`.
+- `environmentVariable`: The name of the environment variable used to store the pattern. Default is `'DEBUG'`.
+
+Note that the `pattern` option will override any pattern detected in the environment.
+
+## How it Works
+
+`createEnvironmentFilter()` loads the pattern from the environment using the following process:
+
+- It looks for a pattern stored in `localStorage` with the key specified in `localStorageKey`. If found, it uses that pattern.
+- If `localStorage` is not available or doesn't contain a pattern with the specified key, it looks for a pattern stored in `process.env` specified in `environmentVariable`. If found, it uses that pattern.
+- If no pattern is found in either `localStorage` or the environment variable, it uses the default pattern specified in `defaultPattern`.
+
+Once the pattern is loaded, `createEnvironmentFilter()` uses `createPatternFilter()` from [`@holz/pattern-filter`](https://github.com/PsychoLlama/holz/tree/main/packages/holz-pattern-filter) to create a log processor that filters logs based on the loaded pattern.
+
+## Example
+
+Suppose you want to filter logs in development that come from your app, but disable all logs in production. You can use `@holz/env-filter` to accomplish this by setting the `DEBUG` environment variable in development:
+
+```bash
+DEBUG=your-app*
+```
+
+In production, you may want to disable all logging by default. This can be done by setting the default pattern to an empty string:
+
+```typescript
+import { createEnvironmentFilter } from '@holz/env-filter';
+import { createLogger } from '@holz/core';
+
+const logger = createLogger(
+  createEnvironmentFilter({
+    processor: yourProcessor,
+    defaultPattern: '',
+  })
+);
+```
+
+With this configuration, logs will be disabled by default in production, and only logs originating from the `your-app` namespace will be shown in development.

package/dist/holz-env-filter.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const n=require("@holz/pattern-filter"),o="debug",i=e=>{try{if(typeof localStorage<"u")return localStorage.getItem(e)??void 0}catch{}},l=(e,r)=>{try{typeof localStorage<"u"&&localStorage.setItem(e,r)}catch{}},a=e=>typeof e>"u"||Object(e).type==="renderer"||Object(e).browser===!0||Object(e).__nwjs?t.Browser:t.Server;var t=(e=>(e.Browser="browser",e.Server="server",e))(t||{});const c=e=>{if(typeof process<"u"&&"env"in process)return process.env[e]};class s{constructor(r){this.env=a(globalThis.process),this.processor=r.processor,this.replaceFilter(r.pattern??this.loadPattern()??r.defaultPattern??"*")}processLog(r){this.filter.processLog(r)}setPattern(r){this.replaceFilter(r),this.env===t.Browser&&l(o,r)}getPattern(){return this.filter.pattern}loadPattern(){return i(o)??c("DEBUG")}replaceFilter(r){this.filter=new n.PatternFilter({processor:this.processor,pattern:r})}}exports.EnvironmentFilter=s;exports.default=s;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("@holz/pattern-filter"),c=e=>{if(typeof process<"u"&&"env"in process)return process.env[e]},l=e=>{try{if(typeof localStorage<"u")return localStorage.getItem(e)??void 0}catch{}},s=({processor:e,pattern:t,defaultPattern:r,localStorageKey:n="debug",environmentVariable:o="DEBUG"})=>{const a=()=>l(n)??c(o);return i.createPatternFilter({processor:e,pattern:t??a()??r??"*"})};exports.createEnvironmentFilter=s;

package/dist/holz-env-filter.js

@@ -1,57 +1,23 @@
-import { PatternFilter as s } from "@holz/pattern-filter";
-const o = "debug", n = (e) => {
+import { createPatternFilter as a } from "@holz/pattern-filter";
+const c = (e) => {
+  if (typeof process < "u" && "env" in process)
+    return process.env[e];
+}, i = (e) => {
   try {
     if (typeof localStorage < "u")
       return localStorage.getItem(e) ?? void 0;
   } catch {
   }
-}, a = (e, r) => {
-  try {
-    typeof localStorage < "u" && localStorage.setItem(e, r);
-  } catch {
-  }
-}, c = (e) => typeof e > "u" || Object(e).type === "renderer" || Object(e).browser === !0 || Object(e).__nwjs ? t.Browser : t.Server;
-var t = /* @__PURE__ */ ((e) => (e.Browser = "browser", e.Server = "server", e))(t || {});
-const i = (e) => {
-  if (typeof process < "u" && "env" in process)
-    return process.env[e];
-};
-class f {
-  constructor(r) {
-    this.env = c(globalThis.process), this.processor = r.processor, this.replaceFilter(
-      r.pattern ?? this.loadPattern() ?? r.defaultPattern ?? "*"
-    );
-  }
-  processLog(r) {
-    this.filter.processLog(r);
-  }
-  /**
-   * Change the pattern used to filter logs. If the environment supports it,
-   * it will attempt to persist your preference.
-   */
-  setPattern(r) {
-    this.replaceFilter(r), this.env === t.Browser && a(o, r);
-  }
-  /** Return the current filter pattern. */
-  getPattern() {
-    return this.filter.pattern;
-  }
-  /**
-   * Load from localStorage falling back to `process.env`. We always check
-   * both because we might be in Electron, where both are defined and equally
-   * valid.
-   */
-  loadPattern() {
-    return n(o) ?? i("DEBUG");
-  }
-  replaceFilter(r) {
-    this.filter = new s({
-      processor: this.processor,
-      pattern: r
-    });
-  }
-}
+}, m = ({
+  processor: e,
+  pattern: t,
+  defaultPattern: r,
+  localStorageKey: n = "debug",
+  environmentVariable: o = "DEBUG"
+}) => a({
+  processor: e,
+  pattern: t ?? (() => i(n) ?? c(o))() ?? r ?? "*"
+});
 export {
-  f as EnvironmentFilter,
-  f as default
+  m as createEnvironmentFilter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holz/env-filter",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "description": "Filter logs based on the current environment.",
   "type": "module",
   "main": "./dist/holz-env-filter.cjs",
@@ -40,12 +40,12 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@holz/pattern-filter": "0.2.0"
+    "@holz/pattern-filter": "^0.6.0"
   },
   "devDependencies": {
-    "@holz/core": "0.2.0",
+    "@holz/core": "^0.6.0",
     "@types/node": "^18.14.0",
-    "@vitest/coverage-c8": "0.28.5",
+    "@vitest/coverage-c8": "^0.28.5",
     "vite": "^4.0.0",
     "vitest": "^0.28.5"
   }

package/src/__tests__/environment-filter.test.ts

@@ -1,15 +1,17 @@
-import type { LogProcessor } from '@holz/core';
 import { createLogger } from '@holz/core';
-import EnvironmentFilter from '../environment-filter';
+import { createEnvironmentFilter } from '../environment-filter';
+import { getLocalStorageKey, getEnvironmentVariable } from '../get-env';
 
-class TestBackend implements LogProcessor {
-  processLog = vi.fn();
-}
+vi.mock('../get-env');
 
 describe('EnvironmentFilter', () => {
-  it('filters against the selected pattern', () => {
-    const backend = new TestBackend();
-    const filter = new EnvironmentFilter({
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('uses the given pattern as an override', () => {
+    const backend = vi.fn();
+    const filter = createEnvironmentFilter({
       pattern: '-ignored, -*:wild, *',
       processor: backend,
     });
@@ -17,22 +19,22 @@ describe('EnvironmentFilter', () => {
     const logger = createLogger(filter);
 
     logger.namespace('ignored').info('excluded by filter');
-    expect(backend.processLog).not.toHaveBeenCalled();
+    expect(backend).not.toHaveBeenCalled();
 
     logger.namespace('something').namespace('wild').info('also excluded');
-    expect(backend.processLog).not.toHaveBeenCalled();
+    expect(backend).not.toHaveBeenCalled();
 
     logger.namespace('app').info('not ignored');
-    expect(backend.processLog).toHaveBeenCalledWith(
+    expect(backend).toHaveBeenCalledWith(
       expect.objectContaining({
         message: 'not ignored',
       })
     );
   });
 
-  it('uses the fallback pattern if the env is unset', () => {
-    const backend = new TestBackend();
-    const filter = new EnvironmentFilter({
+  it('uses the fallback pattern if none exist in the environment', () => {
+    const backend = vi.fn();
+    const filter = createEnvironmentFilter({
       pattern: undefined,
       defaultPattern: '*, -ignored',
       processor: backend,
@@ -41,17 +43,17 @@ describe('EnvironmentFilter', () => {
     const logger = createLogger(filter);
 
     logger.namespace('ignored').info('excluded by filter');
-    expect(backend.processLog).not.toHaveBeenCalled();
+    expect(backend).not.toHaveBeenCalled();
 
     logger.info('not ignored');
-    expect(backend.processLog).toHaveBeenCalledWith(
+    expect(backend).toHaveBeenCalledWith(
       expect.objectContaining({ message: 'not ignored' })
     );
   });
 
   it('prints everything by default', () => {
-    const backend = new TestBackend();
-    const filter = new EnvironmentFilter({
+    const backend = vi.fn();
+    const filter = createEnvironmentFilter({
       pattern: undefined,
       processor: backend,
     });
@@ -59,38 +61,34 @@ describe('EnvironmentFilter', () => {
     const logger = createLogger(filter);
 
     logger.info('not excluded');
-    expect(backend.processLog).toHaveBeenCalledWith(
+    expect(backend).toHaveBeenCalledWith(
       expect.objectContaining({ message: 'not excluded' })
     );
   });
 
-  it('can change the pattern on the fly', () => {
-    const backend = new TestBackend();
-    const filter = new EnvironmentFilter({
-      pattern: '',
+  it('allows you to choose a different localStorage key', () => {
+    const backend = vi.fn();
+    const filter = createEnvironmentFilter({
       processor: backend,
+      localStorageKey: 'override',
     });
 
     const logger = createLogger(filter);
+    logger.info('just print something');
 
-    logger.info('all logs excluded');
-    expect(backend.processLog).not.toHaveBeenCalled();
-
-    filter.setPattern('*');
-    logger.info('all logs printed');
-    expect(backend.processLog).toHaveBeenCalledWith(
-      expect.objectContaining({ message: 'all logs printed' })
-    );
+    expect(getLocalStorageKey).toHaveBeenCalledWith('override');
   });
 
-  it('can retrieve the current pattern', () => {
-    const backend = new TestBackend();
-    const filter = new EnvironmentFilter({
-      pattern: undefined,
-      defaultPattern: '*, -ignored',
+  it('allows you to choose a different environment variable', () => {
+    const backend = vi.fn();
+    const filter = createEnvironmentFilter({
       processor: backend,
+      environmentVariable: 'OVERRIDE',
     });
 
-    expect(filter.getPattern()).toBe('*, -ignored');
+    const logger = createLogger(filter);
+    logger.info('just print something');
+
+    expect(getEnvironmentVariable).toHaveBeenCalledWith('OVERRIDE');
   });
 });

package/src/__tests__/get-env.test.ts

@@ -0,0 +1,68 @@
+import * as env from '../get-env';
+
+class MockLocalStorage {
+  private store = new Map();
+
+  getItem = vi.fn((key: string) => this.store.get(key) ?? null);
+  setItem = vi.fn((key: string, value: string) => {
+    this.store.set(key, value);
+  });
+}
+
+describe('environment', () => {
+  describe('getLocalStorageKey', () => {
+    const STORAGE_KEY = 'test-key';
+
+    function setup() {
+      const localStorage = new MockLocalStorage();
+
+      Object.assign(globalThis, { localStorage });
+
+      return {
+        localStorage,
+      };
+    }
+
+    beforeEach(() => {
+      Object.assign(globalThis, { localStorage: undefined });
+    });
+
+    describe('getLocalStorageKey', () => {
+      it('returns the value stored in localStorage, or undefined', () => {
+        const { localStorage } = setup();
+
+        expect(env.getLocalStorageKey(STORAGE_KEY)).toBeUndefined();
+        localStorage.setItem(STORAGE_KEY, 'yolo');
+        expect(env.getLocalStorageKey(STORAGE_KEY)).toBe('yolo');
+      });
+
+      it('survives if the localStorage lookup fails', () => {
+        const { localStorage } = setup();
+
+        localStorage.getItem.mockImplementation(() => {
+          throw new Error('Simulating localStorage DOM exception');
+        });
+
+        expect(env.getLocalStorageKey(STORAGE_KEY)).toBeUndefined();
+      });
+
+      it('survives if localStorage is not available', () => {
+        expect(env.getLocalStorageKey(STORAGE_KEY)).toBeUndefined();
+      });
+    });
+  });
+
+  describe('getEnvVariable', () => {
+    const ENV_KEY = 'HOLZ_DEBUG_TEST_PATTERN';
+
+    beforeEach(() => {
+      delete process.env[ENV_KEY];
+    });
+
+    it('returns the value stored in process.env', () => {
+      expect(env.getEnvironmentVariable(ENV_KEY)).toBeUndefined();
+      process.env[ENV_KEY] = '-stuff:*';
+      expect(env.getEnvironmentVariable(ENV_KEY)).toBe('-stuff:*');
+    });
+  });
+});

package/src/environment-filter.ts

@@ -1,61 +1,31 @@
-import type { Log, LogProcessor } from '@holz/core';
-import { PatternFilter } from '@holz/pattern-filter';
-import * as browserEnv from './browser-env';
-import { detectEnvironment, Environment } from './environment';
-import * as serverEnv from './server-env';
-
-/**
- * Reads the debug pattern from the environment and uses it to filter logs.
- */
-export default class EnvironmentFilter implements LogProcessor {
-  private processor: LogProcessor;
-  private filter!: PatternFilter;
-  private env = detectEnvironment(globalThis.process);
-
-  constructor(options: Config) {
-    this.processor = options.processor;
-    this.replaceFilter(
-      options.pattern ?? this.loadPattern() ?? options.defaultPattern ?? '*'
-    );
-  }
-
-  processLog(log: Log) {
-    this.filter.processLog(log);
-  }
-
-  /**
-   * Change the pattern used to filter logs. If the environment supports it,
-   * it will attempt to persist your preference.
-   */
-  setPattern(pattern: string) {
-    this.replaceFilter(pattern);
-
-    if (this.env === Environment.Browser) {
-      browserEnv.save(browserEnv.STORAGE_KEY, pattern);
-    }
-  }
-
-  /** Return the current filter pattern. */
-  getPattern() {
-    return this.filter.pattern;
-  }
-
+import type { LogProcessor } from '@holz/core';
+import { createPatternFilter } from '@holz/pattern-filter';
+import { getEnvironmentVariable, getLocalStorageKey } from './get-env';
+
+export const createEnvironmentFilter = ({
+  processor,
+  pattern,
+  defaultPattern,
+  localStorageKey = 'debug',
+  environmentVariable = 'DEBUG',
+}: Config): LogProcessor => {
   /**
    * Load from localStorage falling back to `process.env`. We always check
    * both because we might be in Electron, where both are defined and equally
    * valid.
    */
-  private loadPattern() {
-    return browserEnv.load(browserEnv.STORAGE_KEY) ?? serverEnv.load('DEBUG');
-  }
+  const loadPatternFromEnvironment = () => {
+    return (
+      getLocalStorageKey(localStorageKey) ??
+      getEnvironmentVariable(environmentVariable)
+    );
+  };
 
-  private replaceFilter(pattern: string) {
-    this.filter = new PatternFilter({
-      processor: this.processor,
-      pattern,
-    });
-  }
-}
+  return createPatternFilter({
+    processor,
+    pattern: pattern ?? loadPatternFromEnvironment() ?? defaultPattern ?? '*',
+  });
+};
 
 interface Config {
   /** Replace the detected pattern with something else. */
@@ -66,4 +36,10 @@ interface Config {
 
   /** Where to send the logs if they pass the filter. */
   processor: LogProcessor;
+
+  /** The localStorage key where patterns are saved. Default is `debug`. */
+  localStorageKey?: string;
+
+  /** The environment variable where patterns are saved. Default is `DEBUG`. */
+  environmentVariable?: string;
 }

package/src/get-env.ts

@@ -0,0 +1,16 @@
+export const getEnvironmentVariable = (key: string): undefined | string => {
+  if (typeof process !== 'undefined' && 'env' in process) {
+    return process.env[key];
+  }
+};
+
+export const getLocalStorageKey = (key: string): undefined | string => {
+  try {
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem(key) ?? undefined;
+    }
+  } catch (error) {
+    // Sometimes localStorage fails (e.g. in Safari private mode). That's
+    // okay. We'll just use a fallback pattern.
+  }
+};

package/src/index.ts

@@ -1 +1 @@
-export { default, default as EnvironmentFilter } from './environment-filter';
+export { createEnvironmentFilter } from './environment-filter';

package/src/__tests__/browser-env.test.ts

@@ -1,61 +0,0 @@
-import * as browser from '../browser-env';
-
-class MockLocalStorage {
-  getItem = vi.fn((): null | string => null);
-  setItem = vi.fn();
-}
-
-describe('Browser environment', () => {
-  function setup() {
-    const localStorage = new MockLocalStorage();
-
-    Object.assign(globalThis, { localStorage });
-
-    return {
-      localStorage,
-    };
-  }
-
-  beforeEach(() => {
-    Object.assign(globalThis, { localStorage: undefined });
-  });
-
-  describe('load', () => {
-    it('returns the value stored in localStorage, or undefined', () => {
-      const { localStorage } = setup();
-
-      expect(browser.load(browser.STORAGE_KEY)).toBeUndefined();
-      localStorage.getItem.mockReturnValue('yolo');
-      expect(browser.load(browser.STORAGE_KEY)).toBe('yolo');
-    });
-
-    it('survives if the localStorage lookup fails', () => {
-      const { localStorage } = setup();
-
-      localStorage.getItem.mockImplementation(() => {
-        throw new Error('Simulating localStorage DOM exception');
-      });
-
-      expect(browser.load(browser.STORAGE_KEY)).toBeUndefined();
-    });
-
-    it('survives if localStorage is not available', () => {
-      expect(browser.load(browser.STORAGE_KEY)).toBeUndefined();
-    });
-  });
-
-  describe('save', () => {
-    it('saves the value in localStorage', () => {
-      const { localStorage } = setup();
-
-      browser.save(browser.STORAGE_KEY, 'yolo');
-      expect(localStorage.setItem).toHaveBeenCalledWith('debug', 'yolo');
-    });
-
-    it('survives if localStorage is not available', () => {
-      const pass = () => browser.save(browser.STORAGE_KEY, 'no storage');
-
-      expect(pass).not.toThrow();
-    });
-  });
-});

package/src/__tests__/environment.test.ts

@@ -1,11 +0,0 @@
-import { detectEnvironment, Environment } from '../environment';
-
-describe('detectEnvironment', () => {
-  it('detects the correct environment', () => {
-    expect(detectEnvironment(undefined)).toBe(Environment.Browser);
-    expect(detectEnvironment({ browser: true })).toBe(Environment.Browser);
-    expect(detectEnvironment({ type: 'renderer' })).toBe(Environment.Browser);
-    expect(detectEnvironment({ __nwjs: true })).toBe(Environment.Browser);
-    expect(detectEnvironment(process)).toBe(Environment.Server);
-  });
-});

package/src/browser-env.ts

@@ -1,22 +0,0 @@
-export const STORAGE_KEY = 'debug';
-
-export const load = (key: string): undefined | string => {
-  try {
-    if (typeof localStorage !== 'undefined') {
-      return localStorage.getItem(key) ?? undefined;
-    }
-  } catch (error) {
-    // Sometimes localStorage fails (e.g. in Safari private mode). That's
-    // okay.
-  }
-};
-
-export const save = (key: string, pattern: string) => {
-  try {
-    if (typeof localStorage !== 'undefined') {
-      localStorage.setItem(key, pattern);
-    }
-  } catch (error) {
-    // Throwing might break a startup script. Don't do that.
-  }
-};

package/src/environment.ts

@@ -1,19 +0,0 @@
-/**
- * Detect Electron renderer / nwjs processes, which are node, but we should
- * treat them as a browser.
- *
- * Credit: debug-js
- */
-export const detectEnvironment = (process: unknown) => {
-  return typeof process === 'undefined' ||
-    Object(process).type === 'renderer' ||
-    Object(process).browser === true ||
-    Object(process).__nwjs
-    ? Environment.Browser
-    : Environment.Server;
-};
-
-export enum Environment {
-  Browser = 'browser',
-  Server = 'server',
-}

package/src/server-env.ts

@@ -1,9 +0,0 @@
-export const load = (key: string): undefined | string => {
-  if (typeof process !== 'undefined' && 'env' in process) {
-    return process.env[key];
-  }
-};
-
-export const save = () => {
-  // The effect would be useless. Don't bother.
-};