@dxos/echo 0.8.4-staging.ac66bdf99f → 0.9.0

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

@@ -6,14 +6,7 @@ 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 { SchemaEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 
 import { type Mutable } from '../common/proxy';
@@ -21,7 +14,7 @@ import { getSchema } from '../common/types';
 
 /**
  * Set a deeply nested property on an object.
- * Must be called within an Obj.change or Relation.change callback.
+ * 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');
@@ -38,7 +31,7 @@ export const setValue = (obj: Mutable<any>, path: readonly (string | number)[],
     const key = typeof part === 'number' ? part : String(part);
     if (parent[key] === undefined) {
       const propertyAST = getPropertyAST(currentAST, String(part));
-      const shouldBeArray = propertyAST ? isArrayType(propertyAST) : false;
+      const shouldBeArray = propertyAST ? SchemaEx.isArrayType(propertyAST) : false;
 
       if (shouldBeArray) {
         // Create array.
@@ -73,16 +66,16 @@ const getPropertyAST = (ast: SchemaAST.AST | undefined, propertyName: string): S
     return undefined;
   }
 
-  if (isNestedType(ast)) {
-    const properties = getProperties(ast);
+  if (SchemaEx.isNestedType(ast)) {
+    const properties = SchemaEx.getProperties(ast);
     const property = properties.find((p) => p.name.toString() === propertyName);
     if (property) {
-      return getBaseType(property).type;
+      return SchemaEx.getBaseType(property).type;
     }
   }
 
-  if (isArrayType(ast)) {
-    const elementType = getArrayElementType(ast);
+  if (SchemaEx.isArrayType(ast)) {
+    const elementType = SchemaEx.getArrayElementType(ast);
     return elementType;
   }
 
@@ -96,17 +89,17 @@ const getPropertyAST = (ast: SchemaAST.AST | undefined, propertyName: string): S
  * @param ast - Schema AST to inspect.
  * @returns Array of required properties with their types.
  */
-const getRequiredProperties = (ast: SchemaAST.AST | undefined): SchemaProperty[] => {
+const getRequiredProperties = (ast: SchemaAST.AST | undefined): SchemaEx.SchemaProperty[] => {
   if (!ast) {
     return [];
   }
 
   // Only objects/structs have properties with optional/required distinction.
-  if (!isNestedType(ast)) {
+  if (!SchemaEx.isNestedType(ast)) {
     return [];
   }
 
-  const properties = getProperties(ast);
+  const properties = SchemaEx.getProperties(ast);
 
   // Filter to only required properties (where isOptional === false).
   return properties.filter((p) => !p.isOptional);
@@ -156,7 +149,7 @@ const createObjectWithDefaults = (ast: SchemaAST.AST | undefined): any => {
     const defaultValue = getDefaultValueForType(prop.type);
     if (defaultValue !== undefined) {
       obj[prop.name] = defaultValue;
-    } else if (isNestedType(prop.type)) {
+    } else if (SchemaEx.isNestedType(prop.type)) {
       obj[prop.name] = createObjectWithDefaults(prop.type);
     }
   }

package/src/internal/Obj/snapshot.ts

@@ -7,18 +7,20 @@ import { deepMapValues } from '@dxos/util';
 
 import {
   KindId,
-  MetaId,
   ObjectDatabaseId,
   ObjectDeletedId,
+  ParentId,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
   SchemaId,
-  SelfDXNId,
+  SelfURIId,
   SnapshotKindId,
+  TypeEntityId,
   TypeId,
 } from '../common/types';
+import { MetaId } from '../common/types/model-symbols';
 
 /**
  * Copy a Symbol-keyed property from source to target if it has a defined value.
@@ -83,16 +85,23 @@ export const getSnapshot = <T extends object>(obj: T): T => {
   // Type introspection symbols.
   copySymbolProperty(source, snapshot, TypeId);
   copySymbolProperty(source, snapshot, SchemaId);
-  copySymbolProperty(source, snapshot, SelfDXNId);
+  copySymbolProperty(source, snapshot, TypeEntityId);
+  copySymbolProperty(source, snapshot, SelfURIId);
 
   // 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.
+  // Parent reference (required for Obj.getParent to work on snapshots).
+  copySymbolProperty(source, snapshot, ParentId);
+
+  // Metadata symbol. Copy arrays/objects so the snapshot is not affected by mutations to the live meta.
   copySymbolProperty(source, snapshot, MetaId, (meta: any) => ({
     keys: [...(meta?.keys ?? [])],
     tags: [...(meta?.tags ?? [])],
+    ...(meta?.key != null ? { key: meta.key } : {}),
+    ...(meta?.version != null ? { version: meta.version } : {}),
+    ...(meta?.annotations ? { annotations: { ...meta.annotations } } : {}),
   }));
 
   // Relation endpoint symbols.

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

@@ -6,29 +6,27 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
+import { DXN } from '@dxos/keys';
+
+import * as Type from '../../Type';
 import { EchoObjectSchema } from '../Entity';
 
 const Organization = Schema.Struct({
   name: Schema.String,
-}).pipe(
-  EchoObjectSchema({
-    typename: 'com.example.type.organization',
-    version: '0.1.0',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.organization', '0.1.0')));
 
-interface Organization extends Schema.Schema.Type<typeof Organization> {}
+type Organization = Type.InstanceType<typeof Organization>;
 
 describe('EchoObjectSchema DSL', () => {
-  test('type is a valid schema', async () => {
-    expect(Schema.isSchema(Organization)).to.be.true;
+  test('type is a Type.Type entity', async () => {
+    expect(Schema.isSchema(Type.getSchema(Organization))).to.be.true;
   });
 
   test('static typename accessor', async () => {
-    expect(Organization.typename).to.eq('com.example.type.organization');
+    expect(Type.getTypename(Organization)).to.eq('com.example.type.organization');
   });
 
   test('expect schema', async () => {
-    expect(SchemaAST.isTypeLiteral(Organization.ast)).to.be.true;
+    expect(SchemaAST.isTypeLiteral(Type.getSchema(Organization).ast)).to.be.true;
   });
 });

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

@@ -12,7 +12,7 @@ import { type AnyEntity } from '../common/types';
  * 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.
+ * In contrast to a stored `Type.Type` entity, this definition is not recorded in the database.
  *
  * @deprecated Use `Type.AnyObj` from `@dxos/echo` instead.
  */

package/src/internal/Query/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './pretty';

package/src/internal/{Query.ts → Query/pretty.ts}

@@ -1,5 +1,5 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2024 DXOS.org
 //
 
 import { type QueryAST } from '@dxos/echo-protocol';
@@ -10,6 +10,18 @@ import { type QueryAST } from '@dxos/echo-protocol';
 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));
@@ -25,6 +37,13 @@ export const prettyFilter = (filter: QueryAST.Filter): string => {
       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':
@@ -97,6 +116,9 @@ export const prettyQuery = (query: QueryAST.Query): string => {
           return 'Order.natural()';
         } else if (o.kind === 'rank') {
           return `Order.rank(${JSON.stringify(o.direction)})`;
+        } else if (o.kind === 'timestamp') {
+          const fn = o.field === 'updatedAt' ? 'updated' : 'created';
+          return `Order.${fn}(${JSON.stringify(o.direction)})`;
         } else {
           return `Order.property(${JSON.stringify(o.property)}, ${JSON.stringify(o.direction)})`;
         }
@@ -109,22 +131,28 @@ export const prettyQuery = (query: QueryAST.Query): 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.queues !== undefined) {
-          parts.push(`queues: [${scope.queues.map(String).join(', ')}]`);
-        }
-        if (scope.allQueuesFromSpaces !== undefined) {
-          parts.push(`allQueuesFromSpaces: ${scope.allQueuesFromSpaces}`);
+        if (query.from.scopes.length === 0) {
+          return `${prettyQuery(query.query)}.from('all-accessible-spaces')`;
         }
-        return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
+        const scopeStrs = query.from.scopes.map((scope) => {
+          if (scope._tag === 'space') {
+            return scope.includeAllFeeds
+              ? `{ space: ${JSON.stringify(scope.spaceId)}, includeAllFeeds: true }`
+              : `{ space: ${JSON.stringify(scope.spaceId)} }`;
+          }
+          if (scope._tag === 'feed') {
+            return `{ feed: ${JSON.stringify(String(scope.feedUri))} }`;
+          }
+          return `{ registry: ${JSON.stringify(scope.location)} }`;
+        });
+        return `${prettyQuery(query.query)}.from([${scopeStrs.join(', ')}])`;
       }
       return `${prettyQuery(query.query)}.from(${prettyQuery(query.from.query)})`;
     }

package/src/internal/Ref/atoms.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+
+import type { Ref } from './ref';
+import { loadRefTarget } from './utils';
+
+/**
+ * Atom family for ECHO refs.
+ * Uses ref reference as key — same ref returns same atom.
+ * This atom only updates once when the ref loads — it does not subscribe to target object changes.
+ * Use `Obj.atom(ref)` if you need reactive snapshots of ECHO objects via a ref.
+ */
+export const refSimpleFamily = Atom.family(<T>(ref: Ref<T>): Atom.Atom<T | undefined> => {
+  return Atom.make<T | undefined>((get) => {
+    return loadRefTarget(ref, get, (target) => target);
+  });
+});

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

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type ObjectId } from '@dxos/keys';
+import { type EntityId } from '@dxos/keys';
 import { isNonNullable } from '@dxos/util';
 
 import { type AnyEntity } from '../common/types';
