@fin.cx/mt940 2.0.0 → 2.1.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@fin.cx/mt940',
-    version: '2.0.0',
+    version: '2.1.0',
     description: 'A parser to process and extract statements from MT940 format files, commonly used by banks for electronic account statements.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxlQUFlO0lBQ3JCLE9BQU8sRUFBRSxPQUFPO0lBQ2hCLFdBQVcsRUFBRSwrSEFBK0g7Q0FDN0ksQ0FBQSJ9

package/dist_ts/index.d.ts

@@ -1,5 +1,21 @@
 import * as plugins from './mt940parser.plugins.js';
+/** The encoding an MT940 file is read in: UTF-8 where its bytes are valid UTF-8, else Windows-1252. */
+export type TMt940Encoding = 'utf-8' | 'windows-1252';
 export declare class Mt940Parser {
+    /**
+     * Parses MT940 file content given as text. Its characters are read as they
+     * are, whatever encoding the file was in before it became text.
+     */
     parseMt940FileString(fileStringArg: string): Promise<plugins.mt940Js.Statement[]>;
+    /**
+     * Parses the bytes of an MT940 file: UTF-8 where they are valid UTF-8 (a
+     * byte order mark is not part of the text), else Windows-1252, the
+     * encoding German banks write MT940 in. Every field is decoded from its own
+     * bytes, by the Encoding Standard's table for Windows-1252 on every
+     * runtime (`@push.rocks/smartstring`).
+     */
+    parseMt940FileBytes(fileBytesArg: Uint8Array): Promise<plugins.mt940Js.Statement[]>;
+    /** Parses the bytes of an MT940 file in an `ArrayBufferLike`, as `parseMt940FileBytes` does. */
     parseMt940Buffer(fileBufferArg: ArrayBufferLike): Promise<plugins.mt940Js.Statement[]>;
+    private parseBytesIn;
 }

package/dist_ts/index.js

@@ -1,15 +1,132 @@
 import * as plugins from './mt940parser.plugins.js';
