bplist-lossless 0.1.0 → 0.1.1

package/dist/classes/plist-date.d.ts

@@ -0,0 +1,82 @@
+export type PlistDateBinaryInput = Buffer | Uint8Array | ArrayBuffer;
+export type PlistDateInput = PlistDate | Date | number | PlistDateBinaryInput;
+export declare class PlistDate extends Date {
+    #private;
+    static readonly APPLE_PLIST_EPOCH_MS: number;
+    constructor();
+    constructor(value: PlistDateInput);
+    static from(input: PlistDateInput): PlistDate;
+    static fromBuffer(input: PlistDateBinaryInput): PlistDate;
+    static fromPlistSeconds(seconds: number): PlistDate;
+    static fromUnixMilliseconds(milliseconds: number): PlistDate;
+    static isPlistDate(value: unknown): value is PlistDate;
+    /**
+     * Exact plist-native value:
+     * seconds since 2001-01-01T00:00:00Z stored as IEEE 754
+     * (Institute of Electrical and Electronics Engineers 754) double.
+     */
+    get plistSeconds(): number;
+    getPlistSeconds(): number;
+    getPlistSecondsString(): string;
+    /**
+     * Exact raw 8-byte plist payload.
+     * If the object was constructed from raw bytes, those bytes are preserved
+     * until the date is mutated.
+     */
+    getRawBytes(): Buffer;
+    toRawString(encoding?: BufferEncoding): string;
+    getRawHex(): string;
+    getRawBase64(): string;
+    toPlistString(): string;
+    toBuffer(): Buffer;
+    /**
+     * Set the exact plist-native seconds value.
+     * Returns the plist-seconds string.
+     */
+    setPlistSeconds(seconds: number): string;
+    /**
+     * Replace the date from exact raw plist bytes.
+     * Returns the plist-seconds string.
+     */
+    setRawBytes(input: PlistDateBinaryInput): string;
+    /**
+     * Parse raw hex into the exact 8-byte plist payload.
+     */
+    setRawHex(hex: string): string;
+    /**
+     * Exact Unix milliseconds derived from the canonical plist bytes.
+     * This may include a fractional millisecond.
+     */
+    getTime(): number;
+    valueOf(): number;
+    [Symbol.toPrimitive](hint: "default"): string;
+    [Symbol.toPrimitive](hint: "string"): string;
+    [Symbol.toPrimitive](hint: "number"): number;
+    toJSON(): string;
+    clone(): PlistDate;
+    equalsExactly(other: PlistDateInput): boolean;
+    equalsValue(other: PlistDateInput): boolean;
+    /**
+     * Direct time-setting path: normalize immediately to the exact
+     * plist-representable value.
+     */
+    setTime(time: number): number;
+    setMilliseconds(ms: number): number;
+    setUTCMilliseconds(ms: number): number;
+    setSeconds(sec: number, ms?: number): number;
+    setUTCSeconds(sec: number, ms?: number): number;
+    setMinutes(min: number, sec?: number, ms?: number): number;
+    setUTCMinutes(min: number, sec?: number, ms?: number): number;
+    setHours(hours: number, min?: number, sec?: number, ms?: number): number;
+    setUTCHours(hours: number, min?: number, sec?: number, ms?: number): number;
+    setDate(date: number): number;
+    setUTCDate(date: number): number;
+    setMonth(month: number, date?: number): number;
+    setUTCMonth(month: number, date?: number): number;
+    setFullYear(year: number, month?: number, date?: number): number;
+    setUTCFullYear(year: number, month?: number, date?: number): number;
+    /**
+     * @deprecated This method is deprecated and should not be used. Use setFullYear() instead.
+     */
+    setYear(year: number): number;
+}

package/dist/classes/plist-date.js

