@dxos/echo 0.8.2-staging.7ac8446 → 0.8.3-main.672df60

package/dist/types/src/Type.d.ts

@@ -1,49 +1,87 @@
 import { type Schema } from 'effect';
-import { type BaseSchema, type EchoSchema, type Expando as Expando$, type ImmutableSchema, type JsonSchemaType, type TypeMeta, EntityKind, ObjectId, Ref as Ref$, getTypeAnnotation, getSchema, getSchemaDXN, getSchemaTypename, getSchemaVersion, isInstanceOf } from '@dxos/echo-schema';
-export type { TypeMeta as Meta, JsonSchemaType as JsonSchema };
-export { EntityKind as Kind, ObjectId, getTypeAnnotation as getMeta, getSchema, getSchemaDXN as getDXN, getSchemaTypename as getTypename, getSchemaVersion as getVersion, isInstanceOf as instanceOf, };
+import type { EncodedReference } from '@dxos/echo-protocol';
+import * as EchoSchema from '@dxos/echo-schema';
+import type * as Keys from '@dxos/keys';
 /**
- * Type API.
- *
- * @category api namespace
- * @since 0.9.0
+ * ECHO schema.
  */
-export declare namespace Type {
+export type Schema = EchoSchema.EchoSchema;
+/**
+ * EchoObject schema.
+ */
+export declare const Obj: (meta: EchoSchema.TypeMeta) => <Self extends Schema.Schema.Any>(self: Self) => EchoSchema.EchoTypeSchema<Self>;
+/**
+ * EchoRelation schema.
+ */
+export declare const Relation: <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(options: {
+    typename: string;
+    version: string;
+    source: Source;
+    target: Target;
+}) => <Self extends Schema.Schema.Any>(self: Self) => EchoSchema.EchoTypeSchema<Self, EchoSchema.RelationSourceTargetRefs<Schema.Schema.Type<Source>, Schema.Schema.Type<Target>>>;
+/**
+ * Ref schema.
+ */
+export declare const Ref: <S extends Obj.Any>(schema: S) => EchoSchema.Ref$<Schema.Schema.Type<S>>;
+export declare namespace Obj {
+    /**
+     * Type that represents an arbitrary schema type of an object.
+     * NOTE: This is not an instance type.
+     */
+    type Any = Schema.Schema.AnyNoContext;
+}
+export declare namespace Relation {
+    /**
+     * Type that represents an arbitrary schema type of a relation.
+     * NOTE: This is not an instance type.
+     */
+    type Any = Schema.Schema.AnyNoContext;
+    /**
+     * Get relation target type.
+     */
+    type Target<A> = A extends EchoSchema.RelationSourceTargetRefs<infer T, infer _S> ? T : never;
+    /**
+     * Get relation source type.
+     */
+    type Source<A> = A extends EchoSchema.RelationSourceTargetRefs<infer _T, infer S> ? S : never;
+}
+export declare namespace Ref {
     /**
-     * A schema that can be extended with arbitrary properties.
+     * Type that represents an arbitrary schema type of a reference.
+     * NOTE: This is not an instance type.
      */
-    type Expando = Expando$;
-    type Abstract<T = any> = BaseSchema<T>;
-    type ImmutableType<T> = ImmutableSchema<T>;
-    type MutableType<T> = EchoSchema<T>;
+    type Any = Schema.Schema<EchoSchema.Ref<any>, EncodedReference>;
 }
-export declare const ref: <T extends import("@dxos/echo-schema").BaseObject>(obj: T) => Ref$<T>;
-export declare const create: {
-    <T extends import("@dxos/echo-schema").BaseObject>(obj: T): import("@dxos/live-object").ReactiveObject<T>;
-    <T extends import("@dxos/echo-schema").BaseObject>(schema: Schema.Schema<T, any, never>, obj: NoInfer<import("@dxos/echo-schema").ExcludeId<T>>, meta?: import("@dxos/echo-schema").ObjectMeta): import("@dxos/live-object").ReactiveObject<T>;
-};
-/**
- * Defines an ECHO type.
- *
- * @example
- * ```ts
- * const Org = S.Struct({
- *   name: S.String,
- * }).pipe(Type.def({ typename: 'example.com/type/Org', version: '1.0.0' }));
- * ```
- */
-export declare const def: (meta: TypeMeta) => <Self extends Schema.Schema.Any>(self: Self) => import("@dxos/echo-schema").EchoObjectSchema<Self>;
-/**
- * Defines a reference to an ECHO object.
- *
- * @example
- * ```ts
- * import { Type } from '@dxos/echo';
- * const Contact = S.Struct({
- *   name: S.String,
- *   employer: Type.Ref(Org),
- * }).pipe(Type.def({ typename: 'example.com/type/Contact', version: '1.0.0' }));
- * ```
- */
-export declare const Ref: <S extends Schema.Schema.AnyNoContext>(self: S) => import("@dxos/echo-schema").Ref$<Schema.Schema.Type<S>>;
+/**
+ * Gets the full DXN of the schema.
+ * Will include the version if it's a `type` DXN.
+ * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
+ */
+export declare const getDXN: (schema: Obj.Any | Relation.Any) => Keys.DXN | undefined;
+/**
+ * @param schema - Schema to get the typename from.
+ * @returns The typename of the schema. Example: `example.com/type/Person`.
+ */
+export declare const getTypename: (schema: Obj.Any | Relation.Any) => string;
+/**
+ * Gets the version of the schema.
+ * @example 0.1.0
+ */
+export declare const getVersion: (schema: Obj.Any | Relation.Any) => string;
+/**
+ * ECHO type metadata.
+ */
+export type Meta = EchoSchema.TypeAnnotation;
+/**
+ * Gets the meta data of the schema.
+ */
+export declare const getMeta: (schema: Obj.Any | Relation.Any) => Meta | undefined;
+export { EntityKind as Kind } from '@dxos/echo-schema';
+/**
+ * @returns True if the schema is mutable.
+ */
+export declare const isMutable: (schema: Obj.Any | Relation.Any) => boolean;
+export { SpaceId, ObjectId, DXN } from '@dxos/keys';
+export { Expando, JsonSchemaType as JsonSchema, toJsonSchema, Format, } from '@dxos/echo-schema';
 //# sourceMappingURL=Type.d.ts.map

package/dist/types/src/Type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Type.d.ts","sourceRoot":"","sources":["../../../src/Type.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,OAAO,IAAI,QAAQ,EACxB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,QAAQ,EAEb,UAAU,EACV,QAAQ,EACR,GAAG,IAAI,IAAI,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACb,MAAM,mBAAmB,CAAC;AAW3B,YAAY,EAAE,QAAQ,IAAI,IAAI,EAAE,cAAc,IAAI,UAAU,EAAE,CAAC;AAC/D,OAAO,EACL,UAAU,IAAI,IAAI,EAClB,QAAQ,EACR,iBAAiB,IAAI,OAAO,EAC5B,SAAS,EACT,YAAY,IAAI,MAAM,EACtB,iBAAiB,IAAI,WAAW,EAChC,gBAAgB,IAAI,UAAU,EAC9B,YAAY,IAAI,UAAU,GAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B;;OAEG;IACH,KAAY,OAAO,GAAG,QAAQ,CAAC;IAE/B,KAAY,QAAQ,CAAC,CAAC,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9C,KAAY,aAAa,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;IAClD,KAAY,WAAW,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;CAC5C;AAMD,eAAO,MAAM,GAAG,uEAAU,CAAC;AAC3B,eAAO,MAAM,MAAM;;;CAAU,CAAC;AAM9B;;;;;;;;;GASG;AACH,eAAO,MAAM,GAAG,SAAU,QAAQ,uGAAqB,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,CAAC,MAAM,CAAC,YAAY,QAAQ,CAAC,4DAAsC,CAAC"}
+{"version":3,"file":"Type.d.ts","sourceRoot":"","sources":["../../../src/Type.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,UAAU,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,KAAK,IAAI,MAAM,YAAY,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,GAAG,gHAAwB,CAAC;AAEzC;;GAEG;AACH,eAAO,MAAM,QAAQ;;;;;kLAA0B,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,GAAG,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAkB,CAAC;AAE5G,yBAAiB,GAAG,CAAC;IACnB;;;OAGG;IAEH,KAAY,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;CAC9C;AAED,yBAAiB,QAAQ,CAAC;IACxB;;;OAGG;IAEH,KAAY,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IAE7C;;OAEG;IACH,KAAY,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,wBAAwB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAErG;;OAEG;IACH,KAAY,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,wBAAwB,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACtG;AAED,yBAAiB,GAAG,CAAC;IACnB;;;OAGG;IACH,KAAY,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,gBAAgB,CAAC,CAAC;CACxE;AAED;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,QAAQ,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAG,IAAI,CAAC,GAAG,GAAG,SAElE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAG,MAI5D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAG,MAI3D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,UAAU,CAAC,cAAc,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,QAAQ,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAG,IAAI,GAAG,SAE/D,CAAC;AAEF,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,GAAG,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,KAAG,OAE1D,CAAC;AAEF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAEL,OAAO,EACP,cAAc,IAAI,UAAU,EAC5B,YAAY,EACZ,MAAM,GACP,MAAM,mBAAmB,CAAC"}

package/dist/types/src/{Database.d.ts → experimental/database.d.ts}

@@ -5,4 +5,4 @@
  * @since 0.9.0
  */
 export declare namespace Database { }
-//# sourceMappingURL=Database.d.ts.map
+//# sourceMappingURL=database.d.ts.map

package/dist/types/src/experimental/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../../src/experimental/database.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,yBAAiB,QAAQ,CAAC,GAAE"}

package/dist/types/src/experimental/index.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=index.d.ts.map

package/dist/types/src/experimental/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/experimental/index.ts"],"names":[],"mappings":""}

package/dist/types/src/{Queue.d.ts → experimental/queue.d.ts}

@@ -5,4 +5,4 @@
  * @since 0.9.0
  */
 export declare namespace Queue { }
-//# sourceMappingURL=Queue.d.ts.map
+//# sourceMappingURL=queue.d.ts.map

package/dist/types/src/experimental/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../../src/experimental/queue.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,yBAAiB,KAAK,CAAC,GAAE"}

package/dist/types/src/{Space.d.ts → experimental/space.d.ts}

@@ -5,4 +5,4 @@
  * @since 0.9.0
  */
 export declare namespace Space { }
-//# sourceMappingURL=Space.d.ts.map
+//# sourceMappingURL=space.d.ts.map

package/dist/types/src/experimental/space.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"space.d.ts","sourceRoot":"","sources":["../../../../src/experimental/space.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,WAAW,KAAK,CAAC,GAAE"}

package/dist/types/src/index.d.ts

@@ -1,7 +1,7 @@
-import { DXN } from '@dxos/keys';
-export { DXN };
-export * as Database from './Database';
-export * as Queue from './Queue';
-export * as Space from './Space';
 export * as Type from './Type';
+export * as Obj from './Obj';
+export * as Relation from './Relation';
+export * as Ref from './Ref';
+export { type Live } from '@dxos/live-object';
+export { Filter, Query } from '@dxos/echo-schema';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEjC,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,IAAI,MAAM,QAAQ,CAAC;AAC/B,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,KAAK,QAAQ,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAE7B,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/src/{api.test.d.ts.map → test/api.test.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../../../src/api.test.ts"],"names":[],"mappings":""}
+{"version":3,"file":"api.test.d.ts","sourceRoot":"","sources":["../../../../src/test/api.test.ts"],"names":[],"mappings":""}

package/dist/types/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"version":"5.7.3"}
+{"version":"5.8.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.2-staging.7ac8446",
+  "version": "0.8.3-main.672df60",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -21,20 +21,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.6.0",
-    "effect": "3.13.3",
-    "@dxos/debug": "0.8.2-staging.7ac8446",
-    "@dxos/echo-db": "0.8.2-staging.7ac8446",
-    "@dxos/echo-schema": "0.8.2-staging.7ac8446",
-    "@dxos/echo-protocol": "0.8.2-staging.7ac8446",
-    "@dxos/echo-signals": "0.8.2-staging.7ac8446",
-    "@dxos/invariant": "0.8.2-staging.7ac8446",
-    "@dxos/effect": "0.8.2-staging.7ac8446",
-    "@dxos/keys": "0.8.2-staging.7ac8446",
-    "@dxos/live-object": "0.8.2-staging.7ac8446",
-    "@dxos/node-std": "0.8.2-staging.7ac8446",
-    "@dxos/util": "0.8.2-staging.7ac8446",
-    "@dxos/log": "0.8.2-staging.7ac8446"
+    "@preact/signals-core": "^1.9.0",
+    "effect": "3.14.21",
+    "@dxos/debug": "0.8.3-main.672df60",
+    "@dxos/echo-protocol": "0.8.3-main.672df60",
+    "@dxos/echo-schema": "0.8.3-main.672df60",
+    "@dxos/echo-signals": "0.8.3-main.672df60",
+    "@dxos/effect": "0.8.3-main.672df60",
+    "@dxos/invariant": "0.8.3-main.672df60",
+    "@dxos/keys": "0.8.3-main.672df60",
+    "@dxos/live-object": "0.8.3-main.672df60",
+    "@dxos/node-std": "0.8.3-main.672df60",
+    "@dxos/log": "0.8.3-main.672df60",
+    "@dxos/util": "0.8.3-main.672df60"
   },
   "publishConfig": {
     "access": "public"

package/src/Obj.ts

@@ -0,0 +1,120 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import * as EchoSchema from '@dxos/echo-schema';
+import { assertArgument, invariant } from '@dxos/invariant';
+import type { DXN } from '@dxos/keys';
+import * as LiveObject from '@dxos/live-object';
+
+import type * as Ref from './Ref';
+import type * as Type from './Type';
+
+export type Any = EchoSchema.AnyEchoObject;
+
+export const make = LiveObject.live;
+
+// TODO(dmaretskyi): Currently broken
+export const isObject = (obj: unknown): obj is Any => {
+  return LiveObject.isLiveObject(obj);
+};
+
+/**
+ * Check that object or relation is an instance of a schema.
+ * @example
+ * ```ts
+ * const person = Obj.make(Person, { name: 'John' });
+ * const isPerson = Obj.instanceOf(Person);
+ * isPerson(person); // true
+ * ```
+ */
+export const instanceOf: {
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S): (value: unknown) => value is S;
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S, value: unknown): value is S;
+} = ((...args: any[]) => {
+  if (args.length === 1) {
+    return (obj: unknown) => EchoSchema.isInstanceOf(args[0], obj);
+  }
+
+  return EchoSchema.isInstanceOf(args[0], args[1]);
+}) as any;
+
+export const getSchema = EchoSchema.getSchema;
+
+// TODO(dmaretskyi): Allow returning undefined.
+export const getDXN = (obj: Any): DXN => {
+  assertArgument(!Schema.isSchema(obj), 'Object should not be a schema.');
+  const dxn = EchoSchema.getObjectDXN(obj);
+  invariant(dxn != null, 'Invalid object.');
+  return dxn;
+};
+
+/**
+ * @returns The DXN of the object's type.
+ * @example dxn:example.com/type/Contact:1.0.0
+ */
+// TODO(dmaretskyi): Allow returning undefined.
+export const getSchemaDXN = (obj: Any): DXN => {
+  const type = EchoSchema.getType(obj);
+  invariant(type != null, 'Invalid object.');
+  return type;
+};
+
+/**
+ * @returns The typename of the object's type.
+ * @example `example.com/type/Contact`
+ */
+export const getTypename = (obj: Any): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema == null) {
+    // Try to extract typename from DXN.
+    return getSchemaDXN(obj)?.asTypeDXN()?.type;
+  }
+
+  return EchoSchema.getSchemaTypename(schema);
+};
+
+// TODO(dmaretskyi): Allow returning undefined.
+export const getMeta = (obj: Any): EchoSchema.ObjectMeta => {
+  const meta = EchoSchema.getMeta(obj);
+  invariant(meta != null, 'Invalid object.');
+  return meta;
+};
+
+// TODO(dmaretskyi): Default to `false`.
+export const isDeleted = (obj: Any): boolean => {
+  const deleted = EchoSchema.isDeleted(obj);
+  invariant(typeof deleted === 'boolean', 'Invalid object.');
+  return deleted;
+};
+
+export const getLabel = (obj: Any): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    return EchoSchema.getLabel(schema, obj);
+  }
+};
+
+/**
+ * JSON representation of an object.
+ */
+export type JSON = EchoSchema.ObjectJSON;
+
+/**
+ * Converts object to it's JSON representation.
+ *
+ * The same algorithm is used when calling the standard `JSON.stringify(obj)` function.
+ */
+export const toJSON = (obj: Any): JSON => EchoSchema.objectToJSON(obj);
+
+/**
+ * Creates an object from it's json representation.
+ * Performs schema validation.
+ * References and schema will be resolvable if the `refResolver` is provided.
+ *
+ * The function need to be async to support resolving the schema as well as the relation endpoints.
+ */
+export const fromJSON: (json: unknown, options?: { refResolver?: Ref.Resolver }) => Promise<Any> =
+  EchoSchema.objectFromJSON;

