@pikku/core 0.7.7 → 0.8.0

package/dist/events/mcp/mcp-runner.js

@@ -0,0 +1,192 @@
+import { getErrorResponse } from '../../errors/error-handler.js';
+import { closeSessionServices } from '../../utils.js';
+import { pikkuState } from '../../pikku-state.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { rpcService } from '../rpc/rpc-runner.js';
+import { BadRequestError, NotFoundError } from '../../errors/errors.js';
+export class MCPError extends Error {
+    error;
+    constructor(error) {
+        super(error?.message || 'MCP Error');
+        this.error = error;
+        this.name = 'MCPError';
+        this.stack = new Error().stack;
+    }
+}
+export const addMCPResource = (mcpResource) => {
+    const resourcesMeta = pikkuState('mcp', 'resourcesMeta');
+    const mcpResourceMeta = resourcesMeta[mcpResource.uri];
+    if (!mcpResourceMeta) {
+        throw new Error(`MCP resource metadata not found for '${mcpResource.uri}'`);
+    }
+    addFunction(mcpResourceMeta.pikkuFuncName, {
+        func: mcpResource.func,
+    });
+    const resources = pikkuState('mcp', 'resources');
+    if (resources.has(mcpResource.uri)) {
+        throw new Error(`MCP resource already exists: ${mcpResource.uri}`);
+    }
+    resources.set(mcpResource.uri, mcpResource);
+};
+export const addMCPTool = (mcpTool) => {
+    const toolsMeta = pikkuState('mcp', 'toolsMeta');
+    const mcpToolMeta = toolsMeta[mcpTool.name];
+    if (!mcpToolMeta) {
+        throw new Error(`MCP tool metadata not found for '${mcpTool.name}'`);
+    }
+    addFunction(mcpToolMeta.pikkuFuncName, {
+        func: mcpTool.func,
+    });
+    const tools = pikkuState('mcp', 'tools');
+    if (tools.has(mcpTool.name)) {
+        throw new Error(`MCP tool already exists: ${mcpTool.name}`);
+    }
+    tools.set(mcpTool.name, mcpTool);
+};
+export const addMCPPrompt = (mcpPrompt) => {
+    const promptsMeta = pikkuState('mcp', 'promptsMeta');
+    const mcpPromptMeta = promptsMeta[mcpPrompt.name];
+    if (!mcpPromptMeta) {
+        throw new Error(`MCP prompt metadata not found for '${mcpPrompt.name}'`);
+    }
+    addFunction(mcpPromptMeta.pikkuFuncName, {
+        func: mcpPrompt.func,
+    });
+    const prompts = pikkuState('mcp', 'prompts');
+    if (prompts.has(mcpPrompt.name)) {
+        throw new Error(`MCP prompt already exists: ${mcpPrompt.name}`);
+    }
+    prompts.set(mcpPrompt.name, mcpPrompt);
+};
+export async function runMCPResource(request, params, uri) {
+    let endpoint;
+    let pikkuFuncName;
+    let extractedParams = {};
+    const metas = pikkuState('mcp', 'resourcesMeta');
+    const endpoints = pikkuState('mcp', 'resources');
+    if (endpoints.has(uri)) {
+        endpoint = endpoints.get(uri);
+        pikkuFuncName = metas[uri]?.pikkuFuncName;
+    }
+    else {
+        for (const [uriTemplate, value] of endpoints.entries()) {
+            // Extract parameter names from the template
+            const paramNames = Array.from(uriTemplate.matchAll(/\{([^}]+)\}/g), (m) => m[1]);
+            // Create regex pattern to match and capture parameter values
+            const regexPattern = uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)');
+            const regex = new RegExp(`^${regexPattern}$`);
+            const match = uri.match(regex);
+            if (match) {
+                endpoint = value;
+                pikkuFuncName = metas[uriTemplate]?.pikkuFuncName;
+                // Extract parameter values and create params object
+                for (let i = 0; i < paramNames.length; i++) {
+                    extractedParams[paramNames[i]] = match[i + 1]; // match[0] is the full match
+                }
+                break;
+            }
+        }
+    }
+    return await runMCPPikkuFunc({
+        ...request,
+        params: { ...request.params, ...extractedParams },
+    }, 'resource', uri, endpoint, pikkuFuncName, { ...params, mcp: { uri } });
+}
+export async function runMCPTool(request, params, name) {
+    const endpoint = pikkuState('mcp', 'tools').get(name);
+    const meta = pikkuState('mcp', 'toolsMeta')[name];
+    return await runMCPPikkuFunc(request, 'tool', name, endpoint, meta?.pikkuFuncName, params);
+}
+export async function runMCPPrompt(request, params, name) {
+    const endpoint = pikkuState('mcp', 'prompts').get(name);
+    const meta = pikkuState('mcp', 'promptsMeta')[name];
+    return await runMCPPikkuFunc(request, 'prompt', name, endpoint, meta?.pikkuFuncName, params);
+}
+/**
+ * JSON-RPC 2.0 compatible MCP endpoint runner
+ */
+async function runMCPPikkuFunc(request, type, name, mcp, pikkuFuncName, { session, singletonServices, createSessionServices, mcp: interaction, }) {
+    let sessionServices;
+    try {
+        // Validate JSON-RPC request structure
+        if (request.jsonrpc !== '2.0') {
+            throw new BadRequestError('Invalid JSON-RPC version, only supoorted version is 2.0');
+        }
+        if (!mcp) {
+            throw new NotFoundError(`MCP '${type}' registration not found for '${name}'`);
+        }
+        if (!pikkuFuncName) {
+            throw new NotFoundError(`MCP '${type}' PikkuFunction Mapping not found for '${name}'`);
+        }
+        singletonServices.logger.debug(`Running MCP ${type}: ${name}`);
+        const getAllServices = async () => {
+            if (createSessionServices) {
+                const services = await createSessionServices(singletonServices, { mcp: interaction }, session);
+                sessionServices = services;
+                return rpcService.injectRPCService({
+                    ...singletonServices,
+                    ...services,
+                    mcp: interaction,
+                });
+            }
+            return rpcService.injectRPCService({
+                ...singletonServices,
+                mcp: interaction,
+            });
+        };
+        const result = await runPikkuFunc(pikkuFuncName, {
+            getAllServices,
+            session,
+            data: request.params,
+        });
+        return {
+            id: request.id,
+            result,
+        };
+    }
+    catch (e) {
+        singletonServices.logger.error(`Error running MCP ${type} '${name}':`, e.constructor);
+        const errorResponse = getErrorResponse(e);
+        if (errorResponse?.mcpCode) {
+            throw new MCPError({
+                id: request.id,
+                code: errorResponse.mcpCode,
+                message: errorResponse.message,
+            });
+        }
+        else {
+            if (errorResponse) {
+                singletonServices.logger.warn(`Got error without a mapping: ${errorResponse.message}`);
+            }
+            throw new MCPError({
+                id: request.id,
+                code: -32603,
+                message: 'Internal error',
+                data: { message: e.message, stack: e.stack },
+            });
+        }
+    }
+    finally {
+        if (sessionServices) {
+            await closeSessionServices(singletonServices.logger, sessionServices);
+        }
+    }
+}
+export const getMCPTools = () => {
+    return pikkuState('mcp', 'tools');
+};
+export const getMCPResources = () => {
+    return pikkuState('mcp', 'resources');
+};
+export const getMCPResourcesMeta = () => {
+    return pikkuState('mcp', 'resourcesMeta');
+};
+export const getMCPToolsMeta = () => {
+    return pikkuState('mcp', 'toolsMeta');
+};
+export const getMCPPrompts = () => {
+    return pikkuState('mcp', 'prompts');
+};
+export const getMCPPromptsMeta = () => {
+    return pikkuState('mcp', 'promptsMeta');
+};

