@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/SchemaRegistry.ts

@@ -47,7 +47,7 @@ export type Query = {
    * @default false
    *
    * The system schema include but are not limited to:
-   *  - dxos.org/type/Schema
+   *  - org.dxos.type.schema
    */
   includeSystem?: boolean;
 };
@@ -61,7 +61,7 @@ export type Query = {
  * - JSON schema with typename and version
  */
 export type RegisterSchemaInput =
-  | Type.Entity.Any
+  | Type.AnyEntity
   | {
       typename: string;
       version: string;
@@ -72,21 +72,21 @@ export type RegisterSchemaInput =
       name?: string;
     };
 
-export type ExtractQueryResult<Query> = Query extends { location: ('database' | 'runtime')[] }
-  ? Type.Entity.Any
-  : Type.RuntimeType;
-
+// TODO(dmaretskyi): Rename TypeRegistry
 export interface SchemaRegistry {
   /**
    * Checks if the provided schema is registered.
    */
-  // TODO(burdon): Type?
-  hasSchema(schema: Type.Entity.Any): boolean;
+  hasSchema(schema: Type.AnyEntity): boolean;
 
   /**
-   * Registers the provided schema.
+   * Registers the provided schema(s).
    *
-   * @returns Mutable runtime instances of schemas that were registered.
+   * @returns The persisted type entities. The entity kind of each input is
+   * preserved (an object schema comes back as `Type.AnyObj`), so the result can
+   * be chained into `Obj.make` / `Relation.make` without casts. Each stored
+   * schema is also a `Type.Type` record, so its `Ref` targets a
+   * `Ref(Type.Type)` field.
    *
    * 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.
@@ -94,12 +94,8 @@ export interface SchemaRegistry {
    * 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[]>;
+  register<T extends Type.AnyEntity>(input: T[]): Promise<T[]>;
+  register(input: RegisterSchemaInput[]): Promise<Type.Type[]>;
 
-  /**
-   *
-   */
-  query<Q extends Types.NoExcessProperties<Query, Q>>(
-    query?: Q & Query,
-  ): QueryResult.QueryResult<ExtractQueryResult<Q>>;
+  query<Q extends Types.NoExcessProperties<Query, Q>>(query?: Q & Query): QueryResult.QueryResult<Type.Type>;
 }

package/src/Tag.ts

@@ -2,9 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation, SystemTypeAnnotation } from './internal';
+import { DXN } from '@dxos/keys';
+
+import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
 
