xoev-xwasser 0.905.4 → 1.0.1

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.
package/README.md CHANGED
@@ -27,21 +27,310 @@ The crate versions follow the `X.Y.Z+A.B.C` pattern:
27
27
 
28
28
  ## Features
29
29
 
30
- TBD.
30
+ This crate provides several features that can be enabled:
31
+
32
+ | Feature | Description |
33
+ |---------|-------------|
34
+ | `builder` | Enables builder patterns for type construction using `TypedBuilder` |
35
+ | `wasm` | Enables WebAssembly bindings using `wasm-bindgen` and `tsify` |
36
+ | `schema` | Enables XSD schema validation |
37
+ | `trace` | Enables tracing for debugging |
38
+
39
+ ### Default Features
40
+
41
+ By default, no features are enabled. To use the crate with builders and schema validation:
42
+
43
+ ```toml
44
+ xoev-xwasser = { version = "1.0.0", features = ["builder", "schema"] }
45
+ ```
46
+
47
+ ### Builder Pattern
48
+
49
+ The builder feature enables a fluent API for constructing XML messages:
50
+
51
+ ```rust
52
+ use xoev_xwasser::{
53
+ builder::{
54
+ pruefbericht::pruefbericht_type,
55
+ transport::{nachrichtenkopf_g2g, NachrichtenTypEnum},
56
+ vorgang::identifikation_vorgang,
57
+ },
58
+ model::{
59
+ signature::Signature,
60
+ transport::VorgangTransportieren2010,
61
+ vorgang::{Vorgang, VorgangType},
62
+ },
63
+ };
64
+
65
+ // Create a Pruefbericht
66
+ let pruefbericht = pruefbericht_type(
67
+ "1.0".into(),
68
+ None,
69
+ "test-context".into(),
70
+ Default::default(),
71
+ );
72
+
73
+ // Build the message with all required fields
74
+ let message = VorgangTransportieren2010::builder()
75
+ .produkt("MyApp".into())
76
+ .produkthersteller("My Company".into())
77
+ .produktversion("1.0.0".into())
78
+ .nachrichtenkopf_g2g(nachrichtenkopf_g2g(
79
+ NachrichtenTypEnum::VorgangTransportieren2010,
80
+ ))
81
+ .vorgang(
82
+ Vorgang::builder()
83
+ .identifikation_vorgang(identifikation_vorgang(None))
84
+ .vorgang_type(VorgangType::Pruefbericht(pruefbericht))
85
+ .bemerkung(None)
86
+ .anlage(Default::default())
87
+ .build(),
88
+ )
89
+ .zusatzinformationen(Default::default())
90
+ .signature(Some(Signature { exists: true }))
91
+ .build();
92
+ ```
93
+
94
+ ### Serialization
95
+
96
+ The crate supports both XML and JSON serialization:
97
+
98
+ ```rust
99
+ use raxb::{ser::to_string, de::from_str};
100
+ use serde_json;
101
+
102
+ // Serialize to XML
103
+ let xml = to_string(&message)?;
104
+
105
+ // Serialize to JSON
106
+ let json = serde_json::to_string(&message)?;
107
+
108
+ // Deserialize from XML
109
+ let parsed: VorgangTransportieren2010 = from_str(&xml)?;
110
+ ```
111
+
112
+ ### Schema Validation
113
+
114
+ The `schema` feature compiles XSD schemas into a binary format (`.xsdb`) and provides validation:
115
+
116
+ ```rust
117
+ use xoev_xwasser::schemas::XmlValidation;
118
+
119
+ let validation = XmlValidation::new()?;
120
+ validation.validate(xml_bytes)?;
121
+ ```
122
+
123
+ **How it works:**
124
+ 1. During build/test, `raxb_xmlschema_build` compiles `schemas/V1_0_0/xwasser.xsd` to `.xsdb` format
125
+ 2. The compiled schemas are embedded via `rust_embed`
126
+ 3. At runtime, XML is validated against the compiled schemas using `raxb_validate`
127
+
128
+ **Note:** Schema compilation runs automatically via the `schema` feature test:
129
+ ```sh
130
+ cargo test --features schema --test generate_schemas
131
+ ```
31
132
 
32
133
  ## Usage
33
134
 
