### Install @plist/xml.serialize

Source: https://github.com/mat-sz/plist/blob/main/packages/xml.serialize/README.md

Install the library using npm or yarn.

```sh
npm install @plist/xml.serialize
# or:
yarn install @plist/xml.serialize
```

--------------------------------

### Install @plist/xml.parse

Source: https://github.com/mat-sz/plist/blob/main/packages/xml.parse/README.md

Install the library using npm or yarn.

```sh
npm install @plist/xml.parse
# or:
yarn install @plist/xml.parse
```

--------------------------------

### Install @plist/binary.serialize

Source: https://github.com/mat-sz/plist/blob/main/packages/binary.serialize/README.md

Install the library using npm or yarn.

```sh
npm install @plist/binary.serialize
# or:
yarn install @plist/binary.serialize
```

--------------------------------

### Install @plist/serialize

Source: https://github.com/mat-sz/plist/blob/main/packages/serialize/README.md

Install the library using npm or yarn.

```sh
npm install @plist/serialize
# or:
yarn install @plist/serialize
```

--------------------------------

### Install @plist/binary.parse

Source: https://github.com/mat-sz/plist/blob/main/packages/binary.parse/README.md

Install the library using npm or yarn.

```sh
npm install @plist/binary.parse
# or:
yarn install @plist/binary.parse
```

--------------------------------

### Install @plist/plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Install the library using npm. This is the first step before using any of its functionalities.

```bash
npm install @plist/plist
```

--------------------------------

### Install @plist/openstep.parse

Source: https://github.com/mat-sz/plist/blob/main/packages/openstep.parse/README.md

Install the library using npm or yarn.

```sh
npm install @plist/openstep.parse
# or:
yarn install @plist/openstep.parse
```

--------------------------------

### Install OpenStep Serialize

Source: https://github.com/mat-sz/plist/blob/main/packages/openstep.serialize/README.md

Install the @plist/openstep.serialize package using npm or yarn.

```sh
npm install @plist.openstep.serialize
# or:
yarn install @plist.openstep.serialize
```

--------------------------------

### Install @plist/common

Source: https://github.com/mat-sz/plist/blob/main/packages/common/README.md

Install the @plist/common package using npm or yarn.

```sh
npm install @plist/common
# or:
yarn install @plist/common
```

--------------------------------

### Trailer Metadata Example

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Provides an example of the trailer's structure, showing how metadata like offset size, object reference size, number of objects, root object index, and offset table offset are encoded.

```plaintext
[6 null bytes]
[0x01]              // 1-byte offsets
[0x01]              // 1-byte object references
[0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x0A]  // 10 objects
[0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00]  // Root is object 0
[0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x50]  // Offset table at byte 80
```

--------------------------------

### Usage Example for Dictionary Type

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/types.md

Demonstrates how to create and use a Dictionary object. Ensure necessary imports are included.

```typescript
import { parse, Dictionary } from '@plist/plist';

const dict: Dictionary = {
  name: 'example',
  count: 42,
  enabled: true,
  data: new ArrayBuffer(5),
  nested: {
    key: 'value'
  },
  items: ['a', 'b', 'c']
};

const serialized = serialize(dict);
```

--------------------------------

### String Encoding Examples

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Shows examples of ASCII and UTF-16 strings in both short and long forms. Lengths are encoded in the info nibble or a length marker.

```plaintext
0x55 0x48 0x65 0x6C 0x6C 0x6F  // 5-char ASCII: "Hello"
0x5F 0x10 0x00 0x10 ...         // Long ASCII string with length marker
0x64 'H' 0x00 'e' 0x00 'l' 0x00 'l' 0x00 'o' 0x00  // 4-char UTF-16: "Hello"
```

--------------------------------

### Install @plist/plist with npm or yarn

Source: https://github.com/mat-sz/plist/blob/main/README.md

Use npm or yarn to add the @plist/plist library to your project dependencies.

```sh
npm install @plist/plist
# or:
yarn install @plist/plist
```

--------------------------------

### Dictionary Encoding Example

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Illustrates the encoding of a dictionary, showing the number of pairs followed by object references for keys and then for values.

```plaintext
0xD2 0x00 0x01 0x02 0x03  // 2 pairs
// Key refs: 0x00, 0x01
// Value refs: 0x02, 0x03
```

--------------------------------

### Example: Detect Binary Property List Format

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/types.md

Shows how to use the HEADER_BINARY constant to detect if a given ArrayBuffer contains a binary property list.

```typescript
import { HEADER_BINARY, detectFormat } from '@plist/plist';

const binaryData = new ArrayBuffer(/* ... */);
const view = new Uint8Array(binaryData);
const header = String.fromCharCode(...view.slice(0, 8));
if (header === HEADER_BINARY) {
  // This is a binary plist
}
```

--------------------------------

### Array Encoding Example

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Demonstrates the encoding of an array, where the info nibble or length marker specifies the number of items followed by their object references.

```plaintext
0xA3 0x00 0x01 0x02  // Array of 3 items: references to objects 0, 1, 2
```

--------------------------------

### Data Blob Examples

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Illustrates the short and long forms for encoding raw binary data. The info nibble or a length marker indicates the data's length.

```plaintext
0x45 0xAA 0xBB 0xCC 0xDD 0xEE  // 5 bytes of data
0x4F 0x10 0x01 0x00 ...         // Large data with length marker
```

