@fuman/plist 0.1.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2024 alina sireneva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

package/README.md

@@ -0,0 +1,41 @@
+## @fuman/plist
+
+modern typescript utilities for working with property lists (the `.plist` files used in apple operating systems),
+both reading and writing, both binary and xml-based. also supports NSKeyedArchiver/NSKeyedUnarchiver.
+
+### binary plist
+
+```ts
+import { readBinaryPlist, writeBinaryPlist } from '@fuman/plist'
+
+const data = writeBinaryPlist({ meow: 'purr' })
+console.log(readBinaryPlist(data))
+```
+
+### xml plist
+
+```ts
+import { readXmlPlist, writeXmlPlist } from '@fuman/plist'
+
+const data = writeXmlPlist({ meow: 'purr' })
+console.log(readXmlPlist(data))
+```
+
+> note: `readXmlPlist` uses [`DOMParser`](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser), which
+> might not be available in your environment (notably, under node.js as of writing). consider using `@xmldom/xmldom`:
+>
+> ```ts
+> import { DOMParser } from '@xmldom/xmldom'
+> console.log(readXmlPlist(data, { DOMParser }))
+> ```
+
+### NSKeyedArchiver
+
+```ts
+import { nsKeyedArchive, nsKeyedUnarchive, readBinaryPlist, writeBinaryPlist } from '@fuman/plist'
+
+const file = nsKeyedUnarchive(readBinaryPlist(await readFile('meow.plist')))
+console.log(file)
+file.foo = 123
+await writeFile('meow2.plist', writeBinaryPlist(nsKeyedArchive(file)))
+```

package/_constants.cjs

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const utils = require("@fuman/utils");
+const BPLIST_MAGIC = /* @__PURE__ */ utils.utf8.encoder.encode("bplist");
+const CORE_DATA_EPOCH = 9783072e5;
+const MAX_OBJECT_COUNT = 1024 * 1024;
+const NS_KEYED_ARCHIVER_VERSION = 1e5;
+exports.BPLIST_MAGIC = BPLIST_MAGIC;
+exports.CORE_DATA_EPOCH = CORE_DATA_EPOCH;
+exports.MAX_OBJECT_COUNT = MAX_OBJECT_COUNT;
+exports.NS_KEYED_ARCHIVER_VERSION = NS_KEYED_ARCHIVER_VERSION;

package/_constants.d.cts

@@ -0,0 +1,4 @@
+export declare const BPLIST_MAGIC: Uint8Array;
+export declare const CORE_DATA_EPOCH = 978307200000;
+export declare const MAX_OBJECT_COUNT: number;
+export declare const NS_KEYED_ARCHIVER_VERSION = 100000;

package/_constants.d.ts

@@ -0,0 +1,4 @@
+export declare const BPLIST_MAGIC: Uint8Array;
+export declare const CORE_DATA_EPOCH = 978307200000;
+export declare const MAX_OBJECT_COUNT: number;
+export declare const NS_KEYED_ARCHIVER_VERSION = 100000;

package/_constants.js

@@ -0,0 +1,11 @@
+import { utf8 } from "@fuman/utils";
+const BPLIST_MAGIC = /* @__PURE__ */ utf8.encoder.encode("bplist");
+const CORE_DATA_EPOCH = 9783072e5;
+const MAX_OBJECT_COUNT = 1024 * 1024;
+const NS_KEYED_ARCHIVER_VERSION = 1e5;
+export {
+  BPLIST_MAGIC,
+  CORE_DATA_EPOCH,
+  MAX_OBJECT_COUNT,
+  NS_KEYED_ARCHIVER_VERSION
+};

package/_utils.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function safeToNumber(value) {
+  if (typeof value === "bigint") {
+    if (value > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`value is too large: ${value}`);
+    }
+    return Number(value);
+  }
+  return value;
+}
+exports.safeToNumber = safeToNumber;

package/_utils.d.cts

@@ -0,0 +1 @@
+export declare function safeToNumber(value: number | bigint): number;

package/_utils.d.ts

@@ -0,0 +1 @@
+export declare function safeToNumber(value: number | bigint): number;

package/_utils.js

