@fin.cx/compatibility 5.2.0 → 5.3.0

package/ts/error.ts

@@ -14,7 +14,7 @@
  *   centres its record does not state (stored before 4.1) and no rows sent were given; the message names it;
  * - `invalid_buchungsliste`: a Buchungsliste that cannot be read or booked as it is: no header line, a required
  *   column missing, a field that is not of its format, a field this version does not map, or a row that gives no
- *   valid entry; `details` names the line, the row and the field where it can.
+ *   valid entry; `details` names why (`reason`), the line, the row and the field where it can.
  */
 export type TCompatibilityErrorCode =
   | 'invalid_bookings'
@@ -25,8 +25,35 @@ export type TCompatibilityErrorCode =
   | 'handed_over_cost_centres_unknown'
   | 'invalid_buchungsliste';
 
+/**
+ * Why a Buchungsliste was refused (`invalid_buchungsliste`), so a consumer can tell its user without reading the
+ * message:
+ * - `unreadable`: the text is no list of rows of the first line's fields: a byte order mark of UTF-8, no first line,
+ *   no delimiter, a quote never closed or text after a closing quote, a required column missing or two columns of
+ *   one field, a row of another number of fields;
+ * - `field_malformed`: a field not of its format (a day, an amount or 0, an account, a Buchungsperiode), or no
+ *   Belegdatum;
+ * - `field_unmapped`: a row that states Zusatzangaben, an EU Land or an EU %, which this version does not map;
+ * - `currency_unsupported`: a Währung other than EUR;
+ * - `bu_key_unknown`: a Steuerschlüssel `@fin.cx/skr` does not know;
+ * - `tax_account_unclear`: a row with a tax where the account it is computed on cannot be told (skr's
+ *   `extf_tax_account_unclear`);
+ * - `row_invalid`: a row whose entry skr refuses otherwise; where its check (`validateJournalDraft`) refused it, what
+ *   the check found in `details.errors`.
+ */
+export type TBuchungslisteRefusalReason =
+  | 'unreadable'
+  | 'field_malformed'
+  | 'field_unmapped'
+  | 'currency_unsupported'
+  | 'bu_key_unknown'
+  | 'tax_account_unclear'
+  | 'row_invalid';
+
 /** Where a refusal of a file read stands, as far as it is known; empty for a file written. */
 export interface ICompatibilityErrorDetails {
+  /** why a Buchungsliste was refused; stated on every `invalid_buchungsliste` */
+  reason?: TBuchungslisteRefusalReason;
   /** the data row, from 1 */
   row?: number;
   /** the line of the file, from 1 */

package/ts/extf/index.ts

@@ -36,8 +36,9 @@ export interface IExportBooking {
   kost1?: string;
   kost2?: string;
   /**
-   * The row is a general reversal (field 118 "Generalumkehr", written "1"): it takes back the booking of the same
-   * fields on DATEV's side. Absent on an ordinary row.
+   * The row is a general reversal (field 118 "Generalumkehr", written "1"): DATEV books it on the other side, so it
+   * takes back a booking of the same fields, and one that mirrors none (a Storno posted on a later day) stands as the
+   * counter-booking on its own day. Absent on an ordinary row.
    */
   generalumkehr?: true;
 }
@@ -470,6 +471,65 @@ const bookingNameOf = (bookingArg: IExportBooking, indexArg: number): string =>
   `booking ${indexArg + 1} (${bookingArg.date}, ${bookingArg.umsatzCents} ${bookingArg.sollHaben} ${bookingArg.konto}/${bookingArg.gegenkonto}`
   + `${bookingArg.belegfeld1 ? `, Belegfeld 1 ${bookingArg.belegfeld1}` : ''})`;
 
+/** The booking that takes a booking back on DATEV's side: what it says, its general reversal (field 118) turned over. */
+const mirrorOf = (bookingArg: IExportBooking): IExportBooking => {
+  const { generalumkehr, ...fields } = bookingArg;
+  return generalumkehr ? fields : { ...fields, generalumkehr: true };
+};
+
+/**
+ * The indexes of the bookings that stand on DATEV's side after all of them, handed over in their order and compared as
+ * a file states them (`comparableOf`), in their order. A booking that mirrors one standing before it (`mirrorOf`: it
+ * says what it says, `differingBookingCount`'s fields, the general reversal turned over) takes it back, and neither
+ * stands: a general reversal takes back the booking it mirrors, and an ordinary row the general reversal it mirrors. A
+ * booking that mirrors none stands, a general reversal too: DATEV books it as the counter-booking on its own day. Of the
+ * bookings a booking mirrors, one on the cost centres it states is taken first, then one stored before 4.1, which records
+ * none; of several, the last. Linear in their number.
+ */
+const standingIndexesOf = (comparableArg: readonly IExportBooking[]): number[] => {
+  const standing = comparableArg.map(() => true);
+  // the bookings that stand, by what they say: recorded ones on every key field and on the rest, unrecorded ones on the rest
+  const recordedByFullKey = new Map<string, number[]>();
+  const recordedByBaseKey = new Map<string, number[]>();
+  const unrecordedByBaseKey = new Map<string, number[]>();
+  const stand = (queuesArg: Map<string, number[]>, keyArg: string, indexArg: number): void => {
+    const queue = queuesArg.get(keyArg);
+    if (queue) {
+      queue.push(indexArg);
+    } else {
+      queuesArg.set(keyArg, [indexArg]);
+    }
+  };
+  // the last booking of a queue that still stands; a booking taken back through another queue is passed over for good
+  const lastStanding = (queuesArg: Map<string, number[]>, keyArg: string): number | undefined => {
+    const queue = queuesArg.get(keyArg);
+    while (queue && queue.length > 0 && !standing[queue[queue.length - 1]]) {
+      queue.pop();
+    }
+    return queue?.[queue.length - 1];
+  };
+  comparableArg.forEach((bookingArg, indexArg) => {
+    const mirrored = mirrorOf(bookingArg);
+    const baseKey = baseKeyOf(mirrored);
+    const unrecorded = lastStanding(unrecordedByBaseKey, baseKey);
+    const taken = recordsCostCentres(mirrored)
+      ? lastStanding(recordedByFullKey, fullKeyOf(mirrored)) ?? unrecorded
+      : Math.max(lastStanding(recordedByBaseKey, baseKey) ?? -1, unrecorded ?? -1);
+    if (taken !== undefined && taken >= 0) {
+      standing[taken] = false;
+      standing[indexArg] = false;
+      return;
+    }
+    if (recordsCostCentres(bookingArg)) {
+      stand(recordedByFullKey, fullKeyOf(bookingArg), indexArg);
+      stand(recordedByBaseKey, baseKeyOf(bookingArg), indexArg);
+    } else {
+      stand(unrecordedByBaseKey, baseKeyOf(bookingArg), indexArg);
+    }
+  });
+  return comparableArg.flatMap((_bookingArg, indexArg) => (standing[indexArg] ? [indexArg] : []));
+};
+
 /**
  * Refuses a state handed over that holds a booking whose cost centres its record does not state (stored before 4.1).
  * The Stapel sent stated them (fields 37 and 38), so DATEV holds them: whether the booking must be taken back turns on
@@ -491,7 +551,10 @@ const refuseCostCentresUnknown = (handedOverArg: readonly IExportBooking[]): voi
  * handed over that the current ones no longer hold (`reversed`, each once for each time it is missing), the ones they
  * still hold (`kept`, as they were handed over) and the current rows the bookings handed over do not hold (`added`),
  * each in its order. A booking that stands in both is kept: a changed text or document link is no changed booking,
- * a changed cost centre is. The current rows are compared as a file states them (`bookingsAsWritten`), as the
+ * a changed cost centre is. Each side is compared as what stands of it (`bookingsHeldOf`): a general reversal and the
+ * booking before it that it mirrors take each other back, among the bookings handed over and among the current rows (a
+ * Storno on the day of the booking it takes back), and a general reversal that mirrors none (a Storno posted on a later
+ * day) is a booking as any other. The current rows are compared as a file states them (`bookingsAsWritten`), as the
  * bookings handed over are; `added` are the rows themselves, which the writer writes. A booking handed over whose
  * cost centres its record does not state (stored before 4.1) is refused (`handed_over_cost_centres_unknown`): pass
  * `bookingsOfRows` of the rows sent instead.
@@ -502,18 +565,23 @@ export const correctionOf = (
 ): { reversed: IExportBooking[]; kept: IExportBooking[]; added: IDatevBuchungsstapelRow[] } => {
   refuseCostCentresUnknown(handedOverArg);
   // the current rows as a file states them, as the state handed over was: a reference the writer changes is the same
-  const { leftPaired, rightPaired } = pairBookings(comparableOf(handedOverArg), bookingsAsWritten(currentArg));
+  const handedOver = comparableOf(handedOverArg);
+  const current = bookingsAsWritten(currentArg);
+  // what stands of each
+  const held = standingIndexesOf(handedOver);
+  const standing = standingIndexesOf(current);
+  const { leftPaired, rightPaired } = pairBookings(held.map((indexArg) => handedOver[indexArg]), standing.map((indexArg) => current[indexArg]));
   return {
-    reversed: handedOverArg.filter((_bookingArg, indexArg) => !leftPaired[indexArg]),
-    kept: handedOverArg.filter((_bookingArg, indexArg) => leftPaired[indexArg]),
-    added: currentArg.filter((_rowArg, indexArg) => !rightPaired[indexArg]),
+    reversed: held.filter((_indexArg, positionArg) => !leftPaired[positionArg]).map((indexArg) => handedOverArg[indexArg]),
+    kept: held.filter((_indexArg, positionArg) => leftPaired[positionArg]).map((indexArg) => handedOverArg[indexArg]),
+    added: standing.filter((_indexArg, positionArg) => !rightPaired[positionArg]).map((indexArg) => currentArg[indexArg]),
   };
 };
 
 /**
  * The state of a period handed over, given once: the bookings stored of it (`handedOver`) or the rows of the Stapel
- * sent (`handedOverRows`). A general reversal in it is refused: the state handed over is compared, not a correction
- * file.
+ * sent (`handedOverRows`). What stands of it is compared (`bookingsHeldOf`): a general reversal in it takes back the
+ * booking before it that it mirrors, and one that mirrors none (a Storno posted on a later day) stands.
  */
 export interface ICorrectionBuchungsstapelOptions {
   /**
@@ -544,7 +612,10 @@ export interface ICorrectionBuchungsstapelOptions {
 }
 
 export interface ICorrectionBuchungsstapelFile extends IBuchungsstapelFile {
-  /** the bookings handed over it takes back, each written as a general reversal */
+  /**
+   * The bookings handed over it takes back, each written as the row that mirrors it: an ordinary booking with field
+   * 118 "Generalumkehr" set, a general reversal that stands as the ordinary row.
+   */
   reversed: IExportBooking[];
   /** the rows it books anew */
   added: IDatevBuchungsstapelRow[];
@@ -559,11 +630,12 @@ export interface ICorrectionBuchungsstapelFile extends IBuchungsstapelFile {
 /**
  * Writes the correction Buchungsstapel of a period handed over whose bookings changed since: only what changed. Each
  * booking handed over that the drafts no longer hold is written again with field 118 "Generalumkehr" set, so DATEV
- * takes it back on its side and day, and each row the drafts hold that was not handed over is written as it is; rows
- * in both are not written. Every row keeps its Belegdatum, so it counts in the period it belongs to. A booking handed
- * over is never changed or replaced (§ 146 Abs. 4 AO): it is taken back and booked anew. Throws `nothing_to_correct`
- * when nothing changed; `invalid_bookings` for a general reversal in the state handed over, or for a state given
- * twice or not at all; `handed_over_cost_centres_unknown` for a booking whose cost centres are not known.
+ * takes it back on its side and day (a general reversal handed over that stands, as the ordinary row), and each row
+ * the drafts hold that was not handed over is written as it is; rows in both are not written. Both are compared as
+ * what stands of them (`correctionOf`). Every row keeps its Belegdatum, so it counts in the period it belongs to. A
+ * booking handed over is never changed or replaced (§ 146 Abs. 4 AO): it is taken back and booked anew. Throws
+ * `nothing_to_correct` when nothing changed; `invalid_bookings` for a state given twice or not at all;
+ * `handed_over_cost_centres_unknown` for a booking whose cost centres are not known.
  */
 export const writeCorrectionBuchungsstapel = (optionsArg: ICorrectionBuchungsstapelOptions): ICorrectionBuchungsstapelFile => {
   // rows read back from the file sent are as written already; rows given to the writer become what it wrote
@@ -571,16 +643,12 @@ export const writeCorrectionBuchungsstapel = (optionsArg: ICorrectionBuchungssta
   if (handedOver === undefined || (optionsArg.handedOver !== undefined && optionsArg.handedOverRows !== undefined)) {
     throw new CompatibilityError('invalid_bookings', 'pass the state handed over once: the bookings stored (handedOver) or the rows sent (handedOverRows)');
   }
-  const reversal = handedOver.findIndex((bookingArg) => bookingArg.generalumkehr === true);
-  if (reversal >= 0) {
-    throw new CompatibilityError('invalid_bookings', `the state handed over holds a general reversal (booking ${reversal + 1}); pass the period's bookings as they stood, not a correction file`);
-  }
   const current = datevRowsOf(optionsArg.drafts, optionsArg.policy);
   const { reversed, kept, added } = correctionOf(handedOver, current);
   if (reversed.length === 0 && added.length === 0) {
     throw new CompatibilityError('nothing_to_correct', 'the bookings of the period are the ones handed over; there is nothing to correct');
   }
-  const rows = [...reversed.map((bookingArg) => ({ ...rowOfBooking(bookingArg), generalumkehr: true })), ...added];
+  const rows = [...reversed.map((bookingArg) => rowOfBooking(mirrorOf(bookingArg))), ...added];
   const file = fileOfRows(rows, optionsArg.header, optionsArg.filename);
   // the rows booked anew as the correction file states them, after the reversals
   return { ...file, reversed, added, bookingsAfter: [...kept, ...file.bookings.slice(reversed.length)] };
@@ -590,64 +658,19 @@ export const writeCorrectionBuchungsstapel = (optionsArg: ICorrectionBuchungssta
  * The bookings of a period as DATEV holds them after its Stapel, handed over in the order given: the period's
  * Buchungsstapel, the additional Stapel after it and its correction Stapel (`writeCorrectionBuchungsstapel`), each as
  * the bookings it stated (`IBuchungsstapelFile.bookings` as stored, or `bookingsOfRows` of its file read back), in
- * their order. An ordinary booking stands. A general reversal (field 118 "Generalumkehr") takes back one booking that
- * stands before it, in an earlier Stapel or earlier in its own, and does not stand itself: the booking it mirrors says
- * what it says (`differingBookingCount`'s fields, the reversal apart), compared as a file states them
- * (`comparableOf`), so wording and document link do not count. A booking on the cost centres the reversal states is
- * taken first, then one stored before 4.1, which records none; of several, the last, as a correction reverses the
- * last of several bookings it no longer holds. A reversal of no booking that stands before it is refused
- * (`invalid_bookings`, naming its Stapel and place): DATEV would hold a counter-booking of nothing. The bookings that
- * stand, as they were given and in their order: what the next correction is compared against (`handedOver`), and
- * after one correction its `bookingsAfter`. A booking a Buchungsstapel cannot hold is refused (`invalid_bookings`).
+ * their order. A booking that mirrors one standing before it, in an earlier Stapel or earlier in its own, takes it
+ * back, and neither stands: the booking it mirrors says what it says (`differingBookingCount`'s fields), compared as a
+ * file states them (`comparableOf`), so wording and document link do not count, and is a general reversal (field 118
+ * "Generalumkehr") where it is not. A general reversal takes back the booking it mirrors, and an ordinary row the general
+ * reversal it mirrors, as a correction takes back a general reversal that stands. A booking that mirrors none stands,
+ * a general reversal too: DATEV books it as the counter-booking on its own day, as it books a Storno posted on a later
+ * day than the booking it takes back, or in a later period. A booking on the cost centres the reversal states is taken
+ * first, then one stored before 4.1, which records none; of several, the last, as a correction reverses the last of
+ * several bookings it no longer holds. The bookings that stand, as they were given and in their order: what the next
+ * correction is compared against (`handedOver`), and after one correction its `bookingsAfter`. A booking a
+ * Buchungsstapel cannot hold is refused (`invalid_bookings`).
  */
 export const bookingsHeldOf = (stapelArg: readonly (readonly IExportBooking[])[]): IExportBooking[] => {
   const given = stapelArg.flat();
-  const comparable = comparableOf(given);
-  // where each booking stands: its Stapel and its place in it, for a refusal
-  const places = stapelArg.flatMap((stapelBookingsArg, stapelIndexArg) => stapelBookingsArg.map((_bookingArg, indexArg) => ({ stapel: stapelIndexArg, index: indexArg })));
-  const takenBack = given.map(() => false);
-  // the bookings that stand, by what they say: recorded ones on every key field and on the rest, unrecorded ones on the rest
-  const recordedByFullKey = new Map<string, number[]>();
-  const recordedByBaseKey = new Map<string, number[]>();
-  const unrecordedByBaseKey = new Map<string, number[]>();
-  const stand = (queuesArg: Map<string, number[]>, keyArg: string, indexArg: number): void => {
-    const queue = queuesArg.get(keyArg);
-    if (queue) {
-      queue.push(indexArg);
-    } else {
-      queuesArg.set(keyArg, [indexArg]);
-    }
-  };
-  // the last booking of a queue that still stands; a booking taken back through another queue is passed over for good
-  const lastStanding = (queuesArg: Map<string, number[]>, keyArg: string): number | undefined => {
-    const queue = queuesArg.get(keyArg);
-    while (queue && queue.length > 0 && takenBack[queue[queue.length - 1]]) {
-      queue.pop();
-    }
-    return queue?.[queue.length - 1];
-  };
-  comparable.forEach((bookingArg, indexArg) => {
-    if (!bookingArg.generalumkehr) {
-      if (recordsCostCentres(bookingArg)) {
-        stand(recordedByFullKey, fullKeyOf(bookingArg), indexArg);
-        stand(recordedByBaseKey, baseKeyOf(bookingArg), indexArg);
-      } else {
-        stand(unrecordedByBaseKey, baseKeyOf(bookingArg), indexArg);
-      }
-      return;
-    }
-    // the booking the reversal mirrors says what it says
-    const { generalumkehr: _generalumkehr, ...mirrored } = bookingArg;
-    const baseKey = baseKeyOf(mirrored);
-    const unrecorded = lastStanding(unrecordedByBaseKey, baseKey);
-    const taken = recordsCostCentres(mirrored)
-      ? lastStanding(recordedByFullKey, fullKeyOf(mirrored)) ?? unrecorded
-      : Math.max(lastStanding(recordedByBaseKey, baseKey) ?? -1, unrecorded ?? -1);
-    if (taken === undefined || taken < 0) {
-      const { stapel, index } = places[indexArg];
-      throw new CompatibilityError('invalid_bookings', `Stapel ${stapel + 1}, ${bookingNameOf(given[indexArg], index)} is a general reversal of no booking handed over before it`);
-    }
-    takenBack[taken] = true;
-  });
-  return given.filter((_bookingArg, indexArg) => !comparable[indexArg].generalumkehr && !takenBack[indexArg]);
+  return standingIndexesOf(comparableOf(given)).map((indexArg) => given[indexArg]);
 };