@glion/builder 0.15.0 → 0.15.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +45 -75
  2. package/package.json +15 -7
package/README.md CHANGED
@@ -1,43 +1,20 @@
1
- # HL7v2 Builder
1
+ # @glion/builder
2
2
 
3
- `@glion/builder` provides a tiny set of helpers for assembling HL7v2 abstract syntax trees that follow the [`@glion/ast`](../hl7v2-ast/) schema. The helpers wrap [`unist-builder`](https://github.com/syntax-tree/unist-builder) so you can build trees with a couple of function calls instead of manually nesting nodes.
3
+ Tiny, typed helpers for assembling HL7v2 ASTs by hand.
4
4
 
5
- ## Why it helps
5
+ ## What it does
6
6
 
7
- - Work directly with typed nodes while avoiding the repetitive `u('node-type', …)` boilerplate from `unist-builder`.
8
- - Describe complex segments declaratively without worrying about separator placement or empty components.
9
-
10
- ## Philosophy
11
-
12
- - Stay explicit: you build the same AST shape you would by hand, so there is no hidden serialization logic or format guessing.
13
- - Compose freely: each helper is a thin wrapper over `unist-builder`, making it easy to mix raw nodes and other utilities when needed.
14
- - Keep things minimal: a small surface area means fewer abstractions to learn and less room for divergent interpretations of the HL7v2 model.
15
-
16
- ## Functions at a glance
17
-
18
- - `m(...segments)` – build a `root` (i.e. message) node from any number of segments.
19
- - `s(...fields)` – build a `segment` node from one or more `Field` nodes.
20
- - `f(...values)` – build a `field` node from strings, components, repetitions, or arrays thereof.
21
- - `r(...components)` – build a `field-repetition` node from strings or components.
22
- - `c(...values)` – build a `component` node from strings or arrays of strings.
23
-
24
- Each helper returns objects typed from `@glion/ast`, so the resulting tree can be consumed by any package in the ecosystem (parsers, linters, etc.).
7
+ `@glion/builder` provides five short functions (`m`, `s`, `f`, `r`, `c`) that wrap [`unist-builder`](https://github.com/syntax-tree/unist-builder) and return nodes typed from [`@glion/ast`](../ast/). You build trees with a few function calls instead of nesting `u('node-type', ...)` boilerplate by hand, and the output is the same shape a parser would produce — so any Glion consumer (serializers, linters, annotators) can read it back. The builder is intentionally small: no hidden serialization, no format guessing, no HL7v2 semantics. You decide what the tree looks like; the helpers just reduce the typing.
25
8
 
26
9
  ## Install
27
10
 
28
- This package is ESM-only. In Node.js 18+ run one of:
29
-
30
11
  ```bash
31
12
  npm install @glion/builder
32
- # or
33
- yarn add @glion/builder
34
- # or
35
- pnpm add @glion/builder
36
13
  ```
37
14
 
38
- ## Usage
15
+ ## Use
39
16
 
40
- ```typescript
17
+ ```ts
41
18
  import { c, f, m, s } from "@glion/builder";
42
19
 
43
20
  const tree = m(
@@ -49,58 +26,47 @@ const tree = m(
49
26
  f("PID"),
50
27
  f(), // empty field
51
28
  f([
52
- c(["123456", "DOE", "JOHN"]), // accept arrays or individual args interchangeably
29
+ c(["123456", "DOE", "JOHN"]), // arrays and individual args are interchangeable
53
30
  ])
54
31
  )
55
32
  );
56
33
  ```
57
34
 
58
- `tree` is now a `Root` node with two segments (`MSH`, `PID`). You can serialise it, transform it, or feed it into other HL7v2 utilities.
59
-
60
- ### Experimental: Empty Mode
61
-
62
- The builder respects the `emptyMode` experimental setting from `@glion/config`. When `emptyMode: "empty"` is configured in your `.hl7v2rc.json`, empty fields, repetitions, and components will have empty children arrays instead of the legacy full structure.
63
-
64
- **Legacy mode (default):**
65
-
66
- ```typescript
67
- f(); // → Field → Rep → Comp → Sub("")
68
- ```
69
-
70
- **Empty mode (via config):**
71
-
72
- ```typescript
73
- // With .hl7v2rc.json: { "settings": { "experimental": { "emptyMode": "empty" } } }
74
- f(); // → Field with children: []
75
- ```
76
-
77
- See [`@glion/config`](../hl7v2-config/) for configuration details.
35
+ `tree` is a `Root` node containing two segments (`MSH`, `PID`). Pass it to `@glion/to-hl7v2` to serialize, to `@glion/jsonify` to jsonify, or to any `unist` visitor to inspect it.
78
36
 
79
37
  ## API
80
38
 
81
39
  ### `m(...children: RootContent[]): Root`
82
40
 
41
+ Build a `Root` (message) node.
42
+
83
43
  - No arguments → empty root.
84
- - Pass any number of `RootContent` nodes (segments, fragments, etc.); they are appended in order.
85
- - Arguments are used as-is, so pass concrete AST nodes rather than nested arrays.
44
+ - Pass any number of `RootContent` nodes (segments, fragments); they are appended in order.
45
+ - Arguments are used as-is. Pass concrete AST nodes rather than nested arrays.
86
46
 
87
47
  ### `s(...fields: Field[]): Segment`
88
48
 
49
+ Build a `Segment` node.
50
+
89
51
  - No arguments → empty segment.
90
- - Provide the header field yourself, typically with `f('PID')`, and include it as the first argument.
91
- - Fields are appended in the order provided; the helper does not do any automatic flattening.
52
+ - Include the header field yourself, typically `f('PID')`, as the first argument.
53
+ - Fields are appended in the order provided; the helper does not auto-flatten.
92
54
 
93
55
  ### `f(...values: Array<string | Component | FieldRepetition | Array<string | Component | FieldRepetition>>): Field`
94
56
 
57
+ Build a `Field` node.
58
+
95
59
  - No arguments → empty field with a single empty repetition.
96
60
  - Strings become components with a single subcomponent containing the value.
97
61
  - `Component` instances are added directly.
98
- - `FieldRepetition` instances are preserved and allow you to control repetitions explicitly.
99
- - Arrays are flattened one level so you can pass a mixture of individual values and grouped lists.
100
- - Sequences of strings/components are grouped into a single repetition unless you introduce a `FieldRepetition` explicitly.
62
+ - `FieldRepetition` instances are preserved so you can control repetitions explicitly.
63
+ - Arrays are flattened one level, letting you mix individual values and grouped lists.
64
+ - Sequences of strings/components are grouped into a single repetition unless a `FieldRepetition` is introduced explicitly.
101
65
 
102
66
  ### `r(...components: Array<string | Component | Array<string | Component>>): FieldRepetition`
103
67
 
68
+ Build a `FieldRepetition` node.
69
+
104
70
  - No arguments → repetition with an empty component.
105
71
  - Strings become components with a single subcomponent containing the value.
106
72
  - Components are inserted as-is.
@@ -108,33 +74,37 @@ See [`@glion/config`](../hl7v2-config/) for configuration details.
108
74
 
109
75
  ### `c(...values: Array<string | string[]>): Component`
110
76
 
77
+ Build a `Component` node.
78
+
111
79
  - No arguments → component with an empty subcomponent.
112
80
  - Strings become subcomponents.
113
- - Arrays are flattened one level so you can pass `c('DOE', ['JOHN', 'Q'])`.
81
+ - Arrays are flattened one level, so `c('DOE', ['JOHN', 'Q'])` works.
82
+
83
+ For advanced scenarios — multiple repetitions per field, custom metadata, node reuse — drop down to `unist-builder` (`u`) directly and mix those nodes with the helpers above.
114
84
 
115
- > **Note**
116
- > These helpers are intentionally minimal. For advanced scenarios—multiple repetitions per field, custom metadata, or node reuse—you can still drop down to `unist-builder` (`u`) directly and mix those nodes with the helpers above.
85
+ ## Design
117
86
 
118
- ## Contributing
87
+ - **Explicit.** You build the same AST shape you would by hand. There is no hidden serialization logic or format guessing.
88
+ - **Composable.** Each helper is a thin wrapper over `unist-builder`, so raw nodes from `u()` and other utilities can be mixed freely.
89
+ - **Minimal.** A small surface means fewer abstractions to learn and less room for divergent interpretations of the HL7v2 model.
119
90
 
120
- We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.
91
+ ### Experimental: empty mode
121
92
 
122
- 1. Fork the repository
123
- 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
124
- 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
125
- 4. Push to the branch (`git push origin feature/amazing-feature`)
126
- 5. Open a Pull Request
93
+ The builder respects the `emptyMode` experimental setting from `@glion/config`. When `emptyMode: "empty"` is configured in your `.hl7v2rc.json`, empty fields, repetitions, and components use empty `children` arrays instead of the legacy full structure:
127
94
 
128
- ## Code of Conduct
95
+ ```ts
96
+ // Legacy mode (default):
97
+ f(); // → Field → Rep → Comp → Sub("")
129
98
 
130
- 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.
99
+ // Empty mode (via .hl7v2rc.json: { settings: { experimental: { emptyMode: "empty" } } }):
100
+ f(); // → Field with children: []
101
+ ```
131
102
 
132
- ## License
103
+ See [`@glion/config`](../config/) for configuration details.
133
104
 
134
- Copyright 2025 Rethink Health, SUARL. All rights reserved.
105
+ ## Part of Glion
135
106
 
136
- 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.
107
+ `@glion/builder` is part of **[Glion]**, the application framework for HL7v2. See the [Glion README] for the full package catalog and architecture.
137
108
 
138
- [github-code-of-conduct]: https://github.com/rethinkhealth/glion/blob/main/CODE_OF_CONDUCT.md
139
- [github-license]: https://github.com/rethinkhealth/glion/blob/main/LICENSE
140
- [github-contributing]: https://github.com/rethinkhealth/glion/blob/main/CONTRIBUTING.md
109
+ [Glion]: https://github.com/rethinkhealth/glion#readme
110
+ [Glion README]: https://github.com/rethinkhealth/glion#readme
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@glion/builder",
3
- "version": "0.15.0",
3
+ "version": "0.15.2",
4
4
  "description": "Build HL7v2 AST nodes",
5
5
  "keywords": [
6
6
  "health",
@@ -16,7 +16,11 @@
16
16
  "name": "Melek Somai",
17
17
  "email": "melek@rethinkhealth.io"
18
18
  },
19
- "repository": "rethinkhealth/glion.git",
19
+ "repository": {
20
+ "type": "git",
21
+ "url": "git+https://github.com/rethinkhealth/glion.git",
22
+ "directory": "packages/builder"
23
+ },
20
24
  "files": [
21
25
  "dist"
22
26
  ],
@@ -30,19 +34,21 @@
30
34
  },
31
35
  "dependencies": {
32
36
  "unist-builder": "4.0.0",
33
- "@glion/ast": "0.15.0",
34
- "@glion/config": "0.15.0"
37
+ "@glion/config": "0.15.2",
38
+ "@glion/ast": "0.15.2"
35
39
  },
36
40
  "devDependencies": {
37
41
  "@types/node": "^25.5.0",
38
42
  "@types/unist": "^3.0.3",
39
43
  "@vitest/coverage-v8": "4.1.2",
44
+ "publint": "0.3.18",
40
45
  "tsdown": "0.21.7",
41
46
  "typescript": "^5.9.3",
42
47
  "unified": "^11.0.5",
43
48
  "vitest": "4.1.2",
44
- "@glion/tsconfig": "0.15.0",
45
- "@glion/testing": "0.15.0"
49
+ "@glion/check-readme": "0.15.2",
50
+ "@glion/testing": "0.15.2",
51
+ "@glion/tsconfig": "0.15.2"
46
52
  },
47
53
  "engines": {
48
54
  "node": ">=18"
@@ -51,8 +57,10 @@
51
57
  "scripts": {
52
58
  "build": "tsdown && tsc --emitDeclarationOnly",
53
59
  "check-types": "tsc --noEmit",
60
+ "check:readme": "glion-check-readme",
54
61
  "test": "vitest run",
55
62
  "test:coverage": "vitest run --coverage",
56
- "test:watch": "vitest"
63
+ "test:watch": "vitest",
64
+ "publint": "publint --strict"
57
65
  }
58
66
  }