@dxos/echo 0.8.3-main.672df60 → 0.8.3-staging.0fa589b

package/src/Type.ts

@@ -3,32 +3,75 @@
 //
 
 import { type Schema } from 'effect';
+import type { Simplify } from 'effect/Schema';
 
 import type { EncodedReference } from '@dxos/echo-protocol';
 import * as EchoSchema from '@dxos/echo-schema';
+import type { ToMutable } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import type * as Keys from '@dxos/keys';
 
+import type * as RelationModule from './Relation';
+
+export const KindId: unique symbol = EchoSchema.EntityKindId as any;
+export type KindId = typeof KindId;
+
+export { EntityKind as Kind } from '@dxos/echo-schema';
+
 /**
- * ECHO schema.
+ * Assigns a kind to an Object or Relation instance.
  */
-export type Schema = EchoSchema.EchoSchema;
+// NOTE: Needed to make `isRelation` and `isObject` checks work.
+export interface OfKind<Kind extends EchoSchema.EntityKind> {
+  readonly id: Keys.ObjectId;
+  readonly [KindId]: Kind;
+}
+
+interface ObjJsonProps {
+  id: string;
+}
+
+interface RelationJsonProps {
+  id: string;
+  [EchoSchema.ATTR_RELATION_SOURCE]: string;
+  [EchoSchema.ATTR_RELATION_TARGET]: string;
+}
+
+/**
+ * Returns all properties of an object or relation except for the id and kind.
+ */
+export type Properties<T> = Omit<T, 'id' | KindId | RelationModule.Source | RelationModule.Target>;
 
 /**
- * EchoObject schema.
+ * Base ECHO schema type.
  */
-export const Obj = EchoSchema.EchoObject;
+export type Schema = EchoSchema.EchoSchema;
 
 /**
- * EchoRelation schema.
+ * 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.
  */
-export const Relation = EchoSchema.EchoRelation;
+export interface obj<Self extends Schema.Schema.Any>
+  extends Schema.AnnotableClass<
+      obj<Self>,
+      OfKind<EchoSchema.EntityKind.Object> & ToMutable<Schema.Schema.Type<Self>>,
+      Simplify<ObjJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
+      Schema.Schema.Context<Self>
+    >,
+    EchoSchema.TypeMeta {}
 
 /**
- * Ref schema.
+ * Object schema.
  */
-export const Ref: <S extends Obj.Any>(schema: S) => EchoSchema.Ref$<Schema.Schema.Type<S>> = EchoSchema.Ref;
+export const Obj: {
+  (opts: EchoSchema.TypeMeta): <Self extends Schema.Schema.Any>(self: Self) => obj<Self>;
+} = EchoSchema.EchoObject as any;
 
