Remote / foldkit-remote-server

How a read resolves

A client selection can request several IDs and nested relations at once. Before calling your Sources, the handler groups requirements by entity, takes the union of requested fields across screens, keeps only declared fields that pass authorize, and batches de-duplicated IDs into one read({ ids, fields, windows?, principal }) call per entity.

If any selected field is a relation reference, the handler follows the returned IDs level by level into the target Entity's Source until every selected branch is resolved, then returns normalized patches.

Key rules enforced by every Entity Source:

  • Undeclared fields are dropped before authorize or read runs. Fields, relations, and derived members are all declared on the Entity, so a relation such as owner is authorized and followed like any field.
  • Requested fields are matched as own properties returned by your Source, so constructor or __proto__ are settled rather than read from Object.prototype.
  • authorize can only narrow requested fields; it never adds fields the client did not ask for.
  • A Source may omit a requested field; any omitted field is settled as unavailable so the client stops re-requesting it.
  • Shared IDs across multiple selections are fetched once, and relation targets are batched level by level without redundant fetches.
  • A relation the principal may not read is skipped without following its target.
  • authorize runs once per field across all rows; filter runs per record after read and may request extra fields (such as an owner ID) needed to decide visibility. Members removed by filter are settled as unavailable. foldkit-guard builds filter rules from member guards.
  • A Source or Query Source may declare visible (from a Drizzle binding or RemoteServer.memory's readable) so startup checks like GuardServer.validate can verify row-level rules.

Keep your Source queries tight by projecting only fields in your database or API call: the handler strips extra keys on return, and projecting at the data boundary avoids wasted work.

Nested selections

When a client projects Project:p1 { id, name, owner { id, name } }, the Project Source returns owner as a reference (User:u7) rather than joining or inlining the user row.

RemoteServer collects all owner refs across the batch and requests their selected fields from UserSource in one batched level. The Sources never call each other recursively: RemoteServer handles traversal, depth limits, batching, and de-duplication while each Source answers only for its own Entity.