@endevops/peppol-schema 0.1.2 → 0.1.4

package/src/schemas/utils/peppol-base-64-schema.ts

@@ -1,5 +1,7 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
+
 // RFC 4648 §4 — Base 64 Encoding
 //
 // Alphabet: A-Z a-z 0-9 + /  (pad: =)
@@ -25,9 +27,17 @@ const BASE64_RE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=
 /**
  * @description RFC 4648 base64 string (PEM / MIME / XML line endings tolerated). Effect port of `base64Schema` (`z.string().check(z.refine(...))`): strips CRLF /
  * LF line endings before testing the quantum regex.
+ *
+ * @example
+ *   ```ts
+ *   const value = 'SGVsbG8=';
+ *   ```;
  */
-export const peppolBase64Schema = Schema.String.check(Schema.makeFilter((val: string) => BASE64_RE.test(val.replace(/\r?\n/g, '')))).annotate({
-  message: 'Invalid base64',
-});
+export class PeppolBase64 extends opaque<PeppolBase64>()(
+  Schema.String.check(Schema.makeFilter((val: string) => BASE64_RE.test(val.replace(/\r?\n/g, '')))).annotate({ message: 'Invalid base64' })
+) {}
 
-export type Base64 = typeof peppolBase64Schema.Type;
+/**
+ * @description Alias of {@link PeppolBase64} for callers that prefer the shorter name.
+ */
+export type Base64 = PeppolBase64;

package/src/schemas/utils/peppol-vat-regex-schema.ts

@@ -1,6 +1,7 @@
 import { Schema } from 'effect';
 
 import { isValidMod97_0208 } from '#/peppol-validations/is-valid-mod97-0208.ts';
+import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
  * @description Belgian VAT number (`BE` + 10 digits with mod 97-0208 check digits). Effect port of the `BE` member of `vatRegexSchema`: prefix, exact length,
