Can we get more examples for createWorkflow

[soomtong]

Hi, I've been writing a lot of code lately that creates a context, bundles a task and a workflow and runs them.

However, I'm using a lot of any because I'm not familiar with the typing and definitions. For example,

const workflow = createWorkflow<BaseContext, any, any, any, void>(
  tap(() => console.log("Workflow started")),
  mainTask,
  tap(() => console.log("Workflow finished")),
);

How can we reduce that any?

It would be very helpful to have an example of type enforcement, especially for createWorkflow.

[doeixd]

The Definitive Guide to Type Safety in Effectively

The true power of Effectively is unlocked when you partner with the TypeScript compiler. The library is designed not just to be used with TypeScript, but to leverage its type inference engine to build workflows that are provably correct at compile time.

This guide will teach you how to write fully type-safe code in Effectively. When you master these concepts, you will almost never need to write any or manually specify a generic type argument again. A type error will no longer be an annoyance; it will be your most trusted co-pilot, pointing out logical flaws before they become runtime bugs.

The Four Pillars of Type Safety

1. The Foundation: Context Type Safety
2. The Building Blocks: Task Type Safety
3. The Blueprint: Workflow Type Safety
4. The Glue: Operator Type Safety

---

Pillar 1: The Foundation - Context Type Safety

Your entire application's type safety rests on a well-defined context. The context is your dependency injection container; giving it a strong type is the first and most critical step.

How It Works: createContext<C>

The createContext function is generic. You provide it with an interface that defines the "shape" of your application's dependencies. This creates a typed "bubble" for your application.

import { createContext, defineTask, getContext, type BaseContext } from '@doeixd/effectively';

// 1. Define your data models for clarity.
interface User { id: string; name: string; email: string; }

// 2. Define your context interface. It MUST extend BaseContext.
interface AppContext extends BaseContext {
  api: {
    fetchUser: (userId: string) => Promise<User>;
  };
  logger: Console;
}

// 3. Create your type-safe tools with default implementations.
const { run, defineTask: appDefineTask, getContext: getAppContext } = createContext<AppContext>({
  api: {
    fetchUser: async (userId) => ({ id: userId, name: 'Jane Doe', email: 'jane@example.com' }),
  },
  logger: console,
});

From this point on, every tool returned by createContext—run, defineTask, getContext—is permanently and safely bound to the AppContext type.

The Golden Rule of Context:
Inside any function executed by your specific run or provide, calling the corresponding getContext will return your fully typed AppContext. You get full autocompletion and compile-time validation.

const someTask = appDefineTask(async () => {
  const ctx = getAppContext();
  // `ctx` is now fully and safely typed as AppContext!
  ctx.logger.info(`Fetching user...`);
  // ctx.nonExistentProperty; // <-- TypeScript Error: Property 'nonExistentProperty' does not exist.
});

---

Pillar 2: The Building Blocks - Task Type Safety

A Task is the atomic unit of your workflow. Its type signature is a contract that tells createWorkflow how it can be connected to other tasks.

How It Works: Task<Context, InputValue, ReturnValue>

A task's type signature has three parts. When you use the defineTask function from your typed context, the Context generic is already handled. Your job is to correctly type the task's InputValue and its Promise of the ReturnValue.

// This task's signature is implicitly: Task<AppContext, string, User>
const fetchUserTask = appDefineTask(
  // InputValue: The task accepts a `string` (userId).
  async (userId: string): Promise<User> => { // ReturnValue: The task returns a `User`.
    const { api } = getAppContext();
    return api.fetchUser(userId);
  }
);

By being explicit with your function's parameters and its Promise<ReturnType>, you create a perfect, composable building block.

---

Pillar 3: The Blueprint - Workflow Type Safety

This is where the magic happens. createWorkflow inspects the type signature of every task you give it and validates that they form an unbroken, logical chain.

How It Works: The Type Chain

TypeScript checks that the ReturnValue of one task is assignable to the InputValue of the next.

graph LR
    subgraph createWorkflow
        A[Task 1 <br> In: string <br> Out: User] --> B[Task 2 <br> In: User <br> Out: string];
        B --> C[Task 3 <br> In: string <br> Out: void];
    end
    Input[Workflow Input <br> string] --> A;
    C --> Output[Workflow Output <br> void];

Loading

The Golden Rule of Workflows:
NEVER manually provide the generic types for createWorkflow.
Let TypeScript infer them. If you get a type error, it means you have a bug in your logic—the type chain is broken. This is the library working as designed to help you.

✅ Correct, Type-Inferred Workflow:
The User output from fetchUserTask perfectly matches the User input of the next step.

const processUserWorkflow = createWorkflow(
  fetchUserTask,         // Input: string, Output: User
  (user: User) => `Welcome, ${user.name}!`, // Lifted function. Input: User, Output: string
  logMessageTask         // Input: string, Output: void
);
// Inferred final type: Task<AppContext, string, void>

