Ref

import { Ref } from '@dxos/echo';

A reference is a field that points at another entity. It stores the target’s DXN, not a copy, and resolves the target only when you ask. org.dxos.echo#F-4.1 References and DXNs explains the model; this page is the API.

Declare a reference field

Ref.Ref(Type) is the schema of a field that points at that type. Use it inside Schema.optional or Schema.Array like any other field schema. The tutorial’s Person and Event declare both:

src/schema.ts

import * as Schema from 'effect/Schema';

import { Annotation, DXN, Format, Ref, Type } from '@dxos/echo';

export class Organization extends Type.makeObject<Organization>(
  DXN.make('com.example.type.organization', '0.1.0'),
)(
  Schema.Struct({
    name: Schema.String,
    website: Schema.optional(Format.URL),
  }).pipe(
    Annotation.IconAnnotation.set({
      icon: 'ph--buildings--regular',
      hue: 'amber',
    }),
  ),
) {}

export class Person extends Type.makeObject<Person>(
  DXN.make('com.example.type.person', '0.1.0'),
)(
  Schema.Struct({
    name: Schema.String,
    email: Schema.optional(Format.Email),
    employer: Schema.optional(Ref.Ref(Organization)),
  }).pipe(
    Annotation.IconAnnotation.set({ icon: 'ph--user--regular', hue: 'cyan' }),
  ),
) {}

Make a reference

Ref.make takes an object you already hold. db.makeRef takes a URI and returns a reference bound to the database, so it can load its target. Ref.fromURI also takes a URI, but its reference has nothing to load from until a database binds it.

import { Obj, Ref } from '@dxos/echo';
import { Event, Organization, Person } from './schema.ts';

const acme = db.add(Obj.make(Organization, { name: 'Acme' }));
const ada = db.add(Obj.make(Person, { name: 'Ada', employer: Ref.make(acme) }));
const launch = db.add(
  Obj.make(Event, { title: 'Launch', attendees: [Ref.make(ada)] }),
);

// From a URI: bound to the database, so it can load.
const again = db.makeRef<Person>(Obj.getURI(ada));

Resolve a reference

peek returns the target if it is already in memory and never starts a load. load waits for the target, reading it from disk or the network, and throws if it cannot be found; tryLoad returns undefined instead. Ref.loadAll loads an array of references at once.

Avoid ref.target. It is deprecated because reading it starts a load as a side effect and can throw.

import { Ref } from '@dxos/echo';
import { Organization } from './schema.ts';

const loaded = ada.employer?.peek(); // Organization | undefined, never loads
// loads from disk or the network if needed
const employer = await ada.employer?.load();
// undefined instead of throwing when the target is missing
const maybe = await again.tryLoad();
// missing and deleted targets are left out
const attendees = await Ref.loadAll(launch.attendees ?? []);

Compare references

Each read of a reference field returns a new wrapper, so === never matches. Compare with Ref.equals, or test the target id with Ref.hasEntityId.

import { Ref } from '@dxos/echo';

const same =
  ada.employer !== undefined && Ref.equals(ada.employer, Ref.make(acme));
const attending = (launch.attendees ?? []).some(Ref.hasEntityId(ada.id));
Ref.isRef(ada.employer); // true

Members at a glance

Member	Summary
Ref(Type)	Schema of a reference field
Array(Type)	Schema of an array of references
make	A reference to an object you hold
fromURI	An unbound reference from a URI
loadAll	Load many targets, skipping missing and deleted ones
equals hasEntityId	Compare references
isRef	Predicate
ref.peek() ref.load() ref.tryLoad()	Read the target in memory, or load it

The full list is in the API reference.

Related

• References and DXNs
• Query traverses references inside a query.