@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/internal/ref/ref.ts

@@ -8,14 +8,16 @@ import * as ParseResult from 'effect/ParseResult';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-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 * as Database from '../../Database';
 import { ReferenceAnnotationId, getSchemaDXN, getTypeAnnotation, getTypeIdentifierAnnotation } from '../annotations';
 import { type JsonSchemaType } from '../json-schema';
-import type { AnyProperties, WithId } from '../types';
+import type { AnyEntity, AnyProperties } from '../types';
 
 /**
  * The `$id` and `$ref` fields for an ECHO reference schema.
@@ -70,7 +72,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 +103,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,18 +117,12 @@ 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);
 };
 
 /**
@@ -139,12 +135,15 @@ export interface Ref<T> {
    */
   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 +157,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 +219,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 +244,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 +262,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 +344,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 +356,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 +371,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 +409,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,6 +452,10 @@ export class RefImpl<T> implements Ref<T> {
     return `Ref(${this.#dxn.toString()})`;
   }
 
+  [inspectCustom]: CustomInspectFunction = (depth, options, inspect) => {
+    return this.toString();
+  };
+
   [RefTypeId] = refVariance;
 
   /**
@@ -442,9 +468,6 @@ 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 {

package/src/internal/schema/compose.test.ts

@@ -6,18 +6,18 @@ import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
 import { FieldPath } from '../annotations';
+import { EchoObjectSchema } from '../entities';
 import { FormatAnnotation, TypeFormat } from '../formats';
 import { ECHO_ANNOTATIONS_NS_KEY, toJsonSchema } from '../json-schema';
-import { TypedObject } from '../object';
 
 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: 'example.com/Person', version: '0.1.0' }));
 
     const OverlaySchema = Schema.Struct({
       email: Schema.String.pipe(FieldPath('$.email'), FormatAnnotation.set(TypeFormat.Email)),

package/src/internal/schema/compose.ts

@@ -5,8 +5,7 @@
 import { invariant } from '@dxos/invariant';
 
 import { type JsonSchemaType } from '../json-schema';
-
-import { getSnapshot } from './snapshot';
+import { getSnapshot } from '../object';
 
 /**
  * Creates a composite schema from the source and projection schemas.

package/src/internal/schema/echo-schema.ts

@@ -10,7 +10,9 @@ import { type ObjectId } from '@dxos/keys';
 
 import { type SchemaMeta, SchemaMetaSymbol, type TypeAnnotation, getTypeAnnotation } from '../annotations';
 import { type JsonSchemaType, toEffectSchema, toJsonSchema } from '../json-schema';
-import { type TypedObject, type TypedObjectPrototype } from '../object';
+import { type TypedObject, type TypedObjectPrototype, getSnapshot } from '../object';
+import { ChangeId } from '../proxy';
+import { EntityKind, SchemaKindId } from '../types';
 
 import {
   addFieldsToSchema,
@@ -20,7 +22,6 @@ import {
   updateFieldsInSchema,
 } from './manipulation';
 import { PersistentSchema } from './persistent-schema';
-import { getSnapshot } from './snapshot';
 
 /**
  * Base schema type.
@@ -83,6 +84,10 @@ export class ImmutableSchema<A = any, I = any> implements BaseSchema<A, I> {
   // TypedObject
   //
 
+  get kind(): EntityKind {
+    return this._objectAnnotation.kind;
+  }
+
   get typename(): string {
     return this._objectAnnotation.typename;
   }
@@ -172,7 +177,7 @@ const schemaVariance = {
  *
  * @example
  * ```ts
- * export class TableType extends Schema.Struct({...}).pipe(Type.Obj({ typename: 'example.org/type/Table', version: '0.1.0' })){
+ * export class TableType extends Schema.Struct({...}).pipe(Type.object({ typename: 'example.org/type/Table', version: '0.1.0' })){
  *   title: Schema.String,
  *   schema: Schema.optional(ref(EchoSchema)),
  *   props: Schema.mutable(S.Array(TablePropSchema)),
@@ -185,6 +190,12 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   private _schema: Schema.Schema.AnyNoContext | undefined;
   private _isDirty = true;
 
+  /**
+   * Schema kind key that marks this as an ECHO schema.
+   * Makes EchoSchema satisfy the Type.Obj.Any type.
+   */
+  readonly [SchemaKindId]: EntityKind.Object = EntityKind.Object;
+
   constructor(private readonly _persistentSchema: PersistentSchema) {
     super();
   }
