@digitalservicebund/a2j-xjustiz-bridge 0.6.0 → 0.7.1

package/README.md

@@ -24,6 +24,34 @@ XJustiz-Bridge, read the [documentation overview](../README.md).
 > for justice). It is part of the shared project [Zugang zum
 > Recht](https://www.zugang-zum-recht-projekte.de/).
 
+## Table of Contents
+
+- [Setup](#setup)
+  - [Installation](#installation)
+  - [Runtime Environment Requirements](#runtime-environment-requirements)
+  - [TypeScript Configuration Options (Recommended)](#typescript-configuration-options-recommended)
+  - [Additional Glossary (Optional)](#additional-glossary-optional)
+  - [A Word on Type Security](#a-word-on-type-security)
+- [Usage](#usage)
+  - [Find the Correct Message Profile](#find-the-correct-message-profile)
+  - [Use the Message Orchestrator](#use-the-message-orchestrator)
+  - [Fill the Content](#fill-the-content)
+    - [From Scalars to Full Messages](#from-scalars-to-full-messages)
+    - [Refined Types and Input Validation](#refined-types-and-input-validation)
+      - [Construction](#construction)
+        - [Using the Standard Schema](#using-the-standard-schema)
+        - [Using the Parsing Function Directly](#using-the-parsing-function-directly)
+      - [Customizing Issue Messages](#customizing-issue-messages)
+      - [Operating Safely on Refined Type Instances](#operating-safely-on-refined-type-instances)
+      - [Excursion - Deep Integrated Usage with Zod](#excursion---deeply-integrated-usage-with-zod)
+    - [Working with Identifiers](#working-with-identifiers)
+      - [Generating Identifiers](#generating-identifiers)
+      - [Identifiers with Additional Discriminator](#identifiers-with-additional-discriminator)
+      - [Referencing](#referencing)
+    - [Using Codelisten](#using-codelisten)
+    - [Accessing the Scope Type Directly](#accessing-the-scope-type-directly)
+- [More on the Scoping Pattern](#more-on-the-scoping-pattern)
+
 ## Setup
 
 ### Installation
@@ -32,8 +60,8 @@ The library is published to the [NPM package
 registry](https://www.npmjs.com/package/@digitalservicebund/a2j-xjustiz-bridge) and can be installed using any compatible package manager.
 
 ```sh
-npm add @digitalservicebund/a2j-xjustiz-bridge
-# or pnpm, yarn, ...
+pnpm add @digitalservicebund/a2j-xjustiz-bridge
+# or npm, yarn, ...
 ```
 
 The library comes with rich IntelliSense support. Contextual hover hints,
@@ -50,6 +78,12 @@ available on the global context object (`globalThis`):
 - `crypto.randomUUID` (for unique identifier generation, UUID v4 expected)
 - `Temporal` (for calendar based scalars)
 
+> [!IMPORTANT]
+> When using NodeJS, version 26 or newer is required because the library uses
+> the native Temporal API. If upgrading NodeJS is not possible, provide a
+> Temporal polyfill on `globalThis` before using the library, for example with
+> [`@js-temporal/polyfill`](https://github.com/js-temporal/temporal-polyfill).
+
 ### TypeScript Configuration Options (Recommended)
 
 The XJustiz-Bridge is built around a strong type system (more of this in the
@@ -190,17 +224,16 @@ Message orchestrators put multiple restrictions onto the composition function.
 The output must be a valid instance of the matching message profile (here
 `Zahlungsklage`). There are dedicated guides [how to fill the content of the message](#fill-the-content).
 
-The instance of the message profile must then pass a final verification to
-obtain a `VerifiedNachricht` using the `verifyNachricht` function, as expected
-by the orchestrator. Any violations at this point cause a type mismatch and
-result in compiler errors that must be fixed. For example, a duplicate
-identifier.
+The message must then pass a final verification to obtain a `VerifiedNachricht`.
+Therefore, each message profile provides a matching verification function. Any
+violations at this point cause a type mismatch and result in compiler errors
+that must be fixed. For example, a duplicate identifier.
 
 ```typescript
 zahlungsklage((scope) => {
-  // Composing message ...
-  return verifyNachricht({
-    /* ... */
+  // Preparations ...
+  return verifyZahlungsklage(scope, {
+    // Message ...
   });
 });
 ```
@@ -271,7 +304,7 @@ import {
   datatypeA, // Actual DIN 91379 datatypes, no documentation placeholders.
   datatypeB,
   Rollenbezeichnung,
-  verifyNachricht,
+  verifyZahlungsklage,
   zahlungsklage,
   // ... everything else used during composition
 } from "@digitalservicebund/a2j-xjustiz-bridge/nachricht/zahlungsklage";
@@ -339,7 +372,7 @@ const compositionResult = zahlungsklage(
 
     // ... and much more
 
-    return verifyNachricht({
+    return verifyZahlungsklage(scope, {
       nachrichtenkopf: {
         /* ... */
       },
@@ -357,6 +390,32 @@ const compositionResult = zahlungsklage(
 );
 ```
 
+#### Using Ergonomic Shortcuts
+
+Because composing a full message can be so extensive and constructing all the
+composites by hand becomes tedious, there is the concept of ergonomic
+constructor functions. They provide convenient shortcuts to construct large
+chunks quicker. They directly address real-world use cases and provide sensible
+defaults, saving many lines of code.
+
+Each message profile exports an `ergonomic` namespace that can be imported. It
+contains all ergonomic functions that might be relevant to compose a message for
+this profile. Functions can be discovered on the namespace itself. Furthermore,
+composite types are documented with references to related ergonomic functions.
+
+```typescript
+import {
+  zahlungsklage,
+  ergonomics,
+} from "@digitalservicebund/xjustiz-bridge/zahlungsklage";
+
+zahlungsklage((scope) => {
+  const wertAnspruch = ergonomics.geldbetrag(891.5);
+  const versaeumnisurteil = ergonomics.antragAufVersaeumnisurteil();
+  // ...
+}, connectionParameters);
+```
+
 #### Refined Types and Input Validation
 
 The XJustiz standard defines a set of datatypes with certain restrictions. For
@@ -512,7 +571,23 @@ const result = datatypeA(someInput);
 Notice that the customization does not apply to compile-time parsing. Parsing
 issues reported by the compiler only face developers and can't be changed.
 
-##### Excursion - Deep Integrated Usage with Zod
+##### Operating Safely on Refined Type Instances
+
+Because they way refined types are defined, their base type can be used
+directly. For example, a string based refined type can be used anywhere a string
+is expected. However, string based operations don't maintain the invariants and
+become plain strings on the output. The compiler can't know which operations are
+safe and which aren't. Therefore, to operate safely on refined type instances
+requires to use the operations provided by the respective type. Available
+operations can be discovered as part of the refined types documentation.
+
+For example, increment a `PositiveInteger` using the respective operation:
+
+```typescript
+const three = increment(positiveInteger(2).value); // Remains of type PositiveInteger
+```
+
+##### Excursion - Deeply Integrated Usage with Zod
 
 When using Zod as schema library (as the _Onlinedienste der Justiz_ do), it
 might be necessary to integrate more deeply with the refined types. While Zod
@@ -587,16 +662,11 @@ generator instance can be obtained using the provided scope token. Trying to
 create a generator for the same scope twice, results into the exact same instance.
 
 ```typescript
-zahlungsklage(
-  (scope) => {
-    const uuid = createUuidGenerator(scope);
-    // ...
-    const exactSameGenerator = createUuidGenerator(scope);
-  },
-  {
-    /* ... */
-  },
-);
+zahlungsklage((scope) => {
+  const uuid = createUuidGenerator(scope);
+  // ...
+  const exactSameGenerator = createUuidGenerator(scope);
+}, connectionParameters);
 ```
 
 Identifier generators produce a sorted sequence of unique instances for the
@@ -616,23 +686,18 @@ declared in. An advantage of the requirement to generate identifiers first is
 the possibility for forward referencing.
 
 ```typescript
-zahlungsklage(
-  (scope) => {
-    const uuid = createUuidGenerator(scope);
-    const eigeneNachrichtenID = uuid.first();
-
-    const nachrichtenkopf = {
-      absender: { eigeneNachrichtenID },
-      // ...
-    };
+zahlungsklage((scope) => {
+  const uuid = createUuidGenerator(scope);
+  const eigeneNachrichtenID = uuid.first();
 
-    const vortragsID = uuid.next(eigeneNachrichtenID);
+  const nachrichtenkopf = {
+    absender: { eigeneNachrichtenID },
     // ...
-  },
-  {
-    /* ... */
-  },
-);
+  };
+
+  const vortragsID = uuid.next(eigeneNachrichtenID);
+  // ...
+}, connectionParameters);
 ```
 
 ##### Identifiers with Additional Discriminator
@@ -648,34 +713,27 @@ In the following example, the `Rollennummer` identifier has an associated
 `Rollenbezeichnung` as discriminator.
 
 ```typescript
-zahlungsklage(
-  (scope) => {
-    const rollennummer = createRollennummerGenerator(scope);
-    const rollennummerFuerKlaeger = rollennummer.first(
-      Rollenbezeichnung.Klaeger,
-    );
+zahlungsklage((scope) => {
+  const rollennummer = createRollennummerGenerator(scope);
+  const rollennummerFuerKlaeger = rollennummer.first(Rollenbezeichnung.Klaeger);
 
-    const klaeger = {
-      rolle: [
-        {
-          rollennummer: rollennummerFuerKlaeger,
-          rollenbezeichnung: Rollenbezeichnung.Klaeger,
-        },
-      ],
-      // ...
-    };
+  const klaeger = {
+    rolle: [
+      {
+        rollennummer: rollennummerFuerKlaeger,
+        rollenbezeichnung: Rollenbezeichnung.Klaeger,
+      },
+    ],
+    // ...
+  };
 
-    const rollennummerFuerBeklagter = rollennummer.next(
-      rollennummerFuerKlaeger,
-      Rollenbezeichnung.Beklagter,
-    );
+  const rollennummerFuerBeklagter = rollennummer.next(
+    rollennummerFuerKlaeger,
+    Rollenbezeichnung.Beklagter,
+  );
 
-    // ...
-  },
-  {
-    /* ... */
-  },
-);
+  // ...
+}, connectionParameters);
 ```
 
 ##### Referencing
@@ -689,38 +747,31 @@ a dangling reference. Therefore, make sure any referenced identifier is actually
 used for declaration too.
 
 ```typescript
-zahlungsklage(
-  (scope) => {
-    const rollennummer = createRollennummerGenerator(scope);
-    const rollennummerFuerKlaeger = rollennummer.first(
-      Rollenbezeichnung.Klaeger,
-    );
-
-    const klaeger = {
-      rolle: [
-        {
-          rollennummer: rollennummerFuerKlaeger,
-          rollenbezeichnung: Rollenbezeichnung.Klaeger,
-        },
-      ],
-      // ...
-    };
+zahlungsklage((scope) => {
+  const rollennummer = createRollennummerGenerator(scope);
+  const rollennummerFuerKlaeger = rollennummer.first(Rollenbezeichnung.Klaeger);
 
-    const gesetzlicherVertreter = {
-      rolle: [
-        {
-          referenz: [{ refRollennummer: reference(rollennummerFuerKlaeger) }],
-        },
-      ],
-      // ...
-    };
+  const klaeger = {
+    rolle: [
+      {
+        rollennummer: rollennummerFuerKlaeger,
+        rollenbezeichnung: Rollenbezeichnung.Klaeger,
+      },
+    ],
+    // ...
+  };
 
+  const gesetzlicherVertreter = {
+    rolle: [
+      {
+        referenz: [{ refRollennummer: reference(rollennummerFuerKlaeger) }],
+      },
+    ],
     // ...
-  },
-  {
-    /* ... */
-  },
-);
+  };
+
+  // ...
+}, connectionParameters);
 ```
 
 #### Using Codelisten
@@ -740,22 +791,17 @@ maps to `{ "code": "101" }`. `Rollenbezeichnung` is the type as well as the rela
 constant object map of the Codeliste.
 
 ```typescript
-zahlungsklage(
-  (scope) => {
-    const klaeger = {
-      rolle: [
-        {
-          rollenbezeichnung: Rollenbezeichnung.Klaeger,
-        },
-      ],
-      // ...
-    };
+zahlungsklage((scope) => {
+  const klaeger = {
+    rolle: [
+      {
+        rollenbezeichnung: Rollenbezeichnung.Klaeger,
+      },
+    ],
     // ...
-  },
-  {
-    /* ... */
-  },
-);
+  };
+  // ...
+}, connectionParameters);
 ```
 
 #### Accessing the Scope Type Directly
@@ -768,21 +814,16 @@ composites depend on the scope, it becomes necessary to access the scope type
 directly — carried by the scope token.
 
 ```typescript
-zahlungsklage(
-  <NachrichtenScope>(scope: ScopeToken<NachrichtenScope>) => {
-    const klaeger = {
-      // Full language support here.
-    } satisfies Klaeger<NachrichtenScope>;
-  },
-  {
-    /* ... */
-  },
-);
+zahlungsklage(<NachrichtenScope>(scope: ScopeToken<NachrichtenScope>) => {
+  const klaeger = {
+    // Full language support here.
+  } satisfies Klaeger<NachrichtenScope>;
+}, connectionParameters);
 ```
 
-It is important to use `satisfies` operator. Otherwise, the final
-`verifyNachricht` will not work and report issues, because it can't properly
-evaluate the exact type of the composed message object.
+It is important to use `satisfies` operator. Otherwise, the final verification
+will not work and report issues, because it can't properly evaluate the exact
+type of the composed message object.
 
 ## More on the Scoping Pattern