effect 4.0.0-beta.67 → 4.0.0-beta.69

package/src/unstable/http/Url.ts

@@ -38,11 +38,11 @@ import * as UrlParams from "./UrlParams.ts"
  * `base`. This is especially useful when dealing with URLs that might not be
  * fully qualified.
  *
- * **Example**
+ * **Example** (Parsing absolute and relative URLs)
  *
  * ```ts
- * import { Url } from "effect/unstable/http"
  * import { Result } from "effect"
+ * import { Url } from "effect/unstable/http"
  *
  * // Parse an absolute URL
  * //
@@ -68,7 +68,7 @@ import * as UrlParams from "./UrlParams.ts"
  * // Output: Parsed relative URL: https://example.com/relative-path
  * ```
  *
- * @category Constructors
+ * @category constructors
  * @since 4.0.0
  */
 export const fromString: {
@@ -89,11 +89,11 @@ export const fromString: {
    * `base`. This is especially useful when dealing with URLs that might not be
    * fully qualified.
    *
-   * **Example**
+   * **Example** (Parsing absolute and relative URLs)
    *
    * ```ts
-   * import { Url } from "effect/unstable/http"
    * import { Result } from "effect"
+   * import { Url } from "effect/unstable/http"
    *
    * // Parse an absolute URL
    * //
@@ -119,7 +119,7 @@ export const fromString: {
    * // Output: Parsed relative URL: https://example.com/relative-path
    * ```
    *
-   * @category Constructors
+   * @category constructors
    * @since 4.0.0
    */
   (url: string, base?: string | URL | undefined): Result.Result<URL, Cause.IllegalArgumentError>
@@ -134,7 +134,7 @@ export const fromString: {
  * This function clones the original `URL` object and applies a callback to the
  * clone, allowing multiple updates at once.
  *
- * **Example**
+ * **Example** (Mutating URL credentials)
  *
  * ```ts
  * import { Url } from "effect/unstable/http"
@@ -158,7 +158,7 @@ export const mutate: {
    * This function clones the original `URL` object and applies a callback to the
    * clone, allowing multiple updates at once.
    *
-   * **Example**
+   * **Example** (Mutating URL credentials)
    *
    * ```ts
    * import { Url } from "effect/unstable/http"
@@ -182,7 +182,7 @@ export const mutate: {
    * This function clones the original `URL` object and applies a callback to the
    * clone, allowing multiple updates at once.
    *
-   * **Example**
+   * **Example** (Mutating URL credentials)
    *
    * ```ts
    * import { Url } from "effect/unstable/http"
@@ -462,7 +462,7 @@ export const setUsername: {
  * object using the provided `UrlParams`. It creates a new `URL` object with the
  * updated parameters, leaving the original object unchanged.
  *
- * **Example**
+ * **Example** (Replacing query parameters)
  *
  * ```ts
  * import { Url, UrlParams } from "effect/unstable/http"
@@ -492,7 +492,7 @@ export const setUrlParams: {
    * object using the provided `UrlParams`. It creates a new `URL` object with the
    * updated parameters, leaving the original object unchanged.
    *
-   * **Example**
+   * **Example** (Replacing query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -522,7 +522,7 @@ export const setUrlParams: {
    * object using the provided `UrlParams`. It creates a new `URL` object with the
    * updated parameters, leaving the original object unchanged.
    *
-   * **Example**
+   * **Example** (Replacing query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -557,7 +557,7 @@ export const setUrlParams: {
  * them as `UrlParams`. The resulting structure can be easily manipulated or
  * inspected.
  *
- * **Example**
+ * **Example** (Reading query parameters)
  *
  * ```ts
  * import { Url } from "effect/unstable/http"
@@ -571,7 +571,7 @@ export const setUrlParams: {
  * // Output: [ [ 'foo', 'bar' ] ]
  * ```
  *
- * @category Getters
+ * @category getters
  * @since 4.0.0
  */
 export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(url.searchParams)
@@ -586,7 +586,7 @@ export const urlParams = (url: URL): UrlParams.UrlParams => UrlParams.fromInput(
  * writing the updated parameters back to the URL. It returns a new `URL` object
  * with the modified parameters, ensuring immutability.
  *
- * **Example**
+ * **Example** (Modifying query parameters)
  *
  * ```ts
  * import { Url, UrlParams } from "effect/unstable/http"
@@ -613,7 +613,7 @@ export const modifyUrlParams: {
    * writing the updated parameters back to the URL. It returns a new `URL` object
    * with the modified parameters, ensuring immutability.
    *
-   * **Example**
+   * **Example** (Modifying query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"
@@ -640,7 +640,7 @@ export const modifyUrlParams: {
    * writing the updated parameters back to the URL. It returns a new `URL` object
    * with the modified parameters, ensuring immutability.
    *
-   * **Example**
+   * **Example** (Modifying query parameters)
    *
    * ```ts
    * import { Url, UrlParams } from "effect/unstable/http"

package/src/unstable/http/UrlParams.ts

@@ -59,7 +59,7 @@ export interface UrlParams extends Pipeable, Inspectable, Iterable<readonly [str
 /**
  * Returns `true` when a value is a `UrlParams` instance.
  *
- * @category Guards
+ * @category guards
  * @since 4.0.0
  */
 export const isUrlParams = (u: unknown): u is UrlParams => hasProperty(u, TypeId)
@@ -562,7 +562,7 @@ export const remove: {
 /**
  * Error returned when constructing a `URL` from `UrlParams` fails.
  *
- * @category Errors
+ * @category errors
  * @since 4.0.0
  */
 export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
@@ -575,7 +575,7 @@ export class UrlParamsError extends Data.TaggedError("UrlParamsError")<{
  * Returns a `Result` that fails with `UrlParamsError` if the URL cannot be
  * constructed.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const makeUrl = (
@@ -603,7 +603,7 @@ export const makeUrl = (
 /**
  * Serializes `UrlParams` to a URL query string without a leading question mark.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toString = (self: UrlParams): string => new URLSearchParams(self.params as any).toString()
@@ -625,7 +625,7 @@ const baseUrl = (): string | undefined => {
  * as `string` (if only one value for a key) or a `NonEmptyArray<string>`
  * (when more than one value for a key)
  *
- * **Example**
+ * **Example** (Converting parameters to a record)
  *
  * ```ts
  * import { UrlParams } from "effect/unstable/http"
@@ -645,7 +645,7 @@ const baseUrl = (): string | undefined => {
  * )
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toRecord = (self: UrlParams): Record<string, string | Arr.NonEmptyArray<string>> => {
@@ -669,7 +669,7 @@ export const toRecord = (self: UrlParams): Record<string, string | Arr.NonEmptyA
  * Keys with one value map to a string, and keys with multiple values map to a
  * non-empty readonly array of strings.
  *
- * @category conversions
+ * @category converting
  * @since 4.0.0
  */
 export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, string | Arr.NonEmptyReadonlyArray<string>> =
@@ -678,7 +678,7 @@ export const toReadonlyRecord: (self: UrlParams) => ReadonlyRecord<string, strin
 /**
  * Schema type for decoding one URL parameter field as JSON.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonString, UrlParamsSchema> {}
@@ -687,6 +687,8 @@ export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonS
  * Extract a JSON value from the first occurrence of the given `field` in the
  * `UrlParams`.
  *
+ * **Example** (Decoding JSON parameter fields)
+ *
  * ```ts
  * import { Schema } from "effect"
  * import { UrlParams } from "effect/unstable/http"
@@ -706,7 +708,7 @@ export interface schemaJsonField extends Schema.decodeTo<Schema.UnknownFromJsonS
  * )
  * ```
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaJsonField = (field: string): schemaJsonField =>
@@ -727,7 +729,7 @@ export const schemaJsonField = (field: string): schemaJsonField =>
 /**
  * Extract a record of key-value pairs from the `UrlParams`.
  *
- * @category Schemas
+ * @category schemas
  * @since 4.0.0
  */
 export interface schemaRecord extends
@@ -745,7 +747,7 @@ export interface schemaRecord extends
  * Keys with one value decode to a string, and keys with multiple values decode to
  * a non-empty readonly array of strings.
  *
- * **Example**
+ * **Example** (Decoding URL parameters to a record)
  *
  * ```ts
  * import { Schema } from "effect"
@@ -766,7 +768,7 @@ export interface schemaRecord extends
  * )
  * ```
  *
- * @category schema
+ * @category schemas
  * @since 4.0.0
  */
 export const schemaRecord: schemaRecord = UrlParamsSchema.pipe(