fhir-persistence 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2025-03-17
+
+### Added
+
+#### Full-Text Search (SQLite FTS5 + PostgreSQL tsvector/GIN)
+
+- **`table-schema-builder.ts`** — HumanName and Address lookup tables now include tsvector GIN expression indexes (`to_tsvector('simple'::regconfig, column)`) for PostgreSQL full-text search
+- **`where-builder.ts`** — Lookup table string search supports FTS query paths: SQLite FTS5 MATCH and PostgreSQL `to_tsvector @@ plainto_tsquery` with automatic fallback to LIKE
+- **`fhir-system.ts`** — `FhirSystemConfig.features.fullTextSearch` option to enable FTS query paths (default: `false` for backward compatibility)
+- SQLite FTS5 virtual tables generated via `MigrationGenerator` for HumanName/Address lookup columns
+
+#### Reindex Progress Callbacks
+
+- **`cli/reindex.ts`** — `ReindexProgressCallbackV2` type with `onProgress` callback reporting `{ resourceType, processed, total }` per batch
+- **`reindexResourceTypeV2`** and **`reindexAllV2`** accept optional `onProgress` parameter for CLI and UI progress display
+
+#### Conditional Operations API
+
+- **`store/conditional-service.ts`** — `ConditionalService` class with full FHIR R4 conditional semantics:
+  - `conditionalCreate`: 0 match → create, 1 match → return existing, 2+ → `PreconditionFailedError`
+  - `conditionalUpdate`: 0 match → create, 1 match → update, 2+ → `PreconditionFailedError`
+  - `conditionalDelete`: delete all matching resources, return count
+- **`repo/errors.ts`** — `PreconditionFailedError` (HTTP 412) for multiple-match conditional operations
+- All conditional operations execute within transactions (TOCTOU protection)
+
+### Changed
+
+- **`table-schema-builder.ts`** — HumanName lookup table adds `pg_trgm` GIN indexes (`gin_trgm_ops`) alongside tsvector indexes for trigram fuzzy matching
+- **`migration-generator.ts`** — Automatically creates `pg_trgm` and `btree_gin` extensions on PostgreSQL before GIN index generation
+
+## [0.5.0] - 2025-03-16
+
+### Fixed
+
+#### PostgreSQL Migration Path Fixes
+
+- **`migration-generator.ts`** — IG migration path now creates PostgreSQL extensions (`pg_trgm`, `btree_gin`) and helper function (`token_array_to_text`) before generating GIN indexes, fixing "no default operator class for access method gin" error
+- **`where-builder.ts`** — Lookup table EXISTS subqueries now use fully-qualified `"ResourceType"."id"` instead of ambiguous `"id"`, fixing PostgreSQL "operator does not exist: text = integer" error in name/address/telecom searches
+
+### Changed
+
+- **`buildWhereFragment` (v1)** — Added optional `resourceType` parameter, passed to `buildLookupTableFragment`
+- **`buildWhereFragmentV2` (v2)** — Added optional `resourceType` parameter, passed to `buildLookupTableFragmentV2`
+- Both `buildLookupTableFragment*` functions now generate `outerIdRef = "ResourceType"."id"` to eliminate column name ambiguity in PostgreSQL
+
+### Test Coverage
+
+- **1014 total tests** (1006 passing, 8 skipped) across 56 test files — no regressions
+- Updated 7 lookup table test assertions to use qualified column references
+
 ## [0.4.0] - 2025-03-15
 
 ### Fixed

package/README.md

