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

package/src/unstable/http/Template.ts

@@ -32,6 +32,8 @@ export type PrimitiveValue = string | number | bigint | boolean | null | undefin
 /**
  * Primitive template interpolation value.
  *
+ * **Details**
+ *
  * Arrays are rendered by converting each element to a string and concatenating the
  * results.
  *
@@ -43,6 +45,8 @@ export type Primitive = PrimitiveValue | ReadonlyArray<PrimitiveValue>
 /**
  * Value accepted by the string template constructor.
  *
+ * **Details**
+ *
  * Interpolations can be primitive values, optional primitive values, or effects
  * that produce primitive values.
  *
@@ -57,6 +61,8 @@ export type Interpolated =
 /**
  * Value accepted by the streaming template constructor.
  *
+ * **Details**
+ *
  * In addition to normal interpolations, stream interpolations can emit primitive
  * values over time.
  *
@@ -74,6 +80,8 @@ export declare namespace Interpolated {
   /**
    * Extracts the required context from an effect or stream interpolation.
    *
+   * **Details**
+   *
    * Plain values and `Option` interpolations contribute no context.
    *
    * @category models
@@ -88,6 +96,8 @@ export declare namespace Interpolated {
   /**
    * Extracts the error type from an effect or stream interpolation.
    *
+   * **Details**
+   *
    * Plain values and `Option` interpolations contribute no error type.
    *
    * @category models
@@ -103,6 +113,8 @@ export declare namespace Interpolated {
 /**
  * Creates an effectful string from a template literal.
  *
+ * **Details**
+ *
  * Primitive and `Option` interpolations are rendered immediately. Effect
  * interpolations are evaluated and rendered before the final string is produced.
  *
@@ -161,6 +173,8 @@ export function make<A extends ReadonlyArray<Interpolated>>(
 /**
  * Creates a stream of strings from a template literal.
  *
+ * **Details**
+ *
  * Static text is emitted with interpolated values. Effect interpolations are
  * evaluated as stream chunks, and stream interpolations are flattened into the
  * output.

package/src/unstable/http/UrlParams.ts

@@ -45,6 +45,8 @@ const TypeId = "~effect/http/UrlParams"
 /**
  * Immutable collection of URL query parameters.
  *
+ * **Details**
+ *
  * Parameters are stored as ordered string key-value pairs and can contain multiple
  * values for the same key.
  *
@@ -67,6 +69,8 @@ export const isUrlParams = (u: unknown): u is UrlParams => hasProperty(u, TypeId
 /**
  * Input accepted when constructing `UrlParams`.
  *
+ * **Details**
+ *
  * Values can be provided as a coercible record, an iterable of key-value pairs, or
  * a native `URLSearchParams` value.
  *
@@ -85,6 +89,8 @@ type CoercibleRecordInput = CoercibleRecord & {
 /**
  * Primitive value that can be converted into a URL parameter string.
  *
+ * **Gotchas**
+ *
  * `undefined` values are skipped when constructing from input.
  *
  * @category models
@@ -104,6 +110,8 @@ type CoercibleRecordField<A> = A extends Coercible ? A
 /**
  * Record input whose fields can be coerced into URL parameter values.
  *
+ * **Details**
+ *
  * Nested records are rendered using bracket notation, and arrays produce repeated
  * parameters.
  *
@@ -137,6 +145,8 @@ const Proto = {
 /**
  * Creates `UrlParams` from ordered string key-value pairs.
  *
+ * **Details**
+ *
  * The input pairs are used as-is and are not coerced or normalized.
  *
  * @category constructors
@@ -151,6 +161,8 @@ export const make = (params: ReadonlyArray<readonly [string, string]>): UrlParam
 /**
  * Creates `UrlParams` from a supported input shape.
  *
+ * **Details**
+ *
  * Primitive values are converted to strings, arrays produce repeated parameters,
  * nested records use bracket notation, and `undefined` values are omitted.
  *
@@ -198,6 +210,8 @@ const fromInputNested = (input: Input): Array<[string | Array<string>, any]> =>
 /**
  * Order-sensitive equivalence for `UrlParams`.
  *
+ * **Details**
+ *
  * Two values are equivalent when they contain the same key-value pairs in the same
  * order.
  *
@@ -223,6 +237,8 @@ export interface UrlParamsSchema extends Schema.declare<UrlParams, ReadonlyArray
 /**
  * Schema for `UrlParams`.
  *
+ * **Details**
+ *
  * The encoded representation is an array of string key-value tuples.
  *
  * @category schemas
@@ -264,6 +280,8 @@ export const empty: UrlParams = make([])
 /**
  * Returns all values for a query parameter key in insertion order.
  *
+ * **Details**
+ *
  * Returns an empty array when the key is absent.
  *
  * @category combinators
@@ -273,6 +291,8 @@ export const getAll: {
   /**
    * Returns all values for a query parameter key in insertion order.
    *
+   * **Details**
+   *
    * Returns an empty array when the key is absent.
    *
    * @category combinators
@@ -282,6 +302,8 @@ export const getAll: {
   /**
    * Returns all values for a query parameter key in insertion order.
    *
+   * **Details**
+   *
    * Returns an empty array when the key is absent.
    *
    * @category combinators
@@ -302,6 +324,8 @@ export const getAll: {
 /**
  * Returns the first value for a query parameter key.
  *
+ * **Details**
+ *
  * Returns `Option.none` when the key is absent.
  *
  * @category combinators
@@ -311,6 +335,8 @@ export const getFirst: {
   /**
    * Returns the first value for a query parameter key.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent.
    *
    * @category combinators
@@ -320,6 +346,8 @@ export const getFirst: {
   /**
    * Returns the first value for a query parameter key.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent.
    *
    * @category combinators
@@ -337,6 +365,8 @@ export const getFirst: {
 /**
  * Returns the last value for a query parameter key.
  *
+ * **Details**
+ *
  * Returns `Option.none` when the key is absent.
  *
  * @category combinators
@@ -346,6 +376,8 @@ export const getLast: {
   /**
    * Returns the last value for a query parameter key.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent.
    *
    * @category combinators
@@ -355,6 +387,8 @@ export const getLast: {
   /**
    * Returns the last value for a query parameter key.
    *
+   * **Details**
+   *
    * Returns `Option.none` when the key is absent.
    *
    * @category combinators
@@ -369,6 +403,8 @@ export const getLast: {
 /**
  * Sets a query parameter to a single value.
  *
+ * **Details**
+ *
  * Existing values for the same key are removed, and the new value is appended to
  * the end.
  *
@@ -379,6 +415,8 @@ export const set: {
   /**
    * Sets a query parameter to a single value.
    *
+   * **Details**
+   *
    * Existing values for the same key are removed, and the new value is appended to
    * the end.
    *
@@ -389,6 +427,8 @@ export const set: {
   /**
    * Sets a query parameter to a single value.
    *
+   * **Details**
+   *
    * Existing values for the same key are removed, and the new value is appended to
    * the end.
    *
@@ -407,6 +447,8 @@ export const set: {
 /**
  * Transforms the underlying ordered key-value pairs of `UrlParams`.
  *
+ * **Details**
+ *
  * The result is wrapped in a new `UrlParams` value.
  *
  * @category combinators
@@ -416,6 +458,8 @@ export const transform: {
   /**
    * Transforms the underlying ordered key-value pairs of `UrlParams`.
    *
+   * **Details**
+   *
    * The result is wrapped in a new `UrlParams` value.
    *
    * @category combinators
@@ -425,6 +469,8 @@ export const transform: {
   /**
    * Transforms the underlying ordered key-value pairs of `UrlParams`.
    *
+   * **Details**
+   *
    * The result is wrapped in a new `UrlParams` value.
    *
    * @category combinators
@@ -439,6 +485,8 @@ export const transform: {
 /**
  * Sets multiple query parameters from input.
  *
+ * **Details**
+ *
  * Keys present in the input replace existing values for those keys, while
  * unmentioned existing parameters are preserved.
  *
@@ -449,6 +497,8 @@ export const setAll: {
   /**
    * Sets multiple query parameters from input.
    *
+   * **Details**
+   *
    * Keys present in the input replace existing values for those keys, while
    * unmentioned existing parameters are preserved.
    *
@@ -459,6 +509,8 @@ export const setAll: {
   /**
    * Sets multiple query parameters from input.
    *
+   * **Details**
+   *
    * Keys present in the input replace existing values for those keys, while
    * unmentioned existing parameters are preserved.
    *
@@ -510,6 +562,8 @@ export const append: {
 /**
  * Appends all query parameters produced from the supplied input.
  *
+ * **Details**
+ *
  * Existing parameters are preserved.
  *
  * @category combinators
@@ -519,6 +573,8 @@ export const appendAll: {
   /**
    * Appends all query parameters produced from the supplied input.
    *
+   * **Details**
+   *
    * Existing parameters are preserved.
    *
    * @category combinators
@@ -528,6 +584,8 @@ export const appendAll: {
   /**
    * Appends all query parameters produced from the supplied input.
    *
+   * **Details**
+   *
    * Existing parameters are preserved.
    *
    * @category combinators
@@ -572,6 +630,8 @@ export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
 /**
  * Creates a `URL` by appending `UrlParams` and an optional hash to a URL string.
  *
+ * **Details**
+ *
  * Returns a `Result` that fails with `UrlParamsError` if the URL cannot be
  * constructed.
  *
@@ -666,6 +726,8 @@ export const toRecord = (self: UrlParams): Record<string, string | Arr.NonEmptyA
 /**
  * Builds a readonly record from `UrlParams`.
  *
+ * **Details**
+ *
  * Keys with one value map to a string, and keys with multiple values map to a
  * non-empty readonly array of strings.
  *
@@ -744,6 +806,8 @@ export interface schemaRecord extends
 /**
  * Schema that decodes `UrlParams` into a record of key-value pairs.
  *
+ * **Details**
+ *
  * Keys with one value decode to a string, and keys with multiple values decode to
  * a non-empty readonly array of strings.
  *

package/src/unstable/httpapi/HttpApi.ts

@@ -52,6 +52,8 @@ export const isHttpApi = (u: unknown): u is Any => Predicate.hasProperty(u, Type
  * An `HttpApi` is a collection of HTTP API groups and endpoints that represents a
  * portion of your domain.
  *
+ * **When to use**
+ *
  * Endpoint implementations can be provided with `HttpApiBuilder.group`, and the
  * completed API can be registered with `HttpApiBuilder.layer`.
  *
@@ -86,11 +88,11 @@ export interface HttpApi<
   prefix<const Prefix extends PathInput>(prefix: Prefix): HttpApi<Id, HttpApiGroup.AddPrefix<Groups, Prefix>>
 
   /**
-   * Add a middleware to a `HttpApi`. It will be applied to all endpoints in the
-   * `HttpApi`.
+   * Adds a middleware to every endpoint currently in the `HttpApi`.
+   *
+   * **Gotchas**
    *
-   * Note that this will only add the middleware to the endpoints **before** this
-   * api is called.
+   * Endpoints added after this method is called do not receive the middleware.
    */
   middleware<I extends HttpApiMiddleware.AnyId, S>(
     middleware: Context.Key<I, S>
@@ -208,6 +210,8 @@ const makeProto = <Id extends string, Groups extends HttpApiGroup.Any>(
 /**
  * Creates an empty `HttpApi` with the supplied identifier.
  *
+ * **When to use**
+ *
  * Add groups with `add` or `addHttpApi`, provide endpoint implementations with
  * `HttpApiBuilder.group`, and register the API with `HttpApiBuilder.layer`.
  *
@@ -224,6 +228,8 @@ export const make = <const Id extends string>(identifier: Id): HttpApi<Id, never
 /**
  * Walks 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.
  *

package/src/unstable/httpapi/HttpApiBuilder.ts

@@ -121,12 +121,13 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
   }))
 
 /**
- * Create a `Layer` that will implement all the endpoints in an `HttpApi`.
+ * Create a `Layer` that implements all endpoints in an `HttpApi` group.
  *
- * An unimplemented `Handlers` instance is passed to the `build` function, which
- * you can use to add handlers to the group.
+ * **Details**
  *
- * You can implement endpoints using the `handlers.handle` api.
+ * The `build` function receives an unimplemented `Handlers` instance that can
+ * be used to add handlers to the group. Implement endpoints with
+ * `handlers.handle`.
  *
  * @category handlers
  * @since 4.0.0
@@ -187,6 +188,8 @@ export type HandlersTypeId = typeof HandlersTypeId
 /**
  * Mutable handler collection for one `HttpApi` group.
  *
+ * **Details**
+ *
  * Each call to `handle` or `handleRaw` registers an endpoint implementation and
  * removes that endpoint from the type-level set of endpoints still requiring
  * handlers.
@@ -263,6 +266,8 @@ export declare namespace Handlers {
   /**
    * Record stored for a registered endpoint handler.
    *
+   * **Details**
+   *
    * It keeps the endpoint metadata, handler function, whether raw request handling
    * is used, and whether the handler should run uninterruptibly.
    *

package/src/unstable/httpapi/HttpApiEndpoint.ts

@@ -1343,6 +1343,8 @@ const del = make("DELETE")
 
 export {
   /**
+   * Creates a `DELETE` endpoint declaration.
+   *
    * @category constructors
    * @since 4.0.0
    */

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -46,10 +46,12 @@ const TypeId = "~effect/httpapi/HttpApiGroup"
 export const isHttpApiGroup = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
 /**
- * An `HttpApiGroup` is a collection of `HttpApiEndpoint`s. You can use an `HttpApiGroup` to
- * represent a portion of your domain.
+ * An `HttpApiGroup` is a named collection of `HttpApiEndpoint`s that represents
+ * a portion of your domain.
  *
- * The endpoints can be implemented later using the `HttpApiBuilder.group` api.
+ * **Details**
+ *
+ * Endpoint implementations can be provided later with `HttpApiBuilder.group`.
  *
  * @category models
  * @since 4.0.0
@@ -83,9 +85,11 @@ export interface HttpApiGroup<
   ): HttpApiGroup<Id, HttpApiEndpoint.AddPrefix<Endpoints, Prefix>, TopLevel>
 
   /**
-   * Add an `HttpApiMiddleware` to the `HttpApiGroup`.
+   * Adds an `HttpApiMiddleware` to every endpoint currently in the group.
+   *
+   * **Gotchas**
    *
-   * Endpoints added after this api is called **will not** have the middleware
+   * Endpoints added after this method is called do not have the middleware
    * applied.
    */
   middleware<I extends HttpApiMiddleware.AnyId, S>(middleware: Context.Key<I, S>): HttpApiGroup<
@@ -105,18 +109,20 @@ export interface HttpApiGroup<
   annotate<I, S>(key: Context.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
 
   /**
-   * For each endpoint in an `HttpApiGroup`, update the annotations with a new
-   * Context.
+   * Merges the provided context into every endpoint currently in the group.
+   *
+   * **Gotchas**
    *
-   * Note that this will only update the annotations before this api is called.
+   * Endpoints added after this method is called do not have these annotations.
    */
   annotateEndpointsMerge<I>(annotations: Context.Context<I>): HttpApiGroup<Id, Endpoints, TopLevel>
 
   /**
-   * For each endpoint in an `HttpApiGroup`, add an annotation.
+   * Adds an annotation to every endpoint currently in the group.
    *
-   * Note that this will only add the annotation to the endpoints before this api
-   * is called.
+   * **Gotchas**
+   *
+   * Endpoints added after this method is called do not have this annotation.
    */
   annotateEndpoints<I, S>(key: Context.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
 }
@@ -368,10 +374,13 @@ const makeProto = <
 }
 
 /**
- * An `HttpApiGroup` is a collection of `HttpApiEndpoint`s. You can use an `HttpApiGroup` to
- * represent a portion of your domain.
+ * Creates an empty `HttpApiGroup` with the supplied identifier.
+ *
+ * **Details**
  *
- * The endpoints can be implemented later using the `HttpApiBuilder.group` api.
+ * Add endpoints with `add`, provide implementations with `HttpApiBuilder.group`,
+ * and set `topLevel` when the generated client should expose endpoint methods
+ * directly instead of nesting them under the group name.
  *
  * @category constructors
  * @since 4.0.0

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -66,6 +66,8 @@ type ErrorSchemaFromConstraint<E> = E extends ReadonlyArray<Schema.Top> ? E[numb
 /**
  * Server-side middleware function for an HTTP API endpoint.
  *
+ * **Details**
+ *
  * It receives the endpoint response effect and endpoint/group metadata, and returns
  * a new response effect that may require additional services and fail with the
  * middleware's declared error schema.
@@ -84,6 +86,8 @@ export type HttpApiMiddleware<Provides, E extends ErrorConstraint, Requires> = (
 /**
  * Server-side middleware implementations for one or more security schemes.
  *
+ * **Details**
+ *
  * Each property handles the credential decoded for that scheme and wraps the
  * endpoint response effect with the middleware's declared requirements and errors.
  *
@@ -113,6 +117,8 @@ export type HttpApiMiddlewareSecurity<
 /**
  * Client-side middleware function for generated HTTP API clients.
  *
+ * **Details**
+ *
  * It receives endpoint/group metadata, the outgoing request, and a `next` function
  * for continuing the request pipeline.
  *
@@ -269,6 +275,8 @@ export type ErrorServicesDecode<A> = ErrorSchema<A>["DecodingServices"]
 /**
  * Class type produced by `Service` for an HTTP API middleware service.
  *
+ * **Details**
+ *
  * It combines a `Context.Service` class with the middleware metadata used by
  * endpoints, builders, and generated clients.
  *
@@ -314,6 +322,8 @@ export type ServiceClass<
 /**
  * Creates a `Context.Service` class for an HTTP API middleware implementation.
  *
+ * **When to use**
+ *
  * Use the optional configuration to declare required services, provided services,
  * typed error schemas, security schemes, client errors, and whether generated
  * clients must provide a matching client middleware.
@@ -390,6 +400,8 @@ function getError(error: ErrorConstraint | undefined): ReadonlySet<Schema.Top> {
 /**
  * Creates a middleware layer that transforms `HttpApiSchemaError` failures.
  *
+ * **Details**
+ *
  * The middleware catches schema errors produced while running an endpoint and uses
  * the supplied `transform` function to convert them into the middleware's declared
  * error schema.
@@ -445,6 +457,8 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
 /**
  * Provides a client-side middleware implementation for a middleware that is required by generated clients.
  *
+ * **Details**
+ *
  * The layer captures the surrounding services and makes the middleware available
  * through the `ForClient` service marker used by HTTP API clients.
  *

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -70,19 +70,19 @@ export type ScalarConfig = {
   /**
    * Whether to show models in the sidebar, search, and content.
    *
-   * Default: `false`
+   * @default false
    */
   hideModels?: boolean
   /**
    * Whether to show the "Test Request" button.
    *
-   * Default: `false`
+   * @default false
    */
   hideTestRequestButton?: boolean
   /**
    * Whether to show the sidebar search bar.
    *
-   * Default: `false`
+   * @default false
    */
   hideSearch?: boolean
   /** Whether dark mode is on or off initially (light mode) */
@@ -94,37 +94,56 @@ export type ScalarConfig = {
   /**
    * Path to a favicon image.
    *
-   * Default: `undefined`
-   * Example: "/favicon.svg"
+   * **Example** (Relative favicon)
+   *
+   * ```ts
+   * const favicon = "/favicon.svg"
+   * ```
+   *
+   * @default undefined
    */
   favicon?: string
   /** Custom CSS to be added to the page */
   customCss?: string
   /**
-   * The baseServerURL is used when the spec servers are relative paths and we are using SSR.
-   * On the client we can grab the window.location.origin but on the server we need
-   * to use this prop.
+   * Origin used when the OpenAPI document contains relative server URLs and is
+   * rendered during SSR.
+   *
+   * **Details**
+   *
+   * Browsers can derive the origin from `window.location.origin`; server
+   * rendering needs this value supplied explicitly.
+   *
+   * **Example** (Local server URL)
    *
-   * Default: `undefined`
-   * Example: "http://localhost:3000"
+   * ```ts
+   * const baseServerURL = "http://localhost:3000"
+   * ```
+   *
+   * @default undefined
    */
   baseServerURL?: string
   /**
-   * We use Inter and JetBrains Mono as the default fonts. If you want to use your own fonts, set this to false.
+   * Whether Scalar loads its default Inter and JetBrains Mono fonts.
+   *
+   * **Details**
+   *
+   * Set this to `false` when supplying custom fonts.
    *
-   * Default: `true`
+   * @default true
    */
   withDefaultFonts?: boolean
   /**
-   * By default we only open the relevant tag based on the url, however if you want all the tags open by default then set this configuration option.
+   * Whether all tags are open by default instead of only the tag matching the
+   * current URL.
    *
-   * Default: `false`
+   * @default false
    */
   defaultOpenAllTags?: boolean
   /**
    * Whether to display the operation ID in the operation reference.
    *
-   * Default: `false`
+   * @default false
    */
   showOperationId?: boolean
 }
@@ -190,6 +209,8 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
 /**
  * Mounts a Scalar API reference page for an `HttpApi` using the bundled Scalar script.
  *
+ * **Details**
+ *
  * The route serves the OpenAPI specification generated from the API at the
  * configured path, defaulting to `/docs`.
  *
@@ -218,6 +239,8 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
 /**
  * Mounts a Scalar API reference page for an `HttpApi` that loads Scalar from jsDelivr.
  *
+ * **Details**
+ *
  * The route serves the OpenAPI specification generated from the API at the
  * configured path, defaulting to `/docs`; `version` selects the Scalar package
  * version loaded from the CDN.