@dxos/echo 0.8.4-main.7ace549 → 0.8.4-main.8360d9e660

package/src/View.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { JsonPath } from '@dxos/effect';
+import { PublicKey } from '@dxos/keys';
+
+import * as Filter from './Filter';
+import * as internal from './internal';
+import * as Obj from './Obj';
+import * as Query from './Query';
+import * as Type from './Type';
+import * as Annotation from './Annotation';
+
+/**
+ * Stored field metadata (e.g., for UX).
+ */
+export const FieldSchema = Schema.Struct({
+  id: Schema.String,
+  path: JsonPath,
+  visible: Schema.optional(Schema.Boolean),
+
+  // TODO(wittjosiah): Presentation-specific?
+  referencePath: Schema.optional(JsonPath),
+});
+
+export type FieldType = Schema.Schema.Type<typeof FieldSchema>;
+
+export const KeyValueProps = Schema.Record({ key: Schema.String, value: Schema.Any });
+
+export const createFieldId = () => PublicKey.random().truncate();
+
+export const Projection = Schema.Struct({
+  /**
+   * Optional schema override used to customize the underlying schema.
+   */
+  schema: internal.JsonSchemaType.pipe(Schema.optional),
+
+  /**
+   * UX metadata associated with displayed fields (in table, form, etc.)
+   */
+  // TODO(wittjosiah): Should this just be an array of JsonPath?
+  fields: Schema.Array(FieldSchema),
+
+  /**
+   * The id for the field used to pivot the view.
+   * E.g., the field to use for kanban columns or the field to use for map coordinates.
+   */
+  pivotFieldId: Schema.String.pipe(Schema.optional),
+});
+
+export type Projection = Schema.Schema.Type<typeof Projection>;
+
+/**
+ * Views are generated or user-defined projections of a schema's properties.
+ * They are used to configure the visual representation of the data.
+ */
+const ViewSchema = Schema.Struct({
+  /**
+   * Query used to retrieve data.
+   * Can be a user-provided query grammar string or a query AST.
+   */
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String),
+    ast: QueryAST.Query,
+  }),
+
+  /**
+   * Projection of the data returned from the query.
+   */
+  projection: Projection,
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.view',
+    version: '0.1.0',
+  }),
+  internal.SystemTypeAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--funnel--regular',
+    hue: 'green',
+  }),
+);
+
+export interface View extends Schema.Schema.Type<typeof ViewSchema> {}
+
+/**
+ * View instance type.
+ */
+// NOTE: This interface is explicitly defined rather than derived from the schema to avoid
+//   TypeScript "cannot be named" portability errors. The schema contains QueryAST.Query which
+//   references internal @dxos/echo-protocol module paths. Without this explicit interface,
+//   any schema using Ref.Ref(View) would inherit the non-portable type and fail to compile.
+// TODO(wittjosiah): Find a better solution that doesn't require manually keeping the interface in sync.
+export const View: Type.Obj<View> = ViewSchema as any;
+
+export const make = (props: Partial<Obj.MakeProps<typeof View>>): View => {
+  return Obj.make(View, {
+    query: { ast: Query.select(Filter.nothing()).ast },
+    projection: { fields: [] },
+    ...props,
+  });
+};

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

@@ -2,21 +2,29 @@
 // Copyright 2025 DXOS.org
 //
 
+export { QueryAST } from '@dxos/echo-protocol';
+// TODO(wittjosiah): Refactor DXN to not use statics similar to Query.
 export { DXN } from '@dxos/keys';
 
-export * from './errors';
-
-// TODO(burdon): Separate namesapces for Query (Query.Query, Query.Filter, etc.)
-export * from './query';
-
 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';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
 export * as Obj from './Obj';
+export * as Order from './Order';
+export * as Query from './Query';
+export * as QueryResult from './QueryResult';
 export * as Ref from './Ref';
 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,9 +5,9 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { EchoObjectSchema } from '../entities';
+import { EchoObjectSchema } from '../Entity';
 
