@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/syntax/parser-obj.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview PDF typed-object constructors and reflection helpers.
+ *
+ * Extracted from `parser.js` so the parser orchestrator stays under the
+ * 300-LOC cap. The `obj` factory is the canonical way to build typed
+ * objects literally — both internal use (parser construction) and
+ * external use (tests, content-stream serializers in L1+).
+ *
+ * @module pdf/syntax/parser-obj
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+export const pdfParserObj = {
+    name: 'pdfParserObj',
+    dependencies: [],
+    factory() {
+        const obj = {
+            nul:    () => ({ type: 'null' }),
+            bool:   (v) => ({ type: 'bool',   value: !!v }),
+            int:    (v) => ({ type: 'int',    value: v | 0 }),
+            real:   (v) => ({ type: 'real',   value: +v }),
+            name:   (s) => ({ type: 'name',   value: String(s) }),
+            string: (bytes, syntax) => ({
+                type: 'string',
+                value: bytes,
+                syntax: syntax === 'hex' ? 'hex' : 'lit'
+            }),
+            array:  (items) => ({ type: 'array', items: items || [] }),
+            dict:   (entries) => ({ type: 'dict', entries: entries || {} }),
+            ref:    (num, gen) => ({ type: 'ref', num: num | 0, gen: (gen | 0) || 0 }),
+            stream: (dict, raw) => ({ type: 'stream', dict, raw })
+        };
+
+        function getEntry(dict, key) {
+            if (!dict || dict.type !== 'dict') return undefined;
+            return dict.entries[key];
+        }
+
+        function isType(v, kind) {
+            return !!(v && v.type === kind);
+        }
+
+        return { obj, getEntry, isType };
+    }
+};

package/src/syntax/parser.js