--------------------------------

### API Reference - Core Functions

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/MANIFEST.txt

This section details the core functions exported by the @plist/plist library, including parsing, serialization, and format detection. It provides function signatures, parameters, return types, and usage examples.

```APIDOC
## @plist/plist (main entry)

### Description
Provides the main interface for interacting with the plist library.

### Functions
- **parse(input: string | Buffer | ArrayBuffer, options?: ParseOptions): any**
  - Parses a plist string or buffer into a JavaScript object.
  - Supports format detection.

- **serialize(data: any, options?: SerializeOptions): string | Buffer**
  - Serializes a JavaScript object into a plist string or buffer.
  - Supports various plist formats.

## @plist/parse (format detection)

### Description
Module specifically for detecting the format of a plist input.

### Functions
- **detectFormat(input: string | Buffer | ArrayBuffer): PlistFormat | null**
  - Detects the plist format of the given input.

## @plist/serialize (format selection)

### Description
Module for selecting and applying specific plist serialization formats.

### Functions
- **serializeToFormat(data: any, format: PlistFormat, options?: SerializeOptions): string | Buffer**
  - Serializes data into a specified plist format.
```

--------------------------------

### Parse and Serialize Property Lists

Source: https://github.com/mat-sz/plist/blob/main/README.md

Import the parse and serialize functions to convert between Property List data and JavaScript objects. This example demonstrates serializing an object and then parsing it back.

```typescript
import { parse, serialize } from '@plist/plist';

parse(serialize({ hello: 'world' })); // => { hello: 'world' }
```

--------------------------------

### Binary Plist Header Magic Number

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

The file must start with 'bplist00' to identify the format and version. The parser validates this at offset 0.

```text
bplist00
```

--------------------------------

### Examples of Valid Value Types

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/types.md

Illustrates various data types that conform to the `Value` type, including null, strings, numbers, BigInt, booleans, ArrayBuffer, Date, Dictionaries, and arrays. This helps in understanding the scope of data that can be handled.

```typescript
import { parse, serialize, Value } from '@plist/plist';

// All valid Value types
const examples: Value[] = [
  null,
  'hello',
  42,
  3.14,
  BigInt('9007199254740992'),
  true,
  new ArrayBuffer(10),
  new Date(),
  { key: 'value' },
  [1, 'two', true]
];

// Type-safe handling
const result: Value = parse(someInput);
if (typeof result === 'object' && !Array.isArray(result)) {
  const dict = result as Dictionary;
  console.log(dict.key);
}
```

--------------------------------

### Serialize Function Entry Point

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/serialization-architecture.md

The main entry point for serialization. Accepts a value and an optional format, defaulting to XML, and routes to the appropriate format-specific serializer.

```typescript
type ISerialize = {
  (input: Value, format: PlistFormat.XML): string;
  (input: Value, format: PlistFormat.OPENSTEP): string;
  (input: Value, format: PlistFormat.BINARY): ArrayBuffer;
};

export const serialize: ISerialize = (
  input: Value,
  format: PlistFormat = PlistFormat.XML
): any => {
  switch (format) {
    case PlistFormat.XML:
      return serializeXML(input);
    case PlistFormat.BINARY:
      return serializeBinary(input);
    case PlistFormat.OPENSTEP:
      return serializeOpenstep(input);
  }
  
  throw new Error('Unsupported format.');
};

```

--------------------------------

### Module Hierarchy Diagram

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/serialization-architecture.md

Illustrates the package structure and dependencies within the plist serialization system.

```text
@plist/plist (main entry point)
├── @plist/serialize (format routing + dispatch)
│   ├── @plist/binary.serialize
│   ├── @plist/xml.serialize
│   └── @plist/openstep.serialize
└── @plist/common (shared types)

```

--------------------------------

### Error: Unsupported format (Serialize)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

This error occurs when the provided format is not one of the three standard formats: BINARY, XML, or OPENSTEP.

```text
Error: "Unsupported format."
```

--------------------------------

### Convert Plist Between Formats

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Demonstrates converting a plist from XML format to binary format. This is useful for optimizing storage or transfer size.

```typescript
import { parse, serialize, PlistFormat } from '@plist/plist';

// Read XML, convert to binary
const xmlContent = readFileSync('input.plist', 'utf-8');
const data = parse(xmlContent);
const binaryBuffer = serialize(data, PlistFormat.BINARY);
```

--------------------------------

### Main API Entry Points

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

The main API provides functions for parsing and serializing plists with auto-detection of the format.

```APIDOC
## Main API

### Description
Provides the primary interface for parsing and serializing plist data with automatic format detection.

### Import
```javascript
import { parse, serialize } from "@plist/plist";
```

### Usage
```javascript
// Parsing a plist
const data = parse("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!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>example</string></dict></plist>");
console.log(data); // Output: { name: 'example' }

// Serializing data
const xmlString = serialize({ name: "example" });
console.log(xmlString); // Output: XML string representation of the plist
```
```

--------------------------------

### Package Reference

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/MANIFEST.txt

Overview of the npm packages that constitute the @plist/plist library, including main and format-specific packages.