package/dist/events/mcp/mcp.types.d.ts

@@ -0,0 +1,117 @@
+import { CoreAPIFunctionSessionless } from '../../function/functions.types.js';
+export type PikkuMCP<Tools extends string = any> = {
+    uri?: string;
+    sendResourceUpdated: (uri: string) => void;
+    enableResources: (resources: Record<string, boolean>) => Promise<boolean>;
+    enablePrompts: (prompts: Record<string, boolean>) => Promise<boolean>;
+    enableTools: (tools: Record<Tools, boolean>) => Promise<boolean>;
+};
+/**
+ * Represents metadata for MCP resources, including name, description, and documentation.
+ */
+export type MCPResourceMeta = Record<string, Omit<CoreMCPResource, 'func'> & {
+    pikkuFuncName: string;
+    inputSchema: string | null;
+    outputSchema: string | null;
+}>;
+/**
+ * Represents metadata for MCP tools, including name, description, and documentation.
+ */
+export type MCPToolMeta = Record<string, Omit<CoreMCPTool, 'func'> & {
+    pikkuFuncName: string;
+    inputSchema: string | null;
+    outputSchema: string | null;
+}>;
+/**
+ * Represents metadata for MCP prompts, including name, description, and arguments.
+ */
+export type MCPPromptMeta = Record<string, Omit<CoreMCPPrompt, 'func'> & {
+    pikkuFuncName: string;
+    inputSchema: string | null;
+    outputSchema: string | null;
+    arguments: Array<{
+        name: string;
+        description: string;
+        required: boolean;
+    }>;
+}>;
+/**
+ * Represents an MCP resource with specific properties.
+ */
+export type CoreMCPResource<APIFunction = CoreAPIFunctionSessionless<any, any>> = {
+    uri: string;
+    title: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+    streaming?: boolean;
+    func: APIFunction;
+    tags?: string[];
+};
+/**
+ * Represents an MCP tool with specific properties.
+ */
+export type CoreMCPTool<APIFunction = CoreAPIFunctionSessionless<any, any>> = {
+    name: string;
+    title?: string;
+    description: string;
+    annotations?: Record<string, any>;
+    func: APIFunction;
+    tags?: string[];
+    streaming?: boolean;
+};
+/**
+ * Represents an MCP prompt with specific properties.
+ */
+export type CoreMCPPrompt<APIFunction = CoreAPIFunctionSessionless<any, MCPPromptResponse>> = {
+    name: string;
+    description?: string;
+    func: APIFunction;
+    tags?: string[];
+};
+export type JsonRpcRequest = {
+    jsonrpc: string;
+    id?: string | number | null;
+    params?: any;
+};
+export type JsonRpcResponse = {
+    id?: string | number | null;
+    result?: any;
+};
+export type JsonRpcErrorResponse = {
+    id?: string | number | null;
+    code: number;
+    message: string;
+    data?: any;
+};
+/**
+ * Represents a message in an MCP prompt response
+ */
+export type MCPPromptMessage = {
+    role: 'user' | 'assistant' | 'system';
+    content: {
+        type: 'text' | 'image';
+        text: string;
+        data?: string;
+    };
+};
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+export type MCPPromptResponse = MCPPromptMessage[];
+export type MCPResourceMessage = {
+    uri: string;
+    text: string;
+};
+export type MCPResourceResponse = MCPResourceMessage[];
+/**
+ * Standard response type for MCP prompts - array of messages
+ */
+export type MCPToolMessage = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+};
+export type MCPToolResponse = MCPToolMessage[];

