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

package/src/unstable/http/Url.ts

@@ -38,7 +38,7 @@ import * as Result from "../../Result.ts"
 import * as UrlParams from "./UrlParams.ts"
 
 /**
- * Parses a URL string into a `URL` object, returning an `Result` type for safe
+ * Parses a URL string safely into a `URL` object, returning a `Result` type for
  * error handling.
  *
  * **Details**
@@ -89,7 +89,7 @@ import * as UrlParams from "./UrlParams.ts"
  */
 export const fromString: {
   /**
-   * Parses a URL string into a `URL` object, returning an `Result` type for safe
+   * Parses a URL string safely into a `URL` object, returning a `Result` type for
    * error handling.
    *
    * **Details**
@@ -147,8 +147,7 @@ export const fromString: {
   })
 
 /**
- * This function clones the original `URL` object and applies a callback to the
- * clone, allowing multiple updates at once.
+ * Updates a cloned `URL` with a callback, allowing multiple changes at once.
  *
  * **Example** (Mutating URL credentials)
  *
@@ -166,13 +165,12 @@ export const fromString: {
  * // Output: Mutated: https://user:pass@example.com/
  * ```
  *
- * @category Modifiers
+ * @category modifiers
  * @since 4.0.0
  */
 export const mutate: {
   /**
-   * This function clones the original `URL` object and applies a callback to the
-   * clone, allowing multiple updates at once.
+   * Updates a cloned `URL` with a callback, allowing multiple changes at once.
    *
    * **Example** (Mutating URL credentials)
    *
@@ -190,13 +188,12 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (f: (url: URL) => void): (self: URL) => URL
   /**
-   * This function clones the original `URL` object and applies a callback to the
-   * clone, allowing multiple updates at once.
+   * Updates a cloned `URL` with a callback, allowing multiple changes at once.
    *
    * **Example** (Mutating URL credentials)
    *
@@ -214,7 +211,7 @@ export const mutate: {
    * // Output: Mutated: https://user:pass@example.com/
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (self: URL, f: (url: URL) => void): URL
@@ -593,7 +590,7 @@ export const setUrlParams: {
 export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(url.searchParams)
 
 /**
- * Reads, modifies, and updates the query parameters of a URL.
+ * Reads the query parameters of a URL, modifies them, and updates the URL.
  *
  * **Details**
  *
@@ -615,12 +612,12 @@ export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(
  * // Output: https://example.com/?foo=bar&key=value
  * ```
  *
- * @category Modifiers
+ * @category modifiers
  * @since 4.0.0
  */
 export const modifyUrlParams: {
   /**
-   * Reads, modifies, and updates the query parameters of a URL.
+   * Reads the query parameters of a URL, modifies them, and updates the URL.
    *
    * **Details**
    *
@@ -642,12 +639,12 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): (url: URL) => URL
   /**
-   * Reads, modifies, and updates the query parameters of a URL.
+   * Reads the query parameters of a URL, modifies them, and updates the URL.
    *
    * **Details**
    *
@@ -669,7 +666,7 @@ export const modifyUrlParams: {
    * // Output: https://example.com/?foo=bar&key=value
    * ```
    *
-   * @category Modifiers
+   * @category modifiers
    * @since 4.0.0
    */
   (url: URL, f: (urlParams: UrlParams.UrlParams) => UrlParams.UrlParams): URL

package/src/unstable/http/UrlParams.ts

@@ -223,14 +223,14 @@ const fromInputNested = (input: Input): Array<[string | Array<string>, any]> =>
 }
 
 /**
- * Order-sensitive equivalence for `UrlParams`.
+ * Provides an order-sensitive `Equivalence` instance for `UrlParams`.
  *
  * **Details**
  *
  * Two values are equivalent when they contain the same key-value pairs in the same
  * order.
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const Equivalence: Equ.Equivalence<UrlParams> = Equ.make<UrlParams>((a, b) =>
@@ -337,7 +337,7 @@ export const getAll: {
 )
 
 /**
- * Returns the first value for a query parameter key.
+ * Returns the first value for a query parameter key safely.
  *
  * **Details**
  *
@@ -348,7 +348,7 @@ export const getAll: {
  */
 export const getFirst: {
   /**
-   * Returns the first value for a query parameter key.
+   * Returns the first value for a query parameter key safely.
    *
    * **Details**
    *
@@ -359,7 +359,7 @@ export const getFirst: {
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * Returns the first value for a query parameter key.
+   * Returns the first value for a query parameter key safely.
    *
    * **Details**
    *
@@ -378,7 +378,7 @@ export const getFirst: {
 )
 
 /**
- * Returns the last value for a query parameter key.
+ * Returns the last value for a query parameter key safely.
  *
  * **Details**
  *
@@ -389,7 +389,7 @@ export const getFirst: {
  */
 export const getLast: {
   /**
-   * Returns the last value for a query parameter key.
+   * Returns the last value for a query parameter key safely.
    *
    * **Details**
    *
@@ -400,7 +400,7 @@ export const getLast: {
    */
   (key: string): (self: UrlParams) => Option.Option<string>
   /**
-   * Returns the last value for a query parameter key.
+   * Returns the last value for a query parameter key safely.
    *
    * **Details**
    *
@@ -643,7 +643,7 @@ export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
 }> {}
 
 /**
- * Creates a `URL` by appending `UrlParams` and an optional hash to a URL string.
+ * Creates a `URL` safely by appending `UrlParams` and an optional hash to a URL string.
  *
  * **Details**
  *
@@ -761,7 +761,7 @@ export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, strin
 export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonString, UrlParamsSchema> {}
 
 /**
- * Extract a JSON value from the first occurrence of the given `field` in the
+ * Extracts a JSON value from the first occurrence of the given `field` in the
  * `UrlParams`.
  *
  * **Example** (Decoding JSON parameter fields)

package/src/unstable/httpapi/HttpApi.ts

@@ -250,14 +250,14 @@ export const make = <const Id extends string>(identifier: Id): HttpApi<Id, never
   })
 
 /**
- * Walks the groups and endpoints in an `HttpApi`.
+ * Describes the groups and endpoints in an `HttpApi`.
  *
  * **Details**
  *
  * The callbacks receive each group or endpoint with merged annotations, endpoint
  * middleware, and response schemas grouped by HTTP status.
  *
- * @category Reflection
+ * @category reflection
  * @since 4.0.0
  */
 export const reflect = <Id extends string, Groups extends HttpApiGroup.Any>(

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -85,7 +85,7 @@ import type * as HttpApiSecurity from "./HttpApiSecurity.ts"
 import * as OpenApi from "./OpenApi.ts"
 
 /**
- * Register an `HttpApi` with a `HttpRouter`.
+ * Registers an `HttpApi` with a `HttpRouter`.
  *
  * @category constructors
  * @since 4.0.0
@@ -186,7 +186,7 @@ export const group = <
 /**
  * Type identifier symbol used to brand `Handlers` values.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export const HandlersTypeId: unique symbol = Symbol.for("@effect/platform/HttpApiBuilder/Handlers")
@@ -194,7 +194,7 @@ export const HandlersTypeId: unique symbol = Symbol.for("@effect/platform/HttpAp
 /**
  * Type of the `Handlers` type identifier symbol.
  *
- * @category handlers
+ * @category type IDs
  * @since 4.0.0
  */
 export type HandlersTypeId = typeof HandlersTypeId
@@ -443,10 +443,10 @@ export const securityDecode = <Security extends HttpApiSecurity.HttpApiSecurity>
   HttpServerRequest | Request.ParsedSearchParams
 > => {
   switch (self._tag) {
-    case "Bearer": {
+    case "Http": {
       return Effect.map(
         HttpServerRequest,
-        (request) => Redacted.make((request.headers.authorization ?? "").slice(bearerLen)) as any
+        (request) => Redacted.make((request.headers.authorization ?? "").slice(self.schemeLength)) as any
       )
     }
     case "ApiKey": {
@@ -521,7 +521,6 @@ export const securitySetCookie = (
 // Internal
 // -----------------------------------------------------------------------------
 
-const bearerLen = `Bearer `.length
 const basicLen = `Basic `.length
 
 const HandlersProto = {

package/src/unstable/httpapi/HttpApiError.ts

@@ -427,7 +427,7 @@ export const ServiceUnavailableNoContent = ServiceUnavailable.pipe(HttpApiSchema
 /**
  * Type-level identifier used to mark `HttpApiSchemaError` values.
  *
- * @category Parsing errors
+ * @category type IDs
  * @since 4.0.0
  */
 export type HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSchemaError"
@@ -435,7 +435,7 @@ export type HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSche
 /**
  * Runtime identifier used to mark and detect `HttpApiSchemaError` values.
  *
- * @category Parsing errors
+ * @category type IDs
  * @since 4.0.0
  */
 export const HttpApiSchemaErrorTypeId: HttpApiSchemaErrorTypeId = "~effect/httpapi/HttpApiError/HttpApiSchemaError"

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -166,7 +166,7 @@ const statusCodeByLiteral = {
 export type StatusLiteral = keyof typeof statusCodeByLiteral
 
 /**
- * A convenience function to set the HTTP status code of a schema.
+ * Sets the HTTP status code of a schema.
  *
  * **Details**
  *
@@ -206,8 +206,7 @@ export const Empty = (code: number): Schema.Void => Schema.Void.pipe(status(code
 export interface NoContent extends Schema.Void {}
 
 /**
- * A void schema with the HTTP status code 204.
- * This is used to represent empty responses with the status code 204.
+ * Schema for empty HTTP responses with status code 204.
  *
  * @category Empty
  * @since 4.0.0
@@ -223,8 +222,7 @@ export const NoContent: NoContent = Empty(204)
 export interface Created extends Schema.Void {}
 
 /**
- * A void schema with the HTTP status code 201.
- * This is used to represent empty responses with the status code 201.
+ * Schema for empty HTTP responses with status code 201.
  *
  * @category Empty
  * @since 4.0.0
@@ -240,8 +238,7 @@ export const Created: Created = Empty(201)
 export interface Accepted extends Schema.Void {}
 
 /**
- * A void schema with the HTTP status code 202.
- * This is used to represent empty responses with the status code 202.
+ * Schema for empty HTTP responses with status code 202.
  *
  * @category Empty
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -51,7 +51,7 @@ const TypeId = "~effect/httpapi/HttpApiSecurity"
  * @category models
  * @since 4.0.0
  */
-export type HttpApiSecurity = Bearer | ApiKey | Basic
+export type HttpApiSecurity = Http | ApiKey | Basic
 
 /**
  * Helper types for HTTP API security schemes.
@@ -82,13 +82,16 @@ export declare namespace HttpApiSecurity {
 }
 
 /**
- * Bearer token security scheme whose decoded credential is a redacted token.
+ * Http token security scheme whose decoded credential is a redacted token.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Bearer extends HttpApiSecurity.Proto<Redacted> {
-  readonly _tag: "Bearer"
+export interface Http extends HttpApiSecurity.Proto<Redacted> {
+  readonly _tag: "Http"
+  readonly scheme: string
+  /** @internal */
+  readonly schemeLength: number
 }
 
 /**
@@ -131,6 +134,34 @@ const Proto = {
   }
 }
 
+/**
+ * Creates a Http token security scheme.
+ *
+ * **When to use**
+ *
+ * Use to require `Authorization: scheme ...` credentials for an HTTP API group
+ * or endpoint.
+ *
+ * **Details**
+ *
+ * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
+ * security scheme.
+ *
+ * @see {@link apiKey} for an API-key security scheme
+ * @see {@link basic} for an HTTP Basic security scheme
+ * @category constructors
+ * @since 4.0.0
+ */
+export const http = (options: {
+  readonly scheme: string
+}): Http =>
+  Object.assign(Object.create(Proto), {
+    _tag: "Http",
+    scheme: options.scheme,
+    schemeLength: options.scheme.length,
+    annotations: Context.empty()
+  })
+
 /**
  * Creates a Bearer token security scheme.
  *
@@ -149,10 +180,7 @@ const Proto = {
  * @category constructors
  * @since 4.0.0
  */
-export const bearer: Bearer = Object.assign(Object.create(Proto), {
-  _tag: "Bearer",
-  annotations: Context.empty()
-})
+export const bearer: Http = http({ scheme: "Bearer" })
 
 /**
  * Creates an API key security scheme.

package/src/unstable/httpapi/HttpApiTest.ts

@@ -48,7 +48,7 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
  * Handlers for the selected groups are taken from the environment; unselected
  * groups are wired with placeholder handlers that fail if called.
  *
- * @category Testing
+ * @category testing
  * @since 4.0.0
  */
 export const groups = Effect.fnUntraced(function*<

package/src/unstable/httpapi/OpenApi.ts

@@ -154,7 +154,13 @@ export class Deprecated extends Context.Service<Deprecated, boolean>()("effect/h
 export class Override extends Context.Service<Override, Record<string, unknown>>()("effect/httpapi/OpenApi/Override") {}
 
 /**
- * OpenAPI annotation reference that excludes an annotated group or endpoint from the generated specification.
+ * Annotation that excludes an annotated group or endpoint from the generated
+ * OpenAPI specification.
+ *
+ * **When to use**
+ *
+ * Use to hide internal, experimental, or otherwise undocumented HTTP API groups
+ * and endpoints from generated OpenAPI output.
  *
  * @category annotations
  * @since 4.0.0
@@ -724,7 +730,7 @@ const makeSecurityScheme = (security: HttpApiSecurity): OpenAPISecurityScheme =>
         scheme: "basic"
       }
     }
-    case "Bearer": {
+    case "Http": {
       const format = Context.getOption(security.annotations, Format).pipe(
         Option.map((format) => ({ bearerFormat: format })),
         Option.getOrUndefined
@@ -732,7 +738,7 @@ const makeSecurityScheme = (security: HttpApiSecurity): OpenAPISecurityScheme =>
       return {
         ...meta,
         type: "http",
-        scheme: "bearer",
+        scheme: security.scheme,
         ...format
       }
     }

package/src/unstable/observability/OtlpLogger.ts

@@ -117,7 +117,7 @@ export const make: (
 })
 
 /**
- * Installs the OTLP logger created by `make` as an Effect logging layer.
+ * Layer that installs the OTLP logger created by `make`.
  *
  * **Details**
  *

package/src/unstable/observability/PrometheusMetrics.ts

@@ -101,7 +101,7 @@ export interface HttpOptions extends FormatOptions {
 }
 
 /**
- * Format all metrics in the registry to Prometheus exposition format.
+ * Formats all metrics in the registry to Prometheus exposition format.
  *
  * **Example** (Formatting metrics)
  *
@@ -139,7 +139,7 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
 )
 
 /**
- * Synchronously format all metrics in the registry to Prometheus exposition format.
+ * Formats all metrics in the registry to Prometheus exposition format synchronously.
  *
  * **When to use**
  *

package/src/unstable/persistence/KeyValueStore.ts

@@ -101,7 +101,7 @@ export interface KeyValueStore {
   readonly has: (key: string) => Effect.Effect<boolean, KeyValueStoreError>
 
   /**
-   * Checks if the KeyValueStore contains any entries.
+   * Checks whether the KeyValueStore contains any entries.
    */
   readonly isEmpty: Effect.Effect<boolean, KeyValueStoreError>
 }
@@ -207,7 +207,12 @@ export class KeyValueStoreError extends Data.TaggedError("KeyValueStoreError")<{
 }
 
 /**
- * Context service tag for the `KeyValueStore` service.
+ * Service tag for string and binary key/value storage.
+ *
+ * **When to use**
+ *
+ * Use to access or provide the persistence store used for lightweight durable
+ * state.
  *
  * @category tags
  * @since 4.0.0
@@ -752,7 +757,7 @@ export interface SchemaStore<S extends Schema.Top> {
   readonly has: (key: string) => Effect.Effect<boolean, KeyValueStoreError>
 
   /**
-   * Checks if the KeyValueStore contains any entries.
+   * Checks whether the KeyValueStore contains any entries.
    */
   readonly isEmpty: Effect.Effect<boolean, KeyValueStoreError>
 }

package/src/unstable/persistence/Persistable.ts

@@ -31,10 +31,15 @@ import type * as Types from "../../Types.ts"
 import type { PersistenceError } from "./Persistence.ts"
 
 /**
- * Property key used to attach success and error schemas to persistable
+ * Defines the property key used to attach success and error schemas to persistable
  * requests.
  *
- * @category Symbols
+ * **When to use**
+ *
+ * Use to implement persistable request values by attaching success and error
+ * schemas at this property key.
+ *
+ * @category symbols
  * @since 4.0.0
  */
 export const symbol = "~effect/persistence/Persistable" as const
@@ -211,7 +216,7 @@ export const Class = <
  * Returns the cached `Exit` schema for a persistable request's success and
  * error schemas.
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const exitSchema = <A extends Schema.Top, E extends Schema.Top>(

package/src/unstable/persistence/PersistedQueue.ts

@@ -131,7 +131,7 @@ export class PersistedQueueFactory extends Context.Service<
  * Accesses `PersistedQueueFactory` to create a named persisted queue for a
  * schema.
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const make = <S extends Schema.Top>(options: {
@@ -220,7 +220,7 @@ export const layer: Layer.Layer<
 /**
  * Runtime type identifier for `PersistedQueueError`.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export const ErrorTypeId: ErrorTypeId = "~@effect/experimental/PersistedQueue/PersistedQueueError"
@@ -228,7 +228,7 @@ export const ErrorTypeId: ErrorTypeId = "~@effect/experimental/PersistedQueue/Pe
 /**
  * Type-level identifier used to brand `PersistedQueueError` values.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export type ErrorTypeId = "~@effect/experimental/PersistedQueue/PersistedQueueError"
@@ -255,14 +255,19 @@ export class PersistedQueueError extends Schema.ErrorClass<PersistedQueueError>(
 }
 
 /**
- * Low-level backing store service used by `PersistedQueue`.
+ * Defines the low-level backing store service used by `PersistedQueue`.
+ *
+ * **When to use**
+ *
+ * Use to provide the persistence backend that stores queued elements, scoped
+ * takes, retry attempts, and acknowledgements.
  *
  * **Details**
  *
  * The store persists offered elements and returns taken elements in a scope so
  * the finalizer can complete or retry them based on the processing exit.
  *
- * @category Store
+ * @category store
  * @since 4.0.0
  */
 export class PersistedQueueStore extends Context.Service<

package/src/unstable/persistence/RateLimiter.ts

@@ -72,9 +72,14 @@ export interface RateLimiter {
 }
 
 /**
- * Context service tag for the `RateLimiter` service.
+ * Service tag for persistent token-consumption services.
  *
- * @category Tags
+ * **When to use**
+ *
+ * Use to access or provide rate-limit checks backed by fixed-window counters or
+ * token-bucket state.
+ *
+ * @category tags
  * @since 4.0.0
  */
 export const RateLimiter: Context.Service<RateLimiter, RateLimiter> = Context.Service<RateLimiter>(TypeId)
@@ -235,7 +240,7 @@ export const layer: Layer.Layer<
 > = Layer.effect(RateLimiter, make)
 
 /**
- * Access a function that applies rate limiting to an effect.
+ * Accesses a function that applies rate limiting to an effect.
  *
  * **Example** (Applying rate limits to effects)
  *
@@ -260,7 +265,7 @@ export const layer: Layer.Layer<
  * })
  * ```
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const makeWithRateLimiter: Effect.Effect<
@@ -284,7 +289,7 @@ export const makeWithRateLimiter: Effect.Effect<
 )
 
 /**
- * Access a function that sleeps when the rate limit is exceeded.
+ * Accesses a function that sleeps when the rate limit is exceeded.
  *
  * **Example** (Sleeping until rate limit permits)
  *
@@ -307,7 +312,7 @@ export const makeWithRateLimiter: Effect.Effect<
  * })
  * ```
  *
- * @category Accessors
+ * @category accessors
  * @since 4.0.0
  */
 export const makeSleep: Effect.Effect<
@@ -338,7 +343,7 @@ export const makeSleep: Effect.Effect<
 /**
  * Runtime type identifier for `RateLimiterError`.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export const ErrorTypeId: ErrorTypeId = "~@effect/experimental/RateLimiter/RateLimiterError"
@@ -346,7 +351,7 @@ export const ErrorTypeId: ErrorTypeId = "~@effect/experimental/RateLimiter/RateL
 /**
  * Type-level identifier used to brand `RateLimiterError` values.
  *
- * @category errors
+ * @category type IDs
  * @since 4.0.0
  */
 export type ErrorTypeId = "~@effect/experimental/RateLimiter/RateLimiterError"
@@ -481,9 +486,14 @@ export interface ConsumeResult {
 }
 
 /**
- * Low-level backing store for fixed-window counters and token-bucket state.
+ * Defines the low-level backing store for fixed-window counters and token-bucket state.
  *
- * @category RateLimiterStore
+ * **When to use**
+ *
+ * Use to provide the shared counter storage used by persistent rate-limit
+ * checks.
+ *
+ * @category store
  * @since 4.0.0
  */
 export class RateLimiterStore extends Context.Service<