DateTimeUtcType-level representation of DateTimeUtc.
export interface DateTimeUtc 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.Utc> {
readonly "Rebuild": DateTimeUtc
}
/**
* Schema for `DateTime.Utc` values.
*
* **When to use**
*
* Use to validate existing `DateTime.Utc` schema values and use the default JSON
* codec that represents them as UTC ISO strings.
*
* **Details**
*
* The default JSON codec decodes UTC ISO strings into `DateTime.Utc` values and
* encodes `DateTime.Utc` values as UTC ISO strings.
*
* @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
* @see {@link DateTimeUtcFromDate} for decoding JavaScript Date values into UTC values
* @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
* @see {@link DateTimeZoned} for preserving zoned DateTime values
*
* @category DateTime
* @since 3.10.0
*/
export const const DateTimeUtc: DateTimeUtcconst DateTimeUtc: {
Rebuild: DateTimeUtc;
Iso: Iso;
ast: Ast;
Type: T;
Encoded: E;
DecodingServices: RD;
EncodingServices: RE;
annotate: (annotations: Annotations.Bottom<DateTime.Utc, readonly []>) => DateTimeUtc;
annotateKey: (annotations: Annotations.Key<DateTime.Utc>) => DateTimeUtc;
check: (checks_0: SchemaAST.Check<DateTime.Utc>, ...checks: Array<SchemaAST.Check<DateTime.Utc>>) => DateTimeUtc;
rebuild: (ast: SchemaAST.Declaration) => DateTimeUtc;
make: (input: DateTime.Utc, options?: MakeOptions) => DateTime.Utc;
makeOption: (input: DateTime.Utc, options?: MakeOptions) => Option_.Option<DateTime.Utc>;
makeEffect: (input: DateTime.Utc, options?: MakeOptions) => Effect.Effect<DateTime.Utc, 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
DateTimeUtc
.
Schema for DateTime.Utc values.
When to use
Use to validate existing DateTime.Utc schema values and use the default JSON
codec that represents them as UTC ISO strings.
Details
The default JSON codec decodes UTC ISO strings into DateTime.Utc values and
encodes DateTime.Utc values as UTC ISO strings.
DateTimeUtc: DateTimeUtc = 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 isUtc: (
self: DateTime
) => self is Utc
Checks whether a DateTime is a UTC DateTime (no time zone information).
When to use
Use to narrow a DateTime before passing it to code that requires a UTC
value without an associated time zone.
isUtc(u: DateTime.DateTimeu),
{
Annotations.Declaration<Utc, readonly []>.typeConstructor?: {
readonly [key: string]: unknown;
readonly _tag: string;
} | undefined
_tag: string_tag: "effect/DateTime.Utc"
},
Annotations.Declaration<Utc, readonly []>.generation?: {
readonly runtime: string;
readonly Type: string;
readonly Encoded?: string | undefined;
readonly importDeclaration?: string | undefined;
} | undefined
runtime: stringruntime: `Schema.DateTimeUtc`,
type Type: stringType: `DateTime.Utc`,
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.Utc",
Annotations.Declaration<Utc, 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.Utc>()(
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,
import SchemaTransformationSchemaTransformation.const dateTimeUtcFromString: Transformation<
DateTime.Utc,
string
>
const dateTimeUtcFromString: {
_tag: 'Transformation';
decode: SchemaGetter.Getter<T, E, RD>;
encode: SchemaGetter.Getter<E, T, RE>;
flip: () => SchemaTransformation.Transformation<string, DateTime.Utc, never, never>;
compose: (other: SchemaTransformation.Transformation<T2, DateTime.Utc, RD2, RE2>) => SchemaTransformation.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
),
Annotations.Declaration<Utc, readonly []>.toArbitrary?: Annotations.ToArbitrary.Declaration<DateTime.Utc, readonly []> | undefinedtoArbitrary: () => (fc: typeof FastCheckfc, ctx: Annotations.ToArbitrary.Context(parameter) ctx: {
constraint: ToArbitrary.GenerationConstraint | undefined;
recursion: ToArbitrary.Recursion | undefined;
}
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,
{ 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
))
.map((date: anydate) => import DateTimeDateTime.const fromDateUnsafe: (date: Date) => UtcCreate a DateTime from a Date.
Details
If the Date is invalid, an IllegalArgumentError will be thrown.
Example (Creating DateTime values from Dates)
import { DateTime } from "effect"
const date = new Date("2024-01-01T12:00:00Z")
const dateTime = DateTime.fromDateUnsafe(date)
console.log(DateTime.formatIso(dateTime)) // "2024-01-01T12:00:00.000Z"
fromDateUnsafe(date: anydate)),
Annotations.Declaration<Utc, readonly []>.toFormatter?: Annotations.ToFormatter.Declaration<DateTime.Utc, readonly []> | undefinedtoFormatter: () => (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;
}
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;
}
Inspectable.toString(): stringtoString(),
Annotations.Declaration<Utc, readonly []>.toEquivalence?: Annotations.ToEquivalence.Declaration<DateTime.Utc, 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
}
)