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

package/src/SchemaRegistry.ts

@@ -0,0 +1,101 @@
+//
+// 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;
+    };
+
+// TODO(dmaretskyi): Rename TypeRegistry
+export interface SchemaRegistry {
+  /**
+   * Checks if the provided schema is registered.
+   */
+  hasSchema(schema: Type.AnyEntity): boolean;
+
+  /**
+   * Registers the provided schema(s).
+   *
+   * @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.
+   * 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<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<Type.Type>;
+}

package/src/{query/tag.ts → Tag.ts}

@@ -2,36 +2,39 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation } from '../internal';
-import * as Obj from '../Obj';
-import * as Type from '../Type';
+import { DXN } from '@dxos/keys';
+
+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.Obj({
-    typename: 'dxos.org/type/Tag',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['label']),
+  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);
 
-export type TagMap = Record<string, Tag>;
+export type Map = Record<string, Tag>;
 
 export const sortTags = ({ label: a }: Tag, { label: b }: Tag) => a.localeCompare(b);
 
-export const createTagList = (tags: TagMap): Tag[] =>
+export const createTagList = (tags: Map): Tag[] =>
   Object.entries(tags)
     .map(([id, tag]) => ({ ...tag, id }))
     .sort(sortTags);
 
-export const findTagByLabel = (tags: TagMap | undefined, name: string): Tag | undefined => {
+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,197 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+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('Obj.Unknown schema', () => {
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // 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(Obj.Unknown)(obj)).toBe(true);
+    });
+  });
+
+  describe('Relation.Unknown schema', () => {
+    test('Schema.is validates structural compatibility only', ({ expect }) => {
+      // 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(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');
+    });
+  });
+});