Document

The document contract is Forze's CRUD aggregate store: a DocumentSpec binds a read model (and optional write models) to a logical name, and the context resolves a query port (reads) and a command port (writes) for it. The conceptual model is in Reading data and the writing-operation chapter; this is the exhaustive surface.

q = ctx.document.query(spec)    # reads
c = ctx.document.command(spec)  # writes

All methods are async. Naming is systematic: get*/find* return the read model R; project* returns a JsonDict of selected fields; select* validates into a caller-supplied return_type. The suffix sets the result container — none → CountlessPage (no total), _page → Page (with .count), _cursor → CursorPage (keyset), _stream → an async generator of batches. The filters, sorts, and aggregates arguments follow the query DSL.

Spec¶

DocumentSpec[R, D, C, U] — binds the read model and optional write types to a name, plus per-aggregate policy:

write is a DocumentWriteTypes TypedDict — domain (the Document subclass), create_cmd, and an optional update_cmd.

Lenient read fields¶

By default every read-model field must map to a stored column, and a relational backend fails at startup if one is missing — drift is caught at boot, not on the first query. lenient_read_fields opts named fields out of that rule, on the read side only:

• the field is dropped from the read projection and hydrated from its model default on every read (so it carries the same default for every row);
• it is removed from the filter / sort / aggregate allow-sets — a column that is not there cannot be queried;
• the Postgres startup schema check tolerates the missing column instead of failing (Mongo and Firestore are schemaless, so they tolerate it naturally).

Honored on Postgres, Mongo, and Firestore. Each name must be a non-computed read-model field that carries a default (is non-required) and is not an identity/audit field (id, rev, created_at, last_update_at) or a materialized field. It is read-side only: if the same field is also stored on the write/domain model over that relation, Postgres write-schema validation still requires its column.

Use it for a field that exists in code ahead of (or independently of) the physical column — e.g. during an expand/contract migration — or a read-model display field the write model does not persist.

Instead of listing fields, set read_conformity="lenient" to auto-derive the set: every statically-defaulted, non-identity read field that is not materialized becomes lenient (fields with a default_factory are excluded — declare those explicitly to accept a fresh value per row). Explicit lenient_read_fields are always added on top. resolved_lenient_read_fields is the effective set every backend reads.

write_omit_fields is the write-side counterpart: a domain field with no column is silently stripped from every insert/update and hydrates from the domain default on read-back (Postgres, Mongo, and Firestore). Because the value is dropped (not persisted), it is explicit-only — never auto-derived — requires a write spec, and each name must be a defaulted, non-identity domain field. Use it for a domain field that is computed or stored elsewhere, not on this table.

Query port¶

Fetch one¶

for_update takes a RowLockMode (True / "nowait" / "skip_locked") to lock the row inside a transaction.

Fetch many¶

Each comes in find / project / select flavors and _many / _page / _cursor containers. All take filters, sorts, and pagination:

Stream & aggregate¶

filters, sorts, and aggregates use the query DSL; pagination is {"limit": …, "offset": …}.

Command port¶

Every mutating method takes return_new: bool = True — return the resulting read model(s), or None when you don't need them back.

Create¶

Update¶

Delete¶

kill(pk) and kill_many(pks) hard-delete — there is no soft-delete or restore on the port (model soft-delete is a domain concern, applied via update).

Implemented by¶

The in-memory mock implements the full surface, so an aggregate is testable without a backend — see Testing.