@dxos/echo 0.8.4-main.d05539e30a → 0.8.4-main.d9fc60f731

package/src/TagIndex.test.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, expect, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import * as Obj from './Obj';
+import * as TagIndex from './TagIndex';
+import * as Type from './Type';
+
+/** A minimal item standing in for an immutable feed object. */
+const Item = Schema.Struct({
+  text: Schema.String,
+}).pipe(Type.makeObject(DXN.make('org.dxos.test.TagIndexItem', '0.1.0')));
+
+/** A host object carrying a tag index alongside (a notional feed of) items. */
+const Host = Schema.Struct({
+  tags: TagIndex.field(),
+}).pipe(Type.makeObject(DXN.make('org.dxos.test.TagIndexHost', '0.1.0')));
+
+describe('TagIndex', () => {
+  test('sets, unsets, and inverts feed-object tags', () => {
+    const host = Obj.make(Host, {});
+    const tags = TagIndex.bind(host, 'tags');
+
+    const a = Obj.make(Item, { text: 'a' });
+    const b = Obj.make(Item, { text: 'b' });
+    const urgent = 'dxn:tag:urgent';
+    const later = 'dxn:tag:later';
+
+    tags.setTag(urgent, a.id);
+    tags.setTag(urgent, b.id);
+    tags.setTag(later, b.id);
+    // Idempotent.
+    tags.setTag(urgent, a.id);
+
+    // Filter the feed by tag: tag -> object ids.
+    expect([...tags.objects(urgent)]).toEqual([a.id, b.id]);
+    expect([...tags.objects(later)]).toEqual([b.id]);
+    expect([...tags.objects('dxn:tag:missing')]).toEqual([]);
+
+    // Inverse: object -> tag ids.
+    expect(tags.tags(b.id).sort()).toEqual([later, urgent]);
+    expect(tags.tags(a.id)).toEqual([urgent]);
+    expect(tags.tagIds().sort()).toEqual([later, urgent]);
+
+    // Unset prunes the membership; emptying a tag drops the key.
+    tags.unsetTag(urgent, a.id);
+    expect([...tags.objects(urgent)]).toEqual([b.id]);
+    tags.unsetTag(urgent, b.id);
+    expect([...tags.objects(urgent)]).toEqual([]);
+    expect(tags.tagIds()).toEqual([later]);
+  });
+});

package/src/TagIndex.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { FormInputAnnotation } from './internal';
+import * as Obj from './Obj';
+
+/**
+ * An inverse tag index: an in-document `Record<tagId, objectId[]>` mapping a tag id to the ids of
+ * the objects carrying that tag.
+ *
+ * Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of tag ids).
+ * Immutable feed/queue objects cannot carry their own meta, so this index — managed alongside the
+ * feed on its host object — augments that same process for them. Tags are sparse, so keying by tag
+ * id (rather than object id) keeps the index small and makes "filter the feed by tag" a single
+ * lookup.
+ *
+ * The tag id is an existing {@link Tag} object's id/URI; labels are never duplicated here — they
+ * live on the {@link Tag} object and stay editable in one place.
+ */
+
+/** Read/write accessor over a host object's tag-index field, bound to a single field key. */
+export interface Accessor {
+  /** All tag ids present in the index. */
+  tagIds(): string[];
+  /** Object ids carrying the given tag; `[]` when the tag is absent (filter the feed by tag). */
+  objects(tagId: string): readonly string[];
+  /** Inverse lookup: the tag ids applied to the given object id. */
+  tags(objectId: string): string[];
+  /** Applies a tag to an object (creating the tag entry when absent); idempotent. */
+  setTag(tagId: string, objectId: string): void;
+  /** Removes a tag from an object, pruning the tag entry when it empties. */
+  unsetTag(tagId: string, objectId: string): void;
+}
+
+/**
+ * Schema fragment for a tag-index field. Splice into a host Struct. Optional record, hidden from
+ * forms. Keyed by tag id; the value is the array of object ids carrying that tag.
+ */
+export const field = () =>
+  Schema.Record({ key: Schema.String, value: Schema.Array(Obj.ID) }).pipe(
+    FormInputAnnotation.set(false),
+    Schema.optional,
+  );
+
+/** Binds an {@link Accessor} over `host[key]`; all mutations go through `Obj.update`. */
+export const bind = (host: Obj.Any, key: string): Accessor => {
+  type Record_ = Record<string, string[]>;
+
+  // The field is addressed by a runtime key, so the ECHO object is viewed as a keyed record — a
+  // deliberate type-system boundary (dynamic field access — the field name is a parameter).
+  const asView = (obj: Obj.Any) => obj as unknown as Record<string, Record_ | undefined>;
+  const read = (): Record_ => asView(host)[key] ?? {};
+
+  // Mutate the live typed record in place (do NOT reassign the whole tree); assigning a detached
+  // plain object tree bypasses ECHO's schema-aware conversion and stores arrays as numeric-keyed
+  // objects. Mutating the typed proxy (and assigning real arrays to its values) preserves arrays.
+  const write = (mutate: (record: Record_) => void): void => {
+    Obj.update(host, (host) => {
+      const view = asView(host);
+      if (view[key] === undefined) {
+        view[key] = {};
+      }
+      // Re-read after assignment: the assignment expression yields the plain RHS, not the
+      // ECHO-backed reactive record, so mutating that would not persist.
+      mutate(view[key]!);
+    });
+  };
+
+  // Existence check via `Object.keys` — ECHO's reactive record proxy auto-vivifies missing keys on
+  // direct access, so `record[tagId]` is not reliably `undefined` for absent tags.
+  const has = (record: Record_, tagId: string): boolean => Object.keys(record).includes(tagId);
+
+  return {
+    tagIds: () => Object.keys(read()),
+    objects: (tagId) => {
+      const record = read();
+      return has(record, tagId) ? record[tagId] : [];
+    },
+    tags: (objectId) => {
+      const record = read();
+      return Object.keys(record).filter((tagId) => record[tagId].includes(objectId));
+    },
+    setTag: (tagId, objectId) =>
+      write((record) => {
+        // Use `has` (not `record[tagId]`) for absence — the proxy auto-vivifies missing keys.
+        if (!has(record, tagId)) {
+          record[tagId] = [objectId];
+        } else if (!record[tagId].includes(objectId)) {
+          record[tagId] = [...record[tagId], objectId];
+        }
+      }),
+    unsetTag: (tagId, objectId) =>
+      write((record) => {
+        if (!has(record, tagId)) {
+          return;
+        }
+        const next = record[tagId].filter((existing) => existing !== objectId);
+        if (next.length === 0) {
+          delete record[tagId];
+        } else {
+          record[tagId] = next;
+        }
+      }),
+  };
+};

