@tasker-systems/tasker 0.1.5 → 0.1.7

package/dist/events/index.d.ts

@@ -1,3 +1,3 @@
-export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-Bvdub2HH.js';
+export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-CRCYa9Xk.js';
 import 'eventemitter3';
 import '../ffi/index.js';

package/dist/{index-Bvdub2HH.d.ts → index-CRCYa9Xk.d.ts}

@@ -948,6 +948,10 @@ declare abstract class StepHandler {
     /**
      * Version string for the handler.
      * Default: "1.0.0"
+     *
+     * Currently a no-op — not yet wired through FFI bridges to
+     * StepExecutionMetadata. Reserved for future observability
+     * and compatibility tracking.
      */
     static handlerVersion: string;
     /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NapiModule, FfiLayer, FfiDomainEvent, FfiLayerConfig } from './ffi/index.js';
 export { BootstrapConfig as FfiBootstrapConfig, BootstrapResult as FfiBootstrapResult, FfiDispatchMetrics, LogFields as FfiLogFields, FfiStepEvent, StopResult as FfiStopResult, WorkerStatus as FfiWorkerStatus, NapiBackoffHint, NapiCheckpointYieldData, NapiClientResult, NapiDependencyResult, NapiDispatchMetrics, NapiDomainEvent, NapiDomainEventMetadata, NapiListTasksParams, NapiOrchestrationMetadata, NapiStepDefinition, NapiStepEvent, NapiStepExecutionError, NapiStepExecutionMetadata, NapiStepExecutionResult, NapiTaskInfo, NapiTaskRequest, NapiWorkflowStep, StepExecutionResult } from './ffi/index.js';
-import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, E as ExecutableHandler, c as StepHandlerClass, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-Bvdub2HH.js';
-export { y as ErrorCallback, I as ErrorType, n as EventName, o as EventNames, z as EventPollerConfig, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, L as StepContextParams, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, H as StepExecutionSubscriberConfig, N as StepHandlerResultParams, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller, J as isStandardErrorType, K as isTypicallyRetryable } from './index-Bvdub2HH.js';
+import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, c as StepHandlerClass, E as ExecutableHandler, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-CRCYa9Xk.js';
+export { y as ErrorCallback, I as ErrorType, n as EventName, o as EventNames, z as EventPollerConfig, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, L as StepContextParams, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, H as StepExecutionSubscriberConfig, N as StepHandlerResultParams, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller, J as isStandardErrorType, K as isTypicallyRetryable } from './index-CRCYa9Xk.js';
 import { Logger } from 'pino';
 import 'eventemitter3';
 
@@ -2629,6 +2629,257 @@ declare function ffiEventToDomainEvent(ffiEvent: FfiDomainEvent): DomainEvent;
  */
 declare function createFfiPollAdapter(module: NapiModule): () => DomainEvent | null;
 
