@sdxc/zone-file 0.0.0-stage → 2026.10.9

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Xalambrí
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# @sdxc/zone-file
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read and write RFC 1035 DNS zone files, with the record data codec for every typed record.
+
+## Installation
+
+```bash
+npm add @sdxc/zone-file
+```
+
+`parse` returns a [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result) value, which
+installs alongside this package.
+
+A zone file (a BIND "master file") is how DNS operators export, import, review and version a
+zone. `parse` reads the whole RFC 1035 grammar — `$ORIGIN`, `$TTL`, `$INCLUDE`, parentheses,
+blank owners, escapes, TTL units, any class and any type — and returns the records it read beside
+every entry it could not use, each with its line and a reason. `stringify` writes records back, so
+`parse(stringify(zone))` gives the same records.
+
+## Usage
+
+### Read A Zone File
+
+```typescript
+import * as ZoneFile from "@sdxc/zone-file";
+import { isSuccess } from "@sdxc/result";
+
+let parsed = ZoneFile.parse(text, { origin: "example.com" });
+if (isSuccess(parsed)) {
+	for (let record of parsed.data.records) console.log(record.name, record.ttl, record.type);
+	for (let rejection of parsed.data.rejected) console.warn(rejection.line, rejection.message);
+}
+```
+
+### Write One
+
+```typescript
+import * as ZoneFile from "@sdxc/zone-file";
+
+let text = ZoneFile.stringify(
+	{
+		origin: "example.com",
+		ttl: 3600,
+		records: [
+			{ name: "example.com", type: "MX", preference: 10, exchange: "mail.example.com" },
+			{ name: "www.example.com", ttl: 300, type: "CNAME", target: "example.com" },
+		],
+	},
+	{ relative: true },
+);
+// $ORIGIN example.com.
+// $TTL 3600
+// @	IN	MX	10 mail
+// www	300	IN	CNAME	@
+```
+
+### Read Record Data From Anywhere
+
+```typescript
+import { parseRecordData } from "@sdxc/zone-file";
+
+parseRecordData("MX", "10 Mail.Example.com.");
+// success({ type: "MX", preference: 10, exchange: "mail.example.com" })
+```
+
+## API
+
+### `parse(text, options): Result<ZoneFile.Zone, ZoneFileError>`
+
+Reads a zone file into `{ origin, records, rejected }`. The only failure is a `ZoneFileError`
+for input past `maxBytes`; any other problem — a bad line, an unknown directive, RDATA that does
+not fit its type — is a `Rejection` beside the records that did parse, so a caller wanting
+all-or-nothing checks `rejected.length`.
+
+| Option          | Default     | Meaning                                                                                                          |
+| --------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `origin`        | Required    | The initial `$ORIGIN`; `@` and relative names resolve against it until a `$ORIGIN` line changes it               |
+| `ttl`           | `null`      | The TTL a record gets when neither it, a `$TTL` nor an earlier record states one                                 |
+| `include`       | None        | `(fileName, origin) => string \| null`, the text of an `$INCLUDE`d file; without it every `$INCLUDE` is rejected |
+| `relativeNames` | `"rfc1035"` | `"origin-suffix"` also reads a dotless name that equals the origin or ends in it as absolute                     |
+| `maxBytes`      | 1 MiB       | The largest input in UTF-8 bytes, counted across included files                                                  |
+
+The grammar:
+
+- `;` starts a comment outside quotes; a record's trailing comment is kept as `comment`.
+- `"…"` quotes a field, with `\"`, `\\` and `\DDD` escapes; a `;` or parenthesis inside is data.
+- `(` … `)` joins lines into one entry; `line` is where it starts and `endLine` where it ends.
+- `@` is the current origin, and a name without a trailing dot gets the origin appended, in owners
+  and in the name fields of typed RDATA.
+- Names come back absolute, lowercased, without the trailing dot, `\DDD` and `\.` escapes resolved
+  to one canonical spelling; the root is `"."`.
+- A line starting with whitespace takes the previous record's owner.
+- TTL and class are optional, in either order. A TTL is seconds or BIND units (`1h30m`, `2W`), up
+  to 2³¹−1. A record without one takes `$TTL`, else the previous record's TTL, else `options.ttl`.
+- `$ORIGIN`, `$TTL` and `$INCLUDE file [origin]` are read. An included file starts with the given
+  or current origin, and the origin, `$TTL` and owner revert after it; includes nest 8 deep.
+  `$GENERATE` is rejected.
+- Classes are `IN`, `CH`, `HS`, `CS` and `CLASSnnn`; types are any mnemonic or `TYPEnnn`, and RFC
+  3597 generic data (`\# 4 C0000201`) is read for every type.
+
+Records outside the origin, a record listed twice, classes other than `IN` and every type are all
+returned: which of them to keep is the caller's decision.
+
+### `stringify(zone, options?): string`
+
+Writes `{ origin?, ttl?, records }` (a parsed `Zone` is one) as one tab-separated line per record.
+`$ORIGIN` and `$TTL` lead when the input names them, and a record's TTL is left out when it equals
+`$TTL`. `relative: true` writes names under the origin relative to it and the apex as `@`;
+otherwise every name is absolute. An untyped record read under another origin gets an `$ORIGIN`
+line first, so relative names in its verbatim data keep their meaning. Comments are written back
+after `;`; spacing, standalone comments and parentheses are not kept.
+
+### `parseRecordData(type, data): Result<ZoneFile.RecordData<Type>, RecordDataError>`
+
+Reads RDATA in presentation format into typed fields. Typed types: `A` and `AAAA` (`address`, IPv6
+in RFC 5952 form), `CNAME`, `PTR` and `DNAME` (`target`), `NS` (`host`), `MX` (`preference`,
+`exchange`), `TXT` (`text`, `strings`), `CAA` (`flags`, `critical`, `tag`, `value`), `SRV`
+(`priority`, `weight`, `port`, `target`) and `SOA` (`primary`, `mailbox`, `serial`, `refresh`,
+`retry`, `expire`, `minimum`, the timers accepting TTL units). Any other type returns
+`{ type, data }`. RFC 3597 generic data is decoded for the typed types. Names are not qualified:
+relative names stay relative.
+
+```typescript
+parseRecordData("TXT", '"v=DKIM1; p=AAA" "BBB"');
+// success({ type: "TXT", text: "v=DKIM1; p=AAABBB", strings: ["v=DKIM1; p=AAA", "BBB"] })
+```
+
+### `formatRecordData(data): string`
+
+Prints record data in canonical presentation format, the inverse of `parseRecordData`: names
+absolute with the trailing dot, TXT strings and the CAA value quoted with every octet outside
+printable ASCII as `\DDD`, the CAA tag lowercased, untyped data as is. Two spellings of one record —
+`0 ISSUE "ca.example"` and its generic form — print to one string.
+
+```typescript
+formatRecordData({ type: "MX", preference: 10, exchange: "mx.example.com" }); // "10 mx.example.com."
+```
+
+### `canonicalType(type): string` / `typeName(code): string`
+
+`canonicalType("txt")` is `"TXT"` and `canonicalType("TYPE16")` is `"TXT"`; `typeName(16)` is
+`"TXT"`, and a code without a mnemonic is `"TYPEnnn"`.
+
+### Errors
+
+| Class             | When                                                                                   |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `ZoneFileError`   | `code: "too-large"`: the input, with its includes, passed `maxBytes`; `bytes` holds it |
+| `RecordDataError` | `parseRecordData` on data that does not fit the type                                   |
+
+### Rejection reasons
+
+| `reason`                | When                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
+| `malformed`             | An unterminated quote, unbalanced parentheses, a bad owner or TTL, a missing type or data |
+| `invalid-data`          | RDATA that does not fit its type; `message` holds the codec's error                       |
+| `missing-owner`         | A blank owner with no earlier record to take it from                                      |
+| `include`               | `$INCLUDE` without the `include` option, a file it returned `null` for, or nesting past 8 |
+| `unsupported-directive` | `$GENERATE` or any other `$` word                                                         |
+
+Each rejection carries `file` (`null` for the text passed to `parse`), `line`, `endLine`, `input`
+(the entry as written) and `message`.
+
+### `ZoneFile` namespace
+
+Types only: `Zone`, `Record`, `RecordFor<Type>`, `RecordFields`, `UntypedRecord`, `Rejection`,
+`RejectionReason`, `ParseOptions`, `ZoneInput`, `RecordInput`, `StringifyOptions`, `RecordType`,
+`TypedRecordType`, `RecordClass`, `RecordData<Type>`, and one data interface per typed type
+(`AData` through `SOAData`) plus `UnknownData`.
+
+## Pattern: Import Only What You Track
+
+`parse` returns everything; the policy is a filter.
+
+```typescript
+import * as ZoneFile from "@sdxc/zone-file";
+import { isFailure } from "@sdxc/result";
+
+let parsed = ZoneFile.parse(text, { origin: domain, relativeNames: "origin-suffix" });
+if (isFailure(parsed)) throw new Error(parsed.error.message);
+
+let tracked = parsed.data.records.filter(
+	(record) =>
+		record.class === "IN" &&
+		["A", "AAAA", "MX", "TXT"].includes(record.type) &&
+		(record.name === domain || record.name.endsWith(`.${domain}`)),
+);
+```
+
+## Pattern: Normalize A Zone File For Review
+
+Reading and printing gives every zone one spelling — absolute names, canonical addresses, quoted
+TXT — so two exports diff only where their records differ.
+
+```typescript
+import * as ZoneFile from "@sdxc/zone-file";
+import { unwrap } from "@sdxc/result";
+
+function normalize(text: string, origin: string): string {
+	let zone = unwrap(ZoneFile.parse(text, { origin }));
+	let records = [...zone.records].sort((a, b) => a.name.localeCompare(b.name));
+	return ZoneFile.stringify({ origin, records }, { relative: true });
+}
+```
+
+## Pattern: Read A Zone With Includes
+
+```typescript
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import * as ZoneFile from "@sdxc/zone-file";
+
+let parsed = ZoneFile.parse(readFileSync("zones/example.com.zone", "utf8"), {
+	origin: "example.com",
+	include: (fileName) => readFileSync(join("zones", fileName), "utf8"),
+});
+```
+
+## Versioning
+
+Releases are dated rather than semantic. A version is the UTC date it was published,
+written `YYYY.M.D`, so `2026.9.4` is the release from 4 September 2026. At most one
+release goes out per day.
+
+Those numbers say when, not what: a later date means a later release and carries no
+compatibility promise. Any release may change or remove an export.
+
+Depend on one exact date, and move it when you are ready to take the change:
+
+```json
+{
+	"dependencies": {
+		"@sdxc/zone-file": "2026.9.4"
+	}
+}
+```
+
+A caret or tilde range reads the date as major, minor and patch, so it accepts every
+later release in the same year. An exact version keeps the upgrade yours to schedule.
+
+## License
+
+MIT
+
+## Author
+
+[Sergio Xalambrí](https://sergiodxa.com)

package/dist/character-strings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reads the character-strings of TXT RDATA in presentation format (RFC 1035 section 5.1):
+ * quoted strings keep their spaces, bare words split on whitespace, and `\"`, `\\` and
+ * `\DDD` escapes are decoded, so a resolver's quoting never leaks into the text.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import { RecordDataError } from "./errors.js";
+/**
+ * Splits TXT presentation data into its character-strings. Escapes are decoded to octets
+ * and each string is read as UTF-8, so text a resolver writes as `\195\169` comes back as
+ * `é`. Fails on an unterminated quote or a decimal escape above 255.
+ *
+ * @param data - One or more quoted or bare character-strings.
+ * @returns The strings in order, empty strings included.
+ * @example readCharacterStrings('"v=DKIM1; p=AAA" "BBB"') // success(["v=DKIM1; p=AAA", "BBB"])
+ */
+export declare function readCharacterStrings(data: string): Result<string[], RecordDataError>;
+/** Decodes octets as UTF-8, the reading applied to every character-string. */
+export declare function decodeOctets(octets: Uint8Array): string;

package/dist/character-strings.js

@@ -0,0 +1,72 @@
+import { failure, success } from "@sdxc/result";
+import { RecordDataError } from "./errors.js";
+/** Decodes a character-string's octets as UTF-8, replacing invalid sequences with U+FFFD. */
+const DECODER = new TextDecoder();
+/** Encodes literal characters into the octets they stand for. */
+const ENCODER = new TextEncoder();
+/** Whether a character separates character-strings. */
+function isSpace(char) {
+    return char === " " || char === "\t" || char === "\n" || char === "\r";
+}
+/**
+ * Splits TXT presentation data into its character-strings. Escapes are decoded to octets
+ * and each string is read as UTF-8, so text a resolver writes as `\195\169` comes back as
+ * `é`. Fails on an unterminated quote or a decimal escape above 255.
+ *
+ * @param data - One or more quoted or bare character-strings.
+ * @returns The strings in order, empty strings included.
+ * @example readCharacterStrings('"v=DKIM1; p=AAA" "BBB"') // success(["v=DKIM1; p=AAA", "BBB"])
+ */
+export function readCharacterStrings(data) {
+    let chars = Array.from(data);
+    let strings = [];
+    let index = 0;
+    while (index < chars.length) {
+        if (isSpace(chars[index])) {
+            index += 1;
+            continue;
+        }
+        let quoted = chars[index] === '"';
+        if (quoted)
+            index += 1;
+        let octets = [];
+        let terminated = !quoted;
+        while (index < chars.length) {
+            let char = chars[index] ?? "";
+            if (quoted && char === '"') {
+                terminated = true;
+                index += 1;
+                break;
+            }
+            if (!quoted && isSpace(char))
+                break;
+            if (char === "\\") {
+                let digits = chars.slice(index + 1, index + 4).join("");
+                if (/^\d{3}$/.test(digits)) {
+                    let octet = Number(digits);
+                    if (octet > 255)
+                        return failure(new RecordDataError(`Invalid escape \\${digits} in TXT data`));
+                    octets.push(octet);
+                    index += 4;
+                    continue;
+                }
+                let next = chars[index + 1];
+                if (next === undefined)
+                    return failure(new RecordDataError("TXT data ends in a lone backslash"));
+                octets.push(...ENCODER.encode(next));
+                index += 2;
+                continue;
+            }
+            octets.push(...ENCODER.encode(char));
+            index += 1;
+        }
+        if (!terminated)
+            return failure(new RecordDataError("TXT data has an unterminated quoted string"));
+        strings.push(DECODER.decode(new Uint8Array(octets)));
+    }
+    return success(strings);
+}
+/** Decodes octets as UTF-8, the reading applied to every character-string. */
+export function decodeOctets(octets) {
+    return DECODER.decode(octets);
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two failures this package returns: RDATA that does not fit its type, and a zone file
+ * too large to read at all. Everything else wrong with a file is a line-level rejection
+ * beside the records that did parse.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** RDATA that does not parse for its type. */
+export declare class RecordDataError extends Error {
+    name: string;
+}
+/** A zone file that `parse` refuses whole; its `code` names why. */
+export declare class ZoneFileError extends Error {
+    name: string;
+    /** The input, with its includes, passed `maxBytes`. */
+    readonly code = "too-large";
+    /** UTF-8 bytes read when the limit was passed, included files counted. */
+    readonly bytes: number;
+    /**
+     * @param bytes - The bytes read so far.
+     * @param maxBytes - The limit they passed.
+     */
+    constructor(bytes: number, maxBytes: number);
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+/**
+ * The two failures this package returns: RDATA that does not fit its type, and a zone file
+ * too large to read at all. Everything else wrong with a file is a line-level rejection
+ * beside the records that did parse.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** RDATA that does not parse for its type. */
+export class RecordDataError extends Error {
+    name = "RecordDataError";
+}
+/** A zone file that `parse` refuses whole; its `code` names why. */
+export class ZoneFileError extends Error {
+    name = "ZoneFileError";
+    /** The input, with its includes, passed `maxBytes`. */
+    code = "too-large";
+    /** UTF-8 bytes read when the limit was passed, included files counted. */
+    bytes;
+    /**
+     * @param bytes - The bytes read so far.
+     * @param maxBytes - The limit they passed.
+     */
+    constructor(bytes, maxBytes) {
+        super(`The zone file is ${bytes} bytes, over the ${maxBytes} byte limit`);
+        this.bytes = bytes;
+    }
+}

package/dist/format-record-data.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Prints typed record data back to canonical presentation format, the inverse of
+ * `parseRecordData`, so two spellings of one record (a zone file's text and a resolver's
+ * RFC 3597 generic form) print to one string a diff can key on.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type * as ZoneFile from "./types.js";
+/**
+ * Prints a record's data in canonical presentation format. Names print absolute with the
+ * trailing dot (the root stays `"."`), TXT and CAA values print quoted with `"` and `\`
+ * escaped and every octet outside printable ASCII as `\DDD`, and untyped data prints as is.
+ * `parseRecordData(data.type, formatRecordData(data))` gives back `data`.
+ *
+ * @param data - Record data, as `parseRecordData` produces it.
+ * @returns The RDATA in presentation format.
+ * @example formatRecordData({ type: "MX", preference: 10, exchange: "mx.example.com" }) // "10 mx.example.com."
+ * @example formatRecordData({ type: "CAA", flags: 0, critical: false, tag: "issue", value: "pki.goog" }) // '0 issue "pki.goog"'
+ */
+export declare function formatRecordData(data: ZoneFile.RecordData<ZoneFile.RecordType>): string;
+/**
+ * Prints record data with every name written by `printName`, which lets a zone file write
+ * names relative to its origin while the data's other fields print as `formatRecordData`
+ * prints them.
+ *
+ * @param data - Typed or untyped record data.
+ * @param printName - Writes one canonical name as it appears in the output.
+ */
+export declare function printRecordData(data: {
+    type: string;
+}, printName: (name: string) => string): string;

package/dist/format-record-data.js

@@ -0,0 +1,84 @@
+import { absoluteName } from "./names.js";
+/** Encodes a character-string into the octets `\DDD` escapes stand for. */
+const ENCODER = new TextEncoder();
+/**
+ * Prints a record's data in canonical presentation format. Names print absolute with the
+ * trailing dot (the root stays `"."`), TXT and CAA values print quoted with `"` and `\`
+ * escaped and every octet outside printable ASCII as `\DDD`, and untyped data prints as is.
+ * `parseRecordData(data.type, formatRecordData(data))` gives back `data`.
+ *
+ * @param data - Record data, as `parseRecordData` produces it.
+ * @returns The RDATA in presentation format.
+ * @example formatRecordData({ type: "MX", preference: 10, exchange: "mx.example.com" }) // "10 mx.example.com."
+ * @example formatRecordData({ type: "CAA", flags: 0, critical: false, tag: "issue", value: "pki.goog" }) // '0 issue "pki.goog"'
+ */
+export function formatRecordData(data) {
+    return printRecordData(data, absoluteName);
+}
+/**
+ * Prints record data with every name written by `printName`, which lets a zone file write
+ * names relative to its origin while the data's other fields print as `formatRecordData`
+ * prints them.
+ *
+ * @param data - Typed or untyped record data.
+ * @param printName - Writes one canonical name as it appears in the output.
+ */
+export function printRecordData(data, printName) {
+    switch (data.type) {
+        case "A":
+        case "AAAA":
+            return data.address;
+        case "CNAME":
+        case "PTR":
+        case "DNAME":
+            return printName(data.target);
+        case "NS":
+            return printName(data.host);
+        case "MX": {
+            let { preference, exchange } = data;
+            return `${preference} ${printName(exchange)}`;
+        }
+        case "TXT": {
+            let { strings } = data;
+            return strings.length === 0 ? "\\# 0" : strings.map(quote).join(" ");
+        }
+        case "CAA": {
+            let { flags, tag, value } = data;
+            return `${flags} ${tag.toLowerCase()} ${quote(value)}`;
+        }
+        case "SRV": {
+            let { priority, weight, port, target } = data;
+            return `${priority} ${weight} ${port} ${printName(target)}`;
+        }
+        case "SOA": {
+            let soa = data;
+            return [
+                printName(soa.primary),
+                printName(soa.mailbox),
+                soa.serial,
+                soa.refresh,
+                soa.retry,
+                soa.expire,
+                soa.minimum,
+            ].join(" ");
+        }
+        default:
+            return String(data.data);
+    }
+}
+/**
+ * One quoted character-string: `"` and `\` escaped, every octet outside printable ASCII
+ * written `\DDD`, so the text reads back to the same UTF-8 whatever the reader's encoding.
+ */
+function quote(text) {
+    let printed = "";
+    for (let octet of ENCODER.encode(text)) {
+        if (octet === 0x22 || octet === 0x5c)
+            printed += `\\${String.fromCharCode(octet)}`;
+        else if (octet >= 0x20 && octet <= 0x7e)
+            printed += String.fromCharCode(octet);
+        else
+            printed += `\\${String(octet).padStart(3, "0")}`;
+    }
+    return `"${printed}"`;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads and writes RFC 1035 master files (BIND zone files), reporting every entry it cannot
+ * use beside the records it read, and owns the RDATA presentation codec, so record data from
+ * a zone file and from a resolver reads into the same typed fields.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export type * from "./types.js";
+export type * as ZoneFile from "./types.js";
+export { RecordDataError, ZoneFileError } from "./errors.js";
+export { formatRecordData } from "./format-record-data.js";
+export { parse } from "./parse.js";
+export { parseRecordData } from "./parse-record-data.js";
+export { canonicalType, typeName } from "./record-types.js";
+export { stringify } from "./stringify.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * Reads and writes RFC 1035 master files (BIND zone files), reporting every entry it cannot
+ * use beside the records it read, and owns the RDATA presentation codec, so record data from
+ * a zone file and from a resolver reads into the same typed fields.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+export { RecordDataError, ZoneFileError } from "./errors.js";
+export { formatRecordData } from "./format-record-data.js";
+export { parse } from "./parse.js";
+export { parseRecordData } from "./parse-record-data.js";
+export { canonicalType, typeName } from "./record-types.js";
+export { stringify } from "./stringify.js";

package/dist/lexer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Splits master-file text into entries: one per line, or one per parenthesized group of
+ * lines, each a list of fields with its trailing comment. Quotes, escapes and parentheses
+ * are settled here, so the entry reader sees fields and never characters.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** One field of an entry, as written: quotes and escapes kept for the field's own reader. */
+export interface Token {
+    text: string;
+    quoted: boolean;
+}
+/** One logical entry of a zone file: a directive, a record, or something unreadable. */
+export interface Entry {
+    line: number;
+    endLine: number;
+    /** The first line starts with whitespace, which leaves the owner to the previous entry. */
+    blankOwner: boolean;
+    tokens: Token[];
+    /** The `;` comment outside parentheses, trimmed; `null` without one. */
+    comment: string | null;
+    /** Why the entry cannot be read; `null` when it lexed cleanly. */
+    error: string | null;
+    /** The entry as written, every line of it. */
+    input: string;
+}
+/**
+ * Splits text into entries. Blank and comment-only lines produce none; an entry whose
+ * parentheses never close runs to the end of the text and carries an error, as does one
+ * with a quote left open at the end of a line.
+ *
+ * @param text - The zone file's contents.
+ * @returns The entries in file order.
+ * @example lex("www IN A 192.0.2.1 ; web")[0]?.tokens.length // 4
+ */
+export declare function lex(text: string): Entry[];