@endevops/peppol-schema 0.1.3 → 0.1.5

package/src/schemas/values/peppol-process-schema.ts

@@ -2,29 +2,33 @@ import { Schema } from 'effect';
 
 import type { ProcessesKeys } from '#/values/processes.generated';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { processes, processesKeys } from '#/values/processes.generated';
 
 /**
- * @description A PEPPOL business process identifier key as defined by the processes codelist.
+ * @description A full PEPPOL business process identifier in `<scheme>::<value>` form from the known processes table.
+ *
+ * @example
+ *   ```ts
+ *   'cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0';
+ *   ```;
  *
  * @see {@link processes}
  */
-export type PeppolProcesses = typeof peppolProcessSchema.Encoded;
+export class PeppolProcess extends opaque<PeppolProcess>()(
+  Schema.TemplateLiteral([Schema.Literals(processesKeys), Schema.Literal('::'), Schema.String]).check(
+    Schema.makeFilter((val: string) => {
+      const [prefix, suffix] = val.split('::');
+      if (prefix === undefined || suffix === undefined) return false;
+      const info = processes[prefix as ProcessesKeys];
+      return info !== undefined && info.some(v => v === suffix);
+    })
+  )
+) {}
 
 /**
- * @description Validates a full PEPPOL business process identifier (`<scheme>::<value>`) against the known processes.
- *
- * @param error - The custom error message to use when validation fails. Defaults to `'invalid peppol process identifier'`.
- *
- * @returns An Effect schema that matches a valid `scheme::value` process identifier.
+ * @description A PEPPOL business process identifier key as defined by the processes codelist.
  *
  * @see {@link processes}
  */
-export const peppolProcessSchema = Schema.TemplateLiteral([Schema.Literals(processesKeys), Schema.Literal('::'), Schema.String]).check(
-  Schema.makeFilter((val: string) => {
-    const [prefix, suffix] = val.split('::');
-    if (prefix === undefined || suffix === undefined) return false;
-    const info = processes[prefix as ProcessesKeys];
-    return info !== undefined && info.some(v => v === suffix);
-  })
-);
+export type PeppolProcesses = Schema.Codec.Encoded<typeof PeppolProcess>;

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

@@ -2,7 +2,7 @@ import { Schema } from 'effect';
 
 import type { PeppolDocumentType } from '#/schemas/values/peppol-document-type-schema.ts';
 
