open-index/open-npm huggingface dataset:
npm package: @rippledb/client
Description: Client-side sync orchestration for RippleDB.
Latest version: 0.1.3

# @rippledb/client

Client-side sync orchestration for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/reference/client](https://rippledb.dev/docs/reference/client)

## Installation

```bash
npm install @rippledb/client @rippledb/core
```

## Usage

```typescript
import { createReplicator, syncOnce } from "@rippledb/client";

// Create a replicator for continuous sync
const replicator = createReplicator({
  stream: "user-123",
  store, // Local Store implementation
  remote, // Remote implementation (HTTP, tRPC, etc.)
});

// Push local changes and pull remote changes
await replicator.sync();

// Or use syncOnce for one-shot sync
const result = await syncOnce({ stream: "user-123", store, remote });
```

## Exports

| Export             | Description                             |
| ------------------ | --------------------------------------- |
| `createReplicator` | Create a replicator for continuous sync |
| `syncOnce`         | One-shot sync operation                 |
| `Store`            | Interface for local truth store         |
| `Remote`           | Interface for remote sync endpoint      |
| `DbEvent`          | Event emitted after store changes       |

## License

MIT
npm package: @rippledb/client-controllers
Description: Abstract CRUD controllers with batch loading for RippleDB
Latest version: 0.1.2

# @rippledb/client-controllers

Abstract CRUD controllers with batch loading for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/adapters/controllers](https://rippledb.dev/docs/adapters/controllers)

## Installation

```bash
npm install @rippledb/client-controllers
```

## Usage

```typescript
import { createEntityController } from "@rippledb/client-controllers";
import { MemoryStore } from "@rippledb/store-memory";

const store = new MemoryStore<MySchema>();

// Create a controller for an entity type
const todoController = createEntityController({
  store,
  entity: "todos",
  stream: "user-123",
});

// CRUD operations with automatic batch loading
const todo = await todoController.create({ title: "Buy milk" });
const fetched = await todoController.read(todo.id);
const updated = await todoController.update(todo.id, { done: true });
await todoController.delete(todo.id);
```

## Features

- **Batch loading**: Multiple `read()` calls in the same tick are automatically
  batched
- **CRUD operations**: Simple, type-safe create/read/update/delete API
- **Framework agnostic**: Works with any UI framework or backend
- **Store abstraction**: Works with any `Store` implementation

## Relationship to bind-tanstack-query

- **Controllers**: Handle reads/writes and batch loading (data access layer)
- **bind-tanstack-query**: Handles cache invalidation (UI reactivity layer)

Use controllers for CRUD operations, and `bind-tanstack-query` for automatic
cache invalidation.

## License

MIT
npm package: @rippledb/client-query
Description: Final DX package combining controllers + bind-tanstack-query for RippleDB
Latest version: 0.1.2

# @rippledb/client-query

Final DX package combining:

- `@rippledb/client-controllers` (CRUD controllers)
- `@rippledb/bind-tanstack-query` (TanStack Query invalidation wiring)

This package is intended to be the ergonomic “one import” for client apps using
RippleDB + TanStack Query.

📚 **Documentation:**
[rippledb.dev/docs/reference/client-query](https://rippledb.dev/docs/reference/client-query)

## Installation

```bash
pnpm add @rippledb/client-query @tanstack/query-core
```

If you use a framework adapter (e.g. `@tanstack/react-query`), you already have
`@tanstack/query-core`.

## Usage

```ts
import { createClientQueryApi } from "@rippledb/client-query";
import { defineSchema } from "@rippledb/core";
import { MemoryStore } from "@rippledb/store-memory";
import { QueryClient } from "@tanstack/query-core";

type Schema = {
  todos: { id: string; title: string; done: boolean; };
  users: { id: string; name: string; email: string; };
};

const store = new MemoryStore<Schema>();
const queryClient = new QueryClient();

// Runtime descriptor (entity + field discovery)
const schema = defineSchema({
  todos: { id: "", title: "", done: false },
  users: { id: "", name: "", email: "" },
});

const api = createClientQueryApi({
  store,
  stream: "user-123",
  queryClient,
  schema,
});

// CRUD via dynamic controllers
const todo = await api.todos.create({ title: "Buy milk", done: false });
await api.todos.update(todo.id, { done: true });

// Cached query helper + automatic invalidation
const todos = await api.query({
  key: ["todos"],
  deps: ["todos"],
  fn: () => api.todos.list({ entity: "todos" }),
});
```

## Query registry

If you want to register “list queries” up-front (recommended), build a registry
and pass it in:

```ts
import { defineListRegistry } from "@rippledb/bind-tanstack-query";

const registry = defineListRegistry()
  .list(["todos"], { deps: ["todos"] })
  .list(["dashboard"], { deps: ["todos", "users"] });

const api = createClientQueryApi({
  store,
  stream,
  queryClient,
  schema,
  registry,
});
```

## License

MIT
npm package: @rippledb/core
Description: Core primitives for RippleDB: HLC timestamps, Change types, and merge logic.
Latest version: 0.3.0

# @rippledb/core

Core primitives for RippleDB: HLC timestamps, Change types, and merge logic.

📚 **Documentation:**
[rippledb.dev/docs/reference/core](https://rippledb.dev/docs/reference/core)

## Installation

```bash
npm install @rippledb/core
```

## Usage

```typescript
import {
  createHlcState,
  makeDelete,
  makeUpsert,
  tickHlc,
} from "@rippledb/core";

// Create HLC state for a node
const hlcState = createHlcState("node-1");

// Generate a timestamp
const hlc = tickHlc(hlcState, Date.now());

// Create changes
const upsert = makeUpsert({
  stream: "user-123",
  entity: "todos",
  entityId: "todo-1",
  patch: { title: "Buy milk", done: false },
  hlc,
});

const deletion = makeDelete({
  stream: "user-123",
  entity: "todos",
  entityId: "todo-1",
  hlc,
});
```

## Exports

| Export           | Description                 |
| ---------------- | --------------------------- |
| `createHlcState` | Create HLC state for a node |
| `tickHlc`        | Generate next HLC timestamp |
| `compareHlc`     | Compare two HLC timestamps  |
| `makeUpsert`     | Create an upsert change     |
| `makeDelete`     | Create a delete change      |
| `RippleSchema`   | Type for entity schemas     |
| `Change`         | Type for changes            |
| `Hlc`            | Type for HLC timestamps     |

## License

MIT
npm package: @rippledb/db-drizzle
Description: Database-agnostic Drizzle ORM adapter for RippleDB.
Latest version: 0.2.0

# @rippledb/db-drizzle

Database-agnostic Drizzle ORM adapter for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/adapters/db-drizzle](https://rippledb.dev/docs/adapters/db-drizzle)

## Installation

```bash
npm install @rippledb/db-drizzle @rippledb/core @rippledb/server drizzle-orm
```

## Usage

```typescript
import { DrizzleDb } from "@rippledb/db-drizzle";
import { drizzle } from "drizzle-orm/better-sqlite3";
import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
import { getTableConfig } from "drizzle-orm/sqlite-core";

// Define your tables
const changesTable = sqliteTable("ripple_changes", {
  seq: integer("seq").primaryKey({ autoIncrement: true }),
  stream: text("stream").notNull(),
  change_json: text("change_json").notNull(),
});

const idempotencyTable = sqliteTable("ripple_idempotency", {
  stream: text("stream").notNull(),
  idempotency_key: text("idempotency_key").notNull(),
  last_seq: integer("last_seq").notNull(),
});

// Create the adapter
const rippleDb = new DrizzleDb({
  db: drizzle(sqlite),
  changesTable,
  idempotencyTable,
  getTableConfig,
  isSync: true, // For better-sqlite3
});
```

## Features

- Works with any Drizzle-supported database (SQLite, PostgreSQL, MySQL)
- Type-safe with full TypeScript support
- Supports both sync (better-sqlite3) and async drivers
- Optional materialization with Drizzle schemas

## License

MIT
npm package: @rippledb/db-memory
Description: In-memory database adapter for RippleDB testing.
Latest version: 0.1.3

# @rippledb/db-memory

In-memory database adapter for RippleDB testing.

📚 **Documentation:**
[rippledb.dev/docs/adapters/db-memory](https://rippledb.dev/docs/adapters/db-memory)

## Installation

```bash
npm install @rippledb/db-memory @rippledb/core @rippledb/server
```

## Usage

```typescript
import { MemoryDb } from "@rippledb/db-memory";

const db = new MemoryDb<MySchema>();

// Append changes
await db.append({
  stream: "user-123",
  changes: [
    /* ... */
  ],
});

// Pull changes
const { changes, nextCursor } = await db.pull({
  stream: "user-123",
  cursor: null,
});
```

## Features

- No persistence (data lost on restart)
- Fast synchronous operations
- Idempotency key support
- Perfect for unit tests and prototyping

## License

MIT
npm package: @rippledb/db-sqlite
Description: SQLite database adapter for RippleDB using better-sqlite3.
Latest version: 0.2.0

# @rippledb/db-sqlite

SQLite database adapter for RippleDB using better-sqlite3.

📚 **Documentation:**
[rippledb.dev/docs/adapters/db-sqlite](https://rippledb.dev/docs/adapters/db-sqlite)

## Installation

```bash
npm install @rippledb/db-sqlite @rippledb/core @rippledb/server better-sqlite3
```

## Usage

```typescript
import { SqliteDb } from "@rippledb/db-sqlite";

const db = new SqliteDb({
  filename: "ripple.db",
  // Optional: custom pragmas
  pragmas: ["journal_mode = WAL"],
});

// Append changes
await db.append({
  stream: "user-123",
  changes: [
    /* ... */
  ],
});

// Pull changes
const { changes, nextCursor } = await db.pull({
  stream: "user-123",
  cursor: null,
});

// Close when done
db.close();
```

## Features

- Synchronous operations (fast, no async overhead)
- WAL mode by default for better concurrency
- Idempotency key support
- Optional materialization

## License

MIT
npm package: @rippledb/db-turso
Description: Turso/libSQL database adapter for RippleDB.
Latest version: 0.2.0

# @rippledb/db-turso

Turso/libSQL database adapter for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/adapters/db-turso](https://rippledb.dev/docs/adapters/db-turso)

## Installation

```bash
npm install @rippledb/db-turso @rippledb/core @rippledb/server @libsql/client
```

## Usage

### Factory Pattern (Recommended)

```typescript
import { TursoDb } from "@rippledb/db-turso";

const db = await TursoDb.create({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

// Already initialized, ready to use
```

### Constructor + Init Pattern (For Top-Level Exports)

```typescript
import { TursoDb } from "@rippledb/db-turso";

// Top-level export (works in all frameworks)
export const db = new TursoDb({
  url: process.env.TURSO_URL!,
  authToken: process.env.TURSO_AUTH_TOKEN!,
});

// Initialize during app startup (after migrations if needed)
await db.init();

// Append changes
await db.append({
  stream: "user-123",
  changes: [
    /* ... */
  ],
});

// Pull changes
const { changes, nextCursor } = await db.pull({
  stream: "user-123",
  cursor: null,
});

// Close when done
db.close();
```

## Features

- Edge-ready (works with Turso's global edge network)
- Async operations with batched transactions
- Idempotency key support
- Optional materialization

## License

MIT
npm package: @rippledb/materialize-core
Description: Core materialization logic for RippleDB using per-field LWW.
Latest version: 0.2.0

# @rippledb/materialize-core

Core materialization logic for RippleDB using per-field LWW.

📚 **Documentation:**
[rippledb.dev/docs/adapters/materialize-core](https://rippledb.dev/docs/adapters/materialize-core)

## Installation

```bash
npm install @rippledb/materialize-core @rippledb/core
```

## Usage

```typescript
import {
  applyChangeToState,
  materializeChange,
} from "@rippledb/materialize-core";

// Low-level: apply a single change to state
const { state, changed, deleted } = applyChangeToState(currentState, change);

// High-level: materialize with an adapter
await materializeChange(adapter, change);
```

## Exports

| Export                | Description                             |
| --------------------- | --------------------------------------- |
| `applyChangeToState`  | Apply change to entity state using LWW  |
| `materializeChange`   | Materialize a single change via adapter |
| `materializeChanges`  | Materialize multiple changes            |
| `MaterializerState`   | Type for entity state with LWW tags     |
| `MaterializerAdapter` | Interface for storage adapters          |

## License

MIT
npm package: @rippledb/materialize-db
Description: SQL-based state materializer for RippleDB.
Latest version: 0.2.0

# @rippledb/materialize-db

SQL-based state materializer for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/adapters/materialize-db](https://rippledb.dev/docs/adapters/materialize-db)

## Installation

```bash
npm install @rippledb/materialize-db @rippledb/materialize-core @rippledb/core
```

## Usage

```typescript
import { createSyncMaterializer } from "@rippledb/materialize-db";

const materializer = createSyncMaterializer({
  tableMap: { todos: "todos", users: "users" },
  executor: {
    load: (entity, id) =>
      db.get(`SELECT * FROM ${entity}_tags WHERE id = ?`, [id]),
    save: (entity, id, data, tags) => {
      /* ... */
    },
    remove: (entity, id) => {
      /* ... */
    },
  },
});

// Load, save, remove entities
const state = materializer.load("todos", "todo-1");
materializer.save("todos", "todo-1", state);
materializer.remove("todos", "todo-1", state);
```

## Features

- Works with raw SQL databases
- Sync and async executor support
- Pairs with `db-sqlite` and `db-turso`

## License

MIT
npm package: @rippledb/materialize-drizzle
Description: Type-safe Drizzle ORM materializer for RippleDB.
Latest version: 0.2.0

# @rippledb/materialize-drizzle

Type-safe Drizzle ORM materializer for RippleDB.

📚 **Documentation:**
[rippledb.dev/docs/adapters/materialize-drizzle](https://rippledb.dev/docs/adapters/materialize-drizzle)

## Installation

```bash
npm install @rippledb/materialize-drizzle @rippledb/materialize-core @rippledb/core drizzle-orm
```

## Usage

```typescript
import { DrizzleDb } from "@rippledb/db-drizzle";

const rippleDb = new DrizzleDb({
  db: drizzle(sqlite),
  changesTable,
  idempotencyTable,
  getTableConfig,
  materializer: ({ db }) => ({
    tableMap: { todos: "todos" },
    executor: createDrizzleMaterializerExecutor({ db, tagsTable, todosTable }),
  }),
});
```

## Features

- Type-safe with Drizzle schemas
- Automatic table mapping
- Pairs with `db-drizzle`

## License

MIT
npm package: @rippledb/remote-http
Description: HTTP client for RippleDB sync.
Latest version: 0.1.3

# @rippledb/remote-http

HTTP client for RippleDB sync.

📚 **Documentation:**
[rippledb.dev/docs/reference/remote-http](https://rippledb.dev/docs/reference/remote-http)

## Installation

```bash
npm install @rippledb/remote-http @rippledb/client @rippledb/core
```

## Usage

```typescript
import { createReplicator } from "@rippledb/client";
import { createHttpRemote } from "@rippledb/remote-http";

const remote = createHttpRemote({
  baseUrl: "https://api.example.com/ripple",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const replicator = createReplicator({
  stream: "user-123",
  store,
  remote,
});

await replicator.sync();
```

## Features

- Simple HTTP POST to `/pull` and `/append`
- Custom headers support
- Custom fetch implementation (for SSR, testing, etc.)

## License

MIT
npm package: @rippledb/remote-trpc
Description: tRPC client for RippleDB sync.
Latest version: 0.1.6

# @rippledb/remote-trpc

tRPC client for RippleDB sync.

📚 **Documentation:**
[rippledb.dev/docs/reference/remote-trpc](https://rippledb.dev/docs/reference/remote-trpc)

## Installation

```bash
npm install @rippledb/remote-trpc @rippledb/client @rippledb/core @trpc/client
```

## Usage

```typescript
import { createReplicator } from "@rippledb/client";
import { createTrpcRemote } from "@rippledb/remote-trpc";
import { trpc } from "./trpc";

const remote = createTrpcRemote({
  pull: trpc.ripple.pull.query,
  append: trpc.ripple.append.mutate,
});

const replicator = createReplicator({
  stream: "user-123",
  store,
  remote,
});

await replicator.sync();
```

## Features

- Type-safe with tRPC
- Works with any tRPC client setup
- Easy testing with direct caller

## License

MIT
npm package: @rippledb/server
Description: Server-side contracts and interfaces for RippleDB persistence.
Latest version: 0.1.3

# @rippledb/server

Server-side contracts and interfaces for RippleDB persistence.

📚 **Documentation:**
[rippledb.dev/docs/reference/server](https://rippledb.dev/docs/reference/server)

## Installation

```bash
npm install @rippledb/server @rippledb/core
```

## Usage

```typescript
import type { AppendRequest, Db, PullRequest } from "@rippledb/server";

// Implement the Db interface for your database
class MyDb implements Db<MySchema> {
  async append(req: AppendRequest<MySchema>) {
    // Store changes in your database
    return { accepted: req.changes.length };
  }

  async pull(req: PullRequest) {
    // Fetch changes from your database
    return { changes: [], nextCursor: req.cursor };
  }
}
```

## Exports

| Export          | Description                        |
| --------------- | ---------------------------------- |
| `Db`            | Interface for database adapters    |
| `AppendRequest` | Request type for appending changes |
| `AppendResult`  | Result type for append operations  |
| `PullRequest`   | Request type for pulling changes   |
| `PullResponse`  | Response type for pull operations  |
| `Cursor`        | Cursor type for pagination         |

## License

MIT
npm package: @rippledb/server-trpc
Description: tRPC router for RippleDB sync endpoints.
Latest version: 0.1.6

# @rippledb/server-trpc

tRPC router for RippleDB sync endpoints.

📚 **Documentation:**
[rippledb.dev/docs/reference/server-trpc](https://rippledb.dev/docs/reference/server-trpc)

## Installation

```bash
npm install @rippledb/server-trpc @rippledb/server @rippledb/core @trpc/server
```

## Usage

```typescript
import { createRippleTrpcRouter } from "@rippledb/server-trpc";
import { initTRPC } from "@trpc/server";

const rippleRouter = createRippleTrpcRouter({ db });

const t = initTRPC.create();
export const appRouter = t.router({
  ripple: rippleRouter,
});

// Exposes:
// - ripple.pull (query)
// - ripple.append (mutation)
```

## Features

- Creates `pull` and `append` procedures
- Works with any RippleDB `Db` adapter
- Type-safe with tRPC

## License

MIT
npm package: @rippledb/store-memory
Description: In-memory client-side Store for RippleDB testing.
Latest version: 0.1.3

# @rippledb/store-memory

In-memory client-side Store for RippleDB testing.

📚 **Documentation:**
[rippledb.dev/docs/adapters/store-memory](https://rippledb.dev/docs/adapters/store-memory)

## Installation

```bash
npm install @rippledb/store-memory @rippledb/client @rippledb/core
```

## Usage

```typescript
import { MemoryStore } from "@rippledb/store-memory";

const store = new MemoryStore<MySchema>();

// Subscribe to events
const unsubscribe = store.onEvent(event => {
  console.log("Change:", event.entity, event.kind, event.id);
});

// Apply changes
await store.applyChanges([change]);

// Query data
const todo = await store.getRow("todos", "todo-1");
const todos = await store.listRows({ entity: "todos" });
```

## Features

- Implements the `Store` interface from `@rippledb/client`
- Emits `DbEvent`s for UI reactivity
- No persistence (data lost on refresh)
- Perfect for unit tests and prototyping

## License

MIT
npm package: @rippledb/store-sqlite
Description: SQLite-based client-side Store for RippleDB with persistent storage.
Latest version: 0.2.1

# @rippledb/store-sqlite

SQLite-based client-side Store for RippleDB with persistent storage.

📚 **Documentation:**
[rippledb.dev/docs/adapters/store-sqlite](https://rippledb.dev/docs/adapters/store-sqlite)

## Installation

```bash
npm install @rippledb/store-sqlite @rippledb/client @rippledb/core better-sqlite3
```

## Usage

```typescript
import { defineSchema, s } from "@rippledb/core";
import { SqliteStore } from "@rippledb/store-sqlite";

const schema = defineSchema({
  todos: {
    id: s.string(),
    title: s.string(),
    done: s.boolean(),
  },
});

const store = new SqliteStore({
  filename: "./data.db",
  schema, // Required - creates tables with proper columns
});

// Subscribe to events
const unsubscribe = store.onEvent(event => {
  console.log("Change:", event.entity, event.kind, event.id);
});

// Apply changes
await store.applyChanges([change]);

// Query data
const todo = await store.getRow("todos", "todo-1");
const todos = await store.getRows("todos", ["todo-1", "todo-2"]);

// SQL queries with WHERE clauses
const activeTodos = await store.listRows(
  "SELECT * FROM todos WHERE done = 0 AND deleted = 0",
);
```

## Features

- Implements the `Store` interface from `@rippledb/client`
- Persistent storage with SQLite
- SQL WHERE clauses on actual columns
- Type-safe: infers schema from descriptor
- Field-level conflict resolution with HLC

## License

MIT