@dxos/echo 0.8.4-main.3a94e84 → 0.8.4-main.3c1ae3b

package/src/QueryResult.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type CleanupFn } from '@dxos/async';
+
+import type * as Entity from './Entity';
+
+/**
+ * Individual query result entry.
+ */
+export type Entry<T> = {
+  id: string;
+
+  /**
+   * May not be present for remote results.
+   */
+  result?: T;
+
+  match?: {
+    // TODO(dmaretskyi): text positional info.
+
+    /**
+     * Higher means better match.
+     */
+    rank: number;
+  };
+
+  /**
+   * Query resolution metadata.
+   */
+  // TODO(dmaretskyi): Rename to meta?
+  resolution?: {
+    // TODO(dmaretskyi): Make this more generic.
+    source: 'remote' | 'local' | 'index';
+
+    /**
+     * Query resolution time in milliseconds.
+     */
+    time: number;
+  };
+};
+
+/**
+ * Invidual query result entry for a database Entity.
+ */
+export type EntityEntry<T extends Entity.Unknown = Entity.Unknown> = Entry<T>;
+
+export type RunOptions = {
+  timeout?: number;
+};
+
+export type SubscriptionOptions = {
+  /**
+   * Fire the callback immediately.
+   */
+  fire?: boolean;
+};
+
+export interface QueryResult<T> {
+  /**
+   * Currently available results along with their match metadata.
+   *
+   * @reactive
+   */
+  readonly entries: Entry<T>[];
+
+  /**
+   * Currently available results.
+   *
+   * @reactive
+   */
+  readonly results: T[];
+
+  /**
+   * Returns all known results.
+   */
+  run(opts?: RunOptions): Promise<T[]>;
+
+  /**
+   * Returns all known results along with their match metadata.
+   */
+  runEntries(opts?: RunOptions): Promise<Entry<T>[]>;
+
+  /**
+   * Returns currently available results synchronously.
+   */
+  runSync(): T[];
+
+  /**
+   * Returns currently available results synchronously along with their match metadata.
+   */
+  runSyncEntries(): Entry<T>[];
+
+  /**
+   * Returns first result.
+   */
+  first(opts?: RunOptions): Promise<T>;
+
+  /**
+   * Returns first result if there is one.
+   */
+  firstOrUndefined(opts?: RunOptions): Promise<T | undefined>;
+
+  /**
+   * Subscribes to changes in query results.
+   */
+  subscribe(callback?: (query: QueryResult<T>) => void, opts?: SubscriptionOptions): CleanupFn;
+}

package/src/Ref.ts

@@ -2,28 +2,44 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as EchoSchema from '@dxos/echo-schema';
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
 
+import { Ref as Ref$, RefArray, type RefResolver } from './internal';
+import { getSchemaReference } from './internal';
+import type * as JsonSchema from './JsonSchema';
 import type * as Obj from './Obj';
 
-export type Ref<T> = EchoSchema.Ref<T>;
-export type Any = EchoSchema.Ref<Obj.Any>;
+export type Ref<T> = Ref$<T>;
+export type Any = Ref$<Obj.Any>;
 
-export const Array = EchoSchema.RefArray;
+export const Array = RefArray;
 
 /**
  * Extract reference target.
  */
-export type Target<R extends Any> = R extends EchoSchema.Ref<infer T> ? T : never;
+export type Target<R extends Any> = R extends Ref$<infer T> ? T : never;
 
 /**
  * Reference resolver.
  */
-export type Resolver = EchoSchema.RefResolver;
+export type Resolver = RefResolver;
 
-export const isRef: (value: unknown) => value is Any = EchoSchema.Ref.isRef;
+export const isRef: (value: unknown) => value is Any = Ref$.isRef;
 
-export const make = EchoSchema.Ref.make;
+export const make = Ref$.make;
 
 // TODO(dmaretskyi): Consider just allowing `make` to accept DXN.