+/**
+ * Object schema type definitions.
+ */
 export namespace Obj {
   /**
    * Type that represents an arbitrary schema type of an object.
@@ -38,6 +81,39 @@ export namespace Obj {
   export type Any = Schema.Schema.AnyNoContext;
 }
 
+/**
+ * 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.
+ */
+export interface relation<
+  Self extends Schema.Schema.Any,
+  SourceSchema extends Schema.Schema.Any,
+  TargetSchema extends Schema.Schema.Any,
+> extends Schema.AnnotableClass<
+      relation<Self, SourceSchema, TargetSchema>,
+      OfKind<EchoSchema.EntityKind.Relation> &
+        Relation.Endpoints<Schema.Schema.Type<SourceSchema>, Schema.Schema.Type<TargetSchema>> &
+        ToMutable<Schema.Schema.Type<Self>>,
+      Simplify<RelationJsonProps & ToMutable<Schema.Schema.Encoded<Self>>>,
+      Schema.Schema.Context<Self>
+    >,
+    EchoSchema.TypeMeta {}
+
+/**
+ * Relation schema.
+ */
+// TODO(dmaretskyi): I have to redefine the type here so that the definition uses symbols from @dxos/echo/Relation.
+export const Relation: {
+  <Source extends Schema.Schema.AnyNoContext, Target extends Schema.Schema.AnyNoContext>(
+    opts: EchoSchema.EchoRelationOptions<Source, Target>,
+  ): <Self extends Schema.Schema.Any>(self: Self) => relation<Self, Source, Target>;
+} = EchoSchema.EchoRelation as any;
+
+/**
+ * Relation schema type definitions.
+ */
 export namespace Relation {
   /**
    * Type that represents an arbitrary schema type of a relation.
@@ -49,14 +125,36 @@ export namespace Relation {
   /**
    * Get relation target type.
    */
-  export type Target<A> = A extends EchoSchema.RelationSourceTargetRefs<infer T, infer _S> ? T : never;
+  export type Target<A> = A extends Relation.Endpoints<infer _S, infer T> ? T : never;
 
   /**
    * Get relation source type.
    */
-  export type Source<A> = A extends EchoSchema.RelationSourceTargetRefs<infer _T, infer S> ? S : never;
+  export type Source<A> = A extends Relation.Endpoints<infer S, infer _T> ? S : never;
+
+  export type Endpoints<Source, Target> = {
+    [RelationModule.Source]: Source;
+    [RelationModule.Target]: Target;
+  };
 }
 
+/**
+ * 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.
+ */
+export interface ref<TargetSchema extends Schema.Schema.Any>
+  extends EchoSchema.Ref$<Schema.Schema.Type<TargetSchema>> {}
+
+/**
+ * Ref schema.
+ */
+export const Ref: <S extends Obj.Any>(schema: S) => ref<S> = EchoSchema.Ref;
+
+export interface Ref<T> extends Schema.SchemaClass<EchoSchema.Ref<T>, EncodedReference> {}
+
+// TODO(buurdon): Move to Ref?
 export namespace Ref {
   /**
    * Type that represents an arbitrary schema type of a reference.
@@ -107,21 +205,27 @@ export const getMeta = (schema: Obj.Any | Relation.Any): Meta | undefined => {
   return EchoSchema.getTypeAnnotation(schema);
 };
 
-export { EntityKind as Kind } from '@dxos/echo-schema';
-
 /**
  * @returns True if the schema is mutable.
  */
-export const isMutable = (schema: Obj.Any | Relation.Any): boolean => {
-  return EchoSchema.isMutable(schema);
-};
+export const isMutable = EchoSchema.isMutable;
 
 export { SpaceId, ObjectId, DXN } from '@dxos/keys';
 
-export {
-  //
+export interface Expando extends OfKind<EchoSchema.EntityKind.Object> {
+  [key: string]: any;
+}
+
+export const Expando: Schema.Schema<
   Expando,
+  Simplify<ObjJsonProps & { [key: string]: any }>,
+  never
+> = EchoSchema.Expando as any;
+
+export {
+  // TODO(burdon): Standardize.
+  Format,
   JsonSchemaType as JsonSchema,
+  toEffectSchema,
   toJsonSchema,
-  Format,
 } from '@dxos/echo-schema';

package/src/index.ts

@@ -2,10 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-export * as Type from './Type';
+export * as Key from './Key';
 export * as Obj from './Obj';
-export * as Relation from './Relation';
 export * as Ref from './Ref';
+export * as Relation from './Relation';
+export * as Type from './Type';
 
+export { DXN } from '@dxos/keys';
+export { Filter, Query } from './query';
 export { type Live } from '@dxos/live-object';
-export { Filter, Query } from '@dxos/echo-schema';

package/src/query/dsl.test.ts

@@ -0,0 +1,323 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Schema } from 'effect';
+import { describe, expect, test } from 'vitest';
+
+import { QueryAST } from '@dxos/echo-protocol';
+import { DXN } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { Filter, Query } from './dsl';
+import * as Obj from '../Obj';
+import * as Ref from '../Ref';
+import * as Type from '../Type';
+
+//
+// Example schema
+//
+
+// TODO(dmaretskyi): Need common set of test types.
+const Person = Schema.Struct({
+  name: Schema.String,
+  email: Schema.optional(Schema.String),
+  age: Schema.optional(Schema.Number),
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Person',
+    version: '0.1.0',
+  }),
+);
+interface Person extends Schema.Schema.Type<typeof Person> {}
+
+const Organization = Schema.Struct({
+  name: Schema.String,
+}).pipe(
+  Type.Obj({
+    typename: 'dxos.org/type/Organization',
+    version: '0.1.0',
+  }),
+);
+interface Organization extends Schema.Schema.Type<typeof Organization> {}
+
+const WorksFor = Schema.Struct({
+  since: Schema.String,
+}).pipe(
+  Type.Relation({
+    typename: 'dxos.org/type/WorksFor',
+    version: '0.1.0',
+    source: Person,
+    target: Organization,
+  }),
+);
+interface WorksFor extends Schema.Schema.Type<typeof WorksFor> {}
+
+const Task = Schema.Struct({
+  title: Schema.String,
+  createdAt: Schema.String,
+  assignee: Schema.optional(Type.Ref(Person)),
+}).pipe(Type.Obj({ typename: 'dxos.org/type/Task', version: '0.1.0' }));
+interface Task extends Schema.Schema.Type<typeof Task> {}
+
+//
+// Example queries
+//
+
+describe('query api', () => {
+  test('get all people', () => {
+    const getAllPeople = Query.type(Person);
+
+    log('query', { ast: getAllPeople.ast });
+    Schema.validateSync(QueryAST.Query)(getAllPeople.ast);
+    console.log('getAllPeople', JSON.stringify(getAllPeople.ast, null, 2));
+  });
+
+  test('get all people named Fred', () => {
+    const PeopleNamedFred = Query.select(Filter.type(Person, { name: 'Fred' }));
+
+    log('query', { ast: PeopleNamedFred.ast });
+    Schema.validateSync(QueryAST.Query)(PeopleNamedFred.ast);
+    console.log('PeopleNamedFred', JSON.stringify(PeopleNamedFred.ast, null, 2));
+  });
+
+  test('get all orgs Fred worked for since 2020', () => {
+    const fred = Obj.make(Person, { name: 'Fred' });
+    const OrganizationsFredWorkedForSince2020 = Query.select(Filter.type(Person, { id: fred.id }))
+      .sourceOf(WorksFor, { since: Filter.gt('2020') })
+      .target();
+
+    log('query', { ast: OrganizationsFredWorkedForSince2020.ast });
+    Schema.validateSync(QueryAST.Query)(OrganizationsFredWorkedForSince2020.ast);
+    console.log(
+      'OrganizationsFredWorkedForSince2020',
+      JSON.stringify(OrganizationsFredWorkedForSince2020.ast, null, 2),
+    );
+  });
+
+  test('get all tasks for Fred', () => {
+    const fred = Obj.make(Person, { name: 'Fred' });
+    const TasksForFred = Query.select(Filter.type(Person, { id: fred.id })).referencedBy(Task, 'assignee');
+
+    log('query', { ast: TasksForFred.ast });
+    Schema.validateSync(QueryAST.Query)(TasksForFred.ast);
+    console.log('TasksForFred', JSON.stringify(TasksForFred.ast, null, 2));
+  });
+
+  test('get all tasks for employees of Cyberdyne', () => {
+    const TasksForEmployeesOfCyberdyne = Query.select(Filter.type(Organization, { name: 'Cyberdyne' }))
+      .targetOf(WorksFor)
+      .source()
+      .referencedBy(Task, 'assignee');
+
+    log('query', { ast: TasksForEmployeesOfCyberdyne.ast });
+    Schema.validateSync(QueryAST.Query)(TasksForEmployeesOfCyberdyne.ast);
+    console.log('TasksForEmployeesOfCyberdyne', JSON.stringify(TasksForEmployeesOfCyberdyne.ast, null, 2));
+  });
+
+  test('get all people or orgs', () => {
+    const PeopleOrOrganizations = Query.all(Query.select(Filter.type(Person)), Query.select(Filter.type(Organization)));
+
+    log('query', { ast: PeopleOrOrganizations.ast });
+    Schema.validateSync(QueryAST.Query)(PeopleOrOrganizations.ast);
+    console.log('PeopleOrOrganizations', JSON.stringify(PeopleOrOrganizations.ast, null, 2));
+  });
+
+  test('get all people not in orgs', () => {
+    const PeopleNotInOrganizations = Query.without(
+      Query.select(Filter.type(Person)),
+      Query.select(Filter.type(Person)).sourceOf(WorksFor).source(),
+    );
+
+    log('query', { ast: PeopleNotInOrganizations.ast });
+    Schema.validateSync(QueryAST.Query)(PeopleNotInOrganizations.ast);
+    console.log('PeopleNotInOrganizations', JSON.stringify(PeopleNotInOrganizations.ast, null, 2));
+  });
+
+  test('get assignees of all tasks created after 2020', () => {
+    const AssigneesOfAllTasksCreatedAfter2020 = Query.select(
+      Filter.type(Task, { createdAt: Filter.gt('2020') }),
+    ).reference('assignee');
+
+    log('query', { ast: AssigneesOfAllTasksCreatedAfter2020.ast });
+    Schema.validateSync(QueryAST.Query)(AssigneesOfAllTasksCreatedAfter2020.ast);
+    console.log(
+      'AssigneesOfAllTasksCreatedAfter2020',
+      JSON.stringify(AssigneesOfAllTasksCreatedAfter2020.ast, null, 2),
+    );
+  });
+
+  test('untyped full-text search', () => {
+    const contactFullTextSearch = Query.select(Filter.text('Bill'));
+
+    log('query', { ast: contactFullTextSearch.ast });
+    Schema.validateSync(QueryAST.Query)(contactFullTextSearch.ast);
+    expect(contactFullTextSearch.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "searchKind": undefined,
+          "text": "Bill",
+          "type": "text-search",
+        },
+        "type": "select",
+      }
+    `);
+  });
+
+  test('typed full-text search', () => {
+    const contactFullTextSearch = Query.select(Filter.type(Person)).select(Filter.text('Bill'));
+
+    log('query', { ast: contactFullTextSearch.ast });
+    Schema.validateSync(QueryAST.Query)(contactFullTextSearch.ast);
+    expect(contactFullTextSearch.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "searchKind": undefined,
+          "text": "Bill",
+          "type": "text-search",
+        },
+        "selection": {
+          "filter": {
+            "id": undefined,
+            "props": {},
+            "type": "object",
+            "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+          },
+          "type": "select",
+        },
+        "type": "filter",
+      }
+    `);
+  });
+
+  test('filter by ref', () => {
+    const fred = Obj.make(Person, { name: 'Fred' });
+    const tasksByFred = Filter.type(Task, { assignee: Ref.make(fred) });
+    expect(tasksByFred.ast).toEqual({
+      props: {
+        assignee: {
+          operator: 'eq',
+          type: 'compare',
+          value: {
+            '/': DXN.fromLocalObjectId(fred.id).toString(),
+          },
+        },
+      },
+      type: 'object',
+      typename: 'dxn:type:dxos.org/type/Task:0.1.0',
+    });
+    console.log('tasksByFred', JSON.stringify(tasksByFred.ast, null, 2));
+  });
+
+  test('select orgs and people', () => {
+    const orgsAndPeople = Query.select(Filter.or(Filter.type(Organization), Filter.type(Person)));
+
+    Schema.validateSync(QueryAST.Query)(orgsAndPeople.ast);
+    expect(orgsAndPeople.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "filters": [
+            {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:dxos.org/type/Organization:0.1.0",
+            },
+            {
+              "id": undefined,
+              "props": {},
+              "type": "object",
+              "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+            },
+          ],
+          "type": "or",
+        },
+        "type": "select",
+      }
+    `);
+  });
+
+  test('select everything but orgs and people', () => {
+    const everythingButOrgsAndPeople = Query.select(
+      Filter.not(Filter.or(Filter.type(Organization), Filter.type(Person))),
+    );
+
+    Schema.validateSync(QueryAST.Query)(everythingButOrgsAndPeople.ast);
+    expect(everythingButOrgsAndPeople.ast).toMatchInlineSnapshot(`
+      {
+        "filter": {
+          "filter": {
+            "filters": [
+              {
+                "id": undefined,
+                "props": {},
+                "type": "object",
+                "typename": "dxn:type:dxos.org/type/Organization:0.1.0",
+              },
+              {
+                "id": undefined,
+                "props": {},
+                "type": "object",
+                "typename": "dxn:type:dxos.org/type/Person:0.1.0",
+              },
+            ],
+            "type": "or",
+          },
+          "type": "not",
+        },
+        "type": "select",
+      }
+    `);
+  });
+
+  test('select deleted tasks', () => {
+    const deletedTasks = Query.select(Filter.type(Task)).options({
+      deleted: 'only',
+    });
+
+    Schema.validateSync(QueryAST.Query)(deletedTasks.ast);
+    expect(deletedTasks.ast).toMatchInlineSnapshot(`
+      {
+        "options": {
+          "deleted": "only",
+        },
+        "query": {
+          "filter": {
+            "id": undefined,
+            "props": {},
+            "type": "object",
+            "typename": "dxn:type:dxos.org/type/Task:0.1.0",
+          },
+          "type": "select",
+        },
+        "type": "options",
+      }
+    `);
+  });
+
+  test.skip('chain', () => {
+    // NOTE: Can't support props without type since they can't be inferred.
+    // const f1: Filter<Person> = Filter.props({ name: 'Fred' });
+
+    // const x = Query.select(Filter.props({ id: '123' }));
+    const y = Query.select(Filter.type(Person));
+
+    const or = Filter.or(Filter.type(Person, { id: Filter.in('1', '2', '3') }), Filter.type(Organization));
+
+    const and = Filter.and(
+      Filter.type(Person, { id: Filter.in('1', '2', '3') }),
+      Filter.type(Person, { name: 'Fred' }),
+    );
+
+    const q = Query
+      //
+      // NOTE: Can't support functions since they can't be serialized (to server).
+      // .filter((object) => Math.random() > 0.5)
+      .select(Filter.type(Person))
+      .select(Filter.type(Person, { name: 'Fred' }))
+      .select({ age: Filter.between(20, 40) })
+      .select(Filter.and(Filter.type(Person), Filter.type(Person, { name: Filter.in('bob', 'bill') })));
+
+    log('stuff', { fOr: or, fAnd: and, q, y });
+  });
+});