@dxos/echo 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/src/hierarchy.test.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import * as Obj from './Obj';
+import { TestSchema } from './testing';
+
+describe('Hierarchy', () => {
+  test('setParent and getParent', async () => {
+    const parent = Obj.make(TestSchema.Organization, { name: 'parent' });
+    const child = Obj.make(TestSchema.Person, { name: 'child' });
+    expect(Obj.getParent(child)).toBeUndefined();
+
+    Obj.setParent(child, parent);
+    expect(Obj.getParent(child)).toBe(parent);
+
+    Obj.setParent(child, undefined);
+    expect(Obj.getParent(child)).toBeUndefined();
+  });
+
+  test('create object with Obj.Parent in props', () => {
+    const parent = Obj.make(TestSchema.Organization, { name: 'DXOS' });
+    const child = Obj.make(TestSchema.Person, {
+      [Obj.Parent]: parent,
+      name: 'John',
+    });
+
+    expect(child.name).toBe('John');
+    expect(Obj.getParent(child)).toBe(parent);
+  });
+});

package/src/index.ts

@@ -10,6 +10,7 @@ export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
 export * as Err from './Err';
+export * as Feed from './Feed';
 export * as Filter from './Filter';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
@@ -24,3 +25,6 @@ export * as Relation from './Relation';
 export * as SchemaRegistry from './SchemaRegistry';
 export * as Tag from './Tag';
 export * as Type from './Type';
+export * as Collection from './Collection';
+export * as View from './View';
+export * as Dataset from './Dataset';

package/src/internal/{annotations → Annotation}/annotations.test.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
+import { EchoObjectSchema } from '../Entity';
 
 import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
 
@@ -20,7 +20,7 @@ type TestObject = Schema.Schema.Type<typeof TestObject>;
 
 const TestEchoSchema = TestObject.pipe(
   EchoObjectSchema({
-    typename: 'dxos.org/type/Test',
+    typename: 'org.dxos.type.test',
     version: '0.1.0',
   }),
 );
