DateTimeZonedType-level representation of DateTimeZoned.
export interface DateTimeZoned extends interface declare<T, Iso = T>Creates a schema for a non-parametric opaque type using a type-guard
function. The schema accepts any unknown value and succeeds when is returns
true, failing with an InvalidType issue otherwise.
When to use
Use when you are defining a schema for an opaque type with no type parameters
and validation can be expressed as a type guard.
Example (Defining a schema for a custom UserId branded type)
import { Schema } from "effect"
type UserId = string & { readonly _tag: "UserId" }
const isUserId = (u: unknown): u is UserId =>
typeof u === "string" && u.startsWith("user_")
const UserId = Schema.declare<UserId>(isUserId, {
title: "UserId",
description: "A user identifier starting with 'user_'"
})
Type-level representation returned by
declare
.
declare<import DateTimeDateTime.Zoned> {
readonly "Rebuild": DateTimeZoned
}
const const DateTimeZonedString: Stringconst DateTimeZonedString: {
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; <…;
}
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">.annotate(annotations: Annotations.Bottom<string, readonly []>): Stringannotate({
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: "a zoned DateTime string (e.g. 2024-01-01T00:00:00.000+00:00[Europe/London])"
})
/**
* Schema for `DateTime.Zoned` values.
*
* **Details**
*
* Default JSON serializer:
*
* - encodes offset zones as an ISO date-time with a numeric offset, such as
* `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`
* - encodes named zones by appending the IANA identifier in brackets, such as
* `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`
*
* @category DateTime
* @since 3.10.0
*/
export const const DateTimeZoned: DateTimeZonedconst DateTimeZoned: {
Rebuild: DateTimeZoned;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<DateTime.Zoned, readonly []>) => DateTimeZoned;
annotateKey: (annotations: Annotations.Key<DateTime.Zoned>) => DateTimeZoned;
check: (checks_0: SchemaAST.Check<DateTime.Zoned>, ...checks: Array<SchemaAST.Check<DateTime.Zoned>>) => DateTimeZoned;
rebuild: (ast: SchemaAST.Declaration) => DateTimeZoned;
make: (input: DateTime.Zoned, options?: MakeOptions) => DateTime.Zoned;
makeOption: (input: DateTime.Zoned, options?: MakeOptions) => Option_.Option<DateTime.Zoned>;
makeEffect: (input: DateTime.Zoned, options?: MakeOptions) => Effect.Effect<DateTime.Zoned, 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
DateTimeZoned
.
Schema for DateTime.Zoned values.
Details
Default JSON serializer:
- encodes offset zones as an ISO date-time with a numeric offset, such as
YYYY-MM-DDTHH:mm:ss.sss+HH:MM
- encodes named zones by appending the IANA identifier in brackets, such as
YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]
DateTimeZoned: DateTimeZoned = function declare<T, Iso = T>(
is: (u: unknown) => u is T,
annotations?:
| Annotations.Declaration<T>
| undefined
): declare<T, Iso>
Creates a schema for a non-parametric opaque type using a type-guard
function. The schema accepts any unknown value and succeeds when is returns
true, failing with an InvalidType issue otherwise.
When to use
Use when you are defining a schema for an opaque type with no type parameters
and validation can be expressed as a type guard.
Example (Defining a schema for a custom UserId branded type)
import { Schema } from "effect"
type UserId = string & { readonly _tag: "UserId" }
const isUserId = (u: unknown): u is UserId =>
typeof u === "string" && u.startsWith("user_")
const UserId = Schema.declare<UserId>(isUserId, {
title: "UserId",
description: "A user identifier starting with 'user_'"
})
declare(
(u: unknownu) => import DateTimeDateTime.const isDateTime: (
u: unknown
) => u is DateTime
Checks whether a value is a DateTime.
When to use
Use to narrow an unknown value before treating it as a DateTime.
isDateTime(u: unknownu) && import DateTimeDateTime.const isZoned: (
self: DateTime
) => self is Zoned
Checks whether a DateTime is a zoned DateTime (has time zone information).
When to use
Use to narrow a known DateTime before reading its zone or passing it to
APIs that require DateTime.Zoned.
isZoned(u: DateTime.DateTimeu),
{
Annotations.Declaration<Zoned, readonly []>.typeConstructor?: {
readonly [key: string]: unknown;
readonly _tag: string;
} | undefined
_tag: string_tag: "effect/DateTime.Zoned"
},
Annotations.Declaration<Zoned, readonly []>.generation?: {
readonly runtime: string;
readonly Type: string;
readonly Encoded?: string | undefined;
readonly importDeclaration?: string | undefined;
} | undefined
runtime: stringruntime: `Schema.DateTimeZoned`,
type Type: stringType: `DateTime.Zoned`,
importDeclaration?: string | undefinedimportDeclaration: `import * as DateTime from "effect/DateTime"`
},
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: "DateTime.Zoned",
Annotations.Declaration<Zoned, 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<import DateTimeDateTime.Zoned>()(
const DateTimeZonedString: Stringconst DateTimeZonedString: {
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; <…;
}
import SchemaTransformationSchemaTransformation.const dateTimeZonedFromString: Transformation<
DateTime.Zoned,
string
>
const dateTimeZonedFromString: {
_tag: 'Transformation';
decode: SchemaGetter.Getter<T, E, RD>;
encode: SchemaGetter.Getter<E, T, RE>;
flip: () => SchemaTransformation.Transformation<string, DateTime.Zoned, never, never>;
compose: (other: SchemaTransformation.Transformation<T2, DateTime.Zoned, RD2, RE2>) => SchemaTransformation.Transformation<T2, string, RD2, RE2>;
}
Decodes a zoned date-time string into a DateTime.Zoned and encodes it back
to an ISO zoned string.
When to use
Use when you need a schema transformation for ISO zoned date-time strings
that decode to DateTime.Zoned and encode with DateTime.formatIsoZoned.
Details
Decode uses DateTime.makeZonedFromString and fails with InvalidValue when
the input is not a valid zoned date-time. Encode uses
DateTime.formatIsoZoned.
dateTimeZonedFromString
),
Annotations.Declaration<Zoned, readonly []>.toArbitrary?: Annotations.ToArbitrary.Declaration<DateTime.Zoned, readonly []> | undefinedtoArbitrary: () => (fc: typeof FastCheckfc, ctx: Annotations.ToArbitrary.Context(parameter) ctx: {
constraint: ToArbitrary.GenerationConstraint | undefined;
recursion: ToArbitrary.Recursion | undefined;
}
fc: typeof FastCheckfc.tuple(
fc: typeof FastCheckfc.date(function dateArbitraryConstraints<DateTime.DateTime>(constraint: Annotations.ToArbitrary.GenerationConstraint | undefined, ordered: Annotations.ToArbitrary.OrderedConstraint<DateTime.DateTime> | undefined, base?: DateArbitraryConstraints | undefined, toDate?: ((value: DateTime.DateTime) => globalThis.Date) | undefined): FastCheck.DateConstraintsdateArbitraryConstraints(
ctx: Annotations.ToArbitrary.Context(parameter) ctx: {
constraint: ToArbitrary.GenerationConstraint | undefined;
recursion: ToArbitrary.Recursion | undefined;
}
Annotations.ToArbitrary.Context.constraint?: Annotations.ToArbitrary.GenerationConstraint | undefinedconstraint,
ctx: Annotations.ToArbitrary.Context(parameter) ctx: {
constraint: ToArbitrary.GenerationConstraint | undefined;
recursion: ToArbitrary.Recursion | undefined;
}
Annotations.ToArbitrary.Context.constraint?: Annotations.ToArbitrary.GenerationConstraint | undefinedconstraint?.Annotations.ToArbitrary.GenerationConstraint.ordered?: Annotations.ToArbitrary.OrderedConstraint<any> | undefinedordered?.Annotations.ToArbitrary.OrderedConstraint<any>.order: Order.Order<T>order === import DateTimeDateTime.const Order: order.Order<DateTime>Provides an Order for comparing and sorting DateTime values.
Details
DateTime values are ordered by their epoch milliseconds, so earlier times
come before later times regardless of time zone.
Example (Sorting DateTime values chronologically)
import { Array, DateTime } from "effect"
const dates = [
DateTime.makeUnsafe("2024-03-01"),
DateTime.makeUnsafe("2024-01-01"),
DateTime.makeUnsafe("2024-02-01")
]
const sorted = Array.sort(dates, DateTime.Order)
// Results in chronological order: 2024-01-01, 2024-02-01, 2024-03-01
Order ? ctx: Annotations.ToArbitrary.Context(parameter) ctx: {
constraint: ToArbitrary.GenerationConstraint | undefined;
recursion: ToArbitrary.Recursion | undefined;
}
Annotations.ToArbitrary.Context.constraint?: Annotations.ToArbitrary.GenerationConstraint(property) Annotations.ToArbitrary.Context.constraint?: {
minLength: number | undefined;
maxLength: number | undefined;
patterns: readonly [string, ...Array<string>];
integer: boolean | undefined;
noInfinity: boolean | undefined;
noNaN: boolean | undefined;
valid: boolean | undefined;
unique: boolean | undefined;
ordered: OrderedConstraint<any> | undefined;
}
Annotations.ToArbitrary.GenerationConstraint.ordered?: Annotations.ToArbitrary.OrderedConstraint<any>(property) Annotations.ToArbitrary.GenerationConstraint.ordered?: {
order: Order.Order<T>;
minimum: T | undefined;
exclusiveMinimum: boolean | undefined;
maximum: T | undefined;
exclusiveMaximum: boolean | undefined;
}
var undefinedundefined,
{
max: globalThis.Datemax: new module globalThisglobalThis.var Date: DateConstructor
new (value: number | string | globalThis.Date) => globalThis.Date (+4 overloads)
min: globalThis.Datemin: new module globalThisglobalThis.var Date: DateConstructor
new (value: number | string | globalThis.Date) => globalThis.Date (+4 overloads)
valid: booleanvalid: true
},
import DateTimeDateTime.const toDateUtc: (self: DateTime) => DateGets the UTC Date of a DateTime.
Details
This always returns the UTC representation, ignoring any time zone information.
Example (Converting DateTime values to UTC Dates)
import { DateTime } from "effect"
const dt = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
timeZone: "Europe/London"
})
const utcDate = DateTime.toDateUtc(dt)
console.log(utcDate.toISOString()) // "2024-01-01T12:00:00.000Z"
toDateUtc
)),
fc: typeof FastCheckfc.constantFrom("UTC", "Europe/London", "America/New_York", "Asia/Tokyo", "Australia/Sydney")
).map(([date: anydate, zone: anyzone]) => import DateTimeDateTime.const makeZonedUnsafe: (
input: DateTime.Input,
options?: {
readonly timeZone?:
| number
| string
| TimeZone
| undefined
readonly adjustForTimeZone?:
| boolean
| undefined
readonly disambiguation?:
| Disambiguation
| undefined
}
) => Zoned
Create a DateTime.Zoned using DateTime.makeUnsafe and a time zone.
When to use
Use when the date/time input and zone options are trusted and invalid or
rejected ambiguous times should throw instead of returning Option.none.
Details
The input is treated as UTC and then the time zone is attached, unless
adjustForTimeZone is set to true. In that case, the input is treated as
already in the time zone.
When adjustForTimeZone is true and ambiguous times occur during DST transitions,
the disambiguation option controls how to resolve the ambiguity:
compatible (default): Choose earlier time for repeated times, later for gapsearlier: Always choose the earlier of two possible timeslater: Always choose the later of two possible timesreject: Throw an error when ambiguous times are encountered
Example (Creating zoned DateTime values unsafely)
import { DateTime } from "effect"
const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:00Z", {
timeZone: "Europe/London"
})
console.log(DateTime.formatIsoZoned(zoned)) // "2024-06-15T15:30:00.000+01:00[Europe/London]"
makeZonedUnsafe(date: anydate, { timeZone?: | string
| number
| DateTime.TimeZone
| undefined
zone: anyzone })),
Annotations.Declaration<Zoned, readonly []>.toFormatter?: Annotations.ToFormatter.Declaration<DateTime.Zoned, readonly []> | undefinedtoFormatter: () => (zoned: DateTime.Zoned(parameter) zoned: {
_tag: "Zoned";
epochMilliseconds: number;
zone: TimeZone;
adjustedEpochMilliseconds: number | undefined;
partsAdjusted: DateTime.PartsWithWeekday | undefined;
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 DateTimeDateTime.const formatIsoZoned: (
self: Zoned
) => string
Formats a DateTime.Zoned as a string.
Details
It uses the format: YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone].
Example (Formatting zoned DateTime values)
import { DateTime } from "effect"
const zoned = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
timeZone: "Europe/London"
})
const formatted = DateTime.formatIsoZoned(zoned)
console.log(formatted) // "2024-06-15T15:30:45.123+01:00[Europe/London]"
const offsetZone = DateTime.makeZonedUnsafe("2024-06-15T14:30:45.123Z", {
timeZone: DateTime.zoneMakeOffset(3 * 60 * 60 * 1000)
})
const offsetFormatted = DateTime.formatIsoZoned(offsetZone)
console.log(offsetFormatted) // "2024-06-15T17:30:45.123+03:00"
formatIsoZoned(zoned: DateTime.Zoned(parameter) zoned: {
_tag: "Zoned";
epochMilliseconds: number;
zone: TimeZone;
adjustedEpochMilliseconds: number | undefined;
partsAdjusted: DateTime.PartsWithWeekday | undefined;
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;
}
Annotations.Declaration<Zoned, readonly []>.toEquivalence?: Annotations.ToEquivalence.Declaration<DateTime.Zoned, readonly []> | undefinedtoEquivalence: () => import DateTimeDateTime.const Equivalence: Equ.Equivalence<DateTime>Provides an Equivalence for comparing two DateTime values for equality.
Details
Two DateTime values are considered equivalent if they represent the same
point in time, regardless of their time zone.
Example (Comparing DateTime values for equivalence)
import { DateTime } from "effect"
const utc = DateTime.makeUnsafe("2024-01-01T12:00:00Z")
const zoned = DateTime.makeZonedUnsafe("2024-01-01T12:00:00Z", {
timeZone: "Europe/London"
})
console.log(DateTime.Equivalence(utc, zoned)) // true
Equivalence
}
)