@@ -16,34 +17,41 @@ const belgianVat = Schema.String.check(
 /**
  * @description EU VAT identification number (one member per member-state prefix/pattern). Effect port of `vatRegexSchema` (`z.union([...])` of
  * `z.string().check(...)` members): each member keeps its original prefix + pattern checks as `Schema.String.check` filters.
+ *
+ * @example
+ *   ```ts
+ *   const value = 'DE123456789';
+ *   ```;
  */
-export const peppolVatRegexSchema = Schema.Union([
-  belgianVat,
-  Schema.String.check(Schema.isStartsWith('AT'), Schema.isPattern(/^ATU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('BG'), Schema.isPattern(/^BG\d{9,10}$/)),
-  Schema.String.check(Schema.isStartsWith('CY'), Schema.isPattern(/^CY\d{8}L$/)),
-  Schema.String.check(Schema.isStartsWith('CZ'), Schema.isPattern(/^CZ\d{8,10}$/)),
-  Schema.String.check(Schema.isStartsWith('DE'), Schema.isPattern(/^DE\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('DK'), Schema.isPattern(/^DK\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('EE'), Schema.isPattern(/^EE\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('EL'), Schema.isPattern(/^EL\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('GR'), Schema.isPattern(/^GR\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('ES'), Schema.isPattern(/^ES[0-9A-Z]\d{7}[0-9A-Z]$/)),
-  Schema.String.check(Schema.isStartsWith('FI'), Schema.isPattern(/^FI\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('FR'), Schema.isPattern(/^FR[0-9A-Z]{2}\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('GB'), Schema.isPattern(/^GB(\d{9}(\d{3})?|[A-Z]{2}\d{3})$/)),
-  Schema.String.check(Schema.isStartsWith('HU'), Schema.isPattern(/^HU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('IE'), Schema.isPattern(/^IE\dS\d{5}L$/)),
-  Schema.String.check(Schema.isStartsWith('IT'), Schema.isPattern(/^IT\d{11}$/)),
-  Schema.String.check(Schema.isStartsWith('LT'), Schema.isPattern(/^LT(\d{9}|\d{12})$/)),
-  Schema.String.check(Schema.isStartsWith('LU'), Schema.isPattern(/^LU\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('LV'), Schema.isPattern(/^LV\d{11}$/)),
-  Schema.String.check(Schema.isStartsWith('MT'), Schema.isPattern(/^MT\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('NL'), Schema.isPattern(/^NL\d{9}B\d{2}$/)),
-  Schema.String.check(Schema.isStartsWith('PL'), Schema.isPattern(/^PL\d{10}$/)),
-  Schema.String.check(Schema.isStartsWith('PT'), Schema.isPattern(/^PT\d{9}$/)),
-  Schema.String.check(Schema.isStartsWith('RO'), Schema.isPattern(/^RO\d{2,10}$/)),
-  Schema.String.check(Schema.isStartsWith('SE'), Schema.isPattern(/^SE\d{12}$/)),
-  Schema.String.check(Schema.isStartsWith('SI'), Schema.isPattern(/^SI\d{8}$/)),
-  Schema.String.check(Schema.isStartsWith('SK'), Schema.isPattern(/^SK\d{10}$/)),
-]);
+export class PeppolVatRegex extends opaque<PeppolVatRegex>()(
+  Schema.Union([
+    belgianVat,
+    Schema.String.check(Schema.isStartsWith('AT'), Schema.isPattern(/^ATU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('BG'), Schema.isPattern(/^BG\d{9,10}$/)),
+    Schema.String.check(Schema.isStartsWith('CY'), Schema.isPattern(/^CY\d{8}L$/)),
+    Schema.String.check(Schema.isStartsWith('CZ'), Schema.isPattern(/^CZ\d{8,10}$/)),
+    Schema.String.check(Schema.isStartsWith('DE'), Schema.isPattern(/^DE\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('DK'), Schema.isPattern(/^DK\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('EE'), Schema.isPattern(/^EE\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('EL'), Schema.isPattern(/^EL\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('GR'), Schema.isPattern(/^GR\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('ES'), Schema.isPattern(/^ES[0-9A-Z]\d{7}[0-9A-Z]$/)),
+    Schema.String.check(Schema.isStartsWith('FI'), Schema.isPattern(/^FI\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('FR'), Schema.isPattern(/^FR[0-9A-Z]{2}\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('GB'), Schema.isPattern(/^GB(\d{9}(\d{3})?|[A-Z]{2}\d{3})$/)),
+    Schema.String.check(Schema.isStartsWith('HU'), Schema.isPattern(/^HU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('IE'), Schema.isPattern(/^IE\dS\d{5}L$/)),
+    Schema.String.check(Schema.isStartsWith('IT'), Schema.isPattern(/^IT\d{11}$/)),
+    Schema.String.check(Schema.isStartsWith('LT'), Schema.isPattern(/^LT(\d{9}|\d{12})$/)),
+    Schema.String.check(Schema.isStartsWith('LU'), Schema.isPattern(/^LU\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('LV'), Schema.isPattern(/^LV\d{11}$/)),
+    Schema.String.check(Schema.isStartsWith('MT'), Schema.isPattern(/^MT\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('NL'), Schema.isPattern(/^NL\d{9}B\d{2}$/)),
+    Schema.String.check(Schema.isStartsWith('PL'), Schema.isPattern(/^PL\d{10}$/)),
+    Schema.String.check(Schema.isStartsWith('PT'), Schema.isPattern(/^PT\d{9}$/)),
+    Schema.String.check(Schema.isStartsWith('RO'), Schema.isPattern(/^RO\d{2,10}$/)),
+    Schema.String.check(Schema.isStartsWith('SE'), Schema.isPattern(/^SE\d{12}$/)),
+    Schema.String.check(Schema.isStartsWith('SI'), Schema.isPattern(/^SI\d{8}$/)),
+    Schema.String.check(Schema.isStartsWith('SK'), Schema.isPattern(/^SK\d{10}$/)),
+  ])
+) {}

package/src/schemas/utils/peppol-xsd-time-schema.ts

@@ -17,9 +17,14 @@ const numberFromString = (value: string | undefined): number => {
 /**
  * @description Parse a timezone offset from a string. The string must be in the format `(+|-)HH:MM` where `HH` and `MM` are two digits.
  *
- * @param tz - The timzeone offset string.
+ * @example
+ *   ```ts
+ *   parseZoneOffsetFromString('+01:00'); // a +01:00 zone offset
+ *   ```;
  *
- * @returns
+ * @param tz - The timezone offset string.
+ *
+ * @returns A `DateTime.Zone` offset built from the parsed hours and minutes, or `undefined` when `tz` does not match the offset pattern.
  *
  * @internal
  */
@@ -36,6 +41,11 @@ export const parseZoneOffsetFromString = (tz: `+${number}:${number}` | `-${numbe
 /**
  * @description XSD `time` lexical value (`HH:MM:SS` with optional fractional seconds and timezone). Effect port of `xsdTime` (`z.string().check(z.regex(...))`):
  * keeps the value as a plain string and only validates the shape.
+ *
+ * @example
+ *   ```ts
+ *   const value = '12:30:45+01:00';
+ *   ```;
  */
 export class PeppolXsdTime extends opaque<PeppolXsdTime>()(
   Schema.String.check(

package/src/schemas/utils/quantity-unit-code-to-intl-unit.ts

@@ -1,5 +1,8 @@
 import type { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
+/**
+ * @description String union of `Intl.NumberFormat` unit identifiers for base units such as length, area, volume, mass, and temperature.
+ */
 export type BaseIntlUnit =
   | 'acre'
   | 'bit'
@@ -36,10 +39,26 @@ export type BaseIntlUnit =
   | 'terabit'
   | 'terabyte'
   | 'yard';
+/**
+ * @description String union of `Intl.NumberFormat` unit identifiers for time units, used on their own and as the denominator of a rate.
+ */
 export type TimeIntlUnit = 'nanosecond' | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
 
+/**
+ * @description Any `Intl.NumberFormat` unit identifier supported by this module: a {@link BaseIntlUnit}, a {@link TimeIntlUnit}, or a rate such as
+ * `'kilometer-per-hour'`.
+ */
 export type IntlUnit = BaseIntlUnit | TimeIntlUnit | `${BaseIntlUnit}-per-${TimeIntlUnit}`;
 
+/**
+ * @description Maps UN/ECE Rec 20 quantity unit codes to `Intl.NumberFormat` unit identifiers. Unmapped codes are omitted.
+ *
+ * @example
+ *   ```ts
+ *   quantityToIntlUnitMap.KGM; // 'kilogram'
+ *   quantityToIntlUnitMap.KMH; // 'kilometer-per-hour'
+ *   ```;
+ */
 export const quantityToIntlUnitMap = {
   CMT: 'centimeter',
   MTR: 'meter',
@@ -106,6 +125,21 @@ export const quantityToIntlUnitMap = {
   '4M': 'gram-per-hour' as IntlUnit,
 } satisfies Partial<Record<string, IntlUnit>>;
 
+/**
+ * @description Looks up the `Intl.NumberFormat` unit identifier for a UN/ECE Rec 20 quantity unit code.
+ *
+ * @example
+ *   ```ts
+ *   quantityUnitCodeToIntlUnit('KGM'); // 'kilogram'
+ *   quantityUnitCodeToIntlUnit('EA'); // undefined
+ *   ```;
+ *
+ * @param code - A quantity unit code, typed as {@link PeppolQuantityUnitCode} but accepting any string.
+ *
+ * @returns The matching {@link IntlUnit}, or `undefined` when the code has no `Intl` unit mapping.
+ *
+ * @see {@link quantityToIntlUnitMap}
+ */
 export function quantityUnitCodeToIntlUnit(code: PeppolQuantityUnitCode | (string & {})): IntlUnit | undefined {
   return (quantityToIntlUnitMap as Record<string, IntlUnit>)[code];
 }

package/src/schemas/values/additional-document-reference-code-schema.ts

@@ -1,25 +1,19 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { additionalDocumentReferenceCodesKeys } from '#/values/additional-document-reference-codes.generated';
 
 /**
- * @description Additional document reference.
+ * @description An additional document reference code from the PEPPOL subset of UNCL 1153 (invoiced object identifier scheme).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1153/
- * @see {@link additionalDocumentReferenceCodesKeys}
- */
-export type PeppolAdditionalDocumentReferenceCode = typeof additionalDocumentReferenceCodeSchema.Type;
-
-/**
- * @description Validates an additional document reference code against the PEPPOL subset of UNCL 1153 (reference qualifiers).
- *
- * @param error - The custom error message to use when validation fails. Defaults to the generic message.
- *
- * @returns An Effect schema that accepts only valid additional document reference codes.
+ * @example
+ *   ```ts
+ *   'AAA';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1153/
  * @see {@link additionalDocumentReferenceCodesKeys}
  */
-export const additionalDocumentReferenceCodeSchema = Schema.Literals(additionalDocumentReferenceCodesKeys).pipe(
-  Schema.brand('PeppolAdditionalDocumentReferenceCode')
-);
+export class PeppolAdditionalDocumentReferenceCode extends opaque<PeppolAdditionalDocumentReferenceCode>()(
+  Schema.Literals(additionalDocumentReferenceCodesKeys).pipe(Schema.brand('PeppolAdditionalDocumentReferenceCode'))
+) {}

package/src/schemas/values/allowance-charge-reason-code-schema.ts

@@ -1,26 +1,24 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { allowanceChargeReasonCodesKeys } from '#/values/allowance-charge-reason-codes.generated';
 
 /**
- * @description An allowance or charge reason code as defined by the PEPPOL subset of UNCL 5189.
+ * @description An allowance or charge reason code from the PEPPOL subset of UNCL 5189 (D.16B).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5189/
- */
-export type PeppolAllowanceChargeReasonCode = typeof allowanceChargeReasonCodeSchema.Type;
-
-/**
- * @description Validates an allowance or charge reason code against the PEPPOL subset of UNCL 5189 (D.16B).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid allowance/charge reason codes.
+ * @example
+ *   ```ts
+ *   '41';
+ *   ```;
  *
  * @validations
  * - PEPPOL-EN16931-CL002: Document allowance reason code MUST be according to the subset of UNCL 5189 D.16B.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5189/
+ * @see {@link allowanceChargeReasonCodesKeys}
  */
-export const allowanceChargeReasonCodeSchema = Schema.Literals(allowanceChargeReasonCodesKeys)
-  .pipe(Schema.brand('PeppolAllowanceChargeReasonCode'))
-  .annotate({ documentation: 'PEPPOL-EN16931-CL002: Reason code MUST be according to subset of UNCL 5189 D.16B.' });
+export class PeppolAllowanceChargeReasonCode extends opaque<PeppolAllowanceChargeReasonCode>()(
+  Schema.Literals(allowanceChargeReasonCodesKeys)
+    .pipe(Schema.brand('PeppolAllowanceChargeReasonCode'))
+    .annotate({ documentation: 'PEPPOL-EN16931-CL002: Reason code MUST be according to subset of UNCL 5189 D.16B.' })
+) {}

package/src/schemas/values/application-response-type-code-schema.ts

@@ -1,23 +1,19 @@
 import { Schema } from 'effect';
 
-import type { ApplicationResponseTypeCodesKeys } from '#/values/application-response-type-codes.generated';
-
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { applicationResponseTypeCodesKeys } from '#/values/application-response-type-codes.generated';
 
 /**
- * @description An application response type code as defined by the PEPPOL subset of UNCL 4343.
- *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343/
- */
-export type PeppolApplicationResponseTypeCode = ApplicationResponseTypeCodesKeys;
-
-/**
- * @description Validates an application response type code against the PEPPOL subset of UNCL 4343.
- *
- * @param error - The custom error message to use when validation fails.
+ * @description An application response type code from the PEPPOL subset of UNCL 4343.
  *
- * @returns An Effect schema that accepts only valid application response type codes.
+ * @example
+ *   ```ts
+ *   'AB';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343/
+ * @see {@link applicationResponseTypeCodesKeys}
  */
-export const applicationResponseTypeCodeSchema = Schema.Literals(applicationResponseTypeCodesKeys);
+export class PeppolApplicationResponseTypeCode extends opaque<PeppolApplicationResponseTypeCode>()(
+  Schema.Literals(applicationResponseTypeCodesKeys)
+) {}

package/src/schemas/values/charge-reason-code-schema.ts

@@ -1,26 +1,24 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { chargeReasonCodesKeys } from '#/values/charge-reason-codes.generated';
 
 /**
- * @description A charge reason code as defined by the PEPPOL subset of UNCL 7161.
+ * @description A charge reason code from the PEPPOL subset of UNCL 7161 (D.16B).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/
- */
-export type PeppolChargeReasonCode = typeof chargeReasonCodeSchema.Type;
-
-/**
- * @description Validates a charge reason code against the PEPPOL subset of UNCL 7161 (D.16B).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid charge reason codes.
+ * @example
+ *   ```ts
+ *   'AA';
+ *   ```;
  *
  * @validations
  * - PEPPOL-EN16931-CL003: Charge reason code MUST be according to UNCL 7161 D.16B.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/
+ * @see {@link chargeReasonCodesKeys}
  */
-export const chargeReasonCodeSchema = Schema.Literals(chargeReasonCodesKeys)
-  .pipe(Schema.brand('PeppolChargeReasonCode'))
-  .annotate({ documentation: 'PEPPOL-EN16931-CL003: Reason code MUST be according to UNCL 7161 D.16B.' });
+export class PeppolChargeReasonCode extends opaque<PeppolChargeReasonCode>()(
+  Schema.Literals(chargeReasonCodesKeys)
+    .pipe(Schema.brand('PeppolChargeReasonCode'))
+    .annotate({ documentation: 'PEPPOL-EN16931-CL003: Reason code MUST be according to UNCL 7161 D.16B.' })
+) {}

package/src/schemas/values/credit-note-type-code-schema.ts

@@ -1,23 +1,17 @@
 import { Schema } from 'effect';
 
-import type { CreditNoteTypeCodesKeys } from '#/values/credit-notes-type-codes.generated';
-
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { creditNoteTypeCodesKeys } from '#/values/credit-notes-type-codes.generated';
 
 /**
- * @description A credit note type code as defined by the PEPPOL subset of UNCL 1001 (credit note).
- *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1001-cn/
- */
-export type PeppolCreditNoteTypeCode = CreditNoteTypeCodesKeys;
-
-/**
- * @description Validates a credit note type code against the PEPPOL subset of UNCL 1001 (credit note).
- *
- * @param error - The custom error message to use when validation fails.
+ * @description A credit note type code from the PEPPOL subset of UNCL 1001 (credit note).
  *
- * @returns An Effect schema that accepts only valid credit note type codes.
+ * @example
+ *   ```ts
+ *   '81';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1001-cn/
+ * @see {@link creditNoteTypeCodesKeys}
  */
-export const creditNoteTypeCodeSchema = Schema.Literals(creditNoteTypeCodesKeys);
+export class PeppolCreditNoteTypeCode extends opaque<PeppolCreditNoteTypeCode>()(Schema.Literals(creditNoteTypeCodesKeys)) {}

package/src/schemas/values/currency-code-schema.ts

@@ -7,31 +7,28 @@
 
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { currencyCodesKeys } from '#/values/currency-code.generated';
 
 /**
- * @description An ISO 4217 currency code as defined by the PEPPOL subset.
+ * @description An ISO 4217 currency code from the PEPPOL codelist.
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/
- */
-export type PeppolCurrencyCode = Schema.Schema.Type<typeof currencyCodeSchema>;
-/**
- * @description An ISO 4217 currency code as defined by the PEPPOL subset.
+ * @example
+ *   ```ts
+ *   'AED';
+ *   ```;
+ *
+ * @validations
+ * - PEPPOL-EN16931-CL007: Currency codes MUST be valid ISO 4217 codes.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/
+ * @see {@link currencyCodesKeys}
  */
-export type PeppolCurrencyCodeEncoded = Schema.Codec.Encoded<typeof currencyCodeSchema>;
+export class PeppolCurrencyCode extends opaque<PeppolCurrencyCode>()(Schema.Literals(currencyCodesKeys).pipe(Schema.brand('PeppolCurrencyCode'))) {}
 
 /**
- * @description Validates an ISO 4217 currency code against the PEPPOL codelist.
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid currency codes.
- *
- * @validations
- * - PEPPOL-EN16931-CL007: Currency codes MUST be valid ISO 4217 codes.
+ * @description An ISO 4217 currency code as defined by the PEPPOL subset.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/
  */
-export const currencyCodeSchema = Schema.Literals(currencyCodesKeys).pipe(Schema.brand('PeppolCurrencyCode'));
+export type PeppolCurrencyCodeEncoded = Schema.Codec.Encoded<typeof PeppolCurrencyCode>;

package/src/schemas/values/document-type-schemes-schema.ts

@@ -1,14 +1,18 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { documentTypesScheme } from '#/values/document-type.generated';
 
 /**
- * @description Validates a PEPPOL document type scheme (e.g. `busdox-docid-qns`, `peppol-doctype-wildcard`).
+ * @description A PEPPOL document type scheme, for example `busdox-docid-qns` or `peppol-doctype-wildcard`.
  *
- * @param error - The error message to use when validation fails. Defaults to `'invalid Peppol document type scheme'`.
- *
- * @returns An Effect schema that accepts only valid document type schemes.
+ * @example
+ *   ```ts
+ *   'busdox-docid-qns';
+ *   ```;
  *
  * @see {@link documentTypesScheme}
  */
-export const documentTypeSchemesSchema = Schema.Literals(documentTypesScheme as [string, ...Array<string>]);
+export class PeppolDocumentTypeScheme extends opaque<PeppolDocumentTypeScheme>()(
+  Schema.Literals(documentTypesScheme as [string, ...Array<string>])
+) {}

package/src/schemas/values/document-type-values-schema.ts

@@ -1,16 +1,15 @@
 import { Record, Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { documentTypesTable } from '#/values/document-type.generated';
 
 const values = Record.values(documentTypesTable).flat();
 
 /**
- * @description Validates the value part of a PEPPOL document type identifier (the portion after the scheme prefix) against the known document type table.
- *
- * @param error - The error message to use when validation fails. Defaults to `'invalid Peppol document type value'`.
- *
- * @returns An Effect schema that accepts only valid document type values.
+ * @description The value part of a PEPPOL document type identifier (the portion after the scheme prefix) from the known document type table.
  *
  * @see {@link documentTypesTable}
  */
-export const documentTypeValuesSchema = Schema.String.check(Schema.makeFilter((val: string) => values.includes(val as never)));
+export class PeppolDocumentTypeValue extends opaque<PeppolDocumentTypeValue>()(
+  Schema.String.check(Schema.makeFilter((val: string) => values.includes(val as never)))
+) {}

package/src/schemas/values/duty-tax-fee-category-schema.ts

@@ -1,25 +1,27 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { dutyTaxFeeCategoriesKeys } from '#/values/duty-tax-fee-categories.generated';
 
 /**
- * @description A duty, tax or fee category code as defined by the PEPPOL subset of UNCL 5305 (VAT category code).
+ * @description A duty, tax or fee category code from the PEPPOL subset of UNCL 5305 (VAT category code).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5305/
- */
-export type PeppolDutyTaxFeeCategoryCode = typeof peppolDutyTaxFeeCategorySchema.Type;
-export type PeppolDutyTaxFeeCategoryCodeEncoded = typeof peppolDutyTaxFeeCategorySchema.Encoded;
-
-/**
- * @description Validates a duty, tax or fee category code against the PEPPOL subset of UNCL 5305 (VAT category code).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid duty/tax/fee category codes.
+ * @example
+ *   ```ts
+ *   'AE';
+ *   ```;
  *
  * @validations
  * - BR-CL-17 / BR-CL-18: VAT category code MUST be a valid UNCL 5305 code.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5305/
+ * @see {@link dutyTaxFeeCategoriesKeys}
+ */
+export class PeppolDutyTaxFeeCategoryCode extends opaque<PeppolDutyTaxFeeCategoryCode>()(
+  Schema.Literals(dutyTaxFeeCategoriesKeys).pipe(Schema.brand('PeppolDutyTaxFeeCategoryCode'))
+) {}
+
+/**
+ * @description The encoded form of {@link PeppolDutyTaxFeeCategoryCode}, a string literal union.
  */
-export const peppolDutyTaxFeeCategorySchema = Schema.Literals(dutyTaxFeeCategoriesKeys).pipe(Schema.brand('PeppolDutyTaxFeeCategoryCode'));
+export type PeppolDutyTaxFeeCategoryCodeEncoded = Schema.Codec.Encoded<typeof PeppolDutyTaxFeeCategoryCode>;

package/src/schemas/values/electronic-codes-schema.ts

@@ -7,25 +7,23 @@
  */
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { electronicAddressCodesKeys } from '#/values/eas-codes.generated';
 
 /**
- * @description An electronic address scheme (EAS) code, identifying the scheme of an electronic address (e.g. `0088` for GLN).
+ * @description An electronic address scheme (EAS) code from the PEPPOL Electronic Address Identifier Scheme codelist.
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
- */
-export type PeppolElectronicAddressCode = typeof electronicCodesSchema.Type;
-
-/**
- * @description Validates an electronic address scheme (EAS) code against the PEPPOL Electronic Address Identifier Scheme codelist.
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid electronic address scheme codes.
+ * @example
+ *   ```ts
+ *   '0002';
+ *   ```;
  *
  * @validations
  * - PEPPOL-EN16931-CL008: Electronic address identifier scheme MUST be from the codelist "Electronic Address Identifier Scheme".
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/
+ * @see {@link electronicAddressCodesKeys}
  */
-export const electronicCodesSchema = Schema.Literals(electronicAddressCodesKeys).pipe(Schema.brand('PeppolElectronicAddressCode'));
+export class PeppolElectronicAddressCode extends opaque<PeppolElectronicAddressCode>()(
+  Schema.Literals(electronicAddressCodesKeys).pipe(Schema.brand('PeppolElectronicAddressCode'))
+) {}

package/src/schemas/values/icd-codes-schema.ts

@@ -1,24 +1,20 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { icdCodesKeys } from '#/values/icd-codes.generated';
 
 /**
- * @description An ISO 6523 ICD (International Code Designator) code identifying an identifier scheme.
+ * @description An ISO 6523 ICD code from the PEPPOL codelist.
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/
- */
-export type PeppolIcdCode = typeof icdCodesSchema.Type;
-
-/**
- * @description Validates an ISO 6523 ICD code against the PEPPOL codelist.
- *
- * @param error - The custom error message to use when validation fails. Defaults to `'Invalid ICD code provided'`.
- *
- * @returns An Effect schema that accepts only valid ICD codes.
+ * @example
+ *   ```ts
+ *   '0002';
+ *   ```;
  *
  * @validations
  * - BR-CL-10 / BR-CL-11 / BR-CL-21: Identifier scheme MUST be a valid ISO 6523 ICD code.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/
+ * @see {@link icdCodesKeys}
  */
-export const icdCodesSchema = Schema.Literals(icdCodesKeys).pipe(Schema.brand('PeppolIcdCode'));
+export class PeppolIcdCode extends opaque<PeppolIcdCode>()(Schema.Literals(icdCodesKeys).pipe(Schema.brand('PeppolIcdCode'))) {}

package/src/schemas/values/invoice-status-code-schema.ts

@@ -1,21 +1,19 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { invoiceStatusCodesKeys } from '#/values/invoice-status-codes.generated';
 
 /**
- * @description An invoice status code as defined by the PEPPOL subset of UNCL 4343 (T111).
+ * @description An invoice status code from the PEPPOL subset of UNCL 4343 (T111).
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343-T111/
- */
-export type PeppolInvoiceStatusCodes = typeof invoiceStatusCodeSchema.Type;
-
-/**
- * @description Validates an invoice status code against the PEPPOL subset of UNCL 4343 (T111).
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid invoice status codes.
+ * @example
+ *   ```ts
+ *   'AB';
+ *   ```;
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL4343-T111/
+ * @see {@link invoiceStatusCodesKeys}
  */
-export const invoiceStatusCodeSchema = Schema.Literals(invoiceStatusCodesKeys).pipe(Schema.brand('PeppolInvoiceStatusCodes'));
+export class PeppolInvoiceStatusCodes extends opaque<PeppolInvoiceStatusCodes>()(
+  Schema.Literals(invoiceStatusCodesKeys).pipe(Schema.brand('PeppolInvoiceStatusCodes'))
+) {}