{"_id":"@2ez4dan/zbun","_rev":"6-339b26415d6a22e5b264c6fa7203da29","name":"@2ez4dan/zbun","dist-tags":{"latest":"0.1.5"},"versions":{"0.1.0":{"name":"@2ez4dan/zbun","version":"0.1.0","_id":"@2ez4dan/zbun@0.1.0","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"dist":{"shasum":"4397223bc4869eaa80cb5d53cd221ce236f9df88","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.0.tgz","fileCount":15,"integrity":"sha512-9+fN52+LhdxT6kVbJULYL70vVhVQ8zwTVUD4mAK8Jo1rt1LELDcOpKUp8nubGaqD5FFudslpoBK4Yn54pcc3Ww==","signatures":[{"sig":"MEUCIGOAXjsaBMlN8wcsesKduez/8d+1wRHD4veSbNqEEi3ZAiEAmwlJI+bQnWqKDdqV0EfQpta30wPthuJhzjCNj/lQOrQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62291},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"09dd8581372a418c8f793671d4f0642fec712a90","scripts":{"lint":"biome check src/ tests/ benchmarks/","test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","format":"biome format --write src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","prepublishOnly":"bun run build"},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"_npmVersion":"11.6.2","description":"The fastest structured logging library for [Bun](https://bun.sh).","directories":{},"_nodeVersion":"24.12.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"pino":"^10.3.1","winston":"^3.19.0","bun-types":"^1.3.10","typescript":"^5.0.0","@biomejs/biome":"^2.4.5"},"_npmOperationalInternal":{"tmp":"tmp/zbun_0.1.0_1772635072289_0.03337010916112404","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@2ez4dan/zbun","version":"0.1.1","_id":"@2ez4dan/zbun@0.1.1","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"dist":{"shasum":"838204d5f91172625ca804099aaaaf7804d7b7d9","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.1.tgz","fileCount":15,"integrity":"sha512-y2NB5uP9Y917USSkNslMPHAihTgWUzgmtZueNKBFfskQuFGzW/zsYyDXv15bJxiN97RBUg0KZ4o7uEjcK4vtWw==","signatures":[{"sig":"MEQCIAX5V1YP9H4ZZRYsENTiPCyNhV9/gkkgYWjUPLq2wJbxAiAE+LVubLCQXPO+iI7+ritANrsnQ82gz1YCjlvgkaOPIQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62309},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"eb4a1add10edadf23742409937cc08a0140fdc35","scripts":{"lint":"biome check src/ tests/ benchmarks/","test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","format":"biome format --write src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","prepublishOnly":"bun run build"},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"_npmVersion":"11.6.2","description":"The fastest structured logging library for [Bun](https://bun.sh).","directories":{},"_nodeVersion":"24.12.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"pino":"^10.3.1","winston":"^3.19.0","bun-types":"^1.3.10","typescript":"^5.0.0","@biomejs/biome":"^2.4.5"},"_npmOperationalInternal":{"tmp":"tmp/zbun_0.1.1_1772635554842_0.8990805826480128","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@2ez4dan/zbun","version":"0.1.2","_id":"@2ez4dan/zbun@0.1.2","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"dist":{"shasum":"5c394fd02c345213022cd501b855893ebea77f61","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.2.tgz","fileCount":15,"integrity":"sha512-RnHN7mfKG8t3y6CxAEHXeQXYY8j/+5aeiqBrrICxfpI1paLElkXdb7KQZCswFHif4bHjxAG8lsuapV/KJm59sQ==","signatures":[{"sig":"MEQCIGSWTeJZyS67os5yhIfaonELgARb8yuHBfbq7fwkwNi0AiBI8iryzALI6A7KjlJItdbqDEUGdWNTuWiSCAVpESYTPw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62309},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"16c9979624451ab74c635d1cdf21dade22d304f0","scripts":{"lint":"biome check src/ tests/ benchmarks/","test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","format":"biome format --write src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","prepublishOnly":"bun run build"},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"_npmVersion":"10.8.2","description":"The fastest structured logging library for [Bun](https://bun.sh).","directories":{},"_nodeVersion":"20.20.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"pino":"^10.3.1","winston":"^3.19.0","bun-types":"^1.3.10","typescript":"^5.0.0","@biomejs/biome":"^2.4.5"},"_npmOperationalInternal":{"tmp":"tmp/zbun_0.1.2_1772636252926_0.6013181416313063","host":"s3://npm-registry-packages-npm-production"}},"0.1.3":{"name":"@2ez4dan/zbun","version":"0.1.3","_id":"@2ez4dan/zbun@0.1.3","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"dist":{"shasum":"4bd9404abefbbfa59399fe039dc1beb237e6a333","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.3.tgz","fileCount":15,"integrity":"sha512-+Thm6fjiDw2DHUqcavMrbKtVIRPVe+eI5/JbgVY6BVxabfZhkajO8rhuHaflq0Vi7/+F1QQnlzG4rSL4UfTOZA==","signatures":[{"sig":"MEQCIFjCtHYXX/8SAjAwXquKcQk3za0F8bcIzrst4QOcHK74AiAlb6N4L/KiQcVkXc509cA9N0wZgTChVbSF+hKLUEncbw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62309},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"e33ad1357172e34fcf5d7102b30ec6ccc8459369","scripts":{"lint":"biome check src/ tests/ benchmarks/","test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","format":"biome format --write src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","prepublishOnly":"bun run build"},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"_npmVersion":"10.8.2","description":"The fastest structured logging library for [Bun](https://bun.sh).","directories":{},"_nodeVersion":"20.20.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"pino":"^10.3.1","winston":"^3.19.0","bun-types":"^1.3.10","typescript":"^5.0.0","@biomejs/biome":"^2.4.5"},"_npmOperationalInternal":{"tmp":"tmp/zbun_0.1.3_1772637041438_0.6674827727026851","host":"s3://npm-registry-packages-npm-production"}},"0.1.4":{"name":"@2ez4dan/zbun","version":"0.1.4","_id":"@2ez4dan/zbun@0.1.4","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"homepage":"https://github.com/DanDalanDone69/zbun#readme","bugs":{"url":"https://github.com/DanDalanDone69/zbun/issues"},"dist":{"shasum":"002b51669e1625e38ee8c0ca72d48b3feb6db233","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.4.tgz","fileCount":15,"integrity":"sha512-LTWKWLzBrlBkYNtjhZ/K3JR+HE8siIkrdxW6d5jWkMk1tBw8k2eSzL3dFmQkYp3rkGUW0XSzFZylIh+ZmI31WQ==","signatures":[{"sig":"MEUCIG/uwURME4r3rpyEMoZjDIzW9r+CmtHwEEoWgtkYPdoRAiEAwGY59wj4NrIlZgLtvWUANj/B8vOKx3Gu9Sk7fWLGji0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62367},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"bun":">=1.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"888dc692250f6fb14833dc7d6b3f6cd403561509","scripts":{"lint":"biome check src/ tests/ benchmarks/","test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","format":"biome format --write src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","prepublishOnly":"bun run build"},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"repository":{"url":"git+https://github.com/DanDalanDone69/zbun.git","type":"git"},"_npmVersion":"10.8.2","description":"The fastest structured logging library for [Bun](https://bun.sh).","directories":{},"_nodeVersion":"20.20.0","dependencies":{},"_hasShrinkwrap":false,"devDependencies":{"pino":"^10.3.1","winston":"^3.19.0","bun-types":"^1.3.10","typescript":"^5.0.0","@biomejs/biome":"^2.4.5"},"_npmOperationalInternal":{"tmp":"tmp/zbun_0.1.4_1772717727503_0.5094986031909408","host":"s3://npm-registry-packages-npm-production"}},"0.1.5":{"name":"@2ez4dan/zbun","version":"0.1.5","description":"The fastest structured logging library for Bun — zero dependencies, zero allocations, lock-free async I/O","keywords":["bun","logger","logging","structured-logging","json-logger","zero-dependency","async-logging","high-performance"],"author":{"name":"Danielle Bote","email":"daniellebote@gmail.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/DanDalanDone69/zbun.git"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"engines":{"bun":">=1.0.0"},"scripts":{"test":"bun test","bench":"bun run benchmarks/run.ts","build":"bun build src/index.ts --outdir dist --target bun --sourcemap=external && bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","build:types":"bun x tsc --project tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist","lint":"biome check src/ tests/ benchmarks/","lint:fix":"biome check --write src/ tests/ benchmarks/","format":"biome format --write src/ tests/ benchmarks/","prepublishOnly":"bun run build"},"dependencies":{},"devDependencies":{"@biomejs/biome":"^2.4.5","bun-types":"^1.3.10","pino":"^10.3.1","typescript":"^5.0.0","winston":"^3.19.0"},"_id":"@2ez4dan/zbun@0.1.5","gitHead":"6cf8ca1070a3a6d78fc669b6ec5a418ccc0015d5","bugs":{"url":"https://github.com/DanDalanDone69/zbun/issues"},"homepage":"https://github.com/DanDalanDone69/zbun#readme","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-37oypjqpGh0nIgJp3auqi/vqVgo4JXFVq1fdlmpJTIto71a6n4XW1k+zhWJ5RqqfcFQdZue3AwYGh1Mow9awUg==","shasum":"739c9d203d7b04b8766f94fab0b151887aa123e6","tarball":"https://registry.npmjs.org/@2ez4dan/zbun/-/zbun-0.1.5.tgz","fileCount":15,"unpackedSize":62742,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC8NeuHZAvhP/yhADBFePItgMC+sxksC9dCdCGzVlZWpQIhAKkajGZOT1fyEuIk6D8wDrBQ2MqrbHkivFgzbzfgZQnJ"}]},"_npmUser":{"name":"2ez4dan","email":"daniellebote@gmail.com"},"directories":{},"maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zbun_0.1.5_1772720489750_0.592221776892502"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-04T14:37:52.172Z","modified":"2026-03-05T14:21:30.006Z","0.1.0":"2026-03-04T14:37:52.432Z","0.1.1":"2026-03-04T14:45:55.016Z","0.1.2":"2026-03-04T14:57:33.089Z","0.1.3":"2026-03-04T15:10:41.612Z","0.1.4":"2026-03-05T13:35:27.646Z","0.1.5":"2026-03-05T14:21:29.890Z"},"bugs":{"url":"https://github.com/DanDalanDone69/zbun/issues"},"homepage":"https://github.com/DanDalanDone69/zbun#readme","repository":{"type":"git","url":"git+https://github.com/DanDalanDone69/zbun.git"},"description":"The fastest structured logging library for Bun — zero dependencies, zero allocations, lock-free async I/O","maintainers":[{"name":"2ez4dan","email":"daniellebote@gmail.com"}],"readme":"# ZBun\n\nThe fastest structured logging library for [Bun](https://bun.sh).\n\nZBun merges the zero-allocation fluent API of Go's [zerolog](https://github.com/rs/zerolog) with the lock-free asynchronous I/O of C++'s [spdlog](https://github.com/gabime/spdlog) — built from scratch for the Bun runtime. Zero dependencies.\n\n## Benchmarks\n\nStructured logging (`str` + `int` + `bool` fields) writing to `/dev/null`, Bun 1.3.10, 100k iterations x 5 rounds (median):\n\n| Logger | Ops/sec | vs ZBun |\n|--------|---------|---------|\n| **zbun** | **2,888,549** | — |\n| pino | 931,519 | 3.10x slower |\n| winston | 1,016,133 | 2.84x slower |\n\n> ZBun achieves **3.1x higher throughput** than pino and **2.8x** over winston with zero memory overhead (0KB heap delta).\n\n## Install\n\n```bash\nbun add @2ez4dan/zbun\n```\n\n**Requires Bun >= 1.1.** Recommended: Bun >= 1.3.x.\n\n## Quick Start\n\n```typescript\nimport { createLogger } from '@2ez4dan/zbun';\n\nconst log = createLogger({\n  level: 'info',          // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'\n  target: 'stdout',       // or a file path like './app.log'\n});\n\nlog.info()\n   .str('module', 'auth')\n   .int('userId', 12345)\n   .bool('success', true)\n   .msg('User login completed');\n\n// Output: {\"level\":\"info\",\"time\":1709568000000,\"module\":\"auth\",\"userId\":12345,\"success\":true,\"message\":\"User login completed\"}\n```\n\n## API\n\n### Log Levels\n\n```typescript\nlog.trace()  // Level 0\nlog.debug()  // Level 1\nlog.info()   // Level 2\nlog.warn()   // Level 3\nlog.error()  // Level 4\nlog.fatal()  // Level 5\n```\n\nIf a level is disabled, the call returns a frozen no-op singleton — zero allocation, zero buffer writes.\n\n### Typed Field Methods\n\n```typescript\nlog.info()\n   .str('name', 'alice')        // String field (JSON-escaped)\n   .int('age', 30)              // Integer (no toString() allocation)\n   .float('score', 9.5)         // Floating point\n   .bool('active', true)        // Boolean\n   .any('meta', { x: 1 })       // Any value (JSON.stringify fallback for objects)\n   .msg('user created');\n```\n\nType-specific methods (`.str`, `.int`, `.bool`) are faster than `.any` because they skip type checking and use optimized byte encoding paths.\n\n### Error Logging\n\n```typescript\ntry {\n  await db.connect();\n} catch (e) {\n  log.error()\n     .err(e)                    // Extracts message + stack trace\n     .str('host', 'db-1')\n     .msg('Connection failed');\n}\n```\n\n### Child Loggers\n\nAttach persistent context fields that are included in every log entry:\n\n```typescript\nconst reqLog = log.with()\n                  .str('reqId', 'req-55aa77')\n                  .str('path', '/api/users')\n                  .logger();\n\nreqLog.info().msg('Request started');\n// Output: {\"level\":\"info\",\"time\":...,\"reqId\":\"req-55aa77\",\"path\":\"/api/users\",\"message\":\"Request started\"}\n\n// Child loggers nest — grandchild inherits all parent context\nconst dbLog = reqLog.with().str('db', 'postgres').logger();\n```\n\nContext fields are pre-serialized as a byte array when `.logger()` is called. On each subsequent log call, they are copied directly into the buffer — O(1) cost regardless of how many context fields exist.\n\n### Async Mode\n\nFor maximum throughput, enable async mode to offload I/O to a background Worker thread:\n\n```typescript\nconst log = createLogger({\n  level: 'info',\n  target: 'stdout',\n  async: true,                  // Enables SharedArrayBuffer + Worker\n  bufferSize: 1024 * 1024,      // 1MB ring buffer (default)\n});\n\n// Logs are written to a lock-free ring buffer on the main thread,\n// then flushed to I/O by a background Bun Worker.\nlog.info().str('fast', 'path').msg('Non-blocking');\n\n// Flush before exit to ensure all buffered logs are written\nawait log.flush();\n```\n\nIf the ring buffer fills up, ZBun transparently falls back to synchronous writing — no messages are ever dropped.\n\n### `.send()` — Log Without a Message\n\n```typescript\nlog.info().str('event', 'heartbeat').int('uptime', 3600).send();\n// Output: {\"level\":\"info\",\"time\":...,\"event\":\"heartbeat\",\"uptime\":3600}\n```\n\n## How It's Fast\n\n1. **Manual byte encoding** — JSON is built byte-by-byte into a pre-allocated `Uint8Array`. No `JSON.stringify()`, no intermediate string objects.\n\n2. **Buffer pooling** — Each logger holds a stack of reusable write buffers. In steady state, zero allocations per log call.\n\n3. **No-op singleton** — Disabled log levels return a frozen `Object.freeze`'d singleton. Every chained method is a no-op that returns itself.\n\n4. **Type-specific formatters** — `.int(k, 42)` writes ASCII digits directly via `% 10` extraction (no `Number.toString()` allocation). `.bool(k, true)` writes the 4 pre-encoded bytes `true`.\n\n5. **Pre-computed contexts** — Child logger context fields are serialized once as raw bytes, then `memcpy`'d on each log call.\n\n6. **Lock-free async I/O** — Async mode uses a SPSC ring buffer over `SharedArrayBuffer` with `Atomics` for zero-contention, zero-copy handoff to a background Worker.\n\n## Configuration\n\n```typescript\ninterface LoggerOptions {\n  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';\n  target?: 'stdout' | string;   // 'stdout' or a file path\n  async?: boolean;               // Enable background Worker transport\n  bufferSize?: number;           // Ring buffer size in bytes (default: 1MB)\n}\n```\n\n## Running Tests\n\n```bash\nbun test\n```\n\n## Running Benchmarks\n\n```bash\nbun add -d pino winston\nbun run benchmarks/run.ts\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","keywords":["bun","logger","logging","structured-logging","json-logger","zero-dependency","async-logging","high-performance"],"author":{"name":"Danielle Bote","email":"daniellebote@gmail.com"},"license":"MIT"}