@@ -0,0 +1,389 @@
+const APPLE_PLIST_EPOCH_MS = Date.UTC(2001, 0, 1);
+function isBinaryInput(value) {
+    return (Buffer.isBuffer(value) ||
+        value instanceof Uint8Array ||
+        value instanceof ArrayBuffer);
+}
+function normalizeRaw8(input) {
+    const raw = Buffer.isBuffer(input)
+        ? Buffer.from(input)
+        : input instanceof Uint8Array
+            ? Buffer.from(input)
+            : Buffer.from(new Uint8Array(input));
+    if (raw.length !== 8) {
+        throw new RangeError(`PlistDate raw value must be exactly 8 bytes, got ${raw.length}.`);
+    }
+    return raw;
+}
+function encodePlistSeconds(seconds) {
+    const raw = Buffer.allocUnsafe(8);
+    raw.writeDoubleBE(seconds, 0);
+    return raw;
+}
+function decodePlistSeconds(raw) {
+    return raw.readDoubleBE(0);
+}
+function plistSecondsToUnixMilliseconds(seconds) {
+    return APPLE_PLIST_EPOCH_MS + seconds * 1000;
+}
+function unixMillisecondsToPlistSeconds(milliseconds) {
+    return (milliseconds - APPLE_PLIST_EPOCH_MS) / 1000;
+}
+function numberToStableString(value) {
+    if (Object.is(value, -0))
+        return "-0";
+    if (Number.isNaN(value))
+        return "NaN";
+    if (value === Infinity)
+        return "Infinity";
+    if (value === -Infinity)
+        return "-Infinity";
+    return value.toString();
+}
+/**
+ * Exact raw plist path.
+ */
+function canonicalStateFromRaw(input) {
+    const raw = normalizeRaw8(input);
+    const plistSeconds = decodePlistSeconds(raw);
+    const unixMilliseconds = plistSecondsToUnixMilliseconds(plistSeconds);
+    return { raw, plistSeconds, unixMilliseconds };
+}
+/**
+ * Canonicalize a plist-seconds number by round-tripping it through the
+ * actual 8-byte binary representation.
+ */
+function canonicalStateFromPlistSeconds(seconds) {
+    const raw = encodePlistSeconds(seconds);
+    const plistSeconds = decodePlistSeconds(raw);
+    const unixMilliseconds = plistSecondsToUnixMilliseconds(plistSeconds);
+    return { raw, plistSeconds, unixMilliseconds };
+}
+/**
+ * Canonicalize Unix milliseconds into the exact plist-representable value.
+ *
+ * This is the key fix for discrepancies like:
+ *   4410317596806472
+ * becoming
+ *   4410317596806471.5
+ *
+ * We normalize immediately instead of only discovering the change after
+ * encode -> decode.
+ */
+function canonicalStateFromUnixMilliseconds(milliseconds) {
+    return canonicalStateFromPlistSeconds(unixMillisecondsToPlistSeconds(milliseconds));
+}
+function resolveInitialState(value) {
+    if (value instanceof PlistDate) {
+        return canonicalStateFromRaw(value.getRawBytes());
+    }
+    if (isBinaryInput(value)) {
+        return canonicalStateFromRaw(value);
+    }
+    if (value instanceof Date) {
+        return canonicalStateFromUnixMilliseconds(value.getTime());
+    }
+    if (typeof value === "number") {
+        return canonicalStateFromUnixMilliseconds(value);
+    }
+    return canonicalStateFromUnixMilliseconds(Date.now());
+}
+export class PlistDate extends Date {
+    static APPLE_PLIST_EPOCH_MS = APPLE_PLIST_EPOCH_MS;
+    /**
+     * Raw 8-byte plist payload is the canonical source of truth.
+     */
+    #raw = encodePlistSeconds(0);
+    constructor(value) {
+        const state = resolveInitialState(value);
+        super(state.unixMilliseconds);
+        this.#raw = state.raw;
+    }
+    static from(input) {
+        return new PlistDate(input);
+    }
+    static fromBuffer(input) {
+        return new PlistDate(input);
+    }
+    static fromPlistSeconds(seconds) {
+        return new PlistDate(encodePlistSeconds(seconds));
+    }
+    static fromUnixMilliseconds(milliseconds) {
+        return new PlistDate(milliseconds);
+    }
+    static isPlistDate(value) {
+        return value instanceof PlistDate;
+    }
+    #applyCanonicalState(state) {
+        this.#raw = Buffer.from(state.raw);
+        // Native Date only keeps whole-millisecond precision internally.
+        // We still keep the exact plist value in #raw and expose it through
+        // plistSeconds/getTime().
+        super.setTime(state.unixMilliseconds);
+    }
+    #replaceFromRaw(input) {
+        this.#applyCanonicalState(canonicalStateFromRaw(input));
+    }
+    #replaceFromPlistSeconds(seconds) {
+        this.#applyCanonicalState(canonicalStateFromPlistSeconds(seconds));
+    }
+    #replaceFromUnixMilliseconds(milliseconds) {
+        this.#applyCanonicalState(canonicalStateFromUnixMilliseconds(milliseconds));
+        return this.getTime();
+    }
+    #resyncFromDateState() {
+        return this.#replaceFromUnixMilliseconds(super.getTime());
+    }
+    /**
+     * Exact plist-native value:
+     * seconds since 2001-01-01T00:00:00Z stored as IEEE 754
+     * (Institute of Electrical and Electronics Engineers 754) double.
+     */
+    get plistSeconds() {
+        return decodePlistSeconds(this.#raw);
+    }
+    getPlistSeconds() {
+        return this.plistSeconds;
+    }
+    getPlistSecondsString() {
+        return numberToStableString(this.plistSeconds);
+    }
+    /**
+     * Exact raw 8-byte plist payload.
+     * If the object was constructed from raw bytes, those bytes are preserved
+     * until the date is mutated.
+     */
+    getRawBytes() {
+        return Buffer.from(this.#raw);
+    }
+    toRawString(encoding = "hex") {
+        return this.#raw.toString(encoding);
+    }
+    getRawHex() {
+        return this.toRawString("hex");
+    }
+    getRawBase64() {
+        return this.toRawString("base64");
+    }
+    toPlistString() {
+        return this.getPlistSecondsString();
+    }
+    toBuffer() {
+        return this.getRawBytes();
+    }
+    /**
+     * Set the exact plist-native seconds value.
+     * Returns the plist-seconds string.
+     */
+    setPlistSeconds(seconds) {
+        if (typeof seconds !== "number") {
+            throw new TypeError("PlistDate seconds must be a number.");
+        }
+        this.#replaceFromPlistSeconds(seconds);
+        return this.getPlistSecondsString();
+    }
+    /**
+     * Replace the date from exact raw plist bytes.
+     * Returns the plist-seconds string.
+     */
+    setRawBytes(input) {
+        this.#replaceFromRaw(input);
+        return this.getPlistSecondsString();
+    }
+    /**
+     * Parse raw hex into the exact 8-byte plist payload.
+     */
+    setRawHex(hex) {
+        if (typeof hex !== "string" || !/^[0-9a-fA-F]{16}$/.test(hex)) {
+            throw new TypeError("PlistDate raw hex must be a 16-character hexadecimal string.");
+        }
+        return this.setRawBytes(Buffer.from(hex, "hex"));
+    }
+    /**
+     * Exact Unix milliseconds derived from the canonical plist bytes.
+     * This may include a fractional millisecond.
+     */
+    getTime() {
+        return plistSecondsToUnixMilliseconds(this.plistSeconds);
+    }
+    valueOf() {
+        return this.getTime();
+    }
+    [Symbol.toPrimitive](hint) {
+        if (hint === "number") {
+            return this.getTime();
+        }
+        return this.toString();
+    }
+    toJSON() {
+        return new Date(this.getTime()).toISOString();
+    }
+    clone() {
+        return new PlistDate(this.#raw);
+    }
+    equalsExactly(other) {
+        const rhs = PlistDate.from(other);
+        return this.#raw.equals(rhs.#raw);
+    }
+    equalsValue(other) {
+        const rhs = PlistDate.from(other);
+        return Object.is(this.plistSeconds, rhs.plistSeconds);
+    }
+    /**
+     * Direct time-setting path: normalize immediately to the exact
+     * plist-representable value.
+     */
+    setTime(time) {
+        return this.#replaceFromUnixMilliseconds(time);
+    }
+    setMilliseconds(ms) {
+        super.setMilliseconds(ms);
+        return this.#resyncFromDateState();
+    }
+    setUTCMilliseconds(ms) {
+        super.setUTCMilliseconds(ms);
+        return this.#resyncFromDateState();
+    }
+    setSeconds(sec, ms) {
+        if (ms === undefined) {
+            super.setSeconds(sec);
+        }
+        else {
+            super.setSeconds(sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setUTCSeconds(sec, ms) {
+        if (ms === undefined) {
+            super.setUTCSeconds(sec);
+        }
+        else {
+            super.setUTCSeconds(sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setMinutes(min, sec, ms) {
+        if (sec === undefined) {
+            super.setMinutes(min);
+        }
+        else if (ms === undefined) {
+            super.setMinutes(min, sec);
+        }
+        else {
+            super.setMinutes(min, sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setUTCMinutes(min, sec, ms) {
+        if (sec === undefined) {
+            super.setUTCMinutes(min);
+        }
+        else if (ms === undefined) {
+            super.setUTCMinutes(min, sec);
+        }
+        else {
+            super.setUTCMinutes(min, sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setHours(hours, min, sec, ms) {
+        if (min === undefined) {
+            super.setHours(hours);
+        }
+        else if (sec === undefined) {
+            super.setHours(hours, min);
+        }
+        else if (ms === undefined) {
+            super.setHours(hours, min, sec);
+        }
+        else {
+            super.setHours(hours, min, sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setUTCHours(hours, min, sec, ms) {
+        if (min === undefined) {
+            super.setUTCHours(hours);
+        }
+        else if (sec === undefined) {
+            super.setUTCHours(hours, min);
+        }
+        else if (ms === undefined) {
+            super.setUTCHours(hours, min, sec);
+        }
+        else {
+            super.setUTCHours(hours, min, sec, ms);
+        }
+        return this.#resyncFromDateState();
+    }
+    setDate(date) {
+        super.setDate(date);
+        return this.#resyncFromDateState();
+    }
+    setUTCDate(date) {
+        super.setUTCDate(date);
+        return this.#resyncFromDateState();
+    }
+    setMonth(month, date) {
+        if (date === undefined) {
+            super.setMonth(month);
+        }
+        else {
+            super.setMonth(month, date);
+        }
+        return this.#resyncFromDateState();
+    }
+    setUTCMonth(month, date) {
+        if (date === undefined) {
+            super.setUTCMonth(month);
+        }
+        else {
+            super.setUTCMonth(month, date);
+        }
+        return this.#resyncFromDateState();
+    }
+    setFullYear(year, month, date) {
+        if (month === undefined) {
+            super.setFullYear(year);
+        }
+        else if (date === undefined) {
+            super.setFullYear(year, month);
+        }
+        else {
+            super.setFullYear(year, month, date);
+        }
+        return this.#resyncFromDateState();
+    }
+    setUTCFullYear(year, month, date) {
+        if (month === undefined) {
+            super.setUTCFullYear(year);
+        }
+        else if (date === undefined) {
+            super.setUTCFullYear(year, month);
+        }
+        else {
+            super.setUTCFullYear(year, month, date);
+        }
+        return this.#resyncFromDateState();
+    }
+    /**
+     * @deprecated This method is deprecated and should not be used. Use setFullYear() instead.
+     */
+    // @ts-ignore
+    setYear(year) {
+        // @ts-ignore
+        super.setYear(year);
+        return this.#resyncFromDateState();
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        const iso = (() => {
+            try {
+                return this.toISOString();
+            }
+            catch {
+                return "Invalid Date";
+            }
+        })();
+        return `PlistDate(${iso}, plistSeconds=${this.getPlistSecondsString()}, raw=${this.getRawHex()})`;
+    }
+}

package/dist/classes/uid.d.ts

@@ -0,0 +1,6 @@
+export declare class UID extends Uint8Array {
+    static from(bytes: Uint8Array): UID;
+    constructor(buffer: ArrayBuffer, byteOffset?: number, length?: number);
+    static isUID(value: unknown): value is UID;
+    toHex(): string;
+}

package/dist/classes/uid.js

@@ -0,0 +1,26 @@
+const UID_BRAND = Symbol.for('plist.UID');
+export class UID extends Uint8Array {
+    static from(bytes) {
+        return new UID(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    constructor(buffer, byteOffset, length) {
+        super(buffer, byteOffset, length);
+        Object.defineProperty(this, UID_BRAND, {
+            value: true,
+            enumerable: false,
+        });
+    }
+    static isUID(value) {
+        return (value instanceof Uint8Array &&
+            value != null &&
+            value[UID_BRAND] === true);
+    }
+    toHex() {
+        return Array.from(this)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `UID(${this.toHex()})`;
+    }
+}

package/dist/classes/utf16-string.d.ts

@@ -0,0 +1,7 @@
+export declare class Utf16String extends Uint8Array {
+    static from(bytes: Uint8Array): Utf16String;
+    constructor(buffer: ArrayBuffer, byteOffset?: number, length?: number);
+    static isUtf16String(value: unknown): value is Utf16String;
+    toString(): string;
+    toHex(): string;
+}

package/dist/classes/utf16-string.js

@@ -0,0 +1,38 @@
+const UTF16_STRING_BRAND = Symbol.for('plist.Utf16String');
+export class Utf16String extends Uint8Array {
+    static from(bytes) {
+        return new Utf16String(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    }
+    constructor(buffer, byteOffset, length) {
+        super(buffer, byteOffset, length);
+        Object.defineProperty(this, UTF16_STRING_BRAND, {
+            value: true,
+            enumerable: false,
+        });
+    }
+    static isUtf16String(value) {
+        return (value instanceof Uint8Array &&
+            value != null &&
+            value[UTF16_STRING_BRAND] === true);
+    }
+    toString() {
+        const copy = new Uint8Array(this);
+        if (this.length % 2 !== 0) {
+            throw new Error('Invalid UTF-16 byte length');
+        }
+        for (let i = 0; i < copy.length; i += 2) {
+            const a = copy[i];
+            copy[i] = copy[i + 1];
+            copy[i + 1] = a;
+        }
+        return Buffer.from(copy).toString('ucs2');
+    }
+    toHex() {
+        return Array.from(this)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    [Symbol.for('nodejs.util.inspect.custom')]() {
+        return `Utf16String(${this.toString()})`;
+    }
+}

package/{src/exports/main.ts → dist/exports/main.d.ts}

@@ -2,4 +2,4 @@ export * from '../utils/parse.js';
 export * from '../utils/serialize.js';
 export * from '../classes/plist-date.js';
 export * from '../classes/uid.js';
-export * from '../classes/utf16-string.js';
+export * from '../classes/utf16-string.js';

package/dist/exports/main.js

@@ -0,0 +1,5 @@
+export * from '../utils/parse.js';
+export * from '../utils/serialize.js';
+export * from '../classes/plist-date.js';
+export * from '../classes/uid.js';
+export * from '../classes/utf16-string.js';

package/dist/utils/parse.d.ts

@@ -0,0 +1,3 @@
+export declare var maxObjectSize: number;
+export declare var maxObjectCount: number;
+export declare function parseBplist(buffer: Buffer): any;