package/src/Tagging.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { EID, URI } from '@dxos/keys';
+
+import type * as Database from './Database';
+import * as Obj from './Obj';
+import * as Ref from './Ref';
+import type * as Tag from './Tag';
+import * as TagIndex from './TagIndex';
+
+/**
+ * Unified tag handling for objects whether their tags live on the object (mutable database objects)
+ * or alongside it (immutable feed/queue objects).
+ *
+ * - Mutable database objects track their tags in `Obj.getMeta(obj).tags` (an array of `Ref<Tag>`).
+ * - Immutable feed objects can't carry their own meta, so their tags live in a {@link TagIndex} on
+ *   a host object; pass that host via {@link Options.host}.
+ *
+ * Either way the tag id is an existing {@link Tag} object's id/URI, so the same tag applies across
+ * mutable and immutable objects and its label is resolved (and edited) in one place. This API works
+ * in terms of those URI tag ids; on the mutable path it converts to/from the stored `Ref<Tag>`.
+ */
+export interface Options {
+  /** Host object whose tag index holds tags for the (immutable) object. Omit for mutable objects. */
+  host?: Obj.Any;
+  /** Tag-index field name on the host (default `tags`). */
+  key?: string;
+}
+
+const DEFAULT_KEY = 'tags';
+
+/** Returns the tag ids (URIs) applied to an object. */
+export const get = (object: Obj.Any, options: Options = {}): string[] => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    return TagIndex.bind(host, key).tags(object.id);
+  }
+  return Obj.getMeta(object).tags.map((tag) => tag.uri);
+};
+
+/** Applies a tag (by id/URI) to an object (idempotent). */
+export const set = (object: Obj.Any, tagId: string, options: Options = {}): void => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    TagIndex.bind(host, key).setTag(tagId, object.id);
+    return;
+  }
+  // Stored tag refs are canonical EIDs (read-time upgrade normalizes legacy DXN ids); normalize the
+  // incoming id the same way so dedupe compares like-for-like.
+  const id = EID.tryParse(tagId) ?? tagId;
+  Obj.update(object, (object) => {
+    const meta = Obj.getMeta(object);
+    if (!meta.tags.some((tag) => tag.uri === id)) {
+      meta.tags.push(Ref.fromURI(URI.make(id)));
+    }
+  });
+};
+
+/** Removes a tag (by id/URI) from an object. No-op when not present. */
+export const unset = (object: Obj.Any, tagId: string, options: Options = {}): void => {
+  const { host, key = DEFAULT_KEY } = options;
+  if (host) {
+    TagIndex.bind(host, key).unsetTag(tagId, object.id);
+    return;
+  }
+  const id = EID.tryParse(tagId) ?? tagId;
+  Obj.update(object, (object) => {
+    const meta = Obj.getMeta(object);
+    for (let i = meta.tags.length - 1; i >= 0; i--) {
+      if (meta.tags[i].uri === id) {
+        meta.tags.splice(i, 1);
+      }
+    }
+  });
+};
+
+/** Resolves tag ids (URIs) to {@link Tag} object refs via the database. */
+export const resolve = (db: Pick<Database.Database, 'makeRef'>, tagIds: readonly string[]): Ref.Ref<Tag.Tag>[] =>
+  tagIds.map((id) => db.makeRef<Tag.Tag>(URI.make(id)));

