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

package/src/unstable/http/HttpServerResponse.ts

@@ -53,6 +53,8 @@ const TypeId = "~effect/http/HttpServerResponse"
 /**
  * Server-side HTTP response model.
  *
+ * **Details**
+ *
  * A response contains a status, optional status text, headers, cookies, and an
  * HTTP body that can later be converted to platform-specific response types.
  *
@@ -120,6 +122,8 @@ export const isHttpServerResponse = (u: unknown): u is HttpServerResponse => has
 /**
  * Creates an empty HTTP response.
  *
+ * **Details**
+ *
  * The default status is `204`.
  *
  * @category constructors
@@ -138,6 +142,8 @@ export const empty = (
 /**
  * Creates a redirect response with a `Location` header.
  *
+ * **Details**
+ *
  * The default status is `302`; custom headers are merged with the generated
  * `Location` header.
  *
@@ -217,6 +223,8 @@ export const text = (
 /**
  * Creates an HTML response with the `text/html` content type.
  *
+ * **Details**
+ *
  * Passing a string returns a response directly. Using it as a template tag returns
  * an effect so interpolated values can be rendered with their required services
  * and errors.
@@ -228,6 +236,8 @@ export const html: {
   /**
    * Creates an HTML response with the `text/html` content type.
    *
+   * **Details**
+   *
    * Passing a string returns a response directly. Using it as a template tag returns
    * an effect so interpolated values can be rendered with their required services
    * and errors.
@@ -243,6 +253,8 @@ export const html: {
   /**
    * Creates an HTML response with the `text/html` content type.
    *
+   * **Details**
+   *
    * Passing a string returns a response directly. Using it as a template tag returns
    * an effect so interpolated values can be rendered with their required services
    * and errors.
@@ -265,6 +277,8 @@ export const html: {
 /**
  * Creates a streaming HTML response from a template.
  *
+ * **Details**
+ *
  * The template is encoded as a byte stream and can use streaming interpolated
  * values from the current context.
  *
@@ -296,6 +310,8 @@ export const htmlStream = <
 /**
  * Creates a JSON HTTP response.
  *
+ * **Details**
+ *
  * The body is serialized with `JSON.stringify`; serialization errors are captured
  * as `HttpBodyError` failures.
  *
@@ -320,6 +336,8 @@ export const json = (
 /**
  * Creates a JSON response constructor backed by a schema encoder.
  *
+ * **Details**
+ *
  * The returned function encodes the value with the supplied schema before
  * serializing it as JSON, and can fail with `HttpBodyError` if schema encoding or
  * JSON serialization fails.
@@ -351,6 +369,8 @@ export const schemaJson = <A, I, RD, RE>(
 /**
  * Creates a JSON HTTP response synchronously.
  *
+ * **Gotchas**
+ *
  * Unlike `json`, serialization errors from `JSON.stringify` are not captured in
  * `Effect`.
  *
@@ -398,6 +418,8 @@ export const urlParams = (
 /**
  * Creates a response with a raw body value.
  *
+ * **When to use**
+ *
  * Use this when the underlying runtime already understands the body value, such
  * as a Web `Response`, `Blob`, or `ReadableStream`; the body is passed through
  * for later platform conversion.
@@ -441,6 +463,8 @@ export const formData = (
 /**
  * Creates a streaming response from a stream of byte chunks.
  *
+ * **Details**
+ *
  * Optional response metadata can supply the status, headers, content type, and
  * content length.
  *
@@ -475,6 +499,8 @@ const HttpPlatformKey = Context.Service<
 /**
  * Creates a streamed file response for a file system path.
  *
+ * **Details**
+ *
  * The effect requires `HttpPlatform`, can fail with a platform error, and supports
  * options for status, headers, offset, and byte range.
  *
@@ -496,6 +522,8 @@ export const file = (
 /**
  * Creates a streamed file response for a Web `File`-like value.
  *
+ * **Details**
+ *
  * The effect requires `HttpPlatform` and supports options for status, headers,
  * offset, and byte range.
  *
@@ -633,6 +661,8 @@ export const replaceCookies: {
 /**
  * Sets a cookie on the response.
  *
+ * **Details**
+ *
  * The effect fails with `CookiesError` if the cookie name, value, or options are
  * invalid.
  *
@@ -643,6 +673,8 @@ export const setCookie: {
   /**
    * Sets a cookie on the response.
    *
+   * **Details**
+   *
    * The effect fails with `CookiesError` if the cookie name, value, or options are
    * invalid.
    *
@@ -655,6 +687,8 @@ export const setCookie: {
   /**
    * Sets a cookie on the response.
    *
+   * **Details**
+   *
    * The effect fails with `CookiesError` if the cookie name, value, or options are
    * invalid.
    *
@@ -688,6 +722,8 @@ export const setCookie: {
 /**
  * Expires a cookie on an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * Returns an effect because cookie encoding can fail. The original response is not
  * mutated; the effect succeeds with a response containing the updated cookie set.
  *
@@ -698,6 +734,8 @@ export const expireCookie: {
   /**
    * Expires a cookie on an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * Returns an effect because cookie encoding can fail. The original response is not
    * mutated; the effect succeeds with a response containing the updated cookie set.
    *
@@ -713,6 +751,8 @@ export const expireCookie: {
   /**
    * Expires a cookie on an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * Returns an effect because cookie encoding can fail. The original response is not
    * mutated; the effect succeeds with a response containing the updated cookie set.
    *
@@ -745,6 +785,8 @@ export const expireCookie: {
  * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
  * encoded.
  *
+ * **When to use**
+ *
  * Use `setCookie` when cookie errors should be represented as `CookiesError`
  * failures.
  *
@@ -756,6 +798,8 @@ export const setCookieUnsafe: {
    * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
    * encoded.
    *
+   * **When to use**
+   *
    * Use `setCookie` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -767,6 +811,8 @@ export const setCookieUnsafe: {
    * Sets a cookie on an `HttpServerResponse`, throwing if the cookie cannot be
    * encoded.
    *
+   * **When to use**
+   *
    * Use `setCookie` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -797,6 +843,8 @@ export const setCookieUnsafe: {
  * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
  * cannot be encoded.
  *
+ * **When to use**
+ *
  * Use `expireCookie` when cookie errors should be represented as `CookiesError`
  * failures.
  *
@@ -808,6 +856,8 @@ export const expireCookieUnsafe: {
    * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
+   * **When to use**
+   *
    * Use `expireCookie` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -822,6 +872,8 @@ export const expireCookieUnsafe: {
    * Expires a cookie on an `HttpServerResponse`, throwing if the expiration cookie
    * cannot be encoded.
    *
+   * **When to use**
+   *
    * Use `expireCookie` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -850,6 +902,8 @@ export const expireCookieUnsafe: {
  * Updates the cookies attached to an `HttpServerResponse` using the supplied
  * function.
  *
+ * **Details**
+ *
  * The original response is not mutated; a new response is returned with the
  * callback result as its cookie collection.
  *
@@ -861,6 +915,8 @@ export const updateCookies: {
    * Updates the cookies attached to an `HttpServerResponse` using the supplied
    * function.
    *
+   * **Details**
+   *
    * The original response is not mutated; a new response is returned with the
    * callback result as its cookie collection.
    *
@@ -872,6 +928,8 @@ export const updateCookies: {
    * Updates the cookies attached to an `HttpServerResponse` using the supplied
    * function.
    *
+   * **Details**
+   *
    * The original response is not mutated; a new response is returned with the
    * callback result as its cookie collection.
    *
@@ -895,6 +953,8 @@ export const updateCookies: {
  * Merges additional cookies into the cookies attached to an
  * `HttpServerResponse`.
  *
+ * **Details**
+ *
  * The original response is not mutated; a new response is returned with the merged
  * cookie collection.
  *
@@ -906,6 +966,8 @@ export const mergeCookies: {
    * Merges additional cookies into the cookies attached to an
    * `HttpServerResponse`.
    *
+   * **Details**
+   *
    * The original response is not mutated; a new response is returned with the merged
    * cookie collection.
    *
@@ -917,6 +979,8 @@ export const mergeCookies: {
    * Merges additional cookies into the cookies attached to an
    * `HttpServerResponse`.
    *
+   * **Details**
+   *
    * The original response is not mutated; a new response is returned with the merged
    * cookie collection.
    *
@@ -933,6 +997,8 @@ export const mergeCookies: {
 /**
  * Sets multiple cookies on an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * Each input entry contains a cookie name, value, and optional cookie options. The
  * returned effect fails with `CookiesError` if any cookie cannot be encoded.
  *
@@ -943,6 +1009,8 @@ export const setCookies: {
   /**
    * Sets multiple cookies on an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * Each input entry contains a cookie name, value, and optional cookie options. The
    * returned effect fails with `CookiesError` if any cookie cannot be encoded.
    *
@@ -963,6 +1031,8 @@ export const setCookies: {
   /**
    * Sets multiple cookies on an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * Each input entry contains a cookie name, value, and optional cookie options. The
    * returned effect fails with `CookiesError` if any cookie cannot be encoded.
    *
@@ -1002,6 +1072,8 @@ export const setCookies: {
  * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
  * be encoded.
  *
+ * **When to use**
+ *
  * Use `setCookies` when cookie errors should be represented as `CookiesError`
  * failures.
  *
@@ -1013,6 +1085,8 @@ export const setCookiesUnsafe: {
    * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
    * be encoded.
    *
+   * **When to use**
+   *
    * Use `setCookies` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -1032,6 +1106,8 @@ export const setCookiesUnsafe: {
    * Sets multiple cookies on an `HttpServerResponse`, throwing if any cookie cannot
    * be encoded.
    *
+   * **When to use**
+   *
    * Use `setCookies` when cookie errors should be represented as `CookiesError`
    * failures.
    *
@@ -1069,6 +1145,8 @@ export const setCookiesUnsafe: {
 /**
  * Replaces the body of an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * When the body carries a content type or content length, the returned response
  * includes the corresponding headers.
  *
@@ -1079,6 +1157,8 @@ export const setBody: {
   /**
    * Replaces the body of an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * When the body carries a content type or content length, the returned response
    * includes the corresponding headers.
    *
@@ -1089,6 +1169,8 @@ export const setBody: {
   /**
    * Replaces the body of an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * When the body carries a content type or content length, the returned response
    * includes the corresponding headers.
    *
@@ -1104,6 +1186,8 @@ export const setBody: {
 /**
  * Sets the HTTP status code of an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * When `statusText` is omitted, the existing status text is preserved.
  *
  * @category combinators
@@ -1113,6 +1197,8 @@ export const setStatus: {
   /**
    * Sets the HTTP status code of an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * When `statusText` is omitted, the existing status text is preserved.
    *
    * @category combinators
@@ -1122,6 +1208,8 @@ export const setStatus: {
   /**
    * Sets the HTTP status code of an `HttpServerResponse`.
    *
+   * **Details**
+   *
    * When `statusText` is omitted, the existing status text is preserved.
    *
    * @category combinators
@@ -1145,6 +1233,8 @@ export const setStatus: {
 /**
  * Converts an `HttpServerResponse` to a Web `Response`.
  *
+ * **Details**
+ *
  * Cookies are appended as `Set-Cookie` headers. Stream bodies are converted using
  * the supplied context, and `withoutBody` can be used for responses such as HEAD
  * responses.
@@ -1222,6 +1312,8 @@ export const toWeb = (
 /**
  * Wraps an `HttpServerResponse` as an `HttpClientResponse`.
  *
+ * **Details**
+ *
  * An optional request can be supplied for client-response metadata and decode
  * errors.
  *
@@ -1441,6 +1533,8 @@ const textDecoder = new TextDecoder()
 /**
  * Converts an `HttpClientResponse` to an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * The response body is streamed from the client response. `Set-Cookie` headers are
  * removed from the header map and represented in the response cookie collection.
  *
@@ -1532,6 +1626,8 @@ const makeResponse = (options: {
 /**
  * Converts a Web `Response` to an `HttpServerResponse`.
  *
+ * **Details**
+ *
  * `Set-Cookie` headers are parsed into the response cookie collection and removed
  * from the header map. A present Web body is exposed as a stream body.
  *

package/src/unstable/http/HttpTraceContext.ts

@@ -26,6 +26,8 @@ import * as Headers from "./Headers.ts"
 /**
  * Function type for decoding tracing headers into an external span.
  *
+ * **Details**
+ *
  * Returns `Option.none` when the headers do not contain a supported or valid trace
  * context.
  *
@@ -39,6 +41,8 @@ export interface FromHeaders {
 /**
  * Encodes a span into HTTP trace propagation headers.
  *
+ * **Details**
+ *
  * The generated headers include both compact B3 (`b3`) and W3C `traceparent`
  * formats.
  *
@@ -59,6 +63,8 @@ export const toHeaders = (span: Tracer.Span): Headers.Headers =>
 /**
  * Decodes an external span from HTTP trace propagation headers.
  *
+ * **Details**
+ *
  * W3C `traceparent` is tried first, followed by compact B3 (`b3`) and then
  * multi-header B3 (`x-b3-*`).
  *
@@ -80,6 +86,8 @@ export const fromHeaders = (headers: Headers.Headers): Option.Option<Tracer.Exte
 /**
  * Decodes an external span from the compact B3 `b3` header.
  *
+ * **Details**
+ *
  * Returns `Option.none` when the header is missing or does not contain trace and
  * span identifiers.
  *
@@ -104,6 +112,8 @@ export const b3: FromHeaders = (headers) => {
 /**
  * Decodes an external span from multi-header B3 propagation headers.
  *
+ * **Details**
+ *
  * The decoder reads `x-b3-traceid`, `x-b3-spanid`, and optional `x-b3-sampled`
  * headers.
  *
@@ -127,6 +137,8 @@ const w3cSpanId = /^[0-9a-f]{16}$/i
 /**
  * Decodes an external span from the W3C `traceparent` header.
  *
+ * **Details**
+ *
  * Only version `00` headers with valid trace and span identifiers are accepted.
  *
  * @category decoding

package/src/unstable/http/Multipart.ts

@@ -53,6 +53,8 @@ export const TypeId = "~effect/http/Multipart"
 /**
  * A parsed multipart part.
  *
+ * **Details**
+ *
  * A part is either a text `Field` or a streamed `File`.
  *
  * @category models
@@ -69,6 +71,8 @@ export declare namespace Part {
   /**
    * Common protocol implemented by multipart part values.
    *
+   * **Details**
+   *
    * It provides the multipart type identifier, tag, and inspectable behavior shared
    * by fields, files, and persisted files.
    *
@@ -84,6 +88,8 @@ export declare namespace Part {
 /**
  * Multipart form field containing a decoded text value.
  *
+ * **Details**
+ *
  * The `key` is the field name, `contentType` is the part media type, and `value`
  * is the decoded field content.
  *
@@ -116,6 +122,8 @@ export const isField = (u: unknown): u is Field => isPart(u) && u._tag === "Fiel
 /**
  * Multipart file part.
  *
+ * **Gotchas**
+ *
  * The file content is exposed as a byte stream. `contentEffect` collects the full
  * file into memory and should be used only when the file size is acceptable.
  *
@@ -142,6 +150,8 @@ export const isFile = (u: unknown): u is File => isPart(u) && u._tag === "File"
 /**
  * Multipart file part that has been written to the filesystem.
  *
+ * **Details**
+ *
  * The `path` points to the persisted file while the scope used to persist the
  * multipart data remains open.
  *
@@ -168,6 +178,8 @@ export const isPersistedFile = (u: unknown): u is PersistedFile =>
 /**
  * Record representation of persisted multipart data.
  *
+ * **Details**
+ *
  * Field names map to text values, arrays of text values, or arrays of
  * `PersistedFile` values.
  *
@@ -183,6 +195,8 @@ const MultipartErrorTypeId = "~effect/http/Multipart/MultipartError"
 /**
  * Reason carried by a `MultipartError`.
  *
+ * **Details**
+ *
  * It identifies parser and limit failures such as oversized files or fields, too
  * many parts, total body size limits, parse errors, and internal errors.
  *
@@ -197,6 +211,8 @@ export class MultipartErrorReason extends Data.Error<{
 /**
  * Error raised while parsing, streaming, or persisting multipart form data.
  *
+ * **Details**
+ *
  * The `reason` field contains the concrete `MultipartErrorReason`.
  *
  * @category errors
@@ -242,6 +258,8 @@ export interface PersistedFileSchema extends Schema.declare<PersistedFile> {}
 /**
  * Schema for persisted multipart files.
  *
+ * **Details**
+ *
  * The encoded form contains the field key, original file name, content type, and
  * filesystem path.
  *
@@ -292,6 +310,8 @@ export const FilesSchema: Schema.$Array<PersistedFileSchema> = Schema.Array(Pers
 /**
  * Schema for exactly one persisted multipart file.
  *
+ * **Details**
+ *
  * The encoded form is a one-element file array, while the decoded value is the
  * single `PersistedFile`.
  *
@@ -314,6 +334,8 @@ export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Arra
 /**
  * Creates a decoder for persisted multipart data using the supplied schema.
  *
+ * **Details**
+ *
  * The returned function decodes an unknown input into the schema output and fails
  * with `SchemaError` when validation fails.
  *
@@ -328,6 +350,8 @@ export const schemaPersisted = <A, I extends Partial<Persisted>, RD, RE>(
 /**
  * Creates a decoder for a JSON-encoded field in persisted multipart data.
  *
+ * **Details**
+ *
  * The selected field is parsed from a JSON string and decoded with the supplied
  * schema.
  *
@@ -355,6 +379,8 @@ export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, opt
  * Builds the low-level multipart parser configuration from request headers and
  * the current fiber context.
  *
+ * **Details**
+ *
  * Parser limits are read from the multipart references, including maximum parts,
  * field size, file size, total body size, and field MIME type overrides.
  *
@@ -382,6 +408,8 @@ export const makeConfig = (
 /**
  * Creates a channel that parses multipart byte chunks into multipart parts.
  *
+ * **Details**
+ *
  * The channel consumes non-empty batches of `Uint8Array` chunks and emits
  * non-empty batches of parsed `Part` values, failing with `MultipartError` for
  * parser and limit failures.
@@ -578,6 +606,8 @@ const defaultWriteFile = (path: string, file: File) =>
  * Runs a channel of byte chunks and collects all output into a single
  * `Uint8Array`.
  *
+ * **Gotchas**
+ *
  * This materializes the full content in memory.
  *
  * @category converting
@@ -601,9 +631,14 @@ export const collectUint8Array = <OE, OD, R>(
 /**
  * Persists a stream of multipart parts into a record.
  *
+ * **Details**
+ *
  * Text fields are collected as strings, and file parts are written to files in a
- * scoped temporary directory. Persisted file paths remain valid for the lifetime
- * of the scope.
+ * scoped temporary directory.
+ *
+ * **Gotchas**
+ *
+ * Persisted file paths remain valid for the lifetime of the scope.
  *
  * @category converting
  * @since 4.0.0
@@ -685,6 +720,8 @@ class PersistedFileImpl extends PartBase implements PersistedFile {
 /**
  * Creates a context containing multipart parser limit settings.
  *
+ * **Details**
+ *
  * The context can provide maximum part count, field size, file size, total body
  * size, and MIME types that should be parsed as fields.
  *
@@ -726,6 +763,8 @@ export declare namespace withLimits {
   /**
    * Options for overriding multipart parser limits.
    *
+   * **Details**
+   *
    * These settings control maximum part count, field size, file size, total body
    * size, and MIME types that should be treated as fields instead of files.
    *
@@ -744,6 +783,8 @@ export declare namespace withLimits {
 /**
  * Context reference for the maximum number of multipart parts allowed.
  *
+ * **Details**
+ *
  * The default is `undefined`, meaning no explicit part-count limit.
  *
  * @category references
@@ -756,6 +797,8 @@ export const MaxParts = Context.Reference<number | undefined>("effect/http/Multi
 /**
  * Context reference for the maximum size of a multipart field value.
  *
+ * **Details**
+ *
  * The default limit is 10 MiB.
  *
  * @category references
@@ -768,6 +811,8 @@ export const MaxFieldSize = Context.Reference<FileSystem.SizeInput>("effect/http
 /**
  * Context reference for the maximum size of a multipart file part.
  *
+ * **Details**
+ *
  * The default is `undefined`, meaning no explicit per-file limit.
  *
  * @category references
@@ -782,6 +827,8 @@ export const MaxFileSize = Context.Reference<FileSystem.SizeInput | undefined>(
  * Context reference for MIME type fragments that should be parsed as multipart
  * fields instead of files.
  *
+ * **Details**
+ *
  * The default treats `application/json` parts as fields.
  *
  * @category references