❌ Incorrect, Mismatched Workflow:
The User output from fetchUserTask does not match the string input expected by logMessageTask.

const brokenWorkflow = createWorkflow(
  fetchUserTask,      // Output: User
  logMessageTask      // ERROR! This task expects a string, but is given a User.
);
// TypeScript Error: Argument of type 'Task<AppContext, User, any>' is not assignable to parameter of type 'Task<AppContext, string, any>'.

This compile-time error is invaluable. It has just saved you from a runtime TypeError.

---

Pillar 4: The Glue - Operator Type Safety

Pipeable operators like map and tap are also tasks and participate in the type chain. Understanding their distinct roles is key to using them without resorting to any.

• map(fn): A Transformer
  The purpose of map is to transform the value. The type chain is therefore altered.

  import { map } from '@doeixd/effectively';
  
  const getUserNameWorkflow = createWorkflow(
    fetchUserTask,              // Input: string, Output: User
    map((user: User) => user.name) // Input: User, Output: string
  );
  // Inferred final type: Task<AppContext, string, string>

• tap(fn): A Pass-Through Observer
  The purpose of tap is to perform a side-effect (like logging) and pass the original value through unmodified. The type chain is preserved.

  import { tap } from '@doeixd/effectively';
  
  const workflowWithLogging = createWorkflow(
    fetchUserTask,                             // Input: string, Output: User
    tap((user: User) => console.log(user.id)), // Input: User, Output: User
    formatUserMessageTask                      // Still correctly receives a User
  );
  // Inferred final type: string (from formatUserMessageTask)

---

Deep Dive: How Generics and Inference Actually Work

Let's demystify the inference process. Consider this workflow:

const workflow = createWorkflow(taskA, taskB, taskC);

Here's how TypeScript determines the final type, Task<C, V, R>:

1. C (Context): It inspects taskA, taskB, and taskC. It finds the most specific Context type they all share. If they were all made with createContext<AppContext>(), then C becomes AppContext.
2. V (InputValue): It looks only at the first task, taskA. It takes taskA's input type and makes that the input type for the entire workflow.
3. The Chain: It then checks if the output of taskA matches the input of taskB, and if the output of taskB matches the input of taskC. If not, you get a compile error.
4. R (ReturnValue): It looks only at the last task, taskC. It takes taskC's return type and makes that the return type for the entire workflow.

This is why any is so destructive: if taskB has an input type of any, it will accept the output of taskA no matter what it is, breaking the type chain and hiding potential bugs.

---

Common Patterns and Advanced Scenarios

Pattern: Passing Data Through a Workflow

Problem: A task late in the chain needs data from a task early in the chain, but the intermediate steps have transformed the data.

Solution: Pass an object or tuple through the workflow.

import { map } from '@doeixd/effectively';

const generateAndSendInvoice = createWorkflow(
  // Step 1: Input: string (userId) -> Output: User
  fetchUser,
  
  // Step 2: Input: User -> Output: { user: User, invoice: Invoice }
  // Use `map` to transform the data shape to include both the original user and the new invoice.
  map(async (user: User) => {
    const { api } = getAppContext();
    const invoice = await api.createInvoice(user);
    return { user, invoice }; // Pass both pieces of data forward
  }),
  
  // Step 3: Input: { user: User, invoice: Invoice } -> Output: { success: boolean }
  appDefineTask(async (data: { user: User; invoice: Invoice }) => {
    const { api } = getAppContext();
    return api.sendEmail(data.user.email, `Invoice #${data.invoice.id}`, `...`);
  })
);

// Final inferred type: Task<AppContext, string, { success: boolean }>

Pattern: Handling Result Types

Workflows seamlessly handle Result types from neverthrow.

import { Result, ok, err } from 'neverthrow';

const validateInput = appDefineTask(
  (id: string): Result<string, Error> => id ? ok(id) : err(new Error('ID is empty'))
);

const processWorkflow = createWorkflow(
  validateInput,
  map((result: Result<string, Error>) => 
    result.match(
      (validId) => `Processed: ${validId}`, // Handle Ok case
      (error) => `Error: ${error.message}` // Handle Err case
    )
  )
);
// Final inferred type: Task<AppContext, string, string>

---

Troubleshooting & Gotchas

• Symptom: My workflow type is Task<any, any, any>.

  • Cause: One or more tasks in your chain have an any type, or you haven't provided enough type information for a plain function to be inferred correctly.
  • Solution: Go through each task and ensure its input parameters and Promise<ReturnType> are explicitly typed.

• Symptom: I'm getting a long, confusing type error from createWorkflow.

  • Cause: The type chain is broken.
  • Solution: Look for the core of the message: Argument of type 'Task<..., A, B>' is not assignable to parameter of type 'Task<..., C, D>'. The mismatch is between B and C. Find the task that returns B and the one that expects C and fix the logic.

