@sdxc/zone-file 0.0.0-pre.1

package/dist/parse.js

@@ -0,0 +1,282 @@
+import { failure, isFailure, success } from "@sdxc/result";
+import { ZoneFileError } from "./errors.js";
+import { lex } from "./lexer.js";
+import { absoluteName, canonicalName, qualifyName } from "./names.js";
+import { parseRecordData } from "./parse-record-data.js";
+import { isTypedType } from "./record-types.js";
+import { looksLikeTtl, readTtl } from "./ttl.js";
+/** Measures input in the UTF-8 bytes `maxBytes` counts. */
+const ENCODER = new TextEncoder();
+/** @default 1 MiB, larger than any zone a DNS provider accepts for import. */
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+/** How deep `$INCLUDE` may nest; the text passed to `parse` is depth 0. */
+const MAX_INCLUDE_DEPTH = 8;
+/** The RDATA fields of each typed type that hold a name, which a relative spelling qualifies. */
+const NAME_FIELDS = {
+    CNAME: [0],
+    NS: [0],
+    PTR: [0],
+    DNAME: [0],
+    MX: [1],
+    SRV: [3],
+    SOA: [0, 1],
+};
+/** The class numbers with a mnemonic, so `CLASS1` and `IN` read as one class. */
+const CLASS_NAMES = { "1": "IN", "2": "CS", "3": "CH", "4": "HS" };
+/**
+ * Reads a zone file. The only failure is `too-large`; every unreadable entry is a
+ * `Rejection` beside the records that did parse, so one bad line never costs the rest, and
+ * a caller that wants all-or-nothing checks `rejected.length`.
+ *
+ * Records outside the origin, repeats, non-`IN` classes and every record type are all
+ * returned: which of them to keep is the caller's decision.
+ *
+ * @param text - The zone file's contents.
+ * @param options - The origin, and how to read TTLs, includes and relative names.
+ * @returns The records and rejections, or the size that passed `maxBytes`.
+ * @example parse("www 300 IN A 192.0.2.1", { origin: "example.com" }) // records: [{ name: "www.example.com", ttl: 300, … }]
+ */
+export function parse(text, options) {
+    let reader = new ZoneReader(options);
+    let state = {
+        origin: canonicalName(options.origin) ?? options.origin.toLowerCase(),
+        defaultTtl: null,
+        lastTtl: null,
+        lastOwner: null,
+        lastClass: "IN",
+    };
+    let read = reader.read(text, null, state, 0);
+    if (isFailure(read))
+        return read;
+    return success({ origin: state.origin, records: reader.records, rejected: reader.rejected });
+}
+/** Reads one file's entries into shared record and rejection lists, recursing into includes. */
+class ZoneReader {
+    records = [];
+    rejected = [];
+    #options;
+    #maxBytes;
+    #mode;
+    #bytes = 0;
+    /** @param options - The options `parse` was called with. */
+    constructor(options) {
+        this.#options = options;
+        this.#maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.#mode = options.relativeNames ?? "rfc1035";
+    }
+    /**
+     * Reads one file, mutating `state` as its directives and records do; an included file
+     * reads with a copy, so the origin, `$TTL` and owner revert after it.
+     *
+     * @param text - The file's contents.
+     * @param file - The included file's name; `null` for the text passed to `parse`.
+     * @param state - The state the file starts with.
+     * @param depth - How many `$INCLUDE`s led here.
+     */
+    read(text, file, state, depth) {
+        this.#bytes += ENCODER.encode(text).byteLength;
+        if (this.#bytes > this.#maxBytes)
+            return failure(new ZoneFileError(this.#bytes, this.#maxBytes));
+        for (let entry of lex(text)) {
+            let reject = (reason, message) => {
+                this.rejected.push({
+                    file,
+                    line: entry.line,
+                    endLine: entry.endLine,
+                    input: entry.input,
+                    reason,
+                    message,
+                });
+            };
+            if (entry.error !== null) {
+                reject("malformed", entry.error);
+                continue;
+            }
+            let first = entry.tokens[0];
+            if (!entry.blankOwner && first && !first.quoted && first.text.startsWith("$")) {
+                let included = this.#directive(entry, file, state, depth, reject);
+                if (isFailure(included))
+                    return included;
+                continue;
+            }
+            this.#record(entry, file, state, reject);
+        }
+        return success(undefined);
+    }
+    /** Applies one `$` directive to `state`, reading an included file through the option. */
+    #directive(entry, file, state, depth, reject) {
+        let [directive, ...args] = entry.tokens;
+        let word = (directive?.text ?? "").toUpperCase();
+        switch (word) {
+            case "$ORIGIN": {
+                let origin = args.length === 1 ? this.#name(args[0], state.origin) : null;
+                if (origin === null)
+                    reject("malformed", "$ORIGIN needs one domain name");
+                else
+                    state.origin = origin;
+                break;
+            }
+            case "$TTL": {
+                let ttl = args.length === 1 && args[0] && !args[0].quoted ? readTtl(args[0].text) : null;
+                if (ttl === null)
+                    reject("malformed", "$TTL needs one TTL of at most 2147483647 seconds");
+                else
+                    state.defaultTtl = ttl;
+                break;
+            }
+            case "$INCLUDE": {
+                let [fileToken, originToken] = args;
+                let fileName = fileToken ? unquote(fileToken) : "";
+                let origin = originToken ? this.#name(originToken, state.origin) : state.origin;
+                if (args.length < 1 || args.length > 2 || fileName === "" || origin === null) {
+                    reject("malformed", "$INCLUDE needs a file name and an optional origin");
+                    break;
+                }
+                if (!this.#options.include) {
+                    reject("include", "$INCLUDE needs the include option to read a file");
+                    break;
+                }
+                if (depth >= MAX_INCLUDE_DEPTH) {
+                    reject("include", `$INCLUDE nests deeper than ${MAX_INCLUDE_DEPTH} files`);
+                    break;
+                }
+                let included = this.#options.include(fileName, origin);
+                if (included === null) {
+                    reject("include", `The include option returned no text for ${JSON.stringify(fileName)}`);
+                    break;
+                }
+                let read = this.read(included, fileName, { ...state, origin }, depth + 1);
+                if (isFailure(read))
+                    return read;
+                break;
+            }
+            default:
+                reject("unsupported-directive", `${directive?.text ?? word} is not a supported directive`);
+        }
+        return success(undefined);
+    }
+    /** Reads one record entry, or rejects it with the reason it cannot be one. */
+    #record(entry, file, state, reject) {
+        let tokens = entry.tokens;
+        let cursor = 0;
+        let owner;
+        if (entry.blankOwner) {
+            owner = state.lastOwner;
+            if (owner === null) {
+                reject("missing-owner", "A blank owner needs an earlier record to take it from");
+                return;
+            }
+        }
+        else {
+            let ownerToken = tokens[0];
+            cursor = 1;
+            owner = ownerToken ? this.#name(ownerToken, state.origin) : null;
+            if (owner === null) {
+                reject("malformed", `Invalid owner name ${JSON.stringify(ownerToken?.text ?? "")}`);
+                return;
+            }
+            state.lastOwner = owner;
+        }
+        let ttl = null;
+        let recordClass = null;
+        let ttlRead = false;
+        while (cursor < tokens.length) {
+            let token = tokens[cursor];
+            if (!token || token.quoted)
+                break;
+            if (!ttlRead && looksLikeTtl(token.text)) {
+                ttl = readTtl(token.text);
+                if (ttl === null) {
+                    reject("malformed", `TTL ${token.text} is over 2147483647 seconds`);
+                    return;
+                }
+                ttlRead = true;
+                cursor += 1;
+                continue;
+            }
+            let classMatch = /^(IN|CH|HS|CS|CLASS(\d+))$/i.exec(token.text);
+            if (recordClass === null && classMatch) {
+                let number = classMatch[2];
+                recordClass =
+                    number === undefined
+                        ? token.text.toUpperCase()
+                        : (CLASS_NAMES[String(Number(number))] ?? `CLASS${Number(number)}`);
+                cursor += 1;
+                continue;
+            }
+            break;
+        }
+        let typeToken = tokens[cursor];
+        if (!typeToken || typeToken.quoted || !/^[A-Za-z][A-Za-z0-9-]*$/.test(typeToken.text)) {
+            let found = typeToken ? `found ${JSON.stringify(typeToken.text)}` : "found nothing";
+            reject("malformed", `Expected a record type, ${found}`);
+            return;
+        }
+        let rdata = tokens.slice(cursor + 1);
+        if (rdata.length === 0) {
+            reject("malformed", `${typeToken.text.toUpperCase()} record has no data`);
+            return;
+        }
+        let data = this.#data(typeToken.text, rdata, state.origin);
+        if (typeof data === "string") {
+            reject("invalid-data", data);
+            return;
+        }
+        if (ttl !== null)
+            state.lastTtl = ttl;
+        let resolvedTtl = ttl ?? state.defaultTtl ?? state.lastTtl ?? this.#options.ttl ?? null;
+        if (resolvedTtl !== null)
+            state.lastTtl = resolvedTtl;
+        if (recordClass !== null)
+            state.lastClass = recordClass;
+        let fields = {
+            name: owner,
+            ttl: resolvedTtl,
+            class: recordClass ?? state.lastClass,
+            file,
+            line: entry.line,
+            endLine: entry.endLine,
+            comment: entry.comment,
+        };
+        this.records.push((isTypedType(data.type)
+            ? { ...fields, ...data }
+            : { ...fields, ...data, origin: state.origin }));
+    }
+    /**
+     * Reads a record's RDATA for its type: name fields qualified against the origin first,
+     * since `parseRecordData` has no origin to qualify them with. RFC 3597 generic data is
+     * read as is, its names being absolute on the wire.
+     *
+     * @returns The data, or the message for an `invalid-data` rejection.
+     */
+    #data(type, rdata, origin) {
+        let tokens = rdata.map((token) => token.text);
+        let generic = rdata[0]?.text === "\\#" && !rdata[0].quoted;
+        let upper = type.toUpperCase();
+        if (!generic) {
+            for (let index of NAME_FIELDS[upper] ?? []) {
+                let token = rdata[index];
+                if (!token)
+                    continue;
+                let name = this.#name(token, origin);
+                if (name === null)
+                    return `Invalid name ${JSON.stringify(token.text)} in ${upper} data`;
+                tokens[index] = absoluteName(name);
+            }
+        }
+        let parsed = parseRecordData(type, tokens.join(" "));
+        return isFailure(parsed) ? parsed.error.message : parsed.data;
+    }
+    /** Qualifies a name field, refusing a quoted one: quotes mark a character-string. */
+    #name(token, origin) {
+        if (!token || token.quoted)
+            return null;
+        return qualifyName(token.text, origin, this.#mode);
+    }
+}
+/** The text of a quoted field with `\X` escapes resolved, or a bare field as written. */
+function unquote(token) {
+    if (!token.quoted)
+        return token.text;
+    return token.text.slice(1, -1).replace(/\\(.)/g, "$1");
+}