+const UTF8_BYTE_ORDER_MARK = [0xef, 0xbb, 0xbf];
+const startsWithUtf8ByteOrderMark = (bytesArg) => UTF8_BYTE_ORDER_MARK.every((byteArg, indexArg) => bytesArg[indexArg] === byteArg);
+/** The byte of the no-break space in Windows-1252, and of a UTF-8 continuation byte a character may end in (à is C3 A0). */
+const NO_BREAK_SPACE_BYTE = 0xa0;
+/**
+ * The bytes a field of mt940-js holds. mt940-js reads its input one byte as
+ * one character (`String.fromCharCode` of each byte), so each code unit of a
+ * field it answers is one byte of the file.
+ */
+const bytesOfField = (fieldArg) => {
+    const bytes = new Uint8Array(fieldArg.length);
+    for (let index = 0; index < fieldArg.length; index++) {
+        const codeUnit = fieldArg.charCodeAt(index);
+        if (codeUnit > 0xff) {
+            throw new Error(`mt940-js answered a character that is no byte (U+${codeUnit.toString(16)})`);
+        }
+        bytes[index] = codeUnit;
+    }
+    return bytes;
+};
+/** How many continuation bytes the UTF-8 sequence at the end of `bytesArg` still lacks (0 when it is complete). */
+const missingContinuationBytes = (bytesArg) => {
+    for (let back = 1; back <= Math.min(3, bytesArg.length); back++) {
+        const byte = bytesArg[bytesArg.length - back];
+        if (byte < 0x80) {
+            return 0;
+        }
+        if (byte >= 0xc0) {
+            const length = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : 2;
+            return Math.max(0, length - back);
+        }
+    }
+    return 0;
+};
+const decodeField = (bytesArg, encodingArg) => encodingArg === 'utf-8' ? new TextDecoder('utf-8').decode(bytesArg) : plugins.smartstring.encoding.decodeWindows1252(bytesArg);
+/**
+ * A text of an :86: field, which mt940-js trims as it reads it byte by byte:
+ * JavaScript's `trim` takes a no-break space (0xA0) off its end, and in a
+ * file of UTF-8 0xA0 is also the last byte of characters (à is C3 A0, Š C5
+ * A0, † E2 80 A0). No other byte from 0x80 up is whitespace to `trim`, so the
+ * bytes the sequence at the end lacks were each 0xA0 and are put back; what
+ * was trimmed after that character was whitespace.
+ */
+const decodeTrimmedField = (fieldArg, encodingArg) => {
+    const bytes = bytesOfField(fieldArg);
+    if (encodingArg !== 'utf-8') {
+        return decodeField(bytes, encodingArg);
+    }
+    const missing = missingContinuationBytes(bytes);
+    if (missing === 0) {
+        return decodeField(bytes, encodingArg);
+    }
+    const completed = new Uint8Array(bytes.length + missing);
+    completed.set(bytes);
+    completed.fill(NO_BREAK_SPACE_BYTE, bytes.length);
+    return decodeField(completed, encodingArg);
+};
+/*
+ * mt940-js does not set every field its types name: a :61: line without a
+ * transaction code answers `code` undefined. A field that is no string is
+ * passed through as mt940-js answered it; a string is decoded from its bytes.
+ */
+/** A field of mt940-js in the file's encoding. */
+const decodeText = (valueArg, encodingArg) => typeof valueArg === 'string' ? decodeField(bytesOfField(valueArg), encodingArg) : valueArg;
+/** An :86: text of mt940-js in the file's encoding (`decodeTrimmedField`). */
+const decodeTrimmedText = (valueArg, encodingArg) => typeof valueArg === 'string' ? decodeTrimmedField(valueArg, encodingArg) : valueArg;
+const decodeBalance = (balanceArg, encodingArg) => ({
+    ...balanceArg,
+    date: decodeText(balanceArg.date, encodingArg),
+    currency: decodeText(balanceArg.currency, encodingArg),
+});
+/** A statement mt940-js read, with every text decoded from its bytes in the file's encoding. */
+const decodeStatement = (statementArg, encodingArg) => {
+    const text = (valueArg) => decodeText(valueArg, encodingArg);
+    const { referenceNumber, relatedReferenceNumber, accountId, number, additionalInformation, openingBalance, closingBalance, closingAvailableBalance, forwardAvailableBalance, } = statementArg;
+    return {
+        ...statementArg,
+        ...(referenceNumber !== undefined ? { referenceNumber: text(referenceNumber) } : {}),
+        ...(relatedReferenceNumber !== undefined ? { relatedReferenceNumber: text(relatedReferenceNumber) } : {}),
+        ...(accountId !== undefined ? { accountId: text(accountId) } : {}),
+        ...(number !== undefined ? { number: text(number) } : {}),
+        ...(additionalInformation !== undefined ? { additionalInformation: decodeTrimmedText(additionalInformation, encodingArg) } : {}),
+        ...(openingBalance ? { openingBalance: decodeBalance(openingBalance, encodingArg) } : {}),
+        ...(closingBalance ? { closingBalance: decodeBalance(closingBalance, encodingArg) } : {}),
+        ...(closingAvailableBalance ? { closingAvailableBalance: decodeBalance(closingAvailableBalance, encodingArg) } : {}),
+        ...(forwardAvailableBalance ? { forwardAvailableBalance: decodeBalance(forwardAvailableBalance, encodingArg) } : {}),
+        transactions: statementArg.transactions.map((transactionArg) => ({
+            ...transactionArg,
+            code: text(transactionArg.code),
+            fundsCode: text(transactionArg.fundsCode),
+            currency: text(transactionArg.currency),
+            description: decodeTrimmedText(transactionArg.description, encodingArg),
+            valueDate: text(transactionArg.valueDate),
+            entryDate: text(transactionArg.entryDate),
+            customerReference: text(transactionArg.customerReference),
+            bankReference: text(transactionArg.bankReference),
+        })),
+    };
+};
 export class Mt940Parser {
+    /**
+     * Parses MT940 file content given as text. Its characters are read as they
+     * are, whatever encoding the file was in before it became text.
+     */
     async parseMt940FileString(fileStringArg) {
-        const textEncode = new TextEncoder();
-        const statements = await this.parseMt940Buffer(textEncode.encode(fileStringArg).buffer);
-        return statements;
+        return this.parseBytesIn(new TextEncoder().encode(fileStringArg), 'utf-8');
     }
+    /**
+     * Parses the bytes of an MT940 file: UTF-8 where they are valid UTF-8 (a
+     * byte order mark is not part of the text), else Windows-1252, the
+     * encoding German banks write MT940 in. Every field is decoded from its own
+     * bytes, by the Encoding Standard's table for Windows-1252 on every
+     * runtime (`@push.rocks/smartstring`).
+     */
+    async parseMt940FileBytes(fileBytesArg) {
+        const encoding = plugins.smartstring.encoding.isValidUtf8(fileBytesArg) ? 'utf-8' : 'windows-1252';
+        return this.parseBytesIn(fileBytesArg, encoding);
+    }
+    /** Parses the bytes of an MT940 file in an `ArrayBufferLike`, as `parseMt940FileBytes` does. */
     async parseMt940Buffer(fileBufferArg) {
-        const fileBuffer = fileBufferArg instanceof ArrayBuffer
-            ? fileBufferArg
-            : new Uint8Array(fileBufferArg).slice().buffer;
-        const statements = await plugins.mt940Js.read(fileBuffer);
+        return this.parseMt940FileBytes(new Uint8Array(fileBufferArg));
+    }
+    async parseBytesIn(fileBytesArg, encodingArg) {
+        // a byte order mark is no text of the file, and mt940-js finds no statement behind one
+        const text = encodingArg === 'utf-8' && startsWithUtf8ByteOrderMark(fileBytesArg) ? fileBytesArg.subarray(UTF8_BYTE_ORDER_MARK.length) : fileBytesArg;
+        // mt940-js takes an ArrayBuffer of its own; it reads each byte as one character
+        const fileBuffer = text.slice().buffer;
+        const statements = (await plugins.mt940Js.read(fileBuffer)).map((statementArg) => decodeStatement(statementArg, encodingArg));
         // bank afterburner
         for (const statement of statements) {
             if (statement.referenceNumber === 'BUNQ BV' && statement.accountId) {
@@ -19,4 +136,4 @@ export class Mt940Parser {
         return statements;
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLDBCQUEwQixDQUFDO0FBRXBELE1BQU0sT0FBTyxXQUFXO0lBQ2YsS0FBSyxDQUFDLG9CQUFvQixDQUFDLGFBQXFCO1FBQ3JELE1BQU0sVUFBVSxHQUFHLElBQUksV0FBVyxFQUFFLENBQUM7UUFDckMsTUFBTSxVQUFVLEdBQUcsTUFBTSxJQUFJLENBQUMsZ0JBQWdCLENBQUMsVUFBVSxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUV4RixPQUFPLFVBQVUsQ0FBQztJQUNwQixDQUFDO0lBRU0sS0FBSyxDQUFDLGdCQUFnQixDQUFDLGFBQThCO1FBQzFELE1BQU0sVUFBVSxHQUFHLGFBQWEsWUFBWSxXQUFXO1lBQ3JELENBQUMsQ0FBQyxhQUFhO1lBQ2YsQ0FBQyxDQUFDLElBQUksVUFBVSxDQUFDLGFBQWEsQ0FBQyxDQUFDLEtBQUssRUFBRSxDQUFDLE1BQXFCLENBQUM7UUFDaEUsTUFBTSxVQUFVLEdBQUcsTUFBTSxPQUFPLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUUxRCxtQkFBbUI7UUFDbkIsS0FBSyxNQUFNLFNBQVMsSUFBSSxVQUFVLEVBQUUsQ0FBQztZQUNuQyxJQUFJLFNBQVMsQ0FBQyxlQUFlLEtBQUssU0FBUyxJQUFJLFNBQVMsQ0FBQyxTQUFTLEVBQUUsQ0FBQztnQkFDbkUsU0FBUyxDQUFDLFNBQVMsR0FBRyxTQUFTLENBQUMsU0FBUyxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQztZQUMxRCxDQUFDO1FBQ0gsQ0FBQztRQUVELE9BQU8sVUFBVSxDQUFDO0lBQ3BCLENBQUM7Q0FDRiJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLDBCQUEwQixDQUFDO0FBS3BELE1BQU0sb0JBQW9CLEdBQXNCLENBQUMsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLENBQUMsQ0FBQztBQUVuRSxNQUFNLDJCQUEyQixHQUFHLENBQUMsUUFBb0IsRUFBVyxFQUFFLENBQ3BFLG9CQUFvQixDQUFDLEtBQUssQ0FBQyxDQUFDLE9BQU8sRUFBRSxRQUFRLEVBQUUsRUFBRSxDQUFDLFFBQVEsQ0FBQyxRQUFRLENBQUMsS0FBSyxPQUFPLENBQUMsQ0FBQztBQUVwRiw0SEFBNEg7QUFDNUgsTUFBTSxtQkFBbUIsR0FBRyxJQUFJLENBQUM7QUFFakM7Ozs7R0FJRztBQUNILE1BQU0sWUFBWSxHQUFHLENBQUMsUUFBZ0IsRUFBYyxFQUFFO0lBQ3BELE1BQU0sS0FBSyxHQUFHLElBQUksVUFBVSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsQ0FBQztJQUM5QyxLQUFLLElBQUksS0FBSyxHQUFHLENBQUMsRUFBRSxLQUFLLEdBQUcsUUFBUSxDQUFDLE1BQU0sRUFBRSxLQUFLLEVBQUUsRUFBRSxDQUFDO1FBQ3JELE1BQU0sUUFBUSxHQUFHLFFBQVEsQ0FBQyxVQUFVLENBQUMsS0FBSyxDQUFDLENBQUM7UUFDNUMsSUFBSSxRQUFRLEdBQUcsSUFBSSxFQUFFLENBQUM7WUFDcEIsTUFBTSxJQUFJLEtBQUssQ0FBQyxvREFBb0QsUUFBUSxDQUFDLFFBQVEsQ0FBQyxFQUFFLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDaEcsQ0FBQztRQUNELEtBQUssQ0FBQyxLQUFLLENBQUMsR0FBRyxRQUFRLENBQUM7SUFDMUIsQ0FBQztJQUNELE9BQU8sS0FBSyxDQUFDO0FBQ2YsQ0FBQyxDQUFDO0FBRUYsbUhBQW1IO0FBQ25ILE1BQU0sd0JBQXdCLEdBQUcsQ0FB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

package/dist_ts/mt940parser.plugins.d.ts

@@ -1,2 +1,4 @@
+import * as smartstring from '@push.rocks/smartstring';
+export { smartstring };
 import * as mt940Js from 'mt940-js';
 export { mt940Js };

package/dist_ts/mt940parser.plugins.js

@@ -1,3 +1,7 @@
+// @push.rocks scope
+import * as smartstring from '@push.rocks/smartstring';
+export { smartstring };
+// third party scope
 import * as mt940Js from 'mt940-js';
 export { mt940Js };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibXQ5NDBwYXJzZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL210OTQwcGFyc2VyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxVQUFVLENBQUM7QUFFcEMsT0FBTyxFQUNMLE9BQU8sRUFDUixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibXQ5NDBwYXJzZXIucGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL210OTQwcGFyc2VyLnBsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxXQUFXLE1BQU0seUJBQXlCLENBQUM7QUFFdkQsT0FBTyxFQUFFLFdBQVcsRUFBRSxDQUFDO0FBRXZCLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssT0FBTyxNQUFNLFVBQVUsQ0FBQztBQUVwQyxPQUFPLEVBQ0wsT0FBTyxFQUNSLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/mt940",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "A parser to process and extract statements from MT940 format files, commonly used by banks for electronic account statements.",
   "main": "dist_ts/index.js",
@@ -9,11 +9,11 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.10.1",
-    "@git.zone/tsrun": "^2.0.5",
-    "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.1.0"
+    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsbundle": "^3.1.0",
+    "@git.zone/tsrun": "^3.0.2",
+    "@git.zone/tstest": "^6.3.2",
+    "@types/node": "^26.6.2"
   },
   "browserslist": [
     "last 1 chrome versions"
@@ -32,6 +32,7 @@
     "readme.md"
   ],
   "dependencies": {
+    "@push.rocks/smartstring": "^4.2.0",
     "mt940-js": "^1.0.0"
   },
   "keywords": [

package/readme.md

@@ -14,8 +14,9 @@ pnpm add @fin.cx/mt940
 
 ## What It Does
 
+- Parses the bytes of an MT940 file with `parseMt940FileBytes()`: UTF-8 where they are valid UTF-8, else Windows-1252.
 - Parses complete MT940 file content from a string with `parseMt940FileString()`.
-- Parses MT940 data from an `ArrayBufferLike` with `parseMt940Buffer()`.
+- Parses MT940 data from an `ArrayBufferLike` with `parseMt940Buffer()`, as `parseMt940FileBytes()` does.
 - Returns the statement, balance, and transaction objects produced by `mt940-js`.
 - Normalizes BUNQ statement account ids by stripping the trailing currency segment from `accountId`.
 - Works with modern ESM TypeScript projects.
@@ -43,23 +44,23 @@ console.log(statements[0].transactions[0].amount); // 5
 
 ## Parsing File Data In Node.js
 
-`parseMt940Buffer()` expects an `ArrayBufferLike`. When reading with Node.js, slice the underlying `ArrayBuffer` to the actual byte range of the `Buffer`.
+`parseMt940FileBytes()` takes the file's bytes as they are; a Node.js `Buffer` is a `Uint8Array`.
 
 ```typescript
 import { readFile } from 'node:fs/promises';
 import { Mt940Parser } from '@fin.cx/mt940';
 
 const parser = new Mt940Parser();
-const fileBuffer = await readFile('./statement.mt940');
-const arrayBuffer = fileBuffer.buffer.slice(
-  fileBuffer.byteOffset,
-  fileBuffer.byteOffset + fileBuffer.byteLength
-);
-
-const statements = await parser.parseMt940Buffer(arrayBuffer);
+const statements = await parser.parseMt940FileBytes(await readFile('./statement.mt940'));
 console.log(statements);
 ```
 
+## Encodings
+
+MT940 files carry no declaration of their encoding. German banks write them in Windows-1252; newer exports use UTF-8. `parseMt940FileBytes()` reads a file as UTF-8 when its bytes are valid UTF-8 (a byte order mark is not part of the text) and as Windows-1252 otherwise, by the WHATWG Encoding Standard's table through `@push.rocks/smartstring`, so `€`, `„`, `“` and `–` read the same on every runtime. `parseMt940Buffer()` does the same for an `ArrayBufferLike`; `parseMt940FileString()` takes text that is already decoded.
+
+`mt940-js` reads one byte as one character. This module hands it the file's bytes and decodes every text it answers from those bytes, so umlauts are neither lost nor garbled, and a transaction's `id` stays the one `mt940-js` computes from the file's bytes: the same file read again yields the same ids.
+
 ## Parsing Browser File Uploads
 
 Browser `File` objects already expose `arrayBuffer()`, so uploaded MT940 files can be parsed without Node.js APIs.
@@ -70,7 +71,7 @@ import { Mt940Parser } from '@fin.cx/mt940';
 const parser = new Mt940Parser();
 
 async function parseUploadedMt940(file: File) {
-  const statements = await parser.parseMt940Buffer(await file.arrayBuffer());
+  const statements = await parser.parseMt940FileBytes(new Uint8Array(await file.arrayBuffer()));
   return statements;
 }
 ```

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/mt940',
-  version: '2.0.0',
+  version: '2.1.0',
   description: 'A parser to process and extract statements from MT940 format files, commonly used by banks for electronic account statements.'
 }

package/ts/index.ts

@@ -1,18 +1,165 @@
 import * as plugins from './mt940parser.plugins.js';
 
+/** The encoding an MT940 file is read in: UTF-8 where its bytes are valid UTF-8, else Windows-1252. */
+export type TMt940Encoding = 'utf-8' | 'windows-1252';
+
+const UTF8_BYTE_ORDER_MARK: readonly number[] = [0xef, 0xbb, 0xbf];
+
+const startsWithUtf8ByteOrderMark = (bytesArg: Uint8Array): boolean =>
+  UTF8_BYTE_ORDER_MARK.every((byteArg, indexArg) => bytesArg[indexArg] === byteArg);
+
+/** The byte of the no-break space in Windows-1252, and of a UTF-8 continuation byte a character may end in (à is C3 A0). */
+const NO_BREAK_SPACE_BYTE = 0xa0;
+
+/**
+ * The bytes a field of mt940-js holds. mt940-js reads its input one byte as
+ * one character (`String.fromCharCode` of each byte), so each code unit of a
+ * field it answers is one byte of the file.
+ */
+const bytesOfField = (fieldArg: string): Uint8Array => {
+  const bytes = new Uint8Array(fieldArg.length);
+  for (let index = 0; index < fieldArg.length; index++) {
+    const codeUnit = fieldArg.charCodeAt(index);
+    if (codeUnit > 0xff) {
+      throw new Error(`mt940-js answered a character that is no byte (U+${codeUnit.toString(16)})`);
+    }
+    bytes[index] = codeUnit;
+  }
+  return bytes;
+};
+
+/** How many continuation bytes the UTF-8 sequence at the end of `bytesArg` still lacks (0 when it is complete). */
+const missingContinuationBytes = (bytesArg: Uint8Array): number => {
+  for (let back = 1; back <= Math.min(3, bytesArg.length); back++) {
+    const byte = bytesArg[bytesArg.length - back];
+    if (byte < 0x80) {
+      return 0;
+    }
+    if (byte >= 0xc0) {
+      const length = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : 2;
+      return Math.max(0, length - back);
+    }
+  }
+  return 0;
+};
+
+const decodeField = (bytesArg: Uint8Array, encodingArg: TMt940Encoding): string =>
+  encodingArg === 'utf-8' ? new TextDecoder('utf-8').decode(bytesArg) : plugins.smartstring.encoding.decodeWindows1252(bytesArg);
+
+/**
+ * A text of an :86: field, which mt940-js trims as it reads it byte by byte:
+ * JavaScript's `trim` takes a no-break space (0xA0) off its end, and in a
+ * file of UTF-8 0xA0 is also the last byte of characters (à is C3 A0, Š C5
+ * A0, † E2 80 A0). No other byte from 0x80 up is whitespace to `trim`, so the
+ * bytes the sequence at the end lacks were each 0xA0 and are put back; what
+ * was trimmed after that character was whitespace.
+ */
+const decodeTrimmedField = (fieldArg: string, encodingArg: TMt940Encoding): string => {
+  const bytes = bytesOfField(fieldArg);
+  if (encodingArg !== 'utf-8') {
+    return decodeField(bytes, encodingArg);
+  }
+  const missing = missingContinuationBytes(bytes);
+  if (missing === 0) {
+    return decodeField(bytes, encodingArg);
+  }
+  const completed = new Uint8Array(bytes.length + missing);
+  completed.set(bytes);
+  completed.fill(NO_BREAK_SPACE_BYTE, bytes.length);
+  return decodeField(completed, encodingArg);
+};
+
+/*
+ * mt940-js does not set every field its types name: a :61: line without a
+ * transaction code answers `code` undefined. A field that is no string is
+ * passed through as mt940-js answered it; a string is decoded from its bytes.
+ */
+
+/** A field of mt940-js in the file's encoding. */
+const decodeText = <T>(valueArg: T, encodingArg: TMt940Encoding): T =>
+  typeof valueArg === 'string' ? (decodeField(bytesOfField(valueArg), encodingArg) as T) : valueArg;
+
+/** An :86: text of mt940-js in the file's encoding (`decodeTrimmedField`). */
+const decodeTrimmedText = <T>(valueArg: T, encodingArg: TMt940Encoding): T =>
+  typeof valueArg === 'string' ? (decodeTrimmedField(valueArg, encodingArg) as T) : valueArg;
+
+const decodeBalance = (balanceArg: plugins.mt940Js.BalanceInfo, encodingArg: TMt940Encoding): plugins.mt940Js.BalanceInfo => ({
+  ...balanceArg,
+  date: decodeText(balanceArg.date, encodingArg),
+  currency: decodeText(balanceArg.currency, encodingArg),
+});
+
+/** A statement mt940-js read, with every text decoded from its bytes in the file's encoding. */
+const decodeStatement = (statementArg: plugins.mt940Js.Statement, encodingArg: TMt940Encoding): plugins.mt940Js.Statement => {
+  const text = <T>(valueArg: T): T => decodeText(valueArg, encodingArg);
+  const {
+    referenceNumber,
+    relatedReferenceNumber,
+    accountId,
+    number,
+    additionalInformation,
+    openingBalance,
+    closingBalance,
+    closingAvailableBalance,
+    forwardAvailableBalance,
+  } = statementArg;
+  return {
+    ...statementArg,
+    ...(referenceNumber !== undefined ? { referenceNumber: text(referenceNumber) } : {}),
+    ...(relatedReferenceNumber !== undefined ? { relatedReferenceNumber: text(relatedReferenceNumber) } : {}),
+    ...(accountId !== undefined ? { accountId: text(accountId) } : {}),
+    ...(number !== undefined ? { number: text(number) } : {}),
+    ...(additionalInformation !== undefined ? { additionalInformation: decodeTrimmedText(additionalInformation, encodingArg) } : {}),
+    ...(openingBalance ? { openingBalance: decodeBalance(openingBalance, encodingArg) } : {}),
+    ...(closingBalance ? { closingBalance: decodeBalance(closingBalance, encodingArg) } : {}),
+    ...(closingAvailableBalance ? { closingAvailableBalance: decodeBalance(closingAvailableBalance, encodingArg) } : {}),
+    ...(forwardAvailableBalance ? { forwardAvailableBalance: decodeBalance(forwardAvailableBalance, encodingArg) } : {}),
+    transactions: statementArg.transactions.map((transactionArg) => ({
+      ...transactionArg,
+      code: text(transactionArg.code),
+      fundsCode: text(transactionArg.fundsCode),
+      currency: text(transactionArg.currency),
+      description: decodeTrimmedText(transactionArg.description, encodingArg),
+      valueDate: text(transactionArg.valueDate),
+      entryDate: text(transactionArg.entryDate),
+      customerReference: text(transactionArg.customerReference),
+      bankReference: text(transactionArg.bankReference),
+    })),
+  };
+};
+
 export class Mt940Parser {
+  /**
+   * Parses MT940 file content given as text. Its characters are read as they
+   * are, whatever encoding the file was in before it became text.
+   */
   public async parseMt940FileString(fileStringArg: string) {
-    const textEncode = new TextEncoder();
-    const statements = await this.parseMt940Buffer(textEncode.encode(fileStringArg).buffer);
+    return this.parseBytesIn(new TextEncoder().encode(fileStringArg), 'utf-8');
+  }
 
-    return statements;
+  /**
+   * Parses the bytes of an MT940 file: UTF-8 where they are valid UTF-8 (a
+   * byte order mark is not part of the text), else Windows-1252, the
+   * encoding German banks write MT940 in. Every field is decoded from its own
+   * bytes, by the Encoding Standard's table for Windows-1252 on every
+   * runtime (`@push.rocks/smartstring`).
+   */
+  public async parseMt940FileBytes(fileBytesArg: Uint8Array) {
+    const encoding: TMt940Encoding = plugins.smartstring.encoding.isValidUtf8(fileBytesArg) ? 'utf-8' : 'windows-1252';
+    return this.parseBytesIn(fileBytesArg, encoding);
   }
 
+  /** Parses the bytes of an MT940 file in an `ArrayBufferLike`, as `parseMt940FileBytes` does. */
   public async parseMt940Buffer(fileBufferArg: ArrayBufferLike) {
-    const fileBuffer = fileBufferArg instanceof ArrayBuffer
-      ? fileBufferArg
-      : new Uint8Array(fileBufferArg).slice().buffer as ArrayBuffer;
-    const statements = await plugins.mt940Js.read(fileBuffer);
+    return this.parseMt940FileBytes(new Uint8Array(fileBufferArg));
+  }
+
+  private async parseBytesIn(fileBytesArg: Uint8Array, encodingArg: TMt940Encoding) {
+    // a byte order mark is no text of the file, and mt940-js finds no statement behind one
+    const text = encodingArg === 'utf-8' && startsWithUtf8ByteOrderMark(fileBytesArg) ? fileBytesArg.subarray(UTF8_BYTE_ORDER_MARK.length) : fileBytesArg;
+    // mt940-js takes an ArrayBuffer of its own; it reads each byte as one character
+    const fileBuffer = text.slice().buffer as ArrayBuffer;
+    const statements = (await plugins.mt940Js.read(fileBuffer)).map((statementArg) => decodeStatement(statementArg, encodingArg));
 
     // bank afterburner
     for (const statement of statements) {

package/ts/mt940parser.plugins.ts

@@ -1,3 +1,9 @@
+// @push.rocks scope
+import * as smartstring from '@push.rocks/smartstring';
+
+export { smartstring };
+
+// third party scope
 import * as mt940Js from 'mt940-js';
 
 export {