effect 4.0.0-beta.71 → 4.0.0-beta.73

package/src/unstable/eventlog/EventLogServerUnencrypted.ts

@@ -71,10 +71,15 @@ import {
 import * as EventLogServer from "./EventLogServer.ts"
 
 /**
- * Server-side service for writing plaintext event-log entries directly to
+ * Service that writes plaintext event-log entries directly to
  * unencrypted storage through registered event handlers.
  *
- * @category EventLogServerUnencrypted
+ * **When to use**
+ *
+ * Use to access or provide the server service that handles plaintext
+ * event-log writes.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogServerUnencrypted extends Context.Service<EventLogServerUnencrypted, {
@@ -277,10 +282,15 @@ export class EventLogServerAuthError extends Data.TaggedError("EventLogServerAut
 }> {}
 
 /**
- * Authorization service used by the unencrypted event-log server to validate
+ * Service that validates unencrypted event-log server
  * write access, read access, and identities.
  *
- * @category context
+ * **When to use**
+ *
+ * Use to provide authorization checks for plaintext event-log writes, reads,
+ * and identity authentication.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class EventLogServerAuthorization extends Context.Service<EventLogServerAuthorization, {
@@ -302,7 +312,12 @@ export class EventLogServerAuthorization extends Context.Service<EventLogServerA
  * Service that resolves client-requested store ids to server store ids and checks
  * whether a store exists.
  *
- * @category context
+ * **When to use**
+ *
+ * Use to map client-visible store identifiers to server storage identifiers
+ * before authorizing or serving unencrypted event-log requests.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export class StoreMapping extends Context.Service<StoreMapping, {
@@ -352,7 +367,12 @@ export const layerStoreMappingStatic = (options: {
   })
 
 /**
- * Storage service used by the unencrypted event-log server.
+ * Defines the backing store service used by the unencrypted event-log server.
+ *
+ * **When to use**
+ *
+ * Use to provide durable event-log persistence for an unencrypted event-log
+ * server layer.
  *
  * **Details**
  *
@@ -479,7 +499,12 @@ const toCompactedRemoteEntries = (options: {
 }
 
 /**
- * Compacts a backlog of remote entries using the registered compactors.
+ * Runs the registered compactors over a backlog of remote entries.
+ *
+ * **When to use**
+ *
+ * Use to reduce stored remote entries before replaying them to an unencrypted
+ * event-log client.
  *
  * **Details**
  *
@@ -759,6 +784,11 @@ export const make = Effect.gen(function*() {
  * Provides `EventLogServerUnencrypted` and an event-log `Registry` using the
  * configured unencrypted server `Storage`.
  *
+ * **When to use**
+ *
+ * Use to provide the unencrypted event-log server service together with the
+ * registry needed by event handlers.
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/unstable/eventlog/EventLogSessionAuth.ts

@@ -46,7 +46,13 @@ const textDecoder = new TextDecoder("utf-8", { fatal: true })
 const constLengthPrefixBytes = 4
 
 /**
- * Domain-separation string embedded in canonical session authentication payloads.
+ * Defines the domain-separation string embedded in canonical session
+ * authentication payloads.
+ *
+ * **When to use**
+ *
+ * Use when you need the domain-separation string used to build canonical
+ * event-log session authentication payloads.
  *
  * @category constants
  * @since 4.0.0
@@ -54,16 +60,26 @@ const constLengthPrefixBytes = 4
 export const AuthPayloadContext = "eventlog-auth-v1"
 
 /**
- * Required byte length for raw Ed25519 public keys used in session
+ * Defines the required byte length for raw Ed25519 public keys used in session
  * authentication.
  *
+ * **When to use**
+ *
+ * Use when you need to validate the byte length of raw Ed25519 public keys for
+ * session authentication.
+ *
  * @category constants
  * @since 4.0.0
  */
 export const Ed25519PublicKeyLength = 32
 
 /**
- * Required byte length for Ed25519 signatures used in session authentication.
+ * Defines the required byte length for Ed25519 signatures used in session authentication.
+ *
+ * **When to use**
+ *
+ * Use when you need to validate the byte length of Ed25519 signatures for
+ * session authentication.
  *
  * @category constants
  * @since 4.0.0
@@ -71,7 +87,12 @@ export const Ed25519PublicKeyLength = 32
 export const Ed25519SignatureLength = 64
 
 /**
- * Number of random bytes generated for a session authentication challenge.
+ * Defines the number of random bytes generated for a session authentication
+ * challenge.
+ *
+ * **When to use**
+ *
+ * Use when you need the challenge size for event-log session authentication.
  *
  * @category constants
  * @since 4.0.0
@@ -79,7 +100,13 @@ export const Ed25519SignatureLength = 64
 export const SessionAuthChallengeLength = 32
 
 /**
- * Time-to-live, in milliseconds, for a pending session authentication challenge.
+ * Defines the time-to-live, in milliseconds, for a pending session
+ * authentication challenge.
+ *
+ * **When to use**
+ *
+ * Use when you need the timeout for pending event-log session authentication
+ * challenges.
  *
  * @category constants
  * @since 4.0.0
@@ -347,8 +374,7 @@ export const decodeSessionAuthPayload = Effect.fnUntraced(
 )
 
 /**
- * Signs canonical session authentication payload bytes with an Ed25519 private
- * key.
+ * Creates a canonical session authentication signature with an Ed25519 private key.
  *
  * **Details**
  *

package/src/unstable/http/Cookies.ts

@@ -213,8 +213,8 @@ export const CookieSchema: CookieSchema = Schema.declare(
 const CookieErrorTypeId = "~effect/http/Cookies/CookieError"
 
 /**
- * Structured reason describing why cookie construction failed, such as invalid
- * name, value, domain, path, or infinite max-age.
+ * Error reason describing why cookie construction failed, such as invalid name,
+ * value, domain, path, or infinite max-age.
  *
  * @category errors
  * @since 4.0.0
@@ -548,21 +548,21 @@ export const makeCookieUnsafe = (
 ): Cookie => Result.getOrThrow(makeCookie(name, value, options))
 
 /**
- * Add a cookie to a Cookies object
+ * Adds a cookie to a Cookies object
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setCookie: {
   /**
-   * Add a cookie to a Cookies object
+   * Adds a cookie to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
    */
   (cookie: Cookie): (self: Cookies) => Cookies
   /**
-   * Add a cookie to a Cookies object
+   * Adds a cookie to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
@@ -579,21 +579,21 @@ export const setCookie: {
 )
 
 /**
- * Add multiple cookies to a Cookies object
+ * Adds multiple cookies to a Cookies object
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setAllCookie: {
   /**
-   * Add multiple cookies to a Cookies object
+   * Adds multiple cookies to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
    */
   (cookies: Iterable<Cookie>): (self: Cookies) => Cookies
   /**
-   * Add multiple cookies to a Cookies object
+   * Adds multiple cookies to a Cookies object
    *
    * @category combinators
    * @since 4.0.0
@@ -608,21 +608,21 @@ export const setAllCookie: {
 })
 
 /**
- * Combine two Cookies objects, removing duplicates from the first
+ * Combines two Cookies objects, removing duplicates from the first
  *
  * @category combinators
  * @since 4.0.0
  */
 export const merge: {
   /**
-   * Combine two Cookies objects, removing duplicates from the first
+   * Combines two Cookies objects, removing duplicates from the first
    *
    * @category combinators
    * @since 4.0.0
    */
   (that: Cookies): (self: Cookies) => Cookies
   /**
-   * Combine two Cookies objects, removing duplicates from the first
+   * Combines two Cookies objects, removing duplicates from the first
    *
    * @category combinators
    * @since 4.0.0
@@ -635,21 +635,21 @@ export const merge: {
   }))
 
 /**
- * Remove a cookie by name
+ * Removes a cookie by name
  *
  * @category combinators
  * @since 4.0.0
  */
 export const remove: {
   /**
-   * Remove a cookie by name
+   * Removes a cookie by name
    *
    * @category combinators
    * @since 4.0.0
    */
   (name: string): (self: Cookies) => Cookies
   /**
-   * Remove a cookie by name
+   * Removes a cookie by name
    *
    * @category combinators
    * @since 4.0.0
@@ -658,21 +658,21 @@ export const remove: {
 } = dual(2, (self: Cookies, name: string) => fromReadonlyRecord(Record.remove(self.cookies, name)))
 
 /**
- * Get a cookie from a Cookies object
+ * Gets a cookie from a Cookies object safely.
  *
  * @category combinators
  * @since 4.0.0
  */
 export const get: {
   /**
-   * Get a cookie from a Cookies object
+   * Gets a cookie from a Cookies object safely.
    *
    * @category combinators
    * @since 4.0.0
    */
   (name: string): (self: Cookies) => Option.Option<Cookie>
   /**
-   * Get a cookie from a Cookies object
+   * Gets a cookie from a Cookies object safely.
    *
    * @category combinators
    * @since 4.0.0
@@ -684,7 +684,7 @@ export const get: {
 )
 
 /**
- * Gets the decoded value of a cookie by name.
+ * Gets the decoded value of a cookie by name safely.
  *
  * **Details**
  *
@@ -695,7 +695,7 @@ export const get: {
  */
 export const getValue: {
   /**
-   * Gets the decoded value of a cookie by name.
+   * Gets the decoded value of a cookie by name safely.
    *
    * **Details**
    *
@@ -706,7 +706,7 @@ export const getValue: {
    */
   (name: string): (self: Cookies) => Option.Option<string>
   /**
-   * Gets the decoded value of a cookie by name.
+   * Gets the decoded value of a cookie by name safely.
    *
    * **Details**
    *
@@ -722,7 +722,7 @@ export const getValue: {
 )
 
 /**
- * Creates and adds a cookie by name and value.
+ * Creates and adds a cookie safely by name and value.
  *
  * **Details**
  *
@@ -733,7 +733,7 @@ export const getValue: {
  */
 export const set: {
   /**
-   * Creates and adds a cookie by name and value.
+   * Creates and adds a cookie safely by name and value.
    *
    * **Details**
    *
@@ -744,7 +744,7 @@ export const set: {
    */
   (name: string, value: string, options?: Cookie["options"]): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Creates and adds a cookie by name and value.
+   * Creates and adds a cookie safely by name and value.
    *
    * **Details**
    *
@@ -795,7 +795,7 @@ export const setUnsafe: {
 )
 
 /**
- * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+ * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
  *
  * **Details**
  *
@@ -806,7 +806,7 @@ export const setUnsafe: {
  */
 export const expireCookie: {
   /**
-   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
    *
    * **Details**
    *
@@ -820,7 +820,7 @@ export const expireCookie: {
     options?: Omit<NonNullable<Cookie["options"]>, "expires" | "maxAge">
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Adds an expired cookie with an empty value, `Max-Age=0`, and an epoch `Expires` value.
+   * Adds an expired cookie safely with an empty value, `Max-Age=0`, and an epoch `Expires` value.
    *
    * **Details**
    *
@@ -849,14 +849,14 @@ export const expireCookie: {
 )
 
 /**
- * Add an expired cookie to a Cookies object, throwing an error if invalid
+ * Adds an expired cookie to a Cookies object, throwing an error if invalid
  *
  * @category combinators
  * @since 4.0.0
  */
 export const expireCookieUnsafe: {
   /**
-   * Add an expired cookie to a Cookies object, throwing an error if invalid
+   * Adds an expired cookie to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -866,7 +866,7 @@ export const expireCookieUnsafe: {
     options?: Omit<NonNullable<Cookie["options"]>, "expires" | "maxAge">
   ): (self: Cookies) => Cookies
   /**
-   * Add an expired cookie to a Cookies object, throwing an error if invalid
+   * Adds an expired cookie to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -891,7 +891,7 @@ export const expireCookieUnsafe: {
 )
 
 /**
- * Creates and adds multiple cookies from name/value/options tuples.
+ * Creates and adds multiple cookies safely from name/value/options tuples.
  *
  * **Details**
  *
@@ -902,7 +902,7 @@ export const expireCookieUnsafe: {
  */
 export const setAll: {
   /**
-   * Creates and adds multiple cookies from name/value/options tuples.
+   * Creates and adds multiple cookies safely from name/value/options tuples.
    *
    * **Details**
    *
@@ -915,7 +915,7 @@ export const setAll: {
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
   ): (self: Cookies) => Result.Result<Cookies, CookiesError>
   /**
-   * Creates and adds multiple cookies from name/value/options tuples.
+   * Creates and adds multiple cookies safely from name/value/options tuples.
    *
    * **Details**
    *
@@ -947,14 +947,14 @@ export const setAll: {
 )
 
 /**
- * Add multiple cookies to a Cookies object, throwing an error if invalid
+ * Adds multiple cookies to a Cookies object, throwing an error if invalid
  *
  * @category combinators
  * @since 4.0.0
  */
 export const setAllUnsafe: {
   /**
-   * Add multiple cookies to a Cookies object, throwing an error if invalid
+   * Adds multiple cookies to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -963,7 +963,7 @@ export const setAllUnsafe: {
     cookies: Iterable<readonly [name: string, value: string, options?: Cookie["options"]]>
   ): (self: Cookies) => Cookies
   /**
-   * Add multiple cookies to a Cookies object, throwing an error if invalid
+   * Adds multiple cookies to a Cookies object, throwing an error if invalid
    *
    * @category combinators
    * @since 4.0.0
@@ -981,7 +981,7 @@ export const setAllUnsafe: {
 )
 
 /**
- * Serialize a cookie into a string
+ * Serializes a cookie into a string.
  *
  * **Details**
  *
@@ -1061,7 +1061,7 @@ export function serializeCookie(self: Cookie): string {
 }
 
 /**
- * Serialize a Cookies object into a Cookie header
+ * Serializes a `Cookies` object into a Cookie header.
  *
  * @category encoding
  * @since 4.0.0
@@ -1086,7 +1086,8 @@ export const toRecord = (self: Cookies): Record<string, string> => {
 }
 
 /**
- * Schema transformation between `Cookies` and a record of decoded string values keyed by cookie name.
+ * Schema for transforming `Cookies` into records of decoded string values keyed
+ * by cookie name.
  *
  * @category schemas
  * @since 4.0.0
@@ -1110,7 +1111,7 @@ export const schemaRecord = CookiesSchema.pipe(
 export const toSetCookieHeaders = (self: Cookies): Array<string> => Object.values(self.cookies).map(serializeCookie)
 
 /**
- * Parse a cookie header into a record of key-value pairs
+ * Parses a cookie header into a record of key-value pairs
  *
  * **Details**
  *

package/src/unstable/http/FetchHttpClient.ts

@@ -55,7 +55,12 @@ export const Fetch = Context.Reference<typeof globalThis.fetch>("effect/http/Fet
 })
 
 /**
- * Service containing default `RequestInit` options for the fetch-based HTTP client.
+ * Service that contains default fetch options for the fetch-based HTTP client.
+ *
+ * **When to use**
+ *
+ * Use to provide default credentials, cache, redirect, integrity, or other
+ * fetch options for outgoing HTTP requests.
  *
  * **Details**
  *

package/src/unstable/http/Headers.ts

@@ -70,7 +70,7 @@ import * as Transformation from "../../SchemaTransformation.ts"
 import type { Mutable } from "../../Types.ts"
 
 /**
- * This is a symbol to allow direct access of keys without conflicts.
+ * Runtime type identifier for `Headers` values.
  *
  * @category type IDs
  * @since 4.0.0
@@ -146,9 +146,10 @@ const make = (input: Record.ReadonlyRecord<string, string>): Mutable<Headers> =>
   Object.assign(Object.create(Proto), input) as Headers
 
 /**
- * Equivalence instance that compares `Headers` by their header names and string values.
+ * Provides an `Equivalence` instance that compares `Headers` by header names
+ * and string values.
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<Headers> = Record.makeEquivalence(Equ.strictEqual<string>())
@@ -250,7 +251,7 @@ export const fromInput: (input?: Input) => Headers = (input) => {
 }
 
 /**
- * Unsafely treats an existing record as `Headers`.
+ * Treats an existing record as `Headers` unsafely.
  *
  * **Gotchas**
  *
@@ -321,7 +322,7 @@ export const has: {
 >(2, (self, key) => key.toLowerCase() in self)
 
 /**
- * Gets a header value by name.
+ * Gets a header value by name safely.
  *
  * **Details**
  *
@@ -332,7 +333,7 @@ export const has: {
  */
 export const get: {
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -343,7 +344,7 @@ export const get: {
    */
   (key: string): (self: Headers) => Option.Option<string>
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -355,7 +356,7 @@ export const get: {
   (self: Headers, key: string): Option.Option<string>
 } = dual<
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *
@@ -366,7 +367,7 @@ export const get: {
    */
   (key: string) => (self: Headers) => Option.Option<string>,
   /**
-   * Gets a header value by name.
+   * Gets a header value by name safely.
    *
    * **Details**
    *

package/src/unstable/http/HttpBody.ts

@@ -198,9 +198,13 @@ export class Empty extends Proto {
 }
 
 /**
- * Singleton empty HTTP body.
+ * Provides the singleton empty HTTP body.
  *
- * @category constructors
+ * **When to use**
+ *
+ * Use when you need an HTTP body value that represents no body content.
+ *
+ * @category constants
  * @since 4.0.0
  */
 export const empty: Empty = new Empty()

package/src/unstable/http/HttpClient.ts

@@ -161,7 +161,12 @@ export declare namespace HttpClient {
 }
 
 /**
- * Service tag for the default `HttpClient` used by HTTP client accessors.
+ * Service tag for the default outgoing HTTP client service.
+ *
+ * **When to use**
+ *
+ * Use to provide the HTTP client implementation consumed by the module's
+ * request accessor functions.
  *
  * @category tags
  * @since 4.0.0
@@ -1680,21 +1685,36 @@ export const tapRequest: {
 )
 
 /**
- * Associates a `Ref` of cookies with the client for handling cookies across requests.
+ * Adds a `Ref` of cookies to the client for handling cookies across requests.
+ *
+ * **When to use**
+ *
+ * Use to add shared cookie storage to a client so response cookies are retained
+ * and sent by later requests.
  *
  * @category cookies
  * @since 4.0.0
  */
 export const withCookiesRef: {
   /**
-   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   *
+   * **When to use**
+   *
+   * Use to add shared cookie storage to a client so response cookies are retained
+   * and sent by later requests.
    *
    * @category cookies
    * @since 4.0.0
    */
   (ref: Ref.Ref<Cookies.Cookies>): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
   /**
-   * Associates a `Ref` of cookies with the client for handling cookies across requests.
+   * Adds a `Ref` of cookies to the client for handling cookies across requests.
+   *
+   * **When to use**
+   *
+   * Use to add shared cookie storage to a client so response cookies are retained
+   * and sent by later requests.
    *
    * @category cookies
    * @since 4.0.0
@@ -1725,9 +1745,9 @@ export const withCookiesRef: {
 )
 
 /**
- * Ties the lifetime of the `HttpClientRequest` to a `Scope`.
+ * Attaches the lifetime of the `HttpClientRequest` to a `Scope`.
  *
- * @category Scope
+ * @category resource management
  * @since 4.0.0
  */
 export const withScope = <E, R>(
@@ -1746,21 +1766,21 @@ export const withScope = <E, R>(
   )
 
 /**
- * Follows HTTP redirects up to a specified number of times.
+ * Enables following HTTP redirects up to a specified number of times.
  *
  * @category redirects
  * @since 4.0.0
  */
 export const followRedirects: {
   /**
-   * Follows HTTP redirects up to a specified number of times.
+   * Enables following HTTP redirects up to a specified number of times.
    *
    * @category redirects
    * @since 4.0.0
    */
   (maxRedirects?: number | undefined): <E, R>(self: HttpClient.With<E, R>) => HttpClient.With<E, R>
   /**
-   * Follows HTTP redirects up to a specified number of times.
+   * Enables following HTTP redirects up to a specified number of times.
    *
    * @category redirects
    * @since 4.0.0