@@ -0,0 +1,12 @@
+function safeToNumber(value) {
+  if (typeof value === "bigint") {
+    if (value > Number.MAX_SAFE_INTEGER) {
+      throw new Error(`value is too large: ${value}`);
+    }
+    return Number(value);
+  }
+  return value;
+}
+export {
+  safeToNumber
+};

package/bplist-reader.cjs

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const io = require("@fuman/io");
+const utils = require("@fuman/utils");
+const _constants = require("./_constants.cjs");
+const _utils = require("./_utils.cjs");
+const types = require("./types.cjs");
+const UINT_SIZES = new Uint8Array([1, 2, 4, 8]);
+function readBinaryPlist(data, options) {
+  const {
+    maxObjectCount = _constants.MAX_OBJECT_COUNT,
+    skipMagicCheck = false,
+    preserveType = false
+  } = options ?? {};
+  if (data.length < 38) {
+    throw new Error("bplist is too small");
+  }
+  const magic = data.subarray(0, 6);
+  if (!skipMagicCheck && !utils.typed.equal(magic, _constants.BPLIST_MAGIC)) {
+    throw new Error(`bplist magic is invalid: ${utils.utf8.decoder.decode(magic)}`);
+  }
+  const trailer = data.subarray(-32);
+  const offsetSize = trailer[6];
+  const objectRefSize = trailer[7];
+  const numObjects = _utils.safeToNumber(io.read.uint64be(trailer.subarray(8, 16)));
+  const topObject = _utils.safeToNumber(io.read.uint64be(trailer.subarray(16, 24)));
+  const offsetTableOffset = _utils.safeToNumber(io.read.uint64be(trailer.subarray(24, 32)));
+  if (numObjects > maxObjectCount) {
+    throw new Error("MAX_OBJECT_COUNT exceeded");
+  }
+  function checkBounds(offset) {
+    if (offset >= data.length) {
+      throw new Error(`out of bounds: offset ${offset} >= ${data.length}`);
+    }
+  }
+  function readUint(offset, size) {
+    switch (size) {
+      case 1: {
+        checkBounds(offset);
+        return data[offset];
+      }
+      case 2:
+        return io.read.uint16be(data.subarray(offset, offset + 2));
+      case 4:
+        return io.read.uint32be(data.subarray(offset, offset + 4));
+      case 8:
+        return io.read.uint64be(data.subarray(offset, offset + 8));
+      default:
+        throw new Error(`invalid int size: ${size}`);
+    }
+  }
+  const readNumber = (offset, size) => _utils.safeToNumber(readUint(offset, size));
+  const offsetTable = [];
+  for (let i = 0, offset = offsetTableOffset; i < numObjects; i++, offset += offsetSize) {
+    offsetTable[i] = readNumber(offset, offsetSize);
+  }
+  function readBytes(offset, size, isUtf16 = false) {
+    if (size === 15) {
+      const intSize = UINT_SIZES[data[offset + 1] & 15];
+      size = readNumber(offset + 2, intSize);
+      offset += 1 + intSize;
+    }
+    if (isUtf16) size *= 2;
+    checkBounds(offset + 1 + size);
+    return data.subarray(offset + 1, offset + 1 + size);
+  }
+  function readObject(ref) {
+    const offset = offsetTable[ref];
+    if (!offset) throw new Error(`object ${ref} not found`);
+    checkBounds(offset);
+    const type = data[offset];
+    const low = type & 15;
+    const high = type >> 4 & 15;
+    switch (high) {
+      case 0:
+        switch (low) {
+          case 0:
+            return null;
+          case 8:
+            return false;
+          case 9:
+            return true;
+          case 15:
+            return void 0;
+          // padding
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+      case 1: {
+        let int;
+        switch (low) {
+          case 0:
+            int = data[offset + 1];
+            break;
+          case 1:
+            int = io.read.uint16be(data.subarray(offset + 1, offset + 3));
+            break;
+          case 2:
+            int = io.read.uint32be(data.subarray(offset + 1, offset + 7));
+            break;
+          case 3:
+            int = io.read.int64be(data.subarray(offset + 1, offset + 9));
+            break;
+          case 4:
+            int = io.read.intbe(data.subarray(offset + 1, offset + 17), 16);
+            break;
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+        return preserveType ? new types.PlistValue("int", int) : int;
+      }
+      case 2: {
+        let float;
+        switch (low) {
+          case 2:
+            float = io.read.float32be(data.subarray(offset + 1));
+            break;
+          case 3:
+            float = io.read.float64be(data.subarray(offset + 1));
+            break;
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+        return preserveType ? new types.PlistValue(low === 2 ? "float32" : "float64", float) : float;
+      }
+      case 3: {
+        if (low !== 3) throw new Error(`invalid type 0b${type.toString(2)}`);
+        const seconds = io.read.float64be(data.subarray(offset + 1));
+        return new Date(_constants.CORE_DATA_EPOCH + seconds * 1e3);
+      }
+      case 4:
+        return readBytes(offset, low);
+      case 5: {
+        const bytes = readBytes(offset, low);
+        let str = "";
+        for (let i = 0; i < bytes.length; i++) {
+          const char = bytes[i];
+          if (char === 0) break;
+          str += String.fromCharCode(char);
+        }
+        return preserveType ? new types.PlistValue("ascii", str) : str;
+      }
+      case 6: {
+        const bytes = readBytes(offset, low, true);
+        const str = io.read.utf16beString(bytes, bytes.length);
+        return preserveType ? new types.PlistValue("utf16", str) : str;
+      }
+      case 7: {
+        const str = utils.utf8.decoder.decode(readBytes(offset, low));
+        return preserveType ? new types.PlistValue("utf8", str) : str;
+      }
+      case 8: {
+        const int = readUint(offset + 1, UINT_SIZES[low]);
+        return new types.PlistValue("uid", int);
+      }
+      case 10:
+      // array-like
+      case 11: {
+        const array = [];
+        let arraySize = low;
+        let arrayOffset = offset + 1;
+        if (arraySize === 15) {
+          const intSize = UINT_SIZES[data[offset + 1] & 15];
+          arraySize = readNumber(offset + 2, intSize);
+          arrayOffset += 1 + intSize;
+        }
+        checkBounds(arrayOffset + arraySize * objectRefSize);
+        for (let i = 0, offset2 = arrayOffset; i < arraySize; i++, offset2 += objectRefSize) {
+          array[i] = readObject(readNumber(offset2, objectRefSize));
+        }
+        switch (high) {
+          case 10:
+            return array;
+          case 11:
+            return new Set(array);
+          default:
+            return utils.unreachable();
+        }
+      }
+      case 13: {
+        const dict = {};
+        let dictSize = low;
+        let keysOffset = offset + 1;
+        if (dictSize === 15) {
+          const intSize = UINT_SIZES[data[offset + 1] & 15];
+          dictSize = readNumber(offset + 2, intSize);
+          keysOffset += 1 + intSize;
+        }
+        const valuesOffset = keysOffset + objectRefSize * dictSize;
+        checkBounds(valuesOffset + dictSize * objectRefSize);
+        for (let i = 0, keyOffset = keysOffset, valueOffset = valuesOffset; i < dictSize; i++, keyOffset += objectRefSize, valueOffset += objectRefSize) {
+          let key = readObject(readNumber(keyOffset, objectRefSize));
+          if (preserveType && key instanceof types.PlistValue) {
+            key = key.valueOf();
+          }
+          if (typeof key !== "string" && typeof key !== "number") {
+            throw new TypeError(`invalid key: ${String(key)}`);
+          }
+          const value = readObject(readNumber(valueOffset, objectRefSize));
+          dict[key] = value;
+        }
+        return dict;
+      }
+      default:
+        throw new Error(`invalid type 0b${type.toString(2)}`);
+    }
+  }
+  return readObject(topObject);
+}
+exports.readBinaryPlist = readBinaryPlist;

package/bplist-reader.d.cts

@@ -0,0 +1,14 @@
+export declare function readBinaryPlist(data: Uint8Array, options?: {
+    /**
+     *  maximum number of objects to read
+     * @default 1024 * 1024
+     */
+    maxObjectCount?: number;
+    /** when true, the magic check will be skipped */
+    skipMagicCheck?: boolean;
+    /**
+     * when true, some primitive values will be wrapped into {@link PlistValueType} to allow for lossless operation
+     * otherwise, only `uid*` values will be wrapped
+     */
+    preserveType?: boolean;
+}): unknown;

package/bplist-reader.d.ts

@@ -0,0 +1,14 @@
+export declare function readBinaryPlist(data: Uint8Array, options?: {
+    /**
+     *  maximum number of objects to read
+     * @default 1024 * 1024
+     */
+    maxObjectCount?: number;
+    /** when true, the magic check will be skipped */
+    skipMagicCheck?: boolean;
+    /**
+     * when true, some primitive values will be wrapped into {@link PlistValueType} to allow for lossless operation
+     * otherwise, only `uid*` values will be wrapped
+     */
+    preserveType?: boolean;
+}): unknown;

package/bplist-reader.js

@@ -0,0 +1,210 @@
+import { read } from "@fuman/io";
+import { typed, utf8, unreachable } from "@fuman/utils";
+import { BPLIST_MAGIC, MAX_OBJECT_COUNT, CORE_DATA_EPOCH } from "./_constants.js";
+import { safeToNumber } from "./_utils.js";
+import { PlistValue } from "./types.js";
+const UINT_SIZES = new Uint8Array([1, 2, 4, 8]);
+function readBinaryPlist(data, options) {
+  const {
+    maxObjectCount = MAX_OBJECT_COUNT,
+    skipMagicCheck = false,
+    preserveType = false
+  } = options ?? {};
+  if (data.length < 38) {
+    throw new Error("bplist is too small");
+  }
+  const magic = data.subarray(0, 6);
+  if (!skipMagicCheck && !typed.equal(magic, BPLIST_MAGIC)) {
+    throw new Error(`bplist magic is invalid: ${utf8.decoder.decode(magic)}`);
+  }
+  const trailer = data.subarray(-32);
+  const offsetSize = trailer[6];
+  const objectRefSize = trailer[7];
+  const numObjects = safeToNumber(read.uint64be(trailer.subarray(8, 16)));
+  const topObject = safeToNumber(read.uint64be(trailer.subarray(16, 24)));
+  const offsetTableOffset = safeToNumber(read.uint64be(trailer.subarray(24, 32)));
+  if (numObjects > maxObjectCount) {
+    throw new Error("MAX_OBJECT_COUNT exceeded");
+  }
+  function checkBounds(offset) {
+    if (offset >= data.length) {
+      throw new Error(`out of bounds: offset ${offset} >= ${data.length}`);
+    }
+  }
+  function readUint(offset, size) {
+    switch (size) {
+      case 1: {
+        checkBounds(offset);
+        return data[offset];
+      }
+      case 2:
+        return read.uint16be(data.subarray(offset, offset + 2));
+      case 4:
+        return read.uint32be(data.subarray(offset, offset + 4));
+      case 8:
+        return read.uint64be(data.subarray(offset, offset + 8));
+      default:
+        throw new Error(`invalid int size: ${size}`);
+    }
+  }
+  const readNumber = (offset, size) => safeToNumber(readUint(offset, size));
+  const offsetTable = [];
+  for (let i = 0, offset = offsetTableOffset; i < numObjects; i++, offset += offsetSize) {
+    offsetTable[i] = readNumber(offset, offsetSize);
+  }
+  function readBytes(offset, size, isUtf16 = false) {
+    if (size === 15) {
+      const intSize = UINT_SIZES[data[offset + 1] & 15];
+      size = readNumber(offset + 2, intSize);
+      offset += 1 + intSize;
+    }
+    if (isUtf16) size *= 2;
+    checkBounds(offset + 1 + size);
+    return data.subarray(offset + 1, offset + 1 + size);
+  }
+  function readObject(ref) {
+    const offset = offsetTable[ref];
+    if (!offset) throw new Error(`object ${ref} not found`);
+    checkBounds(offset);
+    const type = data[offset];
+    const low = type & 15;
+    const high = type >> 4 & 15;
+    switch (high) {
+      case 0:
+        switch (low) {
+          case 0:
+            return null;
+          case 8:
+            return false;
+          case 9:
+            return true;
+          case 15:
+            return void 0;
+          // padding
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+      case 1: {
+        let int;
+        switch (low) {
+          case 0:
+            int = data[offset + 1];
+            break;
+          case 1:
+            int = read.uint16be(data.subarray(offset + 1, offset + 3));
+            break;
+          case 2:
+            int = read.uint32be(data.subarray(offset + 1, offset + 7));
+            break;
+          case 3:
+            int = read.int64be(data.subarray(offset + 1, offset + 9));
+            break;
+          case 4:
+            int = read.intbe(data.subarray(offset + 1, offset + 17), 16);
+            break;
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+        return preserveType ? new PlistValue("int", int) : int;
+      }
+      case 2: {
+        let float;
+        switch (low) {
+          case 2:
+            float = read.float32be(data.subarray(offset + 1));
+            break;
+          case 3:
+            float = read.float64be(data.subarray(offset + 1));
+            break;
+          default:
+            throw new Error(`invalid type 0b${type.toString(2)}`);
+        }
+        return preserveType ? new PlistValue(low === 2 ? "float32" : "float64", float) : float;
+      }
+      case 3: {
+        if (low !== 3) throw new Error(`invalid type 0b${type.toString(2)}`);
+        const seconds = read.float64be(data.subarray(offset + 1));
+        return new Date(CORE_DATA_EPOCH + seconds * 1e3);
+      }
+      case 4:
+        return readBytes(offset, low);
+      case 5: {
+        const bytes = readBytes(offset, low);
+        let str = "";
+        for (let i = 0; i < bytes.length; i++) {
+          const char = bytes[i];
+          if (char === 0) break;
+          str += String.fromCharCode(char);
+        }
+        return preserveType ? new PlistValue("ascii", str) : str;
+      }
+      case 6: {
+        const bytes = readBytes(offset, low, true);
+        const str = read.utf16beString(bytes, bytes.length);
+        return preserveType ? new PlistValue("utf16", str) : str;
+      }
+      case 7: {
+        const str = utf8.decoder.decode(readBytes(offset, low));
+        return preserveType ? new PlistValue("utf8", str) : str;
+      }
+      case 8: {
+        const int = readUint(offset + 1, UINT_SIZES[low]);
+        return new PlistValue("uid", int);
+      }
+      case 10:
+      // array-like
+      case 11: {
+        const array = [];
+        let arraySize = low;
+        let arrayOffset = offset + 1;
+        if (arraySize === 15) {
+          const intSize = UINT_SIZES[data[offset + 1] & 15];
+          arraySize = readNumber(offset + 2, intSize);
+          arrayOffset += 1 + intSize;
+        }
+        checkBounds(arrayOffset + arraySize * objectRefSize);
+        for (let i = 0, offset2 = arrayOffset; i < arraySize; i++, offset2 += objectRefSize) {
+          array[i] = readObject(readNumber(offset2, objectRefSize));
+        }
+        switch (high) {
+          case 10:
+            return array;
+          case 11:
+            return new Set(array);
+          default:
+            return unreachable();
+        }
+      }
+      case 13: {
+        const dict = {};
+        let dictSize = low;
+        let keysOffset = offset + 1;
+        if (dictSize === 15) {
+          const intSize = UINT_SIZES[data[offset + 1] & 15];
+          dictSize = readNumber(offset + 2, intSize);
+          keysOffset += 1 + intSize;
+        }
+        const valuesOffset = keysOffset + objectRefSize * dictSize;
+        checkBounds(valuesOffset + dictSize * objectRefSize);
+        for (let i = 0, keyOffset = keysOffset, valueOffset = valuesOffset; i < dictSize; i++, keyOffset += objectRefSize, valueOffset += objectRefSize) {
+          let key = readObject(readNumber(keyOffset, objectRefSize));
+          if (preserveType && key instanceof PlistValue) {
+            key = key.valueOf();
+          }
+          if (typeof key !== "string" && typeof key !== "number") {
+            throw new TypeError(`invalid key: ${String(key)}`);
+          }
+          const value = readObject(readNumber(valueOffset, objectRefSize));
+          dict[key] = value;
+        }
+        return dict;
+      }
+      default:
+        throw new Error(`invalid type 0b${type.toString(2)}`);
+    }
+  }
+  return readObject(topObject);
+}
+export {
+  readBinaryPlist
+};