foldkit-remote-server 0.1.0 → 0.2.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.
Files changed (2) hide show
  1. package/README.md +78 -44
  2. package/package.json +14 -3
package/README.md CHANGED
@@ -1,16 +1,36 @@
1
1
  # `foldkit-remote-server`
2
2
 
3
- The server half of [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote).
4
- It owns the semantic work Effect RPC does not know about: entity, query, and
5
- mutation Sources, **selection authorization**, normalization, and compilation to
6
- the `RemoteRpc` handlers.
3
+ Answers the requests a
4
+ [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote)
5
+ client makes. You write one **Source** per entity, query, and mutation — plain
6
+ Effect functions that load rows — and this package compiles them into the
7
+ `RemoteRpc` handlers: it groups and de-duplicates the ids a client asked for,
8
+ drops the fields a principal may not read, resolves a nested selection level by
9
+ level through each entity's own Source, and normalizes the results into the
10
+ patches the client's store reconciles.
11
+
12
+ Reach for it when the server is yours and you want the client's field-level
13
+ selections honoured end to end, with authorization enforced where the field
14
+ names are still known rather than in the view. It owns no HTTP, WebSockets,
15
+ serialization, authentication protocol, or database connection: `principal` is
16
+ resolved outside and passed in, and a Source's database is an Effect requirement
17
+ the Source declares, not something this package holds.
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ pnpm add foldkit-remote-server
23
+ ```
7
24
 
8
- It does not own HTTP, WebSockets, serialization, the authentication protocol, or
9
- database connections. `principal` is resolved outside and passed in; runtime
10
- dependencies stay in the Effect environment instead of being captured.
25
+ `effect` is a peer dependency; `foldkit-remote` and `foldkit-surface` come with
26
+ it. `foldkit-remote-drizzle` compiles its selections and queries to SQL.
11
27
 
12
28
  ## Quick start
13
29
 
30
+ One entity, one mutation, one query, one live stream, compiled to a layer.
31
+ `loadProjects`, `renameProject`, `projectsPage`, and `projectEvents` are the
32
+ application's own data access; `principal` is whatever authentication resolved.
33
+
14
34
  ```ts
15
35
  import { Effect, Schema } from 'effect'
16
36
  import { Entity, Mutation, Query, RemoteRpc } from 'foldkit-remote'
@@ -67,22 +87,24 @@ const layer = RemoteRpc.toLayer(handlers)
67
87
  ```
68
88
 
69
89
  `handlers(server, principal, options?)` takes a `HandlerOptions<P, R>`:
70
- `maxIdsPerEntity` (default 1000) bounds a read batch and a live subscription
71
- per entity, `maxDepth` (default 8) bounds nested resolution, and `live` is the
72
- hub whose signals reach the subscriptions this handler registers. In-process,
73
- the handlers are a `RemoteClient` through `Remote.clientLayer(handlers)`, with
74
- whatever the sources require supplied by `Layer.provide`.
90
+ `maxIdsPerEntity` (default 1000) bounds how many distinct ids of one entity a
91
+ read batch — or a `liveHub` subscription — may name, `maxDepth` (default 8)
92
+ bounds nested resolution, and `live` is the hub whose signals reach the
93
+ subscriptions this handler registers. In-process, the handlers are a
94
+ `RemoteClient` through `Remote.clientLayer(handlers)`, with whatever the sources
95
+ require supplied by `Layer.provide`.
75
96
 
76
97
  ## Sources
77
98
 
78
99
  ### `RemoteServer.entity`
79
100
 
80
- ```ts
81
- RemoteServer.entity(Project, {
82
- authorize?: (principal: P, fields: readonly string[]) => readonly string[],
83
- read: (context: { ids; fields; windows?; principal }) =>
84
- Effect.Effect<ReadonlyArray<{ id: string; values: Record<string, unknown> }>, RemoteServerError, R>,
85
- })
101
+ ```text
102
+ RemoteServer.entity(entity, {
103
+ read: (context: { ids: readonly string[]; fields: readonly string[]
104
+ windows?: Record<string, QueryWindow>; principal: P })
105
+ => Effect<ReadonlyArray<{ id: string; values: Record<string, unknown> }>, RemoteServerError, R>
106
+ authorize?: (principal: P, fields: readonly string[]) => readonly string[]
107
+ }): EntitySource<P, R>
86
108
  ```