-export const fromDXN = EchoSchema.Ref.fromDXN;
+export const fromDXN = Ref$.fromDXN;
+
+// TODO(wittjosiah): Factor out?
+export const isRefType = (ast: SchemaAST.AST): boolean => {
+  return SchemaAST.getAnnotation<JsonSchema.JsonSchema>(ast, SchemaAST.JSONSchemaAnnotationId).pipe(
+    Option.flatMap((jsonSchema) => ('$id' in jsonSchema ? Option.some(jsonSchema) : Option.none())),
+    Option.flatMap((jsonSchema) => {
+      const { typename } = getSchemaReference(jsonSchema) ?? {};
+      return typename ? Option.some(true) : Option.some(false);
+    }),
+    Option.getOrElse(() => false),
+  );
+};

package/src/Relation.ts

@@ -2,43 +2,71 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { raise } from '@dxos/debug';
-import * as EchoSchema from '@dxos/echo-schema';
 import { assertArgument, invariant } from '@dxos/invariant';
-import { DXN } from '@dxos/keys';
-import { type Live, live } from '@dxos/live-object';
+import { DXN, type ObjectId } from '@dxos/keys';
+import { type Live } from '@dxos/live-object';
 import { assumeType } from '@dxos/util';
 
-import type * as Obj from './Obj';
-import type * as Type from './Type';
+import * as Entity from './Entity';
+import {
+  ATTR_RELATION_SOURCE,
+  ATTR_RELATION_TARGET,
+  type AnyEchoObject,
+  EntityKind,
+  type InternalObjectProps,
+  MetaId,
+  type ObjectMeta,
+  RelationSourceDXNId,
+  RelationSourceId,
+  RelationTargetDXNId,
+  RelationTargetId,
+  getObjectDXN,
+  getTypeAnnotation,
+  makeObject,
+} from './internal';
+import * as Obj from './Obj';
+import * as Type from './Type';
 
-// NOTE: Don't export: Relation.Relation and Relation.Any form the public API.
-interface RelationBase<Source, Target>
-  extends Type.Relation.Endpoints<Source, Target>,
-    Type.OfKind<EchoSchema.EntityKind.Relation> {
-  readonly id: EchoSchema.ObjectId;
-}
+/**
+ * Base type for all ECHO relations.
+ * @private
+ */
+interface BaseRelation<Source, Target>
+  extends AnyEchoObject,
+    Type.Relation.Endpoints<Source, Target>,
+    Entity.OfKind<EntityKind.Relation> {}
 
 /**
- * Relation type with specific properties.
+ * Base type for all Relations objects.
  */
-export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = RelationBase<Source, Target> & Props;
+export interface Any extends BaseRelation<Obj.Any, Obj.Any> {}
+
+export const Any = Schema.Struct({}).pipe(
+  Type.Relation({
+    typename: 'dxos.org/type/Any',
+    version: '0.1.0',
+    source: Obj.Any,
+    target: Obj.Any,
+  }),
+);
 
 /**
- * Base type for all ECHO relations.
+ * Relation type with specific source and target types.
  */
-export interface Any extends RelationBase<Obj.Any, Obj.Any> {}
+export type Relation<Source extends Obj.Any, Target extends Obj.Any, Props> = BaseRelation<Source, Target> & Props;
 
-// TODO(dmaretskyi): Has to be `unique symbol`.
-export const Source: unique symbol = EchoSchema.RelationSourceId as any;
+export const Source: unique symbol = RelationSourceId as any;
 export type Source = typeof Source;
-export const Target: unique symbol = EchoSchema.RelationTargetId as any;
+
+export const Target: unique symbol = RelationTargetId as any;
 export type Target = typeof Target;
 
 type MakeProps<T extends Any> = {
-  id?: EchoSchema.ObjectId;
+  id?: ObjectId;
+  [MetaId]?: ObjectMeta;
   [Source]: T[Source];
   [Target]: T[Target];
 } & Type.Properties<T>;
