@pogodisco/task-runner 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./main.js";
-export * from "./utils/index.js";
+export { runSchema as runSchemaV1, defineSchema as defineSchemaV1, wrapSchema as wrapSchemaV1, } from "./v1/index.js";
+export * from "./v2/index.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export * from "./main.js";
-export * from "./utils/index.js";
+export { runSchema as runSchemaV1, defineSchema as defineSchemaV1, wrapSchema as wrapSchemaV1, } from "./v1/index.js";
+export * from "./v2/index.js";

package/dist/v1/index.d.ts

@@ -0,0 +1,2 @@
+export { wrapSchema } from "./utils/index.js";
+export { runSchema, defineSchema } from "./main.js";

package/dist/v1/index.js

@@ -0,0 +1,2 @@
+export { wrapSchema } from "./utils/index.js";
+export { runSchema, defineSchema } from "./main.js";

package/dist/v1/utils/index.d.ts

@@ -0,0 +1 @@
+export { wrapSchema } from "./wrap-schema.js";

package/dist/v1/utils/index.js

@@ -0,0 +1 @@
+export { wrapSchema } from "./wrap-schema.js";

package/dist/v2/command/main.d.ts

@@ -0,0 +1,5 @@
+import type { TResponse } from "@pogodisco/response";
+export type CommandInputFor<R extends Record<string, any>, K extends keyof R> = R[K] extends (args: infer I) => any ? I : never;
+export type CommandOutputFor<R extends Record<string, any>, K extends keyof R> = R[K] extends (args: any) => Promise<TResponse<infer O>> ? O : never;
+export declare function createCommandRegistrar<R extends Record<string, (...args: any) => Promise<TResponse<any>>>>(registry: R): CommandRegistrar<R>;
+export type CommandRegistrar<R extends Record<string, (...args: any) => Promise<TResponse<any>>>> = <K extends keyof R & string>(name: K, params: CommandInputFor<R, K>) => Promise<TResponse<CommandOutputFor<R, K>>>;

package/dist/v2/command/main.js

@@ -0,0 +1,20 @@
+// -----------------------------
+// Registrar creator
+// -----------------------------
+// export function createCommandRegistrar<
+// 	R extends Record<string, (...args: any) => Promise<TResponse<any>>>,
+// >(registry: R): CommandRegistrar<R> {
+// 	return async function appCommand<K extends keyof R & string>(
+// 		name: K,
+// 		params: CommandInputFor<R, K>,
+// 	): Promise<TResponse<CommandOutputFor<R, K>>> {
+// 		const fn = registry[name];
+// 		return await fn(params);
+// 	};
+// }
+export function createCommandRegistrar(registry) {
+    return async (name, params) => {
+        const fn = registry[name];
+        return fn(params);
+    };
+}

package/dist/v2/graph/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types/index.js";
+export { createGraph, runGraph } from "./main.js";
+export * from "./registry.js";

package/dist/v2/graph/index.js

@@ -0,0 +1,3 @@
+export * from "./types/index.js";
+export { createGraph, runGraph } from "./main.js";
+export * from "./registry.js";

package/dist/v2/graph/main.d.ts

@@ -0,0 +1,4 @@
+import { GraphBuilder, GraphEdge, GraphNode, RuntimeCtx, SchemaGraph } from "./types/index.js";
+export declare function edge<K extends keyof any>(from: K, to: K, when?: (ctx: any) => boolean): GraphEdge<K>;
+export declare function createGraph<Init = {}>(): GraphBuilder<{}, Init>;
+export declare function runGraph<Nodes extends Record<string, GraphNode<any>>, Init>(graph: SchemaGraph<Nodes, Init>, initArgs: Init): Promise<RuntimeCtx<Nodes, Init>>;

package/dist/v2/graph/main.js

