effect-lens 0.1.5 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 A Lens type for [Effect](https://effect.website/) to easily manage nested state.
 
+This version is for Effect v3. For Effect v4, use version 2.X.X-beta.X.
+
 ## Install
 ```
 npm install effect-lens
@@ -28,7 +30,7 @@ Lens<
     A,   // Type of the value the lens is focused on
     ER,  // Errors that can happen when reading
     EW,  // Errors that can happen when writing
-    RE,  // Requirements for reading
+    RR,  // Requirements for reading
     RW   // Requirements for writing
 >
 ```
@@ -55,11 +57,14 @@ yield* Lens.update(lens, Array.replace(1, 1664))
 Currently available:
 - `fromSubscriptionRef`
 - `fromSynchronizedRef` (note: since `SynchronizedRef` is not reactive (does not produce a stream of value changes), the resulting Lens' `changes` stream will only emit the current value of the lens when evaluated, and nothing else)
-
-More to come!
+- `fromRef` (returns an effect because it creates an internal lock)
 
 #### Manually
-You can also create Lenses manually using `make` by providing a getter, a stream of changes and either a `set` or `modify` function depending on your needs.
+You can also create Lenses manually using `make` by providing:
+- `get`: an effect that reads the current value,
+- `changes`: a stream of value changes,
+- `commit`: an effectful write primitive,
+- `lock`: an effect that produces the lock used to serialize writes.
 
 You can get pretty creative! Here's an example of a Lens that points to a specific key of the browser `LocalStorage`:
 ```typescript
@@ -67,8 +72,9 @@ You can get pretty creative! Here's an example of a Lens that points to a specif
 const lens = Effect.all([
     KeyValueStore.KeyValueStore,
     Effect.succeed("someKey"),
+    Effect.makeSemaphore(1),
 ]).pipe(
-    Effect.map(([kv, key]) => Lens.make({
+    Effect.map(([kv, key, semaphore]) => Lens.make({
         get: kv.get(key),
 
         changes: kv.get(key).pipe(
@@ -83,9 +89,11 @@ const lens = Effect.all([
             Stream.unwrap,
         ),
 
-        set: a => Option.isSome(a)
+        commit: a => Option.isSome(a)
             ? kv.set(key, a.value)
             : kv.remove(key),
+
+        lock: Effect.succeed(semaphore.withPermits(1)),
     })),
 
     Effect.provide(BrowserKeyValueStore.layerLocalStorage),
@@ -165,8 +173,7 @@ Currently available:
 | `focusTupleAt` | Focuses to an indexed entry of a readonly tuple. Replaces the parent tuple immutably when writing to the focused index | Immutable | |
 | `focusMutableTupleAt` | Focuses to an indexed entry of a mutable tuple. Mutates the parent tuple in place at the focused index | Mutable | Type-safe: will not allow you to mutate `readonly` tuples |
 | `focusChunkAt` | Focuses to an indexed entry of a `Chunk`. Replaces the parent `Chunk` immutably when writing to the focused element | Immutable | |
-
-Also more to come!
+| `focusOption` | Focuses to the value inside an `Option`. Wraps writes back into `Option.some` | Immutable | Reading or writing fails with `NoSuchElementException` when the parent option is `None` |
 
 #### Manually
 You can create focused Lenses by composing them manually using `map`, `mapEffect` and `unwrap`:
@@ -196,6 +203,42 @@ const benzemonstreLens = ref.pipe(
 // As you can see, this is automatically tracked by the Lens type
 ```
 
+#### Low-level derived lenses
+For advanced cases, you can derive a Lens manually using `derive`. This is the primitive used by the built-in transforms.
+
+A derived Lens describes how to transform three parent channels:
+- `resolve`: reads the parent and returns the focused value plus a `commit` function to rebuild the parent,
+- `mapStream`: transforms the parent `changes` stream,
+- `mapLock`: transforms the parent write lock.
+
+Most custom focusing logic should use `map` or `mapEffect`, but `derive` is useful when you need full control over read, stream, lock, and write-back behavior.
+
+```typescript
+declare const lens: Lens.Lens<User, never, never, never, never>
+
+const nameLens = lens.pipe(
+    Lens.derive({
+        resolve: parent => Effect.map(
+            parent,
+            resolved => ({
+                value: resolved.value.name,
+                commit: next => resolved.commit(
+                    Effect.map(next, name => ({
+                        ...resolved.value,
+                        name,
+                    })),
+                ),
+            }),
+        ),
+
+        mapStream: Stream.map(user => user.name),
+
+        // This derived Lens does not add lock behavior, so it reuses the parent lock.
+        mapLock: identity,
+    }),
+)
+```
+
 
 ### Subscribable
 
@@ -222,7 +265,7 @@ yield* someFunctionThatShouldOnlyHaveReadonlyAccessToTheState(lens)
 ```
 
 #### Focusing
-This library re-exports Effect's `Subscribable` module and adds a few transforms to narrow the focus of `Subscribable`'s, same as Lenses:
+This library re-exports Effect's `Subscribable` module and adds error transforms and recovery (`catchAll`, `catchAllCause`, `orElse`, `orElseSucceed`, and `retry`), plus transforms to narrow the focus of `Subscribable`'s, same as Lenses:
 ```typescript
 import { Subscribable } from "effect-lens"
 
@@ -240,15 +283,16 @@ Currently available:
 | - | - |
 | `focusObjectOn` | Focuses to the field of an object |
 | `focusArrayAt` | Focuses to an indexed entry of an array |
+| `focusArrayLength` | Focuses to the length of an array |
 | `focusTupleAt` | Focuses to an indexed entry of a tuple |
 | `focusChunkAt` | Focuses to an indexed entry of a `Chunk` |
+| `focusChunkSize` | Focuses to the size of a `Chunk` |
+| `focusIterableSize` | Focuses to the size of an iterable |
 
 
 ## Todo
 
 This library is already ready to use! However, there is always more to do...
-- Finish those docs
 - Provide an API reference
 - Add new adapters for various data source types
 - Add new focus transforms
-- Provide a preview version for Effect 4 beta

package/dist/Lens.d.ts

@@ -1,4 +1,4 @@
-import { Chunk, Effect, Option, Pipeable, Readable, Stream, type SubscriptionRef, type SynchronizedRef } from "effect";
+import { Chunk, type Context, Effect, Option, Pipeable, PubSub, Readable, Ref, Stream, type SubscriptionRef, type SynchronizedRef } from "effect";
 import type { NoSuchElementException } from "effect/Cause";
 import * as Subscribable from "./Subscribable.js";
 export declare const LensTypeId: unique symbol;
@@ -12,42 +12,96 @@ export type LensTypeId = typeof LensTypeId;
  */
 export interface Lens<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never> extends Subscribable.Subscribable<A, ER, RR> {
     readonly [LensTypeId]: LensTypeId;
-    readonly modify: <B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>;
+    readonly modifyEffect: <B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>;
 }
-declare const LensImpl_base: Pipeable.PipeableConstructor;
 /**
- * Internal `Lens` implementation.
+ * Checks whether a value is a `Lens`.
  */
-export declare class LensImpl<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never> extends LensImpl_base implements Lens<A, ER, EW, RR, RW> {
-    readonly get: Effect.Effect<A, ER, RR>;
-    readonly changes: Stream.Stream<A, ER, RR>;
-    readonly modify: <B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>;
+export declare const isLens: (u: unknown) => u is Lens<unknown, unknown, unknown, unknown, unknown>;
+export declare const LensImplTypeId: unique symbol;
+export type LensImplTypeId = typeof LensImplTypeId;
+export declare namespace LensImpl {
+    interface Resolved<in out A, in out EW = never, in out RW = never> {
+        readonly value: A;
+        readonly commit: <E = never, R = never>(next: Effect.Effect<A, E, R>) => Effect.Effect<void, EW | E, RW | R>;
+    }
+    interface Lock {
+        <A1, E1, R1>(self: Effect.Effect<A1, E1, R1>): Effect.Effect<A1, E1, R1>;
+    }
+}
+declare const LensImpl_base: Pipeable.PipeableConstructor;
+export declare abstract class LensImpl<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never> extends LensImpl_base implements Lens<A, ER, EW, RR, RW> {
     readonly [Readable.TypeId]: Readable.TypeId;
     readonly [Subscribable.TypeId]: Subscribable.TypeId;
     readonly [LensTypeId]: LensTypeId;
-    constructor(get: Effect.Effect<A, ER, RR>, changes: Stream.Stream<A, ER, RR>, modify: <B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>);
+    readonly [LensImplTypeId]: LensImplTypeId;
+    abstract readonly resolve: Effect.Effect<LensImpl.Resolved<A, EW, RW>, ER, RR>;
+    abstract readonly changes: Stream.Stream<A, ER, RR>;
+    abstract readonly lock: Effect.Effect<LensImpl.Lock, EW, RW>;
+    get get(): Effect.Effect<A, ER, RR>;
+    modifyEffect<B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>): Effect.Effect<B, ER | EW | E1, RR | RW | R1>;
+}
+export declare const isLensImpl: (u: unknown) => u is LensImpl<unknown, unknown, unknown, unknown, unknown>;
+export declare const asLensImpl: <A, ER, EW, RR, RW>(lens: Lens<A, ER, EW, RR, RW>) => LensImpl<A, ER, EW, RR, RW>;
+export declare const asSubscribable: <A, ER, EW, RR, RW>(lens: Lens<A, ER, EW, RR, RW>) => Subscribable.Subscribable<A, ER, RR>;
+export declare namespace LensLazyImpl {
+    interface Source<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never> {
+        readonly get: Effect.Effect<A, ER, RR>;
+        readonly changes: Stream.Stream<A, ER, RR>;
+        readonly commit: (a: A) => Effect.Effect<void, EW, RW>;
+        readonly lock: Effect.Effect<LensImpl.Lock, EW, RW>;
+    }
+}
+export declare class LensLazyImpl<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never> extends LensImpl<A, ER, EW, RR, RW> {
+    readonly source: LensLazyImpl.Source<A, ER, EW, RR, RW>;
+    constructor(source: LensLazyImpl.Source<A, ER, EW, RR, RW>);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A, EW, RW>, ER, RR>;
+    get changes(): Stream.Stream<A, ER, RR>;
+    get lock(): Effect.Effect<LensImpl.Lock, EW, RW>;
 }
 /**
- * Checks whether a value is a `Lens`.
+ * Creates a `Lens` by supplying how to read the current value, observe changes, and apply transformations.
  */
-export declare const isLens: (u: unknown) => u is Lens<unknown, unknown, unknown, unknown, unknown>;
+export declare const make: <A, ER, EW, RR, RW>(source: LensLazyImpl.Source<A, ER, EW, RR, RW>) => Lens<A, ER, EW, RR, RW>;
+export declare class UnwrappedLensImpl<in out A, in out ER, in out EW, in out RR, in out RW, in out E1, in out R1> extends LensImpl<A, ER | E1, EW | E1, RR | R1, RW | R1> {
+    readonly effect: Effect.Effect<Lens<A, ER, EW, RR, RW>, E1, R1>;
+    constructor(effect: Effect.Effect<Lens<A, ER, EW, RR, RW>, E1, R1>);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A, EW | E1, RW | R1>, ER | E1, RR | R1>;
+    get changes(): Stream.Stream<A, ER | E1, RR | R1>;
+    get lock(): Effect.Effect<LensImpl.Lock, EW | E1, RW | R1>;
+}
 /**
- * Creates a `Lens` by supplying how to read the current value, observe changes, and apply transformations.
- *
- * Either `modify` or `set` needs to be supplied.
+ * Flattens an effectful `Lens`.
  */
-export declare const make: <A, ER, EW, RR, RW>(options: {
-    readonly get: Effect.Effect<A, ER, RR>;
-    readonly changes: Stream.Stream<A, ER, RR>;
-} & ({
-    readonly modify: <B, E1 = never, R1 = never>(f: (a: A) => Effect.Effect<readonly [B, A], E1, R1>) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>;
-} | {
-    readonly set: (a: A) => Effect.Effect<void, EW, RW>;
-})) => Lens<A, ER, EW, RR, RW>;
+export declare const unwrap: <A, ER, EW, RR, RW, E1, R1>(effect: Effect.Effect<Lens<A, ER, EW, RR, RW>, E1, R1>) => Lens<A, ER | E1, EW | E1, RR | R1, RW | R1>;
+export declare class RefLensImpl<in out A> extends LensImpl<A, never, never, never, never> {
+    readonly ref: Ref.Ref<A>;
+    readonly semaphore: Effect.Semaphore;
+    constructor(ref: Ref.Ref<A>, semaphore: Effect.Semaphore);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A>, never, never>;
+    get changes(): Stream.Stream<A, never, never>;
+    get lock(): Effect.Effect<(<A_1, E, R>(self: Effect.Effect<A_1, E, R>) => Effect.Effect<A_1, E, R>), never, never>;
+}
 /**
- * Creates a `Lens` that proxies a `SubscriptionRef`.
+ * Creates a `Lens` that proxies a `Ref`.
+ *
+ * Note: since `Ref` does not provide any kind of reactivity mechanism, the produced `Lens` will be non-reactive.
+ * This means its `changes` stream will only emit the current value once when evaluated and nothing else.
  */
-export declare const fromSubscriptionRef: <A>(ref: SubscriptionRef.SubscriptionRef<A>) => Lens<A, never, never, never, never>;
+export declare const fromRef: <A>(ref: Ref.Ref<A>) => Effect.Effect<Lens<A, never, never, never, never>, never, never>;
+export declare namespace SynchronizedRefLensImpl {
+    interface SynchronizedRefWithInternals<in out A> extends SynchronizedRef.SynchronizedRef<A> {
+        readonly ref: Ref.Ref<A>;
+        readonly withLock: LensImpl.Lock;
+    }
+}
+export declare class SynchronizedRefLensImpl<in out A> extends LensImpl<A, never, never, never, never> {
+    readonly ref: SynchronizedRefLensImpl.SynchronizedRefWithInternals<A>;
+    constructor(ref: SynchronizedRefLensImpl.SynchronizedRefWithInternals<A>);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A>, never, never>;
+    get changes(): Stream.Stream<A, never, never>;
+    get lock(): Effect.Effect<LensImpl.Lock, never, never>;
+}
 /**
  * Creates a `Lens` that proxies a `SynchronizedRef`.
  *
@@ -55,23 +109,59 @@ export declare const fromSubscriptionRef: <A>(ref: SubscriptionRef.SubscriptionR
  * This means its `changes` stream will only emit the current value once when evaluated and nothing else.
  */
 export declare const fromSynchronizedRef: <A>(ref: SynchronizedRef.SynchronizedRef<A>) => Lens<A, never, never, never, never>;
+export declare namespace SubscriptionRefLensImpl {
+    interface SubscriptionRefWithInternals<in out A> extends SubscriptionRef.SubscriptionRef<A> {
+        readonly ref: Ref.Ref<A>;
+        readonly pubsub: PubSub.PubSub<A>;
+        readonly semaphore: Effect.Semaphore;
+    }
+}
+export declare class SubscriptionRefLensImpl<in out A> extends LensImpl<A, never, never, never, never> {
+    readonly ref: SubscriptionRefLensImpl.SubscriptionRefWithInternals<A>;
+    constructor(ref: SubscriptionRefLensImpl.SubscriptionRefWithInternals<A>);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A>, never, never>;
+    get changes(): Stream.Stream<A, never, never>;
+    get lock(): Effect.Effect<(<A_1, E, R>(self: Effect.Effect<A_1, E, R>) => Effect.Effect<A_1, E, R>), never, never>;
+}
 /**
- * Flattens an effectful `Lens`.
+ * Creates a `Lens` that proxies a `SubscriptionRef`.
  */
-export declare const unwrap: <A, ER, EW, RR, RW, E1, R1>(effect: Effect.Effect<Lens<A, ER, EW, RR, RW>, E1, R1>) => Lens<A, ER | E1, EW | E1, RR | R1, RW | R1>;
+export declare const fromSubscriptionRef: <A>(ref: SubscriptionRef.SubscriptionRef<A>) => Lens<A, never, never, never, never>;
+export declare namespace DerivedLensImpl {
+    interface Source<in out A, in out B, in out ER = never, in out ESR = never, in out EW = never, in out ESW = never, in out RR = never, in out RSR = never, in out RW = never, in out RSW = never> {
+        readonly resolve: (effect: Effect.Effect<LensImpl.Resolved<B, ESW, RSW>, ESR, RSR>) => Effect.Effect<LensImpl.Resolved<A, EW, RW>, ER, RR>;
+        readonly mapStream: (stream: Stream.Stream<B, ESR, RSR>) => Stream.Stream<A, ER, RR>;
+        readonly mapLock: (lock: Effect.Effect<LensImpl.Lock, ESW, RSW>) => Effect.Effect<LensImpl.Lock, EW, RW>;
+    }
+}
+export declare class DerivedLensImpl<in out A, in out B, in out ER = never, in out PER = never, in out EW = never, in out PEW = never, in out RR = never, in out PRR = never, in out RW = never, in out PRW = never> extends LensImpl<A, ER, EW, RR, RW> {
+    readonly parent: LensImpl<B, PER, PEW, PRR, PRW>;
+    readonly source: DerivedLensImpl.Source<A, B, ER, PER, EW, PEW, RR, PRR, RW, PRW>;
+    constructor(parent: LensImpl<B, PER, PEW, PRR, PRW>, source: DerivedLensImpl.Source<A, B, ER, PER, EW, PEW, RR, PRR, RW, PRW>);
+    get resolve(): Effect.Effect<LensImpl.Resolved<A, EW, RW>, ER, RR>;
+    get changes(): Stream.Stream<A, ER, RR>;
+    get lock(): Effect.Effect<LensImpl.Lock, EW, RW>;
+}
+/**
+ * Derives a new `Lens` by linking a step to an existing parent lens.
+ */
+export declare const derive: {
+    <A, B, ER, EW, RR, RW, ER2, EW2, RR2, RW2>(source: DerivedLensImpl.Source<A, B, ER2, ER, EW2, EW, RR2, RR, RW2, RW>): (self: Lens<B, ER, EW, RR, RW>) => Lens<A, ER2, EW2, RR2, RW2>;
+    <A, B, ER, EW, RR, RW, ER2, EW2, RR2, RW2>(self: Lens<B, ER, EW, RR, RW>, source: DerivedLensImpl.Source<A, B, ER2, ER, EW2, EW, RR2, RR, RW2, RW>): Lens<A, ER2, EW2, RR2, RW2>;
+};
 /**
  * Derives a new `Lens` by applying synchronous getters and setters over the focused value.
  */
 export declare const map: {
-    <A, ER, EW, RR, RW, B>(self: Lens<A, ER, EW, RR, RW>, get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): Lens<B, ER, EW, RR, RW>;
     <A, ER, EW, RR, RW, B>(get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): (self: Lens<A, ER, EW, RR, RW>) => Lens<B, ER, EW, RR, RW>;
+    <A, ER, EW, RR, RW, B>(self: Lens<A, ER, EW, RR, RW>, get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): Lens<B, ER, EW, RR, RW>;
 };
 /**
  * Derives a new `Lens` by applying effectful getters and setters over the focused value.
  */
 export declare const mapEffect: {
-    <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(self: Lens<A, ER, EW, RR, RW>, get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): Lens<B, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
     <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): (self: Lens<A, ER, EW, RR, RW>) => Lens<B, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
+    <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(self: Lens<A, ER, EW, RR, RW>, get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): Lens<B, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
 };
 /**
  * Derives a new `Lens` by applying synchronous getters and setters over the value inside an `Option`.
@@ -81,8 +171,8 @@ export declare const mapEffect: {
  * - If the `Option` is `None`, it remains `None`
  */
 export declare const mapOption: {
-    <A, ER, EW, RR, RW, B>(self: Lens<Option.Option<A>, ER, EW, RR, RW>, get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): Lens<Option.Option<B>, ER, EW, RR, RW>;
     <A, ER, EW, RR, RW, B>(get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): (self: Lens<Option.Option<A>, ER, EW, RR, RW>) => Lens<Option.Option<B>, ER, EW, RR, RW>;
+    <A, ER, EW, RR, RW, B>(self: Lens<Option.Option<A>, ER, EW, RR, RW>, get: (a: NoInfer<A>) => B, set: (a: NoInfer<A>, b: B) => NoInfer<A>): Lens<Option.Option<B>, ER, EW, RR, RW>;
 };
 /**
  * Derives a new `Lens` by applying effectful getters and setters over the value inside an `Option`.
@@ -92,22 +182,97 @@ export declare const mapOption: {
  * - If the `Option` is `None`, it remains `None`
  */
 export declare const mapOptionEffect: {
-    <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(self: Lens<Option.Option<A>, ER, EW, RR, RW>, get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): Lens<Option.Option<B>, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
     <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): (self: Lens<Option.Option<A>, ER, EW, RR, RW>) => Lens<Option.Option<B>, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
+    <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(self: Lens<Option.Option<A>, ER, EW, RR, RW>, get: (a: NoInfer<A>) => Effect.Effect<B, EGet, RGet>, set: (a: NoInfer<A>, b: B) => Effect.Effect<NoInfer<A>, ESet, RSet>): Lens<Option.Option<B>, ER | EGet, EW | ESet, RR | RGet, RW | RSet>;
 };
 /**
  * Allows transforming only the `changes` stream of a `Lens` while keeping the focus type intact.
  */
 export declare const mapStream: {
-    <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, f: (changes: Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>) => Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>): Lens<A, ER, EW, RR, RW>;
     <A, ER, EW, RR, RW>(f: (changes: Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>) => Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER, EW, RR, RW>;
+    <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, f: (changes: Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>) => Stream.Stream<NoInfer<A>, NoInfer<ER>, NoInfer<RR>>): Lens<A, ER, EW, RR, RW>;
+};
+/**
+ * Transforms read errors of a `Lens`.
+ *
+ * Applies to `get` and `changes` while leaving `modify` unchanged.
+ */
+export declare const mapErrorRead: {
+    <A, ER, EW, RR, RW, E2>(f: (error: NoInfer<ER>) => E2): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, E2, EW, RR, RW>;
+    <A, ER, EW, RR, RW, E2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<ER>) => E2): Lens<A, E2, EW, RR, RW>;
+};
+/**
+ * Transforms modify errors of a `Lens`.
+ *
+ * Applies to the commit/rebuild portion of `modifyEffect` while leaving failures from the
+ * user-supplied callback unchanged.
+ */
+export declare const mapErrorWrite: {
+    <A, ER, EW, RR, RW, E2>(f: (error: NoInfer<EW>) => E2): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER, E2, RR, RW>;
+    <A, ER, EW, RR, RW, E2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<EW>) => E2): Lens<A, ER, E2, RR, RW>;
+};
+/**
+ * Transforms all errors of a `Lens`.
+ *
+ * Applies to `get`, `changes`, and the commit/rebuild portion of `modifyEffect` while leaving
+ * failures from the user-supplied callback unchanged.
+ */
+export declare const mapError: {
+    <A, ER, EW, RR, RW, E2>(f: (error: NoInfer<ER | EW>) => E2): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, E2, E2, RR, RW>;
+    <A, ER, EW, RR, RW, E2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<ER | EW>) => E2): Lens<A, E2, E2, RR, RW>;
+};
+/**
+ * Runs an effect when read failures occur.
+ *
+ * Applies to `get` and `changes` while leaving `modify` unchanged.
+ */
+export declare const tapErrorRead: {
+    <A, ER, EW, RR, RW, B, E2, R2>(f: (error: NoInfer<ER>) => Effect.Effect<B, E2, R2>): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER | E2, EW, RR | R2, RW>;
+    <A, ER, EW, RR, RW, B, E2, R2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<ER>) => Effect.Effect<B, E2, R2>): Lens<A, ER | E2, EW, RR | R2, RW>;
+};
+/**
+ * Runs an effect when modify failures occur.
+ *
+ * Applies to the commit/rebuild portion of `modifyEffect` while leaving failures from the
+ * user-supplied callback unchanged.
+ */
+export declare const tapErrorWrite: {
+    <A, ER, EW, RR, RW, B, E2, R2>(f: (error: NoInfer<EW>) => Effect.Effect<B, E2, R2>): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER, EW | E2, RR, RW | R2>;
+    <A, ER, EW, RR, RW, B, E2, R2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<EW>) => Effect.Effect<B, E2, R2>): Lens<A, ER, EW | E2, RR, RW | R2>;
+};
+/**
+ * Runs an effect when any `Lens` failure occurs.
+ *
+ * Applies to `get`, `changes`, and the commit/rebuild portion of `modifyEffect` while leaving
+ * failures from the user-supplied callback unchanged.
+ */
+export declare const tapError: {
+    <A, ER, EW, RR, RW, B, E2, R2>(f: (error: NoInfer<ER | EW>) => Effect.Effect<B, E2, R2>): (self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER | E2, EW | E2, RR | R2, RW | R2>;
+    <A, ER, EW, RR, RW, B, E2, R2>(self: Lens<A, ER, EW, RR, RW>, f: (error: NoInfer<ER | EW>) => Effect.Effect<B, E2, R2>): Lens<A, ER | E2, EW | E2, RR | R2, RW | R2>;
+};
+/**
+ * Provides a `Context` to a `Lens`, removing it from both the read and write environments.
+ */
+export declare const provideContext: {
+    <R2>(context: Context.Context<R2>): <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER, EW, Exclude<RR, R2>, Exclude<RW, R2>>;
+    <A, ER, EW, RR, RW, R2>(self: Lens<A, ER, EW, RR, RW>, context: Context.Context<R2>): Lens<A, ER, EW, Exclude<RR, R2>, Exclude<RW, R2>>;
+};
+/**
+ * Provides a single service to a `Lens`, removing it from both the read and write environments.
+ *
+ * This is the `Lens` equivalent of `Effect.provideService`: use it when a lens requires one
+ * `Context.Tag` and you already have the concrete service value.
+ */
+export declare const provideService: {
+    <I, S>(tag: Context.Tag<I, S>, service: NoInfer<S>): <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Lens<A, ER, EW, Exclude<RR, I>, Exclude<RW, I>>;
+    <A, ER, EW, RR, RW, I, S>(self: Lens<A, ER, EW, RR, RW>, tag: Context.Tag<I, S>, service: NoInfer<S>): Lens<A, ER, EW, Exclude<RR, I>, Exclude<RW, I>>;
 };
 /**
  * Narrows the focus to a field of an object. Replaces the object in an immutable fashion when written to.
  */
 export declare const focusObjectOn: {
-    <A extends object, ER, EW, RR, RW, K extends keyof A>(self: Lens<A, ER, EW, RR, RW>, key: K): Lens<A[K], ER, EW, RR, RW>;
     <A extends object, ER, EW, RR, RW, K extends keyof A>(key: K): (self: Lens<A, ER, EW, RR, RW>) => Lens<A[K], ER, EW, RR, RW>;
+    <A extends object, ER, EW, RR, RW, K extends keyof A>(self: Lens<A, ER, EW, RR, RW>, key: K): Lens<A[K], ER, EW, RR, RW>;
 };
 export declare namespace focusObjectOnWritable {
     type WritableKeys<T> = {
@@ -123,48 +288,85 @@ export declare namespace focusObjectOnWritable {
  * Narrows the focus to a writable field of an object. Mutates the object in place when written to.
  */
 export declare const focusObjectOnWritable: {
-    <A extends object, ER, EW, RR, RW, K extends focusObjectOnWritable.WritableKeys<A>>(self: Lens<A, ER, EW, RR, RW>, key: K): Lens<A[K], ER, EW, RR, RW>;
     <A extends object, ER, EW, RR, RW, K extends focusObjectOnWritable.WritableKeys<A>>(key: K): (self: Lens<A, ER, EW, RR, RW>) => Lens<A[K], ER, EW, RR, RW>;
+    <A extends object, ER, EW, RR, RW, K extends focusObjectOnWritable.WritableKeys<A>>(self: Lens<A, ER, EW, RR, RW>, key: K): Lens<A[K], ER, EW, RR, RW>;
 };
 /**
  * Narrows the focus to an indexed element of an array. Replaces the array in an immutable fashion when written to.
  */
 export declare const focusArrayAt: {
-    <A extends readonly any[], ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, index: number): Lens<A[number], ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
     <A extends readonly any[], ER, EW, RR, RW>(index: number): (self: Lens<A, ER, EW, RR, RW>) => Lens<A[number], ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
+    <A extends readonly any[], ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, index: number): Lens<A[number], ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
 };
 /**
  * Narrows the focus to an indexed element of a mutable array. Mutates the array in place when written to.
  */
 export declare const focusMutableArrayAt: {
-    <A, ER, EW, RR, RW>(self: Lens<A[], ER, EW, RR, RW>, index: number): Lens<A, ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
     <A, ER, EW, RR, RW>(index: number): (self: Lens<A[], ER, EW, RR, RW>) => Lens<A, ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
+    <A, ER, EW, RR, RW>(self: Lens<A[], ER, EW, RR, RW>, index: number): Lens<A, ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
 };
 /**
  * Narrows the focus to an indexed element of a readonly tuple. Replaces the tuple in an immutable fashion when written to.
  */
 export declare const focusTupleAt: {
-    <T extends readonly [any, ...any[]], ER, EW, RR, RW, I extends number>(self: Lens<T, ER, EW, RR, RW>, index: I): Lens<T[I], ER, EW, RR, RW>;
     <T extends readonly [any, ...any[]], ER, EW, RR, RW, I extends number>(index: I): (self: Lens<T, ER, EW, RR, RW>) => Lens<T[I], ER, EW, RR, RW>;
+    <T extends readonly [any, ...any[]], ER, EW, RR, RW, I extends number>(self: Lens<T, ER, EW, RR, RW>, index: I): Lens<T[I], ER, EW, RR, RW>;
 };
 /**
  * Narrows the focus to an indexed element of a mutable tuple. Mutates the tuple in place when written to.
  */
 export declare const focusMutableTupleAt: {
-    <T extends [any, ...any[]], ER, EW, RR, RW, I extends number>(self: Lens<T, ER, EW, RR, RW>, index: I): Lens<T[I], ER, EW, RR, RW>;
     <T extends [any, ...any[]], ER, EW, RR, RW, I extends number>(index: I): (self: Lens<T, ER, EW, RR, RW>) => Lens<T[I], ER, EW, RR, RW>;
+    <T extends [any, ...any[]], ER, EW, RR, RW, I extends number>(self: Lens<T, ER, EW, RR, RW>, index: I): Lens<T[I], ER, EW, RR, RW>;
 };
 /**
  * Narrows the focus to an indexed element of `Chunk`. Replaces the `Chunk` in an immutable fashion when written to.
  */
 export declare const focusChunkAt: {
-    <A, ER, EW, RR, RW>(self: Lens<Chunk.Chunk<A>, ER, EW, RR, RW>, index: number): Lens<A, ER | NoSuchElementException, EW, RR, RW>;
     <A, ER, EW, RR, RW>(index: number): (self: Lens<Chunk.Chunk<A>, ER, EW, RR, RW>) => Lens<A, ER | NoSuchElementException, EW, RR, RW>;
+    <A, ER, EW, RR, RW>(self: Lens<Chunk.Chunk<A>, ER, EW, RR, RW>, index: number): Lens<A, ER | NoSuchElementException, EW, RR, RW>;
+};
+/**
+ * Narrows the focus to the value inside an `Option`.
+ *
+ * Reading or writing through this lens fails with `NoSuchElementException` when the parent option is `None`.
+ * Writing wraps the new focused value back into `Option.some`.
+ */
+export declare const focusOption: {
+    <A, ER, EW, RR, RW>(self: Lens<Option.Option<A>, ER, EW, RR, RW>): Lens<A, ER | NoSuchElementException, EW | NoSuchElementException, RR, RW>;
 };
 /**
  * Reads the current value from a `Lens`.
  */
 export declare const get: <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER, RR>;
+/**
+ * Atomically modifies the value of a `Lens` and returns a computed result.
+ */
+export declare const modify: {
+    <A, B>(f: (a: A) => readonly [B, A]): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<B, ER | EW, RR | RW>;
+    <A, ER, EW, RR, RW, B>(self: Lens<A, ER, EW, RR, RW>, f: (a: A) => readonly [B, A]): Effect.Effect<B, ER | EW, RR | RW>;
+};
+/**
+ * Atomically modifies the value of a `Lens` with an effect and returns a computed result.
+ */
+export declare const modifyEffect: {
+    <A, B, E, R>(f: (a: A) => Effect.Effect<readonly [B, A], E, R>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<B, ER | EW | E, RR | RW | R>;
+    <A, ER, EW, RR, RW, B, E, R>(self: Lens<A, ER, EW, RR, RW>, f: (a: A) => Effect.Effect<readonly [B, A], E, R>): Effect.Effect<B, ER | EW | E, RR | RW | R>;
+};
+/**
+ * Conditionally modifies the value of a `Lens`, returning `fallback` when the function returns `None`.
+ */
+export declare const modifySome: {
+    <B, A>(fallback: B, pf: (a: NoInfer<A>) => Option.Option<readonly [B, NoInfer<A>]>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<B, ER | EW, RR | RW>;
+    <A, ER, EW, RR, RW, B>(self: Lens<A, ER, EW, RR, RW>, fallback: B, pf: (a: A) => Option.Option<readonly [B, A]>): Effect.Effect<B, ER | EW, RR | RW>;
+};
+/**
+ * Conditionally modifies the value of a `Lens` with an effect, returning `fallback` when the function returns `None`.
+ */
+export declare const modifySomeEffect: {
+    <B, A, E = never, R = never>(fallback: B, pf: (a: NoInfer<A>) => Option.Option<Effect.Effect<readonly [B, NoInfer<A>], E, R>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<B, ER | EW | E, RR | RW | R>;
+    <A, ER, EW, RR, RW, B, E = never, R = never>(self: Lens<A, ER, EW, RR, RW>, fallback: B, pf: (a: A) => Option.Option<Effect.Effect<readonly [B, A], E, R>>): Effect.Effect<B, ER | EW | E, RR | RW | R>;
+};
 /**
  * Sets the value of a `Lens`.
  */
@@ -207,6 +409,20 @@ export declare const getAndUpdateEffect: {
     <A, ER, EW, RR, RW, E, R>(f: (a: A) => Effect.Effect<A, E, R>): (self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW | E, RR | RW | R>;
     <A, ER, EW, RR, RW, E, R>(self: Lens<A, ER, EW, RR, RW>, f: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, ER | EW | E, RR | RW | R>;
 };
+/**
+ * Conditionally updates a `Lens` and returns the previous value.
+ */
+export declare const getAndUpdateSome: {
+    <A>(pf: (a: NoInfer<A>) => Option.Option<NoInfer<A>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW, RR | RW>;
+    <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<A>): Effect.Effect<A, ER | EW, RR | RW>;
+};
+/**
+ * Conditionally updates a `Lens` with an effect and returns the previous value.
+ */
+export declare const getAndUpdateSomeEffect: {
+    <A, E = never, R = never>(pf: (a: NoInfer<A>) => Option.Option<Effect.Effect<NoInfer<A>, E, R>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW | E, RR | RW | R>;
+    <A, ER, EW, RR, RW, E = never, R = never>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<Effect.Effect<A, E, R>>): Effect.Effect<A, ER | EW | E, RR | RW | R>;
+};
 /**
  * Sets the value of a `Lens` and returns the new value.
  */
@@ -228,4 +444,32 @@ export declare const updateAndGetEffect: {
     <A, ER, EW, RR, RW, E, R>(f: (a: A) => Effect.Effect<A, E, R>): (self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW | E, RR | RW | R>;
     <A, ER, EW, RR, RW, E, R>(self: Lens<A, ER, EW, RR, RW>, f: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, ER | EW | E, RR | RW | R>;
 };
+/**
+ * Conditionally updates the value of a `Lens`.
+ */
+export declare const updateSome: {
+    <A>(pf: (a: NoInfer<A>) => Option.Option<NoInfer<A>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<void, ER | EW, RR | RW>;
+    <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<A>): Effect.Effect<void, ER | EW, RR | RW>;
+};
+/**
+ * Conditionally updates the value of a `Lens` with an effect.
+ */
+export declare const updateSomeEffect: {
+    <A, E = never, R = never>(pf: (a: NoInfer<A>) => Option.Option<Effect.Effect<NoInfer<A>, E, R>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<void, ER | EW | E, RR | RW | R>;
+    <A, ER, EW, RR, RW, E = never, R = never>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<Effect.Effect<A, E, R>>): Effect.Effect<void, ER | EW | E, RR | RW | R>;
+};
+/**
+ * Conditionally updates a `Lens` and returns the resulting value.
+ */
+export declare const updateSomeAndGet: {
+    <A>(pf: (a: NoInfer<A>) => Option.Option<NoInfer<A>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW, RR | RW>;
+    <A, ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<A>): Effect.Effect<A, ER | EW, RR | RW>;
+};
+/**
+ * Conditionally updates a `Lens` with an effect and returns the resulting value.
+ */
+export declare const updateSomeAndGetEffect: {
+    <A, E = never, R = never>(pf: (a: NoInfer<A>) => Option.Option<Effect.Effect<NoInfer<A>, E, R>>): <ER, EW, RR, RW>(self: Lens<A, ER, EW, RR, RW>) => Effect.Effect<A, ER | EW | E, RR | RW | R>;
+    <A, ER, EW, RR, RW, E = never, R = never>(self: Lens<A, ER, EW, RR, RW>, pf: (a: A) => Option.Option<Effect.Effect<A, E, R>>): Effect.Effect<A, ER | EW | E, RR | RW | R>;
+};
 export {};