@xml-auditfile/auditfile 0.0.0-stage → 0.0.2-alpha.1

package/src/index.js

@@ -0,0 +1,20 @@
+// Streaming reader for Dutch tax audit files (XAF and related), following auditfile-spec.
+
+export { Auditfile, AuditfileReader } from './auditfile.js';
+export { Dialect, DialectCorrection } from './definitions/dialect.js';
+export { ElementDefinition } from './definitions/element-definition.js';
+export { LocalizedText, TextLanguage } from './definitions/localized-text.js';
+export { AuditfileManifest, ColumnType, ManifestColumn, ManifestKey, ManifestReference, ManifestTable } from './definitions/manifest.js';
+export { DialectAction, ViewAggregate, ViewOperator } from './definitions/names.js';
+export { ViewColumn, ViewDefinition, ViewJoin, ViewJoinCondition, ViewParameter, ViewValue } from './definitions/view-definition.js';
+export { compareSeverity, Diagnostic, DiagnosticSeverity } from './diagnostics/diagnostic.js';
+export { AuditfileReport } from './diagnostics/report.js';
+export { Decimal } from './internal/decimal.js';
+export { MemorySink } from './memory/memory-sink.js';
+export { ReadMode, ReadProgress } from './reading/read-options.js';
+export { AuditfileRow } from './reading/row.js';
+export { AuditfileSource, PartInfo, SourcePart } from './reading/source.js';
+export { AuditfileSchema, SchemaColumn, SchemaTable, VersionSource } from './schema/schema.js';
+export { ImportContext, SinkCapabilities } from './sinks/sink.js';
+export { AuditfileVersion } from './versioning/version.js';
+export { ViewResult } from './views/view-result.js';

package/src/internal/composite-key.js

@@ -0,0 +1,2 @@
+/** Joins the values of composite keys, view groups and joins: a character that cannot occur in XML text. */
+export const SEPARATOR = '\u001f';

package/src/internal/decimal.js

