pdf-oxide 0.3.37 → 0.3.39

package/lib/native.js

@@ -0,0 +1,69 @@
+/**
+ * Shared loader for the pdf-oxide N-API addon.
+ *
+ * Extracted so that modules which can't import from `./index.ts`
+ * (due to the index ↔ editor / builder cycle) can still reach the
+ * addon through the same prebuild-aware resolver. The published
+ * package ships a platform-specific `.node` file under
+ * `prebuilds/<triple>/`; loading the addon through this helper is
+ * what makes `DocumentEditor` / `DocumentBuilder` work for consumers
+ * installed from npm (where `build/Release/` does not exist).
+ *
+ * In development mode (`NODE_ENV=development` or `NAPI_DEV` set), we
+ * fall back to `../build/Release/pdf_oxide.node` — the node-gyp
+ * output that in-tree tests run against.
+ */
+import { createRequire } from 'node:module';
+import { arch, platform } from 'node:os';
+const require = createRequire(import.meta.url);
+// Prebuild paths are relative to the *compiled* `lib/native.js` — at
+// runtime the file lives at `js/lib/native.js`, so `../prebuilds/`
+// resolves to `js/prebuilds/`.
+const PLATFORMS = {
+    darwin: {
+        x64: '../prebuilds/darwin-x64/pdf_oxide.node',
+        arm64: '../prebuilds/darwin-arm64/pdf_oxide.node',
+    },
+    linux: {
+        x64: '../prebuilds/linux-x64/pdf_oxide.node',
+        arm64: '../prebuilds/linux-arm64/pdf_oxide.node',
+    },
+    win32: {
+        x64: '../prebuilds/win32-x64/pdf_oxide.node',
+    },
+};
+function getPrebuildPath() {
+    const os = platform();
+    const cpu = arch();
+    const osPaths = PLATFORMS[os];
+    if (!osPaths) {
+        throw new Error(`Unsupported platform: ${os}. Supported: ${Object.keys(PLATFORMS).join(', ')}`);
+    }
+    const prebuildPath = osPaths[cpu];
+    if (!prebuildPath) {
+        throw new Error(`Unsupported architecture: ${cpu} for ${os}. Supported: ${Object.keys(osPaths).join(', ')}`);
+    }
+    return prebuildPath;
+}
+let cached;
+export function loadNative() {
+    if (cached)
+        return cached;
+    try {
+        cached = require(getPrebuildPath());
+        return cached;
+    }
+    catch (e) {
+        // Dev fallback — in-tree `node-gyp rebuild` output.
+        if (process.env.NODE_ENV === 'development' || process.env.NAPI_DEV) {
+            try {
+                cached = require('../build/Release/pdf_oxide.node');
+                return cached;
+            }
+            catch {
+                /* fall through to rethrow the original error */
+            }
+        }
+        throw new Error(`Failed to load pdf-oxide native addon: ${e.message}`);
+    }
+}

package/lib/pdf-creator-manager.js

