@docverse-pdf/server 1.0.6 → 1.1.1

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { PDFDocument } from './PDFDocument.js';
 export type { PageSize, TextBlock, SearchResult, AnnotationInfo, PageObjectInfo, FormField, Bookmark, RenderOptions, ImageInfo, TextObjectStyle, } from './PDFDocument.js';
 export { flattenXFDF, mergeXFDFIntoPDF } from './flattenXFDF.js';
-export { wordToPDF, LibreOfficePool } from './wordToPDF.js';
+export { wordToPDF, LibreOfficePool, stopSharedUnoServer } from './wordToPDF.js';
 export type { ConvertOptions, PoolOptions } from './wordToPDF.js';
+export { UnoServer, UnoServerPool } from './unoServer.js';
+export type { UnoServerOptions, UnoServerPoolOptions, UnoServerStats, } from './unoServer.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { PDFDocument } from './PDFDocument.js';
 export { flattenXFDF, mergeXFDFIntoPDF } from './flattenXFDF.js';
-export { wordToPDF, LibreOfficePool } from './wordToPDF.js';
+export { wordToPDF, LibreOfficePool, stopSharedUnoServer } from './wordToPDF.js';
+export { UnoServer, UnoServerPool } from './unoServer.js';

package/dist/unoServer.d.ts

@@ -0,0 +1,86 @@
+export interface UnoServerOptions {
+    /** TCP port the unoserver daemon listens on for its own RPC (default: 2003). */
+    port?: number;
+    /**
+     * TCP port used by the underlying LibreOffice UNO socket. Must be unique per
+     * daemon — otherwise multiple daemons collide on the default 2002.
+     * (default: undefined = unoserver picks 2002, which only works for one daemon.)
+     */
+    unoPort?: number;
+    /** Host/interface the daemon binds to (default: 127.0.0.1). */
+    host?: string;
+    /** Path to the `unoserver` executable (default: auto-detect). */
+    unoserverPath?: string;
+    /** Path to the `unoconvert` client executable (default: auto-detect). */
+    unoconvertPath?: string;
+    /** Path to the LibreOffice `soffice` binary (passed to unoserver --executable). */
+    libreOfficePath?: string;
+    /**
+     * Dedicated UNO user-profile dir for this daemon (passed to unoserver
+     * --user-installation). **Must be an absolute filesystem path, not a
+     * `file://` URI** — unoserver converts it internally via `Path(...).as_uri()`.
+     */
+    userInstallation?: string;
+    /** Max time (ms) to wait for the daemon to become ready (default: 15000). */
+    startTimeout?: number;
+    /** Max time (ms) to wait for a single conversion (default: 30000). */
+    convertTimeout?: number;
+}
+export interface UnoServerPoolOptions extends Omit<UnoServerOptions, 'port' | 'unoPort' | 'userInstallation'> {
+    /** Number of parallel unoserver daemons (default: 2). */
+    workers?: number;
+    /** First daemon RPC port; each worker gets basePort+i (default: 2003). */
+    basePort?: number;
+    /**
+     * First LibreOffice UNO-socket port; each worker gets unoBasePort+i
+     * (default: 2100). Must be in a non-overlapping range with `basePort`.
+     */
+    unoBasePort?: number;
+    /** Base dir for per-worker user-profile dirs (default: os.tmpdir()/docverse_unoserver). */
+    tempDir?: string;
+}
+export interface UnoServerStats {
+    workers: number;
+    ready: number;
+    busy: number;
+    queued: number;
+}
+/**
+ * Wraps a single `unoserver` daemon process and a matching `unoconvert` client.
+ *
+ * Requires the `unoserver` Python package on the host:
+ *   pip install unoserver
+ *
+ * A single running daemon holds a warm LibreOffice instance, so conversions
+ * typically complete in 200–500 ms — roughly 10× faster than cold `soffice
+ * --convert-to` invocations.
+ */
+export declare class UnoServer {
+    private proc;
+    private readonly opts;
+    private ready;
+    constructor(options?: UnoServerOptions);
+    get port(): number;
+    get host(): string;
+    isReady(): boolean;
+    start(): Promise<void>;
+    convert(input: Buffer | Uint8Array, format?: string): Promise<Buffer>;
+    stop(): Promise<void>;
+}
+/**
+ * A pool of warm `unoserver` daemons, each listening on its own port.
+ * Use this when you need concurrent conversions — jobs are dispatched
+ * to the first idle worker, otherwise queued FIFO.
+ */
+export declare class UnoServerPool {
+    private workers;
+    private queue;
+    private readonly opts;
+    private running;
+    constructor(options?: UnoServerPoolOptions);
+    start(): Promise<void>;
+    convert(input: Buffer | Uint8Array, format?: string): Promise<Buffer>;
+    private dispatch;
+    stop(): Promise<void>;
+    getStats(): UnoServerStats;
+}