@@ -0,0 +1,59 @@
+export function edge(from, to, when) {
+    return { from, to, when };
+}
+export function createGraph() {
+    const nodes = {};
+    // const edges: GraphEdge<string>[] = [];
+    const edges = [];
+    let entry;
+    const builder = {
+        node(key, schema, mapInput) {
+            if (!entry)
+                entry = key;
+            nodes[key] = { schema, mapInput };
+            return builder;
+        },
+        edge(from, to) {
+            // if (!(from in nodes))
+            // 	throw new Error(`Edge 'from' node "${from}" does not exist`);
+            // if (!(to in nodes))
+            // 	throw new Error(`Edge 'to' node "${to}" does not exist`);
+            edges.push({ from, to });
+            return builder;
+        },
+        build() {
+            if (!entry)
+                throw new Error("Graph must have an entry node");
+            return {
+                entry,
+                nodes: nodes,
+                edges: edges,
+            };
+        },
+    };
+    return builder;
+}
+export async function runGraph(graph, initArgs) {
+    const ctx = {
+        _init: initArgs,
+        results: {},
+    };
+    const queue = [graph.entry];
+    const visited = new Set();
+    while (queue.length) {
+        const nodeName = queue.shift();
+        if (visited.has(nodeName))
+            continue;
+        const node = graph.nodes[nodeName];
+        const input = node.mapInput ? node.mapInput(ctx) : ctx._init;
+        const res = await node.schema(input);
+        if (!res.ok)
+            throw res;
+        ctx.results[nodeName] = res.data;
+        visited.add(nodeName);
+        const nextEdges = graph.edges.filter((e) => e.from === nodeName && (!e.when || e.when(ctx)));
+        for (const e of nextEdges)
+            queue.push(e.to);
+    }
+    return ctx;
+}

package/dist/v2/graph/registry.d.ts

@@ -0,0 +1,5 @@
+import { RuntimeCtx, SchemaGraph } from "./types/index.js";
+export type GraphInputFor<R extends Record<string, SchemaGraph<any, any>>, K extends keyof R> = R[K] extends SchemaGraph<any, infer I> ? I : never;
+export type GraphOutputFor<R extends Record<string, SchemaGraph<any, any>>, K extends keyof R> = R[K] extends SchemaGraph<infer N, infer I> ? RuntimeCtx<N, I> : never;
+export type GraphRegistrar<R extends Record<string, SchemaGraph<any, any>>> = <K extends keyof R & string>(name: K, params: GraphInputFor<R, K>) => Promise<GraphOutputFor<R, K>>;
+export declare function createGraphRegistrar<R extends Record<string, SchemaGraph<any, any>>>(registry: R): GraphRegistrar<R>;

package/dist/v2/graph/registry.js

@@ -0,0 +1,10 @@
+import { runGraph } from "./main.js";
+// -----------------------------
+// Factory
+// -----------------------------
+export function createGraphRegistrar(registry) {
+    return async (name, params) => {
+        const graph = registry[name];
+        return runGraph(graph, params);
+    };
+}

package/dist/v2/graph/types/index.d.ts

