DNS Zone File Parser and Generator

Common errors

• Error: Invalid zone file syntax at line X: Y

  cause The input string provided to `parseZone` contains malformed DNS record entries or overall syntax errors according to RFC1035.
  fix Review the `zoneFileContent` string for correct record types, hostnames (e.g., trailing dots for FQDNs), TTLs, and other DNS specific syntax. Use a DNS zone file validator to pinpoint the exact issue.

• TypeError: zonefile.parseZone is not a function

  cause The module was imported incorrectly, or the `zonefile` variable does not properly reference the functions exported by the package.
  fix Ensure you are using the correct import statement: `import { parseZone, generate } from 'zone-file';` for ESM, or `const { parseZone, generate } = require('zone-file');` for CommonJS.

Warnings

• breaking The `zone-file` npm package (v1.0.0) has not been updated since January 2019. While the underlying code may be developed under a different GitHub repository (`stacks-network/zone-file-js`), no new versions have been published to npm under this package name. This means it lacks recent bug fixes, performance improvements, and security updates.
  Fix: Consider migrating to a more actively maintained DNS zone file parsing library if long-term support, security patches, or new features are required. Inspect `stacks-network/zone-file-js` for alternative distribution methods or package names.
• gotcha Incorrectly formatted zone file input can lead to parsing errors or the generation of invalid DNS configurations, which can cause significant service disruptions. DNS zone files are highly sensitive to syntax, including trailing dots on FQDNs and correct record structures.
  Fix: Always validate generated or parsed zone files using external tools (e.g., `named-checkzone` from BIND, online validators) before deployment. Carefully review the input data structure for `generate` and the output of `parseZone`.
• gotcha The `zone-file` package uses CommonJS `require()` internally and exports functions for `import` in modern JavaScript environments. If using `require()` directly, ensure your environment is set up for CommonJS or that you destructure correctly.
  Fix: For CommonJS, use `const zonefile = require('zone-file'); const parsed = zonefile.parseZone(...);`. For ESM, ensure your `package.json` has `"type": "module"` or use a bundler configured for module resolution.

Install

• npm install zone-file npm
• yarn add zone-file yarn
• pnpm add zone-file pnpm

Imports

• parseZone
  wrong:

  const { parseZone } = require('zone-file');

  correct:

  import { parseZone } from 'zone-file';

  The original `zone-file` v1.0.0 was primarily CommonJS. Modern Node.js projects should configure their environment for ESM. For older environments, use `require`.
• generate
  wrong:

  const { generate } = require('zone-file');

  correct:

  import { generate } from 'zone-file';

  The `generate` function creates a zone file string from a JavaScript object. Ensure your environment supports ESM imports for newer syntax.

Quickstart

This example demonstrates how to parse an existing DNS zone file string into a JavaScript object, modify the object by adding a new CNAME record, and then generate an updated zone file string.

import { parseZone, generate } from 'zone-file';

const zoneFileContent = `
$ORIGIN example.com.
$TTL 3600
@ IN SOA ns1.example.com. hostmaster.example.com. (
  2023010101 ; Serial
  7200       ; Refresh
  3600       ; Retry
  1209600    ; Expire
  3600       ; Minimum TTL
)
@ IN NS ns1.example.com.
@ IN NS ns2.example.com.
@ IN A 192.0.2.1
www IN A 192.0.2.2
mail IN MX 10 mail.example.com.
mail IN A 192.0.2.3
`;

try {
  // Parse the zone file content into a JavaScript object
  const parsedZone = parseZone(zoneFileContent);
  console.log('Parsed Zone Object:');
  console.log(JSON.stringify(parsedZone, null, 2));

  // Add a new record to the parsed object
  parsedZone.cname = parsedZone.cname || [];
  parsedZone.cname.push({ name: 'blog', alias: 'www' });

  // Generate a new zone file string from the modified object
  const generatedZone = generate(parsedZone);
  console.log('\nGenerated Zone File with new CNAME record:');
  console.log(generatedZone);

} catch (error) {
  console.error('Error processing zone file:', error.message);
}