sof-mssql 1.0.1 → 2.0.0

package/README.md

@@ -1,4 +1,4 @@
-# SQL on FHIR views for Microsoft SQL Server
+# 🔥 MSSQL on FHIR 🔥
 
 A TypeScript library and CLI tool for loading FHIR into Microsoft SQL Server,
 and transpiling [SQL on FHIR](https://sql-on-fhir.org/) view definitions into
@@ -209,59 +209,76 @@ WHERE [r].[resource_type] = 'Patient'
 
 ### Basic usage
 
-```javascript
+```typescript
 import {SqlOnFhir} from 'sof-mssql';
 
-// Create an instance with default configuration
 const sqlOnFhir = new SqlOnFhir();
+```
 
-// Transpile a ViewDefinition to T-SQL
-const viewDefinition = {
-  resourceType: 'ViewDefinition',
-  resource: 'Patient',
-  name: 'patient_demographics',
-  select: [
+Create a ViewDefinition to transpile:
+
+```json
+{
+  "resourceType": "ViewDefinition",
+  "resource": "Patient",
+  "name": "patient_demographics",
+  "select": [
     {
-      column: [
+      "column": [
         {
-          name: 'id',
-          path: 'id',
-          type: 'id'
+          "name": "id",
+          "path": "id",
+          "type": "id"
         },
         {
-          name: 'family_name',
-          path: 'name.family',
-          type: 'string'
+          "name": "family_name",
+          "path": "name.family",
+          "type": "string"
         },
         {
-          name: 'birth_date',
-          path: 'birthDate',
-          type: 'date'
+          "name": "birth_date",
+          "path": "birthDate",
+          "type": "date"
         }
       ]
     }
   ]
-};
+}
+```
+
+Transpile the ViewDefinition to T-SQL:
 
+```typescript
 const result = sqlOnFhir.transpile(viewDefinition);
 
 console.log(result.sql);
-// Output:
-// SELECT
-//   r.id AS [id],
-//   JSON_VALUE(r.json, '$.name[0].family') AS [family_name],
-//   CAST(JSON_VALUE(r.json, '$.birthDate') AS DATETIME2) AS [birth_date]
-// FROM [dbo].[fhir_resources] AS [r]
-// WHERE [r].[resource_type] = 'Patient'
-
-// Access column metadata
+```
+
+Generated SQL output:
+
+```sql
+SELECT
+  r.id AS [id],
+  JSON_VALUE(r.json, '$.name[0].family') AS [family_name],
+  CAST(JSON_VALUE(r.json, '$.birthDate') AS DATETIME2) AS [birth_date]
+FROM [dbo].[fhir_resources] AS [r]
+WHERE [r].[resource_type] = 'Patient'
+```
+
+Access column metadata:
+
+```typescript
 console.log(result.columns);
-// Output:
-// [
-//   { name: 'id', type: 'NVARCHAR(64)', nullable: true },
-//   { name: 'family_name', type: 'NVARCHAR(MAX)', nullable: true },
-//   { name: 'birth_date', type: 'DATETIME2', nullable: true }
-// ]
+```
+
+Column metadata output:
+
+```json
+[
+  { "name": "id", "type": "VARCHAR(64)", "nullable": true },
+  { "name": "family_name", "type": "NVARCHAR(MAX)", "nullable": true },
+  { "name": "birth_date", "type": "VARCHAR(10)", "nullable": true }
+]
 ```
 
 ### Custom table configuration
@@ -292,8 +309,131 @@ const fhirResource = {
   // ... rest of ViewDefinition
 };
 const result2 = sqlOnFhir.transpile(fhirResource);
+````
+
+### Type mappings and type hints
+
+#### Default type mappings
+
+By default, FHIR primitive types are mapped to the following T-SQL types:
+
+| FHIR Type                               | Default T-SQL Type | Rationale                                 |
+|-----------------------------------------|--------------------|-------------------------------------------|
+| `id`                                    | `VARCHAR(64)`      | ASCII-only, fixed max length              |
+| `boolean`                               | `BIT`              | Native boolean                            |
+| `integer`, `positiveint`, `unsignedint` | `INT`              | 32-bit integer                            |
+| `integer64`                             | `BIGINT`           | 64-bit integer                            |
+| `decimal`                               | `VARCHAR(MAX)`     | Preserves arbitrary precision             |
+| `date`                                  | `VARCHAR(10)`      | Preserves partial dates (e.g., "2024-01") |
+| `datetime`                              | `VARCHAR(50)`      | Preserves partial datetimes and timezones |
+| `instant`                               | `VARCHAR(50)`      | Preserves full ISO 8601 format            |
+| `time`                                  | `VARCHAR(20)`      | Preserves partial times                   |
+| `string`, `markdown`, `code`            | `NVARCHAR(MAX)`    | Unicode-capable text                      |
+| `uri`, `url`, `canonical`               | `NVARCHAR(MAX)`    | Can contain Unicode (IRIs)                |
+| `uuid`                                  | `VARCHAR(100)`     | ASCII UUID format                         |
+| `oid`                                   | `VARCHAR(255)`     | ASCII OID format                          |
+| `base64binary`                          | `VARBINARY(MAX)`   | Binary data                               |
+
+**Design principle:** Default mappings use `VARCHAR` for temporal and numeric types to preserve FHIR semantics (partial dates, arbitrary precision decimals) rather than forcing conversion to SQL native types.
+
+#### Using type hints
+
+You can override default type mappings using the `tag` array on column definitions. Two tag types are supported:
+
+**`tsql/type` - Direct T-SQL type specification:**
+
+```json
+{
+  "name": "birth_date",
+  "path": "birthDate",
+  "type": "date",
+  "tag": [
+    { "name": "tsql/type", "value": "DATE" }
+  ]
+}
 ```
 
+This generates a CAST expression: `CAST(JSON_VALUE(r.json, '$.birthDate') AS DATE) AS [birth_date]`
+
+**`ansi/type` - ANSI/ISO SQL standard types (automatically converted to T-SQL):**
+
+```json
+{
+  "name": "age",
+  "path": "age",
+  "type": "integer",
+  "tag": [
+    { "name": "ansi/type", "value": "INTEGER" }
+  ]
+}
+```
+
+The ANSI type `INTEGER` is automatically converted to T-SQL `INT`.
+
+```json
+{
+  "name": "active",
+  "path": "active",
+  "type": "boolean",
+  "tag": [
+    { "name": "ansi/type", "value": "BOOLEAN" }
+  ]
+}
+```
+
+The ANSI type `BOOLEAN` is automatically converted to T-SQL `BIT`.
+
+**Type precedence:** `tsql/type` > `ansi/type` > FHIR type defaults
+
+**Supported ANSI types:**
+- Character: `CHARACTER`, `CHARACTER VARYING`, `NATIONAL CHARACTER VARYING`
+- Numeric: `INTEGER`, `SMALLINT`, `BIGINT`, `DECIMAL`, `NUMERIC`, `FLOAT`, `REAL`, `DOUBLE PRECISION`
+- Temporal: `DATE`, `TIME`, `TIMESTAMP` (converted to `DATETIME2`)
+- Boolean: `BOOLEAN` (converted to `BIT`)
+
+**Example with multiple columns:**
+
+This example demonstrates how different type hints affect the resulting SQL types:
+
+```json
+{
+  "resourceType": "ViewDefinition",
+  "resource": "Patient",
+  "select": [
+    {
+      "column": [
+        {
+          "name": "id",
+          "path": "id",
+          "type": "id"
+        },
+        {
+          "name": "birth_date",
+          "path": "birthDate",
+          "type": "date",
+          "tag": [
+            { "name": "tsql/type", "value": "DATE" }
+          ]
+        },
+        {
+          "name": "deceased",
+          "path": "deceasedBoolean",
+          "type": "boolean",
+          "tag": [
+            { "name": "ansi/type", "value": "BOOLEAN" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+Type behaviour for each column:
+- `id` - Uses default FHIR type mapping: `VARCHAR(64)`
+- `birth_date` - Overrides default `VARCHAR(10)` with T-SQL `DATE` type
+- `deceased` - Uses ANSI `BOOLEAN` type, automatically converted to T-SQL `BIT`
+
 ## Database setup
 
 ### Table structure

package/dist/fhirpath/transpiler.d.ts

@@ -2,6 +2,7 @@
  * FHIRPath expression transpiler to T-SQL.
  * Converts FHIRPath expressions to equivalent T-SQL expressions for MS SQL Server.
  */
+import type { ViewDefinitionColumnTag } from "../types.js";
 import { TranspilerContext } from "./visitor";
 export { TranspilerContext } from "./visitor";
 export declare class Transpiler {
@@ -11,8 +12,45 @@ export declare class Transpiler {
     static transpile(expression: string, context: TranspilerContext): string;
     private static parseExpression;
     /**
-     * Get the SQL data type for a FHIRPath expression result.
+     * Get the SQL data type for a FHIR type, with optional tag-based override.
+     *
+     * Default mappings are conservative to accommodate ALL valid FHIR data,
+     * using MAX sizes where needed and NVARCHAR for any fields that could
+     * potentially contain Unicode characters.
+     *
+     * Design principles:
+     * - Use NVARCHAR for fields that may contain Unicode (string, code, uri/url/canonical)
+     * - Use VARCHAR for ASCII-only fields (id, uuid, oid, decimal, dates/times)
+     * - Use MAX or generous fixed sizes to prevent truncation
+     * - Preserve FHIR semantics (partial dates, arbitrary precision decimals)
+     *
+     * Users can optimise storage using type tags:
+     * - 'tsql/type' - Direct T-SQL type (e.g., 'DATE', 'VARCHAR(50)')
+     * - 'ansi/type' - ANSI/ISO SQL standard type (e.g., 'INTEGER', 'CHARACTER(50)', 'BOOLEAN')
+     *
+     * Type precedence: tsql/type > ansi/type > FHIR type defaults
+     *
+     * Example tag usage:
+     * - { "name": "tsql/type", "value": "DATE" } - Use T-SQL DATE type
+     * - { "name": "ansi/type", "value": "INTEGER" } - Use ANSI INTEGER (converted to T-SQL INT)
+     * - { "name": "ansi/type", "value": "BOOLEAN" } - Use ANSI BOOLEAN (converted to T-SQL BIT)
+     *
+     * @param fhirType - FHIR primitive type name (e.g., 'string', 'integer')
+     * @param tags - Optional array of column tags for type hints
+     * @returns MS SQL Server type specification
      */
-    static inferSqlType(fhirType?: string): string;
+    static inferSqlType(fhirType?: string, tags?: ViewDefinitionColumnTag[]): string;
+    /**
+     * Get type override from tsql/type or ansi/type tag if present.
+     *
+     * Precedence order:
+     * 1. tsql/type - Direct T-SQL type specification
+     * 2. ansi/type - ANSI/ISO SQL standard type (converted to T-SQL equivalent)
+     */
+    private static getTagTypeOverride;
+    /**
+     * Get default MS SQL Server type mapping for a FHIR primitive type.
+     */
+    private static getDefaultFhirTypeMapping;
 }
 //# sourceMappingURL=transpiler.d.ts.map

package/dist/fhirpath/transpiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transpiler.d.ts","sourceRoot":"","sources":["../../src/fhirpath/transpiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,EAAyB,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,qBAAa,UAAU;IACrB;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAkBxE,OAAO,CAAC,MAAM,CAAC,eAAe;IA4B9B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;CA8B/C"}
+{"version":3,"file":"transpiler.d.ts","sourceRoot":"","sources":["../../src/fhirpath/transpiler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EAAyB,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,qBAAa,UAAU;IACrB;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM;IAkBxE,OAAO,CAAC,MAAM,CAAC,eAAe;IA4B9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,YAAY,CACjB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,uBAAuB,EAAE,GAC/B,MAAM;IAWT;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAuBjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;CA0CzC"}

package/dist/fhirpath/transpiler.js

@@ -8,6 +8,7 @@ exports.Transpiler = void 0;
 const antlr4ts_1 = require("antlr4ts");
 const fhirpathLexer_1 = require("../generated/grammar/fhirpathLexer");
 const fhirpathParser_1 = require("../generated/grammar/fhirpathParser");
+const validation_js_1 = require("../validation.js");
 const visitor_1 = require("./visitor");
 class Transpiler {
     /**
@@ -47,29 +48,98 @@ class Transpiler {
         return { success: true, tree };
     }
     /**
-     * Get the SQL data type for a FHIRPath expression result.
+     * Get the SQL data type for a FHIR type, with optional tag-based override.
+     *
+     * Default mappings are conservative to accommodate ALL valid FHIR data,
+     * using MAX sizes where needed and NVARCHAR for any fields that could
+     * potentially contain Unicode characters.
+     *
+     * Design principles:
+     * - Use NVARCHAR for fields that may contain Unicode (string, code, uri/url/canonical)
+     * - Use VARCHAR for ASCII-only fields (id, uuid, oid, decimal, dates/times)
+     * - Use MAX or generous fixed sizes to prevent truncation
+     * - Preserve FHIR semantics (partial dates, arbitrary precision decimals)
+     *
+     * Users can optimise storage using type tags:
+     * - 'tsql/type' - Direct T-SQL type (e.g., 'DATE', 'VARCHAR(50)')
+     * - 'ansi/type' - ANSI/ISO SQL standard type (e.g., 'INTEGER', 'CHARACTER(50)', 'BOOLEAN')
+     *
+     * Type precedence: tsql/type > ansi/type > FHIR type defaults
+     *
+     * Example tag usage:
+     * - { "name": "tsql/type", "value": "DATE" } - Use T-SQL DATE type
+     * - { "name": "ansi/type", "value": "INTEGER" } - Use ANSI INTEGER (converted to T-SQL INT)
+     * - { "name": "ansi/type", "value": "BOOLEAN" } - Use ANSI BOOLEAN (converted to T-SQL BIT)
+     *
+     * @param fhirType - FHIR primitive type name (e.g., 'string', 'integer')
+     * @param tags - Optional array of column tags for type hints
+     * @returns MS SQL Server type specification
      */
-    static inferSqlType(fhirType) {
+    static inferSqlType(fhirType, tags) {
+        // Check for tsql/type tag override.
+        const tagOverride = this.getTagTypeOverride(tags);
+        if (tagOverride) {
+            return tagOverride;
+        }
+        // Use default FHIR type mapping.
+        return this.getDefaultFhirTypeMapping(fhirType);
+    }
+    /**
+     * Get type override from tsql/type or ansi/type tag if present.
+     *
+     * Precedence order:
+     * 1. tsql/type - Direct T-SQL type specification
+     * 2. ansi/type - ANSI/ISO SQL standard type (converted to T-SQL equivalent)
+     */
+    static getTagTypeOverride(tags) {
+        if (!tags) {
+            return null;
+        }
+        // Check for tsql/type tag first (highest precedence)
+        const tsqlTypeTag = tags.find((tag) => tag.name === "tsql/type");
+        if (tsqlTypeTag) {
+            (0, validation_js_1.validateMsSqlType)(tsqlTypeTag.value);
+            return tsqlTypeTag.value;
+        }
+        // Check for ansi/type tag (lower precedence)
+        const ansiTypeTag = tags.find((tag) => tag.name === "ansi/type");
+        if (ansiTypeTag) {
+            return (0, validation_js_1.validateAnsiSqlType)(ansiTypeTag.value);
+        }
+        return null;
+    }
+    /**
+     * Get default MS SQL Server type mapping for a FHIR primitive type.
+     */
+    static getDefaultFhirTypeMapping(fhirType) {
+        // Conservative default type mappings based on FHIR R4 constraints.
+        // Sized to accommodate ALL valid FHIR data.
+        // Uses NVARCHAR for potential Unicode, VARCHAR for ASCII-only.
         const typeMap = {
-            id: "NVARCHAR(MAX)",
+            // ASCII-only types with fixed constraints
+            id: "VARCHAR(64)",
+            boolean: "BIT",
+            integer: "INT",
+            positiveint: "INT",
+            unsignedint: "INT",
+            integer64: "BIGINT",
+            // ASCII-only structured formats
+            uuid: "VARCHAR(100)",
+            oid: "VARCHAR(255)",
+            decimal: "VARCHAR(MAX)",
+            date: "VARCHAR(10)",
+            datetime: "VARCHAR(50)",
+            instant: "VARCHAR(50)",
+            time: "VARCHAR(20)",
+            // Unicode-capable text types
             string: "NVARCHAR(MAX)",
             markdown: "NVARCHAR(MAX)",
             code: "NVARCHAR(MAX)",
+            // URIs (can be IRIs with Unicode)
             uri: "NVARCHAR(MAX)",
             url: "NVARCHAR(MAX)",
             canonical: "NVARCHAR(MAX)",
-            uuid: "NVARCHAR(MAX)",
-            oid: "NVARCHAR(MAX)",
-            boolean: "BIT",
-            integer: "INT",
-            positiveint: "INT",
-            unsignedint: "INT",
-            integer64: "BIGINT",
-            decimal: "DECIMAL(18,6)",
-            date: "DATETIME2",
-            datetime: "DATETIME2",
-            instant: "DATETIME2",
-            time: "TIME",
+            // Binary data
             base64binary: "VARBINARY(MAX)",
         };
         if (!fhirType) {

package/dist/fhirpath/transpiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"transpiler.js","sourceRoot":"","sources":["../../src/fhirpath/transpiler.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,uCAA0D;AAC1D,sEAAmE;AACnE,wEAG6C;AAC7C,uCAAqE;AAKrE,MAAa,UAAU;IACrB;;OAEG;IACH,MAAM,CAAC,SAAS,CAAC,UAAkB,EAAE,OAA0B;QAC7D,sDAAsD;QACtD,MAAM,WAAW,GAAG,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC;QACrD,IAAI,CAAC,WAAW,CAAC,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,wCAAwC,UAAU,GAAG,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,CAAC;YACH,0CAA0C;YAC1C,MAAM,OAAO,GAAG,IAAI,+BAAqB,CAAC,OAAO,CAAC,CAAC;YACnD,OAAO,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,4CAA4C,UAAU,MAAM,KAAK,EAAE,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,eAAe,CAAC,UAAkB;QAI/C,4BAA4B;QAC5B,MAAM,WAAW,GAAG,sBAAW,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAEvD,eAAe;QACf,MAAM,KAAK,GAAG,IAAI,6BAAa,CAAC,WAAW,CAAC,CAAC;QAC7C,MAAM,WAAW,GAAG,IAAI,4BAAiB,CAAC,KAAK,CAAC,CAAC;QAEjD,gBAAgB;QAChB,MAAM,MAAM,GAAG,IAAI,+BAAc,CAAC,WAAW,CAAC,CAAC;QAE/C,yDAAyD;QACzD,MAAM,CAAC,oBAAoB,EAAE,CAAC;QAE9B,8BAA8B;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAEvC,yBAAyB;QACzB,IAAI,MAAM,CAAC,oBAAoB,GAAG,CAAC,EAAE,CAAC;YACpC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,QAAiB;QACnC,MAAM,OAAO,GAA2B;YACtC,EAAE,EAAE,eAAe;YACnB,MAAM,EAAE,eAAe;YACvB,QAAQ,EAAE,eAAe;YACzB,IAAI,EAAE,eAAe;YACrB,GAAG,EAAE,eAAe;YACpB,GAAG,EAAE,eAAe;YACpB,SAAS,EAAE,eAAe;YAC1B,IAAI,EAAE,eAAe;YACrB,GAAG,EAAE,eAAe;YACpB,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,eAAe;YACxB,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,WAAW;YACrB,OAAO,EAAE,WAAW;YACpB,IAAI,EAAE,MAAM;YACZ,YAAY,EAAE,gBAAgB;SAC/B,CAAC;QAEF,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,eAAe,CAAC;QACzB,CAAC;QAED,OAAO,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,eAAe,CAAC;IAC5D,CAAC;CACF;AAnFD,gCAmFC"}
+{"version":3,"file":"transpiler.js","sourceRoot":"","sources":["../../src/fhirpath/transpiler.ts"],"names":[],"mappings":"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"}

package/dist/loader/tables.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/loader/tables.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAY,EAAE,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAEjD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAUf"}
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../../src/loader/tables.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAY,EAAE,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAGjD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAUf"}

package/dist/loader/tables.js

@@ -14,6 +14,7 @@ exports.createTable = createTable;
 exports.truncateTable = truncateTable;
 exports.ensureTable = ensureTable;
 const mssql_1 = __importDefault(require("mssql"));
+const validation_js_1 = require("../validation.js");
 /**
  * Check if a table exists in the database.
  *
@@ -42,6 +43,9 @@ async function tableExists(pool, schemaName, tableName) {
  * @param tableName - Name of the table to create.
  */
 async function createTable(pool, schemaName, tableName) {
+    // Validate identifiers to prevent SQL injection
+    (0, validation_js_1.validateSqlServerIdentifier)(schemaName, "Schema name");
+    (0, validation_js_1.validateSqlServerIdentifier)(tableName, "Table name");
     // Create the table.
     await pool.request().query(`
     CREATE TABLE [${schemaName}].[${tableName}] (
@@ -64,6 +68,9 @@ async function createTable(pool, schemaName, tableName) {
  * @param tableName - Name of the table to truncate.
  */
 async function truncateTable(pool, schemaName, tableName) {
+    // Validate identifiers to prevent SQL injection
+    (0, validation_js_1.validateSqlServerIdentifier)(schemaName, "Schema name");
+    (0, validation_js_1.validateSqlServerIdentifier)(tableName, "Table name");
     await pool.request().query(`TRUNCATE TABLE [${schemaName}].[${tableName}]`);
 }
 /**

package/dist/loader/tables.js.map

@@ -1 +1 @@
-{"version":3,"file":"tables.js","sourceRoot":"","sources":["../../src/loader/tables.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AAYH,kCAeC;AAUD,kCAmBC;AASD,sCAMC;AAUD,kCAeC;AA9FD,kDAAiD;AAEjD;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,IAAI;SACtB,OAAO,EAAE;SACT,KAAK,CAAC,YAAY,EAAE,eAAG,CAAC,QAAQ,EAAE,UAAU,CAAC;SAC7C,KAAK,CAAC,WAAW,EAAE,eAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC;;;;KAIlD,CAAC,CAAC;IAEL,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,oBAAoB;IACpB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC;oBACT,UAAU,MAAM,SAAS;;;;;GAK1C,CAAC,CAAC;IAEH,6EAA6E;IAC7E,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC;uBACN,SAAS;UACtB,UAAU,MAAM,SAAS;GAChC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,aAAa,CACjC,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,mBAAmB,UAAU,MAAM,SAAS,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB,EACjB,WAAoB,KAAK;IAEzB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"tables.js","sourceRoot":"","sources":["../../src/loader/tables.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AAaH,kCAeC;AAUD,kCAuBC;AASD,sCAUC;AAUD,kCAeC;AAvGD,kDAAiD;AACjD,oDAA+D;AAE/D;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,IAAI;SACtB,OAAO,EAAE;SACT,KAAK,CAAC,YAAY,EAAE,eAAG,CAAC,QAAQ,EAAE,UAAU,CAAC;SAC7C,KAAK,CAAC,WAAW,EAAE,eAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC;;;;KAIlD,CAAC,CAAC;IAEL,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,gDAAgD;IAChD,IAAA,2CAA2B,EAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACvD,IAAA,2CAA2B,EAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAErD,oBAAoB;IACpB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC;oBACT,UAAU,MAAM,SAAS;;;;;GAK1C,CAAC,CAAC;IAEH,6EAA6E;IAC7E,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC;uBACN,SAAS;UACtB,UAAU,MAAM,SAAS;GAChC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,aAAa,CACjC,IAAoB,EACpB,UAAkB,EAClB,SAAiB;IAEjB,gDAAgD;IAChD,IAAA,2CAA2B,EAAC,UAAU,EAAE,aAAa,CAAC,CAAC;IACvD,IAAA,2CAA2B,EAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAErD,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,mBAAmB,UAAU,MAAM,SAAS,GAAG,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,WAAW,CAC/B,IAAoB,EACpB,UAAkB,EAClB,SAAiB,EACjB,WAAoB,KAAK;IAEzB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/parser.d.ts

@@ -15,6 +15,10 @@ export declare class ViewDefinitionParser {
      * Validate and narrow a ViewDefinition structure using type predicate.
      */
     private static isValidViewDefinition;
+    /**
+     * Validate constant names match SQL on FHIR specification.
+     */
+    private static validateConstants;
     /**
      * Validate select element using type predicate.
      */
@@ -43,6 +47,14 @@ export declare class ViewDefinitionParser {
      * Validate column using type predicate.
      */
     private static isValidColumn;
+    /**
+     * Validate column tag structure.
+     */
+    private static validateColumnTags;
+    /**
+     * Validate a single tag object.
+     */
+    private static validateSingleTag;
     /**
      * Validate collection property constraints.
      */

package/dist/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,SAAS,EAIT,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,qBAAa,oBAAoB;IAC/B;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc;IAWjE;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUvD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA8BpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAa5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAQtC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAUxC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAWpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAWpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAyB5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAiC5C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IA0CtC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CA+BxC"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,SAAS,EAIT,cAAc,EAGf,MAAM,YAAY,CAAC;AAEpB,qBAAa,oBAAoB;IAC/B;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc;IAWjE;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUvD;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAqCpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAqBhC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAa5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAQtC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAYxC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAWpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAWpC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAY/B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IA6B5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAcjC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IA0BhC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAiC5C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB;IA0CtC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CA+BxC"}

package/dist/parser.js

@@ -30,12 +30,12 @@ class ViewDefinitionParser {
      */
     static isValidViewDefinition(data) {
         if (!data.resource || typeof data.resource !== "string") {
-            throw new Error("ViewDefinition must specify a resource type.");
+            throw new TypeError("ViewDefinition must specify a resource type.");
         }
         if (!data.select ||
             !Array.isArray(data.select) ||
             data.select.length === 0) {
-            throw new Error("ViewDefinition must have at least one select element.");
+            throw new TypeError("ViewDefinition must have at least one select element.");
         }
         // Status is optional for test cases, but recommended for production use
         // The SQL-on-FHIR spec requires status, but test cases may omit it
@@ -47,8 +47,30 @@ class ViewDefinitionParser {
                 return false;
             }
         }
+        // Validate constants if present
+        if (data.constant) {
+            this.validateConstants(data.constant);
+        }
         return true;
     }
+    /**
+     * Validate constant names match SQL on FHIR specification.
+     */
+    static validateConstants(constants) {
+        for (const constant of constants) {
+            if (!constant ||
+                typeof constant !== "object" ||
+                !("name" in constant) ||
+                typeof constant.name !== "string") {
+                throw new TypeError("Constant must have a valid name.");
+            }
+            // Validate constant name matches SQL on FHIR specification pattern
+            // Pattern: must start with a letter, followed by letters, digits, or underscores
+            if (!/^[A-Za-z]\w*$/.test(constant.name)) {
+                throw new Error(`Constant name '${constant.name}' does not match SQL on FHIR specification. Must start with a letter, followed by letters, digits, or underscores.`);
+            }
+        }
+    }
     /**
      * Validate select element using type predicate.
      */
@@ -72,10 +94,10 @@ class ViewDefinitionParser {
      */
     static validateSelectExpressions(select) {
         if (select.forEach && typeof select.forEach !== "string") {
-            throw new Error("forEach must be a string FHIRPath expression.");
+            throw new TypeError("forEach must be a string FHIRPath expression.");
         }
         if (select.forEachOrNull && typeof select.forEachOrNull !== "string") {
-            throw new Error("forEachOrNull must be a string FHIRPath expression.");
+            throw new TypeError("forEachOrNull must be a string FHIRPath expression.");
         }
     }
     /**
@@ -123,19 +145,54 @@ class ViewDefinitionParser {
      */
     static isValidColumn(column, selectContext) {
         if (!column.name || typeof column.name !== "string") {
-            throw new Error("Column must have a valid name.");
+            throw new TypeError("Column must have a valid name.");
         }
         if (!column.path || typeof column.path !== "string") {
-            throw new Error("Column must have a valid FHIRPath expression.");
+            throw new TypeError("Column must have a valid FHIRPath expression.");
         }
-        // Validate column name is database-friendly
-        if (!/^[a-zA-Z_]\w*$/.test(column.name)) {
-            throw new Error(`Column name '${column.name}' is not database-friendly. Use alphanumeric and underscores only.`);
+        // Validate column name matches SQL on FHIR specification pattern
+        // Pattern: must start with a letter, followed by letters, digits, or underscores
+        if (!/^[A-Za-z]\w*$/.test(column.name)) {
+            throw new Error(`Column name '${column.name}' does not match SQL on FHIR specification. Must start with a letter, followed by letters, digits, or underscores.`);
         }
         // Validate collection constraints
         this.validateCollectionConstraints(column, selectContext);
+        // Validate tag structure if present
+        this.validateColumnTags(column);
         return true;
     }
+    /**
+     * Validate column tag structure.
+     */
+    static validateColumnTags(column) {
+        if (column.tag === undefined) {
+            return;
+        }
+        if (!Array.isArray(column.tag)) {
+            throw new TypeError(`Column '${column.name}' tag must be an array.`);
+        }
+        for (const tag of column.tag) {
+            this.validateSingleTag(column.name, tag);
+        }
+    }
+    /**
+     * Validate a single tag object.
+     */
+    static validateSingleTag(columnName, tag) {
+        if (typeof tag !== "object" || tag === null) {
+            throw new TypeError(`Column '${columnName}' tag entry must be an object.`);
+        }
+        if (!("name" in tag) ||
+            typeof tag.name !== "string" ||
+            tag.name.trim().length === 0) {
+            throw new TypeError(`Column '${columnName}' tag must have a non-empty 'name' string.`);
+        }
+        if (!("value" in tag) ||
+            typeof tag.value !== "string" ||
+            tag.value.trim().length === 0) {
+            throw new TypeError(`Column '${columnName}' tag must have a non-empty 'value' string.`);
+        }
+    }
     /**
      * Validate collection property constraints.
      */