@dxos/echo 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/Entity.ts

@@ -0,0 +1,217 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { ForeignKey } from '@dxos/echo-protocol';
+import type { DXN, ObjectId } from '@dxos/keys';
+
+import {
+  type ChangeCallback,
+  EntityKind,
+  EntityKindSchema,
+  KindId,
+  type Mutable,
+  type ObjectJSON,
+  type ObjectMeta,
+  type ReadonlyMeta,
+  SnapshotKindId,
+  addTag as addTag$,
+  change as change$,
+  getDXN as getDXN$,
+  getDatabase as getDatabase$,
+  getDescription as getDescription$,
+  getEntityKind,
+  getKeys as getKeys$,
+  getLabel as getLabel$,
+  getMetaChecked as getMeta$,
+  getTypeDXN as getTypeDXN$,
+  getTypename as getTypename$,
+  isDeleted as isDeleted$,
+  removeTag as removeTag$,
+  subscribe as subscribe$,
+  objectToJSON as toJSON$,
+} from './internal';
+
+// Re-export KindId and SnapshotKindId from internal.
+export { KindId, SnapshotKindId };
+
+// NOTE: Relation does not extend Obj so that, for example, we can prevent Relations from being used as source and target objects.
+//  However, we generally refer to Obj and Relation instances as "objects",
+//  and many API methods accept both Obj.Unknown and Relation.Unknown (i.e., Entity.Unknown) instances.
+
+export const Kind = EntityKind;
+export type Kind = EntityKind;
+export const KindSchema = EntityKindSchema;
+
+/**
+ * Assigns a kind to an Object or Relation instance.
+ * NOTE: Needed to make `isRelation` and `isObject` checks work.
+ */
+export interface OfKind<K extends Kind> {
+  readonly [KindId]: K;
+  readonly id: ObjectId;
+}
+
+/**
+ * Assigns a snapshot kind to an Object or Relation snapshot.
+ */
+export interface SnapshotOfKind<K extends Kind> {
+  readonly [SnapshotKindId]: K;
+  readonly id: ObjectId;
+}
+
+/**
+ * Obj or Relation with a specific set of properties.
+ */
+export type Entity<Props> = OfKind<Kind> & Props;
+
+/**
+ * Unknown Obj or Relation (reactive).
+ */
+export interface Unknown extends OfKind<Kind> {}
+
+/**
+ * Snapshot of an Obj or Relation.
+ * Branded with SnapshotKindId instead of KindId.
+ */
+export interface Snapshot extends SnapshotOfKind<Kind> {}
+
+/**
+ * Object with arbitrary properties.
+ *
+ * NOTE: Due to how typescript works, this type is not assignable to a specific schema type.
+ * In that case, use `Obj.instanceOf` to check if an object is of a specific type.
+ *
+ * This type is very permissive and allows accessing any property on the object.
+ * We should move to Obj.Unknown that is not permissive and requires explicit instanceof checks..
+ */
+export interface Any extends OfKind<Kind> {
+  [key: string]: unknown;
+}
+
+export const getKind = getEntityKind;
+
+//
+// Entity-level functions that work on any entity (object or relation).
+// Use these when you don't know or care about the specific entity kind.
+// For kind-specific functions, use Obj.* or Relation.*.
+//
+
+/**
+ * JSON representation of an entity.
+ */
+export type JSON = ObjectJSON;
+
+/**
+ * Get the DXN of an entity (object or relation).
+ */
+export const getDXN = (entity: Unknown | Snapshot): DXN => getDXN$(entity);
+
+/**
+ * Get the DXN of an entity's type.
+ */
+export const getTypeDXN = getTypeDXN$;
+
+/**
+ * Get the typename of an entity's type.
+ */
+export const getTypename = (entity: Unknown | Snapshot): string | undefined => getTypename$(entity);
+
+/**
+ * Get the database an entity belongs to.
+ */
+export const getDatabase = (entity: Unknown | Snapshot): any | undefined => getDatabase$(entity);
+
+/**
+ * Get the metadata for an entity.
+ * Returns mutable meta when passed a mutable entity (inside change callback).
+ * Returns read-only meta when passed a regular entity or snapshot.
+ */
+// TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
+export function getMeta(entity: Mutable<Unknown>): ObjectMeta;
+export function getMeta(entity: Unknown | Snapshot): ReadonlyMeta;
+export function getMeta(entity: Unknown | Snapshot | Mutable<Unknown>): ObjectMeta | ReadonlyMeta {
+  return getMeta$(entity);
+}
+
+/**
+ * Get foreign keys for an entity from the specified source.
+ */
+export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[] => getKeys$(entity, source);
+
+/**
+ * Check if an entity is deleted.
+ */
+export const isDeleted = (entity: Unknown | Snapshot): boolean => isDeleted$(entity);
+
+/**
+ * Get the label of an entity.
+ */
+export const getLabel = (entity: Unknown | Snapshot): string | undefined => getLabel$(entity);
+
+/**
+ * Get the description of an entity.
+ */
+export const getDescription = (entity: Unknown | Snapshot): string | undefined => getDescription$(entity);
+
+/**
+ * Convert an entity to its JSON representation.
+ */
+export const toJSON = (entity: Unknown | Snapshot): JSON => toJSON$(entity);
+
+/**
+ * Subscribe to changes on an entity (object or relation).
+ * @returns Unsubscribe function.
+ */
+export const subscribe = (entity: Unknown, callback: () => void): (() => void) => {
+  return subscribe$(entity, callback);
+};
+
+//
+// Change
+//
+
+/**
+ * Used to provide a mutable view of an entity within `Entity.change`.
+ */
+export type { Mutable };
+
+/**
+ * Perform mutations on an entity (object or relation) within a change context.
+ *
+ * Entities are read-only by default. Mutations are batched and notifications fire
+ * when the callback completes. Direct mutations outside of `Entity.change` will throw
+ * at runtime.
+ *
+ * @param entity - The echo entity (object or relation) to mutate.
+ * @param callback - Receives a mutable view of the entity. All mutations must occur here.
+ *
+ * @example
+ * ```typescript
+ * // Mutate within Entity.change
+ * Entity.change(entity, (e) => {
+ *   e.name = 'Updated';
+ *   e.count = 42;
+ * });
+ *
+ * // Direct mutation throws
+ * entity.name = 'Bob'; // Error: Cannot modify outside Entity.change()
+ * ```
+ *
+ * Note: For type-specific operations, prefer `Obj.change` or `Relation.change`.
+ */
+export const change = <T extends Unknown>(entity: T, callback: ChangeCallback<T>): void => {
+  change$(entity, callback);
+};
+
+/**
+ * Add a tag to an entity.
+ * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ */
+export const addTag = (entity: Mutable<Unknown>, tag: string): void => addTag$(entity, tag);
+
+/**
+ * Remove a tag from an entity.
+ * Must be called within an `Entity.change`, `Obj.change`, or `Relation.change` callback.
+ */
+export const removeTag = (entity: Mutable<Unknown>, tag: string): void => removeTag$(entity, tag);

