@livequery/rest 2.0.91 → 2.0.92

package/README.md

@@ -1,18 +1,40 @@
 # @livequery/rest
 
-REST transporter for [livequery](https://github.com/livequery) — connects your livequery client to a REST API backend with optional real-time WebSocket support.
+`@livequery/rest` is a REST + WebSocket transporter for `@livequery/core`.
+
+It adapts the `LivequeryTransporter` interface to:
+
+- HTTP requests for `query`, `add`, `update`, `delete`, and `trigger`
+- optional WebSocket subscriptions for realtime collection updates
+- request/response hooks for auth, caching, logging, or mocking
+
+This package does not implement local cache or collection state management. That stays in `@livequery/core`. This package is only the transport layer between a livequery client and your backend.
 
 ## Installation
 
 ```bash
 npm install @livequery/rest
-# or
+```
+
+```bash
 bun add @livequery/rest
 ```
 
-## Usage
+## What It Implements
+
+`RestTransporter` implements the `LivequeryTransporter` contract from `@livequery/core`:
+
+- `query()` returns an `Observable<Partial<LivequeryQueryResult>>`
+- `add()` sends `POST`
+- `update()` sends `PATCH`
+- `delete()` sends `DELETE`
+- `trigger()` sends `POST /<ref>/~<action>`
+
+When a WebSocket endpoint is configured, `query()` can also attach a realtime subscription and merge server-pushed `DataChangeEvent`s into the observable stream.
+
+## Quick Start
 
-### Basic REST
+### REST only
 
 ```ts
 import { RestTransporter } from '@livequery/rest'
@@ -22,88 +44,424 @@ const transporter = new RestTransporter({
 })
 ```
 
-### With WebSocket (real-time updates)
+### REST + realtime
+
+```ts
+import { RestTransporter } from '@livequery/rest'
+
+const transporter = new RestTransporter({
+  api: 'https://api.example.com',
+  ws: 'wss://api.example.com/ws'
+})
+```
+
+### With `@livequery/core`
 
 ```ts
+import { LivequeryCore } from '@livequery/core'
+import { RestTransporter } from '@livequery/rest'
+
 const transporter = new RestTransporter({
   api: 'https://api.example.com',
   ws: 'wss://api.example.com/ws'
 })
+
+const core = new LivequeryCore({
+  storage,
+  transporters: {
+    rest: transporter
+  }
+})
+```
+
+## Constructor
+
+```ts
+type RestTransporterConfig = {
+  api: string
+  ws?: string
+  onRequest?: (
+    request: RestTransporterRequest & { ref: string }
+  ) =>
+    | void
+    | Partial<RestTransporterRequest & { response?: LivequeryResult<any> }>
+    | Promise<void | Partial<RestTransporterRequest & { response?: LivequeryResult<any> }>>
+  onResponse?: (
+    request: RestTransporterRequest & { ref: string },
+    response: LivequeryResult<any>
+  ) => void | Promise<void>
+}
+```
+
+### Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `api` | `string` | Base HTTP URL used for all REST calls. |
+| `ws` | `string` | Optional WebSocket endpoint for realtime sync. |
+| `onRequest` | `function` | Optional interceptor before `fetch()`. Can override request fields or return a fake response. |
+| `onResponse` | `function` | Optional hook called after the response is resolved. |
+
+## Request Model
+
+Outgoing requests use this shape internally:
+
+```ts
+type RestTransporterRequest = {
+  url: string
+  method: string
+  query?: Record<string, any>
+  body?: Record<string, any> | string
+  headers?: Record<string, string | undefined>
+}
+```
+
+The transporter builds URLs like this:
+
+```text
+<api>/<ref>
+<api>/<ref>?<query>
+<api>/<ref>/~<action>
+```
+
+Examples:
+
+```text
+GET    /users
+GET    /users/123
+POST   /users
+PATCH  /users/123
+DELETE /users/123
+POST   /users/~ban
 ```
 
-### Request / Response Hooks
+## Hooks
 
-Use `onRequest` to modify or intercept outgoing requests (e.g. inject auth headers), and `onResponse` to inspect responses.
+### `onRequest`
+
+Use `onRequest` to:
+
+- inject auth headers
+- override request body or URL
+- short-circuit requests from cache
+- mock server responses in tests
 
 ```ts
 const transporter = new RestTransporter({
   api: 'https://api.example.com',
   ws: 'wss://api.example.com/ws',
-
-  onRequest: async ({ url, method, headers, ref }) => {
+  onRequest: async ({ headers }) => {
     const token = await getAccessToken()
+
+    return {
+      headers: {
+        ...headers,
+        Authorization: `Bearer ${token}`
+      }
+    }
+  }
+})
+```
+
+To skip the network completely, return a `response`:
+
+```ts
+const transporter = new RestTransporter({
+  api: 'https://api.example.com',
+  onRequest: ({ ref }) => {
+    const cached = cache.get(ref)
+    if (!cached) return
+
     return {
-      headers: { Authorization: `Bearer ${token}` }
+      response: {
+        data: cached
+      }
     }
-  },
+  }
+})
+```
+
+### `onResponse`
+
+Use `onResponse` for logging, metrics, or centralized error inspection:
 
+```ts
+const transporter = new RestTransporter({
+  api: 'https://api.example.com',
   onResponse: async (request, response) => {
-    if (response.error) console.error('API error', response.error)
+    if (response.error) {
+      console.error('Livequery REST error', {
+        url: request.url,
+        method: request.method,
+        error: response.error
+      })
+    }
   }
 })
 ```
 
-You can also short-circuit a request by returning a `response` from `onRequest` — useful for caching or mocking:
+## REST Response Contract
+
+The transporter expects your backend to return a `LivequeryResult<T>` envelope:
 
 ```ts
-onRequest: ({ ref }) => {
-  const cached = cache.get(ref)
-  if (cached) return { response: { data: cached } }
+type LivequeryResult<T> = {
+  data: T
+  error?: {
+    code: string
+    message: string
+  }
 }
 ```
 
-## API
+### Collection query response
 
-### `RestTransporter`
+For collection reads, `data` should look like:
 
-#### Constructor options (`RestTransporterConfig`)
+```ts
+type LivequeryCollectionResponse<T> = {
+  summary?: Record<string, any>
+  items: T[]
+  subscription_token?: string
+  count?: {
+    prev: number
+    next: number
+    total: number
+    current: number
+  }
+  has?: {
+    prev: boolean
+    next: boolean
+  }
+  cursor?: {
+    first: string
+    last: string
+  }
+}
+```
 
-| Option | Type | Description |
-|---|---|---|
-| `api` | `string` | Base URL of your REST API |
-| `ws` | `string` (optional) | WebSocket endpoint for real-time updates |
-| `onRequest` | function (optional) | Interceptor called before each request. Return partial request overrides or a fake response. |
-| `onResponse` | function (optional) | Called after each response. |
+Example:
+
+```json
+{
+  "data": {
+    "items": [
+      { "id": "u1", "name": "Ada" },
+      { "id": "u2", "name": "Linus" }
+    ],
+    "summary": {
+      "active": 2
+    },
+    "count": {
+      "prev": 0,
+      "next": 20,
+      "current": 2,
+      "total": 22
+    },
+    "has": {
+      "prev": false,
+      "next": true
+    },
+    "cursor": {
+      "first": "cursor-1",
+      "last": "cursor-2"
+    },
+    "subscription_token": "rt_abc123"
+  }
+}
+```
+
+### Single document response
 
-#### Methods
+For document reads, `data` should contain `item`:
+
+```json
+{
+  "data": {
+    "item": {
+      "id": "u1",
+      "name": "Ada"
+    }
+  }
+}
+```
 
-These follow the `LivequeryTransporter` interface from `@livequery/core`:
+### Create response
 
-| Method | Description |
-|---|---|
-| `query(ref, filters)` | Query a collection or document. Returns an Observable. |
-| `add(ref, data)` | Create a new document (`POST`) |
-| `update(ref, id, data)` | Update a document (`PATCH`) |
-| `delete(ref, id)` | Delete a document (`DELETE`) |
-| `trigger({ ref, action, payload })` | Trigger a custom action (`POST /ref/~action`) |
+`add()` accepts either of these backend shapes:
 
-### `Socket`
+```json
+{
+  "data": {
+    "item": {
+      "id": "u1",
+      "name": "Ada"
+    }
+  }
+}
+```
+
+```json
+{
+  "data": {
+    "id": "u1",
+    "name": "Ada"
+  }
+}
+```
+
+## Query Output Shape
+
+`query()` converts server data into the shape expected by `@livequery/core`:
+
+```ts
+type LivequeryQueryResult = {
+  changes: DataChangeEvent[]
+  summary: Record<string, any>
+  paging: {
+    total: number
+    current: number
+    next?: { count: number; cursor: string }
+    prev?: { count: number; cursor: string }
+  }
+  source: 'query' | 'realtime' | 'action'
+  error: { code: string; message: string }
+}
+```
+
+Collection responses are converted to `added` events for each returned item. Document responses are converted to a single `added` event for the returned document.
+
+## Realtime
+
+If `ws` is provided, the transporter creates a `Socket` instance and adds these headers to REST calls:
+
+- `socket_id`
+- `x-lcid`
+- `x-lgid`
+
+This lets your backend bind the HTTP query to the active realtime session.
+
+### Realtime flow
+
+1. A collection query returns `subscription_token`.
+2. The transporter forwards that token to the socket with a `subscribe` event.
+3. The socket listens for server `sync` messages.
+4. Incoming changes are emitted as `DataChangeEvent`s with `source: 'realtime'`.
+
+Realtime listening is only attached for standard collection queries. It is skipped when:
+
+- no `ws` endpoint is configured
+- the request is a cursor query using `:after`
+- the request is a cursor query using `:before`
+- the request is an around query using `:around`
+
+### WebSocket protocol expected by `Socket`
+
+When the socket opens, it sends:
+
+```json
+{ "event": "start", "data": { "id": "<client_id>" } }
+```
+
+It also sends a heartbeat every 60 seconds:
+
+```json
+{ "event": "ping" }
+```
 
-Manages the WebSocket connection lifecycle automatically — reconnects on failure, sends heartbeat pings, and routes server-pushed `DataChangeEvent`s to the appropriate collection streams.
+To subscribe a collection query, it sends:
+
+```json
+{ "event": "subscribe", "data": { "realtime_token": "<token>" } }
+```
+
+The server should respond with a hello message containing the gateway id:
+
+```json
+{ "event": "hello", "gid": "gateway-1" }
+```
+
+Realtime sync messages should look like:
+
+```json
+{
+  "event": "sync",
+  "data": {
+    "changes": [
+      {
+        "ref": "users",
+        "id": "u1",
+        "type": "modified",
+        "data": { "name": "Ada Lovelace" }
+      }
+    ]
+  }
+}
+```
+
+Each sync change is routed to `listen(ref)` subscribers and normalized to:
+
+```ts
+type DataChangeEvent = {
+  collection_ref: string
+  id: string
+  type: 'added' | 'removed' | 'modified'
+  data?: Record<string, any>
+}
+```
+
+## Public API
+
+### `RestTransporter`
+
+```ts
+import { RestTransporter } from '@livequery/rest'
+```
+
+Methods:
+
+- `query({ ref, filters })`
+- `add(ref, data)`
+- `update(collectionRef, id, data)`
+- `delete(collectionRef, id)`
+- `trigger({ ref, action, payload })`
+
+### `Socket`
 
 ```ts
 import { Socket } from '@livequery/rest'
+```
+
+The socket class is exported for low-level integrations and debugging.
+
+Example:
 
+```ts
 const socket = new Socket('wss://api.example.com/ws')
-socket.listen('users/123').subscribe(change => console.log(change))
-socket.stop() // close connection
+
+socket.listen('users').subscribe(change => {
+  console.log(change)
+})
+
+socket.stop()
+```
+
+## Error Handling
+
+If `fetch()` throws or the backend returns an error envelope, the transporter surfaces it as:
+
+```ts
+{
+  error: {
+    code: string,
+    message: string
+  }
+}
 ```
 
-## Real-time Flow
+For `query()`, errors are emitted as an observable result with `source: 'query'`.
 
-1. On `query()`, a `subscription_token` returned by the server is forwarded to the socket.
-2. The socket subscribes to the token and listens for `sync` events from the server.
-3. Incoming changes are emitted as `DataChangeEvent`s with `source: "realtime"`.
+For `add()`, `update()`, `delete()`, and `trigger()`, errors are thrown as rejected promises.
 
 ## Build
 
@@ -111,7 +469,11 @@ socket.stop() // close connection
 bun run build
 ```
 
-Outputs ESM + type declarations to `dist/`.
+Build steps:
+
+- clean `dist/`
+- bundle ESM output with Bun
+- generate `.d.ts` files with TypeScript
 
 ## License
 

package/package.json

@@ -3,7 +3,7 @@
     "repository": {
         "url": "https://github.com/livequery/rest"
     },
-    "version": "2.0.91",
+    "version": "2.0.92",
     "type": "module",
     "description": "",
     "main": "build/index.js",
@@ -23,7 +23,7 @@
         "uuid": "^13.0.0"
     },
     "devDependencies": {
-        "@livequery/core": "2.0.74",
+        "@livequery/core": "2.0.92",
         "typescript": "5.6.3"
     },
     "peerDependencies": {},