@triplef/pdf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugen Hildt
+
+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,25 @@
+# @triplef/pdf
+
+Single-owner pdfjs integration for the tripleF (3F) apps — the one and only place that depends on `pdfjs-dist`.
+
+- `PdfService.extractText(buffer)` → per-page text layer (`string[]`, aligned 1:1 with pages; `''` for pages without a text layer, e.g. scanned pages).
+- `PdfService.renderPages(buffer, scale?)` → per-page PNG buffers (`{ buffer, mimeType: 'image/png', pageNumber }`), white background, rendered via pdfjs' built-in `NodeCanvasFactory` on top of `@napi-rs/canvas` (a runtime dependency of this package).
+
+## Usage
+
+```ts
+import { PdfModule } from '@triplef/pdf';
+
+@Module({
+  imports: [PdfModule.registerAsync({ global: true })],
+})
+export class AppModule {}
+```
+
+Then inject `PdfService` wherever it is needed.
+
+## Notes
+
+- Uses the pdfjs **legacy Node build** (`pdfjs-dist/legacy/build/pdf.mjs`) with standard fonts and CMaps resolved from the installed `pdfjs-dist` package, so CJK documents extract and render correctly.
+- No `isEvalSupported` option: pdfjs ≥5.7 removed it together with the PostScript `eval` path (CVE-2024-4367 surface).
+- Post-processing (e.g. JPEG re-encode for token efficiency) is intentionally left to the consuming app.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PdfModule, PdfOptions, PdfPage, PdfService } from './pdf/index.js';
+import '@nestjs/common';

package/dist/index.mjs

@@ -0,0 +1,112 @@
+import { Injectable, Module } from '@nestjs/common';
+import { createRequire } from 'module';
+import path from 'path';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var DEFAULT_RENDER_SCALE = 2;
+var PdfService = class {
+  /**
+   * Extract the text layer, one entry per page and aligned with the page
+   * order of renderPages(). A page without a text layer (scanned/image-only)
+   * yields ''. Throws when the buffer is not a parseable pdf.
+   */
+  async extractText(buffer) {
+    const loadingTask = await this.loadDocument(buffer);
+    try {
+      const document = await loadingTask.promise;
+      const pages = [];
+      for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+        const page = await document.getPage(pageNumber);
+        const { items } = await page.getTextContent();
+        pages.push(toPageText(items));
+        page.cleanup();
+      }
+      return pages;
+    } finally {
+      await loadingTask.destroy();
+    }
+  }
+  /**
+   * Render every page to a PNG at the given scale with a white background
+   * (transparent pages would re-encode poorly to JPEG downstream). Entries
+   * carry 1-based page numbers aligned with extractText().
+   */
+  async renderPages(buffer, scale = DEFAULT_RENDER_SCALE) {
+    const loadingTask = await this.loadDocument(buffer);
+    try {
+      const document = await loadingTask.promise;
+      const pages = [];
+      for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+        pages.push(await renderPage(document, pageNumber, scale));
+      }
+      return pages;
+    } finally {
+      await loadingTask.destroy();
+    }
+  }
+  /**
+   * Open the document with the legacy Node build; pdfjs standard fonts and
+   * CMaps resolve from the installed package — createRequire with the file's
+   * own url keeps the resolution working from the compiled dist too.
+   */
+  async loadDocument(buffer) {
+    const { getDocument } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const pdfjsPath = path.dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+    const params = {
+      data: new Uint8Array(buffer),
+      standardFontDataUrl: path.join(pdfjsPath, `standard_fonts${path.sep}`),
+      cMapUrl: path.join(pdfjsPath, `cmaps${path.sep}`),
+      cMapPacked: true
+    };
+    return getDocument(params);
+  }
+};
+PdfService = __decorateClass([
+  Injectable()
+], PdfService);
+function toPageText(items) {
+  return items.map((item) => !item.str ? "" : item.hasEOL ? `${item.str}
+` : `${item.str} `).join("").trim();
+}
+async function renderPage(document, pageNumber, scale) {
+  const page = await document.getPage(pageNumber);
+  const viewport = page.getViewport({ scale });
+  const { canvas, context } = document.canvasFactory.create(
+    Math.ceil(viewport.width),
+    Math.ceil(viewport.height)
+  );
+  await page.render({
+    // napi-rs canvas/context are structurally the DOM types the renderer
+    // drives at runtime; the pdfjs params expect the DOM interfaces.
+    canvasContext: context,
+    canvas,
+    viewport,
+    background: "rgb(255,255,255)"
+  }).promise;
+  page.cleanup();
+  return { buffer: canvas.toBuffer("image/png"), mimeType: "image/png", pageNumber };
+}
+
+// src/pdf/pdf.module.ts
+var PdfModule = class {
+  static registerAsync(options) {
+    return {
+      global: options?.global,
+      module: PdfModule,
+      exports: [PdfService],
+      providers: [PdfService]
+    };
+  }
+};
+PdfModule = __decorateClass([
+  Module({})
+], PdfModule);
+
+export { PdfModule, PdfService };

package/dist/pdf/index.d.ts

@@ -0,0 +1,22 @@
+import { DynamicModule } from '@nestjs/common';
+
+interface PdfOptions {
+    global?: boolean;
+}
+interface PdfPage {
+    buffer: Buffer;
+    mimeType: 'image/png';
+    pageNumber: number;
+}
+
+declare class PdfModule {
+    static registerAsync(options?: PdfOptions): DynamicModule;
+}
+
+declare class PdfService {
+    extractText(buffer: Buffer): Promise<string[]>;
+    renderPages(buffer: Buffer, scale?: number): Promise<PdfPage[]>;
+    private loadDocument;
+}
+
+export { PdfModule, type PdfOptions, type PdfPage, PdfService };

