@datafn/server 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +765 -0
- package/dist/index.cjs +13170 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +577 -0
- package/dist/index.d.ts +577 -0
- package/dist/index.js +13163 -0
- package/dist/index.js.map +1 -0
- package/package.json +60 -0
package/README.md
ADDED
|
@@ -0,0 +1,765 @@
|
|
|
1
|
+
# @datafn/server
|
|
2
|
+
|
|
3
|
+
HTTP server runtime for DataFn. Provides DFQL query execution, mutations with idempotency and optimistic concurrency, atomic transactions, full bidirectional sync (clone/pull/push/reconcile/seed), per-user/tenant isolation, REST endpoint generation, WebSocket real-time updates, plugin hooks, and configurable limits.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @datafn/server @datafn/core @superfunctions/db @superfunctions/http
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Features
|
|
12
|
+
|
|
13
|
+
| Feature | Description |
|
|
14
|
+
|---------|-------------|
|
|
15
|
+
| **Query Execution** | DFQL queries with filtering, sorting, pagination, relations, aggregations |
|
|
16
|
+
| **Mutations** | CRUD with idempotency (`clientId` + `mutationId` deduplication) and optimistic concurrency (`if` guards) |
|
|
17
|
+
| **Relation Operations** | `relate`, `unrelate`, `modifyRelation` for many-many and other relation types |
|
|
18
|
+
| **Transactions** | Atomic multi-step operations with query + mutation steps |
|
|
19
|
+
| **Sync: Clone** | Full data download for initial hydration |
|
|
20
|
+
| **Sync: Pull** | Incremental cursor-based change sync |
|
|
21
|
+
| **Sync: Push** | Upload offline mutations from client changelog |
|
|
22
|
+
| **Sync: Reconcile** | Detect and resolve local/remote drift |
|
|
23
|
+
| **Sync: Seed** | Seed data into the database |
|
|
24
|
+
| **Authorization** | Per-action authorization hook |
|
|
25
|
+
| **Multi-User Isolation** | Per-user/tenant namespace isolation for change tracking |
|
|
26
|
+
| **REST Endpoints** | Optional REST wrappers over DFQL (GET/POST/PATCH/DELETE) |
|
|
27
|
+
| **WebSocket** | Real-time cursor broadcast for live updates |
|
|
28
|
+
| **Plugins** | Hook into queries, mutations, and sync on the server side |
|
|
29
|
+
| **Sequence Store** | Pluggable serverSeq backend: Database, Redis, KV, or chained store |
|
|
30
|
+
| **Payload Limits** | Configurable max query limits, transaction steps, and payload size |
|
|
31
|
+
| **KV Resource** | Built-in key-value resource auto-included in schema |
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Quick Start
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { createDatafnServer } from "@datafn/server";
|
|
39
|
+
import { drizzleAdapter } from "@superfunctions/db/adapters";
|
|
40
|
+
import { toHono } from "@superfunctions/http-hono";
|
|
41
|
+
import { Hono } from "hono";
|
|
42
|
+
import { serve } from "@hono/node-server";
|
|
43
|
+
|
|
44
|
+
const server = await createDatafnServer({
|
|
45
|
+
schema: {
|
|
46
|
+
resources: [
|
|
47
|
+
{
|
|
48
|
+
name: "tasks",
|
|
49
|
+
version: 1,
|
|
50
|
+
fields: [
|
|
51
|
+
{ name: "id", type: "string", required: true, unique: true },
|
|
52
|
+
{ name: "title", type: "string", required: true },
|
|
53
|
+
{ name: "completed", type: "boolean", required: true, default: false },
|
|
54
|
+
],
|
|
55
|
+
},
|
|
56
|
+
],
|
|
57
|
+
},
|
|
58
|
+
db: drizzleAdapter({ db: myDrizzleInstance, dialect: "postgres" }),
|
|
59
|
+
authorize: async (ctx, action, payload) => {
|
|
60
|
+
return true; // Allow all (replace with real logic)
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
const app = new Hono();
|
|
65
|
+
app.route("/", toHono(server.router));
|
|
66
|
+
serve({ fetch: app.fetch, port: 3000 });
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Configuration
|
|
72
|
+
|
|
73
|
+
### DatafnServerConfig
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
interface DatafnServerConfig<TContext = any> {
|
|
77
|
+
/** DataFn schema — validated and normalized at startup */
|
|
78
|
+
schema: DatafnSchema;
|
|
79
|
+
|
|
80
|
+
/** Database adapter (e.g. drizzleAdapter, memoryAdapter) */
|
|
81
|
+
db?: Adapter;
|
|
82
|
+
|
|
83
|
+
/** Server-side plugins */
|
|
84
|
+
plugins?: DatafnPlugin[];
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Authorization callback. Called on every request after JSON parsing.
|
|
88
|
+
* Return true to allow, false to reject with 403 FORBIDDEN.
|
|
89
|
+
*/
|
|
90
|
+
authorize?: (
|
|
91
|
+
ctx: TContext,
|
|
92
|
+
action:
|
|
93
|
+
| "status" | "query" | "mutation" | "transact"
|
|
94
|
+
| "seed" | "clone" | "pull" | "push" | "reconcile",
|
|
95
|
+
payload: unknown,
|
|
96
|
+
) => Promise<boolean> | boolean;
|
|
97
|
+
|
|
98
|
+
/** Configurable limits */
|
|
99
|
+
limits?: {
|
|
100
|
+
/** Maximum number of records per query (default: 100) */
|
|
101
|
+
maxLimit?: number;
|
|
102
|
+
/** Maximum transaction steps */
|
|
103
|
+
maxTransactSteps?: number;
|
|
104
|
+
/** Maximum request body size in bytes */
|
|
105
|
+
maxPayloadBytes?: number;
|
|
106
|
+
};
|
|
107
|
+
|
|
108
|
+
/** Custom server time provider (for testing) */
|
|
109
|
+
getServerTime?: () => number;
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Enable REST endpoint generation.
|
|
113
|
+
* When true, generates REST wrappers alongside DFQL endpoints.
|
|
114
|
+
*/
|
|
115
|
+
rest?: boolean;
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Auth context provider for per-user/tenant isolation.
|
|
119
|
+
* Extracts user/tenant context from request to create isolated namespaces.
|
|
120
|
+
*/
|
|
121
|
+
authContextProvider?: {
|
|
122
|
+
getContext: (ctx: TContext) => AuthContext | Promise<AuthContext>;
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Redis adapter for atomic operations (serverSeq, rate limiting, caching).
|
|
127
|
+
* Used when dbMapping.serverseq = "redis".
|
|
128
|
+
*/
|
|
129
|
+
redis?: RedisAdapter;
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* KV store adapter for simple key-value operations.
|
|
133
|
+
* Must support incr() for serverSeq. Used when dbMapping.serverseq = "kv".
|
|
134
|
+
*/
|
|
135
|
+
kvStore?: KVStoreAdapter;
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Database mapping — choose which backend for each concern.
|
|
139
|
+
* Default: main database for everything.
|
|
140
|
+
*/
|
|
141
|
+
dbMapping?: DbMapping;
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### DbMapping
|
|
146
|
+
|
|
147
|
+
Route different server concerns to different backends:
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
type DbMapping = {
|
|
151
|
+
/** Backend for serverSeq counter: "db" | "redis" | "kv" */
|
|
152
|
+
serverseq?: "db" | "redis" | "kv";
|
|
153
|
+
/** Backend for rate limiting */
|
|
154
|
+
ratelimiting?: "db" | "redis" | "kv";
|
|
155
|
+
/** Backend for caching */
|
|
156
|
+
cache?: "db" | "redis" | "kv";
|
|
157
|
+
};
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Endpoints
|
|
163
|
+
|
|
164
|
+
### GET /datafn/status
|
|
165
|
+
|
|
166
|
+
Server health check, schema hash, capabilities, and limits.
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"ok": true,
|
|
171
|
+
"result": {
|
|
172
|
+
"schemaHash": "a1b2c3...",
|
|
173
|
+
"capabilities": [
|
|
174
|
+
"dfql.query", "dfql.mutation", "dfql.transact",
|
|
175
|
+
"sync.seed", "sync.clone", "sync.pull", "sync.push", "sync.reconcile"
|
|
176
|
+
],
|
|
177
|
+
"limits": { "maxLimit": 100 },
|
|
178
|
+
"serverTimeMs": 1707000000000
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### POST /datafn/query
|
|
184
|
+
|
|
185
|
+
Execute DFQL queries with full filtering, sorting, pagination, and relation expansion.
|
|
186
|
+
|
|
187
|
+
**Request:**
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"resource": "tasks",
|
|
192
|
+
"version": 1,
|
|
193
|
+
"select": ["id", "title", "completed"],
|
|
194
|
+
"filters": { "completed": false },
|
|
195
|
+
"sort": ["title:asc"],
|
|
196
|
+
"limit": 20
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
**Response:**
|
|
201
|
+
|
|
202
|
+
```json
|
|
203
|
+
{
|
|
204
|
+
"ok": true,
|
|
205
|
+
"result": {
|
|
206
|
+
"data": [
|
|
207
|
+
{ "id": "task:1", "title": "Buy milk", "completed": false }
|
|
208
|
+
],
|
|
209
|
+
"nextCursor": null
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**Filter operators:**
|
|
215
|
+
|
|
216
|
+
| Operator | Example | Description |
|
|
217
|
+
|----------|---------|-------------|
|
|
218
|
+
| `eq` (implicit) | `{ "status": "active" }` | Equals |
|
|
219
|
+
| `eq` (explicit) | `{ "status": { "eq": "active" } }` | Equals |
|
|
220
|
+
| `ne` | `{ "status": { "ne": "archived" } }` | Not equals |
|
|
221
|
+
| `gt` / `gte` | `{ "age": { "gt": 18 } }` | Greater than / or equal |
|
|
222
|
+
| `lt` / `lte` | `{ "age": { "lt": 65 } }` | Less than / or equal |
|
|
223
|
+
| `like` | `{ "name": { "like": "%john%" } }` | Case-sensitive pattern match |
|
|
224
|
+
| `ilike` | `{ "name": { "ilike": "%john%" } }` | Case-insensitive pattern match |
|
|
225
|
+
| `is_null` | `{ "deletedAt": { "is_null": true } }` | Is null |
|
|
226
|
+
| `is_not_null` | `{ "email": { "is_not_null": true } }` | Is not null |
|
|
227
|
+
| `in` | `{ "status": { "in": ["active", "pending"] } }` | In set |
|
|
228
|
+
| `nin` | `{ "status": { "nin": ["archived"] } }` | Not in set |
|
|
229
|
+
| `contains` | `{ "tags": { "contains": "urgent" } }` | Array/JSON contains |
|
|
230
|
+
|
|
231
|
+
**Logical groups:**
|
|
232
|
+
|
|
233
|
+
```json
|
|
234
|
+
{
|
|
235
|
+
"$or": [
|
|
236
|
+
{ "status": "active" },
|
|
237
|
+
{ "priority": { "gte": 4 } }
|
|
238
|
+
]
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### POST /datafn/search
|
|
243
|
+
|
|
244
|
+
Execute cross-resource search through the configured server `searchProvider`.
|
|
245
|
+
|
|
246
|
+
**Request:**
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"query": "test",
|
|
251
|
+
"resources": ["tasks", "projects"],
|
|
252
|
+
"limit": 20,
|
|
253
|
+
"prefix": true,
|
|
254
|
+
"fuzzy": 0.2,
|
|
255
|
+
"fieldBoosts": { "title": 2, "name": 1 }
|
|
256
|
+
}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
**Response:**
|
|
260
|
+
|
|
261
|
+
```json
|
|
262
|
+
{
|
|
263
|
+
"ok": true,
|
|
264
|
+
"result": {
|
|
265
|
+
"results": [
|
|
266
|
+
{ "resource": "tasks", "id": "task:1", "score": 12.34, "data": {} }
|
|
267
|
+
]
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Search option parity with client paths:
|
|
273
|
+
|
|
274
|
+
- `prefix` enables prefix matching.
|
|
275
|
+
- `fuzzy` enables fuzzy matching.
|
|
276
|
+
- `fieldBoosts` applies field-level weighting.
|
|
277
|
+
|
|
278
|
+
These options are validated at route/query boundaries and forwarded to provider execution.
|
|
279
|
+
|
|
280
|
+
**Aggregation queries:**
|
|
281
|
+
|
|
282
|
+
```json
|
|
283
|
+
{
|
|
284
|
+
"resource": "tasks",
|
|
285
|
+
"version": 1,
|
|
286
|
+
"groupBy": ["status"],
|
|
287
|
+
"aggregations": {
|
|
288
|
+
"count": { "fn": "count" },
|
|
289
|
+
"avgPriority": { "fn": "avg", "field": "priority" }
|
|
290
|
+
},
|
|
291
|
+
"having": { "count": { "gt": 5 } }
|
|
292
|
+
}
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### POST /datafn/mutation
|
|
296
|
+
|
|
297
|
+
Execute mutations with idempotency and optimistic concurrency.
|
|
298
|
+
|
|
299
|
+
**Insert:**
|
|
300
|
+
|
|
301
|
+
```json
|
|
302
|
+
{
|
|
303
|
+
"resource": "tasks",
|
|
304
|
+
"version": 1,
|
|
305
|
+
"operation": "insert",
|
|
306
|
+
"clientId": "client:device-1",
|
|
307
|
+
"mutationId": "m-001",
|
|
308
|
+
"record": { "title": "New task", "completed": false }
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
**Merge (partial update):**
|
|
313
|
+
|
|
314
|
+
```json
|
|
315
|
+
{
|
|
316
|
+
"resource": "tasks",
|
|
317
|
+
"version": 1,
|
|
318
|
+
"operation": "merge",
|
|
319
|
+
"clientId": "client:device-1",
|
|
320
|
+
"mutationId": "m-002",
|
|
321
|
+
"id": "task:abc",
|
|
322
|
+
"record": { "completed": true }
|
|
323
|
+
}
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
**Delete:**
|
|
327
|
+
|
|
328
|
+
```json
|
|
329
|
+
{
|
|
330
|
+
"resource": "tasks",
|
|
331
|
+
"version": 1,
|
|
332
|
+
"operation": "delete",
|
|
333
|
+
"clientId": "client:device-1",
|
|
334
|
+
"mutationId": "m-003",
|
|
335
|
+
"id": "task:abc"
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**Optimistic concurrency (if guards):**
|
|
340
|
+
|
|
341
|
+
```json
|
|
342
|
+
{
|
|
343
|
+
"resource": "tasks",
|
|
344
|
+
"version": 1,
|
|
345
|
+
"operation": "merge",
|
|
346
|
+
"id": "task:abc",
|
|
347
|
+
"record": { "status": "completed" },
|
|
348
|
+
"if": { "status": "in_progress" }
|
|
349
|
+
}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
The mutation is rejected with `CONFLICT` if the guard condition is not met.
|
|
353
|
+
|
|
354
|
+
**Relation operations:**
|
|
355
|
+
|
|
356
|
+
```json
|
|
357
|
+
{
|
|
358
|
+
"resource": "tasks",
|
|
359
|
+
"version": 1,
|
|
360
|
+
"operation": "relate",
|
|
361
|
+
"id": "task:1",
|
|
362
|
+
"relation": "tags",
|
|
363
|
+
"targetId": "tag:urgent"
|
|
364
|
+
}
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
| Operation | Description |
|
|
368
|
+
|-----------|-------------|
|
|
369
|
+
| `relate` | Create a relation between records |
|
|
370
|
+
| `unrelate` | Remove a relation |
|
|
371
|
+
| `modifyRelation` | Update relation metadata |
|
|
372
|
+
|
|
373
|
+
**Response:**
|
|
374
|
+
|
|
375
|
+
```json
|
|
376
|
+
{
|
|
377
|
+
"ok": true,
|
|
378
|
+
"result": {
|
|
379
|
+
"ok": true,
|
|
380
|
+
"mutationId": "m-001",
|
|
381
|
+
"affectedIds": ["task:new-uuid"],
|
|
382
|
+
"errors": [],
|
|
383
|
+
"deduped": false
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
- `deduped: true` means the mutation was already applied (idempotency).
|
|
389
|
+
|
|
390
|
+
### POST /datafn/transact
|
|
391
|
+
|
|
392
|
+
Atomic multi-step transactions mixing queries and mutations.
|
|
393
|
+
|
|
394
|
+
**Request:**
|
|
395
|
+
|
|
396
|
+
```json
|
|
397
|
+
{
|
|
398
|
+
"transactionId": "tx-batch",
|
|
399
|
+
"atomic": true,
|
|
400
|
+
"steps": [
|
|
401
|
+
{
|
|
402
|
+
"query": {
|
|
403
|
+
"resource": "tasks",
|
|
404
|
+
"version": 1,
|
|
405
|
+
"select": ["id"],
|
|
406
|
+
"filters": { "completed": false }
|
|
407
|
+
}
|
|
408
|
+
},
|
|
409
|
+
{
|
|
410
|
+
"mutation": {
|
|
411
|
+
"resource": "tasks",
|
|
412
|
+
"version": 1,
|
|
413
|
+
"operation": "merge",
|
|
414
|
+
"id": "task:1",
|
|
415
|
+
"record": { "completed": true }
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
]
|
|
419
|
+
}
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
**Response:**
|
|
423
|
+
|
|
424
|
+
```json
|
|
425
|
+
{
|
|
426
|
+
"ok": true,
|
|
427
|
+
"result": {
|
|
428
|
+
"ok": true,
|
|
429
|
+
"results": [
|
|
430
|
+
{ "kind": "query", "ok": true, "result": { "data": [...] } },
|
|
431
|
+
{ "kind": "mutation", "ok": true, "result": { ... } }
|
|
432
|
+
]
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
### POST /datafn/clone
|
|
438
|
+
|
|
439
|
+
Full data download for initial hydration. Supports pagination.
|
|
440
|
+
|
|
441
|
+
**Request:**
|
|
442
|
+
|
|
443
|
+
```json
|
|
444
|
+
{
|
|
445
|
+
"version": 1,
|
|
446
|
+
"tables": ["tasks", "categories"]
|
|
447
|
+
}
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
**Response:**
|
|
451
|
+
|
|
452
|
+
```json
|
|
453
|
+
{
|
|
454
|
+
"ok": true,
|
|
455
|
+
"result": {
|
|
456
|
+
"ok": true,
|
|
457
|
+
"data": {
|
|
458
|
+
"tasks": [{ "id": "task:1", "title": "..." }],
|
|
459
|
+
"categories": [{ "id": "cat:1", "name": "..." }]
|
|
460
|
+
},
|
|
461
|
+
"cursors": {
|
|
462
|
+
"tasks": "42",
|
|
463
|
+
"categories": "15"
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
}
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
### POST /datafn/pull
|
|
470
|
+
|
|
471
|
+
Incremental sync — only returns changes since the last cursor.
|
|
472
|
+
|
|
473
|
+
**Request:**
|
|
474
|
+
|
|
475
|
+
```json
|
|
476
|
+
{
|
|
477
|
+
"version": 1,
|
|
478
|
+
"cursors": {
|
|
479
|
+
"tasks": "42",
|
|
480
|
+
"categories": "15"
|
|
481
|
+
}
|
|
482
|
+
}
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
**Response:**
|
|
486
|
+
|
|
487
|
+
```json
|
|
488
|
+
{
|
|
489
|
+
"ok": true,
|
|
490
|
+
"result": {
|
|
491
|
+
"ok": true,
|
|
492
|
+
"records": {
|
|
493
|
+
"tasks": [{ "id": "task:3", "title": "New since last pull", "__deleted": false }]
|
|
494
|
+
},
|
|
495
|
+
"cursors": {
|
|
496
|
+
"tasks": "44",
|
|
497
|
+
"categories": "15"
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
### POST /datafn/push
|
|
504
|
+
|
|
505
|
+
Upload offline mutations from the client changelog.
|
|
506
|
+
|
|
507
|
+
**Request:**
|
|
508
|
+
|
|
509
|
+
```json
|
|
510
|
+
{
|
|
511
|
+
"version": 1,
|
|
512
|
+
"mutations": [
|
|
513
|
+
{
|
|
514
|
+
"resource": "tasks",
|
|
515
|
+
"version": 1,
|
|
516
|
+
"operation": "insert",
|
|
517
|
+
"clientId": "client:device-1",
|
|
518
|
+
"mutationId": "m-offline-1",
|
|
519
|
+
"record": { "title": "Created offline" }
|
|
520
|
+
}
|
|
521
|
+
]
|
|
522
|
+
}
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
### POST /datafn/reconcile
|
|
526
|
+
|
|
527
|
+
Detect and resolve drift between local and remote state.
|
|
528
|
+
|
|
529
|
+
**Request:**
|
|
530
|
+
|
|
531
|
+
```json
|
|
532
|
+
{
|
|
533
|
+
"version": 1,
|
|
534
|
+
"counts": {
|
|
535
|
+
"tasks": 42,
|
|
536
|
+
"categories": 8
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
### POST /datafn/seed
|
|
542
|
+
|
|
543
|
+
Seed data into the database.
|
|
544
|
+
|
|
545
|
+
**Request:**
|
|
546
|
+
|
|
547
|
+
```json
|
|
548
|
+
{
|
|
549
|
+
"data": {
|
|
550
|
+
"tasks": [
|
|
551
|
+
{ "id": "task:seed-1", "title": "Seeded Task", "completed": false }
|
|
552
|
+
]
|
|
553
|
+
}
|
|
554
|
+
}
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
---
|
|
558
|
+
|
|
559
|
+
## Multi-User / Multi-Tenant Isolation
|
|
560
|
+
|
|
561
|
+
Isolate change tracking per user or tenant. Each namespace gets its own `serverSeq` counter, ensuring users see only their own changes.
|
|
562
|
+
|
|
563
|
+
```typescript
|
|
564
|
+
const server = await createDatafnServer({
|
|
565
|
+
schema,
|
|
566
|
+
db: adapter,
|
|
567
|
+
authContextProvider: {
|
|
568
|
+
getContext: (ctx) => ({
|
|
569
|
+
userId: ctx.session?.userId,
|
|
570
|
+
tenantId: ctx.session?.tenantId,
|
|
571
|
+
}),
|
|
572
|
+
},
|
|
573
|
+
});
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
**Namespace format:**
|
|
577
|
+
- No auth: `datafn` (default)
|
|
578
|
+
- Single-tenant: `user:${userId}`
|
|
579
|
+
- Multi-tenant: `tenant:${tenantId}:user:${userId}`
|
|
580
|
+
|
|
581
|
+
**Behavior:**
|
|
582
|
+
1. On each request, `authContextProvider.getContext(ctx)` is called
|
|
583
|
+
2. A namespace is derived from `userId` and optional `tenantId`
|
|
584
|
+
3. All change tracking (serverSeq, change records) uses this namespace
|
|
585
|
+
4. Pull/clone only returns changes from the user's namespace
|
|
586
|
+
5. If `getContext()` fails, falls back to default `datafn` namespace
|
|
587
|
+
|
|
588
|
+
---
|
|
589
|
+
|
|
590
|
+
## Sequence Store
|
|
591
|
+
|
|
592
|
+
The server uses a `SequenceStore` for generating monotonically increasing sequence numbers. Choose the backend that fits your infrastructure:
|
|
593
|
+
|
|
594
|
+
```typescript
|
|
595
|
+
// Default: use main database
|
|
596
|
+
const server = await createDatafnServer({
|
|
597
|
+
schema,
|
|
598
|
+
db: adapter,
|
|
599
|
+
});
|
|
600
|
+
|
|
601
|
+
// Redis for high-throughput atomic INCR
|
|
602
|
+
const server = await createDatafnServer({
|
|
603
|
+
schema,
|
|
604
|
+
db: adapter,
|
|
605
|
+
redis: myRedisAdapter,
|
|
606
|
+
dbMapping: { serverseq: "redis" },
|
|
607
|
+
});
|
|
608
|
+
|
|
609
|
+
// KV store (e.g. Cloudflare KV, DynamoDB)
|
|
610
|
+
const server = await createDatafnServer({
|
|
611
|
+
schema,
|
|
612
|
+
db: adapter,
|
|
613
|
+
kvStore: myKVAdapter,
|
|
614
|
+
dbMapping: { serverseq: "kv" },
|
|
615
|
+
});
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
**Available implementations:**
|
|
619
|
+
|
|
620
|
+
| Store | Backend | Best for |
|
|
621
|
+
|-------|---------|----------|
|
|
622
|
+
| `DatabaseSequenceStore` | Main DB | Simple deployments |
|
|
623
|
+
| `RedisSequenceStore` | Redis | High throughput, atomic INCR |
|
|
624
|
+
| `KVSequenceStore` | KV store | Serverless environments |
|
|
625
|
+
| `ChainedSequenceStore` | Chain | Primary + database chain (e.g. Redis → DB) |
|
|
626
|
+
|
|
627
|
+
### createSequenceStore(config)
|
|
628
|
+
|
|
629
|
+
Factory that creates the appropriate store based on `dbMapping`:
|
|
630
|
+
|
|
631
|
+
```typescript
|
|
632
|
+
import { createSequenceStore } from "@datafn/server";
|
|
633
|
+
|
|
634
|
+
const store = createSequenceStore({
|
|
635
|
+
db: myAdapter,
|
|
636
|
+
redis: myRedisAdapter,
|
|
637
|
+
dbMapping: { serverseq: "redis" },
|
|
638
|
+
});
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
---
|
|
642
|
+
|
|
643
|
+
## REST Endpoints (Optional)
|
|
644
|
+
|
|
645
|
+
Enable REST wrappers alongside DFQL endpoints:
|
|
646
|
+
|
|
647
|
+
```typescript
|
|
648
|
+
const server = await createDatafnServer({
|
|
649
|
+
schema,
|
|
650
|
+
db: adapter,
|
|
651
|
+
rest: true, // Enable REST endpoints
|
|
652
|
+
});
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
**Generated routes:**
|
|
656
|
+
|
|
657
|
+
| Method | Path | Maps to |
|
|
658
|
+
|--------|------|---------|
|
|
659
|
+
| GET | `/datafn/resources/:resource` | Query wrapper |
|
|
660
|
+
| POST | `/datafn/resources/:resource` | Insert wrapper |
|
|
661
|
+
| PATCH | `/datafn/resources/:resource/:id` | Merge wrapper |
|
|
662
|
+
| DELETE | `/datafn/resources/:resource/:id` | Delete wrapper |
|
|
663
|
+
|
|
664
|
+
---
|
|
665
|
+
|
|
666
|
+
## WebSocket
|
|
667
|
+
|
|
668
|
+
The server exposes a WebSocket handler for real-time cursor broadcasts:
|
|
669
|
+
|
|
670
|
+
```typescript
|
|
671
|
+
const server = await createDatafnServer({ schema, db: adapter });
|
|
672
|
+
|
|
673
|
+
// Wire WebSocket connections to server handler
|
|
674
|
+
wss.on("connection", (ws) => {
|
|
675
|
+
const client = { id: ws.id, send: (msg) => ws.send(msg) };
|
|
676
|
+
server.websocketHandler.addClient(client);
|
|
677
|
+
ws.on("message", (data) => server.websocketHandler.handleMessage(client, data));
|
|
678
|
+
ws.on("close", () => server.websocketHandler.removeClient(client));
|
|
679
|
+
});
|
|
680
|
+
```
|
|
681
|
+
|
|
682
|
+
---
|
|
683
|
+
|
|
684
|
+
## Plugins
|
|
685
|
+
|
|
686
|
+
Server-side plugins intercept queries, mutations, and sync:
|
|
687
|
+
|
|
688
|
+
```typescript
|
|
689
|
+
const auditPlugin: DatafnPlugin = {
|
|
690
|
+
name: "server-audit",
|
|
691
|
+
runsOn: ["server"],
|
|
692
|
+
|
|
693
|
+
afterMutation(ctx, mutation, result) {
|
|
694
|
+
console.log("Server mutation:", mutation);
|
|
695
|
+
},
|
|
696
|
+
|
|
697
|
+
beforeSync(ctx, phase, payload) {
|
|
698
|
+
console.log(`Sync ${phase} started`);
|
|
699
|
+
return payload; // Return modified payload or original
|
|
700
|
+
},
|
|
701
|
+
};
|
|
702
|
+
|
|
703
|
+
const server = await createDatafnServer({
|
|
704
|
+
schema,
|
|
705
|
+
db: adapter,
|
|
706
|
+
plugins: [auditPlugin],
|
|
707
|
+
});
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
---
|
|
711
|
+
|
|
712
|
+
## Server Instance
|
|
713
|
+
|
|
714
|
+
`createDatafnServer` returns a `DatafnServer`:
|
|
715
|
+
|
|
716
|
+
```typescript
|
|
717
|
+
interface DatafnServer<TContext = any> {
|
|
718
|
+
/** HTTP router — wire to your framework (Hono, Express, etc.) */
|
|
719
|
+
router: Router<TContext>;
|
|
720
|
+
|
|
721
|
+
/** WebSocket handler for real-time updates */
|
|
722
|
+
websocketHandler: {
|
|
723
|
+
addClient(client: WebSocketClient): void;
|
|
724
|
+
removeClient(client: WebSocketClient): void;
|
|
725
|
+
handleMessage(client: WebSocketClient, data: string): void;
|
|
726
|
+
};
|
|
727
|
+
}
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
Use `@superfunctions/http-hono` or `@superfunctions/http-express` to mount the router:
|
|
731
|
+
|
|
732
|
+
```typescript
|
|
733
|
+
// Hono
|
|
734
|
+
import { toHono } from "@superfunctions/http-hono";
|
|
735
|
+
app.route("/", toHono(server.router));
|
|
736
|
+
|
|
737
|
+
// Express
|
|
738
|
+
import { toExpress } from "@superfunctions/http-express";
|
|
739
|
+
app.use("/", toExpress(server.router));
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
---
|
|
743
|
+
|
|
744
|
+
## Exports
|
|
745
|
+
|
|
746
|
+
```typescript
|
|
747
|
+
// Server factory and types
|
|
748
|
+
export { createDatafnServer }
|
|
749
|
+
export type { DatafnServerConfig, DatafnServer }
|
|
750
|
+
export type { StatusResult }
|
|
751
|
+
|
|
752
|
+
// Sequence store
|
|
753
|
+
export type { SequenceStore, DbMapping }
|
|
754
|
+
export {
|
|
755
|
+
createSequenceStore,
|
|
756
|
+
RedisSequenceStore,
|
|
757
|
+
KVSequenceStore,
|
|
758
|
+
DatabaseSequenceStore,
|
|
759
|
+
ChainedSequenceStore,
|
|
760
|
+
}
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
## License
|
|
764
|
+
|
|
765
|
+
MIT
|