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

package/src/SchemaRegistry.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Types from 'effect/Types';
+
+import type * as JsonSchema from './JsonSchema';
+import type * as Key from './Key';
+import type * as QueryResult from './QueryResult';
+import type * as Type from './Type';
+
+// TODO(wittjosiah): Replace w/ Query.Query.
+export type Query = {
+  /**
+   * Filter by schema ID.
+   * Schema id is a DXN with `echo` or `type` kind.
+   */
+  id?: string | string[];
+
+  /**
+   * Id of the backing ECHO object.
+   */
+  backingObjectId?: Key.ObjectId | Key.ObjectId[];
+
+  /**
+   * One or more typenames to filter by.
+   */
+  typename?: string | string[];
+
+  /**
+   * [Semver Range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges) for the schema version.
+   */
+  version?: string;
+
+  /**
+   * Where to look for the schema.
+   *
+   * Database schema are stored in the database of the current space.
+   * Runtime schema are registered in the runtime.
+   *
+   * @default ['database']
+   */
+  location?: ('database' | 'runtime')[];
+
+  /**
+   * Include system schemas.
+   * @default false
+   *
+   * The system schema include but are not limited to:
+   *  - org.dxos.type.schema
+   */
+  includeSystem?: boolean;
+};
+
+/**
+ * Input for schema registration.
+ * The typename, version and schema mutability metadata is read from the schema annotations.
+ *
+ * Accepts:
+ * - Branded ECHO schemas created with Type.Obj() or Type.Relation()
+ * - JSON schema with typename and version
+ */
+export type RegisterSchemaInput =
+  | Type.AnyEntity
+  | {
+      typename: string;
+      version: string;
+      jsonSchema: JsonSchema.JsonSchema;
+      /**
+       * Display name of the schema.
+       */
+      name?: string;
+    };
+
+export type ExtractQueryResult<Query> = Query extends { location: ('database' | 'runtime')[] }
+  ? Type.AnyEntity
+  : Type.RuntimeType;
+
+// TODO(dmaretskyi): Rename TypeRegistry
+export interface SchemaRegistry {
+  /**
+   * Checks if the provided schema is registered.
+   */
+  // TODO(burdon): Type?
+  hasSchema(schema: Type.AnyEntity): boolean;
+
+  /**
+   * Registers the provided schema.
+   *
+   * @returns Mutable runtime instances of schemas that were registered.
+   *
+   * The behavior of this method depends on the state of the database.
+   * The general principle is that the schema will be upserted into the space.
+   * If an equivalent schema with the same name and version already exists, the method does nothing.
+   * If a different schema with the same name and version exists, the method throws an error.
+   * If no schema with the same name and version exists, a new schema will be inserted based on semantic versioning rules.
+   */
+  register(input: RegisterSchemaInput[]): Promise<Type.RuntimeType[]>;
+
+  /**
+   *
+   */
+  query<Q extends Types.NoExcessProperties<Query, Q>>(
+    query?: Q & Query,
+  ): QueryResult.QueryResult<ExtractQueryResult<Q>>;
+}

package/src/Tag.ts

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation, SystemTypeAnnotation } from './internal';
+import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
 
@@ -12,19 +14,18 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Tag',
+  Type.object({
+    typename: 'org.dxos.type.tag',
     version: '0.1.0',
   }),
-  LabelAnnotation.set(['label']),
-  SystemTypeAnnotation.set(true),
+  internal.LabelAnnotation.set(['label']),
+  internal.SystemTypeAnnotation.set(true),
 );
 
 export type Tag = Schema.Schema.Type<typeof Tag>;
 
 export const make = (props: Obj.MakeProps<typeof Tag>) => Obj.make(Tag, props);
 
-// TODO(burdon): Rename Map.
 export type Map = Record<string, Tag>;
 
 export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);

