✨ types(hooks): …Async-Zwillinge, context.after/enqueue, TaskConfig
continuous-integration/drone/push Build is passing

- `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`.
This commit is contained in:
apairon committed 2026-11-14 13:38:40 +00:00
1 parent c3106e7e1e
commit 3ef0d86290
1 file changed
+207 -1
Vendored
+207 -1
View File
@@ -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<void>
}
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<string | any>
/**
* Wie `writeFile`, aber als Promise.
*/
writeFileAsync(path: string, data: string | any): Promise<null>
/**
* 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<void>
}
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<any>
/**
* Wie `cpu`, aber als Promise.
*/
cpuAsync(
command: "watermark" | "stamp" | "merge" | "rotate" | "create",
pdfData: any | any[],
options?: { [key: string]: any }
): Promise<any>
}
/** 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<string>
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>): 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