@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 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