@dxos/echo 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/Tag.ts

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import * as Schema from 'effect/Schema';
 
-import { LabelAnnotation } from './internal';
+import * as internal from './internal';
 import * as Obj from './Obj';
 import * as Type from './Type';
 
@@ -12,18 +14,18 @@ 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',
+  Type.object({
+    typename: 'org.dxos.type.tag',
     version: '0.1.0',
   }),
-  LabelAnnotation.set(['label']),
+  internal.LabelAnnotation.set(['label']),
+  internal.SystemTypeAnnotation.set(true),
 );
 
 export type Tag = Schema.Schema.Type<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

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+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('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.
+      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('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.
+      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);
+    });
+  });
+});

package/src/Type.ts

@@ -2,212 +2,231 @@
 // Copyright 2025 DXOS.org
 //
 
-import type * as EffectSchema from 'effect/Schema';
+// @import-as-namespace
+
+import type * as Schema from 'effect/Schema';
 
 import { type EncodedReference } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
-import type * as Keys from '@dxos/keys';
+import { type DXN } from '@dxos/keys';
+import { type ToMutable } from '@dxos/util';
 
-import { type ToMutable } from './internal';
-import * as EchoSchema from './internal';
+import type * as Entity from './Entity';
+import * as internal from './internal';
+import * as typeInternal from './internal/Type';
+import type * as ObjModule from './Obj';
 import type * as RelationModule from './Relation';
 
-//
-// Kind
-//
-
-export const KindId: unique symbol = EchoSchema.EntityKindId as any;
-export type KindId = typeof KindId;
-
-export const Kind = EchoSchema.EntityKind;
-
 /**
- * Assigns a kind to an Object or Relation instance.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-// NOTE: Needed to make `isRelation` and `isObject` checks work.
-export interface OfKind<Kind extends EchoSchema.EntityKind> {
-  readonly id: Keys.ObjectId;
-  readonly [KindId]: Kind;
-}
+export const RuntimeType = typeInternal.EchoSchema;
 
 /**
- * Base ECHO schema type.
+ * Dynamic type that can be constructed, mutated, and persisted in the ECHO database.
  */
-export type Schema = EchoSchema.EchoSchema;
+export type RuntimeType = typeInternal.EchoSchema;
+
+//
+// Internal types (not exported)
+//
 
 /**
- * Returns all properties of an object or relation except for the id and kind.
+ * Type that marks a schema as an ECHO schema.
+ * The value indicates the entity kind (Object or Relation).
  */
-export type Properties<T = any> = Omit<T, 'id' | KindId | RelationModule.Source | RelationModule.Target>;
+type EchoSchemaKind<K extends internal.EntityKind = internal.EntityKind> = {
+  readonly [internal.SchemaKindId]: K;
+};
 
 //
-// Obj
+// Obj - Runtime schema for any ECHO object
 //
 
-interface ObjJsonProps {
-  id: string;
+/**
+ * TypeScript type for an ECHO object schema.
+ * `T` is the instance type produced by the schema.
+ * `Fields` is the optional struct fields type for introspection.
+ *
+ * @example
+ * ```ts
+ * const PersonSchema: Type.Obj<Person> = Schema.Struct({
+ *   name: Schema.String,
+ * }).pipe(Type.object({ typename: 'Person', version: '0.1.0' }));
+ *
+ * // Access fields for introspection:
+ * Object.keys(PersonSchema.fields); // ['name']
+ * ```
+ */
+export interface Obj<T, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Object>,
+    Schema.AnnotableClass<
+      Obj<T, Fields>,
+      Entity.OfKind<typeof Entity.Kind.Object> & T,
+      Schema.Simplify<ObjModule.BaseObjJson & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
 }
 
 /**
- * Return type of the `Obj` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * Structural base type for any ECHO object schema.
+ * Accepts both static schemas (created with Type.object()) and EchoSchema.
+ * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
+ * Use Type.isObjectSchema() for runtime type guards.
  */