-import { LabelAnnotation, TypenameSchema, VersionSchema, getLabel } from './annotations';
+import { LabelAnnotation, TypenameSchema, VersionSchema, getLabelWithSchema } from './annotations';
 
 // TODO(dmaretskyi): Use one of the testing schemas.
 const TestObject = Schema.Struct({
@@ -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();
@@ -51,7 +51,7 @@ describe('annotations', () => {
     });
   });
 
-  describe('getLabel', () => {
+  describe('getLabelWithSchema', () => {
     test('should return first available label value', ({ expect }) => {
       const obj: TestObject = {
         name: 'Primary Name',
@@ -59,7 +59,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toEqual('Primary Name');
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Primary Name');
     });
 
     test('should fallback to second path if first is undefined', ({ expect }) => {
@@ -69,7 +69,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toEqual('Fallback Name');
+      expect(getLabelWithSchema(TestObject, obj)).toEqual('Fallback Name');
     });
 
     test('should return undefined if no label paths resolve', ({ expect }) => {
@@ -79,7 +79,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestObject, obj)).toBeUndefined();
+      expect(getLabelWithSchema(TestObject, obj)).toBeUndefined();
     });
 
     test('should return label from echo object', ({ expect }) => {
@@ -90,7 +90,7 @@ describe('annotations', () => {
         other: 'Other',
       };
 
-      expect(getLabel(TestEchoSchema, obj)).toEqual('Primary Name');
+      expect(getLabelWithSchema(TestEchoSchema, obj)).toEqual('Primary Name');
     });
   });
 });

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

@@ -7,15 +7,16 @@ import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
 import * as SchemaAST from 'effect/SchemaAST';
 
-import { Reference } from '@dxos/echo-protocol';
+import { raise } from '@dxos/debug';
 import { type JsonPath, getField } from '@dxos/effect';
 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
@@ -29,6 +30,10 @@ export const FIELD_PATH_ANNOTATION = 'path';
 // TODO(burdon): Field, vs. path vs. property.
 export const FieldPath = (path: string) => PropertyMeta(FIELD_PATH_ANNOTATION, path);
 
+//
+// Type
+//
+
 /**
  * ECHO identifier (for a stored schema).
  * Must be a `dxn:echo:` URI.
@@ -41,16 +46,56 @@ export const getTypeIdentifierAnnotation = (schema: Schema.Schema.All) =>
     Option.getOrElse(() => undefined),
   )(schema.ast);
 
+/**
+ * @returns DXN of the schema.
+ *
+ * For non-stored schema returns `dxn:type:`.
+ * For stored schema returns `dxn:echo:`.
+ */
+export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
+  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
+  const id = getTypeIdentifierAnnotation(schema);
+  if (id) {
+    return DXN.parse(id);
+  }
+
+  // TODO(dmaretskyi): Add support for dynamic schema.
+  const objectAnnotation = getTypeAnnotation(schema);
+  if (!objectAnnotation) {
+    return undefined;
+  }
+
+  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
+};
+
+/**
+ * @param input schema or a typename string.
+ * @return type DXN.
+ */
+export const getTypeDXNFromSpecifier = (input: Schema.Schema.All | string): DXN => {
+  if (Schema.isSchema(input)) {
+    return getSchemaDXN(input) ?? raise(new TypeError('Schema has no DXN'));
+  } else {
+    assertArgument(typeof input === 'string', 'input');
+    assertArgument(!input.startsWith('dxn:'), 'input');
+    return DXN.fromTypename(input);
+  }
+};
+
+//
+// TypeAnnotation
+//
+
 /**
  * Fully qualified globally unique typename.
- * Example: `dxos.org/type/Person`
+ * 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/Person',
+    description: 'Fully qualified globally unique typename in lowercase reverse-DNS form.',
+    example: 'org.dxos.type.message',
   },
 );
 
@@ -82,9 +127,6 @@ export const TypeAnnotation = Schema.extend(
   TypeMeta,
   Schema.Struct({
     kind: Schema.Enums(EntityKind),
-    // kind: Schema.Enums(EntityKind),
-    // typename: Typename,
-    // version: VersionSchema,
 
     /**
      * If this is a relation, the schema of the source object.
@@ -102,8 +144,6 @@ export const TypeAnnotation = Schema.extend(
 
 export interface TypeAnnotation extends Schema.Schema.Type<typeof TypeAnnotation> {}
 
-// export type TypeMeta = Pick<TypeAnnotation, 'typename' | 'version'>;
-
 /**
  * @returns {@link TypeAnnotation} from a schema.
  * Schema must have been created with {@link TypedObject} or {@link TypedLink} or manually assigned an appropriate annotation.
@@ -136,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)
  */