package/src/Err.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+import { type DXN } from '@dxos/keys';
+
+export class SchemaNotFoundError extends BaseError.extend('SchemaNotFoundError', 'Schema not found') {
+  constructor(schema: string, options?: BaseErrorOptions) {
+    super({ context: { schema }, ...options });
+  }
+}
+
+export class ObjectNotFoundError extends BaseError.extend('ObjectNotFoundError', 'Object not found') {
+  constructor(dxn: DXN, options?: BaseErrorOptions) {
+    super({ context: { dxn }, ...options });
+  }
+}

package/src/Filter.ts

@@ -0,0 +1,376 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+import { type ForeignKey, type QueryAST } from '@dxos/echo-protocol';
+import { assertArgument } from '@dxos/invariant';
+import { DXN, ObjectId } from '@dxos/keys';
+
+import { getTypeDXNFromSpecifier } from './internal';
+import * as Ref from './Ref';
+
+export interface Filter<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Filter': { value: Types.Contravariant<T> };
+
+  ast: QueryAST.Filter;
+}
+
+export type Props<T> = {
+  // Predicate or a value as a shorthand for `eq`.
+  [K in keyof T & string]?: Filter<T[K]> | T[K];
+};
+
+export type Any = Filter<any>;
+
+export type Type<F extends Any> = F extends Filter<infer T> ? T : never;
+
+class FilterClass implements Any {
+  private static variance: Any['~Filter'] = {} as Any['~Filter'];
+
+  constructor(public readonly ast: QueryAST.Filter) {}
+
+  '~Filter' = FilterClass.variance;
+}
+
+export const is = (value: unknown): value is Any => {
+  return typeof value === 'object' && value !== null && '~Filter' in value;
+};
+
+/** Construct a filter from an ast. */
+export const fromAst = (ast: QueryAST.Filter): Any => {
+  return new FilterClass(ast);
+};
+
+/**
+ * Filter that matches all objects.
+ */
+// TODO(dmaretskyi): `Entity.Any` would be more type-safe, but causes annoying errors in existing code
+export const everything = (): FilterClass => {
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    props: {},
+  });
+};
+
+/**
+ * Filter that matches no objects.
+ */
+export const nothing = (): FilterClass => {
+  return new FilterClass({
+    type: 'not',
+    filter: {
+      type: 'object',
+      typename: null,
+      props: {},
+    },
+  });
+};
+
+/*
+ * Filter by ObjectId.
+ */
+export const id = (...ids: ObjectId[]): Any => {
+  assertArgument(
+    ids.every((id) => ObjectId.isValid(id)),
+    'ids',
+    'ids must be valid',
+  );
+
+  if (ids.length === 0) {
+    return nothing();
+  }
+
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    id: ids,
+    props: {},
+  });
+};
+
+/**
+ * Filter by type.
+ */
+export const type = <S extends Schema.Schema.All>(
+  schema: S | string,
+  props?: Props<Schema.Schema.Type<S>>,
+): Filter<Schema.Schema.Type<S>> => {
+  const dxn = getTypeDXNFromSpecifier(schema);
+  return new FilterClass({
+    type: 'object',
+    typename: dxn.toString(),
+    ...propsFilterToAst(props ?? {}),
+  });
+};
+
+/**
+ * Filter by non-qualified typename.
+ */
+export const typename = (typename: string): Any => {
+  assertArgument(!typename.startsWith('dxn:'), 'typename', 'Typename must no be qualified');
+  return new FilterClass({
+    type: 'object',
+    typename: DXN.fromTypename(typename).toString(),
+    props: {},
+  });
+};
+
+/**
+ * Filter by fully qualified type DXN.
+ */
+export const typeDXN = (dxn: DXN): Any => {
+  return new FilterClass({
+    type: 'object',
+    typename: dxn.toString(),
+    props: {},
+  });
+};
+
+/**
+ * Filter by tag.
+ */
+export const tag = (tag: string): Any => {
+  return new FilterClass({
+    type: 'tag',
+    tag,
+  });
+};
+
+/**
+ * Filter by properties.
+ */
+export const props = <T>(props: Props<T>): Filter<T> => {
+  return new FilterClass({
+    type: 'object',
+    typename: null,
+    ...propsFilterToAst(props),
+  });
+};
+
+export type TextSearchOptions = {
+  // TODO(dmaretskyi): Hybrid search.
+  type?: 'full-text' | 'vector';
+};
+
+/**
+ * Full-text or vector search.
+ */
+export const text = (
+  // TODO(dmaretskyi): Consider passing a vector here, but really the embedding should be done on the query-executor side.
+  text: string,
+  options?: TextSearchOptions,
+): Any => {
+  return new FilterClass({
+    type: 'text-search',
+    text,
+    searchKind: options?.type,
+  });
+};
+
+/**
+ * Filter by foreign keys.
+ */
+export const foreignKeys = <S extends Schema.Schema.All>(
+  schema: S | string,
+  keys: ForeignKey[],
+): Filter<Schema.Schema.Type<S>> => {
+  const dxn = getTypeDXNFromSpecifier(schema);
+  return new FilterClass({
+    type: 'object',
+    typename: dxn.toString(),
+    props: {},
+    foreignKeys: keys,
+  });
+};
+
+/**
+ * Predicate for property to be equal to the provided value.
+ */
+export const eq = <T>(value: T): Filter<T | undefined> => {
+  if (!Ref.isRef(value) && typeof value === 'object' && value !== null) {
+    throw new TypeError('Cannot use object as a value for eq filter');
+  }
+
+  return new FilterClass({
+    type: 'compare',
+    operator: 'eq',
+    value: Ref.isRef(value) ? value.noInline().encode() : value,
+  });
+};
+
+/**
+ * Predicate for property to be not equal to the provided value.
+ */
+export const neq = <T>(value: T): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'compare',
+    operator: 'neq',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be greater than the provided value.
+ */
+export const gt = <T>(value: T): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'compare',
+    operator: 'gt',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be greater than or equal to the provided value.
+ */
+export const gte = <T>(value: T): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'compare',
+    operator: 'gte',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be less than the provided value.
+ */
+export const lt = <T>(value: T): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'compare',
+    operator: 'lt',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be less than or equal to the provided value.
+ */
+export const lte = <T>(value: T): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'compare',
+    operator: 'lte',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be in the provided array.
+ * @param values - Values to check against.
+ */
+const in$ = <T>(...values: T[]): Filter<T | undefined> => {
+  return new FilterClass({
+    type: 'in',
+    values,
+  });
+};
+export { in$ as in };
+
+/**
+ * Predicate for an array property to contain the provided value.
+ * @param value - Value to check against.
+ */
+export const contains = <T>(value: T): Filter<readonly T[] | undefined> => {
+  return new FilterClass({
+    type: 'contains',
+    value,
+  });
+};
+
+/**
+ * Predicate for property to be in the provided range.
+ * @param from - Start of the range (inclusive).
+ * @param to - End of the range (exclusive).
+ */
+export const between = <T>(from: T, to: T): Filter<unknown> => {
+  return new FilterClass({
+    type: 'range',
+    from,
+    to,
+  });
+};
+
+/**
+ * Negate the filter.
+ */
+export const not = <F extends Any>(filter: F): Filter<Type<F>> => {
+  return new FilterClass({
+    type: 'not',
+    filter: filter.ast,
+  });
+};
+
+/**
+ * Combine filters with a logical AND.
+ */
+export const and = <Filters extends readonly Any[]>(...filters: Filters): Filter<Type<Filters[number]>> => {
+  return new FilterClass({
+    type: 'and',
+    filters: filters.map((f) => f.ast),
+  });
+};
+
+/**
+ * Combine filters with a logical OR.
+ */
+export const or = <Filters extends readonly Any[]>(...filters: Filters): Filter<Type<Filters[number]>> => {
+  return new FilterClass({
+    type: 'or',
+    filters: filters.map((f) => f.ast),
+  });
+};
+
+// TODO(dmaretskyi): Add `Filter.match` to support pattern matching on string props.
+
+const propsFilterToAst = (predicates: Props<any>): Pick<QueryAST.FilterObject, 'id' | 'props'> => {
+  let idFilter: readonly ObjectId[] | undefined;
+  if ('id' in predicates) {
+    assertArgument(
+      typeof predicates.id === 'string' || Array.isArray(predicates.id),
+      'predicates.id',
+      'invalid id filter',
+    );
+    idFilter = typeof predicates.id === 'string' ? [predicates.id] : predicates.id;
+    Schema.Array(ObjectId).pipe(Schema.validateSync)(idFilter);
+  }
+
+  return {
+    id: idFilter,
+    props: Object.fromEntries(
+      Object.entries(predicates)
+        .filter(([prop, _value]) => prop !== 'id')
+        .map(([prop, predicate]) => [prop, processPredicate(predicate)]),
+    ) as Record<string, QueryAST.Filter>,
+  };
+};
+
+const processPredicate = (predicate: any): QueryAST.Filter => {
+  return Match.value(predicate).pipe(
+    Match.withReturnType<QueryAST.Filter>(),
+    Match.when(is, (predicate) => predicate.ast),
+    // TODO(wittjosiah): Add support for array predicates.
+    Match.when(Array.isArray, (_predicate) => {
+      throw new Error('Array predicates are not yet supported.');
+    }),
+    Match.when(
+      (predicate: any) => !Ref.isRef(predicate) && typeof predicate === 'object' && predicate !== null,
+      (predicate) => {
+        const nestedProps = Object.fromEntries(
+          Object.entries(predicate).map(([key, value]) => [key, processPredicate(value)]),
+        );
+
+        return {
+          type: 'object',
+          typename: null,
+          props: nestedProps,
+        };
+      },
+    ),
+    Match.orElse((value) => eq(value).ast),
+  );
+};