```APIDOC
## Packages

### Main Packages
- **@plist/plist**: The primary package.
- **@plist/parse**: For format detection.
- **@plist/serialize**: For format selection.

### Format-Specific Packages
- **@plist/binary**
- **@plist/xml**
- **@plist/openstep**
- **@plist/common**

### Other Information
- Package dependencies and tree.
- Build configuration.
- External dependencies.
- Version and license information.
```

--------------------------------

### Import and Use Plist Package

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Import top-level functions from the @plist/plist package to detect format, parse, and serialize property lists.

```typescript
import { parse, serialize, detectFormat, PlistFormat } from '@plist/plist';

const format = detectFormat(input);
const data = parse(input);
const result = serialize(data, PlistFormat.BINARY);
```

--------------------------------

### Parse Binary Property List from ArrayBuffer

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

This function parses binary property list data from an ArrayBuffer. The buffer must start with the 'bplist00' header. Be aware of limits on object count and size, and that '__proto__' keys are rejected for security.

```typescript
import { parse } from '@plist/binary.parse';

const buffer = new ArrayBuffer(/* binary plist data */);
const data = parse(buffer);
```

--------------------------------

### High-Level Serialize Flow

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/serialization-architecture.md

Visualizes the process from input value to serialized output, showing format routing.

```text
Value (input)
    ↓
serialize(value, format?)
    ↓
    ├─→ BINARY? → serializeBinary() → ArrayBuffer
    ├─→ XML? → serializeXML() → string
    └─→ OPENSTEP? → serializeOpenstep() → string
    ↓
Output (string | ArrayBuffer)

```

--------------------------------

### Main Entry Points: Parse and Detect Format

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Provides functions to automatically detect the format of a property list input and parse it into a JavaScript object. It also shows how to serialize data into different formats.

```APIDOC
## Main Entry Points

### Parse and Detect Format

This section covers the primary functions for parsing property list data and detecting its format.

#### `parse(input: Input)`

**Description**: Auto-detects the format of the input and parses it into a JavaScript object.

**Usage**: 
```typescript
import { parse } from '@plist/plist';
const data = parse(input);
```

#### `detectFormat(input: Input)`

**Description**: Detects the format of the input property list.

**Usage**: 
```typescript
import { detectFormat } from '@plist/plist';
const format = detectFormat(input);
```

#### `serialize(data: Value, format: PlistFormat)`

**Description**: Serializes the given data into the specified property list format.

**Usage**: 
```typescript
import { serialize, PlistFormat } from '@plist/plist';
const result = serialize(data, PlistFormat.BINARY);
```

### Format-Specific Parsers and Serializers

This section provides access to format-specific parsing and serialization functions.

#### Binary Format

- **Parse**: `import { parse as parseBinary } from '@plist/binary.parse';`
- **Serialize**: `import { serialize as serializeBinary } from '@plist/binary.serialize';`

#### XML Format

- **Parse**: `import { parse as parseXML } from '@plist/xml.parse';`
- **Serialize**: `import { serialize as serializeXML } from '@plist/xml.serialize';`

#### OpenStep Format

- **Parse**: `import { parse as parseOpenStep } from '@plist/openstep.parse';`
- **Serialize**: `import { serialize as serializeOpenStep } from '@plist/openstep.serialize';`

### Types and Constants

This section exports essential types and constants for working with property lists.

- **Types**: `Value`, `Dictionary`, `PlistFormat`
- **Constants**: `EPOCH`, `HEADER_BINARY`, `HEADER_OPENSTEP_UTF8`

**Usage**: 
```typescript
import { Value, Dictionary, PlistFormat } from '@plist/plist';
import { EPOCH, HEADER_BINARY, HEADER_OPENSTEP_UTF8 } from '@plist/common';

type MyPlist = Value;
type MyDict = Dictionary;
```
```

--------------------------------

### Binary Plist File Structure

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

A binary plist file is composed of a header, objects section, offset table, and a trailer.

```text
[Header (8 bytes)]
[Objects (variable length)]
[Offset Table (variable length)]
[Trailer (32 bytes)]
```

--------------------------------

### Package Build Commands

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

These commands are used to build the packages in both CommonJS and ES Modules formats, and for linting.

```json
{
  "build": "npm run build:cjs && npm run build:esm",
  "build:cjs": "tsc --module commonjs --outDir lib/cjs",
  "build:esm": "tsc --module esnext --outDir lib/esm",
  "lint": "eslint src"
}
```

--------------------------------

### Convert Plist Data Between Formats

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Shows how to parse plist data and then serialize it into different formats: BINARY, XML, and OPENSTEP. This is useful for interoperability with various systems.

```typescript
const data = parse(inputData);
const binaryOutput = serialize(data, PlistFormat.BINARY);
const xmlOutput = serialize(data, PlistFormat.XML);
const openstepOutput = serialize(data, PlistFormat.OPENSTEP);
```

--------------------------------

### Serialize Data with Different Plist Formats

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/types.md

Demonstrates how to serialize a JavaScript object into different Plist formats using the `serialize` function and the `PlistFormat` enum. Ensure the `@plist/plist` package is imported.

```typescript
import { PlistFormat, serialize } from '@plist/plist';

const data = { key: 'value' };
const binaryResult = serialize(data, PlistFormat.BINARY);
const xmlResult = serialize(data, PlistFormat.XML);
const openstepResult = serialize(data, PlistFormat.OPENSTEP);
```

--------------------------------

### Module Dependencies for Plist Parsing

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/parsing-architecture.md

