fhir-persistence 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,76 @@ 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.10.0] - 2025-03-24
+
+### Added
+
+#### PERS-01: PUT-as-Create (Upsert)
+
+- **`FhirStore.updateResource`** and **`FhirPersistence.updateResource`** — new `upsert` option; when `true` and resource does not exist, creates it instead of throwing `ResourceNotFoundError`
+- Return type changed to `UpdateResourceResult<T>` with `{ resource, created }` — `created: true` for upsert-created resources, `false` for normal updates
+- **`FhirPersistence.createResource`** — return type changed to `CreateResourceResult<T>` with `{ resource, created }` for consistency
+
+#### PERS-02: Conditional Create (ifNoneExist)
+
+- **`FhirPersistence.createResource`** — new `ifNoneExist` option accepting `ParsedSearchParam[]`; searches first, returns existing resource if exactly one match, throws `PreconditionFailedError` if multiple matches, creates new resource if no matches
+
+#### PERS-06: Type-Level History
+
+- **`FhirStore.readTypeHistory`** and **`FhirPersistence.readTypeHistory`** — new method for `GET /<ResourceType>/_history` queries with `_since`, `_count`, and cursor pagination support
+
+#### Exports
+
+- **`ConditionalService`** + types (`ConditionalCreateResult`, `ConditionalUpdateResult`, `ConditionalDeleteResult`) now exported from package entry point
+- **`processTransactionV2`**, **`processBatchV2`** + bundle types (`Bundle`, `BundleEntry`, `BundleResponse`, `BundleResponseEntry`) now exported
+- **`buildUrnMap`**, **`deepResolveUrns`** + `UrnTarget` type now exported
+- **`FhirStore`** option/result types (`StoreUpdateResourceResult`, `StoreUpdateResourceOptions`) now exported
+- **`FhirPersistence`** option/result types (`PersistenceCreateResourceOptions`, `CreateResourceResult`, `PersistenceUpdateResourceOptions`, `UpdateResourceResult`) now exported
+
+### Fixed
+
+#### PERS-07: String `:exact` Search Modifier on HumanName
+
+- **`where-builder.ts`** — `name:exact` search now matches against individual `family` and `given` columns in the HumanName lookup table instead of the concatenated `name` column
+- Previously `name:exact=Smith` would fail to match because the `name` column contains `"Smith John"` (concatenated); now correctly matches if `family = "Smith"` OR `given = "Smith"`
+- Fix applied to both v1 (PostgreSQL `$N`) and v2 (SQLite `?`) WHERE builders
+
+#### Bundle Processor PUT Compatibility
+
+- **`bundle-processor.ts`** — `processBatchEntry` PUT handler updated to extract `.resource` from `UpdateResourceResult` and use `upsert: true` for PUT-as-Create semantics; response status now correctly returns `201` for created resources
+
+### Changed
+
+- **`FhirStore.updateResource`** — return type changed from `T & PersistedResource` to `UpdateResourceResult<T>` (breaking change for direct callers)
+- **`FhirPersistence.createResource`** — return type changed from `T & PersistedResource` to `CreateResourceResult<T>` (breaking change for direct callers)
+- **`FhirPersistence.updateResource`** — return type changed from `T & PersistedResource` to `UpdateResourceResult<T>` (breaking change for direct callers)
+
+### Test Coverage
+
+- **1057 passing tests**, 8 skipped, across 63 test files — no regressions
+- All existing tests updated for new `UpdateResourceResult` / `CreateResourceResult` return types
+- PERS-07 test assertions updated to verify per-component HumanName matching
+
+## [0.9.0] - 2025-03-20
+
+### Fixed
+
+#### Bug-3: Token WHERE clause code-only / empty-system matching failure (P0)
+
+- **`buildTokenColumnFragmentV2()`** (v2, SQLite) and **`buildTokenColumnFragment()`** (v1, PostgreSQL) — corrected token value resolution logic per FHIR spec:
+  - `system|code` → exact match against stored `"system|code"` ✅
+  - `|code` → exact match against stored `"|code"` (empty system, keep pipe) ✅
+  - `system|` → `LIKE "system|%"` (any code within system) ✅
+  - `code` (bare, no pipe) → `LIKE "%|code"` (any system, match code) ✅
+- **Root cause**: Previous logic stripped leading `|` from `|code` values and used exact match for bare codes, causing zero results for `gender=male` (stored as `"|male"`) and `gender=|male`
+- **Impact**: All token searches using bare code or `|code` format now correctly match stored values
+- New helper: `arrayContainsLikeV2()` generates dialect-aware `LIKE` subqueries (SQLite `json_each` / PostgreSQL `unnest`)
+
+### Test Coverage
+
+- **1065 total tests** (1057 passing, 8 skipped) across 63 test files — no regressions
+- **5 new Bug-3 regression tests** in v2 and v1 test suites verifying all four token formats
+
 ## [0.8.0] - 2025-03-20
 
 ### 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.8.0** — Token search bug fix: DDL/INSERT/WHERE column name alignment
+> **v0.10.0** — PUT-as-Create (upsert), Conditional Create, Type-Level History, HumanName `:exact` fix
 
 ## Features
 
@@ -22,9 +22,12 @@ Embedded FHIR R4 persistence layer — CRUD, search, indexing, and schema migrat
 - **IG-driven schema** — StructureDefinition + SearchParameter → DDL (SQLite + PostgreSQL dialects)
 - **Migration engine** — SchemaDiff → MigrationGenerator → MigrationRunnerV2
 - **Full-text search** — SQLite FTS5 + PostgreSQL tsvector/GIN for string search parameters
+- **PUT-as-Create (upsert)** — `updateResource({ upsert: true })` creates resource if not found
+- **Conditional Create** — `createResource({ ifNoneExist })` with FHIR R4 conditional semantics
 - **Conditional operations** — conditionalCreate / conditionalUpdate / conditionalDelete via `ConditionalService`
+- **Type-level history** — `readTypeHistory('Patient')` for `GET /Patient/_history`
 - **Reindex progress** — `onProgress` callback for CLI and UI progress reporting
-- **Bundle processing** — transaction and batch bundle support
+- **Bundle processing** — transaction and batch bundle support with PUT-as-Create
 - **Terminology** — TerminologyCodeRepo + ValueSetRepo
 - **FhirSystem orchestrator** — end-to-end startup flow for `fhir-engine` integration
 - **Provider bridges** — `FhirDefinitionBridge` + `FhirRuntimeProvider` for `fhir-definition` / `fhir-runtime`
@@ -69,7 +72,7 @@ const persistence = new FhirPersistence({
 });
 
 // 4. CRUD with automatic indexing
-const patient = await persistence.createResource("Patient", {
+const { resource: patient } = await persistence.createResource("Patient", {
   resourceType: "Patient",
   name: [{ family: "Smith", given: ["John"] }],
   birthDate: "1990-01-15",
@@ -132,7 +135,7 @@ const { persistence, sdRegistry, spRegistry, igResult } =
   await system.initialize(definitionBridge);
 
 // 5. Use persistence
-const patient = await persistence.createResource('Patient', { resourceType: 'Patient', ... });
+const { resource: patient } = await persistence.createResource('Patient', { resourceType: 'Patient', ... });
 ```
 
 ## Architecture