@@ -0,0 +1,38 @@
+import { TResponse } from "@pogodisco/response";
+export type WrappedSchema<I, O> = (args: I) => Promise<TResponse<O>>;
+export type ExtractInput<T> = T extends WrappedSchema<infer I, any> ? I : never;
+export type ExtractOutput<T> = T extends WrappedSchema<any, infer O> ? O : never;
+export type GraphNode<FN extends WrappedSchema<any, any>> = {
+    schema: FN;
+    mapInput?: (ctx: any) => ExtractInput<FN>;
+};
+export type RuntimeCtx<Nodes extends Record<string, GraphNode<any>>, Init> = {
+    _init: Init;
+    results: {
+        [K in keyof Nodes]: ExtractOutput<Nodes[K]["schema"]>;
+    };
+};
+export type GraphEdge<NodeKeys extends keyof any> = {
+    from: NodeKeys;
+    to: NodeKeys;
+    when?: (ctx: any) => boolean;
+};
+export type BuiltNode<FN extends WrappedSchema<any, any>, Nodes extends Record<string, GraphNode<any>>> = GraphNode<FN>;
+export type SchemaGraph<Nodes extends Record<string, GraphNode<any>>, Init> = {
+    entry: keyof Nodes;
+    nodes: Nodes;
+    edges: GraphEdge<keyof Nodes>[];
+};
+export type GraphBuilder<Nodes extends Record<string, GraphNode<any>> = {}, Init = {}> = {
+    node<K extends string, FN extends WrappedSchema<any, any>>(key: K, schema: FN, mapInput?: (ctx: RuntimeCtx<Nodes & Record<K, GraphNode<FN>>, Init>) => ExtractInput<FN>): GraphBuilder<Nodes & Record<K, GraphNode<FN>>, Init>;
+    edge<From extends keyof Nodes, To extends keyof Nodes>(from: From, to: To): GraphBuilder<Nodes, Init>;
+    build(): SchemaGraph<Nodes, Init>;
+};
+export type GraphEntryInput<G extends SchemaGraph<any, any>> = G extends SchemaGraph<infer Nodes, any> ? RuntimeCtx<Nodes, any>["_init"] : never;
+export type GraphNodes<G> = G extends SchemaGraph<infer Nodes, any> ? Nodes : never;
+export type InferGraphNodes<G> = G extends SchemaGraph<infer N, any> ? N : never;
+export type InferGraphInit<G> = G extends SchemaGraph<any, infer I> ? I : never;
+export type GraphInput<K extends keyof GraphRegistry> = GraphRegistry[K] extends SchemaGraph<any, infer Init> ? Init : never;
+export type GraphOutput<K extends keyof GraphRegistry> = GraphRegistry[K] extends SchemaGraph<infer Nodes, infer Init> ? RuntimeCtx<Nodes, Init> : never;
+export interface GraphRegistry {
+}

package/dist/v2/graph/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/v2/index.d.ts

@@ -0,0 +1,5 @@
+export { runSchema, defineSchema } from "./main.js";
+export { wrapSchema } from "./utils/index.js";
+export * from "./graph/index.js";
+export * from "./types/index.js";
+export * from "./command/main.js";

package/dist/v2/index.js

@@ -0,0 +1,5 @@
+export { runSchema, defineSchema } from "./main.js";
+export { wrapSchema } from "./utils/index.js";
+export * from "./graph/index.js";
+export * from "./types/index.js";
+export * from "./command/main.js";

package/dist/v2/main.d.ts

@@ -0,0 +1,13 @@
+import { TResponse } from "@pogodisco/response";
+import { TaskMap, TaskDefinition, TaskResultsData, TaskState, TaskSchemaWithContracts, SchemaOptions, ExecutionTrace } from "./types/index.js";
+export declare function defineSchema<T extends TaskMap, I extends Record<string, any>, O>(schema: {
+    [K in keyof T]: TaskDefinition<any, T, I>;
+} & {
+    _output: (results: TaskResultsData<T, I>, status?: Record<keyof T, TaskState>) => O;
+}): TaskSchemaWithContracts<T, I, O>;
+export declare const runSchema: <T extends TaskMap, I extends Record<string, any>, O>(schema: TaskSchemaWithContracts<T, I, O>, initArgs: I, options?: SchemaOptions | undefined) => Promise<TResponse<{
+    _output: O;
+    _status: Record<keyof T, TaskState>;
+    _batches: (keyof T)[][];
+    _trace: ExecutionTrace;
+}>>;

package/dist/v2/main.js