@@ -0,0 +1,321 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview PDF object parser — turns a tokenizer stream into a tree
+ * of typed PDF objects per ISO 32000-2:2020 §7.3 (Objects).
+ *
+ * Object types produced:
+ *
+ * | type      | shape                                                  |
+ * |-----------|--------------------------------------------------------|
+ * | `null`    | `{ type: 'null' }`                                     |
+ * | `bool`    | `{ type: 'bool',   value: boolean }`                   |
+ * | `int`     | `{ type: 'int',    value: number }`                    |
+ * | `real`    | `{ type: 'real',   value: number }`                    |
+ * | `name`    | `{ type: 'name',   value: string }`                    |
+ * | `string`  | `{ type: 'string', value: Uint8Array, syntax: 'lit'\|'hex' }` |
+ * | `array`   | `{ type: 'array',  items: object[] }`                  |
+ * | `dict`    | `{ type: 'dict',   entries: { [name: string]: object } }` |
+ * | `ref`     | `{ type: 'ref',    num: int, gen: int }`               |
+ * | `stream`  | `{ type: 'stream', dict, raw: Uint8Array }`            |
+ *
+ * Indirect object definitions (`<num> <gen> obj ... endobj`) are parsed
+ * by `parseIndirect()` and return `{ num, gen, value }`.
+ *
+ * Companion files:
+ * - `parser-obj.js` — `obj.*` constructors and `getEntry`, `isType`.
+ *
+ * @module pdf/syntax/parser
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ *
+ * Receives `pdfErrors` and `pdfTokenizer` via DI ; carries its own
+ * stream-length and `endstream` helpers in the body so the factory is
+ * self-sufficient.
+ *
+ * Re-exports the injected `pdfTokenizer`'s `tokenize` alongside the
+ * parser's own API: `pdfContentStream` declares `pdfParser` as its
+ * `tokenize` source, so the returned module must expose it for the
+ * public module graph to resolve a working `parseContentStream`.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from './parser-obj.js';
+import { pdfTokenizer } from './tokenizer.js';
+
+export const pdfParser = {
+    name: 'pdfParser',
+    dependencies: ['pdfErrors', 'pdfParserObj', 'pdfTokenizer'],
+    deps: [pdfErrors, pdfParserObj, pdfTokenizer],
+    factory(errors, parserObj, tokenizerMod) {
+        const { ParseError } = errors;
+        const { obj, getEntry, isType } = parserObj;
+        const tokenize = tokenizerMod.tokenize;
+        const LF = 0x0A, CR = 0x0D;
+
+        // --- stream-length and `endstream` helpers ---
+        function resolveStreamLength(streamDict, resolveRef) {
+            const e = streamDict.entries && streamDict.entries.Length;
+            if (!e) return -1;
+            if (e.type === 'int') return e.value;
+            if (e.type === 'ref' && typeof resolveRef === 'function') {
+                const r = resolveRef(e);
+                if (r && r.type === 'int') return r.value;
+            }
+            return -1;
+        }
+        function findEndstream(bytes, from, quota) {
+            const needle = [0x65,0x6E,0x64,0x73,0x74,0x72,0x65,0x61,0x6D]; // endstream
+            const lim = Math.min(bytes.length, from + (quota | 0));
+            outer: for (let i = from; i + needle.length <= lim; i++) {
+                for (let k = 0; k < needle.length; k++) {
+                    if (bytes[i + k] !== needle[k]) continue outer;
+                }
+                // Walk back over trailing EOL whitespace before `endstream`.
+                let end = i;
+                if (end > from && bytes[end - 1] === LF) end--;
+                if (end > from && bytes[end - 1] === CR) end--;
+                return end;
+            }
+            return -1;
+        }
+        function skipEolWs(tok) {
+            const b = tok.bytes;
+            let p = tok.pos();
+            while (p < b.length) {
+                const c = b[p];
+                if (c === 0x20 || c === 0x09 || c === LF || c === CR) p++;
+                else break;
+            }
+            tok.seek(p);
+        }
+
+        // --- parserLimits (mutable per-instance state) ---
+        const parserLimits = {
+            maxDepth: 200,
+            maxArrayLen: 1_000_000,
+            maxStreamBytes: 256 * 1024 * 1024
+        };
+        function setParserLimits(partial) {
+            if (partial && typeof partial === 'object') {
+                if (Number.isInteger(partial.maxDepth) && partial.maxDepth > 0)
+                    parserLimits.maxDepth = partial.maxDepth;
+                if (Number.isInteger(partial.maxArrayLen) && partial.maxArrayLen > 0)
+                    parserLimits.maxArrayLen = partial.maxArrayLen;
+                if (Number.isInteger(partial.maxStreamBytes)
+                    && partial.maxStreamBytes > 0)
+                    parserLimits.maxStreamBytes = partial.maxStreamBytes;
+            }
+            return parserLimits;
+        }
+
+        function parseObject(tok) {
+            const t = tok.next();
+            if (!t) {
+                throw new ParseError('pdf/parser/eof', 'unexpected end of input');
+            }
+            return continueParse(tok, t, 0);
+        }
+
+        function continueParse(tok, t, depth) {
+            if (depth > parserLimits.maxDepth) {
+                throw new ParseError('pdf/parser/depth-exceeded',
+                    'parser depth limit exceeded',
+                    { context: { depth, limit: parserLimits.maxDepth,
+                                 offset: t && t.offset } });
+            }
+            switch (t.kind) {
+                case 'kw':
+                    if (t.value === 'null')  return { type: 'null' };
+                    if (t.value === 'true')  return { type: 'bool', value: true };
+                    if (t.value === 'false') return { type: 'bool', value: false };
+                    throw new ParseError('pdf/parser/unexpected-keyword',
+                        `unexpected keyword "${t.value}"`,
+                        { context: { offset: t.offset, keyword: t.value } });
+                case 'name':
+                    return { type: 'name', value: t.value };
+                case 'string':
+                    return { type: 'string', value: t.value, syntax: 'lit' };
+                case 'hex':
+                    return { type: 'string', value: t.value, syntax: 'hex' };
+                case 'int':
+                    return tryReadRef(tok, t);
+                case 'real':
+                    return { type: 'real', value: t.value };
+                case 'open_arr':
+                    return readArray(tok, t.offset, depth);
+                case 'open_dict':
+                    return readDict(tok, t.offset, depth);
+                case 'close_arr':
+                case 'close_dict':
+                    throw new ParseError('pdf/parser/unbalanced',
+                        `unexpected ${t.kind}`,
+                        { context: { offset: t.offset } });
+                default:
+                    throw new ParseError('pdf/parser/unexpected-token',
+                        `unexpected token of kind "${t.kind}"`,
+                        { context: { offset: t.offset, kind: t.kind } });
+            }
+        }
+
+        function tryReadRef(tok, intTok) {
+            const at = tok.pos();
+            const p1 = tok.peek();
+            if (!p1 || p1.kind !== 'int') {
+                return { type: 'int', value: intTok.value };
+            }
+            tok.next();
+            const p2 = tok.peek();
+            if (p2 && p2.kind === 'kw' && p2.value === 'R') {
+                tok.next();
+                return { type: 'ref', num: intTok.value | 0, gen: p1.value | 0 };
+            }
+            tok.seek(at);
+            return { type: 'int', value: intTok.value };
+        }
+
+        function readArray(tok, startOff, depth) {
+            const items = [];
+            for (;;) {
+                const p = tok.peek();
+                if (!p) {
+                    throw new ParseError('pdf/parser/unterminated-array',
+                        'array not closed',
+                        { context: { offset: startOff } });
+                }
+                if (p.kind === 'close_arr') { tok.next(); return { type: 'array', items }; }
+                if (items.length >= parserLimits.maxArrayLen) {
+                    throw new ParseError('pdf/parser/array-too-long',
+                        'array exceeds parserLimits.maxArrayLen',
+                        { context: { length: items.length,
+                                     limit: parserLimits.maxArrayLen,
+                                     offset: startOff } });
+                }
+                const sub = tok.next();
+                items.push(continueParse(tok, sub, (depth | 0) + 1));
+            }
+        }
+
+        function readDict(tok, startOff, depth) {
+            const entries = {};
+            for (;;) {
+                const p = tok.peek();
+                if (!p) {
+                    throw new ParseError('pdf/parser/unterminated-dict',
+                        'dict not closed',
+                        { context: { offset: startOff } });
+                }
+                if (p.kind === 'close_dict') { tok.next(); return { type: 'dict', entries }; }
+                if (p.kind !== 'name') {
+                    throw new ParseError('pdf/parser/dict-key-not-name',
+                        'expected /Name as dict key',
+                        { context: { offset: p.offset, kind: p.kind } });
+                }
+                const keyTok = tok.next();
+                const sub = tok.next();
+                if (!sub) {
+                    throw new ParseError('pdf/parser/eof', 'unexpected end of input');
+                }
+                const value = continueParse(tok, sub, (depth | 0) + 1);
+                entries[keyTok.value] = value;
+            }
+        }
+
+        function parseIndirect(tok, resolveRef) {
+            const t1 = tok.next();
+            if (!t1 || t1.kind !== 'int') {
+                throw new ParseError('pdf/parser/indirect-bad-num',
+                    'expected object number',
+                    { context: { offset: t1 ? t1.offset : tok.pos() } });
+            }
+            const t2 = tok.next();
+            if (!t2 || t2.kind !== 'int') {
+                throw new ParseError('pdf/parser/indirect-bad-gen',
+                    'expected generation number',
+                    { context: { offset: t2 ? t2.offset : tok.pos() } });
+            }
+            const t3 = tok.next();
+            if (!t3 || t3.kind !== 'kw' || t3.value !== 'obj') {
+                throw new ParseError('pdf/parser/indirect-missing-obj',
+                    'expected obj keyword',
+                    { context: { offset: t3 ? t3.offset : tok.pos() } });
+            }
+
+            const value = parseObject(tok);
+            let body = value;
+
+            const after = tok.peek();
+            if (value.type === 'dict' && after && after.kind === 'kw' && after.value === 'stream') {
+                tok.next();
+                const bytes = tok.bytes;
+                let p = tok.pos();
+                if (p < bytes.length && bytes[p] === CR) p++;
+                if (p < bytes.length && bytes[p] === LF) p++;
+                tok.seek(p);
+
+                const dataStart = tok.pos();
+                const length = resolveStreamLength(value, resolveRef);
+                let dataEnd;
+                if (Number.isFinite(length) && length >= 0
+                    && dataStart + length <= bytes.length) {
+                    dataEnd = dataStart + length;
+                } else {
+                    dataEnd = findEndstream(bytes, dataStart,
+                        parserLimits.maxStreamBytes);
+                    if (dataEnd < 0) {
+                        throw new ParseError('pdf/parser/stream/no-endstream',
+                            'cannot locate endstream within quota',
+                            { context: { offset: dataStart,
+                                         num: t1.value, gen: t2.value,
+                                         quota: parserLimits.maxStreamBytes } });
+                    }
+                }
+                const raw = bytes.subarray(dataStart, dataEnd);
+                tok.seek(dataEnd);
+                skipEolWs(tok);
+                const endTok = tok.next();
+                if (!endTok || endTok.kind !== 'kw' || endTok.value !== 'endstream') {
+                    throw new ParseError('pdf/parser/stream/expected-endstream',
+                        'expected endstream',
+                        { context: { offset: endTok ? endTok.offset : tok.pos() } });
+                }
+                body = { type: 'stream', dict: value, raw };
+            }
+
+            const endObj = tok.next();
+            if (!endObj || endObj.kind !== 'kw' || endObj.value !== 'endobj') {
+                throw new ParseError('pdf/parser/indirect-missing-endobj',
+                    'expected endobj',
+                    { context: { offset: endObj ? endObj.offset : tok.pos(),
+                                 num: t1.value, gen: t2.value } });
+            }
+            return { num: t1.value, gen: t2.value, value: body };
+        }
+
+        function parseFromBytes(bytes) {
+            const tok = tokenize(bytes);
+            return parseObject(tok);
+        }
+        function parseIndirectFromBytes(bytes, at, resolveRef) {
+            const tok = tokenize(bytes, { start: at | 0 });
+            return parseIndirect(tok, resolveRef);
+        }
+
+        return {
+            tokenize,
+            parseObject,
+            parseIndirect,
+            parseFromBytes,
+            parseIndirectFromBytes,
+            parserLimits,
+            setParserLimits,
+            obj,
+            getEntry,
+            isType
+        };
+    }
+};

