foldkit-remote 0.11.0 → 0.12.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,3493 +1,2 @@
1
- import { Context, Duration, Effect, Layer, Option, Result, Schema, Stream } from "effect";
2
- import * as Domain from "foldkit-entity";
3
- import { AnyEntity, AnyQuery, Dependencies, InputExpr, Query as Query$1 } from "foldkit-entity";
4
- import { Command } from "foldkit/command";
5
- import { EntryWithoutKeepAlive } from "foldkit/subscription";
6
- import { ActiveSurface, Contract, Invalid, Metadata, ModelRef, Projection, Surface, Wiring } from "foldkit-surface";
7
- import { Rpc, RpcClientError, RpcGroup } from "effect/rpc";
8
- import { KeyValueStore } from "effect/persistence";
9
- import * as Update from "foldkit/update";
10
- //#region ../metadata/src/index.d.ts
11
- /** Marks a `Metadata` value. Its entries are private to this module. */
12
- declare const MetadataTypeId: unique symbol;
13
- type MetadataTypeId = typeof MetadataTypeId;
14
- /**
15
- * Declarative facts an interpreter attaches to a node it does not own, such as
16
- * the server data a Remote selection needs. The carrier holds and combines
17
- * them without knowing what they mean; a package reads only the key it owns.
18
- *
19
- * Opaque: only a key's `of` and `Metadata.combine` make one, so entries cannot
20
- * be forged past a key's type or `merge`, and they are frozen.
21
- */
22
- interface Metadata$1 {
23
- readonly [MetadataTypeId]: MetadataTypeId;
24
- }
25
- /**
26
- * An interpreter's typed slot in `Metadata`. Lookup is by the key object, never
27
- * its `name`, so two packages cannot collide by choosing the same string.
28
- */
29
- interface MetadataKey<A> {
30
- /** For tooling output only. */
31
- readonly name: string;
32
- /** Normalizes the entries gathered from combined values, e.g. unioning duplicates. */
33
- readonly merge: (values: ReadonlyArray<A>) => ReadonlyArray<A>;
34
- /** One line per entry for tooling output. */
35
- readonly summarize: (value: A) => string;
36
- readonly of: (...values: ReadonlyArray<A>) => Metadata$1;
37
- readonly get: (metadata: Metadata$1) => ReadonlyArray<A>;
38
- }
39
- /** One key's entries as serializable text, named by the key. */
40
- interface MetadataSummary {
41
- readonly name: string;
42
- readonly entries: readonly string[];
43
- }
44
- declare const Metadata$1: {
45
- /**
46
- * Declares an interpreter's slot. Call once per package, at module level:
47
- * entries are found by the key object, so two copies of a package (a
48
- * duplicated install, a reloaded module) do not see each other's entries.
49
- */
50
- key: <A>(name: string, options: {
51
- readonly merge: (values: ReadonlyArray<A>) => ReadonlyArray<A>;
52
- readonly summarize: (value: A) => string;
53
- }) => MetadataKey<A>;
54
- empty: Metadata$1;
55
- /** True only for a value this module made; a copy or a hand-built brand is not one. */
56
- is: (value: unknown) => value is Metadata$1;
57
- /** Gathers every part's entries and runs each key's `merge` over its group. */
58
- combine: (parts: ReadonlyArray<Metadata$1>) => Metadata$1;
59
- summarize: (metadata: Metadata$1) => readonly MetadataSummary[];
60
- };
61
- //#endregion
62
- //#region src/connection.d.ts
63
- export interface EdgeRef {
64
- readonly entity: string;
65
- readonly id: string;
66
- }
67
- /** `key` is the edge identity used for de-duplication. */
68
- export interface Edge {
69
- readonly key: string;
70
- readonly ref: EdgeRef;
71
- }
72
- export declare const edge: (ref: EdgeRef, key?: string) => Edge;
73
- export type Cursor = string;
74
- export type Boundary = {
75
- readonly _tag: 'Terminal';
76
- } | {
77
- readonly _tag: 'Cursor';
78
- readonly cursor: Cursor;
79
- } | {
80
- readonly _tag: 'Unknown';
81
- };
82
- export declare const terminal: Boundary;
83
- export declare const unknown: Boundary;
84
- export declare const cursor: (value: Cursor) => Boundary;
85
- export interface Segment {
86
- readonly edges: readonly Edge[];
87
- readonly start: Boundary;
88
- readonly end: Boundary;
89
- }
90
- export interface Connection {
91
- readonly segments: readonly Segment[];
92
- readonly stale: boolean;
93
- }
94
- export declare const emptyConnection: Connection;
95
- export declare const segment: (edges: readonly Edge[], start: Boundary, end: Boundary) => Segment;
96
- /** Adds a page to the connection, joining contiguous or overlapping segments. */
97
- export declare const merge: (current: Connection, page: Segment) => Connection;
98
- /** Visible edges, segment by segment. */
99
- export declare const items: (connection: Connection) => ReadonlyArray<Edge>;
100
- /** There is more before the known region. Derived from boundaries, never row count. */
101
- export declare const hasPrevious: (connection: Connection) => boolean;
102
- /** There is more after the known region. Derived from boundaries, never row count. */
103
- export declare const hasNext: (connection: Connection) => boolean;
104
- /** A connection with more than one segment has an explicit unknown gap. */
105
- export declare const isGapped: (connection: Connection) => boolean;
106
- //#endregion
107
- //#region src/remoteData.d.ts
108
- export interface RemoteError {
109
- readonly _tag: string;
110
- readonly message: string;
111
- }
112
- export type RemoteData<A> = {
113
- readonly _tag: 'Initial';
114
- } | {
115
- readonly _tag: 'Loading';
116
- } | {
117
- readonly _tag: 'Ready';
118
- readonly value: A;
119
- } | {
120
- readonly _tag: 'Refreshing';
121
- readonly value: A;
122
- } | {
123
- readonly _tag: 'Failed';
124
- readonly error: RemoteError;
125
- readonly previous?: A;
126
- } | {
127
- readonly _tag: 'NotFound';
128
- };
129
- /**
130
- * What `RemoteData.render` tells the `data` branch about the value it is
131
- * given: whether a newer answer is on its way, and whether this one is what
132
- * was last known good before a read failed. It is one tag rather than two
133
- * booleans because a value cannot be both at once, and a type that can say so
134
- * invites a view to handle a state that never arrives.
135
- */
136
- export type Freshness = {
137
- readonly _tag: 'Fresh';
138
- } | {
139
- readonly _tag: 'Refreshing';
140
- } | {
141
- readonly _tag: 'Stale';
142
- readonly error: RemoteError;
143
- };
144
- export declare const remoteErrorSchema: Schema.Struct<{
145
- readonly _tag: Schema.String;
146
- readonly message: Schema.String;
147
- }>;
148
- export declare const remoteDataSchema: <A>(value: Schema.Schema<A>) => Schema.Codec<RemoteData<A>, unknown>;
149
- export declare const RemoteData: {
150
- /**
151
- * The `RemoteData` schema for a value schema. Exposed so a `RemoteData` can
152
- * be embedded in a hand-written Model schema, not only through `Remote.select`.
153
- */
154
- schema: <A>(value: Schema.Schema<A>) => Schema.Schema<RemoteData<A>>;
155
- /** Exhaustive: omitting a state is a compile error. */
156
- match: <A, R>(data: RemoteData<A>, cases: {
157
- readonly Initial: () => R;
158
- readonly Loading: () => R;
159
- readonly Ready: (value: A) => R;
160
- readonly Refreshing: (value: A) => R;
161
- readonly Failed: (error: RemoteError, previous: Option.Option<A>) => R;
162
- readonly NotFound: () => R;
163
- }) => R;
164
- /**
165
- * The view-oriented fold: the six states as the three things a view actually
166
- * draws, under the policy that useful data stays on screen. A value that is
167
- * being refetched, or that a later read failed to replace, still reaches
168
- * `data` — with `freshness` saying which — instead of being replaced by a
169
- * spinner or an error the reader cannot act on.
170
- *
171
- * ```ts
172
- * RemoteData.render(model.user, {
173
- * loading: () => UserSkeleton(),
174
- * notFound: () => NoSuchUser(),
175
- * failed: error => ErrorView(error),
176
- * data: (user, freshness) => UserView({ user, dimmed: freshness._tag !== 'Fresh' }),
177
- * })
178
- * ```
179
- *
180
- * `notFound` is its own branch and not optional: a row the server answered
181
- * for and does not have is neither loading nor a failure, and drawing it as
182
- * either is a spinner that never ends or an error nobody can fix.
183
- *
184
- * This does not replace `match`, which is the exhaustive fold over the states
185
- * themselves. Reach for `match` when the six states really do draw
186
- * differently, and for this when they draw the usual three ways.
187
- */
188
- render: <A, R>(data: RemoteData<A>, cases: {
189
- readonly loading: () => R;
190
- readonly notFound: () => R;
191
- readonly failed: (error: RemoteError) => R;
192
- readonly data: (value: A, freshness: Freshness) => R;
193
- }) => R;
194
- map: <A, B>(data: RemoteData<A>, f: (value: A) => B) => RemoteData<B>;
195
- };
196
- //#endregion
197
- //#region src/store.d.ts
198
- export type EntityKey = string;
199
- export interface EntityEntry {
200
- readonly values: Readonly<Record<string, unknown>>;
201
- readonly present: ReadonlySet<string>;
202
- /** Present fields whose value may be outdated (revalidation needed). */
203
- readonly stale: ReadonlySet<string>;
204
- /**
205
- * Fields the server settled without a value: asked for, and answered without
206
- * them, whatever the reason. Not planned again until a refresh asks; a later
207
- * write of the field clears it.
208
- */
209
- readonly unavailable: ReadonlySet<string>;
210
- /** The entity is known to be absent; a later write clears this. */
211
- readonly tombstone: boolean;
212
- /** Injected clock reading of the last write; never read from ambient state. */
213
- readonly updatedAt: number;
214
- /**
215
- * The canonical window each present field was fetched with (`""` for none).
216
- * A later request with a *known, different* window is planned as missing.
217
- */
218
- readonly windows: Readonly<Record<string, string>>;
219
- }
220
- export type EntityStore = Readonly<Record<EntityKey, EntityEntry>>;
221
- /** The separator keeps an untrusted id from colliding with a prototype key. */
222
- export declare const entityKey: (entity: string, id: string) => EntityKey;
223
- export declare const emptyStore: EntityStore;
224
- export interface EntityWrite {
225
- readonly key: EntityKey;
226
- readonly values: Readonly<Record<string, unknown>>;
227
- /** The canonical window each written relation field was fetched with. */
228
- readonly windows?: Readonly<Record<string, string>> | undefined;
229
- /** When this write dates the entity, instead of the batch's `now`. */
230
- readonly updatedAt?: number | undefined;
231
- }
232
- /**
233
- * Merges known values into many entities, copying the store once. Every
234
- * written field becomes present and non-stale; a tombstone is cleared because
235
- * the entity is evidently not absent.
236
- */
237
- export declare const writeEntities: (store: EntityStore, writes: ReadonlyArray<EntityWrite>, now?: number) => EntityStore;
238
- /** `writeEntities` for one entity. */
239
- export declare const writeEntity: (store: EntityStore, key: EntityKey, values: Readonly<Record<string, unknown>>, now?: number, windows?: Readonly<Record<string, string>>) => EntityStore;
240
- /**
241
- * Marks present fields stale (`true`) or ends their staleness (`false`) across
242
- * many entities, copying the store once. A field never present stays missing;
243
- * an unknown entity is left alone.
244
- */
245
- export declare const setStale: (store: EntityStore, marks: ReadonlyArray<readonly [key: EntityKey, fields: Iterable<string>]>, stale: boolean) => EntityStore;
246
- /** Marks present fields stale; fields that were never present stay missing. */
247
- export declare const markStale: (store: EntityStore, key: EntityKey, fields: Iterable<string>) => EntityStore;
248
- /** Ends a refresh that did not land: the fields are present again as they were. */
249
- export declare const clearStale: (store: EntityStore, key: EntityKey, fields: Iterable<string>) => EntityStore;
250
- /**
251
- * Records fields the server settled without a value. A present field is left
252
- * as it is: the answer that settled it was not about the value it holds.
253
- * `false` forgets the marks, which is how a refresh asks again.
254
- */
255
- export declare const setUnavailable: (store: EntityStore, marks: ReadonlyArray<readonly [key: EntityKey, fields: Iterable<string>]>, unavailable: boolean) => EntityStore;
256
- /** Whether the server settled this field without a value, and nothing has written it since. */
257
- export declare const isFieldUnavailable: (store: EntityStore, key: EntityKey, field: string) => boolean;
258
- /** Records that the entity is known to be absent, so it is not refetched. */
259
- export declare const tombstone: (store: EntityStore, key: EntityKey) => EntityStore;
260
- /** Forgets everything known about the entity, including a tombstone. */
261
- export declare const remove: (store: EntityStore, key: EntityKey) => EntityStore;
262
- export declare const entry: (store: EntityStore, key: EntityKey) => Option.Option<EntityEntry>;
263
- export declare const isTombstone: (store: EntityStore, key: EntityKey) => boolean;
264
- /** A field is known only if it is present and not stale. */
265
- export declare const hasField: (store: EntityStore, key: EntityKey, field: string) => boolean;
266
- /** A present field whose value may be outdated; absent fields are not stale. */
267
- export declare const isFieldStale: (store: EntityStore, key: EntityKey, field: string) => boolean;
268
- /**
269
- * Reads a present field, stale or not. Absence and a tombstone both yield
270
- * `Option.none()`; a present `undefined`/`null` yields `Option.some`.
271
- */
272
- export declare const readField: (store: EntityStore, key: EntityKey, field: string) => Option.Option<unknown>;
273
- /**
274
- * The fields the planner must fetch. A tombstone makes every field known
275
- * (absent), so it returns an empty list and the entity is not refetched, and a
276
- * field the server settled without a value is known the same way. A
277
- * requested window that differs from the one a field was fetched with also
278
- * marks it missing, but only when the stored window is known (never `""`), so a
279
- * writer that does not record windows cannot cause a refetch loop.
280
- */
281
- export declare const missingFields: (store: EntityStore, key: EntityKey, fields: Iterable<string>, windows?: Readonly<Record<string, string>>) => ReadonlyArray<string>;
282
- //#endregion
283
- //#region src/mutation.d.ts
284
- export interface NormalizedPatch {
285
- readonly entity: string;
286
- readonly id: string;
287
- readonly values: Readonly<Record<string, unknown>>;
288
- }
289
- export interface MutationState {
290
- readonly pending: ReadonlySet<string>;
291
- readonly applied: ReadonlySet<string>;
292
- readonly failed: ReadonlySet<string>;
293
- /** Why each request in `failed` failed, kept exactly as long as `failed` keeps its id. */
294
- readonly errors: ReadonlyMap<string, RemoteError>;
295
- /**
296
- * How many mutations this model has started. A bound domain takes its next
297
- * request id from here, so `update` stays pure and the id exists before the
298
- * Command runs.
299
- */
300
- readonly sequence: number;
301
- }
302
- export declare const emptyMutationState: MutationState;
303
- export declare const beginMutation: (state: MutationState, requestId: string) => MutationState;
304
- export declare const failMutation: (state: MutationState, requestId: string, error: RemoteError) => MutationState;
305
- /** What Remote knows of one mutation request, by the id `mutate` returned. */
306
- export type MutationStatus =
307
- /** Never started here, or settled so long ago its id has left the window. */
308
- {
309
- readonly _tag: 'Unknown';
310
- } | {
311
- readonly _tag: 'Pending';
312
- } | {
313
- readonly _tag: 'Applied';
314
- } | {
315
- readonly _tag: 'Failed';
316
- readonly error: RemoteError;
317
- };
318
- export declare const mutationStatus: (state: MutationState, requestId: string) => MutationStatus;
319
- export interface Reconciled {
320
- readonly store: EntityStore;
321
- readonly state: MutationState;
322
- }
323
- /** What a settled mutation wrote, as `MutationSucceeded` carries it. */
324
- export interface MutationAnswer {
325
- readonly entities: ReadonlyArray<NormalizedPatch>;
326
- /** Entities the mutation deleted; each is tombstoned. */
327
- readonly deleted?: ReadonlyArray<{
328
- readonly entity: string;
329
- readonly id: string;
330
- }> | undefined;
331
- /** Injected clock reading of the answer, which dates what it writes. */
332
- readonly now: number;
333
- }
334
- /**
335
- * Applies a mutation result once and marks the request settled. A second call
336
- * with the same `requestId` (a retry, or a live event describing the same change)
337
- * does not re-apply the entities, but still clears `pending`.
338
- */
339
- export declare const reconcileMutation: (store: EntityStore, state: MutationState, requestId: string, answer: MutationAnswer) => Reconciled;
340
- /** A mutation an application declares: its name and input/output codecs. */
341
- export interface MutationDescriptor<Name extends string, Input, Output> {
342
- readonly name: Name;
343
- readonly Input: Schema.Codec<Input>;
344
- readonly Output: Schema.Codec<Output>;
345
- }
346
- /** A codec, or the fields of a `Schema.Struct` where one is expected. */
347
- export type SchemaOrFields = Schema.Codec<any, any, any, any> | Schema.Struct.Fields;
348
- /** The decoded type of a codec, or of the Struct the fields describe. */
349
- export type TypeOf<S extends SchemaOrFields> = S extends Schema.Codec<infer T, any, any, any> ? T : S extends Schema.Struct.Fields ? Schema.Struct.Type<S> : never;
350
- /** The codec itself, or a `Schema.Struct` over the fields. */
351
- export declare const schemaOf: <S extends SchemaOrFields>(shape: S) => Schema.Codec<TypeOf<S>>;
352
- export declare const Mutation: {
353
- /**
354
- * Declares a mutation. `Input` and `Output` are codecs, or the fields of the
355
- * `Schema.Struct` they would be (`{ id: ProjectId, name: Schema.String }`).
356
- */
357
- make: <const Name extends string, Input extends SchemaOrFields, Output extends SchemaOrFields>(name: Name, config: {
358
- readonly Input: Input;
359
- readonly Output: Output;
360
- }) => MutationDescriptor<Name, TypeOf<Input>, TypeOf<Output>>;
361
- };
362
- //#endregion
363
- //#region src/query.d.ts
364
- export type LiveInsertion = 'visible' | 'boundary' | 'invalidate' | 'ignore';
365
- export interface LivePolicy {
366
- readonly prepend?: LiveInsertion;
367
- readonly append?: LiveInsertion;
368
- }
369
- export interface ConnectionSpec<Entity extends string = string> {
370
- readonly entity: Entity;
371
- readonly edgeKey?: Schema.Schema<unknown>;
372
- readonly live?: LivePolicy;
373
- }
374
- export interface QueryWindow {
375
- readonly first?: number | undefined;
376
- readonly last?: number | undefined;
377
- readonly after?: Cursor | undefined;
378
- readonly before?: Cursor | undefined;
379
- }
380
- export interface QueryRef<Name extends string, Input> {
381
- readonly query: Name;
382
- readonly input: Input;
383
- /** The input codec, so a `QueryRef` can encode itself without its descriptor. */
384
- readonly Input: Schema.Codec<Input>;
385
- readonly window: QueryWindow;
386
- /** Connection identity: descriptor + canonical input, excluding the window. */
387
- readonly identity: string;
388
- }
389
- export interface QueryDescriptor<Name extends string, Input, Result> {
390
- readonly name: Name;
391
- readonly Input: Schema.Codec<Input>;
392
- readonly Result: Result;
393
- readonly ref: (input: Input) => QueryRef<Name, Input>;
394
- /**
395
- * What the query means, when it was declared with `Query.define`: the rows it
396
- * is about, as a value an interpreter can compile. A descriptor from
397
- * `Query.make` has none — its meaning lives in whatever the server registered
398
- * to answer it — and a source is free to answer either.
399
- */
400
- readonly body?: AnyQuery | undefined;
401
- }
402
- /**
403
- * The inputs of a definition's body: one placeholder per key of `Input`, typed
404
- * as that key's value. A body is built once, so these stand for what the query
405
- * will be given rather than being it.
406
- */
407
- export type QueryInputs<Input> = { readonly [K in keyof Input & string]: InputExpr<Input[K]>; };
408
- /**
409
- * What separates a query's name from its canonical encoded input in a
410
- * connection identity.
411
- *
412
- * NUL, because `JSON.stringify` escapes it inside a string (`\u0000`) and a
413
- * query name is a TypeScript identifier — so the first occurrence is always the
414
- * boundary, and a name or an input value cannot forge one. Anything recovering
415
- * the query from an identity splits here.
416
- */
417
- export declare const IDENTITY_SEPARATOR = "\0";
418
- /** Stable stringify: object keys sorted, undefined-valued keys dropped, so equal inputs encode equally. */
419
- export declare const stableStringify: (value: unknown) => string;
420
- /**
421
- * `Result: Project` (or anything with the entity's `name`, as `Query.connection`
422
- * takes) means a connection over it; a `ConnectionSpec` names its `entity`
423
- * instead and is the result as given.
424
- */
425
- export type ResultOf<Result> = Result extends {
426
- readonly name: infer Entity extends string;
427
- } ? ConnectionSpec<Entity> : Result;
428
- /** A relational `Query` over one Entity, as `Query.define`'s body returns. */
429
- type RelationalQueryOf<E extends AnyEntity> = ReturnType<typeof Query$1.from<E>>;
430
- export declare const Query: {
431
- /** Declares the entity and options a query's result is a connection over. */
432
- connection: <Entity extends string>(entity: {
433
- readonly name: Entity;
434
- }, options?: {
435
- readonly edgeKey?: Schema.Schema<unknown>;
436
- readonly live?: LivePolicy;
437
- }) => ConnectionSpec<Entity>;
438
- /**
439
- * Declares a query. `Input` is a codec or the fields of the `Schema.Struct` it
440
- * would be; `Result` is a `Query.connection(...)`, or the entity the result is
441
- * a connection over.
442
- */
443
- make: <const Name extends string, Input extends SchemaOrFields, Result>(name: Name, config: {
444
- readonly Input: Input;
445
- readonly Result: Result;
446
- }) => QueryDescriptor<Name, TypeOf<Input>, ResultOf<Result>>;
447
- /**
448
- * Declares a query by what it means. The body is built once, here, and the
449
- * `input` it is given holds placeholders rather than values — there is
450
- * nothing yet to branch on, so a condition that depends on what was passed is
451
- * a comparison over the placeholder:
452
- *
453
- * ```ts
454
- * const PostsBySlug = Query.define('PostsBySlug', { slug: Schema.String }, ({ input }) =>
455
- * Query.from(Post).pipe(
456
- * Query.where(Expr.eq(Post.fields.slug, input.slug)),
457
- * Query.orderBy(Order.asc(Post.fields.id)),
458
- * ),
459
- * )
460
- * ```
461
- *
462
- * What comes back is an ordinary `QueryDescriptor` — the same name, `Input`,
463
- * `ref` and connection identity `Query.make` gives — carrying its `body`
464
- * besides. A server can compile that body instead of being told the same
465
- * thing again in its own dialect, and one that would rather answer the query
466
- * its own way still can.
467
- *
468
- * The result is a connection over the Entity the body reads, so it is not
469
- * named twice.
470
- */
471
- define: <const Name extends string, Input extends SchemaOrFields, E extends AnyEntity>(name: Name, Input: Input, body: (context: {
472
- readonly input: QueryInputs<TypeOf<Input>>;
473
- }) => RelationalQueryOf<E>, options?: {
474
- readonly edgeKey?: Schema.Schema<unknown>;
475
- readonly live?: LivePolicy;
476
- }) => QueryDescriptor<Name, TypeOf<Input>, ConnectionSpec<E["name"]>>;
477
- first: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
478
- last: (count: number) => <R extends QueryRef<string, unknown>>(ref: R) => R;
479
- after: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
480
- before: (cursor: Cursor) => <R extends QueryRef<string, unknown>>(ref: R) => R;
481
- from: <E extends AnyEntity>(entity: E) => Query$1<E>;
482
- where: (...predicates: ReadonlyArray<import("foldkit-entity").Predicate>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
483
- orderBy: (...terms: ReadonlyArray<import("foldkit-entity").OrderTerm>) => <E extends AnyEntity>(self: Query$1<E>) => Query$1<E>;
484
- dependencies: (self: AnyQuery) => import("foldkit-entity").Dependencies;
485
- unsupported: (self: AnyQuery, supported: ReadonlyArray<import("foldkit-entity").Operation>) => ReadonlyArray<import("foldkit-entity").Operation>;
486
- show: (self: AnyQuery) => string;
487
- };
488
- //#endregion
489
- //#region src/requirement.d.ts
490
- /**
491
- * The slice required of an entity. `windows` carries a pagination window per
492
- * relation field, and `relations` the slice required of each relation's
493
- * target, so one requirement describes a whole selection graph.
494
- */
495
- export interface RelationRequirement {
496
- readonly entity: string;
497
- readonly fields: readonly string[];
498
- readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
499
- readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
500
- }
501
- export interface Requirement extends RelationRequirement {
502
- readonly id: string;
503
- /** The projection also subscribes to changes of this entity (`Data.live`). */
504
- readonly live?: boolean | undefined;
505
- }
506
- /**
507
- * A query connection a projection reads: the page it first asks for and the
508
- * slice it selects of each item. `identity` is the connection's (query plus
509
- * canonical input, excluding the window).
510
- */
511
- export interface ConnectionRequirement {
512
- readonly identity: string;
513
- readonly window: QueryWindow;
514
- readonly select: RelationRequirement;
515
- }
516
- /**
517
- * Merges connection requirements for the same connection and window into one,
518
- * unioning what they select of each item; the first keeps its other properties.
519
- */
520
- declare function mergeConnections(connections: readonly ConnectionRequirement[]): readonly ConnectionRequirement[];
521
- /** Unions two relation slices for the same target: fields, windows, and nested relations. */
522
- declare function mergeRelation(current: RelationRequirement, next: RelationRequirement): RelationRequirement;
523
- /** Unions requirements for the same entity + id, dropping duplicate fields. */
524
- declare function mergeRequirements(requirements: readonly Requirement[]): readonly Requirement[];
525
- /**
526
- * Requirement helpers, for the packages that plan and serve requirements.
527
- * `merge` unions same-entity+id requirements; `mergeRelation` unions two
528
- * slices of one target (fields, windows, nested relations).
529
- */
530
- export declare const Requirement: {
531
- merge: typeof mergeRequirements;
532
- mergeRelation: typeof mergeRelation;
533
- mergeConnections: typeof mergeConnections;
534
- };
535
- /** Remote's entity requirements on a Projection, unioned per entity and id as nodes compose. */
536
- export declare const RemoteRequirements: MetadataKey<Requirement>;
537
- /** Remote's query connections on a Projection, unioned per connection and window. */
538
- export declare const RemoteConnections: MetadataKey<ConnectionRequirement>;
539
- /** The entity requirements a Projection carries. */
540
- export declare const requirementsOf: (projection: {
541
- readonly metadata: Metadata;
542
- }) => ReadonlyArray<Requirement>;
543
- /** The query connections a Projection carries. */
544
- export declare const connectionsOf: (projection: {
545
- readonly metadata: Metadata;
546
- }) => ReadonlyArray<ConnectionRequirement>;
547
- //#endregion
548
- //#region src/optimistic.d.ts
549
- export interface EntityLayer {
550
- readonly id: string;
551
- readonly patches: ReadonlyArray<NormalizedPatch>;
552
- }
553
- /**
554
- * Edges placed outside a connection's server-known region (`prepend`,
555
- * `append`) or hidden from it (`remove`), owned by the request or live event
556
- * that produced them.
557
- */
558
- export interface ConnectionOverlay {
559
- readonly id: string;
560
- readonly connection: string;
561
- readonly edges: ReadonlyArray<Edge>;
562
- readonly position: 'prepend' | 'append' | 'remove';
563
- }
564
- /** A connection change a request makes optimistically or a mutation result confirms. */
565
- export type ConnectionChange = {
566
- readonly _tag: 'Insert';
567
- readonly connection: string;
568
- readonly position: 'prepend' | 'append';
569
- readonly edge: Edge;
570
- } | {
571
- readonly _tag: 'Remove';
572
- readonly connection: string;
573
- readonly edge: Edge;
574
- };
575
- /** What a request changes before the server answers: entity patches and connection changes. */
576
- export type OptimisticOperation = NormalizedPatch | ConnectionChange;
577
- /** A connection, by identity string or by anything that carries one (a `QueryRef`). */
578
- export type ConnectionIdentity = string | {
579
- readonly identity: string;
580
- };
581
- export declare const connectionIdentity: (connection: ConnectionIdentity) => string;
582
- /**
583
- * Constructors for connection changes: what a request shows optimistically
584
- * (`MutateOptions.optimistic`) and what a mutation source reports it made
585
- * (`MutationOutcome.connections`).
586
- */
587
- export declare const ConnectionChange: {
588
- /** Show `ref` at the front of the connection until the request settles. */
589
- prepend: (connection: ConnectionIdentity, ref: {
590
- readonly entity: string;
591
- readonly id: string;
592
- }) => ConnectionChange;
593
- /** Show `ref` at the end of the connection until the request settles. */
594
- append: (connection: ConnectionIdentity, ref: {
595
- readonly entity: string;
596
- readonly id: string;
597
- }) => ConnectionChange;
598
- /** Hide `ref` from the connection until the request settles. */
599
- remove: (connection: ConnectionIdentity, ref: {
600
- readonly entity: string;
601
- readonly id: string;
602
- }) => ConnectionChange;
603
- };
604
- /**
605
- * Applies a request's operations: its patches become one layer and its
606
- * connection changes become overlays, all owned by `requestId` so settling
607
- * removes every one of them together.
608
- */
609
- export declare const beginOptimistic: (optimistic: OptimisticState, requestId: string, operations: ReadonlyArray<OptimisticOperation>) => OptimisticState;
610
- /** Pending entity layers and connection overlays over the base store. */
611
- export interface OptimisticState {
612
- readonly layers: ReadonlyArray<EntityLayer>;
613
- readonly overlays: ReadonlyArray<ConnectionOverlay>;
614
- }
615
- export declare const emptyOptimistic: OptimisticState;
616
- export declare const addLayer: (optimistic: OptimisticState, layer: EntityLayer) => OptimisticState;
617
- export declare const removeLayer: (optimistic: OptimisticState, id: string) => OptimisticState;
618
- export declare const addOverlay: (optimistic: OptimisticState, overlay: ConnectionOverlay) => OptimisticState;
619
- export declare const removeOverlay: (optimistic: OptimisticState, id: string) => OptimisticState;
620
- /**
621
- * Base store with every layer applied in order. Later layers win. A patch is
622
- * not news from the server, so it keeps the date of the value under it; an
623
- * entity only a request holds (a temporary id) is not the server's to age, and
624
- * is dated `Infinity`, so freshness never plans or times it.
625
- */
626
- export declare const visibleStore: (base: EntityStore, optimistic: OptimisticState) => EntityStore;
627
- /**
628
- * A fresh page is newer than any settled overlay it covers: an edge the page
629
- * carries no longer needs an insert overlay, and a `remove` overlay hiding it
630
- * is stale (the server says it is back). A pending request's overlays are
631
- * left alone; they settle with the request.
632
- */
633
- export declare const pruneOverlays: (optimistic: OptimisticState, connection: string, covered: ReadonlySet<string>, pending: ReadonlySet<string>) => OptimisticState;
634
- /**
635
- * Applies a result idempotently and releases the request's layer and overlays:
636
- * a later layer re-wins on rebase. Confirmed connection changes are recorded
637
- * once per request, as overlays the request no longer owns.
638
- */
639
- export declare const settleSuccess: (base: EntityStore, optimistic: OptimisticState, state: MutationState, requestId: string, answer: MutationAnswer & {
640
- /** Connection changes the server confirmed; they replace the request's own. */
641
- readonly connections?: ReadonlyArray<ConnectionChange> | undefined;
642
- }) => {
643
- readonly store: EntityStore;
644
- readonly state: MutationState;
645
- readonly optimistic: OptimisticState;
646
- };
647
- /** A failed request's layer and overlays are dropped; the base was never mutated. */
648
- export declare const settleFailure: (optimistic: OptimisticState, requestId: string) => OptimisticState;
649
- /**
650
- * Visible edges for one connection: applicable overlays are placed outside the
651
- * server-known segments and de-duplicated by edge identity (across overlays too),
652
- * so a pending insert never corrupts server-known ordering; a `remove` overlay
653
- * hides its edges wherever they are, and so does a tombstone on the edge's
654
- * target when `store` is given. A later prepend lands before an earlier one, a
655
- * later append after, so pending inserts read in the order they were made.
656
- * Boundaries still come from the connection's segments.
657
- */
658
- export declare const visibleItems: (connection: Connection, connectionId: string, overlays: ReadonlyArray<ConnectionOverlay>, store?: EntityStore) => ReadonlyArray<Edge>;
659
- //#endregion
660
- //#region src/live.d.ts
661
- export type LiveCursor = number;
662
- export type LiveEvent = {
663
- readonly _tag: 'EntityPatched';
664
- readonly ref: EdgeRef;
665
- readonly values: Readonly<Record<string, unknown>>;
666
- readonly changed: ReadonlyArray<string>;
667
- readonly cursor: LiveCursor;
668
- } | {
669
- readonly _tag: 'EntityDeleted';
670
- readonly ref: EdgeRef;
671
- readonly cursor: LiveCursor;
672
- } | {
673
- readonly _tag: 'ConnectionInsert';
674
- readonly connection: string;
675
- readonly position: 'prepend' | 'append';
676
- readonly edge: Edge;
677
- readonly cursor: LiveCursor;
678
- } | {
679
- readonly _tag: 'ConnectionRemove';
680
- readonly connection: string;
681
- readonly edge: Edge;
682
- readonly cursor: LiveCursor;
683
- } | {
684
- readonly _tag: 'ConnectionInvalidate';
685
- readonly connection: string;
686
- readonly cursor: LiveCursor;
687
- };
688
- export interface BoundaryCounts {
689
- readonly before: number;
690
- readonly after: number;
691
- }
692
- export interface LiveState {
693
- /** Last applied cursor for this stream. */
694
- readonly cursor: LiveCursor;
695
- /** Edges recorded outside the loaded boundary, not visible in `items`. */
696
- readonly boundary: Readonly<Record<string, BoundaryCounts>>;
697
- }
698
- export declare const emptyLiveState: LiveState;
699
- export type LiveOutcome = 'applied' | 'duplicate' | 'gap';
700
- /**
701
- * Ordering per stream: at most the next cursor; ahead is a gap. Cursor `0` means
702
- * "no baseline yet" (cursors are 1-based), so the first event of a stream is
703
- * accepted whatever its cursor — otherwise a stream not starting at 1 would be a
704
- * spurious gap.
705
- */
706
- export declare const classifyLive: (state: LiveState, cursor: LiveCursor) => LiveOutcome;
707
- export interface EntityApplied {
708
- readonly state: LiveState;
709
- readonly store: EntityStore;
710
- readonly outcome: LiveOutcome;
711
- }
712
- export declare const applyEntityEvent: (state: LiveState, store: EntityStore, event: Extract<LiveEvent, {
713
- _tag: "EntityPatched" | "EntityDeleted";
714
- }>, now?: number) => EntityApplied;
715
- export interface ConnectionApplied {
716
- readonly state: LiveState;
717
- readonly optimistic: OptimisticState;
718
- readonly outcome: LiveOutcome;
719
- /**
720
- * A connection the event says to refetch. Reported rather than recorded here,
721
- * because staleness lives on the connection in the Model — which is what the
722
- * planner and every read consult. It used to be written into a set on this
723
- * live state that nothing read, so an invalidating event did nothing at all.
724
- */
725
- readonly invalidated?: string | undefined;
726
- }
727
- export declare const applyConnectionEvent: (state: LiveState, optimistic: OptimisticState, event: Extract<LiveEvent, {
728
- _tag: "ConnectionInsert" | "ConnectionRemove" | "ConnectionInvalidate";
729
- }>, policy?: LivePolicy) => ConnectionApplied;
730
- /** `hasPrevious` accounting for edges recorded outside the loaded boundary. */
731
- export declare const liveHasPrevious: (connection: Connection, state: LiveState, connectionId: string) => boolean;
732
- /** `hasNext` accounting for edges recorded outside the loaded boundary. */
733
- export declare const liveHasNext: (connection: Connection, state: LiveState, connectionId: string) => boolean;
734
- //#endregion
735
- //#region src/retain.d.ts
736
- /** A connection to keep: its identity, and what a page of it selects of each item, if a projection reads it. */
737
- export interface ConnectionRoot {
738
- readonly identity: string;
739
- readonly select?: RelationRequirement | undefined;
740
- }
741
- export interface RetentionRoots {
742
- readonly requirements: ReadonlyArray<Requirement>;
743
- /** Connections (`QueryRef.identity`) to keep, with their edges' targets and what `select` reaches through them. */
744
- readonly connections: ReadonlyArray<ConnectionRoot>;
745
- }
746
- export interface Retained {
747
- readonly entities: EntityStore;
748
- readonly connections: Readonly<Record<string, Connection>>;
749
- readonly optimistic: OptimisticState;
750
- }
751
- /**
752
- * The entity keys the roots reach: each root entity, the targets its retained
753
- * fields refer to, and recursively the targets a nested relation selects.
754
- */
755
- export declare const reachable: (store: EntityStore, roots: RetentionRoots, connections: Readonly<Record<string, Connection>>, optimistic: OptimisticState, pending: ReadonlySet<string>) => ReadonlySet<EntityKey>;
756
- /**
757
- * Drops every entity the roots do not reach, every connection they do not
758
- * name, and every settled overlay on a dropped connection, keeping whatever a
759
- * pending request's layer or overlays touch. Pure.
760
- */
761
- export declare const gc: (state: Retained & {
762
- readonly mutations: MutationState;
763
- }, roots: RetentionRoots) => Retained;
764
- //#endregion
765
- //#region src/persistence.d.ts
766
- /** Bump when the serialized shape changes; a mismatch discards the cache. */
767
- export declare const REMOTE_CACHE_VERSION = 5;
768
- /**
769
- * What survives a reload: the entity cache, and the connections an application
770
- * **declared** should come back.
771
- *
772
- * Connections are session state by default and stay that way — `snapshotOf`
773
- * takes none unless asked. What a declared one keeps is its **edges and
774
- * nothing else**, which is not a simplification but the rule: a connection's
775
- * boundaries are cursors the server minted, and a cursor may name server state
776
- * that no longer exists. Restoring one would be claiming to know where the
777
- * page ends. The shape has nowhere to put a cursor, so that cannot be got
778
- * wrong later.
779
- */
780
- export interface Snapshot {
781
- readonly entities: EntityStore;
782
- /**
783
- * By connection identity: its **segments**, each a run of edges. No
784
- * boundaries.
785
- *
786
- * Segments rather than one flat list, because the gaps between them are
787
- * knowledge too. A connection paged from both ends holds a head and a tail
788
- * with an unfetched middle; flattening those into one run would claim the
789
- * tail's first row follows the head's last, which is a thing the client was
790
- * never told.
791
- */
792
- readonly connections: Readonly<Record<string, ReadonlyArray<ReadonlyArray<Edge>>>>;
793
- }
794
- export interface SnapshotOptions {
795
- /**
796
- * Who or what the snapshot is for (a user id, a tenant, a build). A snapshot
797
- * taken under another scope is discarded rather than shown to the wrong
798
- * reader. Default: unscoped, which only matches unscoped.
799
- */
800
- readonly scope?: string | undefined;
801
- /** Snapshots larger than this many bytes are not written and not read. */
802
- readonly maxBytes?: number | undefined;
803
- }
804
- /** How a snapshot meets a store that already has entries. */
805
- export type MergePolicy = 'replace' | 'preserve-existing';
806
- /**
807
- * The snapshot text, or `undefined` when it would exceed `maxBytes`. Build the
808
- * snapshot with `snapshotOf`, which is where the connections that survive are
809
- * named; runtime state — optimistic layers, live cursors, gaps, the mutation
810
- * ledger — is never in one.
811
- */
812
- declare function dehydrate(snapshot: Snapshot, options?: SnapshotOptions & {
813
- readonly maxBytes?: undefined;
814
- }): string;
815
- declare function dehydrate(snapshot: Snapshot, options?: SnapshotOptions): string | undefined;
816
- export declare const RemotePersistence: {
817
- /** The snapshot text, or `undefined` when it would exceed `maxBytes`. */
818
- dehydrate: typeof dehydrate;
819
- /** What a snapshot text holds, or `undefined` when it is refused. */
820
- hydrate: (raw: string | undefined | null, options?: SnapshotOptions) => Snapshot | undefined;
821
- /**
822
- * What to keep of a Model, naming the connections that should survive a
823
- * reload. Naming none is the default and is what Remote always did.
824
- */
825
- snapshotOf: (model: {
826
- readonly entities: EntityStore;
827
- readonly connections: Readonly<Record<string, Connection>>;
828
- }, options?: {
829
- readonly connections?: ReadonlyArray<ConnectionIdentity> | undefined;
830
- }) => Snapshot;
831
- /** A snapshot's entities brought into a store by policy. */
832
- mergeStores: (current: EntityStore, snapshot: EntityStore, policy: MergePolicy) => EntityStore;
833
- /** The cache as a fresh session has it; what a refused `restore` yields. */
834
- emptySnapshot: Snapshot;
835
- /**
836
- * Writes the snapshot under `key`, or removes the key when the store would
837
- * exceed `maxBytes`, so a stale smaller snapshot cannot outlive a larger
838
- * store it no longer describes.
839
- */
840
- save: (snapshot: Snapshot, options: {
841
- readonly key: string;
842
- } & SnapshotOptions) => Effect.Effect<void, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
843
- /**
844
- * Reads the cache. A missing key yields `emptySnapshot`; anything `hydrate`
845
- * refuses yields `emptySnapshot` and removes the key, so the next `restore`
846
- * is clean and the planner refetches.
847
- */
848
- restore: (options: {
849
- readonly key: string;
850
- } & SnapshotOptions) => Effect.Effect<Snapshot, KeyValueStore.KeyValueStoreError, KeyValueStore.KeyValueStore>;
851
- };
852
- //#endregion
853
- //#region src/wire.d.ts
854
- /**
855
- * The read/live protocol version. A batch names the version it speaks and the
856
- * server refuses a mismatch with `RemoteProtocolError`, so a shape change never
857
- * drifts silently: bump it whenever `ReadRequest` or `LiveRequirement` change.
858
- */
859
- export declare const REMOTE_PROTOCOL_VERSION = 4;
860
- declare const RemoteReadError_base: Schema.Class<RemoteReadError, Schema.TaggedStruct<"RemoteReadError", {
861
- readonly message: Schema.String;
862
- }>, import("effect/Cause").YieldableError>;
863
- export declare class RemoteReadError extends RemoteReadError_base {}
864
- declare const RemoteMutationError_base: Schema.Class<RemoteMutationError, Schema.TaggedStruct<"RemoteMutationError", {
865
- readonly message: Schema.String;
866
- }>, import("effect/Cause").YieldableError>;
867
- export declare class RemoteMutationError extends RemoteMutationError_base {}
868
- declare const RemoteLiveError_base: Schema.Class<RemoteLiveError, Schema.TaggedStruct<"RemoteLiveError", {
869
- readonly message: Schema.String;
870
- }>, import("effect/Cause").YieldableError>;
871
- export declare class RemoteLiveError extends RemoteLiveError_base {}
872
- declare const RemoteProtocolError_base: Schema.Class<RemoteProtocolError, Schema.TaggedStruct<"RemoteProtocolError", {
873
- readonly message: Schema.String;
874
- readonly expected: Schema.Number;
875
- readonly received: Schema.Number;
876
- }>, import("effect/Cause").YieldableError>;
877
- /** The peer speaks another protocol version; nothing was read. */
878
- export declare class RemoteProtocolError extends RemoteProtocolError_base {}
879
- /** A page size: a non-negative integer, refused at decode otherwise rather than defaulted. */
880
- export declare const PageSize: Schema.Number;
881
- export declare const WindowSchema: Schema.Struct<{
882
- readonly first: Schema.optional<Schema.Number>;
883
- readonly last: Schema.optional<Schema.Number>;
884
- readonly after: Schema.optional<Schema.String>;
885
- readonly before: Schema.optional<Schema.String>;
886
- }>;
887
- /** A request may not name more fields of one entity than this; a selection never does. */
888
- export declare const MAX_FIELDS_PER_REQUEST = 256;
889
- /** A selection may not nest relations deeper than this; the wire refuses more. */
890
- export declare const MAX_RELATION_DEPTH = 8;
891
- export declare const RelationRequest: Schema.Codec<RelationRequirement, RelationRequirement, never, never>;
892
- export declare const ReadRequest: Schema.Codec<Requirement, Requirement>;
893
- export declare const ReadBatch: Schema.Struct<{
894
- readonly version: Schema.Number;
895
- readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
896
- }>;
897
- export declare const NormalizedEntity: Schema.Struct<{
898
- readonly entity: Schema.String;
899
- readonly id: Schema.String;
900
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
901
- }>;
902
- /**
903
- * Fields a read asked for that the server answered without, and will not
904
- * answer with: the client stops asking. It says nothing about why, so a rule
905
- * that withholds a field is not itself on the wire.
906
- */
907
- export declare const SettledFields: Schema.Struct<{
908
- readonly entity: Schema.String;
909
- readonly id: Schema.String;
910
- readonly fields: Schema.$Array<Schema.String>;
911
- }>;
912
- export declare const ReadBatchResult: Schema.Struct<{
913
- readonly entities: Schema.$Array<Schema.Struct<{
914
- readonly entity: Schema.String;
915
- readonly id: Schema.String;
916
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
917
- }>>;
918
- readonly settled: Schema.$Array<Schema.Struct<{
919
- readonly entity: Schema.String;
920
- readonly id: Schema.String;
921
- readonly fields: Schema.$Array<Schema.String>;
922
- }>>;
923
- }>;
924
- export declare const MutationRequest: Schema.Struct<{
925
- /** Stable across transport retries so a mutation is not applied twice. */
926
- readonly requestId: Schema.String;
927
- readonly mutation: Schema.String;
928
- readonly input: Schema.Unknown;
929
- }>;
930
- export declare const LiveEdge: Schema.Struct<{
931
- readonly entity: Schema.String;
932
- readonly id: Schema.String;
933
- readonly key: Schema.String;
934
- }>;
935
- /** A connection change a mutation confirms: the same facts a live event carries, without a cursor. */
936
- export declare const ConnectionChangeSchema: Schema.Union<readonly [Schema.Struct<{
937
- readonly _tag: Schema.Literal<"Insert">;
938
- readonly connection: Schema.String;
939
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
940
- readonly edge: Schema.Struct<{
941
- readonly entity: Schema.String;
942
- readonly id: Schema.String;
943
- readonly key: Schema.String;
944
- }>;
945
- }>, Schema.Struct<{
946
- readonly _tag: Schema.Literal<"Remove">;
947
- readonly connection: Schema.String;
948
- readonly edge: Schema.Struct<{
949
- readonly entity: Schema.String;
950
- readonly id: Schema.String;
951
- readonly key: Schema.String;
952
- }>;
953
- }>]>;
954
- export declare const MutationResult: Schema.Struct<{
955
- readonly output: Schema.Unknown;
956
- readonly entities: Schema.$Array<Schema.Struct<{
957
- readonly entity: Schema.String;
958
- readonly id: Schema.String;
959
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
960
- }>>;
961
- /** Connection changes the mutation made, applied alongside its entity patches. */
962
- readonly connections: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
963
- readonly _tag: Schema.Literal<"Insert">;
964
- readonly connection: Schema.String;
965
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
966
- readonly edge: Schema.Struct<{
967
- readonly entity: Schema.String;
968
- readonly id: Schema.String;
969
- readonly key: Schema.String;
970
- }>;
971
- }>, Schema.Struct<{
972
- readonly _tag: Schema.Literal<"Remove">;
973
- readonly connection: Schema.String;
974
- readonly edge: Schema.Struct<{
975
- readonly entity: Schema.String;
976
- readonly id: Schema.String;
977
- readonly key: Schema.String;
978
- }>;
979
- }>]>>>;
980
- /** Entities the mutation deleted; the client knows them absent from then on. */
981
- readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
982
- readonly entity: Schema.String;
983
- readonly id: Schema.String;
984
- }>>>;
985
- }>;
986
- export declare const LiveRequirement: Schema.Struct<{
987
- readonly version: Schema.Number;
988
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
989
- /** Resume cursor; events at or before it are duplicates. */
990
- readonly after: Schema.Number;
991
- }>;
992
- /**
993
- * A live change. Entity changes update the store; connection changes alter
994
- * membership and ordering; both carry a per-stream cursor.
995
- */
996
- export declare const LiveChange: Schema.Union<readonly [Schema.Struct<{
997
- readonly _tag: Schema.Literal<"EntityPatched">;
998
- readonly cursor: Schema.Number;
999
- readonly entity: Schema.String;
1000
- readonly id: Schema.String;
1001
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1002
- readonly changed: Schema.$Array<Schema.String>;
1003
- }>, Schema.Struct<{
1004
- readonly _tag: Schema.Literal<"EntityDeleted">;
1005
- readonly cursor: Schema.Number;
1006
- readonly entity: Schema.String;
1007
- readonly id: Schema.String;
1008
- }>, Schema.Struct<{
1009
- readonly _tag: Schema.Literal<"ConnectionInsert">;
1010
- readonly cursor: Schema.Number;
1011
- readonly connection: Schema.String;
1012
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
1013
- readonly edge: Schema.Struct<{
1014
- readonly entity: Schema.String;
1015
- readonly id: Schema.String;
1016
- readonly key: Schema.String;
1017
- }>;
1018
- }>, Schema.Struct<{
1019
- readonly _tag: Schema.Literal<"ConnectionRemove">;
1020
- readonly cursor: Schema.Number;
1021
- readonly connection: Schema.String;
1022
- readonly edge: Schema.Struct<{
1023
- readonly entity: Schema.String;
1024
- readonly id: Schema.String;
1025
- readonly key: Schema.String;
1026
- }>;
1027
- }>, Schema.Struct<{
1028
- readonly _tag: Schema.Literal<"ConnectionInvalidate">;
1029
- readonly cursor: Schema.Number;
1030
- readonly connection: Schema.String;
1031
- }>]>;
1032
- export declare const Read: Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
1033
- readonly version: Schema.Number;
1034
- readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1035
- }>, Schema.Struct<{
1036
- readonly entities: Schema.$Array<Schema.Struct<{
1037
- readonly entity: Schema.String;
1038
- readonly id: Schema.String;
1039
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1040
- }>>;
1041
- readonly settled: Schema.$Array<Schema.Struct<{
1042
- readonly entity: Schema.String;
1043
- readonly id: Schema.String;
1044
- readonly fields: Schema.$Array<Schema.String>;
1045
- }>>;
1046
- }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError]>, never, never>;
1047
- export declare const Mutate: Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
1048
- /** Stable across transport retries so a mutation is not applied twice. */
1049
- readonly requestId: Schema.String;
1050
- readonly mutation: Schema.String;
1051
- readonly input: Schema.Unknown;
1052
- }>, Schema.Struct<{
1053
- readonly output: Schema.Unknown;
1054
- readonly entities: Schema.$Array<Schema.Struct<{
1055
- readonly entity: Schema.String;
1056
- readonly id: Schema.String;
1057
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1058
- }>>;
1059
- /** Connection changes the mutation made, applied alongside its entity patches. */
1060
- readonly connections: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
1061
- readonly _tag: Schema.Literal<"Insert">;
1062
- readonly connection: Schema.String;
1063
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
1064
- readonly edge: Schema.Struct<{
1065
- readonly entity: Schema.String;
1066
- readonly id: Schema.String;
1067
- readonly key: Schema.String;
1068
- }>;
1069
- }>, Schema.Struct<{
1070
- readonly _tag: Schema.Literal<"Remove">;
1071
- readonly connection: Schema.String;
1072
- readonly edge: Schema.Struct<{
1073
- readonly entity: Schema.String;
1074
- readonly id: Schema.String;
1075
- readonly key: Schema.String;
1076
- }>;
1077
- }>]>>>;
1078
- /** Entities the mutation deleted; the client knows them absent from then on. */
1079
- readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
1080
- readonly entity: Schema.String;
1081
- readonly id: Schema.String;
1082
- }>>>;
1083
- }>, typeof RemoteMutationError, never, never>;
1084
- export declare const Live: Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
1085
- readonly version: Schema.Number;
1086
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1087
- /** Resume cursor; events at or before it are duplicates. */
1088
- readonly after: Schema.Number;
1089
- }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
1090
- readonly _tag: Schema.Literal<"EntityPatched">;
1091
- readonly cursor: Schema.Number;
1092
- readonly entity: Schema.String;
1093
- readonly id: Schema.String;
1094
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1095
- readonly changed: Schema.$Array<Schema.String>;
1096
- }>, Schema.Struct<{
1097
- readonly _tag: Schema.Literal<"EntityDeleted">;
1098
- readonly cursor: Schema.Number;
1099
- readonly entity: Schema.String;
1100
- readonly id: Schema.String;
1101
- }>, Schema.Struct<{
1102
- readonly _tag: Schema.Literal<"ConnectionInsert">;
1103
- readonly cursor: Schema.Number;
1104
- readonly connection: Schema.String;
1105
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
1106
- readonly edge: Schema.Struct<{
1107
- readonly entity: Schema.String;
1108
- readonly id: Schema.String;
1109
- readonly key: Schema.String;
1110
- }>;
1111
- }>, Schema.Struct<{
1112
- readonly _tag: Schema.Literal<"ConnectionRemove">;
1113
- readonly cursor: Schema.Number;
1114
- readonly connection: Schema.String;
1115
- readonly edge: Schema.Struct<{
1116
- readonly entity: Schema.String;
1117
- readonly id: Schema.String;
1118
- readonly key: Schema.String;
1119
- }>;
1120
- }>, Schema.Struct<{
1121
- readonly _tag: Schema.Literal<"ConnectionInvalidate">;
1122
- readonly cursor: Schema.Number;
1123
- readonly connection: Schema.String;
1124
- }>]>, Schema.Union<readonly [typeof RemoteLiveError, typeof RemoteProtocolError]>>, Schema.Never, never, never>;
1125
- declare const RemoteQueryError_base: Schema.Class<RemoteQueryError, Schema.TaggedStruct<"RemoteQueryError", {
1126
- readonly message: Schema.String;
1127
- }>, import("effect/Cause").YieldableError>;
1128
- export declare class RemoteQueryError extends RemoteQueryError_base {}
1129
- export declare const WireBoundary: Schema.Union<readonly [Schema.Struct<{
1130
- readonly _tag: Schema.Literal<"Terminal">;
1131
- }>, Schema.Struct<{
1132
- readonly _tag: Schema.Literal<"Cursor">;
1133
- readonly cursor: Schema.String;
1134
- }>, Schema.Struct<{
1135
- readonly _tag: Schema.Literal<"Unknown">;
1136
- }>]>;
1137
- export declare const QueryRequest: Schema.Struct<{
1138
- readonly query: Schema.String;
1139
- readonly input: Schema.Unknown;
1140
- readonly window: Schema.Struct<{
1141
- readonly first: Schema.optional<Schema.Number>;
1142
- readonly last: Schema.optional<Schema.Number>;
1143
- readonly after: Schema.optional<Schema.String>;
1144
- readonly before: Schema.optional<Schema.String>;
1145
- }>;
1146
- /**
1147
- * What to read of each item, as the relation slice a read asks the server
1148
- * for. Absent for a query run without one: the response carries only edges,
1149
- * and the client's read entry fetches fields in a second round trip.
1150
- */
1151
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1152
- }>;
1153
- export declare const QueryEdge: Schema.Struct<{
1154
- readonly entity: Schema.String;
1155
- readonly id: Schema.String;
1156
- readonly key: Schema.String;
1157
- }>;
1158
- export declare const QueryResult: Schema.Struct<{
1159
- readonly edges: Schema.$Array<Schema.Struct<{
1160
- readonly entity: Schema.String;
1161
- readonly id: Schema.String;
1162
- readonly key: Schema.String;
1163
- }>>;
1164
- readonly start: Schema.Union<readonly [Schema.Struct<{
1165
- readonly _tag: Schema.Literal<"Terminal">;
1166
- }>, Schema.Struct<{
1167
- readonly _tag: Schema.Literal<"Cursor">;
1168
- readonly cursor: Schema.String;
1169
- }>, Schema.Struct<{
1170
- readonly _tag: Schema.Literal<"Unknown">;
1171
- }>]>;
1172
- readonly end: Schema.Union<readonly [Schema.Struct<{
1173
- readonly _tag: Schema.Literal<"Terminal">;
1174
- }>, Schema.Struct<{
1175
- readonly _tag: Schema.Literal<"Cursor">;
1176
- readonly cursor: Schema.String;
1177
- }>, Schema.Struct<{
1178
- readonly _tag: Schema.Literal<"Unknown">;
1179
- }>]>;
1180
- /**
1181
- * The selected fields of the page's items, in the same shape a read batch
1182
- * returns. Absent from a server that predates payload planning: the client
1183
- * reads it as empty and fetches fields as before.
1184
- */
1185
- readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
1186
- readonly entity: Schema.String;
1187
- readonly id: Schema.String;
1188
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1189
- }>>>;
1190
- readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
1191
- readonly entity: Schema.String;
1192
- readonly id: Schema.String;
1193
- readonly fields: Schema.$Array<Schema.String>;
1194
- }>>>;
1195
- }>;
1196
- export declare const QueryRpc: Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
1197
- readonly query: Schema.String;
1198
- readonly input: Schema.Unknown;
1199
- readonly window: Schema.Struct<{
1200
- readonly first: Schema.optional<Schema.Number>;
1201
- readonly last: Schema.optional<Schema.Number>;
1202
- readonly after: Schema.optional<Schema.String>;
1203
- readonly before: Schema.optional<Schema.String>;
1204
- }>;
1205
- /**
1206
- * What to read of each item, as the relation slice a read asks the server
1207
- * for. Absent for a query run without one: the response carries only edges,
1208
- * and the client's read entry fetches fields in a second round trip.
1209
- */
1210
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1211
- }>, Schema.Struct<{
1212
- readonly edges: Schema.$Array<Schema.Struct<{
1213
- readonly entity: Schema.String;
1214
- readonly id: Schema.String;
1215
- readonly key: Schema.String;
1216
- }>>;
1217
- readonly start: Schema.Union<readonly [Schema.Struct<{
1218
- readonly _tag: Schema.Literal<"Terminal">;
1219
- }>, Schema.Struct<{
1220
- readonly _tag: Schema.Literal<"Cursor">;
1221
- readonly cursor: Schema.String;
1222
- }>, Schema.Struct<{
1223
- readonly _tag: Schema.Literal<"Unknown">;
1224
- }>]>;
1225
- readonly end: Schema.Union<readonly [Schema.Struct<{
1226
- readonly _tag: Schema.Literal<"Terminal">;
1227
- }>, Schema.Struct<{
1228
- readonly _tag: Schema.Literal<"Cursor">;
1229
- readonly cursor: Schema.String;
1230
- }>, Schema.Struct<{
1231
- readonly _tag: Schema.Literal<"Unknown">;
1232
- }>]>;
1233
- /**
1234
- * The selected fields of the page's items, in the same shape a read batch
1235
- * returns. Absent from a server that predates payload planning: the client
1236
- * reads it as empty and fetches fields as before.
1237
- */
1238
- readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
1239
- readonly entity: Schema.String;
1240
- readonly id: Schema.String;
1241
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1242
- }>>>;
1243
- readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
1244
- readonly entity: Schema.String;
1245
- readonly id: Schema.String;
1246
- readonly fields: Schema.$Array<Schema.String>;
1247
- }>>>;
1248
- }>, typeof RemoteQueryError, never, never>;
1249
- export declare const RemoteRpc: RpcGroup.RpcGroup<Rpc.Rpc<"FoldkitRemoteRead", Schema.Struct<{
1250
- readonly version: Schema.Number;
1251
- readonly requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1252
- }>, Schema.Struct<{
1253
- readonly entities: Schema.$Array<Schema.Struct<{
1254
- readonly entity: Schema.String;
1255
- readonly id: Schema.String;
1256
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1257
- }>>;
1258
- readonly settled: Schema.$Array<Schema.Struct<{
1259
- readonly entity: Schema.String;
1260
- readonly id: Schema.String;
1261
- readonly fields: Schema.$Array<Schema.String>;
1262
- }>>;
1263
- }>, Schema.Union<readonly [typeof RemoteReadError, typeof RemoteProtocolError]>, never, never> | Rpc.Rpc<"FoldkitRemoteMutate", Schema.Struct<{
1264
- /** Stable across transport retries so a mutation is not applied twice. */
1265
- readonly requestId: Schema.String;
1266
- readonly mutation: Schema.String;
1267
- readonly input: Schema.Unknown;
1268
- }>, Schema.Struct<{
1269
- readonly output: Schema.Unknown;
1270
- readonly entities: Schema.$Array<Schema.Struct<{
1271
- readonly entity: Schema.String;
1272
- readonly id: Schema.String;
1273
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1274
- }>>;
1275
- /** Connection changes the mutation made, applied alongside its entity patches. */
1276
- readonly connections: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
1277
- readonly _tag: Schema.Literal<"Insert">;
1278
- readonly connection: Schema.String;
1279
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
1280
- readonly edge: Schema.Struct<{
1281
- readonly entity: Schema.String;
1282
- readonly id: Schema.String;
1283
- readonly key: Schema.String;
1284
- }>;
1285
- }>, Schema.Struct<{
1286
- readonly _tag: Schema.Literal<"Remove">;
1287
- readonly connection: Schema.String;
1288
- readonly edge: Schema.Struct<{
1289
- readonly entity: Schema.String;
1290
- readonly id: Schema.String;
1291
- readonly key: Schema.String;
1292
- }>;
1293
- }>]>>>;
1294
- /** Entities the mutation deleted; the client knows them absent from then on. */
1295
- readonly deleted: Schema.optional<Schema.$Array<Schema.Struct<{
1296
- readonly entity: Schema.String;
1297
- readonly id: Schema.String;
1298
- }>>>;
1299
- }>, typeof RemoteMutationError, never, never> | Rpc.Rpc<"FoldkitRemoteLive", Schema.Struct<{
1300
- readonly version: Schema.Number;
1301
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1302
- /** Resume cursor; events at or before it are duplicates. */
1303
- readonly after: Schema.Number;
1304
- }>, import("effect/rpc/RpcSchema").Stream<Schema.Union<readonly [Schema.Struct<{
1305
- readonly _tag: Schema.Literal<"EntityPatched">;
1306
- readonly cursor: Schema.Number;
1307
- readonly entity: Schema.String;
1308
- readonly id: Schema.String;
1309
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1310
- readonly changed: Schema.$Array<Schema.String>;
1311
- }>, Schema.Struct<{
1312
- readonly _tag: Schema.Literal<"EntityDeleted">;
1313
- readonly cursor: Schema.Number;
1314
- readonly entity: Schema.String;
1315
- readonly id: Schema.String;
1316
- }>, Schema.Struct<{
1317
- readonly _tag: Schema.Literal<"ConnectionInsert">;
1318
- readonly cursor: Schema.Number;
1319
- readonly connection: Schema.String;
1320
- readonly position: Schema.Union<readonly [Schema.Literal<"prepend">, Schema.Literal<"append">]>;
1321
- readonly edge: Schema.Struct<{
1322
- readonly entity: Schema.String;
1323
- readonly id: Schema.String;
1324
- readonly key: Schema.String;
1325
- }>;
1326
- }>, Schema.Struct<{
1327
- readonly _tag: Schema.Literal<"ConnectionRemove">;
1328
- readonly cursor: Schema.Number;
1329
- readonly connection: Schema.String;
1330
- readonly edge: Schema.Struct<{
1331
- readonly entity: Schema.String;
1332
- readonly id: Schema.String;
1333
- readonly key: Schema.String;
1334
- }>;
1335
- }>, Schema.Struct<{
1336
- readonly _tag: Schema.Literal<"ConnectionInvalidate">;
1337
- readonly cursor: Schema.Number;
1338
- readonly connection: Schema.String;
1339
- }>]>, Schema.Union<readonly [typeof RemoteLiveError, typeof RemoteProtocolError]>>, Schema.Never, never, never> | Rpc.Rpc<"FoldkitRemoteQuery", Schema.Struct<{
1340
- readonly query: Schema.String;
1341
- readonly input: Schema.Unknown;
1342
- readonly window: Schema.Struct<{
1343
- readonly first: Schema.optional<Schema.Number>;
1344
- readonly last: Schema.optional<Schema.Number>;
1345
- readonly after: Schema.optional<Schema.String>;
1346
- readonly before: Schema.optional<Schema.String>;
1347
- }>;
1348
- /**
1349
- * What to read of each item, as the relation slice a read asks the server
1350
- * for. Absent for a query run without one: the response carries only edges,
1351
- * and the client's read entry fetches fields in a second round trip.
1352
- */
1353
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1354
- }>, Schema.Struct<{
1355
- readonly edges: Schema.$Array<Schema.Struct<{
1356
- readonly entity: Schema.String;
1357
- readonly id: Schema.String;
1358
- readonly key: Schema.String;
1359
- }>>;
1360
- readonly start: Schema.Union<readonly [Schema.Struct<{
1361
- readonly _tag: Schema.Literal<"Terminal">;
1362
- }>, Schema.Struct<{
1363
- readonly _tag: Schema.Literal<"Cursor">;
1364
- readonly cursor: Schema.String;
1365
- }>, Schema.Struct<{
1366
- readonly _tag: Schema.Literal<"Unknown">;
1367
- }>]>;
1368
- readonly end: Schema.Union<readonly [Schema.Struct<{
1369
- readonly _tag: Schema.Literal<"Terminal">;
1370
- }>, Schema.Struct<{
1371
- readonly _tag: Schema.Literal<"Cursor">;
1372
- readonly cursor: Schema.String;
1373
- }>, Schema.Struct<{
1374
- readonly _tag: Schema.Literal<"Unknown">;
1375
- }>]>;
1376
- /**
1377
- * The selected fields of the page's items, in the same shape a read batch
1378
- * returns. Absent from a server that predates payload planning: the client
1379
- * reads it as empty and fetches fields as before.
1380
- */
1381
- readonly entities: Schema.optional<Schema.$Array<Schema.Struct<{
1382
- readonly entity: Schema.String;
1383
- readonly id: Schema.String;
1384
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1385
- }>>>;
1386
- readonly settled: Schema.optional<Schema.$Array<Schema.Struct<{
1387
- readonly entity: Schema.String;
1388
- readonly id: Schema.String;
1389
- readonly fields: Schema.$Array<Schema.String>;
1390
- }>>>;
1391
- }>, typeof RemoteQueryError, never, never>>;
1392
- //#endregion
1393
- //#region src/model.d.ts
1394
- /**
1395
- * The normalized cache as a Foldkit Submodel. `Remote.define` returns a schema
1396
- * and an `update` for this shape; `updateRemote` reconciles every producer.
1397
- */
1398
- export interface RemoteModel {
1399
- /** Entity values, presence, staleness, tombstones, and applied windows. */
1400
- readonly entities: EntityStore;
1401
- /** Normalized ordered connections, keyed by connection identity. */
1402
- readonly connections: Readonly<Record<string, Connection>>;
1403
- /**
1404
- * How many rows `Data.more` has grown a read's window to, by
1405
- * `windowGrowthKey`. A read shows at most its window, so this is what "load
1406
- * more" changes; it lives here because a list holds no state of its own.
1407
- */
1408
- readonly grown: Readonly<Record<string, number>>;
1409
- /** Optimistic entity layers and connection overlays over the base store. */
1410
- readonly optimistic: OptimisticState;
1411
- /** Live cursor and boundary state, keyed by the subscription's stream key. */
1412
- readonly live: Readonly<Record<string, LiveState>>;
1413
- /** Mutation pending/applied/failed ledger. */
1414
- readonly mutations: MutationState;
1415
- /** Streams whose live cursor fell behind; the caller should resync or refetch. */
1416
- readonly gaps: ReadonlySet<string>;
1417
- /**
1418
- * The `entity\0id\0field` marks a read is currently fetching. A field absent
1419
- * from the store reads as `Loading` while its mark is here and `Initial`
1420
- * otherwise, which is what separates "being fetched" from "nothing is
1421
- * fetching this".
1422
- */
1423
- readonly loading: ReadonlySet<string>;
1424
- /**
1425
- * `Remote.refresh` generations, held per field rather than for the store as a
1426
- * whole. A read entry restarts when the generation over the fields it plans
1427
- * moves, so a read sent before a refresh of its own fields cannot land after
1428
- * it, and a refresh of one field leaves every other entry's read alone.
1429
- */
1430
- readonly refresh: RefreshState;
1431
- /**
1432
- * The reads that failed and have not been settled since, so a read can say
1433
- * `Failed` rather than `Initial`.
1434
- *
1435
- * Without them a read that failed before anything loaded read exactly like
1436
- * one nobody had asked for, and nothing asked again: a read entry restarts
1437
- * only when what it plans changes, and a failure changed nothing. What failed
1438
- * is not planned again on its own either, so a persistent error is not
1439
- * retried every time an unrelated read restarts the entry. `Remote.refresh`
1440
- * is how a view retries.
1441
- */
1442
- readonly failures: Failures;
1443
- }
1444
- /**
1445
- * Failed reads, as the errors they failed with.
1446
- *
1447
- * `connections` is by connection identity, and is settled by a page arriving,
1448
- * an invalidation, or retention dropping the connection. `fields` is by field
1449
- * mark (`entity\0id\0field`, the marks `loading` uses), and is settled by the
1450
- * field being written again, a refresh asking for it, or retention dropping the
1451
- * entity. A read of it in flight reads `Loading` over the failure without
1452
- * settling it: if that read fails too, the failure is simply recorded again.
1453
- */
1454
- export interface Failures {
1455
- readonly connections: Readonly<Record<string, RemoteError>>;
1456
- readonly fields: Readonly<Record<string, RemoteError>>;
1457
- }
1458
- export declare const noFailures: Failures;
1459
- /**
1460
- * `Remote.refresh` generations, per field mark. `generation` is the last one
1461
- * handed out; `requested` is when each field was last refreshed, and `started`
1462
- * is the generation each field's read last began under. Holding them per field
1463
- * is what keeps one Projection's refresh from restarting every read entry.
1464
- */
1465
- export interface RefreshState {
1466
- readonly generation: number;
1467
- readonly requested: ReadonlyMap<string, number>;
1468
- readonly started: ReadonlyMap<string, number>;
1469
- /**
1470
- * The generation every entry is refreshed at, at least: `forgetRemote` moves
1471
- * it, so every read and live entry restarts, and a read or stream begun for
1472
- * the principal before is interrupted rather than landing after.
1473
- */
1474
- readonly floor: number;
1475
- }
1476
- export declare const emptyRefresh: RefreshState;
1477
- /**
1478
- * The Model with everything the server told it forgotten: values, tombstones,
1479
- * unavailable fields, connections, live cursors, failures, and what is in
1480
- * flight. For a change of principal, whose facts these were. The mutation
1481
- * sequence is kept, so request ids stay unique, and a mutation in flight is
1482
- * treated as applied: its answer, when it comes, writes nothing here.
1483
- */
1484
- export declare const forgetRemote: (model: RemoteModel) => RemoteModel;
1485
- export declare const initialRemoteModel: RemoteModel;
1486
- export declare const remoteModelSchema: () => Schema.Codec<RemoteModel, unknown>;
1487
- /** The submodel's Messages; each reduces to `RemoteModel` through `updateRemote`. */
1488
- export type RemoteMessage = {
1489
- readonly _tag: 'ReadReceived';
1490
- readonly requests: readonly Requirement[];
1491
- readonly result: Schema.Schema.Type<typeof ReadBatchResult>;
1492
- readonly now: number;
1493
- } | {
1494
- readonly _tag: 'ReadFailed';
1495
- readonly requests: readonly Requirement[];
1496
- readonly error: RemoteError;
1497
- /**
1498
- * The live stream whose subscription broke, when this is that rather
1499
- * than a read. Nothing was being read, so no field failed: the stream is
1500
- * recorded as a gap, since changes after it are missed until the host
1501
- * resubscribes.
1502
- */
1503
- readonly stream?: string | undefined;
1504
- } |
1505
- /** A refetch of present fields began; they read as `Refreshing` until it lands. */
1506
- {
1507
- readonly _tag: 'RefreshStarted';
1508
- readonly requests: readonly Requirement[];
1509
- } |
1510
- /** A read began; the fields it asks for that the store lacks read as `Loading`. */
1511
- {
1512
- readonly _tag: 'ReadStarted';
1513
- readonly requests: readonly Requirement[];
1514
- /** The refresh generation the read was planned under. */
1515
- readonly refresh?: number | undefined;
1516
- } |
1517
- /**
1518
- * Queries for these connections were sent. One with nothing to show reads
1519
- * `Loading` until its page or its failure arrives, which is what separates
1520
- * "being fetched" from `Initial`, "nothing is fetching this".
1521
- */
1522
- {
1523
- readonly _tag: 'QueryStarted';
1524
- readonly connections: readonly string[];
1525
- } |
1526
- /** The active Surfaces' roots changed; everything they do not reach is collected. */
1527
- {
1528
- readonly _tag: 'RetentionChanged';
1529
- readonly roots: RetentionRoots;
1530
- } |
1531
- /** A restored snapshot meets the store; runtime state is untouched. */
1532
- {
1533
- readonly _tag: 'Hydrated';
1534
- readonly entities: EntityStore;
1535
- /**
1536
- * The connections a snapshot declared should survive, as their edges.
1537
- * Restored with **unknown** boundaries and marked stale: the rows show
1538
- * at once and the connection is refetched, because a persisted cursor
1539
- * may name server state that is gone.
1540
- */
1541
- readonly connections?: Readonly<Record<string, ReadonlyArray<ReadonlyArray<Edge>>>> | undefined;
1542
- readonly merge: MergePolicy;
1543
- } |
1544
- /** A mutation began; its optimistic operations show until it settles. */
1545
- {
1546
- readonly _tag: 'MutationStarted';
1547
- readonly requestId: string;
1548
- readonly optimistic?: ReadonlyArray<OptimisticOperation> | undefined;
1549
- } | {
1550
- readonly _tag: 'MutationSucceeded';
1551
- readonly requestId: string;
1552
- readonly entities: readonly NormalizedPatch[];
1553
- /** Connection changes the server confirmed; they replace the request's own. */
1554
- readonly connections?: ReadonlyArray<ConnectionChange> | undefined;
1555
- /** Entities the mutation deleted: tombstoned, which hides them from every connection. */
1556
- readonly deleted?: ReadonlyArray<{
1557
- readonly entity: string;
1558
- readonly id: string;
1559
- }> | undefined;
1560
- /** Injected clock reading of the answer: how fresh the written entities are. */
1561
- readonly now: number;
1562
- } | {
1563
- readonly _tag: 'MutationFailed';
1564
- readonly requestId: string;
1565
- readonly error: RemoteError;
1566
- } |
1567
- /**
1568
- * Operations shown over the store with no request behind them, until they are
1569
- * lifted: a preview of a change nobody has made. Showing an id again replaces
1570
- * what it showed.
1571
- */
1572
- {
1573
- readonly _tag: 'OverlayShown';
1574
- readonly id: string;
1575
- readonly optimistic: ReadonlyArray<OptimisticOperation>;
1576
- } | {
1577
- readonly _tag: 'OverlayLifted';
1578
- readonly id: string;
1579
- } |
1580
- /** `Data.more`: a read's window, by `windowGrowthKey`, now shows `size` rows. */
1581
- {
1582
- readonly _tag: 'WindowGrown';
1583
- readonly window: string;
1584
- readonly size: number;
1585
- } | {
1586
- readonly _tag: 'LiveReceived';
1587
- readonly stream: string;
1588
- readonly event: LiveEvent;
1589
- readonly policy?: LivePolicy;
1590
- readonly now: number;
1591
- } | {
1592
- readonly _tag: 'GapCleared';
1593
- readonly stream: string;
1594
- } | {
1595
- readonly _tag: 'ConnectionMerged';
1596
- readonly connection: string;
1597
- readonly page: Segment;
1598
- /** The page answers the connection's refresh, so the merge also clears `stale`. */
1599
- readonly refreshes?: boolean | undefined;
1600
- /**
1601
- * The slice the query asked for, so the payload's entities write like a
1602
- * read: one request per matching edge. Absent for a page from a server
1603
- * that predates payload planning, which carries edges only.
1604
- */
1605
- readonly select?: RelationRequirement | undefined;
1606
- /** The selected fields of the page's items, as a read batch returns them. */
1607
- readonly entities?: ReadonlyArray<{
1608
- readonly entity: string;
1609
- readonly id: string;
1610
- readonly values: Record<string, unknown>;
1611
- }> | undefined;
1612
- /** Fields asked for that the server settled without a value. */
1613
- readonly settled?: ReadonlyArray<{
1614
- readonly entity: string;
1615
- readonly id: string;
1616
- readonly fields: ReadonlyArray<string>;
1617
- }> | undefined;
1618
- /** Injected clock reading of the answer, dating what the payload writes. */
1619
- readonly now?: number | undefined;
1620
- } | {
1621
- readonly _tag: 'ConnectionInvalidated';
1622
- readonly connection: string;
1623
- } | {
1624
- readonly _tag: 'ConnectionRefreshed';
1625
- readonly connection: string;
1626
- } |
1627
- /**
1628
- * A query for the connection failed. Its pages stay as they were, and it
1629
- * reads `Failed` — with them as `previous`, when it has any — until a page
1630
- * arrives, it is invalidated, or retention drops it.
1631
- */
1632
- {
1633
- readonly _tag: 'QueryFailed';
1634
- readonly connection: string;
1635
- readonly error: RemoteError;
1636
- };
1637
- export declare const retentionRootsSchema: Schema.Struct<{
1638
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1639
- readonly connections: Schema.$Array<Schema.Struct<{
1640
- readonly identity: Schema.String;
1641
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1642
- }>>;
1643
- }>;
1644
- /**
1645
- * The Messages' fields by tag, without `_tag`: what `defineMessageUnion` takes,
1646
- * so an application spreads them into its own union (`Remote.messages`).
1647
- */
1648
- export declare const remoteMessageCases: {
1649
- ReadReceived: {
1650
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1651
- result: Schema.Struct<{
1652
- readonly entities: Schema.$Array<Schema.Struct<{
1653
- readonly entity: Schema.String;
1654
- readonly id: Schema.String;
1655
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1656
- }>>;
1657
- readonly settled: Schema.$Array<Schema.Struct<{
1658
- readonly entity: Schema.String;
1659
- readonly id: Schema.String;
1660
- readonly fields: Schema.$Array<Schema.String>;
1661
- }>>;
1662
- }>;
1663
- now: Schema.Number;
1664
- };
1665
- ReadFailed: {
1666
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1667
- error: Schema.Struct<{
1668
- readonly _tag: Schema.String;
1669
- readonly message: Schema.String;
1670
- }>;
1671
- stream: Schema.optional<Schema.String>;
1672
- };
1673
- RefreshStarted: {
1674
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1675
- };
1676
- ReadStarted: {
1677
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1678
- refresh: Schema.optional<Schema.Number>;
1679
- };
1680
- QueryStarted: {
1681
- connections: Schema.$Array<Schema.String>;
1682
- };
1683
- RetentionChanged: {
1684
- roots: Schema.Struct<{
1685
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
1686
- readonly connections: Schema.$Array<Schema.Struct<{
1687
- readonly identity: Schema.String;
1688
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1689
- }>>;
1690
- }>;
1691
- };
1692
- Hydrated: {
1693
- connections: Schema.optional<Schema.Unknown>;
1694
- entities: Schema.Unknown;
1695
- merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
1696
- };
1697
- MutationStarted: {
1698
- requestId: Schema.String;
1699
- optimistic: Schema.optional<Schema.$Array<Schema.Unknown>>;
1700
- };
1701
- MutationSucceeded: {
1702
- requestId: Schema.String;
1703
- entities: Schema.$Array<Schema.Struct<{
1704
- readonly entity: Schema.String;
1705
- readonly id: Schema.String;
1706
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1707
- }>>;
1708
- connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
1709
- deleted: Schema.optional<Schema.$Array<Schema.Struct<{
1710
- readonly entity: Schema.String;
1711
- readonly id: Schema.String;
1712
- }>>>;
1713
- now: Schema.Number;
1714
- };
1715
- MutationFailed: {
1716
- requestId: Schema.String;
1717
- error: Schema.Struct<{
1718
- readonly _tag: Schema.String;
1719
- readonly message: Schema.String;
1720
- }>;
1721
- };
1722
- OverlayShown: {
1723
- id: Schema.String;
1724
- optimistic: Schema.$Array<Schema.Unknown>;
1725
- };
1726
- OverlayLifted: {
1727
- id: Schema.String;
1728
- };
1729
- WindowGrown: {
1730
- window: Schema.String;
1731
- size: Schema.Number;
1732
- };
1733
- LiveReceived: {
1734
- stream: Schema.String;
1735
- event: Schema.Unknown;
1736
- policy: Schema.optional<Schema.Unknown>;
1737
- now: Schema.Number;
1738
- };
1739
- GapCleared: {
1740
- stream: Schema.String;
1741
- };
1742
- ConnectionMerged: {
1743
- connection: Schema.String;
1744
- page: Schema.Unknown;
1745
- refreshes: Schema.optional<Schema.Boolean>;
1746
- select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
1747
- entities: Schema.optional<Schema.$Array<Schema.Struct<{
1748
- readonly entity: Schema.String;
1749
- readonly id: Schema.String;
1750
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
1751
- }>>>;
1752
- settled: Schema.optional<Schema.$Array<Schema.Struct<{
1753
- readonly entity: Schema.String;
1754
- readonly id: Schema.String;
1755
- readonly fields: Schema.$Array<Schema.String>;
1756
- }>>>;
1757
- now: Schema.optional<Schema.Number>;
1758
- };
1759
- ConnectionInvalidated: {
1760
- connection: Schema.String;
1761
- };
1762
- ConnectionRefreshed: {
1763
- connection: Schema.String;
1764
- };
1765
- QueryFailed: {
1766
- connection: Schema.String;
1767
- error: Schema.Struct<{
1768
- readonly _tag: Schema.String;
1769
- readonly message: Schema.String;
1770
- }>;
1771
- };
1772
- };
1773
- export type RemoteMessageTag = RemoteMessage['_tag'];
1774
- /**
1775
- * A Remote Message as an application's union constructs it from
1776
- * `remoteMessageCases`: the same shape `RemoteMessage` names, with the runtime
1777
- * slots (`entities`, `event`, `page`) typed `unknown` by their schemas.
1778
- */
1779
- export type RemoteMessageInput = { [Tag in RemoteMessageTag]: {
1780
- readonly _tag: Tag;
1781
- } & Schema.Struct.Type<(typeof remoteMessageCases)[Tag]>; }[RemoteMessageTag];
1782
- /**
1783
- * Whether a Message is one of Remote's, by tag. Narrows an application's union
1784
- * to its Remote cases, and its complement to the application's own.
1785
- */
1786
- export declare const isRemoteMessage: <M extends {
1787
- readonly _tag: string;
1788
- }>(message: M) => message is Extract<M, {
1789
- readonly _tag: RemoteMessageTag;
1790
- }>;
1791
- export declare const remoteMessageSchema: Schema.Schema<RemoteMessage>;
1792
- /** The key a grown window is kept under: its connection and the window first asked for. */
1793
- export declare const windowGrowthKey: (identity: string, window: string) => string;
1794
- /**
1795
- * Whether only overlays show this entity: the server has told the store
1796
- * nothing of it and no request's layer writes it, so nothing will fetch what an
1797
- * overlay leaves out.
1798
- */
1799
- export declare const onlyOverlaid: (model: RemoteModel, entity: string, id: string) => boolean;
1800
- /** Whether a query for this connection is in flight. */
1801
- export declare const isQueryLoading: (model: RemoteModel, identity: string) => boolean;
1802
- /**
1803
- * The generation a read is planned under: the highest any of the fields it
1804
- * reads or connections it runs was refreshed at. A read entry carries this as a
1805
- * dependency, so it restarts when what it observes is refreshed and not when
1806
- * anything else is.
1807
- */
1808
- export declare const refreshedAt: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => number;
1809
- /**
1810
- * Marks every field of `requests` and every connection in `connections`
1811
- * refreshed at the next generation.
1812
- */
1813
- export declare const withRefreshRequested: (refresh: RefreshState, requests: ReadonlyArray<Requirement>, connections?: ReadonlyArray<string>) => RefreshState;
1814
- /**
1815
- * Whether one field's read already began under the generation that field was
1816
- * last refreshed at. Such a read is in flight and would otherwise outlive the
1817
- * refresh, so the refresh takes a new generation to restart it even though the
1818
- * field is already stale.
1819
- */
1820
- export declare const refreshIsInFlight: (refresh: RefreshState, request: Requirement, field: string) => boolean;
1821
- /**
1822
- * Whether a read is fetching any of `fields` for this entity. Consulted only
1823
- * when the store lacks the value, which is what separates `Loading` from
1824
- * `Initial`.
1825
- */
1826
- export declare const isLoading: (model: RemoteModel, entity: string, id: string, fields: ReadonlyArray<string>) => boolean;
1827
- /**
1828
- * The pure reducer all four producers share. A live event that arrives ahead of
1829
- * its cursor is a gap: it is not applied, and the stream is recorded so the host
1830
- * can resubscribe rather than silently miss facts. When every field a Message
1831
- * touches keeps its identity, `model` itself is returned, so the application's
1832
- * root keeps its identity and Foldkit does not render. The common no-ops do (a
1833
- * duplicate live event, a repeated `ReadStarted`); a repeated failure, or a
1834
- * `preserve-existing` restore of entities already held, still makes an equal
1835
- * copy.
1836
- */
1837
- export declare const updateRemote: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
1838
- /** Whether this field's last read failed and nothing has settled it since. */
1839
- export declare const isFieldFailed: (model: RemoteModel, entity: string, id: string, field: string) => boolean;
1840
- /**
1841
- * Whether a read is fetching any field `relation` reads of an entity, its own
1842
- * or, through each relation the store holds, its targets'. A value whose owner
1843
- * is being fetched is loading, not `Initial`: nothing is missing a fetch.
1844
- */
1845
- export declare const isLoadingThrough: (model: RemoteModel, entity: string, id: string, relation: RelationRequirement) => boolean;
1846
- /**
1847
- * The first failure among the fields `relation` reads of an entity, following
1848
- * each relation the store holds into its targets, as `assemble` does. A read
1849
- * that consults it shows `Failed` for a related entity's failure too, rather
1850
- * than waiting on a field nothing will fetch.
1851
- */
1852
- export declare const failureOf: (model: RemoteModel, entity: string, id: string, relation: RelationRequirement) => RemoteError | undefined;
1853
- /**
1854
- * Writes a read result into the store, recording each field's applied window so
1855
- * a later request with a different window refetches. A relation page requested
1856
- * with a cursor is merged onto the page already stored, so "load more"
1857
- * accumulates rather than replaces. Every read path should use this rather than
1858
- * reducing `writeEntity` by hand.
1859
- */
1860
- export declare const writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
1861
- //#endregion
1862
- //#region src/resume.d.ts
1863
- /**
1864
- * A resume part, in the shape `foldkit-ssr`'s `SSR.plan` takes in `parts`.
1865
- * Declared here structurally, so neither package depends on the other.
1866
- */
1867
- interface RemoteResumePart<AppModel> {
1868
- readonly id: string;
1869
- /** The metadata key names whose reads this part resumes. */
1870
- readonly covers: ReadonlyArray<string>;
1871
- readonly capture: (model: AppModel, projections: ReadonlyArray<{
1872
- readonly metadata: Metadata;
1873
- }>) => unknown;
1874
- readonly restore: (model: AppModel, value: unknown) => Result.Result<AppModel, string>;
1875
- /** Whether a Subscription entry is one of this domain's, which may start late. */
1876
- readonly deferrable: (key: string, entry: unknown) => boolean;
1877
- }
1878
- //#endregion
1879
- //#region src/coalesce.d.ts
1880
- type Batch = Schema.Schema.Type<typeof ReadBatch>;
1881
- type BatchResult = Schema.Schema.Type<typeof ReadBatchResult>;
1882
- type ReadError = RemoteReadError | RemoteProtocolError;
1883
- export type BatchRead = (batch: Batch) => Effect.Effect<BatchResult, ReadError>;
1884
- type QueryRequestValue = Schema.Schema.Type<typeof QueryRequest>;
1885
- type QueryResultValue = Schema.Schema.Type<typeof QueryResult>;
1886
- export type QueryRun = (request: QueryRequestValue) => Effect.Effect<QueryResultValue, RemoteQueryError>;
1887
- export interface CoalesceOptions {
1888
- /**
1889
- * How long a batch waits to collect more requirements before it runs.
1890
- * Requirements issued concurrently coalesce even at the default of no wait.
1891
- */
1892
- readonly window?: Duration.Input | undefined;
1893
- }
1894
- /** A stable key for a requirement, so an equal requirement in flight is joined. */
1895
- export declare const requirementKey: (requirement: Requirement) => string;
1896
- /**
1897
- * Wraps a raw query so that an identical query in flight (same query, input,
1898
- * and window) is joined rather than run again; distinct queries run
1899
- * concurrently. A page answers exactly one window, so nothing is batched.
1900
- */
1901
- export declare const coalesceQueries: (query: QueryRun, options?: CoalesceOptions) => Effect.Effect<QueryRun>;
1902
- /**
1903
- * Wraps a raw batch read so that requirements are batched and deduplicated.
1904
- * Every waiter receives the whole batch result; `Remote.writeRead` is
1905
- * idempotent, so writing it more than once is harmless.
1906
- */
1907
- export declare const coalesceReads: (read: BatchRead, options?: CoalesceOptions) => Effect.Effect<BatchRead>;
1908
- //#endregion
1909
- //#region src/client.d.ts
1910
- declare const RemoteClient_base: Context.ServiceClass<RemoteClient, "foldkit-remote/RemoteClient", {
1911
- readonly read: (batch: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError>;
1912
- readonly query: (request: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError>;
1913
- readonly mutate: (request: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError>;
1914
- readonly live: (request: {
1915
- readonly requirements: ReadonlyArray<Requirement>;
1916
- readonly after: LiveCursor;
1917
- }) => Stream.Stream<LiveEvent, RemoteLiveError | RemoteProtocolError>;
1918
- }>;
1919
- /**
1920
- * The transport boundary. `foldkit-remote` never talks to a transport directly;
1921
- * it depends on this Effect service, which a later phase wires to Effect RPC.
1922
- */
1923
- export declare class RemoteClient extends RemoteClient_base {}
1924
- /**
1925
- * The methods an Effect RPC client for `RemoteRpc` exposes. `R` is the
1926
- * environment a handler needs; it defaults to `never`, which is what a real
1927
- * transport client satisfies. `RemoteServer.handlers` returns this type with its
1928
- * own `R`, so the two sides cannot drift apart.
1929
- *
1930
- * `TransportError` is what the transport itself may fail with on top of the
1931
- * declared errors: `RpcClientError` for the client `RpcClient.make` builds,
1932
- * `never` for in-process handlers.
1933
- */
1934
- export interface RemoteRpcClient<R = never, TransportError = never> {
1935
- readonly FoldkitRemoteRead: (payload: Schema.Schema.Type<typeof ReadBatch>) => Effect.Effect<Schema.Schema.Type<typeof ReadBatchResult>, RemoteReadError | RemoteProtocolError | TransportError, R>;
1936
- readonly FoldkitRemoteQuery: (payload: Schema.Schema.Type<typeof QueryRequest>) => Effect.Effect<Schema.Schema.Type<typeof QueryResult>, RemoteQueryError | TransportError, R>;
1937
- readonly FoldkitRemoteMutate: (payload: Schema.Schema.Type<typeof MutationRequest>) => Effect.Effect<Schema.Schema.Type<typeof MutationResult>, RemoteMutationError | TransportError, R>;
1938
- readonly FoldkitRemoteLive: (payload: Schema.Schema.Type<typeof LiveRequirement>) => Stream.Stream<Schema.Schema.Type<typeof LiveChange>, RemoteLiveError | RemoteProtocolError | TransportError, R>;
1939
- }
1940
- /** Reconstructs the client's `ConnectionChange` from the wire's flattened edge. */
1941
- export declare const connectionChangeOf: (change: Schema.Schema.Type<typeof ConnectionChangeSchema>) => ConnectionChange;
1942
- /** Reconstructs the client's `LiveEvent` from the wire's flattened `LiveChange`. */
1943
- export declare const liveEventOf: (change: Schema.Schema.Type<typeof LiveChange>) => LiveEvent;
1944
- export declare const remoteError: (error: {
1945
- readonly _tag: string;
1946
- readonly message: string;
1947
- }) => RemoteError;
1948
- export declare const coalescedLayer: <E, R>(layer: Layer.Layer<RemoteClient, E, R>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, E, R>;
1949
- /**
1950
- * `Remote.mutate` as a standalone effect, so `Remote.mutateInto` can reuse it
1951
- * without the object literal referencing itself.
1952
- */
1953
- export declare const mutateRemote: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string) => Effect.Effect<{
1954
- output: Output;
1955
- entities: readonly {
1956
- readonly entity: string;
1957
- readonly id: string;
1958
- readonly values: {
1959
- readonly [x: string]: unknown;
1960
- };
1961
- }[];
1962
- connections: ConnectionChange[];
1963
- deleted: readonly {
1964
- readonly entity: string;
1965
- readonly id: string;
1966
- }[];
1967
- }, RemoteMutationError, RemoteClient>;
1968
- //#endregion
1969
- //#region src/relation.d.ts
1970
- export interface RefParts {
1971
- readonly entity: string;
1972
- readonly id: string;
1973
- }
1974
- /** A page of refs as the wire and the store hold it. */
1975
- export interface RefPageValue {
1976
- readonly refs: ReadonlyArray<string>;
1977
- readonly hasNext: boolean;
1978
- readonly hasPrevious: boolean;
1979
- }
1980
- /** Marks the codec `Entity.ref`/`Entity.refPage` produce, so a Selection can tell the field's shape. */
1981
- export declare const RelationAnnotation = "foldkitRemoteRelation";
1982
- /** The target entity's name on the same codec, so a nested selection of another entity is refused. */
1983
- export declare const RelationEntityAnnotation = "foldkitRemoteRelationEntity";
1984
- export type RelationKind = 'one' | 'many' | 'page';
1985
- export interface RelationShape {
1986
- readonly kind: RelationKind;
1987
- readonly nullable: boolean;
1988
- readonly entity: string;
1989
- }
1990
- /**
1991
- * A page of a relation that is a whole list is read under a name of its own, the
1992
- * field's name and the page's size: `comments@first=10`. It is a field like any
1993
- * other to the store, the planner, and the wire, so the whole list and a page of
1994
- * it are held side by side, merged, marked stale, and persisted each on its own.
1995
- * The server reads the name apart, reads the relation with the window, and
1996
- * answers under the alias. A cursor is not part of the name: a page read from a
1997
- * cursor merges onto the page it continues.
1998
- */
1999
- export declare const RELATION_ALIAS = "@";
2000
- /** The alias a relation field is read under, for a window of this size. */
2001
- export declare const relationAlias: (field: string, window: {
2002
- readonly first?: number | undefined;
2003
- readonly last?: number | undefined;
2004
- readonly after?: string | undefined;
2005
- readonly before?: string | undefined;
2006
- }) => string;
2007
- /** The field an alias reads; a name that is no alias is its own field. */
2008
- export declare const aliasedField: (name: string) => string;
2009
- /** Splits a ref key (`"Entity:id"`, the store key too) back into its parts. */
2010
- export declare const refParts: (encoded: string) => RefParts;
2011
- /**
2012
- * The refs a relation value carries, in order. Anything that is not a ref key,
2013
- * an array of them, or a page of them contributes nothing.
2014
- */
2015
- export declare const refsIn: (value: unknown) => ReadonlyArray<RefParts>;
2016
- /** The refs in a relation value that name the relation's target entity, and no other. */
2017
- export declare const targetsOf: (value: unknown, relation: RelationRequirement) => ReadonlyArray<RefParts>;
2018
- export declare const isRefPage: (value: unknown) => value is RefPageValue;
2019
- /**
2020
- * The relation shape an entity field schema declares: a ref (`one`), a nullable
2021
- * ref, an array of refs (`many`), or a page of refs (`page`). `undefined` for a
2022
- * scalar field, which cannot take a nested selection.
2023
- */
2024
- export declare const relationShape: (schema: Schema.Top) => RelationShape | undefined;
2025
- //#endregion
2026
- //#region src/selection.d.ts
2027
- /** One page of a paginated relation with each target assembled through a nested selection. */
2028
- export interface Page<Item> {
2029
- readonly items: ReadonlyArray<Item>;
2030
- readonly hasNext: boolean;
2031
- readonly hasPrevious: boolean;
2032
- }
2033
- /**
2034
- * The fields a projection reads of one entity, plus the slice it reads of each
2035
- * relation's target. `Shape` tells a parent selection whether this one is a
2036
- * paginated relation (`connection`) or a plain entity slice (`entity`).
2037
- */
2038
- export interface Selection<Value, Name extends string = string, Shape extends 'entity' | 'connection' = 'entity' | 'connection'> {
2039
- readonly entity: Name;
2040
- readonly fields: readonly string[];
2041
- /** A pure codec: entity fields carry no decoding or encoding services. */
2042
- readonly schema: Schema.Codec<Value, unknown, never, never>;
2043
- /** Pagination windows for nested relation fields, keyed by field name. */
2044
- readonly connections?: Readonly<Record<string, QueryWindow>> | undefined;
2045
- /** The slice required of each nested relation's target, keyed by field name. */
2046
- readonly relations?: Readonly<Record<string, RelationRequirement>> | undefined;
2047
- /** Present when this selection is itself a paginated relation. */
2048
- readonly window?: QueryWindow | undefined;
2049
- /** Phantom: see `Shape`. */
2050
- readonly shape?: Shape | undefined;
2051
- }
2052
- /** Flattens a mapped type so hovers show the picked fields, not the machinery. */
2053
- type Simplify<T> = T extends (infer O) ? { readonly [K in keyof O]: O[K]; } : never;
2054
- /** The value a Selection reads: `Selection.Value<typeof ProjectCard>`. */
2055
- export type SelectionValueOf<S> = S extends Selection<infer V, any, any> ? V : never;
2056
- /** The nested selections a relation field admits: of its target entity, in the shapes its value takes. */
2057
- type NestedFor<Field> = Exclude<Field, null | undefined> extends ReadonlyArray<EntityRef<infer Name, any>> ? Selection<unknown, Name, 'entity' | 'connection'> : Exclude<Field, null | undefined> extends RefPage<infer Name, any> ? Selection<unknown, Name, 'entity' | 'connection'> : Exclude<Field, null | undefined> extends EntityRef<infer Name, any> ? Selection<unknown, Name, 'entity'> : never;
2058
- /** What a selection of an entity with fields `F` may pick: `true` per scalar, a nested selection per relation. */
2059
- export type SelectionOf<F extends Schema.Struct.Fields> = { readonly [K in keyof F]?: true | NestedFor<Schema.Schema.Type<F[K]>>; };
2060
- /** `T | null` when the field admits `null` or `undefined` (both assemble to `null`). */
2061
- type Nullable<Field, T> = [Extract<Field, null | undefined>] extends [never] ? T : T | null;
2062
- /** A nested selection's value takes the shape of the field it selects through. */
2063
- type NestedValue<Field, Sel> = Sel extends Selection<infer V, string, 'connection'> ? Nullable<Field, V> : Sel extends Selection<infer V, string, 'entity'> ? Nullable<Field, Exclude<Field, null | undefined> extends ReadonlyArray<EntityRef<any, any>> ? ReadonlyArray<V> : Exclude<Field, null | undefined> extends RefPage<any, any> ? Page<V> : V> : never;
2064
- /** The value a selection `Sel` of fields `F` reads. */
2065
- export type SelectionValue<F extends Schema.Struct.Fields, Sel> = Simplify<{ readonly [K in keyof Sel & keyof F]: Sel[K] extends true ? Schema.Schema.Type<F[K]> : NestedValue<Schema.Schema.Type<F[K]>, Sel[K]>; }>;
2066
- export declare const pageSchema: (item: AnySchema) => AnySchema;
2067
- /** The requirement a nested selection contributes for its relation's target. */
2068
- export declare const relationOf: (selection: Selection<unknown>) => RelationRequirement;
2069
- export declare const Selection: {
2070
- /**
2071
- * The Remote Selection of a `foldkit-entity` Selection: the same members, read
2072
- * from Remote's store. `true` on a relation reads its refs, as it does here.
2073
- */
2074
- from: <Name extends string, S extends Schema.Constraint>(selection: Domain.Selection<Name, unknown, S>) => Selection<S["Type"], Name, "entity">;
2075
- /**
2076
- * The fields to read of `entity`. A nested `Selection` on a relation field
2077
- * reads through the ref (or refs, or page of refs) the field holds into the
2078
- * target's fields; a scalar field cannot take one.
2079
- */
2080
- make: <Name extends string, F extends Schema.Struct.Fields, const Sel extends SelectionOf<F>>(entity: EntityDescriptor<Name, F>, selection: Sel) => Selection<SelectionValue<F, Sel>, Name, "entity">;
2081
- /**
2082
- * A paginated relation: one page of refs to `entity` with a window, or, with
2083
- * a nested selection, one page of targets assembled through it.
2084
- */
2085
- connection: {
2086
- <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>, window: QueryWindow): Selection<RefPage<Name, F>, Name, "connection">;
2087
- <Name extends string, F extends Schema.Struct.Fields, Item>(entity: EntityDescriptor<Name, F>, window: QueryWindow, selection: Selection<Item, NoInfer<Name>, "entity">): Selection<Page<Item>, Name, "connection">;
2088
- };
2089
- };
2090
- interface Assembled {
2091
- readonly values: unknown;
2092
- readonly refreshing: boolean;
2093
- }
2094
- /**
2095
- * Reads an entity's selected fields out of the store, following each nested
2096
- * relation into its targets. `undefined` means some field, at any depth, is
2097
- * not present yet. A tombstoned target reads as `null` (or is dropped from a
2098
- * list), so the Selection's codec decides whether that is a failure.
2099
- */
2100
- export declare const assemble: (store: EntityStore, key: string, requirement: RelationRequirement) => Assembled | undefined;
2101
- /**
2102
- * The first field `requirement` reads, at any depth, that the server settled
2103
- * without a value, as `Entity:id.field`. A read that consults it says why it
2104
- * cannot assemble rather than waiting on a field nothing will fetch.
2105
- */
2106
- export declare const unavailableOf: (store: EntityStore, key: string, requirement: RelationRequirement) => string | undefined;
2107
- //#endregion
2108
- //#region src/entity.d.ts
2109
- export type AnySchema = Schema.Schema<unknown>;
2110
- declare const entityRefFields: unique symbol;
2111
- /**
2112
- * A normalized reference to an entity. `F` is a phantom carrying the entity's
2113
- * fields so `Entity.patch` can type its patch; it is absent at runtime.
2114
- */
2115
- export interface EntityRef<Name extends string, F extends Schema.Struct.Fields = Schema.Struct.Fields> {
2116
- readonly entity: Name;
2117
- readonly id: string;
2118
- readonly [entityRefFields]?: F;
2119
- }
2120
- export interface EntityDescriptor<Name extends string, F extends Schema.Struct.Fields> {
2121
- readonly name: Name;
2122
- readonly schema: Schema.Struct<F>;
2123
- readonly fields: F;
2124
- ref(id: Schema.Schema.Type<F['id']>): EntityRef<Name, F>;
2125
- /** The fields a Surface reads of this entity; `Selection.make(entity, …)` with the entity as receiver. */
2126
- select<const Sel extends SelectionOf<F>>(selection: Sel): Selection<SelectionValue<F, Sel>, Name, 'entity'>;
2127
- /** A patch of this entity's wire-shaped values; `Entity.patch(entity.ref(id), values)`. */
2128
- patch(id: Schema.Schema.Type<F['id']>, values: Partial<Schema.Struct.Encoded<F>>): EntityPatch<Name, F>;
2129
- }
2130
- /**
2131
- * Relations are **references**, never inline target schemas: a ref cannot
2132
- * reconstruct a full entity, and dereferencing is a store concern. Because the
2133
- * target schema is not inlined, recursive relations cannot arise through the
2134
- * schema graph.
2135
- */
2136
- /**
2137
- * A ref as the wire carries it: the target's name, a colon, and its id. Typed
2138
- * with the name, so a relation to `User` takes `'User:u1'` and not a ref to
2139
- * some other entity, which would read as a row that does not exist.
2140
- */
2141
- export type RefKey<Name extends string> = `${Name}:${string}`;
2142
- /**
2143
- * A patch in wire shape: the values the store holds, so a relation is its ref
2144
- * key (`Entity.refKey`), not an `EntityRef`.
2145
- */
2146
- export interface EntityPatch<Name extends string, F extends Schema.Struct.Fields> {
2147
- readonly entity: Name;
2148
- readonly id: string;
2149
- readonly values: Partial<Schema.Struct.Encoded<F>>;
2150
- }
2151
- /**
2152
- * One authoritative page of a paginated relation: refs (never inline entities)
2153
- * plus whether more exist. The adapter does not hold segmentation state; the
2154
- * client merges pages.
2155
- */
2156
- export interface RefPage<Name extends string, F extends Schema.Struct.Fields = Schema.Struct.Fields> {
2157
- readonly refs: ReadonlyArray<EntityRef<Name, F>>;
2158
- readonly hasNext: boolean;
2159
- readonly hasPrevious: boolean;
2160
- }
2161
- /** The ref codec a `foldkit-entity` relation becomes: one ref, a nullable ref, or an array of refs. */
2162
- type RelationField<Spec> = Spec extends Domain.RelationSpec<infer Target, infer Cardinality, infer Optional> ? Cardinality extends 'many' ? Schema.$Array<Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>>> : Optional extends true ? Schema.NullOr<Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>>> : Schema.Codec<EntityRef<Target['name']>, RefKey<Target['name']>> : never;
2163
- /**
2164
- * The fields Remote stores for a `foldkit-entity` Entity: its own fields, its
2165
- * derived members (the server supplies them like any field), and each relation
2166
- * as refs.
2167
- */
2168
- export type FieldsFrom<E> = E extends Domain.Entity<any, infer Fields, infer Relations, infer Derived> ? Fields & { readonly [K in keyof Derived]: Derived[K]['schema']; } & { readonly [K in keyof Relations]: RelationField<Relations[K]>; } : never;
2169
- declare const Entity$1: {
2170
- /**
2171
- * The Remote descriptor of a `foldkit-entity` Entity. Relations declared with
2172
- * `Entity.relate` become ref fields, so the store, the planner, and the server
2173
- * treat it as they treat an `Entity.make` descriptor.
2174
- */
2175
- from: <E extends Domain.AnyEntity>(entity: E & {
2176
- readonly fields: {
2177
- readonly id: unknown;
2178
- };
2179
- }) => EntityDescriptor<E["name"], FieldsFrom<E>>;
2180
- make: <const Name extends string, const F extends Schema.Struct.Fields & {
2181
- readonly id: Schema.Schema<unknown>;
2182
- }>(name: Name, schema: Schema.Struct<F>) => EntityDescriptor<Name, F>;
2183
- /** A relation to a known entity, decoded as a reference. */
2184
- ref: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<EntityRef<Name, F>, RefKey<Name>>;
2185
- /** A relation by name, for recursive or forward references. */
2186
- refTo: <Name extends string>(name: Name) => Schema.Codec<EntityRef<Name>, RefKey<Name>>;
2187
- /**
2188
- * The wire key a relation field carries (`"Entity:id"`). Adapters that read a
2189
- * foreign key emit this so the ref codec can decode it on the client.
2190
- */
2191
- refKey: (ref: {
2192
- readonly entity: string;
2193
- readonly id: string;
2194
- }) => string;
2195
- /** Splits a ref key back into its entity and id. */
2196
- refParts: (encoded: string) => RefParts;
2197
- /** A relation value of one authoritative page of refs. */
2198
- refPage: <Name extends string, F extends Schema.Struct.Fields>(entity: EntityDescriptor<Name, F>) => Schema.Codec<RefPage<Name, F>, {
2199
- readonly refs: ReadonlyArray<string>;
2200
- readonly hasNext: boolean;
2201
- readonly hasPrevious: boolean;
2202
- }>;
2203
- /**
2204
- * A normalized patch for an entity, typed against its fields' wire shape:
2205
- * write a relation as its ref key (`Entity.refKey`), as the server does.
2206
- */
2207
- patch: <Name extends string, F extends Schema.Struct.Fields>(ref: EntityRef<Name, F>, patch: Partial<Schema.Struct.Encoded<F>>) => EntityPatch<Name, F>;
2208
- };
2209
- //#endregion
2210
- //#region src/matching.d.ts
2211
- /**
2212
- * An answer over the rows the client holds — never over the rows that exist.
2213
- *
2214
- * `complete` is the whole reason this is its own type rather than a `Page`. A
2215
- * `Page` carries `hasNext`/`hasPrevious`, which are facts the *server* stated
2216
- * about rows beyond the ones it delivered; a local answer has no such facts and
2217
- * cannot invent them. What it can say is whether the population it judged was
2218
- * all of it, which is decidable: a connection terminal at both ends is wholly
2219
- * held, and nothing was skipped for a missing field.
2220
- *
2221
- * An incomplete answer is not wrong — it is an answer about less than the
2222
- * caller may have meant, and the flag is what lets a view say "3 so far" rather
2223
- * than "3", or a caller decide to ask the server.
2224
- */
2225
- export interface Matched<A> {
2226
- readonly items: ReadonlyArray<A>;
2227
- /** Whether every row the answer is about was judged. */
2228
- readonly complete: boolean;
2229
- }
2230
- /**
2231
- * What the rows the client holds had to say about a body.
2232
- *
2233
- * `skipped` is the honest half. A row missing a field the body reads cannot be
2234
- * judged — it is neither a match nor a non-match — and dropping it silently
2235
- * would turn "I could not tell" into "no". Naming it lets a caller decide:
2236
- * fetch the field, ask the server, or say the answer is partial.
2237
- */
2238
- export interface Judged {
2239
- /** Keys of the rows that satisfy the body, in the order the body asks for. */
2240
- readonly matched: ReadonlyArray<EntityKey>;
2241
- /** Keys of rows held but missing a field the body reads, so not judged either way. */
2242
- readonly skipped: ReadonlyArray<EntityKey>;
2243
- }
2244
- export interface MatchingOptions {
2245
- /**
2246
- * Judge only these keys. Without it every row of the body's Entity in the
2247
- * store is a candidate, which is what a filter over a loaded list wants; with
2248
- * it, a caller narrows to a connection's own edges.
2249
- */
2250
- readonly among?: ReadonlyArray<EntityKey> | undefined;
2251
- }
2252
- /**
2253
- * The rows of `descriptor`'s Entity that the store holds and the body matches.
2254
- *
2255
- * The input is given **decoded**, as an application writes it, and encoded here
2256
- * through the descriptor's own `Input` codec. That is deliberate and is the
2257
- * whole reason this takes a descriptor rather than a bare body: a store holds
2258
- * wire values, so an input has to be in that space to be compared against them,
2259
- * and handing an interpreter a decoded value is a mistake **no runtime error
2260
- * catches** — the reference interpreter answers "no rows", which reads exactly
2261
- * like a correct answer. Doing it here means a caller cannot get it wrong.
2262
- *
2263
- * Literals in the body are deliberately *not* encoded. A literal written in
2264
- * domain terms is already broken against the server, which binds it to a column
2265
- * the same way; accepting it here would make the client quietly more permissive
2266
- * than the thing it has to agree with.
2267
- */
2268
- export declare const matching: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, input: Input, options?: MatchingOptions) => Judged;
2269
- /**
2270
- * Whether one row belongs to a query, as far as the client can tell.
2271
- *
2272
- * Three answers, and the third is the one that makes this usable. `'unknown'`
2273
- * is a row the store never fetched, or holds without a field the body reads —
2274
- * a caller that collapses it into `'no'` has turned "I could not tell" into an
2275
- * answer, which is the mistake this whole module is shaped against.
2276
- *
2277
- * **Membership is decidable where position is not.** Whether a row satisfies
2278
- * `eq`, `isNull` or `contains` needs no collation: equality on text is exact
2279
- * and `contains` folds ASCII, both stated in §6.0.1. *Where* a row sorts needs
2280
- * text collation, which is the backend's and deliberately outside the
2281
- * conformant subset — so this answers the half that is always answerable, and
2282
- * ordering stays the server's until a query can declare its collation.
2283
- */
2284
- export type Belongs = 'yes' | 'no' | 'unknown';
2285
- /**
2286
- * Takes the input **encoded**, because its one caller holds it that way: a
2287
- * connection identity carries the canonical encoded input, and making it decode
2288
- * only for this to encode again would be a round trip that can fail.
2289
- *
2290
- * A decoded-input sibling was written first and deleted: nothing called it. The
2291
- * asymmetry with `matching`, which takes a decoded input, is the shape of the
2292
- * two real callers rather than an oversight.
2293
- */
2294
- export declare const belongsEncoded: <Name extends string, Input>(store: EntityStore, descriptor: QueryDescriptor<Name, Input, unknown>, encoded: Readonly<Record<string, unknown>>, key: EntityKey) => Belongs;
2295
- //#endregion
2296
- //#region src/inspect.d.ts
2297
- /** A query body's `Dependencies` as plain data: each field by its Entity's name and key. */
2298
- export interface ExplainedDependencies {
2299
- readonly fields: ReadonlyArray<{
2300
- readonly entity: string;
2301
- readonly key: string;
2302
- }>;
2303
- readonly inputs: Dependencies['inputs'];
2304
- readonly operations: Dependencies['operations'];
2305
- }
2306
- /** A serializable summary of a RemoteModel for DevTools and diagnostics. */
2307
- export interface RemoteInspection {
2308
- readonly entities: ReadonlyArray<{
2309
- readonly key: string;
2310
- readonly present: ReadonlyArray<string>;
2311
- readonly stale: ReadonlyArray<string>;
2312
- readonly unavailable: ReadonlyArray<string>;
2313
- readonly tombstone: boolean;
2314
- readonly updatedAt: number;
2315
- readonly windows: Readonly<Record<string, string>>;
2316
- }>;
2317
- readonly connections: ReadonlyArray<string>;
2318
- readonly live: ReadonlyArray<string>;
2319
- readonly gaps: ReadonlyArray<string>;
2320
- /**
2321
- * The `entity\0id\0field` marks of reads in flight, and a
2322
- * `\0connection\0identity` mark for each query in flight. This is what "Remote is
2323
- * working" means here, and it is read from the Model rather than from the
2324
- * fibers doing the work: a tool that shows it shows something the Model can
2325
- * be replayed to, and nothing that needs the runtime to be asked.
2326
- */
2327
- readonly loading: ReadonlyArray<string>;
2328
- /**
2329
- * The reads that failed and are not yet settled: queries by connection
2330
- * identity, entity fields by `entity\0id\0field` mark, each with its error.
2331
- */
2332
- readonly failures: Failures;
2333
- readonly mutations: {
2334
- readonly pending: ReadonlyArray<string>;
2335
- readonly failed: ReadonlyArray<string>;
2336
- readonly applied: number;
2337
- };
2338
- }
2339
- /** A pure, serializable view of the whole cache. */
2340
- export declare const inspectRemote: (model: RemoteModel) => RemoteInspection;
2341
- /** A pure, serializable view of one entity, or `undefined` if unknown. */
2342
- export declare const inspectEntity: (model: RemoteModel, key: string) => RemoteInspection["entities"][number] | undefined;
2343
- /**
2344
- * Why a read shows what it shows, in words, and for `Initial`, which of the
2345
- * usual mistakes it is.
2346
- *
2347
- * `Initial` means nothing is fetching the read, and that is almost always
2348
- * wiring rather than the network: no active Surface reads it, or one does and
2349
- * Remote's Subscriptions are not running. The Model can tell those apart when
2350
- * it is given the active record, so this says which, and what to do.
2351
- */
2352
- export interface ReadDiagnosis {
2353
- readonly state: RemoteData<unknown>['_tag'];
2354
- /**
2355
- * For `Initial` only. `NotObserved`: no active Surface reads it.
2356
- * `NotFetching`: one does, and nothing is fetching it, so Remote's
2357
- * Subscriptions are most likely not installed. `Unknown`: no active record
2358
- * was given to tell.
2359
- */
2360
- readonly reason?: 'NotObserved' | 'NotFetching' | 'Unknown' | undefined;
2361
- /** One or two sentences a developer can act on. */
2362
- readonly message: string;
2363
- /** The active Surfaces reading it, when the active record was given. */
2364
- readonly surfaces?: ReadonlyArray<string> | undefined;
2365
- }
2366
- /**
2367
- * What one query read is, and what it currently is — data-query-DESIGN §29.1.
2368
- *
2369
- * Every member is gathered from something that already existed: the read was
2370
- * always this many pieces, and nothing had ever been asked to put them in one
2371
- * place. It is plain serializable data, so a DevTools panel, a log line and a
2372
- * test assert on the same value.
2373
- *
2374
- * Two members of §29.1's sketch are **not** here, and their absence is the
2375
- * finding rather than an omission:
2376
- *
2377
- * - **Surface.** A Projection does not know which Surface reads it, and often
2378
- * several do — so it is not a property of the read, and `explain` cannot
2379
- * recover it alone. Given the active Surfaces (the same record
2380
- * `subscriptions` takes), it reports **every** Surface reading the connection
2381
- * rather than guessing one, and omits the member entirely when it was not
2382
- * given them.
2383
- * - **Executor.** The thing that answers a query is a `RemoteClient` Layer in
2384
- * the runtime, not a value in the Model, and a pure read of the Model cannot
2385
- * see it. That is the same boundary that makes this function pure and
2386
- * replayable, so it is worth more than the line of text.
2387
- *
2388
- * And one that the design proposed and this does not want: *expectation*
2389
- * (required versus optional). §11 left it unbuilt for want of a consumer, and
2390
- * the explanation was the likeliest consumer. It turns out not to need it — a
2391
- * query's result is a connection, so the shape is a `Page`, decided by the
2392
- * definition rather than by the read. Nothing here has an opinion about whether
2393
- * an empty one is an error, because nothing here has to have one.
2394
- */
2395
- export interface QueryExplanation {
2396
- /** The bound Remote domain that answers it. */
2397
- readonly domain: string;
2398
- /** The definition's name. */
2399
- readonly query: string;
2400
- /** The input as encoded, which is what the identity is built from. */
2401
- readonly input: unknown;
2402
- /** The connection identity: definition plus canonical input, excluding the window. */
2403
- readonly identity: string;
2404
- /** How much of the connection this read asks for. */
2405
- readonly window: QueryWindow;
2406
- /** What it reads of each item, as the slice asked of the server. */
2407
- readonly select: RelationRequirement;
2408
- /**
2409
- * What the query means, as readable text — `Query.show`, and so neither SQL
2410
- * nor whatever the backend compiled. Absent for a definition made with
2411
- * `Query.make`, whose meaning lives on the server that answers it.
2412
- */
2413
- readonly body?: string | undefined;
2414
- /**
2415
- * The fields, inputs and operations the body reads; absent with the body.
2416
- * Plain data, so it serializes: a field is its Entity's name and key, which
2417
- * is unambiguous because a query reads one Entity.
2418
- */
2419
- readonly dependencies?: ExplainedDependencies | undefined;
2420
- /** What the read answers from this Model right now. */
2421
- readonly state: RemoteData<unknown>['_tag'];
2422
- /**
2423
- * The active Surfaces reading this connection at this Model, if the active
2424
- * record was supplied. Plural because several may, which is why a Projection
2425
- * cannot carry the answer itself.
2426
- */
2427
- readonly surfaces?: ReadonlyArray<string> | undefined;
2428
- /**
2429
- * Why each of those Surfaces is active, where it was placed with
2430
- * `Surface.when` — the Model path and the tag, without running anything. A
2431
- * Surface placed with `Surface.at` has no entry: a callback cannot be read.
2432
- */
2433
- readonly activation?: ReadonlyArray<{
2434
- readonly surface: string;
2435
- readonly path: readonly string[];
2436
- readonly tag: string;
2437
- }> | undefined;
2438
- }
2439
- //#endregion
2440
- //#region src/plan.d.ts
2441
- type Window = NonNullable<Requirement['windows']>[string];
2442
- /** A stable key for a window, so two equal windows compare equal. */
2443
- export declare const windowKey: (window: Window) => string;
2444
- export interface PlanFreshness {
2445
- readonly now: number;
2446
- /** A present entry older than this many milliseconds is refreshed whole. */
2447
- readonly freshness: number;
2448
- }
2449
- export interface PlanOptions {
2450
- readonly freshness?: PlanFreshness | undefined;
2451
- /** Plan every requested field, present or not, tombstoned or not. */
2452
- readonly force?: boolean | undefined;
2453
- }
2454
- /** When present values next go stale, and the requirements of the entities that do. */
2455
- export interface Deadline {
2456
- readonly at: number;
2457
- readonly due: ReadonlyArray<Requirement>;
2458
- }
2459
- /**
2460
- * The earliest moment a value `requirements` read, following the relations the
2461
- * store holds as `plan` does, goes stale under `freshness`, with the
2462
- * requirements of the entities that go stale then. A field the server settled
2463
- * without a value ages with its entity too, since `plan` asks for it again once
2464
- * the entity expires. Nothing when no such field is still fresh: what is
2465
- * already expired or stale is planned, not awaited, which is what keeps a
2466
- * timer from firing on what it already fired on. It is the next moment the
2467
- * plan can change with the clock alone, which the read entry relies on to
2468
- * reuse its plan until then.
2469
- */
2470
- export declare const deadlineOf: (store: EntityStore, requirements: readonly Requirement[], freshness: PlanFreshness) => Deadline | undefined;
2471
- export declare const plan: (store: EntityStore, requirements: readonly Requirement[], options?: PlanOptions) => ReadonlyArray<Requirement>;
2472
- //#endregion
2473
- //#region src/policy.d.ts
2474
- export type RemotePolicy =
2475
- /** Fetch only fields the store lacks (missing, stale, or re-windowed). */
2476
- {
2477
- readonly _tag: 'CacheFirst';
2478
- } |
2479
- /**
2480
- * Keep present values visible, read them as `Refreshing`, and refetch an
2481
- * entry older than `maxAge` milliseconds.
2482
- */
2483
- {
2484
- readonly _tag: 'StaleWhileRevalidate';
2485
- readonly maxAge: number;
2486
- } |
2487
- /** Fetch every selected field regardless of coverage; cached values stay visible meanwhile. */
2488
- {
2489
- readonly _tag: 'NetworkOnly';
2490
- };
2491
- export declare const RemotePolicy: {
2492
- /** Fetch only what the store lacks. */
2493
- cacheFirst: {
2494
- readonly _tag: "CacheFirst";
2495
- };
2496
- /** Keep present values visible, read as `Refreshing`, and refetch an entry older than `maxAge` ms. */
2497
- staleWhileRevalidate: (options: {
2498
- readonly maxAge: number;
2499
- }) => RemotePolicy;
2500
- /** Fetch every selected field regardless of coverage; cached values stay visible meanwhile. */
2501
- networkOnly: {
2502
- readonly _tag: "NetworkOnly";
2503
- };
2504
- /** The planner options a policy compiles to at `now`. */
2505
- toPlan: (policy: RemotePolicy, now: number) => PlanOptions;
2506
- /**
2507
- * Whether a read under this policy may refetch fields the store already
2508
- * holds, so an observer marks them stale (read as `Refreshing`) while the
2509
- * request is pending.
2510
- */
2511
- refreshes: (policy: RemotePolicy) => boolean;
2512
- };
2513
- //#endregion
2514
- //#region src/index.d.ts
2515
- /** What a domain registers: a Remote descriptor, or a `foldkit-entity` Entity (read through `Entity.from`). */
2516
- export type EntityLike = EntityDescriptor<any, any> | Domain.AnyEntity;
2517
- /**
2518
- * What a read selects: a Remote Selection, or a `foldkit-entity` Selection
2519
- * (read through `Selection.from`).
2520
- */
2521
- export type EntitySelection<Value, Name extends string, Id extends string = string> = Selection<Value, Name, 'entity'> | Domain.Selection<Name, unknown, Schema.Constraint & {
2522
- readonly Type: Value;
2523
- }, Id>;
2524
- /** The Remote descriptor either kind of entity reads as, at the type level. */
2525
- type DescriptorOf<E extends EntityLike> = E extends EntityDescriptor<any, any> ? E : E extends Domain.AnyEntity ? EntityDescriptor<E['name'], FieldsFrom<E>> : never;
2526
- type NameOf<E extends EntityLike> = DescriptorOf<E> extends EntityDescriptor<infer N, any> ? N : never;
2527
- type FieldsOf<E extends EntityLike> = DescriptorOf<E> extends EntityDescriptor<any, infer F> ? F : never;
2528
- type EntityName<D> = D extends {
2529
- readonly name: infer Name extends string;
2530
- } ? Name : never;
2531
- type QueryName<D> = D extends QueryDescriptor<infer Name, any, any> ? Name : never;
2532
- type MutationName<D> = D extends MutationDescriptor<infer Name, any, any> ? Name : never;
2533
- /**
2534
- * Nothing when `Name` is one of the domain's registered `Names`; otherwise a
2535
- * branded failure naming the descriptor, so `Data.get(Team.select(…))` for an
2536
- * unregistered `Team` errors at the selection in one line.
2537
- */
2538
- export type Registered<Name extends string, Names extends string, Kind extends string> = [Name] extends [Names] ? unknown : Invalid<`${Kind} "${Name}" is not registered with this Remote domain`>;
2539
- /** Nothing when a selection is of the query's entity; otherwise a branded failure naming both. */
2540
- export type SelectsEntity<Entity extends string, Of extends string> = [Entity] extends [Of] ? unknown : Invalid<`the selection is of "${Entity}", but the query lists "${Of}"`>;
2541
- export interface RemoteDescriptor<Entities extends readonly EntityLike[] = readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]> {
2542
- readonly entities: Entities;
2543
- readonly queries: Queries;
2544
- readonly mutations: Mutations;
2545
- readonly Model: Schema.Codec<RemoteModel, unknown>;
2546
- readonly initial: RemoteModel;
2547
- readonly Message: Schema.Schema<RemoteMessage>;
2548
- readonly update: (model: RemoteModel, message: RemoteMessage) => RemoteModel;
2549
- readonly rpc: typeof RemoteRpc;
2550
- /** Name-keyed lookups built from the declared entities, queries, and mutations. */
2551
- readonly registry: {
2552
- readonly entities: ReadonlyMap<string, EntityDescriptor<any, any>>;
2553
- readonly queries: ReadonlyMap<string, QueryDescriptor<any, any, any>>;
2554
- readonly mutations: ReadonlyMap<string, MutationDescriptor<any, any, any>>;
2555
- };
2556
- }
2557
- declare const boundRemoteNames: unique symbol;
2558
- export interface BoundRemote<AppModel, Store extends RemoteModel, Names extends string = string> {
2559
- readonly definition: RemoteDescriptor;
2560
- readonly store: ModelRef<AppModel, Store>;
2561
- /** For `Module`: owns the store's Model path. */
2562
- readonly contract: Contract;
2563
- /** Phantom: the entity names this Remote definition registers. */
2564
- readonly [boundRemoteNames]?: Names;
2565
- }
2566
- type MutationInput<M> = M extends MutationDescriptor<any, infer Input, any> ? Input : never;
2567
- export interface DomainMutateOptions {
2568
- /** Overrides the generated id, for a retry, a durable bridge, or a test. */
2569
- readonly requestId?: string | undefined;
2570
- /**
2571
- * What the request changes before the server answers, released when it
2572
- * settles. A function receives the generated ids, so a created entity can
2573
- * carry `tempId` until the result names the real one.
2574
- */
2575
- readonly optimistic?: ReadonlyArray<OptimisticOperation> | ((ids: {
2576
- readonly requestId: string;
2577
- readonly tempId: string;
2578
- }) => ReadonlyArray<OptimisticOperation>) | undefined;
2579
- /** The clock `MutationSucceeded` stamps the answer with; default `Date.now`, read at each use. */
2580
- readonly now?: (() => number) | undefined;
2581
- }
2582
- /** A Foldkit Subscription entry of the Remote domain, emitting its Messages through `RemoteClient`. */
2583
- export type RemoteEntry<AppModel, Dependencies> = EntryWithoutKeepAlive<AppModel, RemoteMessage, Dependencies, RemoteClient>;
2584
- /**
2585
- * The entries `RemoteDomain.subscriptions` returns for an active record: a read
2586
- * and a live entry per key (the live one idles when nothing is read live), and
2587
- * `retain`.
2588
- */
2589
- export type SubscriptionEntries<AppModel, Active, Message = RemoteMessage> = { readonly [K in keyof Active & (string | number) as `${K}.read`]: EntryWithoutKeepAlive<AppModel, Message, ReadDependencies, RemoteClient>; } & { readonly [K in keyof Active & (string | number) as `${K}.live`]: EntryWithoutKeepAlive<AppModel, Message, LiveDependencies, RemoteClient>; } & {
2590
- readonly retain: EntryWithoutKeepAlive<AppModel, Message, RetentionRoots, never>;
2591
- };
2592
- /** The dependencies of a live entry: what it subscribes to, and where a restart resumes. */
2593
- export interface LiveDependencies {
2594
- readonly requirements: ReadonlyArray<Requirement>;
2595
- readonly cursor: LiveCursor;
2596
- readonly floor: number;
2597
- }
2598
- export interface SubscriptionsOptions extends ObserveOptions, LiveOptions, RetainOptions {}
2599
- /** A Remote domain's wiring for an assembly: it routes Remote's Messages into `reduce`, brings its Subscriptions and contract, and requires `RemoteClient` from the runtime's resources Layer. */
2600
- export type RemoteWiring<AppModel> = Wiring<AppModel, RemoteMessage | RemoteMessageInput, RemoteClient>;
2601
- /** What `RemoteDomain.mutate` hands `update`: the Model with the request started, and the Command that settles it. */
2602
- export interface MutationStarted<AppModel> {
2603
- readonly model: AppModel;
2604
- readonly requestId: string;
2605
- readonly tempId: string;
2606
- /** Yields `MutationSucceeded` or `MutationFailed`; never fails. */
2607
- readonly command: Command<RemoteMessage, never, RemoteClient>;
2608
- }
2609
- /**
2610
- * A Remote domain bound to its place in the application Model: the descriptor
2611
- * (`Remote.define`), the binding (`Remote.at`), and the application-facing
2612
- * operations over them. Every method compiles to the `Remote.*` function of the
2613
- * same name, which stays exported for tooling, SSR, and tests.
2614
- */
2615
- export interface RemoteDomain<AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]> extends BoundRemote<AppModel, Store, EntityName<Entities[number]>>, RemoteDescriptor<Entities, Queries, Mutations> {
2616
- /** `Remote.select`: a Projection reading one entity through a selection of a registered entity. */
2617
- get<Value, Name extends string, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): Projection<AppModel, RemoteData<Value>>;
2618
- /**
2619
- * `get`, and the projection also subscribes to the entity's changes: its
2620
- * requirements are marked `live`, so `subscriptions` derives a live entry for
2621
- * the Surfaces that read it.
2622
- */
2623
- live<Value, Name extends string, Id extends string = string>(selection: EntitySelection<Value, Name, Id> & Registered<Name, EntityName<Entities[number]>, 'Entity'>, id: NoInfer<Id>): Projection<AppModel, RemoteData<Value>>;
2624
- /**
2625
- * A query connection read as a `Page` of items selected of the query's
2626
- * entity: `Initial` until the page and every item's selected fields are
2627
- * present, `Refreshing` while any of them is being refetched. The window is
2628
- * the page first asked for; the pages `next`, `previous` and `fetch` merge
2629
- * onto the connection read through the same projection.
2630
- */
2631
- query<Q extends QueryDescriptor<any, any, any>, Value, Entity extends string>(query: Q & Registered<Q['name'], QueryName<Queries[number]>, 'Query'>, input: QueryInput<Q>, options: QueryOptions<Value, Entity, QueryEntity<Q>>): QueryProjection<AppModel, Value, Q['name'], QueryInput<Q>>;
2632
- /**
2633
- * "Load more": the Model with the read's window grown by one page, so it
2634
- * shows that many more rows; the read entry fetches what the connection
2635
- * lacks. None when the read shows everything there is (or is not a sized
2636
- * window). Called from `update`.
2637
- */
2638
- more<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>): Option.Option<AppModel>;
2639
- /**
2640
- * What a query read is and what it currently is, as one serializable value —
2641
- * data-query-DESIGN §29.1: the domain, the definition and its input, the
2642
- * connection identity, the window, the Selection, the body as readable text
2643
- * with what it depends on, and what the read answers from this Model.
2644
- *
2645
- * Pure, so a DevTools panel showing it shows something the Model can be
2646
- * replayed to.
2647
- *
2648
- * Given `surfaces` — the same active record `subscriptions` takes — it also
2649
- * reports which of them read this connection, and why each is active where
2650
- * that is a readable fact (`Surface.when`) rather than a callback
2651
- * (`Surface.at`). A Projection cannot carry this itself: several Surfaces may
2652
- * read one connection, so it is not a property of the read.
2653
- */
2654
- explain<Name extends string, Input>(model: AppModel, projection: QueryProjection<AppModel, any, Name, Input>, options?: {
2655
- readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
2656
- }): QueryExplanation;
2657
- /**
2658
- * Why a read shows what it shows, in words. Any Remote read: `Data.get`,
2659
- * `Data.live` or `Data.query`.
2660
- *
2661
- * Its point is `Initial`, which means nothing is fetching the read and is
2662
- * almost always a wiring mistake. Given `surfaces`, the same active record
2663
- * `subscriptions` takes, it says which: no active Surface reads it, or one
2664
- * does and Remote's Subscriptions are not running. Pure, like `explain`.
2665
- */
2666
- why(model: AppModel, projection: Projection<AppModel, RemoteData<unknown>>, options?: {
2667
- readonly surfaces?: Readonly<Record<string, ActiveSurface<AppModel>>> | undefined;
2668
- }): ReadDiagnosis;
2669
- /**
2670
- * The rows of a loaded list that a body matches, decoded as the list decodes
2671
- * them — a filter that asks the server nothing.
2672
- *
2673
- * **It filters a list; it does not run a query.** That distinction is what
2674
- * keeps it honest. "Which rows match" would need to know that the list holds
2675
- * every row the body could match, which is predicate containment and is
2676
- * deliberately not built. "Which rows *of this list* match" is decidable from
2677
- * what is already here, and is what a search box over a loaded page actually
2678
- * wants.
2679
- *
2680
- * `complete` says whether the answer is about the whole list: every edge
2681
- * judged, and the connection terminal at both ends. An incomplete answer is
2682
- * not wrong — it is about less than the caller may have meant, which is why
2683
- * it is said rather than left for a view to assume.
2684
- *
2685
- * Creates no connection, so there is nothing new to retain and nothing new to
2686
- * fetch. The server stays authoritative for which rows exist.
2687
- */
2688
- filtered<Value, Name extends string, Input, Q extends QueryDescriptor<any, any, any>>(model: AppModel, over: QueryProjection<AppModel, Value, Name, Input>, by: Q & Registered<Q['name'], QueryName<Queries[number]>, 'Query'>, input: QueryInput<Q>): Matched<Value>;
2689
- /**
2690
- * Shows operations over the store with no request behind them, as a mutation's
2691
- * `optimistic` ones show while it is in flight: every Selection and view draws
2692
- * them. For a preview of a change nobody has made. They stay until `lift`;
2693
- * showing an id again replaces what it showed. Called from `update`. A read
2694
- * of an entity only overlays show, lacking a field it selects, is `Failed`
2695
- * (`Overlaid`): nothing will fetch that field.
2696
- */
2697
- overlay(model: AppModel, id: string, optimistic: ReadonlyArray<OptimisticOperation>): AppModel;
2698
- /** Lifts what `overlay` showed under this id. Lifting nothing returns the same Model. */
2699
- lift(model: AppModel, id: string): AppModel;
2700
- /** `Remote.refresh`: marks what a projection or a Surface requires as due, for its read entry to refetch. */
2701
- refresh(model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>): AppModel;
2702
- /** `Remote.forget`: the Model with every server-derived fact gone, for a change of principal. */
2703
- forget(model: AppModel): AppModel;
2704
- /**
2705
- * A read of this domain as an active Surface, for `subscriptions` and
2706
- * `wiring`: `projectionOf` is what it reads for a Model, none while it
2707
- * reads nothing. It belongs to the domain's application, and lists no
2708
- * Messages: it is a requirement, not a sender. A domain made from a raw
2709
- * optic names no application, so this throws for one.
2710
- */
2711
- active<Value>(name: string, projectionOf: (model: AppModel) => Option.Option<Projection<AppModel, Value>>): ActiveSurface<AppModel>;
2712
- /**
2713
- * The Foldkit Subscription entries for the active Surfaces, keyed for
2714
- * `Subscription.make`: a read entry per Surface (`Remote.observe`), a live
2715
- * entry per Surface that reads through `live` (`Remote.live`), and one
2716
- * retain entry (`Remote.retain`). Retention is the domain's: the retain
2717
- * entry of every call roots the active Surfaces of every call, so reads
2718
- * split over calls (one per policy) do not collect each other's data. A
2719
- * Surface's params are a function of the Model (`Surface.at`), so what is
2720
- * fetched, subscribed, and retained follows the Model.
2721
- */
2722
- subscriptions<const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions): SubscriptionEntries<AppModel, Active>;
2723
- /** `Remote.plan`: the requirements the store does not satisfy. */
2724
- plan<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions): ReadonlyArray<Requirement>;
2725
- /** `Remote.meta`: when what a projection shows was last received, and whether it is stale or loading. */
2726
- meta<Value>(model: AppModel, projection: Projection<AppModel, Value>): ReadMeta;
2727
- /** `Remote.storeOf`: the visible store, base under the pending optimistic layers. */
2728
- storeOf(model: AppModel): EntityStore;
2729
- /**
2730
- * `Remote.confirmed`: the same projection read against the server-derived
2731
- * store alone, with every pending optimistic layer and connection overlay
2732
- * left off. What it plans is unchanged — the requirements are the
2733
- * projection's own — so observing it reads exactly what observing the
2734
- * projection reads; only what it *shows* differs.
2735
- *
2736
- * A view usually wants the projection itself, which is the visible read:
2737
- * the optimistic layers are there so a change shows before the server has
2738
- * agreed to it. This is for the reader that must not believe a change until
2739
- * the server has confirmed it, which in practice is an Agent capability
2740
- * reporting that what it was asked to do is done:
2741
- *
2742
- * ```ts
2743
- * Agent.when({
2744
- * projection: Data.confirmed(ProjectPage.model.project),
2745
- * predicate: (project, request) => project.name === request.name,
2746
- * })
2747
- * ```
2748
- *
2749
- * There is deliberately no `visible`: a projection is already the visible
2750
- * read, and a wrapper that only forwards would be a second name for it.
2751
- */
2752
- confirmed<P extends Projection<AppModel, any>>(projection: P): P;
2753
- /**
2754
- * The plan run through `RemoteClient` and reduced into the Model: the
2755
- * projection's pending queries first, then the fields it lacks (the pages'
2756
- * items included). For SSR, route or hover prefetch, and tests.
2757
- */
2758
- prefetch<Value>(model: AppModel, projection: Projection<AppModel, Value>, options?: ObserveOptions): Effect.Effect<AppModel, RemoteReadError | RemoteProtocolError | RemoteQueryError, RemoteClient>;
2759
- /**
2760
- * The Model with everything the active Surfaces read, for a render that
2761
- * fetches nothing (SSR, a prerender). Each pass prefetches every Surface
2762
- * that plans a read, over the Model the one before it left, so a Surface
2763
- * active only once another's read has arrived is read in the next pass (or
2764
- * the same one, when it comes later in `active`). It stops at the first
2765
- * pass that plans nothing, and fails with `RemoteUnsatisfied` when
2766
- * `options.passes` run out first. Reads are cache-first: a field already
2767
- * held is not asked again.
2768
- */
2769
- satisfy(model: AppModel, active: Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>, options?: SatisfyOptions): Effect.Effect<AppModel, RemoteReadError | RemoteProtocolError | RemoteQueryError | RemoteUnsatisfied, RemoteClient>;
2770
- /**
2771
- * Starts a registered mutation from `update`: applies `MutationStarted` (with
2772
- * the optimistic operations) to the Model and returns the Command that runs
2773
- * it and yields the settling Message. The request id comes from the model's
2774
- * mutation sequence unless `options.requestId` is given.
2775
- */
2776
- mutate<M extends MutationDescriptor<any, any, any>>(model: AppModel, mutation: M & Registered<M['name'], MutationName<Mutations[number]>, 'Mutation'>, input: MutationInput<M>, options?: DomainMutateOptions): MutationStarted<AppModel>;
2777
- /**
2778
- * What Remote knows of a mutation `mutate` started, by its request id:
2779
- * pending, applied, or failed with the error the server or transport gave.
2780
- */
2781
- mutation(model: AppModel, requestId: string): MutationStatus;
2782
- /** `updateRemote` on the bound slice: reduces one of Remote's Messages, as `RemoteMessage` or as the application's union constructs it. */
2783
- reduce(model: AppModel, message: RemoteMessage | RemoteMessageInput): AppModel;
2784
- /**
2785
- * How this domain joins an assembly: it routes Remote's Messages into
2786
- * `reduce`, brings its Subscriptions and contract, and requires
2787
- * `RemoteClient` from the runtime's resources Layer. One assembly holds at
2788
- * most one Remote wiring: every domain claims the same tags, and routing
2789
- * takes the first claimant.
2790
- */
2791
- wiring: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => RemoteWiring<AppModel>;
2792
- /** `Remote.inspect` of the bound slice. */
2793
- inspect(model: AppModel): RemoteInspection;
2794
- }
2795
- /** What `Remote.fold(Data, …).mutate` starts: `Data.mutate`'s result with its Command lifted. */
2796
- export type FoldedMutationStarted<AppModel, ParentMessage> = Omit<MutationStarted<AppModel>, 'command'> & {
2797
- readonly command: Command<ParentMessage, never, RemoteClient>;
2798
- };
2799
- /**
2800
- * A bound domain folded under one of the application's own Message variants,
2801
- * from `Remote.fold`. Calling it reduces a Remote Message into the Model; the
2802
- * members that produce Messages, `fetch`, `mutate`, and `subscriptions`,
2803
- * yield the wrapper Message instead of `RemoteMessage`, with the lift recorded
2804
- * so Story and Scene can resolve a fetch or a mutation by Remote's own answer.
2805
- * Members that only read or write the Model (`get`, `refresh`, `next`,
2806
- * `overlay`, and the rest) stay on the domain itself.
2807
- */
2808
- export interface RemoteFold<AppModel, ParentMessage, Domain extends RemoteDomain<AppModel, any, any, any, any>> {
2809
- (model: AppModel, message: RemoteMessage | RemoteMessageInput): Update.Return<AppModel, ParentMessage>;
2810
- /** `Data.mutate`, its Command lifted. */
2811
- readonly mutate: (...args: Parameters<Domain['mutate']>) => FoldedMutationStarted<AppModel, ParentMessage>;
2812
- /** `Data.subscriptions`, every entry lifted to the wrapper Message. */
2813
- readonly subscriptions: <const Active extends Readonly<Record<string, ActiveSurface<AppModel> | Surface<AppModel, any, any, void>>>>(active: Active, options?: SubscriptionsOptions) => SubscriptionEntries<AppModel, Active, ParentMessage>;
2814
- }
2815
- /** The application Model a bound domain is over. */
2816
- export type ModelOfDomain<Domain> = Domain extends RemoteDomain<infer AppModel, any, any, any, any> ? AppModel : never;
2817
- /** A projection's connection requirement with the `QueryRef` that runs it. */
2818
- export interface QueryRequirement extends ConnectionRequirement {
2819
- readonly ref: QueryRef<string, unknown>;
2820
- }
2821
- /** A page forward (`first`, `after`) or back (`last`, `before`); mixing the two is a type error. */
2822
- export type QueryWindowOptions = {
2823
- readonly first?: number | undefined;
2824
- readonly after?: string | undefined;
2825
- readonly last?: undefined;
2826
- readonly before?: undefined;
2827
- } | {
2828
- readonly last: number;
2829
- readonly before?: string | undefined;
2830
- readonly first?: undefined;
2831
- readonly after?: undefined;
2832
- };
2833
- export type QueryOptions<Value, Entity extends string, Of extends string = Entity> = {
2834
- /** What to read of each item: a selection of the query's entity (`Of`). */
2835
- readonly select: EntitySelection<Value, Entity> & SelectsEntity<Entity, Of>;
2836
- } & QueryWindowOptions;
2837
- /** A query connection read as a `Page` of selected items; `ref` is the connection with its first window. */
2838
- export interface QueryProjection<AppModel, Value, Name extends string, Input> extends Projection<AppModel, RemoteData<Page<Value>>> {
2839
- readonly ref: QueryRef<Name, Input>;
2840
- /** What it reads of each item, so a filter over the same list decodes identically. */
2841
- readonly selection: Selection<Value, string>;
2842
- }
2843
- /** The input of a query descriptor. */
2844
- export type QueryInput<Q> = Q extends QueryDescriptor<any, infer Input, any> ? Input : never;
2845
- /** The entity a query's connection is over. */
2846
- export type QueryEntity<Q> = Q extends QueryDescriptor<any, any, ConnectionSpec<infer Entity>> ? Entity : string;
2847
- /**
2848
- * When what a projection shows was last received, and whether it is stale
2849
- * or loading. See `Remote.meta`.
2850
- */
2851
- export interface ReadMeta {
2852
- /** The newest server write among what is shown; none received reads `undefined`. */
2853
- readonly updatedAt: number | undefined;
2854
- /** Any shown field or connection is marked stale. */
2855
- readonly stale: boolean;
2856
- /** Any shown field or connection is in flight. */
2857
- readonly loading: boolean;
2858
- }
2859
- export interface MutateOptions {
2860
- /** What the request changes before the server answers; released when it settles. */
2861
- readonly optimistic?: ReadonlyArray<OptimisticOperation> | undefined;
2862
- /** The clock `MutationSucceeded` stamps the answer with; default `Date.now`, read at each use. */
2863
- readonly now?: (() => number) | undefined;
2864
- }
2865
- export interface RetainOptions {
2866
- /** The query connections the application shows, by `QueryRef` or identity. */
2867
- readonly connections?: ReadonlyArray<ConnectionIdentity> | undefined;
2868
- /** How long the roots must be stable before collecting; default none. */
2869
- readonly grace?: Duration.Input | undefined;
2870
- }
2871
- /** How `Remote.observe` and `Remote.prefetch` treat fields the store already holds. */
2872
- export interface ObserveOptions {
2873
- /** Default `RemotePolicy.cacheFirst`. */
2874
- readonly policy?: RemotePolicy | undefined;
2875
- /** The clock a refreshing policy reads; default `Date.now`, read at each use. */
2876
- readonly now?: (() => number) | undefined;
2877
- }
2878
- /** How `Data.satisfy` reads: how many passes it may take, and the clock. */
2879
- export interface SatisfyOptions {
2880
- /** At most this many passes over the Surfaces; default 8. */
2881
- readonly passes?: number | undefined;
2882
- /** The clock the reads are stamped with; default `Date.now`, read at each use. */
2883
- readonly now?: (() => number) | undefined;
2884
- }
2885
- declare const RemoteUnsatisfied_base: Schema.Class<RemoteUnsatisfied, Schema.TaggedStruct<"RemoteUnsatisfied", {
2886
- readonly surfaces: Schema.$Array<Schema.String>;
2887
- readonly passes: Schema.Number;
2888
- }>, import("effect/Cause").YieldableError>;
2889
- /**
2890
- * `Data.satisfy` reached its bound with Surfaces still reading, such as a
2891
- * chain whose every read reveals one more. It names them, so a page that
2892
- * would have rendered them loading fails instead. (A read the server leaves
2893
- * unanswered settles as missing and ends the loop.)
2894
- */
2895
- export declare class RemoteUnsatisfied extends RemoteUnsatisfied_base {}
2896
- export interface LiveOptions {
2897
- /** The clock `LiveReceived` stamps events with; default `Date.now`, read at each use. */
2898
- readonly now?: (() => number) | undefined;
2899
- }
2900
- /** A query the read entry runs, as its dependencies carry it: plain data Foldkit compares. */
2901
- declare const PlannedQuery: Schema.Struct<{
2902
- readonly identity: Schema.String;
2903
- readonly window: Schema.Struct<{
2904
- readonly first: Schema.optional<Schema.Number>;
2905
- readonly last: Schema.optional<Schema.Number>;
2906
- readonly after: Schema.optional<Schema.String>;
2907
- readonly before: Schema.optional<Schema.String>;
2908
- }>;
2909
- readonly select: Schema.Codec<RelationRequirement, RelationRequirement, never, never>;
2910
- }>;
2911
- /** The dependencies of the read entry: the entity fields to read and the queries to run. */
2912
- export interface ReadDependencies {
2913
- readonly requirements: ReadonlyArray<Requirement>;
2914
- readonly queries: ReadonlyArray<Schema.Schema.Type<typeof PlannedQuery>>;
2915
- /**
2916
- * The highest generation the fields this entry reads were refreshed at: a
2917
- * refresh of any of them restarts the entry, and a refresh of anything else
2918
- * leaves it running.
2919
- */
2920
- readonly refresh: number;
2921
- /**
2922
- * Under a refreshing policy, when a value the entry holds next ages out and
2923
- * what is due then. Time reaches Remote only as a Message: the entry sleeps
2924
- * until then and emits `RefreshStarted`, which marks the fields stale, and
2925
- * the plan that follows fetches them. A Model that does not change past its
2926
- * `maxAge` is otherwise never looked at again.
2927
- */
2928
- readonly expires: Deadline | null;
2929
- }
2930
- export declare const Remote: {
2931
- /** The submodel's schema, the same for every domain; embed it in the application Model. */
2932
- Model: Schema.Codec<RemoteModel, unknown, never, never>;
2933
- /** The submodel's initial value. */
2934
- initial: RemoteModel;
2935
- /**
2936
- * Remote's Message cases for `defineMessageUnion`: spread them into the
2937
- * application's union, and reduce the ones `Remote.reduces` recognizes with
2938
- * `RemoteDomain.reduce`.
2939
- */
2940
- messages: {
2941
- ReadReceived: {
2942
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
2943
- result: Schema.Struct<{
2944
- readonly entities: Schema.$Array<Schema.Struct<{
2945
- readonly entity: Schema.String;
2946
- readonly id: Schema.String;
2947
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
2948
- }>>;
2949
- readonly settled: Schema.$Array<Schema.Struct<{
2950
- readonly entity: Schema.String;
2951
- readonly id: Schema.String;
2952
- readonly fields: Schema.$Array<Schema.String>;
2953
- }>>;
2954
- }>;
2955
- now: Schema.Number;
2956
- };
2957
- ReadFailed: {
2958
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
2959
- error: Schema.Struct<{
2960
- readonly _tag: Schema.String;
2961
- readonly message: Schema.String;
2962
- }>;
2963
- stream: Schema.optional<Schema.String>;
2964
- };
2965
- RefreshStarted: {
2966
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
2967
- };
2968
- ReadStarted: {
2969
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
2970
- refresh: Schema.optional<Schema.Number>;
2971
- };
2972
- QueryStarted: {
2973
- connections: Schema.$Array<Schema.String>;
2974
- };
2975
- RetentionChanged: {
2976
- roots: Schema.Struct<{
2977
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
2978
- readonly connections: Schema.$Array<Schema.Struct<{
2979
- readonly identity: Schema.String;
2980
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
2981
- }>>;
2982
- }>;
2983
- };
2984
- Hydrated: {
2985
- connections: Schema.optional<Schema.Unknown>;
2986
- entities: Schema.Unknown;
2987
- merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
2988
- };
2989
- MutationStarted: {
2990
- requestId: Schema.String;
2991
- optimistic: Schema.optional<Schema.$Array<Schema.Unknown>>;
2992
- };
2993
- MutationSucceeded: {
2994
- requestId: Schema.String;
2995
- entities: Schema.$Array<Schema.Struct<{
2996
- readonly entity: Schema.String;
2997
- readonly id: Schema.String;
2998
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
2999
- }>>;
3000
- connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
3001
- deleted: Schema.optional<Schema.$Array<Schema.Struct<{
3002
- readonly entity: Schema.String;
3003
- readonly id: Schema.String;
3004
- }>>>;
3005
- now: Schema.Number;
3006
- };
3007
- MutationFailed: {
3008
- requestId: Schema.String;
3009
- error: Schema.Struct<{
3010
- readonly _tag: Schema.String;
3011
- readonly message: Schema.String;
3012
- }>;
3013
- };
3014
- OverlayShown: {
3015
- id: Schema.String;
3016
- optimistic: Schema.$Array<Schema.Unknown>;
3017
- };
3018
- OverlayLifted: {
3019
- id: Schema.String;
3020
- };
3021
- WindowGrown: {
3022
- window: Schema.String;
3023
- size: Schema.Number;
3024
- };
3025
- LiveReceived: {
3026
- stream: Schema.String;
3027
- event: Schema.Unknown;
3028
- policy: Schema.optional<Schema.Unknown>;
3029
- now: Schema.Number;
3030
- };
3031
- GapCleared: {
3032
- stream: Schema.String;
3033
- };
3034
- ConnectionMerged: {
3035
- connection: Schema.String;
3036
- page: Schema.Unknown;
3037
- refreshes: Schema.optional<Schema.Boolean>;
3038
- select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
3039
- entities: Schema.optional<Schema.$Array<Schema.Struct<{
3040
- readonly entity: Schema.String;
3041
- readonly id: Schema.String;
3042
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
3043
- }>>>;
3044
- settled: Schema.optional<Schema.$Array<Schema.Struct<{
3045
- readonly entity: Schema.String;
3046
- readonly id: Schema.String;
3047
- readonly fields: Schema.$Array<Schema.String>;
3048
- }>>>;
3049
- now: Schema.optional<Schema.Number>;
3050
- };
3051
- ConnectionInvalidated: {
3052
- connection: Schema.String;
3053
- };
3054
- ConnectionRefreshed: {
3055
- connection: Schema.String;
3056
- };
3057
- QueryFailed: {
3058
- connection: Schema.String;
3059
- error: Schema.Struct<{
3060
- readonly _tag: Schema.String;
3061
- readonly message: Schema.String;
3062
- }>;
3063
- };
3064
- };
3065
- /** Whether a Message is one of Remote's, by tag. */
3066
- reduces: <M extends {
3067
- readonly _tag: string;
3068
- }>(message: M) => message is Extract<M, {
3069
- readonly _tag: RemoteMessageTag;
3070
- }>;
3071
- /**
3072
- * Remote's Messages as one Schema, for a wrapper variant in the
3073
- * application's union: `GotRemoteMessage: { message: Remote.Message }`. With
3074
- * a wrapper, `update` matches the application's union exhaustively and
3075
- * `Remote.fold` reduces what arrives inside it.
3076
- */
3077
- Message: import("foldkit/message").MessageUnion<{
3078
- ReadReceived: {
3079
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
3080
- result: Schema.Struct<{
3081
- readonly entities: Schema.$Array<Schema.Struct<{
3082
- readonly entity: Schema.String;
3083
- readonly id: Schema.String;
3084
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
3085
- }>>;
3086
- readonly settled: Schema.$Array<Schema.Struct<{
3087
- readonly entity: Schema.String;
3088
- readonly id: Schema.String;
3089
- readonly fields: Schema.$Array<Schema.String>;
3090
- }>>;
3091
- }>;
3092
- now: Schema.Number;
3093
- };
3094
- ReadFailed: {
3095
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
3096
- error: Schema.Struct<{
3097
- readonly _tag: Schema.String;
3098
- readonly message: Schema.String;
3099
- }>;
3100
- stream: Schema.optional<Schema.String>;
3101
- };
3102
- RefreshStarted: {
3103
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
3104
- };
3105
- ReadStarted: {
3106
- requests: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
3107
- refresh: Schema.optional<Schema.Number>;
3108
- };
3109
- QueryStarted: {
3110
- connections: Schema.$Array<Schema.String>;
3111
- };
3112
- RetentionChanged: {
3113
- roots: Schema.Struct<{
3114
- readonly requirements: Schema.$Array<Schema.Codec<Requirement, Requirement, never, never>>;
3115
- readonly connections: Schema.$Array<Schema.Struct<{
3116
- readonly identity: Schema.String;
3117
- readonly select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
3118
- }>>;
3119
- }>;
3120
- };
3121
- Hydrated: {
3122
- connections: Schema.optional<Schema.Unknown>;
3123
- entities: Schema.Unknown;
3124
- merge: Schema.Union<readonly [Schema.Literal<"replace">, Schema.Literal<"preserve-existing">]>;
3125
- };
3126
- MutationStarted: {
3127
- requestId: Schema.String;
3128
- optimistic: Schema.optional<Schema.$Array<Schema.Unknown>>;
3129
- };
3130
- MutationSucceeded: {
3131
- requestId: Schema.String;
3132
- entities: Schema.$Array<Schema.Struct<{
3133
- readonly entity: Schema.String;
3134
- readonly id: Schema.String;
3135
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
3136
- }>>;
3137
- connections: Schema.optional<Schema.$Array<Schema.Unknown>>;
3138
- deleted: Schema.optional<Schema.$Array<Schema.Struct<{
3139
- readonly entity: Schema.String;
3140
- readonly id: Schema.String;
3141
- }>>>;
3142
- now: Schema.Number;
3143
- };
3144
- MutationFailed: {
3145
- requestId: Schema.String;
3146
- error: Schema.Struct<{
3147
- readonly _tag: Schema.String;
3148
- readonly message: Schema.String;
3149
- }>;
3150
- };
3151
- OverlayShown: {
3152
- id: Schema.String;
3153
- optimistic: Schema.$Array<Schema.Unknown>;
3154
- };
3155
- OverlayLifted: {
3156
- id: Schema.String;
3157
- };
3158
- WindowGrown: {
3159
- window: Schema.String;
3160
- size: Schema.Number;
3161
- };
3162
- LiveReceived: {
3163
- stream: Schema.String;
3164
- event: Schema.Unknown;
3165
- policy: Schema.optional<Schema.Unknown>;
3166
- now: Schema.Number;
3167
- };
3168
- GapCleared: {
3169
- stream: Schema.String;
3170
- };
3171
- ConnectionMerged: {
3172
- connection: Schema.String;
3173
- page: Schema.Unknown;
3174
- refreshes: Schema.optional<Schema.Boolean>;
3175
- select: Schema.optional<Schema.Codec<RelationRequirement, RelationRequirement, never, never>>;
3176
- entities: Schema.optional<Schema.$Array<Schema.Struct<{
3177
- readonly entity: Schema.String;
3178
- readonly id: Schema.String;
3179
- readonly values: Schema.$Record<Schema.String, Schema.Unknown>;
3180
- }>>>;
3181
- settled: Schema.optional<Schema.$Array<Schema.Struct<{
3182
- readonly entity: Schema.String;
3183
- readonly id: Schema.String;
3184
- readonly fields: Schema.$Array<Schema.String>;
3185
- }>>>;
3186
- now: Schema.optional<Schema.Number>;
3187
- };
3188
- ConnectionInvalidated: {
3189
- connection: Schema.String;
3190
- };
3191
- ConnectionRefreshed: {
3192
- connection: Schema.String;
3193
- };
3194
- QueryFailed: {
3195
- connection: Schema.String;
3196
- error: Schema.Struct<{
3197
- readonly _tag: Schema.String;
3198
- readonly message: Schema.String;
3199
- }>;
3200
- };
3201
- }>;
3202
- /**
3203
- * A bound domain under one wrapper variant of the application's union, the
3204
- * same shape Foldkit gives a Submodel: `toParentMessage` wraps Remote's
3205
- * Messages, the fold reduces them, and its `fetch`, `mutate`, and
3206
- * `subscriptions` yield the wrapper. Spreading `Remote.messages` and
3207
- * narrowing with `Remote.reduces` remains the shorter path for an
3208
- * application whose `update` only reduces.
3209
- *
3210
- * @example
3211
- * ```ts
3212
- * const Message = defineMessageUnion({ GotRemoteMessage: { message: Remote.Message } })
3213
- * const foldData = Remote.fold(Data, message => Message.GotRemoteMessage({ message }))
3214
- *
3215
- * const update = (model: Model, message: Message): Return =>
3216
- * Message.match(message, {
3217
- * GotRemoteMessage: ({ message }) => foldData(model, message),
3218
- * })
3219
- * const subscriptions = Subscription.make<Model, Message, RemoteClient>()(() =>
3220
- * foldData.subscriptions({ page: Surface.at(ProjectPage, …) }),
3221
- * )
3222
- * ```
3223
- */
3224
- fold: <Domain extends RemoteDomain<any, any, any, any, any>, ParentMessage>(domain: Domain, toParentMessage: (message: RemoteMessage) => ParentMessage) => RemoteFold<ModelOfDomain<Domain>, ParentMessage, Domain>;
3225
- /**
3226
- * A patch of one entity's values, for a mutation's `optimistic` list or an
3227
- * overlay. Takes a `foldkit-entity` Entity or a Remote descriptor alike, so
3228
- * the domain you declared once is the one you patch:
3229
- * `Remote.patch(Project, 'p1', { name: 'Apollo II' })`. Values are the
3230
- * fields' wire shape, as the server writes them; a relation is its ref key
3231
- * (`'User:u1'`).
3232
- */
3233
- patch: <E extends EntityLike>(entity: E, id: string, values: Partial<Schema.Struct.Encoded<FieldsOf<E>>>) => EntityPatch<NameOf<E>, FieldsOf<E>>;
3234
- /**
3235
- * A reference to one entity, for `ConnectionChange` and anything else that
3236
- * names a row: `Remote.ref(Project, 'p3')`. Either kind of entity, as with
3237
- * `Remote.patch`.
3238
- */
3239
- ref: <E extends EntityLike>(entity: E, id: string) => EntityRef<NameOf<E>, FieldsOf<E>>;
3240
- /**
3241
- * Declares a Remote domain and binds it to its place in the application Model
3242
- * in one step; the result carries the application-facing operations. The
3243
- * descriptor alone is `Remote.define`, the binding alone `Remote.at`.
3244
- */
3245
- make: <AppModel, Store extends RemoteModel, const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly [], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly []>(config: {
3246
- readonly model: ModelRef<AppModel, Store>;
3247
- readonly entities: Entities;
3248
- readonly queries?: Queries;
3249
- readonly mutations?: Mutations;
3250
- }) => RemoteDomain<AppModel, Store, Entities, Queries, Mutations>;
3251
- /**
3252
- * Declares a Remote domain without binding it: its entities, queries, and
3253
- * mutations, plus the submodel. For a domain reused across applications or
3254
- * bound in a test; `Remote.make` is the one-step form.
3255
- */
3256
- define: <const Entities extends readonly EntityLike[], const Queries extends readonly QueryDescriptor<any, any, any>[] = readonly QueryDescriptor<any, any, any>[], const Mutations extends readonly MutationDescriptor<any, any, any>[] = readonly MutationDescriptor<any, any, any>[]>(config: {
3257
- readonly entities: Entities;
3258
- readonly queries?: Queries;
3259
- readonly mutations?: Mutations;
3260
- }) => RemoteDescriptor<Entities, Queries, Mutations>;
3261
- /**
3262
- * Binds a Remote domain to its store's location in the application Model. The
3263
- * registered entity names are carried on the returned value, so `Remote.select`
3264
- * rejects a selection for an entity this domain never declared.
3265
- */
3266
- at: <AppModel, Store extends RemoteModel, Entities extends readonly EntityLike[], Queries extends readonly QueryDescriptor<any, any, any>[], Mutations extends readonly MutationDescriptor<any, any, any>[]>(definition: RemoteDescriptor<Entities, Queries, Mutations>, store: ModelRef<AppModel, Store>) => BoundRemote<AppModel, Store, EntityName<Entities[number]>>;
3267
- /**
3268
- * The resume part for this domain, for `foldkit-ssr`'s `SSR.plan({ parts })`:
3269
- * a server render sends what the plan's active Surfaces read from the store,
3270
- * each connection with its boundaries and each live cursor with it, and
3271
- * nothing else. `id` tells two domains in one application apart.
3272
- */
3273
- resume: <AppModel, Store extends RemoteModel>(domain: {
3274
- readonly store: ModelRef<AppModel, Store>;
3275
- }, options?: {
3276
- readonly id?: string | undefined;
3277
- }) => RemoteResumePart<AppModel>;
3278
- /**
3279
- * A Projection node that reads a `RemoteData` value out of the store. The id
3280
- * is supplied by the caller, usually from a Surface's params. The assembled
3281
- * value is decoded against the Selection, so malformed server data surfaces
3282
- * as `Failed` instead of being asserted into `Value`. A present value with a
3283
- * stale field reads as `Refreshing`: an observer is refetching it.
3284
- */
3285
- select: <AppModel, Store extends RemoteModel, Names extends string, Value, Name extends string>(bound: BoundRemote<AppModel, Store, Names>, given: EntitySelection<Value, Name> & Registered<Name, Names, "Entity">) => (id: string) => Projection<AppModel, RemoteData<Value>>;
3286
- /**
3287
- * When what a projection shows was last received, and whether it is stale
3288
- * or loading. Pure, so a view can show "updated 5s ago" without I/O.
3289
- *
3290
- * `updatedAt` is the newest server write among what is shown, as the
3291
- * store dates it; `undefined` when nothing shown was received (nothing
3292
- * loaded, or only an optimistic preview). `stale` is any shown field or
3293
- * connection marked stale; `loading` is any of them in flight. Optimistic
3294
- * previews do not date: showing only one reads `updatedAt: undefined`.
3295
- */
3296
- meta: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>) => ReadMeta;
3297
- /**
3298
- * The pure plan for a projection against a Model: the requirements its
3299
- * remote store does not satisfy, under `options` (freshness, force). A
3300
- * Surface's projection is `surface.projection(params)`.
3301
- */
3302
- plan: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<Requirement>;
3303
- /**
3304
- * The queries a projection needs run before its connections read: those the
3305
- * Model does not hold, or holds stale (every one under `force`).
3306
- */
3307
- planQueries: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store>, model: AppModel, projection: Projection<AppModel, Value>, options?: PlanOptions) => ReadonlyArray<QueryRef<string, unknown>>;
3308
- /**
3309
- * The store reads see: the base store under the pending optimistic layers.
3310
- * One store is shared by every read and plan of a Model whose remote state
3311
- * has not changed.
3312
- */
3313
- storeOf: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel) => EntityStore;
3314
- /**
3315
- * The projection read against the server-derived store alone: the same
3316
- * requirements, planned the same way, with the pending optimistic layers and
3317
- * connection overlays left off. See the bound `Remote.confirmed`.
3318
- */
3319
- confirmed: <AppModel, Store extends RemoteModel, P extends Projection<AppModel, any>>(bound: BoundRemote<AppModel, Store>, projection: P) => P;
3320
- /**
3321
- * Executes the plan against the `RemoteClient` and returns a new store. Used
3322
- * for SSR route prefetch, hover prefetch, and tests. Never called during render.
3323
- * `policy` decides what a present field means (default cache-first); `now`
3324
- * is the clock it reads, so the planner itself stays pure and time-injected.
3325
- */
3326
- prefetch: <AppModel, Store extends RemoteModel, Value>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, projection: Projection<AppModel, Value>, options?: ObserveOptions | undefined) => Effect.Effect<Readonly<Record<string, EntityEntry>>, RemoteReadError | RemoteProtocolError, RemoteClient>;
3327
- /**
3328
- * Marks what a projection, or a Surface without params, requires as due again.
3329
- * Called from `update`: every selected field the store holds reads `Refreshing`,
3330
- * and every loaded query connection is invalidated. Nothing is fetched here.
3331
- * The read entries `Data.subscriptions` derives refetch it, because a stale
3332
- * field or connection is planned again under every policy, so a refresh never
3333
- * sends a request beside the entry already observing the same data.
3334
- *
3335
- * A refreshed connection's page replaces its pages, so items the server removed
3336
- * or reordered follow it; pages loaded past the first are dropped and paged
3337
- * again with `next`/`previous`. The read entries restart, so a read or query
3338
- * sent before the refresh is not applied after it.
3339
- *
3340
- * It is also how a failed query is retried: a connection whose query failed
3341
- * is not run again on its own, so its read stays `Failed` until this asks.
3342
- *
3343
- * The projection must be observed, which it is while it is on screen. Live
3344
- * subscriptions are left as they are. For data nothing observes (SSR, tests),
3345
- * use `Remote.prefetch` with `RemotePolicy.networkOnly`. Refreshing what is
3346
- * already being refreshed returns the same Model.
3347
- */
3348
- refresh: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel, target: Projection<AppModel, unknown> | Surface<AppModel, any, any, void>) => AppModel;
3349
- /**
3350
- * Forgets everything the server told this Model: values, tombstones,
3351
- * unavailable fields, connections, live cursors, failures. What is known is
3352
- * known for a principal, and this is the one boundary for a login, a logout
3353
- * or a switch of organization: called from `update`, it performs no I/O, and
3354
- * every active Surface's read and live entries restart, so the screen asks
3355
- * again as whoever the client now is. A read or stream begun before is
3356
- * interrupted rather than landing after. A mutation in flight is treated as
3357
- * applied: its answer writes nothing here.
3358
- */
3359
- forget: <AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store>, model: AppModel) => AppModel;
3360
- /**
3361
- * Writes a read result into the store, recording each field's applied window.
3362
- * `requests` are the planned requirements the result answers.
3363
- */
3364
- writeRead: (store: EntityStore, requests: ReadonlyArray<Requirement>, result: Schema.Schema.Type<typeof ReadBatchResult>, now?: number) => EntityStore;
3365
- /**
3366
- * Adapts an Effect RPC client for `RemoteRpc` to `RemoteClient`, so an
3367
- * application provides the transport's RPC layer instead of writing the
3368
- * `LiveChange`-to-`LiveEvent` mapping by hand. The client `RpcClient.make`
3369
- * builds is accepted as it is: when its transport fails (`RpcClientError`),
3370
- * the call fails with its own Remote error, which the application shows and
3371
- * retries like any failed read, query, mutation or live stream.
3372
- */
3373
- clientLayer: <R = never>(client: RemoteRpcClient<R, RpcClientError.RpcClientError>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, never, R>;
3374
- /**
3375
- * Wraps a `RemoteClient` layer so its reads coalesce: requirements issued
3376
- * together become one batch, and a requirement already in flight is joined.
3377
- * `Remote.clientLayer` applies this; use it on a hand-written client.
3378
- */
3379
- coalesced: <E, R>(layer: Layer.Layer<RemoteClient, E, R>, options?: CoalesceOptions) => Layer.Layer<RemoteClient, E, R>;
3380
- /**
3381
- * A Foldkit Subscription entry that keeps the cache to what the active
3382
- * Surfaces reach. `projections` are the ones the application observes (the
3383
- * same it passes to `Remote.observe`), `connections` the query connections
3384
- * it shows; anything else is collected once the roots have been stable for
3385
- * `grace`, so a route transition that comes straight back does not thrash.
3386
- */
3387
- retain: <AppModel, Message = RemoteMessage>(projections: ReadonlyArray<Projection<AppModel, unknown>>, toMessage?: (message: RemoteMessage) => Message, options?: RetainOptions) => EntryWithoutKeepAlive<AppModel, Message, RetentionRoots, never>;
3388
- /**
3389
- * Runs a `Query` through `RemoteClient`, encoding its input from the ref.
3390
- * Pair the result with `Remote.queryMessage` to merge the page into the Model.
3391
- * With `select`, the server also returns the selected fields of the page's
3392
- * items, so one response populates both the connection and the store.
3393
- */
3394
- query: <Name extends string, Input>(ref: QueryRef<Name, Input>, select?: RelationRequirement | undefined) => Effect.Effect<{
3395
- readonly edges: readonly {
3396
- readonly entity: string;
3397
- readonly id: string;
3398
- readonly key: string;
3399
- }[];
3400
- readonly start: {
3401
- readonly _tag: "Terminal";
3402
- } | {
3403
- readonly _tag: "Cursor";
3404
- readonly cursor: string;
3405
- } | {
3406
- readonly _tag: "Unknown";
3407
- };
3408
- readonly end: {
3409
- readonly _tag: "Terminal";
3410
- } | {
3411
- readonly _tag: "Cursor";
3412
- readonly cursor: string;
3413
- } | {
3414
- readonly _tag: "Unknown";
3415
- };
3416
- readonly entities?: readonly {
3417
- readonly entity: string;
3418
- readonly id: string;
3419
- readonly values: {
3420
- readonly [x: string]: unknown;
3421
- };
3422
- }[] | undefined;
3423
- readonly settled?: readonly {
3424
- readonly entity: string;
3425
- readonly id: string;
3426
- readonly fields: readonly string[];
3427
- }[] | undefined;
3428
- }, RemoteQueryError, RemoteClient>;
3429
- /** The `RemoteMessage` that merges a query page into its connection. */
3430
- queryMessage: <Name extends string, Input>(ref: QueryRef<Name, Input>, result: Schema.Schema.Type<typeof QueryResult>, select?: RelationRequirement | undefined, now?: number | undefined) => RemoteMessage;
3431
- /**
3432
- * The edges a connection shows: its server-known region with pending and
3433
- * confirmed overlays placed around it, minus removed edges and edges whose
3434
- * target is a tombstone.
3435
- */
3436
- visibleItems: (model: RemoteModel, connection: ConnectionIdentity) => ReadonlyArray<Edge>;
3437
- /** A pure, serializable view of the whole cache. */
3438
- inspect: (model: RemoteModel) => RemoteInspection;
3439
- /** A pure, serializable view of one entity, or `undefined` if unknown. */
3440
- inspectEntity: (model: RemoteModel, key: string) => RemoteInspection["entities"][number] | undefined;
3441
- /**
3442
- * Runs a mutation through `RemoteClient`, decoding its typed Output and
3443
- * returning the result's normalized patches so the caller can reconcile them
3444
- * through `updateRemote`'s `MutationSucceeded` (or `Remote.mutateInto`).
3445
- */
3446
- mutate: <Name extends string, Input, Output>(mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string) => Effect.Effect<{
3447
- output: Output;
3448
- entities: readonly {
3449
- readonly entity: string;
3450
- readonly id: string;
3451
- readonly values: {
3452
- readonly [x: string]: unknown;
3453
- };
3454
- }[];
3455
- connections: ConnectionChange[];
3456
- deleted: readonly {
3457
- readonly entity: string;
3458
- readonly id: string;
3459
- }[];
3460
- }, RemoteMutationError, RemoteClient>;
3461
- /**
3462
- * Runs a mutation and reconciles its patches into a `RemoteModel` in one step,
3463
- * returning the new model alongside the typed Output. The model-level form of
3464
- * `MutationStarted` → `RemoteClient.mutate` → `MutationSucceeded`; in an
3465
- * application the three are `update` (with `optimistic`), a Command, and the
3466
- * Message the Command returns, so the optimistic operations show meanwhile.
3467
- */
3468
- mutateInto: <Name extends string, Input, Output, AppModel, Store extends RemoteModel>(bound: BoundRemote<AppModel, Store, string>, model: AppModel, mutation: MutationDescriptor<Name, Input, Output>, input: Input, requestId: string, options?: MutateOptions | undefined) => Effect.Effect<{
3469
- output: Output;
3470
- model: AppModel;
3471
- }, RemoteMutationError, RemoteClient>;
3472
- /**
3473
- * A Foldkit Subscription entry that plans a Surface's missing fields from the
3474
- * Model and fetches them through `RemoteClient`, emitting a `RemoteMessage`
3475
- * per outcome. Wrap it in an application Message (`toMessage`) and reduce it
3476
- * with the domain's `update`. Under a refreshing `policy` the entry first
3477
- * emits `RefreshStarted`, so the fields being refetched read as `Refreshing`
3478
- * while the request is pending.
3479
- */
3480
- observe: <AppModel, Store extends RemoteModel, Names extends string, Model, SurfaceMessage, Params, Message = RemoteMessage>(bound: BoundRemote<AppModel, Store, Names>, surface: Surface<AppModel, Model, SurfaceMessage, Params>, params: Params, toMessage?: (message: RemoteMessage) => Message, options?: ObserveOptions) => EntryWithoutKeepAlive<AppModel, Message, ReadDependencies, RemoteClient>;
3481
- /**
3482
- * A Foldkit Subscription entry that consumes the live stream for a Surface's
3483
- * requirements, emitting a `LiveReceived` per event and a `ReadFailed`
3484
- * carrying its `stream` when the stream breaks (including
3485
- * `ResumeUnavailable`). That records a gap on the stream rather than a failed
3486
- * read, since nothing was being read. The resume cursor is read
3487
- * from `RemoteModel.live`, so the application tracks no cursor of its own.
3488
- */
3489
- live: <AppModel, Store extends RemoteModel, Names extends string, Model, SurfaceMessage, Params, Message = RemoteMessage>(bound: BoundRemote<AppModel, Store, Names>, surface: Surface<AppModel, Model, SurfaceMessage, Params>, params: Params, toMessage?: (message: RemoteMessage) => Message, options?: LiveOptions) => EntryWithoutKeepAlive<AppModel, Message, LiveDependencies, RemoteClient>;
3490
- };
3491
- //#endregion
3492
- export { Entity$1 as Entity, type RemoteResumePart };
3493
- //# sourceMappingURL=index.d.mts.map
1
+ import { $ as Entity, $i as isGapped, $n as Snapshot, $r as ResultOf, $t as failureOf, A as SelectsEntity, Ai as readField, An as PageSize, Ar as pruneOverlays, At as RemoteJsonRequest, B as ExplainedDependencies, Bi as remoteDataSchema, Bn as RelationRequest, Br as RemoteRequirements, Bt as CoalesceOptions, C as RemoteDomain, Ci as entry, Cn as LiveRequirement, Cr as OptimisticOperation, Ct as isRefPage, D as RemoteWiring, Di as isTombstone, Dn as MutationRequest, Dr as beginOptimistic, Dt as relationShape, E as RemoteUnsatisfied, Ei as isFieldUnavailable, En as Mutate, Er as addOverlay, Et as relationAlias, F as PlanFreshness, Fi as writeEntities, Fn as REMOTE_PROTOCOL_VERSION, Fr as visibleItems, Ft as connectionChangeOf, G as inspectRemote, Gi as Edge, Gn as RemoteReadError, Gr as IDENTITY_SEPARATOR, Gt as RemoteResumePart, H as ReadDiagnosis, Hi as Boundary, Hn as RemoteMutationError, Hr as connectionsOf, Ht as coalesceQueries, I as PlanOptions, Ii as writeEntity, In as Read, Ir as visibleStore, It as liveEventOf, J as Matched, Ji as cursor, Jn as WindowSchema, Jr as Query, Jt as RemoteMessage, K as Belongs, Ki as EdgeRef, Kn as RemoteRpc, Kr as LiveInsertion, Kt as Failures, L as deadlineOf, Li as Freshness, Ln as ReadBatch, Lr as ConnectionRequirement, Lt as mutateRemote, M as SubscriptionsOptions, Mi as setStale, Mn as QueryRequest, Mr as removeOverlay, Mt as RemoteClient, N as RemotePolicy, Ni as setUnavailable, Nn as QueryResult, Nr as settleFailure, Nt as RemoteRpcClient, O as RetainOptions, Oi as markStale, On as MutationResult, Or as connectionIdentity, Ot as targetsOf, P as Deadline, Pi as tombstone, Pn as QueryRpc, Pr as settleSuccess, Pt as coalescedLayer, Q as AnySchema, Qi as hasPrevious, Qn as RemotePersistence, Qr as QueryWindow, Qt as emptyRefresh, R as plan, Ri as RemoteData, Rn as ReadBatchResult, Rr as RelationRequirement, Rt as remoteError, S as RemoteDescriptor, Si as entityKey, Sn as LiveEdge, Sr as EntityLayer, St as aliasedField, T as RemoteFold, Ti as isFieldStale, Tn as MAX_RELATION_DEPTH, Tr as addLayer, Tt as refsIn, U as RemoteInspection, Ui as Connection, Un as RemoteProtocolError, Ur as requirementsOf, Ut as coalesceReads, V as QueryExplanation, Vi as remoteErrorSchema, Vn as RemoteLiveError, Vr as Requirement, Vt as QueryRun, W as inspectEntity, Wi as Cursor, Wn as RemoteQueryError, Wr as ConnectionSpec, Wt as requirementKey, X as belongsEncoded, Xi as emptyConnection, Xn as MergePolicy, Xr as QueryInputs, Xt as RemoteMessageTag, Y as MatchingOptions, Yi as edge, Yn as WireBoundary, Yr as QueryDescriptor, Yt as RemoteMessageInput, Z as matching, Zi as hasNext, Zn as REMOTE_CACHE_VERSION, Zr as QueryRef, Zt as RemoteModel, _ as QueryWindowOptions, _i as EntityKey, _n as withRefreshRequested, _r as liveHasNext, _t as RefParts, a as FoldedMutationStarted, ai as MutationStatus, an as isQueryLoading, ar as reachable, at as RefPage, b as Registered, bi as clearStale, bn as Live, br as ConnectionIdentity, bt as RelationKind, c as ModelOfDomain, ci as SchemaOrFields, cn as onlyOverlaid, cr as EntityApplied, ct as SelectionOf, d as ObserveOptions, di as emptyMutationState, dn as remoteMessageCases, dr as LiveOutcome, dt as assemble, ea as items, ei as stableStringify, en as forgetRemote, er as SnapshotOptions, et as EntityDescriptor, f as QueryEntity, fi as failMutation, fn as remoteMessageSchema, fr as LiveState, ft as pageSchema, g as QueryRequirement, gi as EntityEntry, gn as windowGrowthKey, gr as emptyLiveState, gt as RefPageValue, h as QueryProjection, hi as schemaOf, hn as updateRemote, hr as classifyLive, ht as RELATION_ALIAS, i as EntitySelection, ia as unknown, ii as MutationState, in as isLoadingThrough, ir as gc, it as RefKey, j as SubscriptionEntries, ji as remove, jn as QueryEdge, jr as removeLayer, jt as RemoteJsonSend, k as SatisfyOptions, ki as missingFields, kn as NormalizedEntity, kr as emptyOptimistic, kt as RemoteJsonAnswer, l as MutateOptions, li as TypeOf, ln as refreshIsInFlight, lr as LiveCursor, lt as SelectionValue, m as QueryOptions, mi as reconcileMutation, mn as retentionRootsSchema, mr as applyEntityEvent, mt as unavailableOf, n as DomainMutateOptions, na as segment, ni as MutationAnswer, nn as isFieldFailed, nr as Retained, nt as EntityRef, o as LiveDependencies, oi as NormalizedPatch, on as isRemoteMessage, or as BoundaryCounts, ot as Page, p as QueryInput, pi as mutationStatus, pn as remoteModelSchema, pr as applyConnectionEvent, pt as relationOf, q as Judged, qi as Segment, qn as SettledFields, qr as LivePolicy, qt as RefreshState, r as EntityLike, ra as terminal, ri as MutationDescriptor, rn as isLoading, rr as RetentionRoots, rt as FieldsFrom, s as LiveOptions, si as Reconciled, sn as noFailures, sr as ConnectionApplied, st as Selection, t as BoundRemote, ta as merge, ti as Mutation, tn as initialRemoteModel, tr as ConnectionRoot, tt as EntityPatch, u as MutationStarted, ui as beginMutation, un as refreshedAt, ur as LiveEvent, ut as SelectionValueOf, v as ReadDependencies, vi as EntityStore, vn as writeRead, vr as liveHasPrevious, vt as RelationAnnotation, w as RemoteEntry, wi as hasField, wn as MAX_FIELDS_PER_REQUEST, wr as OptimisticState, wt as refParts, x as Remote, xi as emptyStore, xn as LiveChange, xr as ConnectionOverlay, xt as RelationShape, y as ReadMeta, yi as EntityWrite, yn as ConnectionChangeSchema, yr as ConnectionChange, yt as RelationEntityAnnotation, z as windowKey, zi as RemoteError, zn as ReadRequest, zr as RemoteConnections, zt as BatchRead } from "./index-njA5CxbS.mjs";
2
+ export { AnySchema, BatchRead, Belongs, BoundRemote, Boundary, BoundaryCounts, CoalesceOptions, Connection, ConnectionApplied, ConnectionChange, ConnectionChangeSchema, ConnectionIdentity, ConnectionOverlay, ConnectionRequirement, ConnectionRoot, ConnectionSpec, Cursor, Deadline, DomainMutateOptions, Edge, EdgeRef, Entity, EntityApplied, EntityDescriptor, EntityEntry, EntityKey, EntityLayer, EntityLike, EntityPatch, EntityRef, EntitySelection, EntityStore, EntityWrite, ExplainedDependencies, Failures, FieldsFrom, FoldedMutationStarted, Freshness, IDENTITY_SEPARATOR, Judged, Live, LiveChange, LiveCursor, LiveDependencies, LiveEdge, LiveEvent, LiveInsertion, LiveOptions, LiveOutcome, LivePolicy, LiveRequirement, LiveState, MAX_FIELDS_PER_REQUEST, MAX_RELATION_DEPTH, Matched, MatchingOptions, MergePolicy, ModelOfDomain, Mutate, MutateOptions, Mutation, MutationAnswer, MutationDescriptor, MutationRequest, MutationResult, MutationStarted, MutationState, MutationStatus, NormalizedEntity, NormalizedPatch, ObserveOptions, OptimisticOperation, OptimisticState, Page, PageSize, PlanFreshness, PlanOptions, Query, QueryDescriptor, QueryEdge, QueryEntity, QueryExplanation, QueryInput, QueryInputs, QueryOptions, QueryProjection, QueryRef, QueryRequest, QueryRequirement, QueryResult, QueryRpc, QueryRun, QueryWindow, QueryWindowOptions, RELATION_ALIAS, REMOTE_CACHE_VERSION, REMOTE_PROTOCOL_VERSION, Read, ReadBatch, ReadBatchResult, ReadDependencies, ReadDiagnosis, ReadMeta, ReadRequest, Reconciled, RefKey, RefPage, RefPageValue, RefParts, RefreshState, Registered, RelationAnnotation, RelationEntityAnnotation, RelationKind, RelationRequest, RelationRequirement, RelationShape, Remote, RemoteClient, RemoteConnections, RemoteData, RemoteDescriptor, RemoteDomain, RemoteEntry, RemoteError, RemoteFold, RemoteInspection, RemoteJsonAnswer, RemoteJsonRequest, type RemoteJsonSend, RemoteLiveError, RemoteMessage, RemoteMessageInput, RemoteMessageTag, RemoteModel, RemoteMutationError, RemotePersistence, RemotePolicy, RemoteProtocolError, RemoteQueryError, RemoteReadError, RemoteRequirements, type RemoteResumePart, RemoteRpc, RemoteRpcClient, RemoteUnsatisfied, RemoteWiring, Requirement, ResultOf, RetainOptions, Retained, RetentionRoots, SatisfyOptions, SchemaOrFields, Segment, Selection, SelectionOf, SelectionValue, SelectionValueOf, SelectsEntity, SettledFields, Snapshot, SnapshotOptions, SubscriptionEntries, SubscriptionsOptions, TypeOf, WindowSchema, WireBoundary, addLayer, addOverlay, aliasedField, applyConnectionEvent, applyEntityEvent, assemble, beginMutation, beginOptimistic, belongsEncoded, classifyLive, clearStale, coalesceQueries, coalesceReads, coalescedLayer, connectionChangeOf, connectionIdentity, connectionsOf, cursor, deadlineOf, edge, emptyConnection, emptyLiveState, emptyMutationState, emptyOptimistic, emptyRefresh, emptyStore, entityKey, entry, failMutation, failureOf, forgetRemote, gc, hasField, hasNext, hasPrevious, initialRemoteModel, inspectEntity, inspectRemote, isFieldFailed, isFieldStale, isFieldUnavailable, isGapped, isLoading, isLoadingThrough, isQueryLoading, isRefPage, isRemoteMessage, isTombstone, items, liveEventOf, liveHasNext, liveHasPrevious, markStale, matching, merge, missingFields, mutateRemote, mutationStatus, noFailures, onlyOverlaid, pageSchema, plan, pruneOverlays, reachable, readField, reconcileMutation, refParts, refreshIsInFlight, refreshedAt, refsIn, relationAlias, relationOf, relationShape, remoteDataSchema, remoteError, remoteErrorSchema, remoteMessageCases, remoteMessageSchema, remoteModelSchema, remove, removeLayer, removeOverlay, requirementKey, requirementsOf, retentionRootsSchema, schemaOf, segment, setStale, setUnavailable, settleFailure, settleSuccess, stableStringify, targetsOf, terminal, tombstone, unavailableOf, unknown, updateRemote, visibleItems, visibleStore, windowGrowthKey, windowKey, withRefreshRequested, writeEntities, writeEntity, writeRead };