package/dist/pdf/index.mjs

@@ -0,0 +1,112 @@
+import { Injectable, Module } from '@nestjs/common';
+import { createRequire } from 'module';
+import path from 'path';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var DEFAULT_RENDER_SCALE = 2;
+var PdfService = class {
+  /**
+   * Extract the text layer, one entry per page and aligned with the page
+   * order of renderPages(). A page without a text layer (scanned/image-only)
+   * yields ''. Throws when the buffer is not a parseable pdf.
+   */
+  async extractText(buffer) {
+    const loadingTask = await this.loadDocument(buffer);
+    try {
+      const document = await loadingTask.promise;
+      const pages = [];
+      for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+        const page = await document.getPage(pageNumber);
+        const { items } = await page.getTextContent();
+        pages.push(toPageText(items));
+        page.cleanup();
+      }
+      return pages;
+    } finally {
+      await loadingTask.destroy();
+    }
+  }
+  /**
+   * Render every page to a PNG at the given scale with a white background
+   * (transparent pages would re-encode poorly to JPEG downstream). Entries
+   * carry 1-based page numbers aligned with extractText().
+   */
+  async renderPages(buffer, scale = DEFAULT_RENDER_SCALE) {
+    const loadingTask = await this.loadDocument(buffer);
+    try {
+      const document = await loadingTask.promise;
+      const pages = [];
+      for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+        pages.push(await renderPage(document, pageNumber, scale));
+      }
+      return pages;
+    } finally {
+      await loadingTask.destroy();
+    }
+  }
+  /**
+   * Open the document with the legacy Node build; pdfjs standard fonts and
+   * CMaps resolve from the installed package — createRequire with the file's
+   * own url keeps the resolution working from the compiled dist too.
+   */
+  async loadDocument(buffer) {
+    const { getDocument } = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    const pdfjsPath = path.dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+    const params = {
+      data: new Uint8Array(buffer),
+      standardFontDataUrl: path.join(pdfjsPath, `standard_fonts${path.sep}`),
+      cMapUrl: path.join(pdfjsPath, `cmaps${path.sep}`),
+      cMapPacked: true
+    };
+    return getDocument(params);
+  }
+};
+PdfService = __decorateClass([
+  Injectable()
+], PdfService);
+function toPageText(items) {
+  return items.map((item) => !item.str ? "" : item.hasEOL ? `${item.str}
+` : `${item.str} `).join("").trim();
+}
+async function renderPage(document, pageNumber, scale) {
+  const page = await document.getPage(pageNumber);
+  const viewport = page.getViewport({ scale });
+  const { canvas, context } = document.canvasFactory.create(
+    Math.ceil(viewport.width),
+    Math.ceil(viewport.height)
+  );
+  await page.render({
+    // napi-rs canvas/context are structurally the DOM types the renderer
+    // drives at runtime; the pdfjs params expect the DOM interfaces.
+    canvasContext: context,
+    canvas,
+    viewport,
+    background: "rgb(255,255,255)"
+  }).promise;
+  page.cleanup();
+  return { buffer: canvas.toBuffer("image/png"), mimeType: "image/png", pageNumber };
+}
+
+// src/pdf/pdf.module.ts
+var PdfModule = class {
+  static registerAsync(options) {
+    return {
+      global: options?.global,
+      module: PdfModule,
+      exports: [PdfService],
+      providers: [PdfService]
+    };
+  }
+};
+PdfModule = __decorateClass([
+  Module({})
+], PdfModule);
+
+export { PdfModule, PdfService };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@triplef/pdf",
+  "description": "tripleF (3F) PDF domain — single-owner pdfjs integration: per-page text-layer extraction and page rendering for the apps.",
+  "version": "0.1.0",
+  "packageManager": "pnpm@11.25.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./pdf": {
+      "types": "./dist/pdf/index.d.ts",
+      "import": "./dist/pdf/index.mjs"
+    }
+  },
+  "main": "dist/index.mjs",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ehildt/tripleF.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "email": "eugen.hildt@gmail.com",
+    "name": "Eugen Hildt"
+  },
+  "bugs": {
+    "email": "eugen.hildt@gmail.com"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "build": "pnpm tsup",
+    "depcheck": "npx depcheck .",
+    "depcruise": "npx dependency-cruiser -c .depcruise.mjs --ts-config tsconfig.json src",
+    "format": "prettier --write .",
+    "lint": "eslint ./src",
+    "lint-staged": "npx lint-staged --allow-empty",
+    "ncu:update": "npx npm-check-updates -u --format group --dep prod,dev,optional,packageManager,peer",
+    "ncu:interactive": "npx npm-check-updates -u --interactive --format group",
+    "ncu:validate": "npx npm-check-updates -e 2 --packageFile=./package.json",
+    "prebuild": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "lint:unused": "npx ts-unused-exports ./tsconfig.exclude.json --maxIssues=6"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.100",
+    "pdfjs-dist": "~5.7.284"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^3.0.2",
+    "@eslint/js": "^10.0.1",
+    "@types/eslint": "^9.6.1",
+    "@types/node": "^26.4.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "depcheck": "^1.4.7",
+    "dependency-cruiser": "^18.2.0",
+    "eslint": "^10.10.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "globals": "^17.12.0",
+    "husky": "^9.1.7",
+    "jiti": "^2.7.0",
+    "lint-staged": "^17.4.1",
+    "npm-check-updates": "^23.1.0",
+    "prettier": "^3.9.6",
+    "rimraf": "^6.1.3",
+    "ts-unused-exports": "^11.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^4.1.11"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.2.3"
+  }
+}