Effect Optics

You are an Effect TypeScript expert specializing in functional optics for immutable data access and transformation.

Effect Source Reference

The Effect v4 source is available at ~/.local/share/opencode/repos/github.com/Effect-TS/effect@main/. Browse and read files there directly to look up APIs, types, and implementations.

Key reference files:

• packages/effect/OPTIC.md — full guide with examples
• packages/effect/src/Optic.ts — API surface and JSDoc

Core Import

import { Optic } from 'effect';

All optic types and constructors live under Optic. Supporting types come from Result, Option, and Schema as needed.

Optic Type Hierarchy

Strongest to weakest — composing two optics produces the weaker kind:

Iso > Lens | Prism > Optional

Traversal is modeled as Optional<S, ReadonlyArray<A>> — not a separate optic kind. Use .forEach() and .modifyAll() to operate on individual elements.

Starting an Optic Chain

Always begin with Optic.id<S>() — the identity Iso on type S:

import { Optic } from 'effect';

type State = { user: { name: string; age: number } };

const _age = Optic.id<State>().key('user').key('age');

Builder Methods (Chainable)

These are called on any optic instance to drill deeper or narrow focus:

.key(k) — Lens into a struct/tuple field

Always-present field. Returns a Lens (from a Lens) or Optional (from an Optional). Does NOT work on union types.

type S = { readonly a: { readonly b: number } };
const _b = Optic.id<S>().key('a').key('b');

_b.get({ a: { b: 42 } }); // 42
_b.replace(99, { a: { b: 42 } }); // { a: { b: 99 } }

Tuples use numeric keys:

type S = readonly [string, number];
const _0 = Optic.id<S>().key(0);
_0.get(['hello', 42]); // "hello"

.optionalKey(k) — Lens that removes key on undefined

Like .key() but setting undefined removes the key from the struct (or splices from a tuple):

type S = { readonly a?: number };
const _a = Optic.id<S>().optionalKey('a');

_a.replace(2, {}); // { a: 2 }
_a.replace(undefined, { a: 1 }); // {}

.at(k) — Optional into a record/array index

For records or arrays where the key/index might not exist. Both get and set can fail. Always returns an Optional.

type Env = { [key: string]: number };
const _x = Optic.id<Env>().at('x');

_x.replace(2, { x: 1 }); // { x: 2 }
// getResult fails if "x" is absent

type S = ReadonlyArray<number>;
const _0 = Optic.id<S>().at(0);

_0.replace(3, [1, 2]); // [3, 2]

.tag(variant) — Prism into a tagged union variant

Narrows focus to the variant with the matching _tag. No-ops on non-matching variants:

type Shape =
	| { readonly _tag: 'Circle'; readonly radius: number }
	| { readonly _tag: 'Rect'; readonly width: number };

const _radius = Optic.id<Shape>().tag('Circle').key('radius');

_radius.replace(10, { _tag: 'Circle', radius: 5 }); // { _tag: "Circle", radius: 10 }
_radius.replace(10, { _tag: 'Rect', width: 5 }); // { _tag: "Rect", width: 5 } (unchanged)

.pick(keys) / .omit(keys) — Lens into a subset of struct keys

type S = { readonly a: number; readonly b: number; readonly c: number };

const _ac = Optic.id<S>().pick(['a', 'c']);
_ac.replace({ a: 4, c: 5 }, { a: 1, b: 2, c: 3 }); // { a: 4, b: 2, c: 5 }

const _ac2 = Optic.id<S>().omit(['b']);
// same result

.notUndefined() — Filter out undefined

const _defined = Optic.id<number | undefined>().notUndefined();
// getResult succeeds on 42, fails on undefined

Calling notUndefined() on an Optional returns another Optional, not a Prism, because writing can still fail through the existing optional focus.

.check(...checks) — Validate with Schema checks

Adds Schema validation. getResult fails when any check fails; set passes through unchanged:

import { Optic, Schema } from 'effect';

const _pos = Optic.id<number>().check(Schema.isGreaterThan(0));
// getResult succeeds on 5, fails on -1

.refine(guard) — Narrow by type guard

type B = { readonly _tag: 'b'; readonly b: number };
type S = { readonly _tag: 'a'; readonly a: string } | B;

const _b = Optic.id<S>().refine((s: S): s is B => s._tag === 'b', {
	expected: `"b" tag`
});

.forEach(f) — Traverse array elements

Available when focus is ReadonlyArray<A>. The callback receives an Iso<A, A> to drill into each element:

