@temporal-contract/client 0.0.3 → 0.0.5

package/dist/index.d.mts

@@ -1,71 +1,196 @@
 import { ClientOptions, WorkflowHandle, WorkflowOptions, WorkflowStartOptions } from "@temporalio/client";
-import { ClientInferInput, ClientInferOutput, ClientInferWorkflowQueries, ClientInferWorkflowSignals, ClientInferWorkflowUpdates, ContractDefinition, WorkflowDefinition } from "@temporal-contract/contract";
+import { Future, Result } from "@temporal-contract/boxed";
+import { ActivityDefinition, AnySchema, ContractDefinition, QueryDefinition, SignalDefinition, UpdateDefinition, WorkflowDefinition } from "@temporal-contract/contract";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
-//#region src/client.d.ts
+//#region src/types.d.ts
 
+/**
+ * Infer input type from a definition (client perspective)
+ * Client sends the input type (before input schema parsing/transformation)
+ */
+type ClientInferInput<T extends {
+  input: AnySchema;
+}> = StandardSchemaV1.InferInput<T["input"]>;
+/**
+ * Infer output type from a definition (client perspective)
+ * Client receives the output type (after output schema parsing/transformation)
+ */
+type ClientInferOutput<T extends {
+  output: AnySchema;
+}> = StandardSchemaV1.InferOutput<T["output"]>;
+/**
+ * CLIENT PERSPECTIVE
+ * Client sends z.output and receives z.input
+ */
+/**
+ * Infer workflow function signature from client perspective
+ * Client sends z.output and receives z.input
+ */
+type ClientInferWorkflow<TWorkflow extends WorkflowDefinition> = (args: ClientInferInput<TWorkflow>) => Promise<ClientInferOutput<TWorkflow>>;
+/**
+ * Infer activity function signature from client perspective
+ * Client sends z.output and receives z.input
+ */
+type ClientInferActivity<TActivity extends ActivityDefinition> = (args: ClientInferInput<TActivity>) => Promise<ClientInferOutput<TActivity>>;
+/**
+ * Infer signal handler signature from client perspective
+ * Client sends z.output and returns Future<Result<void, Error>>
+ */
+type ClientInferSignal<TSignal extends SignalDefinition> = (args: ClientInferInput<TSignal>) => Future<Result<void, Error>>;
+/**
+ * Infer query handler signature from client perspective
+ * Client sends z.output and receives z.input wrapped in Future<Result<T, Error>>
+ */
+type ClientInferQuery<TQuery extends QueryDefinition> = (args: ClientInferInput<TQuery>) => Future<Result<ClientInferOutput<TQuery>, Error>>;
+/**
+ * Infer update handler signature from client perspective
+ * Client sends z.output and receives z.input wrapped in Future<Result<T, Error>>
+ */
+type ClientInferUpdate<TUpdate extends UpdateDefinition> = (args: ClientInferInput<TUpdate>) => Future<Result<ClientInferOutput<TUpdate>, Error>>;
+/**
+ * CLIENT PERSPECTIVE - Contract-level types
+ */
+/**
+ * Infer all workflows from a contract (client perspective)
+ */
+type ClientInferWorkflows<TContract extends ContractDefinition> = { [K in keyof TContract["workflows"]]: ClientInferWorkflow<TContract["workflows"][K]> };
+/**
+ * Infer all activities from a contract (client perspective)
+ */
+type ClientInferActivities<TContract extends ContractDefinition> = TContract["activities"] extends Record<string, ActivityDefinition> ? { [K in keyof TContract["activities"]]: ClientInferActivity<TContract["activities"][K]> } : {};
+/**
+ * Infer activities from a workflow definition (client perspective)
+ */
+type ClientInferWorkflowActivities<T extends WorkflowDefinition> = T["activities"] extends Record<string, ActivityDefinition> ? { [K in keyof T["activities"]]: ClientInferActivity<T["activities"][K]> } : {};
+/**
+ * Infer signals from a workflow definition (client perspective)
+ */
+type ClientInferWorkflowSignals<T extends WorkflowDefinition> = T["signals"] extends Record<string, SignalDefinition> ? { [K in keyof T["signals"]]: ClientInferSignal<T["signals"][K]> } : {};
+/**
+ * Infer queries from a workflow definition (client perspective)
+ */
+type ClientInferWorkflowQueries<T extends WorkflowDefinition> = T["queries"] extends Record<string, QueryDefinition> ? { [K in keyof T["queries"]]: ClientInferQuery<T["queries"][K]> } : {};
+/**
+ * Infer updates from a workflow definition (client perspective)
+ */
+type ClientInferWorkflowUpdates<T extends WorkflowDefinition> = T["updates"] extends Record<string, UpdateDefinition> ? { [K in keyof T["updates"]]: ClientInferUpdate<T["updates"][K]> } : {};
+/**
+ * Infer all activities available in a workflow context (client perspective)
+ * Combines workflow-specific activities with global activities
+ */
+type ClientInferWorkflowContextActivities<TContract extends ContractDefinition, TWorkflowName extends keyof TContract["workflows"]> = ClientInferWorkflowActivities<TContract["workflows"][TWorkflowName]> & ClientInferActivities<TContract>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base class for all typed client errors with boxed pattern
+ */
+declare class TypedClientError extends Error {
+  constructor(message: string);
+}
+/**
+ * Thrown when a workflow is not found in the contract
+ */
+declare class WorkflowNotFoundError extends TypedClientError {
+  readonly workflowName: string;
+  readonly availableWorkflows: string[];
+  constructor(workflowName: string, availableWorkflows: string[]);
+}
+/**
+ * Thrown when workflow input or output validation fails
+ */
+declare class WorkflowValidationError extends TypedClientError {
+  readonly workflowName: string;
+  readonly direction: "input" | "output";
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(workflowName: string, direction: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+/**
+ * Thrown when query input or output validation fails
+ */
+declare class QueryValidationError extends TypedClientError {
+  readonly queryName: string;
+  readonly direction: "input" | "output";
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(queryName: string, direction: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+/**
+ * Thrown when signal input validation fails
+ */
+declare class SignalValidationError extends TypedClientError {
+  readonly signalName: string;
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(signalName: string, issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+/**
+ * Thrown when update input or output validation fails
+ */
+declare class UpdateValidationError extends TypedClientError {
+  readonly updateName: string;
+  readonly direction: "input" | "output";
+  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+  constructor(updateName: string, direction: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+//#endregion
+//#region src/client.d.ts
 /**
  * Extended options for starting workflows with Temporal-specific features
  * Combines required workflowId with optional Temporal workflow options
  */
 type TypedWorkflowStartOptions = Pick<WorkflowStartOptions, "workflowId" | "workflowIdReusePolicy" | "workflowExecutionTimeout" | "workflowRunTimeout" | "workflowTaskTimeout" | "retry" | "memo" | "searchAttributes" | "cronSchedule"> & Pick<WorkflowOptions, "workflowId">;
 /**
- * Typed workflow handle with validated results, queries, signals and updates
+ * Typed workflow handle with validated results using Result/Future pattern
  */
 interface TypedWorkflowHandle<TWorkflow extends WorkflowDefinition> {
   workflowId: string;
   /**
-   * Type-safe queries based on workflow definition
+   * Type-safe queries based on workflow definition with Result pattern
+   * Each query returns Future<Result<T, Error>> instead of Promise<T>
    */
-  queries: ClientInferWorkflowQueries<TWorkflow>;
+  queries: { [K in keyof ClientInferWorkflowQueries<TWorkflow>]: ClientInferWorkflowQueries<TWorkflow>[K] extends ((...args: infer Args) => Future<Result<infer R, Error>>) ? (...args: Args) => Future<Result<R, TypedClientError>> : never };
   /**
-   * Type-safe signals based on workflow definition
+   * Type-safe signals based on workflow definition with Result pattern
+   * Each signal returns Future<Result<void, Error>> instead of Promise<void>
    */
-  signals: ClientInferWorkflowSignals<TWorkflow>;
+  signals: { [K in keyof ClientInferWorkflowSignals<TWorkflow>]: ClientInferWorkflowSignals<TWorkflow>[K] extends ((...args: infer Args) => Future<Result<void, Error>>) ? (...args: Args) => Future<Result<void, TypedClientError>> : never };
   /**
-   * Type-safe updates based on workflow definition
+   * Type-safe updates based on workflow definition with Result pattern
+   * Each update returns Future<Result<T, Error>> instead of Promise<T>
    */
-  updates: ClientInferWorkflowUpdates<TWorkflow>;
-  result: () => Promise<ClientInferOutput<TWorkflow>>;
-  terminate: (reason?: string) => Promise<void>;
-  cancel: () => Promise<void>;
+  updates: { [K in keyof ClientInferWorkflowUpdates<TWorkflow>]: ClientInferWorkflowUpdates<TWorkflow>[K] extends ((...args: infer Args) => Future<Result<infer R, Error>>) ? (...args: Args) => Future<Result<R, TypedClientError>> : never };
+  /**
+   * Get workflow result with Result pattern
+   */
+  result: () => Future<Result<ClientInferOutput<TWorkflow>, TypedClientError>>;
+  /**
+   * Terminate workflow with Result pattern
+   */
+  terminate: (reason?: string) => Future<Result<void, TypedClientError>>;
+  /**
+   * Cancel workflow with Result pattern
+   */
+  cancel: () => Future<Result<void, TypedClientError>>;
   /**
    * Get workflow execution description including status and metadata
-   *
-   * @example
-   * ```ts
-   * const handle = await client.getHandle('processOrder', 'order-123');
-   * const description = await handle.describe();
-   * console.log(description.workflowExecutionInfo.status); // RUNNING, COMPLETED, etc.
-   * ```
    */
-  describe: () => ReturnType<WorkflowHandle["describe"]>;
+  describe: () => Future<Result<Awaited<ReturnType<WorkflowHandle["describe"]>>, TypedClientError>>;
   /**
    * Fetch the workflow execution history
-   *
-   * @example
-   * ```ts
-   * const handle = await client.getHandle('processOrder', 'order-123');
-   * const history = handle.fetchHistory();
-   * for await (const event of history) {
-   *   console.log(event);
-   * }
-   * ```
    */
   fetchHistory: () => ReturnType<WorkflowHandle["fetchHistory"]>;
 }
 /**
- * Typed Temporal client based on a contract
+ * Typed Temporal client with Result/Future pattern based on a contract
  *
  * Provides type-safe methods to start and execute workflows
- * defined in the contract.
+ * defined in the contract, with explicit error handling using Result pattern.
  */
 declare class TypedClient<TContract extends ContractDefinition> {
   private readonly contract;
   private readonly client;
   private constructor();
   /**
-   * Create a typed Temporal client from a contract
+   * Create a typed Temporal client with boxed pattern from a contract
    *
    * @example
    * ```ts
@@ -77,24 +202,35 @@ declare class TypedClient<TContract extends ContractDefinition> {
    *
    * const result = await client.executeWorkflow('processOrder', {
    *   workflowId: 'order-123',
-   *   args: [...],
+   *   args: { ... },
+   * });
+   *
+   * result.match({
+   *   Ok: (output) => console.log('Success:', output),
+   *   Error: (error) => console.error('Failed:', error),
    * });
    * ```
    */
   static create<TContract extends ContractDefinition>(contract: TContract, options: ClientOptions): TypedClient<TContract>;
   /**
-   * Start a workflow and return a typed handle
+   * Start a workflow and return a typed handle with Future pattern
    *
    * @example
    * ```ts
-   * const handle = await client.startWorkflow('processOrder', {
+   * const handleResult = await client.startWorkflow('processOrder', {
    *   workflowId: 'order-123',
-   *   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+   *   args: { orderId: 'ORD-123' },
    *   workflowExecutionTimeout: '1 day',
    *   retry: { maximumAttempts: 3 },
    * });
    *
-   * const result = await handle.result();
+   * handleResult.match({
+   *   Ok: async (handle) => {
+   *     const result = await handle.result();
+   *     // ... handle result
+   *   },
+   *   Error: (error) => console.error('Failed to start:', error),
+   * });
    * ```
    */
   startWorkflow<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, {
@@ -102,20 +238,23 @@ declare class TypedClient<TContract extends ContractDefinition> {
     ...temporalOptions
   }: TypedWorkflowStartOptions & {
     args: ClientInferInput<TContract["workflows"][TWorkflowName]>;
-  }): Promise<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>>;
+  }): Future<Result<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>, TypedClientError>>;
   /**
-   * Execute a workflow (start and wait for result)
+   * Execute a workflow (start and wait for result) with Future/Result pattern
    *
    * @example
    * ```ts
    * const result = await client.executeWorkflow('processOrder', {
    *   workflowId: 'order-123',
-   *   args: ['ORD-123', 'CUST-456', [{ productId: 'PROD-1', quantity: 2 }]],
+   *   args: { orderId: 'ORD-123' },
    *   workflowExecutionTimeout: '1 day',
    *   retry: { maximumAttempts: 3 },
    * });
    *
-   * console.log(result.status); // fully typed!
+   * result.match({
+   *   Ok: (output) => console.log('Order processed:', output.status),
+   *   Error: (error) => console.error('Processing failed:', error),
+   * });
    * ```
    */
   executeWorkflow<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, {
@@ -123,69 +262,24 @@ declare class TypedClient<TContract extends ContractDefinition> {
     ...temporalOptions
   }: TypedWorkflowStartOptions & {
     args: ClientInferInput<TContract["workflows"][TWorkflowName]>;
-  }): Promise<ClientInferOutput<TContract["workflows"][TWorkflowName]>>;
+  }): Future<Result<ClientInferOutput<TContract["workflows"][TWorkflowName]>, TypedClientError>>;
   /**
-   * Get a handle to an existing workflow
+   * Get a handle to an existing workflow with Future/Result pattern
    *
    * @example
    * ```ts
-   * const handle = await client.getHandle('processOrder', 'order-123');
-   * const result = await handle.result();
+   * const handleResult = await client.getHandle('processOrder', 'order-123');
+   * handleResult.match({
+   *   Ok: async (handle) => {
+   *     const result = await handle.result();
+   *     // ... handle result
+   *   },
+   *   Error: (error) => console.error('Failed to get handle:', error),
+   * });
    * ```
    */
-  getHandle<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, workflowId: string): Promise<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>>;
+  getHandle<TWorkflowName extends keyof TContract["workflows"]>(workflowName: TWorkflowName, workflowId: string): Future<Result<TypedWorkflowHandle<TContract["workflows"][TWorkflowName]>, TypedClientError>>;
   private createTypedHandle;
 }
 //#endregion
-//#region src/errors.d.ts
-/**
- * Base error class for typed client errors
- */
-declare class TypedClientError extends Error {
-  constructor(message: string);
-}
-/**
- * Error thrown when a workflow is not found in the contract
- */
-declare class WorkflowNotFoundError extends TypedClientError {
-  readonly workflowName: string;
-  readonly availableWorkflows: readonly string[];
-  constructor(workflowName: string, availableWorkflows?: readonly string[]);
-}
-/**
- * Error thrown when workflow input or output validation fails
- */
-declare class WorkflowValidationError extends TypedClientError {
-  readonly workflowName: string;
-  readonly phase: "input" | "output";
-  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
-  constructor(workflowName: string, phase: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
-}
-/**
- * Error thrown when query input or output validation fails
- */
-declare class QueryValidationError extends TypedClientError {
-  readonly queryName: string;
-  readonly phase: "input" | "output";
-  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
-  constructor(queryName: string, phase: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
-}
-/**
- * Error thrown when signal input validation fails
- */
-declare class SignalValidationError extends TypedClientError {
-  readonly signalName: string;
-  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
-  constructor(signalName: string, issues: ReadonlyArray<StandardSchemaV1.Issue>);
-}
-/**
- * Error thrown when update input or output validation fails
- */
-declare class UpdateValidationError extends TypedClientError {
-  readonly updateName: string;
-  readonly phase: "input" | "output";
-  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
-  constructor(updateName: string, phase: "input" | "output", issues: ReadonlyArray<StandardSchemaV1.Issue>);
-}
-//#endregion
-export { QueryValidationError, SignalValidationError, TypedClient, TypedClientError, type TypedWorkflowHandle, type TypedWorkflowStartOptions, UpdateValidationError, WorkflowNotFoundError, WorkflowValidationError };
+export { type ClientInferActivities, type ClientInferActivity, type ClientInferInput, type ClientInferOutput, type ClientInferQuery, type ClientInferSignal, type ClientInferUpdate, type ClientInferWorkflow, type ClientInferWorkflowActivities, type ClientInferWorkflowContextActivities, type ClientInferWorkflowQueries, type ClientInferWorkflowSignals, type ClientInferWorkflowUpdates, type ClientInferWorkflows, QueryValidationError, SignalValidationError, TypedClient, TypedClientError, type TypedWorkflowHandle, type TypedWorkflowStartOptions, UpdateValidationError, WorkflowNotFoundError, WorkflowValidationError };