@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.8360d9e660

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.change or Relation.change 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/{object → Obj}/typed-object.test.ts

@@ -6,26 +6,26 @@ import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 import { describe, expect, test } from 'vitest';
 
-import { TypedObject } from './typed-object';
+import { EchoObjectSchema } from '../Entity';
 
-class Organization extends TypedObject({
-  typename: 'example.com/type/Organization',
-  version: '0.1.0',
-})({
+const Organization = Schema.Struct({
   name: Schema.String,
-}) {}
+}).pipe(
+  EchoObjectSchema({
+    typename: 'com.example.type.organization',
+    version: '0.1.0',
+  }),
+);
 
-describe('EchoObjectSchema class DSL', () => {
+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('example.com/type/Organization');
-  });
-
-  test('expect constructor to throw', async () => {
-    expect(() => new Organization()).to.throw();
+    expect(Organization.typename).to.eq('com.example.type.organization');
   });
 
   test('expect schema', async () => {

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/{ref → Ref}/ref-array.ts

@@ -5,7 +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 +16,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,8 +7,8 @@ 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';
 
@@ -16,7 +16,7 @@ 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 +26,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 JsonSchemaType } from '../JsonSchema';
+import type { AnyEntity, AnyProperties } from '../common/types';
 
 /**
  * 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);
+  }
 }
 
 /**