@@ -30,10 +30,10 @@ type TestEchoSchema = Schema.Schema.Type<typeof TestEchoSchema>;
 describe('annotations', () => {
   describe('Typename', () => {
     test('should validate typename', ({ expect }) => {
-      // Valid.
-      expect(TypenameSchema.make('dxos.org/type/foo')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo-bar')).to.exist;
-      expect(TypenameSchema.make('dxos.org/type/foo_bar')).to.exist;
+      // Valid (reverse-DNS format).
+      expect(TypenameSchema.make('org.dxos.type.foo')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.foo-bar')).to.exist;
+      expect(TypenameSchema.make('org.dxos.type.foobar')).to.exist;
 
       // Invalid.
       expect(() => TypenameSchema.make('dxn:dxos.org')).to.throw();

package/src/internal/{annotations → Annotation}/annotations.ts

@@ -13,9 +13,10 @@ import { assertArgument, invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 import { type Primitive } from '@dxos/util';
 
-import { type AnyProperties, EntityKind, TypeId, getSchema } from '../types';
+import { type Mutable } from '../common/proxy';
+import { type AnyProperties, EntityKind, TypeId, getSchema } from '../common/types';
 
-import { createAnnotationHelper } from './util';
+import { type AnnotationHelper, createAnnotationHelper } from './util';
 
 /**
  * @internal
@@ -87,14 +88,14 @@ export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN
 
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Message`
+ * Example: `org.dxos.type.message`
  */
 // TODO(burdon): Reconcile with short DXN format.
-// TODO(burdon): Change "/type" => "/schema" throughout.
-export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-zA-Z]\w+\.[a-zA-Z]\w{1,}\/[\w/_-]+$/)).annotations(
+// TODO(burdon): Change "type" => "schema" throughout.
+export const TypenameSchema = Schema.String.pipe(Schema.pattern(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/)).annotations(
   {
-    description: 'Fully qualified globally unique typename',
-    example: 'dxos.org/type/Message',
+    description: 'Fully qualified globally unique typename in lowercase reverse-DNS form.',
+    example: 'org.dxos.type.message',
   },
 );
 
@@ -175,7 +176,7 @@ export const getSchemaVersion = (schema: Schema.Schema.All): string | undefined
 /**
  * Gets the typename of the object without the version.
  * Returns only the name portion, not the DXN.
- * @example "example.org/type/Contact"
+ * @example "org.example.type.contact"
  *
  * @internal (use Obj.getTypename)
  */
@@ -207,7 +208,7 @@ export const setTypename = (obj: any, typename: DXN): void => {
 /**
  * @returns Object type as {@link DXN}.
  * @returns undefined if the object doesn't have a type.
- * @example `dxn:example.com/type/Person:1.0.0`
+ * @example `dxn:com.example.type.person:1.0.0`
  *
  * @internal (use Obj.getTypeDXN)
  */
@@ -458,3 +459,113 @@ export type GeneratorAnnotationValue =
     };
 
 export const GeneratorAnnotation = createAnnotationHelper<GeneratorAnnotationValue>(GeneratorAnnotationId);
+
+interface MakeAnnoationsProps<T> {
+  id: string;
+  schema: Schema.Schema<T, any, never>;
+}
+
+// TODO(wittjosiah): Comment.
+export const makeUserAnnotation = <T>(props: MakeAnnoationsProps<T>): AnnotationHelper<T> => {
+  assertArgument(
+    /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*){2,}$/.test(props.id),
+    'id',
+    'Annotation id must be in the FQN format (org.dxos.annotation.example).',
+  );
+
+  const getFromAst = (ast: SchemaAST.AST) =>
+    SchemaAST.getAnnotation<PropertyMetaAnnotation>(PropertyMetaAnnotationId)(ast).pipe(
+      Option.map((meta) => meta[props.id] as unknown),
+      Option.map(Schema.decodeUnknownSync(props.schema)),
+    );
+
+  return {
+    get: (schema) => getFromAst(schema.ast),
+    getFromAst: (ast) => getFromAst(ast),
+    set: (value) =>
+      PropertyMeta(props.id, Schema.encodeSync(props.schema)(value)) as <S extends Schema.Schema.Any>(schema: S) => S,
+  };
+};
+
+const IconAnnotationSchema = Schema.Struct({
+  /**
+   * Phosphor icon name (e.g., 'ph--user--regular', 'ph--cube--regular', 'ph--link--regular ', etc.)
+   */
+  icon: Schema.String.pipe(Schema.pattern(/^ph--[a-z-]+--[a-z]+$/)),
+
+  /**
+   * Color name.
+   *
+   * List of colors:
+   *  - 'red'
+   *  - 'orange'
+   *  - 'amber'
+   *  - 'yellow'
+   *  - 'lime'
+   *  - 'green'
+   *  - 'emerald'
+   *  - 'teal'
+   *  - 'cyan'
+   *  - 'violet'
+   *  - 'purple'
+   *  - 'fuchsia'
+   *  - 'pink'
+   *  - 'rose'
+   */
+
+  hue: Schema.optional(Schema.String),
+});
+
+export interface IconAnnotation extends Schema.Schema.Type<typeof IconAnnotationSchema> {}
+
+/**
+ * Icon to render in the UI.
+ */
+export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
+  id: 'org.dxos.annotation.icon',
+  schema: IconAnnotationSchema,
+});
+
+/**
+ * Get the label of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getLabel = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getLabelWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the label of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
+  }
+};
+
+/**
+ * Get the description of an entity.
+ * Accepts both reactive entities and snapshots.
+ */
+export const getDescription = (entity: AnyProperties): string | undefined => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    return getDescriptionWithSchema(schema, entity);
+  }
+};
+
+/**
+ * Set the description of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
+ */
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
+  }
+};

package/src/internal/{annotations → Annotation}/index.ts

@@ -3,4 +3,5 @@
 //
 
 export * from './annotations';
+export * from './sorting';
 export * from './util';

package/src/internal/{api → Annotation}/sorting.ts

