@dxos/echo 0.8.4-main.70d3990 → 0.8.4-main.74a063c4e0

package/src/internal/Query.ts

@@ -0,0 +1,132 @@
+//
+// 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': {
+      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(', ')}]`);
+      }
+      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 '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)}`);
+      }
+      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.queues !== undefined) {
+          parts.push(`queues: [${scope.queues.map(String).join(', ')}]`);
+        }
+        if (scope.allQueuesFromSpaces !== undefined) {
+          parts.push(`allQueuesFromSpaces: ${scope.allQueuesFromSpaces}`);
+        }
+        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 → Ref}/ref-array.ts

@@ -5,8 +5,7 @@
 import { type ObjectId } from '@dxos/keys';
 import { isNonNullable } from '@dxos/util';
 
-import { type AnyEchoObject } from '../types';
-
+import { type AnyEntity } from '../common/types';
 import { Ref } from './ref';
 
 /**
@@ -16,21 +15,21 @@ export const RefArray = Object.freeze({
   /**
    * @returns all resolved targets.
    */
-  targets: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): T[] => {
+  targets: <T extends AnyEntity>(refs: readonly Ref<T>[]): T[] => {
     return refs.map((ref) => ref.target).filter(isNonNullable);
   },
 
   /**
    * Load all referenced objects.
    */
-  loadAll: <T extends AnyEchoObject>(refs: readonly Ref<T>[]): Promise<T[]> => {
+  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<AnyEchoObject>[], id: ObjectId) => {
+  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}/ref.test.ts

@@ -7,16 +7,15 @@ import { describe, expect, test } from 'vitest';
 
 import { DXN, ObjectId } from '@dxos/keys';
 
-import { EchoObjectSchema, getObjectDXN } from '../entities';
-import { createObject } from '../object';
-
+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: 'example.com/type/Task',
+    typename: 'com.example.type.task',
     version: '0.1.0',
   }),
 );
@@ -26,10 +25,10 @@ type Task = Schema.Schema.Type<typeof Task>;
 const Contact = Schema.Struct({
   name: Schema.String,
   email: Schema.optional(Schema.String),
-  tasks: Schema.mutable(Schema.Array(Ref(Task))),
+  tasks: Schema.Array(Ref(Task)),
 }).pipe(
   EchoObjectSchema({
-    typename: 'example.com/type/Person',
+    typename: 'com.example.type.person',
     version: '0.1.0',
   }),
 );

package/src/internal/{ref → Ref}/ref.ts

@@ -3,19 +3,25 @@
 //
 
 import * as Effect from 'effect/Effect';
+import * as Equal from 'effect/Equal';
+import * as Hash from 'effect/Hash';
 import * as Option from 'effect/Option';
 import * as ParseResult from 'effect/ParseResult';
+import * as Pipeable from 'effect/Pipeable';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
+import type * as Types from 'effect/Types';
 
-import { type EncodedReference, Reference } from '@dxos/echo-protocol';
-import { compositeRuntime } from '@dxos/echo-signals/runtime';
+import { Event } from '@dxos/async';
+import { type CustomInspectFunction, inspectCustom } from '@dxos/debug';
+import { EncodedReference } from '@dxos/echo-protocol';
 import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN, ObjectId } from '@dxos/keys';
 
-import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
-import type { AnyProperties, WithId } from '../types';
+import * as Database from '../../Database';
+import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../Annotation';
+import type { AnyEntity, AnyProperties } from '../common/types';
+import { type JsonSchemaType } from '../JsonSchema';
 
 /**
  * The `$id` and `$ref` fields for an ECHO reference schema.
@@ -29,7 +35,7 @@ export const getSchemaReference = (property: JsonSchemaType): { typename: string
   }
 };
 
-export const createSchemaReference = (typename: string): JsonSchemaType => {
+export const createSchemaReference = (typename: string): Types.DeepMutable<JsonSchemaType> => {
   return {
     $id: JSON_SCHEMA_ECHO_REF_ID,
     reference: {
@@ -70,7 +76,7 @@ export const RefTypeId: unique symbol = Symbol('@dxos/echo/internal/Ref');
 /**
  * Reference Schema.
  */
