@dxos/echo 0.8.4-main.28f8d3d → 0.8.4-main.2c6827d

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dxos/echo",
-  "version": "0.8.4-main.28f8d3d",
+  "version": "0.8.4-main.2c6827d",
   "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,19 +83,19 @@
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.9.0",
-    "effect": "3.17.7",
-    "@dxos/debug": "0.8.4-main.28f8d3d",
-    "@dxos/echo-schema": "0.8.4-main.28f8d3d",
-    "@dxos/echo-signals": "0.8.4-main.28f8d3d",
-    "@dxos/echo-protocol": "0.8.4-main.28f8d3d",
-    "@dxos/invariant": "0.8.4-main.28f8d3d",
-    "@dxos/live-object": "0.8.4-main.28f8d3d",
-    "@dxos/keys": "0.8.4-main.28f8d3d",
-    "@dxos/effect": "0.8.4-main.28f8d3d",
-    "@dxos/log": "0.8.4-main.28f8d3d",
-    "@dxos/node-std": "0.8.4-main.28f8d3d",
-    "@dxos/util": "0.8.4-main.28f8d3d"
+    "@preact/signals-core": "^1.12.1",
+    "effect": "3.18.3",
+    "@dxos/debug": "0.8.4-main.2c6827d",
+    "@dxos/effect": "0.8.4-main.2c6827d",
+    "@dxos/echo-protocol": "0.8.4-main.2c6827d",
+    "@dxos/echo-signals": "0.8.4-main.2c6827d",
+    "@dxos/errors": "0.8.4-main.2c6827d",
+    "@dxos/invariant": "0.8.4-main.2c6827d",
+    "@dxos/keys": "0.8.4-main.2c6827d",
+    "@dxos/log": "0.8.4-main.2c6827d",
+    "@dxos/node-std": "0.8.4-main.2c6827d",
+    "@dxos/util": "0.8.4-main.2c6827d",
+    "@dxos/live-object": "0.8.4-main.2c6827d"
   },
   "publishConfig": {
     "access": "public"

package/src/Obj.ts

@@ -2,18 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+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 type * as LiveObject from '@dxos/live-object';
-import { live } from '@dxos/live-object';
-import { assumeType } from '@dxos/util';
+import * as LiveObject 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.
@@ -27,33 +28,72 @@ 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>>>;
+export type MakeProps<T extends Type.Obj.Any> = NoInfer<Props<Schema.Schema.Type<T>>> & {
+  [Meta]?: Partial<EchoSchema.ObjectMeta>;
+};
+
+export const Meta: unique symbol = EchoSchema.MetaId as any;
+
+const DEFAULT_META: EchoSchema.ObjectMeta = {
+  keys: [],
+};
 
 /**
  * Creates new object.
+ * @param schema - Object schema.
+ * @param props - Object properties.
+ * @param meta - Object metadata (deprecated) -- pass with Obj.Meta.
+ *
+ * Meta can be passed as a symbol in `props`.
+ *
+ * Example:
+ * ```ts
+ * const obj = Obj.make(Person, { [Obj.Meta]: { keys: [...] }, name: 'John' });
+ * ```
  */
-// TODO(dmaretskyi): Move meta into props.
 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,
+    'schema',
     'Expected an object schema',
   );
 
   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 => {
@@ -69,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
  * }
  * ```
@@ -91,7 +131,7 @@ export const getSchema = EchoSchema.getSchema;
 
 // TODO(dmaretskyi): Allow returning undefined.
 export const getDXN = (obj: Any | Relation.Any): DXN => {
-  assertArgument(!Schema.isSchema(obj), 'Object should not be a schema.');
+  assertArgument(!Schema.isSchema(obj), 'obj', 'Object should not be a schema.');
   const dxn = EchoSchema.getObjectDXN(obj);
   invariant(dxn != null, 'Invalid object.');
   return dxn;
@@ -99,14 +139,14 @@ export const getDXN = (obj: Any | Relation.Any): DXN => {
 
 /**
  * @returns The DXN of the object's type.
- * @example dxn:example.com/type/Contact:1.0.0
+ * @example dxn:example.com/type/Person:1.0.0
  */
 // TODO(burdon): Expando does not have a type.
 export const getTypeDXN = EchoSchema.getType;
 
 /**
  * @returns The typename of the object's type.
- * @example `example.com/type/Contact`
+ * @example `example.com/type/Person`
  */
 export const getTypename = (obj: Any | Relation.Any): string | undefined => {
   const schema = getSchema(obj);
@@ -125,6 +165,33 @@ export const getMeta = (obj: Any | Relation.Any): EchoSchema.ObjectMeta => {
   return meta;
 };
 
+/**
+ * @returns Foreign keys for the object from the specified source.
+ */
+export const getKeys: {
+  (obj: Any | Relation.Any, source: string): EchoSchema.ForeignKey[];
+  (source: string): (obj: Any | Relation.Any) => 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);
+});
+
+/**
+ * Delete all keys from the object for the specified source.
+ * @param obj
+ * @param source
+ */
+export const deleteKeys = (obj: Any | Relation.Any, source: string) => {
+  const meta = EchoSchema.getMeta(obj);
+  for (let i = 0; i < meta.keys.length; i++) {
+    if (meta.keys[i].source === source) {
+      meta.keys.splice(i, 1);
+      i--;
+    }
+  }
+};
+
 // TODO(dmaretskyi): Default to `false`.
 export const isDeleted = (obj: Any | Relation.Any): boolean => {
   const deleted = EchoSchema.isDeleted(obj);
@@ -132,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) {
@@ -147,6 +213,68 @@ 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);
+  }
+};
+
+export const addTag = (obj: Any | Relation.Any, tag: string) => {
+  const meta = getMeta(obj);
+  meta.tags ??= [];
+  meta.tags.push(tag);
+};
+
+export const removeTag = (obj: Any | Relation.Any, tag: string) => {
+  const meta = getMeta(obj);
+  if (!meta.tags) {
+    return;
+  }
+  for (let i = 0; i < meta.tags.length; i++) {
+    if (meta.tags[i] === tag) {
+      meta.tags.splice(i, 1);
+      i--;
+    }
+  }
+};
+
+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.
  */
@@ -172,6 +300,11 @@ export const toJSON = (obj: Any | Relation.Any): JSON => EchoSchema.objectToJSON
 export const fromJSON: (json: unknown, options?: { refResolver?: Ref.Resolver; dxn?: DXN }) => Promise<Any> =
   EchoSchema.objectFromJSON as any;
 
+/**
+ * Returns an immutable snapshot of an object.
+ */
+export const getSnapshot: <T extends Any>(obj: Obj<T>) => T = LiveObject.getSnapshot;
+
 export type CloneOptions = {
   /**
    * Retain the original object's ID.
@@ -189,9 +322,110 @@ export const clone = <T extends Any | Relation.Any>(obj: T, opts?: CloneOptions)
   const { id, ...data } = obj;
   const schema = getSchema(obj);
   invariant(schema != null, 'Object should have a schema');
-  const props: any = { ...data };
+  const props: any = deepMapValues(data, (value, recurse) => {
+    if (EchoSchema.Ref.isRef(value)) {
+      return value;
+    }
+    return recurse(value);
+  });
   if (opts?.retainId) {
     props.id = id;
   }
+  const meta = getMeta(obj);
+  props[EchoSchema.MetaId] = deepMapValues(meta, (value, recurse) => {
+    if (EchoSchema.Ref.isRef(value)) {
+      return value;
+    }
+    return recurse(value);
+  });
   return make(schema, props);
 };
+
+export const VersionTypeId = EchoSchema.VersionTypeId;
+export type VersionType = typeof VersionTypeId;
+
+/**
+ * Represent object version.
+ * May be backed by Automerge.
+ * Objects with no history are not versioned.
+ */
+export interface Version {
+  [VersionTypeId]: {};
+
+  /**
+   * Whether the object is versioned.
+   */
+  versioned: boolean;
+
+  /**
+   * Automerge heads.
+   */
+  automergeHeads?: string[];
+}
+
+const unversioned: Version = {
+  [VersionTypeId]: {},
+  versioned: false,
+};
+
+/**
+ * Checks that `obj` is a version object.
+ */
+export const isVersion = (obj: unknown): obj is Version => {
+  return obj != null && typeof obj === 'object' && VersionTypeId in obj;
+};
+
+/**
+ * Returns the version of the object.
+ */
+export const version = (obj: Any | Relation.Any): Version => {
+  const version = (obj as any)[EchoSchema.ObjectVersionId];
+  if (version === undefined) {
+    return unversioned;
+  }
+  return version;
+};
+
+/**
+ * Checks that `version` is a valid version object.
+ */
+export const versionValid = (version: Version): boolean => {
+  assertArgument(isVersion(version), 'version', 'Invalid version object');
+  return !!version.versioned;
+};
+
+export type VersionCompareResult = 'unversioned' | 'equal' | 'different';
+
+/**
+ * Compares two versions.
+ * @param version1
+ * @param version2
+ * @returns 'unversioned' if either object is unversioned, 'equal' if the versions are equal, 'different' if the versions are different.
+ */
+export const compareVersions = (version1: Version, version2: Version): VersionCompareResult => {
+  assertArgument(isVersion(version1), 'version1', 'Invalid version object');
+  assertArgument(isVersion(version2), 'version2', 'Invalid version object');
+
+  if (!versionValid(version1) || !versionValid(version2)) {
+    return 'unversioned';
+  }
+
+  if (version1.automergeHeads?.length !== version2.automergeHeads?.length) {
+    return 'different';
+  }
+  if (version1.automergeHeads?.some((head) => !version2.automergeHeads?.includes(head))) {
+    return 'different';
+  }
+
+  return 'equal';
+};
+
+export const encodeVersion = (version: Version): string => {
+  return JSON.stringify(version);
+};
+
+export const decodeVersion = (version: string): Version => {
+  const parsed = JSON.parse(version);
+  parsed[VersionTypeId] = {};
+  return parsed;
+};

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;
@@ -60,6 +70,7 @@ export const make = <S extends Type.Relation.Any>(
 ): Live<Schema.Schema.Type<S> & Type.OfKind<EchoSchema.EntityKind.Relation>> => {
   assertArgument(
     EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Relation,
+    'schema',
     'Expected a relation schema',
   );
 

package/src/Tag.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { LabelAnnotation } from './internal';
+import * as Obj from './Obj';
+import * as Type from './Type';
+
+export const Tag = Schema.Struct({
+  label: Schema.String,
+  hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Tag',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['label']),
+);
+
+export type Tag = Schema.Schema.Type<typeof Tag>;
+
+export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
+
+// TODO(burdon): Rename Map.
+export type Map = Record<string, Tag>;
+
+export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
+
+export const createTagList = (tags: Map): Tag[] =>
+  Object.entries(tags)
+    .map(([id, tag]) => ({ ...tag, id }))
+    .sort(sortTags);
+
+export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undefined => {
+  const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
+  return entry ? { ...entry[1], id: entry[0] } : undefined;
+};