@@ -29,8 +29,8 @@ export const RefArray = Object.freeze({
   /**
    * Removes the ref with the given id.
    */
-  removeById: (refs: Ref<AnyEntity>[], id: ObjectId) => {
-    const index = refs.findIndex(Ref.hasObjectId(id));
+  removeById: (refs: Ref<AnyEntity>[], id: EntityId) => {
+    const index = refs.findIndex(Ref.hasEntityId(id));
     if (index >= 0) {
       refs.splice(index, 1);
     }

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

@@ -5,46 +5,37 @@
 import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
-import { DXN, ObjectId } from '@dxos/keys';
+import { EID, EntityId, DXN } from '@dxos/keys';
 
-import { EchoObjectSchema, getObjectDXN } from '../Entity';
+import * as Type from '../../Type';
+import { EchoObjectSchema, getObjectEchoUri } 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',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.task', '0.1.0')));
 
-type Task = Schema.Schema.Type<typeof Task>;
+type Task = Type.InstanceType<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',
-  }),
-);
+}).pipe(EchoObjectSchema(DXN.make('com.example.type.person', '0.1.0')));
 
-type Contact = Schema.Schema.Type<typeof Contact>;
+type Contact = Type.InstanceType<typeof Contact>;
 
 describe('Ref', () => {
   test('Schema is', () => {
-    Ref(Contact).pipe(Schema.is)(Ref.fromDXN(DXN.parse(`dxn:echo:@:${ObjectId.random()}`)));
+    Ref(Contact).pipe(Schema.is)(Ref.fromURI(EID.make({ entityId: EntityId.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 });
+    expect(refAst).toEqual({ typename: Type.getTypename(Task), version: Type.getVersion(Task) });
   });
 
   // TODO(dmaretskyi): Figure out how to expose this in the API.
@@ -55,14 +46,14 @@ describe('Ref', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
       name: 'John Doe',
       tasks: [
         {
-          '/': getObjectDXN(task as any)!.toString(),
+          '/': getObjectEchoUri(task)!.toString(),
           target: JSON.parse(JSON.stringify(task)),
         },
       ],
@@ -76,25 +67,25 @@ describe('Ref', () => {
     const json = JSON.parse(JSON.stringify(contact));
     expect(json).toEqual({
       id: contact.id,
-      '@type': `dxn:type:${Contact.typename}:${Contact.version}`,
+      '@type': `dxn:${Type.getTypename(Contact)}:${Type.getVersion(Contact)}`,
       '@meta': {
         keys: [],
       },
       name: 'John Doe',
-      tasks: [{ '/': getObjectDXN(task)!.toString() }],
+      tasks: [{ '/': getObjectEchoUri(task)!.toString() }],
     });
   });
 
   test('decode object', () => {
-    const id = ObjectId.random();
+    const id = EntityId.random();
     const contactData = {
-      id: ObjectId.random(),
+      id: EntityId.random(),
       name: 'John Doe',
-      tasks: [{ '/': `dxn:echo:@:${id}` }],
+      tasks: [{ '/': `echo:/${id}` }],
     };
 
-    const contact = Contact.pipe(Schema.decodeUnknownSync)(contactData);
+    const contact = Type.getSchema(Contact).pipe(Schema.decodeUnknownSync)(contactData);
     expect(Ref.isRef(contact.tasks[0])).toEqual(true);
-    expect(contact.tasks[0].dxn.toString()).toEqual(`dxn:echo:@:${id}`);
+    expect(contact.tasks[0].uri.toString()).toEqual(`echo:/${id}`);
   });
 });