@blokjs/runner 0.2.0

package/dist/defineNode.js

@@ -0,0 +1,191 @@
+import { GlobalError, NodeBase } from "@blokjs/shared";
+import BlokService from "./Blok";
+import BlokResponse from "./BlokResponse";
+/**
+ * FunctionNode wrapper that bridges function-first nodes to existing BlokService infrastructure
+ *
+ * This class wraps a function-first node definition and makes it compatible with the
+ * existing BlokService.run() execution model. It handles:
+ * - Zod input validation
+ * - Zod output validation
+ * - Error mapping (ZodError → GlobalError)
+ * - Response wrapping (BlokResponse)
+ */
+export class FunctionNode extends BlokService {
+    definition;
+    constructor(definition) {
+        super();
+        this.definition = definition;
+        this.name = definition.name;
+        // Set content type if specified (e.g. "text/html", "application/pdf")
+        if (definition.contentType) {
+            this.contentType = definition.contentType;
+        }
+        // Set flow flag for control flow nodes (e.g. if-else) that return sub-steps
+        if (definition.flow) {
+            this.flow = true;
+        }
+        // Convert Zod schemas to JSON Schema for backward compatibility
+        // This allows existing tools that expect JSON Schema to continue working
+        this.inputSchema = this.zodToJsonSchema(definition.input);
+        this.outputSchema = this.zodToJsonSchema(definition.output);
+    }
+    /**
+     * Implementation of the abstract handle() method required by BlokService
+     *
+     * This method:
+     * 1. Validates input with Zod
+     * 2. Executes the user's execute() function
+     * 3. Validates output with Zod
+     * 4. Wraps result in BlokResponse
+     * 5. Maps any errors to GlobalError
+     */
+    async handle(ctx, inputs) {
+        const response = new BlokResponse();
+        try {
+            // Step 1: Validate input with Zod
+            const validatedInput = this.definition.input.parse(inputs);
+            // Step 2: Execute user's function
+            const result = await this.definition.execute(ctx, validatedInput);
+            // Step 3: If execute() returns an array of NodeBase instances (flow nodes
+            // like if-else), return them directly. The runner's processFlow() expects
+            // handle() to return BlokService[] for flow nodes, not a wrapped response.
+            if (Array.isArray(result) && result.length > 0 && result[0] instanceof NodeBase) {
+                return result;
+            }
+            // Step 4: Validate output with Zod
+            const validatedOutput = this.definition.output.parse(result);
+            // Step 5: Success!
+            response.setSuccess(validatedOutput);
+        }
+        catch (error) {
+            // Step 6: Map errors to GlobalError
+            const globalError = this.mapErrorToGlobalError(error);
+            response.setError(globalError);
+        }
+        return response;
+    }
+    /**
+     * Maps any error to GlobalError, with special handling for ZodError
+     *
+     * ZodError produces detailed validation errors that are transformed into
+     * a user-friendly error message with all validation issues listed.
+     *
+     * @param error - Any error thrown during execution
+     * @returns GlobalError instance
+     */
+    mapErrorToGlobalError(error) {
+        // Duck typing check for ZodError - more reliable than instanceof across module boundaries
+        // ZodError has: { name: "ZodError", issues: [...] }
+        if (error &&
+            typeof error === "object" &&
+            "issues" in error &&
+            Array.isArray(error.issues) &&
+            "name" in error &&
+            error.name === "ZodError") {
+            return this.zodErrorToGlobalError(error);
+        }
+        if (error instanceof Error) {
+            const globalError = new GlobalError(error.message);
+            globalError.setStack(error.stack);
+            globalError.setName(this.name);
+            globalError.setCode(500);
+            return globalError;
+        }
+        // Unknown error type
+        const globalError = new GlobalError(String(error));
+        globalError.setName(this.name);
+        globalError.setCode(500);
+        return globalError;
+    }
+    /**
+     * Converts ZodError to GlobalError with detailed validation messages
+     *
+     * Example output:
+     * "Validation failed: userId (expected string, received undefined),
+     *  email (invalid email format)"
+     *
+     * @param zodError - Zod validation error
+     * @returns GlobalError with formatted validation messages
+     */
+    zodErrorToGlobalError(zodError) {
+        const errorMessages = zodError.errors.map((err) => {
+            const path = err.path.join(".");
+            return `${path} (${err.message})`;
+        });
+        const message = `Validation failed: ${errorMessages.join(", ")}`;
+        const globalError = new GlobalError(message);
+        globalError.setCode(400); // Bad Request
+        globalError.setName(this.name);
+        globalError.setJson({
+            validation_errors: zodError.errors.map((err) => ({
+                path: err.path,
+                message: err.message,
+                code: err.code,
+            })),
+        });
+        return globalError;
+    }
+    /**
+     * Converts Zod schema to JSON Schema for backward compatibility
+     *
+     * This is a simplified conversion that covers basic types.
+     * For production use, consider using zod-to-json-schema library.
+     *
+     * @param zodSchema - Zod schema to convert
+     * @returns JSON Schema representation
+     */
+    zodToJsonSchema(_zodSchema) {
+        // Return a permissive schema — the actual validation happens via Zod in handle().
+        // Using {} (no type constraint) instead of { type: "object" } so that nodes
+        // accepting arrays (e.g. if-else conditions) also pass the JSON Schema pre-check.
+        return {};
+    }
+}
+/**
+ * Define a function-first node with Zod schema validation
+ *
+ * This is the main API for creating modern, type-safe nodes in Blok.
+ *
+ * Benefits over class-based nodes:
+ * - 60%+ less boilerplate code
+ * - Type-safe inputs and outputs via Zod
+ * - Automatic validation
+ * - Better AI generation success rates
+ * - Easier to test and maintain
+ *
+ * @example
+ * ```typescript
+ * import { defineNode } from "@blokjs/runner";
+ * import { z } from "zod";
+ *
+ * export default defineNode({
+ *   name: "fetch-user",
+ *   description: "Fetches user by ID from database",
+ *
+ *   input: z.object({
+ *     userId: z.string().uuid(),
+ *   }),
+ *
+ *   output: z.object({
+ *     user: z.object({
+ *       id: z.string(),
+ *       name: z.string(),
+ *       email: z.string().email(),
+ *     }),
+ *   }),
+ *
+ *   async execute(ctx, input) {
+ *     const user = await db.users.findById(input.userId);
+ *     return { user };
+ *   },
+ * });
+ * ```
+ *
+ * @param definition - Node definition with Zod schemas
+ * @returns FunctionNode instance compatible with existing runner
+ */
+export function defineNode(definition) {
+    return new FunctionNode(definition);
+}
+//# sourceMappingURL=defineNode.js.map

