foldkit-remote-server 0.18.0 → 0.19.0

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/dist/index.d.mts CHANGED
@@ -1,670 +1,2 @@
1
- import { Context, Effect, Layer, Option, Schema, Stream } from "effect";
2
- import { AnyQuery, AnyWrite, Computation, EntityRef, MemoryOperators, QueryEvaluateError, Row, WriteAssignment, assertSupported, evaluate, supported } from "foldkit-entity";
3
- import { Boundary, ConnectionChangeSchema, ConnectionIdentity, LiveChange, MutationDescriptor, NormalizedPatch, QueryDescriptor, QueryWindow, RelationRequirement, RemoteClient, RemoteDescriptor, RemoteForbidden, RemoteJsonAnswer, RemoteReadError, RemoteRpcClient, RemoteUnauthenticated, Requirement } from "foldkit-remote";
4
- declare const RemoteServerError_base: Schema.Class<RemoteServerError, Schema.TaggedStruct<"RemoteServerError", {
5
- readonly message: Schema.String;
6
- }>, import("effect/Cause").YieldableError>;
7
- export declare class RemoteServerError extends RemoteServerError_base {}
8
- declare const RemoteUnmet_base: Schema.Class<RemoteUnmet, Schema.TaggedStruct<"RemoteUnmet", {
9
- readonly message: Schema.String;
10
- }>, import("effect/Cause").YieldableError>;
11
- /**
12
- * A writer's word that the row does not hold what the write's `when` asks of
13
- * it, where the write would commit: `RemoteServer.write` answers it as the
14
- * mutation's `Unmet` refusal.
15
- */
16
- export declare class RemoteUnmet extends RemoteUnmet_base {}
17
- declare const RemoteInvalid_base: Schema.Class<RemoteInvalid, Schema.TaggedStruct<"RemoteInvalid", {
18
- readonly message: Schema.String;
19
- readonly rule: Schema.Option<Schema.String>;
20
- readonly path: Schema.$Array<Schema.String>;
21
- }>, import("effect/Cause").YieldableError>;
22
- /**
23
- * A writer's word that the row a write would leave breaks one of its Entity's
24
- * invariants: `RemoteServer.write` answers it as the mutation's `Invalid`
25
- * refusal. `rule` and `path` are none and empty when saying them would tell
26
- * the caller what a member hidden from them holds.
27
- */
28
- export declare class RemoteInvalid extends RemoteInvalid_base {}
29
- /** A write's precondition as a writer is handed it: the body, and the input encoded. */
30
- export interface WriteWhen {
31
- readonly body: AnyQuery;
32
- readonly input: Readonly<Record<string, unknown>>;
33
- }
34
- declare const MutationRefused_base: Schema.Class<MutationRefused, Schema.TaggedStruct<"MutationRefused", {
35
- /** The mutation the refusal was made for: a Source refusing as another is a bug. */
36
- readonly mutation: Schema.String;
37
- readonly refusal: Schema.Unknown;
38
- /** What a person reads: the error's message beside the refusal. */
39
- readonly message: Schema.String;
40
- }>, import("effect/Cause").YieldableError>;
41
- /**
42
- * A mutation Source's refusal, as the value its descriptor's `Refusal`
43
- * declares: made with `RemoteServer.refuse`, which checks the value's type
44
- * against the mutation, and sent to the client encoded, beside a message.
45
- */
46
- export declare class MutationRefused extends MutationRefused_base {}
47
- export interface EntityRecord {
48
- readonly id: string;
49
- readonly values: Readonly<Record<string, unknown>>;
50
- }
51
- export interface EntitySourceContext<P> {
52
- readonly ids: readonly string[];
53
- readonly fields: readonly string[];
54
- /** A pagination window per requested relation field. */
55
- readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
56
- readonly principal: P;
57
- }
58
- export interface EntitySource<P, R = never> {
59
- readonly entity: string;
60
- /** The fields the entity declares; a request for any other never reaches `read`. */
61
- readonly fields?: ReadonlySet<string> | undefined;
62
- readonly read: (context: EntitySourceContext<P>) => Effect.Effect<ReadonlyArray<EntityRecord>, RemoteServerError, R>;
63
- /** Returns the fields this principal may read; omitted means all requested. */
64
- readonly authorize?: (principal: P, fields: readonly string[]) => readonly string[];
65
- /**
66
- * Decides, per record, what a principal sees of the fields `authorize`
67
- * allowed: run once per read, before `read`. A member it drops from a
68
- * record is settled unread, as one the source did not return.
69
- */
70
- readonly filter?: (principal: P, fields: readonly string[]) => Effect.Effect<ReadPlan, RemoteServerError, R>;
71
- /**
72
- * The rule that decides which rows this source returns, as it was given one
73
- * (a Drizzle binding's `visible`, `RemoteServer.memory`'s `readable`). The
74
- * server never runs it: it is here so a check at startup, such as
75
- * `GuardServer.validate`, can confirm a source applies the rule its Entity
76
- * requires.
77
- */
78
- readonly visible?: unknown;
79
- /**
80
- * The fields every principal reads alike, of every row: no rule about who
81
- * is asking hides the row or the field, or changes its value. A promise the
82
- * server keeps by trusting it: the live hub sends a declared write's value
83
- * of one to every subscriber as it is, with no read per principal.
84
- */
85
- readonly shared?: ReadonlySet<string> | undefined;
86
- }
87
- /** What `EntitySource.filter` decides for one read. */
88
- export interface ReadPlan {
89
- /** The fields to read: those allowed, and any the decision itself needs. */
90
- readonly fields: readonly string[];
91
- /** One record as the principal sees it: a member dropped, or its value replaced. */
92
- readonly apply: (record: EntityRecord) => EntityRecord;
93
- }
94
- /**
95
- * Where a declared write lands: one row's new values, encoded as the store holds
96
- * them. With `expect`, the row is written only while its revision is still that
97
- * value, and the revision moves on with the write. With `when`, only while the
98
- * row holds its body, checked in the statement that writes it; a row there at
99
- * the expected revision that does not hold it fails with `RemoteUnmet`. The row
100
- * as written answers; none when no row matched.
101
- */
102
- export interface EntityWriter<P, R = never> {
103
- readonly entity: string;
104
- /**
105
- * Whether `update` and `delete` honour `when`. `RemoteServer.write` refuses
106
- * a write with a precondition over a writer without it, which would write
107
- * whatever the row held.
108
- */
109
- readonly preconditions?: true;
110
- /**
111
- * Whether `update` adds `increments` to their fields where it writes.
112
- * `RemoteServer.write` refuses a write with an increment over a writer
113
- * without it, which would leave the fields where they were.
114
- */
115
- readonly increments?: true;
116
- /**
117
- * Whether `update` computes `assignments` where it writes, over the row it
118
- * writes. `RemoteServer.write` refuses a write computing a field over a
119
- * writer without it.
120
- */
121
- readonly assignments?: true;
122
- /**
123
- * The memory table this writer works out the row a write leaves by
124
- * (`Write.apply`'s), where its own statement computes it: what a wrapping
125
- * writer (a guard) judges by, so it judges the value the database writes.
126
- */
127
- readonly operators?: MemoryOperators | undefined;
128
- /**
129
- * Whether `update` writes only the row it read, at the revision it read it,
130
- * whatever the write `expect`s: what a guard does so its rules judge the row
131
- * written. Concurrent writes then cannot interleave, so an increment of a
132
- * real number, or any computed assignment, needs no `expect` of its own.
133
- */
134
- readonly pins?: true;
135
- /**
136
- * Whether `assignment`, landed without `expect`, gives one result whatever
137
- * order concurrent writes land in: its operator `op(field, amount)`, with
138
- * commutativity and associativity tested for the implementations this
139
- * writer runs. `RemoteServer.write` asks of each computed assignment a
140
- * write lands without a revision.
141
- */
142
- readonly commutes?: (assignment: WriteAssignment) => boolean;
143
- /**
144
- * Whether `update` records each write it lands under its `operation`, in
145
- * the transaction that writes, and answers a retry of it from that record
146
- * rather than writing again. An increment that expects no revision needs one.
147
- */
148
- readonly ledger?: true;
149
- /**
150
- * Whether `update` and `insert` refuse a row, or a change, that would break
151
- * one of its Entity's invariants (`Entity.invariant`), with `RemoteInvalid`,
152
- * judged over the rows they write; an insert judges the state invariants
153
- * alone. `RemoteServer.write` refuses a write the Entity holds to any through
154
- * a writer without it.
155
- */
156
- readonly invariants?: true;
157
- /**
158
- * Why this writer cannot land `write`, each a sentence; none when it can.
159
- * `RemoteServer.write` asks once, where the write is registered, for what
160
- * only the store knows: a column's type, say, which the Entity does not say.
161
- */
162
- readonly refuses?: (write: AnyWrite) => ReadonlyArray<string>;
163
- /**
164
- * The answer recorded for `operation`, when this writer has a ledger and
165
- * holds one: what a wrapping writer (a guard) answers a retry with, without
166
- * deciding again over a row that has moved since.
167
- */
168
- readonly recorded?: (context: {
169
- readonly operation: string;
170
- /** The row the operation writes: one operation may write several rows. */
171
- readonly id: string;
172
- readonly principal: P;
173
- }) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
174
- readonly update: (context: {
175
- readonly id: string;
176
- /** The operation's identity across clients, when the client sent one: a ledger's key. */
177
- readonly operation: Option.Option<string>;
178
- readonly values: Readonly<Record<string, unknown>>;
179
- /**
180
- * Each field to move, by the amount, encoded: added to the stored value in
181
- * the statement that writes, never computed from a value read before it.
182
- */
183
- readonly increments: Readonly<Record<string, number>>;
184
- /**
185
- * Each field to compute, as data (`Write.bind`'s): run in the statement
186
- * that writes, over the row as it is there.
187
- */
188
- readonly assignments: Readonly<Record<string, Computation>>;
189
- /** Each `one` relation it points, by the relation's key: the row, or none. */
190
- readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
191
- readonly expect: Option.Option<{
192
- readonly field: string;
193
- readonly revision: unknown;
194
- }>;
195
- readonly when: Option.Option<WriteWhen>;
196
- readonly principal: P;
197
- }) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError | RemoteForbidden | RemoteUnmet | RemoteInvalid, R>;
198
- /**
199
- * Inserts the row, or finds one already there under that id holding what
200
- * it writes (a retry); answers the row as it is. Fails when the id holds
201
- * any other row.
202
- */
203
- readonly insert: (context: {
204
- readonly id: string;
205
- readonly values: Readonly<Record<string, unknown>>;
206
- readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
207
- readonly principal: P;
208
- }) => Effect.Effect<Readonly<Record<string, unknown>>, RemoteServerError | RemoteForbidden | RemoteInvalid, R>;
209
- /**
210
- * Deletes the row, while it is still at the revision when one is expected:
211
- * `deleted`, `absent` (no row, so nothing to delete; a retry's case), or
212
- * `moved` (the row is there at another revision, and stays).
213
- */
214
- readonly delete: (context: {
215
- readonly id: string;
216
- readonly expect: Option.Option<{
217
- readonly field: string;
218
- readonly revision: unknown;
219
- }>;
220
- readonly when: Option.Option<WriteWhen>;
221
- readonly principal: P;
222
- }) => Effect.Effect<'deleted' | 'absent' | 'moved', RemoteServerError | RemoteForbidden | RemoteUnmet, R>;
223
- /**
224
- * The row as `principal` may see it, under the read rule its Source applies:
225
- * none when there is no such row, or it is hidden. Given, a write's answer
226
- * is read back through it, so an answer never shows its writer a row it may
227
- * not read, and a row the write hid from them answers as deleted.
228
- */
229
- readonly read?: (context: {
230
- readonly id: string;
231
- readonly fields: ReadonlyArray<string>;
232
- readonly principal: P;
233
- }) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
234
- /**
235
- * Each of `relations`' links as stored, by ref key (`'Project:p1'`) or
236
- * `null`, whatever a reader may see of the row it points at; none when there
237
- * is no such row. A guard reads it to tell a write that unlinks a row hidden
238
- * from its writer from one that changes nothing.
239
- */
240
- readonly linked?: (context: {
241
- readonly id: string;
242
- readonly relations: ReadonlyArray<string>;
243
- }) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
244
- }
245
- /** A connection change a mutation made, as the wire carries it. */
246
- export type ConnectionChange = Schema.Schema.Type<typeof ConnectionChangeSchema>;
247
- export interface MutationOutcome<Output> {
248
- readonly output: Output;
249
- readonly entities?: ReadonlyArray<NormalizedPatch>;
250
- /** Connection changes the mutation made; the client settles them with its patches. */
251
- readonly connections?: ReadonlyArray<ConnectionChange>;
252
- /**
253
- * Entities the mutation deleted. The client knows them absent from then on:
254
- * they leave every connection and read `NotFound`, with no connection to name.
255
- */
256
- readonly deleted?: ReadonlyArray<{
257
- readonly entity: string;
258
- readonly id: string;
259
- }>;
260
- }
261
- export interface MutationSource<P, R = never> {
262
- readonly mutation: string;
263
- /**
264
- * For a declared write (`RemoteServer.write`), the Entity it writes, the
265
- * writer it lands through, as it was given one, and the write itself. The
266
- * server never reads it; a startup check such as `GuardServer.validate` does.
267
- */
268
- readonly writes?: {
269
- readonly entity: string;
270
- readonly writer: unknown;
271
- readonly write: AnyWrite;
272
- };
273
- readonly Input: Schema.Codec<unknown>;
274
- readonly Output: Schema.Codec<unknown>;
275
- readonly Refusal: Schema.Codec<unknown, unknown>;
276
- readonly run: (context: {
277
- readonly input: unknown;
278
- readonly principal: P;
279
- /**
280
- * The client's id for this request, the same on every retry of it. It is
281
- * unique within that client only: two clients' first requests can share
282
- * it. Key a record of the write by `operation`, never by this.
283
- */
284
- readonly requestId: string;
285
- /**
286
- * The operation's identity across clients, the same on every retry of it,
287
- * when the client sent one (Remote's does); none from an older client.
288
- */
289
- readonly operation: Option.Option<string>;
290
- /** For a declared write: the input keys to write, when the client named only some. */
291
- readonly keys?: ReadonlyArray<string> | undefined;
292
- }) => Effect.Effect<{
293
- readonly output: unknown;
294
- readonly entities: ReadonlyArray<NormalizedPatch>;
295
- readonly connections: ReadonlyArray<ConnectionChange>;
296
- readonly deleted: ReadonlyArray<{
297
- readonly entity: string;
298
- readonly id: string;
299
- }>;
300
- }, RemoteServerError | MutationRefused | RemoteForbidden, R>;
301
- }
302
- export interface QueryPage {
303
- readonly edges: ReadonlyArray<{
304
- readonly entity: string;
305
- readonly id: string;
306
- readonly key: string;
307
- }>;
308
- readonly start: Boundary;
309
- readonly end: Boundary;
310
- }
311
- export interface QuerySource<P, R = never> {
312
- readonly query: string;
313
- readonly Input: Schema.Codec<unknown>;
314
- readonly run: (context: {
315
- readonly input: unknown;
316
- readonly window: QueryWindow;
317
- readonly principal: P;
318
- /**
319
- * What the client reads of each item. A source may use it to answer
320
- * fields with the page, or ignore it: the handlers fetch what the page
321
- * leaves out through the entity sources, so one response still carries
322
- * both either way.
323
- */
324
- readonly select?: RelationRequirement | undefined;
325
- }) => Effect.Effect<QueryPage, RemoteServerError, R>;
326
- /** The rule that decides which rows the query lists. See `EntitySource.visible`. */
327
- readonly visible?: unknown;
328
- }
329
- export interface LiveSource<P, R = never> {
330
- readonly entity: string;
331
- readonly subscribe: (context: {
332
- readonly requirements: ReadonlyArray<Requirement>;
333
- readonly after: number;
334
- readonly principal: P;
335
- }) => Stream.Stream<Schema.Schema.Type<typeof LiveChange>, RemoteServerError, R>;
336
- }
337
- export interface ServerDefinition<P, R = never> {
338
- readonly entities: ReadonlyMap<string, EntitySource<P, R>>;
339
- readonly mutations: ReadonlyMap<string, MutationSource<P, R>>;
340
- readonly queries: ReadonlyMap<string, QuerySource<P, R>>;
341
- readonly live: ReadonlyMap<string, LiveSource<P, R>>;
342
- }
343
- export interface HandlerOptions<P, R = never> {
344
- /** A read or live subscription may not name more ids of one entity than this; default 1000. */
345
- readonly maxIdsPerEntity?: number | undefined;
346
- /** A nested selection may not reach further than this many relation levels; default 8. */
347
- readonly maxDepth?: number | undefined;
348
- /** A hub whose `changed`/`deleted` signals reach the subscribers this handler registers. */
349
- readonly live?: LiveHub<P, R> | undefined;
350
- }
351
- type LiveChangeValue = Schema.Schema.Type<typeof LiveChange>;
352
- interface LiveRef {
353
- readonly entity: string;
354
- readonly id: string;
355
- }
356
- /**
357
- * The server-side "these fields changed" signal. A hub tracks each live
358
- * subscriber's requirements (entity, id, fields) and principal; `changed`
359
- * re-reads the changed fields a subscriber selects through the entity's own
360
- * source, under that subscriber's principal, and streams the patch to it.
361
- * Subscribers that select none of the changed fields do no work. Cursors
362
- * continue from the cursor each subscriber resumed at, so the client's
363
- * duplicate and gap handling is unchanged.
364
- */
365
- export interface LiveHub<P, R = never> {
366
- /**
367
- * `values`, when given, are the row's stored values of `fields` (a declared
368
- * write's answer): a field of them the source declares `shared` is sent as
369
- * it is, and only the rest are re-read.
370
- */
371
- readonly changed: (ref: LiveRef, fields: ReadonlyArray<string>, values?: Readonly<Record<string, unknown>> | undefined) => Effect.Effect<void, RemoteServerError, R>;
372
- /**
373
- * `ref` may be gone: each subscriber's selection of it is read again, and
374
- * one it is no longer there to is sent a deletion. A row deleted for one
375
- * writer may only be hidden from them, and still there to others.
376
- */
377
- readonly deleted: (ref: LiveRef) => Effect.Effect<void, RemoteServerError, R>;
378
- /** Registers a subscriber for the stream's lifetime; `handlers` calls this. */
379
- readonly subscribe: (context: {
380
- readonly requirements: ReadonlyArray<Requirement>;
381
- readonly after: number;
382
- readonly principal: P;
383
- /** Refuses a subscription naming more ids of one entity than this. */
384
- readonly maxIdsPerEntity?: number | undefined;
385
- }) => Stream.Stream<LiveChangeValue, RemoteServerError>;
386
- /** How many subscribers are registered now. */
387
- readonly size: Effect.Effect<number>;
388
- }
389
- declare const liveHub: <P, R>(entities: ReadonlyArray<EntitySource<P, R>>, options?: {
390
- /**
391
- * Who a principal is, for sharing re-reads: subscribers whose principals
392
- * have one key share one read, under the first one's principal. Default:
393
- * the principal itself, so only the same value shares.
394
- */
395
- readonly key?: ((principal: P) => unknown) | undefined;
396
- }) => Effect.Effect<LiveHub<P, R>>;
397
- /**
398
- * A descriptor's name and, when it declares them, its readable members: an
399
- * Entity's `members` (its fields, relations and derived members), or a plain
400
- * descriptor's `fields`.
401
- */
402
- interface EntityName {
403
- readonly name: string;
404
- readonly fields?: Readonly<Record<string, unknown>> | undefined;
405
- readonly members?: Readonly<Record<string, unknown>> | undefined;
406
- }
407
- /** One entity's rows in their wire shape: a relation is its ref key, `'User:u1'`. */
408
- export type MemoryRows = Readonly<Record<string, ReadonlyArray<Readonly<Record<string, unknown>> & {
409
- readonly id: string;
410
- }>>>;
411
- /**
412
- * The rows a memory backend holds, which its mutations write through. A
413
- * change is what the next read sees; nothing is pushed to a client.
414
- */
415
- export interface MemoryStore {
416
- /** The rows of one entity, in insertion order. */
417
- readonly rows: (entity: string) => ReadonlyArray<Readonly<Record<string, unknown>>>;
418
- /** Writes these values onto a row, creating it if it is new. */
419
- readonly write: (entity: string, id: string, values: Readonly<Record<string, unknown>>) => void;
420
- readonly remove: (entity: string, id: string) => void;
421
- }
422
- /**
423
- * A memory backend made without a `principal`: its rows and the server over
424
- * them, answered as whoever its caller names per request (`serveFetch`,
425
- * `RemoteServer.handlers(served.server, principal)`).
426
- */
427
- export interface MemoryServed<P> extends MemoryStore {
428
- /**
429
- * The rows' server, for serving them over a real transport, or as any
430
- * principal: `RemoteRpc.toLayer(RemoteServer.handlers(backend.server, principal))`.
431
- */
432
- readonly server: ServerDefinition<P>;
433
- }
434
- export interface MemoryBackend<P = undefined> extends MemoryServed<P> {
435
- /**
436
- * A `RemoteClient` answering from the rows as the configured `principal`.
437
- * Provide it where the real one would go.
438
- */
439
- readonly layer: Layer.Layer<RemoteClient>;
440
- }
441
- /** What `RemoteServer.memory` is made from. See `memory`. */
442
- export type MemoryConfig<P> = {
443
- readonly domain: Pick<RemoteDescriptor, 'registry'>;
444
- readonly rows: MemoryRows;
445
- /**
446
- * How the bodies' primitive operators are run: every query body is checked
447
- * against it where the server is built, and one calling an operator it lacks
448
- * is refused there. `Operators.kernel` when not given.
449
- */
450
- readonly operators?: MemoryOperators | undefined;
451
- /**
452
- * Sources for entities the domain does not declare, which no row backs (a
453
- * `Me` row answered from the principal, `GuardServer.me`), served beside
454
- * the rows. One for a declared entity is refused: the rows serve it.
455
- */
456
- readonly entities?: ReadonlyArray<EntitySource<P>>;
457
- /** Sources for queries, beside the domain's: one named as a declared query answers it instead of its body. */
458
- readonly queries?: ReadonlyArray<QuerySource<P>>;
459
- readonly mutations?: (store: MemoryStore) => ReadonlyArray<MutationSource<P>>;
460
- /** Per entity name, the fields a principal may read, as `RemoteServer.entity` takes it. */
461
- readonly authorize?: Readonly<Record<string, NonNullable<EntitySource<P>['authorize']>>>;
462
- /** Per entity name, what a principal sees of each record, as `RemoteServer.entity` takes it. */
463
- readonly filter?: Readonly<Record<string, NonNullable<EntitySource<P>['filter']>>>;
464
- /** Per entity name, the fields every principal reads alike: see `EntitySource.shared`. */
465
- readonly shared?: Readonly<Record<string, ReadonlyArray<string>>>;
466
- /**
467
- * Which stored rows a principal may read, decided once per read. A row it
468
- * may not read is absent from a read by id and from every query, and a ref
469
- * to one is dropped from a relation (a `one` ref reads as `null`). `row`
470
- * looks another stored row up, for a decision that follows a relation.
471
- */
472
- readonly readable?: (principal: P, row: (entity: string, id: string) => Option.Option<Readonly<Record<string, unknown>>>) => Effect.Effect<MemoryReadable, RemoteServerError>;
473
- /** Who the `layer` answers as. Without it there is no `layer`, unless `P` admits `undefined`. */
474
- readonly principal?: P;
475
- };
476
- /** What a backend needs to give a `layer`: a principal to answer as, or one `undefined` can be. */
477
- export type MemoryAnswering<P> = undefined extends P ? unknown : {
478
- readonly principal: P;
479
- };
480
- /** Whether a stored row of `entity` may be read, given its whole stored values. */
481
- export type MemoryReadable = (entity: string, row: Readonly<Record<string, unknown>>) => boolean;
482
- /**
483
- * A backend held in memory: the rows you give it, served through the same
484
- * handlers a real server uses. For a first run, a test, a story or a demo, with
485
- * no database and no network.
486
- *
487
- * Reads go through `handlers`, so field filtering and nested relations behave
488
- * as they do in production. A query declared with `Query.define` is answered
489
- * by running its body over the rows with the reference interpreter, the one
490
- * every interpreter is held to by the conformance suite. A query with no body
491
- * has nothing to run and is refused when the backend is made, unless `queries`
492
- * supplies a source for it. Mutations are yours to give: each one writes
493
- * through the store it is handed, and the next read sees the change.
494
- *
495
- * Every field of every row is readable unless `authorize` names the entity:
496
- * then its function decides, per principal, as `RemoteServer.entity`'s does.
497
- * `entities` adds Sources for entities no row backs, which the domain must not
498
- * declare. The `layer` answers as `principal`, and is absent without one
499
- * (unless `P` admits `undefined`); `server` answers as any. It does not push
500
- * live changes. It is not a server to deploy.
501
- */
502
- declare function memory<P = undefined>(config: MemoryConfig<P> & MemoryAnswering<P>): MemoryBackend<P>;
503
- declare function memory<P = undefined>(config: MemoryConfig<P>): MemoryServed<P>;
504
- export declare const RemoteServer: {
505
- /** A backend held in memory, for a first run, a test or a demo. See `memory`. */
506
- memory: typeof memory;
507
- /** A mutation outcome's report that `ref` now heads the connection. */
508
- prepend: (connection: ConnectionIdentity, ref: {
509
- readonly entity: string;
510
- readonly id: string;
511
- }) => ConnectionChange;
512
- /** A mutation outcome's report that `ref` now ends the connection. */
513
- append: (connection: ConnectionIdentity, ref: {
514
- readonly entity: string;
515
- readonly id: string;
516
- }) => ConnectionChange;
517
- /** A mutation outcome's report that `ref` left the connection. */
518
- remove: (connection: ConnectionIdentity, ref: {
519
- readonly entity: string;
520
- readonly id: string;
521
- }) => ConnectionChange;
522
- /**
523
- * An entity source. Given the Entity, every member it declares (fields,
524
- * relations, derived members) may be requested; given anything with a
525
- * `name` and `fields`, those fields. A request for anything else never
526
- * reaches `read` or `authorize`. Given only a `name`, every field passes.
527
- */
528
- entity: <P = unknown, R = never>(entity: EntityName, options: {
529
- readonly read: EntitySource<P, R>['read'];
530
- readonly authorize?: EntitySource<P, R>['authorize'];
531
- readonly filter?: EntitySource<P, R>['filter'];
532
- /** See `EntitySource.shared`: each must be a member the source serves. */
533
- readonly shared?: ReadonlyArray<string> | undefined;
534
- }) => EntitySource<P, R>;
535
- mutation: <P = unknown, R = never, Name extends string = string, Input = unknown, Output = unknown, Refused = unknown>(mutation: MutationDescriptor<Name, Input, Output, Refused>, run: (context: {
536
- readonly input: Input;
537
- readonly principal: P;
538
- /** The client's id for this request, unique within that client only. */
539
- readonly requestId: string;
540
- /** The operation's identity across clients, for a record of the write; see `MutationSource`. */
541
- readonly operation: Option.Option<string>;
542
- }) => Effect.Effect<MutationOutcome<Output>, RemoteServerError | MutationRefused | RemoteForbidden, R>) => MutationSource<P, R>;
543
- /**
544
- * A refusal of `mutation`, as a value of its declared `Refusal`: fail a
545
- * Source with it (`yield* RemoteServer.refuse(SavePost, { _tag: 'Field', ... })`)
546
- * and the client reads it, decoded, with `Data.refusal`. `message` is what a
547
- * person reads, beside it.
548
- */
549
- refuse: <Refused>(mutation: MutationDescriptor<string, any, any, Refused>, refusal: NoInfer<Refused>, message?: string) => MutationRefused;
550
- /**
551
- * A writer's refusal of a row that does not hold the write's `when`: fail
552
- * `update` or `delete` with it (`yield* RemoteServer.unmet()`), and
553
- * `RemoteServer.write` answers the mutation's `Unmet` refusal.
554
- */
555
- unmet: (message?: string) => RemoteUnmet;
556
- /**
557
- * A writer's refusal of a row that would break an invariant: fail `update`
558
- * or `insert` with it, naming the invariant's id and path when the caller
559
- * may be told them, and `RemoteServer.write` answers the mutation's
560
- * `Invalid` refusal.
561
- */
562
- invalid: (message: string, rule?: Option.Option<string>, path?: ReadonlyArray<string>) => RemoteInvalid;
563
- /**
564
- * A refusal of who is asking: fail a Source with it
565
- * (`yield* RemoteServer.forbid()`) and the write never runs. `reason`, when
566
- * given, is what the person who asked reads; without it the refusal says
567
- * nothing of why. `answer` sends it as a 403, and the client's mutation
568
- * fails with `_tag: 'Forbidden'`.
569
- */
570
- forbid: (reason?: string) => RemoteForbidden;
571
- /**
572
- * A refusal of a caller who could not be told: a `serveFetch` or
573
- * `defineDocumentHost` resolver fails with it (`RemoteServer.unauthenticated()`)
574
- * when the credential it was sent no longer holds. It answers 401, with
575
- * `reason`, when given, for the person who asked.
576
- */
577
- unauthenticated: (reason?: string) => RemoteUnauthenticated;
578
- /**
579
- * The Source of a mutation that is a declared `Write`, with no handler: the
580
- * input bound to the write lands through `writer`, and the row as written
581
- * answers as a patch (a deletion as `deleted`). An update writes only the
582
- * keys the client named, when it named some, and fails for a row that is not
583
- * there; an insert of an id already holding what it writes (a retry)
584
- * answers with that row, and of one holding anything else fails; a delete of
585
- * a row already gone succeeds. A row that moved past the revision the write
586
- * `expect`s is refused as a conflict, and one that does not hold its `when`
587
- * as unmet; a write with a `when` needs a writer that checks it
588
- * (`preconditions`), and is refused here without one.
589
- */
590
- write: <P = unknown, R = never, Name extends string = string, Input = unknown, Refused extends {
591
- readonly _tag: 'Conflict' | 'Unmet' | 'Invalid';
592
- } = {
593
- readonly _tag: 'Conflict';
594
- }>(mutation: MutationDescriptor<Name, Input, {}, Refused> & {
595
- readonly write: AnyWrite;
596
- }, writer: EntityWriter<P, R>) => MutationSource<P, R>;
597
- query: <P = unknown, R = never, Input = unknown>(query: QueryDescriptor<string, Input, unknown>, run: (context: {
598
- readonly input: Input;
599
- readonly window: QueryWindow;
600
- readonly principal: P;
601
- readonly select?: RelationRequirement | undefined;
602
- }) => Effect.Effect<QueryPage, RemoteServerError, R>) => QuerySource<P, R>;
603
- /** Streams live entity patches for a client's live requirements. */
604
- live: <P = unknown, R = never>(entity: EntityName, options: {
605
- readonly subscribe: LiveSource<P, R>['subscribe'];
606
- }) => LiveSource<P, R>;
607
- /**
608
- * A `LiveHub` over entity sources. Pass it to `handlers` as `live`, and every
609
- * mutation's answered patches and deletions are published to it; call
610
- * `hub.changed(ref, fields)` yourself only for a write that is not a
611
- * mutation (a database trigger, a job). Each subscriber that selects any of
612
- * those fields receives them, re-read through the entity source under its
613
- * own principal.
614
- */
615
- liveHub: typeof liveHub;
616
- make: <P = unknown, R = never>(config: {
617
- readonly entities: readonly EntitySource<P, R>[];
618
- readonly mutations?: readonly MutationSource<P, R>[];
619
- readonly queries?: readonly QuerySource<P, R>[];
620
- readonly live?: readonly LiveSource<P, R>[];
621
- }) => ServerDefinition<P, R>;
622
- /**
623
- * Checks every source name against the declared domain, so an undeclared
624
- * entity/query/mutation fails at startup rather than returning nothing at
625
- * call time.
626
- */
627
- validate: (domain: RemoteDescriptor, server: ServerDefinition<any, any>) => void;
628
- /**
629
- * Reads entity requirements through the entity sources, level by level,
630
- * following relations as `FoldkitRemoteRead` does. Shared by the read
631
- * handler and the query handler's payload: a query page's items are just
632
- * requirements the page names, so one response carries both.
633
- */
634
- readHelper: <P, R>(server: ServerDefinition<P, R>, principal: P, options: HandlerOptions<P, R>, requests: ReadonlyArray<Requirement>) => Effect.Effect<{
635
- readonly entities: Array<{
636
- readonly entity: string;
637
- readonly id: string;
638
- readonly values: Record<string, unknown>;
639
- }>;
640
- readonly settled: Array<{
641
- readonly entity: string;
642
- readonly id: string;
643
- readonly fields: Array<string>;
644
- }>;
645
- }, RemoteReadError, R>;
646
- /**
647
- * Answers one JSON request through `handlers`: what an HTTP endpoint, a
648
- * worker or a server in the page calls with the body it received, parsed.
649
- * The request and its payload are decoded by the protocol's own schemas
650
- * before a handler sees them, so an operation name is one of Remote's three
651
- * and nothing else. A body that is not a request is a 400; a caller who
652
- * could not be told a 401; a refusal of who is asking a 403; a handler's
653
- * failure a 500 with its message; a defect a 500 that says nothing of it.
654
- * `Remote.json` and `Remote.http` are the other end.
655
- */
656
- answer: <R>(handlers: RemoteRpcClient<R>, body: unknown) => Effect.Effect<{
657
- readonly status: 200 | 400 | 401 | 403 | 422 | 500;
658
- readonly body: RemoteJsonAnswer;
659
- }, never, R>;
660
- /**
661
- * Compiles the server into Remote's RPC handlers, answering as `principal`:
662
- * a value, or a Context key (`G.Principal`) read on each call, which
663
- * authentication provides per request. Unknown entities, entities with no
664
- * allowed fields, and unknown mutations return an error or nothing rather
665
- * than leaking existence.
666
- */
667
- handlers: <P, R, I = never>(server: ServerDefinition<P, R>, principal: P | Context.Key<I, P>, options?: HandlerOptions<P, R>) => RemoteRpcClient<R | I>;
668
- };
669
- export { QueryEvaluateError, type Row, assertSupported, evaluate, supported };
670
- //# sourceMappingURL=index.d.mts.map
1
+ import { A as WriteRequirement, B as assertSupported, C as RemoteInvalid, D as RemoteUnmet, E as RemoteTaken, F as PublishFailed, H as supported, I as RemoteServerDiagnostic, L as ServerDefect, M as exprContext, N as AnswerUnread, O as RowRequirement, P as ClockSkewed, R as QueryEvaluateError, S as ReadPlan, T as RemoteServerError, V as evaluate, _ as MutationOutcome, a as EntityWriter, b as QueryPage, c as LiveQuery, d as MemoryBackend, f as MemoryConfig, g as MemoryStore, h as MemoryServed, i as EntitySourceContext, j as WriteWhen, k as ServerDefinition, l as LiveSource, m as MemoryRows, n as EntityRecord, o as HandlerOptions, p as MemoryReadable, r as EntitySource, s as LiveHub, t as ConnectionChange, u as MemoryAnswering, v as MutationRefused, w as RemoteServer, x as QuerySource, y as MutationSource, z as Row } from "./index-BnaRbvjr.mjs";
2
+ export { type AnswerUnread, type ClockSkewed, ConnectionChange, EntityRecord, EntitySource, EntitySourceContext, EntityWriter, HandlerOptions, LiveHub, LiveQuery, LiveSource, MemoryAnswering, MemoryBackend, MemoryConfig, MemoryReadable, MemoryRows, MemoryServed, MemoryStore, MutationOutcome, MutationRefused, MutationSource, type PublishFailed, QueryEvaluateError, QueryPage, QuerySource, ReadPlan, RemoteInvalid, RemoteServer, type RemoteServerDiagnostic, RemoteServerError, RemoteTaken, RemoteUnmet, type Row, RowRequirement, type ServerDefect, ServerDefinition, WriteRequirement, WriteWhen, assertSupported, evaluate, exprContext, supported };
package/dist/index.mjs CHANGED
@@ -1 +1 @@
1
- export { t as MutationRefused, o as QueryEvaluateError, n as RemoteInvalid, r as RemoteServer, i as RemoteServerError, a as RemoteUnmet, s as assertSupported, c as evaluate, l as supported } from "./src-yDMwdGiL.mjs";
1
+ export { t as MutationRefused, l as QueryEvaluateError, n as RemoteInvalid, r as RemoteServer, i as RemoteServerError, a as RemoteTaken, o as RemoteUnmet, s as RowRequirement, u as assertSupported, d as evaluate, c as exprContext, f as supported } from "./src-ZV9pARkU.mjs";