spacewave 0.0.0 → 0.57.6

package/dist/types/sdk/sync/client.d.ts

@@ -0,0 +1,37 @@
+import { type CollectionAccess, type DatabaseAccess } from './access.js';
+import { SyncError } from './errors.js';
+import type { CallOptions, Output, Query, RecordEntry, Schema, Validator } from './schema.js';
+export interface ConnectionState {
+    readonly status: 'ready' | 'reconnecting' | 'closed';
+    readonly error?: SyncError;
+}
+export interface SubscriptionState<T> {
+    readonly status: 'loading' | 'current' | 'stale' | 'error';
+    readonly data: readonly RecordEntry<T>[];
+    readonly error?: SyncError;
+}
+export interface Observer<T> {
+    next(state: SubscriptionState<T>): void | Promise<void>;
+    error?(error: SyncError): void;
+}
+export interface Collection<V extends Validator> extends CollectionAccess<V> {
+    watch(query?: Query, options?: CallOptions): AsyncIterable<SubscriptionState<Output<V>>>;
+    subscribe(query: Query, observer: Observer<Output<V>>, options?: CallOptions): () => void;
+}
+export interface ConnectionStatus {
+    readonly current: ConnectionState;
+    subscribe(listener: (state: ConnectionState) => void): () => void;
+}
+export interface Database<S extends Schema> extends DatabaseAccess<S>, AsyncDisposable {
+    readonly connection: ConnectionStatus;
+    collection<K extends keyof S['collections'] & string>(name: K): Collection<S['collections'][K]>;
+    close(): Promise<void>;
+}
+export interface ConnectOptions<S extends Schema> {
+    url: string;
+    schema: S;
+    getAccessToken(signal: AbortSignal): string | Promise<string>;
+    signal?: AbortSignal;
+    requestTimeoutMs?: number;
+}
+export declare function connect<S extends Schema>(options: ConnectOptions<S>): Promise<Database<S>>;

package/dist/types/sdk/sync/errors.d.ts

@@ -0,0 +1,12 @@
+export type SyncErrorCode = 'VALIDATION' | 'AUTHENTICATION' | 'DENIED' | 'MISSING_COLLECTION' | 'SCHEMA_MISMATCH' | 'QUERY_LIMIT' | 'CONFLICT' | 'UNAVAILABLE' | 'UNCERTAIN' | 'STORAGE' | 'CLOSED';
+declare const errorBrand: unique symbol;
+export declare class SyncError extends Error {
+    readonly code: SyncErrorCode;
+    readonly requestId?: string | undefined;
+    readonly name = "SyncError";
+    private readonly [errorBrand];
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(code: SyncErrorCode, message: string, requestId?: string | undefined);
+}
+export declare function publicError(error: unknown): SyncError;
+export {};

package/dist/types/sdk/sync/json.d.ts

@@ -0,0 +1,30 @@
+/**
+ * JsonValue is the JSON data model accepted by the sync library.
+ * Values are null, booleans, finite numbers, strings, arrays, and plain
+ * objects (Object.prototype or null prototype). Null is distinct from an
+ * absent record; the service handles that distinction separately.
+ */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * CanonicalJSON returns the deterministic compact JSON form of value.
+ * Object keys sort lexically by code unit. Accepts only JsonValue shapes:
+ * rejects undefined (including properties and array holes), bigint, symbols,
+ * functions, non-finite numbers, cycles, class instances, accessor
+ * properties, enumerable symbol keys, and extra enumerable array properties.
+ * Repeated references without a cycle are allowed. Never calls toJSON or
+ * getters. Throws TypeError with a field path and reason, never the value.
+ */
+export declare function canonicalJSON(value: unknown): string;
+/**
+ * EncodeJSON returns canonicalJSON(value) as strict UTF-8 bytes.
+ * See canonicalJSON for the value contract.
+ */
+export declare function encodeJSON(value: unknown): Uint8Array;
+/**
+ * DecodeJSON parses strict UTF-8 data as JSON and validates it as JsonValue.
+ * Throws TypeError when the data is not valid UTF-8, not valid JSON, or not
+ * a JsonValue (for example a non-finite number from a large exponent).
+ */
+export declare function decodeJSON(data: Uint8Array): JsonValue;

