Fast PLIST Parser

Common errors

• Error: Near offset X: expected < ~~~bad string~~~

  cause Attempting to parse an input string that is not a valid XML-formatted PLIST.
  fix Ensure the input string is a well-formed XML PLIST. The parser is strict and expects valid XML structure from the beginning.

• Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/project/node_modules/fast-plist/index.js from ... not supported

  cause You are trying to `require()` this CommonJS package within an ECMAScript Module (ESM) context in Node.js, and Node.js's interoperability could not handle it, or a bundler issue.
  fix If in an ESM file, change `const parse = require('fast-plist').parse;` to `import { parse } from 'fast-plist';`. If this persists with bundlers, ensure your build configuration is set up to correctly handle CommonJS modules within an ESM project, or consider downgrading your module system to CommonJS if possible for the specific file.

Warnings

• gotcha The package version 0.1.3 is quite old (last published 3 years ago). This may lead to compatibility issues with newer Node.js versions or browser environments, and it might lack patches for potential security vulnerabilities discovered since its last release.
  Fix: Thoroughly test in your target environment. Consider auditing the code or evaluating more actively maintained alternatives if security or compatibility with very recent runtimes is critical.
• gotcha The package primarily exports CommonJS modules. When used in an ECMAScript Module (ESM) project, you might encounter `ERR_REQUIRE_ESM` errors, especially in Node.js environments without proper transpilation or direct ESM support for CommonJS modules. While bundlers often handle this, direct Node.js ESM execution might fail.
  Fix: For Node.js ESM projects, ensure your build setup correctly handles CommonJS dependencies. You might need to use dynamic `import()` or configure your bundler (e.g., Webpack, Rollup, esbuild) to resolve CommonJS modules. If using TypeScript, ensure your `tsconfig.json`'s `moduleResolution` is set appropriately (e.g., 'Bundler' or 'NodeNext').
• gotcha This library only supports XML-based PLIST parsing. It does not provide functionality for parsing or generating binary PLIST (`bplist`) files, which are often used by Apple for performance reasons. Attempting to parse a binary PLIST will result in a parsing error.
  Fix: If you need to work with binary PLISTs, consider using alternative libraries like `bplist-parser` or `@expo/plist` which offer support for both XML and binary formats.

Install

• npm install fast-plist npm
• yarn add fast-plist yarn
• pnpm add fast-plist pnpm

Imports

• parse
  wrong:

  const parse = require('fast-plist');

  correct:

  import { parse } from 'fast-plist';

  The package's primary entry point is CommonJS. For ESM contexts, a named import like this should work via bundler or Node.js's interoperability layers. The `require` syntax directly accesses the `parse` function from the module's exports.

Quickstart

Demonstrates parsing a well-formed XML PLIST string into a JavaScript object and handling errors for malformed input.

import { parse } from 'fast-plist';

const plistString = `
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>name</key>
    <string>Brogrammer</string>
    <key>settings</key>
    <dict>
        <key>background</key>
        <string>#1a1a1a</string>
        <key>caret</key>
        <string>#ecf0f1</string>
        <key>foreground</key>
        <string>#ecf0f1</string>
        <key>invisibles</key>
        <string>#F3FFB51A</string>
        <key>lineHighlight</key>
        <string>#2a2a2a</string>
    </dict>
</dict>
</plist>`;

try {
  const parsedData = parse(plistString);
  console.log(JSON.stringify(parsedData, null, 2));
} catch (error) {
  console.error('Failed to parse PLIST:', error.message);
}

// Example of parsing an invalid string (will throw an error)
try {
  parse(`bad string`);
} catch (error) {
  console.error('Error parsing bad string:', error.message);
}