package/dist/events/queue/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './queue.types.js';
+export { addQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, } from './queue-runner.js';
+export { validateWorkerConfig } from './validate-worker-config.js';
+export type { QueueConfigMapping } from './validate-worker-config.js';
+export { registerqueueWorkers } from './register-queue-helper.js';
+export type { QueueRegistrationCallback } from './register-queue-helper.js';

package/dist/events/queue/index.js

@@ -0,0 +1,6 @@
+// Queue processor management
+export { addQueueWorker, runQueueJob, getQueueWorkers, removeQueueWorker, } from './queue-runner.js';
+// Configuration validation
+export { validateWorkerConfig } from './validate-worker-config.js';
+// Queue registration helper
+export { registerqueueWorkers } from './register-queue-helper.js';

package/dist/events/queue/queue-runner.d.ts

@@ -0,0 +1,24 @@
+import type { CoreServices } from '../../types/core.types.js';
+import type { CoreQueueWorker, QueueJob } from './queue.types.js';
+import type { CoreAPIFunctionSessionless } from '../../function/functions.types.js';
+import { CreateSessionServices } from '../../types/core.types.js';
+/**
+ * Add a queue processor to the system
+ */
+export declare const addQueueWorker: <InputData = any, OutputData = any, APIFunction extends CoreAPIFunctionSessionless<InputData, OutputData> = CoreAPIFunctionSessionless<InputData, OutputData>>(queueWorker: CoreQueueWorker<APIFunction>) => void;
+/**
+ * Get all registered queue processors
+ */
+export declare function getQueueWorkers(): Map<string, CoreQueueWorker>;
+/**
+ * Stop and remove a queue processor
+ */
+export declare function removeQueueWorker(name: string): Promise<void>;
+/**
+ * Process a single queue job - this function is called by queue consumers
+ */
+export declare function runQueueJob({ singletonServices, createSessionServices, job, }: {
+    singletonServices: CoreServices;
+    createSessionServices?: CreateSessionServices;
+    job: QueueJob;
+}): Promise<void>;

