@dxos/echo 0.8.3-main.672df60 → 0.8.3-staging.0fa589b

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

@@ -0,0 +1,113 @@
+import { Schema } from 'effect';
+import { Type } from '..';
+export declare namespace Testing {
+    const _Contact: Type.obj<Schema.SchemaClass<{
+        readonly name?: string | undefined;
+        readonly email?: string | undefined;
+        readonly username?: string | undefined;
+        readonly tasks?: import("@dxos/echo-schema").Ref<Task>[] | undefined;
+        readonly address?: {
+            readonly city?: string | undefined;
+            readonly state?: string | undefined;
+            readonly zip?: string | undefined;
+            readonly coordinates: {
+                readonly lat?: number | undefined;
+                readonly lng?: number | undefined;
+            };
+        } | undefined;
+    }, {
+        readonly name?: string | undefined;
+        readonly email?: string | undefined;
+        readonly username?: string | undefined;
+        readonly tasks?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+        readonly address?: {
+            readonly coordinates: {
+                readonly lat?: number | undefined;
+                readonly lng?: number | undefined;
+            };
+            readonly city?: string | undefined;
+            readonly state?: string | undefined;
+            readonly zip?: string | undefined;
+        } | undefined;
+    }, never>>;
+    export interface Contact extends Schema.Schema.Type<typeof _Contact> {
+    }
+    export const Contact: Schema.Schema<Contact, Schema.Schema.Encoded<typeof _Contact>, never>;
+    const _Task: Type.obj<Schema.SchemaClass<{
+        readonly description?: string | undefined;
+        readonly title?: string | undefined;
+        readonly assignee?: import("@dxos/echo-schema").Ref<Contact> | undefined;
+        readonly completed?: boolean | undefined;
+        readonly previous?: import("@dxos/echo-schema").Ref<Task> | undefined;
+        readonly subTasks?: import("@dxos/echo-schema").Ref<Task>[] | undefined;
+    }, {
+        readonly description?: string | undefined;
+        readonly title?: string | undefined;
+        readonly assignee?: import("@dxos/echo-protocol").EncodedReference | undefined;
+        readonly completed?: boolean | undefined;
+        readonly previous?: import("@dxos/echo-protocol").EncodedReference | undefined;
+        readonly subTasks?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+    }, never>>;
+    export interface Task extends Schema.Schema.Type<typeof _Task> {
+    }
+    export const Task: Schema.Schema<Task, Schema.Schema.Encoded<typeof _Task>, never>;
+    export enum RecordType {
+        UNDEFINED = 0,
+        PERSONAL = 1,
+        WORK = 2
+    }
+    export const Container: Type.obj<Schema.SchemaClass<{
+        readonly records?: {
+            readonly type?: RecordType | undefined;
+            readonly description?: string | undefined;
+            readonly title?: string | undefined;
+            readonly contacts?: import("@dxos/echo-schema").Ref<Contact>[] | undefined;
+        }[] | undefined;
+        readonly objects?: import("@dxos/echo-schema").Ref<Type.Expando>[] | undefined;
+    }, {
+        readonly records?: {
+            readonly type?: RecordType | undefined;
+            readonly description?: string | undefined;
+            readonly title?: string | undefined;
+            readonly contacts?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+        }[] | undefined;
+        readonly objects?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+    }, never>>;
+    export const WorksFor: Type.relation<Schema.Struct<{
+        since: Schema.optional<typeof Schema.String>;
+    }>, Schema.Schema<Contact, {
+        id: string;
+        name?: string | undefined;
+        email?: string | undefined;
+        username?: string | undefined;
+        tasks?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+        address?: {
+            readonly coordinates: {
+                readonly lat?: number | undefined;
+                readonly lng?: number | undefined;
+            };
+            readonly city?: string | undefined;
+            readonly state?: string | undefined;
+            readonly zip?: string | undefined;
+        } | undefined;
+    }, never>, Schema.Schema<Contact, {
+        id: string;
+        name?: string | undefined;
+        email?: string | undefined;
+        username?: string | undefined;
+        tasks?: import("@dxos/echo-protocol").EncodedReference[] | undefined;
+        address?: {
+            readonly coordinates: {
+                readonly lat?: number | undefined;
+                readonly lng?: number | undefined;
+            };
+            readonly city?: string | undefined;
+            readonly state?: string | undefined;
+            readonly zip?: string | undefined;
+        } | undefined;
+    }, never>>;
+    export interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {
+    }
+    export {};
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/testing/types.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAG1B,yBAAiB,OAAO,CAAC;IACvB,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAoBb,CAAC;IACF,MAAM,WAAW,OAAQ,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC;KAAG;IACvE,MAAM,CAAC,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,QAAQ,CAAC,EAAE,KAAK,CAAY,CAAC;IAEvG,MAAM,KAAK;;;;;;;;;;;;;;cAaV,CAAC;IACF,MAAM,WAAW,IAAK,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC;KAAG;IACjE,MAAM,CAAC,MAAM,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,CAAC,EAAE,KAAK,CAAS,CAAC;IAE3F,MAAM,MAAM,UAAU;QACpB,SAAS,IAAI;QACb,QAAQ,IAAI;QACZ,IAAI,IAAI;KACT;IAED,MAAM,CAAC,MAAM,SAAS;;;;;;;;;;;;;;;;cAoBrB,CAAC;IAEF,MAAM,CAAC,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cASpB,CAAC;IACF,MAAM,WAAW,QAAS,SAAQ,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC;KAAG;;CACzE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.3-main.672df60",
+  "version": "0.8.3-staging.0fa589b",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -13,9 +13,53 @@
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./Type": {
+      "types": "./dist/types/src/Type.d.ts",
+      "browser": "./dist/lib/browser/Type.mjs",
+      "node": "./dist/lib/node-esm/Type.mjs"
+    },
+    "./Obj": {
+      "types": "./dist/types/src/Obj.d.ts",
+      "browser": "./dist/lib/browser/Obj.mjs",
+      "node": "./dist/lib/node-esm/Obj.mjs"
+    },
+    "./Relation": {
+      "types": "./dist/types/src/Relation.d.ts",
+      "browser": "./dist/lib/browser/Relation.mjs",
+      "node": "./dist/lib/node-esm/Relation.mjs"
+    },
+    "./Ref": {
+      "types": "./dist/types/src/Ref.d.ts",
+      "browser": "./dist/lib/browser/Ref.mjs",
+      "node": "./dist/lib/node-esm/Ref.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/types.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "Type": [
+        "dist/types/src/Type.d.ts"
+      ],
+      "Obj": [
+        "dist/types/src/Obj.d.ts"
+      ],
+      "Relation": [
+        "dist/types/src/Relation.d.ts"
+      ],
+      "Ref": [
+        "dist/types/src/Ref.d.ts"
+      ],
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ]
+    }
+  },
   "files": [
     "dist",
     "src"
@@ -23,17 +67,17 @@
   "dependencies": {
     "@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"
+    "@dxos/debug": "0.8.3-staging.0fa589b",
+    "@dxos/echo-protocol": "0.8.3-staging.0fa589b",
+    "@dxos/echo-schema": "0.8.3-staging.0fa589b",
+    "@dxos/effect": "0.8.3-staging.0fa589b",
+    "@dxos/echo-signals": "0.8.3-staging.0fa589b",
+    "@dxos/invariant": "0.8.3-staging.0fa589b",
+    "@dxos/keys": "0.8.3-staging.0fa589b",
+    "@dxos/live-object": "0.8.3-staging.0fa589b",
+    "@dxos/log": "0.8.3-staging.0fa589b",
+    "@dxos/node-std": "0.8.3-staging.0fa589b",
+    "@dxos/util": "0.8.3-staging.0fa589b"
   },
   "publishConfig": {
     "access": "public"

package/src/Key.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { SpaceId, ObjectId } from '@dxos/keys';

package/src/Obj.ts

@@ -6,34 +6,80 @@ 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 DXN } from '@dxos/keys';
+import type * as LiveObject from '@dxos/live-object';
+import { live } from '@dxos/live-object';
+import { assumeType } from '@dxos/util';
 
 import type * as Ref from './Ref';
+import type * as Relation from './Relation';
 import type * as Type from './Type';
 
-export type Any = EchoSchema.AnyEchoObject;
+// NOTE: Don't export: Obj.Any and Obj.Obj form the public API.
+interface ObjBase extends Type.OfKind<EchoSchema.EntityKind.Object> {
+  readonly id: EchoSchema.ObjectId;
+}
 
-export const make = LiveObject.live;
+/**
+ * Object type with specific properties.
+ */
+export type Obj<Props> = ObjBase & Props;
+
+/**
+ * Base type for all ECHO objects.
+ */
+export interface Any extends ObjBase {}
+
+type MakeProps<T> = {
+  id?: EchoSchema.ObjectId;
+} & Type.Properties<T>;
+
+/**
+ * Creates new object.
+ */
+// TODO(dmaretskyi): Move meta into props.
+export const make = <S extends Type.Obj.Any>(
+  schema: S,
+  props: NoInfer<MakeProps<Schema.Schema.Type<S>>>,
+  meta?: EchoSchema.ObjectMeta,
+): LiveObject.Live<Schema.Schema.Type<S>> => {
+  assertArgument(
+    EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Object,
+    'Expected an object schema',
+  );
+
+  if (props[EchoSchema.MetaId] != null) {
+    meta = props[EchoSchema.MetaId] as any;
+    delete props[EchoSchema.MetaId];
+  }
+
+  return live<Schema.Schema.Type<S>>(schema, props as any, meta);
+};
 
-// TODO(dmaretskyi): Currently broken
 export const isObject = (obj: unknown): obj is Any => {
-  return LiveObject.isLiveObject(obj);
+  assumeType<EchoSchema.InternalObjectProps>(obj);
+  return typeof obj === 'object' && obj !== null && obj[EchoSchema.EntityKindId] === EchoSchema.EntityKind.Object;
 };
 
 /**
- * Check that object or relation is an instance of a schema.
+ * Test if object or relation is an instance of a schema.
  * @example
  * ```ts
- * const person = Obj.make(Person, { name: 'John' });
+ * const john = Obj.make(Person, { name: 'John' });
+ * const johnIsPerson = Obj.instanceOf(Person)(john);
+ *
  * const isPerson = Obj.instanceOf(Person);
- * isPerson(person); // true
+ * if(isPerson(john)) {
+ *   // john is Person
+ * }
  * ```
  */
 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[]) => {
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S): (value: unknown) => value is Schema.Schema.Type<S>;
+  <S extends Type.Relation.Any | Type.Obj.Any>(schema: S, value: unknown): value is Schema.Schema.Type<S>;
+} = ((
+  ...args: [schema: Type.Relation.Any | Type.Obj.Any, value: unknown] | [schema: Type.Relation.Any | Type.Obj.Any]
+) => {
   if (args.length === 1) {
     return (obj: unknown) => EchoSchema.isInstanceOf(args[0], obj);
   }
@@ -55,12 +101,8 @@ export const getDXN = (obj: Any): 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;
-};
+// TODO(burdon): Expando does not have a type.
+export const getTypeDXN = EchoSchema.getType;
 
 /**
  * @returns The typename of the object's type.
@@ -70,7 +112,7 @@ 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.getType(obj)?.asTypeDXN()?.type;
   }
 
   return EchoSchema.getSchemaTypename(schema);
@@ -103,18 +145,17 @@ export const getLabel = (obj: Any): string | undefined => {
 export type JSON = EchoSchema.ObjectJSON;
 
 /**
- * Converts object to it's JSON representation.
+ * Converts object to its JSON representation.
  *
  * The same algorithm is used when calling the standard `JSON.stringify(obj)` function.
  */
-export const toJSON = (obj: Any): JSON => EchoSchema.objectToJSON(obj);
+export const toJSON = (obj: Any | Relation.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.
+ * Creates an object from its json representation, performing schema validation.
+ * References and schemas 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;
+  EchoSchema.objectFromJSON as any;

package/src/Ref.ts

@@ -6,14 +6,10 @@ import * as EchoSchema from '@dxos/echo-schema';
 
 import type * as Obj from './Obj';
 
+export type Ref<T> = EchoSchema.Ref<T>;
 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;
+export const Array = EchoSchema.RefArray;
 
 /**
  * Extract reference target.
@@ -24,3 +20,10 @@ export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : neve
  * Reference resolver.
  */
 export type Resolver = EchoSchema.RefResolver;
+
+export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+
+export const make = EchoSchema.Ref.make;
+
+// TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
+export const fromDXN = EchoSchema.Ref.fromDXN;

package/src/Relation.ts

@@ -2,18 +2,78 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type Schema } from 'effect';
+
+import { raise } from '@dxos/debug';
 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 { type Live, live } from '@dxos/live-object';
 import { assumeType } from '@dxos/util';
 
-export type Any = EchoSchema.AnyEchoObject & EchoSchema.RelationSourceTargetRefs;
+import type * as Obj from './Obj';
+import type * as Type from './Type';
+
+// NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
+interface RelationBase<Source, Target>
+  extends Type.Relation.Endpoints<Source, Target>,
+    Type.OfKind<EchoSchema.EntityKind.Relation> {
+  readonly id: EchoSchema.ObjectId;
+}
+
+/**
+ * Relation type with specific properties.
+ */
+export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = RelationBase<Source, Target> & Props;
+
+/**
+ * Base type for all ECHO relations.
+ */
+export interface Any extends RelationBase<Obj.Any, Obj.Any> {}
+
+// TODO(dmaretskyi): Has to be `unique symbol`.
+export const Source: unique symbol = EchoSchema.RelationSourceId as any;
+export type Source = typeof Source;
+export const Target: unique symbol = EchoSchema.RelationTargetId as any;
+export type Target = typeof Target;
+
+type MakeProps<T extends Any> = {
+  id?: EchoSchema.ObjectId;
+  [Source]: T[Source];
+  [Target]: T[Target];
+} & Type.Properties<T>;
+
+/**
+ * Creates new relation.
+ * @param schema - Relation schema.
+ * @param props - Relation properties. Endpoints are passed as [Relation.Source] and [Relation.Target] keys.
+ * @param meta - Relation metadata.
+ * @returns
+ */
+// NOTE: Writing the definition this way (with generic over schema) makes typescript perfer to infer the type from the first param (this schema) rather than the second param (the props).
+// TODO(dmaretskyi): Move meta into props.
+export const make = <S extends Type.Relation.Any>(
+  schema: S,
+  props: NoInfer<MakeProps<Schema.Schema.Type<S>>>,
+  meta?: EchoSchema.ObjectMeta,
+): Live<Schema.Schema.Type<S> & Type.OfKind<EchoSchema.EntityKind.Relation>> => {
+  assertArgument(
+    EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Relation,
+    'Expected a relation schema',
+  );
+
+  if (props[EchoSchema.MetaId] != null) {
+    meta = props[EchoSchema.MetaId] as any;
+    delete props[EchoSchema.MetaId];
+  }
 
-export const Source = EchoSchema.RelationSourceId;
-export const Target = EchoSchema.RelationTargetId;
+  const sourceDXN = EchoSchema.getObjectDXN(props[Source]) ?? raise(new Error('Unresolved relation source'));
+  const targetDXN = EchoSchema.getObjectDXN(props[Target]) ?? raise(new Error('Unresolved relation target'));
+  (props as any)[EchoSchema.RelationSourceDXNId] = sourceDXN;
+  (props as any)[EchoSchema.RelationTargetDXNId] = targetDXN;
 
-export const make = LiveObject.live;
+  return live<Schema.Schema.Type<S>>(schema, props as any, meta);
+};
 
 export const isRelation = (value: unknown): value is Any => {
   if (typeof value !== 'object' || value === null) {
@@ -34,7 +94,7 @@ export const isRelation = (value: unknown): value is Any => {
 export const getSourceDXN = (value: Any): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<EchoSchema.InternalObjectProps>(value);
-  const dxn = value[EchoSchema.RelationSourceDXNId];
+  const dxn = (value as EchoSchema.InternalObjectProps)[EchoSchema.RelationSourceDXNId];
   invariant(dxn instanceof DXN);
   return dxn;
 };
@@ -46,7 +106,7 @@ export const getSourceDXN = (value: Any): DXN => {
 export const getTargetDXN = (value: Any): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
   assumeType<EchoSchema.InternalObjectProps>(value);
-  const dxn = value[EchoSchema.RelationTargetDXNId];
+  const dxn = (value as EchoSchema.InternalObjectProps)[EchoSchema.RelationTargetDXNId];
   invariant(dxn instanceof DXN);
   return dxn;
 };
@@ -55,20 +115,22 @@ export const getTargetDXN = (value: Any): DXN => {
  * @returns Relation source.
  * @throws If the object is not a relation.
  */
-export const getSource = <T extends Any>(relation: T): EchoSchema.RelationSource<T> => {
+export const getSource = <T extends Any>(relation: T): Type.Relation.Source<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
-  const obj = relation[EchoSchema.RelationSourceId];
+  assumeType<EchoSchema.InternalObjectProps>(relation);
+  const obj = (relation as EchoSchema.InternalObjectProps)[EchoSchema.RelationSourceId];
   invariant(obj !== undefined, `Invalid source: ${relation.id}`);
-  return obj;
+  return obj as Type.Relation.Source<T>;
 };
 
 /**
  * @returns Relation target.
  * @throws If the object is not a relation.
  */
-export const getTarget = <T extends Any>(relation: T): EchoSchema.RelationTarget<T> => {
+export const getTarget = <T extends Any>(relation: T): Type.Relation.Target<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
-  const obj = relation[EchoSchema.RelationTargetId];
+  assumeType<EchoSchema.InternalObjectProps>(relation);
+  const obj = (relation as EchoSchema.InternalObjectProps)[EchoSchema.RelationTargetId];
   invariant(obj !== undefined, `Invalid target: ${relation.id}`);
-  return obj;
+  return obj as Type.Relation.Target<T>;
 };