package/dist/record-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Maps record type mnemonics to their IANA codes and back, with RFC 3597's `TYPEnnn`
+ * spelling for any code without a mnemonic here, and names the types read into fields.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type * as ZoneFile from "./types.js";
+/** The mnemonic for a type code, or `TYPEnnn` when it has none here. */
+export declare function typeName(code: number): string;
+/**
+ * The spelling of a type as a record's `type`: the uppercase mnemonic, and a known
+ * mnemonic for `TYPEnnn` when one exists.
+ */
+export declare function canonicalType(type: string): string;
+/** Whether a canonical type has typed fields, so its data carries no verbatim `data`. */
+export declare function isTypedType(type: string): type is ZoneFile.TypedRecordType;

package/dist/record-types.js

@@ -0,0 +1,65 @@
+/** The IANA codes of the record types a caller is likely to ask for or see in an answer. */
+const TYPE_CODES = {
+    A: 1,
+    NS: 2,
+    CNAME: 5,
+    SOA: 6,
+    PTR: 12,
+    HINFO: 13,
+    MX: 15,
+    TXT: 16,
+    AAAA: 28,
+    LOC: 29,
+    SRV: 33,
+    NAPTR: 35,
+    DNAME: 39,
+    DS: 43,
+    SSHFP: 44,
+    RRSIG: 46,
+    NSEC: 47,
+    DNSKEY: 48,
+    NSEC3: 50,
+    NSEC3PARAM: 51,
+    TLSA: 52,
+    SMIMEA: 53,
+    CDS: 59,
+    CDNSKEY: 60,
+    OPENPGPKEY: 61,
+    SVCB: 64,
+    HTTPS: 65,
+    URI: 256,
+    CAA: 257,
+};
+/** The types `parseRecordData` reads into typed fields. */
+const TYPED_TYPES = new Set([
+    "A",
+    "AAAA",
+    "CNAME",
+    "NS",
+    "PTR",
+    "DNAME",
+    "MX",
+    "TXT",
+    "CAA",
+    "SRV",
+    "SOA",
+]);
+/** The mnemonic for each code in {@link TYPE_CODES}. */
+const TYPE_NAMES = new Map(Object.entries(TYPE_CODES).map(([name, code]) => [code, name]));
+/** The mnemonic for a type code, or `TYPEnnn` when it has none here. */
+export function typeName(code) {
+    return TYPE_NAMES.get(code) ?? `TYPE${code}`;
+}
+/**
+ * The spelling of a type as a record's `type`: the uppercase mnemonic, and a known
+ * mnemonic for `TYPEnnn` when one exists.
+ */
+export function canonicalType(type) {
+    let upper = type.trim().toUpperCase();
+    let generic = /^TYPE(\d+)$/.exec(upper);
+    return generic ? typeName(Number(generic[1])) : upper;
+}
+/** Whether a canonical type has typed fields, so its data carries no verbatim `data`. */
+export function isTypedType(type) {
+    return TYPED_TYPES.has(type);
+}

