@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/internal/Obj/set-value.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import {
+  type SchemaProperty,
+  getArrayElementType,
+  getBaseType,
+  getProperties,
+  isArrayType,
+  isNestedType,
+} from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { type Mutable } from '../common/proxy';
+import { getSchema } from '../common/types';
+
+/**
+ * Set a deeply nested property on an object.
+ * Must be called within an Obj.update or Relation.update callback.
+ */
+export const setValue = (obj: Mutable<any>, path: readonly (string | number)[], value: any): void => {
+  invariant(path.length > 0, 'Path must not be empty');
+
+  const schema = getSchema(obj);
+  invariant(schema != null, 'Object must have a schema');
+
+  let parent = obj;
+  let currentAST: SchemaAST.AST | undefined = schema.ast;
+
+  // Navigate to the parent of the target property.
+  for (let i = 0; i < path.length - 1; i++) {
+    const part = path[i];
+    const key = typeof part === 'number' ? part : String(part);
+    if (parent[key] === undefined) {
+      const propertyAST = getPropertyAST(currentAST, String(part));
+      const shouldBeArray = propertyAST ? isArrayType(propertyAST) : false;
+
+      if (shouldBeArray) {
+        // Create array.
+        parent[key] = [];
+      } else {
+        // TODO(wittjosiah): Is there a better way to handle this than creating an object with defaults?
+        //   Perhaps properties on objects should be optional by default?
+        // Create object with defaults for required fields.
+        const objWithDefaults = createObjectWithDefaults(propertyAST);
+        parent[key] = objWithDefaults;
+      }
+    }
+
+    parent = parent[key];
+    currentAST = getPropertyAST(currentAST, String(part));
+  }
+
+  const finalKey = path[path.length - 1];
+  parent[finalKey] = value;
+
+  return value;
+};
+
+/**
+ * Helper to get the AST of a nested property.
+ * @param ast - Current schema AST.
+ * @param propertyName - Name of the property to get.
+ * @returns The AST of the nested property, or undefined if not found.
+ */
+const getPropertyAST = (ast: SchemaAST.AST | undefined, propertyName: string): SchemaAST.AST | undefined => {
+  if (!ast) {
+    return undefined;
+  }
+
+  if (isNestedType(ast)) {
+    const properties = getProperties(ast);
+    const property = properties.find((p) => p.name.toString() === propertyName);
+    if (property) {
+      return getBaseType(property).type;
+    }
+  }
+
+  if (isArrayType(ast)) {
+    const elementType = getArrayElementType(ast);
+    return elementType;
+  }
+
+  return undefined;
+};
+
+/**
+ * Get all required properties from a schema AST.
+ * A property is required if it's not optional.
+ *
+ * @param ast - Schema AST to inspect.
+ * @returns Array of required properties with their types.
+ */
+const getRequiredProperties = (ast: SchemaAST.AST | undefined): SchemaProperty[] => {
+  if (!ast) {
+    return [];
+  }
+
+  // Only objects/structs have properties with optional/required distinction.
+  if (!isNestedType(ast)) {
+    return [];
+  }
+
+  const properties = getProperties(ast);
+
+  // Filter to only required properties (where isOptional === false).
+  return properties.filter((p) => !p.isOptional);
+};
+
+/**
+ * Get the default value for a primitive type.
+ * Returns undefined for non-primitive or unsupported types.
+ *
+ * @param ast - Type AST.
+ * @returns Default value for the type, or undefined.
+ */
+const getDefaultValueForType = (ast: SchemaAST.AST | undefined): any => {
+  if (!ast) {
+    return undefined;
+  }
+
+  const defaultValue = SchemaAST.getDefaultAnnotation(ast);
+  if (Option.isSome(defaultValue)) {
+    return defaultValue.value;
+  }
+
+  return Match.value(ast).pipe(
+    Match.when({ _tag: 'StringKeyword' }, () => ''),
+    Match.when({ _tag: 'NumberKeyword' }, () => 0),
+    Match.when({ _tag: 'BooleanKeyword' }, () => false),
+    Match.orElse(() => undefined),
+  );
+};
+
+/**
+ * Create an object with default values for all required properties.
+ * Handles primitive types (String, Number, Boolean) and recursively initializes required nested objects.
+ *
+ * @param ast - Schema AST describing the object structure.
+ * @returns Object with required fields populated with defaults.
+ */
+const createObjectWithDefaults = (ast: SchemaAST.AST | undefined): any => {
+  if (!ast) {
+    return {};
+  }
+
+  const requiredProps = getRequiredProperties(ast);
+  const obj: any = {};
+
+  for (const prop of requiredProps) {
+    const defaultValue = getDefaultValueForType(prop.type);
+    if (defaultValue !== undefined) {
+      obj[prop.name] = defaultValue;
+    } else if (isNestedType(prop.type)) {
+      obj[prop.name] = createObjectWithDefaults(prop.type);
+    }
+  }
+
+  return obj;
+};

