@tstdl/base 0.93.128 → 0.93.129

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.129",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"

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,15 +51,15 @@ 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, spawnWaitReadCommand } 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 stack = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+        const [sourceFile] = await getPdfSourceFiles([file], stack);
+        const process = await spawnCommand('qpdf', ['--show-npages', sourceFile]);
         const { code } = await process.wait();
         if (code != 0) {
             const errorOutput = await process.readError();
@@ -78,14 +78,19 @@ 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);
+        const processResult = await spawnWaitReadCommand('string', 'qpdf', ['--empty', '--pages', sourceFile, pagesString, '--', resultFile.path]);
+        if (processResult.code != 0) {
+            await resultFile.dispose();
+            throw new Error(processResult.error.trim());
+        }
+        return resultFile;
     }
     catch (e_2) {
         env_2.error = e_2;
@@ -97,14 +102,26 @@ 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];
+        });
+        const processResult = await spawnWaitReadCommand('string', 'qpdf', ['--empty', '--pages', ...sourceArguments, '--', resultFile.path]);
+        if (processResult.code != 0) {
+            throw new Error(processResult.error);
+        }
+        return resultFile;
     }
     catch (e_3) {
         env_3.error = e_3;
@@ -116,22 +133,32 @@ 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 [baseFilePath, overlayFilePath] = await getPdfSourceFiles([base, overlay], stack);
+        const resultFile = TemporaryFile.create();
+        stack.use(resultFile);
+        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);
+        const processResult = await spawnWaitReadCommand('string', 'qpdf', args);
+        if (processResult.code != 0) {
+            throw new Error(processResult.error);
+        }
+        return resultFile;
+    }
+    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;
     }
 }
 /**
@@ -151,3 +178,35 @@ export async function pdfToImage(file, page, size, format) {
     }
     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/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);
         }
@@ -45,14 +44,19 @@ export async function renderTypst(source, options) {
             args.push('--pages', pageParts.join(','));
         }
     }
-    args.push('-', '-');
+    else if (command == 'pandoc') {
+        args = ['--from', 'typst', '--to', 'docx', '--output', '-'];
+        if (isDefined(options?.docxReferenceFile)) {
+            args.push('--reference-doc', options.docxReferenceFile);
+        }
+    }
     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) {
+    if (code != 0) {
         throw new Error(`
 Typst compilation failed with exit code ${code}.\n
 Error Output:\n${errorString}