@fuman/plist 0.1.0

package/plist-reader.cjs

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const types = require("./types.cjs");
+function getNextElement(iter) {
+  while (true) {
+    const node = iter.next();
+    if (node.done) return null;
+    if (node.value.nodeType === 1) return node.value;
+  }
+}
+function readXmlPlist(data, params) {
+  const { DOMParser = globalThis.DOMParser, parseUid = false } = params ?? {};
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(data, "text/xml");
+  const root = doc.getElementsByTagName("plist")[0];
+  if (!root) throw new Error("<plist> not found, invalid plist?");
+  const topObject = root.childNodes.filter((node) => node.nodeType === 1);
+  if (topObject.length !== 1) throw new Error("expected exactly one top object");
+  function parseObject(node) {
+    switch (node.tagName) {
+      case "dict": {
+        const dict = {};
+        const childrenIter = node.childNodes[Symbol.iterator]();
+        while (true) {
+          const key = getNextElement(childrenIter);
+          if (!key) break;
+          if (key.tagName !== "key") throw new Error(`expected <key>, got <${key.tagName}>`);
+          const keyText = key.textContent ?? "";
+          const value = getNextElement(childrenIter);
+          if (!value) throw new Error(`value for ${keyText} not found`);
+          dict[keyText] = parseObject(value);
+        }
+        if (parseUid && (typeof dict.CF$UID === "number" || typeof dict.CF$UID === "bigint") && Object.keys(dict).length === 1) {
+          return new types.PlistValue("uid", dict.CF$UID);
+        }
+        return dict;
+      }
+      case "array": {
+        const array = [];
+        const childrenIter = node.childNodes[Symbol.iterator]();
+        while (true) {
+          const value = getNextElement(childrenIter);
+          if (!value) break;
+          array.push(parseObject(value));
+        }
+        return array;
+      }
+      case "string":
+        return node.textContent ?? "";
+      case "data":
+        return utils.base64.decode(node.textContent?.trim() ?? "");
+      case "integer": {
+        const value = node.textContent?.trim() ?? "";
+        const numValue = Number(value);
+        if (Number.isNaN(numValue)) throw new Error(`invalid integer: ${value}`);
+        if (numValue < Number.MIN_SAFE_INTEGER || numValue > Number.MAX_SAFE_INTEGER) {
+          return BigInt(value);
+        }
+        return numValue;
+      }
+      case "date": {
+        const value = new Date(node.textContent?.trim() ?? "");
+        if (Number.isNaN(value.getTime())) throw new Error(`invalid date: ${node.textContent}`);
+        return value;
+      }
+      case "false":
+        return false;
+      case "true":
+        return true;
+      case "real":
+        return Number(node.textContent?.trim() ?? "");
+      default:
+        throw new Error(`unexpected tag: <${node.tagName}>`);
+    }
+  }
+  return parseObject(topObject[0]);
+}
+exports.readXmlPlist = readXmlPlist;

package/plist-reader.d.cts

@@ -0,0 +1,15 @@
+export declare function readXmlPlist(data: string, params?: {
+    /**
+     * implementation of the DOMParser interface (e.g. `@xmldom/xmldom`)
+     *
+     * @default globalThis.DOMParser
+     */
+    DOMParser?: any;
+    /**
+     * in `xml1` plists, uids are serialized as a `<dict>` with a single integer key `CF$UID`.
+     * by default, we keep them as is, but you can opt into parsing them into a `PlistValue<'uid'>` instead.
+     *
+     * @default  false
+     */
+    parseUid?: boolean;
+}): unknown;

package/plist-reader.d.ts

@@ -0,0 +1,15 @@
+export declare function readXmlPlist(data: string, params?: {
+    /**
+     * implementation of the DOMParser interface (e.g. `@xmldom/xmldom`)
+     *
+     * @default globalThis.DOMParser
+     */
+    DOMParser?: any;
+    /**
+     * in `xml1` plists, uids are serialized as a `<dict>` with a single integer key `CF$UID`.
+     * by default, we keep them as is, but you can opt into parsing them into a `PlistValue<'uid'>` instead.
+     *
+     * @default  false
+     */
+    parseUid?: boolean;
+}): unknown;

package/plist-reader.js