package/dist/types/sdk/sync/operation.d.ts

@@ -0,0 +1,23 @@
+import type { JsonValue } from './json.js';
+export type Operation = {
+    kind: 'get';
+    collection: string;
+    key: string;
+} | {
+    kind: 'scan';
+    collection: string;
+    prefix: string;
+} | {
+    kind: 'put';
+    collection: string;
+    key: string;
+    value: JsonValue;
+} | {
+    kind: 'delete';
+    collection: string;
+    key: string;
+} | {
+    kind: 'mutate';
+    name: string;
+    input: JsonValue;
+};

package/dist/types/sdk/sync/schema.d.ts

@@ -0,0 +1,51 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { type JsonValue } from './json.js';
+export type Validator = StandardSchemaV1;
+export type Input<S extends Validator> = StandardSchemaV1.InferInput<S>;
+export type Output<S extends Validator> = StandardSchemaV1.InferOutput<S>;
+export interface MutationDefinition {
+    readonly input: Validator;
+    readonly output: Validator;
+}
+export interface Schema {
+    readonly id: string;
+    readonly version: number;
+    readonly collections: Readonly<Record<string, Validator>>;
+    readonly mutations: Readonly<Record<string, MutationDefinition>>;
+}
+export declare function defineSchema<const S extends Schema>(schema: S): S;
+export declare function validate<V extends Validator>(validator: V, value: unknown, field: string): Promise<Output<V> & JsonValue>;
+export interface CallOptions {
+    readonly signal?: AbortSignal;
+    readonly requestId?: string;
+}
+export interface RecordEntry<T> {
+    readonly key: string;
+    readonly value: T;
+}
+export interface Query {
+    readonly prefix?: string;
+}
+export interface TransactionCollection<V extends Validator> {
+    get(key: string): Promise<Output<V> | undefined>;
+    scan(query?: Query): Promise<readonly RecordEntry<Output<V>>[]>;
+    put(key: string, value: Input<V>): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface Transaction<S extends Schema> {
+    collection<K extends keyof S['collections'] & string>(name: K): TransactionCollection<S['collections'][K]>;
+}
+export interface Principal {
+    readonly subject: string;
+    readonly scope: string;
+    readonly expiresAt?: number;
+    readonly signal?: AbortSignal;
+}
+export interface MutationContext<S extends Schema, P extends Principal> extends Transaction<S> {
+    readonly principal: P;
+    readonly scope: string;
+    readonly signal: AbortSignal;
+}
+export type MutationHandlers<S extends Schema, P extends Principal> = {
+    [K in keyof S['mutations']]: (context: MutationContext<S, P>, input: Output<S['mutations'][K]['input']>) => Promise<Input<S['mutations'][K]['output']>>;
+};

package/dist/types/web/sync/index.d.ts

@@ -0,0 +1,4 @@
+export { createSyncContext } from './react.js';
+export type { Database, SubscriptionState } from '../../sdk/sync/client.js';
+export type { Output, Query, Schema } from '../../sdk/sync/schema.js';
+export { SyncError } from '../../sdk/sync/errors.js';

package/dist/types/web/sync/react.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import type { Database, SubscriptionState } from '../../sdk/sync/client.js';
+import type { Output, Query, Schema } from '../../sdk/sync/schema.js';
+export declare function createSyncContext<S extends Schema>(_schema: S): {
+    SyncProvider: ({ db, children, }: {
+        db: Database<S>;
+        children: ReactNode;
+    }) => import("react").JSX.Element;
+    useDatabase: () => Database<S>;
+    useCollection: <K extends keyof S['collections'] & string>(name: K, query?: Query) => SubscriptionState<Output<S['collections'][K]>>;
+};

package/examples/task-board/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "spacewave-task-board",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24.15.0 <25"
+  },
+  "scripts": {
+    "start": "node server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "spacewave": "0.57.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "esbuild": "^0.27.0",
+    "typescript": "^7.0.2"
+  }
+}

