Agenda

• Introduction to core Effect concepts
• Real world examples by rewriting two apps
• A peek into 'advanced' Effect

There’s lots of room for elasticity

What do you need?

https://github.com/ethanniser/effect-workshop

• Join the channel in the Effect discord (DM Mirela if you are not)
• A way to run typescript (node or bun)
• This repo (available from my github)
• Opening in a github codespace (run ./start.sh)

What is an 'Effect'?

• "Something brought about by a cause or agent"
• Side effects?
• The `Effect` type

declare function Inner(): "baz" | "bar" | Error;

function Outer(): number | Error {
  const result = Inner();
  if (result instanceof Error) {
    return result;
  }
  return result.length;
}

Forced to handle errors at every single point, even if we don't care

Effects are different

type Effect<Value, Error = never> = /* unimportant */;

declare const foo: Effect<number, never>;
// also the same as Effect<number>

declare const bar: Effect<number, Error>;

Sync vs Async

declare async function getUser(id: number): Promise<User>;

declare function getUser(id: number): 
  Effect<User, NotFoundError, UserRepo>;

Execution

const foo = () => Date.now();

console.log(foo); // [Function: foo]

console.log(foo()); // 1707076796922

const effectFoo = Effect.sync(() => Date.now());

console.log(effectFoo);
// { _id: 'Effect', _op: 'Sync', i0: [Function: foo] }

console.log(Effect.runSync(effectFoo)); // 1707076796922

Creating Effects

async, asyncEffect, asyncEither, asyncOption, die, dieMessage, dieSync, fail, failCause, failCauseSync, failSync, gen, never, none, promise, succeed, succeedNone, succeedSome, suspend, sync, unit, withClockScoped, withConsoleScoped, yieldNow

• succeed / fail for values
• sync / try for sync functions
• promise / tryPromise for async functions
• async for async callbacks

Running Effects

Well we have some effects now, but they don’t do anything…

• runSync for synchronous effects
• runPromise for asynchronous effects
• runSyncExit / runPromiseExit for geting the error as a value, instead of thrown

Building up programs

• So far our programs are quite limited

const getDate = () => Date.now();
const double = (x) => x * 2;

const doubleDate = () => {
  const date = getDate();
  return double(date);
};

const getDate = Effect.sync(() => Date.now());
const double = (x) => x * 2;

const doubleDate = Effect.sync(() => {
  const date = Effect.runSync(getDate);
  return double(date);
});

Run Effects at the EDGES of your program

Combinators!

• map: Transform the value of an effect
• flatMap: Transform the value of an effect into another effect
• tap: Perform a side effect without changing the value
• all: Merge multiple effects into a single effect

Error handling

• catchAll: Recover from all errors
• catchTag: Recover from a specific error
• mapError: Transform the error of an effect
• match: Handle both cases
• either: Move the error into the success channel

Context Management

• "Services" are functionality whos type signature is seperate from the implementation
• Context.Tag created a placehold for a service that can be used in an effect as if it were the real thing
• provideService(Tag, implementation) provides the service to the effect
• Layers are programs that create services and run before effects that require them
• provide(Tag, layer) provides the layer to the effect

Resource Management

• A Scope contains 'finalizers' that are run when the scope is closed
• When an Effect requires a Scope service it means: "I have some resources that need to be cleaned up at some point"
• Providing the Scope indicates where the scope should be closed
• acquireRelease: a helper for created scoped resources

Effect Datatypes

• Option<T>: A value that may or may not exist
• Either<A, E>: A disjointed union of two types
• Exit<A, E>: Essentially a Either<A, Cause<E>>
• Cause<E>: The result of a computation
• Duration: A time interval
• Chunk<T>: An immutable, functional array
• HashSet<T> / HashMap<K, V>: Immutable, functional collections that support custom hashing and equality with Equal and Hash
• Data: A module for auto-implementing Equal and Hash for data

Time for a break

• I know that was a lot
• After the break we’ll start looking at some practical applications

Match

• Pattern matching allows for the handling of multiple cases in a single expression
• Can match on values or predicates
• Type level assurance that all cases are handled

Schema

A Schema<A, I, R> can:

• validating that unknown data is of type A
• validating that unknown data is of type I
• encoding A to I
• decoding I to R

Schema is incredibly powerful

• Can model basically any data structure
• Filters
• Transforms (can be effectful)
• Pretty printing errors

@effect/platform

• Platform agnostic interfaces for common operations, with platform specific implementations
• Covers: Http (client and server), workers, file system, spawning processes, key value store, file paths, clipboard, and more

@effect/cli

• Fully featured cli app framework for effect
• Composable and type safe args + options
• Pre-built prompts (lists, select, toggle, confirm, etc…)
• Help, wizard, and completions generation

Schedule

• A Schedule is a description of a series of delays
• Can be used for retrying on failure, or repeating on success
• Have inputs (the output of an effect or another schedule) and outputs (depends on the schedule)
• Very composable (like everything in effect!)

