@dxos/echo 0.8.4-main.66e292d → 0.8.4-main.69d29f4

package/src/Type.ts

@@ -2,28 +2,31 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Schema$ from 'effect/Schema';
+import * as Schema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
-import { type DXN } from '@dxos/keys';
+import { type DXN, type ObjectId } from '@dxos/keys';
 import { type ToMutable } from '@dxos/util';
 
 import type * as Entity$ from './Entity';
 import {
+  ANY_OBJECT_TYPENAME,
+  ANY_OBJECT_VERSION,
   type ATTR_RELATION_SOURCE,
   type ATTR_RELATION_TARGET,
+  type AnyEntity,
+  type AnyProperties,
   EchoObjectSchema,
   EchoRelationSchema,
   type EchoRelationSchemaOptions,
   EchoSchema,
-  Expando as Expando$,
-  type ExpandoEncoded,
+  EntityKind,
   PersistentSchema,
-  type PersistentSchemaEncoded,
   Ref as Ref$,
   type RefFn,
   type RefSchema,
+  SchemaKindId,
   type TypeAnnotation,
   type TypeMeta,
   getSchemaDXN,
@@ -45,126 +48,256 @@ export { toEffectSchema, toJsonSchema };
 export type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;
 
 //
-// Entity
+// Internal types (not exported)
 //
 
-export namespace Entity {
-  /**
-   * Type.Obj.Any | Type.Relation.Any.
-   */
-  export type Any = Obj.Any | Relation.Any;
+/**
+ * Type that marks a schema as an ECHO schema.
+ * The value indicates the entity kind (Object or Relation).
+ */
+type EchoSchemaKind<K extends EntityKind = EntityKind> = {
+  readonly [SchemaKindId]: K;
+};
+
+/**
+ * JSON-encoded properties for objects.
+ */
+interface ObjJsonProps {
+  id: string;
+}
+
+/**
+ * JSON-encoded properties for relations.
+ */
+interface RelationJsonProps {
+  id: string;
+  [ATTR_RELATION_SOURCE]: string;
+  [ATTR_RELATION_TARGET]: string;
 }
 
 //
-// Obj
+// Obj - Runtime schema for any ECHO object
 //
 
-interface ObjJsonProps {
-  id: string;
-}
+// Internal type for the Obj schema constant.
+// NOTE: The `any` in the type intersection is intentional - it makes this type bidirectionally
+//   assignable with specific object types (e.g., Type.Obj can be assigned to/from Meeting.Meeting).
+//   This is needed because operation schemas erase type information.
+// TODO(wittjosiah): Consider alternatives to the `any` intersection hack:
+//   - Generic operation schemas that preserve input type in output
+//   - Branded types that specific schemas also carry
+//   - Accept the limitation and require explicit type narrowing at call sites
+type ObjSchemaType = Schema.Schema<
+  any & AnyEntity & Entity$.OfKind<typeof Entity$.Kind.Object> & AnyProperties,
+  { id: string } & AnyProperties
+> &
+  EchoSchemaKind<EntityKind.Object> &
+  TypeMeta;
+
+// Internal schema definition.
+// NOTE: The EchoObjectSchema annotation is required for Type.Ref(Type.Obj) to work.
+//   The typename/version only satisfy ECHO schema machinery for reference targets.
+const ObjSchema = Schema.Struct({
+  id: Schema.String,
+}).pipe(
+  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  EchoObjectSchema({ typename: ANY_OBJECT_TYPENAME, version: ANY_OBJECT_VERSION }),
+);
 
 /**
- * Return type of the `Obj` schema constructor.
+ * Runtime Effect schema for any ECHO object.
+ * Use for validation, parsing, or as a reference target for collections.
  *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * NOTE: `Schema.is(Type.Obj)` does STRUCTURAL validation only (checks for `id` field).
+ * Use `Obj.isObject()` for proper ECHO instance type guards that check the KindId brand.
+ *
+ * @example
+ * ```ts
+ * // Structural type guard (accepts any object with id field)
+ * if (Schema.is(Type.Obj)(unknownValue)) { ... }
+ *
+ * // ECHO instance type guard (checks KindId brand)
+ * if (Obj.isObject(unknownValue)) { ... }
+ *
+ * // Reference to any object type
+ * const Collection = Schema.Struct({
+ *   objects: Schema.Array(Type.Ref(Type.Obj)),
+ * }).pipe(Type.object({ typename: 'Collection', version: '0.1.0' }));
+ * ```
  */
-export interface obj<Self extends Schema$.Schema.Any>
-  extends TypeMeta,
-    Schema$.AnnotableClass<
-      obj<Self>,
-      Entity$.OfKind<typeof Entity$.Kind.Object> & ToMutable<Schema$.Schema.Type<Self>>,
-      Schema$.Simplify<ObjJsonProps & ToMutable<Schema$.Schema.Encoded<Self>>>,
-      Schema$.Schema.Context<Self>
-    > {}
+// TODO(wittjosiah): Investigate if Schema.filter can validate KindId on ECHO instances.
+//   Effect Schema normalizes proxy objects to plain objects before calling filter predicates.
+//   Possible approaches: custom Schema.declare, AST manipulation, or upstream contribution.
+export const Obj: ObjSchemaType = Object.assign(ObjSchema, {
+  [SchemaKindId]: (ObjSchema as any)[SchemaKindId],
+}) as unknown as ObjSchemaType;
 
 /**
- * Object schema.
+ * TypeScript type for an ECHO object schema.
+ * `T` is the instance type produced by the schema.
+ * `Fields` is the optional struct fields type for introspection.
+ *
+ * @example
+ * ```ts
+ * const PersonSchema: Type.Obj<Person> = Schema.Struct({
+ *   name: Schema.String,
+ * }).pipe(Type.object({ typename: 'Person', version: '0.1.0' }));
+ *
+ * // Access fields for introspection:
+ * Object.keys(PersonSchema.fields); // ['name']
+ * ```
  */
-export const Obj: {
-  (opts: TypeMeta): <Self extends Schema$.Schema.Any>(self: Self) => obj<Self>;
-} = EchoObjectSchema as any;
+export interface Obj<T = any, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends TypeMeta,
+    EchoSchemaKind<EntityKind.Object>,
+    Schema.AnnotableClass<
+      Obj<T, Fields>,
+      Entity$.OfKind<typeof Entity$.Kind.Object> & T,
+      Schema.Simplify<ObjJsonProps & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
+}
 
 /**
- * Object schema type definitions.
+ * Structural base type for any ECHO object schema.
+ * Accepts both static schemas (created with Type.object()) and EchoSchema.
+ * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
+ * Use Type.isObjectSchema() for runtime type guards.
  */
-export declare namespace Obj {
+type ObjectSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
+
+export namespace Obj {
   /**
-   * Type that represents an arbitrary schema type of an object.
-   * NOTE: This is not an instance type.
+   * Type that represents any ECHO object schema.
+   * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
    */
-  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  // TODO(burdon): This erases the ECHO type info (e.g., id, typename).
-  export type Any = obj<Schema$.Schema.AnyNoContext>;
+  export type Any = ObjectSchemaBase;
 }
 
-//
-// Expando
-//
-
-export const Expando: obj<Schema$.Schema<Expando$, ExpandoEncoded>> = Expando$ as any;
-export type Expando = obj<Schema$.Schema<Expando$, ExpandoEncoded>>;
+/**
+ * Factory function to create an ECHO object schema.
+ * Adds object metadata annotations to an Effect schema.
+ *
+ * @example
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ * }).pipe(Type.object({ typename: 'example.com/type/Person', version: '0.1.0' }));
+ * ```
+ */
+export const object: {
+  (opts: TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
+} = EchoObjectSchema as any;
 
 //
-// Schema
+// PersistentType (Schema stored in database)
 //
 
-export const PersistentType: obj<Schema$.Schema<PersistentSchema, PersistentSchemaEncoded>> = PersistentSchema as any;
-export type PersistentType = obj<Schema$.Schema<PersistentSchema, PersistentSchemaEncoded>>;
+export const PersistentType: Obj<PersistentSchema> = PersistentSchema as any;
+
+export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
 export { EchoSchema as RuntimeType };
 
 //
-// Relation
+// Relation - Runtime schema for any ECHO relation
 //
 
-interface RelationJsonProps {
-  id: string;
-  [ATTR_RELATION_SOURCE]: string;
-  [ATTR_RELATION_TARGET]: string;
-}
+// Internal type for the Relation schema constant.
+type RelationSchemaType = Schema.Schema<
+  { id: ObjectId } & Record<string, unknown>,
+  { id: string } & Record<string, unknown>
+> &
+  EchoSchemaKind<EntityKind.Relation> &
+  TypeMeta;
+
+// Internal schema definition.
+// NOTE: The EchoRelationSchema annotation is required for Type.Ref(Type.Relation) to work.
+//   The typename/version/source/target only satisfy ECHO schema machinery for reference targets.
+const RelationSchema = Schema.Struct({
+  id: Schema.String,
+}).pipe(
+  Schema.extend(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  EchoRelationSchema({
+    typename: 'dxos.org/schema/AnyRelation',
+    version: '0.0.0',
+    source: ObjSchema,
+    target: ObjSchema,
+  }),
+);
 
 /**
- * Return type of the `Relation` schema constructor.
+ * Runtime Effect schema for any ECHO relation.
+ * Use for validation, parsing, or as a reference target for collections.
+ * A relation has `id`, source, and target fields plus any additional properties.
  *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * NOTE: `Schema.is(Type.Relation)` does STRUCTURAL validation only (checks for `id` field).
+ * Use `Relation.isRelation()` for proper ECHO instance type guards that check the KindId brand.
+ *
+ * @example
+ * ```ts
+ * // Structural type guard (accepts any object with id field)
+ * if (Schema.is(Type.Relation)(unknownValue)) { ... }
+ *
+ * // ECHO instance type guard (checks KindId brand)
+ * if (Relation.isRelation(unknownValue)) { ... }
+ * ```
  */
-export interface relation<
-  Self extends Schema$.Schema.Any,
-  SourceSchema extends Schema$.Schema.Any,
-  TargetSchema extends Schema$.Schema.Any,
-> extends TypeMeta,
-    Schema$.AnnotableClass<
-      relation<Self, SourceSchema, TargetSchema>,
-      Entity$.OfKind<typeof Entity$.Kind.Relation> &
-        Relation.Endpoints<Schema$.Schema.Type<SourceSchema>, Schema$.Schema.Type<TargetSchema>> &
-        ToMutable<Schema$.Schema.Type<Self>>,
-      Schema$.Simplify<RelationJsonProps & ToMutable<Schema$.Schema.Encoded<Self>>>,
-      Schema$.Schema.Context<Self>
-    > {}
+export const Relation: RelationSchemaType = Object.assign(RelationSchema, {
+  [SchemaKindId]: (RelationSchema as any)[SchemaKindId],
+}) as unknown as RelationSchemaType;
 
 /**
- * Relation schema.
+ * TypeScript type for an ECHO relation schema.
+ * `T` is the instance type produced by the schema (excluding source/target).
+ * `Source` and `Target` are the endpoint types.
+ * `Fields` is the optional struct fields type for introspection.
  */
-// TODO(dmaretskyi): I have to redefine the type here so that the definition uses symbols from @dxos/echo/Relation.
-// TODO(burdon): Remove?
-export const Relation: {
-  <Source extends Schema$.Schema.AnyNoContext, Target extends Schema$.Schema.AnyNoContext>(
-    opts: EchoRelationSchemaOptions<Source, Target>,
-  ): <Self extends Schema$.Schema.Any>(self: Self) => relation<Self, Source, Target>;
-} = EchoRelationSchema as any;
+export interface Relation<
+  T = any,
+  Source = any,
+  Target = any,
+  Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
+> extends TypeMeta,
+    EchoSchemaKind<EntityKind.Relation>,
+    Schema.AnnotableClass<
+      Relation<T, Source, Target, Fields>,
+      Entity$.OfKind<typeof Entity$.Kind.Relation> & Relation.Endpoints<Source, Target> & T,
+      Schema.Simplify<RelationJsonProps & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
+}
 
 /**
- * Relation schema type definitions.
+ * Structural base type for any ECHO relation schema.
+ * Accepts static schemas (created with Type.relation()).
+ * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
+ * Use Type.isRelationSchema() for runtime type guards.
  */
+type RelationSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
+
 export namespace Relation {
   /**
-   * Type that represents an arbitrary schema type of a relation.
-   * NOTE: This is not an instance type.
+   * Type that represents any ECHO relation schema.
+   * Accepts static schemas (Type.relation()).
    */
-  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  export type Any = Schema$.Schema.AnyNoContext;
+  export type Any = RelationSchemaBase;
 
   /**
    * Get relation source type.
@@ -182,9 +315,84 @@ export namespace Relation {
   };
 }
 
+/**
+ * Factory function to create an ECHO relation schema.
+ * Adds relation metadata annotations to an Effect schema.
+ *
+ * @example
+ * ```ts
+ * const WorksFor = Schema.Struct({
+ *   role: Schema.String,
+ * }).pipe(Type.relation({
+ *   typename: 'example.com/type/WorksFor',
+ *   version: '0.1.0',
+ *   source: Person,
+ *   target: Company,
+ * }));
+ * ```
+ */
+export const relation: {
+  <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(
+    opts: EchoRelationSchemaOptions<SourceSchema, TargetSchema>,
+  ): <Self extends Schema.Schema.Any>(
+    self: Self,
+  ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;
+} = EchoRelationSchema as any;
+
+//
+// Entity - Entity schema types (union of Object | Relation)
+//
+
+export namespace Entity {
+  /**
+   * Runtime Effect schema for any ECHO entity (object or relation).
+   * Use for validation, parsing, or type guards on unknown values.
+   *
+   * @example
+   * ```ts
+   * if (Schema.is(Type.Entity.Any)(unknownValue)) {
+   *   // unknownValue is an ECHO entity
+   * }
+   * ```
+   */
+  export const Any: Schema.Schema<
+    { id: ObjectId } & Record<string, unknown>,
+    { id: string } & Record<string, unknown>
+  > = Schema.Union(Obj, Relation);
+
+  /**
+   * Type alias for any ECHO entity schema (object or relation).
+   * Use this in type annotations for schema parameters.
+   */
+  export type Any = Obj.Any | Relation.Any;
+}
+
+/**
+ * Type guard to check if a schema is an object schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.
+ */
+export const isObjectSchema = (schema: Entity.Any): schema is Obj.Any => {
+  return (schema as any)[SchemaKindId] === EntityKind.Object;
+};
+
+/**
+ * Type guard to check if a schema is a relation schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.
+ */
+export const isRelationSchema = (schema: Entity.Any): schema is Relation.Any => {
+  return (schema as any)[SchemaKindId] === EntityKind.Relation;
+};
+
 //
 // Ref
-// TODO(burdon): Reconcile Type.Ref with Ref.Ref.
+//
+// NOTE: `Type.Ref` vs `Ref.Ref`:
+// - `Type.Ref<T>` is the SCHEMA type - a schema that produces `Ref.Ref<T>` instances.
+// - `Ref.Ref<T>` is the INSTANCE type - the actual runtime ref object.
+//
+// Example:
+//   const taskRef: Ref.Ref<Task> = Ref.make(task);  // Instance
+//   const schema: Type.Ref<Task> = Type.Ref(Task);  // Schema
 //
 
 /**
@@ -193,23 +401,49 @@ export namespace Relation {
  * This typedef avoids `TS4023` error (name from external module cannot be used named).
  * See Effect's note on interface types.
  */
-export interface ref<TargetSchema extends Schema$.Schema.Any> extends RefSchema<Schema$.Schema.Type<TargetSchema>> {}
+export interface ref<TargetSchema extends Schema.Schema.Any> extends RefSchema<Schema.Schema.Type<TargetSchema>> {}
 
 /**
- * Ref schema.
+ * Factory function to create a Ref schema for the given target schema.
+ * Use this in schema definitions to declare reference fields.
+ *
+ * @example
+ * ```ts
+ * const Task = Schema.Struct({
+ *   assignee: Type.Ref(Person),  // Creates a Ref schema
+ * }).pipe(Type.object({ typename: 'Task', version: '0.1.0' }));
+ * ```
  */
 export const Ref: RefFn = Ref$;
 
-export interface Ref<T> extends Schema$.SchemaClass<Ref$<T>, EncodedReference> {}
+/**
+ * TypeScript type for a Ref schema.
+ * This is the type of the SCHEMA itself, not the runtime ref instance.
+ * For the instance type, use `Ref.Ref<T>` from the Ref module.
+ *
+ * @example
+ * ```ts
+ * // Schema type annotation (rarely needed, usually inferred):
+ * const refSchema: Type.Ref<Task> = Type.Ref(Task);
+ *
+ * // Instance type annotation (use Ref.Ref instead):
+ * const refInstance: Ref.Ref<Task> = Ref.make(task);
+ * ```
+ */
+export interface Ref<T> extends Schema.SchemaClass<Ref$<T>, EncodedReference> {}
 
 export namespace Ref {
   /**
-   * Type that represents an arbitrary schema type of a reference.
-   * NOTE: This is not an instance type.
+   * Type that represents any Ref schema (with unknown target type).
+   * This is a schema type, not an instance type.
    */
-  export type Any = Schema$.Schema<Ref$<any>, EncodedReference>;
+  export type Any = Schema.Schema<Ref$<any>, EncodedReference>;
 }
 
+//
+// Schema utility functions
+//
+
 /**
  * Gets the full DXN of the schema.
  * Will include the version if it's a `type` DXN.

package/src/index.ts

@@ -2,21 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
+export { QueryAST } from '@dxos/echo-protocol';
+// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
 export { DXN } from '@dxos/keys';
 
-export * from './errors';
-
-// TODO(burdon): Separate namesapces for Query (Query.Query, Query.Filter, etc.)
-export * from './query';
-
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
+export * as Err from './Err';
+export * as Filter from './Filter';
 export * as Format from './Format';
+export * as Hypergraph from './Hypergraph';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
 export * as Obj from './Obj';
+export * as Order from './Order';
+export * as Query from './Query';
+export * as QueryResult from './QueryResult';
 export * as Ref from './Ref';
 export * as Relation from './Relation';
+export * as SchemaRegistry from './SchemaRegistry';
 export * as Tag from './Tag';
 export * as Type from './Type';

package/src/internal/README.md

@@ -11,7 +11,7 @@
 - [x] Entity.Any = Obj.Any | Relation.Any
   - NOTE: Relation does not extend (in not polymorphic with) Obj.
 - [x] import LabelAnnotation => Annotation.LabelAnnotation
-- [x] import Expando => Type.Expando
+- [x] import Expando => @dxos/schema (Expando.Expando)
 - [x] live => Obj.make
 - [x] Rename live => makeObject
 - [x] Rename {EchoObject, EchoRelation} => {EchoObjecSchema, EchoRelationSchema}
@@ -23,30 +23,47 @@
 - [x] TODO(burdon): FIX!!!
 - [x] Fix failing tests.
 - [x] Reconcile types/version with entities/model/version
-- [x] Type.Expando => Obj.Any
+- [x] Expando moved to @dxos/schema
 - [x] Narrow QueryResult and match Schema and Object generics.
 
 2. Clean-up
 
-- [ ] TODO(wittjosiah): Find a simpler way to define this type.
-- [ ] TODO(wittjosiah): Should be Type.obj<...> or equivalent.
-- [ ] Fix Obj.instanceOf(Type.Expando...
-- [ ] Add Obj.Unknown and Relation.Unknown to match Entity.Unknown.
-- [ ] Ref.Array.targets doesn't satisfy Obj.Any because it uses AnyEchoObject.
-- [ ] Add Relation.MakeProps
-- [ ] Schema registry should return Type.Entity.Any instead of Schema.Schema.AnyNoContext.
-- [ ] Remove echo-db/AnyLiveObject<T> => Obj.Obj<T>
+- [x] QueryResult namespace
+- [x] SchemaRegistry interface
+- [x] Schema registry should return Type.Entity.Any instead of Schema.Schema.AnyNoContext.
+- [x] Hypergraph interface
+- [x] Obj.getDatabase
+- [x] SpaceAction.AddObject target should be a db not a space.
+- [x] Add Relation.MakeProps
+- [x] Add Obj.Unknown and Relation.Unknown to match Entity.Unknown.
+- [x] TODO(wittjosiah): Should be Type.obj<...> or equivalent.
+- [x] TODO(wittjosiah): Find a simpler way to define this type.
+- [x] Ref.Array.targets doesn't satisfy Obj.Any because it uses AnyEchoObject.
+- [x] Remove echo-db/AnyLiveObject<T> => Obj.Obj<T>
+- [x] Rename AnyEchoObject => AnyEntity
+- [x] Remove WithId => AnyEntity
+- [x] Remove WithMeta => AnyEntity
+- [x] Obj.Any => Obj.Unknown
+- [x] Relation.Any => Relation.Unknown
+- [x] Ref.Any => Ref.Unknown
+- [x] Obj.AnyProps => Obj.Any
+- [x] Factor Expando out of @dxos/echo (moved to @dxos/schema)
+- [x] Obj.instanceOf works with Expando (tested in @dxos/schema)
+- [x] Obj.Snapshot should be same shape as Obj.Obj but with a different brand
+- [x] Mutators should only work on object after it is made mutable
+
+- [ ] Review usage of Obj.Any, see if it could be stricter
+- [ ] Type.Obj should validate using the echo object brand
+- [ ] Mutable could be a branded type to fix "NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`"
+- [ ] space properties, queues, messagins preventing getSpace from being removed
+- [ ] Schema registry should use Query.Query.
+- [ ] Move EchoSchemaRegistry into hypergraph
 - [ ] Narrow QueryResult and match Schema and Object generics.
+- [ ] BaseSchema
 - [ ] Directly import JSONPath, etc. from @dxos/effect.
-- [ ] DISCUSS: Standradize $ suffix to disambuguate imports (GPT recommended).
-- [ ] Reconcile Type.Ref with Ref.Ref
 - [ ] Promote parts of src/internal/ref to Ref.ts
-- [ ] Rename AnyEchoObject => AnyEntity? (or accept that Object != Obj from naming perspective.)
-- [ ] Remove WithId => AnyEchoObject
-- [ ] Remove WithMeta => AnyEchoObject
-- [ ] BaseSchema
 - [ ] JsonPath, JsonProp, getValue, setValue => Json.Path?
-- [ ] Move EchoSchemaRegistry into hypergraph
+- [ ] DISCUSS: Standradize $ suffix to disambuguate imports (GPT recommended).
 
 3. Audit usage from @dxos/echo-db
 
@@ -81,3 +98,5 @@
 - [ ] Consolidate getters (getType, getSchema, getTypename, getSchemaTypename, etc.)
 - [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
 - [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
+- [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
+- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).

package/src/internal/annotations/annotations.test.ts

@@ -7,7 +7,7 @@ import { describe, test } from 'vitest';
 
 import { EchoObjectSchema } from '../entities';
 
-import { LabelAnnotation, TypenameSchema, VersionSchema, getLabel } from './annotations';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
 const TestObject = Schema.Struct({
@@ -51,7 +51,7 @@ describe('annotations', () => {
     });
   });
 
-  describe('getLabel', () => {
+  describe('getLabelWithSchema', () => {
     test('should return first available label value', ({ expect }) => {
       const obj: TestObject = {
         name: 'Primary Name',
@@ -59,7 +59,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toEqual('Primary Name');
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Primary Name');
     });
 
     test('should fallback to second path if first is undefined', ({ expect }) => {
@@ -69,7 +69,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toEqual('Fallback Name');
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
     });
 
     test('should return undefined if no label paths resolve', ({ expect }) => {
@@ -79,7 +79,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toBeUndefined();
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
     });
 
     test('should return label from echo object', ({ expect }) => {
@@ -90,7 +90,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestEchoSchema, obj)).toEqual('Primary Name');
+      expect(getLabelWithSchema(TestEchoSchema, obj)).toEqual('Primary Name');
     });
   });
 });