package/src/Type.test.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import * as Obj from './Obj';
+import * as Relation from './Relation';
+import { TestSchema } from './testing';
+import * as Type from './Type';
+
+describe('Type', () => {
+  describe('Obj.Unknown schema', () => {
+    test('has SchemaKindId for schema type checking', ({ expect }) => {
+      // Type.isObjectSchema uses SchemaKindId to check if a schema is an object schema.
+      expect(Type.isObjectSchema(Obj.Unknown)).toBe(true);
+      expect(Type.isObjectSchema(TestSchema.Person)).toBe(true);
+      expect(Type.isObjectSchema(Relation.Unknown)).toBe(false);
+    });
+
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field).
+      // It accepts both ECHO objects and plain objects with compatible structure.
+      expect(Schema.is(Obj.Unknown)({ id: 'plain-object' })).toBe(true);
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      expect(Schema.is(Obj.Unknown)(obj)).toBe(true);
+    });
+  });
+
+  describe('Relation.Unknown schema', () => {
+    test('has SchemaKindId for schema type checking', ({ expect }) => {
+      // Type.isRelationSchema uses SchemaKindId to check if a schema is a relation schema.
+      expect(Type.isRelationSchema(Relation.Unknown)).toBe(true);
+      expect(Type.isRelationSchema(TestSchema.HasManager)).toBe(true);
+      expect(Type.isRelationSchema(Obj.Unknown)).toBe(false);
+    });
+
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // Schema.is does structural validation (has id field).
+      // It accepts both ECHO relations and plain objects with compatible structure.
+      expect(Schema.is(Relation.Unknown)({ id: 'plain-object' })).toBe(true);
+      const obj1 = Obj.make(TestSchema.Person, { name: 'Alice' });
+      const obj2 = Obj.make(TestSchema.Person, { name: 'Bob' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: obj1,
+        [Relation.Target]: obj2,
+      });
+      expect(Schema.is(Relation.Unknown)(rel)).toBe(true);
+    });
+  });
+});

package/src/Type.ts

@@ -2,230 +2,231 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as Schema$ from 'effect/Schema';
+// @import-as-namespace
+
+import type * 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 ToMutable } from '@dxos/util';
 
-import type * as Entity$ from './Entity';
-import {
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
-  EchoObjectSchema,
-  EchoRelationSchema,
-  type EchoRelationSchemaOptions,
-  EchoSchema,
-  Expando as Expando$,
-  type ExpandoEncoded,
-  PersistentSchema,
-  type PersistentSchemaEncoded,
-  Ref as Ref$,
-  type RefFn,
-  type RefSchema,
-  type TypeAnnotation,
-  type TypeMeta,
-  getSchemaDXN,
-  getSchemaTypename,
-  getSchemaVersion,
-  getTypeAnnotation,
-  isMutable as isMutable$,
-  toEffectSchema,
-  toJsonSchema,
-} from './internal';
-import type * as Relation$ from './Relation';
+import type * as Entity from './Entity';
+import * as internal from './internal';
+import * as typeInternal from './internal/Type';
+import type * as ObjModule from './Obj';
+import type * as RelationModule from './Relation';
 
-// TODO(burdon): Remove toEffectSchema, toJsonSchema (moved to JsonSchema export).
-export { toEffectSchema, toJsonSchema };
+/**
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
+ */
+export const RuntimeType = typeInternal.EchoSchema;
 
 /**
- * Returns all properties of an object or relation except for the id and kind.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export type Properties<T = any> = Omit<T, 'id' | Entity$.KindId | Relation$.Source | Relation$.Target>;
+export type RuntimeType = typeInternal.EchoSchema;
 
 //
-// 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 internal.EntityKind = internal.EntityKind> = {
+  readonly [internal.SchemaKindId]: K;
+};
 
 //
-// Obj
+// Obj - Runtime schema for any ECHO object
 //
 
-interface ObjJsonProps {
-  id: string;
-}
-
 /**
- * Return type of the `Obj` schema constructor.
+ * 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' }));
  *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * // Access fields for introspection:
+ * Object.keys(PersonSchema.fields); // ['name']
+ * ```
  */
-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>
-    > {}
+export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Object>,
+    Schema.AnnotableClass<
+      Obj<T, Fields>,
+      Entity.OfKind<typeof Entity.Kind.Object> & T,
+      Schema.Simplify<ObjModule.BaseObjJson & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
+}
 
 /**
- * Object schema.
+ * 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 const Obj: {
-  (opts: TypeMeta): <Self extends Schema$.Schema.Any>(self: Self) => obj<Self>;
-} = EchoObjectSchema as any;
+type ObjectSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
 
 /**
- * Object schema type definitions.
+ * Type that represents any ECHO object schema.
+ * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
  */