@@ -0,0 +1,79 @@
+import { base64 } from "@fuman/utils";
+import { PlistValue } from "./types.js";
+function getNextElement(iter) {
+  while (true) {
+    const node = iter.next();
+    if (node.done) return null;
+    if (node.value.nodeType === 1) return node.value;
+  }
+}
+function readXmlPlist(data, params) {
+  const { DOMParser = globalThis.DOMParser, parseUid = false } = params ?? {};
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(data, "text/xml");
+  const root = doc.getElementsByTagName("plist")[0];
+  if (!root) throw new Error("<plist> not found, invalid plist?");
+  const topObject = root.childNodes.filter((node) => node.nodeType === 1);
+  if (topObject.length !== 1) throw new Error("expected exactly one top object");
+  function parseObject(node) {
+    switch (node.tagName) {
+      case "dict": {
+        const dict = {};
+        const childrenIter = node.childNodes[Symbol.iterator]();
+        while (true) {
+          const key = getNextElement(childrenIter);
+          if (!key) break;
+          if (key.tagName !== "key") throw new Error(`expected <key>, got <${key.tagName}>`);
+          const keyText = key.textContent ?? "";
+          const value = getNextElement(childrenIter);
+          if (!value) throw new Error(`value for ${keyText} not found`);
+          dict[keyText] = parseObject(value);
+        }
+        if (parseUid && (typeof dict.CF$UID === "number" || typeof dict.CF$UID === "bigint") && Object.keys(dict).length === 1) {
+          return new PlistValue("uid", dict.CF$UID);
+        }
+        return dict;
+      }
+      case "array": {
+        const array = [];
+        const childrenIter = node.childNodes[Symbol.iterator]();
+        while (true) {
+          const value = getNextElement(childrenIter);
+          if (!value) break;
+          array.push(parseObject(value));
+        }
+        return array;
+      }
+      case "string":
+        return node.textContent ?? "";
+      case "data":
+        return base64.decode(node.textContent?.trim() ?? "");
+      case "integer": {
+        const value = node.textContent?.trim() ?? "";
+        const numValue = Number(value);
+        if (Number.isNaN(numValue)) throw new Error(`invalid integer: ${value}`);
+        if (numValue < Number.MIN_SAFE_INTEGER || numValue > Number.MAX_SAFE_INTEGER) {
+          return BigInt(value);
+        }
+        return numValue;
+      }
+      case "date": {
+        const value = new Date(node.textContent?.trim() ?? "");
+        if (Number.isNaN(value.getTime())) throw new Error(`invalid date: ${node.textContent}`);
+        return value;
+      }
+      case "false":
+        return false;
+      case "true":
+        return true;
+      case "real":
+        return Number(node.textContent?.trim() ?? "");
+      default:
+        throw new Error(`unexpected tag: <${node.tagName}>`);
+    }
+  }
+  return parseObject(topObject[0]);
+}
+export {
+  readXmlPlist
+};

package/plist-writer.cjs

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const types = require("./types.cjs");
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function writeXmlPlist(data, options) {
+  const {
+    indent: indentStr = "	",
+    lineBreak: lineBreakStr = "\n",
+    wrapDataAt = 0,
+    collapseEmpty = true
+  } = options ?? {};
+  const lines = [
+    '<?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">'
+  ];
+  let indent = "";
+  const pushIndent = () => {
+    indent += indentStr;
+  };
+  const popIndent = () => {
+    indent = indent.slice(0, -indentStr.length);
+  };
+  const pushLine = (line) => {
+    lines.push(indent + line);
+  };
+  function writeObject(object) {
+    switch (typeof object) {
+      case "object": {
+        if (object === null) {
+          pushLine("<null/>");
+        } else if (Array.isArray(object)) {
+          if (collapseEmpty && object.length === 0) {
+            pushLine("<array/>");
+          } else {
+            pushLine("<array>");
+            pushIndent();
+            for (const value of object) {
+              writeObject(value);
+            }
+            popIndent();
+            pushLine("</array>");
+          }
+        } else if (object instanceof Date) {
+          pushLine(`<date>${object.toISOString().replace(/\.\d+(Z|\+)$/, "$1")}</date>`);
+        } else if (object instanceof types.PlistValue) {
+          switch (object.type) {
+            case "float32":
+            case "float64":
+              pushLine(`<real>${object.value}</real>`);
+              break;
+            case "int":
+              pushLine(`<integer>${object.value}</integer>`);
+              break;
+            case "uid":
+              writeObject({ CF$UID: object.value });
+              break;
+            case "ascii":
+            case "utf16":
+            case "utf8":
+              pushLine(`<string>${escapeXml(object.value)}</string>`);
+              break;
+            default:
+              throw new Error(`unexpected type: ${object.type}`);
+          }
+        } else if (object instanceof Uint8Array) {
+          const b64 = utils.base64.encode(object);
+          if (wrapDataAt === 0) {
+            pushLine(`<data>${b64}</data>`);
+          } else {
+            const wrapLength = wrapDataAt - indent.replace(/\t/g, "        ").length;
+            pushLine("<data>");
+            for (let i = 0; i < b64.length; i += wrapLength) {
+              pushLine(b64.slice(i, i + wrapLength));
+            }
+            pushLine("</data>");
+          }
+        } else {
+          const keys = Object.keys(object);
+          if (collapseEmpty && keys.length === 0) {
+            pushLine("<dict/>");
+          } else {
+            pushLine("<dict>");
+            pushIndent();
+            for (const key of keys) {
+              pushLine(`<key>${escapeXml(key)}</key>`);
+              writeObject(object[key]);
+            }
+            popIndent();
+            pushLine("</dict>");
+          }
+        }
+        break;
+      }
+      case "string":
+        pushLine(`<string>${escapeXml(object)}</string>`);
+        break;
+      case "number": {
+        const element = Number.isInteger(object) ? "integer" : "real";
+        pushLine(`<${element}>${object}</${element}>`);
+        break;
+      }
+      case "bigint":
+        pushLine(`<integer>${object.toString()}</integer>`);
+        break;
+      case "boolean":
+        pushLine(`<${object ? "true" : "false"}/>`);
+        break;
+      default:
+        throw new Error(`unexpected type: ${typeof object}`);
+    }
+  }
+  writeObject(data);
+  lines.push("</plist>");
+  return lines.join(lineBreakStr);
+}
+exports.writeXmlPlist = writeXmlPlist;

