<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E>Parses a DateTime.Input value into a DateTime.Utc.
When to use
Use when you need a schema getter to decode a present encoded date/time value
to a DateTime.Utc.
Details
- Accepted input includes existing
DateTimevalues, partial date/time parts, instant objects, zoned instant objects, JavaScriptDateinstances, epoch milliseconds, and date strings. - Converts successfully parsed values to UTC.
- Fails with
SchemaIssue.InvalidValueif the input cannot be parsed as a validDateTime.
Example (Parsing DateTime)
import { SchemaGetter } from "effect"
const parseDate = SchemaGetter.dateTimeUtcFromInput<string>()
// Getter<DateTime.Utc, string>export function function dateTimeUtcFromInput<
E extends DateTime.DateTime.Input
>(): Getter<DateTime.Utc, E>
Parses a DateTime.Input value into a DateTime.Utc.
When to use
Use when you need a schema getter to decode a present encoded date/time value
to a DateTime.Utc.
Details
- Accepted input includes existing
DateTime values, partial date/time parts,
instant objects, zoned instant objects, JavaScript Date instances, epoch
milliseconds, and date strings.
- Converts successfully parsed values to UTC.
- Fails with
SchemaIssue.InvalidValue if the input cannot be parsed as a valid
DateTime.
Example (Parsing DateTime)
import { SchemaGetter } from "effect"
const parseDate = SchemaGetter.dateTimeUtcFromInput<string>()
// Getter<DateTime.Utc, string>
dateTimeUtcFromInput<function (type parameter) E in dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E>E extends import DateTimeDateTime.DateTime.type DateTime.Input = string | number | Date | DateTime.DateTime | Partial<DateTime.DateTime.Parts> | DateTime.DateTime.Instant | DateTime.DateTime.InstantWithZoneInput accepted by DateTime.make, DateTime.makeUnsafe, and the zoned
constructors.
Details
Includes existing DateTime values, partial date parts, epoch-millisecond
objects, epoch milliseconds, JavaScript Date instances, and parseable date
strings.
Input>(): class Getter<out T, in E, R = never>class Getter {
run: (input: Option.Option<E>, options: SchemaAST.ParseOptions) => Effect.Effect<Option.Option<T>, SchemaIssue.Issue, R>;
map: <T2>(f: (t: T) => T2) => Getter<T2, E, R>;
compose: <T2, R2>(other: Getter<T2, T, R2>) => Getter<T2, E, R | R2>;
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; <…;
}
Represents a composable transformation from an encoded type E to a decoded type T.
When to use
Use when you need a schema getter to build and compose custom transformations
for Schema.decodeTo or Schema.decode.
Details
A getter wraps a function Option<E> -> Effect<Option<T>, Issue, R>. It
receives Option.None when the encoded key is absent, such as a missing
struct field, and returns Option.None to omit the value from the decoded
output. It fails with Issue on invalid input and may require Effect
services via R. .map(f) applies f to the decoded value inside Some
while leaving None unchanged. .compose(other) chains two getters by
feeding the output of this into other; passthrough getters on either side
are optimized away.
Example (Creating and composing getters)
import { SchemaGetter } from "effect"
const parseNumber = SchemaGetter.transform<number, string>((s) => Number(s))
const double = SchemaGetter.transform<number, number>((n) => n * 2)
const composed = parseNumber.compose(double)
// composed: Getter<number, string> — parses then doubles
Getter<import DateTimeDateTime.Utc, function (type parameter) E in dateTimeUtcFromInput<E extends DateTime.DateTime.Input>(): Getter<DateTime.Utc, E>E> {
return function transformOrFail<T, E, R = never>(
f: (
e: E,
options: SchemaAST.ParseOptions
) => Effect.Effect<T, SchemaIssue.Issue, R>
): Getter<T, E, R>
Creates a getter that applies a fallible, effectful transformation to present values.
When to use
Use when you need a schema getter for a transformation that may fail, require
Effect services, or run asynchronously.
Details
- Skips
None inputs — only called when a value is present.
- On success, wraps the result in
Some.
- On failure, propagates the
Issue.
Example (Parsing with failure)
import { Effect, Option, SchemaGetter, SchemaIssue } from "effect"
const safeParseInt = SchemaGetter.transformOrFail<number, string>(
(s) => {
const n = parseInt(s, 10)
return isNaN(n)
? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "not an integer" }))
: Effect.succeed(n)
}
)
transformOrFail((input: E extends DateTime.DateTime.Inputinput) => {
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(input: E extends DateTime.DateTime.Inputinput), {
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?: Schema.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(input: E extends DateTime.DateTime.Inputinput), { Annotations.Issue.message?: string | undefinedmessage: "Invalid DateTime input" })),
onSome: (
a: DateTime.DateTime.PreserveZone<E>
) => Effect.Effect<DateTime.Utc, never, never>
dt: DateTime.DateTime.PreserveZone<E>dt) => 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(dt: DateTime.DateTimedt))
})
})
}