spacewave 0.57.6 → 0.57.8

package/API.md

@@ -3,7 +3,8 @@
 Spacewave provides typed live collections backed by durable storage. An
 application declares a schema of collections and mutations. Clients hold one
 WebSocket connection and read full snapshots that update live. A Node server
-owns storage, authentication, and per-operation authorization.
+stores the data, authenticates each connection, and checks access on every
+operation.
 
 Package entries:
 
@@ -51,6 +52,102 @@ The server validates each write against the validator and stores the
 validator's output form. Reads and watch snapshots return that stored form, so
 client types use `Output<V>`.
 
+## Shared application definitions
+
+`defineApp(schema, handlers)` bundles a schema with the code for its named
+mutations. It does not open storage, so the same definition can serve a Node
+server and a Space plugin. Spread it into `createServer`:
+
+```ts
+import { defineApp } from 'spacewave'
+
+export const app = defineApp(schema, {
+  async completeTodo({ collection }, { id }) {
+    const todos = collection('todos')
+    const todo = await todos.get(id)
+    if (!todo) throw new Error('Todo is unavailable')
+    const completed = { ...todo, done: true }
+    await todos.put(id, completed)
+    return completed
+  },
+})
+
+const server = await createServer({
+  ...app,
+  directory: './data',
+  authenticate,
+  authorize,
+})
+```
+
+The optional `instance` setting in the server configuration picks a dataset
+within the World. It defaults to `schema.id`. Each app instance and authorized
+scope has its own collection records and its own record of accepted requests.
+
+The Space plugin SDK reads the same definition through `definePlugin` and
+`attachApp`. An attachment implements `AppSource`, which offers read-only
+collections, named mutations, and function queries. Mutations run inside the
+World transaction that the host provides. A mutation must be deterministic: it
+may use only its input and that transaction, and it must await every
+collection call before it returns.
+
+Plugin code is trusted. Transaction and data limits and cooperative
+cancellation bound its work, but they are not a sandbox.
+
+### Function queries in a Space or Node host
+
+A function query is a JavaScript function that reads collections and returns a
+value. Declare one with `defineQuery(schema, { name, input, evaluate })`:
+
+```ts
+import { defineQuery } from 'spacewave'
+
+const incomplete = defineQuery(schema, {
+  name: 'incomplete-todos',
+  input: z.null(),
+  async evaluate({ collection }) {
+    return (await collection('todos').scan())
+      .filter(({ value }) => !value.done)
+  },
+})
+
+for await (const snapshot of attachment.watch(incomplete, null, signal)) {
+  if (snapshot.status === 'current') render(snapshot.value)
+}
+```
+
+While the function runs, the runtime records what it read: the records it
+looked up, the records it found missing, the prefixes it scanned, and the
+fields it used. Each result comes from one World snapshot. When the World
+changes, the runtime compares storage roots to skip unchanged data, then checks
+whether any changed record affects what the query read. Only then does it run
+the query again. If the old roots are no longer available, it runs the query
+again in full.
+
+A query function must await every read before it returns. It must not change
+its input or the records it reads, cause outside effects, or depend on the
+clock or random numbers. A query that returns a whole record depends on every
+field of that record.
+
+Identical queries on the same authorized attachment share one evaluation. It
+stops when the last subscriber closes.
+
+On a Node host, `server.as(principal)` implements the same `AppSource`. Call its
+`watch` method with a query definition, or pass it to the React hooks below.
+Each delivery checks collection permissions again. The scoped object starts no
+query work until you read from its iterator. Closing the last iterator releases
+the source, and closing the server stops every active source.
+
+`spacewave/react` exports `useAppQuery(source, query, args)` and
+`useAppMutation(source, name)`. A query reports pending, current, or error. A
+mutation reports idle, pending, accepted, or error, and provides
+`submit(input)` and `retry()`. `retry()` resends the original input with the
+original request ID, so the server applies it at most once. Keep personal
+selection and unsaved drafts in component state.
+
+The WebSocket `Database` client below subscribes to collection prefixes. It
+does not run function queries.
+
 ## Client
 
 ```ts
@@ -64,8 +161,8 @@ const db = await connect({
 ```
 
 `connect(options)` returns `Promise<Database<S>>`. It resolves after
-authentication, the wire and schema version check, and root admission. On
-failure it closes the connection and throws `SyncError`.
+authentication, the wire and schema version check, and the server's acceptance
+of the connection. On failure it closes the connection and throws `SyncError`.
 
 `ConnectOptions<S>`:
 
@@ -87,8 +184,8 @@ failure it closes the connection and throws `SyncError`.
 | `close()` | Idempotent. Also available through `await using` (`AsyncDisposable`). |
 
 `ConnectionState` is `{ status: 'ready' | 'reconnecting' | 'closed', error? }`.
