@dxos/echo

@dxos/echo

ECHO API.

Installation

pnpm i @dxos/echo

DXOS Resources

• Website
• Developer Documentation
• Talk to us on Discord

Contributions

Your ideas, issues, and code are most welcome. Please take a look at our community code of conduct, the issue guide, and the PR contribution guide.

License: FSL-1.1-Apache-2.0 Copyright 2022 DXOS

API

import { Type, Obj, Relation, Ref, Query, Filter } from '@dxos/echo';

	Object	Relation (extends Obj)	Ref
SCHEMA API
Define schema	Type.Obj()	Type.Relation()	Ref.Ref()
Any schema type	Type.AnyObj	Type.Relation.Any	Type.Ref.Any
Get DXN (of schema)	Type.getURI(schema)	Type.getURI(schema)
Get typename (of schema)	Type.getTypename(schema)	Type.getTypename(schema)
Get type metadata (of schema)	Type.getMeta(schema)	Type.getMeta(schema)
Is mutable schema	Type.isMutable(schema)	Type.isMutable(schema)

| | DATA API | | Unknown instance type | Obj.Unknown | Relation.Unknown | Ref.Unknown | | Create object | Obj.make(Schema, { ... }) | Relation.make(Schema, { ... }) | Ref.make(obj) | | Check kind | Obj.isObject(obj) | Relation.isRelation(obj) | Ref.isRef(ref) | | Get relation source | | Relation.getSource(relation) | | | Get relation target | | Relation.getTarget(relation) | | | Check instance of | Obj.instanceOf(Schema, obj) | | Get schema | Obj.getSchema(obj) | | Get DXN (of instance) | Obj.getDXN(obj) | | Get typename (of instance) | Obj.getTypename(obj) | | Get Meta | Obj.getMeta(obj) | | Is deleted | Obj.isDeleted(obj) |

Type.getURI(schema) == DXN.parse('dxn:type:example.com/type/Person:0.1.0');
Type.getMeta(schema) == { typename: }
Type.getTypename(schema) === 'type.example.type.person'
Type.getVersion(schema) === '0.1.0'

Obj.getDXN(obj) === DXN.parse('dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX')

// We need this for objects that have typename defined, but their schema can't be resolved (Obj.getSchema(obj) === undefined)
Obj.getTypeURI(obj) === DXN.parse('dxn:type:example.com/type/Person:0.1.0');

/**
 * @deprecated
 **/
// TODO(dmaretskyi): Consider keeping it as a shorthand for zType.getTypename(Obj.getSchema(obj)) ?? Obj.getTypeURI(obj)?.asTypeDXN()?.type`
Obj.getTypename(obj) === 'com.example.type.person'

ISSUE: Create vs live: Is it fundamentally the same thing?

Object construction

Option 1:

Relation.make(EmployeeOf, {
  [Relation.Source]: cyberdyne,
  [Relation.Target]: bill,
  [Obj.Meta]: {
    keys: [{ url: 'acme.com', id: '123' }],
  },
  since: '2022',
});

Option 2:

Obj.make(Contact, {
  name: 'Bill',
});

Relation.make(
  Employee,
  {
    source: cyberdyne,
    target: bill,
    meta: {
      keys: [{ url: 'acme.com', id: '123' }],
    },
  },
  {
    since: '2022',
  },
);

Object model representation.

JSON serialization

Obj.toJSON(obj);
Obj.fromJSON(json, { graph, db });

Defines attributes and encoding placed on objects.

	Optional	Runtime prop	Runtime type	JSON prop	JSON type	Description
Id	No	id	ObjectID ULID string	id	string	Unique object ID
Self DXN	Yes	Symbol(@dxos/echo/DXN)	DXN	@dxn	string	DXN to the object itself
Type	No	Symbol(@dxos/echo/Type)	DXN	@type	string	DXN to the object type
Schema	Yes	Symbol(@dxos/echo/Schema)	Effect-Schema	-		Reference to the object schema
Tombstone marker	Yes	Symbol(@dxos/echo/Deleted)	boolean	@deleted	boolean	Deletion marker
Metadata	Yes	Symbol(@dxos/echo/Meta)	Metadata object	@meta	object	Metadata section
Entity kind	No	Symbol(@dxos/echo/EntityKind)	EntityKind	(inferred from other props)	string	Obj vs Relation
Relation Source DXN	No (only on relations)	Symbol(@dxos/echo/RelationSourceDXN)	DXN	@relationSource	DXN string	Relation source DXN
Relation Target DXN	No (only on relations)	Symbol(@dxos/echo/RelationTargetDXN)	DXN	@relationTarget	DXN string	Relation target DXN
Relation Source	Yes (only on relations)	Symbol(@dxos/echo/RelationSource)	Object	-		Relation source object
Relation Target	Yes (only on relations)	Symbol(@dxos/echo/RelationTarget)	Object	-		Relation target object

NOTE: All of the API functions can return undefined since they are also designed to work with objects outside of the database. TODO: Consider how Database, Hypergraph, and RefResolver are attached to the object.

Value representation

	Runtime	JSON
Reference	Ref	{ "/": "dxn:..." }