Module reference

Reference shape types and operations.

Defines the shape linking a resource to another standalone resource, named by an absolute IRI, and provides the reference factory stating it and the accessor reading its target. The factory pairs the IRI with the shape describing the resource it points at, deferred where a definition cycle requires it, so a member pointing at a resource carries the identifier alone and leaves the resource to be retrieved in its own right.

Defining reference members

Wrap a target resource shape with reference and give it a cardinality:

import { id, multiple, required, resource } from '@metreeca/blue/resource';
import { reference } from '@metreeca/blue/reference';

const Vendor = resource({
  id: id()
});

const Product = resource({
  id: id(),
  vendor: required(reference(Vendor)),
  suppliers: multiple(reference(Vendor))
});
Copy

Standalone and embedded resources

A reference links to a standalone resource, identified and managed in its own right. A resource shape included directly, without the wrapper, describes an embedded resource: a nested value with no identity of its own, created and managed together with the resource carrying it.

Ownership and lifecycle are stated on the member rather than on the reference: see foreign and captive.

Reading a target off a shape

getShapeTarget resolves the resource shape a shape points at, crossing a link and taking a resource carried inline to itself, so that a caller reaching for what lies behind a shape needs not tell the two apart.