DEV Community: Max Khramtsov

Effect: Schema optimisation with synchronous transformations

Max Khramtsov — Fri, 27 Jun 2025 06:44:18 +0000

Got interested in this optimisation in Schema — and decided to find out how it works under the hood:

If you want more perf you can use ParseResult.flatMap instead of Effect.gen and get eager optimisation skipping the Effect runtime.
— Michael Arnaldi

// Detect dark theme var iframe = document.getElementById('tweet-1930250026896220482-642'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1930250026896220482&theme=dark" }

Given

Schema.transformOrFail transformers are expected to return Effect<T, ParseResult.ParseIssue, R>. However, for example, Either is a subtype of Effect, so returning Either<T, ParseResult.ParseIssue> is also valid.

The idea

If a schema only uses Either-transformations, then its decoders/encoders can be run without involving the runtime.

The optimisation

For convenience, the following type is used in the schema:

type ParseResult<A> = Either<A, ParseResult.ParseIssue>

We need to preserve the transformation type as Either and not convert it to Effect — this is handled by functions in ParseResult under the @category optimisation, such as ParseResult.flatMap.
These helpers are primarily used in the ParseResult.go function, which is responsible for walking through all AST nodes of the schema and producing a ParseResult.Parser — the actual encode/decode function.
ParseResult.handleForbidden is the function where the final decision to use the runtime or not is made.

The requirements

From its implementation, it's clear that in order for the optimisation ritual to work, two conditions must be met:

The user's intention — to invoke the validate/decode/encode family of functions with the Either/Option/Sync suffix (synchronously)
The schema's capability — using ParseResult<A>(alias for Either) specifically in transformations.

Otherwise, the optimisation won’t apply — and the runtime with the synchronous scheduler will be used, which seems effectively the same as Effect.runSync.

The notes

However, it's also important to note that the schema annotations concurrent and batching will not be applied to synchronous transformations — meaning that here, transformations take precedence.

Optimisation through synchronous transformations with ParseResult potentially improves performance by bypassing the Effect runtime. However, I did not conduct any benchmarks; my interest was solely in how the optimisation is implemented.

I hope this overview will be useful to developers when making design decisions and that it’s helpful to know such an optimisation exists.

Scheduling in Effect: Understanding and Implementing

Max Khramtsov — Mon, 03 Feb 2025 12:24:49 +0000

In this article, I want to talk about schedules in Effect and, for better understanding and fun, implement my own with Promises.

A Schedule is an abstraction for managing the repetition of effects, determining how many times and at what intervals an operation should be executed or restarted. In tools like Effect, schedules are often used to handle retry logic in error handling or to simply repeat effects.

In Effect, schedules consist of the following components:

Schedule: Defines the initial state and a function that, given the current state and input, returns a triple: [new state, output value, decision].
Decision: Indicates whether to continue execution or terminate, and whether to resume immediately or after a delay.
Driver: Essentially a stateful iterator that manages the schedule’s state while exposing only input → output logic externally.

To better understand how this works, I decided to create a simplified model using Promises. Below is a TypeScript example.

interface Schedule<Out, In = unknown, S = any> {
  readonly initial: S;
  readonly step: (input: In, currentState: S) => [newState: S, Out, Decision];
}

type Decision = 
  | { tag: "Continue"; delay: 0 | number } // will use 0 for sync execution
  | { tag: "Done" };

interface Driver<Out, In, S> {
  private state: S;
  constructor(readonly schedule: Schedule<Out, In, S>);
  next(input: In): Promise<Out>;
}

PoC

To start, let's assemble a Proof of Concept to understand how everything will work together.

Schedule

Schedule — a regular class with a pipe method for convenience.

class Schedule<out Out, in In = unknown, in out S = any> {
  constructor( 
    readonly initial: S,
    readonly step: (input: In, state: S) => [state: S, out: Out, Decision],
  ) {}
  pipe<B>(f: (value: this) => B) {
    return f(this);
  }
}

Now let's write the simplest Schedule for generating infinite sequences from a single value — unfold. (similar to the inverse of Array.reduce)

const unfold = <A>(initial: A, f: (a: A) => A): Schedule<A, unknown, A> =>
  new Schedule<A, unknown, A>(initial, (_, state) => [
    f(state), // new state
    state,    // output value
    { tag: "Continue", delay: 0 }, // immediate continuation
  ]);

And use it for count (0-1-2-3-...). We initialize it with the starting value 0 and provide a stepping function:

const count = unfold(0, (x) => x + 1);

Driver

The driver stores the current state returned by the Schedule and feeds it back on the next iteration. It can reset to its initial state since that information is embedded in the schedule itself. The repeat function loops, calling driver.next and executing the effect until a terminal signal is received.


class Driver<Out, In, S> {
  private state: S;
  private readonly schedule: Schedule<Out, In, S>;

  constructor(schedule: Schedule<Out, In, S>) {
    this.schedule = schedule;
    this.state = schedule.initial;
  }

  async next(input: In) {
    const [state, out, decision] = this.schedule.step(input, this.state);

    this.state = state;

    if (decision.tag === "Done") {
      return null;
    } else {
      await Driver.sleep(decision.delay);
    }

    return out;
  }

  private static sleep = (duration: number) =>
    new Promise((res) => setTimeout(() => res(void 0), duration));
}

Repeating

