FileType-level representation of File.
export interface File extends interface instanceOf<T, Iso = T>Creates a schema that validates values using instanceof.
Decoding and encoding pass the value through unchanged.
Example (Defining a schema for a built-in class)
import { Schema } from "effect"
const DateSchema = Schema.instanceOf(Date)
const decoded = Schema.decodeUnknownSync(DateSchema)(new Date("2024-01-01"))
// decoded: Date
Type-level representation returned by
instanceOf
.
instanceOf<module globalThisglobalThis.File> {
readonly "Rebuild": File
}
/**
* Schema for JavaScript `File` objects.
*
* **Details**
*
* The default JSON serializer encodes a `File` as `{ data, type, name, lastModified }`
* where `data` is base64-encoded.
*
* @category file
* @since 4.0.0
*/
export const const File: Fileconst File: {
Rebuild: File;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<globalThis.File, readonly []>) => File;
annotateKey: (annotations: Annotations.Key<globalThis.File>) => File;
check: (checks_0: SchemaAST.Check<globalThis.File>, ...checks: Array<SchemaAST.Check<globalThis.File>>) => File;
rebuild: (ast: SchemaAST.Declaration) => File;
make: (input: globalThis.File, options?: MakeOptions) => globalThis.File;
makeOption: (input: globalThis.File, options?: MakeOptions) => Option_.Option<globalThis.File>;
makeEffect: (input: globalThis.File, options?: MakeOptions) => Effect.Effect<globalThis.File, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
File
.
Schema for JavaScript File objects.
Details
The default JSON serializer encodes a File as { data, type, name, lastModified }
where data is base64-encoded.
File: File = function instanceOf<
C extends abstract new (...args: any) => any,
Iso = InstanceType<C>
>(
constructor: C,
annotations?:
| Annotations.Declaration<InstanceType<C>>
| undefined
): instanceOf<InstanceType<C>, Iso>
Creates a schema that validates values using instanceof.
Decoding and encoding pass the value through unchanged.
Example (Defining a schema for a built-in class)
import { Schema } from "effect"
const DateSchema = Schema.instanceOf(Date)
const decoded = Schema.decodeUnknownSync(DateSchema)(new Date("2024-01-01"))
// decoded: Date
instanceOf(module globalThisglobalThis.var File: {
new (
fileBits: BlobPart[],
fileName: string,
options?: FilePropertyBag
): globalThis.File
prototype: globalThis.File
}
The File interface provides information about files and allows JavaScript in a web page to access their content.
File, {
Annotations.Declaration<globalThis.File, readonly []>.typeConstructor?: {
readonly [key: string]: unknown;
readonly _tag: string;
} | undefined
typeConstructor: {
_tag: string_tag: "File"
},
Annotations.Declaration<globalThis.File, readonly []>.generation?: {
readonly runtime: string;
readonly Type: string;
readonly Encoded?: string | undefined;
readonly importDeclaration?: string | undefined;
} | undefined
generation: {
runtime: stringruntime: `Schema.File`,
type Type: stringType: `globalThis.File`
},
Annotations.Augment.expected?: string | undefinedHuman-readable description of what a value is expected to satisfy.
Details
For filter and refinement failures, the default formatter uses
message first, then expected, and finally falls back to <filter>.
Use this to name a failed filter in the default message:
Expected <expected>, got <actual>.
expected: "File",
Annotations.Declaration<globalThis.File, readonly []>.toCodecJson?: ((typeParameters: readonly []) => SchemaAST.Link) | undefinedtoCodecJson: () =>
function link<T>(): <
To extends Constraint
>(
encodeTo: To,
transformation: {
readonly decode: SchemaGetter.Getter<
T,
NoInfer<To["Type"]>
>
readonly encode: SchemaGetter.Getter<
NoInfer<To["Type"]>,
T
>
}
) => SchemaAST.Link
Constructs an SchemaAST.Link that describes how a value of type T encodes to and decodes from a To schema.
Used when building low-level AST transformations that bridge two schema types.
link<module globalThisglobalThis.File>()(
function Struct<
Fields extends Struct.Fields
>(fields: Fields): Struct<Fields>
Defines a struct schema from a map of field schemas.
Details
Each field value is a schema. Use
optionalKey
or
optional
to
mark fields as optional, and
mutableKey
to mark them as mutable.
The resulting schema's Type is a readonly object type with the fields'
decoded types. The Encoded form mirrors the field schemas' encoded types.
Example (Defining a basic struct)
import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
console.log(alice)
// { name: 'Alice', age: 30 }
Struct({
data: String(property) data: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
data: const String: Stringconst String: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof "string".
String.Bottom<string, string, never, never, String, String, string, string, readonly [], string, "readonly", "required", "no-default", "readonly", "required">.check(checks_0: SchemaAST.Check<string>, ...checks: SchemaAST.Check<string>[]): Stringcheck(function isBase64(
annotations?: Annotations.Filter
): SchemaAST.Filter<string>
Validates that a string is valid Base64 encoded data.
Details
JSON Schema:
This check corresponds to a pattern constraint in JSON Schema that matches
Base64 format.
Arbitrary:
When generating test data with fast-check, this applies a patterns
constraint to ensure generated strings match the Base64 pattern.
isBase64()),
type: String(property) type: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
type: const String: Stringconst String: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof "string".
String,
name: String(property) name: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
name: const String: Stringconst String: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<string, readonly []>) => String;
annotateKey: (annotations: Annotations.Key<string>) => String;
check: (checks_0: SchemaAST.Check<string>, ...checks: Array<SchemaAST.Check<string>>) => String;
rebuild: (ast: SchemaAST.String) => String;
make: (input: string, options?: MakeOptions) => string;
makeOption: (input: string, options?: MakeOptions) => Option_.Option<string>;
makeEffect: (input: string, options?: MakeOptions) => Effect.Effect<string, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
String
.
Schema for string values. Validates that the input is typeof "string".
String,
lastModified: Number(property) lastModified: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<number, readonly []>) => Number;
annotateKey: (annotations: Annotations.Key<number>) => Number;
check: (checks_0: SchemaAST.Check<number>, ...checks: Array<SchemaAST.Check<number>>) => Number;
rebuild: (ast: SchemaAST.Number) => Number;
make: (input: number, options?: MakeOptions) => number;
makeOption: (input: number, options?: MakeOptions) => Option_.Option<number>;
makeEffect: (input: number, options?: MakeOptions) => Effect.Effect<number, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
lastModified: const Number: Numberconst Number: {
Rebuild: Rebuild;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<number, readonly []>) => Number;
annotateKey: (annotations: Annotations.Key<number>) => Number;
check: (checks_0: SchemaAST.Check<number>, ...checks: Array<SchemaAST.Check<number>>) => Number;
rebuild: (ast: SchemaAST.Number) => Number;
make: (input: number, options?: MakeOptions) => number;
makeOption: (input: number, options?: MakeOptions) => Option_.Option<number>;
makeEffect: (input: number, options?: MakeOptions) => Effect.Effect<number, SchemaError, never>;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
}
Type-level representation of
Number
.
Schema for number values, including NaN, Infinity, and -Infinity.
Details
Default JSON serializer:
- Finite numbers are serialized as numbers.
- Non-finite values are serialized as strings (
"NaN", "Infinity", "-Infinity").
Number
}),
import SchemaTransformationSchemaTransformation.function transformOrFail<
T,
E,
RD = never,
RE = never
>(options: {
readonly decode: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, RD>
readonly encode: (
t: T,
options: SchemaAST.ParseOptions
) => Effect.Effect<E, SchemaIssue.Issue, RE>
}): Transformation<T, E, RD, RE>
Creates a Transformation from effectful decode and encode functions that
can fail with Issue.
When to use
Use when you need a schema transformation that may fail or require Effect
services.
Details
- Each function receives the input value and
ParseOptions.
- Must return an
Effect that succeeds with the output or fails with Issue.
- Skips
None inputs (missing keys) — functions are only called on present values.
Example (Parsing a date string that can fail)
import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect"
const DateFromString = Schema.String.pipe(
Schema.decodeTo(
Schema.Date,
SchemaTransformation.transformOrFail({
decode: (s) => {
const d = new Date(s)
return isNaN(d.getTime())
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "Invalid date" }))
: Effect.succeed(d)
},
encode: (d) => Effect.succeed(d.toISOString())
})
)
)
transformOrFail({
decode: (
e: NoInfer<
Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
>,
options: SchemaAST.ParseOptions
) => Effect.Effect<
globalThis.File,
SchemaIssue.Issue,
never
>
decode: (e: NoInfer<
Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
>
e) =>
import Result_Result_.const match: {
<E, B, A, C = B>(options: {
readonly onFailure: (error: E) => B
readonly onSuccess: (ok: A) => C
}): (self: Result<A, E>) => B | C
<A, E, B, C = B>(
self: Result<A, E>,
options: {
readonly onFailure: (error: E) => B
readonly onSuccess: (ok: A) => C
}
): B | C
}
match(import EncodingEncoding.const decodeBase64: (
str: string
) => Result.Result<Uint8Array, EncodingError>
Decodes a base64 (RFC4648) string into bytes safely.
When to use
Use to decode a standard padded Base64 string into bytes without throwing on
invalid input.
Details
Returns Result.succeed with a Uint8Array when decoding succeeds, or
Result.fail with an EncodingError when the input is not valid base64.
Example (Decoding Base64 bytes)
import { Encoding, Result } from "effect"
const result = Encoding.decodeBase64("SGVsbG8=")
if (Result.isSuccess(result)) {
console.log(Array.from(result.success)) // [72, 101, 108, 108, 111]
}
decodeBase64(e: Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
(parameter) e: {
data: string;
type: string;
name: string;
lastModified: number;
}
e.data: stringdata), {
onFailure: (
error: Encoding.EncodingError
) => Effect.Effect<
never,
SchemaIssue.InvalidValue,
never
>
onFailure: (error: Encoding.EncodingError(parameter) error: {
name: string;
message: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
kind: 'Decode' | 'Encode';
module: string;
input: unknown;
}
error) =>
import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(
new import SchemaIssueSchemaIssue.constructor InvalidValue(actual: Option_.Option<unknown>, annotations?: Annotations.Issue | undefined): SchemaIssue.InvalidValueRepresents a schema issue produced when the input has the correct type but its value violates a
constraint (e.g. a string that is too short, a number out of range).
When to use
Use when you need to detect constraint violations from Schema.filter,
Schema.minLength, Schema.greaterThan, or similar checks.
Details
actual is Option.some(value) when the failing value is known, or
Option.none() when absent.
annotations optionally carries a message string for formatting.
- The default formatter renders this as
"Invalid data <actual>" unless a
custom message annotation is provided.
Example (Returning InvalidValue from a custom filter)
import { Option, SchemaIssue } from "effect"
const issue = new SchemaIssue.InvalidValue(
Option.some(""),
{ message: "must not be empty" }
)
console.log(String(issue))
// "must not be empty"
InvalidValue(import Option_Option_.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(e: Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
(parameter) e: {
data: string;
type: string;
name: string;
lastModified: number;
}
e.data: stringdata), {
Annotations.Issue.message?: string | undefinedmessage: error: Encoding.EncodingError(parameter) error: {
name: string;
message: string;
stack: string;
cause: unknown;
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
_tag: Tag;
kind: 'Decode' | 'Encode';
module: string;
input: unknown;
}
error.Error.message: stringmessage
})
),
onSuccess: (
ok: globalThis.Uint8Array<ArrayBufferLike>
) => Effect.Effect<globalThis.File, never, never>
onSuccess: (bytes: globalThis.Uint8Array<ArrayBufferLike>bytes) => {
const const buffer: globalThis.Uint8Array<ArrayBuffer>buffer = new module globalThisglobalThis.var Uint8Array: Uint8ArrayConstructor
new (elements: Iterable<number>) => globalThis.Uint8Array<ArrayBuffer> (+6 overloads)
Uint8Array(bytes: globalThis.Uint8Array<ArrayBufferLike>bytes)
return import EffectEffect.const succeed: <A>(value: A) => Effect<A>Creates an Effect that always succeeds with a given value.
When to use
Use when an effect should complete successfully with a specific value without any errors
or external dependencies.
Example (Creating a successful effect)
import { Effect } from "effect"
// Creating an effect that represents a successful scenario
//
// ┌─── Effect<number, never, never>
// ▼
const success = Effect.succeed(42)
succeed(
new module globalThisglobalThis.var File: new (
fileBits: BlobPart[],
fileName: string,
options?: FilePropertyBag
) => globalThis.File
The File interface provides information about files and allows JavaScript in a web page to access their content.
File([const buffer: globalThis.Uint8Array<ArrayBuffer>buffer], e: Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
(parameter) e: {
data: string;
type: string;
name: string;
lastModified: number;
}
e.name: stringname, { BlobPropertyBag.type?: string | undefinedtype: e: Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
(parameter) e: {
data: string;
type: string;
name: string;
lastModified: number;
}
e.type: stringtype, FilePropertyBag.lastModified?: number | undefinedlastModified: e: Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
(parameter) e: {
data: string;
type: string;
name: string;
lastModified: number;
}
e.lastModified: numberlastModified })
)
}
}),
encode: (
t: globalThis.File,
options: SchemaAST.ParseOptions
) => Effect.Effect<
NoInfer<
Struct.ReadonlySide<
{
readonly data: String
readonly type: String
readonly name: String
readonly lastModified: Number
},
"Type"
>
>,
SchemaIssue.Issue,
never
>
encode: (file: globalThis.Filefile) =>
import EffectEffect.const tryPromise: <
A,
E = Cause.UnknownError
>(
options:
| {
readonly try: (
signal: AbortSignal
) => PromiseLike<A>
readonly catch: (error: unknown) => E
}
| ((signal: AbortSignal) => PromiseLike<A>)
) => Effect<A, E>
Creates an Effect from an asynchronous computation that may throw or
reject, mapping failures into the error channel.
When to use
Use when you need to perform asynchronous operations that might fail, such
as fetching data from an API, and want thrown exceptions or rejected promises
captured as Effect errors.
Details
The promise thunk is evaluated when the effect runs. If it returns a promise
that resolves, the resolved value becomes the success value. If the thunk
throws before returning a promise, or if the returned promise rejects, the
thrown or rejected value is mapped into the error channel.
Passing the thunk directly maps failures to
Cause.UnknownError
.
Passing { try, catch } uses catch to map failures to an error of type
E.
The thunk receives an AbortSignal that is aborted if the effect is
interrupted. The underlying asynchronous operation only stops if it observes
that signal.
Gotchas
If catch throws while mapping the error, that thrown value is treated as a
defect. Return the error value you want in the error channel instead of
throwing it.
Example (Wrapping a fetch request that may fail)
import { Effect } from "effect"
const getTodo = (id: number) =>
// Will catch any errors and propagate them as UnknownError
Effect.tryPromise(() =>
fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
)
// ┌─── Effect<Response, UnknownError, never>
// ▼
const program = getTodo(1)
Example (Mapping Promise rejections to a tagged error)
import { Data, Effect } from "effect"
class TodoFetchError extends Data.TaggedError("TodoFetchError")<{ readonly cause: unknown }> {}
const getTodo = (id: number) =>
Effect.tryPromise({
try: () => fetch(`https://jsonplaceholder.typicode.com/todos/${id}`),
// remap the error
catch: (cause) => new TodoFetchError({ cause })
})
// ┌─── Effect<Response, TodoFetchError, never>
// ▼
const program = getTodo(1)
tryPromise({
try: (signal: AbortSignal) => PromiseLike<{
data: string
type: string
name: string
lastModified: number
}>
try: async () => {
const const bytes: globalThis.Uint8Array<ArrayBuffer>bytes = new module globalThisglobalThis.var Uint8Array: Uint8ArrayConstructor
new <ArrayBuffer>(buffer: ArrayBuffer, byteOffset?: number, length?: number) => globalThis.Uint8Array<ArrayBuffer> (+6 overloads)
Uint8Array(await file: globalThis.Filefile.Blob.arrayBuffer(): Promise<ArrayBuffer>The arrayBuffer() method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer.
arrayBuffer())
return {
data: stringdata: import EncodingEncoding.const encodeBase64: (
input: globalThis.Uint8Array | string
) => string
Encodes the given value into a base64 (RFC4648) string.
When to use
Use to encode text or bytes as a standard padded Base64 string for storage or
transport.
Details
String inputs are encoded as UTF-8 bytes before Base64 encoding.
Uint8Array inputs are encoded directly. The output uses the standard
RFC4648 alphabet with = padding.
Example (Encoding Base64 strings and bytes)
import { Encoding } from "effect"
// Encode a string
console.log(Encoding.encodeBase64("hello")) // "aGVsbG8="
// Encode binary data
const bytes = new Uint8Array([72, 101, 108, 108, 111])
console.log(Encoding.encodeBase64(bytes)) // "SGVsbG8="
encodeBase64(const bytes: globalThis.Uint8Array<ArrayBuffer>bytes),
type: stringtype: file: globalThis.Filefile.Blob.type: stringThe type read-only property of the Blob interface returns the MIME type of the file.
type,
name: stringname: file: globalThis.Filefile.File.name: stringThe name read-only property of the File interface returns the name of the file represented by a File object.
name,
lastModified: numberlastModified: file: globalThis.Filefile.File.lastModified: numberThe lastModified read-only property of the File interface provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight).
lastModified
}
},
catch: (
error: unknown
) => SchemaIssue.InvalidValue
catch: (e: unknowne) =>
new import SchemaIssueSchemaIssue.constructor InvalidValue(actual: Option_.Option<unknown>, annotations?: Annotations.Issue | undefined): SchemaIssue.InvalidValueRepresents a schema issue produced when the input has the correct type but its value violates a
constraint (e.g. a string that is too short, a number out of range).
When to use
Use when you need to detect constraint violations from Schema.filter,
Schema.minLength, Schema.greaterThan, or similar checks.
Details
actual is Option.some(value) when the failing value is known, or
Option.none() when absent.
annotations optionally carries a message string for formatting.
- The default formatter renders this as
"Invalid data <actual>" unless a
custom message annotation is provided.
Example (Returning InvalidValue from a custom filter)
import { Option, SchemaIssue } from "effect"
const issue = new SchemaIssue.InvalidValue(
Option.some(""),
{ message: "must not be empty" }
)
console.log(String(issue))
// "must not be empty"
InvalidValue(import Option_Option_.const some: <A>(value: A) => Option<A>Wraps the given value into an Option to represent its presence.
When to use
Use to wrap a known present value as Option
- Returning a successful result from a partial function
Details
- Always returns
Some<A>
- Does not filter
null or undefined; use
fromNullishOr
for that
Example (Wrapping a value)
import { Option } from "effect"
// ┌─── Option<number>
// ▼
const value = Option.some(1)
console.log(value)
// Output: { _id: 'Option', _tag: 'Some', value: 1 }
some(file: globalThis.Filefile), {
Annotations.Issue.message?: string | undefinedmessage: module globalThisglobalThis.var String: StringConstructor
;(value?: any) => string
Allows manipulation and formatting of text strings and determination and location of substrings within strings.
String(e: unknowne)
})
})
})
)
})