Transformation<DateTime.Utc, string, never, never>Decodes a date-time string into a DateTime.Utc and encodes it back to an ISO
string.
When to use
Use when you need a schema transformation to decode date-time strings to a
normalized DateTime.Utc and encode back as a UTC ISO string.
Details
Decode accepts strings supported by DateTime.make, converts the result to
UTC, and fails with InvalidValue when parsing fails. Encode uses
DateTime.formatIso.
export const const dateTimeUtcFromString: Transformation<
DateTime.Utc,
string
>
const dateTimeUtcFromString: {
_tag: 'Transformation';
decode: SchemaGetter.Getter<T, E, RD>;
encode: SchemaGetter.Getter<E, T, RE>;
flip: () => Transformation<string, DateTime.Utc, never, never>;
compose: (other: Transformation<T2, DateTime.Utc, RD2, RE2>) => Transformation<T2, string, RD2, RE2>;
}
Decodes a date-time string into a DateTime.Utc and encodes it back to an ISO
string.
When to use
Use when you need a schema transformation to decode date-time strings to a
normalized DateTime.Utc and encode back as a UTC ISO string.
Details
Decode accepts strings supported by DateTime.make, converts the result to
UTC, and fails with InvalidValue when parsing fails. Encode uses
DateTime.formatIso.
dateTimeUtcFromString: class Transformation<in out T, in out E, RD = never, RE = never>class Transformation {
_tag: 'Transformation';
decode: SchemaGetter.Getter<T, E, RD>;
encode: SchemaGetter.Getter<E, T, RE>;
flip: () => Transformation<E, T, RE, RD>;
compose: <T2, RD2, RE2>(other: Transformation<T2, T, RD2, RE2>) => Transformation<T2, E, RD | RD2, RE | RE2>;
}
Represents a bidirectional transformation between a decoded type T and an encoded
type E, built from a pair of Getters.
When to use
Use when you need a schema transformation that defines how a schema converts
between two representations.
- You want to compose multiple transformations into a pipeline.
- You want to flip a transformation to swap decode/encode.
Details
This is the primary building block for Schema.decodeTo, Schema.encodeTo,
Schema.decode, Schema.encode, and Schema.link. Each direction is a
SchemaGetter.Getter that handles optionality, failure, and Effect services.
- Immutable —
flip() and compose() return new instances.
flip() swaps the decode and encode getters.compose(other) chains: this.decode then other.decode for decoding,
other.encode then this.encode for encoding.
Example (Composing two transformations)
import { SchemaTransformation } from "effect"
const trimAndLower = SchemaTransformation.trim().compose(
SchemaTransformation.toLowerCase()
)
// decode: trim then lowercase
// encode: passthrough (both directions)
Transformation<import DateTimeDateTime.Utc, string> = 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<
import DateTimeDateTime.Utc,
string
>({
decode: (
e: string,
options: SchemaAST.ParseOptions
) => Effect.Effect<
DateTime.Utc,
SchemaIssue.Issue,
never
>
s: strings) => {
return import OptionOption.const match: {
<B, A, C = B>(options: {
readonly onNone: LazyArg<B>
readonly onSome: (a: A) => C
}): (self: Option<A>) => B | C
<A, B, C = B>(
self: Option<A>,
options: {
readonly onNone: LazyArg<B>
readonly onSome: (a: A) => C
}
): B | C
}
import DateTimeDateTime.const make: <A extends DateTime.Input>(
input: A
) => Option.Option<DateTime.PreserveZone<A>>
Creates a DateTime safely from supported input values.
Details
- A
DateTime
- A JavaScript
Date
- The number of milliseconds since the Unix epoch
- An object with date and time parts
- A string that can be parsed as a date
Returns Some with the constructed DateTime when the input is valid, or
None when construction would fail, including invalid Date instances or
unparseable strings.
Example (Creating optional DateTime values)
import { DateTime } from "effect"
// from Date
const fromDate = DateTime.make(new Date("2024-01-01T12:00:00Z"))
console.log(fromDate._tag) // "Some"
// from parts
const fromParts = DateTime.make({ year: 2024 })
console.log(fromParts._tag) // "Some"
// from string
const fromString = DateTime.make("2024-01-01")
console.log(fromString._tag) // "Some"
const invalid = DateTime.make("not a date")
console.log(invalid._tag) // "None"
make(s: strings), {
onNone: LazyArg<
Effect.Effect<
never,
SchemaIssue.InvalidValue,
never
>
>
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 OptionOption.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(s: strings), { Annotations.Issue.message?: string | undefinedmessage: `Invalid UTC DateTime string: ${s: strings}` })),
onSome: (
a: DateTime.Utc
) => Effect.Effect<DateTime.Utc, never, never>
result: DateTime.Utc(parameter) result: {
_tag: "Utc";
epochMilliseconds: number;
partsUtc: DateTime.PartsWithWeekday | undefined;
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;
}
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(import DateTimeDateTime.const toUtc: (self: DateTime) => UtcConverts a DateTime to a UTC DateTime.
When to use
Use to represent the same instant in UTC instead of its current time zone.
Details
The returned value keeps the same epoch milliseconds and changes only the
DateTime representation to UTC.
Example (Converting DateTime values to UTC)
import { DateTime } from "effect"
const now = DateTime.makeZonedUnsafe({ year: 2024 }, {
timeZone: "Europe/London"
})
// set as UTC
const utc: DateTime.Utc = DateTime.toUtc(now)
toUtc(result: DateTime.Utc(parameter) result: {
_tag: "Utc";
epochMilliseconds: number;
partsUtc: DateTime.PartsWithWeekday | undefined;
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;
}
encode: (
t: DateTime.Utc,
options: SchemaAST.ParseOptions
) => Effect.Effect<
string,
SchemaIssue.Issue,
never
>
utc: DateTime.Utc(parameter) utc: {
_tag: "Utc";
epochMilliseconds: number;
partsUtc: DateTime.PartsWithWeekday | undefined;
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;
}
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(import DateTimeDateTime.const formatIso: (
self: DateTime
) => string
Formats a DateTime as a UTC ISO string.
Details
Always returns the UTC representation in ISO 8601 format, ignoring any time zone.
Example (Formatting DateTime values as ISO strings)
import { DateTime } from "effect"
const dt = DateTime.makeUnsafe("2024-01-01T12:30:45.123Z")
console.log(DateTime.formatIso(dt)) // "2024-01-01T12:30:45.123Z"
const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:30:45.123Z", {
timeZone: "Europe/London"
})
console.log(DateTime.formatIso(zoned)) // "2024-01-01T12:30:45.123Z"
formatIso(utc: DateTime.Utc(parameter) utc: {
_tag: "Utc";
epochMilliseconds: number;
partsUtc: DateTime.PartsWithWeekday | undefined;
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;
}