So, let's finally write a function to repeat an action according to a schedule. It takes the action and the schedule as arguments, and internally creates a driver to coordinate the execution of the task with the schedule.

const repeat = async <T,>(
  task: () => Promise<T>,
  schedule: Schedule<any, T>,
) => {
  const driver = new Driver(schedule);

  while (true) {
    const result = await task();
    const next = await driver.next(result);

    if (next === null) {
      return result;
    }
  }
};

Result

Now, let's put everything together and run it.

const logTask = () => console.log("logTask")

repeat(
  logTask(0), 
  count
);
// "logTask"
// "logTask"
// ... infinity ...

Here we have figured out the mechanism for executing and applying schedules!
Now, let’s dive into composing schedules to create more complex ones from smaller, simpler pieces.

Fibonacci Scheduler

Let’s define a Schedule that fires five times with Fibonacci sequence intervals: 0, 1, 1, 2, and 3 seconds.

const fibonacci = unfold<[number, number]>(
  [0, 1], 
  ([prev, cur]) => [cur, cur + prev]
);

Let’s now write a map function that transforms a schedule’s output by applying a given function to its results. We will use it on order to extract second member from tuple generated by fibonacci function.

const map = <Out, Out1>(f: (out: Out) => Out1) =>
  <In, S>(schedule: Schedule<Out, In, S>) =>
    new Schedule<Out1, In, S>(schedule.initial, (input, state) => {
      const [_state, _out, _decision] = schedule.step(input, state);
      return [_state, f(_out), _decision]; // f(_out) - mapping
    });

Other Combinators

Most other combinators follow a similar structure:

They return a new Schedule
They pass through the initial state
They modify the step function in some way

For example, the check takes a Schedule and a predicate to be applied to its result. If the predicate returns false, it changes the Decision of the original schedule to Done.

const check =
  <Out, In>(predicate: (in_: In, out: Out) => boolean) =>
  <S,>(schedule: Schedule<Out, In, S>) =>
    new Schedule<Out, In, S>(schedule.initial, (input, state) => {
      const [_state, _out, _decision] = schedule.step(input, state);

      if (_decision.tag === "Continue") {
        if (predicate(input, _out)) {
          return [_state, _out, _decision] as const;
        } else {
          return [_state, _out, { tag: "Done" }] as const; // Done
        }
      }

      return [_state, _out, _decision] as const;
    });

By combining count and check, we can create recurs — a schedule that will run only a specified number of times.

const recurs = (n: number) => count
  .pipe(check((_, out) => out + 1 <= n));

The intersect combinator takes two schedules and creates a new one by processing their results. It stops if either schedule decides to terminate. If both emit values, the smallest delay is chosen.

const intersect =
  <Out, In, S>(scheduleA: Schedule<Out, In, S>) =>
  <Out1, In1, S1>(scheduleB: Schedule<Out1, In1, S1>) =>
    new Schedule<[Out, Out1], In & In1, [S, S1]>(
      [scheduleA.initial, scheduleB.initial] as const,
      (input, [stateA, stateB]) => {
        const [_stateA, _outA, _decisionA] = scheduleA.step(input, stateA);
        const [_stateB, _outB, _decisionB] = scheduleB.step(input, stateB);

        let _decision: Decision = { tag: "Done" };

        if (_decisionA.tag === "Continue" && _decisionB.tag === "Continue") {
          _decision = {
            tag: "Continue",
            delay:
              _decisionA.delay !== 0
                ? _decisionB.delay !== 0
                  ? Math.min(_decisionA.delay, _decisionB.delay)
                  : _decisionA.delay
                : _decisionB.delay !== 0
                ? _decisionB.delay
                : 0,
          };
        }

        return [[_stateA, _stateB], [_outA, _outB], _decision] as const;
      },
    );

Great! Now, let’s add time delays to schedules, which is one of the key features of scheduling systems. Actually, this function differs from map only in that it is focused on a different aspect of the step function - Decision.

const addDelay =
  <Out,>(f: (out: Out, timer: number) => number) =>
  <In, S>(schedule: Schedule<Out, In, S>) =>
    new Schedule<Out, In, S>(schedule.initial, (input, state) => {
      const [_state, _out, _decision] = schedule.step(input, state);

      if (_decision.tag === "Continue") {
        return [
          _state,
          _out,
          { tag: "Continue", delay: f(_out, _decision.delay) },
        ] as const;
      }

      return [_state, _out, _decision] as const;
    });

Let's now put everything together

const delayedFibonacci = fibonacci
  .pipe(map((x) => x[1])) // get fibonacci element
  .addDelay(x => x * 1000) // and interpreter it as delay in seconds
const fibonacciScheduler = delayedFibonacci
  .pipe(intersect(recurs(5))) // take only 5 first steps

Full code in playground - https://tsplay.dev/NVBolN

Description of schedule

Since a schedule is simply a description of timing behavior, swapping out the Driver changes how it behaves. We could, for example, ignore delays entirely or integrate this into libraries like RxJS.

The real power of Schedule is its composability. Even in this basic example, we’ve created a fairly sophisticated schedule from a simple unfold combined with mappings.

Instead of the conclusion

I enjoy digging into the inner workings of features because it deepens my understanding not just of specific technologies but also of transferable design patterns and problem-solving techniques. Writing this schedule from scratch wouldn't have been easy without exploring the internals — but now it's clear that everything revolves around a step function.