effect 4.0.0-beta.69 → 4.0.0-beta.70

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -165,10 +165,11 @@ export type StatusLiteral = keyof typeof statusCodeByLiteral
 /**
  * A convenience function to set the HTTP status code of a schema.
  *
- * This is equivalent to calling `.annotate({ httpApiStatus: code })` on the schema.
+ * **Details**
  *
- * You can pass either a numeric status code (for example, `201`) or a common
- * literal name (for example, `"Created"`).
+ * This is equivalent to calling `.annotate({ httpApiStatus: code })` on the
+ * schema. You can pass either a numeric status code (for example, `201`) or a
+ * common literal name (for example, `"Created"`).
  *
  * @category status
  * @since 4.0.0
@@ -255,6 +256,8 @@ export interface asNoContent<S extends Schema.Top> extends Schema.decodeTo<Schem
 /**
  * Marks a schema as a no-content response while preserving a decoded client value.
  *
+ * **Details**
+ *
  * The server encodes the response as `void`; generated clients call `decode` to
  * produce the schema's decoded value when the response has no body.
  *
@@ -410,6 +413,8 @@ export function asJson(options?: {
 /**
  * Marks a schema as an `application/x-www-form-urlencoded` payload or response.
  *
+ * **Details**
+ *
  * The schema's encoded side must be a record of strings.
  *
  * @category encoding
@@ -426,6 +431,8 @@ export function asFormUrlEncoded(options?: {
 /**
  * Marks a schema as a text payload / response.
  *
+ * **Details**
+ *
  * The schema encoded side must be a string.
  *
  * @category encoding
@@ -441,6 +448,8 @@ export function asText(options?: {
 /**
  * Marks a schema as a binary payload / response.
  *
+ * **Details**
+ *
  * The schema encoded side must be a `Uint8Array`.
  *
  * @category encoding
@@ -455,6 +464,8 @@ export function asUint8Array(options?: {
 /**
  * Returns `true` when a schema AST represents a no-content response.
  *
+ * **Details**
+ *
  * The check succeeds for direct `void` schemas and schemas whose encoded or
  * transformation target is `void`.
  *

package/src/unstable/httpapi/HttpApiSecurity.ts

@@ -120,10 +120,12 @@ const Proto = {
 }
 
 /**
- * Create an Bearer token security scheme.
+ * Creates a Bearer token security scheme.
  *
- * You can implement some api middleware for this security scheme using
- * `HttpApiBuilder.middlewareSecurity`.
+ * **When to use**
+ *
+ * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
+ * security scheme.
  *
  * @category constructors
  * @since 4.0.0
@@ -134,15 +136,17 @@ export const bearer: Bearer = Object.assign(Object.create(Proto), {
 })
 
 /**
- * Create an API key security scheme.
+ * Creates an API key security scheme.
  *
- * You can implement some api middleware for this security scheme using
- * `HttpApiBuilder.middlewareSecurity`.
+ * **When to use**
  *
- * To set the correct cookie in a handler, you can use
- * `HttpApiBuilder.securitySetCookie`.
+ * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
+ * security scheme.
  *
- * The default value for `in` is "header".
+ * **Details**
+ *
+ * Use `HttpApiBuilder.securitySetCookie` to set the correct cookie in a
+ * handler. By default, `in` is `"header"`.
  *
  * @category constructors
  * @since 4.0.0
@@ -161,8 +165,10 @@ export const apiKey = (options: {
 /**
  * Creates an HTTP Basic authentication security scheme.
  *
- * You can implement API middleware for this security scheme with
- * `HttpApiBuilder.middlewareSecurity`.
+ * **When to use**
+ *
+ * Use `HttpApiBuilder.middlewareSecurity` to implement API middleware for this
+ * security scheme.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiSwagger.ts

@@ -62,10 +62,8 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
 }
 
 /**
- * Mounts Swagger UI for an `HttpApi`.
- *
- * The route serves the OpenAPI specification generated from the API at the
- * configured path, defaulting to `/docs`.
+ * Mounts Swagger UI for an `HttpApi` at the configured path, defaulting to
+ * `/docs`, using the OpenAPI specification generated from the API.
  *
  * @category layers
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiTest.ts

@@ -43,6 +43,8 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
 /**
  * Creates an in-memory client for testing selected groups of an `HttpApi`.
  *
+ * **Details**
+ *
  * Handlers for the selected groups are taken from the environment; unselected
  * groups are wired with placeholder handlers that fail if called.
  *

package/src/unstable/httpapi/OpenApi.ts

@@ -154,6 +154,8 @@ export const Exclude = Context.Reference<boolean>("effect/httpapi/OpenApi/Exclud
 /**
  * OpenAPI annotation for transforming a generated OpenAPI object.
  *
+ * **Details**
+ *
  * The function is applied during generation to the annotated API, group tag, or
  * endpoint operation.
  *

package/src/unstable/observability/Otlp.ts

@@ -36,6 +36,8 @@ import * as OtlpTracer from "./OtlpTracer.ts"
 /**
  * Creates a combined OTLP layer for logs, metrics, and traces.
  *
+ * **Details**
+ *
  * The layer sends data to `/v1/logs`, `/v1/metrics`, and `/v1/traces` below
  * `baseUrl` and requires an `OtlpSerialization` implementation.
  *

package/src/unstable/observability/OtlpExporter.ts

@@ -61,6 +61,8 @@ const policy = Schedule.forever.pipe(
 /**
  * Creates a scoped OTLP batch exporter.
  *
+ * **Details**
+ *
  * The exporter buffers pushed data, periodically posts encoded batches to the
  * configured URL, retries transient failures, temporarily disables exporting
  * after unhandled failures, and flushes during scope finalization up to

package/src/unstable/observability/OtlpLogger.ts

@@ -38,6 +38,8 @@ import { OtlpSerialization } from "./OtlpSerialization.ts"
 /**
  * Creates an Effect `Logger` that exports log records through OTLP.
  *
+ * **Details**
+ *
  * The logger serializes records with the configured resource, sends them
  * through the OTLP exporter, and requires `Scope` so pending records can be
  * flushed on shutdown.
@@ -101,6 +103,8 @@ export const make: (
 /**
  * Installs the OTLP logger created by `make` as an Effect logging layer.
  *
+ * **Details**
+ *
  * By default the OTLP logger is merged with any existing loggers.
  *
  * @category layers

package/src/unstable/observability/OtlpMetrics.ts

@@ -39,14 +39,13 @@ import * as OtlpResource from "./OtlpResource.ts"
 import { OtlpSerialization } from "./OtlpSerialization.ts"
 
 /**
- * Determines how metric values relate to the time interval over which they
- * are aggregated.
+ * Determines how metric values relate to the time interval over which they are aggregated.
  *
- * - `"cumulative"`: Reports total since a fixed start time. Each data point
- *   depends on all previous measurements. This is the default behavior.
+ * **Details**
  *
- * - `"delta"`: Reports changes since the last export. Each interval is
- *   independent with no dependency on previous measurements.
+ * `"cumulative"` reports total since a fixed start time. Each data point depends on all previous measurements. This is the default behavior.
+ *
+ * `"delta"` reports changes since the last export. Each interval is independent with no dependency on previous measurements.
  *
  * **Example** (Configuring aggregation temporality)
  *
@@ -74,9 +73,9 @@ export type AggregationTemporality = "cumulative" | "delta"
 /**
  * Starts a scoped OTLP metrics exporter.
  *
- * The exporter snapshots registered Effect metrics on the configured interval,
- * serializes them with the selected aggregation temporality, and flushes during
- * scope finalization up to `shutdownTimeout`.
+ * **Details**
+ *
+ * The exporter snapshots registered Effect metrics on the configured interval, serializes them with the selected aggregation temporality, and flushes during scope finalization up to `shutdownTimeout`.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/observability/OtlpResource.ts

@@ -41,6 +41,8 @@ export interface Resource {
 /**
  * Creates an OTLP resource from service metadata and additional attributes.
  *
+ * **Details**
+ *
  * The resource always includes `service.name`, includes `service.version` when
  * provided, and converts custom attributes into OTLP attribute values.
  *
@@ -80,6 +82,8 @@ export const make = (options: {
  * Creates an OTLP resource from explicit options and OpenTelemetry
  * configuration.
  *
+ * **Details**
+ *
  * Explicit options override `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`,
  * and `OTEL_SERVICE_VERSION`; missing required configuration is converted to a
  * defect.
@@ -121,6 +125,8 @@ export const fromConfig: (
 /**
  * Returns the `service.name` attribute from an OTLP resource.
  *
+ * **Gotchas**
+ *
  * Throws if the resource does not contain a string `service.name` attribute.
  *
  * @category Attributes
@@ -156,6 +162,8 @@ export const entriesToAttributes = (entries: Iterable<[string, unknown]>): Array
 /**
  * Converts an arbitrary JavaScript value into an OTLP `AnyValue`.
  *
+ * **Details**
+ *
  * Arrays are converted recursively, primitive values use their matching OTLP
  * fields, and unsupported values are formatted as strings.
  *

package/src/unstable/observability/OtlpTracer.ts

@@ -43,8 +43,9 @@ import * as OtlpResource from "./OtlpResource.ts"
 import { OtlpSerialization } from "./OtlpSerialization.ts"
 
 /**
- * Creates a `Tracer` that exports ended sampled spans to an OTLP traces
- * endpoint.
+ * Creates a `Tracer` that exports ended sampled spans to an OTLP traces endpoint.
+ *
+ * **Details**
  *
  * Spans are batched using the configured interval and batch size, serialized
  * with `OtlpSerialization`, and flushed when the surrounding `Scope` closes.

package/src/unstable/observability/PrometheusMetrics.ts

@@ -141,8 +141,10 @@ export const format: (options?: FormatOptions | undefined) => Effect.Effect<stri
 /**
  * Synchronously format all metrics in the registry to Prometheus exposition format.
  *
- * This is a low-level function that requires access to the context.
- * Most users should use `format` instead.
+ * **When to use**
+ *
+ * Use this low-level function when you already have access to the context. Most
+ * users should use `format` instead.
  *
  * @category Formatting
  * @since 4.0.0
@@ -181,6 +183,8 @@ export const formatUnsafe = (
  * Creates a Layer that registers a `/metrics` HTTP endpoint for Prometheus
  * scraping.
  *
+ * **Details**
+ *
  * This layer automatically adds a GET route to your HTTP router that serves
  * metrics in Prometheus exposition format. By default, the endpoint is
  * registered at `/metrics`, but this can be customized via the `path` option.

package/src/unstable/persistence/KeyValueStore.ts

@@ -109,6 +109,8 @@ export interface KeyValueStore {
 /**
  * Implementation callbacks used by `make` to construct a `KeyValueStore`.
  *
+ * **Details**
+ *
  * Primitive operations are required, while helpers such as `has`, `isEmpty`,
  * and `modify` can be supplied to override the defaults.
  *
@@ -218,6 +220,8 @@ export const KeyValueStore: Context.Service<
 /**
  * Constructs a `KeyValueStore` from primitive store operations.
  *
+ * **Details**
+ *
  * Default implementations are derived for `has`, `isEmpty`, `modify`, and
  * `modifyUint8Array` unless they are provided in the options.
  *
@@ -260,6 +264,8 @@ export const make = (options: MakeOptions): KeyValueStore =>
 /**
  * Adapts a string-only backing store into a `KeyValueStore`.
  *
+ * **Details**
+ *
  * `Uint8Array` values are stored as base64 strings. `getUint8Array` decodes
  * base64 values and falls back to UTF-8 encoding for non-base64 strings.
  *
@@ -354,6 +360,8 @@ export const layerMemory: Layer.Layer<KeyValueStore> = Layer.sync(KeyValueStore)
 /**
  * Provides a `KeyValueStore` backed by files in the specified directory.
  *
+ * **Details**
+ *
  * The directory is created if needed, and each key is encoded as a file name.
  *
  * @category layers
@@ -474,6 +482,8 @@ export interface LayerSqlOptions {
 /**
  * Provides a SQL-backed `KeyValueStore`.
  *
+ * **Details**
+ *
  * The layer creates the configured table if it does not exist and stores both
  * string and binary values through the current `SqlClient`.
  *

package/src/unstable/persistence/Persistable.ts

@@ -139,6 +139,8 @@ export type TimeToLiveFn<K extends Any> = (exit: Exit.Exit<Success<K>, Error<K>>
 /**
  * Creates request classes that implement `Persistable` and `Request.Request`.
  *
+ * **Details**
+ *
  * The generated class stores the supplied tag, derives its primary key from
  * the payload, and carries schemas for persisted success and error exits.
  *

package/src/unstable/persistence/PersistedCache.ts

@@ -55,6 +55,8 @@ export interface PersistedCache<K extends Persistable.Any, out R = never> {
 /**
  * Creates a persisted cache for `Persistable` request keys.
  *
+ * **Details**
+ *
  * The cache reads persisted exits before running the lookup, stores lookup
  * exits with the configured persistent TTL, and also keeps a scoped in-memory
  * cache with its own capacity and TTL.

package/src/unstable/persistence/PersistedQueue.ts

@@ -66,6 +66,8 @@ export type TypeId = "~effect/persistence/PersistedQueue"
 /**
  * Persistent queue of schema-encoded values.
  *
+ * **Details**
+ *
  * `offer` enqueues values by id, and `take` processes one value at a time,
  * marking it complete on success or retrying it until the maximum attempts is
  * reached.
@@ -77,7 +79,9 @@ export interface PersistedQueue<in out A, out R = never> {
   readonly [TypeId]: TypeId
 
   /**
-   * Adds an element to the queue. Returns the id of the enqueued element.
+   * Adds an element to the queue and returns the id of the enqueued element.
+   *
+   * **Details**
    *
    * If an element with the same id already exists in the queue, it will not be
    * added again.
@@ -87,13 +91,14 @@ export interface PersistedQueue<in out A, out R = never> {
   }) => Effect.Effect<string, PersistedQueueError | Schema.SchemaError, R>
 
   /**
-   * Takes an element from the queue.
-   * If the queue is empty, it will wait until an element is available.
+   * Takes an element from the queue, waiting until one is available when the
+   * queue is empty.
    *
-   * If the returned effect succeeds, the element is marked as processed,
-   * otherwise it will be retried according to the provided options.
+   * **Details**
    *
-   * By default, max attempts is set to 10.
+   * If the returned effect succeeds, the element is marked as processed;
+   * otherwise it will be retried according to the provided options. By default,
+   * max attempts is set to 10.
    */
   readonly take: <XA, XE, XR>(
     f: (value: A, metadata: {
@@ -141,6 +146,8 @@ export const make = <S extends Schema.Top>(options: {
 /**
  * Creates a `PersistedQueueFactory` from the current `PersistedQueueStore`.
  *
+ * **Details**
+ *
  * Values are encoded and decoded with the supplied schema, automatically
  * assigned an id when needed, and acknowledged or retried according to the
  * `take` handler's exit.
@@ -250,6 +257,8 @@ export class PersistedQueueError extends Schema.ErrorClass<PersistedQueueError>(
 /**
  * Low-level backing store service used by `PersistedQueue`.
  *
+ * **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.
  *
@@ -286,6 +295,8 @@ export class PersistedQueueStore extends Context.Service<
 /**
  * Provides an in-memory `PersistedQueueStore`.
  *
+ * **Details**
+ *
  * The store is process-local and volatile; failed takes are requeued until the
  * configured maximum attempts is reached.
  *
@@ -357,6 +368,8 @@ export const layerStoreMemory: Layer.Layer<
 /**
  * Creates a Redis-backed `PersistedQueueStore`.
  *
+ * **Details**
+ *
  * The store uses Redis lists and hashes with worker locks, periodically
  * refreshes locks while items are being processed, and moves exhausted items
  * to a failed queue.
@@ -741,6 +754,8 @@ export const layerStoreRedis: (
 /**
  * Creates a SQL-backed `PersistedQueueStore`.
  *
+ * **Details**
+ *
  * The store creates the queue table and indexes, acquires rows with
  * per-worker locks, refreshes active locks while scoped takes are running, and
  * retries or completes rows according to the processing exit.

package/src/unstable/persistence/Persistence.ts

@@ -147,6 +147,8 @@ export interface BackingPersistenceStore {
 /**
  * Provides `Persistence` from `BackingPersistence`.
  *
+ * **Details**
+ *
  * The layer serializes and deserializes `Persistable` exits, applies
  * per-entry TTLs, and skips writes whose TTL is zero or negative.
  *
@@ -246,6 +248,8 @@ export const layer = Layer.effect(Persistence)(Effect.gen(function*() {
 /**
  * Provides an in-memory `BackingPersistence` grouped by store id.
  *
+ * **Details**
+ *
  * Entries are process-local and expire according to their stored TTL.
  *
  * @category layers
@@ -297,6 +301,8 @@ export const layerBackingMemory: Layer.Layer<BackingPersistence> = Layer.sync(Ba
 /**
  * Provides SQL-backed persistence using one table per store id.
  *
+ * **Details**
+ *
  * Each table is created if needed and stores JSON-encoded values with optional
  * expiration timestamps.
  *
@@ -510,6 +516,8 @@ export const layerBackingSqlMultiTable: Layer.Layer<
 /**
  * Provides SQL-backed persistence using a shared `effect_persistence` table.
  *
+ * **Details**
+ *
  * Rows are partitioned by `store_id` and store JSON-encoded values with
  * optional expiration timestamps.
  *
@@ -753,6 +761,8 @@ export const layerBackingSql: Layer.Layer<
 /**
  * Provides Redis-backed persistence.
  *
+ * **Details**
+ *
  * Each store id is used as a key prefix, values are JSON-encoded, and finite
  * TTLs are stored with Redis expiration.
  *
@@ -912,6 +922,8 @@ end
 /**
  * Provides `BackingPersistence` using a `KeyValueStore`.
  *
+ * **Details**
+ *
  * Each store id becomes a key prefix, and values are stored as JSON with
  * optional expiration timestamps.
  *
@@ -1063,6 +1075,8 @@ export const layerSql: Layer.Layer<Persistence, never, SqlClient.SqlClient> = la
 /**
  * Converts a TTL to an absolute expiration timestamp in milliseconds.
  *
+ * **Details**
+ *
  * Returns `null` for no TTL and uses `clock.currentTimeMillisUnsafe`, so it is
  * intended for backing-store internals.
  *

package/src/unstable/persistence/RateLimiter.ts

@@ -82,6 +82,8 @@ export const RateLimiter: Context.Service<RateLimiter, RateLimiter> = Context.Se
 /**
  * Creates a `RateLimiter` from the current `RateLimiterStore`.
  *
+ * **Details**
+ *
  * The limiter supports fixed-window and token-bucket algorithms and either
  * fails or returns a delay when a limit is exceeded.
  *
@@ -352,6 +354,8 @@ export type ErrorTypeId = "~@effect/experimental/RateLimiter/RateLimiterError"
 /**
  * Error reason for a rate-limit check that exceeded the configured limit.
  *
+ * **Details**
+ *
  * Includes the affected key, limit, remaining token count, and retry delay.
  *
  * @category errors
@@ -455,9 +459,8 @@ export class RateLimiterError extends Schema.ErrorClass<RateLimiterError>(ErrorT
 export interface ConsumeResult {
   /**
    * The amount of delay to wait before making the next request, when the rate
-   * limiter is using the "delay" `onExceeded` strategy.
-   *
-   * It will be Duration.zero if the request is allowed immediately.
+   * limiter is using the "delay" `onExceeded` strategy. It will be
+   * Duration.zero if the request is allowed immediately.
    */
   readonly delay: Duration.Duration
 

package/src/unstable/persistence/Redis.ts

@@ -45,6 +45,8 @@ export class Redis extends Context.Service<Redis, {
 /**
  * Creates a `Redis` service from a raw command sender.
  *
+ * **Details**
+ *
  * Lua scripts are loaded through `SCRIPT LOAD`, cached, and then invoked with
  * `EVALSHA`.
  *
@@ -111,6 +113,8 @@ const ScriptTypeId: ScriptTypeId = "~effect/persistence/Redis/Script"
 /**
  * Typed descriptor for a Redis Lua script.
  *
+ * **Details**
+ *
  * It defines the Lua source, parameter-to-argument mapping, Redis key count,
  * and result type used by `Redis.eval`.
  *
@@ -159,6 +163,8 @@ const ScriptProto = {
 /**
  * Constructs a typed Redis Lua script descriptor.
  *
+ * **Details**
+ *
  * The result type defaults to `void` and can be refined with
  * `withReturnType`.
  *