@@ -2,10 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { getTypename } from '../annotations';
-import type { AnyEntity } from '../types';
+import type { AnyEntity } from '../common/types';
 
-import { getLabel } from './annotations';
+import { getLabel, getTypename } from './annotations';
 
 /**
  * String comparison helper for sorting.

package/src/internal/{annotations → Annotation}/util.ts

@@ -9,14 +9,27 @@ import * as SchemaAST from 'effect/SchemaAST';
 import { assertArgument } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
 
-import { EntityKind } from '../types';
+import { EntityKind } from '../common/types';
 
 export interface AnnotationHelper<T> {
+  /**
+   * Get the annotation value from the schema.
+   */
   get: (schema: Schema.Schema.Any) => Option.Option<T>;
+  /**
+   * Get the annotation value from the AST.
+   */
   getFromAst: (ast: SchemaAST.AST) => Option.Option<T>;
+  /**
+   * Set the annotation value on the schema.
+   */
   set: (value: T) => <S extends Schema.Schema.Any>(schema: S) => S;
 }
 
+/**
+ * Note: only for system annotations.
+ */
+// TODO(dmaretskyi): Rename to createSystemAnnotationHelper.
 export const createAnnotationHelper = <T>(id: symbol): AnnotationHelper<T> => {
   return {
     get: (schema) => SchemaAST.getAnnotation(schema.ast, id),

package/src/internal/{api/entity.ts → Entity/api.ts}

@@ -6,8 +6,10 @@ import { invariant } from '@dxos/invariant';
 import { type DXN } from '@dxos/keys';
 import { assumeType } from '@dxos/util';
 
-import { type InternalObjectProps, ObjectDatabaseId, getObjectDXN } from '../entities';
-import type { AnyEntity } from '../types';
+import type { AnyEntity } from '../common/types';
+
+import { type InternalObjectProps, ObjectDatabaseId } from './model';
+import { getObjectDXN } from './util';
 
 /**
  * Get the DXN of an entity.

package/src/internal/{entities → Entity}/entity.ts

@@ -8,8 +8,8 @@ import type * as Types from 'effect/Types';
 
 import { type ToMutable } from '@dxos/util';
 
-import { type TypeMeta } from '../annotations';
-import { type AnyEntity, type EntityKind, SchemaKindId } from '../types';
+import { type TypeMeta } from '../Annotation';
+import { type AnyEntity, type EntityKind, SchemaKindId } from '../common/types';
 
 // TODO(burdon): Define Schema type for `typename` and use consistently for all DXN-like properties.
 
@@ -22,7 +22,9 @@ export interface EchoTypeSchema<
   ExtraFields = {},
   K extends EntityKind = EntityKind,
   Fields extends Schema.Struct.Fields = Schema.Struct.Fields,
-> extends TypeMeta,
+>
+  extends
+    TypeMeta,
     Schema.AnnotableClass<
       EchoTypeSchema<Self, ExtraFields, K, Fields>,
       EchoTypeSchemaProps<Schema.Schema.Type<Self>, ExtraFields>,
@@ -31,7 +33,7 @@ export interface EchoTypeSchema<
     > {
   /**
    * Schema kind key that marks this as an ECHO schema and indicates its kind.
-   * Makes EchoTypeSchema satisfy the Type.Obj.Any or Type.Relation.Any type.
+   * Makes EchoTypeSchema satisfy the Type.AnyObj or Type.Relation.Any type.
    */
   readonly [SchemaKindId]: K;
 

package/src/internal/{entities → Entity}/index.ts

@@ -2,8 +2,10 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './api';
 export * from './entity';
 export * from './model'; // TODO(burdon): Rename.
 export * from './object';
 export * from './relation';
 export * from './util';
+export * from './version';

package/src/internal/{entities → Entity}/model.ts

@@ -12,58 +12,31 @@ import { assumeType } from '@dxos/util';
 import type * as Database from '../../Database';
 import {
   type ATTR_META,
+  type ATTR_PARENT,
   type ATTR_TYPE,
+  ATTR_DELETED,
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  ATTR_SELF_DXN,
   EntityKind,
   KindId,
   type MetaId,
+  ObjectDatabaseId,
+  ObjectDeletedId,
   type ObjectMeta,
-  type SchemaId,
-  TypeId,
-  type Version,
-} from '../types';
-
-import {
-  type ATTR_RELATION_SOURCE,
-  type ATTR_RELATION_TARGET,
+  ObjectVersionId,
+  type ParentId,
   RelationSourceDXNId,
   RelationSourceId,
   RelationTargetDXNId,
   RelationTargetId,
-} from './relation';
-
-//
-// Defines the internal model of the echo object.
-//
-
-/**
- * Property name for self DXN when object is serialized to JSON.
- */
-export const ATTR_SELF_DXN = '@dxn';
-
-/**
- * DXN to the object itself.
- */
-export const SelfDXNId = Symbol.for('@dxos/echo/DXN');
-
-/**
- * Property name for deleted when object is serialized to JSON.
- */
-export const ATTR_DELETED = '@deleted';
-
-/**
- * Deletion marker.
- */
-export const ObjectDeletedId = Symbol.for('@dxos/echo/Deleted');
-
-/**
- * Object version accessor symbol.
- */
-export const ObjectVersionId: unique symbol = Symbol.for('@dxos/echo/Version');
+  type SchemaId,
+  SelfDXNId,
+  TypeId,
+  type Version,
+} from '../common/types';
 
-/**
- * Object database accessor symbol.
- */
-export const ObjectDatabaseId = Symbol.for('@dxos/echo/Database');
+export { ATTR_DELETED, ATTR_SELF_DXN, ObjectDatabaseId, ObjectDeletedId, ObjectVersionId, SelfDXNId };
 
 /**
  * Internal runtime representation of an object.
@@ -77,6 +50,7 @@ export interface InternalObjectProps {
   readonly [SchemaId]: Schema.Schema.AnyNoContext;
   readonly [TypeId]: DXN;
   readonly [MetaId]?: ObjectMeta;
+  [ParentId]?: InternalObjectProps;
   readonly [ObjectDatabaseId]?: Database.Database;
   readonly [ObjectDeletedId]?: boolean;
   readonly [ObjectVersionId]?: Version;
@@ -101,6 +75,7 @@ export interface ObjectJSON {
   id: string;
   [ATTR_TYPE]: DXN.String;
   [ATTR_SELF_DXN]?: DXN.String;
+  [ATTR_PARENT]?: string; // Encoded reference
   [ATTR_DELETED]?: boolean;
   [ATTR_META]?: ObjectMetaJSON;
   [ATTR_RELATION_SOURCE]?: DXN.String;

package/src/internal/{entities → Entity}/object.ts

@@ -7,8 +7,8 @@ import * as SchemaAST from 'effect/SchemaAST';
 
 import { invariant } from '@dxos/invariant';
 
-import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../annotations';
-import { EntityKind } from '../types';
+import { type TypeAnnotation, TypeAnnotationId, type TypeMeta, makeTypeJsonSchemaAnnotation } from '../Annotation';
+import { EntityKind } from '../common/types';
 
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 

package/src/internal/{entities → Entity}/relation.ts

@@ -17,45 +17,28 @@ import {
   getSchemaTypename,
   getTypeIdentifierAnnotation,
   makeTypeJsonSchemaAnnotation,
-} from '../annotations';
-import { EntityKind } from '../types';
+} from '../Annotation';
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  EntityKind,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+} from '../common/types';
+
+export {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+};
 
 import { type EchoTypeSchema, makeEchoTypeSchema } from './entity';
 
-/**
- * Property name for relation source when object is serialized to JSON.
- */
-export const ATTR_RELATION_SOURCE = '@relationSource';
-
-/**
- * Used to access relation source ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationSourceId: unique symbol = Symbol.for('@dxos/echo/RelationSource');
-
-/**
- * Used to access relation source ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationSourceDXNId: unique symbol = Symbol.for('@dxos/echo/RelationSourceDXN');
-
-/**
- * Property name for relation target when object is serialized to JSON.
- */
-export const ATTR_RELATION_TARGET = '@relationTarget';
-
-/**
- * Used to access relation target ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationTargetId: unique symbol = Symbol.for('@dxos/echo/RelationTarget');
-
-/**
- * Used to access relation target ref on live ECHO objects.
- * Reading this symbol must return `Live<EchoObjectSchema<any>>` or a DXN.
- */
-export const RelationTargetDXNId: unique symbol = Symbol.for('@dxos/echo/RelationTargetDXN');
-
 /**
  * Source and target props on relations.
  */

package/src/internal/{api → Entity}/version.ts

@@ -4,8 +4,9 @@
 
 import { assertArgument } from '@dxos/invariant';
 
-import { ObjectVersionId } from '../entities';
-import { type AnyEntity, VersionTypeId } from '../types';
+import { type AnyEntity, VersionTypeId } from '../common/types';
+
+import { ObjectVersionId } from './model';
 
 /**
  * Represent entity version.

package/src/internal/{formats → Format}/date.test.ts

@@ -7,7 +7,7 @@ import { describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
 
-import { toJsonSchema } from '../json-schema';
+import { toJsonSchema } from '../JsonSchema';
 
 import {
   DateOnly,

package/src/internal/{formats → Format}/format.test.ts

@@ -5,7 +5,7 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { toJsonSchema } from '../json-schema';
+import { toJsonSchema } from '../JsonSchema';
 
 import { Format } from './format';
 import { TypeEnum, TypeFormat, getTypeEnum } from './types';

package/src/internal/{formats → Format}/types.ts

@@ -7,8 +7,8 @@ import type * as JSONSchema from 'effect/JSONSchema';
 import * as Option from 'effect/Option';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { createAnnotationHelper } from '../annotations';
-import { type JsonSchemaType } from '../json-schema';
+import { createAnnotationHelper } from '../Annotation';
+import { type JsonSchemaType } from '../JsonSchema';
 
 // TODO(burdon): Rename PropertyType.
 export type ScalarType =
@@ -135,7 +135,7 @@ export const typeToFormat: Partial<Record<TypeEnum, TypeFormat>> = {
  * Map of format to type.
  */
 export const formatToType: Record<TypeFormat, TypeEnum> = {
-  [TypeFormat.None]: undefined as any,
+  [TypeFormat.None]: TypeEnum.String,
   [TypeFormat.String]: TypeEnum.String,
   [TypeFormat.Number]: TypeEnum.Number,
   [TypeFormat.Boolean]: TypeEnum.Boolean,

package/src/internal/{json-schema → JsonSchema}/annotations.ts

@@ -4,9 +4,9 @@
 
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../annotations';
-import { CurrencyAnnotationId, FormatAnnotationId } from '../formats';
-import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../json-schema';
+import { GeneratorAnnotationId, LabelAnnotationId, PropertyMetaAnnotationId } from '../Annotation';
+import { CurrencyAnnotationId, FormatAnnotationId } from '../Format';
+import { type JsonSchemaEchoAnnotations, type JsonSchemaType } from '../JsonSchema';
 
 //
 // This file configures annotations for JSON encoding/decoding.

package/src/internal/{json-schema → JsonSchema}/json-schema-type.ts

@@ -6,9 +6,9 @@ import * as Schema from 'effect/Schema';
 
 import { JsonPath, type JsonProp } from '@dxos/effect';
 
-import { FormatAnnotation, TypeFormat } from '../formats';
-import { type Mutable } from '../proxy';
-import { EntityKindSchema } from '../types';
+import { FormatAnnotation, TypeFormat } from '../Format';
+import { type Mutable } from '../common/proxy';
+import { EntityKindSchema } from '../common/types';
 
 //
 // JSON Schema
@@ -119,7 +119,7 @@ const _JsonSchemaType = Schema.Struct({
    * Typename of this schema.
    * Only on schema representing an ECHO object.
    *
-   * @example 'example.com/type/MyType'
+   * @example 'com.example.type.my-type'
    */
   typename: Schema.optional(Schema.String),