@tstdl/base 0.93.128 → 0.93.130

package/api/client/tests/api-client.test.js

@@ -156,9 +156,9 @@ describe('ApiClient', () => {
         expect(mockHttpClient.rawRequest.mock.calls.at(-1)[0].credentials).toBe('include');
         await client.withBustCache();
         expect(mockHttpClient.rawRequest.mock.calls.at(-1)[0].context[bustCache]).toBe(true);
-        expect(Client.getEndpointResource('withCredentials')).toContain('with-credentials');
-        expect(Client.getEndpointUrl('withCredentials').href).toBe('http://baseurl/api/v1/features/with-credentials');
-        expect(client.getEndpointUrl('withCredentials').href).toBe('http://localhost/api/v1/features/with-credentials');
+        expect(Client.getEndpointResource('withCredentials')).not.toContain('withCredentials');
+        expect(Client.getEndpointUrl('withCredentials').href).toBe('http://baseurl/api/v1/features');
+        expect(client.getEndpointUrl('withCredentials').href).toBe('http://localhost/api/v1/features');
     });
     it('should handle Server Sent Events and DataStream', async () => {
         const apiDefinition = defineApi({
@@ -185,10 +185,10 @@ describe('ApiClient', () => {
         const client = new Client(mockHttpClient);
         const sse = await client.events();
         expect(sse).toBeInstanceOf(ServerSentEvents);
-        expect(EventSourceMock).toHaveBeenCalledWith(expect.stringContaining('sse/events'), expect.any(Object));
+        expect(EventSourceMock).toHaveBeenCalledWith(expect.stringContaining('sse'), expect.any(Object));
         const stream = await client.stream();
         expect(stream).toBeInstanceOf(Object); // It's an Observable
-        expect(EventSourceMock).toHaveBeenCalledWith(expect.stringContaining('sse/stream'), expect.any(Object));
+        expect(EventSourceMock).toHaveBeenCalledWith(expect.stringContaining('sse'), expect.any(Object));
         vi.unstubAllGlobals();
     });
 });

package/api/types.d.ts

@@ -54,7 +54,7 @@ export type ApiEndpointDefinition = {
      *
      * results in
      * ```ts
-     * ${endpoint.rootResource ?? api.ressource}/${endpoint.resource}
+     * ${endpoint.rootResource ?? api.resource}/${endpoint.resource}
      * ```
      * @default name of endpoint property
      */

package/api/types.js

@@ -1,6 +1,5 @@
 import { objectEntries } from '../utils/object/object.js';
-import { hyphenate } from '../utils/string/index.js';
-import { isFunction, isUndefined } from '../utils/type-guards.js';
+import { isFunction } from '../utils/type-guards.js';
 import { resolveValueOrProvider } from '../utils/value-or-provider.js';
 export function defineApi(definition) {
     return definition;
@@ -16,11 +15,5 @@ export function normalizedApiDefinitionEndpoints(apiDefinitionEndpoints) {
     return Object.fromEntries(entries);
 }
 export function normalizedApiDefinitionEndpointsEntries(apiDefinition) {
-    return objectEntries(apiDefinition).map(([key, def]) => {
-        const endpoint = resolveValueOrProvider(def);
-        if (isUndefined(endpoint.resource)) {
-            endpoint.resource = hyphenate(key);
-        }
-        return [key, endpoint];
-    });
+    return objectEntries(apiDefinition).map(([key, def]) => [key, resolveValueOrProvider(def)]);
 }

package/document-management/server/services/document-file.service.js

@@ -6,7 +6,6 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import sharp, {} from 'sharp';
 import { match } from 'ts-pattern';
-import { injectGenkit } from '../../../ai/genkit/index.js';
 import { ForbiddenError } from '../../../errors/forbidden.error.js';
 import { NotImplementedError } from '../../../errors/not-implemented.error.js';
 import { getMimeType, getMimeTypeExtensions, mimeTypes } from '../../../file/index.js';
@@ -20,14 +19,15 @@ import { digest } from '../../../utils/cryptography.js';
 import { currentTimestamp } from '../../../utils/date-time.js';
 import { getRandomString } from '../../../utils/random.js';
 import { readableStreamFromPromise, readBinaryStream } from '../../../utils/stream/index.js';
-import { isNotReadableStream, isNotUint8Array, isUint8Array } from '../../../utils/type-guards.js';
+import { isNotReadableStream, isNotUint8Array, isString, isUint8Array } from '../../../utils/type-guards.js';
 import { millisecondsPerMinute } from '../../../utils/units.js';
 import { Document } from '../../models/index.js';
 import { DocumentManagementConfiguration } from '../module.js';
+import { DocumentManagementAncillaryService } from './document-management-ancillary.service.js';
 import { DocumentManagementSingleton } from './singleton.js';
 let DocumentFileService = class DocumentFileService extends Transactional {
     #configuration = inject(DocumentManagementConfiguration);
-    #genkit = injectGenkit();
+    #documentManagementAncillaryService = inject(DocumentManagementAncillaryService);
     #fileObjectStorage = inject(ObjectStorage, this.#configuration.fileObjectStorageModule);
     #filePreviewObjectStorage = inject(ObjectStorage, this.#configuration.filePreviewObjectStorageModule);
     #fileUploadObjectStorage = inject(ObjectStorage, { module: this.#configuration.fileUploadObjectStorageModule /* , configuration: { lifecycle: { expiration: { after: 5 * secondsPerMinute } } } */ });
@@ -86,7 +86,10 @@ let DocumentFileService = class DocumentFileService extends Transactional {
         return this.#fileObjectStorage.getContentStream(objectKey);
     }
     async getContentUrl(document, download = false) {
-        return await this.getDocumentFileContentObjectUrl(document, document.title ?? document.id, download);
+        const resolvedFilename = await this.#documentManagementAncillaryService.getDocumentFilename(document);
+        const fileExtension = getMimeTypeExtensions(document.mimeType)[0] ?? 'bin';
+        const filename = isString(resolvedFilename) ? `${resolvedFilename}.${fileExtension}` : resolvedFilename.fullname;
+        return await this.getDocumentFileContentObjectUrl(document, filename, download);
     }
     /** Gets the underlying object storage object for the document file */
     async getObject(document) {
@@ -132,14 +135,12 @@ let DocumentFileService = class DocumentFileService extends Transactional {
             await this.#filePreviewObjectStorage.uploadObject(key, image, { contentLength: image.length, contentType: 'image/webp' });
         }
     }
-    async getDocumentFileContentObjectUrl(document, title, download) {
+    async getDocumentFileContentObjectUrl(document, filename, download) {
         const key = getObjectKey(document.id);
-        const fileExtension = getMimeTypeExtensions(document.mimeType)[0] ?? 'bin';
         const disposition = download ? 'attachment' : 'inline';
-        const filename = `${title}.${fileExtension}`;
         return await this.#fileObjectStorage.getDownloadUrl(key, currentTimestamp() + (5 * millisecondsPerMinute), {
-            'Response-Content-Type': document.mimeType,
-            'Response-Content-Disposition': `${disposition}; filename = "${encodeURIComponent(filename)}"`,
+            'Content-Type': document.mimeType,
+            'Content-Disposition': `${disposition}; filename = "${encodeURIComponent(filename)}"`,
         });
     }
 };

package/document-management/server/services/document-management-ancillary.service.d.ts

@@ -1,5 +1,9 @@
-import type { DocumentCollection } from '../../models/index.js';
+import type { Document, DocumentCollection } from '../../models/index.js';
 import type { DocumentCollectionMetadata } from '../../service-models/index.js';
+export type DocumentFileNameResult = string | {
+    /** The full name of the document, including extension. */
+    fullname: string;
+};
 export declare abstract class DocumentManagementAncillaryService {
     /**
      * Resolves application-specific metadata for a list of document collections.
@@ -7,4 +11,11 @@ export declare abstract class DocumentManagementAncillaryService {
      * @returns A promise that resolves to an array of DocumentCollectionMetadata, corresponding to the input collections.
      */
     abstract resolveMetadata(tenantId: string, collections: DocumentCollection[]): DocumentCollectionMetadata[] | Promise<DocumentCollectionMetadata[]>;
+    /**
+     * Resolve the file name for a document, which will be used when downloading the document file. The file extension is automatically determined based on the document's MIME type, so the returned file name should not include the extension.
+     * @param document The Document entity for which to resolve the file name.
+     * @param title An optional title provided by the api call.
+     * @returns The resolved file name for the document, without the file extension.
+     */
+    getDocumentFilename(document: Document): DocumentFileNameResult | Promise<DocumentFileNameResult>;
 }

package/document-management/server/services/document-management-ancillary.service.js

@@ -1,2 +1,11 @@
 export class DocumentManagementAncillaryService {
+    /**
+     * Resolve the file name for a document, which will be used when downloading the document file. The file extension is automatically determined based on the document's MIME type, so the returned file name should not include the extension.
+     * @param document The Document entity for which to resolve the file name.
+     * @param title An optional title provided by the api call.
+     * @returns The resolved file name for the document, without the file extension.
+     */
+    getDocumentFilename(document) {
+        return document.title ?? document.originalFileName ?? document.id;
+    }
 }

package/file/server/temporary-file.d.ts

@@ -12,7 +12,7 @@ export declare class TemporaryFile implements AsyncDisposable {
     /**
      * Prevents the temporary file from being deleted on disposal.
      */
-    keep(): void;
+    keep(): this;
     read(): Promise<Uint8Array>;
     readText(): Promise<string>;
     readStream(): ReadableStream<Uint8Array>;
@@ -25,5 +25,6 @@ export declare class TemporaryFile implements AsyncDisposable {
     moveTo(path: string, keep?: boolean): Promise<void>;
     delete(): Promise<void>;
     size(): Promise<number>;
+    dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/file/server/temporary-file.js

@@ -36,6 +36,7 @@ export class TemporaryFile {
      */
     keep() {
         this.#keep = true;
+        return this;
     }
     async read() {
         return await readFile(this.#path);
@@ -69,7 +70,7 @@ export class TemporaryFile {
         const result = await stat(this.#path);
         return result.size;
     }
-    async [Symbol.asyncDispose]() {
+    async dispose() {
         if (this.#keep) {
             return;
         }
@@ -78,4 +79,7 @@ export class TemporaryFile {
         }
         catch { }
     }
+    async [Symbol.asyncDispose]() {
+        await this.dispose();
+    }
 }

package/object-storage/s3/s3.object-storage.js

@@ -240,16 +240,16 @@ let S3ObjectStorage = S3ObjectStorage_1 = class S3ObjectStorage extends ObjectSt
     async getDownloadUrl(key, expirationTimestamp, responseHeaders) {
         const bucketKey = this.getBucketKey(key);
         const expiration = getExpiration(expirationTimestamp);
-        const expiresHeader = responseHeaders?.['Expires'];
+        const expiresHeader = responseHeaders?.['Expires'] ?? responseHeaders?.['Response-Expires'];
         const mappedExpiresHeader = isDefined(expiresHeader) ? (isDate(expiresHeader) ? expiresHeader : new Date(expiresHeader)) : undefined;
         return await getSignedUrl(this.client, new GetObjectCommand({
             Bucket: this.bucket,
             Key: bucketKey,
-            ResponseContentType: responseHeaders?.['Content-Type'],
-            ResponseContentDisposition: responseHeaders?.['Content-Disposition'],
-            ResponseCacheControl: responseHeaders?.['Cache-Control'],
-            ResponseContentLanguage: responseHeaders?.['Content-Language'],
-            ResponseContentEncoding: responseHeaders?.['Content-Encoding'],
+            ResponseContentType: responseHeaders?.['Content-Type'] ?? responseHeaders?.['Response-Content-Type'],
+            ResponseContentDisposition: responseHeaders?.['Content-Disposition'] ?? responseHeaders?.['Response-Content-Disposition'],
+            ResponseCacheControl: responseHeaders?.['Cache-Control'] ?? responseHeaders?.['Response-Cache-Control'],
+            ResponseContentLanguage: responseHeaders?.['Content-Language'] ?? responseHeaders?.['Response-Content-Language'],
+            ResponseContentEncoding: responseHeaders?.['Content-Encoding'] ?? responseHeaders?.['Response-Content-Encoding'],
             ResponseExpires: mappedExpiresHeader,
         }), { expiresIn: expiration });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.128",
+  "version": "0.93.130",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -162,8 +162,8 @@
     "file-type": "^21.3",
     "genkit": "^1.28",
     "handlebars": "^4.7",
-    "@aws-sdk/client-s3": "^3.990",
-    "@aws-sdk/s3-request-presigner": "^3.990",
+    "@aws-sdk/client-s3": "^3.991",
+    "@aws-sdk/s3-request-presigner": "^3.991",
     "mjml": "^4.18",
     "nodemailer": "^8.0",
     "pg": "^8.18",
@@ -199,7 +199,7 @@
     "typedoc-plugin-markdown": "4.10",
     "typedoc-plugin-missing-exports": "4.1",
     "typescript": "5.9",
-    "typescript-eslint": "8.55",
+    "typescript-eslint": "8.56",
     "vite-tsconfig-paths": "6.1",
     "vitest": "4.0"
   },

package/pdf/tests/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/pdf/tests/utils.test.js

@@ -0,0 +1,187 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { describe, expect, it } from 'vitest';
+import { TemporaryFile } from '../../file/server/temporary-file.js';
+import { spawnCommand } from '../../process/spawn.js';
+import { extractPdfPages, getPdfPageCount, mergePdfs, overlayPdfs, pdfToImage } from '../utils.js';
+describe('pdf utils', () => {
+    async function createPdf(pages) {
+        const file = TemporaryFile.create('.pdf');
+        const source = Array.from({ length: pages }, (_, i) => `Page ${i + 1}`).join('\n#pagebreak()\n');
+        const process = await spawnCommand('typst', ['compile', '-', file.path]);
+        await process.write(source);
+        await process.wait();
+        return file;
+    }
+    it('getPdfPageCount should return correct page count', async () => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf = __addDisposableResource(env_1, await createPdf(5), true);
+            const count = await getPdfPageCount(pdf.path);
+            expect(count).toBe(5);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    });
+    it('extractPdfPages should extract specific pages', async () => {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf = __addDisposableResource(env_2, await createPdf(10), true);
+            const extracted = __addDisposableResource(env_2, await extractPdfPages(pdf.path, [1, { from: 3, to: 5 }]), true);
+            const count = await getPdfPageCount(extracted.path);
+            expect(count).toBe(4); // 1 + (5-3+1) = 4
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            const result_2 = __disposeResources(env_2);
+            if (result_2)
+                await result_2;
+        }
+    });
+    it('mergePdfs should handle different input types and page ranges', async () => {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf1 = __addDisposableResource(env_3, await createPdf(2), true);
+            const pdf2 = __addDisposableResource(env_3, await createPdf(3), true);
+            const pdf2Bytes = await pdf1.read();
+            // Test with path, Uint8Array, and page range object
+            const merged = __addDisposableResource(env_3, await mergePdfs([
+                pdf1.path,
+                pdf2Bytes,
+                { input: pdf2.path, pages: [1, { from: 2, to: 3 }] },
+            ]), true);
+            const count = await getPdfPageCount(merged.path);
+            expect(count).toBe(2 + 2 + 3); // 2 (path) + 2 (bytes) + 3 (page range)
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            const result_3 = __disposeResources(env_3);
+            if (result_3)
+                await result_3;
+        }
+    });
+    it('pdfToImage should work with binary inputs', async () => {
+        const env_4 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf = __addDisposableResource(env_4, await createPdf(1), true);
+            const pdfBytes = await pdf.read();
+            // pdftocairo fails in some environments if no fonts are available,
+            // but here we just want to test the branching logic of writing bytes
+            const result = await pdfToImage(pdfBytes, 1, 100, 'png');
+            expect(result).toBeInstanceOf(Uint8Array);
+        }
+        catch (e_4) {
+            env_4.error = e_4;
+            env_4.hasError = true;
+        }
+        finally {
+            const result_4 = __disposeResources(env_4);
+            if (result_4)
+                await result_4;
+        }
+    });
+    it('overlayPdfs should overlay two pdfs', async () => {
+        const env_5 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf1 = __addDisposableResource(env_5, await createPdf(1), true);
+            const pdf2 = __addDisposableResource(env_5, await createPdf(1), true);
+            const overlaid = __addDisposableResource(env_5, await overlayPdfs(pdf1.path, pdf2.path), true);
+            const count = await getPdfPageCount(overlaid.path);
+            expect(count).toBe(1);
+        }
+        catch (e_5) {
+            env_5.error = e_5;
+            env_5.hasError = true;
+        }
+        finally {
+            const result_5 = __disposeResources(env_5);
+            if (result_5)
+                await result_5;
+        }
+    });
+    it('overlayPdfs with repeat should overlay and respect repeat option', async () => {
+        const env_6 = { stack: [], error: void 0, hasError: false };
+        try {
+            const pdf1 = __addDisposableResource(env_6, await createPdf(1), true);
+            const pdf2 = __addDisposableResource(env_6, await createPdf(1), true);
+            const overlaid = __addDisposableResource(env_6, await overlayPdfs(pdf1.path, pdf2.path, { repeat: true }), true);
+            const count = await getPdfPageCount(overlaid.path);
+            expect(count).toBe(1);
+        }
+        catch (e_6) {
+            env_6.error = e_6;
+            env_6.hasError = true;
+        }
+        finally {
+            const result_6 = __disposeResources(env_6);
+            if (result_6)
+                await result_6;
+        }
+    });
+    it('should throw descriptive error on qpdf failure', async () => {
+        await expect(getPdfPageCount('non-existent.pdf')).rejects.toThrow(/qpdf: open non-existent.pdf: No such file or directory/);
+    });
+});

package/pdf/utils.d.ts

@@ -1,6 +1,23 @@
-export declare function getPdfPageCount(file: string | Uint8Array | ReadableStream<Uint8Array>): Promise<number>;
-export declare function mergePdfs(pdfs: (string | Uint8Array | ReadableStream<Uint8Array>)[]): Promise<Uint8Array>;
-export declare function mergePdfsStream(pdfs: (string | Uint8Array | ReadableStream<Uint8Array>)[]): Promise<ReadableStream<Uint8Array>>;
+import { TemporaryFile } from '../file/server/temporary-file.js';
+export type PdfInput = string | {
+    file: string;
+} | Uint8Array | ReadableStream<Uint8Array>;
+export type PdfInputWithPageRange = string | {
+    file: string;
+} | Uint8Array | ReadableStream<Uint8Array> | {
+    input: PdfInput;
+    pages: PageRange[];
+};
+export type PageRange = number | {
+    from?: number;
+    to?: number;
+};
+export declare function getPdfPageCount(file: PdfInput): Promise<number>;
+export declare function extractPdfPages(file: PdfInput, pages: PageRange[]): Promise<TemporaryFile>;
+export declare function mergePdfs(sourceFiles: PdfInputWithPageRange[]): Promise<TemporaryFile>;
+export declare function overlayPdfs(base: PdfInput, overlay: PdfInput, options?: {
+    repeat?: boolean;
+}): Promise<TemporaryFile>;
 /**
  * Convert a PDF page to an image.
  * @param file The PDF file to convert.
@@ -10,3 +27,7 @@ export declare function mergePdfsStream(pdfs: (string | Uint8Array | ReadableStr
  * @returns The converted image as a byte array.
  */
 export declare function pdfToImage(file: string | Uint8Array | ReadableStream<Uint8Array>, page: number, size: number, format: 'png' | 'jpeg' | 'tiff' | 'ps' | 'eps' | 'pdf' | 'svg'): Promise<Uint8Array>;
+export declare function isInputWithPageRange(input: PdfInputWithPageRange): input is {
+    input: PdfInput;
+    pages: PageRange[];
+};

package/pdf/utils.js

@@ -51,22 +51,17 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 import { TemporaryFile } from '../file/server/temporary-file.js';
-import { spawnCommand } from '../process/spawn.js';
-import { isNotString, isString } from '../utils/type-guards.js';
+import { spawnCommand, spawnWaitCommand } from '../process/spawn.js';
+import { hasOwnProperty } from '../utils/object/object.js';
+import { isNotString, isNumber, isObject, isReadableStream, isString, isUint8Array, isUndefined } from '../utils/type-guards.js';
 export async function getPdfPageCount(file) {
     const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const fileIsPath = isString(file);
-        const tmpFile = __addDisposableResource(env_1, fileIsPath ? undefined : await TemporaryFile.from(file), true);
-        const path = fileIsPath ? file : tmpFile.path;
-        const process = await spawnCommand('qpdf', ['--show-npages', path]);
-        const { code } = await process.wait();
-        if (code != 0) {
-            const errorOutput = await process.readError();
-            throw new Error(errorOutput.trim());
-        }
-        const output = await process.readOutput();
-        return Number(output);
+        const stack = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+        const [sourceFile] = await getPdfSourceFiles([file], stack);
+        const process = await spawnCommand('qpdf', ['--show-npages', sourceFile]);
+        const result = await process.waitRead('string');
+        return Number(result.output);
     }
     catch (e_1) {
         env_1.error = e_1;
@@ -78,14 +73,15 @@ export async function getPdfPageCount(file) {
             await result_1;
     }
 }
-export async function mergePdfs(pdfs) {
+export async function extractPdfPages(file, pages) {
     const env_2 = { stack: [], error: void 0, hasError: false };
     try {
         const stack = __addDisposableResource(env_2, new AsyncDisposableStack(), true);
-        const resultFile = __addDisposableResource(env_2, TemporaryFile.create(), true);
-        const sourceFiles = await getPdfSourceFiles(pdfs, stack);
-        await pdfunite(sourceFiles, resultFile);
-        return await resultFile.read();
+        const [sourceFile] = await getPdfSourceFiles([file], stack);
+        const resultFile = TemporaryFile.create();
+        const pagesString = toQpdfPageRangeString(pages);
+        await spawnWaitCommand('qpdf', ['--empty', '--pages', sourceFile, pagesString, '--', resultFile.path]);
+        return resultFile.keep();
     }
     catch (e_2) {
         env_2.error = e_2;
@@ -97,14 +93,23 @@ export async function mergePdfs(pdfs) {
             await result_2;
     }
 }
-export async function mergePdfsStream(pdfs) {
+export async function mergePdfs(sourceFiles) {
     const env_3 = { stack: [], error: void 0, hasError: false };
     try {
         const stack = __addDisposableResource(env_3, new AsyncDisposableStack(), true);
         const resultFile = __addDisposableResource(env_3, TemporaryFile.create(), true);
-        const sourceFiles = await getPdfSourceFiles(pdfs, stack);
-        await pdfunite(sourceFiles, resultFile);
-        return resultFile.readStream();
+        const sourceFilePaths = await getPdfSourceFiles(sourceFiles, stack);
+        const pages = sourceFiles.map((source) => isInputWithPageRange(source) ? source.pages : undefined);
+        const sourceArguments = sourceFilePaths.flatMap((path, index) => {
+            const pageRanges = pages[index];
+            if (isUndefined(pageRanges)) {
+                return [path];
+            }
+            const pagesString = toQpdfPageRangeString(pageRanges);
+            return [path, pagesString];
+        });
+        await spawnWaitCommand('qpdf', ['--empty', '--pages', ...sourceArguments, '--', resultFile.path]);
+        return resultFile.keep();
     }
     catch (e_3) {
         env_3.error = e_3;
@@ -116,22 +121,28 @@ export async function mergePdfsStream(pdfs) {
             await result_3;
     }
 }
-async function getPdfSourceFiles(pdfs, stack) {
-    return await Promise.all(pdfs.map(async (pdf) => {
-        if (isString(pdf)) {
-            return pdf;
+export async function overlayPdfs(base, overlay, options) {
+    const env_4 = { stack: [], error: void 0, hasError: false };
+    try {
+        const stack = __addDisposableResource(env_4, new AsyncDisposableStack(), true);
+        const resultFile = __addDisposableResource(env_4, TemporaryFile.create(), true);
+        const [baseFilePath, overlayFilePath] = await getPdfSourceFiles([base, overlay], stack);
+        const args = [baseFilePath, '--overlay', overlayFilePath];
+        if (options?.repeat) {
+            args.push('--repeat=1');
         }
-        const tmpFile = await TemporaryFile.from(pdf);
-        stack.use(tmpFile);
-        return tmpFile.path;
-    }));
-}
-async function pdfunite(sourceFiles, resultFile) {
-    const process = await spawnCommand('pdfunite', [...sourceFiles, resultFile.path]);
-    const { code } = await process.wait();
-    if (code != 0) {
-        const errorOutput = await process.readError();
-        throw new Error(errorOutput);
+        args.push('--', resultFile.path);
+        await spawnWaitCommand('qpdf', args);
+        return resultFile.keep();
+    }
+    catch (e_4) {
+        env_4.error = e_4;
+        env_4.hasError = true;
+    }
+    finally {
+        const result_4 = __disposeResources(env_4);
+        if (result_4)
+            await result_4;
     }
 }
 /**
@@ -145,9 +156,40 @@ async function pdfunite(sourceFiles, resultFile) {
 export async function pdfToImage(file, page, size, format) {
     const path = isString(file) ? file : '-';
     const process = await spawnCommand('pdftocairo', ['-f', String(page), '-l', String(page), '-scale-to', String(size), '-singlefile', `-${format}`, path, '-']);
-    process.handleNonZeroExitCode();
     if (isNotString(file)) {
         process.writeInBackground(file);
     }
     return await process.readOutputBytes();
 }
+function toQpdfPageRangeString(pages) {
+    return pages.map((page) => {
+        if (isNumber(page)) {
+            return String(page);
+        }
+        else {
+            const from = page.from ?? '1';
+            const to = page.to ?? 'z';
+            return `${from}-${to}`;
+        }
+    }).join(',');
+}
+async function getPdfSourceFiles(input, stack) {
+    return await Promise.all(input.map(async (pdf) => {
+        if (isUint8Array(pdf) || isReadableStream(pdf)) {
+            const tmpFile = await TemporaryFile.from(pdf);
+            stack.use(tmpFile);
+            return tmpFile.path;
+        }
+        if (isString(pdf)) {
+            return pdf;
+        }
+        if (isInputWithPageRange(pdf)) {
+            const [path] = await getPdfSourceFiles([pdf.input], stack);
+            return path;
+        }
+        return pdf.file;
+    }));
+}
+export function isInputWithPageRange(input) {
+    return isObject(input) && hasOwnProperty(input, 'input') && hasOwnProperty(input, 'pages');
+}

package/process/spawn.d.ts

@@ -18,7 +18,7 @@ export type SpawnOptions = {
     workingDirectory?: string;
     environment?: Record<string, string>;
 };
-export type SpawnCommandResult = TransformStream<Uint8Array, Uint8Array> & {
+export type SpawnCommandResult = TransformStream<Uint8Array, Uint8Array<ArrayBuffer>> & {
     process: ChildProcessWithoutNullStreams;
     stderr: ReadableStream<Uint8Array>;
     write(chunk: ReadableStream<Uint8Array> | Uint8Array | string, options?: StreamPipeOptions): Promise<void>;

package/process/spawn.js

@@ -1,11 +1,11 @@
 import { dynamicImport } from '../import.js';
 import { LazyPromise } from '../promise/lazy-promise.js';
-import { decodeTextStream, encodeUtf8Stream } from '../utils/encoding.js';
-import { readBinaryStream, readTextStream } from '../utils/stream/stream-reader.js';
+import { decodeText, encodeUtf8Stream } from '../utils/encoding.js';
+import { readBinaryStream } from '../utils/stream/stream-reader.js';
 import { toReadableStream } from '../utils/stream/to-readable-stream.js';
-import { assertNotNullOrUndefinedPass, isArray, isReadableStream, isString, isUint8Array } from '../utils/type-guards.js';
+import { assertNotNullOrUndefinedPass, isArray, isNotNull, isReadableStream, isString, isUint8Array } from '../utils/type-guards.js';
 export async function spawnWaitCommand(command, argsOrOptions, optionsOrNothing) {
-    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [undefined, argsOrOptions];
+    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [argsOrOptions?.arguments, argsOrOptions];
     const process = await spawnCommand(command, args, options);
     return await process.wait({ throwOnNonZeroExitCode: options?.throwOnNonZeroExitCode });
 }
@@ -17,7 +17,7 @@ export async function spawnWaitReadCommand(format, command, argsOrOptions, optio
 export async function spawnCommand(command, argsOrOptions, optionsOrNothing) {
     const { spawn } = await dynamicImport('node:child_process');
     const { Readable, Writable } = await dynamicImport('node:stream');
-    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [undefined, argsOrOptions];
+    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [argsOrOptions?.arguments, argsOrOptions];
     const process = spawn(command, args, { stdio: 'pipe', cwd: options?.workingDirectory, env: options?.environment });
     await Promise.race([
         new Promise((resolve) => process.on('spawn', resolve)),
@@ -40,29 +40,41 @@ export async function spawnCommand(command, argsOrOptions, optionsOrNothing) {
     /** Writes data in the background. Must be used with care because of potential unhandled errors */
     function writeInBackground(data, options) {
         write(data, options).catch((error) => {
-            readable.cancel(error).catch(() => { });
-            writable.abort(error).catch(() => { });
+            void readable.cancel(error).catch(() => { });
+            void writable.abort(error).catch(() => { });
+            void stderr.cancel(error).catch(() => { });
         });
     }
+    const outputBytes = new LazyPromise(async () => await readBinaryStream(readable));
+    const errorBytes = new LazyPromise(async () => await readBinaryStream(stderr));
+    const outputText = new LazyPromise(async () => decodeText(await outputBytes));
+    const errorText = new LazyPromise(async () => decodeText(await errorBytes));
     async function readOutputBytes() {
-        return await readBinaryStream(readable);
+        return await outputBytes;
     }
     async function readOutput() {
-        return await readTextStream(readable.pipeThrough(decodeTextStream()));
+        return await outputText;
     }
     async function readErrorBytes() {
-        return await readBinaryStream(stderr);
+        return await errorBytes;
     }
     async function readError() {
-        return await readTextStream(stderr.pipeThrough(decodeTextStream()));
+        return await errorText;
     }
-    const signalPromise = new Promise((resolve) => process.on('close', (code, signal) => resolve({ code, signal })));
+    const signalPromise = new Promise((resolve) => process.on('close', (code, signal) => {
+        const result = { code, signal };
+        resolve(result);
+        if ((code != 0) || isNotNull(signal)) {
+            void handleNonZeroExitCode();
+        }
+    }));
     const nonZeroExitCodeError = new LazyPromise(async () => {
         const result = await signalPromise;
-        if (result.code != 0) {
+        if ((result.code != 0) || isNotNull(result.signal)) {
             try {
-                const errorOutput = await readError();
-                return new Error(errorOutput.trim());
+                const errorOutput = await errorText;
+                const message = errorOutput.trim();
+                return new Error(message.length > 0 ? message : `Process exited with code ${result.code} and signal ${result.signal}.`);
             }
             catch {
                 return new Error(`Process exited with code ${result.code} and signal ${result.signal}.`);
@@ -75,12 +87,12 @@ export async function spawnCommand(command, argsOrOptions, optionsOrNothing) {
         if (error) {
             await writable.abort(error).catch(() => { });
             await readable.cancel(error).catch(() => { });
+            await stderr.cancel(error).catch(() => { });
         }
     }
     async function wait({ throwOnNonZeroExitCode = true } = {}) {
         const result = await signalPromise;
-        const handleNonZeroExitCode = (result.code != 0) && throwOnNonZeroExitCode;
-        if (handleNonZeroExitCode) {
+        if (((result.code != 0) || isNotNull(result.signal)) && throwOnNonZeroExitCode) {
             const error = await nonZeroExitCodeError;
             throw assertNotNullOrUndefinedPass(error);
         }
@@ -88,10 +100,14 @@ export async function spawnCommand(command, argsOrOptions, optionsOrNothing) {
     }
     async function waitRead(format, { throwOnNonZeroExitCode = true } = {}) {
         const [result, output, error] = await Promise.all([
-            wait({ throwOnNonZeroExitCode }),
-            (format === 'string') ? readOutput() : readOutputBytes(),
-            (format === 'string') ? readError() : readErrorBytes(),
+            wait({ throwOnNonZeroExitCode: false }),
+            (format === 'string') ? outputText : outputBytes,
+            (format === 'string') ? errorText : errorBytes,
         ]);
+        if (((result.code != 0) || isNotNull(result.signal)) && throwOnNonZeroExitCode) {
+            const error = await nonZeroExitCodeError;
+            throw assertNotNullOrUndefinedPass(error);
+        }
         return {
             ...result,
             output: output,

package/process/tests/spawn.test.d.ts

@@ -0,0 +1 @@
+export {};

package/process/tests/spawn.test.js

@@ -0,0 +1,182 @@
+import { describe, expect, it, vi } from 'vitest';
+import { encodeUtf8 } from '../../utils/encoding.js';
+import { toReadableStream } from '../../utils/stream/to-readable-stream.js';
+import { spawnCommand, spawnWaitCommand, spawnWaitReadCommand } from '../spawn.js';
+describe('spawn', () => {
+    describe('spawnCommand', () => {
+        it('should spawn a command and wait for completion', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 0']);
+            const result = await process.wait();
+            expect(result.code).toBe(0);
+        });
+        it('should throw on non-zero exit code', async () => {
+            const process = await spawnCommand('sh', ['-c', 'echo "error message" >&2; exit 1']);
+            await expect(process.wait()).rejects.toThrow('error message');
+        });
+        it('should handle process terminated by signal', async () => {
+            const process = await spawnCommand('sh', ['-c', 'kill -9 $$']);
+            await expect(process.wait()).rejects.toThrow('Process exited with code null and signal SIGKILL');
+        });
+        it('should buffer stdout and allow multiple reads', async () => {
+            const process = await spawnCommand('sh', ['-c', 'echo "hello world"']);
+            await process.wait();
+            const output1 = await process.readOutput();
+            const output2 = await process.readOutput();
+            const outputBytes = await process.readOutputBytes();
+            expect(output1.trim()).toBe('hello world');
+            expect(output1).toBe(output2);
+            expect(new TextDecoder().decode(outputBytes).trim()).toBe('hello world');
+        });
+        it('should buffer stderr and allow multiple reads', async () => {
+            const process = await spawnCommand('sh', ['-c', 'echo "error message" >&2']);
+            await process.wait();
+            const error1 = await process.readError();
+            const error2 = await process.readError();
+            const errorBytes = await process.readErrorBytes();
+            expect(error1.trim()).toBe('error message');
+            expect(error1).toBe(error2);
+            expect(new TextDecoder().decode(errorBytes).trim()).toBe('error message');
+        });
+        it('should handle different write data types', async () => {
+            const process1 = await spawnCommand('cat');
+            await process1.write(toReadableStream(encodeUtf8('stream\n')));
+            expect(await process1.readOutput()).toBe('stream\n');
+            const process2 = await spawnCommand('cat');
+            await process2.write(encodeUtf8('bytes\n'));
+            expect(await process2.readOutput()).toBe('bytes\n');
+            const process3 = await spawnCommand('cat');
+            await process3.write('string\n');
+            expect(await process3.readOutput()).toBe('string\n');
+        });
+        it('should handle background writes and error propagation', async () => {
+            const process = await spawnCommand('cat');
+            process.writeInBackground('test data');
+            const result = await process.waitRead('string');
+            expect(result.output).toBe('test data');
+        });
+        it('should handle errors in writeInBackground', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 0']);
+            await process.writable.close();
+            process.writeInBackground('this should fail');
+        });
+        it('should handle non-zero exit code with empty stderr', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 1']);
+            await expect(process.wait()).rejects.toThrow('Process exited with code 1 and signal null.');
+        });
+        it('should support manual handleNonZeroExitCode', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 1']);
+            process.handleNonZeroExitCode();
+            await expect(process.wait()).rejects.toThrow();
+        });
+        it('should handle errors when reading error text in nonZeroExitCodeError', async () => {
+            // Mock TextDecoder to throw
+            const originalTextDecoder = global.TextDecoder;
+            global.TextDecoder = vi.fn().mockImplementation(() => ({
+                decode: () => { throw new Error('mock error'); },
+            }));
+            try {
+                const process = await spawnCommand('sh', ['-c', 'exit 1']);
+                await expect(process.wait()).rejects.toThrow('Process exited with code 1 and signal null.');
+            }
+            finally {
+                global.TextDecoder = originalTextDecoder;
+            }
+        });
+        it('should support passing options as second argument', async () => {
+            const process = await spawnCommand('sh', { arguments: ['-c', 'exit 0'] });
+            const result = await process.wait();
+            expect(result.code).toBe(0);
+        });
+        it('should support separate args and options', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 0'], { workingDirectory: '.' });
+            const result = await process.wait();
+            expect(result.code).toBe(0);
+        });
+        it('should handle explicit undefined options', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 0'], undefined);
+            const result = await process.wait();
+            expect(result.code).toBe(0);
+        });
+        it('should wait without options', async () => {
+            const process = await spawnCommand('sh', ['-c', 'exit 0']);
+            const result = await process.wait(undefined);
+            expect(result.code).toBe(0);
+        });
+        it('should handle command only', async () => {
+            const process = await spawnCommand('ls');
+            const result = await process.wait();
+            expect(result.code).toBe(0);
+        });
+    });
+    describe('spawnWaitCommand', () => {
+        it('should wait for command and return result', async () => {
+            const result = await spawnWaitCommand('sh', ['-c', 'exit 0']);
+            expect(result.code).toBe(0);
+        });
+        it('should throw on error by default', async () => {
+            await expect(spawnWaitCommand('sh', ['-c', 'exit 1'])).rejects.toThrow();
+        });
+        it('should support separate args and options', async () => {
+            const result = await spawnWaitCommand('sh', ['-c', 'exit 0'], { workingDirectory: '.' });
+            expect(result.code).toBe(0);
+        });
+        it('should support passing options directly', async () => {
+            const result = await spawnWaitCommand('sh', { arguments: ['-c', 'exit 0'] });
+            expect(result.code).toBe(0);
+        });
+        it('should support command only', async () => {
+            const result = await spawnWaitCommand('ls');
+            expect(result.code).toBe(0);
+        });
+        it('should handle explicit undefined options', async () => {
+            const result = await spawnWaitCommand('sh', ['-c', 'exit 0'], undefined);
+            expect(result.code).toBe(0);
+        });
+        it('should NOT throw on error if throwOnNonZeroExitCode is false', async () => {
+            const result = await spawnWaitCommand('sh', ['-c', 'exit 1'], { throwOnNonZeroExitCode: false });
+            expect(result.code).toBe(1);
+        });
+    });
+    describe('spawnWaitReadCommand', () => {
+        it('should wait and read output', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', ['-c', 'echo "test"']);
+            expect(result.output.trim()).toBe('test');
+        });
+        it('should read binary output', async () => {
+            const result = await spawnWaitReadCommand('binary', 'sh', ['-c', 'echo "test"']);
+            expect(result.output).toBeInstanceOf(Uint8Array);
+        });
+        it('should include error in exception', async () => {
+            await expect(spawnWaitReadCommand('string', 'sh', ['-c', 'echo "fail" >&2; exit 1'])).rejects.toThrow('fail');
+        });
+        it('should support options object', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', { arguments: ['-c', 'echo "test"'] });
+            expect(result.output.trim()).toBe('test');
+        });
+        it('should support separate args and options', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', ['-c', 'echo "test"'], { workingDirectory: '.' });
+            expect(result.output.trim()).toBe('test');
+        });
+        it('should support command only', async () => {
+            const result = await spawnWaitReadCommand('string', 'ls');
+            expect(result.code).toBe(0);
+        });
+        it('should NOT throw on error if throwOnNonZeroExitCode is false', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', ['-c', 'echo "fail" >&2; exit 1'], { throwOnNonZeroExitCode: false });
+            expect(result.code).toBe(1);
+            expect(result.error.trim()).toBe('fail');
+        });
+        it('should handle explicit undefined options', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', ['-c', 'echo "test"'], undefined);
+            expect(result.output.trim()).toBe('test');
+        });
+        it('should wait and read binary output without options', async () => {
+            const result = await spawnWaitReadCommand('binary', 'sh', ['-c', 'echo "test"']);
+            expect(result.output).toBeInstanceOf(Uint8Array);
+        });
+        it('should wait and read with explicit undefined options', async () => {
+            const result = await spawnWaitReadCommand('string', 'sh', ['-c', 'echo "test"'], undefined);
+            expect(result.output.trim()).toBe('test');
+        });
+    });
+});

package/renderer/d2.js

@@ -51,18 +51,7 @@ export async function renderD2(source, options) {
         args.push('--scale', options.scale.toString());
     }
     const process = await spawnCommand('d2', args);
-    const [{ code, output, error }] = await Promise.all([
-        process.waitRead('binary', { throwOnNonZeroExitCode: false }),
-        process.write(source),
-    ]);
-    const errorString = decodeText(error);
-    if (code !== 0) {
-        throw new Error(`
-D2 rendering failed with exit code ${code}.
-
-Error Output:
-${errorString}
-`.trim());
-    }
-    return output;
+    process.writeInBackground(source);
+    const result = await process.waitRead('binary');
+    return result.output;
 }

package/renderer/graphviz.js

@@ -41,18 +41,7 @@ export async function renderGraphviz(source, options) {
         args.push(`-q${level}`);
     }
     const process = await spawnCommand(engine, args);
-    const [{ code, output, error }] = await Promise.all([
-        process.waitRead('binary', { throwOnNonZeroExitCode: false }),
-        process.write(source),
-    ]);
-    const errorString = decodeText(error);
-    if (code !== 0) {
-        throw new Error(`
-Graphviz rendering failed with exit code ${code}.
-
-Error Output:
-${errorString}
-`.trim());
-    }
-    return output;
+    process.writeInBackground(source);
+    const result = await process.waitRead('binary');
+    return result.output;
 }

package/renderer/tests/renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/renderer/tests/renderer.test.js

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest';
+import { renderD2 } from '../d2.js';
+import { renderGraphviz } from '../graphviz.js';
+import { renderTypst } from '../typst.js';
+describe('renderer', () => {
+    describe('renderGraphviz', () => {
+        it('should render a simple graph with options', async () => {
+            const source = 'graph { a -- b }';
+            const result = await renderGraphviz(source, {
+                format: 'svg',
+                engine: 'dot',
+                graphAttributes: { rankdir: 'LR' },
+                nodeAttributes: { color: 'red' },
+                edgeAttributes: { style: 'dashed' },
+                scale: 2,
+                quiet: true,
+            });
+            const svg = new TextDecoder().decode(result);
+            expect(svg).toContain('<svg');
+            expect(svg).toContain('stroke="red"');
+            expect(svg).toContain('stroke-dasharray');
+        });
+        it('should throw on invalid graphviz source', async () => {
+            const source = 'invalid graph {';
+            await expect(renderGraphviz(source)).rejects.toThrow();
+        });
+    });
+    describe('renderD2', () => {
+        it('should render a simple d2 diagram with options', async () => {
+            const source = 'x -> y';
+            const result = await renderD2(source, {
+                format: 'svg',
+                layout: 'dagre',
+                theme: 1,
+                darkTheme: 200,
+                pad: 20,
+                sketch: true,
+                center: true,
+                animateInterval: 1000,
+                noXmlTag: true,
+                salt: 'test',
+                omitVersion: true,
+                target: '*',
+                scale: 0.5,
+            });
+            const svg = new TextDecoder().decode(result);
+            expect(svg).toContain('<svg');
+        });
+        it('should throw on invalid d2 source', async () => {
+            const source = 'invalid {';
+            await expect(renderD2(source)).rejects.toThrow();
+        });
+    });
+    describe('renderTypst', () => {
+        it('should render a simple typst document with options', async () => {
+            const source = 'Hello World';
+            const result = await renderTypst(source, {
+                format: 'svg',
+                ppi: 300,
+                pages: ['1', { from: 1, to: 1 }],
+                ignoreSystemFonts: true,
+                creationTimestamp: Date.now(),
+                root: '/',
+                fontPaths: ['/tmp'],
+                pdfStandard: '1.7',
+            });
+            const svg = new TextDecoder().decode(result);
+            expect(svg).toContain('<svg');
+            expect(svg).toContain('typst-text');
+        });
+        it('should render to docx (via pandoc) with options', async () => {
+            const source = 'Hello World';
+            // pandoc --from typst --to docx --output - -
+            const result = await renderTypst(source, {
+                format: 'docx',
+                docxReferenceFile: undefined, // Testing the branch
+            });
+            expect(result).toBeInstanceOf(Uint8Array);
+            // Docx is a zip file, it should start with PK
+            expect(result[0]).toBe(0x50); // P
+            expect(result[1]).toBe(0x4B); // K
+        });
+        it('should throw on invalid typst source', async () => {
+            const source = '#invalid_func()';
+            await expect(renderTypst(source)).rejects.toThrow();
+        });
+    });
+});

package/renderer/typst.d.ts

@@ -43,6 +43,11 @@ export type TypstRenderOptions = {
      * One (or multiple comma-separated) PDF standards that Typst will enforce conformance with.
      */
     pdfStandard?: LiteralUnion<'1.4' | '1.5' | '1.6' | '1.7' | '2.0' | 'a-1b' | 'a-1a' | 'a-2b' | 'a-2u' | 'a-2a' | 'a-3b' | 'a-3u' | 'a-3a' | 'a-4' | 'a-4f' | 'a-4e' | 'ua-1', string>;
+    /**
+     * A reference file to use when rendering to docx format. This allows customizing styles, fonts, etc. in the generated docx file. The file should be a valid docx file that serves as a template for the output.
+     * The reference file can be generated with `pandoc --print-default-data-file reference.docx`
+     */
+    docxReferenceFile?: string;
 };
 /**
  * Renders Typst source code to a file in the specified format.

package/renderer/typst.js

@@ -14,10 +14,9 @@ import { isDefined, isNumber, isString } from '../utils/type-guards.js';
 export async function renderTypst(source, options) {
     const format = options?.format ?? 'pdf';
     const command = (format == 'docx') ? 'pandoc' : 'typst';
-    let args = (format == 'docx')
-        ? ['--from', 'typst', '--to', 'docx', '--output']
-        : ['compile', '--format', format];
+    let args = [];
     if (command == 'typst') {
+        args = ['compile', '--format', format];
         if (isDefined(options?.root)) {
             args.push('--root', options.root);
         }
@@ -44,19 +43,17 @@ export async function renderTypst(source, options) {
                 : `${page.from ?? ''}-${page.to ?? ''}`);
             args.push('--pages', pageParts.join(','));
         }
+        args.push('-', '-');
     }
-    args.push('-', '-');
-    const process = await spawnCommand(command, args);
-    const [{ code, output, error }] = await Promise.all([
-        process.waitRead('binary', { throwOnNonZeroExitCode: false }),
-        process.write(source),
-    ]);
-    const errorString = decodeText(error);
-    if (code !== 0) {
-        throw new Error(`
-Typst compilation failed with exit code ${code}.\n
-Error Output:\n${errorString}
-`.trim());
+    else if (command == 'pandoc') {
+        args = ['--from', 'typst', '--to', 'docx'];
+        if (isDefined(options?.docxReferenceFile)) {
+            args.push('--reference-doc', options.docxReferenceFile);
+        }
+        args.push('--output', '-', '-');
     }
-    return output;
+    const process = await spawnCommand(command, args);
+    process.writeInBackground(source);
+    const result = await process.waitRead('binary');
+    return result.output;
 }

package/test5.js

@@ -1,61 +1,11 @@
 import './polyfills.js';
-import { buildPrompts, orderedList } from './ai/index.js';
-import { fewShotPrompt } from './ai/prompts/steering.js';
 import { Application } from './application/application.js';
 import { provideModule, provideSignalHandler } from './application/index.js';
 import { PrettyPrintLogFormatter } from './logger/index.js';
 import { provideConsoleLogTransport } from './logger/transports/console.js';
+import { mergePdfs } from './pdf/utils.js';
 async function main(_cancellationSignal) {
-    const prompt = buildPrompts({
-        baseSystemInstructions: { Role: 'You are a helpful assistant.' },
-        baseUserInstructions: 'Please process the following data.',
-        additionalSystemInstructions: 'Make sure to follow the user instructions carefully.',
-        additionalUserInstructions: [
-            'The data is in JSON format.',
-            fewShotPrompt([
-                {
-                    input: { a: 1, b: 2 },
-                    output: 3,
-                    reason: 'This is a positive example showing that the function should add the two numbers.',
-                },
-                {
-                    input: { a: 1, b: 2 },
-                    output: 4,
-                    isNegative: true,
-                    reason: 'This is a negative example showing that the function should NOT return 4 for these inputs.',
-                },
-            ]),
-            {
-                Foo: {
-                    Bar: 'This is a nested instruction example.',
-                    Baz: {
-                        Qux: 'Make sure to handle nested instructions properly.',
-                        Bux: orderedList('This is an ordered list of instructions', [
-                            'First instruction',
-                            'Second instruction',
-                            'Third instruction',
-                        ]),
-                    },
-                },
-            },
-        ],
-        data: {
-            context: {
-                task: 'Our favorite hikes together',
-                location: 'Boulder',
-                season: 'spring_2025',
-            },
-            friends: ['ana', 'luis', 'sam'],
-            hikes: [
-                { id: 1, name: 'Blue Lake Trail', distanceKm: 7.5, elevationGain: 320, companion: 'ana', wasSunny: true },
-                { id: 2, name: 'Ridge Overlook', distanceKm: 9.2, elevationGain: 540, companion: 'luis', wasSunny: false },
-                { id: 3, name: 'Wildflower Loop', distanceKm: 5.1, elevationGain: 180, companion: 'sam', wasSunny: true },
-            ],
-        },
-    });
-    console.log(prompt.systemPrompt[0].text);
-    console.log();
-    console.log(prompt.userPrompt[0].text);
+    await mergePdfs(['asd', 'bsa']);
 }
 Application.run('Test', [
     provideConsoleLogTransport(PrettyPrintLogFormatter),