{"_id":"@3xhaust/gitdb","name":"@3xhaust/gitdb","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@3xhaust/gitdb","version":"0.1.0","description":"GitHub-backed local database runtime with auditable storage, transactions, and ORM APIs.","type":"module","main":"./dist/src/index.js","types":"./dist/src/index.d.ts","homepage":"https://3x-haust.github.io/gitdb/","exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js"}},"bin":{"gitdb":"dist/src/cli/main.js"},"scripts":{"build":"rm -rf dist && tsc -p tsconfig.json","benchmark":"corepack pnpm build && node scripts/benchmark.mjs","benchmark:compare":"GITDB_BENCH_OUTPUT=.gitdb/bench-current.json corepack pnpm benchmark:evaluate > /dev/null && node scripts/benchmark-compare.mjs --current .gitdb/bench-current.json --baseline docs/BENCHMARK_BASELINE.json --baseline-label \"previous runtime baseline\" --output site/benchmark.json --markdown site/benchmark.md","benchmark:evaluate":"corepack pnpm build && node scripts/benchmark.mjs --json","benchmark:gate":"corepack pnpm build && node scripts/benchmark-gate.mjs","benchmark:site":"GITDB_SITE_OUTPUT=site/benchmark.json corepack pnpm benchmark:evaluate > /dev/null","benchmark:github":"corepack pnpm build && node scripts/benchmark.mjs --github","check":"biome check . && tsc --noEmit","example":"corepack pnpm example:api","example:api":"corepack pnpm build && node examples/api-local/index.mjs && node examples/api-encrypted/index.mjs && node examples/api-encrypted-reopen/index.mjs","example:api-local":"corepack pnpm build && node examples/api-local/index.mjs","example:api-encrypted":"corepack pnpm build && node examples/api-encrypted/index.mjs","example:api-encrypted-reopen":"corepack pnpm build && node examples/api-encrypted-reopen/index.mjs","format":"biome check --write .","pack:dry-run":"corepack pnpm build && COREPACK_ENABLE_STRICT=0 npm pack --dry-run --json","publish:dry-run":"corepack pnpm build && COREPACK_ENABLE_STRICT=0 npm publish --dry-run --access public","site:preview":"python3 -m http.server 4173 --directory site","test":"vitest run","test:e2e":"vitest run tests/e2e.test.ts"},"dependencies":{"@octokit/rest":"22.0.1","alasql":"4.17.3","commander":"15.0.0","pino":"10.3.1","zod":"4.4.3"},"devDependencies":{"@biomejs/biome":"2.4.16","@types/node":"25.9.2","dotenv":"^17.4.2","typescript":"6.0.3","vitest":"4.1.8"},"engines":{"node":">=20.19.0"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/3x-haust/gitdb.git"},"gitHead":"d1d1dc22e2c564affc0dc11ff1892fb9b6b0aa50","_id":"@3xhaust/gitdb@0.1.0","bugs":{"url":"https://github.com/3x-haust/gitdb/issues"},"_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-7r7tcFMOirLctCHB0bBe0MRVFs/YtL8Jz41+dGOPyOYmTAQR7VWUT9Ux8qlf3E09agEHbcqflUb6crvfm1F9Bg==","shasum":"27b8b2f6cdeff4a9e052a884d5cc9854645c5dca","tarball":"https://registry.npmjs.org/@3xhaust/gitdb/-/gitdb-0.1.0.tgz","fileCount":161,"unpackedSize":312370,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDQlAjLiHR2WBNehuAtQgT5oSB+th0A84tE44Omq03fCAiA5OANCBs32rdzM6yOxRJb3x46pmqg9GWQcuWWIM9ml7g=="}]},"_npmUser":{"name":"3xhaust","email":"s2424@e-mirim.hs.kr"},"directories":{},"maintainers":[{"name":"3xhaust","email":"s2424@e-mirim.hs.kr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gitdb_0.1.0_1781488016781_0.9281221319683994"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-15T01:46:56.589Z","0.1.0":"2026-06-15T01:46:56.936Z","modified":"2026-06-15T01:46:57.175Z"},"maintainers":[{"name":"3xhaust","email":"s2424@e-mirim.hs.kr"}],"description":"GitHub-backed local database runtime with auditable storage, transactions, and ORM APIs.","homepage":"https://3x-haust.github.io/gitdb/","repository":{"type":"git","url":"git+https://github.com/3x-haust/gitdb.git"},"bugs":{"url":"https://github.com/3x-haust/gitdb/issues"},"license":"MIT","readme":"# GitDB\n\nEnglish | [한국어](docs/README.ko.md) | [Website](https://3x-haust.github.io/gitdb/)\n\nGitDB is a first-party database runtime that uses repository storage as durable\nhistory. Queries execute locally. Writes commit through a manifest-gated\nmutation log. Plaintext stores expose reviewable page snapshots, while GitHub\nstores sync durable state through Git tree commits.\n\n```text\nApp code\n  -> GitDB DataSource / Repository\n  -> Local SQL engine + equality indexes\n  -> Manifest, mutation log, page snapshots, compaction\n  -> GitHub repository for durable history and audit\n```\n\nGitDB is not a single JSON file with a SQL-shaped API. Its identity is the\nruntime and storage engine: transaction boundaries, single-writer control,\nreplayable logs, checkpointed snapshots, rebuildable indexes, compaction, and\nGitHub audit sync.\n\n## Why GitDB\n\nUse GitDB when you want:\n\n- A database repository per project, for example `my-app-db`\n- Local query execution without per-query network round trips\n- A TypeORM-style `DataSource` and repository API included in the package\n- Human-inspectable plaintext snapshots for public demos and reviewable data\n- Encrypted manifest and mutation logs for private local data\n- Auditable Git commits for agents, demos, content tools, config tools, and\n  low-frequency app data\n\nGitDB is still experimental. Do not use it for high-throughput OLTP, low-latency\ndistributed writers, range-heavy analytics, or workloads that require mature\nmulti-node coordination.\n\n## Current Surface\n\n| Area | Current behavior |\n| --- | --- |\n| App API | `createGitDbDataSource`, `defineEntity`, typed repositories |\n| ORM | `save`, `insert`, `insertMany`, `saveMany`, `find`, `findOne`, `delete` |\n| SQL engine | `CREATE TABLE`, `INSERT`, `DELETE`, `SELECT`, joins, grouping, ordering, aggregates |\n| Indexes | Rebuildable primary/equality indexes for simple equality lookup |\n| Storage | Local plaintext, local encrypted, GitHub plaintext, GitHub encrypted |\n| Durability | Manifest-gated mutation log replay with checkpointed visible snapshots |\n| Concurrency | Local single-writer with multiple readers and stale lock recovery |\n| Compaction | Local plaintext log compaction behind page snapshot checkpoints |\n| GitHub sync | Git Database tree, commit, and non-force ref updates |\n| CLI | `gitdb keygen`, `gitdb query`, `gitdb check` |\n| Package | npm exports, bin, pack dry-run, publish dry-run scripts |\n\n## Guarantee Matrix\n\n| Capability | Guarantee | Boundary |\n| --- | --- | --- |\n| Transactions | Mutations are serialized and manifest-gated before becoming committed state. | In-process queue plus store commit boundary |\n| Concurrency | Local stores own a single writer lock with stale recovery; readers can reopen committed state. | Not distributed OLTP |\n| Durability | Reopen uses a checkpoint only when its sequence matches the manifest; otherwise logs replay. | Manifest sequence |\n| Snapshots | Plaintext snapshots are page-level JSON files plus `snapshot.json`. | Optimization, not source of truth |\n| Indexes | Equality indexes rebuild from committed rows and are ignored when stale or missing. | Derived data |\n| Compaction | Checkpoint first, manifest advance second, obsolete log deletion last. | Local plaintext store |\n| GitHub remote | Writes use tree commit batches and non-force ref updates. | Remote audit sync, not SELECT hot path |\n\n## Repository Layout\n\nPlaintext mode writes internal state plus human-readable snapshots:\n\n```text\ngitdb/v1/\n  manifest.json\n  snapshot.json\n  people/\n    schema.json\n    pages.json\n    pages/\n      000000.json\n    indexes.json\n  log/\n    00000000000000000001.json\n```\n\n`schema.json` contains only schema:\n\n```json\n{\n  \"name\": \"people\",\n  \"columns\": [\"id\", \"name\", \"team_id\"]\n}\n```\n\nPage files contain rows:\n\n```json\n[\n  { \"id\": \"p1\", \"name\": \"Lin\", \"team_id\": \"t1\" },\n  { \"id\": \"p2\", \"name\": \"Ada\", \"team_id\": \"t2\" }\n]\n```\n\nEncrypted mode writes opaque files:\n\n```text\ngitdb/v1/\n  manifest.enc\n  log/\n    00000000000000000001.enc\n```\n\n## Quick Start\n\nInstall:\n\n```bash\nnpm install @3xhaust/gitdb\n```\n\nUse the first-party repository API:\n\n```ts\nimport { LocalPlaintextStore, createGitDbDataSource, defineEntity } from \"@3xhaust/gitdb\"\n\ntype Person = {\n  readonly id: string\n  readonly name: string\n  readonly team_id: string\n}\n\nconst PersonEntity = defineEntity<Person>({\n  columns: { id: \"STRING\", name: \"STRING\", team_id: \"STRING\" },\n  indexes: [{ columns: [\"team_id\"], name: \"people_team_id_idx\" }],\n  primaryKey: \"id\",\n  tableName: \"people\",\n})\n\nconst dataSource = await createGitDbDataSource({\n  entities: [PersonEntity],\n  store: new LocalPlaintextStore({ root: \".gitdb\" }),\n  synchronize: true,\n})\n\nconst people = dataSource.getRepository(PersonEntity)\nawait people.insertMany([\n  { id: \"p1\", name: \"Lin\", team_id: \"storage\" },\n  { id: \"p2\", name: \"Ada\", team_id: \"runtime\" },\n])\nawait people.saveMany([{ id: \"p2\", name: \"Ada Lovelace\", team_id: \"runtime\" }])\n\nconst storagePeople = await people.find({ where: { team_id: \"storage\" } })\n```\n\nSecondary indexes are equality-only metadata on `defineEntity`. The runtime uses\nrebuilt equality indexes for simple `find({ where })` and `SELECT * ... WHERE`\nlookups when the query shape is safe; other SQL falls back to the local SQL\nengine.\n\n## CLI\n\nGenerate an encryption key:\n\n```bash\ngitdb keygen\n```\n\nCheck the configured store:\n\n```bash\nGITDB_ENCRYPTION=off GITDB_ROOT=.gitdb gitdb check\n```\n\nExecute one SQL statement:\n\n```bash\nGITDB_ENCRYPTION=off GITDB_ROOT=.gitdb \\\n  gitdb query \"CREATE TABLE people (id STRING, name STRING)\"\n```\n\n## Environment Model\n\nLocal plaintext mode:\n\n```env\nGITDB_ENCRYPTION=off\nGITDB_ROOT=.gitdb\n```\n\nLocal encrypted mode:\n\n```env\nGITDB_ENCRYPTION=on\nGITDB_KEY=generated-by-gitdb-keygen\nGITDB_ROOT=.gitdb\n```\n\nGitHub-backed modes additionally use:\n\n```env\nGITDB_GITHUB_OWNER=3x-haust\nGITDB_GITHUB_REPO=my-project-db\nGITDB_GITHUB_BRANCH=main\nGITDB_GITHUB_PREFIX=gitdb/v1\nGITDB_GITHUB_TOKEN=github_token_with_contents_write_access\n```\n\nLeave `GITDB_GITHUB_TOKEN` blank for local-only development. Use\n`GITDB_ENCRYPTION=off` only for intentional public demos where table names,\ncolumns, and rows should be visible.\n\n## Operations\n\nRun the bundled example:\n\n```bash\ncorepack pnpm example\n```\n\nThis builds the package and runs the plaintext API example plus two encrypted\nAPI examples:\n\n- `examples/api-local`\n- `examples/api-encrypted`\n- `examples/api-encrypted-reopen`\n\nRun local benchmarks:\n\n```bash\ncorepack pnpm benchmark\n```\n\nCompare current benchmark evidence with the previous documented run:\n\n```bash\nGITDB_BENCH_ROWS=250 corepack pnpm benchmark:compare\n```\n\nCompact committed logs on a local plaintext engine:\n\n```ts\nconst engine = await GitDbEngine.open({ store: new LocalPlaintextStore({ root: \".gitdb\" }) })\nawait engine.compact()\n```\n\nCompaction writes a matching page snapshot first, advances the manifest to an\nempty log list second, and deletes obsolete log segments last.\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md)\n- [API](docs/API.md)\n- [Benchmarks](docs/BENCHMARKS.md)\n- [Migration](docs/MIGRATION.md)\n- [Release Handoff](docs/RELEASE.md)\n- [Release Notes](docs/RELEASE_NOTES.md)\n\n## Current Limitations\n\n- SQL support is intentionally limited to the subset GitDB currently executes.\n- Local writes are single-writer with stale lock recovery. This is not\n  distributed OLTP.\n- GitHub tree commits are for durable audit sync, not the SELECT hot path.\n- Local encrypted compaction is not enabled until encrypted checkpoint restore\n  lands.\n- Public plaintext mode is not private mode.\n\n## Commands\n\n```bash\ncorepack pnpm check\ncorepack pnpm test\ncorepack pnpm build\ncorepack pnpm benchmark\ncorepack pnpm benchmark:evaluate\ncorepack pnpm pack:dry-run\ncorepack pnpm publish:dry-run\ncorepack pnpm example\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-c19b47a067ef4490844224c702ebe1c9"}