@@ -168,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)
  */
@@ -228,6 +268,10 @@ export const isInstanceOf = <Schema extends Schema.Schema.AnyNoContext>(
   return typeDXN.type === typename;
 };
 
+//
+// PropertyMeta
+//
+
 /**
  * PropertyMeta (metadata for dynamic schema properties).
  * For user-defined annotations.
@@ -261,18 +305,16 @@ export const getPropertyMetaAnnotation = <T>(prop: SchemaAST.PropertySignature,
     Option.getOrElse(() => undefined),
   );
 
+//
+// Reference
+//
+
 /**
  * Schema reference.
  */
 export const ReferenceAnnotationId = Symbol.for('@dxos/schema/annotation/Reference');
-
 export type ReferenceAnnotationValue = TypeAnnotation;
-
-export const getReferenceAnnotation = (schema: Schema.Schema.AnyNoContext) =>
-  Function.pipe(
-    SchemaAST.getAnnotation<ReferenceAnnotationValue>(ReferenceAnnotationId)(schema.ast),
-    Option.getOrElse(() => undefined),
-  );
+export const ReferenceAnnotation = createAnnotationHelper<ReferenceAnnotationValue>(ReferenceAnnotationId);
 
 /**
  * SchemaMeta.
@@ -295,9 +337,13 @@ export const LabelAnnotation = createAnnotationHelper<string[]>(LabelAnnotationI
 
 /**
  * Returns the label for a given object based on {@link LabelAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
 // TODO(burdon): Convert to JsonPath?
-export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>): string | undefined => {
+export const getLabelWithSchema = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+): string | undefined => {
   const annotation = LabelAnnotation.get(schema).pipe(Option.getOrElse(() => ['name']));
   for (const accessor of annotation) {
     assertArgument(
@@ -325,8 +371,13 @@ export const getLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.
 
 /**
  * Sets the label for a given object based on {@link LabelAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
-export const setLabel = <S extends Schema.Schema.Any>(schema: S, object: Schema.Schema.Type<S>, label: string) => {
+export const setLabelWithSchema = <S extends Schema.Schema.Any>(
+  schema: S,
+  object: Schema.Schema.Type<S>,
+  label: string,
+) => {
   const annotation = LabelAnnotation.get(schema).pipe(
     Option.map((field) => field[0]),
     Option.getOrElse(() => 'name'),
@@ -342,10 +393,11 @@ export const DescriptionAnnotationId = Symbol.for('@dxos/schema/annotation/Descr
 export const DescriptionAnnotation = createAnnotationHelper<string>(DescriptionAnnotationId);
 
 /**
- * Returns the label for a given object based on {@link LabelAnnotationId}.
+ * Returns the description for a given object based on {@link DescriptionAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
 // TODO(burdon): Convert to JsonPath?
-export const getDescription = <S extends Schema.Schema.Any>(
+export const getDescriptionWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
 ): string | undefined => {
@@ -369,8 +421,9 @@ export const getDescription = <S extends Schema.Schema.Any>(
 
 /**
  * Sets the description for a given object based on {@link DescriptionAnnotationId}.
+ * Lower-level version that requires explicit schema parameter.
  */