-A new client is `reconnecting` until admission completes, and `closed` after
-`close()`.
+A new client is `reconnecting` until the server accepts the connection, and
+`closed` after `close()`.
 
 One collection exposes:
 
@@ -123,7 +220,7 @@ array of `{ key, value }` entries:
 Each state carries the full snapshot of every record matching the prefix,
 ordered by key. There are no per-row deltas and no per-row filters. The client
 reconnects on its own: a lost connection publishes `stale` and the stream
-resumes with `current` once the server admits the client again. An
+resumes with `current` once the server accepts the connection again. An
 unrecoverable failure publishes `error` and ends the stream.
 
 ```ts
@@ -197,7 +294,7 @@ at compile time. The schema argument carries no runtime state.
 
 | Binding | Contract |
 | --- | --- |
-| `SyncProvider({ db, children })` | Supplies an already-connected `Database<S>`. It never opens, retries, or closes the db; the application owns that lifetime. |
+| `SyncProvider({ db, children })` | Supplies an already-connected `Database<S>`. It never opens, retries, or closes the db; the application does that. |
 | `useDatabase()` | Returns the typed `Database<S>`. Throws when no provider is above in the tree. |
 | `useCollection(name, query?)` | Returns `SubscriptionState<Output>` for the collection. |
 
@@ -256,7 +353,7 @@ const server = await createServer({
 
 `createServer(options)` returns `Promise<SyncServer<S, P>>`. It opens the
 dataset, checks the stored application ID and version, runs any migration, and
-only then returns a server that can admit callers. Failures throw `SyncError`.
+only then returns a server that can accept callers. Failures throw `SyncError`.
 
 `ServerOptions<S, P>`:
 
@@ -268,7 +365,7 @@ only then returns a server that can admit callers. Failures throw `SyncError`.
 | `authorize(access)` | Returns `boolean \| Promise<boolean>`. Called for every operation and again for every watch delivery. |
 | `mutations` | One handler per declared mutation. |
 | `limits?` | `maxRecords` (default 10000), `maxSnapshotBytes` (default 8 MiB), `maxRecordBytes` (default 256 KiB). Exceeding a bound fails that query or write with `QUERY_LIMIT`. |
-| `migration?` | Runs before any caller is admitted when the stored schema version differs. |
+| `migration?` | Runs before the server accepts any caller when the stored schema version differs. |
 
 Storage uses built-in SQLite in a dedicated worker. A directory permits one open server writer at a time.
 
@@ -306,8 +403,8 @@ migration: {
 
 `Migration<S>` is `{ from, run(context) }`. `run` receives `scopes()` listing
 the stored scopes, `scope(name)` returning a transaction for that scope, and
-`signal`. The migration runs inside one maintenance transaction before any
-caller is admitted. If the stored version differs and no matching migration is
+`signal`. The migration runs inside one maintenance transaction before the
+server accepts any caller. If the stored version differs and no matching migration is
 supplied, or the dataset belongs to a different application ID, `createServer`
 fails with `SCHEMA_MISMATCH`.
 
@@ -316,8 +413,8 @@ fails with `SCHEMA_MISMATCH`.
 | Member | Contract |
 | --- | --- |
 | `listen(options?)` | Opens its own HTTP server. `ListenerOptions` adds `port?` (default 8787) and `host?` (default 127.0.0.1). Returns `Listener` with a `ws://` `url` and `close()`. |
-| `attach(http, options?)` | Handles the upgrade event of a supplied HTTP server. Other routes and upgrade paths stay yours. Returns `Attachment` with `close()`. |
-| `as(principal)` | `DatabaseAccess<S>` for direct server-side access as that principal. Every operation still passes `authorize`. |
+| `attach(http, options?)` | Handles the upgrade event of a supplied HTTP server. Your server keeps handling other routes and upgrade paths. Returns `Attachment` with `close()`. |
+| `as(principal)` | `DatabaseAccess<S> & AppSource<S>` for server-side reads, named mutations, and function queries as that principal. Every operation still passes `authorize`. |
 | `admin(scope)` | Privileged access as subject `admin`, with only the base principal fields. Handlers that require application-specific principal fields should use `as(principal)`. Collection authorization is bypassed; validation still applies. |
 | `close()` | Closes every attachment the server created, then the application, then storage the server opened. Idempotent. Also available through `await using`. |
 
@@ -349,7 +446,7 @@ http.listen(3000)
 
 Queries return complete, ordered snapshots of a collection or prefix. Defaults bound a query to 10,000 records and 8 MiB of encoded keys and values, and a record to 256 KiB. Exceeding a bound produces `QUERY_LIMIT`. These are safety bounds, not throughput guarantees.
 