@@ -12,19 +16,15 @@ export const Tag = Schema.Struct({
   label: Schema.String,
   hue: Schema.optional(Schema.String), // TODO(burdon): Color name?
 }).pipe(
-  Type.object({
-    typename: 'dxos.org/type/Tag',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['label']),
-  SystemTypeAnnotation.set(true),
+  internal.LabelAnnotation.set(['label']),
+  internal.SystemTypeAnnotation.set(true),
+  Type.makeObject(DXN.make('org.dxos.type.tag', '0.1.0')),
 );
 
-export type Tag = Schema.Schema.Type<typeof Tag>;
+export type Tag = Type.InstanceType<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

@@ -5,48 +5,193 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import * as Entity from './Entity';
+import * as JsonSchema from './JsonSchema';
 import * as Obj from './Obj';
 import * as Relation from './Relation';
 import { TestSchema } from './testing';
 import * as Type from './Type';
 
 describe('Type', () => {
-  describe('Type.Obj', () => {
-    test('has SchemaKindId for schema type checking', ({ expect }) => {
-      // Type.isObjectSchema uses SchemaKindId to check if a schema is an object schema.
-      expect(Type.isObjectSchema(Type.Obj)).toBe(true);
-      expect(Type.isObjectSchema(TestSchema.Person)).toBe(true);
-      expect(Type.isObjectSchema(Type.Relation)).toBe(false);
-    });
-
+  describe('Obj.Unknown schema', () => {
     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(Type.Obj)({ id: 'plain-object' })).toBe(true);
+      // Schema.is does structural validation (has id field). `Obj.Unknown` IS
+      // a raw Effect Schema (branded with EchoSchemaKind), so pass it directly.
+      expect(Schema.is(Obj.Unknown)({ id: 'plain-object' })).toBe(true);
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-      expect(Schema.is(Type.Obj)(obj)).toBe(true);
+      expect(Schema.is(Obj.Unknown)(obj)).toBe(true);
     });
   });
 
-  describe('Type.Relation', () => {
-    test('has SchemaKindId for schema type checking', ({ expect }) => {
-      // Type.isRelationSchema uses SchemaKindId to check if a schema is a relation schema.
-      expect(Type.isRelationSchema(Type.Relation)).toBe(true);
-      expect(Type.isRelationSchema(TestSchema.HasManager)).toBe(true);
-      expect(Type.isRelationSchema(Type.Obj)).toBe(false);
-    });
-
+  describe('Relation.Unknown schema', () => {
     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(Type.Relation)({ id: 'plain-object' })).toBe(true);
+      // Schema.is does structural validation (has id field). `Relation.Unknown`
+      // IS a raw Effect Schema (branded with EchoSchemaKind), so pass it directly.
+      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(Type.Relation)(rel)).toBe(true);
+      expect(Schema.is(Relation.Unknown)(rel)).toBe(true);
+    });
+  });
+
+  describe('Type.Type meta-schema', () => {
+    test('Type.Type is branded as the type entity kind', ({ expect }) => {
+      // The Type.Type entity itself is an in-memory object (KindId=Object) that
+      // *declares* a type-kind schema (SchemaKindId=Type).
+      expect(Type.isTypeKindSchema(Type.Type)).toBe(true);
+      expect(Type.isObject(Type.Type)).toBe(false);
+      expect(Type.isRelation(Type.Type)).toBe(false);
+    });
+
+    test('static object/relation types are not type-kind', ({ expect }) => {
+      expect(Type.isTypeKindSchema(TestSchema.Person)).toBe(false);
+      expect(Type.isTypeKindSchema(TestSchema.HasManager)).toBe(false);
+    });
+
+    test('Type.getMeta(Type.Type) reports key/version of the meta-schema', ({ expect }) => {
+      // `Type.getMeta` returns the entity's `ObjectMeta`. For the static
+      // `Type.Type` meta-schema entity the key/version reflect its registry
+      // identity. The schema-kind brand is on `[SchemaKindId]`, not in meta.
+      const meta = Type.getMeta(Type.Type);
+      expect(meta.key).toBe('org.dxos.type.schema');
+      expect(meta.version).toBe('0.1.0');
+      expect(Type.isTypeKindSchema(Type.Type)).toBe(true);
+    });
+
+    test('Type.getURI(Type.Type) returns the meta-schema DXN', ({ expect }) => {
+      expect(Type.getURI(Type.Type).toString()).toBe('dxn:org.dxos.type.schema:0.1.0');
+    });
+  });
+
+  describe('Type.makeObjectFromJsonSchema', () => {
+    test('creates an instance branded KindId=type', ({ expect }) => {
+      const entity = Type.makeObjectFromJsonSchema({
+        typename: 'com.example.type.test',
+        version: '0.1.0',
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.Number })),
+      });
+      expect((entity as any)[Entity.KindId]).toBe(Entity.Kind.Type);
+      // `typename` / `version` are not direct fields on a persisted `Type.Type`;
+      // they live in `ObjectMeta` (the canonical registry-provenance pair).
+      // Read them via the helpers (or `Type.getMeta`).
+      expect(Type.getTypename(entity)).toBe('com.example.type.test');
+      expect(Type.getVersion(entity)).toBe('0.1.0');
+      expect(entity.jsonSchema).toBeDefined();
+    });
+
+    test('defaults version to 0.0.0 for drafts', ({ expect }) => {
+      const draft = Type.makeObjectFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.String })),
+      });
+      // Drafts default version to `'0.0.0'` in `ObjectMeta.version`; the
+      // typename (`ObjectMeta.key`) is undefined until set.
+      expect(Type.getVersion(draft)).toBe('0.0.0');
+      const meta = Type.getMeta(draft);
+      expect(meta.key).toBeUndefined();
+      expect(meta.version).toBe('0.0.0');
+    });
+
+    test('assigns a stable id', ({ expect }) => {
+      const a = Type.makeObjectFromJsonSchema({ jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})) });
+      const b = Type.makeObjectFromJsonSchema({ jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})) });
+      expect(typeof a.id).toBe('string');
+      expect(a.id).not.toBe(b.id);
+    });
+
+    test('result satisfies isType', ({ expect }) => {
+      const entity = Type.makeObjectFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ field: Schema.Number })),
+      });
+      expect(Type.isType(entity)).toBe(true);
+    });
+  });
+
+  describe('Type.makeRelationFromJsonSchema', () => {
+    test('embeds source/target DXNs into jsonSchema', ({ expect }) => {
+      const entity = Type.makeRelationFromJsonSchema({
+        typename: 'com.example.type.testRel',
+        version: '0.1.0',
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({ note: Schema.String })),
+        source: TestSchema.Person,
+        target: TestSchema.Organization,
+      });
+      expect((entity as any)[Entity.KindId]).toBe(Entity.Kind.Type);
+      expect(entity.jsonSchema.entityKind).toBe(Entity.Kind.Relation);
+      expect((entity.jsonSchema as any).relationSource?.$ref).toBe(Type.getURI(TestSchema.Person).toString());
+      expect((entity.jsonSchema as any).relationTarget?.$ref).toBe(Type.getURI(TestSchema.Organization).toString());
+    });
+
+    test('accepts Obj.Unknown as source/target', ({ expect }) => {
+      const entity = Type.makeRelationFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})),
+        source: Obj.Unknown,
+        target: Obj.Unknown,
+      });
+      const unknownURI = 'dxn:org.dxos.schema.anyObject:0.0.0';
+      expect((entity.jsonSchema as any).relationSource?.$ref).toBe(unknownURI);
+      expect((entity.jsonSchema as any).relationTarget?.$ref).toBe(unknownURI);
+    });
+
+    test('defaults version to 0.0.0 for drafts', ({ expect }) => {
+      const draft = Type.makeRelationFromJsonSchema({
+        jsonSchema: JsonSchema.toJsonSchema(Schema.Struct({})),
+        source: TestSchema.Person,
+        target: TestSchema.Person,
+      });
+      expect(Type.getVersion(draft)).toBe('0.0.0');
+      const meta = Type.getMeta(draft);
+      expect(meta.key).toBeUndefined();
+      expect(meta.version).toBe('0.0.0');
+    });
+  });
+
+  describe('Obj/Relation/Entity.getType', () => {
+    test('Obj.getType returns the static type entity for instances of Type.makeObject', ({ expect }) => {
+      const person = Obj.make(TestSchema.Person, { name: 'Alice' });
+      expect(Obj.getType(person)).toBe(TestSchema.Person);
+    });
+
+    test('Relation.getType returns the static type entity for instances of Type.makeRelation', ({ expect }) => {
+      const a = Obj.make(TestSchema.Person, { name: 'A' });
+      const b = Obj.make(TestSchema.Person, { name: 'B' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: a,
+        [Relation.Target]: b,
+      });
+      expect(Relation.getType(rel)).toBe(TestSchema.HasManager);
+    });
+
+    test('Entity.getType narrows uniformly across object/relation instances', ({ expect }) => {
+      const person = Obj.make(TestSchema.Person, { name: 'A' });
+      const a = Obj.make(TestSchema.Person, { name: 'A' });
+      const b = Obj.make(TestSchema.Person, { name: 'B' });
+      const rel = Relation.make(TestSchema.HasManager, {
+        [Relation.Source]: a,
+        [Relation.Target]: b,
+      });
+      expect(Entity.getType(person)).toBe(TestSchema.Person);
+      expect(Entity.getType(rel)).toBe(TestSchema.HasManager);
+    });
+  });
+
+  describe('static type factories', () => {
+    test('Type.makeObject stamps schema-kind=object', ({ expect }) => {
+      expect((TestSchema.Person as any)['~@dxos/echo/SchemaKind']).toBe(Entity.Kind.Object);
+      expect(Type.isObject(TestSchema.Person)).toBe(true);
+    });
+
+    test('Type.makeRelation stamps schema-kind=relation', ({ expect }) => {
+      expect((TestSchema.HasManager as any)['~@dxos/echo/SchemaKind']).toBe(Entity.Kind.Relation);
+      expect(Type.isRelation(TestSchema.HasManager)).toBe(true);
+    });
+
+    test('Type.getURI returns the DXN for static types', ({ expect }) => {
+      expect(Type.getURI(TestSchema.Person).toString()).toBe('dxn:com.example.type.person:0.1.0');
+      expect(Type.getURI(TestSchema.HasManager).toString()).toBe('dxn:com.example.type.hasManager:0.1.0');
     });
   });
 });