-export interface obj<Self extends EffectSchema.Schema.Any>
-  extends EchoSchema.TypeMeta,
-    EffectSchema.AnnotableClass<
-      obj<Self>,
-      OfKind<EchoSchema.EntityKind.Object> & ToMutable<EffectSchema.Schema.Type<Self>>,
-      EffectSchema.Simplify<ObjJsonProps & ToMutable<EffectSchema.Schema.Encoded<Self>>>,
-      EffectSchema.Schema.Context<Self>
-    > {}
+type ObjectSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
 
 /**
- * Object schema.
+ * Type that represents any ECHO object schema.
+ * Accepts both static schemas (Type.object()) and mutable schemas (EchoSchema).
  */
-export const Obj: {
-  (opts: EchoSchema.TypeMeta): <Self extends EffectSchema.Schema.Any>(self: Self) => obj<Self>;
-} = EchoSchema.EchoObject as any;
+export type AnyObj = ObjectSchemaBase;
 
 /**
- * Object schema type definitions.
+ * Factory function to create an ECHO object schema.
+ * Adds object metadata annotations to an Effect schema.
+ *
+ * @example
+ * ```ts
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ * }).pipe(Type.object({ typename: 'com.example.type.person', version: '0.1.0' }));
+ * ```
  */
-export declare namespace Obj {
-  /**
-   * Type that represents an arbitrary schema type of an object.
-   * NOTE: This is not an instance type.
-   */
-  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  // TODO(burdon): This erases the ECHO type info (e.g., id, typename).
-  export type Any = EffectSchema.Schema.AnyNoContext;
-}
+export const object: {
+  (opts: internal.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => Obj<Schema.Schema.Type<Self>>;
+} = internal.EchoObjectSchema as any;
 
 //
-// Expando
+// PersistentType (Schema stored in database)
 //
 
-// TODO(burdon): We're using Expando in many places as a base type.
-export interface Expando extends OfKind<EchoSchema.EntityKind.Object> {
-  [key: string]: any;
-}
+export const PersistentType: Obj<typeInternal.PersistentSchema> = typeInternal.PersistentSchema as any;
 
-type ExpandoEncoded = EffectSchema.Simplify<ObjJsonProps & { [key: string]: any }>;
+export interface PersistentType extends Schema.Schema.Type<typeof PersistentType> {}
 
-export const Expando: EffectSchema.Schema<Expando, ExpandoEncoded, never> = EchoSchema.Expando as any;
-
-//
-// Relation
-//
-
-interface RelationJsonProps {
-  id: string;
-  [EchoSchema.ATTR_RELATION_SOURCE]: string;
-  [EchoSchema.ATTR_RELATION_TARGET]: string;
+/**
+ * TypeScript type for an ECHO relation schema.
+ * `T` is the instance type produced by the schema (excluding source/target).
+ * `Source` and `Target` are the endpoint types.
+ * `Fields` is the optional struct fields type for introspection.
+ */
+export interface Relation<T, Source, Target, Fields extends Schema.Struct.Fields = Schema.Struct.Fields>
+  extends
+    internal.TypeMeta,
+    EchoSchemaKind<internal.EntityKind.Relation>,
+    Schema.AnnotableClass<
+      Relation<T, Source, Target, Fields>,
+      Entity.OfKind<typeof Entity.Kind.Relation> & RelationModule.Endpoints<Source, Target> & T,
+      Schema.Simplify<RelationModule.BaseRelationJson & ToMutable<T>>,
+      never
+    > {
+  /**
+   * The fields defined in the original struct schema.
+   * Allows accessing field definitions for introspection.
+   */
+  readonly fields: Fields;
 }
 
 /**
- * Return type of the `Relation` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * Structural base type for any ECHO relation schema.
+ * Accepts static schemas (created with Type.relation()).
+ * NOTE: Does not include the brand symbol to avoid TS4053 declaration portability issues.
+ * Use Type.isRelationSchema() for runtime type guards.
  */
-export interface relation<
-  Self extends EffectSchema.Schema.Any,
-  SourceSchema extends EffectSchema.Schema.Any,
-  TargetSchema extends EffectSchema.Schema.Any,
-> extends EchoSchema.TypeMeta,
-    EffectSchema.AnnotableClass<
-      relation<Self, SourceSchema, TargetSchema>,
-      OfKind<EchoSchema.EntityKind.Relation> &
-        Relation.Endpoints<EffectSchema.Schema.Type<SourceSchema>, EffectSchema.Schema.Type<TargetSchema>> &
-        ToMutable<EffectSchema.Schema.Type<Self>>,
-      EffectSchema.Simplify<RelationJsonProps & ToMutable<EffectSchema.Schema.Encoded<Self>>>,
-      EffectSchema.Schema.Context<Self>
-    > {}
+type RelationSchemaBase = Schema.Schema.AnyNoContext & {
+  readonly typename: string;
+  readonly version: string;
+};
 
 /**
- * Relation schema.
+ * Type that represents any ECHO relation schema.
+ * Accepts static schemas (Type.relation()).
  */
-// TODO(dmaretskyi): I have to redefine the type here so that the definition uses symbols from @dxos/echo/Relation.
-export const Relation: {
-  <Source extends EffectSchema.Schema.AnyNoContext, Target extends EffectSchema.Schema.AnyNoContext>(
-    opts: EchoSchema.EchoRelationOptions<Source, Target>,
-  ): <Self extends EffectSchema.Schema.Any>(self: Self) => relation<Self, Source, Target>;
-} = EchoSchema.EchoRelation as any;
+export type AnyRelation = RelationSchemaBase;
 
 /**
- * Relation schema type definitions.
+ * Factory function to create an ECHO relation schema.
+ * Adds relation metadata annotations to an Effect schema.
+ *
+ * @example
+ * ```ts
+ * const WorksFor = Schema.Struct({
+ *   role: Schema.String,
+ * }).pipe(Type.relation({
+ *   typename: 'com.example.type.works-for',
+ *   version: '0.1.0',
+ *   source: Person,
+ *   target: Company,
+ * }));
+ * ```
  */
-export namespace Relation {
-  /**
-   * Type that represents an arbitrary schema type of a relation.
-   * NOTE: This is not an instance type.
-   */
-  // TODO(dmaretskyi): If schema was covariant, we could specify props in here, like `id: ObjectId`.
-  export type Any = EffectSchema.Schema.AnyNoContext;
+export const relation: {
+  <SourceSchema extends Schema.Schema.AnyNoContext, TargetSchema extends Schema.Schema.AnyNoContext>(
+    opts: internal.EchoRelationSchemaOptions<SourceSchema, TargetSchema>,
+  ): <Self extends Schema.Schema.Any>(
+    self: Self,
+  ) => Relation<Schema.Schema.Type<Self>, Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>>;
+} = internal.EchoRelationSchema as any;
 
-  /**
-   * Get relation source type.
-   */
-  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;
-
-  /**
-   * Get relation target type.
-   */
-  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;
-
-  export type Endpoints<Source, Target> = {
-    [RelationModule.Source]: Source;
-    [RelationModule.Target]: Target;
-  };
-}
-
-//
-// Ref
-//
+/**
+ * Type alias for any ECHO entity schema (object or relation).
+ * Use this in type annotations for schema parameters.
+ */
+export type AnyEntity = AnyObj | AnyRelation;
 
 /**
- * Return type of the `Ref` schema constructor.
- *
- * This typedef avoids `TS4023` error (name from external module cannot be used named).
- * See Effect's note on interface types.
+ * Type guard to check if a schema is an object schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Obj.isObject for instances.
  */
-export interface ref<TargetSchema extends EffectSchema.Schema.Any>
-  extends EchoSchema.Ref$<EffectSchema.Schema.Type<TargetSchema>> {}
+export const isObjectSchema = (schema: AnyEntity): schema is AnyObj => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Object;
+};
 
 /**
- * Ref schema.
+ * Type guard to check if a schema is a relation schema.
+ * NOTE: This checks SCHEMAS, not instances. Use Relation.isRelation for instances.
  */
-export const Ref: <S extends Obj.Any>(schema: S) => ref<S> = EchoSchema.Ref;
+export const isRelationSchema = (schema: AnyEntity): schema is AnyRelation => {
+  return (schema as any)[internal.SchemaKindId] === internal.EntityKind.Relation;
+};
 
-export interface Ref<T> extends EffectSchema.SchemaClass<EchoSchema.Ref<T>, EncodedReference> {}
+/**
+ * Type that represents any Ref schema (with unknown target type).
+ * This is a schema type, not an instance type.
+ */
+export type AnyRef = Schema.Schema<internal.Ref<any>, EncodedReference>;
 
-// TODO(buurdon): Move to Ref?
-export namespace Ref {
-  /**
-   * Type that represents an arbitrary schema type of a reference.
-   * NOTE: This is not an instance type.
-   */
-  export type Any = EffectSchema.Schema<EchoSchema.Ref<any>, EncodedReference>;
-}
+//
+// Schema utility functions
+//
 
 /**
  * Gets the full DXN of the schema.
  * Will include the version if it's a `type` DXN.
- * @example "dxn:example.com/type/Person:0.1.0"
+ * @example "dxn:com.example.type.person:0.1.0"
  * @example "dxn:echo:SSSSSSSSSS:XXXXXXXXXXXXX"
  */
-export const getDXN = (schema: Obj.Any | Relation.Any): Keys.DXN | undefined => {
-  return EchoSchema.getSchemaDXN(schema);
+export const getDXN = (schema: AnyEntity): DXN | undefined => {
+  return internal.getSchemaDXN(schema);
 };
 
 /**
  * @param schema - Schema to get the typename from.
- * @returns The typename of the schema. Example: `example.com/type/Person`.
+ * @returns The typename of the schema. Example: `com.example.type.person`.
  */
-export const getTypename = (schema: Obj.Any | Relation.Any): string => {
-  const typename = EchoSchema.getSchemaTypename(schema);
+export const getTypename = (schema: AnyEntity): string => {
+  const typename = internal.getSchemaTypename(schema);
   invariant(typeof typename === 'string' && !typename.startsWith('dxn:'), 'Invalid typename');
   return typename;
 };
@@ -216,8 +235,8 @@ export const getTypename = (schema: Obj.Any | Relation.Any): string => {
  * Gets the version of the schema.
  * @example 0.1.0
  */
-export const getVersion = (schema: Obj.Any | Relation.Any): string => {
-  const version = EchoSchema.getSchemaVersion(schema);
+export const getVersion = (schema: AnyEntity): string => {
+  const version = internal.getSchemaVersion(schema);
   invariant(typeof version === 'string' && version.match(/^\d+\.\d+\.\d+$/), 'Invalid version');
   return version;
 };
@@ -225,21 +244,16 @@ export const getVersion = (schema: Obj.Any | Relation.Any): string => {
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = EchoSchema.isMutable;
+export const isMutable = typeInternal.isMutable;
 
 /**
  * ECHO type metadata.
  */
-export type Meta = EchoSchema.TypeAnnotation;
+export type Meta = internal.TypeAnnotation;
 
 /**
  * Gets the meta data of the schema.
  */
-export const getMeta = (schema: Obj.Any | Relation.Any): Meta | undefined => {
-  return EchoSchema.getTypeAnnotation(schema);
+export const getMeta = (schema: AnyEntity): Meta | undefined => {
+  return internal.getTypeAnnotation(schema);
 };
-
-// TODO(dmaretskyi): Remove re-exports.
-export { SpaceId, ObjectId, DXN } from '@dxos/keys';
-
-export { Format, JsonSchemaType as JsonSchema, toEffectSchema, toJsonSchema } from './internal';

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 Annotation from './Annotation';
+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';
+
+/**
+ * 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);
+  });
+});