package/src/syntax/serializer.js

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview Serialize typed PDF objects back to bytes per
+ * ISO 32000-2:2020 §7.3 / §7.5.
+ *
+ * Public API (via factory):
+ *
+ * - `serializeObject(obj)` → `Uint8Array`
+ * - `serializeIndirect(num, gen, obj)` → `Uint8Array`
+ * - `formatReal(n)` → `string`
+ *
+ * @module pdf/syntax/serializer
+ */
+
+/**
+ * Module factory — worker-safe, self-contained.
+ */
+import { pdfErrors } from '../errors.js';
+
+export const pdfSerializer = {
+    name: 'pdfSerializer',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+    factory(errors) {
+        const { RenderError } = errors;
+        const te = new TextEncoder();
+
+        function serializeObject(obj) {
+            if (!obj || typeof obj.type !== 'string') {
+                throw new RenderError('pdf/serializer/bad-input',
+                    'serializeObject expects a typed object',
+                    { context: { typeof: typeof obj } });
+            }
+            return concat(emitObject(obj));
+        }
+
+        function serializeIndirect(num, gen, body) {
+            if (!Number.isFinite(num) || num < 0) {
+                throw new RenderError('pdf/serializer/bad-num',
+                    'object number must be a non-negative integer',
+                    { context: { num } });
+            }
+            if (!Number.isFinite(gen) || gen < 0) {
+                throw new RenderError('pdf/serializer/bad-gen',
+                    'generation number must be a non-negative integer',
+                    { context: { gen } });
+            }
+            const head = te.encode(`${num | 0} ${gen | 0} obj\n`);
+            const tail = te.encode('\nendobj\n');
+
+            if (body && body.type === 'stream') {
+                const raw = body.raw instanceof Uint8Array ? body.raw : new Uint8Array(0);
+                const dict = body.dict || { type: 'dict', entries: {} };
+                const updated = {
+                    type: 'dict',
+                    entries: {
+                        ...dict.entries,
+                        Length: { type: 'int', value: raw.length }
+                    }
+                };
+                const dictBytes  = concat(emitObject(updated));
+                const streamHead = te.encode('\nstream\n');
+                const streamTail = te.encode('\nendstream');
+                return concatU8([head, dictBytes, streamHead, raw, streamTail, tail]);
+            }
+            return concatU8([head, concat(emitObject(body)), tail]);
+        }
+
+        function formatReal(n) {
+            if (!Number.isFinite(n)) {
+                throw new RenderError('pdf/serializer/bad-real',
+                    'real number must be finite', { context: { value: n } });
+            }
+            if (Number.isInteger(n)) {
+                return `${n}`;
+            }
+            let s = n.toFixed(5);
+            if (s.indexOf('.') >= 0) {
+                s = s.replace(/0+$/, '');
+                if (s.endsWith('.')) s = s.slice(0, -1);
+            }
+            if (s === '-0') s = '0';
+            return s;
+        }
+
+        function emitObject(o) {
+            switch (o.type) {
+                case 'null':  return ['null'];
+                case 'bool':  return [o.value ? 'true' : 'false'];
+                case 'int':   return [`${o.value | 0}`];
+                case 'real':  return [formatReal(o.value)];
+                case 'name':  return [emitName(o.value)];
+                case 'string':return [emitString(o)];
+                case 'array': return emitArray(o);
+                case 'dict':  return emitDict(o);
+                case 'ref':   return [`${o.num | 0} ${o.gen | 0} R`];
+                case 'stream':
+                    throw new RenderError('pdf/serializer/inline-stream',
+                        'stream objects must be serialized via serializeIndirect');
+                default:
+                    throw new RenderError('pdf/serializer/unknown-type',
+                        `unknown object type "${o.type}"`,
+                        { context: { type: o.type } });
+            }
+        }
+
+        function emitName(value) {
+            let out = '/';
+            for (let i = 0; i < value.length; i++) {
+                const cp = value.codePointAt(i);
+                if (cp > 0xFFFF) i++;
+                if (cp < 0x21 || cp > 0x7E
+                        || cp === 0x23 || cp === 0x2F
+                        || cp === 0x28 || cp === 0x29 || cp === 0x3C || cp === 0x3E
+                        || cp === 0x5B || cp === 0x5D || cp === 0x7B || cp === 0x7D
+                        || cp === 0x25) {
+                    const enc = te.encode(String.fromCodePoint(cp));
+                    for (const b of enc) out += '#' + b.toString(16).padStart(2, '0').toUpperCase();
+                } else {
+                    out += String.fromCharCode(cp);
+                }
+            }
+            return out;
+        }
+
+        function emitString(o) {
+            const bytes = o.value;
+            if (!(bytes instanceof Uint8Array)) {
+                throw new RenderError('pdf/serializer/bad-string',
+                    'string value must be Uint8Array',
+                    { context: { typeof: typeof bytes } });
+            }
+            if (o.syntax === 'hex' || shouldUseHex(bytes)) return emitHexString(bytes);
+            return emitLiteralString(bytes);
+        }
+
+        function shouldUseHex(bytes) {
+            let bad = 0;
+            for (let i = 0; i < bytes.length; i++) {
+                const b = bytes[i];
+                if (b < 0x09 || (b > 0x0D && b < 0x20) || b >= 0x7F) bad++;
+                if (bad > bytes.length / 4) return true;
+            }
+            return false;
+        }
+
+        function emitLiteralString(bytes) {
+            const out = ['('];
+            for (let i = 0; i < bytes.length; i++) {
+                const b = bytes[i];
+                if (b === 0x5C) out.push('\\\\');
+                else if (b === 0x28) out.push('\\(');
+                else if (b === 0x29) out.push('\\)');
+                else if (b === 0x0A) out.push('\\n');
+                else if (b === 0x0D) out.push('\\r');
+                else if (b === 0x09) out.push('\\t');
+                else if (b === 0x08) out.push('\\b');
+                else if (b === 0x0C) out.push('\\f');
+                else if (b < 0x20 || b > 0x7E) {
+                    out.push('\\' + b.toString(8).padStart(3, '0'));
+                } else out.push(String.fromCharCode(b));
+            }
+            out.push(')');
+            return out.join('');
+        }
+
+        function emitHexString(bytes) {
+            const H = '0123456789ABCDEF';
+            let s = '<';
+            for (let i = 0; i < bytes.length; i++) {
+                s += H[bytes[i] >> 4] + H[bytes[i] & 0xF];
+            }
+            return s + '>';
+        }
+
+        function emitArray(o) {
+            const parts = ['['];
+            let first = true;
+            for (const it of o.items) {
+                if (!first) parts.push(' ');
+                first = false;
+                for (const p of emitObject(it)) parts.push(p);
+            }
+            parts.push(']');
+            return parts;
+        }
+
+        function emitDict(o) {
+            const parts = ['<<'];
+            for (const k of Object.keys(o.entries)) {
+                parts.push(' ');
+                parts.push(emitName(k));
+                parts.push(' ');
+                for (const p of emitObject(o.entries[k])) parts.push(p);
+            }
+            parts.push(' >>');
+            return parts;
+        }
+
+        function concat(parts) {
+            let s = '';
+            for (const p of parts) s += p;
+            return te.encode(s);
+        }
+
+        function concatU8(arrays) {
+            let n = 0;
+            for (const a of arrays) n += a.length;
+            const out = new Uint8Array(n);
+            let o = 0;
+            for (const a of arrays) { out.set(a, o); o += a.length; }
+            return out;
+        }
+
+        return { serializeObject, serializeIndirect, formatReal };
+    }
+};