pdf-lite 1.0.0

package/packages/pdf-lite/src/utils/padBytes.ts

@@ -0,0 +1,25 @@
+import { ByteArray } from '../types'
+
+/**
+ * Pads a byte array to a specified length with trailing zeros.
+ *
+ * @param bytes - The byte array to pad.
+ * @param length - The target length for the padded array.
+ * @returns A new byte array padded to the specified length.
+ * @throws Error if the input array is already longer than the target length.
+ *
+ * @example
+ * ```typescript
+ * padBytes(new Uint8Array([1, 2]), 4) // Returns Uint8Array([1, 2, 0, 0])
+ * ```
+ */
+export function padBytes(bytes: ByteArray, length: number): ByteArray {
+    if (bytes.length > length) {
+        throw new Error(
+            `Cannot pad bytes: current length ${bytes.length} is greater than or equal to target length ${length}.`,
+        )
+    }
+    const padded = new Uint8Array(length)
+    padded.set(bytes)
+    return padded
+}

package/packages/pdf-lite/src/utils/predictors.ts

@@ -0,0 +1,332 @@
+import { PdfDictionary } from '../core/objects/pdf-dictionary.js'
+import { PdfNumber } from '../core/objects/pdf-number.js'
+import { PdfObject } from '../core/objects/pdf-object.js'
+import { ByteArray, DecodeParms } from '../types.js'
+
+/**
+ * Handles PNG and TIFF predictor encoding and decoding for PDF streams.
+ * Predictors are used to improve compression efficiency by transforming
+ * image data before or after compression.
+ */
+export class Predictor {
+    /**
+     * Decodes data that was encoded with a predictor.
+     *
+     * @param data - The encoded data to decode.
+     * @param params - Optional decode parameters including Predictor, Columns, Colors, and BitsPerComponent.
+     * @returns The decoded byte array.
+     *
+     * @example
+     * ```typescript
+     * const decoded = Predictor.decode(encodedData, { Predictor: 12, Columns: 100 })
+     * ```
+     */
+    static decode(data: ByteArray, params: DecodeParms = {}): ByteArray {
+        const predictor = params.Predictor ?? 1
+        const columns = params.Columns ?? 1
+        const colors = params.Colors ?? 1
+        const bpc = params.BitsPerComponent ?? 8
+
+        const bpp = Math.ceil((colors * bpc) / 8)
+
+        if (predictor === 2) {
+            return this.tiffDecode(data, columns, bpp)
+        } else if (predictor >= 10 && predictor <= 15) {
+            return this.pngDecode(data, columns, bpp)
+        }
+
+        return data
+    }
+
+    /**
+     * Encodes data using a predictor algorithm.
+     *
+     * @param data - The data to encode.
+     * @param params - Optional encode parameters including Predictor, Columns, Colors, and BitsPerComponent.
+     * @param PdfStreamFilterType - The PNG filter type to use for encoding.
+     * @returns The encoded byte array.
+     *
+     * @example
+     * ```typescript
+     * const encoded = Predictor.encode(rawData, { Predictor: 12, Columns: 100 }, 1)
+     * ```
+     */
+    static encode(
+        data: ByteArray,
+        params: DecodeParms = {},
+        PdfStreamFilterType: number = 0,
+    ): ByteArray {
+        const predictor = params.Predictor ?? 1
+        const columns = params.Columns ?? 1
+        const colors = params.Colors ?? 1
+        const bpc = params.BitsPerComponent ?? 8
+
+        const bpp = Math.ceil((colors * bpc) / 8)
+
+        if (predictor === 2) {
+            return this.tiffEncode(data, columns, bpp)
+        } else if (predictor >= 10 && predictor <= 15) {
+            return this.pngEncode(data, columns, bpp, PdfStreamFilterType)
+        }
+
+        return data
+    }
+
+    /**
+     * Decodes TIFF predictor encoded data.
+     *
+     * @param data - The TIFF encoded data.
+     * @param columns - The number of columns in the image.
+     * @param bpp - Bytes per pixel.
+     * @returns The decoded byte array.
+     */
+    static tiffDecode(
+        data: ByteArray,
+        columns: number,
+        bpp: number,
+    ): ByteArray {
+        const rowLength = columns * bpp
+        const output = new Uint8Array(data.length)
+
+        for (let i = 0; i < data.length; i += rowLength) {
+            for (let j = 0; j < rowLength; j++) {
+                output[i + j] =
+                    j < bpp
+                        ? data[i + j]
+                        : (data[i + j] + output[i + j - bpp]) & 0xff
+            }
+        }
+
+        return output
+    }
+
+    /**
+     * Encodes data using TIFF predictor.
+     *
+     * @param data - The data to encode.
+     * @param columns - The number of columns in the image.
+     * @param bpp - Bytes per pixel.
+     * @returns The TIFF encoded byte array.
+     */
+    static tiffEncode(
+        data: ByteArray,
+        columns: number,
+        bpp: number,
+    ): ByteArray {
+        const rowLength = columns * bpp
+        const output = new Uint8Array(data.length)
+
+        for (let i = 0; i < data.length; i += rowLength) {
+            for (let j = 0; j < rowLength; j++) {
+                output[i + j] =
+                    j < bpp
+                        ? data[i + j]
+                        : (data[i + j] - data[i + j - bpp] + 256) & 0xff
+            }
+        }
+
+        return output
+    }
+
+    /**
+     * Decodes PNG predictor encoded data.
+     *
+     * @param data - The PNG encoded data.
+     * @param columns - The number of columns in the image.
+     * @param bpp - Bytes per pixel.
+     * @returns The decoded byte array.
+     * @throws Error if an unsupported PNG filter type is encountered.
+     */
+    static pngDecode(data: ByteArray, columns: number, bpp: number): ByteArray {
+        const rowLength = columns * bpp
+        const output: number[] = []
+
+        for (let i = 0; i < data.length; ) {
+            const filter = data[i]
+            const row = data.slice(i + 1, i + 1 + rowLength)
+            const prior = output.slice(output.length - rowLength, output.length)
+
+            const decodedRow = new Uint8Array(rowLength)
+            for (let j = 0; j < rowLength; j++) {
+                const left = j >= bpp ? decodedRow[j - bpp] : 0
+                const up = prior[j] ?? 0
+                const upperLeft = j >= bpp ? (prior[j - bpp] ?? 0) : 0
+
+                switch (filter) {
+                    case 0:
+                        decodedRow[j] = row[j]
+                        break
+                    case 1:
+                        decodedRow[j] = (row[j] + left) & 0xff
+                        break
+                    case 2:
+                        decodedRow[j] = (row[j] + up) & 0xff
+                        break
+                    case 3:
+                        decodedRow[j] =
+                            (row[j] + Math.floor((left + up) / 2)) & 0xff
+                        break
+                    case 4:
+                        decodedRow[j] =
+                            (row[j] +
+                                this.paethPredictor(left, up, upperLeft)) &
+                            0xff
+                        break
+                    default:
+                        throw new Error(`Unsupported PNG filter: ${filter}`)
+                }
+            }
+
+            output.push(...decodedRow)
+            i += 1 + rowLength
+        }
+
+        return new Uint8Array(output)
+    }
+
+    /**
+     * Encodes data using PNG predictor.
+     *
+     * @param data - The data to encode.
+     * @param columns - The number of columns in the image.
+     * @param bpp - Bytes per pixel.
+     * @param PdfStreamFilterType - The PNG filter type (0-4) to use.
+     * @returns The PNG encoded byte array.
+     * @throws Error if an unsupported PNG filter type is specified.
+     */
+    static pngEncode(
+        data: ByteArray,
+        columns: number,
+        bpp: number,
+        PdfStreamFilterType: number,
+    ): ByteArray {
+        const rowLength = columns * bpp
+        const output: number[] = []
+        let prior = new Uint8Array(rowLength)
+
+        for (let i = 0; i < data.length; i += rowLength) {
+            const row = data.slice(i, i + rowLength)
+            const encodedRow = new Uint8Array(rowLength)
+
+            for (let j = 0; j < rowLength; j++) {
+                const left = j >= bpp ? row[j - bpp] : 0
+                const up = prior[j] ?? 0
+                const upperLeft = j >= bpp ? (prior[j - bpp] ?? 0) : 0
+
+                switch (PdfStreamFilterType) {
+                    case 0:
+                        encodedRow[j] = row[j]
+                        break
+                    case 1:
+                        encodedRow[j] = (row[j] - left + 256) & 0xff
+                        break
+                    case 2:
+                        encodedRow[j] = (row[j] - up + 256) & 0xff
+                        break
+                    case 3:
+                        encodedRow[j] =
+                            (row[j] - Math.floor((left + up) / 2) + 256) & 0xff
+                        break
+                    case 4:
+                        encodedRow[j] =
+                            (row[j] -
+                                this.paethPredictor(left, up, upperLeft) +
+                                256) &
+                            0xff
+                        break
+                    default:
+                        throw new Error(
+                            `Unsupported PNG filter: ${PdfStreamFilterType}`,
+                        )
+                }
+            }
+
+            output.push(PdfStreamFilterType, ...encodedRow)
+            prior = row
+        }
+
+        return new Uint8Array(output)
+    }
+
+    /**
+     * Implements the Paeth predictor algorithm used in PNG filtering.
+     *
+     * @param a - The left pixel value.
+     * @param b - The above pixel value.
+     * @param c - The upper-left pixel value.
+     * @returns The predicted pixel value.
+     */
+    private static paethPredictor(a: number, b: number, c: number): number {
+        const p = a + b - c
+        const pa = Math.abs(p - a)
+        const pb = Math.abs(p - b)
+        const pc = Math.abs(p - c)
+
+        if (pa <= pb && pa <= pc) return a
+        if (pb <= pc) return b
+        return c
+    }
+
+    /**
+     * Extracts decode parameters from a PDF dictionary.
+     *
+     * @param decodeParms - Optional PDF dictionary containing decode parameters.
+     * @returns The decode parameters object or null if not applicable.
+     *
+     * @example
+     * ```typescript
+     * const params = Predictor.getDecodeParms(dictionary)
+     * if (params) {
+     *   console.log(params.Predictor)
+     * }
+     * ```
+     */
+    static getDecodeParms(decodeParms?: PdfDictionary): DecodeParms | null {
+        if (!decodeParms) {
+            return null
+        }
+
+        const predictor = decodeParms.get('Predictor')?.as(PdfNumber)?.value
+
+        if (predictor === undefined) {
+            return null
+        }
+
+        if (predictor <= 1 || predictor > 15) {
+            return null
+        }
+
+        const BitsPerComponent = decodeParms
+            .get('BitsPerComponent')
+            ?.as(PdfNumber)
+        const Columns = decodeParms.get('Columns')?.as(PdfNumber)
+        const Colors = decodeParms.get('Colors')?.as(PdfNumber)
+
+        return {
+            BitsPerComponent: BitsPerComponent?.value,
+            Columns: Columns?.value,
+            Predictor: predictor,
+            Colors: Colors?.value,
+        }
+    }
+
+    /**
+     * Checks if the decode parameters can be handled by this predictor.
+     *
+     * @param decodeParms - Optional PDF dictionary containing decode parameters.
+     * @returns True if the parameters can be handled, false otherwise.
+     *
+     * @example
+     * ```typescript
+     * if (Predictor.canHandleDecodeParms(dictionary)) {
+     *   // Process with predictor
+     * }
+     * ```
+     */
+    static canHandleDecodeParms(decodeParms?: PdfDictionary): boolean {
+        if (Predictor.getDecodeParms(decodeParms) === null) {
+            return false
+        }
+        return true
+    }
+}

