effect 4.0.0-beta.78 → 4.0.0-beta.79

package/src/unstable/observability/Otlp.ts

@@ -1,37 +1,10 @@
 /**
- * Combined OTLP/HTTP export for Effect logs, metrics, and traces.
+ * Configures OpenTelemetry Protocol (OTLP) HTTP export for Effect telemetry.
  *
- * This module installs the signal-specific OTLP logger, metrics exporter, and
- * tracer exporter from one shared configuration. Use it when an application
- * sends all three observability signals to the same OpenTelemetry Collector,
- * vendor OTLP intake, or local development collector and should not configure
- * each exporter separately.
- *
- * **Mental model**
- *
- * `baseUrl` is the OTLP/HTTP root, such as `http://localhost:4318`. The
- * combined layer appends `/v1/logs`, `/v1/metrics`, and `/v1/traces`, then
- * delegates batching, resource handling, and payload construction to the
- * signal-specific modules. `layerJson` and `layerProtobuf` provide the
- * serialization layer; `layer` leaves `OtlpSerialization` in the requirements
- * so callers can provide a custom encoder.
- *
- * **Common tasks**
- *
- * - Use `layerJson` for JSON OTLP/HTTP endpoints and `layerProtobuf` for
- *   protobuf endpoints.
- * - Pass `headers` for collector authentication or routing.
- * - Set `resource` to define service name, service version, and additional
- *   resource attributes.
- * - Tune export intervals, `maxBatchSize`, `metricsTemporality`, and
- *   `shutdownTimeout` for the target backend.
- *
- * **Gotchas**
- *
- * Do not include a signal path in `baseUrl`; this module adds the paths itself.
- * Buffered telemetry flushes when the scoped exporters finalize, subject to
- * `shutdownTimeout`, so long-running services should keep the layer installed
- * for the lifetime of the runtime.
+ * This module installs the OTLP logger, metrics exporter, and tracer exporter
+ * from one shared configuration. Use it when an application sends logs, metrics,
+ * and traces to the same OpenTelemetry Collector, vendor OTLP endpoint, or local
+ * development collector.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpExporter.ts

@@ -1,27 +1,10 @@
 /**
- * Low-level OTLP/HTTP batch exporter used by the observability modules for
- * logs, metrics, and traces.
+ * Shared batch exporter for OTLP/HTTP observability modules.
  *
- * This module owns the scoped transport loop for already-encoded telemetry
- * payloads: callers provide the OTLP endpoint, request headers, a body encoder,
- * and batching settings, then push records that should be delivered to a
- * collector. It is useful when implementing a concrete signal exporter, such
- * as the OTLP logger or tracer, or when wiring a snapshot-based exporter like
- * metrics into the same lifecycle and retry behavior.
- *
- * The exporter sends HTTP POST requests with the provided `HttpClient`, disables
- * tracer propagation for its own traffic, retries transient failures, and
- * honors numeric `retry-after` values on 429 responses. Exports run on
- * `exportInterval`, flush during scope finalization up to `shutdownTimeout`,
- * and can also be triggered early when the buffered item count reaches
- * `maxBatchSize`.
- *
- * Use `maxBatchSize: "disabled"` only for pull-style exporters whose `body`
- * callback builds a fresh payload without relying on drained buffered items,
- * because pushed data is not cleared in that mode. After an unrecovered export
- * failure the exporter drops the buffered batch and disables exporting for 60
- * seconds, so choose intervals, batch sizes, headers, and shutdown timeouts with
- * collector limits and process shutdown behavior in mind.
+ * Signal modules use this exporter to buffer already-encoded telemetry and post
+ * it to a configured OTLP endpoint. It owns the scoped transport loop, batching,
+ * retry behavior, temporary disabling after repeated failures, and final flush
+ * during shutdown.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpLogger.ts

@@ -1,36 +1,10 @@
 /**
- * OTLP/HTTP log exporter for Effect's logging system.
+ * Exports Effect log entries over OTLP/HTTP.
  *
- * This module turns Effect log entries into OTLP log records and sends them to
- * a logs endpoint such as an OpenTelemetry Collector or vendor OTLP intake. It
- * is the signal-specific logger used by the higher-level `Otlp` module when an
- * application wants logs, metrics, and traces configured together.
- *
- * **Mental model**
- *
- * Each call to Effect logging APIs becomes one OTLP log record. The logger
- * serializes the message body, severity, timestamp, fiber id, log annotations,
- * failure cause, and current trace/span identifiers. Active log spans are
- * exported as duration attributes named `logSpan.<label>` unless
- * `excludeLogSpans` is enabled.
- *
- * **Common tasks**
- *
- * - Use `layer` to install the logger in an application; it merges with
- *   existing loggers by default.
- * - Use `make` when composing a custom `Logger` or logger layer manually.
- * - Pass the concrete `/v1/logs` endpoint, or use `Otlp` when a shared
- *   `baseUrl` should construct all signal paths.
- * - Provide `headers` for collector authentication or routing, and choose an
- *   `OtlpSerialization` layer accepted by the endpoint.
- *
- * **Gotchas**
- *
- * Batches are flushed on `exportInterval`, when `maxBatchSize` is reached, and
- * during scope finalization up to `shutdownTimeout`. Resource options are
- * attached to every export and override OpenTelemetry resource environment
- * variables, so ensure a stable `service.name` is available through options,
- * `OTEL_RESOURCE_ATTRIBUTES`, or `OTEL_SERVICE_NAME`.
+ * The logger turns Effect log entries into OTLP log records and sends them to a
+ * logs endpoint, such as an OpenTelemetry Collector or vendor OTLP endpoint. It
+ * includes log levels, messages, annotations, causes, fiber ids, optional log
+ * spans, and current trace/span ids when they are present.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpMetrics.ts

@@ -1,25 +1,13 @@
 /**
- * OTLP/HTTP metrics exporter for Effect's Metric system.
+ * Exports Effect metrics over OTLP/HTTP.
  *
- * This module periodically snapshots the metrics registered in the current
- * Effect context, serializes them as OTLP resource metrics, and posts them to a
- * metrics endpoint such as an OpenTelemetry Collector or vendor OTLP intake.
- * It is typically installed with `layer` in long-running services that already
- * update `Metric` counters, gauges, histograms, frequencies, or summaries and
- * need those values exported without adding instrumentation-specific plumbing
- * to the application code.
- *
- * Pass the concrete `/v1/metrics` endpoint to `make` or `layer`, or use the
- * higher-level `Otlp` module when you want `baseUrl` path construction for all
- * signals. The exporter requires an `HttpClient` and an `OtlpSerialization`
- * implementation, takes resource metadata from explicit options or standard
- * OTEL resource environment variables, and uses the resource `service.name` as
- * the instrumentation scope name. Choose `temporality` for the target backend:
- * cumulative is the default, while delta derives per-export changes from the
- * previous snapshot. Gauges always report their current value, and delta
- * histograms and summaries keep interval counts and sums from previous
- * snapshots, so tune export intervals and shutdown timeouts with backend
- * expectations and process shutdown behavior in mind.
+ * This module periodically snapshots metrics from the current Effect context,
+ * serializes them as OTLP resource metrics, and posts them to a metrics
+ * endpoint such as an OpenTelemetry Collector or vendor intake. It is meant for
+ * long-running services that already update `Metric` counters, gauges,
+ * histograms, frequencies, or summaries. The exporter supports cumulative
+ * reporting from a fixed start time and delta reporting from the previous
+ * export.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpResource.ts

@@ -1,40 +1,10 @@
 /**
- * OTLP resource metadata for logs, metrics, and traces exported by Effect.
+ * Builds OTLP resource metadata shared by exported telemetry.
  *
- * This module builds the resource object attached to every OTLP signal sent by
- * the Effect observability exporters. A resource carries service identity such
- * as `service.name` and `service.version`, plus process, host, deployment, or
- * application attributes that should be shared by all exported telemetry.
- *
- * **Mental model**
- *
- * A {@link Resource} is the OTLP envelope for service-level metadata. Use
- * {@link make} when the service metadata is already known, or use
- * {@link fromConfig} when explicit options should be merged with standard
- * OpenTelemetry environment variables before export. Attribute helpers convert
- * JavaScript values into OTLP {@link KeyValue} and {@link AnyValue} structures
- * used by JSON and protobuf serialization.
- *
- * **Common tasks**
- *
- * - Create explicit resource metadata with {@link make}.
- * - Read `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME`, and
- *   `OTEL_SERVICE_VERSION` with {@link fromConfig}.
- * - Convert custom attribute records with {@link entriesToAttributes}.
- * - Convert individual runtime values with {@link unknownToAttributeValue}.
- *
- * **Gotchas**
- *
- * `service.name` is required because the signal exporters also use it as the
- * instrumentation scope name. OpenTelemetry environment variables take
- * precedence over explicit options. `service.name` and `service.version` are
- * normalized into canonical OTLP attributes instead of being left in the custom
- * attribute map. Unsupported runtime values are formatted as strings.
- *
- * **See also**
- *
- * {@link Resource}, {@link make}, {@link fromConfig},
- * {@link unknownToAttributeValue}.
+ * An OTLP resource describes the service and other attributes attached to every
+ * exported log, metric, or trace. This module builds resources from explicit
+ * options or OpenTelemetry environment variables and converts JavaScript values
+ * into OTLP attribute values.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpSerialization.ts

@@ -1,31 +1,9 @@
 /**
- * OTLP/HTTP serialization service shared by logs, metrics, and traces.
+ * Serializes OTLP payloads into HTTP request bodies.
  *
- * This module decides how in-memory OTLP payloads become HTTP request bodies.
- * The signal exporters build trace, metric, and log data structures, then call
- * `OtlpSerialization` immediately before posting them to a collector.
- *
- * **Mental model**
- *
- * `OtlpSerialization` has one encoder per OTLP signal. `layerJson` writes the
- * structures directly with `HttpBody.jsonUnsafe`, which is useful for debugging
- * or endpoints that explicitly accept OTLP/HTTP JSON. `layerProtobuf` encodes
- * the same structures with the internal OTLP protobuf encoder and sets the
- * `application/x-protobuf` content type expected by many production collectors.
- *
- * **Common tasks**
- *
- * - Provide `layerProtobuf` for collectors that expect binary OTLP payloads.
- * - Provide `layerJson` when inspecting payloads or using an OTLP/HTTP JSON
- *   endpoint.
- * - Provide a custom `OtlpSerialization` service only when an exporter needs a
- *   non-standard body format.
- *
- * **Gotchas**
- *
- * This module only controls the wire format for traces, metrics, and logs.
- * Endpoint paths, authentication headers, batching, retries, and shutdown
- * flushing are handled by the OTLP exporter layers that consume the service.
+ * Signal exporters build trace, metric, and log data structures in memory. This
+ * module provides the service that turns those structures into JSON or protobuf
+ * HTTP bodies before they are posted to an OTLP collector.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/OtlpTracer.ts

@@ -1,25 +1,12 @@
 /**
- * Exports Effect spans to an OpenTelemetry Protocol (OTLP) traces endpoint.
+ * Exports Effect tracing spans over OTLP/HTTP.
  *
- * This module creates a `Tracer.Tracer` backed by the shared OTLP/HTTP batch
- * exporter, so Effect spans created with tracing APIs can be delivered to an
- * OpenTelemetry Collector, vendor OTLP intake, or local development collector.
- * Use `make` when you need to install the tracer manually, or `layer` when an
- * application should provide it through the Effect environment.
- *
- * Pass a concrete traces endpoint, typically `/v1/traces`, or use the
- * higher-level `Otlp` module when you want `baseUrl` path construction for all
- * observability signals. The tracer exports only ended sampled spans, converts
- * span attributes, events, links, status, parent identifiers, and failure
- * causes into OTLP trace data, and groups every batch under the configured
- * resource. Resource options are resolved through `OtlpResource`, so ensure a
- * stable `service.name` is available through options or standard OTEL resource
- * environment variables because it is also used as the instrumentation scope
- * name. Tune `exportInterval`, `maxBatchSize`, and `shutdownTimeout` for the
- * target backend and process shutdown behavior, provide `headers` for
- * authentication or routing, choose an `OtlpSerialization` layer accepted by
- * the endpoint, and use `context` only when a backend needs custom evaluation
- * around the active span.
+ * This module creates a `Tracer.Tracer` backed by the shared OTLP batch
+ * exporter, so spans created by Effect tracing APIs can be sent to an
+ * OpenTelemetry Collector, vendor endpoint, or local collector. Exported spans
+ * include identifiers, parent links, attributes, events, timing, kind, and
+ * status information. Use the constructor directly or install it through the
+ * provided layer.
  *
  * @since 4.0.0
  */