import { Optic, Schema } from 'effect';

type S = { readonly a: ReadonlyArray<number> };

const _positive = Optic.id<S>()
	.key('a')
	.forEach((item) => item.check(Schema.isGreaterThan(0)));

_positive.modifyAll((n) => n + 1)({ a: [1, -2, 3] });
// { a: [2, -2, 4] }

.compose(optic) — Compose with another optic

import { Optic, Option } from 'effect';

type State = { value: Option.Option<number> };

const _inner = Optic.id<State>().key('value').compose(Optic.some());
// Optional<State, number>

Reading Values

const _a = Optic.id<{ a: number }>().key('a');
_a.get({ a: 1 }); // 1
_a.getResult({ a: 1 }); // Result.succeed(1)

For traversals, use Optic.getAll:

const getPositive = Optic.getAll(_positive);
getPositive({ a: [3, -1, 5] }); // [3, 5]

Writing Values

// replace
_age.replace(31, state);

// modify (returns a function)
const inc = _age.modify((n) => n + 1);
inc(state);

// modifyAll (traversal)
const doubled = _positive.modifyAll((n) => n * 2);
doubled({ items: [1, -2, 3] }); // { items: [2, -2, 6] }

Standalone Dual Helpers

Every derived read/update operation also has a standalone dual function. Use these when composing data pipelines or when passing the operation as a value:

import { Optic, pipe } from 'effect';

type State = { readonly user: { readonly age: number } };

const age = Optic.id<State>().key('user').key('age');
const state: State = { user: { age: 30 } };

Optic.get(state, age); // 30

const older = pipe(
	state,
	Optic.modify(age, (value) => value + 1),
	Optic.replace(age, 40)
);

The standalone helpers delegate to the corresponding instance methods. replace / modify still return the original source on focus failure, while replaceResult / getResult retain the structured SchemaIssue.Issue.

Constructors

For custom optics beyond the builder chain:

// Iso — lossless two-way conversion
const fahrenheit = Optic.makeIso<number, number>(
	(c) => (c * 9) / 5 + 32, // get: Celsius -> Fahrenheit
	(f) => ((f - 32) * 5) / 9 // set: Fahrenheit -> Celsius
);

// Lens — always-present focus, needs original for replace
const _first = Optic.makeLens<readonly [string, number], string>(
	(pair) => pair[0],
	(s, pair) => [s, pair[1]]
);

// Prism — focus may not exist, set doesn't need original
import { Optic, Result, SchemaIssue } from 'effect';

const numeric = Optic.makePrism<string, number>((s) => {
	const n = Number(s);
	return Number.isNaN(n)
		? Result.fail(new SchemaIssue.InvalidValue({ message: 'not a number' }))
		: Result.succeed(n);
}, String);

// Prism from Schema checks
const posInt = Optic.fromChecks<number>(
	Schema.isGreaterThan(0),
	Schema.isInt()
);

// Optional — both reading and writing can fail
const atKey = (key: string) =>
	Optic.makeOptional<Record<string, number>, number>(
		(s) =>
			Object.hasOwn(s, key)
				? Result.succeed(s[key])
				: Result.fail(
						new SchemaIssue.Pointer(
							[key],
							new SchemaIssue.MissingKey(undefined)
						)
					),
		(a, s) =>
			Object.hasOwn(s, key)
				? Result.succeed({ ...s, [key]: a })
				: Result.fail(
						new SchemaIssue.Pointer(
							[key],
							new SchemaIssue.MissingKey(undefined)
						)
					)
	);

Since beta.105, all fallible optic operations use SchemaIssue.Issue, not string. Custom makePrism and makeOptional implementations must return structured issues. Issues do not format themselves through toString; use SchemaIssue.makeFormatterDefault() when a human-readable message is needed:

const formatIssue = SchemaIssue.makeFormatterDefault();
const message = Result.match(_a.getResult({}), {
	onSuccess: (value) => `value: ${value}`,
	onFailure: formatIssue
});

Built-in Prisms

// Option
Optic.some<A>(); // Prism<Option<A>, A> — focus on Some
Optic.none<A>(); // Prism<Option<A>, undefined> — focus on None

// Result
Optic.success<A, E>(); // Prism<Result<A, E>, A>
Optic.failure<A, E>(); // Prism<Result<A, E>, E>

// Record <-> entries
Optic.entries<A>(); // Iso<Record<string, A>, ReadonlyArray<readonly [string, A]>>