package/src/Format.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type TypeFormat as Format } from './internal';
+
+export * from './internal/formats';
+
+export type { Format };

package/src/Hypergraph.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type DXN } from '@dxos/keys';
+
+import type * as Database from './Database';
+import type * as Entity from './Entity';
+import { type AnyProperties } from './internal';
+import type * as Key from './Key';
+import type * as Ref from './Ref';
+import type * as SchemaRegistry from './SchemaRegistry';
+
+/**
+ * Resolution context.
+ * Affects how non-absolute DXNs are resolved.
+ */
+export interface RefResolutionContext {
+  /**
+   * Space that the resolution is happening from.
+   */
+  space?: Key.SpaceId;
+
+  /**
+   * Queue that the resolution is happening from.
+   * This queue will be searched first, and then the space it belongs to.
+   */
+  queue?: DXN;
+}
+
+export interface RefResolverOptions {
+  /**
+   * Resolution context.
+   * Affects how non-absolute DXNs are resolved.
+   */
+  context?: RefResolutionContext;
+
+  /**
+   * Middleware to change the resolved object before returning it.
+   * @deprecated On track to be removed.
+   */
+  middleware?: (obj: AnyProperties) => AnyProperties;
+}
+
+/**
+ *
+ */
+// TODO(burdon): Comment required.
+export interface Hypergraph extends Database.Queryable {
+  get schemaRegistry(): SchemaRegistry.SchemaRegistry;
+
+  /**
+   * Query objects.
+   */
+  query: Database.QueryFn;
+
+  /**
+   * Creates a reference to an existing object in the database.
+   *
+   * NOTE: The reference may be dangling if the object is not present in the database.
+   * NOTE: Difference from `Ref.fromDXN`
+   * `Ref.fromDXN(dxn)` returns an unhydrated reference. The `.load` and `.target` APIs will not work.
+   * `db.makeRef(dxn)` is preferable in cases with access to the database.
+   */
+  makeRef<T extends Entity.Unknown = Entity.Unknown>(dxn: DXN): Ref.Ref<T>;
+
+  /**
+   * @param hostDb Host database for reference resolution.
+   * @param middleware Called with the loaded object. The caller may change the object.
+   * @returns Result of `onLoad`.
+   */
+  // TODO(dmaretskyi): Restructure API: Remove middleware.
+  createRefResolver(options: RefResolverOptions): Ref.Resolver;
+}

package/src/JsonSchema.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+
+import { JsonSchemaType } from './internal';
+
+export { toEffectSchema, toJsonSchema } from './internal';
+
+/**
+ * Serializable JsonSchema type definition.
+ */
+export type JsonSchema = JsonSchemaType;
+
+export const JsonSchema: Schema.Schema<JsonSchemaType> = JsonSchemaType;