@beignet/core/dist/tasks/index.d.ts

Core framework primitives for Beignet

import type { StandardSchemaV1 } from "@standard-schema/spec";
import type { TracingPort } from "../tracing/index.js";
/**
 * Any Standard Schema compatible validator.
 */
export type StandardSchema = StandardSchemaV1<unknown, unknown>;
/**
 * Value or promise of that value.
 */
export type MaybePromise<T> = T | Promise<T>;
/**
 * Infer the parsed output type from a Standard Schema.
 */
export type InferSchemaOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
/**
 * Operational task definition created by `defineTask(...)`.
 */
export interface TaskDef<Name extends string = string, Input extends StandardSchema = StandardSchema, Ctx = unknown, Output = unknown> {
    /**
     * Discriminator for task definitions.
     */
    readonly kind: "task";
    /**
     * Stable task name used by CLIs and operational runners.
     */
    readonly name: Name;
    /**
     * Standard Schema input validator.
     */
    readonly input: Input;
    /**
     * Optional human-readable description for docs and tooling.
     */
    readonly description?: string;
    /**
     * Handle a parsed task input.
     */
    handle(args: TaskHandleArgs<TaskDef<Name, Input, Ctx, Output>, Ctx>): MaybePromise<Output>;
}
/**
 * Infer the parsed input type for an operational task.
 */
export type InferTaskInput<T extends TaskDef> = T["input"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
/**
 * Infer the result type for an operational task.
 */
export type InferTaskOutput<T extends TaskDef> = T extends TaskDef<string, StandardSchema, unknown, infer Output> ? Awaited<Output> : never;
/**
 * Arguments passed to a task handler.
 */
export interface TaskHandleArgs<T extends TaskDef, Ctx> {
    /**
     * Task definition being handled.
     */
    task: T;
    /**
     * Parsed task input.
     */
    input: InferTaskInput<T>;
    /** Handler context. */
    ctx: Ctx;
}
/**
 * Options for `defineTask(...)`.
 */
export interface DefineTaskOptions<Name extends string, Input extends StandardSchema, Ctx, Output> {
    /**
     * Standard Schema input validator.
     */
    input: Input;
    /**
     * Optional human-readable description for docs and tooling.
     */
    description?: string;
    /**
     * Handle a parsed task input.
     */
    handle(args: TaskHandleArgs<TaskDef<Name, Input, Ctx, Output>, Ctx>): MaybePromise<Output>;
}
/**
 * Options for one task run.
 */
export interface RunTaskOptions<Ctx> {
    /**
     * Raw task input. It is parsed with the task's Standard Schema before the
     * handler runs.
     */
    input: unknown;
    /** Handler context or factory resolved inside the task span. */
    ctx: Ctx | (() => MaybePromise<Ctx>);
    /** Runtime tracing port used before a lazy context factory runs. */
    tracing?: TracingPort;
}
/**
 * Arguments `beignet task run` passes to the app's `createTaskContext` and
 * `stopTaskContext` exports in `server/tasks.ts`.
 */
export interface TaskRunContextArgs<T extends TaskDef = TaskDef> {
    /**
     * Task definition being run.
     */
    task: T;
    /**
     * Stable task name being run.
     */
    taskName: string;
    /**
     * Schema-parsed task input.
     */
    input: unknown;
    /**
     * Tenant id or slug from `--tenant`, resolved by the app.
     */
    tenant?: string;
}
/**
 * Context-bound operational task helper factory.
 */
export interface Tasks<Ctx> {
    /**
     * Define a task with the bound context type.
     */
    defineTask<Name extends string, Input extends StandardSchema, Output = unknown>(name: Name, options: DefineTaskOptions<Name, Input, Ctx, Output>): TaskDef<Name, Input, Ctx, Output>;
}
/**
 * Error thrown when task input validation fails.
 */
export declare class TaskValidationError extends Error {
    /**
     * Raw Standard Schema validation issues.
     */
    readonly issues: readonly StandardSchemaV1.Issue[];
    constructor(args: {
        name: string;
        issues: readonly StandardSchemaV1.Issue[];
    });
}
/**
 * Validate and parse a task input with the task's Standard Schema.
 */
export declare function parseTaskInput<T extends TaskDef>(task: T, input: unknown): Promise<InferTaskInput<T>>;
/**
 * Parse input and run an operational task.
 */
export declare function runTask<T extends TaskDef<string, StandardSchema, Ctx>, Ctx>(task: T, options: RunTaskOptions<Ctx>): Promise<InferTaskOutput<T>>;
/**
 * Define a task registry while preserving tuple inference.
 */
export declare function defineTasks<const Defs extends readonly TaskDef[]>(tasks: Defs): Defs;
/**
 * Create task helper methods bound to an application context type.
 *
 * Call it once in `lib/tasks.ts`:
 *
 * ```ts
 * export const { defineTask } = createTasks<AppContext>();
 * ```
 */
export declare function createTasks<Ctx>(): Tasks<Ctx>;
//# sourceMappingURL=index.d.ts.map