• Symptom: How do I type the callback for tap or map?

  • Solution: Be explicit. It helps both you and the compiler.
  • tap((user: User) => { ... })
  • map((user: User): string => { ... })

• Symptom: My workflow starts with fromValue. What is its input type?

  • Cause: fromValue, fromPromise, and fromPromiseFn are designed to start a workflow without an initial input from the run call.
  • Solution: The workflow's input type will be null or void.

    import { fromValue } from '@doeixd/effectively';
    const workflow = createWorkflow(fromValue(42), (n: number) => n * 2);
    // Inferred type: Task<..., null, number>
    await run(workflow, null);

[doeixd]

Your original problem was that you were forced to use any because you weren't sure how to correctly type your workflows, as shown in this example:

// Your original code
const workflow = createWorkflow<BaseContext, any, any, any, void>(
  tap(() => console.log("Workflow started")),
  mainTask,
  tap(() => console.log("Workflow finished")),
);

The comprehensive guide solves this exact problem by explaining the core principles that allow TypeScript to do the work for you, completely eliminating the need for any.

Let's connect the dots and show precisely how the guide addresses this with a direct "before and after" refactoring of your code.

How the Guide Directly Solves Your Problem

The guide addresses your question in several key ways:

1. It tells you to STOP manually typing createWorkflow: The "Golden Rule of Workflows" section explicitly states: "dont manually provide the generic types for createWorkflow." This is the direct answer to your core issue. By providing <BaseContext, any, any, any, void>, you were overriding TypeScript's powerful inference engine.

2. It shows you WHAT to type instead: "Pillar 2: Task Type Safety" explains that the foundation is to create strongly-typed Task building blocks. If you give createWorkflow well-typed inputs, it can infer the fully-typed output.

3. It explains HOW the types connect: The "Type Chain" concept in "Pillar 3" shows that the ReturnValue of one task must match the InputValue of the next. This is the logic TypeScript uses and is the key to debugging type errors.

4. It clarifies how tap works: "Pillar 4" explains that tap is a "pass-through" operator. This is crucial for your example, as it means the type of data flowing out of tap is the same as the type flowing in.

Direct Refactoring of Your Example Using the Guide's Principles

Let's apply the guide's principles to refactor your code and eliminate every any.

Assumptions:

• Let's assume your mainTask should accept a jobId (a string) as input.
• Let's assume it returns a result object, like { success: boolean; message: string; }.
• We will use a properly defined AppContext.

---

Before: The any Version

// The original problem: using `any` overrides type inference.
const workflow = createWorkflow<BaseContext, any, any, any, void>(
  tap(() => console.log("Workflow started")),
  mainTask, // The types of mainTask are unknown to the workflow
  tap(() => console.log("Workflow finished")),
);

Here, TypeScript has no information to work with, so it can't help you.

---

After: The Fully Type-Safe Version

import { createContext, defineTask, createWorkflow, tap, type BaseContext } from '@doeixd/effectively';

// Pillar 1: Define a typed context and tools.
interface AppContext extends BaseContext { logger: Console; }
const { run, defineTask: appDefineTask } = createContext<AppContext>({ logger: console });

// Define a clear return type for your main task.
interface MainTaskResult {
  success: boolean;
  message: string;
}

// Pillar 2: Define your main task with explicit types.
// This is the most important step.
const mainTask = appDefineTask(
  // InputValue is `string`
  async (jobId: string): Promise<MainTaskResult> => { // ReturnValue is `MainTaskResult`
    console.log(`Running main task for job: ${jobId}`);
    // ... your actual logic ...
    return { success: true, message: `Job ${jobId} completed.` };
  }
);

// Pillar 3 & 4: Compose the workflow and let TypeScript infer everything.
const processJobWorkflow = createWorkflow(
  // This tap is the first step. The workflow's input type is inferred from it.
  // It receives a string and passes it through, so its Input/Output is `string`.
  tap((jobId: string) => console.log(`Workflow started for job: ${jobId}`)),

  // `mainTask` correctly receives a `string` from the previous tap.
  // Its output is `MainTaskResult`.
  mainTask,

  // This final tap receives `MainTaskResult` from mainTask.
  // It passes it through, so the workflow's final output is `MainTaskResult`.
  tap((result: MainTaskResult) => console.log(`Workflow finished with success: ${result.success}`)),
);

// TypeScript has now correctly inferred the final type:
// const processJobWorkflow: Task<AppContext, string, MainTaskResult>

// Now you can run it with full type safety.
async function execute() {
  const result = await run(processJobWorkflow, 'job-123');
  console.log(result.message); // Autocompletes .message and .success!
  // console.log(result.foo); // <-- TypeScript Error!
}

Conclusion

By focusing on defining strongly-typed tasks first, you empower createWorkflow to act as your automated type-checker, building a complete, safe, and self-documenting asynchronous pipeline without a single any in sight.