-export declare namespace Obj {
-  /**
-   * Type that represents an arbitrary schema type of an object.
-   * NOTE: This is not an instance type.
-   */
-  // 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 AnyObj = 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: 'com.example.type.person', version: '0.1.0' }));
+ * ```
+ */
+export const object: {
+  (opts: internal.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
+} = internal.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<typeInternal.PersistentSchema> = typeInternal.PersistentSchema as any;
 
-export { EchoSchema as RuntimeType };
+export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
-//
-// Relation
-//
-
-interface RelationJsonProps {
-  id: string;
-  [ATTR_RELATION_SOURCE]: string;
-  [ATTR_RELATION_TARGET]: string;
+/**
+ * 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.
+ */
+export interface Relation<T, Source, Target, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Relation>,
+    Schema.AnnotableClass<
+      Relation<T, Source, Target, Fields>,
+      Entity.OfKind<typeof Entity.Kind.Relation> & RelationModule.Endpoints<Source, Target> & T,
+      Schema.Simplify<RelationModule.BaseRelationJson & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
 }
 
 /**
- * Return type of the `Relation` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * 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.
  */
-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>
-    > {}
+type RelationSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
 
 /**
- * Relation schema.
+ * Type that represents any ECHO relation schema.
+ * Accepts static schemas (Type.relation()).
  */
-// 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 type AnyRelation = RelationSchemaBase;
 
 /**
- * Relation schema type definitions.
+ * 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: 'com.example.type.works-for',
+ *   version: '0.1.0',
+ *   source: Person,
+ *   target: Company,
+ * }));
+ * ```
  */
-export namespace Relation {
-  /**
-   * Type that represents an arbitrary schema type of a relation.
-   * NOTE: This is not an instance type.
-   */
-  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  export type Any = Schema$.Schema.AnyNoContext;
-
-  /**
-   * Get relation source type.
-   */
-  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;
-
-  /**
-   * Get relation target type.
-   */
-  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;
-
-  export type Endpoints<Source, Target> = {
-    [Relation$.Source]: Source;
-    [Relation$.Target]: Target;
-  };
-}
+export const relation: {
+  <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(
+    opts: internal.EchoRelationSchemaOptions<SourceSchema, TargetSchema>,
+  ): <Self extends Schema.Schema.Any>(
+    self: Self,
+  ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;
+} = internal.EchoRelationSchema as any;
 
-//
-// Ref
-// TODO(burdon): Reconcile Type.Ref with Ref.Ref.
-//
+/**
+ * Type alias for any ECHO entity schema (object or relation).
+ * Use this in type annotations for schema parameters.
+ */
+export type AnyEntity = AnyObj | AnyRelation;
 
 /**
- * Return type of the `Ref` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * Type guard to check if a schema is an object schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.
  */
-export interface ref<TargetSchema extends Schema$.Schema.Any> extends RefSchema<Schema$.Schema.Type<TargetSchema>> {}
+export const isObjectSchema = (schema: AnyEntity): schema is AnyObj => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Object;
+};
 
 /**
- * Ref schema.
+ * Type guard to check if a schema is a relation schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.
  */
-export const Ref: RefFn = Ref$;
+export const isRelationSchema = (schema: AnyEntity): schema is AnyRelation => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Relation;
+};
 
-export interface Ref<T> extends Schema$.SchemaClass<Ref$<T>, EncodedReference> {}
+/**
+ * Type that represents any Ref schema (with unknown target type).
+ * This is a schema type, not an instance type.
+ */
+export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
 
-export namespace Ref {
-  /**
-   * Type that represents an arbitrary schema type of a reference.
-   * NOTE: This is not an instance type.
-   */
-  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.
- * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:com.example.type.person:0.1.0"
  * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
  */
-export const getDXN = (schema: Entity.Any): DXN | undefined => {
-  return getSchemaDXN(schema);
+export const getDXN = (schema: AnyEntity): DXN | undefined => {
+  return internal.getSchemaDXN(schema);
 };
 
 /**
  * @param schema - Schema to get the typename from.
- * @returns The typename of the schema. Example: `example.com/type/Person`.
+ * @returns The typename of the schema. Example: `com.example.type.person`.
  */
-export const getTypename = (schema: Entity.Any): string => {
-  const typename = getSchemaTypename(schema);
+export const getTypename = (schema: AnyEntity): string => {
+  const typename = internal.getSchemaTypename(schema);
   invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');
   return typename;
 };
@@ -234,8 +235,8 @@ export const getTypename = (schema: Entity.Any): string => {
  * Gets the version of the schema.
  * @example 0.1.0
  */
-export const getVersion = (schema: Entity.Any): string => {
-  const version = getSchemaVersion(schema);
+export const getVersion = (schema: AnyEntity): string => {
+  const version = internal.getSchemaVersion(schema);
   invariant(typeof version === 'string' && version.match(/^\d+\.\d+\.\d+$/), 'Invalid version');
   return version;
 };
@@ -243,16 +244,16 @@ export const getVersion = (schema: Entity.Any): string => {
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = isMutable$;
+export const isMutable = typeInternal.isMutable;
 
 /**
  * ECHO type metadata.
  */
-export type Meta = TypeAnnotation;
+export type Meta = internal.TypeAnnotation;
 
 /**
  * Gets the meta data of the schema.
  */
-export const getMeta = (schema: Entity.Any): Meta | undefined => {
-  return getTypeAnnotation(schema);
+export const getMeta = (schema: AnyEntity): Meta | undefined => {
+  return internal.getTypeAnnotation(schema);
 };