@@ -200,7 +200,10 @@ export class PdfCreatorManager extends EventEmitter {
         this.ensureCurrentPage();
         const lineContent = {
             type: 'line',
-            x1, y1, x2, y2,
+            x1,
+            y1,
+            x2,
+            y2,
             color,
             width,
         };

package/lib/result-accessors-manager.js

@@ -698,7 +698,9 @@ export class ResultAccessorsManager extends EventEmitter {
     clearCachePattern(pattern) {
         const regex = new RegExp(pattern);
         const keysToDelete = Array.from(this.resultCache.keys()).filter((key) => regex.test(key));
-        keysToDelete.forEach((key) => this.resultCache.delete(key));
+        keysToDelete.forEach((key) => {
+            this.resultCache.delete(key);
+        });
     }
 }
 export default ResultAccessorsManager;

package/lib/timestamp.d.ts

@@ -0,0 +1,54 @@
+/** Hash-algorithm enum matching the FFI contract (0 = unknown). */
+export declare enum TimestampHashAlgorithm {
+    Unknown = 0,
+    Sha1 = 1,
+    Sha256 = 2,
+    Sha384 = 3,
+    Sha512 = 4
+}
+/**
+ * Parsed RFC 3161 timestamp token. The underlying native handle is
+ * released by `close()` or on garbage collection (N-API finalizer in
+ * the C++ binding).
+ */
+export declare class Timestamp {
+    private handle;
+    private closed;
+    /** Internal — only the static constructors and sibling classes create Timestamps. */
+    private constructor();
+    /**
+     * Parse a DER blob that may be either a full TimeStampToken (CMS-wrapped)
+     * or the bare TSTInfo SEQUENCE. Throws on parse failure.
+     */
+    static parse(data: Uint8Array | Buffer): Timestamp;
+    /**
+     * Wrap an existing native timestamp handle (produced by
+     * `signatureGetTimestamp` or `tsaRequestTimestamp`). Internal use only.
+     */
+    static fromNativeHandle(handle: unknown): Timestamp;
+    /** Generation time as Unix epoch seconds. */
+    get time(): number;
+    /** Serial number as a hex string (no `0x` prefix). */
+    get serial(): string;
+    /** TSA policy OID in dotted-decimal form. */
+    get policyOid(): string;
+    /** TSA name from the token (may be empty). */
+    get tsaName(): string;
+    /** Hash algorithm used for the message imprint. */
+    get hashAlgorithm(): TimestampHashAlgorithm;
+    /** Raw message-imprint hash bytes. */
+    get messageImprint(): Uint8Array;
+    /** Raw DER token bytes. */
+    get token(): Uint8Array;
+    /**
+     * Cryptographic verify. Today this surfaces whatever the Rust core
+     * returns — real TSA-signer verification lands when the CMS signer
+     * path is wired through `pdf_timestamp_verify`.
+     */
+    verify(): boolean;
+    /** Release the native handle. Idempotent. */
+    close(): void;
+    /** Internal native handle accessor for sibling classes (Signature.addTimestamp). */
+    getInternalHandle(): unknown;
+    private assertOpen;
+}

package/lib/timestamp.js

@@ -0,0 +1,115 @@
+// RFC 3161 TimeStampToken / TSTInfo wrapper for the Node binding.
+//
+// Mirrors the Python PyTimestamp, WASM WasmTimestamp, Go Timestamp, and
+// C# Timestamp surfaces so every binding exposes the same shape.
+// Sourced from:
+//   - Timestamp.parse(buffer) — a standalone DER blob
+//   - A Signature object's embedded timestamp (via the signature manager)
+//   - A TsaClient.requestTimestamp(...) response (see tsa-client.ts)
+import { getNative } from './native-loader.js';
+/** Hash-algorithm enum matching the FFI contract (0 = unknown). */
+export var TimestampHashAlgorithm;
+(function (TimestampHashAlgorithm) {
+    TimestampHashAlgorithm[TimestampHashAlgorithm["Unknown"] = 0] = "Unknown";
+    TimestampHashAlgorithm[TimestampHashAlgorithm["Sha1"] = 1] = "Sha1";
+    TimestampHashAlgorithm[TimestampHashAlgorithm["Sha256"] = 2] = "Sha256";
+    TimestampHashAlgorithm[TimestampHashAlgorithm["Sha384"] = 3] = "Sha384";
+    TimestampHashAlgorithm[TimestampHashAlgorithm["Sha512"] = 4] = "Sha512";
+})(TimestampHashAlgorithm || (TimestampHashAlgorithm = {}));
+/**
+ * Parsed RFC 3161 timestamp token. The underlying native handle is
+ * released by `close()` or on garbage collection (N-API finalizer in
+ * the C++ binding).
+ */
+export class Timestamp {
+    /** Internal — only the static constructors and sibling classes create Timestamps. */
+    constructor(handle) {
+        this.closed = false;
+        this.handle = handle;
+    }
+    /**
+     * Parse a DER blob that may be either a full TimeStampToken (CMS-wrapped)
+     * or the bare TSTInfo SEQUENCE. Throws on parse failure.
+     */
+    static parse(data) {
+        if (!data || data.length === 0) {
+            throw new Error('Timestamp.parse: data must not be empty');
+        }
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const handle = getNative().timestampParse(buf);
+        if (!handle) {
+            throw new Error('Timestamp.parse: native parse returned null');
+        }
+        return new Timestamp(handle);
+    }
+    /**
+     * Wrap an existing native timestamp handle (produced by
+     * `signatureGetTimestamp` or `tsaRequestTimestamp`). Internal use only.
+     */
+    static fromNativeHandle(handle) {
+        return new Timestamp(handle);
+    }
+    /** Generation time as Unix epoch seconds. */
+    get time() {
+        this.assertOpen();
+        return Number(getNative().timestampGetTime(this.handle));
+    }
+    /** Serial number as a hex string (no `0x` prefix). */
+    get serial() {
+        this.assertOpen();
+        return getNative().timestampGetSerial(this.handle);
+    }
+    /** TSA policy OID in dotted-decimal form. */
+    get policyOid() {
+        this.assertOpen();
+        return getNative().timestampGetPolicyOid(this.handle);
+    }
+    /** TSA name from the token (may be empty). */
+    get tsaName() {
+        this.assertOpen();
+        return getNative().timestampGetTsaName(this.handle);
+    }
+    /** Hash algorithm used for the message imprint. */
+    get hashAlgorithm() {
+        this.assertOpen();
+        const v = getNative().timestampGetHashAlgorithm(this.handle);
+        return v;
+    }
+    /** Raw message-imprint hash bytes. */
+    get messageImprint() {
+        this.assertOpen();
+        return new Uint8Array(getNative().timestampGetMessageImprint(this.handle));
+    }
+    /** Raw DER token bytes. */
+    get token() {
+        this.assertOpen();
+        return new Uint8Array(getNative().timestampGetToken(this.handle));
+    }
+    /**
+     * Cryptographic verify. Today this surfaces whatever the Rust core
+     * returns — real TSA-signer verification lands when the CMS signer
+     * path is wired through `pdf_timestamp_verify`.
+     */
+    verify() {
+        this.assertOpen();
+        return getNative().timestampVerify(this.handle);
+    }
+    /** Release the native handle. Idempotent. */
+    close() {
+        if (!this.closed && this.handle) {
+            getNative().timestampFree(this.handle);
+            this.closed = true;
+            this.handle = null;
+        }
+    }
+    /** Internal native handle accessor for sibling classes (Signature.addTimestamp). */
+    getInternalHandle() {
+        this.assertOpen();
+        return this.handle;
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('Timestamp: handle is closed');
+        }
+    }
+}

