Module resource

Resource shape types and operations.

Defines the shapes describing linked data resources and the members they carry, and provides the factories stating them and the accessors reading them. The resource factory states a shape, extending the shapes it is given and closed over the members declared for it; the member factories give each member the shape its values are drawn from and how many of them a resource may carry.

Defining resource shapes

Give each member a range and a cardinality:

import { boolean } from '@metreeca/blue/boolean';
import { integer } from '@metreeca/blue/number';
import { id, nonempty, optional, required, resource } from '@metreeca/blue/resource';
import { string } from '@metreeca/blue/string';

const Product = resource({
  id: id(),
  name: required(string({ minLength: 1 })),
  price: required(integer({ minInclusive: 0 })),
  available: optional(boolean()),
  tags: nonempty(string())
});
Copy

The four named cardinalities cover 1..1, 0..1, 1..* and 0..*; property states any other bounds:

const Shape = resource({
  name: required(string()),                                // 1..1
  alias: optional(string()),                               // 0..1
  tags: nonempty(string()),                                // 1..*
  notes: multiple(string()),                               // 0..*
  codes: property(string(), { minCount: 2, maxCount: 5 })  // 2..5
});
Copy

A member ranging over a dictionary stands apart from its cardinality: it carries the language map whole at every one, never in an array, and the bounds count the values of its other alternatives alone.

Each factory takes, after the range, the constraints the member carries beyond its cardinality, such as the predicate it maps to, the labels it carries, or whether it is serialised by default:

import { createNamespace } from '@metreeca/core/resource';

const schema = createNamespace("http://schema.org/");

const Person = resource({
  name: required(string(), { forward: schema })
});
Copy

Linked and embedded resources

A member reaches another resource in one of two ways. A reference links a standalone resource, identified and managed in its own right; a resource shape included directly describes an embedded resource, carried inline with no identity of its own.

import { reference } from '@metreeca/blue/reference';

const Rating = resource({
  average: required(number({ minInclusive: 0, maxInclusive: 5 })),
  reviews: required(number({ minInclusive: 0 }))
});

const Product = resource({
  id: id(),
  rating: optional(Rating),           // embedded
  vendor: required(reference(Vendor)) // standalone
});
Copy

An embedded resource carries no id member: having no identity of its own, an identifier is rejected as a value is validated rather than as the shape is built, since an id-bearing embedded range reads exactly like an expanded captive target until a value is matched against it.

A shape reaching itself defers the range, breaking the definition cycle:

function Category() {
  return resource({
    id: id(),
    name: required(string()),
    parent: optional(reference(Category))
  });
}
Copy

Inheritance

A shape extends the ones it is given first, carrying their members and constraints:

const NamedEntity = resource({
  id: id(),
  name: required(string({ minLength: 1 }))
});

const Employee = resource(NamedEntity, {
  department: required(string()),
  salary: required(integer({ minInclusive: 0 }))
});
Copy

A member reaching a resource is refined by re-pointing it at a shape extending the inherited target: the refinement states what it adds alone, as the narrower target carries the inherited definition through its own parents, the classes it belongs to included, which every value the refined member admits is held to. A union-valued member is refined by dropping alternatives and tightening the ones it keeps, never by adding new ones.

Reading a resource off a shape

getShapeClass and getShapeClasses resolve the classes the resources a shape describes belong to, getShapeId and getShapeType the names their identifier and class are stated under, and getShapeProperties the members they carry. Each resolves a deferred shape and crosses a link through to the resource behind it, answering with nothing where the shape reaches no resource at all.