feat(types): TimestampFormat, Timestamp

Signed-off-by: Lexus Drumgold <[email protected]>

src/types/__tests__/timestamp-format.spec-d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Type Tests - TimestampFormat
+ * @module tutils/types/tests/unit-d/TimestampFormat
+ */
+
+import type TestSubject from '../timestamp-format'
+
+describe('unit-d:types/TimestampFormat', () => {
+  it('should extract "iso"', () => {
+    expectTypeOf<TestSubject>().extract<'iso'>().not.toBeNever()
+  })
+
+  it('should extract "unix"', () => {
+    expectTypeOf<TestSubject>().extract<'unix'>().not.toBeNever()
+  })
+})

src/types/__tests__/timestamp.spec-d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Type Tests - Timestamp
+ * @module tutils/types/tests/unit-d/Timestamp
+ */
+
+import type { tag } from '../opaque'
+import type TestSubject from '../timestamp'
+import type TimestampFormat from '../timestamp-format'
+
+describe('unit-d:types/Timestamp', () => {
+  it('should extend number if Format extends "unix"', () => {
+    expectTypeOf<TestSubject<'unix'>>().toMatchTypeOf<number>()
+  })
+
+  it('should extend string if Format extends "iso"', () => {
+    expectTypeOf<TestSubject<'iso'>>().toMatchTypeOf<string>()
+  })
+
+  it('should match [readonly [tag]: "$timestamp"]', () => {
+    expectTypeOf<TestSubject<TimestampFormat>>().toMatchTypeOf<{
+      readonly [tag]: '$timestamp'
+    }>()
+  })
+})

src/types/index.ts

@@ -94,5 +94,7 @@ export type { default as Promisable } from './promisable'
 export type { default as Simplify } from './simplify'
 export type { default as Split } from './split'
 export type { default as Stringafiable } from './stringafiable'
+export type { default as Timestamp } from './timestamp'
+export type { default as TimestampFormat } from './timestamp-format'
 export type { default as TupleToUnion } from './tuple-to-union'
 export type { default as TypedArray } from './typed-array'

src/types/timestamp-format.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Type Definitions - TimestampFormat
+ * @module tutils/types/TimestampFormat
+ */
+
+/**
+ * Timestamp formats.
+ *
+ * @see https://en.wikipedia.org/wiki/ISO_8601
+ * @see https://unixtimestamp.com
+ */
+type TimestampFormat = 'iso' | 'unix'
+
+export type { TimestampFormat as default }

src/types/timestamp.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Type Definitions - Timestamp
+ * @module tutils/types/Timestamp
+ */
+
+import type NumberString from './number-string'
+import type Opaque from './opaque'
+import type TimestampFormat from './timestamp-format'
+
+/**
+ * An [ISO 8601][1] or [unix][2] timestamp.
+ *
+ * [1]: https://en.wikipedia.org/wiki/ISO_8601
+ * [2]: https://unixtimestamp.com
+ *
+ * @see {@linkcode TimestampFormat}
+ * @see https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
+ *
+ * @template Format - Timestamp format
+ */
+type Timestamp<Format extends TimestampFormat> = Opaque<
+  Format extends 'unix' ? number : Format extends 'iso' ? string : NumberString,
+  '$timestamp'
+>
+
+export type { Timestamp as default }