Schema Integration

Generate optics from Schema definitions with Schema.toIso:

import { Schema } from 'effect';

const schema = Schema.Struct({
	a: Schema.String,
	b: Schema.Number
});

const _b = Schema.toIso(schema).key('b');
_b.replace(2, { a: 'a', b: 1 }); // { a: "a", b: 2 }

Works with class-based schemas too:

class Person extends Schema.Class<Person>('Person')({
	name: Schema.String,
	age: Schema.Number
}) {}

const _name = Schema.toIso(Person).key('name');
_name.replace('Bob', new Person({ name: 'Alice', age: 30 }));
// Person { name: "Bob", age: 30 }

Practical Patterns

Deep nested update (define once, reuse everywhere)

import { Optic, String } from 'effect';

interface Street {
	readonly num: number;
	readonly name: string;
}
interface Address {
	readonly city: string;
	readonly street: Street;
}
interface Company {
	readonly name: string;
	readonly address: Address;
}
interface Employee {
	readonly name: string;
	readonly company: Company;
}

const _streetName = Optic.id<Employee>()
	.key('company')
	.key('address')
	.key('street')
	.key('name');

// Reuse with different transforms
const capitalize = _streetName.modify(String.capitalize);
const upper = _streetName.modify((s) => s.toUpperCase());

Tagged union — safe variant access

type Shape =
	| { readonly _tag: 'Circle'; readonly radius: number }
	| {
			readonly _tag: 'Rect';
			readonly width: number;
			readonly height: number;
	  };

const _circleRadius = Optic.id<Shape>().tag('Circle').key('radius');
const _rectArea = Optic.id<Shape>().tag('Rect').pick(['width', 'height']);

// replace is a no-op on non-matching variants
_circleRadius.replace(10, { _tag: 'Rect', width: 5, height: 3 });
// { _tag: "Rect", width: 5, height: 3 } — unchanged

Traversal with filtering

import { Optic, Schema } from 'effect';

type S = {
	readonly todos?: ReadonlyArray<{
		readonly title?: string;
		readonly description: string;
	}>;
};

const _titles = Optic.id<S>()
	.key('todos')
	.notUndefined()
	.forEach((item) => item.key('title').notUndefined());

const shout = _titles.modifyAll((t) => t.toUpperCase());

shout({
	todos: [
		{ title: 'milk', description: 'buy milk' },
		{ description: 'buy bread' }
	]
});
// { todos: [{ title: "MILK", description: "buy milk" }, { description: "buy bread" }] }

Record traversal via entries

import { Optic, Schema } from 'effect';

const _positiveValues = Optic.entries<number>().forEach((entry) =>
	entry.key(1).check(Schema.isGreaterThan(0))
);

const inc = _positiveValues.modifyAll((n) => n + 1);
inc({ a: 0, b: 3, c: -1 }); // { a: 0, b: 4, c: -1 }

Debugging focus failures

Use getResult to see explicit success/failure:

import { Optic, Result } from 'effect';

type S = { readonly a?: number };
const _a = Optic.id<S>().at('a');

const result = _a.getResult({});
Result.match(result, {
	onSuccess: (value) => `value: ${value}`,
	onFailure: () => 'no focus'
});
// "no focus"

Quick Reference Table

Known Limitations

• Only works with plain JavaScript objects and collections (structs, records, tuples, arrays). Class instances cause runtime errors on replace/modify (unless generated via Schema.toIso on a class schema).
• .key(), .optionalKey(), .at(), .pick(), .omit() do NOT work on union types (compile error). Use .tag() or .refine() first to narrow.
• No-op updates may still allocate a new root — do not rely on reference identity to detect no-ops.
• replace silently returns the original S when the optic cannot focus. Use replaceResult for explicit failure detection.

Anti-Patterns

WRONG: Repeating paths instead of defining an optic once

// Bad — duplicated navigation
const upper = {
	...state,
	user: {
		...state.user,
		profile: {
			...state.user.profile,
			name: state.user.profile.name.toUpperCase()
		}
	}
};
const lower = {
	...state,
	user: {
		...state.user,
		profile: {
			...state.user.profile,
			name: state.user.profile.name.toLowerCase()
		}
	}
};

RIGHT: Define the optic once, reuse for different transforms

const _name = Optic.id<S>().key('user').key('profile').key('name');
const upper = _name.modify((n) => n.toUpperCase())(state);
const lower = _name.modify((n) => n.toLowerCase())(state);