package/packages/pdf-lite/src/utils/replaceInBuffer.ts

@@ -0,0 +1,56 @@
+import { ByteArray } from '../types'
+
+/**
+ * Replaces occurrences of a search buffer with a replacement buffer within a target buffer.
+ *
+ * @typeParam T - The type of the target buffer, extending ByteArray.
+ * @param searchBuffer - The byte pattern to search for.
+ * @param replaceBuffer - The byte pattern to replace with.
+ * @param targetBuffer - The buffer to search within.
+ * @param multiple - Whether to replace all occurrences or just the first. Defaults to false.
+ * @returns A new byte array with the replacements made.
+ * @throws Error if the search buffer is not found in the target buffer.
+ *
+ * @example
+ * ```typescript
+ * const result = replaceInBuffer(
+ *   new Uint8Array([1, 2]),
+ *   new Uint8Array([3, 4, 5]),
+ *   new Uint8Array([0, 1, 2, 6])
+ * ) // Returns Uint8Array([0, 3, 4, 5, 6])
+ * ```
+ */
+export function replaceInBuffer<T extends ByteArray>(
+    searchBuffer: ByteArray,
+    replaceBuffer: ByteArray,
+    targetBuffer: T,
+    multiple: boolean = false,
+): ByteArray {
+    const searchLength = searchBuffer.length
+    const replaceLength = replaceBuffer.length
+    const targetLength = targetBuffer.length
+    const result = new Uint8Array(targetLength - searchLength + replaceLength)
+    let found = false
+    let offset = 0
+    for (let i = 0; i < targetLength; i++) {
+        if (
+            (multiple || !found) &&
+            i <= targetLength - searchLength &&
+            targetBuffer
+                .subarray(i, i + searchLength)
+                .every((value, index) => value === searchBuffer[index])
+        ) {
+            result.set(replaceBuffer, offset)
+            offset += replaceLength
+            i += searchLength - 1 // Skip the length of the search buffer
+            found = true
+        } else {
+            result[offset++] = targetBuffer[i]
+        }
+    }
+
+    if (!found) {
+        throw new Error(`Search buffer not found in target buffer`)
+    }
+    return result
+}

