Registry / serialization / bplist-parser

bplist-parser

library0.3.2jsnpmunverified

bplist-parser is a JavaScript library designed to parse Apple's binary Property List (.bplist) files. These files are a compact, binary representation often used by macOS and iOS for storing structured data, as an alternative to XML plists. The current stable version is 0.3.2, which was last published to npm approximately four years ago, indicating a very slow or effectively halted release cadence. While the GitHub repository shows some minimal activity related to ESM conversion more recently, the published npm package remains CommonJS-centric. The package includes TypeScript type definitions. Its key differentiator is its singular focus on parsing binary plists, without support for XML or OpenStep plist formats, making it suitable for applications specifically dealing with this file type, though users should be aware of its infrequent updates.

serialization

npm install bplist-parser

github ↗package ↗

INSTALL

IMPORT

SIG · BPLIST-PARSER

bplist-parser

serializationjavascriptv0.3.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bplist

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

✗ import bplist from '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

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

✗ import { parseFile } from '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.

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); } })();

Debug

Known issues

gotchaThe `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');`.

affects: 0.x

breakingThe 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`.

affects: <=0.3.2

gotchaThe 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.

affects: <=0.3.2

Errors

Common errors & fixes

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

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>

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');`.

Upgrade

Version history

0.3.2latest on npm

Audit

Dependencies

big-integerrequiredUsed internally for handling large integers encountered in binary plist parsing, such as timestamps and large offsets.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/nearinfinity/node-bplist-parser ↗

packagehttps://www.npmjs.com/package/bplist-parser ↗