# @dxos/echo

> ECHO API

Latest version **0.16.0** (published 2026-10-19) · FSL-1.1-Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @dxos/echo
pnpm add @dxos/echo
yarn add @dxos/echo
bun add @dxos/echo
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.16.0 |
| Published | 2026-10-19 |
| First published | 2025-04-25 |
| Weekly downloads | 0 |
| License | FSL-1.1-Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 13 |
| Unpacked size | 3.4 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 531 |
| Author | info@dxos.org |
| Maintainers | richburdon, marik_d, wittjosiah, dxos-bot, mykola-vrmchk |

## Links

- npm: https://www.npmjs.com/package/@dxos/echo
- Repository: https://github.com/dxos/dxos
- Homepage: https://dxos.org
- Issues: https://github.com/dxos/dxos/issues
- npm.io page: https://npm.io/package/@dxos/echo

## Dependencies (13)

- [effect](https://npm.io/package/effect.md) 4.0.4
- [semver](https://npm.io/package/semver.md) ^7.7.4
- [@dxos/log](https://npm.io/package/@dxos/log.md) 0.16.0
- [@dxos/blob](https://npm.io/package/@dxos/blob.md) 0.16.0
- [@dxos/keys](https://npm.io/package/@dxos/keys.md) 0.16.0
- [@dxos/util](https://npm.io/package/@dxos/util.md) 0.16.0
- [@dxos/async](https://npm.io/package/@dxos/async.md) 0.16.0
- [@dxos/debug](https://npm.io/package/@dxos/debug.md) 0.16.0
- [@dxos/effect](https://npm.io/package/@dxos/effect.md) 0.16.0
- [@dxos/errors](https://npm.io/package/@dxos/errors.md) 0.16.0
- [@dxos/node-std](https://npm.io/package/@dxos/node-std.md) 0.16.0
- [@dxos/invariant](https://npm.io/package/@dxos/invariant.md) 0.16.0
- [@dxos/echo-protocol](https://npm.io/package/@dxos/echo-protocol.md) 0.16.0

## Recent versions

- 0.16.0 (latest) — 2026-10-19
- 0.16.0-next-60712ab191a99ba90316cc4be753e9e11b17100a (next) — 2026-10-19
- 0.9.1-main.c7dcc2e112 (main) — 2026-06-19
- 0.16.0-next-b440559823fb87ed1a4590dab21ae924d4d76c3a — 2026-10-19
- 0.14.0 — 2026-10-10
- 0.13.0 — 2026-10-07
- 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 — 2026-08-27
- 0.12.0-next-2800d0376abcc62d5544afdd744b16b2b960434e — 2026-08-27
- 0.12.0-next-2be9f24c465d98f4bd186aa03ece788902e6c17a — 2026-08-27
- 1.0.0-next-bbabc02363f18d7643ea4160e3a7a7809870fd0d — 2026-08-10
- 0.11.1 — 2026-08-05
- 0.11.0 — 2026-08-05
- 0.10.0 — 2026-07-02
- 0.9.1-staging.ee54ba693a — 2026-07-02
- 0.9.0 — 2026-06-15
- … 107 more at https://npm.io/package/@dxos/echo/versions

## README

# @dxos/echo

ECHO API.

## Installation

```bash
pnpm i @dxos/echo
```

## DXOS Resources

- [Website](https://dxos.org)
- [Developer Documentation](https://docs.dxos.org)
- Talk to us on [Discord](https://dxos.org/discord)

## Contributions

Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs).

License: [FSL-1.1-Apache-2.0](./LICENSE) Copyright 2022 © DXOS

## API

```ts
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)` |

```ts
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:

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

Option 2:

```ts
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

```ts
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:..." }` |

---
_Source: https://npm.io/package/@dxos/echo · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
