Migrate from 0.2

Breaking changes from logbun 0.2.1 to 1.0 — reliability subpaths, DLQ ids, host maintenance.

Logbun 1.0 is runtime-agnostic: the root package is pure ES2022 / Web API code. Filesystem and Cloudflare durability live on explicit subpaths.

1. Durable mode requires a persistent `reliability` adapter

Before (0.2.x):

new AuditLogger({
  namespace: 'app',
  mode: 'durable',
  dataDir: '.logbun',
  wal: { fsync: true },
  dlqFsync: true,
  encryptionKey: '...',
  instanceLock: true,
  adapter,
});

After (1.0):

import { FileReliabilityAdapter } from 'logbun/durability/filesystem';

new AuditLogger({
  namespace: 'app',
  mode: 'durable',
  reliability: new FileReliabilityAdapter({
    namespace: 'app',
    dataDir: '.logbun',
    wal: { fsync: true },
    dlq: { fsync: true },
    encryptionKey: '...',
    instanceLock: true,
  }),
  adapter,
});

Missing or non-persistent reliability throws synchronously in the constructor when mode: 'durable'.

2. Filesystem config moved off root `LogbunConfig`

0.2.x config	1.0 location
`dataDir`	`FileReliabilityAdapter({ dataDir })`
`wal.*`	`FileReliabilityAdapter({ wal })`
`dlqFsync`	`FileReliabilityAdapter({ dlq: { fsync } })`
`maxWalBytes` / `walSoftLimitBytes`	`FileReliabilityAdapter({ maxWalBytes })`
`maxDlqFiles`	`FileReliabilityAdapter({ dlq: { maxEntries } })`
`encryptionKey`	`FileReliabilityAdapter({ encryptionKey })`
`instanceLock`	`FileReliabilityAdapter({ instanceLock })`

3. DLQ uses opaque IDs (not paths)

const dead = await audit.listDlq({ includeDead: true });
await audit.requeueDead(dead[0]!.id);
await audit.deleteDead(dead[0]!.id);

Filesystem paths may appear in metadata.path for diagnostics only.

4. Host-scheduled maintenance

Removed: RetentionConfig.cronExpression, RetryConfig.scanIntervalMs / initialDelayMs, internal Bun.cron retention and recurring DLQ scan timers.

Added: flush(), runMaintenance(), retryDlqNow(). Short batching flushInterval timers remain.

5. Bun SQLite path rename

- import { BunSQLiteAdapter } from 'logbun/adapters/sqlite';
+ import { BunSQLiteAdapter } from 'logbun/adapters/bun-sqlite';

logbun/adapters/sqlite is removed in 1.0.

6. Path helpers and instance lock leave the root export

import {
  FileReliabilityAdapter,
  resolveLogbunDir,
  resolveDataDir,
  InstanceLock,
  InstanceLockError,
} from 'logbun/durability/filesystem';

Root still exports pure helpers: sanitizeNamespace, sanitizeTenantKey, isTenantIdPresent, crypto (INTEGRITY_GENESIS, verifyIntegrityChain, normalizeEncryptionKey), and UUIDv7. 1.0 also exports MemoryReliabilityAdapter, DurableAdmissionSchedulingError, and isDurableAdmissionSchedulingError.

7. Deno permissions

deno run --allow-read=./.logbun --allow-write=./.logbun --allow-sys=uid,gid your_app.ts

Add --allow-run when automatic recovery of a crashed process’s instance lock is required.

8. Cloudflare Workers

Import CloudflareReliabilityAdapter from logbun/durability/cloudflare inside a Durable Object. Standard Workers call a DO binding; do not put journal/DLQ on D1. Pass waitUntil via LogbunRequestContext. Volatile request runtimes: await fireAsync(...); await flush().

Preserved

AuditLogger, IAdapter, batching, tenancy, events, safety, integrity chain
fire / fireAsync / query / retry semantics (minus timer scheduling)
Optional peers: Turso, ClickHouse, Hono, Elysia
npm package name logbun; Deno consumes the npm artifact