source/adapter/adapter_capabilities library
Opt-in capability markers for adapters.
The base LocalAdapter / RemoteAdapter contracts declare optional methods
(reactive watch*, transaction, pagination, relational fetch) that default
to null or throw UnimplementedError. These mixins let an adapter
advertise which optional capabilities it genuinely supports, so the engine
and callers can branch on adapter is WatchableAdapter instead of probing
for a null stream or catching an exception at runtime.
Most are pure markers (no members) so applying one is free and
backward-compatible. RawQueryCapable additionally declares the rawQuery
method — kept off the base adapter interfaces so adding it never breaks
existing implements LocalAdapter/RemoteAdapter implementations.
Mixins
-
CursorSyncCapable<
T extends DatumEntityInterface> -
The remote adapter serves incremental pulls from an opaque change
cursor — the natural fit for changes-feed backends (Firestore snapshot
tokens, DynamoDB streams, CouchDB
sincesequences, or a plain monotonically increasing change counter). -
DeltaSyncCapable<
T extends DatumEntityInterface> -
The remote adapter can serve incremental pulls: instead of returning
the full dataset every cycle, it returns only entities modified at or
after a watermark (typically
WHERE modified_at >= ?on the backend). - PaginatedAdapter
-
The adapter natively supports pagination (
readAllPaginated/watchAllPaginated) rather than throwing or loading everything. - RawQueryCapable
- The adapter supports raw queries for projections/aggregations without full entity hydration (#11).
- RelationalAdapter
-
The adapter can resolve relationships at the storage layer
(
fetchRelated/watchRelated). - SchemaFingerprintCapable
- The local adapter persists an opaque schema fingerprint — the auto-migration fast path.
- SqlSchemaCapable
- A SQL-backed local adapter that exposes its table and dialect, letting the engine run schema DDL against it (the auto-migration SQL path) without knowing adapter internals. Pair with RawQueryCapable.
- TransactionalAdapter
-
The adapter implements real ACID-style
transactionsemantics (atomic commit/rollback), not just a pass-through. - WatchableAdapter
-
The adapter supports reactive queries (
watchAll/watchById/watchQueryreturn live, non-null streams).
Typedefs
-
CursorPage<
T> = ({List< T> items, String nextCursor}) - The result of one CursorSyncCapable.readChanges page: the changed entities plus the opaque cursor to pass on the next call.