package/plist-writer.d.cts

@@ -0,0 +1,27 @@
+export declare function writeXmlPlist(data: unknown, options?: {
+    /**
+     * string to use for indentation
+     *
+     * @default '\t'
+     */
+    indent?: string;
+    /**
+     * string to use for line breaks
+     *
+     * @default '\n'
+     */
+    lineBreak?: string;
+    /**
+     * some implementations wrap `<data>` base64 strings at a certain length,
+     * this option allows you to set that length
+     *
+     * @default 0 (no wrapping)
+     */
+    wrapDataAt?: number;
+    /**
+     * whether we should collapse empty tags (e.g. `<dict/>`, <array/>`)
+     *
+     * @default true
+     */
+    collapseEmpty?: boolean;
+}): string;

package/plist-writer.d.ts

@@ -0,0 +1,27 @@
+export declare function writeXmlPlist(data: unknown, options?: {
+    /**
+     * string to use for indentation
+     *
+     * @default '\t'
+     */
+    indent?: string;
+    /**
+     * string to use for line breaks
+     *
+     * @default '\n'
+     */
+    lineBreak?: string;
+    /**
+     * some implementations wrap `<data>` base64 strings at a certain length,
+     * this option allows you to set that length
+     *
+     * @default 0 (no wrapping)
+     */
+    wrapDataAt?: number;
+    /**
+     * whether we should collapse empty tags (e.g. `<dict/>`, <array/>`)
+     *
+     * @default true
+     */
+    collapseEmpty?: boolean;
+}): string;

package/plist-writer.js