package/src/internal/Obj/snapshot.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { assertArgument } from '@dxos/invariant';
+import { deepMapValues } from '@dxos/util';
+
+import {
+  KindId,
+  MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  SchemaId,
+  SelfDXNId,
+  SnapshotKindId,
+  TypeId,
+} from '../common/types';
+
+/**
+ * Copy a Symbol-keyed property from source to target if it has a defined value.
+ * Handles both plain objects (symbol in source) and proxies where get returns a value
+ * but has/in returns false (e.g. ObjectDatabaseId on echo-db proxies).
+ * Optional transform clones or mutates the value before assignment (e.g. for MetaId).
+ */
+const copySymbolProperty = (
+  source: any,
+  target: any,
+  symbol: symbol,
+  transform?: (value: unknown) => unknown,
+): void => {
+  let value: unknown;
+  // Echo-db proxy getters (e.g. RelationSourceId, RelationTargetId) can throw in certain states.
+  try {
+    value = source[symbol];
+  } catch {
+    return;
+  }
+  if (value !== undefined) {
+    const finalValue = transform ? transform(value) : value;
+    Object.defineProperty(target, symbol, {
+      value: finalValue,
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
+  }
+};
+
+/**
+ * Returns an immutable snapshot of the reactive object.
+ * The snapshot is branded with SnapshotKindId (not KindId).
+ */
+export const getSnapshot = <T extends object>(obj: T): T => {
+  assertArgument(typeof obj === 'object' && obj !== null && KindId in obj, 'obj', 'must be an entity');
+
+  const snapshot = deepMapValues(obj, (value, recurse) => {
+    // Do not recurse on references (but do recurse on arrays).
+    if (
+      typeof value === 'object' &&
+      value !== null &&
+      Object.getPrototypeOf(value) !== Object.prototype &&
+      !Array.isArray(value)
+    ) {
+      return value;
+    }
+
+    return recurse(value);
+  }) as any;
+
+  // Add SnapshotKindId brand based on original KindId.
+  if (obj != null && typeof obj === 'object' && KindId in obj) {
+    snapshot[SnapshotKindId] = (obj as any)[KindId];
+  }
+
+  // Preserve Symbol-keyed properties that are important for type introspection.
+  // These are not copied by deepMapValues since Object.keys() doesn't include symbols.
+  const source = obj as any;
+
+  // Type introspection symbols.
+  copySymbolProperty(source, snapshot, TypeId);
+  copySymbolProperty(source, snapshot, SchemaId);
+  copySymbolProperty(source, snapshot, SelfDXNId);
+
+  // Database reference (required for Obj.getDatabase to work on snapshots).
+  copySymbolProperty(source, snapshot, ObjectDatabaseId);
+  copySymbolProperty(source, snapshot, ObjectDeletedId);
+
+  // Metadata symbol. Copy arrays so the snapshot is not affected by mutations to the live meta's keys/tags.
+  copySymbolProperty(source, snapshot, MetaId, (meta: any) => ({
+    keys: [...(meta?.keys ?? [])],
+    tags: [...(meta?.tags ?? [])],
+  }));
+
+  // Relation endpoint symbols.
+  copySymbolProperty(source, snapshot, RelationSourceDXNId);
+  copySymbolProperty(source, snapshot, RelationTargetDXNId);
+  copySymbolProperty(source, snapshot, RelationSourceId);
+  copySymbolProperty(source, snapshot, RelationTargetId);
+
+  return Object.freeze(snapshot) as T;
+};

package/src/internal/Obj/typed-object.test.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, expect, test } from 'vitest';
+
+import { EchoObjectSchema } from '../Entity';
+
+const Organization = Schema.Struct({
+  name: Schema.String,
+}).pipe(
+  EchoObjectSchema({
+    typename: 'com.example.type.organization',
+    version: '0.1.0',
+  }),
+);
+
+interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+describe('EchoObjectSchema DSL', () => {
+  test('type is a valid schema', async () => {
+    expect(Schema.isSchema(Organization)).to.be.true;
+  });
+
+  test('static typename accessor', async () => {
+    expect(Organization.typename).to.eq('com.example.type.organization');
+  });
+
+  test('expect schema', async () => {
+    expect(SchemaAST.isTypeLiteral(Organization.ast)).to.be.true;
+  });
+});

package/src/internal/Obj/typed-object.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { type TypeMeta } from '../Annotation';
+import { type AnyEntity } from '../common/types';
+
+/**
+ * Definition for an object type that can be stored in an ECHO database.
+ * Implements effect schema to define object properties.
+ * Has a typename and version.
+ *
+ * In contrast to {@link EchoSchema} this definition is not recorded in the database.
+ *
+ * @deprecated Use `Type.AnyObj` from `@dxos/echo` instead.
+ */
+export interface TypedObject<A = any, I = any> extends TypeMeta, Schema.Schema<A, I> {}
+
+/**
+ * Typed object that could be used as a prototype in class definitions.
+ * This is an internal API type.
+ *
+ * @deprecated Use `Type.AnyObj` from `@dxos/echo` instead.
+ */
+export interface TypedObjectPrototype<A = any, I = any> extends TypedObject<A, I> {
+  /** Type constructor. */
+  new (): AnyEntity & A;
+}

package/src/internal/Query.ts

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type QueryAST } from '@dxos/echo-protocol';
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const prettyFilter = (filter: QueryAST.Filter): string => {
+  switch (filter.type) {
+    case 'object': {
+      // A type-less object filter with only a meta-key constraint is `Filter.key(...)`.
+      if (
+        filter.typename === null &&
+        (filter.id === undefined || filter.id.length === 0) &&
+        Object.keys(filter.props).length === 0 &&
+        (filter.foreignKeys === undefined || filter.foreignKeys.length === 0) &&
+        filter.metaKey !== undefined
+      ) {
+        return filter.metaVersion !== undefined
+          ? `Filter.key(${JSON.stringify(filter.metaKey)}, { version: ${JSON.stringify(filter.metaVersion)} })`
+          : `Filter.key(${JSON.stringify(filter.metaKey)})`;
+      }
+      const parts: string[] = [];
+      if (filter.typename !== null) {
+        parts.push(String(filter.typename));
+      }
+      if (filter.id !== undefined && filter.id.length > 0) {
+        parts.push(`id: [${filter.id.join(', ')}]`);
+      }
+      const propEntries = Object.entries(filter.props);
+      if (propEntries.length > 0) {
+        const propsStr = propEntries.map(([k, v]) => `${k}: ${prettyFilter(v)}`).join(', ');
+        parts.push(`{ ${propsStr} }`);
+      }
+      if (filter.foreignKeys !== undefined && filter.foreignKeys.length > 0) {
+        parts.push(`foreignKeys: [${filter.foreignKeys.map((fk) => JSON.stringify(fk)).join(', ')}]`);
+      }
+      if (filter.metaKey !== undefined) {
+        parts.push(
+          filter.metaVersion !== undefined
+            ? `metaKey: ${JSON.stringify(filter.metaKey)} (${filter.metaVersion})`
+            : `metaKey: ${JSON.stringify(filter.metaKey)}`,
+        );
+      }
+      return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
+    }
+    case 'compare':
+      return `Filter.${filter.operator}(${JSON.stringify(filter.value)})`;
+    case 'in':
+      return `Filter.in([${filter.values.map((v) => JSON.stringify(v)).join(', ')}])`;
+    case 'contains':
+      return `Filter.contains(${JSON.stringify(filter.value)})`;
+    case 'tag':
+      return `Filter.tag(${JSON.stringify(filter.tag)})`;
+    case 'range':
+      return `Filter.range(${JSON.stringify(filter.from)}, ${JSON.stringify(filter.to)})`;
+    case 'text-search':
+      return filter.searchKind
+        ? `Filter.textSearch(${JSON.stringify(filter.text)}, ${JSON.stringify(filter.searchKind)})`
+        : `Filter.textSearch(${JSON.stringify(filter.text)})`;
+    case 'timestamp':
+      return `Filter.${filter.field}.${filter.operator}(${filter.value})`;
+    case 'child-of':
+      return `Filter.childOf([${filter.parents.map((p) => JSON.stringify(p)).join(', ')}], { transitive: ${filter.transitive} })`;
+    case 'not':
+      return `Filter.not(${prettyFilter(filter.filter)})`;
+    case 'and':
+      return `Filter.and(${filter.filters.map(prettyFilter).join(', ')})`;
+    case 'or':
+      return `Filter.or(${filter.filters.map(prettyFilter).join(', ')})`;
+  }
+};
+
+/**
+ * Returns a human-readable string representation of a Query AST.
+ */
+export const prettyQuery = (query: QueryAST.Query): string => {
+  switch (query.type) {
+    case 'select':
+      return `Query.select(${prettyFilter(query.filter)})`;
+    case 'filter':
+      return `${prettyQuery(query.selection)}.select(${prettyFilter(query.filter)})`;
+    case 'reference-traversal':
+      return `${prettyQuery(query.anchor)}.reference(${JSON.stringify(query.property)})`;
+    case 'incoming-references': {
+      const args: string[] = [];
+      if (query.typename !== null) {
+        args.push(String(query.typename));
+      }
+      if (query.property !== null) {
+        args.push(JSON.stringify(query.property));
+      }
+      return `${prettyQuery(query.anchor)}.referencedBy(${args.join(', ')})`;
+    }
+    case 'relation': {
+      const method =
+        query.direction === 'outgoing' ? 'sourceOf' : query.direction === 'incoming' ? 'targetOf' : 'relationOf';
+      const filterStr = query.filter !== undefined ? prettyFilter(query.filter) : '';
+      return `${prettyQuery(query.anchor)}.${method}(${filterStr})`;
+    }
+    case 'relation-traversal':
+      return `${prettyQuery(query.anchor)}.${query.direction}()`;
+    case 'hierarchy-traversal':
+      return query.direction === 'to-parent'
+        ? `${prettyQuery(query.anchor)}.parent()`
+        : `${prettyQuery(query.anchor)}.children()`;
+    case 'union':
+      return `Query.all(${query.queries.map(prettyQuery).join(', ')})`;
+    case 'set-difference':
+      return `Query.without(${prettyQuery(query.source)}, ${prettyQuery(query.exclude)})`;
+    case 'order': {
+      const orders = query.order.map((o) => {
+        if (o.kind === 'natural') {
+          return 'Order.natural()';
+        } else if (o.kind === 'rank') {
+          return `Order.rank(${JSON.stringify(o.direction)})`;
+        } else {
+          return `Order.property(${JSON.stringify(o.property)}, ${JSON.stringify(o.direction)})`;
+        }
+      });
+      return `${prettyQuery(query.query)}.orderBy(${orders.join(', ')})`;
+    }
+    case 'options': {
+      const opts = query.options;
+      const parts: string[] = [];
+      if (opts.deleted !== undefined) {
+        parts.push(`deleted: ${JSON.stringify(opts.deleted)}`);
+      }
+      if (opts.debugLabel !== undefined) {
+        parts.push(`debugLabel: ${JSON.stringify(opts.debugLabel)}`);
+      }
+      return `${prettyQuery(query.query)}.options({ ${parts.join(', ')} })`;
+    }
+    case 'from': {
+      if (query.from._tag === 'scope') {
+        const scope = query.from.scope;
+        const parts: string[] = [];
+        if (scope.spaceIds !== undefined) {
+          parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
+        }
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
+        }
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
+        }
+        return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
+      }
+      return `${prettyQuery(query.query)}.from(${prettyQuery(query.from.query)})`;
+    }
+    case 'limit':
+      return `${prettyQuery(query.query)}.limit(${query.limit})`;
+  }
+};