package/src/Ref.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as EchoSchema from '@dxos/echo-schema';
+
+import type * as Obj from './Obj';
+
+export type Any = EchoSchema.Ref<Obj.Any>;
+
+export const make = EchoSchema.Ref.make;
+
+export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+
+// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
+export const fromDXN = EchoSchema.Ref.fromDXN;
+
+/**
+ * Extract reference target.
+ */
+export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+
+/**
+ * Reference resolver.
+ */
+export type Resolver = EchoSchema.RefResolver;

package/src/Relation.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as EchoSchema from '@dxos/echo-schema';
+import { assertArgument, invariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+import * as LiveObject from '@dxos/live-object';
+import { assumeType } from '@dxos/util';
+
+export type Any = EchoSchema.AnyEchoObject & EchoSchema.RelationSourceTargetRefs;
+
+export const Source = EchoSchema.RelationSourceId;
+export const Target = EchoSchema.RelationTargetId;
+
+export const make = LiveObject.live;
+
+export const isRelation = (value: unknown): value is Any => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  if (EchoSchema.ATTR_RELATION_SOURCE in value || EchoSchema.ATTR_RELATION_TARGET in value) {
+    return true;
+  }
+
+  const kind = (value as any)[EchoSchema.EntityKindId];
+  return kind === EchoSchema.EntityKind.Relation;
+};
+
+/**
+ * @returns Relation source DXN.
+ * @throws If the object is not a relation.
+ */
+export const getSourceDXN = (value: Any): DXN => {
+  assertArgument(isRelation(value), 'Expected a relation');
+  assumeType<EchoSchema.InternalObjectProps>(value);
+  const dxn = value[EchoSchema.RelationSourceDXNId];
+  invariant(dxn instanceof DXN);
+  return dxn;
+};
+
+/**
+ * @returns Relation target DXN.
+ * @throws If the object is not a relation.
+ */
+export const getTargetDXN = (value: Any): DXN => {
+  assertArgument(isRelation(value), 'Expected a relation');
+  assumeType<EchoSchema.InternalObjectProps>(value);
+  const dxn = value[EchoSchema.RelationTargetDXNId];
+  invariant(dxn instanceof DXN);
+  return dxn;
+};
+
+/**
+ * @returns Relation source.
+ * @throws If the object is not a relation.
+ */
+export const getSource = <T extends Any>(relation: T): EchoSchema.RelationSource<T> => {
+  assertArgument(isRelation(relation), 'Expected a relation');
+  const obj = relation[EchoSchema.RelationSourceId];
+  invariant(obj !== undefined, `Invalid source: ${relation.id}`);
+  return obj;
+};
+
+/**
+ * @returns Relation target.
+ * @throws If the object is not a relation.
+ */
+export const getTarget = <T extends Any>(relation: T): EchoSchema.RelationTarget<T> => {
+  assertArgument(isRelation(relation), 'Expected a relation');
+  const obj = relation[EchoSchema.RelationTargetId];
+  invariant(obj !== undefined, `Invalid target: ${relation.id}`);
+  return obj;
+};