-export interface RefSchema<T extends WithId> extends Schema.SchemaClass<Ref<T>, EncodedReference> {}
+export interface RefSchema<T extends AnyEntity> extends Schema.SchemaClass<Ref<T>, EncodedReference> {}
 
 /**
  * Type of the `Ref` function and extra methods attached to it.
@@ -101,8 +107,8 @@ export interface RefFn {
   /**
    * Constructs a reference that points to the given object.
    */
-  // TODO(burdon): Narrow to Obj.Any?
-  make: <T extends WithId>(object: T) => Ref<T>;
+  // TODO(burdon): Narrow to Obj.Unknown?
+  make: <T extends AnyEntity>(object: T) => Ref<T>;
 
   /**
    * Constructs a reference that points to the object specified by the provided DXN.
@@ -115,36 +121,33 @@ export interface RefFn {
  */
 export const Ref: RefFn = <S extends Schema.Schema.Any>(schema: S): RefSchema<Schema.Schema.Type<S>> => {
   assertArgument(Schema.isSchema(schema), 'schema', 'Must call with an instance of effect-schema');
-
   const annotation = getTypeAnnotation(schema);
   if (annotation == null) {
     throw new Error('Reference target must be an ECHO schema.');
   }
 
-  return createEchoReferenceSchema(
-    getTypeIdentifierAnnotation(schema),
-    annotation.typename,
-    annotation.version,
-    getSchemaExpectedName(schema.ast),
-  );
+  return createEchoReferenceSchema(getTypeIdentifierAnnotation(schema), annotation.typename, annotation.version);
 };
 
 /**
  * Represents materialized reference to a target.
  * This is the data type for the fields marked as ref.
  */
