@twinfinity/entity-reference
Index
Functions
- addressable
- cardinalityOf
- child
- componentIdentity
- equals
- forKnownDomain
- format
- formatDomain
- formatQuery
- fromUriComponent
- isExactQuery
- isUnder
- isValidId
- isValidSegment
- isValidTypeName
- isVersionPinned
- leaf
- matchShape
- matchesIdSpelling
- parent
- parse
- parseDomain
- parseQuery
- pinnedDepth
- prefixes
- queryAnchor
- root
- shapeByKey
- shapeKey
- shapeMatches
- stem
- subjectArity
- toUriComponent
- tryChild
- tryParse
- tryParseDomain
- tryParseQuery
- tryRoot
- tryWithPath
- withPath
- withoutVersions
Interfaces
Type Aliases
Variables
Type Aliases
EntityCardinality
EntityIdSpelling
The id spelling a component's identifier must take. Literal patterns throughout -- never a permissive uuid parse, which would admit several non-canonical spellings of one id.
EntityQueryElement
One element of a query pattern, with the separator that precedes it. Discriminated on kind, so
which of type, id and version an element carries follows from what it matches.
EntityQueryElementKind
What an element of a query pattern matches: exact is type:id, one named entity spelled as a
reference spells it; anyId is type:*, any id of this type; anyElement is *, any one element
whatever its type.
EntityVersionPolicy
How a match should treat an @version qualifier on a component.
The distinction is between resolving a reference and merely recognising one. A resolver
asked for file:F@3 that cannot fetch version 3 must refuse, never silently answer with the
current version -- that is the resolution contract. A store asked to persist a reference to
file:F@3 has no such problem: it is recording what the caller pinned, and whether anything can
resolve it yet is a different question asked at a different time.
The C# twin is PS.BIM.Core.Model.EntityVersionPolicy, and the two must offer the same modes:
a client that pre-validates a reference before sending it must reach the same verdict the
receiving service will.
Variables
constALL_SHAPES
Every shape the platform recognises. Ordered by domain, to read against EntityShapes.cs.
constDOMAINS
Every domain that appears in ALL_SHAPES -- the closed allowlist a bare-domain
reference is checked against (ADR-0008 point 8d). forKnownDomain in entity-domain-reference.ts
performs that check.
Mirrors EntityShapes.Domains, and derived from the table for the same reason: the grammar
admits any lowercase word as a domain, so the gate on which ones may actually appear is this set
and never the pattern. Without it exported, a client holding documents had no way to ask
whether that domain exists, and a bare domain nothing serves looked exactly like one that does.
Read-only by type only: Object.freeze cannot seal a Set's entries, so a cast can still
mutate it at runtime. Never write to it.
constMAX_LENGTH
The longest a reference may be, in characters. Matches the maxLength of
schemas/data/entity-reference.json and PS.BIM.Core.Model.ScopedEntityReference.MaxLength.
Bounded in the grammar rather than by each service that stores a reference: unbounded, a reference passes every other rule and then fails inside a btree at insert time, which surfaces as an unmapped 500 -- or, where an insert failure dead-letters, as silent loss. Characters rather than bytes, since 512 four-byte worst-case characters still clear the row limit.
The grammar is the one bound every reference passes through. Some columns back it up and some do not:
issue.topic_references and the Event closure's chain columns carry 512-character char_length
CHECKs, while event.events.entity and related_entities are unbounded.
constMIN_TYPE_NAME_LENGTH
Minimum number of characters in a domain or a component type.
How many entities a reference can name.