@groundstate/server

SQLite-backed server for @groundstate with built-in sync relay and HTTP middleware.

Installation

# npm
npm install @groundstate/server

# yarn
yarn add @groundstate/server

# pnpm
pnpm add @groundstate/server

Quick Start

import { groundstateServer, DocumentDatabase } from '@groundstate/server';
import express from 'express';

const app = express();

// Attach Groundstate middleware (handles sync, REST, and WebSocket upgrade)
app.use('/api', groundstateServer({
  database: new DocumentDatabase('./data/groundstate.db'),
  auth: async (req) => {
    // Return a user object or null to reject
    return verifyToken(req.headers.authorization);
  },
}));

app.listen(3000, () => {
  console.log('Groundstate server listening on :3000');
});

API Highlights

Middleware

• groundstateServer(options) -- Express/Connect-compatible middleware that handles:
  • WebSocket upgrade for real-time sync
  • REST endpoints for document CRUD
  • Authentication and authorization hooks
• ServerOptions -- Configuration type for database path, auth, CORS, and more

Database

• DocumentDatabase -- SQLite-backed document store with built-in CRDT merge support
  • Stores full operation history for any connected client to catch up
  • Supports compaction to reclaim disk space
  • Handles concurrent writes safely

Integration

The server works with any @groundstate/sync transport on the client side:

// Client
import { SyncEngine, WebSocketTransport } from '@groundstate/sync';
const engine = new SyncEngine(doc, new WebSocketTransport('ws://localhost:3000/api'));

Documentation

See the full documentation for complete API reference.

License

MIT