@@ -0,0 +1,264 @@
+import { withResponse } from "@pogodisco/response";
+// --- defineSchema ---
+export function defineSchema(schema) {
+    preflightCheck(schema);
+    return schema;
+}
+// --- preflight check & circular detection ---
+function preflightCheck(schema) {
+    const keys = new Set();
+    for (const key in schema) {
+        if (key === "_output" || key === "_init")
+            continue;
+        if (keys.has(key))
+            throw new Error(`Duplicate task key: ${key}`);
+        keys.add(key);
+        const task = schema[key];
+        if (!task)
+            continue;
+        if (task.abort === undefined)
+            task.abort = true;
+        if (task.bg === undefined)
+            task.bg = false;
+        if (task.runIf === undefined)
+            task.runIf = [];
+    }
+    const visited = new Set();
+    const stack = new Set();
+    const visit = (taskKey) => {
+        if (taskKey === "_output" || taskKey === "_init")
+            return;
+        if (stack.has(taskKey))
+            throw new Error(`Circular dependency: ${[...stack, taskKey].join(" -> ")}`);
+        if (visited.has(taskKey))
+            return;
+        stack.add(taskKey);
+        const task = schema[taskKey];
+        for (const dep of task?.dependencies ?? []) {
+            if (!(dep in schema))
+                throw new Error(`Task "${taskKey}" depends on unknown "${dep}"`);
+            visit(dep);
+        }
+        stack.delete(taskKey);
+        visited.add(taskKey);
+    };
+    for (const key of Object.keys(schema))
+        visit(key);
+}
+// --- mark dependents skipped ---
+function markDependentsSkipped(schema, status, key) {
+    for (const k of Object.keys(schema)) {
+        const task = schema[k];
+        if ((task.dependencies ?? []).includes(key) &&
+            status[k] === "pending") {
+            status[k] = "skipped";
+            markDependentsSkipped(schema, status, k);
+        }
+    }
+}
+function buildTopologicalBatches(schema, keys) {
+    const remaining = new Set(keys);
+    const resolved = new Set();
+    const batches = [];
+    while (remaining.size > 0) {
+        const batch = [];
+        for (const key of remaining) {
+            const deps = schema[key]?.dependencies ?? [];
+            if (deps.every((d) => resolved.has(d))) {
+                batch.push(key);
+            }
+        }
+        if (batch.length === 0) {
+            throw new Error("Unable to build execution batches (circular or unresolved deps)");
+        }
+        for (const key of batch) {
+            remaining.delete(key);
+            resolved.add(key);
+        }
+        batches.push(batch);
+    }
+    return batches;
+}
+export const runSchema = withResponse(async (schema, initArgs, options) => {
+    const logger = options?.log;
+    const parallel = options?.parallel ?? false;
+    function isTResponse(x) {
+        return x && typeof x === "object" && "ok" in x;
+    }
+    const normalizeTaskResult = (result) => {
+        if (isTResponse(result)) {
+            if (result.ok)
+                return { ok: true, data: result.data };
+            return { ok: false, error: result };
+        }
+        // raw return = success
+        return { ok: true, data: result };
+    };
+    // --- result normalization ---
+    // --- control flags ---
+    let abortExecution = false;
+    let earlyOutput = null;
+    // --- extend schema with _init ---
+    const localSchema = {
+        ...schema,
+        _init: { fn: (x) => x, argMap: () => initArgs },
+    };
+    const taskKeys = Object.keys(localSchema).filter((k) => k !== "_output" && k !== "_init");
+    // add to topological batching
+    const batches = buildTopologicalBatches(localSchema, taskKeys);
+    const trace = {
+        batches: batches.map((b) => b.map(String)),
+        events: [],
+    };
+    const pushTrace = (task, type, meta) => {
+        trace.events.push({
+            task: String(task),
+            type,
+            timestamp: Date.now(),
+            meta,
+        });
+    };
+    // const results: Partial<TaskResultsData<T, I>> & { _init: I } = {
+    // 	_init: initArgs,
+    // }
+    const results = {
+        _init: initArgs,
+    };
+    const status = {};
+    for (const key of taskKeys)
+        status[key] = "pending";
+    // --- task runner ---
+    const runTask = async (key) => {
+        if (abortExecution || earlyOutput)
+            return;
+        const task = localSchema[key];
+        if (status[key] !== "pending")
+            return;
+        // --- dependency check ---
+        const deps = task.dependencies ?? [];
+        if (!deps.every((d) => status[d] === "success")) {
+            return;
+        }
+        // --- runIf ---
+        if (task.runIf?.length) {
+            const runIfResults = await Promise.all(task.runIf.map((fn) => fn(results)));
+            if (!runIfResults.every(Boolean)) {
+                status[key] = "skipped";
+                markDependentsSkipped(localSchema, status, key);
+                logger?.("skipped", String(key), {
+                    reason: "runIf",
+                    results: runIfResults,
+                });
+                pushTrace(key, "skipped", { reason: "runIf", results: runIfResults });
+                return;
+            }
+        }
+        const args = task.argMap?.(results);
+        // --- background task ---
+        if (task.bg) {
+            logger?.("background", String(key), args);
+            pushTrace(key, "background", { args });
+            Promise.resolve().then(async () => {
+                try {
+                    const raw = args !== undefined ? await task.fn(args) : await task.fn();
+                    const normalized = normalizeTaskResult(raw);
+                    if (!normalized.ok) {
+                        logger?.("fail", String(key), normalized.error);
+                        pushTrace(key, "fail", { error: normalized.error });
+                    }
+                    else {
+                        logger?.("success", String(key), normalized.data);
+                        pushTrace(key, "success", { result: normalized.data });
+                    }
+                }
+                catch (err) {
+                    logger?.("fail", String(key), err);
+                    pushTrace(key, "fail", { error: err });
+                }
+            });
+            status[key] = "success";
+            results[key] = undefined;
+            return;
+        }
+        // --- normal task ---
+        logger?.("start", String(key), args);
+        pushTrace(key, "start", { args });
+        try {
+            const raw = args !== undefined ? await task.fn(args) : await task.fn();
+            const normalized = normalizeTaskResult(raw);
+            if (!normalized.ok) {
+                status[key] = "failed";
+                logger?.("fail", String(key), normalized.error);
+                pushTrace(key, "fail", { error: normalized.error });
+                if (task.abort) {
+                    abortExecution = true;
+                    markDependentsSkipped(localSchema, status, key);
+                }
+                return;
+            }
+            status[key] = "success";
+            results[key] = normalized.data;
+            logger?.("success", String(key), normalized.data);
+            pushTrace(key, "success", { result: normalized.data });
+            // --- early return ---
+            if (task.returnImmediately) {
+                earlyOutput = schema._output(results, status);
+                logger?.("finish", "_schema (early)", {
+                    results,
+                    status,
+                    output: earlyOutput,
+                });
+            }
+        }
+        catch (err) {
+            status[key] = "failed";
+            logger?.("fail", String(key), err);
+            pushTrace(key, "fail", { error: err });
+            if (task.abort) {
+                abortExecution = true;
+                markDependentsSkipped(localSchema, status, key);
+            }
+        }
+    };
+    for (const batch of batches) {
+        if (abortExecution || earlyOutput)
+            break;
+        if (parallel) {
+            await Promise.all(batch.map((k) => runTask(k)));
+        }
+        else {
+            for (const k of batch) {
+                await runTask(k);
+                if (abortExecution || earlyOutput)
+                    break;
+            }
+        }
+    }
+    // --- early return output ---
+    if (earlyOutput) {
+        return {
+            _output: earlyOutput,
+            _status: status,
+            _batches: batches,
+            _trace: trace,
+        };
+    }
+    // --- abort ---
+    if (abortExecution) {
+        throw new Error("Schema aborted due to task failure");
+    }
+    // --- unresolved tasks ---
+    const pendingKeys = taskKeys.filter((k) => status[k] === "pending");
+    if (pendingKeys.length) {
+        throw new Error(`Unresolved tasks (possible circular deps): ${pendingKeys.join(", ")}`);
+    }
+    // --- normal finish ---
+    const output = schema._output(results, status);
+    logger?.("finish", "_schema", { results, status, output });
+    return {
+        _output: output,
+        _status: status,
+        _batches: batches,
+        _trace: trace,
+    };
+});

