@dxos/echo 0.8.4-main.dedc0f3 → 0.8.4-main.e00bdcdb52

package/src/Filter.ts

@@ -0,0 +1,454 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+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 * as internal from './internal';
+import type * as Obj from './Obj';
+import * as Ref from './Ref';
+
+export interface Filter<T> {
+  // TODO(dmaretskyi): See new effect-schema approach to variance.
+  '~Filter': { value: Types.Covariant<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>> => {
+  if (Schema.isSchema(schema) && SchemaAST.isUnion(schema.ast)) {
+    const typenames = schema.ast.types.map((type) => internal.getTypeDXNFromSpecifier(Schema.make(type)));
+    return new FilterClass({
+      type: 'or',
+      filters: typenames.map((typename) => ({
+        type: 'object',
+        typename: typename.toString(),
+        props: {},
+      })),
+    });
+  }
+
+  const dxn = internal.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 = internal.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> => {
+  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<T> => {
+  return new FilterClass({
+    type: 'range',
+    from,
+    to,
+  });
+};
+
+type TimeRange = { after?: Date | number; before?: Date | number };
+
+const _toUnixMs = (date: Date | number): number => (typeof date === 'number' ? date : date.getTime());
+
+const _timeRangeFilter = (field: 'updatedAt' | 'createdAt', range: TimeRange): Any => {
+  const filters: Any[] = [];
+  if (range.after != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'gte', value: _toUnixMs(range.after) }));
+  }
+  if (range.before != null) {
+    filters.push(new FilterClass({ type: 'timestamp', field, operator: 'lte', value: _toUnixMs(range.before) }));
+  }
+  if (filters.length === 0) {
+    return everything();
+  }
+  return filters.length === 1 ? filters[0] : and(...filters);
+};
+
+/**
+ * Filter objects by updatedAt timestamp.
+ */
+export const updated = (range: TimeRange): Any => _timeRangeFilter('updatedAt', range);
+
+/**
+ * Filter objects by createdAt timestamp.
+ */
+export const created = (range: TimeRange): Any => _timeRangeFilter('createdAt', range);
+
+export type ChildOfOptions = {
+  /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
+  transitive?: boolean;
+};
+
+/**
+ * Filter objects that are children of the specified parent(s).
+ * Accepts ECHO objects, Refs, or arrays of either.
+ * Refs are resolved to DXNs without loading; objects use {@link Obj.getDXN}.
+ * With transitive=true (default), also matches grandchildren and beyond.
+ */
+export const childOf = (
+  parents: Obj.Unknown | Ref.Unknown | readonly (Obj.Unknown | Ref.Unknown)[],
+  options?: ChildOfOptions,
+): Any => {
+  const items = Array.isArray(parents) ? parents : [parents];
+  const dxns = items.map((item) => {
+    if (Ref.isRef(item)) {
+      return item.dxn.toString();
+    }
+    return internal.getDXN(item).toString();
+  });
+  return new FilterClass({
+    type: 'child-of',
+    parents: dxns,
+    transitive: options?.transitive ?? true,
+  });
+};
+
+/**
+ * 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),
+  );
+};
+
+/**
+ * Returns a human-readable string representation of a Filter AST.
+ */
+export const pretty = (filter: Any): string => internal.prettyFilter(filter.ast);

package/src/Format.ts

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

package/src/Hypergraph.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type DXN } from '@dxos/keys';
+
+import type * as Database from './Database';
+import type * as Entity from './Entity';
+import type * as internal 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: internal.AnyProperties) => internal.AnyProperties;
+}
+
+/**
+ * Manages cross-space database interactions.
+ */
+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;
+
+  /**
+   * Get a database by space ID.
+   * @returns The database for the given space ID, or undefined if not found.
+   */
+  getDatabase(spaceId: Key.SpaceId): Database.Database | undefined;
+}