package/dist/defineNode.js.map

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

package/dist/graphql/GraphQLSchemaGenerator.d.ts

@@ -0,0 +1,129 @@
+/**
+ * GraphQL Schema Generator for Blok Workflows
+ *
+ * Automatically generates GraphQL schema definitions (SDL) from workflow definitions.
+ * Introspects HTTP trigger configurations and node structures to produce
+ * Query/Mutation types with appropriate input/output types.
+ *
+ * @example
+ * ```typescript
+ * const generator = new GraphQLSchemaGenerator({
+ *   schemaName: "BlokAPI",
+ *   includeSubscriptions: true,
+ * });
+ *
+ * generator.addWorkflow({
+ *   name: "get-user",
+ *   version: "1.0.0",
+ *   trigger: { http: { method: "GET", path: "/users/:id" } },
+ *   steps: [{ name: "fetch", node: "db-query", type: "local" }],
+ *   nodes: { "db-query": {} },
+ * });
+ *
+ * console.log(generator.generate());
+ * ```
+ */
+export interface GraphQLGeneratorConfig {
+    /** Schema name used in documentation */
+    schemaName?: string;
+    /** Description for the schema */
+    description?: string;
+    /** Include subscription types for WebSocket/SSE workflows */
+    includeSubscriptions?: boolean;
+    /** Include workflow metadata in type descriptions */
+    includeMetadata?: boolean;
+    /** Custom scalar definitions */
+    customScalars?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface GqlWorkflowDefinition {
+    name: string;
+    version: string;
+    description?: string;
+    trigger: {
+        http?: {
+            method: string;
+            path: string;
+        };
+        grpc?: {
+            service: string;
+            method: string;
+        };
+        websocket?: {
+            path?: string;
+        };
+        sse?: {
+            path?: string;
+        };
+        [key: string]: unknown;
+    };
+    steps: Array<{
+        name: string;
+        node: string;
+        type?: string;
+        runtime?: string;
+    }>;
+    nodes: Record<string, unknown>;
+    inputs?: Record<string, GqlFieldDef>;
+    outputs?: Record<string, GqlFieldDef>;
+}
+export interface GqlFieldDef {
+    type: string;
+    required?: boolean;
+    description?: string;
+    items?: GqlFieldDef;
+    fields?: Record<string, GqlFieldDef>;
+}
+export declare class GraphQLSchemaGenerator {
+    private config;
+    private workflows;
+    private customTypes;
+    constructor(config?: GraphQLGeneratorConfig);
+    addWorkflow(workflow: GqlWorkflowDefinition): void;
+    addWorkflows(workflows: GqlWorkflowDefinition[]): void;
+    addCustomType(name: string, definition: string): void;
+    /**
+     * Generate GraphQL Schema Definition Language (SDL)
+     */
+    generate(): string;
+    /**
+     * Generate an introspection-friendly JSON representation
+     */
+    toJSON(): GraphQLSchemaJSON;
+    private resolveWorkflow;
+    private generateInputType;
+    private generateOutputType;
+    private generateFieldDefinition;
+    private generateSubscriptionField;
+    private inferOutputFields;
+    private inferInputFields;
+    private fieldDefToGraphQLType;
+    private getTriggerType;
+    private extractPathParams;
+    private toPascalCase;
+    private toFieldName;
+    private emptySchema;
+}
+export interface GraphQLSchemaJSON {
+    schemaName: string;
+    types: GraphQLTypeInfo[];
+    queries: GraphQLFieldInfo[];
+    mutations: GraphQLFieldInfo[];
+    subscriptions: GraphQLFieldInfo[];
+}
+export interface GraphQLTypeInfo {
+    name: string;
+    kind: "OBJECT" | "INPUT_OBJECT" | "ENUM" | "SCALAR";
+    fields: GraphQLFieldInfo[];
+}
+export interface GraphQLFieldInfo {
+    name: string;
+    type: string;
+    description?: string;
+    args?: Array<{
+        name: string;
+        type: string;
+    }>;
+}