87
109
 
88
110
  Given the Entity, a request for a field it does not declare never reaches
@@ -92,16 +114,15 @@ no fields and passes every requested one through.
92
114
  `read` is called once per entity, id batch, and window per read level: ids are
93
115
  batched up to `maxIdsPerEntity`, ids that page a relation differently are read
94
116
  separately, and a nested selection reads its next level after the refs arrive.
95
- `windows` carries the pagination window for each requested relation field. The result may be a partial
96
- entity: a field the source omits is simply not present, and presence metadata on
97
- the client reflects that.
117
+ `windows` carries the pagination window for each requested relation field. The
118
+ result may be a partial entity: a field the source omits is simply not present,
119
+ and presence metadata on the client reflects that.
98
120
 
99
121
  ### `RemoteServer.query`
100
122
 
101
- ```ts
102
- RemoteServer.query(ProjectsByOwner, ({ input, window, principal }) =>
103
- Effect.Effect<QueryPage, RemoteServerError, R>,
104
- )
123
+ ```text
124
+ RemoteServer.query(query, (context: { input: Input; window: QueryWindow; principal: P })
125
+ => Effect<QueryPage, RemoteServerError, R>): QuerySource<P, R>
105
126
  ```
106
127
 
107
128
  `QueryPage` is `{ edges, start, end }`; `start`/`end` are `Boundary` values
@@ -110,14 +131,12 @@ inferring adjacency from row count.
110
131
 
111
132
  ### `RemoteServer.mutation`
112
133
 
113
- ```ts
114
- RemoteServer.mutation(RenameProject, ({ input, principal }) =>
115
- Effect.Effect<
116
- { output: Output; entities?: NormalizedPatch[]; connections?: ConnectionChange[] },
117
- RemoteServerError,
118
- R
119
- >,
120
- )
134
+ ```text
135
+ RemoteServer.mutation(mutation, (context: { input: Input; principal: P })
136
+ => Effect<{ output: Output
137
+ entities?: ReadonlyArray<NormalizedPatch>
138
+ connections?: ReadonlyArray<ConnectionChange> },
139
+ RemoteServerError, R>): MutationSource<P, R>
121
140
  ```
122
141
 
123
142
  `input` is decoded against the mutation's `Input` schema first, so the callback
@@ -129,11 +148,11 @@ ones in place: `RemoteServer.prepend(connection, ref)`, `append`, and
129
148
 
130
149
  ### `RemoteServer.live`
131
150
 
132
- ```ts
133
- RemoteServer.live(Project, {
134
- subscribe: ({ requirements, after, principal }) =>
135
- Stream.Stream<LiveChange, RemoteServerError, R>,
136
- })
151
+ ```text
152
+ RemoteServer.live(entity, {
153
+ subscribe: (context: { requirements: ReadonlyArray<Requirement>; after: number; principal: P })
154
+ => Stream<LiveChange, RemoteServerError, R>
155
+ }): LiveSource<P, R>
137
156
  ```
138
157
 
139
158
  `after` is the client's resume cursor; events at or before it are duplicates. The
@@ -148,21 +167,26 @@ The higher-level signal. A hub tracks each live subscriber's requirements and
148
167
  principal, so the server says *what changed* and the hub works out *who cares*:
149
168
 
150
169
  ```ts
170
+ // `entitySources` is the same array `RemoteServer.make({ entities })` was given.
151
171
  const hub = yield* RemoteServer.liveHub(entitySources)
152
- const handlers = RemoteServer.handlers(server, principal, { live: hub })
172
+ const handlers = RemoteServer.handlers(Server, principal, { live: hub })
153
173
 
154
174
  // Wherever the data changes (a mutation source, a database trigger):
155
175
  yield* hub.changed(Project.ref(projectId), ['status', 'updatedAt'])
156
176
  yield* hub.deleted(Project.ref(projectId))
