From 3ef0d8629067bbbd352fda4ff96c0477314e3d7c Mon Sep 17 00:00:00 2001 From: Sebastian Frank Date: Sat, 14 Nov 2026 13:38:40 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20types(hooks):=20=E2=80=A6Async-Zwil?= =?UTF-8?q?linge,=20context.after/enqueue,=20TaskConfig?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `http.fetchAsync`, `http.fetchStreamAsync`, `fs.readFileAsync`, `fs.writeFileAsync`, `smtp.sendMailAsync`, `exec.commandAsync`, `image.filterAsync`, `pdf.fromHTMLAsync`, `pdf.cpuAsync` — gespiegelte Signaturen der jeweiligen sync-Methode (ein Go-Kern, zwei Registrierungen). - `HookContext.after(fn)` und `HookContext.enqueue(task, data?)`, inklusive Semantik in den Doc-Kommentaren (nach der Antwort, 2 s; durable, Name wird geprüft, Payload ≤ 64 KB). - `TaskConfig` (Spiegel von task.schema.json) und `HookContext.task`; im Task-Skript ist der Payload die globale Variable `data`. --- index.d.ts | 208 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 207 insertions(+), 1 deletion(-) diff --git a/index.d.ts b/index.d.ts index 51f59ce..8be8e7b 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1020,6 +1020,30 @@ declare global { engine?: "" | "goja" | "v8" } + /** + * Konfigurierte Arbeitseinheit (`tasks:` im Projekt), gestartet über + * `context.enqueue(name, data?)` — kein cron, anders als ein Job. + * Im Task-Skript: `context.task` (diese Konfiguration) und die globale + * Variable `data` (der Payload aus enqueue). + */ + interface TaskConfig { + /** verbindlicher Task-Name im YAML (nicht der Dateiname) */ + name: string + type: "javascript" + /** Pfad relativ zum Projektverzeichnis */ + file?: string + timeout?: number | string + /** überschreibt die Projekt-Engine für diesen Task */ + engine?: "" | "goja" | "v8" + /** maximal gleichzeitig laufende Instanzen (pro Prozess) */ + concurrency?: number + /** Wiederholungen nach einem Fehler */ + retries?: number + backoffBase?: number | string + backoffMax?: number | string + meta?: any + } + interface JobData { /** * job is object of job config @@ -1354,6 +1378,26 @@ declare global { html?: string attach?: string | string[] }): void + + /** + * Wie `sendMail`, aber als Promise (Mailserver-Latenz blockiert den + * Hook-Lauf nicht). + */ + sendMailAsync(options: { + host?: string + username?: string + password?: string + to: string | string[] + cc?: string | string[] + bcc?: string | string[] + subject?: string + from: string + fromName?: string + replyTo?: string + plain?: string + html?: string + attach?: string | string[] + }): Promise } interface FsPackage { @@ -1384,6 +1428,21 @@ declare global { */ writeFile(path: string, data: string | any): null + /** + * Wie `readFile`, aber als Promise. + */ + readFileAsync( + path: string, + options?: { + bytes: boolean // if true return []byte instead of string + } + ): Promise + + /** + * Wie `writeFile`, aber als Promise. + */ + writeFileAsync(path: string, data: string | any): Promise + /** * stat file or directory * @@ -1474,6 +1533,31 @@ declare global { } } + /** + * Wie `fetch`, aber als Promise (eigener Eventloop-Slot, blockiert den + * Hook-Lauf nicht). Signatur und Ergebnis sind identisch. + */ + fetchAsync( + url: string, + options?: { + method?: string + headers?: { [key: string]: string } + body?: string + /** timeout in seconds (default 10) */ + timeout?: number + } + ): Promise<{ + status: number + statusText: string + headers: { [key: string]: string } + trailer: { [key: string]: string } + url: string + body: { + text(): string + json(): any + } + }> + /** * streaming http request — response body is NOT read into memory. * Use body.read() to read line by line (ideal for SSE / newline-delimited @@ -1502,6 +1586,31 @@ declare global { close(): void } } + + /** + * Wie `fetchStream`, aber das Reader-Objekt kommt als Promise. + * `read()` bleibt synchron und liest die nächste Zeile. + */ + fetchStreamAsync( + url: string, + options?: { + method?: string + headers?: { [key: string]: string } + body?: string + /** timeout in seconds (default 0 = no timeout, hook timeout controls duration) */ + timeout?: number + } + ): Promise<{ + status: number + statusText: string + headers: { [key: string]: string } + body: { + /** returns the next line as string, or null at EOF */ + read(): string | null + /** explicitly closes the response body (auto-closed at EOF) */ + close(): void + } + }> } interface DebugPackage { @@ -1679,6 +1788,11 @@ declare global { targetFile: string, filters: ImageFilterParams[] ): void + + /** + * Wie `filter`, aber als Promise (CPU-/IO-lastig). + */ + filterAsync(sourceFile: string, targetFile: string, filters: ImageFilterParams[]): Promise } interface XmlPackage { @@ -1830,10 +1944,42 @@ declare global { mode?: "text" | "image" | "pdf" bytes?: any // []byte of watermark image file?: string // file for pdf watermark - text?: string // text for text watermark + text?: string rotation?: number } ): any + + /** + * Wie `fromHTML`, aber als Promise (PDF-Rendering ist langsam). + */ + fromHTMLAsync( + html: string, + options?: { + copies?: number + dpi?: number + grayscale?: boolean + imageDpi?: number + imageQuality?: number + lowQuality?: boolean + marginBottom?: number + marginLeft?: number + marginRight?: number + marginTop?: number + orientation?: "portrait" | "landscape" + pageSize?: string + noPdfCompression?: boolean + [key: string]: any + } + ): Promise + + /** + * Wie `cpu`, aber als Promise. + */ + cpuAsync( + command: "watermark" | "stamp" | "merge" | "rotate" | "create", + pdfData: any | any[], + options?: { [key: string]: any } + ): Promise } /** Byte encodings shared by the crypto/base64 hook helpers. */ @@ -2275,6 +2421,44 @@ declare global { ? { output: string; exitCode: number } : { stdout: string; stderr: string; exitCode: number } : string + + /** + * Wie `command`, aber als Promise. Externe Prozesse können lange + * laufen; der Hook-Lauf wartet nicht blockierend. + */ + commandAsync( + cmd: string, + options?: { + args?: string[] + stdin?: string + dir?: string + env?: string[] + timeout?: number + returnObject?: boolean + combineOutput?: boolean + } + ): Promise + + commandAsync< + T extends { + args?: string[] + stdin?: string + dir?: string + env?: string[] + timeout?: number + returnObject?: boolean + combineOutput?: boolean + }, + >( + cmd: string, + options: T + ): Promise< + T["returnObject"] extends true + ? T["combineOutput"] extends true + ? { output: string; exitCode: number } + : { stdout: string; stderr: string; exitCode: number } + : string + > } /** RFC 4648 encoding variant shared by the base64 helpers. */ @@ -2553,6 +2737,28 @@ declare global { export interface HookContext extends GetHookData, GetHookGetOnlyData, PostHookData, JobData { + /** + * Task-Konfiguration, wenn der Code als Task läuft (`tasks:`). + * Der Payload aus `context.enqueue(name, data)` steht im Skript als + * globale Variable `data`. + */ + task?: TaskConfig + + /** + * Registriert eine Funktion, die **nach** dem Schreiben der + * HTTP-Antwort läuft (max. 2 s). Fehler ändern die Antwort nie. + * Nur in HTTP-Hooks verfügbar. + */ + after(fn: () => void | Promise): void + + /** + * Reiht einen konfigurierten Task ein (durable, eigener Lauf). + * Der Name wird gegen `tasks:` geprüft (fail fast); `data` muss + * JSON-serialisierbar und begrenzt sein. + */ + enqueue(task: string, data?: any): void + + request(): { method: string remoteAddr: string