{"id":15549,"library":"bplist-parser","title":"Binary Property List Parser","description":"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.","status":"maintenance","version":"0.3.2","language":"javascript","source_language":"en","source_url":"https://github.com/nearinfinity/node-bplist-parser","tags":["javascript","bplist","plist","parser","typescript"],"install":[{"cmd":"npm install bplist-parser","lang":"bash","label":"npm"},{"cmd":"yarn add bplist-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add bplist-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for handling large integers encountered in binary plist parsing, such as timestamps and large offsets.","package":"big-integer","optional":false}],"imports":[{"note":"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.","wrong":"import bplist from 'bplist-parser';","symbol":"bplist","correct":"const bplist = require('bplist-parser');"},{"note":"`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`.","wrong":"import { parseFile } from 'bplist-parser';","symbol":"parseFile","correct":"const { parseFile } = require('bplist-parser');"},{"note":"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.","symbol":"PlistObject","correct":"import type { PlistObject } from 'bplist-parser';"}],"quickstart":{"code":"import { readFile } from 'fs/promises';\nimport { join } from 'path';\nimport type { PlistObject } from 'bplist-parser';\n\n// Assuming bplist-parser is a CJS module, we import it this way for ESM interop.\n// In a pure CJS environment, 'const bplist = require(\"bplist-parser\");' is correct.\nimport * as bplist from 'bplist-parser';\n\nconst createDummyPlistFile = async (filepath: string) => {\n  // In a real scenario, you'd have an actual .bplist file.\n  // This is a minimal example; creating a real binary plist is complex.\n  // For demonstration, we simulate reading a file that *would* be a bplist.\n  console.log(`Simulating parsing of a binary plist file: ${filepath}`);\n  // In a real app, you would read an actual .bplist buffer.\n  // For this example, we'll use a very small, known valid bplist header as a placeholder.\n  // A minimal valid binary plist is much larger, this is just to show the API.\n  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');\n  // Using parseBuffer for a direct buffer, as parseFile expects a file path.\n  const parsedObj: PlistObject[] = await (bplist as any).parseBuffer(dummyBuffer);\n  console.log('Parsed Plist Object:', JSON.stringify(parsedObj, null, 2));\n};\n\n(async () => {\n  const plistPath = join(process.cwd(), 'myPlist.bplist');\n  try {\n    // The parseFile function takes a file path directly.\n    // Since we're simulating, we'll demonstrate parseBuffer directly.\n    // If a real file existed, you'd do: \n    // const obj = await bplist.parseFile(plistPath);\n    await createDummyPlistFile(plistPath);\n  } catch (error) {\n    console.error('Error parsing plist:', error);\n  }\n})();","lang":"typescript","description":"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."},"warnings":[{"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');`.","message":"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.","severity":"gotcha","affected_versions":"0.x"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<=0.3.2"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.3.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","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.","error":"Error: Invalid binary plist. Expected 'bplist' at offset 0."},{"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');`.","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.","error":"TypeError: Cannot read properties of undefined (reading 'parseFile') at Object.<anonymous>"}],"ecosystem":"npm"}