package/dist/stringify.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Writes records as an RFC 1035 master file, one tab-separated line per record, with names
+ * absolute by default or relative to the origin, so a zone built in code or read with
+ * `parse` prints to text any BIND-compatible tool reads back to the same records.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type * as ZoneFile from "./types.js";
+/**
+ * Writes a zone. `$ORIGIN` and `$TTL` lead when the input names them, a record's TTL is
+ * left out when it equals `$TTL`, and an untyped record read under another origin gets an
+ * `$ORIGIN` line first so the relative names in its verbatim data keep their meaning.
+ *
+ * For any `zone` that `parse` produced, `parse(stringify(zone))` yields the same records —
+ * name, TTL, class, type, fields and comment; spacing, standalone comments and
+ * parentheses are not kept.
+ *
+ * @param zone - The origin, default TTL and records to write.
+ * @param options - `relative: true` writes names under the origin relative to it.
+ * @returns The zone file, ending in a newline.
+ * @example stringify({ origin: "example.com", records: [{ name: "www.example.com", ttl: 300, type: "A", address: "192.0.2.1" }] }, { relative: true }) // "$ORIGIN example.com.\nwww\t300\tIN\tA\t192.0.2.1\n"
+ */
+export declare function stringify(zone: ZoneFile.ZoneInput, options?: ZoneFile.StringifyOptions): string;

