@dxos/echo 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

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

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Type from './Type';
+
+export const Tag = Schema.Struct({
+  label: Schema.String,
+  hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.tag',
+    version: '0.1.0',
+  }),
+  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);
+
+export type Map = Record<string, Tag>;
+
+export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
+
+export const createTagList = (tags: Map): Tag[] =>
+  Object.entries(tags)
+    .map(([id, tag]) => ({ ...tag, id }))
+    .sort(sortTags);
+
+export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undefined => {
+  const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
+  return entry ? { ...entry[1], id: entry[0] } : undefined;
+};

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,213 +2,231 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
-import { type Simplify } from 'effect/Schema';
+// @import-as-namespace
+
+import type * as Schema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
-import * as EchoSchema from '@dxos/echo-schema';
-import { type ToMutable } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
-import type * as Keys from '@dxos/keys';
+import { type DXN } from '@dxos/keys';
+import { type ToMutable } from '@dxos/util';
 
+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';
 
-//
-// Kind
-//
-
-export const KindId: unique symbol = EchoSchema.EntityKindId as any;
-export type KindId = typeof KindId;
-
-export const Kind = EchoSchema.EntityKind;
-
 /**
- * Assigns a kind to an Object or Relation instance.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-// NOTE: Needed to make `isRelation` and `isObject` checks work.
-export interface OfKind<Kind extends EchoSchema.EntityKind> {
-  readonly id: Keys.ObjectId;
-  readonly [KindId]: Kind;
-}
+export const RuntimeType = typeInternal.EchoSchema;
 
 /**
- * Base ECHO schema type.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export type Schema = EchoSchema.EchoSchema;
+export type RuntimeType = typeInternal.EchoSchema;
+
+//
+// Internal types (not exported)
+//
 
 /**
- * Returns all properties of an object or relation except for the id and kind.
+ * Type that marks a schema as an ECHO schema.
+ * The value indicates the entity kind (Object or Relation).
  */
-export type Properties<T = any> = Omit<T, 'id' | KindId | RelationModule.Source | RelationModule.Target>;
+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.
  *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * @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 interface obj<Self extends Schema.Schema.Any>
-  extends EchoSchema.TypeMeta,
+export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Object>,
     Schema.AnnotableClass<
-      obj<Self>,
-      OfKind<EchoSchema.EntityKind.Object> & ToMutable<Schema.Schema.Type<Self>>,
-      Simplify<ObjJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
-      Schema.Schema.Context<Self>
-    > {}
+      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: EchoSchema.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => obj<Self>;
-} = EchoSchema.EchoObject 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 = Schema.Schema.AnyNoContext;
-}
-
-//
-// Expando
-//
-
-// TODO(burdon): We're using Expando in many places as a base type.
-export interface Expando extends OfKind<EchoSchema.EntityKind.Object> {
-  [key: string]: any;
-}
-
-type ExpandoEncoded = Simplify<ObjJsonProps & { [key: string]: any }>;
+export type AnyObj = ObjectSchemaBase;
 
-export const Expando: Schema.Schema<Expando, ExpandoEncoded, never> = EchoSchema.Expando as any;
+/**
+ * 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;
 
 //
-// Relation
+// PersistentType (Schema stored in database)
 //
 
-interface RelationJsonProps {
-  id: string;
-  [EchoSchema.ATTR_RELATION_SOURCE]: string;
-  [EchoSchema.ATTR_RELATION_TARGET]: string;
-}
+export const PersistentType: Obj<typeInternal.PersistentSchema> = typeInternal.PersistentSchema as any;
+
+export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
 /**
- * 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.
- */
-export interface relation<
-  Self extends Schema.Schema.Any,
-  SourceSchema extends Schema.Schema.Any,
-  TargetSchema extends Schema.Schema.Any,
-> extends EchoSchema.TypeMeta,
+ * 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<Self, SourceSchema, TargetSchema>,
-      OfKind<EchoSchema.EntityKind.Relation> &
-        Relation.Endpoints<Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>> &
-        ToMutable<Schema.Schema.Type<Self>>,
-      Simplify<RelationJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
-      Schema.Schema.Context<Self>
-    > {}
+      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;
+}
 
 /**
- * Relation schema.
+ * 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.
  */
-// TODO(dmaretskyi): I have to redefine the type here so that the definition uses symbols from @dxos/echo/Relation.
-export const Relation: {
-  <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(
-    opts: EchoSchema.EchoRelationOptions<Source, Target>,
-  ): <Self extends Schema.Schema.Any>(self: Self) => relation<Self, Source, Target>;
-} = EchoSchema.EchoRelation as any;
+type RelationSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
 
 /**
- * Relation schema type definitions.
+ * Type that represents any ECHO relation schema.
+ * Accepts static schemas (Type.relation()).
  */
-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;
+export type AnyRelation = RelationSchemaBase;
 
-  /**
-   * 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> = {
-    [RelationModule.Source]: Source;
-    [RelationModule.Target]: Target;
-  };
-}
+/**
+ * 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 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
-//
+/**
+ * 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 EchoSchema.Ref$<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: <S extends Obj.Any>(schema: S) => ref<S> = EchoSchema.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<EchoSchema.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>;
 
-// TODO(buurdon): Move to Ref?
-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<EchoSchema.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: Obj.Any | Relation.Any): Keys.DXN | undefined => {
-  return EchoSchema.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: Obj.Any | Relation.Any): string => {
-  const typename = EchoSchema.getSchemaTypename(schema);
+export const getTypename = (schema: AnyEntity): string => {
+  const typename = internal.getSchemaTypename(schema);
   invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');
   return typename;
 };
@@ -217,8 +235,8 @@ export const getTypename = (schema: Obj.Any | Relation.Any): string => {
  * Gets the version of the schema.
  * @example 0.1.0
  */
-export const getVersion = (schema: Obj.Any | Relation.Any): string => {
-  const version = EchoSchema.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;
 };
@@ -226,21 +244,16 @@ export const getVersion = (schema: Obj.Any | Relation.Any): string => {
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = EchoSchema.isMutable;
+export const isMutable = typeInternal.isMutable;
 
 /**
  * ECHO type metadata.
  */
-export type Meta = EchoSchema.TypeAnnotation;
+export type Meta = internal.TypeAnnotation;
 
 /**
  * Gets the meta data of the schema.
  */
-export const getMeta = (schema: Obj.Any | Relation.Any): Meta | undefined => {
-  return EchoSchema.getTypeAnnotation(schema);
+export const getMeta = (schema: AnyEntity): Meta | undefined => {
+  return internal.getTypeAnnotation(schema);
 };
-
-// TODO(dmaretskyi): Remove re-exports.
-export { SpaceId, ObjectId, DXN } from '@dxos/keys';
-
-export { Format, JsonSchemaType as JsonSchema, toEffectSchema, toJsonSchema } from '@dxos/echo-schema';