package/examples/task-board/react.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Task board · Spacewave React</title>
+    <link rel="stylesheet" href="/style.css" />
+  </head>
+
+  <body>
+    <main id="app">
+      <p role="status">Connecting…</p>
+    </main>
+
+    <script type="module" src="/react.js"></script>
+  </body>
+</html>

package/examples/task-board/react.tsx

@@ -0,0 +1,235 @@
+import {
+  useCallback,
+  useState,
+  useSyncExternalStore,
+  type FormEvent,
+} from 'react'
+import { createRoot } from 'react-dom/client'
+import { connect, SyncError, type ConnectionState } from 'spacewave'
+import { createSyncContext } from 'spacewave/react'
+
+import { schema } from './schema.ts'
+
+const { SyncProvider, useDatabase, useCollection } = createSyncContext(schema)
+
+/** UncertainWrite retains the original input and request ID for an explicit retry. */
+interface UncertainWrite {
+  requestId: string
+  message: string
+  retry: () => void
+}
+
+const connectionLabels: Record<ConnectionState['status'], string> = {
+  ready: 'Connected',
+  reconnecting: 'Reconnecting…',
+  closed: 'Disconnected',
+}
+
+/** TaskBoard renders accepted tasks and keeps pending form input separate. */
+function TaskBoard() {
+  // Read task and connection state from the database's existing subscriptions.
+  const db = useDatabase()
+  const todos = useCollection('todos')
+  const connection = useSyncExternalStore(
+    db.connection.subscribe,
+    () => db.connection.current,
+    () => db.connection.current,
+  )
+
+  // Keep editable input and unresolved writes outside the accepted task snapshot.
+  const [title, setTitle] = useState('')
+  const [pending, setPending] = useState(false)
+  const [uncertain, setUncertain] = useState<UncertainWrite | null>(null)
+  const [writeError, setWriteError] = useState<string | null>(null)
+
+  /** runWrite exposes an uncertain write's original operation for a later retry. */
+  const runWrite = useCallback(
+    async (run: () => Promise<unknown>, requestId: string): Promise<void> => {
+      // Suspend new edits and clear the previous write's feedback.
+      setPending(true)
+      setUncertain(null)
+      setWriteError(null)
+
+      // Keep failed writes recoverable without inserting unaccepted task rows.
+      try {
+        await run()
+      } catch (error) {
+        if (error instanceof SyncError && error.code === 'UNCERTAIN') {
+          setUncertain({
+            requestId,
+            message: error.message,
+            retry: () => {
+              void runWrite(run, requestId)
+            },
+          })
+        } else {
+          setWriteError(error instanceof Error ? error.message : String(error))
+        }
+      } finally {
+        setPending(false)
+      }
+    },
+    [],
+  )
+
+  /** addTask preserves the title and generated IDs until the write is accepted. */
+  const addTask = (event: FormEvent<HTMLFormElement>) => {
+    // Accept a nonempty title only while connected and ready for another write.
+    event.preventDefault()
+    const trimmed = title.trim()
+    if (!trimmed || pending || connection.status !== 'ready') return
+
+    // Capture the write once so Retry submits the same input with the same ID.
+    const id = crypto.randomUUID()
+    const requestId = crypto.randomUUID()
+    void runWrite(async () => {
+      await db
+        .collection('todos')
+        .put(id, { title: trimmed, done: false }, { requestId })
+      setTitle('')
+    }, requestId)
+  }
+
+  /** completeTask invokes the server mutation with a recoverable request ID. */
+  const completeTask = (id: string) => {
+    const requestId = crypto.randomUUID()
+    void runWrite(
+      () => db.mutate('completeTodo', { id }, { requestId }),
+      requestId,
+    )
+  }
+
+  // Describe the snapshot's freshness without treating stale data as current.
+  const todosStatus =
+    todos.status === 'loading'
+      ? 'Loading tasks…'
+      : todos.status === 'current'
+        ? `Live · ${todos.data.length} ${
+            todos.data.length === 1 ? 'task' : 'tasks'
+          }`
+        : 'Showing the last saved view while reconnecting…'
+
+  // Render connection feedback, write controls, and the accepted task list.
+  return (
+    <>
+      <h1>Task board</h1>
+      <p>
+        Two tabs share one server: the <a href="/">Vanilla</a> example and this{' '}
+        <a href="/react">React</a> example.
+      </p>
+
+      <p className="status">
+        {`Connection: ${connectionLabels[connection.status]}`}
+        {connection.error ? `: ${connection.error.message}` : ''}
+      </p>
+      {todos.status === 'error' && todos.error ? (
+        <p className="notice" role="alert">
+          {todos.error.message}
+        </p>
+      ) : (
+        <p className="status">{todosStatus}</p>
+      )}
+
+      <form onSubmit={addTask}>
+        <label htmlFor="new-task">
+          Add a task
+          <input
+            id="new-task"
+            value={title}
+            onChange={(event) => setTitle(event.target.value)}
+            disabled={pending}
+            required
+            maxLength={120}
+          />
+        </label>
+        <button
+          className="button"
+          type="submit"
+          disabled={pending || connection.status !== 'ready' || !title.trim()}
+        >
+          Add task
+        </button>
+      </form>
+
+      {writeError ? <p className="notice">{writeError}</p> : null}
+      {uncertain ? (
+        <p className="notice">
+          {uncertain.message} The write may not have been accepted (request{' '}
+          {uncertain.requestId}).{' '}
+          <button
+            className="button"
+            type="button"
+            disabled={pending || connection.status !== 'ready'}
+            onClick={uncertain.retry}
+          >
+            Retry
+          </button>
+        </p>
+      ) : null}
+
+      <ul className="tasks">
+        {todos.data.map((entry) => (
+          <li className="task" key={entry.key} data-done={entry.value.done}>
+            <span>{entry.value.title}</span>{' '}
+            <button
+              className="button"
+              type="button"
+              disabled={
+                pending || connection.status !== 'ready' || entry.value.done
+              }
+              onClick={() => completeTask(entry.key)}
+            >
+              {entry.value.done ? 'Completed' : 'Complete'}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </>
+  )
+}
+
+/** start connects the board and releases its React tree and database on pagehide. */
+async function start(): Promise<void> {
+  // Require the page's mount point before opening a connection.
+  const container = document.getElementById('app')
+  if (!container) throw new Error('Missing #app mount point')
+
+  // Connect to the sync endpoint served alongside this page.
+  const url = `${location.protocol === 'https:' ? 'wss' : 'ws'}://${
+    location.host
+  }/sync`
+  const db = await connect({
+    url,
+    schema,
+    getAccessToken: () => 'local-demo',
+  })
+
+  // Supply the admitted database to every task-board component.
+  const root = createRoot(container)
+  root.render(
+    <SyncProvider db={db}>
+      <TaskBoard />
+    </SyncProvider>,
+  )
+
+  // Unmount subscriptions before closing the database they use.
+  window.addEventListener(
+    'pagehide',
+    () => {
+      root.unmount()
+      void db.close()
+    },
+    { once: true },
+  )
+}
+
+// Replace the loading view with a readable failure if startup cannot finish.
+start().catch((error: unknown) => {
+  const container = document.getElementById('app') ?? document.body
+  const notice = document.createElement('p')
+  notice.className = 'notice'
+  notice.textContent = `Task board failed to start: ${
+    error instanceof Error ? error.message : String(error)
+  }`
+  container.replaceChildren(notice)
+})

package/examples/task-board/schema.ts

@@ -0,0 +1,21 @@
+import { defineSchema } from 'spacewave'
+import { z } from 'zod'
+
+/** todo validates stored tasks and the result of completing a task. */
+const todo = z.object({
+  title: z.string().min(1).max(120),
+  done: z.boolean(),
+})
+
+/** schema is the shared contract for the server, vanilla client, and React client. */
+export const schema = defineSchema({
+  id: 'task-board',
+  version: 1,
+  collections: { todos: todo },
+  mutations: {
+    completeTodo: {
+      input: z.object({ id: z.string().min(1) }),
+      output: todo,
+    },
+  },
+})

package/examples/task-board/server.ts

@@ -0,0 +1,133 @@
+import { readFile } from 'node:fs/promises'
+import { createServer as createHTTPServer } from 'node:http'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build } from 'esbuild'
+import { SyncError } from 'spacewave'
+import { createServer } from 'spacewave/server'
+
+import { schema } from './schema.ts'
+
+// Build both browser entry points before accepting page requests.
+const directory = dirname(fileURLToPath(import.meta.url))
+await build({
+  absWorkingDir: directory,
+  entryPoints: ['vanilla.ts', 'react.tsx'],
+  outdir: 'public',
+  bundle: true,
+  format: 'esm',
+  platform: 'browser',
+  target: 'es2024',
+  define: { 'process.env.NODE_ENV': '"production"' },
+})
+
+// Open the persistent task dataset and admit only the local demo identity.
+const server = await createServer({
+  directory: process.env.DATA_DIRECTORY ?? join(directory, '.data'),
+  schema,
+
+  // Replace this verifier with the application's real authentication provider.
+  authenticate: async (token) => {
+    if (token !== 'local-demo') {
+      throw new SyncError('AUTHENTICATION', 'Sign in again')
+    }
+    return { subject: 'demo-user', scope: 'demo' }
+  },
+  authorize: ({ scope }) => scope === 'demo',
+
+  // Mutations read and write through one server transaction.
+  mutations: {
+    completeTodo: async (context, { id }) => {
+      // Read the task before changing its completion state.
+      const todos = context.collection('todos')
+      const todo = await todos.get(id)
+      if (!todo) {
+        throw new SyncError('VALIDATION', 'This task no longer exists')
+      }
+
+      // Update the task within this transaction and return its value.
+      const updated = { ...todo, done: true }
+      await todos.put(id, updated)
+      return updated
+    },
+  },
+})
+
+// Seed the board through the same authorized collection API used by clients.
+const tasks = server
+  .as({ subject: 'demo-user', scope: 'demo' })
+  .collection('todos')
+if (!(await tasks.get('welcome'))) {
+  await tasks.put('welcome', {
+    title: 'Open this board in two tabs',
+    done: false,
+  })
+}
+
+// Serve only the example's page, bundle, and stylesheet routes.
+const files = new Map([
+  ['/', ['vanilla.html', 'text/html']],
+  ['/react', ['react.html', 'text/html']],
+  ['/vanilla.js', ['public/vanilla.js', 'text/javascript']],
+  ['/react.js', ['public/react.js', 'text/javascript']],
+  ['/style.css', ['style.css', 'text/css']],
+])
+const http = createHTTPServer((request, response) => {
+  // Resolve the request through the fixed route map.
+  const path = new URL(request.url ?? '/', 'http://localhost').pathname
+  const file = files.get(path)
+  if (!file) {
+    response.writeHead(404)
+    response.end()
+    return
+  }
+
+  // Send the matching asset or report a read failure.
+  const [filename, contentType] = file
+  void readFile(join(directory, filename)).then(
+    (data) => {
+      response.setHeader('Content-Type', contentType)
+      response.end(data)
+    },
+    () => {
+      response.writeHead(500)
+      response.end('The page could not load')
+    },
+  )
+})
+
+// Share the HTTP listener between pages and the sync endpoint.
+server.attach(http)
+const port = Number(process.env.PORT ?? 8787)
+await new Promise<void>((resolve, reject) => {
+  http.once('error', reject)
+  http.listen(port, '127.0.0.1', resolve)
+})
+const address = http.address()
+if (address && typeof address !== 'string') {
+  console.log(`Task board: http://127.0.0.1:${address.port}`)
+}
+
+// Repeated shutdown signals share one close operation.
+let closing: Promise<void> | undefined
+
+/** close releases sync connections and storage, then the HTTP server we supplied. */
+function close(): Promise<void> {
+  closing ??= (async () => {
+    await server.close()
+    await new Promise<void>((resolve, reject) =>
+      http.close((error) => (error ? reject(error) : resolve())),
+    )
+  })()
+  return closing
+}
+
+// Let both normal interruption and service termination finish cleanup.
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(signal, () => {
+    void close().catch((error: unknown) => {
+      console.error(error)
+      process.exitCode = 1
+    })
+  })
+}