package/dist/v2/types/index.d.ts

@@ -0,0 +1,50 @@
+export type TraceEventType = "start" | "success" | "fail" | "skipped" | "background";
+export interface TraceEvent {
+    task: string;
+    type: TraceEventType;
+    timestamp: number;
+    meta?: any;
+}
+export interface ExecutionTrace {
+    batches: string[][];
+    events: TraceEvent[];
+}
+export type LogEvent = "start" | "finish" | "data" | "deferred" | "skipped" | "background" | "parallel" | "success" | "fail";
+export type TaskLogger = (event: LogEvent, key: string, meta?: any) => void;
+export interface SchemaOptions {
+    log?: TaskLogger;
+    parallel?: boolean;
+}
+export type TaskState = "pending" | "skipped" | "failed" | "success";
+export type TaskDefinition<F extends (...args: any) => any, T extends TaskMap, I extends Record<string, any>> = {
+    fn: F;
+    dependencies?: string[];
+    abort?: boolean;
+    bg?: boolean;
+    runIf?: ((results: TaskResultsData<T, I>) => boolean | Promise<boolean>)[];
+    argMap?: (results: TaskResultsData<T, I>) => Parameters<F>[0];
+    returnImmediately?: boolean;
+};
+export type TaskMap = Record<string, TaskDefinition<any, any, any>>;
+type SuccessData<T> = T extends {
+    ok: true;
+    data: infer D;
+} ? D : never;
+type TDResultData<TD extends TaskDefinition<any, any, any>> = TD extends TaskDefinition<infer F, any, any> ? SuccessData<Awaited<ReturnType<F>>> : never;
+export type TaskResultsData<T extends TaskMap, I> = {
+    _init: I;
+} & {
+    [K in keyof T]: TDResultData<T[K]>;
+};
+export type TasksFromFns<T extends Record<string, (...args: any) => any>> = {
+    [K in keyof T]: TaskDefinition<T[K], any, any>;
+};
+export type TaskSchemaWithContracts<T extends TaskMap, I extends Record<string, any>, O> = {
+    [K in keyof T]: T[K] extends TaskDefinition<infer F, any, any> ? TaskDefinition<F, T, I> : never;
+} & {
+    _init?: I;
+    _output: (results: TaskResultsData<T, I>, status?: Record<keyof T, TaskState>) => O;
+    _batches?: (keyof T)[][];
+    _trace?: ExecutionTrace;
+};
+export {};

