@glion/config 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,390 @@
+# @glion/config
+
+Configuration schema and loader for hl7v2-specific settings.
+
+## Overview
+
+This package provides type-safe configuration loading for hl7v2-specific settings that augment the standard [unified-args](https://github.com/unifiedjs/unified-args) configuration system.
+
+**Key Features:**
+
+- ✅ Type-safe settings with TypeScript types
+- ✅ Runtime validation with Zod
+- ✅ JSON Schema for IDE autocomplete
+- ✅ Compatible with all unified-args RC file formats
+- ✅ Validates only hl7v2-specific `settings` - `plugins` handled by unified-args
+- ✅ Synchronous API for fast startup
+
+## Installation
+
+```bash
+npm install @glion/config
+```
+
+## Quick Start
+
+Create a `.hl7v2rc.json` file in your project:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rethinkhealth/glion/main/packages/hl7v2-config/schema.json",
+  "plugins": ["preset-lint-recommended"],
+  "settings": {
+    "delimiters": {
+      "field": "|",
+      "component": "^",
+      "subcomponent": "&",
+      "repetition": "~",
+      "escape": "\\",
+      "segment": "\r"
+    },
+    "experimental": {
+      "emptyMode": "empty"
+    }
+  }
+}
+```
+
+Then load the configuration:
+
+```typescript
+import { loadConfig } from "@glion/config";
+
+const { settings } = loadConfig();
+console.log(settings.delimiters.field); // "|"
+console.log(settings.experimental.emptyMode); // "empty"
+```
+
+## Configuration Schema
+
+### Settings
+
+The `settings` field contains hl7v2-specific configuration:
+
+```typescript
+type HL7v2Settings = {
+  delimiters?: {
+    field?: string; // default: "|"
+    component?: string; // default: "^"
+    subcomponent?: string; // default: "&"
+    repetition?: string; // default: "~"
+    escape?: string; // default: "\\"
+    segment?: string; // default: "\r"
+  };
+  experimental?: {
+    emptyMode?: "legacy" | "empty"; // default: "legacy"
+  };
+};
+```
+
+#### Delimiters
+
+Configure custom delimiters for HL7v2 message parsing. Each delimiter must be exactly one character.
+
+| Option         | Default | Description            |
+| -------------- | ------- | ---------------------- |
+| `field`        | `\|`    | Field separator        |
+| `component`    | `^`     | Component separator    |
+| `subcomponent` | `&`     | Subcomponent separator |
+| `repetition`   | `~`     | Repetition separator   |
+| `escape`       | `\\`    | Escape character       |
+| `segment`      | `\r`    | Segment terminator     |
+
+**Example:** Using custom delimiters for a non-standard system:
+
+```json
+{
+  "settings": {
+    "delimiters": {
+      "field": "#",
+      "component": "@"
+    }
+  }
+}
+```
+
+#### Experimental Features
+
+##### `emptyMode`
+
+Controls how empty fields/components are represented in the AST.
+
+| Value                | Description                                                                       |
+| -------------------- | --------------------------------------------------------------------------------- |
+| `"legacy"` (default) | Empty fields create full structure (Field -> Rep -> Comp -> Sub with `value: ""`) |
+| `"empty"`            | Empty fields have no children (Field with `children: []`)                         |
+
+**Status:** Experimental. Will become the default in v0.6.0.
+
+### Plugins
+
+The `plugins` field is handled by unified-args and follows the standard unified plugin configuration format:
+
+```json
+{
+  "plugins": [
+    "plugin-name",
+    ["plugin-name", { "option": "value" }],
+    ["plugin-name", ["error", { "option": "value" }]]
+  ]
+}
+```
+
+**Severity Levels:**
+| Value | Description |
+|-------|-------------|
+| `"off"` or `0` | Disable the rule |
+| `"on"` or `"warn"` or `1` | Enable as warning |
+| `"error"` or `2` | Enable as error |
+
+## Configuration Files
+
+The loader searches for configuration in the following locations (in order):
+
+| Location                                                    | Format              |
+| ----------------------------------------------------------- | ------------------- |
+| `package.json`                                              | Under `hl7v2` field |
+| `.hl7v2rc`                                                  | JSON                |
+| `.hl7v2rc.json`                                             | JSON                |
+| `.hl7v2rc.yaml` / `.hl7v2rc.yml`                            | YAML                |
+| `.hl7v2rc.js` / `.hl7v2rc.cjs` / `.hl7v2rc.mjs`             | JavaScript          |
+| `hl7v2.config.js` / `hl7v2.config.cjs` / `hl7v2.config.mjs` | JavaScript          |
+
+### JSON Configuration
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rethinkhealth/glion/main/packages/hl7v2-config/schema.json",
+  "plugins": [
+    "preset-lint-recommended",
+    ["lint-max-message-size", ["error", { "maxBytes": 5000000 }]]
+  ],
+  "settings": {
+    "experimental": {
+      "emptyMode": "empty"
+    }
+  }
+}
+```
+
+### TypeScript Configuration
+
+For type-safe configuration with IDE autocomplete, use `defineConfig()`:
+
+```typescript
+// hl7v2.config.ts
+import { defineConfig } from "@glion/config";
+
+export default defineConfig({
+  plugins: ["preset-lint-recommended"],
+  settings: {
+    delimiters: {
+      field: "|",
+      component: "^",
+    },
+    experimental: {
+      emptyMode: "empty",
+    },
+  },
+});
+```
+
+### JavaScript Configuration
+
+For dynamic configuration, use a JavaScript config file:
+
+```javascript
+// hl7v2.config.js
+export default {
+  plugins: [
+    "preset-lint-recommended",
+    [
+      "lint-max-message-size",
+      ["error", { maxBytes: parseInt(process.env.MAX_SIZE || "10000000") }],
+    ],
+  ],
+  settings: {
+    delimiters: {
+      segment: process.env.HL7_SEGMENT_TERMINATOR || "\r",
+    },
+    experimental: {
+      emptyMode: process.env.HL7_EMPTY_MODE || "legacy",
+    },
+  },
+};
+```
+
+### Package.json Configuration
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "hl7v2": {
+    "plugins": ["preset-lint-recommended"],
+    "settings": {
+      "experimental": {
+        "emptyMode": "empty"
+      }
+    }
+  }
+}
+```
+
+## API
+
+### `loadConfig(searchFrom?)`
+
+Load and validate hl7v2 configuration synchronously.
+
+**Recommended for:** CLI tools, startup code, and most use cases.
+
+```typescript
+import { loadConfig } from "@glion/config";
+
+// Load full config
+const config = loadConfig();
+
+// Load from a specific directory
+const config = loadConfig("/path/to/project");
+
+// Destructure to get only settings
+const { settings } = loadConfig();
+```
+
+**Parameters:**
+
+- `searchFrom` (optional): Directory to start searching from (defaults to cwd)
+
+**Returns:** `HL7v2Config` - Configuration object containing `plugins` and `settings`
+
+**Throws:** `ConfigurationError` if configuration is invalid
+
+### `loadConfigAsync(searchFrom?)`
+
+Load and validate hl7v2 configuration asynchronously.
+
+**Use when:** You need non-blocking I/O or are in an async context.
+
+```typescript
+import { loadConfigAsync } from "@glion/config";
+
+const config = await loadConfigAsync();
+const { settings } = await loadConfigAsync();
+```
+
+**Parameters:**
+
+- `searchFrom` (optional): Directory to start searching from (defaults to cwd)
+
+**Returns:** `Promise<HL7v2Config>` - Configuration object containing `plugins` and `settings`
+
+**Throws:** `ConfigurationError` if configuration is invalid
+
+### `defineConfig(config)`
+
+Type-safe helper for authoring configuration files. Provides IDE autocomplete without any runtime overhead.
+
+```typescript
+import { defineConfig } from "@glion/config";
+
+export default defineConfig({
+  plugins: ["preset-lint-recommended"],
+  settings: {
+    experimental: { emptyMode: "empty" },
+  },
+});
+```
+
+**Parameters:**
+
+- `config`: Configuration object
+
+**Returns:** The same config object (identity function for type inference)
+
+### `ConfigurationError`
+
+Error thrown when configuration validation fails.
+
+```typescript
+class ConfigurationError extends Error {
+  cause?: unknown;
+}
+```
+
+## IDE Support
+
+For IDE autocomplete and validation, add the `$schema` field to your JSON configuration:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/rethinkhealth/glion/main/packages/hl7v2-config/schema.json"
+}
+```
+
+## Integration with Parser
+
+The parser automatically reads settings from the unified processor:
+
+```typescript
+import { unified } from "unified";
+import { parseHL7v2 } from "@glion/hl7v2";
+
+const processor = unified()
+  .use(parseHL7v2)
+  .data("settings", {
+    delimiters: {
+      field: "|",
+      component: "^",
+    },
+    experimental: {
+      emptyMode: "empty",
+    },
+  });
+
+const tree = processor.parse("MSH|^~\\&|...");
+```
+
+When using the CLI, settings are automatically loaded from configuration files.
+
+## Design Principles
+
+1. **Augments, not replaces** - Extends unified-args via the `settings` field
+2. **Validates only settings** - The `plugins` field is handled by unified-args
+3. **Type-safe** - Full TypeScript support with Zod validation
+4. **IDE-friendly** - JSON Schema for autocomplete and validation
+5. **Backward compatible** - Defaults work without configuration
+
+## Related Packages
+
+- [@glion/hl7v2](../hl7v2) - Main hl7v2 parser
+- [@glion/cli](../hl7v2-cli) - CLI that uses this configuration
+- [unified-args](https://github.com/unifiedjs/unified-args) - Plugin configuration system
+
+## Security
+
+This package only validates configuration and does not execute arbitrary code from configuration files (except JS/MJS config files which are explicitly imported). Ensure you trust the source of your configuration files.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Code of Conduct
+
+To ensure a welcoming and positive environment, we have a [Code of Conduct][github-code-of-conduct] that all contributors and participants are expected to adhere to.
+
+## License
+
+Copyright 2025 Rethink Health, SUARL. All rights reserved.
+
+This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE][github-license] file for details.
+
+[github-code-of-conduct]: https://github.com/rethinkhealth/glion/blob/main/CODE_OF_CONDUCT.md
+[github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
+[github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md

package/dist/define.d.ts

@@ -0,0 +1,20 @@
+import type { HL7v2ConfigInput } from "./schema";
+/**
+ * Helper for type-safe configuration authoring.
+ *
+ * Use in your `hl7v2.config.ts` file for IDE autocomplete:
+ *
+ * @example
+ *   ```typescript
+ *   import { defineConfig } from "@glion/config";
+ *
+ *   export default defineConfig({
+ *     plugins: ["preset-lint-recommended"],
+ *     settings: {
+ *       experimental: { emptyMode: "empty" },
+ *     },
+ *   });
+ *   ```;
+ */
+export declare function defineConfig(config: HL7v2ConfigInput): HL7v2ConfigInput;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAEvE"}

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Configuration schema and loader for hl7v2.
+ *
+ * This package provides type-safe configuration loading for hl7v2-specific
+ * settings that augment the standard unified-args configuration system.
+ *
+ * ## Usage
+ *
+ * ### Load configuration programmatically (Synchronous - Recommended)
+ *
+ * ```typescript
+ * import { loadConfig } from "@glion/config";
+ *
+ * // Load full configuration
+ * const config = loadConfig();
+ * console.log(config.settings.experimental.emptyMode); // 'legacy' or 'empty'
+ * console.log(config.plugins); // Array of plugin configurations
+ *
+ * // Or destructure to get only settings
+ * const { settings } = loadConfig();
+ * console.log(settings.experimental.emptyMode); // 'legacy' or 'empty'
+ * ```
+ *
+ * ### Load configuration asynchronously
+ *
+ * ```typescript
+ * import { loadConfigAsync } from "@glion/config";
+ *
+ * const config = await loadConfigAsync();
+ * const { settings } = await loadConfigAsync();
+ * ```
+ *
+ * ### Configuration file format
+ *
+ * Create a `.hl7v2rc.json` file:
+ *
+ * ```json
+ * {
+ *   "$schema": "https://raw.githubusercontent.com/rethinkhealth/hl7v2/main/packages/hl7v2-config/schema.json",
+ *   "plugins": [
+ *     "preset-lint-recommended"
+ *   ],
+ *   "settings": {
+ *     "experimental": {
+ *       "emptyMode": "empty"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @module @glion/config
+ */
+import type { HL7v2Settings } from "./schema.js";
+export { defineConfig } from "./define";
+export { jsonSchema } from "./json-schema";
+export { ConfigurationError, clearCaches, loadConfig, loadConfigAsync, } from "./loader";
+export type { HL7v2Config, HL7v2ConfigInput, HL7v2Settings } from "./schema";
+export { HL7v2ConfigSchema } from "./schema";
+declare module "unified" {
+    interface Settings extends HL7v2Settings {
+    }
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,eAAe,GAChB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,QAAS,SAAQ,aAAa;KAAG;CAC5C"}

package/dist/index.js

@@ -0,0 +1,28 @@
+import { t as jsonSchema } from "./json-schema2.js";
+import { HL7v2ConfigSchema } from "./schema.js";
+import { ConfigurationError, clearCaches, loadConfig, loadConfigAsync } from "./loader.js";
+//#region src/define.ts
+/**
+* Helper for type-safe configuration authoring.
+*
+* Use in your `hl7v2.config.ts` file for IDE autocomplete:
+*
+* @example
+*   ```typescript
+*   import { defineConfig } from "@glion/config";
+*
+*   export default defineConfig({
+*     plugins: ["preset-lint-recommended"],
+*     settings: {
+*       experimental: { emptyMode: "empty" },
+*     },
+*   });
+*   ```;
+*/
+function defineConfig(config) {
+	return config;
+}
+//#endregion
+export { ConfigurationError, HL7v2ConfigSchema, clearCaches, defineConfig, jsonSchema, loadConfig, loadConfigAsync };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define.ts"],"sourcesContent":["import type { HL7v2ConfigInput } from \"./schema\";\n\n/**\n * Helper for type-safe configuration authoring.\n *\n * Use in your `hl7v2.config.ts` file for IDE autocomplete:\n *\n * @example\n *   ```typescript\n *   import { defineConfig } from \"@glion/config\";\n *\n *   export default defineConfig({\n *     plugins: [\"preset-lint-recommended\"],\n *     settings: {\n *       experimental: { emptyMode: \"empty\" },\n *     },\n *   });\n *   ```;\n */\nexport function defineConfig(config: HL7v2ConfigInput): HL7v2ConfigInput {\n  return config;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,aAAa,QAA4C;AACvE,QAAO"}

package/dist/json-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * JSON Schema for hl7v2 configuration.
+ *
+ * This schema can be used for IDE autocomplete by adding:
+ *
+ * ```json
+ * {
+ *   "$schema": "https://raw.githubusercontent.com/rethinkhealth/hl7v2/main/packages/hl7v2-config/schema.json"
+ * }
+ * ```
+ */
+export declare const jsonSchema: import("zod-to-json-schema").JsonSchema7Type & {
+    $schema?: string | undefined;
+    definitions?: {
+        [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+    } | undefined;
+};
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU;;;;;CAIrB,CAAC"}

package/dist/json-schema.js

@@ -0,0 +1,3 @@
+import { t as jsonSchema } from "./json-schema2.js";
+import "./schema.js";
+export { jsonSchema };