@@ -55,36 +83,34 @@ type MakeProps<T extends Any> = {
 export const make = <S extends Type.Relation.Any>(
   schema: S,
   props: NoInfer<MakeProps<Schema.Schema.Type<S>>>,
-  meta?: EchoSchema.ObjectMeta,
-): Live<Schema.Schema.Type<S> & Type.OfKind<EchoSchema.EntityKind.Relation>> => {
-  assertArgument(
-    EchoSchema.getTypeAnnotation(schema)?.kind === EchoSchema.EntityKind.Relation,
-    'Expected a relation schema',
-  );
-
-  if (props[EchoSchema.MetaId] != null) {
-    meta = props[EchoSchema.MetaId] as any;
-    delete props[EchoSchema.MetaId];
+  meta?: ObjectMeta,
+): Live<Schema.Schema.Type<S> & Entity.OfKind<typeof Entity.Kind.Relation>> => {
+  assertArgument(getTypeAnnotation(schema)?.kind === EntityKind.Relation, 'schema', 'Expected a relation schema');
+
+  if (props[MetaId] != null) {
+    meta = props[MetaId] as any;
+    delete props[MetaId];
   }
 
-  const sourceDXN = EchoSchema.getObjectDXN(props[Source]) ?? raise(new Error('Unresolved relation source'));
-  const targetDXN = EchoSchema.getObjectDXN(props[Target]) ?? raise(new Error('Unresolved relation target'));
-  (props as any)[EchoSchema.RelationSourceDXNId] = sourceDXN;
-  (props as any)[EchoSchema.RelationTargetDXNId] = targetDXN;
+  const sourceDXN = getObjectDXN(props[Source]) ?? raise(new Error('Unresolved relation source'));
+  const targetDXN = getObjectDXN(props[Target]) ?? raise(new Error('Unresolved relation target'));
+
+  (props as any)[RelationSourceDXNId] = sourceDXN;
+  (props as any)[RelationTargetDXNId] = targetDXN;
 
-  return live<Schema.Schema.Type<S>>(schema, props as any, meta);
+  return makeObject<Schema.Schema.Type<S>>(schema, props as any, meta);
 };
 
 export const isRelation = (value: unknown): value is Any => {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
-  if (EchoSchema.ATTR_RELATION_SOURCE in value || EchoSchema.ATTR_RELATION_TARGET in value) {
+  if (ATTR_RELATION_SOURCE in value || ATTR_RELATION_TARGET in value) {
     return true;
   }
 
-  const kind = (value as any)[EchoSchema.EntityKindId];
-  return kind === EchoSchema.EntityKind.Relation;
+  const kind = (value as any)[Entity.KindId];
+  return kind === EntityKind.Relation;
 };
 
 /**
@@ -93,8 +119,8 @@ export const isRelation = (value: unknown): value is Any => {
  */
 export const getSourceDXN = (value: Any): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
-  assumeType<EchoSchema.InternalObjectProps>(value);
-  const dxn = (value as EchoSchema.InternalObjectProps)[EchoSchema.RelationSourceDXNId];
+  assumeType<InternalObjectProps>(value);
+  const dxn = (value as InternalObjectProps)[RelationSourceDXNId];
   invariant(dxn instanceof DXN);
   return dxn;
 };
@@ -105,8 +131,8 @@ export const getSourceDXN = (value: Any): DXN => {
  */
 export const getTargetDXN = (value: Any): DXN => {
   assertArgument(isRelation(value), 'Expected a relation');
-  assumeType<EchoSchema.InternalObjectProps>(value);
-  const dxn = (value as EchoSchema.InternalObjectProps)[EchoSchema.RelationTargetDXNId];
+  assumeType<InternalObjectProps>(value);
+  const dxn = (value as InternalObjectProps)[RelationTargetDXNId];
   invariant(dxn instanceof DXN);
   return dxn;
 };
@@ -117,8 +143,8 @@ export const getTargetDXN = (value: Any): DXN => {
  */
 export const getSource = <T extends Any>(relation: T): Type.Relation.Source<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
-  assumeType<EchoSchema.InternalObjectProps>(relation);
-  const obj = (relation as EchoSchema.InternalObjectProps)[EchoSchema.RelationSourceId];
+  assumeType<InternalObjectProps>(relation);
+  const obj = (relation as InternalObjectProps)[RelationSourceId];
   invariant(obj !== undefined, `Invalid source: ${relation.id}`);
   return obj as Type.Relation.Source<T>;
 };
@@ -129,8 +155,8 @@ export const getSource = <T extends Any>(relation: T): Type.Relation.Source<T> =
  */
 export const getTarget = <T extends Any>(relation: T): Type.Relation.Target<T> => {
   assertArgument(isRelation(relation), 'Expected a relation');
-  assumeType<EchoSchema.InternalObjectProps>(relation);
-  const obj = (relation as EchoSchema.InternalObjectProps)[EchoSchema.RelationTargetId];
+  assumeType<InternalObjectProps>(relation);
+  const obj = (relation as InternalObjectProps)[RelationTargetId];
   invariant(obj !== undefined, `Invalid target: ${relation.id}`);
   return obj as Type.Relation.Target<T>;
 };

package/src/SchemaRegistry.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Types from 'effect/Types';
+
+import type * as JsonSchema from './JsonSchema';
+import type * as Key from './Key';
+import type * as QueryResult from './QueryResult';
+import type * as Type from './Type';
+
+// TODO(wittjosiah): Replace w/ Query.Query.
+export type Query = {
+  /**
+   * Filter by schema ID.
+   * Schema id is a DXN with `echo` or `type` kind.
+   */
+  id?: string | string[];
+
+  /**
+   * Id of the backing ECHO object.
+   */
+  backingObjectId?: Key.ObjectId | Key.ObjectId[];
+
+  /**
+   * One or more typenames to filter by.
+   */
+  typename?: string | string[];
+
+  /**
+   * [Semver Range](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges) for the schema version.
+   */
+  version?: string;
+
+  /**
+   * Where to look for the schema.
+   *
+   * Database schema are stored in the database of the current space.
+   * Runtime schema are registered in the runtime.
+   *
+   * @default ['database']
+   */
+  location?: ('database' | 'runtime')[];
+
+  /**
+   * Include system schemas.
+   * @default false
+   *
+   * The system schema include but are not limited to:
+   *  - dxos.org/type/Schema
+   */
+  includeSystem?: boolean;
+};
+
+/**
+ * Input for schema registration.
+ * The typename, version and schema mutability metadata is read from the schema annotations.
+ */
+export type RegisterSchemaInput =
+  | Type.Entity.Any
+  | {
+      typename: string;
+      version: string;
+      jsonSchema: JsonSchema.JsonSchema;
+      /**
+       * Display name of the schema.
+       */
+      name?: string;
+    };
+
+export type ExtractQueryResult<Query> = Query extends { location: ('database' | 'runtime')[] }
+  ? Type.Entity.Any
+  : Type.RuntimeType;
+
+export interface SchemaRegistry {
+  /**
+   * Registers the provided schema.
+   *
+   * @returns Mutable runtime instances of schemas that were registered.
+   *
+   * The behavior of this method depends on the state of the database.
+   * The general principle is that the schema will be upserted into the space.
+   * If an equivalent schema with the same name and version already exists, the method does nothing.
+   * If a different schema with the same name and version exists, the method throws an error.
+   * If no schema with the same name and version exists, a new schema will be inserted based on semantic versioning rules.
+   */
+  register(input: RegisterSchemaInput[]): Promise<Type.RuntimeType[]>;
+
+  query<Q extends Types.NoExcessProperties<Query, Q>>(
+    query?: Q & Query,
+  ): QueryResult.QueryResult<ExtractQueryResult<Q>>;
+}

package/src/Tag.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { LabelAnnotation, SystemTypeAnnotation } from './internal';
+import * as Obj from './Obj';
+import * as Type from './Type';
+
+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',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['label']),
+  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);
+
+export const createTagList = (tags: Map): Tag[] =>
+  Object.entries(tags)
+    .map(([id, tag]) => ({ ...tag, id }))
+    .sort(sortTags);
+
+export const findTagByLabel = (tags: Map | undefined, name: string): Tag | undefined => {
+  const entry = Object.entries(tags ?? {}).find(([_, tag]) => tag.label.toLowerCase() === name.toLowerCase());
+  return entry ? { ...entry[1], id: entry[0] } : undefined;
+};