package/lib/tsa-client.d.ts

@@ -0,0 +1,44 @@
+import { Timestamp, TimestampHashAlgorithm } from './timestamp.js';
+/** Constructor options for a TsaClient. */
+export interface TsaClientOptions {
+    /** TSA server URL, e.g. `https://freetsa.org/tsr`. */
+    url: string;
+    /** HTTP Basic auth username (optional). */
+    username?: string;
+    /** HTTP Basic auth password (optional). */
+    password?: string;
+    /** Request timeout in seconds. Defaults to 30. */
+    timeoutSeconds?: number;
+    /** Hash algorithm to request the TSA use. Defaults to SHA-256. */
+    hashAlgorithm?: TimestampHashAlgorithm;
+    /** Include a nonce in the request (RFC 3161 §2.4.1). Defaults to true. */
+    useNonce?: boolean;
+    /** Ask the TSA to include its certificate in the response. Defaults to true. */
+    certReq?: boolean;
+}
+/**
+ * HTTP client for an RFC 3161 Time Stamp Authority. Construct with a
+ * URL (+ optional HTTP Basic auth), then call `requestTimestamp()` to
+ * turn a blob of data into a Timestamp.
+ */
+export declare class TsaClient {
+    private handle;
+    private closed;
+    constructor(options: TsaClientOptions);
+    /**
+     * Request a timestamp over `data`. The TSA hashes the data using its
+     * configured algorithm and returns a TimeStampToken. Networking and
+     * hashing both happen inside the native call — this method blocks.
+     */
+    requestTimestamp(data: Uint8Array | Buffer): Timestamp;
+    /**
+     * Request a timestamp over an already-computed hash. Use this when the
+     * caller wants to hash the data themselves (e.g. signing the same
+     * bytes end-to-end). `hashAlgorithm` overrides the client's default
+     * for this single request.
+     */
+    requestTimestampHash(hash: Uint8Array | Buffer, hashAlgorithm?: TimestampHashAlgorithm): Timestamp;
+    /** Release the native client. Idempotent. */
+    close(): void;
+    private assertOpen;
+}