157
177
  ```
158
178
 
179
+ `liveHub` and its signals are Effects, so the lines above live inside an
180
+ `Effect.gen`. It needs only the entity sources, so the mutation sources that
181
+ signal it can be built after it.
182
+
159
183
  `changed` intersects the fields with what each subscriber selects, re-reads
160
184
  that intersection through the entity's own source under the subscriber's
161
185
  principal (one read per principal value and window signature; subscribers
162
186
  selecting none of the fields do no work), and streams an `EntityPatched`
163
187
  carrying only the fields that subscriber may see. A record the source does not
164
- return for the changed id reaches nobody. `deleted` streams an `EntityDeleted` to the entity's
165
- subscribers. Cursors continue from the cursor each subscriber resumed at, so
188
+ return for the changed id reaches nobody. `deleted` streams an `EntityDeleted`
189
+ to the entity's subscribers. Cursors continue from the cursor each subscriber resumed at, so
166
190
  the client's duplicate and gap handling is unchanged. A hub and hand-written
167
191
  `RemoteServer.live` sources number their events independently; use one or the
168
192
  other for a given subscription. Nested relation targets are not subscribed by
@@ -185,9 +209,10 @@ principal read this semantic field*. Authorization is mandatory, not opt-in:
185
209
 
186
210
  ## Hardening
187
211
 
188
- - Each read batch and live subscription is bounded per entity
189
- (`maxIdsPerEntity`, default 1000, counted across the batch's window groups),
190
- and an oversized one fails rather than loading unbounded rows.
212
+ - A read batch is bounded per entity (`maxIdsPerEntity`, default 1000, counted
213
+ across the batch's window groups) and an oversized one fails rather than
214
+ loading unbounded rows; a `liveHub` subscription is bounded the same way. A
215
+ hand-written `RemoteServer.live` source bounds itself.
191
216
  - A selection nested past `MAX_RELATION_DEPTH` (8) or naming more than
192
217
  `MAX_FIELDS_PER_REQUEST` (256) fields of one entity is refused at decode.
193
218
  - Returned field names are filtered with `Object.hasOwn` and accumulated into a
@@ -214,3 +239,12 @@ principal read this semantic field*. Authorization is mandatory, not opt-in:
214
239
  connection insert/remove/invalidate events.
215
240
  - Database and other runtime dependencies are the Source's Effect requirements,
216
241
  not this package's.
242
+
243
+ ## See also
244
+
245
+ - [Server-derived state](https://github.com/doeixd/foldkit-plus/blob/main/docs/remote.md) — the mental model for
246
+ both halves.
247
+ - [`foldkit-remote`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote) — the client half this answers; [`foldkit-remote-drizzle`](https://github.com/doeixd/foldkit-plus/tree/main/packages/remote-drizzle)
248
+ compiles its selections and queries to SQL.
249
+ - [`examples/kitchen-sink`](https://github.com/doeixd/foldkit-plus/tree/main/examples/kitchen-sink) — the server packages with a live hub, an optimistic
250
+ insert confirmed in place, and retention.
package/package.json CHANGED
@@ -1,9 +1,20 @@
1
1
  {
2
2
  "name": "foldkit-remote-server",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Server sources and handler compilation for foldkit-remote: entities, selection authorization, and normalization.",
5
+ "keywords": [
6
+ "foldkit",
7
+ "effect",
8
+ "server-state",
9
+ "rpc",
10
+ "authorization",
11
+ "normalization"
12
+ ],
5
13
  "type": "module",
6
14
  "license": "MIT",
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
7
18
  "author": "Patrick Glenn <doeixd@gmail.com>",
8
19
  "repository": {
9
20
  "type": "git",
@@ -27,8 +38,8 @@
27
38
  "LICENSE"
28
39
  ],
29
40
  "dependencies": {
30
- "foldkit-remote": "0.1.0",
31
- "foldkit-surface": "0.1.0"
41
+ "foldkit-remote": "0.2.0",
42
+ "foldkit-surface": "0.1.1"
32
43
  },
33
44
  "peerDependencies": {
34
45
  "effect": "^4.0.0-rc.112"