Illustrates the dependency tree for the '@plist/parse' module, including its direct dependencies and re-exports. Note the external libraries required by the XML parser.

```plaintext
@plist/parse
├── depends on:
│   ├── @plist/common (Value, Dictionary types)
│   ├── @plist/binary.parse
│   ├── @plist/xml.parse (depends on fast-xml-parser, base64-js)
│   └── @plist/openstep.parse
└── re-exported by:
    └── @plist/plist
```

--------------------------------

### Binary Format Specification

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/MANIFEST.txt

Detailed specification of the binary plist format (bplist00), including file structure, object types, and encoding.

```APIDOC
## Binary Plist Format (bplist00)

### File Structure
- Header
- Objects
- Offset table
- Trailer

### Object Types and Encoding
- Detailed breakdown of object types and their byte-level encoding.

### Type/Info Byte Format
- Specification of the type and info byte.

### Length Markers
- Handling of length markers for large containers.

### Offset Table and Trailer Format
- Structure and encoding of the offset table and trailer.

### Serialization Details
- Specifics related to binary plist serialization.

### Limits and Constraints
- Documented limits and constraints for the binary format.
```

--------------------------------

### Error: Unhandled entry type (Binary)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

An internal error during binary serialization where an entry has an unrecognized type.

```text
Error: "unhandled entry type: X"
```

--------------------------------

### @plist/plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

The main entry point for the plist library, providing a universal interface for parsing and serializing Apple's Property Lists in various formats. It re-exports top-level functions from the parse and serialize packages.

```APIDOC
## Package @plist/plist

### Description
Universal TypeScript library for parsing and serializing Apple's Property Lists. Supports binary, XML, and OpenStep/NEXTStep formats. Works in browsers and Node.js.

### Exports
- `detectFormat`: Detects the format of the property list.
- `parse`: Parses the property list data.
- `serialize`: Serializes data into a property list format.
- `PlistFormat`: Enum for specifying property list formats.

### Usage
```typescript
import { parse, serialize, detectFormat, PlistFormat } from '@plist/plist';

const format = detectFormat(input);
const data = parse(input);
const result = serialize(data, PlistFormat.BINARY);
```
```

--------------------------------

### Parse and Serialize OpenStep Plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Employ the `@plist/openstep.parse` and `@plist/openstep.serialize` modules for OpenStep formatted plists.

```typescript
import { parse } from '@plist/openstep.parse';
import { serialize } from '@plist/openstep.serialize';

const openstep = serialize({ key: 'value' });
const result = parse(openstep);
```

--------------------------------

### Parse and Serialize Binary Plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Utilize the `@plist/binary.parse` and `@plist/binary.serialize` modules for handling binary plist files.

```typescript
import { parse } from '@plist/binary.parse';
import { serialize } from '@plist/binary.serialize';

const buffer = serialize({ key: 'value' });
const result = parse(buffer);
```

--------------------------------

### Error: Unhandled entry (Binary)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

An internal error indicating that a value cannot be converted to a serialization entry during binary serialization.

```text
Error: "unhandled entry: X"
```

--------------------------------

### Import and Use Serialize Package

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Import functions from the @plist/serialize package to serialize data into different property list formats. Type-safe overloads ensure the correct return type based on the specified format.

```typescript
import { serialize, PlistFormat } from '@plist/serialize';

const binary = serialize(data, PlistFormat.BINARY);
const xml = serialize(data, PlistFormat.XML);
const openstep = serialize(data, PlistFormat.OPENSTEP);
```

--------------------------------

### Write Trailer for Plist Serialization

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/serialization-architecture.md

Appends the trailer to the buffer, containing metadata such as offset size, object reference size, object count, root object index, and the offset table's position.

```typescript
function writeTrailer() {
  buffer = concat(buffer, nullBytes);  // 6 null bytes
  buffer = concat(buffer, new Uint8Array([
    offsetSizeInBytes,    // Offset size
    idSizeInBytes         // Object ref size
  ]));
  buffer = writeUInt(buffer, BigInt(entries.length), 8);  // Object count
  buffer = writeUInt(buffer, BigInt('0'), 8);             // Root object (always 0)
  buffer = writeUInt(buffer, BigInt(offsetTableOffset), 8); // Offset table offset
}
```

--------------------------------

### @plist/binary.serialize

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Serializes JavaScript values into the binary property list format. This is a low-level serializer; prefer @plist/serialize for format selection.

```APIDOC
## @plist/binary.serialize

### Description
Low-level serializer for binary property list format. Direct use is rare; prefer @plist/serialize for format selection.

### Exports
```typescript
export const serialize = (value: Value): ArrayBuffer
```

### Usage
```typescript
import { serialize } from '@plist/binary.serialize';

const data = { key: 'value', count: 42 };
const binaryBuffer = serialize(data);
```

### Optimizations
- Automatic string deduplication
- Intelligent integer size selection (1, 2, 4, 8, or 16 bytes)
- UTF-8 vs. UTF-16 detection per string
- Minimal offset table size computation
```

--------------------------------

### @plist/binary.parse

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Parses binary property list format (bplist00). This is a low-level parser and @plist/parse is generally recommended for automatic format detection.

```APIDOC
## @plist/binary.parse

### Description
Low-level parser for binary property list format (bplist00). Direct use is rare; prefer @plist/parse for automatic format detection.

### Exports
```typescript
export const parse = (buffer: ArrayBuffer): Value
```

### Usage
```typescript
import { parse } from '@plist/binary.parse';

const binaryBuffer = new ArrayBuffer(/* ... */);
const data = parse(binaryBuffer);
```

### Constraints
- Input must be binary plist (start with 'bplist00')
- Must be passed as ArrayBuffer
- Enforces max 32,768 objects and 100 MB per object
```

--------------------------------

### parse

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Parses a property list with automatic format detection. This function is identical to the main export from the `@plist/plist` package.

```APIDOC
## parse (from @plist/parse)

### Description
Parse a property list with automatic format detection. Identical to the main `@plist/plist` export.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (string | ArrayBuffer) - Required - The property list data to parse.

### Return
`Value` - The parsed property list data.

### Throws
- **Error**: If format is invalid, unrecognized, or if binary plist is passed as string.

### Example
```typescript
import { parse } from '@plist/parse';

const data = parse(plistString);
```
```

--------------------------------

### serialize

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Serialize a value into a property list format. Returns a string for XML and OpenStep formats, or ArrayBuffer for binary format.

```APIDOC
## serialize

### Description
Serialize a value into a property list format. Returns a string for XML and OpenStep formats, or ArrayBuffer for binary format.

### Method
```typescript
serialize(input: Value, format?: PlistFormat): string | ArrayBuffer
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (Value) - Required - The JavaScript value to serialize. Can be a primitive, array, or object.
- **format** (PlistFormat) - Optional - The output format: PlistFormat.XML, PlistFormat.BINARY, or PlistFormat.OPENSTEP.

### Request Example
```typescript
import { serialize, PlistFormat } from '@plist/plist';

const data = { hello: 'world', count: 42 };

// Serialize to XML (default)
const xmlString = serialize(data);
// Output: <?xml version="1.0"?>...

// Serialize to binary
const binaryBuffer = serialize(data, PlistFormat.BINARY);

// Serialize to OpenStep
const openStepString = serialize(data, PlistFormat.OPENSTEP);
```

### Response
#### Success Response (200)
- **string | ArrayBuffer** — XML and OpenStep formats return a string; binary format returns an ArrayBuffer.

#### Response Example
```json
{
  "example": "serialized plist data"
}
```

### Throws
- **Error** - If the format is unsupported or if the value contains unsupported types.
```

--------------------------------

### Parse and Modify Plist Data

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Demonstrates how to parse plist input, create a modified version by adding or updating a key, and then serialize it back to a string. Requires importing parse, serialize, and PlistFormat.

```typescript
import { parse, serialize, PlistFormat } from '@plist/plist';

const original = parse(input);
const modified = { ...original, newKey: 'newValue' };
const output = serialize(modified);
```

--------------------------------

### Parse Binary Property List

Source: https://github.com/mat-sz/plist/blob/main/packages/binary.parse/README.md

Import the parse function and use it to parse a binary Property List from a Uint8Array buffer. Ensure necessary modules like readFileSync and path are available.

```ts
import { parse } from '@plist/binary.parse';

const { buffer } = new Uint8Array(
  readFileSync(path.join(TEST_FILE_PATH, 'data_types', 'dict.plist'))
);
const dict = parse(buffer);
// => { hello: "world", whats: "up" }
```

--------------------------------

### Serialize Data to Binary Property List

Source: https://github.com/mat-sz/plist/blob/main/packages/binary.serialize/README.md

Import the `serialize` function and use it to convert a JavaScript object into a binary Property List format. The output is an ArrayBuffer.

```typescript
import { serialize } from '@plist/binary.serialize';

const binary = serialize({
  dictionary: {
    hello: 'world',
  },
});
// => ArrayBuffer
```

--------------------------------

### Offset Table Structure

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/binary-format-reference.md

Illustrates the format of the offset table, which maps object indices to their byte offsets within the objects section. Each entry's size depends on the offsetSize specified in the trailer.

```plaintext
[offset to object 0]   // 4 bytes
[offset to object 1]   // 4 bytes
[offset to object 2]   // 4 bytes
...
```

--------------------------------

### Core API Functions

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/MANIFEST.txt

The main entry points for interacting with the Plist library. These functions allow for parsing, serialization, and format detection of property list data.

```APIDOC
## Core API Functions

### Description
Provides the primary interface for working with property lists. Includes functions to parse data into a JavaScript value, serialize a JavaScript value into a property list format, and automatically detect the format of given data.

### Functions

#### `parse(input: string | ArrayBuffer): Value`

Parses a property list from a string or ArrayBuffer into a JavaScript `Value`.

#### `serialize(input: Value, format?: PlistFormat): string | ArrayBuffer`

Serializes a JavaScript `Value` into a property list format. The `format` parameter can be used to specify BINARY, XML, or OPENSTEP. If omitted, a default format may be used.

#### `detectFormat(input: string | ArrayBuffer): PlistFormat`

Detects the property list format (BINARY, XML, or OPENSTEP) of the provided input data.
```

--------------------------------

### parse (from @plist/openstep.parse)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Parses OpenStep property list content from a string into a JavaScript Value object.

```APIDOC
## parse (from @plist/openstep.parse)

### Description
Parse an OpenStep property list (NextStep text format). Supports dictionary syntax `{}`, array syntax `()`, quoted and unquoted strings, hex data `<>`, and dates.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **input** (string) - Required - OpenStep plist content as a string.

### Request Example
```typescript
import { parse } from '@plist/openstep.parse';

const openstep = '{ name = test; count = 42; items = (a, b, c); }';
const data = parse(openstep);
// => { name: 'test', count: 42, items: ['a', 'b', 'c'] }
```

### Response
#### Success Response (200)
- **Value** - The parsed property list data.

#### Response Example
```json
{
  "name": "test",
  "count": 42,
  "items": [
    "a",
    "b",
    "c"
  ]
}
```

### Throws
- **Error** - If syntax is invalid, unmatched braces/parentheses, invalid hex data, or unexpected content at end. Rejects '__proto__' keys for prototype pollution protection.
```

--------------------------------

### Serialize to Binary Property List

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Use this low-level serializer for binary property list format. It optimizes by deduplicating strings, selecting intelligent integer sizes, and detecting UTF-8 vs. UTF-16 per string. Prefer @plist/serialize for format selection.

```typescript
import { serialize } from '@plist/binary.serialize';

const data = { key: 'value', count: 42 };
const binaryBuffer = serialize(data);
```

--------------------------------

### @plist/parse

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Provides automatic format detection and parsing capabilities for binary, XML, and OpenStep property lists. It allows users to determine the format of a property list and then parse its content.

```APIDOC
## Package @plist/parse

### Description
Provides automatic format detection and parsing for binary, XML, and OpenStep property lists.

### Exports
- `detectFormat(input: string | ArrayBuffer): PlistFormat`: Detects the format of the property list.
- `parse(input: string | ArrayBuffer): Value`: Parses the property list data, handling all supported formats.

### Usage
```typescript
import { parse, detectFormat, PlistFormat } from '@plist/parse';

const format = detectFormat(data);
if (format === PlistFormat.BINARY) {
  const result = parse(data); // parse handles all formats
}
```
```

--------------------------------

### Parse OpenStep/NEXTStep Property Lists

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Use this parser to convert OpenStep/NEXTStep formatted strings into JavaScript objects. It supports various data types, comments, and offers protection against prototype pollution.

```typescript
import { parse } from '@plist/openstep.parse';

const openstep = '{ name = test; count = 42; items = (a, b, c); }';
const data = parse(openstep);
// => { name: 'test', count: 42, items: ['a', 'b', 'c'] }
```

--------------------------------

### Read Plist from File (Node.js)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Reads a plist file from the file system and parses its content into a JavaScript object. Ensure the file exists and is accessible.

```typescript
import { readFileSync } from 'fs';
import { parse } from '@plist/plist';

const content = readFileSync('config.plist', 'utf-8');
const config = parse(content);
```

--------------------------------

### Build and Wrap XML Document

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/serialization-architecture.md

Serializes a JavaScript value into an XML string using fast-xml-parser's builder and then wraps the result with the standard XML declaration, DOCTYPE, and plist tags. Configured to preserve element order and suppress empty nodes.

```typescript
export const serialize = (value: Value): string => {
  const xml = builder.build([serializeValue(value)]);
  
  return `<?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">
${xml}
</plist>`;
};
```

```typescript
const builder = new XMLBuilder({
  preserveOrder: true,      // Keep element order
  suppressEmptyNode: true,  // Don't output empty nodes
});
```

--------------------------------

### Parse Function Entry Point

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/parsing-architecture.md

This function detects the input plist format and delegates parsing to the correct format-specific parser. It handles ArrayBuffer to string conversion for text-based formats and throws an error for unsupported formats or incorrect input types.

```typescript
export const parse = (input: string | ArrayBuffer): Value => {
  const format = detectFormat(input);  // Step 1: Detect format
  
  switch (format) {
    case PlistFormat.BINARY:
      if (typeof input === 'string') {
        throw new Error('Binary plists must be passed as ArrayBuffer');
      }
      return parseBinary(input);      // Step 2a: Route to binary parser
      
    case PlistFormat.XML:
      if (input instanceof ArrayBuffer) {
        return parseXML(DECODER.decode(input));  // Step 2b: Convert and route
      }
      return parseXML(input);
      
    case PlistFormat.OPENSTEP:
      if (input instanceof ArrayBuffer) {
        return parseOpenstep(DECODER.decode(input));
      }
      return parseOpenstep(input);
  }
  
  throw new Error('Unsupported format');
};
```

--------------------------------

### Serialize to OpenStep/NEXTStep Property Lists

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Use this serializer to convert JavaScript objects into OpenStep/NEXTStep formatted strings. It handles quoting strings only when necessary and represents booleans and numbers in their standard formats.

```typescript
import { serialize } from '@plist/openstep.serialize';