-A qualification workload on Node 24.21.0 and macOS arm64 used 1,000 numeric records, three subscribers, and ten writes. Identical queries shared one producer.
+A qualification workload on Node 24.21.0 and macOS arm64 used 1,000 numeric records, three subscribers, and ten writes. Identical queries shared one evaluation.
 
 | Measurement | Observed sample |
 | --- | --- |
@@ -359,6 +456,6 @@ A qualification workload on Node 24.21.0 and macOS arm64 used 1,000 numeric reco
 | RSS when ready / after the workload | 336 MB / 1.10 GB |
 | Encoded snapshot | 28.9 KB |
 
-Each changed revision still requires a complete scan. RSS includes the compiled runtime and is not a retained-heap measurement. These observations describe one workload; measure representative scan and delivery time, memory, and storage growth before raising limits. Acceptance receipts and World history accumulate for the dataset lifetime.
+In this workload, each changed revision makes a collection-prefix subscription scan its whole collection. A function query first compares storage roots and the fields it read, and runs again only when they changed. RSS includes the compiled runtime and is not a retained-heap measurement. These observations describe one workload; measure representative scan and delivery time, memory, and storage growth before raising limits. Acceptance receipts and World history accumulate for the dataset lifetime.
 
 A qualified release artifact's `qualification.json` records its own sample, source revision, package sizes, and checksum. See the [README](README.md) for supported runtimes and current release scope.

package/CHANGELOG.md

@@ -4,7 +4,7 @@
 
 The first typed sync release candidate provides shared Standard Schema contracts, live ordered collections, named atomic server mutations, scoped authentication and authorization, durable SQLite storage, retained acceptance receipts, reconnect recovery, and optional React bindings.
 
-The package ships ESM client, server, and React exports with public TypeScript declarations and a compiled engine worker. Node 24.15–24.x is required for the server. Complete vanilla TypeScript and React task boards use the same contract and storage.
+The package ships ESM client, server, and React exports with public TypeScript declarations and a compiled engine worker. Node 24.15 to 24.x is required for the server. Complete vanilla TypeScript and React task boards use the same contract and storage.
 
 Subscriptions share a bounded producer for identical scope, collection, and prefix queries. Each subscriber retains its own authorization checks and cancellation lifetime. Query limits fail the affected subscription while independent queries continue.
 

package/README.md

@@ -187,7 +187,7 @@ export function App() {
 }
 ```
 
-`useCollection` cleans up with the component. `useDatabase` gives components the same typed database for writes. The application owns and closes the connection. See the [React task board](examples/task-board/react.tsx) for forms, connection feedback, and write recovery.
+`useCollection` cleans up with the component. `useDatabase` gives components the same typed database for writes. Your application opens and closes the connection. See the [React task board](examples/task-board/react.tsx) for forms, connection feedback, and write recovery.
 
 ### Retry without repeating a change
 
@@ -213,7 +213,7 @@ An accepted duplicate returns the original result, including after a server rest
 
 Adding live data often means writing the same contract in several places: database models, API handlers, client types, subscription messages, and UI state. Every new feature has to keep those pieces in agreement.
 
-Spacewave gives that work a shared starting point. Define collections and mutations once with [Standard Schema](https://standardschema.dev/) validators, such as Zod. The server validates writes, TypeScript infers the client API, and subscriptions deliver accepted state to each view. Your application chooses its authentication provider, access policy, and interface.
+With Spacewave, you write that contract once. Define collections and mutations once with [Standard Schema](https://standardschema.dev/) validators, such as Zod. The server validates writes, TypeScript infers the client API, and subscriptions deliver accepted state to each view. Your application chooses its authentication provider, access policy, and interface.
 
 ## Architecture
 
@@ -224,9 +224,9 @@ flowchart LR
     Server <-->|Transactions| Storage[SQLite-backed World]
 ```
 
-The Node server authenticates connections, selects each caller's scope, and checks collection permissions on operations and subscription deliveries. Accepted writes commit to a Spacewave World, the engine's durable dataset stored in SQLite. Each dataset directory permits one server writer.
+The Node server authenticates connections, selects each caller's scope, and checks collection permissions on operations and subscription deliveries. Accepted writes commit to a Spacewave World, the engine's durable dataset stored in SQLite. Only one server at a time can write to a dataset directory.
 
-Clients receive whole-collection or prefix snapshots with `loading`, `current`, `stale`, or `error` status. Reconnection refreshes subscriptions; durable write receipts support recovery when acceptance is uncertain.
+Clients receive whole-collection or prefix snapshots with `loading`, `current`, `stale`, or `error` status. Reconnecting refreshes each subscription. The server keeps a receipt for every accepted write, so a client that is unsure whether a write went through can retry it safely.
 
 The npm package includes its compiled engine, which runs in a dedicated Node worker. Installing it requires no Go toolchain or lifecycle scripts. See the [API reference](API.md) for the storage, access, and connection contracts.