package/dist/events/queue/queue-runner.js

@@ -0,0 +1,83 @@
+import { getErrorResponse } from '../../errors/error-handler.js';
+import { pikkuState } from '../../pikku-state.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+/**
+ * Error class for queue processor not found
+ */
+class QueueWorkerNotFoundError extends Error {
+    constructor(name) {
+        super(`Queue processor not found: ${name}`);
+    }
+}
+/**
+ * Add a queue processor to the system
+ */
+export const addQueueWorker = (queueWorker) => {
+    // Get processor metadata
+    const meta = pikkuState('queue', 'meta');
+    const processorMeta = meta[queueWorker.queueName];
+    if (!processorMeta) {
+        throw new Error(`Queue processor metadata not found for '${queueWorker.queueName}'. Make sure to run the CLI to generate metadata.`);
+    }
+    // Register the function with pikku
+    addFunction(processorMeta.pikkuFuncName, {
+        func: queueWorker.func,
+    });
+    // Store processor definition in state - runtime adapters will pick this up
+    const registrations = pikkuState('queue', 'registrations');
+    registrations.set(queueWorker.queueName, queueWorker);
+};
+/**
+ * Get all registered queue processors
+ */
+export function getQueueWorkers() {
+    return pikkuState('queue', 'registrations');
+}
+/**
+ * Stop and remove a queue processor
+ */
+export async function removeQueueWorker(name) {
+    const registrations = pikkuState('queue', 'registrations');
+    const registration = registrations.get(name);
+    if (!registration) {
+        throw new QueueWorkerNotFoundError(name);
+    }
+    registrations.delete(name);
+}
+/**
+ * Process a single queue job - this function is called by queue consumers
+ */
+export async function runQueueJob({ singletonServices, createSessionServices, job, }) {
+    const logger = singletonServices.logger;
+    const meta = pikkuState('queue', 'meta');
+    const processorMeta = meta[job.queueName];
+    if (!processorMeta) {
+        throw new Error(`Processor metadata not found for: ${job.queueName}`);
+    }
+    try {
+        logger.info(`Processing job ${job.id} in queue ${job.queueName}`);
+        // Use provided singleton services
+        const getAllServices = () => ({
+            ...singletonServices,
+            ...(createSessionServices
+                ? createSessionServices(singletonServices, {}, undefined)
+                : {}),
+        });
+        // Execute the pikku function with the job data
+        const result = await runPikkuFunc(processorMeta.pikkuFuncName, {
+            getAllServices,
+            data: job.data,
+        });
+        logger.debug(`Successfully processed job ${job.id} in queue ${job.queueName}`);
+        return result;
+    }
+    catch (error) {
+        logger.error(`Error processing job ${job.id} in queue ${job.queueName}:`, error);
+        const errorResponse = getErrorResponse(error);
+        if (errorResponse != null) {
+            logger.error('Processed error response:', errorResponse);
+        }
+        // Re-throw the error so the queue service can handle retries/DLQ
+        throw error;
+    }
+}

package/dist/events/queue/queue.types.d.ts