package/dist/unoServer.js

@@ -0,0 +1,378 @@
+import { spawn, execSync } from 'child_process';
+import { createConnection } from 'net';
+import { resolve as resolvePath } from 'path';
+// ═══════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════
+function which(cmd) {
+    try {
+        const out = execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim();
+        return out || null;
+    }
+    catch {
+        return null;
+    }
+}
+function findUnoserver() {
+    const candidates = [
+        'unoserver',
+        '/usr/local/bin/unoserver',
+        '/usr/bin/unoserver',
+        '/opt/homebrew/bin/unoserver',
+    ];
+    for (const c of candidates) {
+        const resolved = c.startsWith('/') ? c : which(c);
+        if (resolved)
+            return resolved;
+    }
+    return 'unoserver';
+}
+function findUnoconvert() {
+    const candidates = [
+        'unoconvert',
+        '/usr/local/bin/unoconvert',
+        '/usr/bin/unoconvert',
+        '/opt/homebrew/bin/unoconvert',
+    ];
+    for (const c of candidates) {
+        const resolved = c.startsWith('/') ? c : which(c);
+        if (resolved)
+            return resolved;
+    }
+    return 'unoconvert';
+}
+function findSoffice() {
+    const candidates = [
+        '/usr/bin/soffice',
+        '/usr/bin/libreoffice',
+        '/usr/local/bin/soffice',
+        '/Applications/LibreOffice.app/Contents/MacOS/soffice',
+    ];
+    for (const c of candidates) {
+        try {
+            execSync(`${c} --version`, { stdio: 'ignore' });
+            return c;
+        }
+        catch { }
+    }
+    return undefined;
+}
+async function probePort(host, port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const sock = createConnection({ host, port });
+        const timer = setTimeout(() => {
+            sock.destroy();
+            resolve(false);
+        }, timeoutMs);
+        sock.once('connect', () => {
+            clearTimeout(timer);
+            sock.end();
+            resolve(true);
+        });
+        sock.once('error', () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+async function waitForPort(host, port, deadline) {
+    while (Date.now() < deadline) {
+        if (await probePort(host, port))
+            return;
+        await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new Error(`unoserver did not become ready on ${host}:${port} within the timeout`);
+}
+// ═══════════════════════════════════════════════
+// SINGLE UNOSERVER DAEMON
+// ═══════════════════════════════════════════════
+/**
+ * Wraps a single `unoserver` daemon process and a matching `unoconvert` client.
+ *
+ * Requires the `unoserver` Python package on the host:
+ *   pip install unoserver
+ *
+ * A single running daemon holds a warm LibreOffice instance, so conversions
+ * typically complete in 200–500 ms — roughly 10× faster than cold `soffice
+ * --convert-to` invocations.
+ */
+export class UnoServer {
+    proc = null;
+    opts;
+    ready = false;
+    constructor(options = {}) {
+        this.opts = {
+            port: options.port ?? 2003,
+            unoPort: options.unoPort,
+            host: options.host ?? '127.0.0.1',
+            unoserverPath: options.unoserverPath ?? findUnoserver(),
+            unoconvertPath: options.unoconvertPath ?? findUnoconvert(),
+            libreOfficePath: options.libreOfficePath ?? findSoffice(),
+            userInstallation: options.userInstallation
+                ? resolvePath(options.userInstallation)
+                : undefined,
+            startTimeout: options.startTimeout ?? 15000,
+            convertTimeout: options.convertTimeout ?? 30000,
+        };
+    }
+    get port() {
+        return this.opts.port;
+    }
+    get host() {
+        return this.opts.host;
+    }
+    isReady() {
+        return this.ready;
+    }
+    async start() {
+        if (this.ready)
+            return;
+        const args = ['--interface', this.opts.host, '--port', String(this.opts.port)];
+        if (this.opts.unoPort !== undefined) {
+            args.push('--uno-port', String(this.opts.unoPort));
+        }
+        if (this.opts.libreOfficePath) {
+            args.push('--executable', this.opts.libreOfficePath);
+        }
+        if (this.opts.userInstallation) {
+            args.push('--user-installation', this.opts.userInstallation);
+        }
+        const proc = spawn(this.opts.unoserverPath, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: false,
+        });
+        this.proc = proc;
+        // Capture stderr so startup failures surface the real reason, not just a
+        // generic "did not become ready" timeout.
+        const stderrChunks = [];
+        proc.stderr?.on('data', (c) => stderrChunks.push(c));
+        // Also drain stdout (unoserver is quiet here but we must consume it to
+        // avoid filling the pipe buffer on some platforms).
+        proc.stdout?.on('data', () => { });
+        const collectStderr = () => Buffer.concat(stderrChunks).toString('utf8').trim();
+        let earlyExit = null;
+        const earlyExitPromise = new Promise((_, reject) => {
+            proc.once('exit', (code, signal) => {
+                this.ready = false;
+                this.proc = null;
+                if (earlyExit === null) {
+                    earlyExit = { code, signal };
+                    reject(new Error(`unoserver exited during startup (code=${code}, signal=${signal})\n` +
+                        `stderr:\n${collectStderr() || '(empty)'}`));
+                }
+            });
+        });
+        const spawnErrorPromise = new Promise((_, reject) => {
+            proc.once('error', (err) => {
+                this.ready = false;
+                reject(new Error(`unoserver spawn error: ${err.message}`));
+            });
+        });
+        const deadline = Date.now() + this.opts.startTimeout;
+        try {
+            await Promise.race([
+                waitForPort(this.opts.host, this.opts.port, deadline),
+                earlyExitPromise,
+                spawnErrorPromise,
+            ]);
+        }
+        catch (err) {
+            await this.stop();
+            if (earlyExit !== null) {
+                // Early-exit error is already descriptive; rethrow as-is.
+                throw err;
+            }
+            // Timeout path — attach whatever stderr we collected for debugging.
+            const stderr = collectStderr();
+            const message = `unoserver did not become ready on ${this.opts.host}:${this.opts.port} ` +
+                `within ${this.opts.startTimeout}ms\nstderr:\n${stderr || '(empty)'}`;
+            throw new Error(message);
+        }
+        this.ready = true;
+    }
+    async convert(input, format = 'pdf') {
+        if (!this.ready) {
+            throw new Error('UnoServer not started. Call .start() first.');
+        }
+        return new Promise((resolve, reject) => {
+            const args = [
+                '--host', this.opts.host,
+                '--port', String(this.opts.port),
+                '--convert-to', format,
+                '-', // input: stdin
+                '-', // output: stdout
+            ];
+            const client = spawn(this.opts.unoconvertPath, args, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const chunks = [];
+            const errChunks = [];
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                try {
+                    client.kill('SIGKILL');
+                }
+                catch { }
+                reject(new Error(`unoconvert timed out after ${this.opts.convertTimeout}ms`));
+            }, this.opts.convertTimeout);
+            client.stdout.on('data', (c) => chunks.push(c));
+            client.stderr.on('data', (c) => errChunks.push(c));
+            client.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+            client.on('close', (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (code === 0) {
+                    resolve(Buffer.concat(chunks));
+                }
+                else {
+                    const stderr = Buffer.concat(errChunks).toString('utf8').trim();
+                    reject(new Error(`unoconvert exited with code ${code}: ${stderr}`));
+                }
+            });
+            client.stdin.on('error', (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                reject(err);
+            });
+            client.stdin.end(Buffer.from(input));
+        });
+    }
+    async stop() {
+        this.ready = false;
+        const proc = this.proc;
+        this.proc = null;
+        if (!proc)
+            return;
+        try {
+            proc.kill('SIGTERM');
+        }
+        catch { }
+        // Give it a moment to exit cleanly, then force.
+        await new Promise((resolve) => {
+            const killTimer = setTimeout(() => {
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch { }
+                resolve();
+            }, 2000);
+            proc.once('exit', () => {
+                clearTimeout(killTimer);
+                resolve();
+            });
+        });
+    }
+}
+/**
+ * A pool of warm `unoserver` daemons, each listening on its own port.
+ * Use this when you need concurrent conversions — jobs are dispatched
+ * to the first idle worker, otherwise queued FIFO.
+ */
+export class UnoServerPool {
+    workers = [];
+    queue = [];
+    opts;
+    running = false;
+    constructor(options = {}) {
+        this.opts = {
+            workers: options.workers ?? 2,
+            basePort: options.basePort ?? 2003,
+            unoBasePort: options.unoBasePort ?? 2100,
+            tempDir: options.tempDir ?? `${process.env.TMPDIR ?? '/tmp'}/docverse_unoserver`,
+            startTimeout: options.startTimeout ?? 15000,
+            convertTimeout: options.convertTimeout ?? 30000,
+            host: options.host,
+            unoserverPath: options.unoserverPath,
+            unoconvertPath: options.unoconvertPath,
+            libreOfficePath: options.libreOfficePath,
+        };
+    }
+    async start() {
+        if (this.running)
+            return;
+        const { mkdirSync, existsSync } = await import('fs');
+        if (!existsSync(this.opts.tempDir)) {
+            mkdirSync(this.opts.tempDir, { recursive: true });
+        }
+        const servers = [];
+        for (let i = 0; i < this.opts.workers; i++) {
+            // unoserver expects a raw absolute path for --user-installation; passing
+            // a `file://` URI trips its internal `Path(...).as_uri()` and crashes.
+            const userInstallation = resolvePath(this.opts.tempDir, `worker_${i}`);
+            servers.push(new UnoServer({
+                port: this.opts.basePort + i,
+                unoPort: this.opts.unoBasePort + i,
+                host: this.opts.host,
+                unoserverPath: this.opts.unoserverPath,
+                unoconvertPath: this.opts.unoconvertPath,
+                libreOfficePath: this.opts.libreOfficePath,
+                userInstallation,
+                startTimeout: this.opts.startTimeout,
+                convertTimeout: this.opts.convertTimeout,
+            }));
+        }
+        await Promise.all(servers.map((s) => s.start()));
+        this.workers = servers.map((server) => ({ server, busy: false }));
+        this.running = true;
+    }
+    async convert(input, format = 'pdf') {
+        if (!this.running) {
+            throw new Error('UnoServerPool not started. Call .start() first.');
+        }
+        const buf = Buffer.from(input);
+        return new Promise((resolve, reject) => {
+            const idle = this.workers.find((w) => !w.busy);
+            if (idle) {
+                this.dispatch(idle, buf, format, resolve, reject);
+            }
+            else {
+                this.queue.push({ input: buf, format, resolve, reject });
+            }
+        });
+    }
+    dispatch(worker, buf, format, resolve, reject) {
+        worker.busy = true;
+        worker.server
+            .convert(buf, format)
+            .then(resolve, reject)
+            .finally(() => {
+            worker.busy = false;
+            const next = this.queue.shift();
+            if (next) {
+                this.dispatch(worker, next.input, next.format, next.resolve, next.reject);
+            }
+        });
+    }
+    async stop() {
+        this.running = false;
+        const pending = this.queue.splice(0);
+        for (const job of pending) {
+            job.reject(new Error('UnoServerPool stopped before job completed'));
+        }
+        await Promise.all(this.workers.map((w) => w.server.stop()));
+        this.workers = [];
+    }
+    getStats() {
+        return {
+            workers: this.workers.length,
+            ready: this.workers.filter((w) => w.server.isReady()).length,
+            busy: this.workers.filter((w) => w.busy).length,
+            queued: this.queue.length,
+        };
+    }
+}

package/dist/wordToPDF.d.ts

@@ -1,8 +1,21 @@
+import { UnoServer, UnoServerPool } from './unoServer.js';
+import type { UnoServerOptions } from './unoServer.js';
 export interface ConvertOptions {
     format?: string;
-    mode?: 'process' | 'socket' | 'pool';
+    mode?: 'process' | 'socket' | 'pool' | 'unoserver';
     socketUrl?: string;
     timeout?: number;
+    /**
+     * When `mode: 'unoserver'`, reuse this instance instead of the module-level
+     * shared singleton. Pass a `UnoServer` for a single warm daemon, or a
+     * `UnoServerPool` for concurrent workers.
+     */
+    unoServer?: UnoServer | UnoServerPool;
+    /**
+     * When `mode: 'unoserver'` and no `unoServer` is supplied, these options
+     * are used to lazily construct the shared singleton on the first call.
+     */
+    unoServerOptions?: UnoServerOptions;
 }
 export interface PoolOptions {
     workers?: number;
@@ -12,6 +25,12 @@ export interface PoolOptions {
     convertTimeout?: number;
 }
 export declare function wordToPDF(wordBuffer: Buffer | Uint8Array, optionsOrFormat?: string | ConvertOptions): Promise<Buffer>;
+/**
+ * Stops and clears the shared unoserver singleton created lazily by
+ * `wordToPDF(..., { mode: 'unoserver' })`. Safe to call even if nothing
+ * was started. Useful in graceful-shutdown hooks.
+ */
+export declare function stopSharedUnoServer(): Promise<void>;
 export declare class LibreOfficePool {
     private workers;
     private queue;

package/dist/wordToPDF.js

@@ -4,6 +4,7 @@ import { writeFileSync, readFileSync, unlinkSync, mkdirSync, existsSync } from '
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomBytes } from 'crypto';
+import { UnoServer } from './unoServer.js';
 // ═══════════════════════════════════════════════
 // SIMPLE CONVERT (backward compatible)
 // ═══════════════════════════════════════════════
@@ -14,12 +15,50 @@ export async function wordToPDF(wordBuffer, optionsOrFormat = 'pdf') {
     const format = opts.format ?? 'pdf';
     const mode = opts.mode ?? 'process';
     const timeout = opts.timeout ?? 30000;
+    if (mode === 'unoserver') {
+        return convertViaUnoServer(wordBuffer, format, opts);
+    }
     if (mode === 'socket' && opts.socketUrl) {
         return convertViaSocket(wordBuffer, format, opts.socketUrl, timeout);
     }
     return convertViaProcess(wordBuffer, format, timeout);
 }
 // ═══════════════════════════════════════════════
+// UNOSERVER MODE (warm LibreOffice, 200–500ms)
+// ═══════════════════════════════════════════════
+let sharedUnoServer = null;
+let sharedUnoServerStarting = null;
+async function getSharedUnoServer(options) {
+    if (sharedUnoServer && sharedUnoServer.isReady())
+        return sharedUnoServer;
+    if (sharedUnoServerStarting)
+        return sharedUnoServerStarting;
+    sharedUnoServerStarting = (async () => {
+        const server = new UnoServer(options);
+        await server.start();
+        sharedUnoServer = server;
+        sharedUnoServerStarting = null;
+        return server;
+    })();
+    return sharedUnoServerStarting;
+}
+/**
+ * Stops and clears the shared unoserver singleton created lazily by
+ * `wordToPDF(..., { mode: 'unoserver' })`. Safe to call even if nothing
+ * was started. Useful in graceful-shutdown hooks.
+ */
+export async function stopSharedUnoServer() {
+    const server = sharedUnoServer;
+    sharedUnoServer = null;
+    sharedUnoServerStarting = null;
+    if (server)
+        await server.stop();
+}
+async function convertViaUnoServer(wordBuffer, format, opts) {
+    const instance = opts.unoServer ?? (await getSharedUnoServer(opts.unoServerOptions));
+    return instance.convert(wordBuffer, format);
+}
+// ═══════════════════════════════════════════════
 // PROCESS MODE (original, 3-5s)
 // ═══════════════════════════════════════════════
 async function convertViaProcess(wordBuffer, format, timeout) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docverse-pdf/server",
-  "version": "1.0.6",
-  "description": "DocVerse Server SDK — server-side PDF processing, XFDF merge, Word to PDF, image extraction",
+  "version": "1.1.1",
+  "description": "DocVerse Server SDK — server-side PDF processing, XFDF merge, Word to PDF (unoserver + LibreOffice), image extraction",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",