@jr200-labs/xstate-duckdb
v2.0.3
Published
XState machine for DuckDB
Downloads
1,537
Maintainers
Readme
@jr200-labs/xstate-duckdb
A state machine for managing DuckDB operations in web applications. This library provides a type-safe interface for database initialization, query execution, transaction management, and table catalog operations.
Features
- State Management: Full XState integration for predictable database state management
- DuckDB Integration: Built on top of
@duckdb/duckdb-wasmfor browser-based analytics - Transaction Support: Complete transaction lifecycle management (begin, execute, commit, rollback)
- Table Catalog: Dynamic table loading, versioning, and management
- Type Safety: Full TypeScript support with comprehensive type definitions
- Multiple Data Formats: Support for Arrow IPC and JSON data formats
- Compression: Built-in support for data compression (zlib)
- Real-time Updates: Subscription-based table change notifications
- Optimistic Projections: Typed local operations over authoritative DuckDB views with acknowledgement and reconciliation
Installation
npm install @jr200-labs/xstate-duckdb
# or
yarn add @jr200-labs/xstate-duckdb
# or
pnpm add @jr200-labs/xstate-duckdbPeer dependencies
@duckdb/duckdb-wasm, apache-arrow, @opentelemetry/api, and @opentelemetry/api-logs are declared as peer dependencies and must be installed directly by the consumer. This guarantees a single resolved version across the dependency tree -- preventing the class of bug where a transitive copy of DuckDB-wasm diverges from the .wasm assets the consumer actually ships.
pnpm add @duckdb/duckdb-wasm apache-arrow @opentelemetry/api @opentelemetry/api-logsSupported ranges:
| Peer | Range |
| ------------------------- | --------------------- |
| @duckdb/duckdb-wasm | >=1.33.1-dev42.0 <2 |
| apache-arrow | >=21 <22 |
| @opentelemetry/api | ^1.10.0 |
| @opentelemetry/api-logs | ^0.223.0 |
This version requires OpenTelemetry API 1.10.0 or newer within major 1 and OpenTelemetry Logs API 0.223.x. Consumers using API 1.9.x or Logs API 0.222.x must upgrade those direct dependencies together with this package.
Documentation and live demo
The Quarto documentation lives in docs/, with guides for
getting started, queries and transactions,
the catalog, observability, and
optimistic projections.
The interactive React example now lives in docs/demo/. It runs DuckDB in the
visitor's browser and displays a live XState lifecycle diagram alongside query,
transaction, and catalog controls.
pnpm install --frozen-lockfile
pnpm demo:dev # library build + Vite demo
pnpm docs:preview # Quarto docs with embedded production demo
pnpm docs:build # static site in docs/_site
pnpm testDocumentation builds require Node.js 22+ and Quarto. Quarto's pre-render hook builds the library and demo automatically. Generated files are not committed.
Publishing
.github/workflows/bespoke_docs.yaml validates the site on pull requests and
uses GAT's reusable Quarto publisher on master. The caller includes library and
lockfile changes as well as docs, so the demo is rebuilt when its code changes.
GAT publishes the rendered site to gh-pages. Configure GitHub Pages to serve
that branch's root directory. The demo uses relative asset paths so the site
works beneath the project's GitHub Pages path.
Contributing
Contributions welcome!
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details.
