DatumRelationSpec<E extends RelationalDatumEntity, R extends DatumEntityInterface> class

A typed, declare-once relation between entities E and R.

class Project extends RelationalDatumEntity with MemoizedRelations {
  static final authorRel = DatumRelationSpec<Project, Author>.belongsTo(
      'author', foreignKey: authorIdField);
  static final ticketsRel = DatumRelationSpec<Project, Ticket>.hasMany(
      'tickets', foreignKey: Ticket.projectIdField,
      cascadeDelete: CascadeDeleteBehavior.cascade);

  @override
  Map<String, Relation> buildRelations() => datumRelationsFor(this, [authorRel, ticketsRel]);
}

// Eager load with typed names, read back with bound name + type:
final p = await projects.read('p1', userId: uid, withRelated: [Project.ticketsRel].names);
final tickets = Project.ticketsRel.listOf(p!) ?? const [];

// Or fetch lazily — resolved through Datum.manager<R>() on any adapter:
final author = await Project.authorRel.fetchOneFor(p);

Constructors

DatumRelationSpec.belongsTo(String name, {required DatumFieldSpec<E, String> foreignKey, String localKey = 'id', CascadeDeleteBehavior cascadeDelete = CascadeDeleteBehavior.none})
A to-one parent relation: the R whose localKey equals this entity's foreignKey — the owning entity's own field spec (e.g. Ticket.projectIdField on Ticket).
DatumRelationSpec.hasMany(String name, {required DatumFieldSpec<R, String> foreignKey, String localKey = 'id', CascadeDeleteBehavior cascadeDelete = CascadeDeleteBehavior.none})
A to-many relation: rows of R whose foreignKey equals this entity's localKey. foreignKey is the child's field spec (e.g. Ticket.projectIdField), keeping one vocabulary for queries, migration, and relations.
DatumRelationSpec.hasOne(String name, {required DatumFieldSpec<R, String> foreignKey, String localKey = 'id', CascadeDeleteBehavior cascadeDelete = CascadeDeleteBehavior.none})
A to-one child relation, same key semantics as DatumRelationSpec.hasMany.

Properties

cascadeDelete → CascadeDeleteBehavior
Cascade-delete behavior carried onto the built relation.
final
foreignKeyName → String
The serialized foreign-key field name, taken from the typed field spec (for DatumRelationKind.manyToMany: the pivot's self-side key).
final
hashCode → int
The hash code for this object.
no setterinherited
kind → DatumRelationKind
The relation shape.
final
localKey → String
The key on the referenced side (default 'id').
final
name → String
The relation name (the relations map key / withRelated entry).
final
otherLocalKey → String
The referenced-side key for the far end of a many-to-many.
final
pivotOtherKeyName → String?
The pivot's other-side key name (DatumRelationKind.manyToMany only).
final
pivotType → Type?
The pivot entity type (DatumRelationKind.manyToMany only) — must be registered with Datum so managerByType can resolve it.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

buildFor(E entity) → Relation<R>
Builds the runtime Relation for entity — buildRelations() becomes a one-liner via datumRelationsFor.
fetchListFor(E entity) → Future<List<R>>
Lazily fetches this to-many relation for entity, resolving through the registered Datum.manager<R>() — identical on every adapter. Returns the cached value when already loaded.
fetchOneFor(E entity) → Future<R?>
Lazily fetches this to-one relation for entity (DatumRelationKind.belongsTo or DatumRelationKind.hasOne), resolving through Datum.manager<R>().
listOf(E entity) → List<R>?
The loaded values of this to-many relation on entity, or null when not loaded (eager-load first with withRelated: [spec].names).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
oneOf(E entity) → R?
The loaded value of this to-one relation on entity, or null when absent or not loaded.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

manyToMany<E extends RelationalDatumEntity, R extends DatumEntityInterface, P extends DatumEntityInterface>(String name, {required DatumFieldSpec<P, String> pivotSelfKey, required DatumFieldSpec<P, String> pivotOtherKey, String localKey = 'id', String otherLocalKey = 'id', CascadeDeleteBehavior cascadeDelete = CascadeDeleteBehavior.none}) → DatumRelationSpec<E, R>
A many-to-many relation through a registered pivot entity P: pivot rows whose pivotSelfKey equals this entity's id select the R rows referenced by their pivotOtherKey. Both keys are the pivot's typed field specs, so the whole join is spelled in one vocabulary: