plist 3.1.1: build

audit=false
fund=false
update-notifier=false

# plist.build verification for plist@3.1.1

This sample demonstrates and proves the behavior of `plist.build` in `pkg:npm/plist@3.1.1`.

## Behavior Verified

1. **Primitive and Object Serialization**:
   `plist.build` converts JavaScript objects, arrays, strings, numbers, booleans, dates, and buffers into Apple XML Property List (version 1.0) format.

2. **Type Mapping**:
   - Objects are serialized to `<dict>` containing `<key>` and value tags.
   - Arrays are serialized to `<array>`.
   - Strings are enclosed in `<string>` with XML entities escaped (`&lt;`, `&gt;`, `&amp;`).
   - Integers and floating-point numbers are encoded into `<integer>` or `<real>`.
   - Buffers are base64-encoded inside `<data>`.
   - Booleans are represented as `<true/>` or `<false/>`.
   - Dates are formatted into ISO 8601 strings inside `<date>`.

3. **Formatting Options**:
   Custom indentation can be provided via `{ indent: '...' }` to format the resulting XML string.

The contract test in `test/contract.js` runs offline and validates each assertion.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify plist.build in pkg:npm/plist@3.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/plist@3.1.1
Demonstrate these symbols/APIs:
  - plist.build

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:137252753913270f72cb99060c06e8dfd35748c7c3539f78684c28f20ddf26af","contract":["plist.build serializes JavaScript primitives and objects into standard XML property list format","plist.build encodes numbers into integer or real tags and buffers into base64 data tags","plist.build encodes Date objects into ISO 8601 date tags and booleans into true and false tags","plist.build handles nested dictionaries and arrays with proper tag hierarchy","plist.build escapes special XML characters in string values and keys","plist.build applies custom formatting options such as custom indentation"],"goal":"verify plist.build in pkg:npm/plist@3.1.1","kind":"HOW","packages":["pkg:npm/plist@3.1.1"],"schemaVersion":1,"symbols":["plist.build"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/plist@3.1.1"],"schemaVersion":1,"subject":"pkg:npm/plist@3.1.1","symbols":["plist.build"],"verifierAdapter":"node-typescript@1"}

{
  "name": "plist-build-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "plist-build-sample",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "plist": "3.1.1"
      }
    },
    "node_modules/@xmldom/xmldom": {
      "version": "0.9.12",
      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.9.12.tgz",
      "integrity": "sha512-5AXjrcMClTryPe9LgZrygpB1lj7s0S9E0+W+AHaVKAVyHanafK86iPSvG5xHVSp/jC+VH1UXu0TAEmY279xH7A==",
      "license": "MIT",
      "engines": {
        "node": ">=14.6"
      }
    },
    "node_modules/base64-js": {
      "version": "1.5.1",
      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/feross"
        },
        {
          "type": "patreon",
          "url": "https://www.patreon.com/feross"
        },
        {
          "type": "consulting",
          "url": "https://feross.org/support"
        }
      ],
      "license": "MIT"
    },
    "node_modules/plist": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/plist/-/plist-3.1.1.tgz",
      "integrity": "sha512-ZIfcLJC+7E7FBFnDxm9MPmt7D+DidyQ26lewieO75AdhA2ayMtsJSES0iWzqJQbcVRSrTufQoy0DR94xHue0oA==",
      "license": "MIT",
      "dependencies": {
        "@xmldom/xmldom": "^0.9.10",
        "base64-js": "^1.5.1",
        "xmlbuilder": "^15.1.1"
      },
      "engines": {
        "node": ">=10.4.0"
      }
    },
    "node_modules/xmlbuilder": {
      "version": "15.1.1",
      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-15.1.1.tgz",
      "integrity": "sha512-yMqGBqtXyeN1e3TGYvgNgDVZ3j84W4cwkOXQswghol6APgZWaff9lnbvN7MHYJOiXsvGPXtjTYJEiC9J2wv9Eg==",
      "license": "MIT",
      "engines": {
        "node": ">=8.0"
      }
    }
  }
}

{
  "name": "plist-build-sample",
  "version": "1.0.0",
  "description": "verify plist.build in pkg:npm/plist@3.1.1",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "plist": "3.1.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify plist.build in pkg:npm/plist@3.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/plist@3.1.1"
  ],
  "symbols": [
    "plist.build"
  ]
}

const plist = require('plist');

/**
 * Builds an XML Property List string from any JavaScript value.
 *
 * @param {*} data - JavaScript data structure to serialize.
 * @param {object} [options] - Optional formatting options (indent, offset, head).
 * @returns {string} The formatted XML Property List document string.
 */
function buildPlist(data, options) {
  return plist.build(data, options);
}

/**
 * Builds a Property List representing a dictionary (object) structure.
 *
 * @param {Record<string, *>} entries - Key-value map to serialize as a plist dictionary.
 * @param {object} [options] - Optional formatting options.
 * @returns {string} The formatted XML Property List string.
 */
function buildDictionary(entries, options) {
  return plist.build(entries, options);
}

/**
 * Builds a Property List representing an array structure.
 *
 * @param {Array<*>} items - Array of elements to serialize.
 * @param {object} [options] - Optional formatting options.
 * @returns {string} The formatted XML Property List string.
 */
function buildArray(items, options) {
  return plist.build(items, options);
}

/**
 * Builds a Property List with custom indentation.
 *
 * @param {*} data - JavaScript value to serialize.
 * @param {string} indentString - Indentation string (e.g., '\t' or '  ').
 * @returns {string} The formatted XML Property List string.
 */
function buildFormattedPlist(data, indentString) {
  return plist.build(data, { indent: indentString });
}

module.exports = {
  buildPlist,
  buildDictionary,
  buildArray,
  buildFormattedPlist,
};

const assert = require('node:assert/strict');
const plist = require('plist');
const {
  buildPlist,
  buildDictionary,
  buildArray,
  buildFormattedPlist,
} = require('../src/index.js');

// Contract 1: plist.build serializes JavaScript primitives and objects into standard XML property list format
{
  const input = { title: 'App Configuration', version: 1 };
  const xml = buildPlist(input);

  assert.ok(xml.includes('<?xml version="1.0" encoding="UTF-8"?>'), 'Must include XML declaration');
  assert.ok(xml.includes('DOCTYPE plist PUBLIC') && xml.includes('PropertyList-1.0.dtd'), 'Must include Apple plist DOCTYPE');
  assert.ok(xml.includes('<plist version="1.0">'), 'Must include plist root tag with version');
  assert.ok(xml.includes('<dict>'), 'Object root should serialize as dict');
  assert.ok(xml.includes('<key>title</key>'), 'Object keys should serialize as key tags');
  assert.ok(xml.includes('<string>App Configuration</string>'), 'String values should serialize as string tags');
}

// Contract 2: plist.build encodes numbers into integer or real tags and buffers into base64 data tags
{
  const bufferContent = Buffer.from('CodeSampleX payload', 'utf8');
  const input = {
    count: 42,
    ratio: 3.14159,
    binaryPayload: bufferContent,
  };
  const xml = buildDictionary(input);

  assert.ok(xml.includes('<key>count</key>') && xml.includes('<integer>42</integer>'), 'Integer numbers should serialize as integer tags');
  assert.ok(xml.includes('<key>ratio</key>') && xml.includes('<real>3.14159</real>'), 'Floating point numbers should serialize as real tags');
  assert.ok(xml.includes('<key>binaryPayload</key>') && xml.includes('<data>' + bufferContent.toString('base64') + '</data>'), 'Buffers should serialize as base64 data tags');
}

// Contract 3: plist.build encodes Date objects into ISO 8601 date tags and booleans into true and false tags
{
  const timestamp = new Date('2026-08-26T11:00:00.000Z');
  const input = {
    createdAt: timestamp,
    isActive: true,
    isDeprecated: false,
  };
  const xml = buildDictionary(input);

  assert.ok(xml.includes('<date>2026-08-26T11:00:00Z</date>') || xml.includes('<date>' + timestamp.toISOString() + '</date>'), 'Date objects should serialize into ISO date tags');
  assert.ok(xml.includes('<true/>'), 'True boolean should serialize as true tag');
  assert.ok(xml.includes('<false/>'), 'False boolean should serialize as false tag');
}

// Contract 4: plist.build handles nested dictionaries and arrays with proper tag hierarchy
{
  const input = [
    {
      id: 101,
      tags: ['alpha', 'beta'],
      settings: {
        enabled: true,
      },
    },
  ];
  const xml = buildArray(input);

  assert.ok(xml.includes('<plist version="1.0">'), 'Array root should include plist root tag');
  assert.ok(xml.includes('<array>'), 'Array root should serialize as array tag');
  assert.ok(xml.includes('<dict>'), 'Nested dictionary inside array');
  assert.ok(xml.includes('<key>tags</key>'), 'Nested array under key');
  assert.ok(xml.includes('<string>alpha</string>'), 'Array items serialized properly');
  assert.ok(xml.includes('<string>beta</string>'), 'Array items serialized properly');

  // Verify round-trip parsing
  const parsed = plist.parse(xml);
  assert.strictEqual(parsed[0].id, 101);
  assert.deepStrictEqual(parsed[0].tags, ['alpha', 'beta']);
  assert.strictEqual(parsed[0].settings.enabled, true);
}

// Contract 5: plist.build escapes special XML characters in string values and keys
{
  const input = {
    'custom&key': '<script>alert("xss") & \'test\'</script>',
  };
  const xml = buildPlist(input);

  assert.ok(xml.includes('&lt;script&gt;'), 'Unescaped tag brackets should be escaped');
  assert.ok(xml.includes('&amp;'), 'Ampersands must be escaped');
  assert.ok(!xml.includes('<script>'), 'Raw script tags must not appear in XML output');

  const parsed = plist.parse(xml);
  assert.strictEqual(parsed['custom&key'], '<script>alert("xss") & \'test\'</script>');
}

// Contract 6: plist.build applies custom formatting options such as custom indentation
{
  const input = { item: 1 };
  const tabFormatted = buildFormattedPlist(input, '\t');
  const spaceFormatted = buildFormattedPlist(input, '    ');

  assert.ok(tabFormatted.includes('\t<dict>'), 'Custom tab indentation should be applied');
  assert.ok(spaceFormatted.includes('    <dict>'), 'Custom 4-space indentation should be applied');
}

console.log('All plist.build contract tests passed successfully.');