Fix .first() transpilation in forEach with .where() filtering

Previously, .first() was incorrectly converted to [0] array indexing,
which applied index filtering BEFORE the WHERE condition. This caused
queries to fail when the desired element was not at index 0.

For example, in blood pressure observations where:
- component[0] = diastolic (8462-4)
- component[1] = systolic (8480-6)

The query `component.where(code='8480-6').first()` would incorrectly
check only index 0 (which has code 8462-4), returning no results.

Changes:
- Modified FhirPathWhereResult interface to include useFirst flag
- Updated parseFhirPathWhere() to detect .first() and set flag instead
  of converting to [0]
- Modified ForEachProcessor.buildSimpleApplyClause() to use TOP 1 with
  ORDER BY [key] when useFirst is true
- This generates: SELECT TOP 1 * ... WHERE condition ORDER BY [key]
- Correctly filters all elements first, then takes the first match

The fix ensures .first() applies to filtered results, not to
pre-filtered array positions.

Author: johngrimes

src/queryGenerator/ForEachProcessor.ts

@@ -383,8 +383,11 @@ export class ForEachProcessor {
     const applyAlias = forEachContext.currentForEachAlias ?? "";
     const sourceExpression = forEachContext.forEachSource ?? "";
 
-    const { path: pathWithoutWhere, whereCondition } =
-      this.pathParser.parseFhirPathWhere(rawPath ?? "", forEachContext);
+    const {
+      path: pathWithoutWhere,
+      whereCondition,
+      useFirst,
+    } = this.pathParser.parseFhirPathWhere(rawPath ?? "", forEachContext);
     const { path: forEachPath, arrayIndex } =
       this.pathParser.parseArrayIndexing(pathWithoutWhere);
     const arrayPaths = this.pathParser.detectArrayFlatteningPaths(forEachPath);
@@ -407,6 +410,7 @@ export class ForEachProcessor {
       applyAlias,
       arrayIndex,
       whereCondition,
+      useFirst,
     );
   }
 
@@ -420,13 +424,20 @@ export class ForEachProcessor {
     applyAlias: string,
     arrayIndex: number | null,
     whereCondition: string | null,
+    useFirst: boolean = false,
   ): string {
     const whereClauses = this.buildWhereClauses(arrayIndex, whereCondition);
 
-    if (whereClauses.length > 0) {
+    if (whereClauses.length > 0 || useFirst) {
+      // Build SELECT with WHERE clause and/or TOP 1 for .first()
+      const topClause = useFirst ? "TOP 1 " : "";
+      const orderBy = useFirst ? " ORDER BY [key]" : "";
+      const whereClause =
+        whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+
       return `\n${applyType} (
-        SELECT * FROM OPENJSON(${sourceExpression}, '$.${forEachPath}')
-        WHERE ${whereClauses.join(" AND ")}
+        SELECT ${topClause}* FROM OPENJSON(${sourceExpression}, '$.${forEachPath}')
+        ${whereClause}${orderBy}
       ) AS ${applyAlias}`;
     }
 

src/queryGenerator/PathParser.ts

@@ -10,6 +10,7 @@ import { Transpiler, TranspilerContext } from "../fhirpath/transpiler.js";
 export interface FhirPathWhereResult {
   path: string;
   whereCondition: string | null;
+  useFirst: boolean;
 }
 
 /**
@@ -94,7 +95,7 @@ export class PathParser {
   ): FhirPathWhereResult {
     const whereIndex = path.indexOf(".where(");
     if (whereIndex === -1) {
-      return { path, whereCondition: null };
+      return { path, whereCondition: null, useFirst: false };
     }
 
     const basePath = path.substring(0, whereIndex);
@@ -108,9 +109,10 @@ export class PathParser {
     const condition = path.substring(whereStart, conditionEnd).trim();
     let remainingPath = path.substring(conditionEnd + 1);
 
-    // Handle .first() by converting it to [0] array indexing.
-    if (remainingPath === ".first()") {
-      remainingPath = "[0]";
+    // Detect .first() to apply TOP 1 in SQL generation.
+    const useFirst = remainingPath === ".first()";
+    if (useFirst) {
+      remainingPath = ""; // Remove .first() from path - it will be handled via TOP 1
     }
 
     const fullPath = remainingPath ? `${basePath}${remainingPath}` : basePath;
@@ -120,12 +122,14 @@ export class PathParser {
       return {
         path: fullPath,
         whereCondition: "1 = 0",
+        useFirst: false,
       };
     }
 
     return {
       path: fullPath,
       whereCondition: this.transpileWhereCondition(condition, context),
+      useFirst,
     };
   }