package/src/internal/Ref/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ref';
+export * from './ref-array';

package/src/internal/Ref/ref-array.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type ObjectId } from '@dxos/keys';
+import { isNonNullable } from '@dxos/util';
+
+import { type AnyEntity } from '../common/types';
+import { Ref } from './ref';
+
+/**
+ * Helper functions for working with arrays of refs.
+ */
+export const RefArray = Object.freeze({
+  /**
+   * @returns all resolved targets.
+   */
+  targets: <T extends AnyEntity>(refs: readonly Ref<T>[]): T[] => {
+    return refs.map((ref) => ref.target).filter(isNonNullable);
+  },
+
+  /**
+   * Load all referenced objects.
+   */
+  loadAll: <T extends AnyEntity>(refs: readonly Ref<T>[]): Promise<T[]> => {
+    return Promise.all(refs.map((ref) => ref.load()));
+  },
+
+  /**
+   * Removes the ref with the given id.
+   */
+  removeById: (refs: Ref<AnyEntity>[], id: ObjectId) => {
+    const index = refs.findIndex(Ref.hasObjectId(id));
+    if (index >= 0) {
+      refs.splice(index, 1);
+    }
+  },
+});

package/src/internal/Ref/ref.test.ts

@@ -0,0 +1,100 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { DXN, ObjectId } from '@dxos/keys';
+
+import { EchoObjectSchema, getObjectDXN } from '../Entity';
+import { createObject } from '../Obj';
+import { Ref, getReferenceAst } from './ref';
+
+const Task = Schema.Struct({
+  title: Schema.optional(Schema.String),
+}).pipe(
+  EchoObjectSchema({
+    typename: 'com.example.type.task',
+    version: '0.1.0',
+  }),
+);
+
+type Task = Schema.Schema.Type<typeof Task>;
+
+const Contact = Schema.Struct({
+  name: Schema.String,
+  email: Schema.optional(Schema.String),
+  tasks: Schema.Array(Ref(Task)),
+}).pipe(
+  EchoObjectSchema({
+    typename: 'com.example.type.person',
+    version: '0.1.0',
+  }),
+);
+
+type Contact = Schema.Schema.Type<typeof Contact>;
+
+describe('Ref', () => {
+  test('Schema is', () => {
+    Ref(Contact).pipe(Schema.is)(Ref.fromDXN(DXN.parse(`dxn:echo:@:${ObjectId.random()}`)));
+  });
+
+  test('ref ast', () => {
+    const ref = Ref(Task);
+    expect(ref.ast._tag).toEqual('Declaration');
+    const refAst = getReferenceAst(ref.ast);
+    expect(refAst).toEqual({ typename: Task.typename, version: Task.version });
+  });
+
+  // TODO(dmaretskyi): Figure out how to expose this in the API.
+  test.skip('encode with inlined target', () => {
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task)] });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@meta': {
+        keys: [],
+      },
+      name: 'John Doe',
+      tasks: [
+        {
+          '/': getObjectDXN(task as any)!.toString(),
+          target: JSON.parse(JSON.stringify(task)),
+        },
+      ],
+    });
+  });
+
+  test('encode without inlining target', () => {
+    const task = createObject(Task, { title: 'Fix bugs' });
+    const contact = createObject(Contact, { name: 'John Doe', tasks: [Ref.make(task).noInline()] });
+
+    const json = JSON.parse(JSON.stringify(contact));
+    expect(json).toEqual({
+      id: contact.id,
+      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@meta': {
+        keys: [],
+      },
+      name: 'John Doe',
+      tasks: [{ '/': getObjectDXN(task)!.toString() }],
+    });
+  });
+
+  test('decode object', () => {
+    const id = ObjectId.random();
+    const contactData = {
+      id: ObjectId.random(),
+      name: 'John Doe',
+      tasks: [{ '/': `dxn:echo:@:${id}` }],
+    };
+
+    const contact = Contact.pipe(Schema.decodeUnknownSync)(contactData);
+    expect(Ref.isRef(contact.tasks[0])).toEqual(true);
+    expect(contact.tasks[0].dxn.toString()).toEqual(`dxn:echo:@:${id}`);
+  });
+});