Merge pull request 'docs: Add Development, CI, and Maintenance sections to README' (#8) from update-readme-dev-guide into main

The  action is a GitHub Marketplace action
that doesn't exist on self-hosted Gitea instances. Replace it with
the standard curl-based Bun installation method and add ~/.bun/bin
to GITHUB_PATH.

eslint.config.mjs

@@ -3,7 +3,7 @@ import tsParser from '@typescript-eslint/parser'
 import eslintJs from '@eslint/js'
 import eslintTs from 'typescript-eslint'
 
-const tsFiles = ['src/**/*.ts', 'test/**/*.ts']
+const tsFiles = ['src/**/*.ts']
 
 const customTypescriptConfig = {
   files: tsFiles,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jdbernard/logging",
-  "version": "2.5.0",
+  "version": "2.3.3",
   "description": "Simple Javascript logging service.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/buffer-log-appender.ts

@@ -1,78 +1,21 @@
 import type { LogAppender } from './log-appender'
 import { LogLevel, type LogMessage } from './log-message'
-import { clamp } from './util'
-
-export interface BufferSizeBounds {
-  target: number
-  max: number
-}
 
 export class BufferLogAppender implements LogAppender {
   public threshold: LogLevel
   public buffer: LogMessage[]
 
-  private _size?: BufferSizeBounds
-
-  public get size() {
-    return this._size === undefined ? undefined : { ...this._size }
-  }
-
-  public set size(s: {target: number, max?: number} | undefined) {
-    if (s === undefined) {
-      this._size = undefined
-    } else {
-      const target = clamp(s.target, { min: 1 })
-      this._size = {
-        target,
-        max: s.max === undefined
-          ? clamp(target * 1.2, { min: target + 1 })
-          : clamp(s.max, { min: target + 1 })
-      }
-    }
-  }
-
-  constructor(threshold?: LogLevel, size?: {target: number, max?: number}) {
-    if (size !== undefined && typeof size === 'object') {
-      this.size = size
-    } else {
-      this._size = { target: 1000, max: 1200 }
-    }
-
-    this.buffer = []
+  constructor(buffer?: LogMessage[], threshold?: LogLevel) {
+    this.buffer = buffer ?? []
     this.threshold = threshold ?? LogLevel.ALL
   }
 
   public appendMessage(msg: LogMessage): void {
     if (this.threshold && msg.level < this.threshold) return
-
-    this.buffer.push(msg)
-
-    if (this._size !== undefined) {
-
-      if (this._size.max <= this._size.target) {
-        // This should be impossible, so if it happens, I want to know.
-        const oldSize = this.size
-        this.size = { target: this._size.target }
-        this.buffer.push({
-          scope: '@jdbernard/js-logging/buffer-log-appender.ts',
-          level: LogLevel.ERROR,
-          msg: {
-            msg: 'BufferLogAppender misconfigured: max size was not greater ' +
-            'than target size. Reconfiguring.',
-            oldSize,
-            newSize: this.size
-          },
-          ts: new Date()
-        })
-      }
-
-      if (this.buffer.length > this._size.max) {
-        this.buffer = this.buffer.slice(-this._size.target)
-      }
-    }
+    else this.buffer.push(msg)
   }
 
   public clearBuffer(): void {
-    this.buffer = []
+    this.buffer.length = 0
   }
 }

src/util.ts

@@ -10,14 +10,3 @@ export function omit(
   }
   return result
 }
-
-export function clamp(
-    val: number,
-    bounds?: { min?: number, max?: number},
-    allowFloats?: boolean ): number {
-  let clamped = val
-  if (!allowFloats) clamped = Math.floor(clamped)
-  if (bounds?.min !== undefined) clamped = Math.max(bounds?.min, clamped)
-  if (bounds?.max !== undefined) clamped = Math.min(bounds?.max, clamped)
-  return clamped
-}

test/buffer-log-appender.test.ts

@@ -1,227 +1,74 @@
-import { describe, expect, test } from 'bun:test'
-import {
-  BufferLogAppender,
-  LogLevel,
-  type LogMessage,
-} from '../src'
+import { describe, test, expect } from "bun:test";
+import { BufferLogAppender, LogLevel, LogMessage } from "../src";
 
 function makeMsg(overrides: Partial<LogMessage> = {}): LogMessage {
   return {
-    scope: 'test-scope',
+    scope: "test-scope",
     level: LogLevel.INFO,
-    msg: 'test message',
-    stacktrace: '',
+    msg: "test message",
+    stacktrace: "",
     ts: new Date(),
     ...overrides,
-  }
+  };
 }
 
-describe('BufferLogAppender', () => {
-  test('defaults to empty buffer, ALL threshold, and bounded size', () => {
-    const appender = new BufferLogAppender()
+describe("BufferLogAppender", () => {
+  test("defaults to empty buffer and ALL threshold", () => {
+    const appender = new BufferLogAppender();
 
-    expect(appender.buffer).toEqual([])
-    expect(appender.threshold).toBe(LogLevel.ALL)
-    expect(appender.size).toEqual({ target: 1000, max: 1200 })
-  })
+    expect(appender.buffer).toEqual([]);
+    expect(appender.threshold).toBe(LogLevel.ALL);
+  });
 
-  test('accepts threshold and size constructor options', () => {
-    const appender = new BufferLogAppender(LogLevel.WARN, {
-      target: 20,
-      max: 30,
-    })
+  test("accepts initial buffer", () => {
+    const existing: LogMessage[] = [makeMsg({ msg: "pre-existing" })];
+    const appender = new BufferLogAppender(existing);
 
-    expect(appender.threshold).toBe(LogLevel.WARN)
-    expect(appender.size).toEqual({ target: 20, max: 30 })
-  })
+    expect(appender.buffer.length).toBe(1);
+    expect(appender.buffer[0].msg).toBe("pre-existing");
+  });
 
-  test('appends messages to buffer', () => {
-    const appender = new BufferLogAppender()
+  test("appends messages to buffer", () => {
+    const appender = new BufferLogAppender();
 
-    appender.appendMessage(makeMsg({ msg: 'first' }))
-    appender.appendMessage(makeMsg({ msg: 'second' }))
+    appender.appendMessage(makeMsg({ msg: "first" }));
+    appender.appendMessage(makeMsg({ msg: "second" }));
 
-    expect(appender.buffer.length).toBe(2)
-    expect(appender.buffer[0].msg).toBe('first')
-    expect(appender.buffer[1].msg).toBe('second')
-  })
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("first");
+    expect(appender.buffer[1].msg).toBe("second");
+  });
 
-  test('respects threshold', () => {
-    const appender = new BufferLogAppender(LogLevel.WARN)
+  test("respects threshold", () => {
+    const appender = new BufferLogAppender(undefined, LogLevel.WARN);
 
-    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: 'dropped' }))
-    appender.appendMessage(makeMsg({ level: LogLevel.WARN, msg: 'kept' }))
-    appender.appendMessage(makeMsg({ level: LogLevel.ERROR, msg: 'also kept' }))
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: "dropped" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.WARN, msg: "kept" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.ERROR, msg: "also kept" }));
 
-    expect(appender.buffer.length).toBe(2)
-    expect(appender.buffer[0].msg).toBe('kept')
-    expect(appender.buffer[1].msg).toBe('also kept')
-  })
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("kept");
+    expect(appender.buffer[1].msg).toBe("also kept");
+  });
 