package/dist/stringify.js

@@ -0,0 +1,52 @@
+import { printRecordData } from "./format-record-data.js";
+import { absoluteName, canonicalName, relativeName } from "./names.js";
+import { isTypedType } from "./record-types.js";
+/**
+ * Writes a zone. `$ORIGIN` and `$TTL` lead when the input names them, a record's TTL is
+ * left out when it equals `$TTL`, and an untyped record read under another origin gets an
+ * `$ORIGIN` line first so the relative names in its verbatim data keep their meaning.
+ *
+ * For any `zone` that `parse` produced, `parse(stringify(zone))` yields the same records —
+ * name, TTL, class, type, fields and comment; spacing, standalone comments and
+ * parentheses are not kept.
+ *
+ * @param zone - The origin, default TTL and records to write.
+ * @param options - `relative: true` writes names under the origin relative to it.
+ * @returns The zone file, ending in a newline.
+ * @example stringify({ origin: "example.com", records: [{ name: "www.example.com", ttl: 300, type: "A", address: "192.0.2.1" }] }, { relative: true }) // "$ORIGIN example.com.\nwww\t300\tIN\tA\t192.0.2.1\n"
+ */
+export function stringify(zone, options = {}) {
+    let lines = [];
+    let origin = zone.origin === undefined ? null : canonical(zone.origin);
+    let ttl = zone.ttl ?? null;
+    if (origin !== null)
+        lines.push(`$ORIGIN ${absoluteName(origin)}`);
+    if (ttl !== null)
+        lines.push(`$TTL ${ttl}`);
+    for (let record of zone.records) {
+        if (!isTypedType(record.type) && "origin" in record && record.origin !== undefined) {
+            let recordOrigin = canonical(record.origin);
+            if (recordOrigin !== origin) {
+                origin = recordOrigin;
+                lines.push(`$ORIGIN ${absoluteName(origin)}`);
+            }
+        }
+        let current = origin;
+        let printName = (name) => options.relative && current !== null
+            ? relativeName(canonical(name), current)
+            : absoluteName(canonical(name));
+        let fields = [printName(record.name)];
+        if (record.ttl != null && record.ttl !== ttl)
+            fields.push(String(record.ttl));
+        fields.push(record.class ?? "IN", record.type, printRecordData(record, printName));
+        let line = fields.join("\t");
+        if (record.comment)
+            line += ` ; ${record.comment.replace(/[\r\n]+/g, " ")}`;
+        lines.push(line);
+    }
+    return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+/** A name in canonical form, or as given when it is not a valid name. */
+function canonical(name) {
+    return canonicalName(name) ?? name;
+}

package/dist/ttl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Reads a TTL field as seconds: a plain number, or BIND's unit form (`1h30m`, `2W`), which
+ * every BIND-compatible tool accepts in records and in `$TTL`, capped at RFC 2181's 2³¹−1.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Whether a field is spelled like a TTL, so the record reader takes it as one even when its
+ * value is out of range, and reports that rather than reading it as a record type.
+ */
+export declare function looksLikeTtl(field: string): boolean;
+/**
+ * The seconds a TTL field stands for, or `null` when it is not one or passes 2³¹−1.
+ *
+ * @example readTtl("1h30m") // 5400
+ */
+export declare function readTtl(field: string): number | null;

package/dist/ttl.js

@@ -0,0 +1,31 @@
+/**
+ * Reads a TTL field as seconds: a plain number, or BIND's unit form (`1h30m`, `2W`), which
+ * every BIND-compatible tool accepts in records and in `$TTL`, capped at RFC 2181's 2³¹−1.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The largest TTL RFC 2181 section 8 allows. */
+const MAX_TTL = 2 ** 31 - 1;
+/** Seconds per BIND TTL unit. */
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86_400, w: 604_800 };
+/**
+ * Whether a field is spelled like a TTL, so the record reader takes it as one even when its
+ * value is out of range, and reports that rather than reading it as a record type.
+ */
+export function looksLikeTtl(field) {
+    return /^\d+$/.test(field) || /^(\d+[smhdw])+$/i.test(field);
+}
+/**
+ * The seconds a TTL field stands for, or `null` when it is not one or passes 2³¹−1.
+ *
+ * @example readTtl("1h30m") // 5400
+ */
+export function readTtl(field) {
+    if (!looksLikeTtl(field))
+        return null;
+    let seconds = /^\d+$/.test(field)
+        ? Number(field)
+        : Array.from(field.matchAll(/(\d+)([smhdw])/gi)).reduce((total, [, amount, unit]) => total + Number(amount) * (UNIT_SECONDS[(unit ?? "s").toLowerCase()] ?? 1), 0);
+    return seconds <= MAX_TTL ? seconds : null;
+}