0
# Plist
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: plist
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install plist`
10
- **Node.js Version**: >=10.4.0
11

12
## Core Imports
13

14
```javascript
15
const plist = require('plist');
16
```
17

18
For ES modules:
19

20
```javascript
21
import * as plist from 'plist';
22
```
23

24
Individual functions:
25

26
```javascript
27
const { parse, build } = require('plist');
28
```
29

30
## Basic Usage
31

32
```javascript
33
const plist = require('plist');
34

35
// Parse a plist XML string
36
const xml = `<?xml version="1.0" encoding="UTF-8"?>
37
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
38
<plist version="1.0">
39
  <dict>
40
    <key>name</key>
41
    <string>MyApp</string>
42
    <key>version</key>
43
    <string>1.0.0</string>
44
  </dict>
45
</plist>`;
46

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

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

56
## Capabilities
57

58
### Parsing
59

60
Converts plist XML strings into JavaScript objects.
61

62
```javascript { .api }
63
/**
64
 * Parses a Plist XML string and returns a JavaScript object
65
 * @param {string} xml - the XML String to decode
66
 * @returns {*} the decoded value from the Plist XML
67
 * @throws {Error} if malformed document or invalid plist structure
68
 */
69
function parse(xml);
70
```
71

72
**Usage Examples:**
73

74
```javascript
75
const plist = require('plist');
76
const fs = require('fs');
77

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

82
// Parse inline XML
83
const xml = `<?xml version="1.0" encoding="UTF-8"?>
84
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
85
<plist version="1.0">
86
  <array>
87
    <string>item1</string>
88
    <string>item2</string>
89
    <integer>42</integer>
90
    <true/>
91
    <false/>
92
    <null/>
93
  </array>
94
</plist>`;
95

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

100
### Building
101

102
Converts JavaScript objects into plist XML strings.
103

104
```javascript { .api }
105
/**
106
 * Generate an XML plist string from the input object
107
 * @param {*} obj - the object to convert
108
 * @param {Object} [opts] - optional options object
109
 * @param {boolean} [opts.pretty=true] - whether to format the XML with indentation
110
 * @returns {string} converted plist XML string
111
 */
112
function build(obj, opts);
113
```
114

115
**Usage Examples:**
116

117
```javascript
118
const plist = require('plist');
119

120
// Build from simple object
121
const data = {
122
  CFBundleDisplayName: "My Application",
123
  CFBundleVersion: "1.2.3",
124
  LSRequiresIPhoneOS: true,
125
  UIDeviceFamily: [1, 2]
126
};
127

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

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

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

139
## Supported Data Types
140

141
### JavaScript to Plist Conversion
142

143
- **String** → `<string>`
144
- **Number (integer)** → `<integer>`
145
- **Number (float)** → `<real>`
146
- **BigInt** → `<integer>`
147
- **Boolean** → `<true>` or `<false>`
148
- **Date** → `<date>` (ISO 8601 format)
149
- **Array** → `<array>`
150
- **Object** → `<dict>`
151
- **Buffer** → `<data>` (base64 encoded)
152
- **ArrayBuffer** → `<data>` (base64 encoded)
153
- **TypedArray** → `<data>` (base64 encoded)
154
- **null** → `<null>`
155
- **undefined** → (ignored)
156

157
### Plist to JavaScript Conversion
158

159
- **`<string>`** → String
160
- **`<integer>`** → Number
161
- **`<real>`** → Number
162
- **`<true>`** → Boolean (true)
163
- **`<false>`** → Boolean (false)
164
- **`<date>`** → Date object
165
- **`<array>`** → Array
166
- **`<dict>`** → Object
167
- **`<data>`** → Buffer (base64 decoded)
168
- **`<null>`** → null
169

170
## Error Handling
171

172
The `parse` function throws `Error` objects in the following cases:
173

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

181
```javascript
182
try {
183
  const result = plist.parse(invalidXml);
184
} catch (error) {
185
  console.error('Parsing failed:', error.message);
186
}
187
```
188

189
## Browser Usage
190

191
For browser environments, include the distributed file:
192

193
```html
194
<script src="node_modules/plist/dist/plist.js"></script>
195
<script>
196
  // Global plist object is available
197
  const parsed = plist.parse(xmlString);
198
  const built = plist.build(dataObject);
199
</script>
200
```
201

202
Separate build and parse modules are also available:
203

204
```html
205
<script src="node_modules/plist/dist/plist-parse.js"></script>
206
<script src="node_modules/plist/dist/plist-build.js"></script>
207
```
208

209
## Types
210

211
```javascript { .api }
212
// Build options interface
213
interface BuildOptions {
214
  pretty?: boolean; // Whether to format with indentation (default: true)
215
}
216

217
// Supported input types for build function
218
type PlistValue = 
219
  | string 
220
  | number 
221
  | bigint
222
  | boolean 
223
  | Date 
224
  | null 
225
  | undefined
226
  | Buffer 
227
  | ArrayBuffer
228
  | PlistValue[] 
229
  | { [key: string]: PlistValue };
230

231
// Parse output can be any valid JavaScript value
232
type ParseResult = any;
233
```
234

235
## Dependencies
236

237
This package has the following runtime dependencies:
238

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