@beignet/core 0.0.3 → 0.0.4

package/dist/tasks/index.d.ts

@@ -0,0 +1,139 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * 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.
+     */
+    ctx: Ctx;
+}
+/**
+ * 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

package/dist/tasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tasks/index.ts"],"names":[],"mappings":"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"}

package/dist/tasks/index.js

@@ -0,0 +1,98 @@
+/**
+ * Error thrown when task input validation fails.
+ */
+export class TaskValidationError extends Error {
+    /**
+     * Raw Standard Schema validation issues.
+     */
+    issues;
+    constructor(args) {
+        super(`Task "${args.name}" input validation failed: ${formatIssues(args.issues)}`);
+        this.name = "TaskValidationError";
+        this.issues = args.issues;
+    }
+}
+function formatPath(path) {
+    if (!path || path.length === 0)
+        return "";
+    return path
+        .map((segment) => {
+        if (typeof segment === "number")
+            return `[${segment}]`;
+        const key = String(segment);
+        return /^[A-Za-z_$][\w$]*$/.test(key)
+            ? `.${key}`
+            : `[${JSON.stringify(key)}]`;
+    })
+        .join("")
+        .replace(/^\./, "");
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = formatPath(issue.path);
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+async function parseInput(schema, input, options) {
+    const result = await schema["~standard"].validate(input);
+    if (result.issues?.length) {
+        throw new TaskValidationError({
+            name: options.name,
+            issues: result.issues,
+        });
+    }
+    return result.value;
+}
+function defineTaskImpl(name, options) {
+    return {
+        kind: "task",
+        name,
+        input: options.input,
+        description: options.description,
+        handle: options.handle,
+    };
+}
+/**
+ * Validate and parse a task input with the task's Standard Schema.
+ */
+export async function parseTaskInput(task, input) {
+    return (await parseInput(task.input, input, {
+        name: task.name,
+    }));
+}
+/**
+ * Parse input and run an operational task.
+ */
+export async function runTask(task, options) {
+    const parsed = await parseTaskInput(task, options.input);
+    return (await task.handle({
+        task,
+        input: parsed,
+        ctx: options.ctx,
+    }));
+}
+/**
+ * Define a task registry while preserving tuple inference.
+ */
+export function defineTasks(tasks) {
+    return tasks;
+}
+/**
+ * Create task helper methods bound to an application context type.
+ *
+ * Call it once in `lib/tasks.ts`:
+ *
+ * ```ts
+ * export const { defineTask } = createTasks<AppContext>();
+ * ```
+ */
+export function createTasks() {
+    return {
+        defineTask(name, options) {
+            return defineTaskImpl(name, options);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/tasks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tasks/index.ts"],"names":[],"mappings":"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"}