foldkit-remote 0.3.0 → 0.5.0

package/README.md

@@ -145,9 +145,9 @@ Start with one server entity and one selection:
 
 ```ts
 import { Schema } from 'effect'
-import { Entity } from 'foldkit-remote'
+import { Entity } from 'foldkit-entity'
 
-const Project = Entity.make(
+const Project = Entity.define(
   'Project',
   Schema.Struct({
     id: Schema.String,
@@ -157,12 +157,20 @@ const Project = Entity.make(
 )
 
 // A Selection is the exact server-owned shape this consumer needs.
-const ProjectSummary = Project.select({
+const ProjectSummary = Entity.select(Project, {
   id: true,
   name: true,
 })
 ```
 
+The entity comes from [`foldkit-entity`](../entity), which declares a domain
+without Remote in it. Remote also has an `Entity.make` of its own, and accepts
+either — but only a `foldkit-entity` entity has addressable `fields`, so only
+that one can be given [relations](#entities-declared-with-foldkit-entity),
+derived members, or a [query body](#queries-and-pagination). Reach for
+`Entity.make` when a domain is small enough that Remote is all it will ever
+need; reach for `Entity.define` otherwise, which is most of the time.
+
 Embed Remote's Submodel in the application and bind the domain to that field:
 
 ```ts
@@ -293,6 +301,32 @@ const clientLayer = Remote.clientLayer(rpcClient)
 `RemoteClient` service used by subscriptions and Commands. The transport itself
 is not owned by Remote.
 
+## One list per application with `Data.wiring`
+
+The integration steps above — spread `Remote.messages`, reduce by tag, derive
+`Data.subscriptions`, provide the client — are one value when the application
+uses `foldkit-bundle`:
+
+```ts
+import { Bundle } from 'foldkit-bundle'
+
+const Page = Bundle.parent({ Model, Message })
+const wiring = Page.assemble(
+  Data.wiring({
+    project: Surface.at(ProjectPage, model =>
+      model.route._tag === 'project' ? { projectId: model.route.projectId } : undefined,
+    ),
+  }),
+)
+const update = wiring.update(model => ({ model }))
+```
+
+`Data.wiring` routes Remote's Messages into `Data.reduce`, brings the active
+Surfaces' Subscriptions and the domain's contract, and requires `RemoteClient`
+from the runtime's resources — the same client layer from above. One assembly
+holds at most one Remote domain: every domain claims the same Message tags,
+and the assembly refuses a second claimant at startup, naming both.
+
 ## `RemoteData`: what does the Model know right now?
 
 A Remote Projection never lies by pretending an absent value is present. It
@@ -329,7 +363,13 @@ The states are:
 - **`Ready`** — every selected field is present and decodes.
 - **`Refreshing`** — the current value remains visible while it is being refetched.
 - **`Failed`** — stored server data does not decode against the Selection.
-- **`NotFound`** — the entity is represented by a tombstone.
+- **`NotFound`** — the entity is represented by a tombstone: a live event
+  deleted it, or the server was asked for it by id and answered without it. That
+  id is then known absent, whether it never existed, is gone, or is not this
+  principal's to see. It is not planned again until `Data.refresh` forces it or a
+  write brings it back. The target of a returned ref is not marked this way: a
+  server need not expand a relation that rides on a request, and the planner asks
+  for such a target by id next, which is when its absence is learned.
 
 `Initial` is intentionally different from `Loading`. A Projection belonging to
 no active Surface may remain `Initial` forever. Rendering a spinner for
@@ -339,6 +379,46 @@ state that actually means "wait for this request."
 `RemoteData.match` is exhaustive, so adding or omitting a state is visible at
 compile time.
 
+### Drawing one: `RemoteData.render`
+
+Most views draw these six states three ways, under one policy: useful data
+stays on screen. `RemoteData.render` is that fold.
+
+```ts
+RemoteData.render(project, {
+  loading: () => ProjectSkeleton(),
+  notFound: () => NoSuchProject(),
+  failed: error => ErrorView(error),
+  data: (value, freshness) =>
+    ProjectView({ project: value, dimmed: freshness._tag !== 'Fresh' }),
+})
+```
+
+`Initial` and `Loading` reach `loading`; `Ready` and `Refreshing` reach `data`;
+a `Failed` that still carries the value it had reaches `data` too, so a read
+that failed does not throw away what the reader was already looking at. Only a
+`Failed` with nothing to show reaches `failed`.
+
+The `data` branch is told which it got, as a `Freshness` — exported, so a view
+helper that takes one can name it:
+
+| `Freshness` | What it means |
+| --- | --- |
+| `Fresh` | This is the current answer. |
+| `Refreshing` | A newer answer is on its way; this one is still good. |
+| `Stale` | A read failed; this is what was last known good, with its `error`. |
+
+It is one tag rather than a pair of booleans because a value cannot be both
+refreshing and stale, and a type that can say so invites a view to handle a
+state that never arrives.
+
+`notFound` is its own branch and not optional. A row the server answered for
+and does not have is neither loading nor a failure; drawing it as either is a
+spinner that never ends or an error nobody can act on.
+
+Reach for `match` instead when the six states really do draw differently — it
+stays the exhaustive fold, and `render` does not replace it.
+
 ## Normalized entities and selections
 
 Remote stores an entity once by identity, regardless of how many Surfaces read
@@ -384,6 +464,57 @@ An unknown field or a nested Selection for the wrong entity is a type error.
 Recursive relations remain finite because the entity schema stores references
 (`Entity.ref(User)` / `Entity.refTo('Node')`), not recursively inlined schemas.
 
+### Entities declared with `foldkit-entity`
+
+[`foldkit-entity`](../entity/README.md) declares a domain without Remote in it:
+fields, relations as navigation edges, derived members. `Remote.make` registers
+those Entities, and `Data.get`, `Data.live`, and a query's `select` take their
+Selections. Remote compiles both into the descriptor and Selection above, so
+the store, the planner, and the server see nothing new.
+
+```ts
+import { Schema } from 'effect'
+import { Entity, Relation } from 'foldkit-entity'
+import { Remote } from 'foldkit-remote'
+
+const User = Entity.define('User', Schema.Struct({ id: Schema.String, name: Schema.String }))
+const Project = Entity.define('Project', Schema.Struct({ id: Schema.String, name: Schema.String }))
+const Work = Entity.relate({ User, Project }, { Project: { owner: Relation.one(User) } })
+
+const ProjectCard = Entity.select(Work.Project, {
+  name: true,
+  owner: Entity.select(Work.User, { name: true }),
+})
+
+const Data = Remote.make({ model: App.model.remote, entities: [Work.User, Work.Project] })
+const card = Data.get(ProjectCard, 'p1') // Projection<Model, RemoteData<{ name; owner: { name } }>>
+```
+
+- A relation becomes a ref field: `one` a ref, an optional `one` a nullable ref,
+  `many` an array of refs. A derived member becomes a field the server supplies.
+- The Entity needs an `id` field; Remote keys the store by it. When that field
+  is branded, `Data.get` and `Data.live` take that type for an Entity Selection:
+  another Entity's id, or plain text, does not compile.
+- Register the Entities of one `Entity.relate` result and select from that same
+  result; `Object.values(Work)` registers them all.
+- `Entity.from(entity)` and `Selection.from(selection)` are the compile steps,
+  for when you need the descriptor itself: `patch` and `ref` in a mutation
+  handler.
+- `Entity.page(selection, window)` in an Entity Selection is Remote's
+  `Selection.connection`: the window travels with the read, and the server
+  answers with a page of refs. A page of a whole list is read under a name of
+  its own, `comments@first=10`, so one view can show every comment while another
+  shows the first ten of the same post: they are two fields to the store, fetched
+  in one batch, merged and refreshed each on its own. A write to the list (a
+  mutation's patch, a live change) marks its pages stale, so they are read again.
+  A cursor is not part of the name: a page read from a cursor continues its page.
+  The server refuses a request that pages one relation more than four ways, and
+  a field's own name may not contain `@`.
+
+`Entity.make` with `Entity.ref` keeps working, and both kinds can share one
+domain. Both packages export `Entity`; a module that needs `Entity.from` beside
+`Entity.define` aliases one of them.
+
 Presence is tracked separately from the JavaScript value. These are distinct:
 
 ```text
@@ -433,6 +564,24 @@ Projection itself.
 
 ### Refreshing from `update`
 
+### Showing a change nobody has made
+
+A mutation's `optimistic` operations show over the store while it is in flight.
+`Data.overlay` shows operations the same way with no request behind them, until
+`Data.lift`: a preview, in every Selection and view, of something not yet sent.
+
+```ts
+const previewed = Data.overlay(model, 'post-preview', [Project.patch(id, { name: draft })])
+const back = Data.lift(previewed, 'post-preview')
+```
+
+- Both are called from `update`, and neither performs I/O or touches what the
+  server said: the store beneath is as it was.
+- Showing an id again replaces what it showed. Lifting what was never shown
+  returns the same Model.
+- An overlay's id is apart from every request's, so a mutation that settles does
+  not take a preview with it.
+
 To revalidate what a screen already declares — a refresh button, a focus
 regained — hand its Projection (or a Surface without params) to `Data.refresh`:
 
@@ -445,8 +594,9 @@ case 'ClickedRefresh': {
 ```
 
 `Data.refresh` performs no I/O and restates no request. It returns the Model
-with every selected field the store holds reading `Refreshing` and every loaded
-connection invalidated; the `Data.subscriptions` read entries then refetch it,
+with every selected field the store holds reading `Refreshing`, every entity it
+knew to be absent forgotten, so `NotFound` reads `Loading` and is asked for
+again, and every loaded connection invalidated; the `Data.subscriptions` read entries then refetch it,
 since stale data is planned again under every policy, so the page is requested
 once. The Projection must be observed, as it is while it is on screen; for data
 nothing observes, use `Data.prefetch` with `RemotePolicy.networkOnly`.
@@ -479,6 +629,52 @@ const Data = Remote.make({
 })
 ```
 
+`Query.make` names a query and says what it returns. Where it *means*
+something the client should be able to state, declare it with a body instead:
+
+```ts
+import { Entity, Expr, Order, Query } from 'foldkit-entity'
+
+const Task = Entity.define(
+  'Task',
+  Schema.Struct({ id: Schema.String, ownerId: Schema.String, updatedAt: Schema.Number }),
+)
+
+const TasksByOwner = Query.define(
+  'TasksByOwner',
+  { ownerId: Schema.String },
+  ({ input }) =>
+    Query.from(Task).pipe(
+      Query.where(Expr.eq(Task.fields.ownerId, input.ownerId)),
+      Query.orderBy(Order.desc(Task.fields.updatedAt), Order.asc(Task.fields.id)),
+    ),
+)
+```
+
+A body is written over a [`foldkit-entity`](../entity) Entity, because that is
+what has addressable fields: `Task.fields.ownerId` is a reference an `Expr` can
+be built from, where this package's own `Entity.make` describes a field as the
+schema of its value and has nothing to point at. An entity declared either way
+still reads, selects and normalizes the same; only a query body needs the
+richer declaration.
+
+What comes back is an ordinary descriptor — the same name, `Input`, `ref` and
+connection identity — carrying its `body` besides, and the result is a
+connection over the Entity the body reads, so it is not named twice. A server
+can compile that body rather than be told the same thing again in its own
+dialect; one that would rather answer the query its own way still can, and a
+descriptor from `Query.make` has no body at all.
+
+The body is built **once**, when the query is declared. Inside it `input.ownerId`
+is a placeholder for the value the query will be given, not the value — there is
+nothing there yet to branch on. A condition that depends on what was passed is a
+comparison over the placeholder, never a `?:` around it.
+
+`Input` must be fields or a plain `Schema.Struct`, because that is what the
+placeholders are made from. A codec that exposes no keys is refused where the
+query is declared rather than handing the body an empty object, which would
+compare a column to nothing while every type agreed.
+
 Then a query is still just a Projection:
 
 ```ts
@@ -552,6 +748,17 @@ Those settlement Messages go through `Data.reduce` like every other Remote fact.
 The request id comes from the Remote Model's sequence, so `update` stays pure.
 Settling is idempotent per `requestId`.
 
+A mutation that deletes says so. The server's outcome carries
+`deleted: [{ entity, id }]`, and settling it tombstones those entities: they read
+`NotFound`, and they leave every connection and relation they were in, so the
+server names no list. Patches apply first, so an entity named both ways is
+deleted; a retry of the same request deletes nothing again.
+
+`Data.mutation(model, requestId)` reads what became of it from the Model:
+`Pending`, `Applied`, `Failed` with the error the server or transport gave, or
+`Unknown` for an id never started here (or settled so long ago it left the
+bounded ledger). A retry reuses its id, and the latest outcome wins.
+
 Optimistic entity patches are **layers over the base store**, not inverse
 patches. If multiple mutations overlap, the visible cache is recomputed as base
 plus the still-pending layers, so settling one does not require trying to undo
@@ -576,6 +783,41 @@ const { model: started, command } = Data.mutate(model, AddComment, input, {
 A successful server result can replace the request's temporary connection
 overlays with confirmed ones in place.
 
+### Reading past what is only pending
+
+Every projection reads the **visible** cache: the server-derived store under
+the layers still pending, which is why an optimistic change shows at once. A
+reader that must not believe a change until the server has agreed to it asks
+for the confirmed read instead:
+
+```ts
+Data.confirmed(Data.get(ProjectSummary, projectId))
+```
+
+It is the same projection — the same requirements, planned the same way, so
+observing it fetches exactly what observing the original fetches — reading the
+server-derived store alone, with the pending layers and connection overlays
+left off. An optimistically inserted edge is not in its page; an
+optimistically patched field reads as the server last said.
+
+A view almost always wants the projection itself. This is for the reader that
+reports on the world rather than drawing it, which in practice is an Agent
+capability that must not claim success before the server reflects it:
+
+```ts
+Agent.when({
+  projection: Data.confirmed(Data.get(ProjectSummary, projectId)),
+  predicate: (project, request) => project.name === request.name,
+})
+```
+
+There is deliberately no `Data.visible`: a projection already is the visible
+read, and a second name for it would be a wrapper that only forwards.
+
+Sync draws the same line over its replica, with the same words and a different
+mechanism: see [what a reader sees while a change is in
+flight](../../docs/state-model.md#what-a-reader-sees-while-a-change-is-in-flight).
+
 ### Remote mutation vs Sync operation
 
 Do not use Remote mutation as a durable offline-write mechanism:
@@ -741,6 +983,15 @@ useful question is: **"Why is this Projection still Initial?"** `Data.plan`
 shows whether Remote believes anything is actually missing; active Surface
 wiring determines whether that plan is being executed.
 
+`Data.inspect(model).loading` answers the other one — **"what is Remote doing
+right now?"** — with the `entity\0id\0field` marks of the reads in flight,
+beside `mutations.pending` for the writes. Both are read from the Model, not
+from the fibers doing the work: a tool that shows them shows something a
+recorded Model can be replayed to, and nothing that needs the runtime to be
+asked. That is deliberate. Runtime activity is not a second source of truth
+here, and a view that rendered from it would stop being reproducible from the
+Model.
+
 ## Advanced: the kernel
 
 Everything above compiles to the lower-level exports below; there is not a
@@ -911,6 +1162,15 @@ Remote does **not** own:
 - authentication; server-side authorization belongs at the Source boundary;
 - a background scheduler or general-purpose database/query engine.
 
+## How state changes here
+
+Local application state uses `evo` inside `update`, like anywhere else.
+Remote Messages go through `Data.reduce` into the embedded `Remote.Model`
+submodel — Remote owns that reducer, and it is the only writer of the
+cache. Never install cache state with a ref `set`; the requirements,
+staleness, and tombstones only stay coherent when every fact arrives as a
+Remote Message.
+
 ## Limits
 
 - Effect RPC is the wire contract; the application supplies deployment layers.