xitdb (current version 0.13.0) is an embedded, immutable database library for TypeScript and JavaScript, designed for storing and managing structured data in a versioned manner. It excels by efficiently creating a new "copy" of the database with each transaction, allowing past states to be read from or reverted to. Unlike traditional databases, xitdb operates without a query engine, instead providing direct APIs to manipulate core data structures like ArrayList and HashMap, which can be nested arbitrarily. It supports both single-file and in-memory storage, incrementally reading and writing to handle datasets larger than available memory. A key differentiator is its entirely synchronous API, eliminating the need for `async/await`, and its pure TypeScript implementation with no external dependencies beyond the JavaScript standard library. Reads never block writes, and multiple threads/processes can access the database concurrently without locks. This makes it a powerful alternative to SQL databases like SQLite for applications requiring simplicity, immutability, and tight integration with native TypeScript data structures, especially in scenarios akin to version control systems. The project is under active development, with an irregular, feature-driven release cadence, reflecting its 0.x version status.
npm install xitdbVerified import paths — ran on the pinned version, not inferred.
This example initializes a file-backed xitdb, performs a transaction to write structured data, and then reads the latest state.
Always pin to exact versions (e.g., `"xitdb": "0.13.0"`) or use a version range that accounts for potential breaking changes (e.g., `"xitdb": "^0.13.0"` with caution).
Embrace direct object manipulation. Design your data schema to align with nested ArrayLists and HashMaps for efficient access within your application logic.
Ensure all write operations are performed within the context function passed to `history.appendContext()`, using `WriteArrayList` and `WriteHashMap` objects.
For client-side applications or Node.js servers, consider offloading intensive xitdb operations to Web Workers or child processes to prevent blocking the main thread. In embedded or CLI tools, this is less of a concern.
For security-sensitive use cases outside of xitdb's internal data integrity, use modern cryptographic hash functions like SHA-256 or SHA-3, or libraries designed for password hashing (e.g., bcrypt).
Ensure you are within a `history.appendContext` callback and are using `WriteHashMap` or `WriteArrayList` instances created from the provided `cursor`.
Ensure `CoreBufferedFile` instances are properly closed or disposed of when no longer needed. If using `using` declarations, ensure they are within the correct scope to manage resources. Avoid opening the same file multiple times in parallel within a single process unless explicitly designed for it.
Verify that `history` is indeed an instance of `WriteArrayList` initialized from the database's root cursor, as this is the standard entry point for transactions.
Add `import { Hasher } from 'xitdb';` to the top of your TypeScript/JavaScript file.No dependency data recorded yet.