const data = { name: 'test', count: 42 };
const openstep = serialize(data);
// Output: { name = test; count = 42; }
```

--------------------------------

### Format-Specific OpenStep Serialization

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Import and use the dedicated OpenStep serializer for creating OpenStep plist data. Imports are required.

```typescript
import { serialize as serializeOpenStep } from '@plist/openstep.serialize';
```

--------------------------------

### Error: Unsupported int size (Binary)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

An internal error during integer encoding in binary serialization. The requested integer size must be 1, 2, 4, or 8 bytes.

```text
Error: "Unsupported int size"
```

--------------------------------

### Handling Format-Specific Serialization

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

Illustrates how to handle serialization errors, particularly when dealing with formats like OpenStep that do not support null values. It shows a fallback mechanism to filter out nulls before serializing.

```typescript
// 3. Handle format-specific serialization
try {
  // OpenStep doesn't support null values
  const openstep = serialize(data, PlistFormat.OPENSTEP);
} catch (error) {
  // Fall back to binary or filter out nulls
  const filtered = Object.fromEntries(
    Object.entries(data).filter(([_, v]) => v !== null)
  );
  const openstep = serialize(filtered, PlistFormat.OPENSTEP);
}
```

--------------------------------

### Serialize with Format Selection

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Serialize JavaScript data into a plist format, with the option to explicitly choose the desired format. Imports are required.

```typescript
import { serialize, PlistFormat } from '@plist/plist';
const result = serialize(data, PlistFormat.BINARY);
```

--------------------------------

### Detect Plist Format

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Use `detectFormat` to identify the format of input data. Supported formats include XML, BINARY, and OPENSTEP.

```typescript
import { detectFormat, PlistFormat } from '@plist/parse';

const format = detectFormat(inputData);

switch (format) {
  case PlistFormat.XML:
    console.log('XML format');
    break;
  case PlistFormat.BINARY:
    console.log('Binary format');
    break;
  case PlistFormat.OPENSTEP:
    console.log('OpenStep format');
    break;
}
```

--------------------------------

### Parse and Serialize XML Plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Use the `@plist/xml.parse` and `@plist/xml.serialize` modules for working with XML plist data.

```typescript
import { parse } from '@plist/xml.parse';
import { serialize } from '@plist/xml.serialize';

const xml = serialize({ key: 'value' });
const result = parse(xml);
```

--------------------------------

### Format-Specific Binary Serialization

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Import and use the dedicated binary serializer for creating binary plist data. Imports are required.

```typescript
import { serialize as serializeBinary } from '@plist/binary.serialize';
```

--------------------------------

### detectFormat

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Detects the format (binary, XML, or OpenStep) of a property list without parsing the entire content. It examines the input's structure and headers to determine the format.

```APIDOC
## detectFormat

### Description
Detects the format of a property list without parsing it. Examines the input's structure and headers to determine if it is binary, XML, or OpenStep format.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (string | ArrayBuffer) - Required - The property list data to inspect.

### Return
`PlistFormat` - One of PlistFormat.BINARY, PlistFormat.XML, or PlistFormat.OPENSTEP.

### Throws
- **Error**: If the format cannot be recognized.

### Example
```typescript
import { detectFormat, PlistFormat } from '@plist/parse';

const xmlData = '<?xml version="1.0"?><plist>...';
const format = detectFormat(xmlData); // => PlistFormat.XML

const binaryBuffer = new ArrayBuffer(/* ... */);
const format = detectFormat(binaryBuffer); // => PlistFormat.BINARY
```
```

--------------------------------

### OpenStep Parser: Unmatched Data Bracket Error

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

This error signifies that a data opening bracket '<' is missing its corresponding closing bracket '>'.

```text
Error: "No matching '>' found"
```

--------------------------------

### Importing Types and Constants

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Import common types like Value and Dictionary, as well as constants such as EPOCH and headers, from the common module. Imports are required.

```typescript
import { Value, Dictionary, PlistFormat } from '@plist/plist';
import { EPOCH, HEADER_BINARY, HEADER_OPENSTEP_UTF8 } from '@plist/common';

type MyPlist = Value;
type MyDict = Dictionary;
```

--------------------------------

### Import and Use Parse Package

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Import functions from the @plist/parse package for format detection and parsing of property lists. The parse function handles all supported formats.

```typescript
import { parse, detectFormat, PlistFormat } from '@plist/parse';

const format = detectFormat(data);
if (format === PlistFormat.BINARY) {
  const result = parse(data); // parse handles all formats
}
```

--------------------------------

### Serialize to XML Property List

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Use this serializer for XML property list format, which builds XML using fast-xml-parser. It outputs a standard XML declaration, DOCTYPE, and <plist> root element. Null values will cause an error as they are not supported in this format.

```typescript
import { serialize } from '@plist/xml.serialize';

const data = { greeting: 'hello', count: 42 };
const xml = serialize(data);
// Output: <?xml version="1.0"?>...
```

--------------------------------

### Serialize to Binary Property List

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Use this function to convert JavaScript values into the binary property list format. It optimizes output by deduplicating strings and unwrapping single-element arrays. Ensure values are supported types to avoid errors.

```typescript
import { serialize } from '@plist/binary.serialize';

const data = { name: 'test', count: 42 };
const buffer = serialize(data);
```

--------------------------------

### parse

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Parses binary property list data from an ArrayBuffer. It expects the 'bplist00' header and provides protection against prototype pollution.

```APIDOC
## parse (from @plist/binary.parse)

### Description
Parse a binary property list. Expects an ArrayBuffer with the 'bplist00' header.

### Method Signature
```typescript
parse(buffer: ArrayBuffer): Value
```

### Parameters
#### Parameters
- **buffer** (ArrayBuffer) - Required - Binary plist data. Must start with 'bplist00' header.

### Return
`Value` — The parsed property list object, array, or primitive.

### Throws
- **Error**: If header is invalid, object count exceeds limits, or heap space is insufficient for reading.