34
- TBD.
135
+ ### Basic Example
136
+
137
+ ```rust
138
+ use xoev_xwasser::{
139
+ builder::{
140
+ pruefbericht::pruefbericht_type,
141
+ transport::{nachrichtenkopf_g2g, NachrichtenTypEnum},
142
+ vorgang::identifikation_vorgang,
143
+ },
144
+ model::{
145
+ signature::Signature,
146
+ transport::VorgangTransportieren2010,
147
+ vorgang::{Vorgang, VorgangType},
148
+ },
149
+ };
150
+
151
+ let pruefbericht = pruefbericht_type(
152
+ "1.0".into(),
153
+ None,
154
+ "context".into(),
155
+ Default::default(),
156
+ );
157
+
158
+ let message = VorgangTransportieren2010::builder()
159
+ .produkt("MyApp".into())
160
+ .produkthersteller("My Company".into())
161
+ .produktversion("1.0.0".into())
162
+ .nachrichtenkopf_g2g(nachrichtenkopf_g2g(
163
+ NachrichtenTypEnum::VorgangTransportieren2010,
164
+ ))
165
+ .vorgang(
166
+ Vorgang::builder()
167
+ .identifikation_vorgang(identifikation_vorgang(None))
168
+ .vorgang_type(VorgangType::Pruefbericht(pruefbericht))
169
+ .bemerkung(None)
170
+ .anlage(Default::default())
171
+ .build(),
172
+ )
173
+ .zusatzinformationen(Default::default())
174
+ .signature(Some(Signature { exists: true }))
175
+ .build();
176
+ ```
177
+
178
+ ### Working with Addresses
179
+
180
+ ```rust
181
+ use xoev_xwasser::builder::shared::anschrift::anschrift_type;
182
+
183
+ let addr = anschrift_type(
184
+ "Teststr.".into(),
185
+ "1".into(),
186
+ "12345".into(),
187
+ "Testort".into(),
188
+ );
189
+ ```
190
+
191
+ ### Codelist Codes
192
+
193
+ ```rust
194
+ use xoev_xwasser::model::codes::CodeGesamtbewertungType;
195
+
196
+ let bewertung = CodeGesamtbewertungType::builder()
197
+ .code("1010".into())
198
+ .name(None)
199
+ .build();
200
+ ```
201
+
202
+ ## TypeScript / WebAssembly
203
+
204
+ The crate compiles to WebAssembly for use in TypeScript/JavaScript applications:
205
+
206
+ ```bash
207
+ npm install xoev-xwasser
208
+ ```
209
+
210
+ ### Creating XML Messages
211
+
212
+ ```typescript
213
+ import {
214
+ create_vorgang_transportieren_2010,
215
+ parse_vorgang_transportieren_2010,
216
+ VorgangTransportieren2010,
217
+ PruefberichtType,
218
+ schema,
219
+ local_schema,
220
+ } from "xoev-xwasser";
221
+
222
+ import quality_report from "./quality_report.json";
223
+
224
+ // Create XML from JSON object
225
+ const xml = create_vorgang_transportieren_2010(
226
+ quality_report as unknown as VorgangTransportieren2010
227
+ ).replace(schema(), local_schema());
228
+ ```
229
+
230
+ ### Parsing XML
231
+
232
+ ```typescript
233
+ import { parse_vorgang_transportieren_2010 } from "xoev-xwasser";
234
+
235
+ const source = `<?xml version="1.0"?>
236
+ <VorgangTransportieren2010>...</VorgangTransportieren2010>`;
237
+
238
+ const obj = parse_vorgang_transportieren_2010(source);
239
+ if (obj.vorgang.vorgang_type.t === "Pruefbericht") {
240
+ const p = obj.vorgang.vorgang_type.c;
241
+ console.log(p.id);
242
+ }
243
+ ```
244
+
245
+ ### Utility Functions
246
+
247
+ ```typescript
248
+ import { vorname, familienname } from "xoev-xwasser/utils";
249
+ import { natuerliche_person_type } from "xoev-xwasser";
250
+
251
+ const person = natuerliche_person_type("Sepp", "Meier");
252
+ console.log(vorname(person)); // "Sepp"
253
+ console.log(familienname(person)); // "Meier"
254
+ ```
255
+
256
+ ### Schema Validation (Node.js)
257
+
258
+ ```typescript
259
+ import fs from "fs";
260
+ import xmlvalidate, { XmlValidatorError } from "@raxb/validate-wasm";
261
+
262
+ // Load compiled schema
263
+ const xsdBundle = fs.readFileSync(
264
+ "node_modules/xoev-xwasser/xwasser-v100.xsdb.bin"
265
+ ).buffer;
266
+
267
+ const { XmlValidator } = await xmlvalidate();
268
+ const validator = new XmlValidator(new Uint8Array(xsdBundle));
269
+ validator.init((err: string) => console.error(err));
270
+
271
+ // Validate XML
272
+ validator.validateXml(xmlString, (err: XmlValidatorError) => {
273
+ if (err.level === "fatal") {
274
+ console.error({ line: err.line, message: err.message });
275
+ }
276
+ });
277
+ ```
35
278
 
36
279
  ## Development
37
280
 
38
- wasm-pack watcher:
281
+ ### Building
282
+
283
+ ```sh
284
+ # Build with all features
285
+ cargo build --features builder,wasm,schema
286
+
287
+ # Run tests
288
+ cargo test --features builder,schema
289
+
290
+ # Run clippy
291
+ cargo clippy --features builder
292
+ ```
293
+
294
+ ### Full Build (includes WASM)
295
+
296
+ ```sh
297
+ ./build.sh
298
+ ```
299
+
300
+ ### Testing
301
+
302
+ Tests are run with specific feature combinations:
303
+
304
+ ```sh
305
+ # Core tests
306
+ cargo test
307
+
308
+ # Schema validation tests
309
+ cargo test --features schema,trace
310
+
311
+ # Builder tests
312
+ cargo test --features builder
313
+
314
+ # Full test suite
315
+ cargo test --no-default-features --features schema,trace,builder
316
+ ```
317
+
318
+ ### Code Linting
319
+
320
+ ```sh
321
+ cargo clippy --features builder --fix --allow-dirty
322
+ ```
323
+
324
+ ### WASM Development
325
+
326
+ For WASM builds during development:
39
327
 
40
328
  ```sh
329
+ # Watch mode with auto-rebuild
41
330
  cargo watch --watch src -s "./build.sh"
42
331
  ```
43
332
 
44
- vitest:
333
+ For TypeScript testing:
45
334
 
46
335
  ```sh
47
336
  pnpm i