-import { peppolProcessSchema } from '#/schemas/values/peppol-process-schema.ts';
+import { PeppolProcess } from '#/schemas/values/peppol-process-schema.ts';
 import { documentTypesProcessIds } from '#/values/document-type.generated';
 
 /**
@@ -13,13 +13,13 @@ import { documentTypesProcessIds } from '#/values/document-type.generated';
  *
  * @returns An Effect schema that matches only processes allowed for the given document type.
  *
- * @see {@link peppolProcessSchema}
+ * @see {@link PeppolProcess}
  * @see {@link documentTypesProcessIds}
  */
 export function processFromDocumentTypeSchema(documentType: PeppolDocumentType, error = 'invalid process type for document type') {
   const allowed = documentTypesProcessIds[documentType as keyof typeof documentTypesProcessIds];
   if (allowed === undefined) {
-    return peppolProcessSchema;
+    return PeppolProcess;
   }
   const values = allowed.map(p => `${p.scheme}::${p.value}`);
   return Schema.String.check(Schema.makeFilter((val: string) => values.includes(val as never))).annotate({ message: error });

package/src/schemas/values/quantity-unit-codes-schema.ts

@@ -1,24 +1,22 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { quantityUnitCodesKeys } from '#/values/quantity-unit-codes.generated';
 
 /**
- * @description A unit of measure code as defined by the PEPPOL subset of UN/ECE Recommendation 20.
+ * @description A unit of measure code from the PEPPOL subset of UN/ECE Recommendation 20.
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/
- */
-export type PeppolQuantityUnitCode = typeof quantityUnitCodesSchema.Type;
-
-/**
- * @description Validates a unit of measure code against the PEPPOL subset of UN/ECE Recommendation 20.
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid quantity unit codes.
+ * @example
+ *   ```ts
+ *   '10';
+ *   ```;
  *
  * @validations
  * - BR-CL-23: Unit of measure code MUST be a valid UN/ECE Rec 20 code.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/
+ * @see {@link quantityUnitCodesKeys}
  */
-export const quantityUnitCodesSchema = Schema.Literals(quantityUnitCodesKeys).pipe(Schema.brand('PeppolQuantityUnitCode'));
+export class PeppolQuantityUnitCode extends opaque<PeppolQuantityUnitCode>()(
+  Schema.Literals(quantityUnitCodesKeys).pipe(Schema.brand('PeppolQuantityUnitCode'))
+) {}

package/src/schemas/values/vat-date-code-schema.ts

@@ -1,13 +1,20 @@
 import { Schema } from 'effect';
 
-import type { VatDateCodesKeys } from '#/values/vat-dates.generated';
-
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { vatDateCodesKeys } from '#/values/vat-dates.generated';
 
-export type PeppolVatDateCode = VatDateCodesKeys;
-
 /**
+ * @description A VAT date code from the PEPPOL subset of UNCL 2005 (invoice period description code).
+ *
+ * @example
+ *   ```ts
+ *   '3';
+ *   ```;
+ *
  * @validations
  * - PEPPOL-EN16931-CL006: Invoice period description code must be according to UNCL 2005 D.16B.
+ *
+ * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL2005/
+ * @see {@link vatDateCodesKeys}
  */
-export const vatDateCodeSchema = Schema.Literals(vatDateCodesKeys);
+export class PeppolVatDateCode extends opaque<PeppolVatDateCode>()(Schema.Literals(vatDateCodesKeys)) {}

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

@@ -1,24 +1,20 @@
 import { Schema } from 'effect';
 
+import { opaque } from '#/schemas/utils/opaque.ts';
 import { vatexCodesKeys } from '#/values/vatex-codes.generated';
 
 /**
- * @description A VAT exemption reason code as defined by the CEF VATEX codelist.
+ * @description A VAT exemption reason code from the CEF VATEX codelist.
  *
- * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/
- */
-export type PeppolVatexCode = typeof vatexCodeSchema.Type;
-
-/**
- * @description Validates a VAT exemption reason code against the CEF VATEX codelist.
- *
- * @param error - The custom error message to use when validation fails.
- *
- * @returns An Effect schema that accepts only valid VAT exemption reason codes.
+ * @example
+ *   ```ts
+ *   'VATEX-EU-79-C';
+ *   ```;
  *
  * @validations
  * - BR-CL-22: VAT exemption reason code MUST be a valid CEF VATEX code.
  *
  * @see https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/
+ * @see {@link vatexCodesKeys}
  */
-export const vatexCodeSchema = Schema.Literals(vatexCodesKeys).pipe(Schema.brand('PeppolVatexCode'));
+export class PeppolVatexCode extends opaque<PeppolVatexCode>()(Schema.Literals(vatexCodesKeys).pipe(Schema.brand('PeppolVatexCode'))) {}

package/src/schematron/errors.ts

@@ -2,6 +2,13 @@ import { Schema } from 'effect';
 
 /**
  * @description Failure of a single schematron rule against a document.
+ *
+ * @example
+ *   ```ts
+ *   new SchematronRuleError({ id: 'PEPPOL-EN16931-R001', level: 'fatal', message: 'The document must carry a number.' });
+ *   ```;
+ *
+ * @see {@link SchematronValidationError}
  */
 export class SchematronRuleError extends Schema.TaggedError<SchematronRuleError>()('SchematronRuleError', {
   id: Schema.String,
@@ -11,6 +18,13 @@ export class SchematronRuleError extends Schema.TaggedError<SchematronRuleError>
 
 /**
  * @description Failure of a schematron validation run, wrapping every rule that failed.
+ *
+ * @example
+ *   ```ts
+ *   new SchematronValidationError({ errors: [ruleError] });
+ *   ```;
+ *
+ * @see {@link SchematronRuleError}
  */
 export class SchematronValidationError extends Schema.TaggedError<SchematronValidationError>()('SchematronValidationError', {
   errors: Schema.Array(SchematronRuleError),