or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-plist

Apple's property list parser/builder for Node.js and browsers

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/plist@3.1.x

To install, run

npx @tessl/cli install tessl/npm-plist@3.1.0

Plist

Apple's property list parser/builder for Node.js and browsers. Provides facilities for reading and writing Plist (property list) files commonly used in macOS, iOS applications, and iTunes configuration files.

Package Information

Package Name: plist
Package Type: npm
Language: JavaScript
Installation: npm install plist
Node.js Version: >=10.4.0

Core Imports

const plist = require('plist');

For ES modules:

import * as plist from 'plist';

Individual functions:

const { parse, build } = require('plist');

Basic Usage

const plist = require('plist');

// Parse a plist XML string
const xml = `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>name</key>
    <string>MyApp</string>
    <key>version</key>
    <string>1.0.0</string>
  </dict>
</plist>`;

const obj = plist.parse(xml);
console.log(obj); // { name: "MyApp", version: "1.0.0" }

// Build a plist XML string from an object
const data = { name: "MyApp", version: "1.0.0" };
const plistXml = plist.build(data);
console.log(plistXml);

Capabilities

Parsing

Converts plist XML strings into JavaScript objects.

/**
 * Parses a Plist XML string and returns a JavaScript object
 * @param {string} xml - the XML String to decode
 * @returns {*} the decoded value from the Plist XML
 * @throws {Error} if malformed document or invalid plist structure
 */
function parse(xml);

Usage Examples:

const plist = require('plist');
const fs = require('fs');

// Parse from file
const plistContent = fs.readFileSync('Info.plist', 'utf8');
const parsed = plist.parse(plistContent);

// Parse inline XML
const xml = `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <array>
    <string>item1</string>
    <string>item2</string>
    <integer>42</integer>
    <true/>
    <false/>
    <null/>
  </array>
</plist>`;

const result = plist.parse(xml);
// Result: ["item1", "item2", 42, true, false, null]

Building

Converts JavaScript objects into plist XML strings.

/**
 * Generate an XML plist string from the input object
 * @param {*} obj - the object to convert
 * @param {Object} [opts] - optional options object
 * @param {boolean} [opts.pretty=true] - whether to format the XML with indentation
 * @returns {string} converted plist XML string
 */
function build(obj, opts);

Usage Examples:

const plist = require('plist');

// Build from simple object
const data = {
  CFBundleDisplayName: "My Application",
  CFBundleVersion: "1.2.3",
  LSRequiresIPhoneOS: true,
  UIDeviceFamily: [1, 2]
};

const xml = plist.build(data);
console.log(xml);

// Build with options (disable pretty printing)
const compactXml = plist.build(data, { pretty: false });

// Build from array
const array = ["string", 123, true, false, null, new Date()];
const arrayXml = plist.build(array);

Supported Data Types

JavaScript to Plist Conversion

String → <string>
Number (integer) → <integer>
Number (float) → <real>
BigInt → <integer>
Boolean → <true> or <false>
Date → <date> (ISO 8601 format)
Array → <array>
Object → <dict>
Buffer → <data> (base64 encoded)
ArrayBuffer → <data> (base64 encoded)
TypedArray → <data> (base64 encoded)
null → <null>
undefined → (ignored)

Plist to JavaScript Conversion

<string> → String
<integer> → Number
<real> → Number
<true> → Boolean (true)
<false> → Boolean (false)
<date> → Date object
<array> → Array
<dict> → Object
<data> → Buffer (base64 decoded)
<null> → null

Error Handling

The parse function throws Error objects in the following cases:

Malformed XML document: When the XML cannot be parsed
Invalid root element: When the document root is not <plist>
Missing keys in dictionaries: When <dict> elements have unbalanced key-value pairs
Empty required elements: When <integer>, <real>, or <date> elements are empty
Invalid plist tags: When encountering unknown XML elements
Prototype pollution protection: When encountering __proto__ keys (CVE-2022-22912)

try {
  const result = plist.parse(invalidXml);
} catch (error) {
  console.error('Parsing failed:', error.message);
}

Browser Usage

For browser environments, include the distributed file:

<script src="node_modules/plist/dist/plist.js"></script>
<script>
  // Global plist object is available
  const parsed = plist.parse(xmlString);
  const built = plist.build(dataObject);
</script>

Separate build and parse modules are also available:

<script src="node_modules/plist/dist/plist-parse.js"></script>
<script src="node_modules/plist/dist/plist-build.js"></script>

Types

// Build options interface
interface BuildOptions {
  pretty?: boolean; // Whether to format with indentation (default: true)
}

// Supported input types for build function
type PlistValue = 
  | string 
  | number 
  | bigint
  | boolean 
  | Date 
  | null 
  | undefined
  | Buffer 
  | ArrayBuffer
  | PlistValue[] 
  | { [key: string]: PlistValue };

// Parse output can be any valid JavaScript value
type ParseResult = any;

Dependencies

This package has the following runtime dependencies:

@xmldom/xmldom: XML DOM parser for Node.js environments
base64-js: Base64 encoding/decoding utilities for binary data handling
xmlbuilder: XML document builder for generating well-formed plist XML