@@ -229,6 +240,11 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   // BaseSchema
   //
 
+  public get kind(): EntityKind.Object {
+    // Dynamic schemas are always object schemas.
+    return EntityKind.Object;
+  }
+
   public get typename(): string {
     return this._persistentSchema.typename;
   }
@@ -249,7 +265,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   /**
-   * @reactive
+   * Returns the JSON schema for the schema.
    */
   public get jsonSchema(): JsonSchemaType {
     return this._persistentSchema.jsonSchema;
@@ -309,8 +325,10 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateTypename(typename: string): void {
     const updated = setTypenameInSchema(this._getSchema(), typename);
-    this._persistentSchema.typename = typename;
-    this._persistentSchema.jsonSchema = toJsonSchema(updated);
+    this._change((schema) => {
+      schema.typename = typename;
+      schema.jsonSchema = toJsonSchema(updated);
+    });
   }
 
   /**
@@ -318,7 +336,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public addFields(fields: Schema.Struct.Fields): void {
     const extended = addFieldsToSchema(this._getSchema(), fields);
-    this._persistentSchema.jsonSchema = toJsonSchema(extended);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(extended);
+    });
   }
 
   /**
@@ -326,7 +346,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateFields(fields: Schema.Struct.Fields): void {
     const updated = updateFieldsInSchema(this._getSchema(), fields);
-    this._persistentSchema.jsonSchema = toJsonSchema(updated);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(updated);
+    });
   }
 
   /**
@@ -334,7 +356,9 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public updateFieldPropertyName({ before, after }: { before: PropertyKey; after: PropertyKey }): void {
     const renamed = updateFieldNameInSchema(this._getSchema(), { before, after });
-    this._persistentSchema.jsonSchema = toJsonSchema(renamed);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(renamed);
+    });
   }
 
   /**
@@ -342,7 +366,21 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
    */
   public removeFields(fieldNames: string[]): void {
     const removed = removeFieldsFromSchema(this._getSchema(), fieldNames);
-    this._persistentSchema.jsonSchema = toJsonSchema(removed);
+    this._change((schema) => {
+      schema.jsonSchema = toJsonSchema(removed);
+    });
+  }
+
+  /**
+   * Wrapper for Obj.change that handles the change context for the persistent schema.
+   */
+  private _change(callback: (schema: PersistentSchema) => void): void {
+    const changeFn = (this._persistentSchema as any)[ChangeId];
+    if (changeFn) {
+      changeFn(callback);
+    } else {
+      callback(this._persistentSchema);
+    }
   }
 
   //
@@ -350,7 +388,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   //
 
   /**
-   * Called by EchoSchemaRegistry on update.
+   * Called by DatabaseSchemaRegistry on update.
    */
   _invalidate(): void {
     this._isDirty = true;

package/src/internal/schema/index.ts

@@ -5,5 +5,3 @@
 export * from './echo-schema';
 export * from './manipulation';
 export * from './persistent-schema';
-export * from './runtime-schema-registry';
-export * from './snapshot';

package/src/internal/schema/persistent-schema.ts

@@ -12,7 +12,7 @@ import { JsonSchemaType } from '../json-schema';
  * Persistent representation of a schema.
  */
 // TODO(burdon): Move.
-const PersistentEchoSchema = Schema.Struct({
+export const PersistentSchema = Schema.Struct({
   name: Schema.optional(Schema.String),
   typename: TypenameSchema,
   version: VersionSchema,
@@ -23,6 +23,5 @@ const PersistentEchoSchema = Schema.Struct({
     version: '0.1.0',
   }),
 );
-export interface PersistentSchema extends Schema.Schema.Type<typeof PersistentEchoSchema> {}
-export interface PersistentSchemaEncoded extends Schema.Schema.Encoded<typeof PersistentEchoSchema> {}
-export const PersistentSchema: Schema.Schema<PersistentSchema, PersistentSchemaEncoded> = PersistentEchoSchema;
+
+export interface PersistentSchema extends Schema.Schema.Type<typeof PersistentSchema> {}

package/src/internal/types/base.ts

@@ -9,20 +9,6 @@ import { type ObjectId } from '@dxos/keys';
 
 import { type ATTR_META, type ObjectMeta } from './meta';
 
-/**
- * Marker interface for object with an `id`.
- */
-export interface HasId {
-  readonly id: ObjectId;
-}
-
-/**
- * Object that has an associated typename.
- * The typename is retrievable using {@link getTypename}.
- * The object can be used with {@link isInstanceOf} to check if it is an instance of a schema.
- */
-export type HasTypename = {};
-
 /**
  * Base type for all data objects (reactive, ECHO, and other raw objects).
  * NOTE: This describes the base type for all database objects.
@@ -30,23 +16,22 @@ export type HasTypename = {};
  */
 // TODO(burdon): Make internal.
 // TODO(burdon): Prefer Record<string, unknown>.
-// TODO(burdon): Exclude "id", etc. from keys.
 export type AnyProperties = Record<string, any>;
 
 /**
- * Canonical type for all ECHO objects.
+ * Canonical type for all ECHO entities (objects and relations).
  */
-export interface AnyEchoObject extends HasId, HasTypename {}
-
-// TODO(dmaretskyi): Remove; this type effectively disables type safety due to `any`.
-export type WithId<T extends AnyProperties = AnyProperties> = T & HasId;
+// TODO(wittjosiah): Remove. Prefer higher level types (e.g. Entity.Unknown).
+export interface AnyEntity {
+  readonly id: ObjectId;
+}
 
 export type ExcludeId<T extends AnyProperties> = Omit<T, 'id'>;
 
 export type PropertyKey<T extends AnyProperties> = Extract<keyof ExcludeId<T>, string>;
 
 // TODO(dmaretskyi): Remove. This should be using the symbol type.
-export type WithMeta = { [ATTR_META]?: ObjectMeta };
+type WithMeta = { [ATTR_META]?: ObjectMeta };
 
 /**
  * The raw object should not include the ECHO id, but may include metadata.

package/src/internal/types/entity.ts

@@ -4,10 +4,33 @@
 
 import * as Schema from 'effect/Schema';
 
+// NOTE: String literals are used instead of unique symbols for both KindId and SchemaKindId.
+//   Unique symbols cause TS4023 "cannot be named" errors when external packages
+//   try to export types that reference this key (e.g., `export const Graph = ...`).
+//   TypeScript cannot emit declaration files that reference unique symbols from
+//   external modules. Using a string literal allows the type to be inlined in
+//   declaration files, making the API portable across package boundaries.
+
+/**
+ * String key used to identify the kind of an entity instance (object or relation).
+ */
+export const KindId = '~@dxos/echo/Kind' as const;
+export type KindId = typeof KindId;
+
+/**
+ * String key used to identify the kind of a schema (object schema or relation schema).
+ * Parallels KindId which identifies instance kinds.
+ */
+export const SchemaKindId = '~@dxos/echo/SchemaKind' as const;
+export type SchemaKindId = typeof SchemaKindId;
+
 /**
- * Entity kind.
+ * String key used to brand snapshot types.
+ * Snapshots have SnapshotKindId instead of KindId, making them
+ * distinguishable from reactive objects at the type level.
  */
-const EntityKindId = Symbol.for('@dxos/echo/EntityKind');
+export const SnapshotKindId = '~@dxos/echo/SnapshotKind' as const;
+export type SnapshotKindId = typeof SnapshotKindId;
 
 /**
  * Kinds of entities stored in ECHO: objects and relations.
@@ -19,5 +42,13 @@ export enum EntityKind {
 
 export const EntityKindSchema = Schema.Enums(EntityKind);
 
-export const KindId: unique symbol = EntityKindId as any;
-export type KindId = typeof KindId;
+/**
+ * Typename for generic object references (Type.Obj / Type.Ref(Type.Obj)).
+ * Used when referencing any object without a specific schema.
+ */
+export const ANY_OBJECT_TYPENAME = 'dxos.org/schema/AnyObject';
+
+/**
+ * Version for generic object references.
+ */
+export const ANY_OBJECT_VERSION = '0.0.0';

package/src/internal/types/meta.ts

@@ -8,7 +8,7 @@ import { ForeignKey } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { type Comparator, intersection } from '@dxos/util';
 
-import { type AnyProperties, type WithMeta } from './base';
+import { type AnyProperties } from './base';
 
 /**
  * Property name for meta when object is serialized to JSON.
@@ -54,16 +54,6 @@ export const getMeta = (obj: AnyProperties): ObjectMeta => {
   return metadata;
 };
 
-/**
- * Utility to split meta property from raw object.
- * @deprecated Bad API.
- */
-export const splitMeta = <T>(object: T & WithMeta): { object: T; meta?: ObjectMeta } => {
-  const meta = object[ATTR_META];
-  delete object[ATTR_META];
-  return { meta, object };
-};
-
 //
 // Foreign keys
 //

package/src/testing/api.test.ts

@@ -14,12 +14,12 @@ import { TestSchema } from './test-schema';
 describe('Experimental API review', () => {
   test('type checks', ({ expect }) => {
     const contact = Obj.make(TestSchema.Person, { name: 'Test' });
-    const type: Schema.Schema<TestSchema.Person> = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
+    const schema = Obj.getSchema(contact) ?? raise(new Error('No schema found'));
 
-    expect(Type.getDXN(type)?.typename).to.eq(TestSchema.Person.typename);
-    expect(Type.getTypename(type)).to.eq('example.com/type/Person');
-    expect(Type.getVersion(type)).to.eq('0.1.0');
-    expect(Type.getMeta(type)).to.deep.eq({
+    expect(Type.getDXN(schema)?.typename).to.eq(TestSchema.Person.typename);
+    expect(Type.getTypename(schema)).to.eq('example.com/type/Person');
+    expect(Type.getVersion(schema)).to.eq('0.1.0');
+    expect(Type.getMeta(schema)).to.deep.eq({
       kind: Entity.Kind.Object,
       typename: 'example.com/type/Person',
       version: '0.1.0',
@@ -97,4 +97,30 @@ describe('Experimental API review', () => {
       }
     }
   });
+
+  /**
+   * Test that Obj.make return types are clean and don't expose internal markers like OfKind.
+   * The return type of Obj.make(Schema, props) should be assignable to Obj.Obj<InstanceType>.
+   */
+  describe('Obj.make return type', () => {
+    test('Obj.make with custom schema should be assignable to Obj.Obj<Person>', ({ expect }) => {
+      {
+        const expando = Obj.make(TestSchema.Expando, { content: 'Test' });
+        expect(Obj.isObject(expando)).to.be.true;
+        expect(expando.content).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.Obj<TestSchema.Expando> = expando;
+      }
+
+      {
+        const person = Obj.make(TestSchema.Person, { name: 'Test' });
+        expect(Obj.isObject(person)).to.be.true;
+        expect(person.name).to.eq('Test');
+
+        // This should work: assign to Obj.Obj of the schema's instance type
+        const _typed: Obj.Obj<TestSchema.Person> = person;
+      }
+    });
+  });
 });