@dxos/echo-protocol 0.8.3 → 0.8.4-main.1c7ec43d41

package/src/document-structure.ts

@@ -8,7 +8,7 @@ import { visitValues } from '@dxos/util';
 
 import { type RawString } from './automerge';
 import type { ForeignKey } from './foreign-key';
-import { isEncodedReference, type EncodedReference } from './reference';
+import { type EncodedReference, isEncodedReference } from './reference';
 import { type SpaceDocVersion } from './space-doc-version';
 
 export type SpaceState = {
@@ -137,6 +137,10 @@ export const ObjectStructure = Object.freeze({
     return object.system?.target;
   },
 
+  getParent: (object: ObjectStructure): EncodedReference | undefined => {
+    return object.system?.parent;
+  },
+
   /**
    * @returns All references in the data section of the object.
    */
@@ -153,6 +157,10 @@ export const ObjectStructure = Object.freeze({
     return references;
   },
 
+  getTags: (object: ObjectStructure): string[] => {
+    return object.meta.tags ?? [];
+  },
+
   makeObject: ({
     type,
     data,
@@ -214,6 +222,14 @@ export type ObjectMeta = {
    * Foreign keys.
    */
   keys: ForeignKey[];
+
+  /**
+   * Tags.
+   * An array of DXNs of Tag objects within the space.
+   *
+   * NOTE: Optional for backwards compatibilty.
+   */
+  tags?: string[];
 };
 
 /**
@@ -236,13 +252,19 @@ export type ObjectSystem = {
    */
   deleted?: boolean;
 
+  /**
+   * Object parent.
+   * Objects with no parent are at the top level of the object hierarchy in the space.
+   */
+  parent?: EncodedReference;
+
   /**
    * Only for relations.
    */
   source?: EncodedReference;
 
   /**
-   * Only for relations.w
+   * Only for relations.
    */
   target?: EncodedReference;
 };

package/src/echo-feed-codec.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { FeedProtocol } from '@dxos/protocols';
+
+import type { ForeignKey } from './foreign-key';
+
+/** Property name for meta when object is serialized to JSON. Matches @dxos/echo/internal ATTR_META. */
+const ATTR_META = '@meta';
+
+/**
+ * Codec for ECHO objects in feed block payload: JSON object ↔ UTF-8 bytes.
+ * Encodes with queue position stripped; decodes with optional position injection.
+ */
+export class EchoFeedCodec {
+  static readonly #encoder = new TextEncoder();
+  static readonly #decoder = new TextDecoder();
+
+  /**
+   * Prepares a value for feed storage (strips queue position from metadata) and encodes to bytes.
+   */
+  static encode(value: Record<string, unknown>): Uint8Array {
+    const prepared = EchoFeedCodec.#stripQueuePosition(value);
+    return EchoFeedCodec.#encoder.encode(JSON.stringify(prepared));
+  }
+
+  /**
+   * Decodes feed block bytes to a JSON value.
+   * If position is provided, injects queue position into the decoded object's metadata.
+   */
+  static decode(data: Uint8Array, position?: number): Record<string, unknown> {
+    const decoded = JSON.parse(EchoFeedCodec.#decoder.decode(data));
+    if (position !== undefined && typeof decoded === 'object' && decoded !== null) {
+      EchoFeedCodec.#setQueuePosition(decoded, position);
+    }
+    return decoded;
+  }
+
+  static #stripQueuePosition(value: Record<string, unknown>): Record<string, unknown> {
+    if (typeof value !== 'object' || value === null) {
+      return value;
+    }
+    const obj = structuredClone(value);
+    const meta = obj[ATTR_META] as { keys?: ForeignKey[] } | undefined;
+    if (meta?.keys?.some((key: ForeignKey) => key.source === FeedProtocol.KEY_QUEUE_POSITION)) {
+      meta.keys = meta.keys.filter((key: ForeignKey) => key.source !== FeedProtocol.KEY_QUEUE_POSITION);
+    }
+    return obj;
+  }
+
+  static #setQueuePosition(obj: Record<string, any>, position: number): void {
+    obj[ATTR_META] ??= { keys: [] };
+    obj[ATTR_META]!.keys ??= [];
+    const keys = obj[ATTR_META]!.keys!;
+    for (let i = 0; i < keys.length; i++) {
+      if (keys[i].source === FeedProtocol.KEY_QUEUE_POSITION) {
+        keys.splice(i, 1);
+        i--;
+      }
+    }
+    keys.push({
+      source: FeedProtocol.KEY_QUEUE_POSITION,
+      id: position.toString(),
+    });
+  }
+}

package/src/foreign-key.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema, SchemaAST } from 'effect';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 const ForeignKey_ = Schema.Struct({
   /**
@@ -15,8 +16,8 @@ const ForeignKey_ = Schema.Struct({
    * Id within the foreign database.
    */
   // TODO(wittjosiah): This annotation is currently used to ensure id field shows up in forms.
-  // TODO(dmaretskyi): `false` is not a valid value for the annotation.
-  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: false }),
+  // TODO(dmaretskyi): `false` is not a valid value for the annotation. Use a different annotation.
+  id: Schema.String.annotations({ [SchemaAST.IdentifierAnnotationId]: 'false' }),
 });
 
 export type ForeignKey = Schema.Schema.Type<typeof ForeignKey_>;

