effect 3.10.18 → 3.11.0

package/src/Schema.ts

@@ -628,6 +628,7 @@ export function Literal<Literals extends ReadonlyArray<AST.LiteralValue>>(
  * Creates a new `Schema` from a literal schema.
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  * import { Either } from "effect"
  *
@@ -636,6 +637,7 @@ export function Literal<Literals extends ReadonlyArray<AST.LiteralValue>>(
  * assert.deepStrictEqual(Schema.decodeSync(schema)("a"), "a")
  * assert.deepStrictEqual(Schema.decodeSync(schema)("b"), "b")
  * assert.strictEqual(Either.isLeft(Schema.decodeUnknownEither(schema)("c")), true)
+ * ```
  *
  * @category constructors
  * @since 3.10.0
@@ -2794,6 +2796,7 @@ export interface tag<Tag extends AST.LiteralValue> extends PropertySignature<":"
  * @see {@link TaggedStruct}
  *
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * const User = Schema.Struct({
@@ -2803,6 +2806,7 @@ export interface tag<Tag extends AST.LiteralValue> extends PropertySignature<":"
  * })
  *
  * assert.deepStrictEqual(User.make({ name: "John", age: 44 }), { _tag: "User", name: "John", age: 44 })
+ * ```
  *
  * @since 3.10.0
  */
@@ -2823,6 +2827,7 @@ export type TaggedStruct<Tag extends AST.LiteralValue, Fields extends Struct.Fie
  * The tag is optional when using the `make` method.
  *
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * const User = Schema.TaggedStruct("User", {
@@ -2831,6 +2836,7 @@ export type TaggedStruct<Tag extends AST.LiteralValue, Fields extends Struct.Fie
  * })
  *
  * assert.deepStrictEqual(User.make({ name: "John", age: 44 }), { _tag: "User", name: "John", age: 44 })
+ * ```
  *
  * @category constructors
  * @since 3.10.0
@@ -2899,6 +2905,7 @@ export const omit = <A, I, Keys extends ReadonlyArray<keyof A & keyof I>>(...key
  * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * // ---------------------------------------------
@@ -2918,6 +2925,7 @@ export const omit = <A, I, Keys extends ReadonlyArray<keyof A & keyof I>>(...key
  *
  * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
  * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+ * ```
  *
  * @category struct transformations
  * @since 3.10.0
@@ -2928,6 +2936,7 @@ export const pluck: {
    * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * // ---------------------------------------------
@@ -2947,6 +2956,7 @@ export const pluck: {
    *
    * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
    * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+   * ```
    *
    * @category struct transformations
    * @since 3.10.0
@@ -2959,6 +2969,7 @@ export const pluck: {
    * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * // ---------------------------------------------
@@ -2978,6 +2989,7 @@ export const pluck: {
    *
    * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
    * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+   * ```
    *
    * @category struct transformations
    * @since 3.10.0
@@ -2996,6 +3008,7 @@ export const pluck: {
        * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
        *
        * @example
+       * ```ts
        * import * as Schema from "effect/Schema"
        *
        * // ---------------------------------------------
@@ -3015,6 +3028,7 @@ export const pluck: {
        *
        * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
        * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+       * ```
        *
        * @category struct transformations
        * @since 3.10.0
@@ -3024,6 +3038,7 @@ export const pluck: {
        * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
        *
        * @example
+       * ```ts
        * import * as Schema from "effect/Schema"
        *
        * // ---------------------------------------------
@@ -3043,6 +3058,7 @@ export const pluck: {
        *
        * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
        * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+       * ```
        *
        * @category struct transformations
        * @since 3.10.0
@@ -3052,6 +3068,7 @@ export const pluck: {
        * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
        *
        * @example
+       * ```ts
        * import * as Schema from "effect/Schema"
        *
        * // ---------------------------------------------
@@ -3071,6 +3088,7 @@ export const pluck: {
        *
        * console.log(Schema.decodeUnknownEither(Schema.Array(pullOutColumn))([{ column1: "1", column2: 100 }, { column1: "2", column2: 300 }]))
        * // Output: { _id: 'Either', _tag: 'Right', right: [ 1, 2 ] }
+       * ```
        *
        * @category struct transformations
        * @since 3.10.0
@@ -3132,10 +3150,12 @@ const makeBrandClass = <S extends Schema.Any, B extends string | symbol>(
  * @param brand - The brand to apply.
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * const Int = Schema.Number.pipe(Schema.int(), Schema.brand("Int"))
  * type Int = Schema.Schema.Type<typeof Int> // number & Brand<"Int">
+ * ```
  *
  * @category branding
  * @since 3.10.0
@@ -3431,6 +3451,7 @@ export interface extend<Self extends Schema.Any, That extends Schema.Any> extend
  * - A suspend of a struct with a supported schema
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * const schema = Schema.Struct({
@@ -3452,6 +3473,7 @@ export interface extend<Self extends Schema.Any, That extends Schema.Any> extend
  *   Schema.extend(Schema.Struct({ c: Schema.String })), // <= you can add more fields
  *   Schema.extend(Schema.Record({ key: Schema.String, value: Schema.String })) // <= you can add index signatures
  * ))
+ * ```
  *
  * @category combinators
  * @since 3.10.0
@@ -3473,6 +3495,7 @@ export const extend: {
    * - A suspend of a struct with a supported schema
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * const schema = Schema.Struct({
@@ -3494,6 +3517,7 @@ export const extend: {
    *   Schema.extend(Schema.Struct({ c: Schema.String })), // <= you can add more fields
    *   Schema.extend(Schema.Record({ key: Schema.String, value: Schema.String })) // <= you can add index signatures
    * ))
+   * ```
    *
    * @category combinators
    * @since 3.10.0
@@ -3515,6 +3539,7 @@ export const extend: {
    * - A suspend of a struct with a supported schema
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * const schema = Schema.Struct({
@@ -3536,6 +3561,7 @@ export const extend: {
    *   Schema.extend(Schema.Struct({ c: Schema.String })), // <= you can add more fields
    *   Schema.extend(Schema.Record({ key: Schema.String, value: Schema.String })) // <= you can add index signatures
    * ))
+   * ```
    *
    * @category combinators
    * @since 3.10.0
@@ -4086,11 +4112,13 @@ export interface transformLiteral<Type, Encoded> extends Annotable<transformLite
  * Creates a new `Schema` which transforms literal values.
  *
  * @example
+ * ```ts
  * import * as S from "effect/Schema"
  *
  * const schema = S.transformLiteral(0, "a")
  *
  * assert.deepStrictEqual(S.decodeSync(schema)(0), "a")
+ * ```
  *
  * @category constructors
  * @since 3.10.0
@@ -4105,6 +4133,7 @@ export const transformLiteral = <Encoded extends AST.LiteralValue, Type extends
  * Creates a new `Schema` which maps between corresponding literal values.
  *
  * @example
+ * ```ts
  * import * as S from "effect/Schema"
  *
  * const Animal = S.transformLiterals(
@@ -4114,6 +4143,7 @@ export const transformLiteral = <Encoded extends AST.LiteralValue, Type extends
  * )
  *
  * assert.deepStrictEqual(S.decodeSync(Animal)(1), "dog")
+ * ```
  *
  * @category constructors
  * @since 3.10.0
@@ -4143,6 +4173,7 @@ export function transformLiterals<
  * @param value - The value of the property to add to the schema.
  *
  * @example
+ * ```ts
  * import * as S from "effect/Schema"
  * import { pipe } from "effect/Function"
  *
@@ -4157,6 +4188,7 @@ export function transformLiterals<
  *   kind: "circle",
  *   radius: 10
  * })
+ * ```
  *
  * @category combinators
  * @since 3.10.0
@@ -4172,6 +4204,7 @@ export const attachPropertySignature: {
    * @param value - The value of the property to add to the schema.
    *
    * @example
+   * ```ts
    * import * as S from "effect/Schema"
    * import { pipe } from "effect/Function"
    *
@@ -4186,6 +4219,7 @@ export const attachPropertySignature: {
    *   kind: "circle",
    *   radius: 10
    * })
+   * ```
    *
    * @category combinators
    * @since 3.10.0
@@ -4207,6 +4241,7 @@ export const attachPropertySignature: {
    * @param value - The value of the property to add to the schema.
    *
    * @example
+   * ```ts
    * import * as S from "effect/Schema"
    * import { pipe } from "effect/Function"
    *
@@ -4221,6 +4256,7 @@ export const attachPropertySignature: {
    *   kind: "circle",
    *   radius: 10
    * })
+   * ```
    *
    * @category combinators
    * @since 3.10.0
@@ -4837,11 +4873,13 @@ export class Trimmed extends String$.pipe(
  * leading or trailing whitespace.
  *
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * console.log(Schema.decodeOption(Schema.NonEmptyTrimmedString)("")) // Option.none()
  * console.log(Schema.decodeOption(Schema.NonEmptyTrimmedString)(" a ")) // Option.none()
  * console.log(Schema.decodeOption(Schema.NonEmptyTrimmedString)("a")) // Option.some("a")
+ * ```
  *
  * @category string constructors
  * @since 3.10.0
@@ -4918,10 +4956,12 @@ const getParseJsonTransformation = (options?: ParseJsonOptions) =>
  * Optionally, you can pass a schema `Schema<A, I, R>` to obtain an `A` type instead of `unknown`.
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson())(`{"a":"1"}`), { a: "1" })
  * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson(Schema.Struct({ a: Schema.NumberFromString })))(`{"a":"1"}`), { a: 1 })
+ * ```
  *
  * @category string transformations
  * @since 3.10.0
@@ -4936,10 +4976,12 @@ export const parseJson: {
    * Optionally, you can pass a schema `Schema<A, I, R>` to obtain an `A` type instead of `unknown`.
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson())(`{"a":"1"}`), { a: "1" })
    * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson(Schema.Struct({ a: Schema.NumberFromString })))(`{"a":"1"}`), { a: 1 })
+   * ```
    *
    * @category string transformations
    * @since 3.10.0
@@ -4954,10 +4996,12 @@ export const parseJson: {
    * Optionally, you can pass a schema `Schema<A, I, R>` to obtain an `A` type instead of `unknown`.
    *
    * @example
+   * ```ts
    * import * as Schema from "effect/Schema"
    *
    * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson())(`{"a":"1"}`), { a: "1" })
    * assert.deepStrictEqual(Schema.decodeUnknownSync(Schema.parseJson(Schema.Struct({ a: Schema.NumberFromString })))(`{"a":"1"}`), { a: 1 })
+   * ```
    *
    * @category string transformations
    * @since 3.10.0
@@ -4997,6 +5041,10 @@ export class UUID extends String$.pipe(
     schemaId: UUIDSchemaId,
     identifier: "UUID",
     title: "UUID",
+    jsonSchema: {
+      format: "uuid",
+      pattern: uuidRegexp.source
+    },
     description: "a Universally Unique Identifier",
     arbitrary: (): LazyArbitrary<string> => (fc) => fc.uuid()
   })
@@ -5029,6 +5077,49 @@ export class ULID extends String$.pipe(
   })
 ) {}
 
+/**
+ * Defines a schema that represents a `URL` object.
+ *
+ * @category URL constructors
+ * @since 3.11.0
+ */
+export class URLFromSelf extends instanceOf(URL, {
+  identifier: "URLFromSelf",
+  title: "URLFromSelf",
+  arbitrary: (): LazyArbitrary<URL> => (fc) => fc.webUrl().map((s) => new URL(s)),
+  pretty: () => (url) => url.toString()
+}) {}
+
+/** @ignore */
+class URL$ extends transformOrFail(
+  String$.annotations({ description: "a string that will be parsed into a URL" }),
+  URLFromSelf,
+  {
+    strict: true,
+    decode: (str, _, ast) =>
+      ParseResult.try({
+        try: () => new URL(str),
+        catch: () => new ParseResult.Type(ast, str)
+      }),
+    encode: (url) => ParseResult.succeed(url.toString())
+  }
+).annotations({
+  identifier: "URL",
+  title: "URL",
+  pretty: () => (url) => url.toString()
+}) {}
+
+export {
+  /**
+   * Defines a schema that attempts to convert a `string` to a `URL` object using
+   * the `new URL` constructor.
+   *
+   * @category URL transformations
+   * @since 3.11.0
+   */
+  URL$ as URL
+}
+
 /**
  * @category schema id
  * @since 3.10.0
@@ -5430,6 +5521,7 @@ export const JsonNumberSchemaId: unique symbol = Symbol.for("effect/SchemaId/Jso
  * format.
  *
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * const is = Schema.is(S.JsonNumber)
@@ -5438,6 +5530,7 @@ export const JsonNumberSchemaId: unique symbol = Symbol.for("effect/SchemaId/Jso
  * assert.deepStrictEqual(is(Number.NaN), false)
  * assert.deepStrictEqual(is(Number.POSITIVE_INFINITY), false)
  * assert.deepStrictEqual(is(Number.NEGATIVE_INFINITY), false)
+ * ```
  *
  * @category number constructors
  * @since 3.10.0
@@ -7089,11 +7182,13 @@ export const OptionFromUndefinedOr = <Value extends Schema.Any>(
  * `none` for invalid inputs and `some` for valid non-empty strings.
  *
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * console.log(Schema.decodeSync(Schema.OptionFromNonEmptyTrimmedString)("")) // Option.none()
  * console.log(Schema.decodeSync(Schema.OptionFromNonEmptyTrimmedString)(" a ")) // Option.some("a")
  * console.log(Schema.decodeSync(Schema.OptionFromNonEmptyTrimmedString)("a")) // Option.some("a")
+ * ```
  *
  * @category Option transformations
  * @since 3.10.0
@@ -7279,10 +7374,12 @@ export interface EitherFromUnion<R extends Schema.All, L extends Schema.All> ext
 
 /**
  * @example
+ * ```ts
  * import * as Schema from "effect/Schema"
  *
  * // Schema<string | number, Either<string, number>>
  * Schema.EitherFromUnion({ left: Schema.String, right: Schema.Number })
+ * ```
  *
  * @category Either transformations
  * @since 3.10.0
@@ -8243,6 +8340,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
 
   /**
    * @example
+   * ```ts
    * import { Schema } from "effect"
    *
    * class MyClass extends Schema.Class<MyClass>("MyClass")({
@@ -8260,6 +8358,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
    *    return this.myMethod() + this.myField + this.nextField
    *  }
    * }
+   * ```
    */
   extend<Extended = never>(identifier: string): <newFields extends Struct.Fields>(
     fields: newFields | HasFields<newFields>,
@@ -8277,6 +8376,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
 
   /**
    * @example
+   * ```ts
    * import { Effect, Schema } from "effect"
    *
    * class MyClass extends Schema.Class<MyClass>("MyClass")({
@@ -8301,6 +8401,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
    *     return this.myMethod() + this.myField + this.nextField
    *   }
    * }
+   * ```
    */
   transformOrFail<Transformed = never>(identifier: string): <
     newFields extends Struct.Fields,
@@ -8334,6 +8435,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
 
   /**
    * @example
+   * ```ts
    * import { Effect, Schema } from "effect"
    *
    * class MyClass extends Schema.Class<MyClass>("MyClass")({
@@ -8358,6 +8460,7 @@ export interface Class<Self, Fields extends Struct.Fields, I, R, C, Inherited, P
    *     return this.myMethod() + this.myField + this.nextField
    *   }
    * }
+   * ```
    */
   transformOrFailFrom<Transformed = never>(identifier: string): <
     newFields extends Struct.Fields,
@@ -8410,6 +8513,7 @@ const getFieldsFromFieldsOr = <Fields extends Struct.Fields>(fieldsOr: Fields |
 
 /**
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * class MyClass extends Schema.Class<MyClass>("MyClass")({
@@ -8419,6 +8523,7 @@ const getFieldsFromFieldsOr = <Fields extends Struct.Fields>(fieldsOr: Fields |
  *    return this.someField + "bar"
  *  }
  * }
+ * ```
  *
  * @category classes
  * @since 3.10.0
@@ -8470,11 +8575,13 @@ export interface TaggedClass<Self, Tag extends string, Fields extends Struct.Fie
 
 /**
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * class MyClass extends Schema.TaggedClass<MyClass>("MyClass")("MyClass", {
  *  a: Schema.String
  * }) {}
+ * ```
  *
  * @category classes
  * @since 3.10.0
@@ -8523,6 +8630,7 @@ export interface TaggedErrorClass<Self, Tag extends string, Fields extends Struc
 
 /**
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * class MyError extends Schema.TaggedError<MyError>("MyError")(
@@ -8537,6 +8645,7 @@ export interface TaggedErrorClass<Self, Tag extends string, Fields extends Struc
  *     return `${this.module}.${this.method}: ${this.description}`
  *   }
  * }
+ * ```
  * @category classes
  * @since 3.10.0
  */
@@ -9731,6 +9840,19 @@ export class BooleanFromUnknown extends transform(
   { strict: true, decode: Predicate.isTruthy, encode: identity }
 ).annotations({ identifier: "BooleanFromUnknown" }) {}
 
+/**
+ * Converts an `string` value into its corresponding `boolean`
+ * ("true" as `true` and "false" as `false`).
+ *
+ * @category boolean transformations
+ * @since 3.11.0
+ */
+export class BooleanFromString extends transform(
+  Literal("true", "false"),
+  Boolean$,
+  { strict: true, decode: (value) => value === "true", encode: (value) => value ? "true" : "false" }
+).annotations({ identifier: "BooleanFromString" }) {}
+
 /**
  * @category Config validations
  * @since 3.10.0
@@ -10259,6 +10381,7 @@ export interface TaggedRequestClass<
 
 /**
  * @example
+ * ```ts
  * import { Schema } from "effect"
  *
  * class MyRequest extends Schema.TaggedRequest<MyRequest>("MyRequest")("MyRequest", {
@@ -10266,6 +10389,7 @@ export interface TaggedRequestClass<
  *  success: Schema.Number,
  *  payload: { id: Schema.String }
  * }) {}
+ * ```
  *
  * @category classes
  * @since 3.10.0

package/src/Sink.ts

@@ -1765,6 +1765,17 @@ export const unwrapScoped: <A, In, L, E, R>(
   effect: Effect.Effect<Sink<A, In, L, E, R>, E, R>
 ) => Sink<A, In, L, E, Exclude<R, Scope.Scope>> = internal.unwrapScoped
 
+/**
+ * Constructs a `Sink` from a function which receives a `Scope` and returns
+ * an effect that will result in a `Sink` if successful.
+ *
+ * @since 3.11.0
+ * @category constructors
+ */
+export const unwrapScopedWith: <A, In, L, E, R>(
+  f: (scope: Scope.Scope) => Effect.Effect<Sink<A, In, L, E, R>, E, R>
+) => Sink<A, In, L, E, R> = internal.unwrapScopedWith
+
 /**
  * Returns the sink that executes this one and times its execution.
  *