effect 4.0.0-beta.73 → 4.0.0-beta.75

package/src/unstable/http/HttpRouter.ts

@@ -302,7 +302,7 @@ export const RouterConfig = Context.Reference<Partial<FindMyWay.RouterConfig>>(
  * It provides the route definition and the path parameters captured by the route
  * matcher.
  *
- * @category route context
+ * @category services
  * @since 4.0.0
  */
 export class RouteContext extends Context.Service<RouteContext, {
@@ -313,7 +313,7 @@ export class RouteContext extends Context.Service<RouteContext, {
 /**
  * Effect that returns the path parameters captured for the current matched route.
  *
- * @category RouteContext
+ * @category getters
  * @since 4.0.0
  */
 export const params: Effect.Effect<
@@ -475,7 +475,7 @@ export const schemaPathParams = <A, I extends Readonly<Record<string, string | u
  *
  * **When to use**
  *
- * Use when you use it to register routes or middleware with the router during layer
+ * Use when you need to register routes or middleware with the router during layer
  * construction.
  *
  * **Example** (Registering routes during layer construction)
@@ -1293,7 +1293,7 @@ export const provideRequest =
 /**
  * Runs the provided application layer as an HTTP server.
  *
- * @category Server
+ * @category server
  * @since 4.0.0
  */
 export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.Only<"GlobalRequires", R>>(
@@ -1357,7 +1357,7 @@ export const serve = <A, E, R, HE, HR = Request.Only<"Requires", R> | Request.On
  * Web `Response` values and a `dispose` function for releasing the layer
  * resources.
  *
- * @category Server
+ * @category server
  * @since 4.0.0
  */
 export const toWebHandler = <

package/src/unstable/http/HttpServerResponse.ts

@@ -95,7 +95,7 @@ export interface HttpServerResponse extends Inspectable.Inspectable, Pipeable, E
 /**
  * Common options accepted by HTTP server response constructors.
  *
- * @category models
+ * @category options
  * @since 4.0.0
  */
 export interface Options {
@@ -118,7 +118,7 @@ export declare namespace Options {
    * Response options for constructors whose body determines its own content type
    * and content length.
    *
-   * @category models
+   * @category options
    * @since 4.0.0
    */
   export interface WithContent extends Omit<Options, "contentType" | "contentLength"> {}
@@ -127,7 +127,7 @@ export declare namespace Options {
    * Response options for constructors that allow overriding the content type while
    * deriving the content length from the body.
    *
-   * @category models
+   * @category options
    * @since 4.0.0
    */
   export interface WithContentType extends Omit<Options, "contentLength"> {}
@@ -391,6 +391,11 @@ export const schemaJson = <A, I, RD, RE>(
 /**
  * Creates a JSON HTTP response synchronously.
  *
+ * **When to use**
+ *
+ * Use when the response body is known to be JSON-serializable and you need a
+ * synchronous `HttpServerResponse`.
+ *
  * **Gotchas**
  *
  * Unlike `json`, serialization errors from `JSON.stringify` are not captured in
@@ -442,8 +447,8 @@ export const urlParams = (
  *
  * **When to use**
  *
- * Use when the underlying runtime already understands the body value, such
- * as a Web `Response`, `Blob`, or `ReadableStream`; the body is passed through
+ * Use when you want to pass through a body value already understood by the
+ * underlying runtime, such as a Web `Response`, `Blob`, or `ReadableStream`,
  * for later platform conversion.
  *
  * @category constructors
@@ -809,8 +814,8 @@ export const expireCookie: {
  *
  * **When to use**
  *
- * Use when setting one trusted cookie and encoding failures should throw
- * instead of being represented as `CookiesError` failures.
+ * Use when you need to set one trusted cookie and want encoding failures to
+ * throw instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -822,8 +827,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when setting one trusted cookie and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to set one trusted cookie and want encoding failures to
+   * throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -835,8 +840,8 @@ export const setCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when setting one trusted cookie and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to set one trusted cookie and want encoding failures to
+   * throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -867,8 +872,8 @@ export const setCookieUnsafe: {
  *
  * **When to use**
  *
- * Use when expiring one trusted cookie and encoding failures should throw
- * instead of being represented as `CookiesError` failures.
+ * Use when you need to expire one trusted cookie and want encoding failures to
+ * throw instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -880,8 +885,8 @@ export const expireCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when expiring one trusted cookie and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to expire one trusted cookie and want encoding failures to
+   * throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -896,8 +901,8 @@ export const expireCookieUnsafe: {
    *
    * **When to use**
    *
-   * Use when expiring one trusted cookie and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to expire one trusted cookie and want encoding failures to
+   * throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1096,8 +1101,8 @@ export const setCookies: {
  *
  * **When to use**
  *
- * Use when setting multiple trusted cookies and encoding failures should throw
- * instead of being represented as `CookiesError` failures.
+ * Use when you need to set multiple trusted cookies and want encoding failures
+ * to throw instead of being represented as `CookiesError` failures.
  *
  * @category combinators
  * @since 4.0.0
@@ -1109,8 +1114,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use when setting multiple trusted cookies and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to set multiple trusted cookies and want encoding failures
+   * to throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0
@@ -1130,8 +1135,8 @@ export const setCookiesUnsafe: {
    *
    * **When to use**
    *
-   * Use when setting multiple trusted cookies and encoding failures should throw
-   * instead of being represented as `CookiesError` failures.
+   * Use when you need to set multiple trusted cookies and want encoding failures
+   * to throw instead of being represented as `CookiesError` failures.
    *
    * @category combinators
    * @since 4.0.0

package/src/unstable/http/Multipart.ts

@@ -55,7 +55,7 @@ import * as Predicate from "../../Predicate.ts"
 import * as Pull from "../../Pull.ts"
 import * as Schema from "../../Schema.ts"
 import type { ParseOptions } from "../../SchemaAST.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import type * as Scope from "../../Scope.ts"
 import * as Stream from "../../Stream.ts"
 import * as UndefinedOr from "../../UndefinedOr.ts"
@@ -306,7 +306,7 @@ export const PersistedFileSchema: PersistedFileSchema = Schema.declare(
           contentType: Schema.String.annotate({ contentEncoding: "binary" }),
           path: Schema.String
         }),
-        Transformation.transform({
+        SchemaTransformation.transform({
           decode: ({ contentType, key, name, path }) => new PersistedFileImpl(key, name, contentType, path),
           encode: (file) => ({
             key: file.key,
@@ -344,7 +344,7 @@ export const SingleFileSchema: Schema.decodeTo<PersistedFileSchema, Schema.$Arra
   ).pipe(
     Schema.decodeTo(
       PersistedFileSchema,
-      Transformation.transform({
+      SchemaTransformation.transform({
         decode: ([file]) => file,
         encode: (file) => [file]
       })

package/src/unstable/http/Url.ts

@@ -234,21 +234,21 @@ const immutableURLSetter = <P extends keyof URL, A = never>(property: P): {
 /**
  * Updates the hash fragment of the URL.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setHash: {
   /**
    * Updates the hash fragment of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (hash: string): (url: URL) => URL
   /**
    * Updates the hash fragment of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, hash: string): URL
@@ -257,21 +257,21 @@ export const setHash: {
 /**
  * Updates the host (domain and port) of the URL.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setHost: {
   /**
    * Updates the host (domain and port) of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (host: string): (url: URL) => URL
   /**
    * Updates the host (domain and port) of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, host: string): URL
@@ -280,21 +280,21 @@ export const setHost: {
 /**
  * Updates the domain of the URL without modifying the port.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setHostname: {
   /**
    * Updates the domain of the URL without modifying the port.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (hostname: string): (url: URL) => URL
   /**
    * Updates the domain of the URL without modifying the port.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, hostname: string): URL
@@ -303,21 +303,21 @@ export const setHostname: {
 /**
  * Replaces the entire URL string.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setHref: {
   /**
    * Replaces the entire URL string.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (href: string): (url: URL) => URL
   /**
    * Replaces the entire URL string.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, href: string): URL
@@ -326,21 +326,21 @@ export const setHref: {
 /**
  * Updates the password used for authentication.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setPassword: {
   /**
    * Updates the password used for authentication.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (password: string | Redacted.Redacted): (url: URL) => URL
   /**
    * Updates the password used for authentication.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, password: string | Redacted.Redacted): URL
@@ -354,21 +354,21 @@ export const setPassword: {
 /**
  * Updates the path of the URL.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setPathname: {
   /**
    * Updates the path of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (pathname: string): (url: URL) => URL
   /**
    * Updates the path of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, pathname: string): URL
@@ -377,21 +377,21 @@ export const setPathname: {
 /**
  * Updates the port of the URL.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setPort: {
   /**
    * Updates the port of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (port: string | number): (url: URL) => URL
   /**
    * Updates the port of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, port: string | number): URL
@@ -400,21 +400,21 @@ export const setPort: {
 /**
  * Updates the protocol (e.g., `http`, `https`).
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setProtocol: {
   /**
    * Updates the protocol (e.g., `http`, `https`).
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (protocol: string): (url: URL) => URL
   /**
    * Updates the protocol (e.g., `http`, `https`).
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, protocol: string): URL
@@ -423,21 +423,21 @@ export const setProtocol: {
 /**
  * Updates the query string of the URL.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setSearch: {
   /**
    * Updates the query string of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (search: string): (url: URL) => URL
   /**
    * Updates the query string of the URL.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, search: string): URL
@@ -446,21 +446,21 @@ export const setSearch: {
 /**
  * Updates the username used for authentication.
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setUsername: {
   /**
    * Updates the username used for authentication.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (username: string): (url: URL) => URL
   /**
    * Updates the username used for authentication.
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, username: string): URL
@@ -492,7 +492,7 @@ export const setUsername: {
  * // Output: https://example.com/?key=value
  * ```
  *
- * @category Setters
+ * @category setters
  * @since 4.0.0
  */
 export const setUrlParams: {
@@ -522,7 +522,7 @@ export const setUrlParams: {
    * // Output: https://example.com/?key=value
    * ```
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (urlParams: UrlParams.UrlParams): (url: URL) => URL
@@ -552,7 +552,7 @@ export const setUrlParams: {
    * // Output: https://example.com/?key=value
    * ```
    *
-   * @category Setters
+   * @category setters
    * @since 4.0.0
    */
   (url: URL, urlParams: UrlParams.UrlParams): URL

package/src/unstable/http/UrlParams.ts

@@ -51,8 +51,8 @@ import { hasProperty } from "../../Predicate.ts"
 import type { ReadonlyRecord } from "../../Record.ts"
 import * as Result from "../../Result.ts"
 import * as Schema from "../../Schema.ts"
-import * as Issue from "../../SchemaIssue.ts"
-import * as Transformation from "../../SchemaTransformation.ts"
+import * as SchemaIssue from "../../SchemaIssue.ts"
+import * as SchemaTransformation from "../../SchemaTransformation.ts"
 import * as Tuple from "../../Tuple.ts"
 
 const TypeId = "~effect/http/UrlParams"
@@ -276,7 +276,7 @@ export const UrlParamsSchema: UrlParamsSchema = Schema.declare(
     toCodec: () =>
       Schema.link<UrlParams>()(
         Schema.Array(Schema.Tuple([Schema.String, Schema.String])),
-        Transformation.transform({
+        SchemaTransformation.transform({
           decode: make,
           encode: (self) => self.params
         })
@@ -339,6 +339,11 @@ export const getAll: {
 /**
  * Returns the first value for a query parameter key safely.
  *
+ * **When to use**
+ *
+ * Use when duplicate query parameters are ordered and the first occurrence has
+ * precedence.
+ *
  * **Details**
  *
  * Returns `Option.none` when the key is absent.
@@ -350,6 +355,11 @@ export const getFirst: {
   /**
    * Returns the first value for a query parameter key safely.
    *
+   * **When to use**
+   *
+   * Use when duplicate query parameters are ordered and the first occurrence has
+   * precedence.
+   *
    * **Details**
    *
    * Returns `Option.none` when the key is absent.
@@ -361,6 +371,11 @@ export const getFirst: {
   /**
    * Returns the first value for a query parameter key safely.
    *
+   * **When to use**
+   *
+   * Use when duplicate query parameters are ordered and the first occurrence has
+   * precedence.
+   *
    * **Details**
    *
    * Returns `Option.none` when the key is absent.
@@ -380,6 +395,11 @@ export const getFirst: {
 /**
  * Returns the last value for a query parameter key safely.
  *
+ * **When to use**
+ *
+ * Use when duplicate query parameters are ordered and the last occurrence has
+ * precedence.
+ *
  * **Details**
  *
  * Returns `Option.none` when the key is absent.
@@ -391,6 +411,11 @@ export const getLast: {
   /**
    * Returns the last value for a query parameter key safely.
    *
+   * **When to use**
+   *
+   * Use when duplicate query parameters are ordered and the last occurrence has
+   * precedence.
+   *
    * **Details**
    *
    * Returns `Option.none` when the key is absent.
@@ -402,6 +427,11 @@ export const getLast: {
   /**
    * Returns the last value for a query parameter key safely.
    *
+   * **When to use**
+   *
+   * Use when duplicate query parameters are ordered and the last occurrence has
+   * precedence.
+   *
    * **Details**
    *
    * Returns `Option.none` when the key is absent.
@@ -792,10 +822,10 @@ export const schemaJsonField = (field: string): schemaJsonField =>
   UrlParamsSchema.pipe(
     Schema.decodeTo(
       Schema.UnknownFromJsonString,
-      Transformation.transformOrFail({
+      SchemaTransformation.transformOrFail({
         decode: (params) =>
           Option.match(getFirst(params, field), {
-            onNone: () => Effect.fail(new Issue.Pointer([field], new Issue.MissingKey(undefined))),
+            onNone: () => Effect.fail(new SchemaIssue.Pointer([field], new SchemaIssue.MissingKey(undefined))),
             onSome: Effect.succeed
           }),
         encode: (value) => Effect.succeed(make([[field, value]]))
@@ -856,7 +886,7 @@ export const schemaRecord: schemaRecord = UrlParamsSchema.pipe(
       Schema.String,
       Schema.Union([Schema.String, Schema.NonEmptyArray(Schema.String)])
     ),
-    Transformation.transform({
+    SchemaTransformation.transform({
       decode: toReadonlyRecord,
       encode: fromInput
     })

package/src/unstable/httpapi/HttpApi.ts

@@ -54,7 +54,7 @@ import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Record from "../../Record.ts"
 import type * as Schema from "../../Schema.ts"
-import type * as AST from "../../SchemaAST.ts"
+import type * as SchemaAST from "../../SchemaAST.ts"
 import type { Mutable } from "../../Types.ts"
 import type { PathInput } from "../http/HttpRouter.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
@@ -236,8 +236,9 @@ const makeProto = <Id extends string, Groups extends HttpApiGroup.Any>(
  *
  * **When to use**
  *
- * Use when add groups with `add` or `addHttpApi`, provide endpoint implementations with
- * `HttpApiBuilder.group`, and register the API with `HttpApiBuilder.layer`.
+ * Use when you need to start defining an HTTP API, add groups with `add` or
+ * `addHttpApi`, provide endpoint implementations with `HttpApiBuilder.group`,
+ * and register the API with `HttpApiBuilder.layer`.
  *
  * @category constructors
  * @since 4.0.0
@@ -321,7 +322,7 @@ export const reflect = <Id extends string, Groups extends HttpApiGroup.Any>(
 
 const extractResponseContent = (
   schemas: Array<Schema.Top>,
-  getStatus: (ast: AST.AST) => number
+  getStatus: (ast: SchemaAST.AST) => number
 ): ReadonlyMap<number, [Schema.Top, ...Array<Schema.Top>]> => {
   const map = new Map<number, [Schema.Top, ...Array<Schema.Top>]>()
 
@@ -345,7 +346,7 @@ const extractResponseContent = (
  * Adds additional schemas to components/schemas.
  * The provided schemas must have a `identifier` annotation.
  *
- * @category tags
+ * @category services
  * @since 4.0.0
  */
 export class AdditionalSchemas extends Context.Service<