@@ -0,0 +1,154 @@
+import { APIDocs } from '../../types/core.types.js';
+import { CoreAPIFunctionSessionless } from '../../function/functions.types.js';
+import { QueueConfigMapping } from './validate-worker-config.js';
+/**
+ * Configuration for queue workers - how jobs are processed
+ */
+/**
+ * Configuration for queue workers - how jobs are processed
+ */
+export interface PikkuWorkerConfig {
+    /** Optional worker name for identification and monitoring */
+    name?: string;
+    /** Number of messages to process in batch / in parallel */
+    batchSize?: number;
+    /** Number of messages to prefetch for efficiency */
+    prefetch?: number;
+    /** Polling interval for pull-based queues in ms */
+    pollInterval?: number;
+    /** Message visibility timeout in seconds */
+    visibilityTimeout?: number;
+    /** Duration of job lock in milliseconds */
+    lockDuration?: number;
+    /** Number of seconds to wait when queue is empty before polling again */
+    drainDelay?: number;
+    /** Keep N completed jobs for inspection */
+    removeOnComplete?: number;
+    /** Keep N failed jobs for inspection */
+    removeOnFail?: number;
+    /** Maximum number of times a job can be recovered from stalled state */
+    maxStalledCount?: number;
+    /** Condition to start processor at instance creation */
+    autorun?: boolean;
+}
+/**
+ * Configuration for individual jobs - how jobs behave
+ */
+export interface PikkuJobConfig {
+    /** Maximum retry attempts for failed jobs */
+    retryAttempts?: number;
+    /** Initial retry delay in milliseconds */
+    retryDelay?: number;
+    /** Retry backoff strategy */
+    retryBackoff?: 'linear' | 'exponential' | 'fixed';
+    /** Queue for failed messages after max retries */
+    deadLetterQueue?: string;
+    /** How long to retain completed jobs in seconds */
+    messageRetention?: number;
+    /** Job priority (higher numbers = higher priority) */
+    priority?: number;
+    /** Enable FIFO ordering where supported */
+    fifo?: boolean;
+    /** Job timeout in milliseconds */
+    timeout?: number;
+    /** Delay before job execution in milliseconds */
+    delay?: number;
+}
+/**
+ * Configuration validation result with warnings and fallbacks
+ */
+export interface ConfigValidationResult {
+    applied: Partial<PikkuWorkerConfig>;
+    ignored: Partial<PikkuWorkerConfig>;
+    warnings: string[];
+    fallbacks: {
+        [key: string]: any;
+    };
+}
+/**
+ * Queue job representation
+ */
+export type QueueJobStatus = 'waiting' | 'active' | 'completed' | 'failed' | 'delayed';
+export type QueueJobMetadata = {
+    progress?: number | string | object | undefined | boolean;
+    attemptsMade?: number;
+    maxAttempts?: number;
+    processedAt?: Date;
+    completedAt?: Date;
+    failedAt?: Date;
+    error?: string;
+    createdAt: Date;
+};
+export interface QueueJob<T = any, R = any> {
+    id: string;
+    queueName: string;
+    status: () => Promise<QueueJobStatus> | QueueJobStatus;
+    data: T;
+    result?: R;
+    waitForCompletion?: (ttl?: number) => Promise<R>;
+    metadata?: () => Promise<QueueJobMetadata> | QueueJobMetadata;
+}
+/**
+ * Job options for queue operations
+ */
+export interface JobOptions {
+    priority?: number;
+    delay?: number;
+    attempts?: number;
+    backoff?: string | {
+        type: string;
+        delay?: number;
+    };
+    removeOnComplete?: number;
+    removeOnFail?: number;
+    jobId?: string;
+}
+/**
+ * Queue provider interface for job publishing operations
+ */
+export interface QueueService {
+    /** Whether this queue provider supports job results */
+    readonly supportsResults: boolean;
+    /** Add a job to the queue with type safety */
+    add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
+    /** Get job status and result */
+    getJob<T, R>(queueName: string, jobId: string): Promise<QueueJob<T, R> | null>;
+}
+/**
+ * Queue service interface that queue adapters implement
+ */
+export interface QueueWorkers {
+    /** Service name identifier */
+    name: string;
+    /** Whether this queue service supports job results */
+    supportsResults: boolean;
+    /** Configuration mapping for validation */
+    configMappings: QueueConfigMapping;
+    /** Scan state and register all compatible processors */
+    registerQueues(): Promise<Record<string, ConfigValidationResult[]>>;
+    /** Close all queues and connections */
+    close(): Promise<void>;
+}
+/**
+ * Queue processor metadata
+ */
+export type queueWorkersMeta = Record<string, {
+    pikkuFuncName: string;
+    schemaName?: string;
+    queueName: string;
+    session?: undefined;
+    docs?: APIDocs;
+    tags?: string[];
+    config?: PikkuWorkerConfig;
+}>;
+/**
+ * Core queue processor definition
+ */
+export type CoreQueueWorker<APIFunction = CoreAPIFunctionSessionless<any, any>> = {
+    queueName: string;
+    func: APIFunction;
+    config?: PikkuWorkerConfig;
+    docs?: APIDocs;
+    session?: undefined;
+    tags?: string[];
+};