Config

• Reads config values from a string key to some validated type
• Can be mapped, filtered, etc.
• Any Config can be used just like an effect to get the value or a ConfigError
• Swappable backend with ConfigProvider

Ref

• A mutable reference to an immutable value
• All actions are effectful
• Useful for sharing state (there are other options if you do not want this)

Stream

• A Stream is an Effect that may produce none, one, or many values
• "Pull" based (like an iterator)
• Has all the same properties as an Effect, most of the same combinators
• Must be 'ran' to produce values
• Sink type for more advanced and resuable consuming of streams

Concurrency and Fibers

const normalJS = () => {
  let i = 0;
  setInterval(() => console.log("i", i), 250);
  while (true) {
    i++;
  }
};

Why doesn’t this work?

Effect’s Fiber Model

• Fibers (or green threads) are a lightweight in memory thread
• Fibers can be spawned in the thousands without issue
• If an Effect is a description of a program, a Fiber is a running instance of that program
• Fibers can be paused, restarted, 'awaited' to get their result, or interrupted to cancel them
• Abstracts away sync vs async (to the fiber, everything is sync!)

How is this possible?

• Your os technically can’t even stop your cpu it has to wait for a syscall or an interrupt
• Same with Javascript, there is litterally no way to stop the main thread from whatever it is doing
• But what if we broke our program down into little, lazy, steps
• Then we could 'pause' execution by simply not executing the next step

Structured Concurrency

Fibers have a parent-child relationship, and when a parent fiber completes or is interrupted, it will interrupt all of its children, and their children, and so on

Consider the alternative (callbacks or global coroutines)

• Functions aren’t 'black boxes' anymore as they can 'leak' tasks
• When a task errors, who is responible for that error?
• If a task has resources, who makes sure those get cleaned up?
• How do you stop a task from the outside (you can’t)

Lots of parallels to memory management

Escape hatches if you need them

• forkDaemon spawns a fiber in the top level, global scope
• forkScoped spawns a fiber and requires a Scope to be provided
• forkIn allows you specify a custom scope to spawn a fiber in with a Scope

Fiber to Fiber communication

• Arguable benefits over shared state
• Deferred for 'one shot' channel that can error
• Queue standard 'channel', customizable back pressure behavior
• PubSub for 'publishing' to multiple 'subscribers'

When do Fibers run?

• After the current fiber yields

High Level Abstractions

• Working with fibers directly is often not necessary
• All combinators that operate on multiple effects have special 'concurrency' options
• All the benefits of fibers + structred concurrency in a single line

Custom Schedulers

• Just like everything else, the Scheduler that controls when fibers run is customizable
• Web app: render fiber has priority, or scheduler tied to react render queue or requestIdleCallback
• No good default for every case, yield too much and program becomes unnecessarily slow, yield too little and the program becomes unresponsive and uncooperative

STM

• STM is its own little Effect-like world, has most of the same combinators as Effects
• Inside an STM there should be no side effects, only logic and operating on STM data structures
• Custom T_ versions of most common data structures
• commiting an stm transaction executes it in a single opaque operation
• Either all operations go through sucessfully, or the data remains in its original state
• Requires the data inside T_ data structures to be immutable

Runtime and FiberRefs

• A Runtime<R> is a thing that can run an Effect to an Exit
• Has a Context of services that can be seeded with some initial services (the R)
• FiberRef is a mutable value that is local to a fiber (runtimes start with a bunch of built in ones but you can create your own)
• Defined 'fork' and 'merge' semantics
• RuntimeFlags ultra low level bitflags for controlling runtime behavior

Telemetry and Observability

• Effect has first class support for OpenTelemetry
• Spans, Traces, and Metrics are just as composable as the rest of Effect
• If you know you need this, it should be pretty exciting
• And if not, you’ll be thankful for how easy it is to add later on

RPC

• Network calls as easy as calling a function
• Full client-server typesafey
• Customizable serialization and deserialization with Schema
• Built in HTTP adapter, but can be swapped out for anything

Batching and Caching

• Define Requests and RequestResolvers for those Requests
• Execute request using Effect.request
• If a request can support batching, a special resolver can be used
• When batching is enabled, effects will wait to see if any other effects also wait on the same request and batch together
• Requests can easily be cached with a custom capcaity and TTL

Performance

• Obviously Effect has some overhead
• Effect is made for application code, where the limitation is almost always IO anyway
• Effect actually will likely improve the performance of these parts of your code because of its powerful concurrency primitives (structure concurrency, interruption, worker pool abstractions)
• If you are writing CPU bound code, you could not use Effect and provide a effect wrapper, or maybe you shouldn’t be using javascript at all

Thanks for coming!

• Slides and code will be available on my github- please do try the 'after the workshop' additional exercises
• Feedback / Comments / Questions? Theres a feedback box on the way out. (or just dm me on twitter if your feeling a bit more direct)
• Come say hi to me tomorrow at the conference