-  test('threshold of ALL does not drop messages', () => {
-    const appender = new BufferLogAppender(LogLevel.ALL)
+  test("threshold of ALL (0) does not cause falsy check to drop messages", () => {
+    const appender = new BufferLogAppender(undefined, LogLevel.ALL);
 
-    appender.appendMessage(makeMsg({ level: LogLevel.ALL, msg: 'level all' }))
-    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: 'level info' }))
+    appender.appendMessage(makeMsg({ level: LogLevel.ALL, msg: "level all" }));
+    appender.appendMessage(makeMsg({ level: LogLevel.INFO, msg: "level info" }));
 
-    expect(appender.buffer.length).toBe(2)
-    expect(appender.buffer[0].msg).toBe('level all')
-    expect(appender.buffer[1].msg).toBe('level info')
-  })
+    // Both should be kept — ALL (0) should not be treated as falsy
+    expect(appender.buffer.length).toBe(2);
+    expect(appender.buffer[0].msg).toBe("level all");
+    expect(appender.buffer[1].msg).toBe("level info");
+  });
 
-  test('clearBuffer empties the buffer and reassigns the array', () => {
-    const appender = new BufferLogAppender()
-    appender.appendMessage(makeMsg({ msg: 'to clear' }))
-    const existing = appender.buffer
+  test("clearBuffer empties the buffer", () => {
+    const appender = new BufferLogAppender();
+    appender.appendMessage(makeMsg({ msg: "to clear" }));
+    expect(appender.buffer.length).toBe(1);
 
-    appender.clearBuffer()
-
-    expect(appender.buffer).toEqual([])
-    expect(appender.buffer).not.toBe(existing)
-  })
-
-  describe('size bounds', () => {
-    test('derives max as 120 percent of target by default', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, { target: 20 })
-
-      expect(appender.size).toEqual({ target: 20, max: 24 })
-    })
-
-    test('keeps max at least one greater than target', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 20,
-        max: 10,
-      })
-
-      expect(appender.size).toEqual({ target: 20, max: 21 })
-    })
-
-    test('normalizes fractional and too-small target values', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, { target: 0.5 })
-
-      expect(appender.size).toEqual({ target: 1, max: 2 })
-    })
-
-    test('normalizes fractional max values', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 3,
-        max: 4.9,
-      })
-
-      expect(appender.size).toEqual({ target: 3, max: 4 })
-    })
-
-    test('can be disabled for unbounded buffering', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 2,
-        max: 3,
-      })
-      appender.size = undefined
-
-      for (let i = 1; i <= 5; i++) {
-        appender.appendMessage(makeMsg({ msg: `message ${i}` }))
-      }
-
-      expect(appender.size).toBeUndefined()
-      expect(appender.buffer.map((message) => message.msg)).toEqual([
-        'message 1',
-        'message 2',
-        'message 3',
-        'message 4',
-        'message 5',
-      ])
-    })
-
-    test('returns size as a defensive copy', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 3,
-        max: 4,
-      })
-      const size = appender.size
-
-      if (size !== undefined) {
-        size.max = 1
-      }
-
-      expect(appender.size).toEqual({ target: 3, max: 4 })
-    })
-  })
-
-  describe('buffer trimming', () => {
-    test('allows buffer to grow until max is exceeded', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 3,
-        max: 5,
-      })
-
-      for (let i = 1; i <= 5; i++) {
-        appender.appendMessage(makeMsg({ msg: `message ${i}` }))
-      }
-
-      expect(appender.buffer.map((message) => message.msg)).toEqual([
-        'message 1',
-        'message 2',
-        'message 3',
-        'message 4',
-        'message 5',
-      ])
-    })
-
-    test('batch trims to target when max is exceeded', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 3,
-        max: 5,
-      })
-
-      for (let i = 1; i <= 6; i++) {
-        appender.appendMessage(makeMsg({ msg: `message ${i}` }))
-      }
-
-      expect(appender.buffer.map((message) => message.msg)).toEqual([
-        'message 4',
-        'message 5',
-        'message 6',
-      ])
-    })
-
-    test('reassigns buffer array when trimming', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 2,
-        max: 3,
-      })
-
-      appender.appendMessage(makeMsg({ msg: 'first' }))
-      appender.appendMessage(makeMsg({ msg: 'second' }))
-      appender.appendMessage(makeMsg({ msg: 'third' }))
-      const existing = appender.buffer
-      appender.appendMessage(makeMsg({ msg: 'fourth' }))
-
-      expect(appender.buffer).not.toBe(existing)
-      expect(appender.buffer.map((message) => message.msg)).toEqual([
-        'third',
-        'fourth',
-      ])
-    })
-
-    test('repairs invalid internal bounds before trimming', () => {
-      const appender = new BufferLogAppender(LogLevel.ALL, {
-        target: 3,
-        max: 4,
-      })
-      const unsafeAppender = appender as unknown as {
-        _size: { target: number, max: number }
-      }
-      unsafeAppender._size = { target: 3, max: 2 }
-
-      appender.appendMessage(makeMsg({ msg: 'first' }))
-
-      expect(appender.size).toEqual({ target: 3, max: 4 })
-      expect(appender.buffer.length).toBe(2)
-      expect(appender.buffer[1].level).toBe(LogLevel.ERROR)
-      expect(appender.buffer[1].msg).toMatchObject({
-        oldSize: { target: 3, max: 2 },
-        newSize: { target: 3, max: 4 },
-      })
-    })
-  })
-})
+    appender.clearBuffer();
+    expect(appender.buffer.length).toBe(0);
+  });
+});