@@ -0,0 +1,193 @@
+const PATTERN = /^([+-]?)(\d*)(?:\.(\d*))?$/;
+
+// The range of .NET decimal, so every implementation of the reader accepts the same values.
+const MAX_SCALE = 28;
+const MAX_COEFFICIENT = 79228162514264337593543950335n;
+
+/**
+ * An exact decimal number: a BigInt coefficient and a scale (digits after the point).
+ * Amounts are never floating point, so totals and balances are exact.
+ * The scale is kept as written: `Decimal.parse('100.00').toString()` is `'100.00'`.
+ */
+export class Decimal {
+    #coefficient;
+    #scale;
+
+    /**
+     * @param {bigint} coefficient
+     * @param {number} [scale]
+     */
+    constructor(coefficient, scale = 0) {
+        if (typeof coefficient !== 'bigint') {
+            throw new TypeError('The coefficient of a Decimal must be a bigint.');
+        }
+
+        if (!Number.isInteger(scale) || scale < 0) {
+            throw new RangeError('The scale of a Decimal must be a non-negative integer.');
+        }
+
+        this.#coefficient = coefficient;
+        this.#scale = scale;
+    }
+
+    /** Zero. */
+    static ZERO = new Decimal(0n, 0);
+
+    /**
+     * Parses XSD notation: an optional sign, digits and an optional decimal point. No exponent, no grouping.
+     * Returns null when the text is not valid or outside the range of a .NET decimal.
+     * @param {string} text
+     * @returns {Decimal | null}
+     */
+    static parse(text) {
+        const match = PATTERN.exec(text);
+        if (match === null) {
+            return null;
+        }
+
+        const [, sign, whole, fraction = ''] = match;
+        if (whole.length === 0 && fraction.length === 0) {
+            return null;
+        }
+
+        if (fraction.length > MAX_SCALE) {
+            return null;
+        }
+
+        const digits = (whole + fraction).replace(/^0+/, '');
+        if (digits.length > 29) {
+            return null;
+        }
+
+        const magnitude = digits.length === 0 ? 0n : BigInt(digits);
+        if (magnitude > MAX_COEFFICIENT) {
+            return null;
+        }
+
+        return new Decimal(sign === '-' ? -magnitude : magnitude, fraction.length);
+    }
+
+    /**
+     * Converts a number, bigint, numeric string or Decimal.
+     * @param {Decimal | number | bigint | string} value
+     * @returns {Decimal}
+     */
+    static from(value) {
+        if (value instanceof Decimal) {
+            return value;
+        }
+
+        if (typeof value === 'bigint') {
+            return new Decimal(value, 0);
+        }
+
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                throw new RangeError(`${value} is not a finite number.`);
+            }
+
+            if (Number.isInteger(value)) {
+                if (!Number.isSafeInteger(value)) {
+                    throw new RangeError(`${value} is not a safe integer; pass a string or bigint instead.`);
+                }
+
+                return new Decimal(BigInt(value), 0);
+            }
+        }
+
+        if (typeof value === 'number' || typeof value === 'string') {
+            const parsed = Decimal.parse(String(value).trim());
+            if (parsed !== null) {
+                return parsed;
+            }
+        }
+
+        throw new TypeError(`'${String(value)}' is not a valid decimal.`);
+    }
+
+    /** The unscaled value. */
+    get coefficient() {
+        return this.#coefficient;
+    }
+
+    /** Digits after the decimal point. */
+    get scale() {
+        return this.#scale;
+    }
+
+    /** @param {Decimal} other */
+    add(other) {
+        const scale = Math.max(this.#scale, other.#scale);
+        return new Decimal(this.#rescaled(scale) + other.#rescaled(scale), scale);
+    }
+
+    /** @param {Decimal} other */
+    subtract(other) {
+        return this.add(other.negate());
+    }
+
+    negate() {
+        return new Decimal(-this.#coefficient, this.#scale);
+    }
+
+    /**
+     * Compares by value: `1.0` equals `1.00`.
+     * @param {Decimal} other
+     * @returns {-1 | 0 | 1}
+     */
+    compareTo(other) {
+        const scale = Math.max(this.#scale, other.#scale);
+        const a = this.#rescaled(scale);
+        const b = other.#rescaled(scale);
+        return a < b ? -1 : a > b ? 1 : 0;
+    }
+
+    /** @param {unknown} other */
+    equals(other) {
+        return other instanceof Decimal && this.compareTo(other) === 0;
+    }
+
+    /** True when the value has no fractional part. */
+    get isInteger() {
+        return this.#coefficient % 10n ** BigInt(this.#scale) === 0n;
+    }
+
+    /** The value with trailing fractional zeros removed: `1.50` becomes `1.5`. */
+    normalize() {
+        let coefficient = this.#coefficient;
+        let scale = this.#scale;
+        while (scale > 0 && coefficient % 10n === 0n) {
+            coefficient /= 10n;
+            scale--;
+        }
+
+        return new Decimal(coefficient, scale);
+    }
+
+    /** Nearest JavaScript number; may lose precision. */
+    toNumber() {
+        return Number(this.toString());
+    }
+
+    /** Invariant notation with the scale as written, e.g. `-123.40`. */
+    toString() {
+        const negative = this.#coefficient < 0n;
+        const digits = (negative ? -this.#coefficient : this.#coefficient).toString().padStart(this.#scale + 1, '0');
+        const whole = digits.slice(0, digits.length - this.#scale);
+        const fraction = digits.slice(digits.length - this.#scale);
+        return (negative ? '-' : '') + whole + (this.#scale > 0 ? `.${fraction}` : '');
+    }
+
+    /** Serializes as a string so no precision is lost. */
+    toJSON() {
+        return this.toString();
+    }
+
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `Decimal(${this.toString()})`;
+    }
+
+    #rescaled(scale) {
+        return this.#coefficient * 10n ** BigInt(scale - this.#scale);
+    }
+}

package/src/internal/encoding.js

@@ -0,0 +1,118 @@
+/**
+ * The encoding of a document or part, from its byte order mark or XML declaration (UTF-8 when neither says otherwise),
+ * following the detection rules of XML 1.0 appendix F.
+ */
+export class PartEncoding {
+    /** @internal */
+    constructor(name, bomLength, unitSize, bigEndian) {
+        /** Name as declared, e.g. "utf-8", "utf-16le", "ISO-8859-1". */
+        this.name = name;
+        this.bomLength = bomLength;
+        /** Bytes per code unit: 1 for UTF-8 and single-byte encodings, 2 for UTF-16. */
+        this.unitSize = unitSize;
+        this.bigEndian = bigEndian;
+        Object.freeze(this);
+    }
+
+    /** Upper-case name for messages, e.g. "UTF-8". */
+    get label() {
+        return this.name.toUpperCase();
+    }
+
+    /** True when both decode the same way; labels such as "latin1" and "ISO-8859-1" are the same encoding. */
+    sameAs(other) {
+        return canonical(this.name) === canonical(other.name);
+    }
+
+    /**
+     * @param {Uint8Array} bytes The first bytes.
+     * @returns {PartEncoding}
+     */
+    static detect(bytes) {
+        const startsWith = (...start) => bytes.length >= start.length && start.every((b, i) => bytes[i] === b);
+        if (startsWith(0xef, 0xbb, 0xbf)) {
+            return new PartEncoding('utf-8', 3, 1, false);
+        }
+
+        if (startsWith(0xff, 0xfe) || startsWith(0x3c, 0x00, 0x3f, 0x00)) {
+            return new PartEncoding('utf-16le', startsWith(0xff, 0xfe) ? 2 : 0, 2, false);
+        }
+
+        if (startsWith(0xfe, 0xff) || startsWith(0x00, 0x3c, 0x00, 0x3f)) {
+            return new PartEncoding('utf-16be', startsWith(0xfe, 0xff) ? 2 : 0, 2, true);
+        }
+
+        const head = String.fromCharCode(...bytes.subarray(0, Math.min(bytes.length, 512)));
+        const declaration = /^<\?xml\s[^>]*?encoding\s*=\s*(["'])([A-Za-z][A-Za-z0-9._-]*)\1/.exec(head);
+        return new PartEncoding(declaration === null ? 'utf-8' : declaration[2], 0, 1, false);
+    }
+
+    /**
+     * Number of bytes of a leading byte order mark and XML declaration.
+     * @param {Uint8Array} bytes
+     * @param {number} length Bytes to look at.
+     */
+    skipDeclaration(bytes, length) {
+        const position = this.bomLength;
+        if (!this.#matches(bytes, length, position, '<?xml')) {
+            return position;
+        }
+
+        for (let i = position + 5 * this.unitSize; i + 2 * this.unitSize <= length; i += this.unitSize) {
+            if (this.#matches(bytes, length, i, '?>')) {
+                return i + 2 * this.unitSize;
+            }
+        }
+
+        return position;
+    }
+
+    #matches(bytes, length, position, text) {
+        for (let c = 0; c < text.length; c++) {
+            const at = position + c * this.unitSize;
+            if (at + this.unitSize > length) {
+                return false;
+            }
+
+            const low = this.unitSize === 1 || !this.bigEndian ? bytes[at] : bytes[at + 1];
+            const high = this.unitSize === 1 ? 0 : this.bigEndian ? bytes[at] : bytes[at + 1];
+            if (low !== text.charCodeAt(c) || high !== 0) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}
+
+/** The WHATWG name of an encoding label, or the label itself when no decoder knows it. */
+function canonical(name) {
+    try {
+        return new TextDecoder(name).encoding;
+    } catch {
+        return name.toLowerCase();
+    }
+}
+
+/** The declared encoding is not supported (XAF-X004). */
+export class XmlEncodingError extends Error {
+    constructor(encoding, message = `Encoding '${encoding}' is not supported.`) {
+        super(message);
+        this.name = 'XmlEncodingError';
+        this.encoding = encoding;
+        /** @type {number | null} The part, when one part differs from the first. */
+        this.part = null;
+    }
+}
+
+/**
+ * A continuation part in another encoding than the first part. The parts are decoded as one document,
+ * so it would be read as garbled text without any error; it is refused instead (XAF-X004).
+ */
+export class PartEncodingError extends XmlEncodingError {
+    constructor(part, encoding, first) {
+        super(`${encoding.label} (part 1: ${first.label})`, `Part ${part} is encoded as ${encoding.label}, but part 1 as ${first.label}.`);
+        this.name = 'PartEncodingError';
+        this.part = part;
+    }
+}

package/src/internal/json.js

@@ -0,0 +1,106 @@
+// Typed access to parsed JSON. Every accessor checks the type, so malformed input fails with a clear message
+// instead of producing undefined values further on.
+
+/** @param {unknown} value */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {string} text
+ * @param {string} name
+ */
+export function parseObject(text, name) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    } catch (error) {
+        throw new SyntaxError(`${name} is not valid JSON: ${error.message}`);
+    }
+
+    if (!isObject(value)) {
+        throw new SyntaxError(`${name} is not a JSON object.`);
+    }
+
+    return value;
+}
+
+function has(json, key) {
+    return Object.prototype.hasOwnProperty.call(json, key) && json[key] !== null && json[key] !== undefined;
+}
+
+export function string(json, key) {
+    const value = has(json, key) ? json[key] : undefined;
+    if (typeof value !== 'string') {
+        throw new SyntaxError(`JSON: '${key}' must be a string.`);
+    }
+
+    return value;
+}
+
+export function optionalString(json, key) {
+    return has(json, key) ? string(json, key) : null;
+}
+
+export function int(json, key) {
+    const value = has(json, key) ? json[key] : undefined;
+    if (!Number.isSafeInteger(value)) {
+        throw new SyntaxError(`JSON: '${key}' must be an integer.`);
+    }
+
+    return value;
+}
+
+export function optionalInt(json, key) {
+    return has(json, key) ? int(json, key) : null;
+}
+
+export function bool(json, key) {
+    return has(json, key) && json[key] === true;
+}
+
+export function object(json, key) {
+    if (!has(json, key)) {
+        return null;
+    }
+
+    if (!isObject(json[key])) {
+        throw new SyntaxError(`JSON: '${key}' must be an object.`);
+    }
+
+    return json[key];
+}
+
+export function array(json, key) {
+    if (!has(json, key)) {
+        return [];
+    }
+
+    if (!Array.isArray(json[key])) {
+        throw new SyntaxError(`JSON: '${key}' must be an array.`);
+    }
+
+    return json[key];
+}
+
+export function objects(json, key) {
+    return array(json, key).map((item) => {
+        if (!isObject(item)) {
+            throw new SyntaxError(`JSON: '${key}' must contain objects.`);
+        }
+
+        return item;
+    });
+}
+
+export function strings(json, key) {
+    return array(json, key).map((item) => {
+        if (typeof item !== 'string') {
+            throw new SyntaxError(`JSON: '${key}' must contain strings.`);
+        }
+
+        return item;
+    });
+}
+
+export { isObject };

package/src/internal/sha256.js

@@ -0,0 +1,147 @@
+// Incremental SHA-256 (FIPS 180-4) without platform APIs, so the reader runs in Node and in the browser alike.
+// In Node the built-in implementation is used instead, through process.getBuiltinModule so bundlers see no import.
+
+const nodeCrypto = globalThis.process?.getBuiltinModule?.('node:crypto') ?? null;
+
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+export class Sha256 {
+    #state = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    #block = new Uint8Array(64);
+    #blockLength = 0;
+    #length = 0;
+    #words = new Uint32Array(64);
+    #finished = false;
+
+    /** @param {Uint8Array} data */
+    update(data) {
+        if (this.#finished) {
+            throw new Error('The hash has already been finished.');
+        }
+
+        this.#length += data.length;
+        let offset = 0;
+        if (this.#blockLength > 0) {
+            const take = Math.min(64 - this.#blockLength, data.length);
+            this.#block.set(data.subarray(0, take), this.#blockLength);
+            this.#blockLength += take;
+            offset = take;
+            if (this.#blockLength < 64) {
+                return this;
+            }
+
+            this.#compress(this.#block, 0);
+            this.#blockLength = 0;
+        }
+
+        for (; offset + 64 <= data.length; offset += 64) {
+            this.#compress(data, offset);
+        }
+
+        if (offset < data.length) {
+            this.#block.set(data.subarray(offset), 0);
+            this.#blockLength = data.length - offset;
+        }
+
+        return this;
+    }
+
+    /** Finishes the hash and returns it as lowercase hex. */
+    digestHex() {
+        if (this.#finished) {
+            throw new Error('The hash has already been finished.');
+        }
+
+        const bits = this.#length * 8;
+        const padding = new Uint8Array((this.#blockLength < 56 ? 56 : 120) - this.#blockLength + 8);
+        padding[0] = 0x80;
+        const view = new DataView(padding.buffer);
+        view.setUint32(padding.length - 8, Math.floor(bits / 0x100000000));
+        view.setUint32(padding.length - 4, bits >>> 0);
+        this.#length -= padding.length;
+        this.update(padding);
+        this.#finished = true;
+
+        let hex = '';
+        for (const word of this.#state) {
+            hex += word.toString(16).padStart(8, '0');
+        }
+
+        return hex;
+    }
+
+    /** @param {Uint8Array} data */
+    static hex(data) {
+        return Sha256.create().update(data).digestHex();
+    }
+
+    /**
+     * The fastest available implementation: Node's when present, this one otherwise.
+     * @returns {{ update(data: Uint8Array): unknown, digestHex(): string }}
+     */
+    static create() {
+        if (nodeCrypto === null) {
+            return new Sha256();
+        }
+
+        const hash = nodeCrypto.createHash('sha256');
+        return {
+            update(data) {
+                hash.update(data);
+                return this;
+            },
+            digestHex: () => hash.digest('hex'),
+        };
+    }
+
+    #compress(data, offset) {
+        const w = this.#words;
+        for (let i = 0; i < 16; i++) {
+            const j = offset + i * 4;
+            w[i] = (data[j] << 24) | (data[j + 1] << 16) | (data[j + 2] << 8) | data[j + 3];
+        }
+
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = ((a >>> 7) | (a << 25)) ^ ((a >>> 18) | (a << 14)) ^ (a >>> 3);
+            const s1 = ((b >>> 17) | (b << 15)) ^ ((b >>> 19) | (b << 13)) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+
+        const s = this.#state;
+        let [a, b, c, d, e, f, g, h] = s;
+        for (let i = 0; i < 64; i++) {
+            const s1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+            const t1 = (h + s1 + ((e & f) ^ (~e & g)) + K[i] + w[i]) | 0;
+            const s0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+            const t2 = (s0 + ((a & b) ^ (a & c) ^ (b & c))) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+
+        s[0] += a;
+        s[1] += b;
+        s[2] += c;
+        s[3] += d;
+        s[4] += e;
+        s[5] += f;
+        s[6] += g;
+        s[7] += h;
+    }
+}