@@ -5,7 +5,7 @@ Embedded FHIR R4 persistence layer — CRUD, search, indexing, and schema migrat
 [![npm version](https://img.shields.io/npm/v/fhir-persistence)](https://www.npmjs.com/package/fhir-persistence)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-> **v0.4.0** — Full PostgreSQL DDL compatibility for all system and lookup tables
+> **v0.6.0** — Full-text search (SQLite FTS5 + PostgreSQL tsvector/GIN), reindex progress callbacks, conditional operations API
 
 ## Features
 
@@ -21,7 +21,9 @@ Embedded FHIR R4 persistence layer — CRUD, search, indexing, and schema migrat
 - **Two-phase SQL** — id-first query for large table performance
 - **IG-driven schema** — StructureDefinition + SearchParameter → DDL (SQLite + PostgreSQL dialects)
 - **Migration engine** — SchemaDiff → MigrationGenerator → MigrationRunnerV2
-- **Conditional operations** — conditionalCreate / conditionalUpdate / conditionalDelete
+- **Full-text search** — SQLite FTS5 + PostgreSQL tsvector/GIN for string search parameters
+- **Conditional operations** — conditionalCreate / conditionalUpdate / conditionalDelete via `ConditionalService`
+- **Reindex progress** — `onProgress` callback for CLI and UI progress reporting
 - **Bundle processing** — transaction and batch bundle support
 - **Terminology** — TerminologyCodeRepo + ValueSetRepo
 - **FhirSystem orchestrator** — end-to-end startup flow for `fhir-engine` integration

package/dist/cjs/index.cjs

@@ -5202,12 +5202,12 @@ function arrayContainsLikeV2(col, value, dialect) {
   }
   return { sql: `EXISTS (SELECT 1 FROM json_each(${col}) WHERE json_each.value LIKE ?)`, values: [value] };
 }
-function buildWhereFragmentV2(impl, param, dialect) {
+function buildWhereFragmentV2(impl, param, dialect, resourceType) {
   if (param.modifier === "missing") {
     return buildMissingFragmentV2(impl, param);
   }
   if (impl.strategy === "lookup-table") {
-    return buildLookupTableFragmentV2(impl, param);
+    return buildLookupTableFragmentV2(impl, param, resourceType ?? "Resource");
   }
   if (impl.strategy === "token-column") {
     return buildTokenColumnFragmentV2(impl, param, dialect);
@@ -5235,7 +5235,7 @@ function buildMissingFragmentV2(impl, param) {
   const col = quoteColumn(impl.columnName);
   return { sql: isMissing ? `${col} IS NULL` : `${col} IS NOT NULL`, values: [] };
 }
-function buildLookupTableFragmentV2(impl, param) {
+function buildLookupTableFragmentV2(impl, param, resourceType) {
   const mapping = LOOKUP_TABLE_MAP[impl.code];
   if (!mapping) {
     const sortCol = quoteColumn(`__${impl.columnName}Sort`);
@@ -5245,25 +5245,26 @@ function buildLookupTableFragmentV2(impl, param) {
   }
   const { table, column } = mapping;
   const colRef = `__lookup."${column}"`;
+  const outerIdRef = `"${resourceType}"."id"`;
   if (param.modifier === "exact") {
     if (param.values.length === 1) {
-      return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND ${colRef} = ?)`, values: [param.values[0]] };
+      return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND ${colRef} = ?)`, values: [param.values[0]] };
     }
     const conds2 = param.values.map(() => `${colRef} = ?`);
-    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND (${conds2.join(" OR ")}))`, values: [...param.values] };
+    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND (${conds2.join(" OR ")}))`, values: [...param.values] };
   }
   if (param.modifier === "contains") {
     if (param.values.length === 1) {
-      return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND LOWER(${colRef}) LIKE ?)`, values: [`%${param.values[0].toLowerCase()}%`] };
+      return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND LOWER(${colRef}) LIKE ?)`, values: [`%${param.values[0].toLowerCase()}%`] };
     }
     const conds2 = param.values.map(() => `LOWER(${colRef}) LIKE ?`);
-    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND (${conds2.join(" OR ")}))`, values: param.values.map((v) => `%${v.toLowerCase()}%`) };
+    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND (${conds2.join(" OR ")}))`, values: param.values.map((v) => `%${v.toLowerCase()}%`) };
   }
   if (param.values.length === 1) {
-    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND LOWER(${colRef}) LIKE ?)`, values: [`${param.values[0].toLowerCase()}%`] };
+    return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND LOWER(${colRef}) LIKE ?)`, values: [`${param.values[0].toLowerCase()}%`] };
   }
   const conds = param.values.map(() => `LOWER(${colRef}) LIKE ?`);
-  return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = "id" AND (${conds.join(" OR ")}))`, values: param.values.map((v) => `${v.toLowerCase()}%`) };
+  return { sql: `EXISTS (SELECT 1 FROM "${table}" __lookup WHERE __lookup."resourceId" = ${outerIdRef} AND (${conds.join(" OR ")}))`, values: param.values.map((v) => `${v.toLowerCase()}%`) };
 }
 function buildStringFragmentV2(impl, param) {
   const col = quoteColumn(impl.columnName);
@@ -5432,7 +5433,7 @@ function buildWhereClauseV2(params, registry, resourceType, dialect) {
     }
     const impl = resolveImplV2(param, registry, resourceType);
     if (!impl) continue;
-    const fragment = buildWhereFragmentV2(impl, param, dialect);
+    const fragment = buildWhereFragmentV2(impl, param, dialect, resourceType);
     if (fragment) {
       fragments.push(fragment);
     }
@@ -7280,6 +7281,14 @@ function generateMigration(deltas, dialect) {
   const down = [];
   const reindexDeltas = [];
   const descriptions = [];
+  const needsPgExtensions = deltas.some((d) => d.kind === "ADD_TABLE" || d.kind === "ADD_INDEX");
+  if (dialect === "postgres" && needsPgExtensions) {
+    up.push("CREATE EXTENSION IF NOT EXISTS pg_trgm;");
+    up.push("CREATE EXTENSION IF NOT EXISTS btree_gin;");
+    up.push(
+      `CREATE OR REPLACE FUNCTION token_array_to_text(arr text[]) RETURNS text LANGUAGE sql IMMUTABLE AS $$ SELECT array_to_string(arr, ' ') $$;`
+    );
+  }
   for (const delta of deltas) {
     switch (delta.kind) {
       case "ADD_TABLE": {