package/packages/pdf-lite/src/utils/stringToBytes.ts

@@ -0,0 +1,22 @@
+import { ByteArray } from '../types'
+
+/**
+ * Converts a string or byte array to a byte array using UTF-8 encoding.
+ * If the input is already a byte array, it is returned as-is.
+ *
+ * @param str - The string or byte array to convert.
+ * @returns The input as a byte array.
+ *
+ * @example
+ * ```typescript
+ * stringToBytes('Hello') // Returns Uint8Array([72, 101, 108, 108, 111])
+ * ```
+ */
+export function stringToBytes(str: string | ByteArray): ByteArray {
+    if (typeof str === 'string') {
+        const encoder = new TextEncoder()
+        return encoder.encode(str) as ByteArray
+    } else {
+        return str
+    }
+}

package/packages/pdf-lite/src/utils/stringToHexBytes.ts

@@ -0,0 +1,23 @@
+import { ByteArray } from '../types'
+
+/**
+ * Converts a hexadecimal string (optionally with angle brackets) to a byte array.
+ * Strips any surrounding angle brackets before conversion.
+ *
+ * @param str - The hexadecimal string to convert, optionally wrapped in angle brackets.
+ * @returns A byte array with the decoded values.
+ *
+ * @example
+ * ```typescript
+ * stringToHexBytes('<FF00>') // Returns Uint8Array([255, 0])
+ * stringToHexBytes('FF00') // Also returns Uint8Array([255, 0])
+ * ```
+ */
+export function stringToHexBytes(str: string): ByteArray {
+    const hex = str.replace(/<|>/g, '')
+    const bytes = new Uint8Array(hex.length / 2)
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16)
+    }
+    return bytes
+}

