mburchard/bit-log

Fork 0

Prepare bit-log 2.0 for Node.js 24 and harden appender I/O #68

Merged

mburchard merged 3 commits from dev-2.0 into main

2026-08-15 13:23:25 +00:00

mburchard commented

2026-08-14 23:05:16 +00:00

Owner

Summary

This PR prepares bit-log 2.0 for Node.js 24, modernizes its package and release tooling, and makes appender lifecycle and I/O behaviour deterministic.

Platform and packaging

migrate development to Node.js 24 and pnpm 11
replace the Vite-based build with native TypeScript ESM and declaration output
simplify package exports while preserving supported subpath imports
validate the packed package from a real TypeScript and runtime consumer
modernize Forgejo CI and npm publishing, including native SQLite builds on the ARM64 runner
add a manual workflow for validating npm credentials without publishing

Logging and lifecycle

normalize useLog(), useLog(''), and useLog('root') to the same root logger
reuse unchanged appenders and close replaced instances during reconfiguration
add closeLogging() and await asynchronous appender cleanup
make File and SQLite appenders wait for queued operations before shutdown
normalize string levels on externally emitted log events
warn about unknown appender configuration properties

I/O reliability and performance

serialize SQLite initialization, writes, and shutdown
add configurable SQLite journal and synchronization modes
use WAL with NORMAL synchronization by default, improving local SQLite throughput by roughly 12×
cache successfully validated file paths, roughly doubling local FileAppender throughput
suppress repeated File and SQLite diagnostics while retaining automatic retries

Documentation and quality

document the v1 migration path, lifecycle contracts, SQLite side files, and network file-system configuration
document the measured File and SQLite performance improvements
enforce 100% statement, branch, function, and line coverage
correct the published configuration example and remove obsolete internal helpers

Breaking changes

bit-log 2.x requires Node.js 24 or newer; projects on older Node.js releases should remain on bit-log 1.x
the package is distributed as native ESM
SQLite logging defaults to WAL and creates -wal and -shm side files
unchanged appender configurations now reuse their existing instances
unknown appender configuration properties now produce warnings

Validation

pnpm lint:ci
pnpm typecheck
pnpm coverage: 291 tests, 100% coverage across all metrics
pnpm package:check
packed package verified as a dependency in ComSTAR Application v2

## Summary This PR prepares bit-log 2.0 for Node.js 24, modernizes its package and release tooling, and makes appender lifecycle and I/O behaviour deterministic. ### Platform and packaging - migrate development to Node.js 24 and pnpm 11 - replace the Vite-based build with native TypeScript ESM and declaration output - simplify package exports while preserving supported subpath imports - validate the packed package from a real TypeScript and runtime consumer - modernize Forgejo CI and npm publishing, including native SQLite builds on the ARM64 runner - add a manual workflow for validating npm credentials without publishing ### Logging and lifecycle - normalize `useLog()`, `useLog('')`, and `useLog('root')` to the same root logger - reuse unchanged appenders and close replaced instances during reconfiguration - add `closeLogging()` and await asynchronous appender cleanup - make File and SQLite appenders wait for queued operations before shutdown - normalize string levels on externally emitted log events - warn about unknown appender configuration properties ### I/O reliability and performance - serialize SQLite initialization, writes, and shutdown - add configurable SQLite journal and synchronization modes - use `WAL` with `NORMAL` synchronization by default, improving local SQLite throughput by roughly 12× - cache successfully validated file paths, roughly doubling local FileAppender throughput - suppress repeated File and SQLite diagnostics while retaining automatic retries ### Documentation and quality - document the v1 migration path, lifecycle contracts, SQLite side files, and network file-system configuration - document the measured File and SQLite performance improvements - enforce 100% statement, branch, function, and line coverage - correct the published configuration example and remove obsolete internal helpers ## Breaking changes - bit-log 2.x requires Node.js 24 or newer; projects on older Node.js releases should remain on bit-log 1.x - the package is distributed as native ESM - SQLite logging defaults to `WAL` and creates `-wal` and `-shm` side files - unchanged appender configurations now reuse their existing instances - unknown appender configuration properties now produce warnings ## Validation - `pnpm lint:ci` - `pnpm typecheck` - `pnpm coverage`: 291 tests, 100% coverage across all metrics - `pnpm package:check` - packed package verified as a dependency in ComSTAR Application v2