-export interface Ref<T> {
+export interface Ref<T> extends Pipeable.Pipeable {
   /**
    * Target object DXN.
    */
   get dxn(): DXN;
 
+  /**
+   * Returns true if the reference has a target available (inlined or resolver set).
+   */
+  get isAvailable(): boolean;
+
   /**
    * @returns The reference target.
    * May return `undefined` if the object is not loaded in the working set.
    * Accessing this property, even if it returns `undefined` will trigger the object to be loaded to the working set.
-   *
-   * @reactive Supports signal subscriptions.
    */
   get target(): T | undefined;
 
@@ -158,6 +161,7 @@ export interface Ref<T> {
   /**
    * @returns Promise that will resolves with the target object or undefined if the object is not loaded locally.
    */
+
   tryLoad(): Promise<T | undefined>;
 
   /**
@@ -219,7 +223,7 @@ Ref.make = <T extends AnyProperties>(obj: T): Ref<T> => {
   // TODO(dmaretskyi): Extract to `getObjectDXN` function.
   const id = obj.id;
   invariant(ObjectId.isValid(id), 'Invalid object ID');
-  const dxn = Reference.localObjectReference(id).toDXN();
+  const dxn = DXN.fromLocalObjectId(id);
   return new RefImpl(dxn, obj);
 };
 
@@ -244,7 +248,6 @@ export const createEchoReferenceSchema = (
   echoId: string | undefined,
   typename: string | undefined,
   version: string | undefined,
-  schemaName?: string, // TODO(burdon): Not used.
 ): Schema.SchemaClass<Ref<any>, EncodedReference> => {
   if (!echoId && !typename) {
     throw new TypeError('Either echoId or typename must be provided.');
@@ -263,25 +266,39 @@ export const createEchoReferenceSchema = (
     [],
     {
       encode: () => {
-        return (value) => {
-          return Effect.succeed({
-            '/': (value as Ref<any>).dxn.toString(),
+        return (value) =>
+          Effect.gen(function* () {
+            if (Ref.isRef(value)) {
+              return EncodedReference.fromDXN((value as Ref<any>).dxn);
+            } else if (EncodedReference.isEncodedReference(value)) {
+              return value;
+            }
+            throw new Error('Invalid reference');
           });
-        };
       },
       decode: () => {
-        return (value) => {
-          // TODO(dmaretskyi): This branch seems to be taken by Schema.is
-          if (Ref.isRef(value)) {
-            return Effect.succeed(value);
-          }
-
-          if (typeof value !== 'object' || value == null || typeof (value as any)['/'] !== 'string') {
-            return Effect.fail(new ParseResult.Unexpected(value, 'reference'));
-          }
-
-          return Effect.succeed(Ref.fromDXN(DXN.parse((value as any)['/'])));
-        };
+        return (value) =>
+          Effect.gen(function* () {
+            const dbService = yield* Effect.serviceOption(Database.Service);
+
+            // TODO(dmaretskyi): This branch seems to be taken by Schema.is
+            if (Ref.isRef(value)) {
+              if (Option.isSome(dbService)) {
+                return dbService.value.db.makeRef(value.dxn);
+              } else {
+                return value;
+              }
+            }
+
+            if (!EncodedReference.isEncodedReference(value)) {
+              return yield* Effect.fail(new ParseResult.Unexpected(value, 'reference'));
+            }
+            if (Option.isSome(dbService)) {
+              return dbService.value.db.makeRef(EncodedReference.toDXN(value));
+            } else {
+              return Ref.fromDXN(EncodedReference.toDXN(value));
+            }
+          });
       },
     },
     {
@@ -331,7 +348,7 @@ export interface RefResolver {
 export class RefImpl<T> implements Ref<T> {
   #dxn: DXN;
   #resolver?: RefResolver = undefined;
-  #signal = compositeRuntime.createSignal();
+  #resolved = new Event<void>();
 
   /**
    * Target is set when the reference is created from a specific object.
@@ -343,7 +360,7 @@ export class RefImpl<T> implements Ref<T> {
    * Callback to issue a reactive notification when object is resolved.
    */
   #resolverCallback = () => {
-    this.#signal.notifyWrite();
+    this.#resolved.emit();
   };
 
   constructor(dxn: DXN, target?: T) {
@@ -358,11 +375,17 @@ export class RefImpl<T> implements Ref<T> {
     return this.#dxn;
   }
 
+  /**
+   * @inheritdoc
+   */
+  get isAvailable(): boolean {
+    return this.#target !== undefined || this.#resolver !== undefined;
+  }
+
   /**
    * @inheritdoc
    */
   get target(): T | undefined {
-    this.#signal.notifyRead();
     if (this.#target) {
       return this.#target;
     }
@@ -390,6 +413,9 @@ export class RefImpl<T> implements Ref<T> {
    * @inheritdoc
    */
   async tryLoad(): Promise<T | undefined> {
+    if (this.#target) {
+      return this.#target;
+    }
     invariant(this.#resolver, 'Resolver is not set');
     return (await this.#resolver.resolve(this.#dxn)) as T | undefined;
   }
@@ -430,8 +456,27 @@ export class RefImpl<T> implements Ref<T> {
     return `Ref(${this.#dxn.toString()})`;
   }
 
+  [inspectCustom]: CustomInspectFunction = (depth, options, inspect) => {
+    return this.toString();
+  };
+
   [RefTypeId] = refVariance;
 
+  /**
+   * Effect Hash trait. Required for MutableHashMap-based caches (e.g., Atom.family)
+   * to deduplicate Ref instances that point to the same object.
+   * ECHO proxies return new RefImpl instances on every property access,
+   * so without this, each access would create a separate cache entry.
+   */
+  [Hash.symbol](): number {
+    return Hash.hash(this.#dxn.toString());
+  }
+
+  /** Effect Equal trait. See {@link Hash.symbol} for rationale. */
+  [Equal.symbol](that: Equal.Equal): boolean {
+    return that instanceof RefImpl && this.#dxn.toString() === that.dxn.toString();
+  }
+
   /**
    * Internal method to set the resolver.
    *
@@ -442,14 +487,16 @@ export class RefImpl<T> implements Ref<T> {
   }
 
   /**
-   * Internal method to get the saved target.
-   * Not the same as `target` which is resolved from the resolver.
-   *
    * @internal
    */
   _getSavedTarget(): T | undefined {
     return this.#target;
   }
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
 }
 
 /**

package/src/internal/{schema → Type}/compose.test.ts

@@ -5,19 +5,18 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { FieldPath } from '../annotations';
-import { FormatAnnotation, TypeFormat } from '../formats';
-import { ECHO_ANNOTATIONS_NS_KEY, toJsonSchema } from '../json-schema';
-import { TypedObject } from '../object';
-
+import { FieldPath } from '../Annotation';
+import { EchoObjectSchema } from '../Entity';
+import { FormatAnnotation, TypeFormat } from '../Format';
+import { ECHO_ANNOTATIONS_NS_KEY, toJsonSchema } from '../JsonSchema';
 import { composeSchema } from './compose';
 
 describe('schema composition', () => {
   test('schema composition', ({ expect }) => {
-    class BaseType extends TypedObject({ typename: 'example.com/Person', version: '0.1.0' })({
+    const BaseType = Schema.Struct({
       name: Schema.String,
       email: Schema.String,
-    }) {}
+    }).pipe(EchoObjectSchema({ typename: 'com.example.person', version: '0.1.0' }));
 
     const OverlaySchema = Schema.Struct({
       email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(TypeFormat.Email)),

package/src/internal/{schema → Type}/compose.ts

@@ -2,19 +2,22 @@
 // Copyright 2024 DXOS.org
 //
 
-import { invariant } from '@dxos/invariant';
+import type * as Types from 'effect/Types';
 
-import { type JsonSchemaType } from '../json-schema';
+import { invariant } from '@dxos/invariant';
 
-import { getSnapshot } from './snapshot';
+import { type JsonSchemaType } from '../JsonSchema';
 
 /**
  * Creates a composite schema from the source and projection schemas.
  */
 // TODO(burdon): Use effect schema projections.
 // TODO(burdon): Can avoid having to call this every time we modify any property on the view?
-export const composeSchema = (source: JsonSchemaType, target: JsonSchemaType): JsonSchemaType => {
-  const result: JsonSchemaType = getSnapshot(target);
+export const composeSchema = (
+  source: Types.Mutable<JsonSchemaType>,
+  target: Types.Mutable<JsonSchemaType>,
+): Types.Mutable<JsonSchemaType> => {
+  const result = structuredClone(target);
   invariant('type' in result && result.type === 'object', 'source schema must be an object');
   invariant('type' in source && source.type === 'object', 'target schema must be an object');
 
@@ -22,12 +25,13 @@ export const composeSchema = (source: JsonSchemaType, target: JsonSchemaType): J
     const propSchema = source.properties![prop]; // TODO(dmaretskyi): Find by json-path instead.
     const annotations = (propSchema as JsonSchemaType)?.annotations?.meta;
     if (annotations) {
-      (result.properties[prop] as JsonSchemaType).annotations ??= {};
-      (result.properties[prop] as JsonSchemaType).annotations!.meta ??= {};
+      const resultProp = result.properties[prop] as Record<string, any>;
+      resultProp.annotations ??= {};
+      resultProp.annotations.meta ??= {};
       for (const key in annotations) {
-        (result.properties[prop] as JsonSchemaType).annotations!.meta![key] ??= {};
-        Object.assign((result.properties[prop] as JsonSchemaType).annotations!.meta![key], annotations[key], {
-          ...(result.properties[prop] as JsonSchemaType).annotations!.meta![key],
+        resultProp.annotations.meta[key] ??= {};
+        Object.assign(resultProp.annotations.meta[key], annotations[key], {
+          ...resultProp.annotations.meta[key],
         });
       }
     }