package/packages/pdf-lite/src/utils/unescapeString.ts

@@ -0,0 +1,123 @@
+import { ByteArray } from '../types'
+
+/**
+ * Unescapes a PDF literal string by processing escape sequences.
+ * Handles escape sequences for special characters including newlines, tabs,
+ * backslashes, parentheses, and octal character codes.
+ *
+ * @param input - The escaped byte array to unescape.
+ * @returns A new byte array with escape sequences converted to their literal values.
+ *
+ * @example
+ * ```typescript
+ * // Unescapes '\n' to a literal newline
+ * unescapeString(new Uint8Array([0x5c, 0x6e])) // Returns Uint8Array([0x0a])
+ * ```
+ */
+export function unescapeString(input: ByteArray): ByteArray {
+    const buffer = input
+    const bytes: number[] = []
+    let offset = 0
+    let nesting = 1
+    let inEscape = false
+
+    const ByteMap = {
+        LEFT_PARENTHESIS: 0x28,
+        RIGHT_PARENTHESIS: 0x29,
+        BACKSLASH: 0x5c,
+        n: 0x6e,
+        r: 0x72,
+        t: 0x74,
+        b: 0x62,
+        f: 0x66,
+    }
+
+    function isOctet(byte: number): boolean {
+        return byte >= 0x30 && byte <= 0x37 // 0-7
+    }
+
+    while (inEscape || nesting > 0) {
+        if (offset >= buffer.length) {
+            break
+        }
+
+        if (buffer[offset] === ByteMap.LEFT_PARENTHESIS) {
+            nesting++
+        } else if (buffer[offset] === ByteMap.RIGHT_PARENTHESIS) {
+            nesting--
+            if (nesting === 0) {
+                offset++
+                break
+            }
+        } else if (buffer[offset] === ByteMap.BACKSLASH || inEscape) {
+            inEscape = true
+            const next = buffer[offset + 1]
+
+            if (next === undefined) {
+                break
+            }
+
+            switch (next) {
+                case ByteMap.n:
+                    bytes.push(0x0a)
+                    break // \n
+                case ByteMap.r:
+                    bytes.push(0x0d)
+                    break // \r
+                case ByteMap.t:
+                    bytes.push(0x09)
+                    break // \t
+                case ByteMap.b:
+                    bytes.push(0x08)
+                    break // \b
+                case ByteMap.f:
+                    bytes.push(0x0c)
+                    break // \f
+                case ByteMap.LEFT_PARENTHESIS:
+                    bytes.push(ByteMap.LEFT_PARENTHESIS)
+                    break // \(
+                case ByteMap.RIGHT_PARENTHESIS:
+                    bytes.push(ByteMap.RIGHT_PARENTHESIS)
+                    break // \)
+                case ByteMap.BACKSLASH:
+                    bytes.push(ByteMap.BACKSLASH)
+                    break // \\
+                case 0x0a:
+                case 0x0d:
+                    // Ignore line breaks in the string after a backslash
+                    break
+                default:
+                    if (isOctet(next)) {
+                        let octal = String.fromCharCode(next)
+                        // Octal: up to 3 digits
+                        const next2 = buffer[offset + 2]
+                        if (next2 !== undefined && isOctet(next2)) {
+                            octal += String.fromCharCode(next2)
+                            const next3 = buffer[offset + 3]
+                            if (next3 !== undefined && isOctet(next3)) {
+                                octal += String.fromCharCode(next3)
+                            }
+                        }
+
+                        bytes.push(parseInt(octal, 8))
+                        offset += octal.length + 1 // Adjust offset for the number of octal digits
+                        inEscape = false
+                        continue
+                    } else {
+                        // If it's not a valid escape sequence, just add the next byte
+                        bytes.push(next)
+                    }
+                    break
+            }
+
+            offset += 2 // Skip the escape character and the next character
+            inEscape = false
+            continue
+        }
+
+        bytes.push(buffer[offset])
+        offset++
+    }
+
+    return new Uint8Array(bytes)
+}