meridian-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,658 @@
+import { ClientMessage, ServerMessage, SchemaDefinition, ConflictRecord, PermissionRules, CRDTOperation, ServerChange, StorageAdapterConfig, ConflictInfo } from 'meridian-shared';
+export { CRDTOperation, ConflictRecord, SchemaDefinition, ServerChange, defineSchema, z } from 'meridian-shared';
+import { WebSocket } from 'ws';
+
+/**
+ * Meridian Server — WebSocket Hub
+ *
+ * Manages WebSocket connections with:
+ * - Client authentication (pluggable JWT verifier)
+ * - Namespace isolation (multi-tenant)
+ * - Message routing (push/pull/subscribe/presence)
+ * - Heartbeat/ping-pong health checks
+ * - Auth token expiry tracking and refresh notifications
+ */
+
+interface AuthResult {
+    userId: string;
+    namespace?: string;
+    expiresAt?: number;
+}
+interface WsHubConfig {
+    /** Port to listen on */
+    port: number;
+    /** Path for WebSocket endpoint */
+    path?: string;
+    /** Auth verifier — return user info or throw to reject */
+    auth?: (token: string) => Promise<AuthResult>;
+    /** Message handler */
+    onMessage: (clientId: string, message: ClientMessage, client: ConnectedClient) => void;
+    /** Disconnect handler */
+    onDisconnect?: (clientId: string) => void;
+    /** Subscribe handler — called when client subscribes with optional filter */
+    onSubscribe?: (clientId: string, collections: string[], filter?: Record<string, Record<string, unknown>>) => void;
+    /** Debug mode */
+    debug?: boolean;
+}
+interface ConnectedClient {
+    id: string;
+    ws: WebSocket;
+    userId: string | null;
+    namespace: string | null;
+    subscribedCollections: Set<string>;
+    authExpiresAt: number | null;
+    lastActivity: number;
+}
+/**
+ * WebSocket connection hub for Meridian server.
+ */
+declare class WsHub {
+    private wss;
+    private readonly config;
+    private clients;
+    private heartbeatInterval;
+    private authCheckInterval;
+    constructor(config: WsHubConfig);
+    /**
+     * Start the WebSocket server.
+     */
+    start(): void;
+    /**
+     * Stop the WebSocket server.
+     */
+    stop(): void;
+    private handleConnection;
+    private handleClientMessage;
+    /**
+     * Send a message to a specific client.
+     */
+    sendTo(client: ConnectedClient, msg: ServerMessage): void;
+    /**
+     * Send a message to a client by ID.
+     */
+    sendToId(clientId: string, msg: ServerMessage): void;
+    /**
+     * Broadcast a message to all clients subscribed to a collection.
+     * Excludes the sender.
+     */
+    broadcastToCollection(collection: string, msg: ServerMessage, excludeClientId?: string, namespace?: string | null): void;
+    /**
+     * Broadcast a message to all connected clients.
+     */
+    broadcastToAll(msg: ServerMessage, namespace?: string | null): void;
+    /**
+     * Get all connected client IDs.
+     */
+    getClientIds(): string[];
+    /**
+     * Get a connected client by ID.
+     */
+    getClient(clientId: string): ConnectedClient | undefined;
+    private startHeartbeat;
+    private startAuthCheck;
+    private log;
+}
+
+/**
+ * Meridian Server — Main Entry Point
+ *
+ * `createServer()` wires together all server components:
+ * - PostgreSQL store (auto-DDL, CRDT merge)
+ * - WebSocket hub (auth, connections)
+ * - Merge engine (push/pull processing)
+ * - Presence manager
+ * - Compaction scheduler
+ *
+ * Usage:
+ * ```ts
+ * import { createServer } from 'meridian-server';
+ * import { defineSchema, z } from 'meridian-shared';
+ *
+ * const schema = defineSchema({
+ *   version: 1,
+ *   collections: {
+ *     todos: { id: z.string(), title: z.string(), done: z.boolean() },
+ *   },
+ * });
+ *
+ * const server = createServer({
+ *   port: 3000,
+ *   database: 'postgresql://user:pass@localhost:5432/mydb',
+ *   schema,
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+
+interface MeridianServerConfig {
+    /** Port for WebSocket server */
+    port: number;
+    /** PostgreSQL connection string */
+    database: string;
+    /** Schema definition (same as client) */
+    schema: SchemaDefinition;
+    /** WebSocket path (default: '/sync') */
+    path?: string;
+    /**
+     * Authentication handler.
+     * Called with the token from client's auth message.
+     * Return user info or throw to reject.
+     */
+    auth?: (token: string) => Promise<AuthResult>;
+    /**
+     * Compaction settings for tombstone cleanup.
+     */
+    compaction?: {
+        /** Max age for tombstones in ms (default: 30 days) */
+        tombstoneMaxAge?: number;
+        /** Compaction interval in ms (default: 24 hours) */
+        interval?: number;
+    };
+    /**
+     * Conflict handler — called when a field-level conflict is resolved.
+     * Use this to implement custom merge logic for specific collections or fields.
+     */
+    onConflict?: (conflict: ConflictRecord & {
+        collection: string;
+        docId: string;
+    }) => void;
+    /**
+     * Permission rules for row-level access control.
+     * When provided, only rows the user is authorized to read are returned.
+     *
+     * ```ts
+     * permissions: defineRules({
+     *   todos: {
+     *     read: (auth, doc) => auth?.userId === doc.existing?.ownerId,
+     *     write: (auth, doc) => auth != null,
+     *   }
+     * })
+     * ```
+     */
+    permissions?: PermissionRules;
+    /**
+     * Enable debug logging.
+     * @default false
+     */
+    debug?: boolean;
+}
+interface MeridianServer {
+    /** Start the server */
+    start(): Promise<void>;
+    /** Stop the server gracefully */
+    stop(): Promise<void>;
+    /** Run compaction manually */
+    compact(): Promise<number>;
+    /** Get connected client count */
+    getClientCount(): number;
+}
+/**
+ * Create a Meridian sync server.
+ */
+declare function createServer(config: MeridianServerConfig): MeridianServer;
+
+/**
+ * Meridian Server — PostgreSQL Store
+ *
+ * Handles:
+ * - Auto-creation of tables from client schema
+ * - CRDT metadata storage via _meridian_meta JSONB column
+ * - Server-assigned monotonic sequence numbers
+ * - LISTEN/NOTIFY for change detection
+ * - Tombstone compaction
+ * - Changes-since queries for pull protocol
+ */
+
+interface PgStoreConfig {
+    /** PostgreSQL connection string */
+    connectionString: string;
+    /** Schema definition */
+    schema: SchemaDefinition;
+    /** Optional namespace prefix for multi-tenant isolation */
+    namespace?: string;
+}
+/**
+ * PostgreSQL storage adapter for Meridian server.
+ */
+declare class PgStore {
+    private pool;
+    private readonly config;
+    private changeCallbacks;
+    private listenClient;
+    private minSeq;
+    constructor(config: PgStoreConfig);
+    /**
+     * Initialize the database — create tables, sequences, triggers.
+     */
+    init(): Promise<void>;
+    /**
+     * Get the table name with optional namespace prefix.
+     */
+    private tableName;
+    /**
+     * Create a table for a collection with Meridian system columns.
+     */
+    private createTable;
+    /**
+     * Apply CRDT operations from a client.
+     * Performs field-level LWW merge with existing data.
+     * @returns Array of server changes with assigned sequence numbers and any conflicts
+     */
+    applyOperations(ops: CRDTOperation[]): Promise<{
+        changes: ServerChange[];
+        conflicts: ConflictRecord[];
+    }>;
+    /**
+     * Get all changes since a given sequence number.
+     * Used for pull protocol.
+     *
+     * @returns null if seqNum is below minSeq (compaction gap), otherwise changes
+     */
+    getChangesSince(since: number): Promise<ServerChange[] | null>;
+    /**
+     * Get the current minimum available sequence number.
+     */
+    getMinSeq(): number;
+    /**
+     * Delete tombstoned rows older than maxAge.
+     * @returns Number of rows deleted
+     */
+    compact(maxAgeMs: number): Promise<number>;
+    private updateMinSeqWithClient;
+    private updateMinSeq;
+    private startListening;
+    /**
+     * Register a callback for database changes.
+     */
+    onChange(callback: (tableName: string, docId: string) => void): () => void;
+    /**
+     * Close the database connection pool.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Meridian Server — CRDT Merge Engine
+ *
+ * Handles server-side merge logic:
+ * - Receives client operations
+ * - Merges with existing PostgreSQL state
+ * - Assigns sequence numbers
+ * - Broadcasts results to other clients
+ * - Logs conflicts for debugging
+ */
+
+interface MergeEngineConfig {
+    pgStore: PgStore;
+    wsHub: WsHub;
+    debug?: boolean;
+    /** Custom conflict handler — devs define their own merge logic */
+    onConflict?: (conflict: ConflictRecord & {
+        collection: string;
+        docId: string;
+    }) => void;
+    /** Permission rules for row-level access control */
+    permissions?: PermissionRules;
+}
+/**
+ * Server-side CRDT merge engine with partial sync and row-level permissions.
+ */
+declare class MergeEngine {
+    private readonly config;
+    private conflictLog;
+    private readonly maxConflictLog;
+    /** Per-client subscribe filters: clientId → collection → filter */
+    private clientFilters;
+    private ruleEvaluator;
+    constructor(config: MergeEngineConfig);
+    /** Store a client's subscribe filter for partial sync */
+    setClientFilter(clientId: string, collections: string[], filter?: Record<string, Record<string, unknown>>): void;
+    /** Remove client filters on disconnect */
+    removeClientFilter(clientId: string): void;
+    /**
+     * Process a push from a client.
+     * Merges operations with existing state, assigns seqNums, and broadcasts.
+     *
+     * @param clientId - The sending client's ID
+     * @param ops - CRDT operations from the client
+     * @param client - The connected client object
+     */
+    processPush(clientId: string, ops: CRDTOperation[], client: ConnectedClient): Promise<void>;
+    /**
+     * Process a pull request from a client.
+     * Returns changes since the given sequence number.
+     */
+    processPull(clientId: string, since: number, client: ConnectedClient): Promise<void>;
+    /**
+     * Get the conflict log.
+     */
+    getConflictLog(): (ConflictRecord & {
+        collection: string;
+        docId: string;
+        timestamp: number;
+    })[];
+    private log;
+}
+
+/**
+ * Meridian Server — Presence Manager (Server-side)
+ *
+ * In-memory presence state for connected clients.
+ * - Stores presence data per client
+ * - Broadcasts updates to all peers
+ * - Auto-cleanup on disconnect (no TTL needed — instant)
+ */
+
+type PresenceData = Record<string, unknown>;
+declare class ServerPresenceManager {
+    private presence;
+    private wsHub;
+    private debug;
+    constructor(wsHub: WsHub, debug?: boolean);
+    /**
+     * Update presence for a client and broadcast to peers.
+     */
+    update(clientId: string, data: PresenceData, client: ConnectedClient): void;
+    /**
+     * Remove presence for a disconnected client.
+     */
+    remove(clientId: string): void;
+    /**
+     * Get all current presence data.
+     */
+    getAll(): Record<string, PresenceData>;
+    /**
+     * Send current presence state to a specific client (e.g., on reconnect).
+     */
+    sendCurrentState(client: ConnectedClient): void;
+    private broadcastAll;
+    /**
+     * Clear all presence data.
+     */
+    clear(): void;
+}
+
+/**
+ * Meridian Server — Tombstone Compaction
+ *
+ * Periodically removes soft-deleted rows older than a configurable max age.
+ * After compaction, notifies connected clients so they can clean up local data.
+ */
+
+interface CompactionConfig {
+    /** Maximum age for tombstones in ms (default: 30 days) */
+    tombstoneMaxAge: number;
+    /** Compaction check interval in ms (default: 24 hours) */
+    interval: number;
+    /** Debug mode */
+    debug?: boolean;
+}
+/**
+ * Tombstone compaction scheduler.
+ */
+declare class CompactionManager {
+    private readonly pgStore;
+    private readonly wsHub;
+    private readonly config;
+    private timer;
+    constructor(pgStore: PgStore, wsHub: WsHub, config?: Partial<CompactionConfig>);
+    /**
+     * Start the compaction scheduler.
+     */
+    start(): void;
+    /**
+     * Stop the compaction scheduler.
+     */
+    stop(): void;
+    /**
+     * Run compaction now.
+     */
+    runCompaction(): Promise<number>;
+    private log;
+}
+
+/**
+ * Meridian — WAL Streaming (PostgreSQL Logical Replication)
+ *
+ * Production-grade change streaming using PostgreSQL's
+ * LISTEN/NOTIFY + logical replication protocol.
+ *
+ * Two modes:
+ * 1. NOTIFY mode (default) — Fast, simple, uses pg_notify()
+ *    triggers. Good for up to ~10K concurrent clients.
+ * 2. WAL mode — Uses wal2json logical decoding plugin for
+ *    massive scale (100K+ clients). Requires:
+ *    - `wal_level = logical` in postgresql.conf
+ *    - `CREATE EXTENSION wal2json;` (if not already installed)
+ */
+interface WALStreamConfig {
+    /** PostgreSQL connection string */
+    connectionString: string;
+    /** Mode: 'notify' (default) or 'wal' (logical replication) */
+    mode?: 'notify' | 'wal';
+    /** Channel name for NOTIFY mode */
+    channel?: string;
+    /** Publication name for WAL mode */
+    publication?: string;
+    /** Slot name for WAL mode */
+    slot?: string;
+    /** Called for each change received */
+    onChange: (change: WALChange) => void;
+    /** Debug logging */
+    debug?: boolean;
+}
+interface WALChange {
+    collection: string;
+    docId: string;
+    operation: 'INSERT' | 'UPDATE' | 'DELETE';
+    fields?: Record<string, unknown>;
+    seq?: number;
+}
+/**
+ * Create a WAL stream based on the configured mode.
+ *
+ * ```ts
+ * const stream = createWALStream({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   mode: 'notify', // or 'wal'
+ *   onChange: (change) => {
+ *     // Broadcast to WebSocket clients
+ *     wsHub.broadcastToCollection(change.collection, change);
+ *   },
+ *   debug: true,
+ * });
+ * await stream.start();
+ * ```
+ */
+declare function createWALStream(config: WALStreamConfig): {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+};
+
+/**
+ * Meridian — SQLite Storage Adapter
+ *
+ * Implements StorageAdapter for SQLite databases.
+ * Supports:
+ * - better-sqlite3 (Node.js server)
+ * - sql.js (WASM — browser/React Native)
+ * - Turso/libsql (edge/distributed SQLite)
+ *
+ * Usage:
+ * ```ts
+ * const store = new SQLiteStore({
+ *   databasePath: './meridian.db',
+ *   schema,
+ * });
+ * await store.init();
+ * ```
+ */
+
+/**
+ * Minimal SQL driver interface — compatible with better-sqlite3, sql.js, and libsql.
+ */
+interface SQLDriver {
+    exec(sql: string): void;
+    prepare(sql: string): SQLStatement;
+    close(): void;
+}
+interface SQLStatement {
+    run(...params: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: unknown[]): Record<string, unknown> | undefined;
+    all(...params: unknown[]): Record<string, unknown>[];
+}
+interface SQLiteStoreConfig extends StorageAdapterConfig {
+    /** SQL driver instance (better-sqlite3 Database, sql.js Database, etc.) */
+    driver: SQLDriver;
+}
+declare class SQLiteStore {
+    private readonly driver;
+    private readonly config;
+    private lastSeq;
+    private minSeq;
+    constructor(config: SQLiteStoreConfig);
+    init(): Promise<void>;
+    private createTable;
+    applyOperations(ops: CRDTOperation[]): Promise<{
+        changes: ServerChange[];
+        conflicts: ConflictInfo[];
+    }>;
+    getChangesSince(since: number): Promise<ServerChange[] | null>;
+    getMinSeq(): number;
+    compact(maxAgeMs: number): Promise<number>;
+    close(): Promise<void>;
+}
+
+/**
+ * Meridian — MySQL Storage Adapter
+ *
+ * Implements StorageAdapter for MySQL databases.
+ * Uses mysql2 driver for Node.js.
+ *
+ * Usage:
+ * ```ts
+ * import mysql from 'mysql2/promise';
+ * const pool = mysql.createPool('mysql://localhost/meridian');
+ * const store = new MySQLStore({ pool, schema });
+ * await store.init();
+ * ```
+ */
+
+interface MySQLPool {
+    execute(sql: string, params?: unknown[]): Promise<[ResultSetHeader, any]>;
+    query(sql: string, params?: unknown[]): Promise<[RowDataPacket[], any]>;
+    end(): Promise<void>;
+}
+interface ResultSetHeader {
+    insertId: number;
+    affectedRows: number;
+}
+interface RowDataPacket {
+    [key: string]: unknown;
+}
+interface MySQLStoreConfig {
+    pool: MySQLPool;
+    schema: SchemaDefinition;
+    debug?: boolean;
+}
+declare class MySQLStore {
+    private pool;
+    private config;
+    private lastSeq;
+    private minSeq;
+    constructor(config: MySQLStoreConfig);
+    init(): Promise<void>;
+    applyOperations(ops: CRDTOperation[]): Promise<{
+        changes: ServerChange[];
+        conflicts: ConflictInfo[];
+    }>;
+    getChangesSince(since: number): Promise<ServerChange[] | null>;
+    getMinSeq(): number;
+    compact(maxAgeMs: number): Promise<number>;
+    close(): Promise<void>;
+}
+
+/**
+ * Meridian — Snapshot Recovery
+ *
+ * Optimizes full re-sync by creating periodic snapshots of collection state.
+ * Instead of replaying all operations from seq=0, clients can load a snapshot
+ * and only replay operations since the snapshot's sequence number.
+ *
+ * Benefits:
+ * - New clients sync in O(snapshot + delta) instead of O(all_ops)
+ * - Bandwidth reduction for clients that have been offline for days
+ * - Faster recovery after compaction gaps
+ */
+
+interface Snapshot {
+    /** Sequence number this snapshot was taken at */
+    seq: number;
+    /** ISO timestamp of snapshot creation */
+    createdAt: string;
+    /** Collection snapshots */
+    collections: Record<string, CollectionSnapshot>;
+}
+interface CollectionSnapshot {
+    /** Collection name */
+    name: string;
+    /** Number of documents */
+    count: number;
+    /** All non-deleted documents */
+    documents: Record<string, unknown>[];
+}
+interface SnapshotConfig {
+    /** Create a snapshot every N operations */
+    interval: number;
+    /** Maximum number of snapshots to keep */
+    maxSnapshots: number;
+    /** Database (pgStore or mysqlStore) */
+    store: PgStore | {
+        getChangesSince(since: number): Promise<ServerChange[] | null>;
+        getMinSeq(): number;
+    };
+    /** Schema definition */
+    schema: SchemaDefinition;
+    /** Debug logging */
+    debug?: boolean;
+}
+declare class SnapshotManager {
+    private config;
+    private snapshots;
+    private opCounter;
+    constructor(config: SnapshotConfig);
+    /**
+     * Track an operation. Creates a snapshot when the interval is reached.
+     */
+    trackOp(): Promise<void>;
+    /**
+     * Create a snapshot of all collections at the current sequence number.
+     */
+    createSnapshot(): Promise<Snapshot>;
+    /**
+     * Get the most recent snapshot at or before the given sequence number.
+     */
+    getSnapshotForSeq(seq: number): Snapshot | null;
+    /**
+     * Estimate bandwidth savings from using a snapshot vs full replay.
+     *
+     * @param totalOps - Total operations since seq 0
+     * @param snapshotSeq - Sequence number of the snapshot
+     * @returns Percentage of operations saved
+     */
+    estimateSavings(totalOps: number, snapshotSeq: number): number;
+    /**
+     * Get all stored snapshots (for debugging/management).
+     */
+    getSnapshots(): Snapshot[];
+    /**
+     * Clear all snapshots (e.g., after schema change).
+     */
+    clear(): void;
+}
+
+export { type AuthResult, type CollectionSnapshot, type CompactionConfig, CompactionManager, type ConnectedClient, MergeEngine, type MergeEngineConfig, type MeridianServer, type MeridianServerConfig, type MySQLPool, MySQLStore, type MySQLStoreConfig, PgStore, type PgStoreConfig, type SQLDriver, type SQLStatement, SQLiteStore, type SQLiteStoreConfig, ServerPresenceManager, type Snapshot, type SnapshotConfig, SnapshotManager, type WALChange, type WALStreamConfig, WsHub, type WsHubConfig, createServer, createWALStream };