package/src/unstable/observability/PrometheusMetrics.ts

@@ -1,46 +1,9 @@
 /**
- * Prometheus metrics exporter for Effect's Metric system.
+ * Formats Effect metrics for Prometheus.
  *
- * This module snapshots the metrics registered in the current Effect context
- * and renders them in the Prometheus text exposition format. It is intended for
- * services that already record `Metric` counters, gauges, histograms,
- * frequencies, or summaries and need a pull-based `/metrics` endpoint, or for
- * integrations that want the formatted scrape body for a custom HTTP server.
- *
- * Use `format` when you need the current runtime's registry rendered as a
- * string, `formatUnsafe` when you already have the `Context`, and `layerHttp`
- * when an `HttpRouter` should serve `GET /metrics` directly. Formatting happens
- * at scrape time; the module does not push metrics, schedule exports, or start
- * an HTTP server on its own. Make sure the route is installed in the same
- * application context that records the metrics you want to expose.
- *
- * Metric and label names are sanitized for Prometheus, optional prefixes and
- * name mappers are applied before output, and metric attributes become labels.
- * Keep attributes low-cardinality, avoid relying on invalid characters being
- * preserved exactly, and configure Prometheus to scrape the route served by
- * `layerHttp` with the expected `text/plain; version=0.0.4` response.
- *
- * **Example** (Exporting Prometheus metrics)
- *
- * ```ts
- * import { Effect, Metric } from "effect"
- * import { PrometheusMetrics } from "effect/unstable/observability"
- *
- * const program = Effect.gen(function*() {
- *   // Create and update metrics
- *   const counter = Metric.counter("http_requests_total", {
- *     description: "Total HTTP requests"
- *   })
- *   yield* Metric.update(counter, 42)
- *
- *   // Format metrics for Prometheus
- *   const output = yield* PrometheusMetrics.format()
- *   console.log(output)
- *   // # HELP http_requests_total Total HTTP requests
- *   // # TYPE http_requests_total counter
- *   // http_requests_total 42
- * })
- * ```
+ * This module reads metrics from the current Effect context and renders them in
+ * the Prometheus text format. It can also register a pull-based HTTP endpoint,
+ * such as `/metrics`, for Prometheus to scrape.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/KeyValueStore.ts

@@ -1,24 +1,12 @@
 /**
- * Effectful key/value storage for persistence backends.
- *
- * This module defines the `KeyValueStore` service used by the persistence
- * package when a simple string or binary store is enough. It is useful for
- * lightweight durable state, browser storage, local file-backed data, SQL
- * tables, test stores, and as the storage primitive underneath higher-level
- * persistence APIs.
- *
- * Values are stored as strings or `Uint8Array`s, and `toSchemaStore` adds a
- * schema-aware JSON layer for typed values. Schema changes can make existing
- * JSON fail to decode, and `prefix` should be used to separate namespaces when
- * several logical stores share the same backend. This service does not provide
- * native TTL support; higher-level persistence layers encode expiration
- * metadata in stored values when they need TTLs.
- *
- * Backend behavior is intentionally small but not identical: Web Storage is
- * string-only, `makeStringOnly` stores binary values as base64, filesystem
- * keys become encoded file names, SQL stores value type metadata in a table,
- * and the memory layer is process-local. Choose keys, prefixes, table names,
- * and value formats with those backend constraints in mind.
+ * Provides effectful key/value storage for persistence backends.
+ *
+ * `KeyValueStore` is a service for storing string or binary values by key. It
+ * is useful for lightweight durable state, browser storage, local files, SQL
+ * tables, tests, and as a storage building block for higher-level persistence
+ * APIs. This module includes store operations, prefixed views, schema-aware JSON
+ * storage, error values, and layers for memory, filesystem, Web Storage, and
+ * SQL-backed stores.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/Persistable.ts

@@ -1,23 +1,9 @@
 /**
- * Defines the request-side contract used by the persistence layer.
+ * Describes request values whose results can be persisted.
  *
- * A `Persistable` request is a `PrimaryKey` value that carries the success and
- * error schemas needed to encode and decode the stored `Exit` for that request.
- * Persisted request resolvers and `PersistedCache` use this metadata to restore
- * previous lookup results from a backing store before running the lookup again.
- *
- * Use `Class` for cacheable or durable requests whose results can safely be
- * reused across fibers, processes, or restarts. The request primary key is the
- * entry id inside a persistence store, so it should be stable, collision-free,
- * and usually include a request-specific prefix. The `storeId` is configured on
- * `Persistence` or `PersistedCache`; it selects the backing store namespace and
- * is separate from the request primary key.
- *
- * Success and error schemas are encoded with the JSON codec, so persisted
- * values must be representable by those schemas and any required schema services
- * must be available where the store reads or writes entries. Changing a schema,
- * primary-key format, or store id can make existing persisted values fail to
- * decode or stop being found, so treat those changes as persistence migrations.
+ * A `Persistable` request has a primary key and schemas for its success and
+ * error results. `Persistence` and `PersistedCache` use that information to
+ * store the request's `Exit` value and restore it later from a backing store.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/PersistedCache.ts

@@ -1,33 +1,10 @@
 /**
- * Combines scoped memory caching with durable persistence for `Persistable`
- * lookup keys.
+ * Combines in-memory caching with durable storage for `Persistable` requests.
  *
- * A `PersistedCache` first checks a process-local `Cache`, then a named
- * `Persistence` store, before running the supplied lookup. It is designed for
- * expensive or idempotent requests whose encoded `Exit` can be reused across
- * fibers, process restarts, or multiple workers sharing the same backing store.
- *
- * **Mental model**
- *
- * `make` creates a scoped cache backed by a scoped persistence store. The memory
- * cache controls repeated reads inside the current runtime with `inMemoryTTL`
- * and capacity, while the persistence store controls durable reuse with
- * `timeToLive`, `storeId`, and request primary keys. Both successes and failures
- * are stored as `Exit` values when the persistent TTL allows the write.
- *
- * **Common tasks**
- *
- * Use `get` for lookups that should reuse memory and persisted values, and use
- * `invalidate` when the underlying data changes so both layers forget the key.
- * Use `requireServicesAt` to choose whether lookup services are supplied when
- * constructing the cache or when reading from it.
- *
- * **Gotchas**
- *
- * Persisted entries are decoded with the key's success and error schemas.
- * Changing schemas, primary-key formats, or `storeId` values is a persistence
- * migration; old entries can stop being found or fail to decode. `invalidate`
- * removes the persisted value first and then the in-memory entry.
+ * A `PersistedCache` checks a process-local `Cache`, then a named `Persistence`
+ * store, before running the supplied lookup. It stores the lookup `Exit`, so
+ * expensive or idempotent results can be reused across fibers, process restarts,
+ * or workers that share the same backing store.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/PersistedQueue.ts

@@ -1,28 +1,12 @@
 /**
- * Schema-aware persisted queues for background work.
+ * Stores schema-encoded queue work in persistent storage.
  *
- * A `PersistedQueue` stores JSON-encoded values in a named queue and lets
- * workers `take` one value at a time inside a scoped processing window. It is
+ * A `PersistedQueue<A>` keeps JSON-encoded values in a named queue and lets
+ * workers take one value at a time inside a scoped processing window. It is
  * useful for durable handoffs, background jobs, outbox-style integrations, and
- * workloads where failed work should be retried across fibers, process
- * restarts, or multiple workers sharing Redis or SQL.
- *
- * Delivery is at-least-once: a handler that fails, is interrupted, or loses its
- * backing-store lock may see the same element again until `maxAttempts` is
- * reached. Use stable custom ids when offering idempotent work, and choose ids
- * that are collision-free for the backing store because stores can enforce
- * uniqueness at the queue, prefix, or table level. Ordering is intentionally a
- * store-level concern; retries, lock expiration, polling, and multiple workers
- * can move entries behind newer work, so handlers should not rely on strict
- * FIFO processing.
- *
- * Values are encoded and decoded with the supplied schema using the JSON codec,
- * so schema services must be available when offering and taking values. Changing
- * a queue name, schema, Redis prefix, SQL table, or id format is a persistence
- * migration: old entries may decode differently, stop being visible, or collide
- * with new entries. The memory store is process-local and volatile, while Redis
- * and SQL stores use leases that should be tuned for the expected processing
- * time.
+ * work that should retry across fibers, process restarts, or multiple workers.
+ * This module includes a queue factory, store service, id-based de-duplication,
+ * retry handling, and in-memory, Redis, and SQL-backed store layers.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/Persistence.ts

@@ -1,26 +1,10 @@
 /**
- * Durable storage for encoded `Persistable` request results.
+ * Stores encoded results for `Persistable` requests.
  *
- * The `Persistence` service creates scoped stores that read and write
- * schema-encoded `Exit` values keyed by each request's `PrimaryKey`. It is the
- * lower-level persistence layer used by `PersistedCache` and similar request
- * workflows to reuse expensive or idempotent lookup results across fibers,
- * process restarts, and workers that share a backing store.
- *
- * Each store is selected by a `storeId`, while each entry id comes from the
- * request's primary key. Keep both stable and collision-free: changing the
- * `storeId`, the primary-key format, or the success/error schemas is a
- * persistence migration, because old entries may stop being found or fail to
- * decode. Values are encoded with the request's success and error schemas using
- * the JSON codec, so any required schema services must be available at store
- * read and write time, and the backing value must stay JSON-compatible.
- *
- * TTLs are computed from the stored `Exit` and request key. Infinite TTLs are
- * stored without an expiration, finite TTLs become backing-store expirations,
- * and zero or negative TTLs skip the write entirely. Backing layers provide
- * process-local memory, `KeyValueStore`, Redis, and SQL implementations; store
- * ids are used as prefixes, table names, or SQL partitions and should be
- * chosen with the target backing store in mind.
+ * The `Persistence` service creates scoped stores keyed by each request's
+ * `PrimaryKey`. Stores read and write schema-encoded `Exit` values with
+ * optional TTLs, letting request workflows reuse expensive or idempotent results
+ * across fibers, process restarts, or workers that share a backing store.
  *
  * @since 4.0.0
  */

