Add docs

packages/effect-fc/src/Lens.ts

@@ -5,6 +5,9 @@ import type { NoSuchElementException } from "effect/Cause"
 export const LensTypeId: unique symbol = Symbol.for("@effect-fc/Lens/Lens")
 export type LensTypeId = typeof LensTypeId
 
+/**
+ * Read/write view over a value that exposes the latest value and a stream of updates.
+ */
 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
@@ -14,6 +17,9 @@ extends Subscribable.Subscribable<A, ER, RR> {
     ) => Effect.Effect<B, ER | EW | E1, RR | RW | R1>
 }
 
+/**
+ * Internal `Lens` implementation.
+ */
 export class LensImpl<in out A, in out ER = never, in out EW = never, in out RR = never, in out RW = never>
     extends Pipeable.Class() implements Lens<A, ER, EW, RR, RW> {
     readonly [Readable.TypeId]: Readable.TypeId = Readable.TypeId
@@ -32,9 +38,15 @@ export class LensImpl<in out A, in out ER = never, in out EW = never, in out RR
 }
 
 
+/**
+ * Checks whether a value implements `Lens`.
+ */
 export const isLens = (u: unknown): u is Lens<unknown, unknown, unknown, unknown, unknown> => Predicate.hasProperty(u, LensTypeId)
 
 
+/**
+ * Builds a `Lens` instance when you supply how to read the current value, observe changes, and apply transformations.
+ */
 export const make = <A, ER, EW, RR, RW>(
     options: {
         readonly get: Effect.Effect<A, ER, RR>
@@ -61,7 +73,7 @@ export const make = <A, ER, EW, RR, RW>(
 )
 
 /**
- * Creates a `Lens` that directly proxies a `SubscriptionRef`.
+ * Creates a `Lens` that proxies a `SubscriptionRef`.
  */
 export const fromSubscriptionRef = <A>(
     ref: SubscriptionRef.SubscriptionRef<A>
@@ -73,6 +85,9 @@ export const fromSubscriptionRef = <A>(
     ) => ref.modifyEffect(f),
 })
 
+/**
+ * Flattens an effectful `Lens`.
+ */
 export 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> => make({
@@ -84,6 +99,9 @@ export const unwrap = <A, ER, EW, RR, RW, E1, R1>(
 })
 
 
+/**
+ * Derives a new `Lens` by applying synchronous getters and setters over the focused value.
+ */
 export const map: {
     <A, ER, EW, RR, RW, B>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -108,6 +126,9 @@ export const map: {
     ),
 }))
 
+/**
+ * Derives a new `Lens` by applying effectful getters and setters over the focused value.
+ */
 export const mapEffect: {
     <A, ER, EW, RR, RW, B, EGet = never, RGet = never, ESet = never, RSet = never>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -139,6 +160,9 @@ export const mapEffect: {
     )),
 }))
 
+/**
+ * Allows transforming only the `changes` stream of a `Lens` while keeping the focus type intact.
+ */
 export const mapStream: {
     <A, ER, EW, RR, RW>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -157,6 +181,9 @@ export const mapStream: {
 }))
 
 
+/**
+ * Narrows the focus to a field of an object. Replaces the object in an immutable fashion when written to.
+ */
 export const focusField: {
     <A extends object, K extends keyof A, ER, EW, RR, RW>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -187,6 +214,9 @@ export declare namespace focusMutableField {
     type IfEquals<X, Y, A = X, B = never> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? A : B
 }
 
+/**
+ * Narrows the focus to a mutable field of an object. Mutates the object in place when written to.
+ */
 export const focusMutableField: {
     <A extends object, K extends focusMutableField.WritableKeys<A>, ER, EW, RR, RW>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -200,6 +230,9 @@ export const focusMutableField: {
     key: K,
 ): Lens<A[K], ER, EW, RR, RW> => map(self, a => a[key], (a, b) => { a[key] = b; return a }))
 
+/**
+ * Narrows the focus to an indexed element of an array. Replaces the array in an immutable fashion when written to.
+ */
 export const focusArrayAt: {
     <A extends readonly any[], ER, EW, RR, RW>(
         self: Lens<A, ER, EW, RR, RW>,
@@ -217,6 +250,9 @@ export const focusArrayAt: {
     (a, b) => Array.replaceOption(a, index, b) as any,
 ))
 
+/**
+ * Narrows the focus to an indexed element of a mutable array. Mutates the array in place when written to.
+ */
 export const focusMutableArrayAt: {
     <A, ER, EW, RR, RW>(
         self: Lens<A[], ER, EW, RR, RW>,
@@ -237,6 +273,9 @@ export const focusMutableArrayAt: {
     ),
 ))
 
+/**
+ * Narrows the focus to an indexed element of `Chunk`. Replaces the `Chunk` in an immutable fashion when written to.
+ */
 export const focusChunkAt: {
     <A, ER, EW, RR, RW>(
         self: Lens<Chunk.Chunk<A>, ER, EW, RR, RW>,