Skip to content

3. What each form expresses

The class name is the label. @Node() marks the class as a declared type.

@Node({ description: "A film, keyed by IMDb id.", userAnchor: false, partial: false })
export class Movie extends Entity { /* Other members omitted. */ }

description, userAnchor, partial and internal mean exactly what the YAML keys of the same name mean. Omitting userAnchor takes the framework default; see LABELS_AND_COMPOSITION.md §2.

Ancestors are extends. Capability labels are the declaration-merged interface:

@Node()
export class Trust extends Organisation { /* Other members omitted. */ }
export interface Trust extends Watchable {}

Guarantee — neither is restated. A type does not name its own parents in @Node; the class hierarchy and the merged interface are the declaration. The YAML equivalent is parents: [Organisation] plus carrying Watchable.

A declared property is a declared property. declare because the value comes from the graph, not from a constructor.

@Property supplies what TypeScript cannot:

@Property({ type: "int" }) declare year: number;

Requirement — declare int where you mean int. TypeScript has one numeric type; the graph distinguishes integers from reals, and a source that returns "1994" is coerced according to what you declared. A number property with no @Property({ type }) is treated as a real.

JSDoc on the property is its description.

3.3a Lifecycle — lifecycle: holds every node of a label to a curation rule

Section titled “3.3a Lifecycle — lifecycle: holds every node of a label to a curation rule”

A type may declare which values of its status property a read admits, and which are never returned:

- name: Memory
lifecycle:
active: [ACTIVE] # what a plain read returns — the default
never: [CONTRADICTED] # known-false: not returned even when asked for by name — the default

Guarantee — the rule is written into every read. MATCH (m:Memory) reads only ACTIVE memories. MATCH (m:Memory) WHERE m.status = 'SUPERSEDED', or (m:Memory {status: 'STALE'}), relaxes the read to anything but a never value: the constraint has to be on the node, in the same clause. WHERE m.status = 'CONTRADICTED' answers nothing. This is the rule the platform’s Proposition has always been held to; a declared lifecycle holds your label the same way, whichever source fetched the node and whether it is stored or transient.

Guarantee — a child inherits it. A type whose parents: chain reaches a type with a lifecycle is held to the nearest one; a child that declares its own overrides it. So DiceMemory under Memory is curated without restating anything, and so is a realm’s ZepMemory.

Guarantee — the declaration is the world’s own. It holds in the world whose types declare it, and in no other; a platform-curated label (Proposition) keeps the platform’s lifecycle and a declaration naming it is refused and reported.

Requirement — the property is status, and the node carries it. A lifecycle is a shared vocabulary, so there is one spelling of it; a node of a curated label with no status answers nothing. active must name at least one value; a value may not be both active and never; either breaks the declaration at load, naming the type.

An edge is declared as a field on the side that holds the key:

@Node()
export class MovieRating extends Entity {
@Id() declare imdbId: string;
/** The film this rating is OF. */
@Relationship({ type: "OF", producer: "movieByImdbId",
keyField: "imdbId", recordKeyField: "imdbId" })
declare movie: Movie;
/** Films like this one. */
@Relationship({ type: "SIMILAR_TO", producer: "similarMovies",
keyField: "title", recordKeyField: "similarTo" })
declare similar: Movie[];
}
  • keyField — the property on this node whose value is the fetch key.
  • recordKeyField — the property the fetched record echoes it back in, so the edge links.
  • producer — what fetches the target when a traversal crosses the edge.

Guarantee — the key is one the anchor’s records carry. keyField must be a property the anchor type declares, or a field one of the anchor type’s own joins names as its recordKeyField — a column its records are already said to carry, such as a foreign key a type keeps out of its properties so queries follow the edge instead of returning the id. Any other keyField is reported as a load problem against the declaring realm.

Guarantee — the target is the field’s type. Movie, not the string "Movie".

Guarantee — cardinality is the field’s arity. Movie is one; Movie[] is many. The YAML form has no way to say this.

Guarantee — the direction of declaration does not change the graph. The YAML declares a join under the TARGET type naming its anchor; TypeScript declares it on the ANCHOR naming its target. Both produce the same traversable edge. Write it where it reads better.

3.4a Projected types — local types ai.fromText creates

Section titled “3.4a Projected types — local types ai.fromText creates”

projected: true marks a type as local: created only by ai.fromText, never stored, backed by nothing, and the only kind of type that declares relationships: of its own. The YAML form and its rules are in VIRTUAL_CYPHER.md §7.8.

@Retrieval({ operation: "omdb.getMovie", nameFrom: "title",
fieldMap: { imdbId: "imdbID", title: "Title" } })
export class Movie extends Entity { /* Other members omitted. */ }

fieldMap maps the source’s own field names onto this type’s. nameFrom chooses the property whose value names the binding when the result is put in scope.