package/src/unstable/persistence/RateLimiter.ts

@@ -1,28 +1,12 @@
 /**
- * Persistent rate limiting for effects that need to coordinate token
- * consumption through a shared `RateLimiterStore`.
- *
- * The module exposes a `RateLimiter` service that can consume tokens for
- * string keys using either fixed-window counters or token-bucket state. It is
- * useful for protecting external APIs, enforcing per-user or per-tenant quotas,
- * throttling job workers, and coordinating limits across multiple fibers or
- * processes when they share the Redis-backed store. The helpers can fail fast
- * with `RateLimiterError`, return a delay to apply yourself, or wrap an effect
- * so it waits before continuing.
- *
- * Rate-limit keys and Redis prefixes are part of the persistence namespace, so
- * choose stable, collision-free values. The in-memory store is process-local
- * and is only coordinated inside one runtime, while the Redis store uses Lua
- * scripts for atomic updates under concurrent consumers. Time is measured with
- * the Effect `Clock`, windows are clamped to at least one millisecond, and
- * refill calculations use millisecond granularity.
- *
- * Fixed-window state is TTL-driven: rejected `fail` attempts do not extend the
- * current TTL, and Redis fixed-window keys expire automatically. Token-bucket
- * state keeps the remaining token count and last-refill time instead of using a
- * TTL, so high-cardinality dynamic keys may need an external cleanup or bounded
- * key strategy. With `onExceeded: "delay"`, overflow can be recorded so callers
- * should actually sleep for the returned delay, or use the provided accessors.
+ * Coordinates rate limits through shared persistent storage.
+ *
+ * The `RateLimiter` service consumes tokens for string keys using fixed-window
+ * counters or token-bucket state. It can protect external APIs, enforce quotas,
+ * or throttle workers across fibers and processes that share the same store.
+ * This module includes helpers that fail when a limit is exceeded, return the
+ * delay needed before continuing, or wrap an effect so it waits automatically.
+ * It also defines the store service and in-memory or Redis-backed store layers.
  *
  * @since 4.0.0
  */