package/src/index.ts

@@ -2,10 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
+export type * from './collection-sync';
 export * from './document-structure';
+export * from './echo-feed-codec';
+export * from './foreign-key';
+export * from './query';
 export * from './reference';
 export * from './space-doc-version';
-export * from './collection-sync';
 export * from './space-id';
-export * from './foreign-key';
-export * from './query';

package/src/query/ast.ts

@@ -2,14 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Match from 'effect/Match';
+import * as Schema from 'effect/Schema';
 
 import { DXN, ObjectId } from '@dxos/keys';
 
 import { ForeignKey } from '../foreign-key';
 
 const TypenameSpecifier = Schema.Union(DXN.Schema, Schema.Null).annotations({
-  description: 'DXN or null. Null means any type will match',
+  description: 'DXN or null; null matches any type',
 });
 
 // NOTE: This pattern with 3 definitions per schema is need to make the types opaque, and circular references in AST to not cause compiler errors.
@@ -46,6 +47,9 @@ const FilterObject_ = Schema.Struct({
 export interface FilterObject extends Schema.Schema.Type<typeof FilterObject_> {}
 export const FilterObject: Schema.Schema<FilterObject> = FilterObject_;
 
+/**
+ * Compare.
+ */
 const FilterCompare_ = Schema.Struct({
   type: Schema.Literal('compare'),
   operator: Schema.Literal('eq', 'neq', 'gt', 'gte', 'lt', 'lte'),
@@ -54,6 +58,9 @@ const FilterCompare_ = Schema.Struct({
 export interface FilterCompare extends Schema.Schema.Type<typeof FilterCompare_> {}
 export const FilterCompare: Schema.Schema<FilterCompare> = FilterCompare_;
 
+/**
+ * In.
+ */
 const FilterIn_ = Schema.Struct({
   type: Schema.Literal('in'),
   values: Schema.Array(Schema.Any),
@@ -61,53 +68,137 @@ const FilterIn_ = Schema.Struct({
 export interface FilterIn extends Schema.Schema.Type<typeof FilterIn_> {}
 export const FilterIn: Schema.Schema<FilterIn> = FilterIn_;
 
+/**
+ * Contains.
+ */
+const FilterContains_ = Schema.Struct({
+  type: Schema.Literal('contains'),
+  value: Schema.Any,
+});
+
+export interface FilterContains extends Schema.Schema.Type<typeof FilterContains_> {}
+
+/**
+ * Predicate for an array property to contain the provided value.
+ * Nested objects are matched using strict structural matching.
+ */
+export const FilterContains: Schema.Schema<FilterContains> = FilterContains_;
+
+/**
+ * Filters objects that have certain tag.
+ */
+const FilterTag_ = Schema.Struct({
+  type: Schema.Literal('tag'),
+  tag: Schema.String, // TODO(burdon): Make OR-collection?
+});
+
+export interface FilterTag extends Schema.Schema.Type<typeof FilterTag_> {}
+export const FilterTag: Schema.Schema<FilterTag> = FilterTag_;
+
+/**
+ * Range.
+ */
 const FilterRange_ = Schema.Struct({
   type: Schema.Literal('range'),
   from: Schema.Any,
   to: Schema.Any,
 });
+
 export interface FilterRange extends Schema.Schema.Type<typeof FilterRange_> {}
 export const FilterRange: Schema.Schema<FilterRange> = FilterRange_;
 
+/**
+ * Filter by system timestamp (createdAt / updatedAt).
+ * Timestamps are unix milliseconds stored in the object meta index.
+ */
+const FilterTimestamp_ = Schema.Struct({
+  type: Schema.Literal('timestamp'),
+  field: Schema.Literal('createdAt', 'updatedAt'),
+  operator: Schema.Literal('gt', 'gte', 'lt', 'lte'),
+  value: Schema.Number,
+});
+
+export interface FilterTimestamp extends Schema.Schema.Type<typeof FilterTimestamp_> {}
+export const FilterTimestamp: Schema.Schema<FilterTimestamp> = FilterTimestamp_;
+
+/**
+ * Text search.
+ */
 const FilterTextSearch_ = Schema.Struct({
   type: Schema.Literal('text-search'),
   text: Schema.String,
   searchKind: Schema.optional(Schema.Literal('full-text', 'vector')),
 });
+
 export interface FilterTextSearch extends Schema.Schema.Type<typeof FilterTextSearch_> {}
 export const FilterTextSearch: Schema.Schema<FilterTextSearch> = FilterTextSearch_;
 
+/**
+ * Not.
+ */
 const FilterNot_ = Schema.Struct({
   type: Schema.Literal('not'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface FilterNot extends Schema.Schema.Type<typeof FilterNot_> {}
 export const FilterNot: Schema.Schema<FilterNot> = FilterNot_;
 
+/**
+ * And.
+ */
 const FilterAnd_ = Schema.Struct({
   type: Schema.Literal('and'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterAnd extends Schema.Schema.Type<typeof FilterAnd_> {}
 export const FilterAnd: Schema.Schema<FilterAnd> = FilterAnd_;
 
+/**
+ * Or.
+ */
 const FilterOr_ = Schema.Struct({
   type: Schema.Literal('or'),
   filters: Schema.Array(Schema.suspend(() => Filter)),
 });
+
 export interface FilterOr extends Schema.Schema.Type<typeof FilterOr_> {}
 export const FilterOr: Schema.Schema<FilterOr> = FilterOr_;
 
+/**
+ * Filter objects that are children of the specified parents.
+ * With transitive=true (default), matches grandchildren and beyond.
+ */
+const FilterChildOf_ = Schema.Struct({
+  type: Schema.Literal('child-of'),
+  /** Parent DXNs to match children of. */
+  parents: Schema.Array(DXN.Schema),
+  /** Whether to match transitively (grandchildren, etc.). Defaults to true. */
+  transitive: Schema.Boolean,
+});
+
+export interface FilterChildOf extends Schema.Schema.Type<typeof FilterChildOf_> {}
+export const FilterChildOf: Schema.Schema<FilterChildOf> = FilterChildOf_;
+
+/**
+ * Union of filters.
+ */
 export const Filter = Schema.Union(
   FilterObject,
-  FilterTextSearch,
   FilterCompare,
   FilterIn,
+  FilterContains,
+  FilterTag,
   FilterRange,
+  FilterTimestamp,
+  FilterTextSearch,
+  FilterChildOf,
   FilterNot,
   FilterAnd,
   FilterOr,
-);
+).annotations({ identifier: 'org.dxos.schema.filter' });
+
 export type Filter = Schema.Schema.Type<typeof Filter>;
 
 /**
@@ -117,6 +208,7 @@ const QuerySelectClause_ = Schema.Struct({
   type: Schema.Literal('select'),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QuerySelectClause extends Schema.Schema.Type<typeof QuerySelectClause_> {}
 export const QuerySelectClause: Schema.Schema<QuerySelectClause> = QuerySelectClause_;
 
@@ -128,6 +220,7 @@ const QueryFilterClause_ = Schema.Struct({
   selection: Schema.suspend(() => Query),
   filter: Schema.suspend(() => Filter),
 });
+
 export interface QueryFilterClause extends Schema.Schema.Type<typeof QueryFilterClause_> {}
 export const QueryFilterClause: Schema.Schema<QueryFilterClause> = QueryFilterClause_;
 
@@ -139,6 +232,7 @@ const QueryReferenceTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   property: Schema.String, // TODO(dmaretskyi): Change to EscapedPropPath.
 });
+
 export interface QueryReferenceTraversalClause extends Schema.Schema.Type<typeof QueryReferenceTraversalClause_> {}
 export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversalClause> =
   QueryReferenceTraversalClause_;
@@ -149,9 +243,14 @@ export const QueryReferenceTraversalClause: Schema.Schema<QueryReferenceTraversa
 const QueryIncomingReferencesClause_ = Schema.Struct({
   type: Schema.Literal('incoming-references'),
   anchor: Schema.suspend(() => Query),
-  property: Schema.String,
+  /**
+   * Property path where the reference is located.
+   * If null, matches references from any property.
+   */
+  property: Schema.NullOr(Schema.String),
   typename: TypenameSpecifier,
 });
+
 export interface QueryIncomingReferencesClause extends Schema.Schema.Type<typeof QueryIncomingReferencesClause_> {}
 export const QueryIncomingReferencesClause: Schema.Schema<QueryIncomingReferencesClause> =
   QueryIncomingReferencesClause_;
@@ -170,6 +269,7 @@ const QueryRelationClause_ = Schema.Struct({
   direction: Schema.Literal('outgoing', 'incoming', 'both'),
   filter: Schema.optional(Schema.suspend(() => Filter)),
 });
+
 export interface QueryRelationClause extends Schema.Schema.Type<typeof QueryRelationClause_> {}
 export const QueryRelationClause: Schema.Schema<QueryRelationClause> = QueryRelationClause_;
 
@@ -181,9 +281,27 @@ const QueryRelationTraversalClause_ = Schema.Struct({
   anchor: Schema.suspend(() => Query),
   direction: Schema.Literal('source', 'target', 'both'),
 });
+
 export interface QueryRelationTraversalClause extends Schema.Schema.Type<typeof QueryRelationTraversalClause_> {}
 export const QueryRelationTraversalClause: Schema.Schema<QueryRelationTraversalClause> = QueryRelationTraversalClause_;
 
+/**
+ * Traverse parent-child hierarchy.
+ */
+const QueryHierarchyTraversalClause_ = Schema.Struct({
+  type: Schema.Literal('hierarchy-traversal'),
+  anchor: Schema.suspend(() => Query),
+  /**
+   * to-parent: traverse from child to parent.
+   * to-children: traverse from parent to children.
+   */
+  direction: Schema.Literal('to-parent', 'to-children'),
+});
+
+export interface QueryHierarchyTraversalClause extends Schema.Schema.Type<typeof QueryHierarchyTraversalClause_> {}
+export const QueryHierarchyTraversalClause: Schema.Schema<QueryHierarchyTraversalClause> =
+  QueryHierarchyTraversalClause_;
+
 /**
  * Union of multiple queries.
  */
@@ -191,6 +309,7 @@ const QueryUnionClause_ = Schema.Struct({
   type: Schema.Literal('union'),
   queries: Schema.Array(Schema.suspend(() => Query)),
 });
+
 export interface QueryUnionClause extends Schema.Schema.Type<typeof QueryUnionClause_> {}
 export const QueryUnionClause: Schema.Schema<QueryUnionClause> = QueryUnionClause_;
 
@@ -202,9 +321,47 @@ const QuerySetDifferenceClause_ = Schema.Struct({
   source: Schema.suspend(() => Query),
   exclude: Schema.suspend(() => Query),
 });
+
 export interface QuerySetDifferenceClause extends Schema.Schema.Type<typeof QuerySetDifferenceClause_> {}
 export const QuerySetDifferenceClause: Schema.Schema<QuerySetDifferenceClause> = QuerySetDifferenceClause_;
 
+export const OrderDirection = Schema.Literal('asc', 'desc');
+export type OrderDirection = Schema.Schema.Type<typeof OrderDirection>;
+
+const Order_ = Schema.Union(
+  Schema.Struct({
+    // How database wants to order them (in practice - by id).
+    kind: Schema.Literal('natural'),
+  }),
+  Schema.Struct({
+    kind: Schema.Literal('property'),
+    property: Schema.String,
+    direction: OrderDirection,
+  }),
+  Schema.Struct({
+    // Order by relevance rank (for FTS/vector search results).
+    // Default direction is 'desc' (higher rank = better match first).
+    kind: Schema.Literal('rank'),
+    direction: OrderDirection,
+  }),
+);
+
+export type Order = Schema.Schema.Type<typeof Order_>;
+export const Order: Schema.Schema<Order> = Order_;
+
+/**
+ * Order the query results.
+ * Left-to-right the orders dominate.
+ */
+const QueryOrderClause_ = Schema.Struct({
+  type: Schema.Literal('order'),
+  query: Schema.suspend(() => Query),
+  order: Schema.Array(Order),
+});
+
+export interface QueryOrderClause extends Schema.Schema.Type<typeof QueryOrderClause_> {}
+export const QueryOrderClause: Schema.Schema<QueryOrderClause> = QueryOrderClause_;
+
 /**
  * Add options to a query.
  */
@@ -213,9 +370,37 @@ const QueryOptionsClause_ = Schema.Struct({
   query: Schema.suspend(() => Query),
   options: Schema.suspend(() => QueryOptions),
 });
+
 export interface QueryOptionsClause extends Schema.Schema.Type<typeof QueryOptionsClause_> {}
 export const QueryOptionsClause: Schema.Schema<QueryOptionsClause> = QueryOptionsClause_;
 
+/**
+ * Limit the number of results.
+ */
+const QueryLimitClause_ = Schema.Struct({
+  type: Schema.Literal('limit'),
+  query: Schema.suspend(() => Query),
+  limit: Schema.Number,
+});
+
+export interface QueryLimitClause extends Schema.Schema.Type<typeof QueryLimitClause_> {}
+export const QueryLimitClause: Schema.Schema<QueryLimitClause> = QueryLimitClause_;
+
+export const QueryFromClause_ = Schema.Struct({
+  type: Schema.Literal('from'),
+  query: Schema.suspend(() => Query),
+  from: Schema.Union(
+    Schema.TaggedStruct('scope', {
+      scope: Schema.suspend(() => Scope),
+    }),
+    Schema.TaggedStruct('query', {
+      query: Schema.suspend(() => Query),
+    }),
+  ),
+});
+export interface QueryFromClause extends Schema.Schema.Type<typeof QueryFromClause_> {}
+export const QueryFromClause: Schema.Schema<QueryFromClause> = QueryFromClause_;
+
 const Query_ = Schema.Union(
   QuerySelectClause,
   QueryFilterClause,
@@ -223,46 +408,142 @@ const Query_ = Schema.Union(
   QueryIncomingReferencesClause,
   QueryRelationClause,
   QueryRelationTraversalClause,
+  QueryHierarchyTraversalClause,
   QueryUnionClause,
   QuerySetDifferenceClause,
+  QueryOrderClause,
   QueryOptionsClause,
-);
+  QueryLimitClause,
+  QueryFromClause,
+).annotations({ identifier: 'org.dxos.schema.query' });
 
 export type Query = Schema.Schema.Type<typeof Query_>;
 export const Query: Schema.Schema<Query> = Query_;
 
 export const QueryOptions = Schema.Struct({
-  spaceIds: Schema.optional(Schema.Array(Schema.String)),
+  /**
+   * Nested select statements will use this option to filter deleted objects.
+   */
   deleted: Schema.optional(Schema.Literal('include', 'exclude', 'only')),
+
+  /**
+   * Diagnostics-only label for logs / tooling (not used by execution semantics).
+   */
+  debugLabel: Schema.optional(Schema.String),
 });
+
 export interface QueryOptions extends Schema.Schema.Type<typeof QueryOptions> {}
 
+/**
+ * Specifies the scope of the data to query from.
+ */
+export const Scope = Schema.Struct({
+  /**
+   * The nested select statemets will select from the given spaces.
+   *
+   * NOTE: Spaces and queues are unioned together if both are specified.
+   */
+  spaceIds: Schema.optional(Schema.Array(Schema.String)),
+
+  /**
+   * If true, the nested select statements will select from all queues in the spaces specified by `spaceIds`.
+   */
+  allQueuesFromSpaces: Schema.optional(Schema.Boolean),
+
+  /**
+   * The nested select statemets will select from the given queues.
+   *
+   * NOTE: Spaces and queues are unioned together if both are specified.
+   */
+  queues: Schema.optional(Schema.Array(DXN.Schema)),
+});
+export interface Scope extends Schema.Schema.Type<typeof Scope> {}
+
 export const visit = (query: Query, visitor: (node: Query) => void) => {
-  switch (query.type) {
-    case 'filter':
-      visit(query.selection, visitor);
-      break;
-    case 'reference-traversal':
-      visit(query.anchor, visitor);
-      break;
-    case 'incoming-references':
-      visit(query.anchor, visitor);
-      break;
-    case 'relation':
-      visit(query.anchor, visitor);
-      break;
-    case 'options':
-      visit(query.query, visitor);
-      break;
-    case 'relation-traversal':
-      visit(query.anchor, visitor);
-      break;
-    case 'union':
-      query.queries.forEach((q) => visit(q, visitor));
-      break;
-    case 'set-difference':
-      visit(query.source, visitor);
-      visit(query.exclude, visitor);
-      break;
-  }
+  visitor(query);
+
+  Match.value(query).pipe(
+    Match.when({ type: 'filter' }, ({ selection }) => visit(selection, visitor)),
+    Match.when({ type: 'reference-traversal' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'incoming-references' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'relation' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'options' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'relation-traversal' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'hierarchy-traversal' }, ({ anchor }) => visit(anchor, visitor)),
+    Match.when({ type: 'union' }, ({ queries }) => queries.forEach((q) => visit(q, visitor))),
+    Match.when({ type: 'set-difference' }, ({ source, exclude }) => {
+      visit(source, visitor);
+      visit(exclude, visitor);
+    }),
+    Match.when({ type: 'order' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'limit' }, ({ query }) => visit(query, visitor)),
+    Match.when({ type: 'from' }, (node) => {
+      visit(node.query, visitor);
+      if (node.from._tag === 'query') {
+        visit(node.from.query, visitor);
+      }
+    }),
+    Match.when({ type: 'select' }, () => {}),
+    Match.exhaustive,
+  );
+};
+
+/**
+ * Recursively transforms a query tree bottom-up.
+ * The mapper receives each node with its children already transformed.
+ */
+export const map = (query: Query, mapper: (node: Query) => Query): Query => {
+  const mapped: Query = Match.value(query).pipe(
+    Match.when({ type: 'filter' }, (node) => ({ ...node, selection: map(node.selection, mapper) })),
+    Match.when({ type: 'reference-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'incoming-references' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'relation' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'relation-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'hierarchy-traversal' }, (node) => ({ ...node, anchor: map(node.anchor, mapper) })),
+    Match.when({ type: 'options' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'order' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'limit' }, (node) => ({ ...node, query: map(node.query, mapper) })),
+    Match.when({ type: 'from' }, (node) => ({
+      ...node,
+      query: map(node.query, mapper),
+      ...(node.from._tag === 'query' ? { from: { _tag: 'query' as const, query: map(node.from.query, mapper) } } : {}),
+    })),
+    Match.when({ type: 'union' }, (node) => ({ ...node, queries: node.queries.map((q) => map(q, mapper)) })),
+    Match.when({ type: 'set-difference' }, (node) => ({
+      ...node,
+      source: map(node.source, mapper),
+      exclude: map(node.exclude, mapper),
+    })),
+    Match.when({ type: 'select' }, (node) => node),
+    Match.exhaustive,
+  );
+  return mapper(mapped);
+};
+
+export const fold = <T>(query: Query, reducer: (node: Query) => T): T[] => {
+  return Match.value(query).pipe(
+    Match.withReturnType<T[]>(),
+    Match.when({ type: 'filter' }, ({ selection }) => fold(selection, reducer)),
+    Match.when({ type: 'reference-traversal' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'incoming-references' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'relation' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'options' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'relation-traversal' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'hierarchy-traversal' }, ({ anchor }) => fold(anchor, reducer)),
+    Match.when({ type: 'union' }, ({ queries }) => queries.flatMap((q) => fold(q, reducer))),
+    Match.when({ type: 'set-difference' }, ({ source, exclude }) =>
+      fold(source, reducer).concat(fold(exclude, reducer)),
+    ),
+    Match.when({ type: 'order' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'limit' }, ({ query }) => fold(query, reducer)),
+    Match.when({ type: 'from' }, (node) => {
+      const results = fold(node.query, reducer);
+      if (node.from._tag === 'query') {
+        return results.concat(fold(node.from.query, reducer));
+      }
+      return results;
+    }),
+    Match.when({ type: 'select' }, () => []),
+    Match.exhaustive,
+  );
 };