tetherdb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Renggli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# ⚡ TetherDB
+
+**Lightweight, local-first TypeScript database with reactive IndexedDB storage and real-time two-way WebSocket sync.**
+
+[![NPM Version](https://img.shields.io/npm/v/tetherdb.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/tetherdb)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/renggli/typescript-tetherdb/ci.yml?branch=main&style=flat-square)](https://github.com/renggli/typescript-tetherdb/actions)
+[![Code Coverage](https://img.shields.io/codecov/c/github/renggli/typescript-tetherdb?style=flat-square)](https://codecov.io/gh/renggli/typescript-tetherdb)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
+
+*Open-source under the [MIT License](LICENSE).*
+
+[Features](#features) •
+[Installation](#installation) •
+[Quick Start](#quick-start) •
+[Framework Integration](#framework-integration) •
+[CLI & Server](#cli--server-administration) •
+[Production Deployment](#production-deployment) •
+[Example App](#example-application)
+
+## Features
+
+- **📱 Offline-First & Local-First**: Mutations apply immediately to browser IndexedDB with zero latency and queue in an atomic outbox for background synchronization.
+- **🔄 Real-Time Two-Way Sync**: Fast, bi-directional WebSocket sync with delta diff catch-up on reconnect, adaptive full snapshots, and automatic live broadcast to active sessions.
+- **⚖️ Deterministic Conflict Resolution**: Last-Write-Wins (LWW) conflict handling powered by monotonically increasing logical clocks and deterministic tie-breaking.
+- **🏢 Multi-Tenant & Multi-App**: Host multiple independent web applications on a single domain and server instance. Data and WebSocket streams are strictly isolated by `appId` and user account.
+- **🚀 Seamless Offline-to-Cloud Onboarding**: Start using the local database immediately without an account; attach live cloud sync on demand with a single `client.login()` or `client.register()` call.
+- **🗄️ Pluggable Server Storage**: Built-in persistence engines for SQLite (`SqliteStorage`), sharded filesystem directories (`FileStorage`), and ephemeral testing (`MemoryStorage`).
+- **🔐 Built-in Authentication**: Password hashing using scrypt with salt and HMAC-signed session tokens with automatic session persistence and recovery.
+- **⚡ Batch-by-Default Performance**: High-throughput atomic mutations (`putAll`, `deleteAll`, `getAll`) and coalesced WebSocket frame transmission.
+
+## Installation
+
+Install from npm:
+
+```bash
+npm install tetherdb
+```
+
+Or install directly from GitHub:
+
+```bash
+npm install github:renggli/typescript-tetherdb
+```
+
+## Quick Start
+
+### 1. Launch a Server (Zero-Config)
+
+You can launch a standalone TetherDB server in seconds using the CLI:
+
+```bash
+# Start server with persistent SQLite storage on port 8080
+npx tetherdb --sqlite=./data --port=8080
+```
+
+Or embed it programmatically in your Node.js backend:
+
+```typescript
+import { SqliteStorage, startServer } from 'tetherdb/server';
+
+const running = await startServer({
+  port: 8080,
+  storage: new SqliteStorage({ baseDir: './data' }),
+});
+
+console.log(`TetherDB server listening on http://${running.host}:${running.port}`);
+```
+
+### 2. Client Setup: Instant Local-First Storage
+
+TetherDB works out of the box in the browser. Writes are instant and persist offline:
+
+```typescript
+import { TetherClient } from 'tetherdb/client';
+
+interface Todo {
+  title: string;
+  completed: boolean;
+}
+
+// 1. Initialize client with server endpoint
+const client = new TetherClient('my-todo-app', {
+  url: 'http://localhost:8080',
+});
+
+// 2. Obtain a typed table
+const todos = client.table<Todo>('todos');
+
+// 3. React to local and remote data changes
+const unsubscribe = todos.onChange.register((events) => {
+  for (const { op, id, data, isRemote } of events) {
+    console.log(`Table event [${op}] on ${id} (remote: ${isRemote}):`, data);
+  }
+});
+
+// 4. Instant local writes (offline-ready)
+await todos.put('task-1', {
+  title: 'Try TetherDB',
+  completed: false,
+});
+
+// Batch operations execute in a single atomic transaction
+await todos.putAll([
+  { id: 'task-2', data: { title: 'Add offline support', completed: true } },
+  { id: 'task-3', data: { title: 'Sync with cloud', completed: false } },
+]);
+
+// Read data
+const item = await todos.get('task-1');
+const allItems = await todos.getAll();
+```
+
+### 3. Attach Live Cloud Sync & Authentication
+
+Connect your local data to the cloud whenever the user registers or signs in:
+
+```typescript
+// Register or login to initiate real-time synchronization
+await client.register({
+  username: 'alice',
+  password: 'secure-password',
+  remember: true, // Persists session token across browser reloads
+});
+
+// Monitor live connection and sync status
+client.onSyncStatusChange.register((status) => {
+  // 'disconnected' | 'connecting' | 'connected' | 'syncing' | 'synced'
+  console.log('Sync status:', status);
+});
+```
+
+## Framework Integration
+
+### React Hook Example
+
+Bind any TetherDB table to component state with automatic real-time updates:
+
+```typescript
+import { useEffect, useState } from 'react';
+import type { Table } from 'tetherdb/client';
+
+export function useTable<T>(table: Table<T>): T[] {
+  const [items, setItems] = useState<T[]>([]);
+
+  useEffect(() => {
+    // 1. Initial local load
+    table.getAll().then(setItems);
+
+    // 2. Subscribe to live changes (local writes & remote sync broadcasts)
+    const unsubscribe = table.onChange.register(() => {
+      table.getAll().then(setItems);
+    });
+
+    return unsubscribe;
+  }, [table]);
+
+  return items;
+}
+```
+
+## CLI & Server Administration
+
+TetherDB includes a full CLI suite for running servers and managing databases:
+
+```bash
+# Start standalone server with SQLite persistence
+npx tetherdb --sqlite=./data --port=8080
+
+# Start with filesystem storage
+npx tetherdb --file=./data --port=8080
+
+# Manage apps, tables, and users
+npx tetherdb apps list --sqlite=./data
+npx tetherdb apps add my-todo-app --sqlite=./data
+npx tetherdb tables add my-todo-app todos --sqlite=./data
+npx tetherdb users add alice secret --sqlite=./data
+
+# Run database maintenance & compaction
+npx tetherdb maintenance checkpoint --sqlite=./data
+npx tetherdb maintenance vacuum --sqlite=./data
+npx tetherdb maintenance prune my-todo-app 1000 --sqlite=./data
+```
+
+## HTTP & WebSocket Endpoints
+
+| Method | Endpoint | Description | Authentication |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/health` | Server uptime and health probe | Public |
+| `GET` | `/ready` | Storage backend readiness check | Public |
+| `GET` | `/metrics` | Connected clients and application metrics | Public |
+| `POST` | `/auth/register` | Create a new user account | Public |
+| `POST` | `/auth/login` | Log in and receive a signed session token | Public |
+| `WS` | `/sync` | Bi-directional WebSocket synchronization stream | Token handshake |
+
+## Production Deployment
+
+### Storage Engines
+
+TetherDB supports pluggable server storage backends:
+
+| Engine | CLI Flag | Pros | Cons |
+| :--- | :--- | :--- | :--- |
+| **SQLite** (`SqliteStorage`) | `--sqlite=<dir>` | • High throughput & ACID safety<br>• WAL mode concurrency<br>• Built-in compaction (`vacuum`, `prune`) | • Single-node filesystem binding |
+| **Filesystem** (`FileStorage`) | `--file=<dir>` | • Human-readable JSON structure<br>• Zero binary dependencies<br>• Direct inspection & simple backup | • I/O overhead on large tables<br>• Lower concurrent write throughput |
+| **In-Memory** (`MemoryStorage`) | `--memory` | • Zero disk I/O, ultra-fast<br>• Zero configuration | • Ephemeral (data lost on restart) |
+
+#### When to Use Which
+
+- **SQLite (`--sqlite`) — Best for Production (Recommended)**: Ideal for multi-user and high-concurrency apps requiring fast transactional persistence and operational maintenance tools (`vacuum`, `checkpoint`, `prune`).
+- **Filesystem (`--file`) — Best for Lightweight / Embedded**: Ideal for low-traffic apps, resource-constrained environments, or setups where direct inspection and editing of JSON files is desired.
+- **In-Memory (`--memory`) — Best for Testing & CI/CD**: Ideal for automated unit/integration test suites, ephemeral pipelines, and rapid local prototyping.
+
+### Reverse Proxy & SSL Termination
+
+For production, run TetherDB behind a reverse proxy (such as Caddy or Nginx) to handle SSL/TLS and proxy WebSocket connections:
+
+#### Caddy
+
+```caddy
+api.example.com {
+  reverse_proxy localhost:8080
+}
+```
+
+#### Nginx
+
+```nginx
+server {
+  listen 443 ssl http2;
+  server_name api.example.com;
+
+  ssl_certificate /path/to/cert.pem;
+  ssl_certificate_key /path/to/key.pem;
+
+  location / {
+    proxy_pass http://127.0.0.1:8080;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_buffering off;
+  }
+}
+```
+
+## Example Application
+
+Check out the included real-time multi-client collaborative Todo app in [`examples/todo/`](examples/todo):
+
+```bash
+# Build packages and start example app
+npm run build
+npm run example:todo
+```
+
+Open `http://localhost:3000` in multiple browser windows or simulate offline mode in DevTools to see seamless local-first persistence and instant background synchronization.
+
+## Development & Testing
+
+```bash
+# Format code & lint fix
+npm run format
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Run unit and integration tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Build bundle & type definitions
+npm run build
+```

package/bin/tetherdb.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../dist/cli/index.js';
+
+runCli().catch((err) => {
+  console.error('Failed to start TetherDB CLI:', err);
+  process.exit(1);
+});

package/dist/cli/args.d.cts

@@ -0,0 +1,20 @@
+import type { BackendType } from './backend.cjs';
+/**
+ * Parsed CLI arguments and configuration options.
+ */
+export interface ParsedCliArgs {
+    command: string;
+    positionalArgs: string[];
+    port: number;
+    host: string;
+    backend: BackendType;
+    dir: string;
+}
+/**
+ * Parses raw command-line arguments into structured options.
+ *
+ * @param args - Command line arguments.
+ * @returns Parsed CLI configuration.
+ */
+export declare function parseCliArgs(args: string[]): ParsedCliArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts

@@ -0,0 +1,20 @@
+import type { BackendType } from './backend.js';
+/**
+ * Parsed CLI arguments and configuration options.
+ */
+export interface ParsedCliArgs {
+    command: string;
+    positionalArgs: string[];
+    port: number;
+    host: string;
+    backend: BackendType;
+    dir: string;
+}
+/**
+ * Parses raw command-line arguments into structured options.
+ *
+ * @param args - Command line arguments.
+ * @returns Parsed CLI configuration.
+ */
+export declare function parseCliArgs(args: string[]): ParsedCliArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAsC1D"}

package/dist/cli/backend.d.cts

@@ -0,0 +1,15 @@
+import { type Storage, type StorageOptions } from '../server/index.cjs';
+/**
+ * Backend persistence type for TetherDB server.
+ */
+export type BackendType = 'memory' | 'file' | 'sqlite';
+/**
+ * Instantiates the matching Storage implementation for a given backend type and directory.
+ *
+ * @param backend - Target backend ('memory', 'file', or 'sqlite'). Defaults to 'memory'.
+ * @param baseDir - Directory path for file and sqlite backends. Defaults to '.data'.
+ * @param options - Optional storage configuration and limits.
+ * @returns Instantiated `Storage` engine.
+ */
+export declare function createBackend(backend?: BackendType, baseDir?: string, options?: StorageOptions): Storage;
+//# sourceMappingURL=backend.d.ts.map

package/dist/cli/backend.d.ts

@@ -0,0 +1,15 @@
+import { type Storage, type StorageOptions } from '../server/index.js';
+/**
+ * Backend persistence type for TetherDB server.
+ */
+export type BackendType = 'memory' | 'file' | 'sqlite';
+/**
+ * Instantiates the matching Storage implementation for a given backend type and directory.
+ *
+ * @param backend - Target backend ('memory', 'file', or 'sqlite'). Defaults to 'memory'.
+ * @param baseDir - Directory path for file and sqlite backends. Defaults to '.data'.
+ * @param options - Optional storage configuration and limits.
+ * @returns Instantiated `Storage` engine.
+ */
+export declare function createBackend(backend?: BackendType, baseDir?: string, options?: StorageOptions): Storage;
+//# sourceMappingURL=backend.d.ts.map

package/dist/cli/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/cli/backend.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,cAAc,EAGpB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,GAAE,WAAsB,EAC/B,OAAO,SAAU,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAeT"}

package/dist/cli/cli.d.cts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Standard command line interface for TetherDB.
+ *
+ * @param args - CLI arguments (defaults to process.argv.slice(2)).
+ */
+export declare function runCli(args?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Standard command line interface for TetherDB.
+ *
+ * @param args - CLI arguments (defaults to process.argv.slice(2)).
+ */
+export declare function runCli(args?: string[]): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli/cli.ts"],"names":[],"mappings":";AAoBA;;;;GAIG;AACH,wBAAsB,MAAM,CAC1B,IAAI,GAAE,MAAM,EAA0B,GACrC,OAAO,CAAC,IAAI,CAAC,CAyCf"}

package/dist/cli/commands/apps.d.cts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.cjs';
+/**
+ * Handles the 'apps' command family (list, add, rm).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, appId]`.
+ */
+export declare function handleAppsCommand(storage: Storage, [, action, appId]: string[]): Promise<void>;
+//# sourceMappingURL=apps.d.ts.map

package/dist/cli/commands/apps.d.ts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.js';
+/**
+ * Handles the 'apps' command family (list, add, rm).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, appId]`.
+ */
+export declare function handleAppsCommand(storage: Storage, [, action, appId]: string[]): Promise<void>;
+//# sourceMappingURL=apps.d.ts.map

package/dist/cli/commands/apps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/apps.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGb,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,CAAC,EAAE,MAAe,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/cli/commands/help.d.cts

@@ -0,0 +1,5 @@
+/**
+ * Displays command-line interface usage instructions.
+ */
+export declare function printHelp(): void;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/commands/help.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Displays command-line interface usage instructions.
+ */
+export declare function printHelp(): void;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAkChC"}

package/dist/cli/commands/index.d.cts

@@ -0,0 +1,8 @@
+export { handleAppsCommand } from './apps.cjs';
+export { printHelp } from './help.cjs';
+export { handleMaintenanceCommand } from './maintenance.cjs';
+export { handleServeCommand } from './serve.cjs';
+export { handleStatusCommand } from './status.cjs';
+export { handleTablesCommand } from './tables.cjs';
+export { handleUsersCommand } from './users.cjs';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.d.ts

@@ -0,0 +1,8 @@
+export { handleAppsCommand } from './apps.js';
+export { printHelp } from './help.js';
+export { handleMaintenanceCommand } from './maintenance.js';
+export { handleServeCommand } from './serve.js';
+export { handleStatusCommand } from './status.js';
+export { handleTablesCommand } from './tables.js';
+export { handleUsersCommand } from './users.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/cli/commands/maintenance.d.cts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.cjs';
+/**
+ * Handles the 'maintenance' command to execute maintenance routines.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param positionalArgs - Positional CLI arguments (e.g. ['maintenance', 'checkpoint', 'my-app']).
+ */
+export declare function handleMaintenanceCommand(storage: Storage, positionalArgs: string[]): Promise<void>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/cli/commands/maintenance.d.ts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.js';
+/**
+ * Handles the 'maintenance' command to execute maintenance routines.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param positionalArgs - Positional CLI arguments (e.g. ['maintenance', 'checkpoint', 'my-app']).
+ */
+export declare function handleMaintenanceCommand(storage: Storage, positionalArgs: string[]): Promise<void>;
+//# sourceMappingURL=maintenance.d.ts.map

package/dist/cli/commands/maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGb,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CAsCf"}

package/dist/cli/commands/serve.d.cts

@@ -0,0 +1,14 @@
+import { type RunningServer, type Storage } from '../../server/index.cjs';
+import type { BackendType } from '../backend.cjs';
+/**
+ * Handles the 'serve' command to launch the HTTP and WebSocket synchronization server.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param backend - Storage backend type ('memory', 'file', or 'sqlite').
+ * @param dir - Data directory for file-based backends.
+ * @param port - HTTP port to bind.
+ * @param host - Network interface to bind.
+ * @returns Handle to the running server.
+ */
+export declare function handleServeCommand(storage: Storage, backend: BackendType, dir: string, port: number, host: string): Promise<RunningServer>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/cli/commands/serve.d.ts

@@ -0,0 +1,14 @@
+import { type RunningServer, type Storage } from '../../server/index.js';
+import type { BackendType } from '../backend.js';
+/**
+ * Handles the 'serve' command to launch the HTTP and WebSocket synchronization server.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param backend - Storage backend type ('memory', 'file', or 'sqlite').
+ * @param dir - Data directory for file-based backends.
+ * @param port - HTTP port to bind.
+ * @param host - Network interface to bind.
+ * @returns Handle to the running server.
+ */
+export declare function handleServeCommand(storage: Storage, backend: BackendType, dir: string, port: number, host: string): Promise<RunningServer>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/cli/commands/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/serve.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,OAAO,EAEb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,WAAW,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CA8BxB"}

package/dist/cli/commands/status.d.cts

@@ -0,0 +1,9 @@
+import type { Storage } from '../../server/index.cjs';
+/**
+ * Handles the 'status' command to display storage backend statistics.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param positionalArgs - Positional CLI arguments (e.g. ['status', 'my-app']).
+ */
+export declare function handleStatusCommand(storage: Storage, positionalArgs: string[]): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.d.ts

@@ -0,0 +1,9 @@
+import type { Storage } from '../../server/index.js';
+/**
+ * Handles the 'status' command to display storage backend statistics.
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param positionalArgs - Positional CLI arguments (e.g. ['status', 'my-app']).
+ */
+export declare function handleStatusCommand(storage: Storage, positionalArgs: string[]): Promise<void>;
+//# sourceMappingURL=status.d.ts.map

package/dist/cli/commands/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/cli/commands/tables.d.cts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.cjs';
+/**
+ * Handles the 'tables' command family (list, add, rm, <appid>).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, appId, ...tableNames]`.
+ */
+export declare function handleTablesCommand(storage: Storage, args: string[]): Promise<void>;
+//# sourceMappingURL=tables.d.ts.map

package/dist/cli/commands/tables.d.ts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.js';
+/**
+ * Handles the 'tables' command family (list, add, rm, <appid>).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, appId, ...tableNames]`.
+ */
+export declare function handleTablesCommand(storage: Storage, args: string[]): Promise<void>;
+//# sourceMappingURL=tables.d.ts.map

package/dist/cli/commands/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/tables.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGb,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAuEf"}

package/dist/cli/commands/users.d.cts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.cjs';
+/**
+ * Handles the 'users' command family (list, add, rm).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, arg1, arg2]`.
+ */
+export declare function handleUsersCommand(storage: Storage, [, action, arg1, arg2]: string[]): Promise<void>;
+//# sourceMappingURL=users.d.ts.map

package/dist/cli/commands/users.d.ts

@@ -0,0 +1,9 @@
+import { type Storage } from '../../server/index.js';
+/**
+ * Handles the 'users' command family (list, add, rm).
+ *
+ * @param storage - Instantiated Storage engine.
+ * @param args - Positional arguments: `[command, action, arg1, arg2]`.
+ */
+export declare function handleUsersCommand(storage: Storage, [, action, arg1, arg2]: string[]): Promise<void>;
+//# sourceMappingURL=users.d.ts.map

package/dist/cli/commands/users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/users.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAGb,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,CAAC,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GACxC,OAAO,CAAC,IAAI,CAAC,CA0Cf"}