Function astToSteps

packages/graph/src/astToSteps.ts:133–174

(query: Query)

 * This ensures predictable mutation ordering (e.g., MERGE before CREATE, SET before DELETE).
 */
export function astToSteps(query: Query): readonly Step<any>[] {
  const steps: Step<any>[] = [];

  // Validation: ORDER BY, SKIP, and LIMIT require a RETURN clause
  if (!query.return && (query.orderBy || query.skip !== undefined || query.limit !== undefined)) {
    throw new Error("ORDER BY, SKIP, and LIMIT require a RETURN clause");
  }

  // If we have segments, process them in order for proper execution sequencing
  if (query.segments && query.segments.length > 0) {
    processQuerySegments(query.segments, steps);
  } else if (query.return) {
    // RETURN-only query (no segments): add StartStep to provide initial path
    steps.push(new StartStep({}));
  } else {
    // Backward compatibility: use flat structure
    processLegacyQuery(query, steps);
  }

  // Handle ORDER BY
  if (query.orderBy) {
    // Build alias map from RETURN items for alias resolution
    const aliasMap = buildReturnAliasMap(query.return);
    const directions = query.orderBy.orders.map(
      (order) => resolveOrderItem(order, aliasMap, false), // false = use source property/variable for RETURN ORDER BY
    );
    steps.push(new OrderStep({ directions }));
  }

  // Handle SKIP and LIMIT with RangeStep
  if (query.skip !== undefined || query.limit !== undefined) {
    const start = query.skip ?? 0;
    const end = query.limit !== undefined ? start + query.limit : Number.MAX_SAFE_INTEGER;
    steps.push(new RangeStep({ start, end }));
  }

  // Handle RETURN clause
  const returnSteps = convertReturnClause(query);
  steps.push(...returnSteps);

  return steps;
}

/**
 * Process query segments in order for flexible clause ordering.