@tstdl/base 0.93.67 → 0.93.69

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

@@ -1,17 +1,28 @@
+/** Represents a temporary file on the filesystem which is automatically deleted on disposal. */
 export declare class TemporaryFile implements AsyncDisposable {
     #private;
     get path(): string;
-    static create(): TemporaryFile;
+    static create(extension?: string): TemporaryFile;
     /**
      * Use an existing file as a temporary file which gets deleted on disposal.
      * @param path path to adopt
      */
     static adopt(path: string): TemporaryFile;
-    static from(content: string | Uint8Array | ReadableStream<Uint8Array>): Promise<TemporaryFile>;
+    static from(content: string | Uint8Array | ReadableStream<Uint8Array>, extension?: string): Promise<TemporaryFile>;
+    /**
+     * Prevents the temporary file from being deleted on disposal.
+     */
+    keep(): void;
     read(): Promise<Uint8Array>;
     readText(): Promise<string>;
     readStream(): ReadableStream<Uint8Array>;
     write(content: string | Uint8Array | ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * Moves the file to a new location.
+     * @param path The new path for the file.
+     * @param keep If true, prevents the file from being deleted on disposal.
+     */
+    moveTo(path: string, keep?: boolean): Promise<void>;
     delete(): Promise<void>;
     size(): Promise<number>;
     [Symbol.asyncDispose](): Promise<void>;

package/file/server/temporary-file.js

@@ -1,14 +1,21 @@
 import { createReadStream } from 'node:fs';
-import { readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { Readable } from 'node:stream';
+import { isDefined } from '../../utils/type-guards.js';
+/** Represents a temporary file on the filesystem which is automatically deleted on disposal. */
 export class TemporaryFile {
     #path = `${tmpdir()}/${crypto.randomUUID()}`;
+    #keep = false;
     get path() {
         return this.#path;
     }
-    static create() {
-        return new TemporaryFile();
+    static create(extension) {
+        const file = new TemporaryFile();
+        if (isDefined(extension)) {
+            file.#path += extension.startsWith('.') ? extension : `.${extension}`;
+        }
+        return file;
     }
     /**
      * Use an existing file as a temporary file which gets deleted on disposal.
@@ -19,16 +26,22 @@ export class TemporaryFile {
         file.#path = path;
         return file;
     }
-    static async from(content) {
-        const file = new TemporaryFile();
+    static async from(content, extension) {
+        const file = TemporaryFile.create(extension);
         await file.write(content);
         return file;
     }
+    /**
+     * Prevents the temporary file from being deleted on disposal.
+     */
+    keep() {
+        this.#keep = true;
+    }
     async read() {
-        return readFile(this.#path);
+        return await readFile(this.#path);
     }
     async readText() {
-        return readFile(this.#path, { encoding: 'utf8' });
+        return await readFile(this.#path, { encoding: 'utf8' });
     }
     readStream() {
         const stream = createReadStream(this.#path);
@@ -37,6 +50,18 @@ export class TemporaryFile {
     async write(content) {
         await writeFile(this.#path, content);
     }
+    /**
+     * Moves the file to a new location.
+     * @param path The new path for the file.
+     * @param keep If true, prevents the file from being deleted on disposal.
+     */
+    async moveTo(path, keep) {
+        await rename(this.#path, path);
+        this.#path = path;
+        if (keep) {
+            this.keep();
+        }
+    }
     async delete() {
         await unlink(this.#path);
     }
@@ -45,6 +70,9 @@ export class TemporaryFile {
         return result.size;
     }
     async [Symbol.asyncDispose]() {
+        if (this.#keep) {
+            return;
+        }
         try {
             await this.delete();
         }

package/latex/index.d.ts

@@ -0,0 +1 @@
+export * from './render.js';

package/latex/index.js

@@ -0,0 +1 @@
+export * from './render.js';

package/latex/render.d.ts

@@ -0,0 +1,23 @@
+import { TemporaryFile } from '../file/server/temporary-file.js';
+export type LatexRenderOptions = {
+    /**
+     * The LaTeX engine to use for rendering the document.
+     * @default 'lualatex'
+     */
+    engine?: 'pdflatex' | 'lualatex' | 'xelatex';
+};
+/**
+ * Renders LaTeX source code to a PDF file.
+ *
+ * ## WARNING
+ * **This function should not be used with untrusted LaTeX source, as it can lead to arbitrary code execution on the system.**
+ *
+ * Requires latexmk and LuaTeX to be installed on the system.
+ *
+ * **Minimal recommendation:**
+ * - **Arch Linux:** texlive-binextra texlive-luatex texlive-latexrecommended texlive-fontsrecommended
+ * @param source The LaTeX source code to render
+ * @param options Rendering options
+ * @returns A TemporaryFile representing the generated PDF
+ */
+export declare function renderLatex(source: string, options?: LatexRenderOptions): Promise<TemporaryFile>;

package/latex/render.js

@@ -0,0 +1,102 @@
+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 { TemporaryFile } from '../file/server/temporary-file.js';
+import { spawnWaitCommand, spawnWaitReadCommand } from '../process/spawn.js';
+import { withTimeout } from '../utils/timing.js';
+import { tryIgnoreAsync } from '../utils/try-ignore.js';
+const engineMapping = {
+    pdflatex: '-pdflatex',
+    lualatex: '-pdflua',
+    xelatex: '-pdfxe',
+};
+/**
+ * Renders LaTeX source code to a PDF file.
+ *
+ * ## WARNING
+ * **This function should not be used with untrusted LaTeX source, as it can lead to arbitrary code execution on the system.**
+ *
+ * Requires latexmk and LuaTeX to be installed on the system.
+ *
+ * **Minimal recommendation:**
+ * - **Arch Linux:** texlive-binextra texlive-luatex texlive-latexrecommended texlive-fontsrecommended
+ * @param source The LaTeX source code to render
+ * @param options Rendering options
+ * @returns A TemporaryFile representing the generated PDF
+ */
+export async function renderLatex(source, options) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const latexFile = __addDisposableResource(env_1, await TemporaryFile.from(source, '.tex'), true);
+        const engineFlag = engineMapping[options?.engine ?? 'lualatex'];
+        const { code, output, error } = await spawnWaitReadCommand('string', 'latexmk', ['-interaction=nonstopmode', engineFlag, '-cd', latexFile.path], { throwOnNonZeroExitCode: false });
+        await tryIgnoreAsync(async () => await withTimeout(1000, spawnWaitCommand('latexmk', ['-c', '-cd', engineFlag, latexFile.path])));
+        if (code !== 0) {
+            throw new Error(`
+LaTeX compilation failed with exit code ${code}.\n
+File: ${latexFile.path}\n
+Output:\n${output}\n
+Error Output:\n${error}
+`.trim());
+        }
+        return TemporaryFile.adopt(`${latexFile.path.slice(0, -4)}.pdf`);
+    }
+    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;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.67",
+  "version": "0.93.69",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -73,6 +73,7 @@
     "./jsx": "./jsx/index.js",
     "./key-value-store": "./key-value-store/index.js",
     "./key-value-store/postgres": "./key-value-store/postgres/index.js",
+    "./latex": "./latex/index.js",
     "./lock": "./lock/index.js",
     "./lock/postgres": "./lock/postgres/index.js",
     "./lock/web": "./lock/web/index.js",

package/pdf/utils.js

@@ -147,7 +147,7 @@ export async function pdfToImage(file, page, size, format) {
     const process = await spawnCommand('pdftocairo', ['-f', String(page), '-l', String(page), '-scale-to', String(size), '-singlefile', `-${format}`, path, '-']);
     process.handleNonZeroExitCode();
     if (isNotString(file)) {
-        process.autoWrite(file);
+        process.writeInBackground(file);
     }
     return await process.readOutputBytes();
 }

package/process/spawn.d.ts

@@ -1,22 +1,43 @@
 import type { ChildProcessWithoutNullStreams } from 'node:child_process';
-type WaitOptions = {
+import type { Record } from '../types/types.js';
+type WaitReadResultFormat = 'string' | 'binary';
+type WaitReadResultFormatType<T extends WaitReadResultFormat> = T extends 'string' ? string : Uint8Array<ArrayBuffer>;
+export type WaitOptions = {
     throwOnNonZeroExitCode?: boolean;
 };
-type ProcessResult = {
+export type WaitResult = {
     code: number | null;
     signal: string | null;
 };
+export type WaitReadResult<Format extends WaitReadResultFormat> = WaitResult & {
+    output: WaitReadResultFormatType<Format>;
+    error: WaitReadResultFormatType<Format>;
+};
+export type SpawnOptions = {
+    arguments?: string[];
+    workingDirectory?: string;
+    environment?: Record<string, string>;
+};
 export type SpawnCommandResult = TransformStream<Uint8Array, Uint8Array> & {
     process: ChildProcessWithoutNullStreams;
     stderr: ReadableStream<Uint8Array>;
     write(chunk: ReadableStream<Uint8Array> | Uint8Array | string, options?: StreamPipeOptions): Promise<void>;
-    autoWrite(chunk: ReadableStream<Uint8Array> | Uint8Array | string, options?: StreamPipeOptions): void;
+    writeInBackground(chunk: ReadableStream<Uint8Array> | Uint8Array | string, options?: StreamPipeOptions): void;
     readOutputBytes(): Promise<Uint8Array>;
     readOutput(): Promise<string>;
     readErrorBytes(): Promise<Uint8Array>;
     readError(): Promise<string>;
     handleNonZeroExitCode(): void;
-    wait(options?: WaitOptions): Promise<ProcessResult>;
+    wait(options?: WaitOptions): Promise<WaitResult>;
+    waitRead<F extends WaitReadResultFormat>(format: F, options?: WaitOptions): Promise<WaitReadResult<F>>;
 };
-export declare function spawnCommand(command: string, args?: string[]): Promise<SpawnCommandResult>;
+/** spwans a command and waits for it to complete */
+export declare function spawnWaitCommand(command: string, args?: string[], options?: SpawnOptions & WaitOptions): Promise<WaitResult>;
+export declare function spawnWaitCommand(command: string, options?: SpawnOptions & WaitOptions): Promise<WaitResult>;
+/** spwans a command, waits for it to complete and reads its output */
+export declare function spawnWaitReadCommand<F extends WaitReadResultFormat>(format: F, command: string, args?: string[], options?: SpawnOptions & WaitOptions): Promise<WaitReadResult<F>>;
+export declare function spawnWaitReadCommand<F extends WaitReadResultFormat>(format: F, command: string, options?: SpawnOptions & WaitOptions): Promise<WaitReadResult<F>>;
+/** Spawns a command as a child process. */
+export declare function spawnCommand(command: string, args?: string[], options?: SpawnOptions): Promise<SpawnCommandResult>;
+export declare function spawnCommand(command: string, options?: SpawnOptions): Promise<SpawnCommandResult>;
 export {};

package/process/spawn.js

@@ -3,11 +3,22 @@ import { LazyPromise } from '../promise/lazy-promise.js';
 import { decodeTextStream, encodeUtf8Stream } from '../utils/encoding.js';
 import { readBinaryStream, readTextStream } from '../utils/stream/stream-reader.js';
 import { toReadableStream } from '../utils/stream/to-readable-stream.js';
-import { assertNotNullOrUndefinedPass, isReadableStream, isString, isUint8Array } from '../utils/type-guards.js';
-export async function spawnCommand(command, args) {
+import { assertNotNullOrUndefinedPass, isArray, 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 process = await spawnCommand(command, args, options);
+    return await process.wait({ throwOnNonZeroExitCode: options?.throwOnNonZeroExitCode });
+}
+export async function spawnWaitReadCommand(format, command, argsOrOptions, optionsOrNothing) {
+    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [undefined, argsOrOptions];
+    const process = await spawnCommand(command, args, options);
+    return await process.waitRead(format, { throwOnNonZeroExitCode: options?.throwOnNonZeroExitCode });
+}
+export async function spawnCommand(command, argsOrOptions, optionsOrNothing) {
     const { spawn } = await dynamicImport('node:child_process');
     const { Readable, Writable } = await dynamicImport('node:stream');
-    const process = spawn(command, args, { stdio: 'pipe' });
+    const [args, options] = isArray(argsOrOptions) ? [argsOrOptions, optionsOrNothing] : [undefined, argsOrOptions];
+    const process = spawn(command, args, { stdio: 'pipe', cwd: options?.workingDirectory, env: options?.environment });
     await Promise.race([
         new Promise((resolve) => process.on('spawn', resolve)),
         new Promise((_, reject) => process.on('error', reject)),
@@ -26,7 +37,8 @@ export async function spawnCommand(command, args) {
             await toReadableStream(data).pipeThrough(encodeUtf8Stream()).pipeTo(writable, options);
         }
     }
-    function autoWrite(data, options) {
+    /** 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(() => { });
@@ -74,18 +86,31 @@ export async function spawnCommand(command, args) {
         }
         return result;
     }
+    async function waitRead(format, { throwOnNonZeroExitCode = true } = {}) {
+        const [result, output, error] = await Promise.all([
+            wait({ throwOnNonZeroExitCode }),
+            (format === 'string') ? readOutput() : readOutputBytes(),
+            (format === 'string') ? readError() : readErrorBytes(),
+        ]);
+        return {
+            ...result,
+            output: output,
+            error: error,
+        };
+    }
     return {
         process,
         readable,
         writable,
         stderr,
         write,
-        autoWrite,
+        writeInBackground,
         readOutputBytes,
         readOutput,
         readErrorBytes,
         readError,
         handleNonZeroExitCode: () => void handleNonZeroExitCode(),
         wait,
+        waitRead,
     };
 }

package/utils/try-ignore.d.ts

@@ -1,9 +1,9 @@
 import type { Logger } from '../logger/logger.js';
-export declare function tryIgnore<R>(fn: () => R): R;
+export declare function tryIgnore<R>(fn: () => R): R | undefined;
 export declare function tryIgnore<R, F>(fn: () => R, fallback: F): R | F;
-export declare function tryIgnoreAsync<R>(fn: () => Promise<R>): Promise<R>;
+export declare function tryIgnoreAsync<R>(fn: () => Promise<R>): Promise<R | undefined>;
 export declare function tryIgnoreAsync<R, F>(fn: () => Promise<R>, fallback: F): Promise<F>;
-export declare function tryIgnoreLog<R>(logger: Logger, fn: () => R): R;
+export declare function tryIgnoreLog<R>(logger: Logger, fn: () => R): R | undefined;
 export declare function tryIgnoreLog<R, F>(logger: Logger, fn: () => R, fallback: F): R | F;
-export declare function tryIgnoreLogAsync<R>(logger: Logger, fn: () => Promise<R>): Promise<R>;
+export declare function tryIgnoreLogAsync<R>(logger: Logger, fn: () => Promise<R>): Promise<R | undefined>;
 export declare function tryIgnoreLogAsync<R, F>(logger: Logger, fn: () => Promise<R>, fallback: F): Promise<F>;