fhir-data-utils-ts 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.6.2 - 2026-09-30
+
+- Add strict FHIR `instant` to Unix epoch-second derivation while preserving
+  the boundary between clinical time, `Encounter.id`, provider business
+  identifiers and human display codes.
+
 ## 0.6.1 - 2026-09-30
 
 - Add canonical flat claims, a claims-first builder and native R5 projection

package/README.md

@@ -92,6 +92,12 @@ metadata and protected endpoint references only. DICOM instances and pixel
 payloads remain outside this neutral package and are never embedded as flat
 claims.
 
+FHIR instants, resource ids and provider business identifiers remain separate.
+Use `fhirInstantToEpochSeconds(...)` only when a downstream convention needs a
+derived whole-second value; retain the original timezone-bearing instant and
+an independent `Encounter.id`. See
+[`docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md`](docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md).
+
 No consumer should copy claim paths or rebuild these structures with literals.
 Use `fhir-data-utils-ts/claims`, `/converters`, `/fhir-bundle`,
 `/fhir-search-parameters`, `/clinical-terminology`, `/group-r5` or

package/dist/encounter-transfer-test-data.d.ts

@@ -6,6 +6,7 @@ export declare const FHIR_ENCOUNTER_TRANSFER_TEST_DATA: Readonly<{
     senderReference: "Organization/00000000-0000-4000-8000-000000000403";
     indexRecipientReference: "Organization/00000000-0000-4000-8000-000000000404";
     occurredAt: "2026-09-30T10:10:00Z";
+    invalidOccurredAtWithoutTimezone: "2026-09-30T10:10:00";
     class: Readonly<{
         system: "http://terminology.hl7.org/CodeSystem/v3-ActCode";
         code: "EMER";

package/dist/encounter-transfer-test-data.js

@@ -6,6 +6,7 @@ export const FHIR_ENCOUNTER_TRANSFER_TEST_DATA = Object.freeze({
     senderReference: 'Organization/00000000-0000-4000-8000-000000000403',
     indexRecipientReference: 'Organization/00000000-0000-4000-8000-000000000404',
     occurredAt: '2026-09-30T10:10:00Z',
+    invalidOccurredAtWithoutTimezone: '2026-09-30T10:10:00',
     class: Object.freeze({ system: 'http://terminology.hl7.org/CodeSystem/v3-ActCode', code: 'EMER' }),
     source: Object.freeze({
         id: '00000000-0000-4000-8000-000000000405',

package/dist/fhir-instant.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derives whole Unix epoch seconds from a valid FHIR `instant`.
+ *
+ * A FHIR instant remains the authoritative ISO 8601 value with a timezone.
+ * Epoch seconds are a derived numeric representation and must never replace
+ * `Encounter.id`, `Encounter.identifier`, or the original clinical time.
+ */
+export declare function fhirInstantToEpochSeconds(instant: string): number;

package/dist/fhir-instant.js

@@ -0,0 +1,16 @@
+const FHIR_INSTANT_PATTERN = /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+/**
+ * Derives whole Unix epoch seconds from a valid FHIR `instant`.
+ *
+ * A FHIR instant remains the authoritative ISO 8601 value with a timezone.
+ * Epoch seconds are a derived numeric representation and must never replace
+ * `Encounter.id`, `Encounter.identifier`, or the original clinical time.
+ */
+export function fhirInstantToEpochSeconds(instant) {
+    if (!FHIR_INSTANT_PATTERN.test(instant))
+        throw new TypeError('fhir_instant_invalid');
+    const epochMilliseconds = Date.parse(instant);
+    if (!Number.isFinite(epochMilliseconds))
+        throw new TypeError('fhir_instant_invalid');
+    return Math.floor(epochMilliseconds / 1000);
+}

package/dist/index.d.ts

@@ -27,3 +27,4 @@ export * from './subscription-r5.js';
 export * from './healthcare-service-specialty-map.js';
 export * from './appointment-communication-test-data.js';
 export * from './encounter-transfer-test-data.js';
+export * from './fhir-instant.js';

package/dist/index.js

@@ -27,3 +27,4 @@ export * from './subscription-r5.js';
 export * from './healthcare-service-specialty-map.js';
 export * from './appointment-communication-test-data.js';
 export * from './encounter-transfer-test-data.js';
+export * from './fhir-instant.js';

package/docs/ENCOUNTER_IDENTIFIERS_AND_TIME.md

@@ -0,0 +1,19 @@
+# Encounter identifiers and time
+
+FHIR time and encounter identity are separate concepts.
+
+- A FHIR `instant` is an ISO 8601 date and time with at least second precision
+  and an explicit timezone. It is not a Unix timestamp.
+- Unix epoch seconds may be derived for sorting, interoperability or a
+  provider-owned business identifier, but they never replace the original
+  instant.
+- `Encounter.id` is the FHIR resource identifier.
+- `Encounter.identifier` contains the business identifiers assigned by the
+  care provider. Their namespace and uniqueness belong to the assigning
+  organization.
+- A display code is not sufficient authorization or subject resolution. An
+  authoritative lookup must also verify the assigner and exact subject.
+
+Reusable test data lives in `FHIR_ENCOUNTER_TRANSFER_TEST_DATA`. Tests and
+downstream documentation import its named fields instead of duplicating raw
+identifiers, timestamps or references.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fhir-data-utils-ts",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "FHIR-version-neutral flat-claim and SearchParameter data utilities",
   "license": "Apache-2.0",
   "type": "module",