@file-type/pdf 0.1.0

package/LICENSE.txt

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Borewit
+
+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,50 @@
+[![NPM version](https://img.shields.io/npm/v/@file-type/pdf.svg)](https://npmjs.org/package/@file-type/pdf)
+[![Node.js CI](https://github.com/Borewit/file-type-pdf/actions/workflows/nodejs-ci.yml/badge.svg)](https://github.com/Borewit/file-type-pdf/actions/workflows/nodejs-ci.yml)
+[![npm downloads](http://img.shields.io/npm/dm/@file-type/pdf.svg)](https://npmcharts.com/compare/@file-type/pdf?start=365)
+
+# @file-type/pdf
+
+Detector plugin for [file-type](https://github.com/sindresorhus/file-type) that identifies
+[PDF (Portable Document Format)](https://en.wikipedia.org/wiki/PDF) files and selected PDF-based subtypes.
+
+This plugin goes beyond simple magic-number detection and can inspect the internal PDF
+structure to distinguish between generic PDF files and specific producer formats such as
+**Adobe Illustrator (.ai)**.
+
+The detector is designed to be:
+- tokenizer-based (using `strtok3`)
+- streaming-friendly
+- safe to chain with other `file-type` detectors
+- compatible with both Node.js and browser environments
+
+## Installation
+
+```bash
+npm install @file-type/pdf
+```
+
+## Usage
+
+The following example shows how to add the PDF detector to [file-type](https://github.com/sindresorhus/file-type):
+
+```js
+import { FileTypeParser } from 'file-type';
+import { detectPdf } from '@file-type/pdf';
+
+const parser = new FileTypeParser({
+  customDetectors: [detectPdf],
+});
+
+const fileType = await parser.fromFile('example.pdf');
+console.log(fileType);
+```
+
+## Supported file formats
+
+- `.ai` / `application/illustrator`: Adobe Illustrator
+- `.pdf` / `application/pdf`: Generic Portable Document Format files
+
+## License
+
+This project is licensed under the [MIT License](LICENSE.txt).
+Feel free to use, modify, and distribute it as needed.

package/lib/PdfTokenizerReader.d.ts

@@ -0,0 +1,36 @@
+import type { ITokenizer } from "strtok3";
+export type PdfTokenizerReaderOptions = {
+    chunkSize?: number;
+    debug?: boolean;
+};
+export declare class PdfTokenizerReader {
+    private tokenizer;
+    private buf;
+    private pos;
+    private chunkSize;
+    private eof;
+    private debug;
+    constructor(tokenizer: ITokenizer, opts?: PdfTokenizerReaderOptions);
+    private log;
+    /**
+     * Logical file position of the next byte that will be consumed by the reader.
+     */
+    getPosition(): number;
+    private peekMayBeLess;
+    private readMayBeLess;
+    private compactBuffer;
+    private fill;
+    /**
+     * Reads a line terminated by '\n' (supports '\r\n').
+     * Returns the line (latin1) without line ending, or null at EOF.
+     */
+    readLine(): Promise<string | null>;
+    /**
+     * Reads exactly n bytes, or returns null if EOF occurs before n bytes are available.
+     */
+    readBytes(n: number): Promise<Buffer | null>;
+    /**
+     * Consume exactly one EOL after the 'stream' keyword if present.
+     */
+    consumeStreamEol(): Promise<void>;
+}

package/lib/PdfTokenizerReader.js

@@ -0,0 +1,145 @@
+export class PdfTokenizerReader {
+    constructor(tokenizer, opts = {}) {
+        this.buf = Buffer.alloc(0);
+        this.pos = 0;
+        this.eof = false;
+        this.tokenizer = tokenizer;
+        this.chunkSize = opts.chunkSize ?? 64 * 1024;
+        this.debug = !!opts.debug;
+    }
+    log(msg) {
+        if (this.debug)
+            console.log(msg);
+    }
+    /**
+     * Logical file position of the next byte that will be consumed by the reader.
+     */
+    getPosition() {
+        const bufferedRemaining = this.buf.length - this.pos;
+        return this.tokenizer.position - bufferedRemaining;
+    }
+    async peekMayBeLess(target, length) {
+        const opts = { length, mayBeLess: true };
+        try {
+            return await this.tokenizer.peekBuffer(target, opts);
+        }
+        catch (e) {
+            if (isEndOfStreamError(e))
+                return 0;
+            throw e;
+        }
+    }
+    async readMayBeLess(target, length) {
+        const opts = { length, mayBeLess: true };
+        try {
+            return await this.tokenizer.readBuffer(target, opts);
+        }
+        catch (e) {
+            if (isEndOfStreamError(e))
+                return 0;
+            throw e;
+        }
+    }
+    compactBuffer() {
+        if (this.pos > 0) {
+            this.buf = this.buf.subarray(this.pos);
+            this.pos = 0;
+        }
+    }
+    async fill(minBytes = 1) {
+        if (this.eof)
+            return;
+        while (!this.eof && (this.buf.length - this.pos) < minBytes) {
+            this.compactBuffer();
+            // Peek first, then read exactly what we peeked
+            const peekBuf = Buffer.alloc(this.chunkSize);
+            const peeked = await this.peekMayBeLess(peekBuf, peekBuf.length);
+            if (!peeked) {
+                this.eof = true;
+                this.log(`[READER] EOF @${this.getPosition()} (peekBuffer returned 0)`);
+                break;
+            }
+            const readBuf = Buffer.alloc(peeked);
+            const read = await this.readMayBeLess(readBuf, readBuf.length);
+            if (!read) {
+                this.eof = true;
+                this.log(`[READER] EOF @${this.getPosition()} (readBuffer returned 0)`);
+                break;
+            }
+            const slice = readBuf.subarray(0, read);
+            this.buf = this.buf.length ? Buffer.concat([this.buf, slice]) : slice;
+        }
+    }
+    /**
+     * Reads a line terminated by '\n' (supports '\r\n').
+     * Returns the line (latin1) without line ending, or null at EOF.
+     */
+    async readLine() {
+        while (true) {
+            const idx = this.buf.indexOf(0x0a, this.pos); // '\n'
+            if (idx !== -1) {
+                let lineBuf = this.buf.subarray(this.pos, idx);
+                if (lineBuf.length && lineBuf[lineBuf.length - 1] === 0x0d) {
+                    lineBuf = lineBuf.subarray(0, lineBuf.length - 1); // drop '\r'
+                }
+                this.pos = idx + 1;
+                return lineBuf.toString("latin1");
+            }
+            const before = this.buf.length - this.pos;
+            await this.fill(before + 1);
+            const after = this.buf.length - this.pos;
+            if (after === before && this.eof) {
+                if (before === 0)
+                    return null;
+                const tail = this.buf.subarray(this.pos);
+                this.pos = this.buf.length;
+                return tail.toString("latin1");
+            }
+        }
+    }
+    /**
+     * Reads exactly n bytes, or returns null if EOF occurs before n bytes are available.
+     */
+    async readBytes(n) {
+        if (n < 0)
+            throw new Error("readBytes(n): n must be >= 0");
+        if (n === 0)
+            return Buffer.alloc(0);
+        await this.fill(n);
+        const avail = this.buf.length - this.pos;
+        if (avail < n)
+            return null;
+        const out = this.buf.subarray(this.pos, this.pos + n);
+        this.pos += n;
+        return out;
+    }
+    /**
+     * Consume exactly one EOL after the 'stream' keyword if present.
+     */
+    async consumeStreamEol() {
+        await this.fill(1);
+        const avail = this.buf.length - this.pos;
+        if (avail <= 0)
+            return;
+        const b0 = this.buf[this.pos];
+        if (b0 === 0x0d) {
+            await this.fill(2);
+            const avail2 = this.buf.length - this.pos;
+            if (avail2 >= 2 && this.buf[this.pos + 1] === 0x0a)
+                this.pos += 2; // \r\n
+            else
+                this.pos += 1; // \r
+        }
+        else if (b0 === 0x0a) {
+            this.pos += 1; // \n
+        }
+    }
+}
+function isEndOfStreamError(e) {
+    if (!e || typeof e !== "object")
+        return false;
+    const anyE = e;
+    const name = typeof anyE.name === "string" ? anyE.name : "";
+    const message = typeof anyE.message === "string" ? anyE.message : "";
+    return name === "EndOfStreamError" || message.includes("End-Of-Stream");
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from 'file-type';
+export declare const detectPdf: Detector;

package/lib/index.js

@@ -0,0 +1,348 @@
+import sax from "sax";
+import { PdfTokenizerReader } from "./PdfTokenizerReader.js";
+const OBJ_REGEX = /^\s*(\d+)\s+(\d+)\s+obj\b/;
+const PDF_TYPE = Object.freeze({ ext: "pdf", mime: "application/pdf" });
+const AI_TYPE = Object.freeze({ ext: "ai", mime: "application/illustrator" });
+const encoder = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8");
+function indexOfBytes(hay, needle) {
+    if (needle.length === 0)
+        return 0;
+    outer: for (let i = 0; i <= hay.length - needle.length; i++) {
+        for (let j = 0; j < needle.length; j++) {
+            if (hay[i + j] !== needle[j])
+                continue outer;
+        }
+        return i;
+    }
+    return -1;
+}
+async function peekPdfHeader(tokenizer) {
+    const buf = new Uint8Array(1024);
+    let n = 0;
+    try {
+        const opts = { length: buf.length, mayBeLess: true };
+        n = await tokenizer.peekBuffer(buf, opts);
+    }
+    catch {
+        return { isPdf: false, headerOffset: -1 };
+    }
+    if (!n)
+        return { isPdf: false, headerOffset: -1 };
+    const hay = buf.subarray(0, n);
+    const idx = indexOfBytes(hay, encoder.encode("%PDF-"));
+    if (idx === -1)
+        return { isPdf: false, headerOffset: -1 };
+    return { isPdf: true, headerOffset: idx };
+}
+async function skipBytes(tokenizer, n) {
+    if (n <= 0)
+        return;
+    const tmp = new Uint8Array(Math.min(64 * 1024, n));
+    let left = n;
+    while (left > 0) {
+        const len = Math.min(tmp.length, left);
+        const opts = { length: len };
+        const read = await tokenizer.readBuffer(tmp, opts);
+        if (!read)
+            throw new Error("Unexpected EOF while skipping bytes");
+        left -= read;
+    }
+}
+function parseDictFromRaw(raw) {
+    const dictRegex = /\/(\w+)(?:\s+([^/>\n\r]+))?/g;
+    const info = {};
+    let match = dictRegex.exec(raw);
+    while (match !== null) {
+        const key = match[1];
+        const value = match[2] ? match[2].trim() : true;
+        info[key] = value;
+        match = dictRegex.exec(raw);
+    }
+    return info;
+}
+function normalizeFilters(filterValue) {
+    if (!filterValue || filterValue === true)
+        return [];
+    const names = String(filterValue).match(/FlateDecode|ASCII85Decode|LZWDecode|RunLengthDecode/g);
+    return names ? [...new Set(names)] : [];
+}
+async function inflateFlateDecode(data) {
+    try {
+        return await inflateWithFormat("deflate", data);
+    }
+    catch {
+        return await inflateWithFormat("deflate-raw", data);
+    }
+}
+async function inflateWithFormat(format, data) {
+    // Normalize input so TS sees an ArrayBuffer-backed Uint8Array (not ArrayBufferLike/SharedArrayBuffer).
+    const normalized = new Uint8Array(data.byteLength);
+    normalized.set(data);
+    const ds = new DecompressionStream(format);
+    // Use the most permissive stream element type and cast pipeThrough to avoid DOM lib generic friction.
+    const input = new ReadableStream({
+        start(controller) {
+            controller.enqueue(normalized); // Uint8Array is a valid chunk at runtime
+            controller.close();
+        },
+    });
+    const out = input.pipeThrough(ds);
+    const ab = await new Response(out).arrayBuffer();
+    return new Uint8Array(ab);
+}
+async function decodeStreamBytes(objectInfo, rawBytes) {
+    const filters = normalizeFilters(objectInfo.Filter);
+    if (!filters.length)
+        return rawBytes;
+    let out = rawBytes;
+    for (const f of filters) {
+        if (f === "FlateDecode") {
+            out = await inflateFlateDecode(out);
+        }
+        else {
+            // Unsupported filters, return raw stream
+            return rawBytes;
+        }
+    }
+    return out;
+}
+async function readDictionaryBlock(reader, firstLine) {
+    let raw = firstLine;
+    while (!raw.includes(">>")) {
+        const next = await reader.readLine();
+        if (next === null)
+            break;
+        raw += `\n${next}`;
+    }
+    const start = raw.indexOf("<<");
+    const end = raw.indexOf(">>", start + 2);
+    if (start === -1 || end === -1)
+        return { dictText: null, streamInline: false };
+    const dictText = raw.slice(start + 2, end).trim();
+    const after = raw.slice(end + 2).trim();
+    const streamInline = after === "stream" || after.startsWith("stream ");
+    return { dictText, streamInline };
+}
+class XmlHandler {
+    constructor(opts = {}) {
+        this.readingCreatorTool = false;
+        this.onCreatorTool = opts.onCreatorTool;
+        this.saxParser = sax.parser(true, { xmlns: true });
+        this.saxParser.onerror = (e) => {
+            if (e.message.startsWith("Invalid character entity")) {
+                this.saxParser.error = null;
+                this.saxParser.resume();
+                return;
+            }
+            throw e;
+        };
+        this.saxParser.onopentag = (node) => {
+            const tag = node;
+            const isCreatorTool = tag.uri === "http://ns.adobe.com/xap/1.0/" && tag.local === "CreatorTool";
+            // Fallback by name, in case xmlns typing/runtime differs
+            const nameMatch = typeof tag.name === "string" &&
+                (tag.name === "xap:CreatorTool" ||
+                    tag.name.endsWith(":CreatorTool") ||
+                    tag.name === "CreatorTool");
+            this.readingCreatorTool = isCreatorTool || nameMatch;
+        };
+        this.saxParser.ontext = (text) => {
+            if (!this.readingCreatorTool)
+                return;
+            this.onCreatorTool?.(text);
+            this.readingCreatorTool = false;
+        };
+        this.saxParser.onclosetag = () => {
+            this.readingCreatorTool = false;
+        };
+    }
+    write(text) {
+        this.saxParser.write(text);
+    }
+    close() {
+        this.saxParser.close();
+    }
+}
+function createIllustratorProbe() {
+    return {
+        name: "adobe-illustrator",
+        onDict: (_ctx, dictText, dict) => {
+            if (dict.Illustrator === true)
+                return AI_TYPE;
+            if (dictText.includes("/Illustrator"))
+                return AI_TYPE;
+            const creator = dict.Creator;
+            const producer = dict.Producer;
+            if (creator && creator !== true && String(creator).includes("Illustrator"))
+                return AI_TYPE;
+            if (producer && producer !== true && String(producer).includes("Illustrator"))
+                return AI_TYPE;
+            if (dictText.includes("Adobe Illustrator"))
+                return AI_TYPE;
+            return undefined;
+        },
+        onCreatorTool: (_ctx, creatorTool) => {
+            if (creatorTool.toLowerCase().includes("illustrator"))
+                return AI_TYPE;
+            return undefined;
+        },
+        onStreamText: (_ctx, streamText) => {
+            if (streamText.includes("Adobe Illustrator"))
+                return AI_TYPE;
+            return undefined;
+        },
+    };
+}
+const subtypeProbes = [createIllustratorProbe()];
+/**
+ * File-type detector plugin:
+ * - returns undefined if NOT a PDF (and does not advance tokenizer.position in that case)
+ * - returns PDF_TYPE for PDF
+ * - returns subtype result when a probe matches (e.g. AI_TYPE)
+ */
+async function _detectPdf(tokenizer, opts = {}) {
+    const debug = !!opts.debug;
+    const maxScanLines = opts.maxScanLines ?? 50000;
+    const log = (...args) => {
+        if (debug)
+            console.log(...args);
+    };
+    const ctx = { debug, log };
+    // NOT PDF => PEEK ONLY, do not advance
+    const { isPdf, headerOffset } = await peekPdfHeader(tokenizer);
+    if (!isPdf)
+        return undefined;
+    // Confirmed PDF => ok to advance
+    log(`[PDF] Detected %PDF- header at +${headerOffset} (abs=${tokenizer.position + headerOffset})`);
+    if (headerOffset > 0)
+        await skipBytes(tokenizer, headerOffset);
+    const reader = new PdfTokenizerReader(tokenizer, { debug });
+    // pushback so we don't lose a line when probing for "stream"
+    let pendingLine = null;
+    const readLine = async () => {
+        if (pendingLine !== null) {
+            const l = pendingLine;
+            pendingLine = null;
+            return l;
+        }
+        return await reader.readLine();
+    };
+    const creatorToolListeners = subtypeProbes
+        .map(p => p.onCreatorTool)
+        .filter((fn) => typeof fn === "function");
+    log("[ROOT] Start parsing (PDF)");
+    let state = 0; // ROOT=0, OBJ=10
+    let scannedLines = 0;
+    while (scannedLines++ < maxScanLines) {
+        const line = await readLine();
+        if (line === null)
+            break;
+        if (state === 0) {
+            const m = OBJ_REGEX.exec(line);
+            if (m) {
+                log(`Found object: ${m[1]} Generation: ${m[2]}`);
+                state = 10;
+            }
+            continue;
+        }
+        if (state === 10) {
+            if (line.trim() === "endobj") {
+                log("[OBJ] => [ROOT]");
+                state = 0;
+                continue;
+            }
+            if (!line.includes("<<"))
+                continue;
+            const { dictText, streamInline } = await readDictionaryBlock(reader, line);
+            if (!dictText)
+                continue;
+            log(`[OBJ] Dictionary content: ${dictText.replace(/\s+/g, " ")}`);
+            log(streamInline ? "[OBJ] Stream keyword detected: stream" : "[OBJ] No stream keyword present on this line.");
+            const objectInfo = parseDictFromRaw(dictText);
+            // Dict probes
+            for (const probe of subtypeProbes) {
+                if (!probe.onDict)
+                    continue;
+                const hit = probe.onDict(ctx, dictText, objectInfo);
+                if (hit)
+                    return hit;
+            }
+            // Stream check with pushback
+            let hasStream = streamInline;
+            if (!hasStream) {
+                const nextLine = await readLine();
+                if (nextLine === null)
+                    break;
+                if (nextLine.trim() === "stream") {
+                    hasStream = true;
+                }
+                else {
+                    pendingLine = nextLine;
+                }
+            }
+            if (!hasStream)
+                continue;
+            // Length may be indirect like "12 0 R", skip if not numeric
+            const lenVal = objectInfo.Length;
+            if (!lenVal || lenVal === true)
+                continue;
+            const streamLength = parseInt(lenVal, 10);
+            if (!Number.isFinite(streamLength) || streamLength < 0)
+                continue;
+            log(`[OBJ] => [STREAM] Start read stream of ${streamLength} bytes`);
+            await reader.consumeStreamEol();
+            const rawBytes = await reader.readBytes(streamLength);
+            if (!rawBytes)
+                break;
+            const decodedBytes = await decodeStreamBytes(objectInfo, rawBytes);
+            const streamText = utf8Decoder.decode(decodedBytes);
+            // Stream probes
+            for (const probe of subtypeProbes) {
+                if (!probe.onStreamText)
+                    continue;
+                const hit = probe.onStreamText(ctx, streamText, objectInfo);
+                if (hit)
+                    return hit;
+            }
+            // XMP CreatorTool
+            const looksLikeXmp = objectInfo.Type === "Metadata" ||
+                objectInfo.Type === "/Metadata" ||
+                objectInfo.Subtype === "XML" ||
+                objectInfo.Subtype === "/XML" ||
+                objectInfo.XML === true;
+            if (looksLikeXmp && creatorToolListeners.length) {
+                log("[STREAM] XML metadata detected, feeding SAX");
+                const xml = new XmlHandler({
+                    onCreatorTool: (v) => {
+                        log(`CreatorTool=${v}`);
+                        for (const fn of creatorToolListeners) {
+                            const hit = fn(ctx, v);
+                            if (hit)
+                                throw hit;
+                        }
+                    },
+                });
+                try {
+                    xml.write(streamText);
+                    xml.close();
+                }
+                catch (e) {
+                    if (e && typeof e === "object" && "ext" in e && "mime" in e) {
+                        return e;
+                    }
+                    throw e;
+                }
+            }
+            log("[STREAM] => [OBJ]");
+        }
+    }
+    log("[ROOT] Done parsing (PDF)");
+    return PDF_TYPE;
+}
+export const detectPdf = {
+    id: 'cfbf',
+    detect: async (tokenizer) => {
+        return _detectPdf(tokenizer);
+    }
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@file-type/pdf",
+	"version": "0.1.0",
+	"description": "file-type plugin to parse PDF files",
+	"type": "module",
+	"exports": {
+		"default": "./parse.js"
+	},
+	"files": [
+		"lib/**/*.js",
+		"lib/**/*.d.ts"
+	],
+	"scripts": {
+		"clean": "del-cli lib/**/*.js lib/**/*.js.map lib/**/*.d.ts src/**/*.d.ts",
+		"compile": "tsc -p lib",
+		"build": "npm run clean && npm run compile",
+		"lint:ts": "biome check",
+		"test": "mocha",
+		"prepublishOnly": "npm run build",
+		"update-biome": "npm add -D --exact @biomejs/biome && npx @biomejs/biome migrate --write"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Borewit/file-type-pdf.git"
+	},
+	"keywords": [
+		"file-type",
+		"PDF",
+		"XMP"
+	],
+	"author": "Borewit",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/Borewit/file-type-pdf/issues"
+	},
+	"homepage": "https://github.com/Borewit/file-type-pdf#readme",
+	"dependencies": {
+		"read-next-line": "^0.5.0",
+		"sax": "^1.4.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.10",
+		"@types/node": "^25.0.3",
+		"@types/sax": "^1.2.7",
+		"chai": "^6.2.2",
+		"del-cli": "^7.0.0",
+		"file-type": "^21.2.0",
+		"mocha": "^11.7.5",
+		"strtok3": "^10.3.4",
+		"typescript": "^5.9.3"
+	}
+}