package/dist/v2/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/v2/utils/index.d.ts

@@ -0,0 +1 @@
+export { wrapSchema } from "./wrap-schema.js";

package/dist/v2/utils/index.js

@@ -0,0 +1 @@
+export { wrapSchema } from "./wrap-schema.js";

package/dist/v2/utils/wrap-schema.d.ts

@@ -0,0 +1,2 @@
+import { SchemaOptions, TaskMap, TaskSchemaWithContracts } from "../types/index.js";
+export declare function wrapSchema<T extends TaskMap, I extends Record<string, any>, O>(schema: TaskSchemaWithContracts<T, I, O>, options?: SchemaOptions): (initArgs: I) => Promise<import("@pogodisco/response").TResponse<O>>;

package/dist/v2/utils/wrap-schema.js

@@ -0,0 +1,10 @@
+import { withResponse } from "@pogodisco/response";
+import { runSchema } from "../main.js";
+export function wrapSchema(schema, options) {
+    return withResponse(async (initArgs) => {
+        const res = await runSchema(schema, initArgs, options || {});
+        if (!res.ok)
+            throw res;
+        return res.data._output;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pogodisco/task-runner",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,14 +27,16 @@
   ],
   "scripts": {
     "prepublishOnly": "npm run build",
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "dev": "tsc -w -p tsconfig.json"
   },
   "peerDependencies": {
     "@pogodisco/response": "~0.0.1",
     "typescript": "^5.0.0"
   },
-  "devDependecies": {
-    "@pogodisco/response": "~0.0.1"
+  "devDependencies": {
+    "@pogodisco/response": "~0.0.1",
+    "chalk": "^5.6.2",
+    "pretty-format": "^30.2.0"
   }
 }

package/dist/utils/index.d.ts

@@ -1 +0,0 @@
-export * from "./wrap-schema.js";

package/dist/utils/index.js

@@ -1 +0,0 @@
-export * from "./wrap-schema.js";