+/**
+ * Functional/factory API for step handlers (TAS-294).
+ *
+ * This module provides factory-function alternatives to the class-based handler API.
+ * It reduces boilerplate for common handler patterns while preserving full access
+ * to the underlying StepContext for advanced use cases.
+ *
+ * Factory functions auto-wrap return values and classify exceptions:
+ * - Record return → StepHandlerResult.success(record)
+ * - StepHandlerResult return → pass through unchanged
+ * - PermanentError thrown → StepHandlerResult.failure(retryable=false)
+ * - RetryableError thrown → StepHandlerResult.failure(retryable=true)
+ * - Other errors → StepHandlerResult.failure(retryable=true)
+ *
+ * @example
+ * ```typescript
+ * import { defineHandler, PermanentError } from 'tasker-core';
+ *
+ * const ProcessPayment = defineHandler('process_payment', {
+ *   depends: { cart: 'validate_cart' },
+ *   inputs: { paymentInfo: 'payment_info' },
+ * }, async ({ cart, paymentInfo, context }) => {
+ *   if (!paymentInfo) throw new PermanentError('Payment info required');
+ *   const result = await chargeCard(paymentInfo, cart.total);
+ *   return { paymentId: result.id, amount: cart.total };
+ * });
+ * ```
+ *
+ * @module handler/functional
+ */
+
+/**
+ * Base error for permanent, non-retryable failures.
+ *
+ * Throw this in functional handlers when the error will not succeed on retry.
+ *
+ * @example
+ * ```typescript
+ * throw new PermanentError('Invalid account number');
+ * ```
+ */
+declare class PermanentError extends Error {
+    readonly retryable = false;
+    readonly metadata: Record<string, unknown>;
+    constructor(message: string, metadata?: Record<string, unknown>);
+}
+/**
+ * Base error for transient, retryable failures.
+ *
+ * Throw this in functional handlers when a retry might succeed.
+ *
+ * @example
+ * ```typescript
+ * throw new RetryableError('Service temporarily unavailable');
+ * ```
+ */
+declare class RetryableError extends Error {
+    readonly retryable = true;
+    readonly metadata: Record<string, unknown>;
+    constructor(message: string, metadata?: Record<string, unknown>);
+}
+/**
+ * Options for defineHandler and related factory functions.
+ */
+interface HandlerOptions {
+    /** Mapping of parameter names to dependency step names */
+    depends?: Record<string, string>;
+    /** Mapping of parameter names to input data keys */
+    inputs?: Record<string, string>;
+    /** Handler version (default: "1.0.0") */
+    version?: string;
+}
+/**
+ * The injected arguments object passed to functional handlers.
+ *
+ * Contains declared dependencies, inputs, and always includes `context`.
+ */
+type HandlerArgs = Record<string, unknown> & {
+    context: StepContext;
+};
+/**
+ * Handler function signature.
+ */
+type HandlerFn = (args: HandlerArgs) => Promise<Record<string, unknown> | StepHandlerResult | undefined>;
+/**
+ * Helper for decision handler return values.
+ *
+ * @example
+ * ```typescript
+ * const RouteOrder = defineDecisionHandler('route_order', {
+ *   depends: { order: 'validate_order' },
+ * }, async ({ order }) => {
+ *   if (order.tier === 'premium') {
+ *     return Decision.route(['process_premium'], { tier: 'premium' });
+ *   }
+ *   return Decision.route(['process_standard']);
+ * });
+ * ```
+ */
+declare class Decision {
+    readonly type: 'create_steps' | 'no_branches';
+    readonly steps: string[];
+    readonly reason?: string | undefined;
+    readonly routingContext: Record<string, unknown>;
+    private constructor();
+    /**
+     * Route to the specified steps.
+     */
+    static route(steps: string[], routingContext?: Record<string, unknown>): Decision;
+    /**
+     * Skip all branches.
+     */
+    static skip(reason: string, routingContext?: Record<string, unknown>): Decision;
+}
+/**
+ * Configuration returned by batch analyzer handlers.
+ */
+interface BatchConfig {
+    totalItems: number;
+    batchSize: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Define a step handler from a function.
+ *
+ * Returns a StepHandler subclass that can be registered with HandlerRegistry.
+ * The function receives injected dependencies, inputs, and context.
+ * Return values are auto-wrapped as success results, and exceptions are
+ * auto-classified as failure results.
+ *
+ * @param name - Handler name (must match step definition)
+ * @param options - Dependencies, inputs, and version
+ * @param fn - Handler function
+ * @returns StepHandler subclass
+ *
+ * @example
+ * ```typescript
+ * const ProcessPayment = defineHandler('process_payment', {
+ *   depends: { cart: 'validate_cart' },
+ *   inputs: { paymentInfo: 'payment_info' },
+ * }, async ({ cart, paymentInfo, context }) => {
+ *   if (!paymentInfo) throw new PermanentError('Payment info required');
+ *   const result = await chargeCard(paymentInfo, cart.total);
+ *   return { paymentId: result.id, amount: cart.total };
+ * });
+ *
+ * // Register:
+ * registry.register(ProcessPayment);
+ * ```
+ */
+declare function defineHandler(name: string, options: HandlerOptions, fn: HandlerFn): StepHandlerClass;
+/**
+ * Define a decision handler from a function.
+ *
+ * The function should return a `Decision.route(...)` or `Decision.skip(...)`.
+ *
+ * @param name - Handler name
+ * @param options - Dependencies, inputs, and version
+ * @param fn - Handler function returning a Decision
+ * @returns StepHandler subclass
+ *
+ * @example
+ * ```typescript
+ * const RouteOrder = defineDecisionHandler('route_order', {
+ *   depends: { order: 'validate_order' },
+ * }, async ({ order }) => {
+ *   if (order.tier === 'premium') {
+ *     return Decision.route(['process_premium'], { tier: 'premium' });
+ *   }
+ *   return Decision.route(['process_standard']);
+ * });
+ * ```
+ */
+declare function defineDecisionHandler(name: string, options: HandlerOptions, fn: (args: HandlerArgs) => Promise<Decision | StepHandlerResult>): StepHandlerClass;
+/**
+ * Define a batch analyzer handler.
+ *
+ * The function should return a `BatchConfig` with `totalItems` and `batchSize`.
+ * Cursor configs are generated automatically.
+ *
+ * @param name - Handler name
+ * @param options - Handler options plus `workerTemplate`
+ * @param fn - Handler function returning a BatchConfig
+ * @returns StepHandler subclass
+ */
+declare function defineBatchAnalyzer(name: string, options: HandlerOptions & {
+    workerTemplate: string;
+}, fn: (args: HandlerArgs) => Promise<BatchConfig | StepHandlerResult>): StepHandlerClass;
+/**
+ * Define a batch worker handler.
+ *
+ * The function receives a `batchContext` parameter extracted from the step
+ * context, containing cursor configuration for this worker's partition.
+ *
+ * @param name - Handler name
+ * @param options - Dependencies, inputs, and version
+ * @param fn - Handler function receiving batch context
+ * @returns StepHandler subclass
+ */
+declare function defineBatchWorker(name: string, options: HandlerOptions, fn: (args: HandlerArgs & {
+    batchContext: BatchWorkerContext | null;
+}) => Promise<Record<string, unknown> | StepHandlerResult | undefined>): StepHandlerClass;
+/**
+ * Options for defineApiHandler.
+ */
+interface ApiHandlerOptions extends HandlerOptions {
+    /** Base URL for API calls */
+    baseUrl: string;
+    /** Default request timeout in milliseconds (default: 30000) */
+    defaultTimeout?: number;
+    /** Default headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * The injected arguments for API handlers, including the `api` object
+ * with pre-configured HTTP methods and result helpers.
+ *
+ * `api` is the handler instance itself with API methods applied (matching
+ * the Python/Ruby pattern where `api=self`).
+ */
+type ApiHandlerArgs = HandlerArgs & {
+    api: APICapable;
+};
+/**
+ * Define an API handler with HTTP client functionality.
+ *
+ * The function receives an `api` object providing pre-configured HTTP methods
+ * (get, post, put, patch, delete, request) and result helpers (apiSuccess,
+ * apiFailure, connectionError, timeoutError) from the APIMixin.
+ *
+ * @param name - Handler name (must match step definition)
+ * @param options - Dependencies, inputs, version, and API configuration
+ * @param fn - Handler function receiving api and other injected args
+ * @returns StepHandler subclass
+ *
+ * @example
+ * ```typescript
+ * const FetchUser = defineApiHandler('fetch_user', {
+ *   baseUrl: 'https://api.example.com',
+ *   depends: { userId: 'validate_user' },
+ * }, async ({ userId, api }) => {
+ *   const response = await api.get(`/users/${userId}`);
+ *   if (response.ok) {
+ *     return api.apiSuccess(response);
+ *   }
+ *   return api.apiFailure(response);
+ * });
+ * ```
+ */
+declare function defineApiHandler(name: string, options: ApiHandlerOptions, fn: (args: ApiHandlerArgs) => Promise<Record<string, unknown> | StepHandlerResult | undefined>): StepHandlerClass;
+
 /**
  * TAS-93: Handler definition type for resolver chain.
  *
@@ -3691,12 +3942,18 @@ declare class HandlerSystem {
      * Try to import an index file from the handler path.
      */
     private tryImportIndexFile;
+    /**
+     * TAS-294: Try to import the dsl_examples index file.
+     * This is separate from tryImportIndexFile because dsl_examples/ is a sibling
+     * directory to examples/, and both need to be loaded.
+     */
+    private tryImportDslExamplesIndex;
     /**
      * Register handlers from a module's exports.
      */
     private registerHandlersFromModule;
     /**
-     * Register handlers from ALL_EXAMPLE_HANDLERS array.
+     * Register handlers from a named handler array.
      */
     private registerFromHandlerArray;
     /**
@@ -4104,4 +4361,4 @@ declare class WorkerServer {
     private cleanupOnError;
 }
 
-export { type APICapable, APIMixin, ApiHandler, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, ClassLookupResolver, type CreateBatchesOutcome, type CreateTaskOptions, type CursorConfig, type DecisionCapable, DecisionHandler, DecisionMixin, type DecisionPointOutcome, DecisionType, DefaultPublisher, type DomainEvent, type DomainEventCallback, type DomainEventErrorCallback, type DomainEventMetadata, type DomainEventPollerConfig, DuplicatePublisherError, type EventDeclaration, EventPoller, EventSystem, ExecutableHandler, ExplicitMappingResolver, type FailureStrategy, FfiDomainEvent, FfiLayer, FfiLayerConfig, type HandlerDefinition, type HandlerEntry, type HandlerFactory, HandlerRegistry, type HandlerSpec, HandlerSystem, InProcessDomainEventPoller, type ListTasksOptions, type LogFields, MethodDispatchError, MethodDispatchWrapper, NapiModule, type NoBatchesOutcome, NoResolverMatchError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, type RustBatchWorkerInputs, type RustCursorConfig, type ServerComponents, type HealthCheckResult as ServerHealthCheckResult, type ServerState, type ServerStatus, ShutdownController, type ShutdownHandler, StepContext, type StepEventContext, StepExecutionSubscriber, StepHandler, StepHandlerClass, StepHandlerResult, type StepResult, type StopResult, type SubscriberClass, SubscriberRegistry, type SubscriberStats, TaskerClient, TaskerClientError, TaskerEventEmitter, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, effectiveMethod, ffiEventToDomainEvent, fromCallable, fromDto, getRustVersion, getVersion, getWorkerStatus, hasResolverHint, healthCheck, isCreateBatches, isNoBatches, isWorkerRunning, logDebug, logError, logInfo, logTrace, logWarn, noBatches, normalizeToDefinition, stopWorker, transitionToGracefulShutdown, usesMethodDispatch };
+export { type APICapable, APIMixin, ApiHandler, type ApiHandlerArgs, type ApiHandlerOptions, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchConfig, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, ClassLookupResolver, type CreateBatchesOutcome, type CreateTaskOptions, type CursorConfig, Decision, type DecisionCapable, DecisionHandler, DecisionMixin, type DecisionPointOutcome, DecisionType, DefaultPublisher, type DomainEvent, type DomainEventCallback, type DomainEventErrorCallback, type DomainEventMetadata, type DomainEventPollerConfig, DuplicatePublisherError, type EventDeclaration, EventPoller, EventSystem, ExecutableHandler, ExplicitMappingResolver, type FailureStrategy, FfiDomainEvent, FfiLayer, FfiLayerConfig, type HandlerArgs, type HandlerDefinition, type HandlerEntry, type HandlerFactory, type HandlerFn, type HandlerOptions, HandlerRegistry, type HandlerSpec, HandlerSystem, InProcessDomainEventPoller, type ListTasksOptions, type LogFields, MethodDispatchError, MethodDispatchWrapper, NapiModule, type NoBatchesOutcome, NoResolverMatchError, PermanentError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, RetryableError, type RustBatchWorkerInputs, type RustCursorConfig, type ServerComponents, type HealthCheckResult as ServerHealthCheckResult, type ServerState, type ServerStatus, ShutdownController, type ShutdownHandler, StepContext, type StepEventContext, StepExecutionSubscriber, StepHandler, StepHandlerClass, StepHandlerResult, type StepResult, type StopResult, type SubscriberClass, SubscriberRegistry, type SubscriberStats, TaskerClient, TaskerClientError, TaskerEventEmitter, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, defineApiHandler, defineBatchAnalyzer, defineBatchWorker, defineDecisionHandler, defineHandler, effectiveMethod, ffiEventToDomainEvent, fromCallable, fromDto, getRustVersion, getVersion, getWorkerStatus, hasResolverHint, healthCheck, isCreateBatches, isNoBatches, isWorkerRunning, logDebug, logError, logInfo, logTrace, logWarn, noBatches, normalizeToDefinition, stopWorker, transitionToGracefulShutdown, usesMethodDispatch };