@@ -709,28 +693,26 @@ local overflow = ARGV[5] == "1"
 local current = tonumber(redis.call("GET", key))
 local last_refill = tonumber(redis.call("GET", last_refill_key))
 
-if not current then
-  current = limit
-  last_refill = now
-  redis.call("SET", key, current)
-  redis.call("SET", last_refill_key, last_refill)
-end
+if not current then current = limit end
+if not last_refill then last_refill = now end
 
 local elapsed = now - last_refill
 local refill_amount = math.floor(elapsed / refill_ms)
 if refill_amount > 0 then
   current = math.min(current + refill_amount, limit)
   last_refill = last_refill + (refill_amount * refill_ms)
-  redis.call("SET", last_refill_key, last_refill)
 end
 
 local next = current - tokens
-if next < 0 and not overflow then
-  redis.call("SET", key, current)
-  return next
+local stored = current
+if next >= 0 or overflow then
+  stored = next
 end
 
-redis.call("SET", key, next)
+local ttl = math.floor((limit - stored) * refill_ms)
+if ttl < 1 then ttl = 1 end
+redis.call("SET", key, stored, "PX", ttl)
+redis.call("SET", last_refill_key, last_refill, "PX", ttl)
 return next
 `
   }

package/src/unstable/persistence/Redis.ts

@@ -1,37 +1,11 @@
 /**
- * Redis service adapter for Effect persistence modules.
+ * Redis support shared by persistence modules.
  *
- * This module defines the low-level {@link Redis} service used by Redis-backed
- * persistence, persisted queues, and rate limiter stores. It adapts a Redis
- * client or pool into Effect through a raw `send` command function and cached
- * Lua script execution.
- *
- * **Mental model**
- *
- * The service does not create or own Redis connections. {@link make} wraps a
- * caller-provided command sender, while {@link script} describes a Lua script's
- * source, parameters, key count, and result type. The service loads scripts
- * with `SCRIPT LOAD`, caches the returned SHA, and runs them with `EVALSHA`
- * through `Redis.eval`.
- *
- * **Common tasks**
- *
- * - Wrap an existing Redis client by implementing `send`.
- * - Use `Redis.send` for ordinary Redis commands.
- * - Use {@link script} for typed Lua helpers shared by persistence stores.
- * - Map client or network failures into {@link RedisError} in the provided
- *   command sender.
- *
- * **Gotchas**
- *
- * Script parameters are stringified before execution. The script descriptor's
- * key count controls how Redis splits `KEYS` from `ARGV`. Higher-level stores
- * add key prefixes and store ids on top of this service, so those identifiers
- * must stay stable when persisted data is expected to survive deployments.
- *
- * **See also**
- *
- * {@link Redis}, {@link make}, {@link script}, {@link RedisError}.
+ * This module defines a `Redis` service that can send Redis commands and run
+ * Lua scripts. It does not create a Redis client itself; callers provide a
+ * `send` function from their client or connection pool. The module also
+ * provides helpers for describing Lua scripts, loading them once, and running
+ * them later by their cached Redis id.
  *
  * @since 4.0.0
  */