package/lib/tsa-client.js

@@ -0,0 +1,67 @@
+// RFC 3161 Time Stamp Authority HTTP client wrapper for the Node binding.
+//
+// Mirrors the Python PyTsaClient, Go TsaClient, and C# TsaClient surfaces.
+// (WASM TsaClient is intentionally unshipped — ureq, the HTTP driver in
+// the Rust core, does not run under wasm32-unknown-unknown.)
+import { getNative } from './native-loader.js';
+import { Timestamp, TimestampHashAlgorithm } from './timestamp.js';
+/**
+ * HTTP client for an RFC 3161 Time Stamp Authority. Construct with a
+ * URL (+ optional HTTP Basic auth), then call `requestTimestamp()` to
+ * turn a blob of data into a Timestamp.
+ */
+export class TsaClient {
+    constructor(options) {
+        this.closed = false;
+        if (!options || typeof options.url !== 'string' || options.url.length === 0) {
+            throw new Error('TsaClient: options.url is required');
+        }
+        const handle = getNative().tsaClientCreate(options.url, options.username ?? '', options.password ?? '', options.timeoutSeconds ?? 30, options.hashAlgorithm ?? TimestampHashAlgorithm.Sha256, options.useNonce ?? true, options.certReq ?? true);
+        if (!handle) {
+            throw new Error('TsaClient: native create returned null');
+        }
+        this.handle = handle;
+    }
+    /**
+     * Request a timestamp over `data`. The TSA hashes the data using its
+     * configured algorithm and returns a TimeStampToken. Networking and
+     * hashing both happen inside the native call — this method blocks.
+     */
+    requestTimestamp(data) {
+        this.assertOpen();
+        const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const tsHandle = getNative().tsaRequestTimestamp(this.handle, buf);
+        if (!tsHandle) {
+            throw new Error('TsaClient.requestTimestamp: native returned null');
+        }
+        return Timestamp.fromNativeHandle(tsHandle);
+    }
+    /**
+     * Request a timestamp over an already-computed hash. Use this when the
+     * caller wants to hash the data themselves (e.g. signing the same
+     * bytes end-to-end). `hashAlgorithm` overrides the client's default
+     * for this single request.
+     */
+    requestTimestampHash(hash, hashAlgorithm = TimestampHashAlgorithm.Sha256) {
+        this.assertOpen();
+        const buf = Buffer.isBuffer(hash) ? hash : Buffer.from(hash);
+        const tsHandle = getNative().tsaRequestTimestampHash(this.handle, buf, hashAlgorithm);
+        if (!tsHandle) {
+            throw new Error('TsaClient.requestTimestampHash: native returned null');
+        }
+        return Timestamp.fromNativeHandle(tsHandle);
+    }
+    /** Release the native client. Idempotent. */
+    close() {
+        if (!this.closed && this.handle) {
+            getNative().tsaClientFree(this.handle);
+            this.closed = true;
+            this.handle = null;
+        }
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('TsaClient: handle is closed');
+        }
+    }
+}

package/lib/types/common.d.ts

@@ -14,7 +14,7 @@ export interface Table {
      *  failure, etc.). */
     cells: (string | null)[][];
 }
