alepha/dist/background/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha } from "alepha";
//#region ../../src/background/providers/BackgroundTaskProvider.d.ts
/**
 * Runs fire-and-forget work that should outlive the request that scheduled it
 * (sending a welcome email, an audit write, a webhook) without blocking the
 * response.
 *
 * On a long-lived runtime (Node, Vercel) the event loop keeps the promise
 * alive, so the only job here is to detach the task from the caller and never
 * leak an unhandled rejection. On serverless/edge runtimes that freeze the
 * isolate once the response is returned (Cloudflare Workers) the
 * {@link WorkerdBackgroundTaskProvider} variant additionally wraps the task in
 * `executionCtx.waitUntil` — call sites stay platform-agnostic and only ever
 * call {@link defer}.
 *
 * In-flight tasks are tracked and awaited on shutdown (`flush`), so graceful
 * stop, `run({ once })`, and unit tests don't silently drop work.
 */
declare class BackgroundTaskProvider {
  protected readonly alepha: Alepha;
  protected readonly log: import("alepha/logger").Logger;
  /** In-flight deferred tasks, awaited on stop. */
  protected readonly pending: Set<Promise<void>>;
  /**
   * Schedule `task` to run in the background. Returns immediately — the task is
   * detached onto a microtask, so the caller (e.g. an HTTP handler) is never
   * blocked and a synchronous throw inside `task` can't escape into it. Errors
   * are caught and logged.
   */
  defer(task: () => unknown | Promise<unknown>): void;
  /**
   * Hook for platform variants to keep the runtime alive until `promise`
   * settles. No-op on long-lived runtimes (the event loop already does). The
   * Cloudflare variant overrides this with `executionCtx.waitUntil`.
   */
  protected keepAlive(_promise: Promise<void>): void;
  /**
   * Await all in-flight tasks (best-effort). Called on `stop` so shutdown and
   * tests don't drop deferred work.
   */
  flush(): Promise<void>;
  protected readonly onStop: import("alepha").HookPrimitive<"stop">;
}
//#endregion
//#region ../../src/background/providers/WorkerdBackgroundTaskProvider.d.ts
/**
 * Cloudflare Workers variant of {@link BackgroundTaskProvider}.
 *
 * Cloudflare freezes the isolate once the response is returned, so a plain
 * fire-and-forget promise would be killed mid-flight. The platform exposes a
 * per-request `executionCtx.waitUntil(promise)` that keeps the isolate alive
 * until `promise` settles; the request entry point (generated by the Cloudflare
 * build) stashes it in the Alepha store under `cloudflare.waitUntil`.
 *
 * This is the ONE place that reads that key — call sites use
 * {@link BackgroundTaskProvider.defer} and stay platform-agnostic.
 *
 * `waitUntil` is request-scoped, so `defer()` must be called within the
 * request's async context (which is where background work is scheduled). Outside
 * a request (e.g. a cron tick) the key is absent and we fall back to the base
 * fire-and-track behaviour.
 */
declare class WorkerdBackgroundTaskProvider extends BackgroundTaskProvider {
  protected keepAlive(promise: Promise<void>): void;
}
//#endregion
//#region ../../src/background/index.d.ts
/**
 * Fire-and-forget background work that should outlive the request that
 * scheduled it, without blocking the response.
 *
 * Inject {@link BackgroundTaskProvider} and call `defer(() => …)`:
 *
 * ```ts
 * protected readonly background = $inject(BackgroundTaskProvider);
 *
 * createUser = $action({ handler: async ({ body }) => {
 *   const user = await this.users.create(body);
 *   this.background.defer(() => this.email.send(welcome(user))); // don't block
 *   return user;
 * }});
 * ```
 *
 * On Node/Vercel the event loop keeps the task alive. On Cloudflare Workers the
 * `workerd` build swaps in {@link WorkerdBackgroundTaskProvider}, which wraps
 * the task in `executionCtx.waitUntil` so the isolate isn't frozen at response
 * time — the call site is identical either way.
 *
 * @module alepha.background
 */
declare const AlephaBackground: import("alepha").Service<import("alepha").Module>;
//#endregion
export { AlephaBackground, BackgroundTaskProvider, WorkerdBackgroundTaskProvider };
//# sourceMappingURL=index.d.ts.map