package/dist/events/queue/register-queue-helper.d.ts

@@ -0,0 +1,17 @@
+import type { ConfigValidationResult, CoreQueueWorker } from './queue.types.js';
+import { QueueConfigMapping } from './validate-worker-config.js';
+import { Logger } from '../../services/logger.js';
+/**
+ * Queue processor registration callback
+ */
+export type QueueRegistrationCallback<T = any> = (queueName: string, processor: CoreQueueWorker) => Promise<T>;
+/**
+ * Helper function to register queue processors with validation
+ * This centralizes the common logic for looping over processors and validating configs
+ *
+ * @param configMappings - Configuration mapping for the queue implementation
+ * @param registerCallback - Callback to register each individual queue processor
+ * @param logger - Optional logger for info/error messages
+ * @returns Record of validation results by queue name
+ */
+export declare function registerqueueWorkers<T = any>(configMappings: QueueConfigMapping, logger: Logger, registerCallback: QueueRegistrationCallback<T>): Promise<Record<string, ConfigValidationResult[]>>;

package/dist/events/queue/register-queue-helper.js

@@ -0,0 +1,34 @@
+import { getQueueWorkers } from './queue-runner.js';
+import { validateWorkerConfig, } from './validate-worker-config.js';
+/**
+ * Helper function to register queue processors with validation
+ * This centralizes the common logic for looping over processors and validating configs
+ *
+ * @param configMappings - Configuration mapping for the queue implementation
+ * @param registerCallback - Callback to register each individual queue processor
+ * @param logger - Optional logger for info/error messages
+ * @returns Record of validation results by queue name
+ */
+export async function registerqueueWorkers(configMappings, logger, registerCallback) {
+    const configValidation = {};
+    const queueWorkers = getQueueWorkers();
+    for (const [queueName, processor] of queueWorkers) {
+        logger?.info(`Registering queue processor: ${queueName}`);
+        // Validate the processor configuration
+        const validationResult = validateWorkerConfig(configMappings, processor.config);
+        // Store validation results
+        configValidation[queueName] = configValidation[queueName] || [];
+        configValidation[queueName].push(validationResult);
+        if (validationResult.warnings.length > 0) {
+            logger?.warn(`Configuration warnings for queue ${queueName}:`, validationResult.warnings);
+        }
+        try {
+            await registerCallback(queueName, processor);
+            logger?.info(`Successfully registered queue processor: ${queueName}`);
+        }
+        catch (error) {
+            logger?.error(`Failed to register queue processor ${queueName}:`, error);
+        }
+    }
+    return configValidation;
+}

package/dist/events/queue/validate-worker-config.d.ts

@@ -0,0 +1,41 @@
+import { PikkuWorkerConfig, ConfigValidationResult } from './queue.types.js';
+/**
+ * Configuration mapping structure for queue implementations
+ */
+export interface QueueConfigMapping {
+    /** Configurations that are directly supported */
+    supported: Partial<Record<keyof PikkuWorkerConfig, {
+        /** The property name in the underlying queue system */
+        queueProperty?: string;
+        /** Optional transform function for the value */
+        transform?: (value: any) => any;
+        /** Description of what this configuration does */
+        description: string;
+    }>>;
+    /** Configurations that are not supported */
+    unsupported: Partial<Record<keyof PikkuWorkerConfig, {
+        /** Why this configuration is not supported */
+        reason: string;
+        /** Detailed explanation of what the queue system does instead */
+        explanation: string;
+    }>>;
+    /** Configurations that have partial support or workarounds */
+    fallbacks: Partial<Record<keyof PikkuWorkerConfig, {
+        /** Why this configuration uses a fallback */
+        reason: string;
+        /** Detailed explanation of the fallback behavior */
+        explanation: string;
+        /** The fallback value or description */
+        fallbackValue: string;
+    }>>;
+}
+/**
+ * Validates worker configuration using a mapping table
+ * This provides a flexible, maintainable way to validate configurations
+ * across different queue implementations
+ *
+ * @param config - The worker configuration to validate
+ * @param configMapping - The mapping table defining supported/unsupported configurations
+ * @returns Validation result with applied, ignored, warnings, and fallbacks
+ */
+export declare function validateWorkerConfig(configMapping: QueueConfigMapping, config?: PikkuWorkerConfig): ConfigValidationResult;