datetime: add module definition

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarantoolscript",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "author": "Vitaliy Artemov [email protected]",
   "description": "TypeScript definitions for Tarantool Lua API.",
   "repository": {

src/builtin/datetime/DateTime.d.ts

@@ -0,0 +1,14 @@
+/** @noSelfInFile */
+
+import { DateTimeObject } from './DateTimeObject';
+import { DateTimeUnits } from './DateTimeUnits';
+import { IntervalObject } from './IntervalObject';
+import { IntervalUnits } from './IntervalUnits';
+
+/** @customName new */
+export declare function new_(units?: DateTimeUnits): DateTimeObject;
+
+export declare const interval: {
+  /** @customName new */
+  new_(this: void, units?: IntervalUnits): IntervalObject;
+};

src/builtin/datetime/DateTimeObject.d.ts

@@ -0,0 +1,59 @@
+import { DateTimeTable } from './DateTimeTable';
+import { DateTimeUnits } from './DateTimeUnits';
+import { IntervalObject } from './IntervalObject';
+
+export interface DateTimeObject extends DateTimeTable {
+  /**
+   * Convert the information from a datetime object into the table format.
+   * @returns Table with the date and time parameters.
+   */
+  totable(): DateTimeTable;
+
+  /**
+   * Convert the standard `datetime` object presentation into a formatted string.
+   * The conversion specifications are the same as in the strftime library.
+   * Additional specification for nanoseconds is `%f` which also allows a modifier to control the output precision of fractional part:
+   * `%5f`. If no arguments are set for the method, the default conversions are used: `'%FT%T.%f%z'`.
+   * @param input String consisting of zero or more conversion specifications and ordinary characters.
+   * @returns String with the formatted date and time information.
+   */
+  format(input?: string): string;
+
+  /**
+   * Update the field values in the existing `datetime` object.
+   * @param units Table of time units. The time units are the same as for the `datetime.new()`.
+   * @returns Updated `datetime` object
+   */
+  set(units?: DateTimeUnits): DateTimeObject;
+
+  /**
+   * Convert an input string with the date and time information into a `datetime` object.
+   * The input string should be formatted according to one of the following standards:
+   * - ISO 8601
+   * - RFC 3339
+   * - extended strftime – see description of the `format()` for details.
+   * @param input String with the date and time information.
+   * @param opts Format options:
+   * - format - indicator of the `input` format. Possible values: ‘iso8601’, ‘rfc3339’, or strptime-like format string.
+   * If no value is set, the default formatting is used.
+   * - tzoffset - Time zone offset from UTC, in minutes.
+   * @returns A `datetime` object.
+   */
+  parse(input?: string, opts?: { format?: string, tzoffset?: number }): DateTimeObject;
+
+  /**
+   * Modify an existing datetime object by adding values of the input argument.
+   * @param input An interval object or an equivalent table.
+   * @param opts Operation options:
+   * - adjust - Defines how to round days in a month after an arithmetic operation. Possible values: `none`, `last`, `excess`. Defaults to `none`.
+   */
+  add(input: IntervalObject, opts?: { adjust?: 'none' | 'last' | 'excess' }): DateTimeObject;
+
+  /**
+   * Modify an existing datetime object by subtracting values of the input argument.
+   * @param input An interval object or an equivalent table.
+   * @param opts Operation options:
+   * - adjust - Defines how to round days in a month after an arithmetic operation. Possible values: `none`, `last`, `excess`. Defaults to `none`.
+   */
+  sub(input: IntervalObject, opts?: { adjust?: 'none' | 'last' | 'excess' }): DateTimeObject;
+}

src/builtin/datetime/DateTimeTable.d.ts

@@ -0,0 +1,56 @@
+export interface DateTimeTable {
+  /**
+   * Nanosecods.
+   */
+  nsec: number;
+
+  /**
+   * Seconds
+   */
+  sec: number;
+
+  /**
+   * Minutes.
+   */
+  min: number;
+
+  /**
+   * Hours.
+   */
+  hour: number;
+
+  /**
+   * Day number.
+   */
+  day: number;
+
+  /**
+   * Month number;
+   */
+  month: number;
+
+  /**
+   * Year.
+   */
+  year: number;
+
+  /**
+   * Days since the beginning of the week.
+   */
+  wday: number;
+
+  /**
+   * Days since the beginning of the year.
+   */
+  yday: number;
+
+  /**
+   * Is the DST(Daylight saving time) applicable for the date.
+   */
+  isdst: boolean;
+
+  /**
+   * Time zone offset from UTC.
+   */
+  tzoffset: number;
+}

src/builtin/datetime/DateTimeUnits.d.ts

@@ -0,0 +1,82 @@
+export interface DateTimeUnits {
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  nsec?: number;
+
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  usec?: number;
+
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  msec?: number;
+
+  /**
+   * Seconds. Value range: 0 - 60.
+   * @default 0
+   */
+  sec?: number;
+
+  /**
+   * Minutes. Value range: 0 - 59.
+   * @default 0
+   */
+  min?: number;
+
+  /**
+   * Hours. Value range: 0 - 23.
+   * @default 0
+   */
+  hour?: number;
+
+  /**
+   * Day number. Value range: 1 - 31. The special value `-1` generates the last day of a particular month.
+   * @default 1
+   */
+  day?: number;
+
+  /**
+   * Month number. Value range: 1 - 12.
+   * @default 1
+   */
+  month?: number;
+
+  /**
+   * Year.
+   * @default 1970
+   */
+  year?: number;
+
+  /**
+   * Timestamp, in seconds.
+   * Similar to the Unix timestamp, but can have a fractional part which is converted in nanoseconds in the resulting `datetime` object.
+   * If the fractional part for the last second is set via the `nsec`, `usec`, or `msec` units,
+   * the timestamp value should be integer otherwise an error occurs.
+   * Timestamp is not allowed if you already set time and/or date via specific units, namely, `sec`, `min`, `hour`, `day`, `month`, and `year`.
+   * @default 0
+   */
+  timestamp?: number;
+
+  /**
+   * Time zone offset from UTC, in minutes. If both `tzoffset` and `tz` are specified, `tz` has the preference and the `tzoffset` value is ignored.
+   * @default 0
+   */
+  tzoffset?: number;
+
+  /**
+   * Time zone name according to the tz database.
+   */
+  tz?: string;
+}

src/builtin/datetime/IntervalObject.d.ts

@@ -0,0 +1,7 @@
+import { IntervalTable } from './IntervalTable';
+
+export interface IntervalObject extends IntervalTable {
+  adjust: number;
+
+  totable(): IntervalTable;
+}

src/builtin/datetime/IntervalTable.d.ts

@@ -0,0 +1,46 @@
+export interface IntervalTable {
+  /**
+   * Nanoseconds.
+   */
+  nsec: number;
+
+  /**
+   * Seconds.
+   */
+  sec: number;
+
+  /**
+   * Minutes.
+   */
+  min: number;
+
+  /**
+   * Hours.
+   */
+  hour: number;
+
+  /**
+   * Day number.
+   */
+  day: number;
+
+  /**
+   * Month number.
+   */
+  month: number;
+
+  /**
+   * Year.
+   */
+  year: number;
+
+  /**
+   * Week number.
+   */
+  week: number;
+
+  /**
+   * Defines how to round days in a month after an arithmetic operation.
+   */
+  adjust: 'none' | 'last' | 'excess';
+}

src/builtin/datetime/IntervalUnits.d.ts

@@ -0,0 +1,73 @@
+export interface IntervalUnits {
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  nsec?: number;
+
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  user?: number;
+
+  /**
+   * Fractional part of the last second.
+   * You can specify either nanoseconds (`nsec`), or microseconds (`usec`), or milliseconds (`msec`).
+   * Specifying two of these units simultaneously or all three ones lead to an error.
+   * @default 0
+   */
+  msec?: number;
+
+  /**
+   * Seconds.
+   * @default 0
+   */
+  sec?: number;
+
+  /**
+   * Minutes.
+   * @default 0
+   */
+  min?: number;
+
+  /**
+   * Hours.
+   * @default 0
+   */
+  hour?: number;
+
+  /**
+   * Day.
+   * @default 0
+   */
+  day?: number;
+
+  /**
+   * Week number.
+   * @default 0
+   */
+  week?: number;
+
+  /**
+   * Month number.
+   * @default 0
+   */
+  month?: number;
+
+  /**
+   * Year.
+   * @default 0
+   */
+  year?: number;
+
+  /**
+   * 	Defines how to round days in a month after an arithmetic operation.
+   * @default none
+   */
+  adjust?: 'none' | 'last' | 'excess';
+}

src/builtin/datetime/index.d.ts

@@ -0,0 +1,6 @@
+export * from './DateTimeObject';
+export * from './DateTimeTable';
+export * from './DateTimeUnits';
+export * from './IntervalObject';
+export * from './IntervalTable';
+export * from './IntervalUnits';

src/builtin/index.d.ts

@@ -3,7 +3,6 @@
 /** @todo config https://www.tarantool.io/en/doc/latest/reference/reference_lua/config/ */
 /** @todo console https://www.tarantool.io/en/doc/latest/reference/reference_lua/console/ */
 /** @todo crypto https://www.tarantool.io/en/doc/latest/reference/reference_lua/crypto/ */
-/** @todo datetime https://www.tarantool.io/en/doc/latest/reference/reference_lua/datetime/ */
 /** @todo digest https://www.tarantool.io/en/doc/latest/reference/reference_lua/digest/ */
 /** @todo errno https://www.tarantool.io/en/doc/latest/reference/reference_lua/errno/ */
 /** @todo fio https://www.tarantool.io/en/doc/latest/reference/reference_lua/fio/ */
@@ -30,6 +29,7 @@
 export * from './box';
 export * from './buffer';
 export * from './csv';
+export * from './datetime';
 export * from './fiber';
 export * from './http.client';
 export * from './json';

src/datetime.d.ts

@@ -0,0 +1 @@
+export * from './builtin/datetime/DateTime';