# tarrowren/bitcask-js architecture

> Architecture diagram of the GitHub repository tarrowren/bitcask-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tarrowren/bitcask-js
- Repository: https://github.com/tarrowren/bitcask-js

## Overview

bitcask-js is a JavaScript key/value store built around Bitcask-style append-only data files. A client submits get/put operations to the Bitcask API; the store coordinates key-directory lookups, file-pool reads and writes, and record decoding. Startup and file rotation use manifests, while merge compacts older data and can clear obsolete files. Source excerpts show these major responsibilities and some dependencies; links based on the source index are limited to the imports it records, and unshown runtime details are omitted.

Main entry points: [`src/bitcask.ts`](https://github.com/tarrowren/bitcask-js/blob/main/src/bitcask.ts) (Bitcask API), [`src/record.ts`](https://github.com/tarrowren/bitcask-js/blob/main/src/record.ts) (Record Codec), [`src/merge.ts`](https://github.com/tarrowren/bitcask-js/blob/main/src/merge.ts) (Merge and Cleanup), [`src/file-pool.ts`](https://github.com/tarrowren/bitcask-js/blob/main/src/file-pool.ts) (File Pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Store API"]
  node_bitcask["Bitcask API<br/>[bitcask.ts]"]
  node_options["Store Options<br/>[opts.ts]"]
  node_keydir["Key Directory<br/>[dir.ts]"]
end

subgraph group_storage["File Storage"]
  node_filepool["File Pool<br/>[file-pool.ts]"]
  node_datafiles["File Readers and Writers<br/>[file.ts]"]
  node_filequeue["Request Queue<br/>[queue.ts]"]
  node_stream["Read Stream<br/>[stream.ts]"]
  node_database[("Database Files")]
end

subgraph group_formats["Record Formats"]
  node_records["Record Codec<br/>[record.ts]"]
  node_hints["Hint Codec<br/>[hint.ts]"]
  node_buffers["Buffer Primitives<br/>[buffer.ts]"]
  node_checksums["CRC32<br/>[crc32.ts]"]
  node_definitions["Format Constants<br/>[def.ts]"]
end

subgraph group_maintenance["Metadata and Maintenance"]
  node_manifest["Manifest<br/>[manifest.ts]"]
  node_filelock["Database Lock<br/>[lockfile.ts]"]
  node_merge["Merge and Cleanup<br/>[merge.ts]"]
  node_orderedmap["Linked Map<br/>[linked-map.ts]"]
  node_randomname["File Naming<br/>[random-name.ts]"]
end

node_client(("Application"))

node_client -.->|"submits operations"| node_bitcask
node_bitcask -->|"looks up keys"| node_keydir
node_bitcask -->|"reads and writes"| node_filepool
node_bitcask -->|"decodes records"| node_records
node_bitcask -->|"opens metadata"| node_manifest
node_bitcask -->|"locks database"| node_filelock
node_bitcask -->|"clears files"| node_merge
node_bitcask -->|"uses settings"| node_options
node_filepool -->|"dispatches I/O"| node_datafiles
node_datafiles -->|"creates read streams"| node_stream
node_filepool -->|"checks file metadata"| node_manifest
node_filepool -->|"queues requests"| node_filequeue
node_datafiles -.->|"reads and writes"| node_database
node_records -->|"encodes fields"| node_buffers
node_records -->|"checks CRC"| node_checksums
node_records -->|"uses sizes"| node_definitions
node_records -->|"uses directory types"| node_keydir
node_hints -->|"encodes fields"| node_buffers
node_hints -->|"uses sizes"| node_definitions
node_hints -->|"yields directory entries"| node_keydir
node_manifest -->|"tracks files"| node_orderedmap
node_manifest -->|"chooses file names"| node_randomname
node_merge -->|"reads old data"| node_filepool
node_merge -->|"writes hints"| node_hints
node_merge -->|"uses file metadata"| node_manifest
node_merge -->|"parses records"| node_records

click node_bitcask "https://github.com/tarrowren/bitcask-js/blob/main/src/bitcask.ts"
click node_options "https://github.com/tarrowren/bitcask-js/blob/main/src/opts.ts"
click node_keydir "https://github.com/tarrowren/bitcask-js/blob/main/src/dir.ts"
click node_filepool "https://github.com/tarrowren/bitcask-js/blob/main/src/file-pool.ts"
click node_datafiles "https://github.com/tarrowren/bitcask-js/blob/main/src/file.ts"
click node_filequeue "https://github.com/tarrowren/bitcask-js/blob/main/src/queue.ts"
click node_stream "https://github.com/tarrowren/bitcask-js/blob/main/src/stream.ts"
click node_records "https://github.com/tarrowren/bitcask-js/blob/main/src/record.ts"
click node_hints "https://github.com/tarrowren/bitcask-js/blob/main/src/hint.ts"
click node_buffers "https://github.com/tarrowren/bitcask-js/blob/main/src/buffer.ts"
click node_checksums "https://github.com/tarrowren/bitcask-js/blob/main/src/crc32.ts"
click node_definitions "https://github.com/tarrowren/bitcask-js/blob/main/src/def.ts"
click node_manifest "https://github.com/tarrowren/bitcask-js/blob/main/src/manifest.ts"
click node_filelock "https://github.com/tarrowren/bitcask-js/blob/main/src/lockfile.ts"
click node_merge "https://github.com/tarrowren/bitcask-js/blob/main/src/merge.ts"
click node_orderedmap "https://github.com/tarrowren/bitcask-js/blob/main/src/linked-map.ts"
click node_randomname "https://github.com/tarrowren/bitcask-js/blob/main/src/random-name.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bitcask,node_options,node_keydir toneBlue
class node_filepool,node_datafiles,node_filequeue,node_stream,node_database toneAmber
class node_records,node_hints,node_buffers,node_checksums,node_definitions toneMint
class node_manifest,node_filelock,node_merge,node_orderedmap,node_randomname toneRose
class node_client toneIndigo
```

## Components

### Store API

- [Bitcask API](https://github.com/tarrowren/bitcask-js/blob/main/src/bitcask.ts): `src/bitcask.ts`
- [Store Options](https://github.com/tarrowren/bitcask-js/blob/main/src/opts.ts): `src/opts.ts`
- [Key Directory](https://github.com/tarrowren/bitcask-js/blob/main/src/dir.ts): `src/dir.ts`

### File Storage

- [File Pool](https://github.com/tarrowren/bitcask-js/blob/main/src/file-pool.ts): `src/file-pool.ts`
- [File Readers and Writers](https://github.com/tarrowren/bitcask-js/blob/main/src/file.ts): `src/file.ts`
- [Request Queue](https://github.com/tarrowren/bitcask-js/blob/main/src/queue.ts): `src/queue.ts`
- [Read Stream](https://github.com/tarrowren/bitcask-js/blob/main/src/stream.ts): `src/stream.ts`
- **Database Files**

### Record Formats

- [Record Codec](https://github.com/tarrowren/bitcask-js/blob/main/src/record.ts): `src/record.ts`
- [Hint Codec](https://github.com/tarrowren/bitcask-js/blob/main/src/hint.ts): `src/hint.ts`
- [Buffer Primitives](https://github.com/tarrowren/bitcask-js/blob/main/src/buffer.ts): `src/buffer.ts`
- [CRC32](https://github.com/tarrowren/bitcask-js/blob/main/src/crc32.ts): `src/crc32.ts`
- [Format Constants](https://github.com/tarrowren/bitcask-js/blob/main/src/def.ts): `src/def.ts`

### Metadata and Maintenance

- [Manifest](https://github.com/tarrowren/bitcask-js/blob/main/src/manifest.ts): `src/manifest.ts`
- [Database Lock](https://github.com/tarrowren/bitcask-js/blob/main/src/lockfile.ts): `src/lockfile.ts`
- [Merge and Cleanup](https://github.com/tarrowren/bitcask-js/blob/main/src/merge.ts): `src/merge.ts`
- [Linked Map](https://github.com/tarrowren/bitcask-js/blob/main/src/linked-map.ts): `src/linked-map.ts`
- [File Naming](https://github.com/tarrowren/bitcask-js/blob/main/src/random-name.ts): `src/random-name.ts`

### Other components

- **Application**

## Connections

- Application → Bitcask API: submits operations
- Bitcask API → Key Directory: looks up keys (evidence: `src/bitcask.ts`)
- Bitcask API → File Pool: reads and writes (evidence: `src/bitcask.ts`)
- Bitcask API → Record Codec: decodes records (evidence: `src/bitcask.ts`)
- Bitcask API → Manifest: opens metadata (evidence: `src/bitcask.ts`)
- Bitcask API → Database Lock: locks database (evidence: `src/bitcask.ts`)
- Bitcask API → Merge and Cleanup: clears files (evidence: `src/bitcask.ts`)
- Bitcask API → Store Options: uses settings (evidence: `src/bitcask.ts`)
- File Pool → File Readers and Writers: dispatches I/O (evidence: `src/file-pool.ts`)
- File Readers and Writers → Read Stream: creates read streams (evidence: `src/file.ts`)
- File Pool → Manifest: checks file metadata (evidence: `src/file-pool.ts`)
- File Pool → Request Queue: queues requests (evidence: `src/file-pool.ts`)
- File Readers and Writers → Database Files: reads and writes
- Record Codec → Buffer Primitives: encodes fields (evidence: `src/record.ts`)
- Record Codec → CRC32: checks CRC (evidence: `src/record.ts`)
- Record Codec → Format Constants: uses sizes (evidence: `src/record.ts`)
- Record Codec → Key Directory: uses directory types (evidence: `src/record.ts`)
- Hint Codec → Buffer Primitives: encodes fields (evidence: `src/hint.ts`)
- Hint Codec → Format Constants: uses sizes (evidence: `src/hint.ts`)
- Hint Codec → Key Directory: yields directory entries (evidence: `src/hint.ts`)
- Manifest → Linked Map: tracks files (evidence: `src/manifest.ts`)
- Manifest → File Naming: chooses file names (evidence: `src/manifest.ts`)
- Merge and Cleanup → File Pool: reads old data (evidence: `src/merge.ts`)
- Merge and Cleanup → Hint Codec: writes hints (evidence: `src/merge.ts`)
- Merge and Cleanup → Manifest: uses file metadata (evidence: `src/merge.ts`)
- Merge and Cleanup → Record Codec: parses records (evidence: `src/merge.ts`)