-export type { SearchOptions, SearchResult, Metadata, DocumentInfo, EmbeddedFile, Annotation, NativePdfDocument, NativePdf, NativePdfPage, Rect, Point, Color, PdfElement, PdfText, PdfImage, PdfPath, PdfTable, PdfTableCell, TextAnnotation, HighlightAnnotation, LinkAnnotation, InkAnnotation, SquareAnnotation, CircleAnnotation, LineAnnotation, PolygonAnnotation, } from './native-bindings';
+export type { Annotation, CircleAnnotation, Color, DocumentInfo, EmbeddedFile, HighlightAnnotation, InkAnnotation, LineAnnotation, LinkAnnotation, Metadata, NativePdf, NativePdfDocument, NativePdfPage, PdfElement, PdfImage, PdfPath, PdfTable, PdfTableCell, PdfText, Point, PolygonAnnotation, Rect, SearchOptions, SearchResult, SquareAnnotation, TextAnnotation, } from './native-bindings';
 /**
  * Page range specification for document operations
  */
@@ -103,3 +103,82 @@ export type StreamErrorCallback = (error: Error) => void;
  * Stream end callback
  */
 export type StreamEndCallback = () => void;
+/**
+ * Horizontal alignment for wrapped text and table cells.
+ * Matches the C FFI integer encoding used by
+ * `pdf_page_builder_text_in_rect` and `pdf_page_builder_table`.
+ */
+export declare enum Align {
+    Left = 0,
+    Center = 1,
+    Right = 2
+}
+/**
+ * Column descriptor for {@link TableSpec} / {@link StreamingTableConfig}.
+ */
+export interface Column {
+    /** Header label rendered in bold (used only when `hasHeader`/`repeatHeader`). */
+    header: string;
+    /** Column width in PDF points. */
+    width: number;
+    /** Cell alignment (default {@link Align.Left}). */
+    align?: Align;
+}
+/**
+ * Buffered-table spec passed to `PageBuilder.table(...)`.
+ *
+ * All rows are held in JS memory and flushed to the native
+ * `pdf_page_builder_table` call in a single step.
+ */
+export interface TableSpec {
+    /** Column layout — widths, alignments, and header labels. */
+    columns: Column[];
+    /** Body rows, each row has `columns.length` cells (nullable = empty). */
+    rows: Array<Array<string | null | undefined>>;
+    /** Promote the column headers to a styled first row. Defaults to true. */
+    hasHeader?: boolean;
+}
+/**
+ * Column-sizing strategy for streaming tables (issue #400).
+ *
+ * - `fixed` — use the `width` from each `Column` as-is (default).
+ * - `sample` — buffer the first N rows, measure content, then freeze
+ *   column widths automatically.  Supply `sampleRows`, `minColWidth`,
+ *   and `maxColWidth` to tune.
+ */
+export type TableMode = {
+    kind: 'fixed';
+} | {
+    kind: 'sample';
+    sampleRows?: number;
+    minColWidthPt?: number;
+    maxColWidthPt?: number;
+};
+/**
+ * Configuration for the managed streaming-table adapter.
+ */
+export interface StreamingTableConfig {
+    /** Column layout — widths, alignments, and header labels. */
+    columns: Column[];
+    /**
+     * Whether to repeat the header row on every page break. Defaults to true.
+     */
+    repeatHeader?: boolean;
+    /**
+     * Column-sizing mode. Defaults to `{ kind: 'fixed' }`.
+     */
+    mode?: TableMode;
+    /**
+     * Maximum rowspan a cell may carry.  0 or 1 (default) disables rowspan.
+     * Set to ≥2 to allow `pushRowSpan` cells to span multiple rows.
+     */
+    maxRowspan?: number;
+}
+/**
+ * A single cell value for `StreamingTable.pushRowSpan`.
+ * `rowspan == 1` is equivalent to a normal cell.
+ */
+export interface SpanCell {
+    text: string;
+    rowspan: number;
+}

package/lib/types/common.js

@@ -1,4 +1,17 @@
 /**
  * Common type definitions and utilities
  */
-export {};
+// ============================================================================
+// DocumentBuilder — table primitives (v0.3.39, issue #393)
+// ============================================================================
+/**
+ * Horizontal alignment for wrapped text and table cells.
+ * Matches the C FFI integer encoding used by
+ * `pdf_page_builder_text_in_rect` and `pdf_page_builder_table`.
+ */
+export var Align;
+(function (Align) {
+    Align[Align["Left"] = 0] = "Left";
+    Align[Align["Center"] = 1] = "Center";
+    Align[Align["Right"] = 2] = "Right";
+})(Align || (Align = {}));

