@dxos/echo 0.8.4-main.e098934 → 0.8.4-main.ead640a

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.e098934",
+  "version": "0.8.4-main.ead640a",
   "description": "ECHO API",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "info@dxos.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -39,9 +39,21 @@
       "browser": "./dist/lib/browser/Ref.mjs",
       "node": "./dist/lib/node-esm/Ref.mjs"
     },
+    "./internal": {
+      "source": "./src/internal/index.ts",
+      "types": "./dist/types/src/internal/index.d.ts",
+      "browser": "./dist/lib/browser/internal/index.mjs",
+      "node": "./dist/lib/node-esm/internal/index.mjs"
+    },
+    "./query": {
+      "source": "./src/query/index.ts",
+      "types": "./dist/types/src/query/index.d.ts",
+      "browser": "./dist/lib/browser/query/index.mjs",
+      "node": "./dist/lib/node-esm/query/index.mjs"
+    },
     "./testing": {
-      "source": "./src/testing/types.ts",
-      "types": "./dist/types/src/testing/types.d.ts",
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
       "browser": "./dist/lib/browser/testing/index.mjs",
       "node": "./dist/lib/node-esm/testing/index.mjs"
     }
@@ -71,20 +83,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.9.0",
-    "effect": "3.17.7",
-    "@dxos/debug": "0.8.4-main.e098934",
-    "@dxos/echo-protocol": "0.8.4-main.e098934",
-    "@dxos/echo-schema": "0.8.4-main.e098934",
-    "@dxos/echo-signals": "0.8.4-main.e098934",
-    "@dxos/errors": "0.8.4-main.e098934",
-    "@dxos/effect": "0.8.4-main.e098934",
-    "@dxos/keys": "0.8.4-main.e098934",
-    "@dxos/live-object": "0.8.4-main.e098934",
-    "@dxos/log": "0.8.4-main.e098934",
-    "@dxos/node-std": "0.8.4-main.e098934",
-    "@dxos/util": "0.8.4-main.e098934",
-    "@dxos/invariant": "0.8.4-main.e098934"
+    "@preact/signals-core": "^1.12.1",
+    "effect": "3.18.3",
+    "@dxos/debug": "0.8.4-main.ead640a",
+    "@dxos/echo-protocol": "0.8.4-main.ead640a",
+    "@dxos/echo-signals": "0.8.4-main.ead640a",
+    "@dxos/effect": "0.8.4-main.ead640a",
+    "@dxos/errors": "0.8.4-main.ead640a",
+    "@dxos/invariant": "0.8.4-main.ead640a",
+    "@dxos/live-object": "0.8.4-main.ead640a",
+    "@dxos/log": "0.8.4-main.ead640a",
+    "@dxos/keys": "0.8.4-main.ead640a",
+    "@dxos/node-std": "0.8.4-main.ead640a",
+    "@dxos/util": "0.8.4-main.ead640a"
   },
   "publishConfig": {
     "access": "public"

package/src/Obj.ts

@@ -2,19 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
-import { dual } from 'effect/Function';
+import * as Function from 'effect/Function';
+import * as Schema from 'effect/Schema';
 
-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 { live } from '@dxos/live-object';
 import { assumeType, deepMapValues } from '@dxos/util';
 
+import { live } from './internal';
+import * as EchoSchema from './internal';
 import type * as Ref from './Ref';
 import type * as Relation from './Relation';
-import type * as Type from './Type';
+import * as Type from './Type';
 
 /**
  * NOTE: Don't export: Obj.Any and Obj.Obj form the public API.
@@ -28,9 +28,27 @@ export type Obj<Props> = BaseObj & Props;
 
 /**
  * Base type for all ECHO objects.
+ * This type does not define any properties.
  */
 export interface Any extends BaseObj {}
 
+/**
+ * Object with arbitrary properties.
+ *
+ * NOTE: Due to how typescript works, this type is not assignable to a specific schema type.
+ * In that case, use `Obj.instanceOf` to check if an object is of a specific type.
+ */
+export interface AnyProps extends BaseObj {
+  [key: string]: any;
+}
+
+export const Any = Schema.Struct({}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/types/Any',
+    version: '0.1.0',
+  }),
+);
+
 type Props<T = any> = { id?: EchoSchema.ObjectId } & Type.Properties<T>;
 
 export type MakeProps<T extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type<T>>> & {
@@ -39,7 +57,9 @@ export type MakeProps<T extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type
 
 export const Meta: unique symbol = EchoSchema.MetaId as any;
 
-// TODO(dmaretskyi): Expose Meta = EchoSchema.MetaId.
+const DEFAULT_META: EchoSchema.ObjectMeta = {
+  keys: [],
+};
 
 /**
  * Creates new object.
@@ -57,7 +77,7 @@ export const Meta: unique symbol = EchoSchema.MetaId as any;
 export const make = <S extends Type.Obj.Any>(
   schema: S,
   props: MakeProps<S>,
-  meta?: EchoSchema.ObjectMeta,
+  meta?: Partial<EchoSchema.ObjectMeta>,
 ): LiveObject.Live<Schema.Schema.Type<S>> => {
   assertArgument(
     EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Object,
@@ -66,11 +86,14 @@ export const make = <S extends Type.Obj.Any>(
   );
 
   if (props[EchoSchema.MetaId] != null) {
-    meta = props[EchoSchema.MetaId] as any;
+    // Set default fields on meta on creation.
+    meta = { ...structuredClone(DEFAULT_META), ...props[EchoSchema.MetaId] };
     delete props[EchoSchema.MetaId];
   }
 
-  return live<Schema.Schema.Type<S>>(schema, props as any, meta);
+  const filterUndefined = Object.fromEntries(Object.entries(props).filter(([_, v]) => v !== undefined));
+
+  return live<Schema.Schema.Type<S>>(schema, filterUndefined as any, { keys: [], ...meta });
 };
 
 export const isObject = (obj: unknown): obj is Any => {
@@ -86,7 +109,7 @@ export const isObject = (obj: unknown): obj is Any => {
  * const johnIsPerson = Obj.instanceOf(Person)(john);
  *
  * const isPerson = Obj.instanceOf(Person);
- * if(isPerson(john)) {
+ * if (isPerson(john)) {
  *   // john is Person
  * }
  * ```
@@ -148,7 +171,7 @@ export const getMeta = (obj: Any | Relation.Any): EchoSchema.ObjectMeta => {
 export const getKeys: {
   (obj: Any | Relation.Any, source: string): EchoSchema.ForeignKey[];
   (source: string): (obj: Any | Relation.Any) => EchoSchema.ForeignKey[];
-} = dual(2, (obj: Any | Relation.Any, source?: string): EchoSchema.ForeignKey[] => {
+} = Function.dual(2, (obj: Any | Relation.Any, source?: string): EchoSchema.ForeignKey[] => {
   const meta = EchoSchema.getMeta(obj);
   invariant(meta != null, 'Invalid object.');
   return meta.keys.filter((key) => key.source === source);
@@ -176,7 +199,6 @@ export const isDeleted = (obj: Any | Relation.Any): boolean => {
   return deleted;
 };
 
-// TODO(burdon): Rename "label"
 export const getLabel = (obj: Any | Relation.Any): string | undefined => {
   const schema = getSchema(obj);
   if (schema != null) {
@@ -191,6 +213,49 @@ export const setLabel = (obj: Any | Relation.Any, label: string) => {
   }
 };
 
+export const getDescription = (obj: Any | Relation.Any): string | undefined => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    return EchoSchema.getDescription(schema, obj);
+  }
+};
+
+export const setDescription = (obj: Any | Relation.Any, description: string) => {
+  const schema = getSchema(obj);
+  if (schema != null) {
+    EchoSchema.setDescription(schema, obj, description);
+  }
+};
+
+const compare = (a?: string, b?: string) => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+
+  if (b == null) {
+    return -1;
+  }
+
+  return a.localeCompare(b);
+};
+
+export type Comparator = (a: Any, b: Any) => number;
+
+export const sortByLabel: Comparator = (a: Any, b: Any) => compare(getLabel(a), getLabel(b));
+export const sortByTypename: Comparator = (a: Any, b: Any) => compare(getTypename(a), getTypename(b));
+export const sort = (...comparators: Comparator[]): Comparator => {
+  return (a: Any, b: Any) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+
+    return 0;
+  };
+};
+
 /**
  * JSON representation of an object.
  */

package/src/Ref.ts

@@ -2,8 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from '@dxos/echo-schema';
-
+import * as EchoSchema from './internal';
 import type * as Obj from './Obj';
 
 export type Ref<T> = EchoSchema.Ref<T>;

package/src/Relation.ts

@@ -2,17 +2,18 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
-import * as EchoSchema from '@dxos/echo-schema';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
-import { type Live, live } from '@dxos/live-object';
+import { type Live } from '@dxos/live-object';
 import { assumeType } from '@dxos/util';
 
-import type * as Obj from './Obj';
-import type * as Type from './Type';
+import { live } from './internal';
+import * as EchoSchema from './internal';
+import * as Obj from './Obj';
+import * as Type from './Type';
 
 /**
  * NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
@@ -32,6 +33,15 @@ export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = Ba
  */
 export interface Any extends BaseRelation<Obj.Any, Obj.Any> {}
 
+export const Any = Schema.Struct({}).pipe(
+  Type.Relation({
+    typename: 'dxos.org/types/Any',
+    version: '0.1.0',
+    source: Obj.Any,
+    target: Obj.Any,
+  }),
+);
+
 // TODO(dmaretskyi): Has to be `unique symbol`.
 export const Source: unique symbol = EchoSchema.RelationSourceId as any;
 export type Source = typeof Source;

package/src/Type.ts

@@ -2,15 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
-import { type Simplify } from 'effect/Schema';
+import type * as EffectSchema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
-import * as EchoSchema from '@dxos/echo-schema';
-import { type ToMutable } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import type * as Keys from '@dxos/keys';
 
+import { type ToMutable } from './internal';
+import * as EchoSchema from './internal';
 import type * as RelationModule from './Relation';
 
 //
@@ -55,33 +54,33 @@ interface ObjJsonProps {
  * This typedef avoids `TS4023` error (name from external module cannot be used named).
  * See Effect's note on interface types.
  */
-export interface obj<Self extends Schema.Schema.Any>
+export interface obj<Self extends EffectSchema.Schema.Any>
   extends EchoSchema.TypeMeta,
-    Schema.AnnotableClass<
+    EffectSchema.AnnotableClass<
       obj<Self>,
-      OfKind<EchoSchema.EntityKind.Object> & ToMutable<Schema.Schema.Type<Self>>,
-      Simplify<ObjJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
-      Schema.Schema.Context<Self>
+      OfKind<EchoSchema.EntityKind.Object> & ToMutable<EffectSchema.Schema.Type<Self>>,
+      EffectSchema.Simplify<ObjJsonProps & ToMutable<EffectSchema.Schema.Encoded<Self>>>,
+      EffectSchema.Schema.Context<Self>
     > {}
 
 /**
  * Object schema.
  */
 export const Obj: {
-  (opts: EchoSchema.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => obj<Self>;
+  (opts: EchoSchema.TypeMeta): <Self extends EffectSchema.Schema.Any>(self: Self) => obj<Self>;
 } = EchoSchema.EchoObject as any;
 
 /**
  * Object schema type definitions.
  */
-export namespace Obj {
+export declare namespace Obj {
   /**
    * Type that represents an arbitrary schema type of an object.
    * NOTE: This is not an instance type.
    */
   // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
   // TODO(burdon): This erases the ECHO type info (e.g., id, typename).
-  export type Any = Schema.Schema.AnyNoContext;
+  export type Any = EffectSchema.Schema.AnyNoContext;
 }
 
 //
@@ -93,9 +92,9 @@ export interface Expando extends OfKind<EchoSchema.EntityKind.Object> {
   [key: string]: any;
 }
 
-type ExpandoEncoded = Simplify<ObjJsonProps & { [key: string]: any }>;
+type ExpandoEncoded = EffectSchema.Simplify<ObjJsonProps & { [key: string]: any }>;
 
-export const Expando: Schema.Schema<Expando, ExpandoEncoded, never> = EchoSchema.Expando as any;
+export const Expando: EffectSchema.Schema<Expando, ExpandoEncoded, never> = EchoSchema.Expando as any;
 
 //
 // Relation
@@ -114,17 +113,17 @@ interface RelationJsonProps {
  * See Effect's note on interface types.
  */
 export interface relation<
-  Self extends Schema.Schema.Any,
-  SourceSchema extends Schema.Schema.Any,
-  TargetSchema extends Schema.Schema.Any,
+  Self extends EffectSchema.Schema.Any,
+  SourceSchema extends EffectSchema.Schema.Any,
+  TargetSchema extends EffectSchema.Schema.Any,
 > extends EchoSchema.TypeMeta,
-    Schema.AnnotableClass<
+    EffectSchema.AnnotableClass<
       relation<Self, SourceSchema, TargetSchema>,
       OfKind<EchoSchema.EntityKind.Relation> &
-        Relation.Endpoints<Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>> &
-        ToMutable<Schema.Schema.Type<Self>>,
-      Simplify<RelationJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
-      Schema.Schema.Context<Self>
+        Relation.Endpoints<EffectSchema.Schema.Type<SourceSchema>, EffectSchema.Schema.Type<TargetSchema>> &
+        ToMutable<EffectSchema.Schema.Type<Self>>,
+      EffectSchema.Simplify<RelationJsonProps & ToMutable<EffectSchema.Schema.Encoded<Self>>>,
+      EffectSchema.Schema.Context<Self>
     > {}
 
 /**
@@ -132,9 +131,9 @@ export interface relation<
  */
 // TODO(dmaretskyi): I have to redefine the type here so that the definition uses symbols from @dxos/echo/Relation.
 export const Relation: {
-  <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(
+  <Source extends EffectSchema.Schema.AnyNoContext, Target extends EffectSchema.Schema.AnyNoContext>(
     opts: EchoSchema.EchoRelationOptions<Source, Target>,
-  ): <Self extends Schema.Schema.Any>(self: Self) => relation<Self, Source, Target>;
+  ): <Self extends EffectSchema.Schema.Any>(self: Self) => relation<Self, Source, Target>;
 } = EchoSchema.EchoRelation as any;
 
 /**
@@ -146,7 +145,7 @@ export namespace Relation {
    * NOTE: This is not an instance type.
    */
   // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  export type Any = Schema.Schema.AnyNoContext;
+  export type Any = EffectSchema.Schema.AnyNoContext;
 
   /**
    * Get relation source type.
@@ -174,15 +173,15 @@ export namespace Relation {
  * This typedef avoids `TS4023` error (name from external module cannot be used named).
  * See Effect's note on interface types.
  */
-export interface ref<TargetSchema extends Schema.Schema.Any>
-  extends EchoSchema.Ref$<Schema.Schema.Type<TargetSchema>> {}
+export interface ref<TargetSchema extends EffectSchema.Schema.Any>
+  extends EchoSchema.Ref$<EffectSchema.Schema.Type<TargetSchema>> {}
 
 /**
  * Ref schema.
  */
 export const Ref: <S extends Obj.Any>(schema: S) => ref<S> = EchoSchema.Ref;
 
-export interface Ref<T> extends Schema.SchemaClass<EchoSchema.Ref<T>, EncodedReference> {}
+export interface Ref<T> extends EffectSchema.SchemaClass<EchoSchema.Ref<T>, EncodedReference> {}
 
 // TODO(buurdon): Move to Ref?
 export namespace Ref {
@@ -190,7 +189,7 @@ export namespace Ref {
    * Type that represents an arbitrary schema type of a reference.
    * NOTE: This is not an instance type.
    */
-  export type Any = Schema.Schema<EchoSchema.Ref<any>, EncodedReference>;
+  export type Any = EffectSchema.Schema<EchoSchema.Ref<any>, EncodedReference>;
 }
 
 /**
@@ -243,4 +242,4 @@ export const getMeta = (schema: Obj.Any | Relation.Any): Meta | undefined => {
 // TODO(dmaretskyi): Remove re-exports.
 export { SpaceId, ObjectId, DXN } from '@dxos/keys';
 
-export { Format, JsonSchemaType as JsonSchema, toEffectSchema, toJsonSchema } from '@dxos/echo-schema';
+export { Format, JsonSchemaType as JsonSchema, toEffectSchema, toJsonSchema } from './internal';

package/src/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './errors';
+export * from './query';
 
 export * as Key from './Key';
 export * as Obj from './Obj';
@@ -10,7 +11,6 @@ export * as Ref from './Ref';
 export * as Relation from './Relation';
 export * as Type from './Type';
 
-export { DXN } from '@dxos/keys';
-export { Filter, Order, Query } from './query';
 export { QueryAST } from '@dxos/echo-protocol';
+export { DXN } from '@dxos/keys';
 export { type Live } from '@dxos/live-object';

package/src/internal/ast/annotation-helper.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+export interface AnnotationHelper<T> {
+  get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
+}
+
+export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
+  return {
+    get: (schema) => SchemaAST.getAnnotation(schema.ast, id),
+    set:
+      (value) =>
+      <S extends Schema.Schema.Any>(schema: S) =>
+        schema.annotations({ [id]: value }) as S,
+  };
+};

package/src/internal/ast/annotations.test.ts

@@ -0,0 +1,98 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { EchoObject, getLabel } from '../object';
+
+import { LabelAnnotation, SchemaVersion, Typename } from './annotations';
+
+// TODO(dmaretskyi): Use one of the testing schemas.
+const TestObject = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  fallbackName: Schema.optional(Schema.String),
+  other: Schema.String,
+}).pipe(LabelAnnotation.set(['name', 'fallbackName']));
+
+const a: Schema.Struct<typeof TestObject.fields> = TestObject;
+console.log(a);
+
+type TestObject = Schema.Schema.Type<typeof TestObject>;
+
+const TestEchoSchema = TestObject.pipe(
+  EchoObject({
+    typename: 'dxos.org/type/Test',
+    version: '0.1.0',
+  }),
+);
+type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
+
+describe('annotations', () => {
+  describe('Typename', () => {
+    test('should validate typename', ({ expect }) => {
+      // Valid.
+      expect(Typename.make('dxos.org/type/foo')).to.exist;
+      expect(Typename.make('dxos.org/type/foo-bar')).to.exist;
+      expect(Typename.make('dxos.org/type/foo_bar')).to.exist;
+
+      // Invalid.
+      expect(() => Typename.make('dxn:dxos.org')).to.throw();
+      expect(() => Typename.make('2dxos.org')).to.throw();
+      expect(() => Typename.make('dxos org')).to.throw();
+    });
+
+    test('should validate version', ({ expect }) => {
+      // Valid.
+      expect(SchemaVersion.make('0.1.0')).to.exist;
+
+      // Invalid.
+      expect(() => SchemaVersion.make('0.1.x')).to.throw();
+      expect(() => SchemaVersion.make('0.1.0-alpha')).to.throw();
+    });
+  });
+
+  describe('getLabel', () => {
+    test('should return first available label value', ({ expect }) => {
+      const obj: TestObject = {
+        name: 'Primary Name',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabel(TestObject, obj)).toEqual('Primary Name');
+    });
+
+    test('should fallback to second path if first is undefined', ({ expect }) => {
+      const obj: TestObject = {
+        name: undefined,
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabel(TestObject, obj)).toEqual('Fallback Name');
+    });
+
+    test('should return undefined if no label paths resolve', ({ expect }) => {
+      const obj: TestObject = {
+        name: undefined,
+        fallbackName: undefined,
+        other: 'Other',
+      };
+
+      expect(getLabel(TestObject, obj)).toBeUndefined();
+    });
+
+    test('should return label from echo object', ({ expect }) => {
+      const obj: TestEchoSchema = {
+        id: 'test',
+        name: 'Primary Name',
+        fallbackName: 'Fallback Name',
+        other: 'Other',
+      };
+
+      expect(getLabel(TestEchoSchema, obj)).toEqual('Primary Name');
+    });
+  });
+});