package/src/Type.test.ts

@@ -5,6 +5,10 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
+import { DXN, EntityId } from '@dxos/keys';
+
+import * as Entity from './Entity';
+import * as JsonSchema from './JsonSchema';
 import * as Obj from './Obj';
 import * as Relation from './Relation';
 import { TestSchema } from './testing';
@@ -12,16 +16,9 @@ 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.
+      // 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);
@@ -29,16 +26,9 @@ describe('Type', () => {
   });
 
   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.
+      // 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' });
@@ -49,4 +39,219 @@ describe('Type', () => {
       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.isTypeKind(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.isTypeKind(TestSchema.Person)).toBe(false);
+      expect(Type.isTypeKind(TestSchema.HasManager)).toBe(false);
+    });
+
+    test('Type.getMeta(Type.Type) reports key/version of the meta-schema', ({ expect }) => {
+      // `Type.getMeta` returns the entity's `EntityMeta`. 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.isTypeKind(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 `EntityMeta` (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 `EntityMeta.version`; the
+      // typename (`EntityMeta.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');
+    });
+  });
+
+  describe('deterministic id default', () => {
+    // The default id is `EntityId.deterministic(typename, version)` — required so that
+    // `Type.makeObject(...)` never calls `crypto.getRandomValues()` at module-evaluation
+    // time (forbidden by Cloudflare workerd in global scope).
+    const personDxn = DXN.make('com.example.type.deterministic.person', '0.1.0');
+    const worksForDxn = DXN.make('com.example.type.deterministic.worksFor', '0.1.0');
+
+    test('Type.makeObject with the same DXN twice yields entities with identical ids', ({ expect }) => {
+      const a = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      const b = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      expect(a.id).toBe(b.id);
+      expect(a.id).toBe(EntityId.deterministic('com.example.type.deterministic.person', '0.1.0'));
+    });
+
+    test('different versions produce different ids', ({ expect }) => {
+      const v1 = Schema.Struct({ name: Schema.String }).pipe(
+        Type.makeObject(DXN.make('com.example.type.deterministic.person', '0.1.0')),
+      );
+      const v2 = Schema.Struct({ name: Schema.String }).pipe(
+        Type.makeObject(DXN.make('com.example.type.deterministic.person', '0.2.0')),
+      );
+      expect(v1.id).not.toBe(v2.id);
+    });
+
+    test('Type.makeObject({ id }) override is honoured', ({ expect }) => {
+      const explicit = EntityId.random();
+      const entity = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn, { id: explicit }));
+      expect(entity.id).toBe(explicit);
+      // And the default still kicks in when no override is supplied.
+      const defaultEntity = Schema.Struct({ name: Schema.String }).pipe(Type.makeObject(personDxn));
+      expect(defaultEntity.id).not.toBe(explicit);
+    });
+
+    test('Type.makeRelation defaults id to deterministic(typename, version)', ({ expect }) => {
+      const a = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({ dxn: worksForDxn, source: TestSchema.Person, target: TestSchema.Organization }),
+      );
+      const b = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({ dxn: worksForDxn, source: TestSchema.Person, target: TestSchema.Organization }),
+      );
+      expect(a.id).toBe(b.id);
+      expect(a.id).toBe(EntityId.deterministic('com.example.type.deterministic.worksFor', '0.1.0'));
+    });
+
+    test('Type.makeRelation({ id }) override is honoured', ({ expect }) => {
+      const explicit = EntityId.random();
+      const entity = Schema.Struct({ since: Schema.Number }).pipe(
+        Type.makeRelation({
+          dxn: worksForDxn,
+          source: TestSchema.Person,
+          target: TestSchema.Organization,
+          id: explicit,
+        }),
+      );
+      expect(entity.id).toBe(explicit);
+    });
+  });
 });