DateTimeType

class DateTimeType extends Type 📜

DATETIME type.

This represents a "date time", a date with a time in the underlying database.

Client-side storage for this field will be backed by a Luxon DateTime instance.

You can optionally provide a format argument when constructing this type. This is a client-side format only. It doesn't specify the format for storing the value in the database. Instead it is used to parse provided date strings, and when serializing the field (for example via Model.toJSON).

Example:

• class DatesWithTimes extends Model {
    static fields = {
      dateTime1: Types.DATETIME('yyyy-MM-dd HH:mm:ss'),
      dateTime2: new Types.DateTimeType(),
    };
  }

Notes:

• A BigInt timestamp is used to store the date and time in the underlying database.

See also: Type

property DateTimeType::Default: object = { NOW } 📜

NOW is a method that can be used as the defaultValue of a Field to have this field use "NOW" time. There are a number of different ways to use this defaultValue method. If you use just Types.DATETIME.Default.NOW, then it will use the underlying databases 'NOW' function, setting the field to remote database time. Available also are the following:
1. Types.DATETIME.Default.NOW = Remote database 'NOW' time, set on insert only.
2. Types.DATETIME.Default.NOW.UPDATE = Remote database 'NOW' time, set on insert and update.
3. Types.DATETIME.Default.NOW.LOCAL = Local (client-side) 'NOW' time, set on insert only.
4. Types.DATETIME.Default.NOW.LOCAL.UPDATE = Local (client-side) 'NOW' time, set on insert and update.
Note: It is highly recommended that you do not use LOCAL time unless you know exactly what you are doing, as clock-drift between machines may become an issue.

method DateTimeType::castToType(
    context: CastToTypeContext,
): DateTime | null | undefined 📜

Cast provided value to underlying type.

This will cast the incoming value to the underlying type of this field, a Luxon DateTime instance. If the provided value results in an invalid date, then an exception will be thrown.

See Type.castToType for a more detailed description.

Arguments:

• context: CastToTypeContext

Return value: DateTime | null | undefined

Return the incoming value, cast to this type. null and undefined are simply returned without casting.

method DateTimeType::constructor(
    format?: string,
    length?: number,
): DateTimeType 📜

Construct a new DATETIME type.

The format argument will specify the date format for this field. See the Luxon DateTime docs for a reference on this format.

This format is not the format that will be used to store the DATETIME field in the database. Instead, this is a client-side only format, to define how to parse provided date strings, and to format on serialize when calling Model.toJSON.

The length argument is used by some database drivers to modify the precision of the underlying timestamp/datetime value.

Arguments:

• format?: string

  Specify the client-side formatting for this date field. This will be used for parsing date strings, and for serializing the field.

• length?: number

  Used by some database drivers to specify the precision of the time when stored in the database.

Return value: DateTimeType

method DateTimeType::deserialize(
    value: DateTime | Date | string | number | BigInt | null | undefined,
    connection?: Connection,
): DateTime 📜

Deserialize the field value.

This method is used to deserialize a provided field value. If the value provided is a DateTime instance, then simply return it. Otherwise, if a string is provided, convert it to a DateTime instance, using the format provided (if any).

The connection argument is not used by this method, but is provided if the user wishes to overload this method.

If null or undefined are provided as a value then that value will simply be returned as-is.

Notes:

• This method is called by castToType to cast incoming values into DateTime instances.

Arguments:

• value: DateTime | Date | string | number | BigInt | null | undefined

  The value to deserialize.

• connection?: Connection

  An optional connection that might be provided depending on how and where this method is called from. This method does nothing with the connection. It is simply provided for if the user wishes to overload this method.

Return value: DateTime

method DateTimeType::isValidValue(
    value: any,
): boolean 📜

Check if the provided value is valid.

This will check if the provided value is a valid date. It does so by calling DateTime.isValid. If this check results in true, then this method will return true, otherwise it will return false.

See the Luxon DateTime library documentation for more information.

Arguments:

• value: any

  The value to check.

Return value: boolean

method DateTimeType::serialize(
    value: DateTime,
    connection?: Connection,
): string | null | undefined 📜

Serialize the field value.

This will be called whenever the field's value needs to be serialized. If a connection argument is provided, then this method will assume that the connection is serializing it for storage in the database. In this case, Connection.convertDateToDBTime is called and provided the value for the connection to turn the date into a proper value for the underlying database.

If no connection is provided, then the date will be serialized according to the provided format specified by the user. If no format was specified by the user, then it will be serialized to ISO 8601 format.

Arguments:

• value: DateTime

  The date value to serialize.

• connection?: Connection

  A connection instance, which if provided, will proxy serialization to the underlying database connection via the Connection.convertDateToDBTime method.

Return value: string | null | undefined

static method DateTimeType::getDisplayName(): string 📜

Get the "display" name for this type.

This method is called from Model.toString when stringifying the model for representation.

Notes:

• This is also an instance method that can be called from an instance of the type.

Return value: string

Return the string value 'DATETIME'

method DateTimeType::toString(
    connection?: Connection,
): string 📜

Stringify the type itself.

If a connection argument is provided, then this will go through the connection to generate the type for the underlying database. If no connection is provided, then a "standard" SQL type will be returned for this type instead. The "standard" type returned when no connection is provided is 'TIMESTAMP'.

Arguments:

• connection?: Connection

  An optional connection. If provided, send this type through Type.toConnectionType to have the connection itself generate the underlying type for the database. If connection is not provided, then this will simply return a "standard" generic matching SQL type.

Return value: string