test/util.test.ts

@@ -1,59 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { clamp } from '../src/util'
-
-describe('utils', () => {
-  describe('clamp', () => {
-    test("doesn't alter integers within the given range", () => {
-      expect(clamp(5, { min: 0, max: 10 })).toBe(5)
-      expect(clamp(-8, { min: -100, max: 100 })).toBe(-8)
-    })
-
-    test('keeps values at the range boundaries', () => {
-      expect(clamp(0, { min: 0, max: 10 })).toBe(0)
-      expect(clamp(10, { min: 0, max: 10 })).toBe(10)
-      expect(clamp(-100, { min: -100, max: 100 })).toBe(-100)
-      expect(clamp(100, { min: -100, max: 100 })).toBe(100)
-    })
-
-    test('raises values below the minimum', () => {
-      expect(clamp(-1, { min: 0, max: 10 })).toBe(0)
-      expect(clamp(-101, { min: -100, max: 100 })).toBe(-100)
-    })
-
-    test('lowers values above the maximum', () => {
-      expect(clamp(11, { min: 0, max: 10 })).toBe(10)
-      expect(clamp(101, { min: -100, max: 100 })).toBe(100)
-    })
-
-    test('floors floats by default', () => {
-      expect(clamp(1.5, { min: 0, max: 2 })).toBe(1)
-      expect(clamp(1.999, { min: 0, max: 2 })).toBe(1)
-      expect(clamp(-0.3, { min: -2, max: 2 })).toBe(-1)
-      expect(clamp(-1.1, { min: -2, max: 2 })).toBe(-2)
-    })
-
-    test('floors before applying bounds', () => {
-      expect(clamp(10.5, { min: 0, max: 10 })).toBe(10)
-      expect(clamp(-10.5, { min: -10, max: 10 })).toBe(-10)
-      expect(clamp(1.2, { min: 1.5 })).toBe(1.5)
-    })
-
-    test('preserves floats when allowed', () => {
-      expect(clamp(1.5, { min: 0, max: 2 }, true)).toBe(1.5)
-      expect(clamp(2.5, { min: 0, max: 2 }, true)).toBe(2)
-      expect(clamp(-0.5, { min: 0, max: 2 }, true)).toBe(0)
-    })
-
-    test('supports one-sided bounds', () => {
-      expect(clamp(-1, { min: 0 })).toBe(0)
-      expect(clamp(11, { min: 0 })).toBe(11)
-      expect(clamp(-1, { max: 10 })).toBe(-1)
-      expect(clamp(11, { max: 10 })).toBe(10)
-    })
-
-    test('clamps infinite values to the range boundaries', () => {
-      expect(clamp(Infinity, { min: 0, max: 10 })).toBe(10)
-      expect(clamp(-Infinity, { min: 0, max: 10 })).toBe(0)
-    })
-  })
-})

tsconfig.json

@@ -3,7 +3,6 @@
     "module": "commonjs",
     "target": "es2016",
     "declaration": true,
-    "rootDir": "./src",
     "outDir": "./dist",
     "strict": true,
     "skipLibCheck": true