effect 4.0.0-beta.67 → 4.0.0-beta.68

package/src/unstable/http/HttpMethod.ts

@@ -37,7 +37,6 @@ export type HttpMethod =
 /**
  * Namespace containing subtype helpers associated with `HttpMethod`.
  *
- * @category models
  * @since 4.0.0
  */
 export declare namespace HttpMethod {
@@ -61,6 +60,7 @@ export declare namespace HttpMethod {
 /**
  * Returns `true` when a method can carry a request body and narrows it to `HttpMethod.WithBody`.
  *
+ * @category predicates
  * @since 4.0.0
  */
 export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
@@ -69,6 +69,7 @@ export const hasBody = (method: HttpMethod): method is HttpMethod.WithBody =>
 /**
  * Set containing every supported `HttpMethod` literal.
  *
+ * @category models
  * @since 4.0.0
  */
 export const all: ReadonlySet<HttpMethod> = new Set([
@@ -85,6 +86,7 @@ export const all: ReadonlySet<HttpMethod> = new Set([
 /**
  * Tuples mapping each supported HTTP method to its short request-constructor name.
  *
+ * @category models
  * @since 4.0.0
  */
 export const allShort = [
@@ -101,7 +103,7 @@ export const allShort = [
 /**
  * Tests if a value is a `HttpMethod`.
  *
- * **Example**
+ * **Example** (Checking HTTP method values)
  *
  * ```ts
  * import { HttpMethod } from "effect/unstable/http"

package/src/unstable/http/HttpMiddleware.ts

@@ -62,6 +62,7 @@ export declare namespace HttpMiddleware {
   /**
    * Callable type representing middleware already specialized to a particular transformed app type.
    *
+   * @category models
    * @since 4.0.0
    */
   export interface Applied<A extends Effect.Effect<HttpServerResponse, any, any>, E, R> {

package/src/unstable/http/HttpRouter.ts

@@ -253,7 +253,7 @@ function sliceRequestUrl(request: HttpServerRequest.HttpServerRequest, prefix: s
  * The value is passed to the route matcher when an `HttpRouter` is created and
  * defaults to an empty configuration.
  *
- * @category Configuration
+ * @category configuration
  * @since 4.0.0
  */
 export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
@@ -294,7 +294,7 @@ export const params: Effect.Effect<
  * cookies, path parameters, search parameters, and parsed JSON body. The effect
  * fails if the body cannot be parsed or the schema decode fails.
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaJson = <
@@ -348,7 +348,7 @@ export const schemaJson = <
  * The input passed to the schema includes the request method, URL, headers,
  * cookies, path parameters, and search parameters.
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaNoBody = <
@@ -398,7 +398,7 @@ export const schemaNoBody = <
  *
  * When the same key appears in both sources, the path parameter value is used.
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaParams = <A, I extends Readonly<Record<string, string | ReadonlyArray<string> | undefined>>, RD, RE>(
@@ -417,7 +417,7 @@ export const schemaParams = <A, I extends Readonly<Record<string, string | Reado
  * Decodes a schema from the path parameters captured for the current matched
  * route.
  *
- * @category Schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaPathParams = <A, I extends Readonly<Record<string, string | undefined>>, RD, RE>(
@@ -435,10 +435,11 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  * Use it to register routes or middleware with the router during layer
  * construction.
  *
+ * **Example** (Registering routes during layer construction)
+ *
  * ```ts
- * import { Effect } from "effect"
- * import * as Layer from "effect/Layer"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
+ * import { Effect, Layer } from "effect"
+ * import { HttpRouter } from "effect/unstable/http"
  *
  * const MyRoute = Layer.effectDiscard(Effect.gen(function*() {
  *   const router = yield* HttpRouter.HttpRouter
@@ -457,10 +458,11 @@ export const use = <A, E, R>(
 /**
  * Create a layer that adds a single route to the HTTP router.
  *
+ * **Example** (Adding a GET route)
+ *
  * ```ts
  * import { Effect } from "effect"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Route = HttpRouter.add(
  *   "GET",
@@ -488,10 +490,11 @@ export const add = <E = never, R = never>(
 /**
  * Create a layer that adds multiple routes to the HTTP router.
  *
+ * **Example** (Adding multiple routes)
+ *
  * ```ts
  * import { Effect } from "effect"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Routes = HttpRouter.addAll([
  *   HttpRouter.route(
@@ -588,7 +591,6 @@ export interface Route<E = never, R = never> {
  * Helper types for extracting the error and context types carried by `Route`
  * values.
  *
- * @category Route
  * @since 4.0.0
  */
 export declare namespace Route {
@@ -766,7 +768,6 @@ export interface Request<Kind extends string, T> {
  * Helper types for request-level dependency markers used by router layers and
  * middleware.
  *
- * @category Request types
  * @since 4.0.0
  */
 export declare namespace Request {
@@ -880,13 +881,11 @@ export interface Middleware<
  * If you want to create a middleware that applies globally to all routes, pass
  * the `global` option as `true`.
  *
+ * **Example** (Applying route and global middleware)
+ *
  * ```ts
- * import { Effect } from "effect"
- * import * as Layer from "effect/Layer"
- * import * as Context from "effect/Context"
- * import * as HttpMiddleware from "effect/unstable/http/HttpMiddleware"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
+ * import { Context, Effect, Layer } from "effect"
+ * import { HttpMiddleware, HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * // Here we are defining a CORS middleware
  * const CorsMiddleware = HttpRouter.middleware(HttpMiddleware.cors()).layer
@@ -1056,7 +1055,6 @@ const getMiddleware = (context: Context.Context<never>): Array<middleware.Fn> =>
 /**
  * Types used by the `middleware` constructor.
  *
- * @category Middleware
  * @since 4.0.0
  */
 export declare namespace middleware {
@@ -1180,11 +1178,11 @@ export const cors = (
 /**
  * A middleware that disables the logger for some routes.
  *
+ * **Example** (Disabling route logging)
+ *
  * ```ts
- * import { Effect } from "effect"
- * import * as Layer from "effect/Layer"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
+ * import { Effect, Layer } from "effect"
+ * import { HttpRouter, HttpServerResponse } from "effect/unstable/http"
  *
  * const Route = HttpRouter.add(
  *   "GET",

package/src/unstable/http/HttpServerError.ts

@@ -250,7 +250,7 @@ export class ServeError extends Data.TaggedError("ServeError")<{
  * `causeResponse` uses this annotation to map a pure client abort to a `499`
  * response instead of a server abort response.
  *
- * @category Annotations
+ * @category annotations
  * @since 4.0.0
  */
 export class ClientAbort extends Context.Service<ClientAbort, true>()("effect/http/HttpServerError/ClientAbort") {
@@ -276,6 +276,7 @@ const formatRequestMessage = (reason: string, description: string | undefined, i
  * are already `HttpServerResponse` values are used directly, and pure interrupts
  * produce either `499` for client aborts or `503` for server aborts.
  *
+ * @category error handling
  * @since 4.0.0
  */
 export const causeResponse = <E>(
@@ -330,6 +331,7 @@ export const causeResponse = <E>(
  * response is used and removed from the remaining cause. Otherwise the response
  * defaults to `500`.
  *
+ * @category error handling
  * @since 4.0.0
  */
 export const causeResponseStripped = <E>(
@@ -358,6 +360,7 @@ const serverAbortError = Effect.succeed(Response.empty({ status: 503 }))
  * Extracts the response from a successful handler exit, or derives a response
  * from the failure cause.
  *
+ * @category error handling
  * @since 4.0.0
  */
 export const exitResponse = <E>(exit: Exit.Exit<Response.HttpServerResponse, E>): Response.HttpServerResponse => {

package/src/unstable/http/HttpServerRequest.ts

@@ -54,7 +54,7 @@ export {
 /**
  * Runtime type identifier for `HttpServerRequest` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/http/HttpServerRequest"
@@ -171,7 +171,7 @@ export const upgradeChannel = <IE = never>(): Channel.Channel<
 /**
  * Decodes a schema from the cookies of the current request.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaCookies = <A, I extends Readonly<Record<string, string | undefined>>, RD, RE>(
@@ -185,7 +185,7 @@ export const schemaCookies = <A, I extends Readonly<Record<string, string | unde
 /**
  * Decodes a schema from the headers of the current request.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaHeaders = <A, I extends Readonly<Record<string, string | undefined>>, RD, RE>(
@@ -199,7 +199,7 @@ export const schemaHeaders = <A, I extends Readonly<Record<string, string | unde
 /**
  * Decodes a schema from the parsed search parameters of the current request.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaSearchParams = <
@@ -220,7 +220,7 @@ export const schemaSearchParams = <
  * The effect can fail if the body cannot be read or parsed, or if schema decoding
  * fails.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaBodyJson = <A, I, RD, RE>(
@@ -241,7 +241,7 @@ const isMultipart = (request: HttpServerRequest) =>
  * Multipart requests are persisted and decoded as multipart data; other form
  * requests are decoded from URL-encoded body parameters.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaBodyForm = <A, I extends Partial<Multipart.Persisted>, RD, RE>(
@@ -266,7 +266,7 @@ export const schemaBodyForm = <A, I extends Partial<Multipart.Persisted>, RD, RE
  * Reads the current request body as URL-encoded parameters and decodes them with
  * the supplied schema.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaBodyUrlParams = <
@@ -289,7 +289,7 @@ export const schemaBodyUrlParams = <
  * The effect requires the services needed to persist multipart files, including a
  * scope, file system, and path service.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaBodyMultipart = <A, I extends Partial<Multipart.Persisted>, RD, RE>(
@@ -314,7 +314,7 @@ export const schemaBodyMultipart = <A, I extends Partial<Multipart.Persisted>, R
  * URL-encoded requests, the named parameter is decoded as JSON and then decoded
  * with the supplied schema.
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaBodyFormJson = <A, I, RD, RE>(
@@ -358,7 +358,7 @@ export const schemaBodyFormJson = <A, I, RD, RE>(
  * If the client request can be converted to an absolute URL, that URL is used as
  * the original URL.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromClientRequest = (request: HttpClientRequest.HttpClientRequest): HttpServerRequest => {
@@ -375,7 +375,7 @@ export const fromClientRequest = (request: HttpClientRequest.HttpClientRequest):
  * The request's current URL is stored without the scheme and host, while the
  * original Web URL remains available as `originalUrl`.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromWeb = (request: globalThis.Request): HttpServerRequest =>
@@ -387,7 +387,7 @@ export const fromWeb = (request: globalThis.Request): HttpServerRequest =>
  * The converted request preserves the method, headers, body stream, and a URL
  * derived from the request when possible.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toClientRequest = (request: HttpServerRequest): HttpClientRequest.HttpClientRequest =>
@@ -971,7 +971,7 @@ const textDecoder = new TextDecoder()
  * protocol is `https` only when `x-forwarded-proto` is `https`; invalid URLs
  * return `Option.none`.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toURL = (self: HttpServerRequest): Option.Option<URL> => {
@@ -991,7 +991,7 @@ export const toURL = (self: HttpServerRequest): Option.Option<URL> => {
  * an absolute URL is derived from the request; invalid URLs fail with a
  * `RequestParseError`.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toWebResult = (self: HttpServerRequest, options?: {
@@ -1030,7 +1030,7 @@ export const toWebResult = (self: HttpServerRequest, options?: {
  * The current context is used when streaming the request body into the Web
  * request.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toWeb = (self: HttpServerRequest, options?: {

package/src/unstable/http/HttpServerRespondable.ts

@@ -29,7 +29,7 @@ import * as Response from "./HttpServerResponse.ts"
  * Protocol key used by values that can render themselves as
  * `HttpServerResponse` values.
  *
- * @category Type IDs
+ * @category type IDs
  * @since 4.0.0
  */
 export const symbol = "~effect/http/HttpServerRespondable"

package/src/unstable/http/HttpServerResponse.ts

@@ -112,6 +112,7 @@ export declare namespace Options {
 /**
  * Returns `true` when the supplied value is an `HttpServerResponse`.
  *
+ * @category guards
  * @since 4.0.0
  */
 export const isHttpServerResponse = (u: unknown): u is HttpServerResponse => hasProperty(u, TypeId)
@@ -1148,7 +1149,7 @@ export const setStatus: {
  * the supplied context, and `withoutBody` can be used for responses such as HEAD
  * responses.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toWeb = (
@@ -1224,7 +1225,7 @@ export const toWeb = (
  * An optional request can be supplied for client-response metadata and decode
  * errors.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toClientResponse = (
@@ -1443,7 +1444,7 @@ const textDecoder = new TextDecoder()
  * 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.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromClientResponse = (
@@ -1534,7 +1535,7 @@ const makeResponse = (options: {
  * `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.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const fromWeb = (response: Response): HttpServerResponse => {

package/src/unstable/http/HttpStaticServer.ts

@@ -36,7 +36,7 @@ import * as HttpServerResponse from "./HttpServerResponse.ts"
  *
  * ```ts
  * import { Effect } from "effect"
- * import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+ * import { HttpStaticServer } from "effect/unstable/http"
  *
  * const program = Effect.gen(function*() {
  *   const app = yield* HttpStaticServer.make({ root: "./public" })
@@ -189,9 +189,7 @@ export const make: (options: {
  *
  * ```ts
  * import { Layer } from "effect"
- * import * as HttpRouter from "effect/unstable/http/HttpRouter"
- * import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse"
- * import * as HttpStaticServer from "effect/unstable/http/HttpStaticServer"
+ * import { HttpRouter, HttpServerResponse, HttpStaticServer } from "effect/unstable/http"
  *
  * const ApiLayer = HttpRouter.add("GET", "/health", HttpServerResponse.text("ok"))
  *

package/src/unstable/http/Multipart.ts

@@ -45,6 +45,7 @@ import * as MP from "./Multipasta.ts"
 /**
  * Type identifier used to brand multipart part values.
  *
+ * @category type IDs
  * @since 4.0.0
  */
 export const TypeId = "~effect/http/Multipart"
@@ -99,7 +100,7 @@ export interface Field extends Part.Proto {
 /**
  * Returns `true` when a value is a multipart `Part`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, TypeId)
@@ -107,7 +108,7 @@ export const isPart = (u: unknown): u is Part => Predicate.hasProperty(u, TypeId
 /**
  * Returns `true` when a value is a multipart text `Field`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isField = (u: unknown): u is Field => isPart(u) && u._tag === "Field"
@@ -133,7 +134,7 @@ export interface File extends Part.Proto {
 /**
  * Returns `true` when a value is a multipart `File`.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isFile = (u: unknown): u is File => isPart(u) && u._tag === "File"
@@ -158,7 +159,7 @@ export interface PersistedFile extends Part.Proto {
 /**
  * Returns `true` when a value is a persisted multipart file.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isPersistedFile = (u: unknown): u is PersistedFile =>
@@ -185,7 +186,7 @@ const MultipartErrorTypeId = "~effect/http/Multipart/MultipartError"
  * It identifies parser and limit failures such as oversized files or fields, too
  * many parts, total body size limits, parse errors, and internal errors.
  *
- * @category Errors
+ * @category errors
  * @since 4.0.0
  */
 export class MultipartErrorReason extends Data.Error<{
@@ -198,7 +199,7 @@ export class MultipartErrorReason extends Data.Error<{
  *
  * The `reason` field contains the concrete `MultipartErrorReason`.
  *
- * @category Errors
+ * @category errors
  * @since 4.0.0
  */
 export class MultipartError extends Data.TaggedError("MultipartError")<{
@@ -233,7 +234,7 @@ export class MultipartError extends Data.TaggedError("MultipartError")<{
 /**
  * Schema type for persisted multipart files.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export interface PersistedFileSchema extends Schema.declare<PersistedFile> {}
@@ -244,7 +245,7 @@ export interface PersistedFileSchema extends Schema.declare<PersistedFile> {}
  * The encoded form contains the field key, original file name, content type, and
  * filesystem path.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const PersistedFileSchema: PersistedFileSchema = Schema.declare(
@@ -283,7 +284,7 @@ export const PersistedFileSchema: PersistedFileSchema = Schema.declare(
 /**
  * Schema for an array of persisted multipart files.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const FilesSchema: Schema.$Array<PersistedFileSchema> = Schema.Array(PersistedFileSchema)
@@ -294,7 +295,7 @@ export const FilesSchema: Schema.$Array<PersistedFileSchema> = Schema.Array(Pers
  * The encoded form is a one-element file array, while the decoded value is the
  * single `PersistedFile`.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Array<PersistedFileSchema>> = FilesSchema
@@ -316,7 +317,7 @@ export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Arra
  * The returned function decodes an unknown input into the schema output and fails
  * with `SchemaError` when validation fails.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaPersisted = <A, I extends Partial<Persisted>, RD, RE>(
@@ -330,7 +331,7 @@ export const schemaPersisted = <A, I extends Partial<Persisted>, RD, RE>(
  * The selected field is parsed from a JSON string and decoded with the supplied
  * schema.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaJson = <A, I, RD, RE>(schema: Schema.Codec<A, I, RD, RE>, options?: ParseOptions | undefined): {
@@ -579,6 +580,7 @@ const defaultWriteFile = (path: string, file: File) =>
  *
  * This materializes the full content in memory.
  *
+ * @category converting
  * @since 4.0.0
  */
 export const collectUint8Array = <OE, OD, R>(
@@ -603,7 +605,7 @@ export const collectUint8Array = <OE, OD, R>(
  * scoped temporary directory. Persisted file paths remain valid for the lifetime
  * of the scope.
  *
- * @category Conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toPersisted = (
@@ -686,7 +688,7 @@ class PersistedFileImpl extends PartBase implements PersistedFile {
  * The context can provide maximum part count, field size, file size, total body
  * size, and MIME types that should be parsed as fields.
  *
- * @category References
+ * @category references
  * @since 4.0.0
  */
 export const limitsServices = (options: {
@@ -718,7 +720,6 @@ export const limitsServices = (options: {
 /**
  * Namespace containing multipart parser limit option types.
  *
- * @category fiber refs
  * @since 4.0.0
  */
 export declare namespace withLimits {
@@ -745,7 +746,7 @@ export declare namespace withLimits {
  *
  * The default is `undefined`, meaning no explicit part-count limit.
  *
- * @category References
+ * @category references
  * @since 4.0.0
  */
 export const MaxParts = Context.Reference<number | undefined>("effect/http/Multipart/MaxParts", {
@@ -757,7 +758,7 @@ export const MaxParts = Context.Reference<number | undefined>("effect/http/Multi
  *
  * The default limit is 10 MiB.
  *
- * @category References
+ * @category references
  * @since 4.0.0
  */
 export const MaxFieldSize = Context.Reference<FileSystem.SizeInput>("effect/http/Multipart/MaxFieldSize", {
@@ -769,7 +770,7 @@ export const MaxFieldSize = Context.Reference<FileSystem.SizeInput>("effect/http
  *
  * The default is `undefined`, meaning no explicit per-file limit.
  *
- * @category References
+ * @category references
  * @since 4.0.0
  */
 export const MaxFileSize = Context.Reference<FileSystem.SizeInput | undefined>(
@@ -783,7 +784,7 @@ export const MaxFileSize = Context.Reference<FileSystem.SizeInput | undefined>(
  *
  * The default treats `application/json` parts as fields.
  *
- * @category References
+ * @category references
  * @since 4.0.0
  */
 export const FieldMimeTypes = Context.Reference<ReadonlyArray<string>>("effect/http/Multipart/FieldMimeTypes", {

package/src/unstable/http/Template.ts

@@ -68,7 +68,6 @@ export type InterpolatedWithStream = Interpolated | Stream.Stream<Primitive, any
 /**
  * Namespace containing type-level helpers for template interpolations.
  *
- * @category models
  * @since 4.0.0
  */
 export declare namespace Interpolated {