### Notes
- Maximum object count: 32,768
- Maximum object size: 100MB
- Prototype pollution protection: dictionary keys named '__proto__' are rejected

### Example
```typescript
import { parse } from '@plist/binary.parse';

const buffer = new ArrayBuffer(/* binary plist data */);
const data = parse(buffer);
```
```

--------------------------------

### OpenStep Parser: Unmatched Array Paren Error

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

This error is triggered when an array opening parenthesis '(' lacks a matching closing parenthesis ')' by the end of the file.

```text
Error: "No matching ')' found"
```

--------------------------------

### Parse Binary Property List

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Use this low-level parser for binary property list format (bplist00). Input must be an ArrayBuffer and conform to specific size constraints. Prefer @plist/parse for automatic format detection.

```typescript
import { parse } from '@plist/binary.parse';

const binaryBuffer = new ArrayBuffer(/* ... */);
const data = parse(binaryBuffer);
```

--------------------------------

### Serialize Data to Plist

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/quick-start.md

Serialize JavaScript objects into different plist formats: XML (default), binary, and OpenStep. Specify the desired format using the PlistFormat enum.

```typescript
import { serialize, PlistFormat } from '@plist/plist';

const data = { hello: 'world', count: 42 };

// Default: XML
const xml = serialize(data);

// Binary format
const binary = serialize(data, PlistFormat.BINARY);

// OpenStep format
const openstep = serialize(data, PlistFormat.OPENSTEP);
```

--------------------------------

### OpenStep Parser: Expected String Key Error

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

This error indicates that a key within a dictionary is not a string type, which is a requirement for OpenStep format.

```text
Error: "Expected string key"
```

--------------------------------

### serialize (from @plist/xml.serialize)

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/api-reference-core.md

Serializes a JavaScript value into the XML property list format, producing a complete XML document with DTD and plist tags.

```APIDOC
## serialize (from @plist/xml.serialize)

### Description
Serialize a JavaScript value to XML plist format. Produces a complete XML document with proper DTD declaration.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **value** (Value) - Required - The JavaScript value to serialize.

### Request Example
```typescript
import { serialize } from '@plist/xml.serialize';

const data = { greeting: 'hello', count: 3 };
const xml = serialize(data);
// Output includes <?xml version="1.0"?>, <!DOCTYPE>, and <plist> tags
```

### Response
#### Success Response (200)
- **string** - Complete XML plist document as a string.

#### Response Example
```json
"<?xml version=\"1.0\"?><!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\"><plist version=\"1.0\"><dict><key>greeting</key><string>hello</string><key>count</key><integer>3</integer></dict></plist>"
```

### Throws
- **Error** - If value contains null or unsupported types.
```

--------------------------------

### Shared Property List Types and Constants

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/packages.md

Import shared types like Value and Dictionary, enums such as PlistFormat, and constants like EPOCH and HEADER_BINARY from this package. This is essential for using other @plist packages.

```typescript
// Types
export type Value = null | string | number | bigint | boolean | ArrayBuffer | Date | Dictionary | Value[]
export type Dictionary = { [key: string]: Value }

// Enums
export enum PlistFormat {
  BINARY,
  XML,
  OPENSTEP
}

// Constants
export const EPOCH = 978307200000           // Apple epoch in ms
export const HEADER_BINARY = 'bplist00'      // Binary plist magic
export const HEADER_OPENSTEP_UTF8 = '// !$*UTF8*$!'  // OpenStep UTF8 marker
```

```typescript
import { Value, Dictionary, PlistFormat, EPOCH } from '@plist/common';

function process(value: Value): void {
  if (typeof value === 'object' && !Array.isArray(value)) {
    const dict = value as Dictionary;
    Object.entries(dict).forEach(([key, val]) => {
      console.log(key, val);
    });
  }
}
```

--------------------------------

### Format-Specific XML Serialization

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/README.md

Import and use the dedicated XML serializer for creating XML plist data. Imports are required.

```typescript
import { serialize as serializeXML } from '@plist/xml.serialize';
```

--------------------------------

### Catching and Categorizing Errors

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

Demonstrates how to use a try-catch block to capture parsing errors and categorize them based on their messages for specific handling. This is useful for identifying issues like unknown formats, security threats, or oversized objects.

```typescript
import { parse, serialize, PlistFormat } from '@plist/plist';

// 1. Catch and categorize
try {
  const result = parse(inputData);
} catch (error) {
  const message = error.message || '';

  if (message.includes('Unknown format')) {
    // Handle format detection failure
  } else if (message.includes('prototype pollution')) {
    // Handle security threat
  } else if (message.includes('Too little heap space')) {
    // Handle oversized object
  } else if (message.includes('maxObjectCount')) {
    // Handle too many objects
  } else {
    // Handle other errors
  }
}
```

--------------------------------

### Define HEADER_BINARY Constant

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/types.md

The magic header string 'bplist00' that identifies binary property list files. Used for format detection.

```typescript
export const HEADER_BINARY = 'bplist00'
```

--------------------------------

### OpenStep Parser: Unmatched Dictionary Brace Error

Source: https://github.com/mat-sz/plist/blob/main/_autodocs/errors.md

This error occurs when a dictionary opening brace '{' does not have a corresponding closing brace '}' before the end of the file.

```text
Error: "No matching '}' found"
```