Binary Property List Parser

Common errors

• Error: Invalid binary plist. Expected 'bplist' at offset 0.

  cause The file or buffer provided to `parseFile` or `parseBuffer` is either not a valid binary plist file, is corrupted, or is in an unexpected format (e.g., an XML plist). The parser checks for the 'bplist' magic bytes at the beginning of the file/buffer.
  fix Ensure the input file is indeed a binary plist (.bplist) and not an XML plist (.plist) or any other file type. Validate the file's integrity. If you're dealing with XML plists, you need a different parser (e.g., `plist` npm package).

• TypeError: Cannot read properties of undefined (reading 'parseFile') at Object.<anonymous>

  cause This typically occurs in an ESM environment when attempting to destructure named exports from a CommonJS module imported with `import bplist from 'bplist-parser';`, or when accessing properties on `undefined` if the import failed.
  fix In ESM, use `import * as bplist from 'bplist-parser';` to import the entire module as a namespace object. Then access `bplist.parseFile`. Alternatively, if your project supports it, use `const bplist = require('bplist-parser');`.

Warnings

• gotcha The `bplist-parser` package (version 0.3.2) is primarily a CommonJS module. Attempting to use `import bplist from 'bplist-parser';` directly in a pure ESM environment may lead to unexpected behavior or require specific build tool configurations, as default ESM imports of CJS modules often result in the entire module object being imported as the default. The recommended approach for ESM is `import * as bplist from 'bplist-parser';` or explicit `require` if supported by your runtime.
  Fix: For ESM, use `import * as bplist from 'bplist-parser';`. If using TypeScript, ensure `esModuleInterop` is enabled in `tsconfig.json`. In CommonJS, continue to use `const bplist = require('bplist-parser');`.
• breaking The package has not had a new release in approximately four years (as of 2026), with the latest version being 0.3.2. This means it may not be actively maintained for new Node.js versions, performance improvements, or potential security vulnerabilities discovered in binary plist parsing or its dependencies. Users should be aware that significant changes in Node.js runtime or underlying file system APIs might not be directly supported without manual intervention.
  Fix: Monitor the GitHub repository for any new forks or community-maintained alternatives that offer more active development. Review the source code and dependencies for known vulnerabilities if using in a security-sensitive application. Consider newer, more actively maintained alternatives if available for your specific use case, such as `@plist/binary.parse` or `bplist-lossless`.
• gotcha The library's internal `maxObjectSize` and `maxObjectCount` limits (100MB and 32768 objects respectively) are hardcoded. Parsing extremely large or deeply nested binary plist files may hit these limits, leading to errors or incomplete parsing without providing explicit configuration options.
  Fix: For very large files, consider pre-processing or breaking them down if possible. If you encounter errors related to object size or count, you might need to explore modifying these limits directly in a forked version of the library or choosing an alternative parser that allows configurable limits.

Install

• npm install bplist-parser npm
• yarn add bplist-parser yarn
• pnpm add bplist-parser pnpm

Imports

• bplist
  wrong:

  import bplist from 'bplist-parser';

  correct:

  const bplist = require('bplist-parser');

  The `0.3.2` version is primarily a CommonJS module. While modern Node.js may interop with `import bplist from 'bplist-parser';` for CJS modules, direct `require` is the intended and most reliable way to consume it. For full ESM projects, consider explicitly wrapping it or using a fork.
• parseFile
  wrong:

  import { parseFile } from 'bplist-parser';

  correct:

  const { parseFile } = require('bplist-parser');

  `parseFile` is an exported named function within the CommonJS module. It's often accessed as a property of the default export, e.g., `bplist.parseFile`.
• PlistObject

  import type { PlistObject } from 'bplist-parser';

  The package ships with TypeScript definitions, allowing for type-safe usage and enabling type inference for parsed plist structures. `PlistObject` is a common top-level type for the parsed result.

Quickstart

This example demonstrates how to parse a binary Property List (bplist) file using `bplist-parser`. It shows both CommonJS `require` usage (implicitly via `import * as`) and the `parseFile` and `parseBuffer` methods, including basic TypeScript type usage. A dummy binary plist buffer is used for direct `parseBuffer` demonstration, as creating a valid binary plist file dynamically is outside the scope of a quickstart.

import { readFile } from 'fs/promises';
import { join } from 'path';
import type { PlistObject } from 'bplist-parser';

// Assuming bplist-parser is a CJS module, we import it this way for ESM interop.
// In a pure CJS environment, 'const bplist = require("bplist-parser");' is correct.
import * as bplist from 'bplist-parser';

const createDummyPlistFile = async (filepath: string) => {
  // In a real scenario, you'd have an actual .bplist file.
  // This is a minimal example; creating a real binary plist is complex.
  // For demonstration, we simulate reading a file that *would* be a bplist.
  console.log(`Simulating parsing of a binary plist file: ${filepath}`);
  // In a real app, you would read an actual .bplist buffer.
  // For this example, we'll use a very small, known valid bplist header as a placeholder.
  // A minimal valid binary plist is much larger, this is just to show the API.
  const dummyBuffer = Buffer.from('bplist00\xd1\x01\x02\x10\x11Hello World!\x00\x00\x00\x00\x00\x00\x01\x01\x00\x00\x00\x00\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x17', 'latin1');
  // Using parseBuffer for a direct buffer, as parseFile expects a file path.
  const parsedObj: PlistObject[] = await (bplist as any).parseBuffer(dummyBuffer);
  console.log('Parsed Plist Object:', JSON.stringify(parsedObj, null, 2));
};

(async () => {
  const plistPath = join(process.cwd(), 'myPlist.bplist');
  try {
    // The parseFile function takes a file path directly.
    // Since we're simulating, we'll demonstrate parseBuffer directly.
    // If a real file existed, you'd do: 
    // const obj = await bplist.parseFile(plistPath);
    await createDummyPlistFile(plistPath);
  } catch (error) {
    console.error('Error parsing plist:', error);
  }
})();