mburchard added 1 commit

2026-08-14 23:05:16 +00:00

chore!: modernize toolchain for bit-log 2.0

CI / ci (pull_request) Failing after 1m54s

Details

3f1e3a9031

Replace the Vite build with TypeScript ESM output and validate exports from a real consumer.
Upgrade pnpm, development dependencies, and SQLite tooling for Node.js 24.
Harden Forgejo CI and npm publishing with caching, validation, and release safeguards.
Align ESLint and Vitest tests and document the new runtime requirements.

BREAKING CHANGE: bit-log 2.0 requires Node.js 24 or newer.

mburchard added 1 commit

2026-08-14 23:08:59 +00:00

fix(ci): build SQLite binding for Forgejo runner

CI / ci (pull_request) Failing after 2m55s

Details

c4d408b633

Compile better-sqlite3 against the runner's glibc in CI and publish workflows.
Avoid loading the incompatible ARM64 prebuild that requires GLIBC_2.33.

mburchard added 1 commit

2026-08-14 23:15:14 +00:00

fix(ci): use compatible SQLite binding on Forgejo runner

CI / ci (pull_request) Failing after 3m8s

Details

bfd0d18df6

Hide bundled ARM64 prebuilds after compiling better-sqlite3 against the runner's glibc.
Add a manual workflow to validate NPM_AUTH_TOKEN without publishing a package.

mburchard force-pushed dev-2.0 from bfd0d18df6

CI / ci (pull_request) Failing after 3m8s

Details

to 797ef16a7d

CI / ci (pull_request) Successful in 3m12s

Details

2026-08-15 10:34:41 +00:00

Compare

mburchard added 1 commit

2026-08-15 11:05:01 +00:00

feat: add deterministic appender lifecycle management

CI / ci (pull_request) Successful in 3m11s

Details

03fab48a00

Add closeLogging() and wait for asynchronous cleanup and queued file writes.
Reuse unchanged appenders and close replaced instances during reconfiguration.
Normalize all root logger aliases to one instance and document the lifecycle contracts.
Cover shutdown, replacement, error isolation, and root behavior with regression tests.

mburchard self-assigned this

2026-08-15 11:05:26 +00:00

mburchard added the

dependencies

documentation

enhancement

labels

2026-08-15 11:05:39 +00:00

mburchard changed title from ~~WIP: Prepare bit-log 2.0 for Node.js 24~~ to Prepare bit-log 2.0 for Node.js 24

2026-08-15 11:09:41 +00:00

mburchard added 1 commit

2026-08-15 13:20:03 +00:00

feat: improve appender reliability and I/O performance

CI / ci (pull_request) Successful in 3m9s

Details

CI / ci (push) Successful in 3m17s

Details

Publish Package to npmjs / publish (release) Successful in 3m25s

Details

f6ddf6abb0

- Serialize SQLite initialization, writes, and shutdown and add configurable journal modes.
- Cache validated file paths and suppress repeated diagnostics while preserving automatic retries.
- Normalize emitted log levels and warn about unknown appender configuration properties.
- Enforce 100% coverage and document v2 migration requirements and performance gains.

mburchard changed title from ~~Prepare bit-log 2.0 for Node.js 24~~ to Prepare bit-log 2.0 for Node.js 24 and harden appender I/O

2026-08-15 13:22:15 +00:00

mburchard merged commit f6ddf6abb0 into main

2026-08-15 13:23:25 +00:00

mburchard deleted branch dev-2.0

2026-08-15 13:23:25 +00:00