-export const setDescription = <S extends Schema.Schema.Any>(
+export const setDescriptionWithSchema = <S extends Schema.Schema.Any>(
   schema: S,
   object: Schema.Schema.Type<S>,
   description: string,
@@ -407,57 +460,112 @@ 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> {}
+
 /**
- * @returns DXN of the schema.
- *
- * For non-stored schema returns `dxn:type:`.
- * For stored schema returns `dxn:echo:`.
+ * Icon to render in the UI.
  */
-export const getSchemaDXN = (schema: Schema.Schema.All): DXN | undefined => {
-  assertArgument(Schema.isSchema(schema), 'schema', 'invalid schema');
-
-  const id = getTypeIdentifierAnnotation(schema);
-  if (id) {
-    return DXN.parse(id);
-  }
+export const IconAnnotation = makeUserAnnotation<IconAnnotation>({
+  id: 'org.dxos.annotation.icon',
+  schema: IconAnnotationSchema,
+});
 
-  // TODO(dmaretskyi): Add support for dynamic schema.
-  const objectAnnotation = getTypeAnnotation(schema);
-  if (!objectAnnotation) {
-    return undefined;
+/**
+ * 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);
   }
-
-  return DXN.fromTypenameAndVersion(objectAnnotation.typename, objectAnnotation.version);
 };
 
 /**
- * Returns a reference that will be used to point to a schema.
- * @deprecated Use {@link getSchemaDXN} instead.
+ * Set the label of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
  */
-export const getTypeReference = (schema: Schema.Schema.All | undefined): Reference | undefined => {
-  if (!schema) {
-    return undefined;
+export const setLabel = (entity: Mutable<AnyProperties>, label: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setLabelWithSchema(schema, entity, label);
   }
+};
 
-  const schemaDXN = getSchemaDXN(schema);
-  if (!schemaDXN) {
-    return undefined;
+/**
+ * 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);
   }
-  return Reference.fromDXN(schemaDXN);
 };
 
 /**
- * Returns a reference that will be used to point to a schema.
- * @throws If it is not possible to reference this schema.
- *
- * @deprecated Use {@link getSchemaDXN} instead.
+ * Set the description of an entity.
+ * Must be called within an Obj.change or Relation.change callback.
  */
-export const requireTypeReference = (schema: Schema.Schema.AnyNoContext): Reference => {
-  const typeReference = getTypeReference(schema);
-  if (typeReference == null) {
-    // TODO(burdon): Catalog user-facing errors (this is too verbose).
-    throw new Error('Schema must be defined via TypedObject.');
+export const setDescription = (entity: Mutable<AnyProperties>, description: string) => {
+  const schema = getSchema(entity);
+  if (schema != null) {
+    setDescriptionWithSchema(schema, entity, description);
   }
-
-  return typeReference;
 };

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

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

package/src/internal/Annotation/sorting.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { AnyEntity } from '../common/types';
+
+import { getLabel, getTypename } from './annotations';
+
+/**
+ * String comparison helper for sorting.
+ */
+export const compare = (a?: string, b?: string): number => {
+  if (a == null) {
+    return b == null ? 0 : 1;
+  }
+  if (b == null) {
+    return -1;
+  }
+  return a.localeCompare(b);
+};
+
+/**
+ * Comparator function type for sorting entities.
+ * Accepts both reactive entities and snapshots.
+ */
+export type Comparator<T extends AnyEntity = AnyEntity> = (a: T, b: T) => number;
+
+/**
+ * Sort entities by label.
+ */
+export const sortByLabel: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getLabel(a), getLabel(b));
+
+/**
+ * Sort entities by typename.
+ */
+export const sortByTypename: Comparator = (a: AnyEntity, b: AnyEntity) => compare(getTypename(a), getTypename(b));
+
+/**
+ * Compose multiple comparators into one.
+ * Applies comparators in order until one returns non-zero.
+ */
+export const sort = <T extends AnyEntity>(...comparators: Comparator<T>[]): Comparator<T> => {
+  return (a: T, b: T) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) {
+        return result;
+      }
+    }
+    return 0;
+  };
+};