package/lib/types/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Type definitions index - re-exports all types for easy consumption
  */
-export * from './native-bindings';
 export * from './common';
+export * from './native-bindings';

package/lib/types/index.js

@@ -1,5 +1,5 @@
 /**
  * Type definitions index - re-exports all types for easy consumption
  */
-export * from './native-bindings.js';
 export * from './common.js';
+export * from './native-bindings.js';

package/lib/types/manager-types.js

@@ -88,8 +88,10 @@ export class BaseManager extends EventEmitter {
     }
     invalidateCache(pattern) {
         if (pattern) {
-            const keys = Array.from(this.cache.keys()).filter(k => k.includes(pattern));
-            keys.forEach(k => this.cache.delete(k));
+            const keys = Array.from(this.cache.keys()).filter((k) => k.includes(pattern));
+            keys.forEach((k) => {
+                this.cache.delete(k);
+            });
         }
         else {
             this.cache.clear();

package/lib/workers/index.d.ts

@@ -2,5 +2,5 @@
  * Worker Threads Module
  * Exports worker pool and types for parallel PDF processing
  */
+export type { WorkerResult, WorkerTask } from './pool.js';
 export { WorkerPool, workerPool } from './pool.js';
-export type { WorkerTask, WorkerResult } from './pool.js';

package/lib/workers/pool.js

@@ -2,10 +2,10 @@
  * Worker Thread Pool Manager
  * Enables non-blocking parallel PDF processing
  */
-import { Worker } from 'worker_threads';
 import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { Worker } from 'worker_threads';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /**
  * Thread pool for parallel PDF processing
@@ -151,9 +151,7 @@ export class WorkerPool {
             }
         }
         // Terminate all workers
-        await Promise.all(this.workers.map((worker) => worker
-            .terminate()
-            .catch((error) => console.warn('Error terminating worker:', error))));
+        await Promise.all(this.workers.map((worker) => worker.terminate().catch((error) => console.warn('Error terminating worker:', error))));
         this.cleanup();
     }
     cleanup() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-oxide",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "type": "module",
   "description": "High-performance PDF parsing and text extraction library — prebuilt native bindings, no build toolchain required",
   "main": "lib/index.js",
@@ -14,7 +14,13 @@
     "clean:ts": "rimraf lib/",
     "clean": "npm run clean:ts && node-gyp clean",
     "prepack": "npm run build:ts",
-    "test": "node --test tests/smoke.test.mjs"
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check:publint": "publint",
+    "check:types": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
+    "audit:prod": "npm audit --omit=dev --audit-level=high",
+    "test": "node --test tests/smoke.test.mjs tests/feature-guard.test.mjs tests/api-coverage.test.mjs tests/html-css.test.mjs tests/document-builder.test.mjs tests/document-editor.test.mjs tests/render-options.test.mjs tests/tables.test.mjs"
   },
   "files": [
     "lib/",
@@ -36,7 +42,7 @@
   "homepage": "https://github.com/yfedoseev/pdf_oxide",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yfedoseev/pdf_oxide.git",
+    "url": "git+https://github.com/yfedoseev/pdf_oxide.git",
     "directory": "js"
   },
   "engines": {
@@ -44,20 +50,20 @@
   },
   "exports": {
     ".": {
-      "import": "./lib/index.js",
-      "types": "./lib/index.d.ts"
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
     },
     "./builders": {
-      "import": "./lib/builders/index.js",
-      "types": "./lib/builders/index.d.ts"
+      "types": "./lib/builders/index.d.ts",
+      "import": "./lib/builders/index.js"
     },
     "./managers": {
-      "import": "./lib/managers/index.js",
-      "types": "./lib/managers/index.d.ts"
+      "types": "./lib/managers/index.d.ts",
+      "import": "./lib/managers/index.js"
     },
     "./errors": {
-      "import": "./lib/errors.js",
-      "types": "./lib/errors.d.ts"
+      "types": "./lib/errors.d.ts",
+      "import": "./lib/errors.js"
     }
   },
   "devDependencies": {