@@ -0,0 +1,120 @@
+import { base64 } from "@fuman/utils";
+import { PlistValue } from "./types.js";
+function escapeXml(str) {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function writeXmlPlist(data, options) {
+  const {
+    indent: indentStr = "	",
+    lineBreak: lineBreakStr = "\n",
+    wrapDataAt = 0,
+    collapseEmpty = true
+  } = options ?? {};
+  const lines = [
+    '<?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">'
+  ];
+  let indent = "";
+  const pushIndent = () => {
+    indent += indentStr;
+  };
+  const popIndent = () => {
+    indent = indent.slice(0, -indentStr.length);
+  };
+  const pushLine = (line) => {
+    lines.push(indent + line);
+  };
+  function writeObject(object) {
+    switch (typeof object) {
+      case "object": {
+        if (object === null) {
+          pushLine("<null/>");
+        } else if (Array.isArray(object)) {
+          if (collapseEmpty && object.length === 0) {
+            pushLine("<array/>");
+          } else {
+            pushLine("<array>");
+            pushIndent();
+            for (const value of object) {
+              writeObject(value);
+            }
+            popIndent();
+            pushLine("</array>");
+          }
+        } else if (object instanceof Date) {
+          pushLine(`<date>${object.toISOString().replace(/\.\d+(Z|\+)$/, "$1")}</date>`);
+        } else if (object instanceof PlistValue) {
+          switch (object.type) {
+            case "float32":
+            case "float64":
+              pushLine(`<real>${object.value}</real>`);
+              break;
+            case "int":
+              pushLine(`<integer>${object.value}</integer>`);
+              break;
+            case "uid":
+              writeObject({ CF$UID: object.value });
+              break;
+            case "ascii":
+            case "utf16":
+            case "utf8":
+              pushLine(`<string>${escapeXml(object.value)}</string>`);
+              break;
+            default:
+              throw new Error(`unexpected type: ${object.type}`);
+          }
+        } else if (object instanceof Uint8Array) {
+          const b64 = base64.encode(object);
+          if (wrapDataAt === 0) {
+            pushLine(`<data>${b64}</data>`);
+          } else {
+            const wrapLength = wrapDataAt - indent.replace(/\t/g, "        ").length;
+            pushLine("<data>");
+            for (let i = 0; i < b64.length; i += wrapLength) {
+              pushLine(b64.slice(i, i + wrapLength));
+            }
+            pushLine("</data>");
+          }
+        } else {
+          const keys = Object.keys(object);
+          if (collapseEmpty && keys.length === 0) {
+            pushLine("<dict/>");
+          } else {
+            pushLine("<dict>");
+            pushIndent();
+            for (const key of keys) {
+              pushLine(`<key>${escapeXml(key)}</key>`);
+              writeObject(object[key]);
+            }
+            popIndent();
+            pushLine("</dict>");
+          }
+        }
+        break;
+      }
+      case "string":
+        pushLine(`<string>${escapeXml(object)}</string>`);
+        break;
+      case "number": {
+        const element = Number.isInteger(object) ? "integer" : "real";
+        pushLine(`<${element}>${object}</${element}>`);
+        break;
+      }
+      case "bigint":
+        pushLine(`<integer>${object.toString()}</integer>`);
+        break;
+      case "boolean":
+        pushLine(`<${object ? "true" : "false"}/>`);
+        break;
+      default:
+        throw new Error(`unexpected type: ${typeof object}`);
+    }
+  }
+  writeObject(data);
+  lines.push("</plist>");
+  return lines.join(lineBreakStr);
+}
+export {
+  writeXmlPlist
+};

package/types.cjs

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+class PlistValue {
+  constructor(type, value) {
+    this.type = type;
+    this.value = value;
+  }
+  valueOf() {
+    return this.value;
+  }
+  toString() {
+    return String(this.value);
+  }
+}
+class KeyedArchiverValue {
+  constructor(header, value) {
+    this.header = header;
+    this.value = value;
+  }
+  valueOf() {
+    return this.value;
+  }
+}
+exports.KeyedArchiverValue = KeyedArchiverValue;
+exports.PlistValue = PlistValue;

package/types.d.cts

@@ -0,0 +1,27 @@
+export interface PlistValueType {
+    float32: number;
+    float64: number;
+    int: number | bigint;
+    uid: number | bigint;
+    ascii: string;
+    utf16: string;
+    utf8: string;
+}
+export declare class PlistValue<Type extends keyof PlistValueType = keyof PlistValueType> {
+    readonly type: Type;
+    readonly value: PlistValueType[Type];
+    constructor(type: Type, value: PlistValueType[Type]);
+    valueOf(): PlistValueType[Type];
+    toString(): string;
+}
+export interface KeyedArchiverValueHeader {
+    $classname: string;
+    $classes: string[];
+    $classhints?: string[];
+}
+export declare class KeyedArchiverValue {
+    readonly header: KeyedArchiverValueHeader;
+    readonly value: unknown;
+    constructor(header: KeyedArchiverValueHeader, value: unknown);
+    valueOf(): unknown;
+}

package/types.d.ts

@@ -0,0 +1,27 @@
+export interface PlistValueType {
+    float32: number;
+    float64: number;
+    int: number | bigint;
+    uid: number | bigint;
+    ascii: string;
+    utf16: string;
+    utf8: string;
+}
+export declare class PlistValue<Type extends keyof PlistValueType = keyof PlistValueType> {
+    readonly type: Type;
+    readonly value: PlistValueType[Type];
+    constructor(type: Type, value: PlistValueType[Type]);
+    valueOf(): PlistValueType[Type];
+    toString(): string;
+}
+export interface KeyedArchiverValueHeader {
+    $classname: string;
+    $classes: string[];
+    $classhints?: string[];
+}
+export declare class KeyedArchiverValue {
+    readonly header: KeyedArchiverValueHeader;
+    readonly value: unknown;
+    constructor(header: KeyedArchiverValueHeader, value: unknown);
+    valueOf(): unknown;
+}

package/types.js

@@ -0,0 +1,25 @@
+class PlistValue {
+  constructor(type, value) {
+    this.type = type;
+    this.value = value;
+  }
+  valueOf() {
+    return this.value;
+  }
+  toString() {
+    return String(this.value);
+  }
+}
+class KeyedArchiverValue {
+  constructor(header, value) {
+    this.header = header;
+    this.value = value;
+  }
+  valueOf() {
+    return this.value;
+  }
+}
+export {
+  KeyedArchiverValue,
+  PlistValue
+};