Hive

Hive (hive) allows for seamlessly embedding SQLite-backed databases into modern TypeScript projects.

Its modular architecture and components allow it to scale from small in-memory demos or test scenarios to full-blown replicated and S3-based production setups.

Features:

• Pure TypeScript and Web Standards
  Ships with components to support any runtime ranging from browsers and workers to full-fledged runtimes like Bun, Deno, or Node.

• Pluggable Storage Backends
  Storage backends including MemoryStorage, DiskStorage, S3Storage, and RemoteStorage enable seamless implementation of Hive instances for testing, synchronized desktop and mobile clients, globally replicated APIs and more.

• Built-in Replication & Sync
  Keep clients and server replicas in sync with automatic, bidirectional replication.

• Extensible SDK
  Well-documented API for building custom components tailored to your specific needs.

• Lightweight & Performant
  Optimized for tree-shaking to ship the most minimal bundle size. Hive is optimized both for scale and performance. Benchmarks follow.

Contents

• Installation
  Learn how to add hive to your project.

• Usage
  Create, query, and manage your first databases.

• Examples
  The following examples showcase the most common setup scenarios. More examples for individual features can be found under Components.

  • Automatic Snapshots
  • Namespaces
  • Server & Auth
  • Replication
  • Logging
  • Sentry

• Components
  All components hive natively ships with.

Installation

In a project, simply add hive as a dependency using your package manager of choice (bun, pnpm, npm, ...):

bun add hive

Usage

import { Database, Hive } from 'hive';
import { MemoryStorage } from 'hive/memory-storage';
import { BunDriver } from 'hive/bun-driver';

// 1. Create a new Hive instance.
const hive = new Hive({
  storage: ({ events }) =>
    new MemoryStorage({
      events,
      driver: new BunDriver(),
    }),
});

// 2. Create a new Database.
const db = await hive.create(new Database({ id: 'auth' }));

// 3. Query the Database.
interface User {
  id: string;
  handle: string;
}

await db.query([
  'CREATE TABLE users (id TEXT PRIMARY KEY, handle TEXT);',
  {
    sql: 'INSERT INTO users (id, handle) VALUES (?, ?);',
    params: [crypto.randomUUID(), 'juri'],
  },
]);

const [{ rows: users }] = await db.query<[User]>([
  'SELECT * FROM users;',
]);

// Recommended: Shut down gracefully.
process.on('SIGINT', async () => {
  await hive.stop();
  process.exit(0);
});

This concise example illustrates how to create a new Hive instance, create a new database, execute queries, and enable graceful shutdowns.

In future versions, drivers will be selected automatically, according to which one is best optimized for the current runtime.

Components

Hive

• hive
  ^{readme ⋅ examples}
  Main entrypoint exporting the Hive class, which operates configured components.

Storage

• hive/memory-storage
  ^{readme ⋅ examples}
  Persist database state in memory, useful for development, testing or migration scripts.

• hive/disk-storage
  ^{readme ⋅ examples}
  Persist database state on the file system, useful for simple monolithic APIs or temporary offloading.

• hive/s3-storage
  ^{readme ⋅ examples}
  Persist database state in any S3-compatible Storage, useful for backups or when scaling.

• hive/remote-storage
  ^{readme ⋅ examples}
  Persist database state on a remote Hive instance, fetch-only by default but can replicate state locally if a cache is configured.

Drivers

• hive/bun-driver
  ^{readme ⋅ examples}
  Native support for the Bun runtime, wrapping bun:sqlite.

Resource Management

• hive/snapshots
  ^{readme ⋅ examples}
  Automatically create, clean-up and manage snapshots.

Networking

• hive/server
  ^{readme ⋅ examples}
  Expose a Hive instance over the network.

• hive/api
  ^{readme ⋅ examples}
  REST API for operating a Hive instance via HTTP, comes with a fully-typed client.

• hive/api-key-auth
  ^{readme ⋅ examples}
  Secure an exposed Hive instance with granular API keys.

• hive/static-auth
  ^{readme ⋅ examples}
  Secure an exposed Hive instance with static shared secrets.

Customization and Development

• hive/sdk
  ^{readme ⋅ examples}
  Collection of interfaces, types, and utilities allowing to easily build on top of Hive.

• hive/streams
  ^{readme ⋅ examples}
  Utilities for working with binary data streams.

• hive/sockets
  ^{readme ⋅ examples}
  Custom WebSocket Server and Client implementation adding full-duplex, channel-based and authenticated communication between instances.