@naturalcycles/js-lib 14.258.0 → 14.260.0

package/dist/datetime/localDate.d.ts

@@ -1,5 +1,5 @@
 import { Iterable2 } from '../iter/iterable2';
-import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
+import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
 import { DateObject, ISODayOfWeek, LocalTime } from './localTime';
 export type LocalDateUnit = LocalDateUnitStrict | 'week';
 export type LocalDateUnitStrict = 'year' | 'month' | 'day';
@@ -142,11 +142,11 @@ export declare class LocalDate {
     /**
      * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC).
      */
-    get unix(): UnixTimestampNumber;
+    get unix(): UnixTimestamp;
     /**
      * Same as .unix(), but in milliseconds.
      */
-    get unixMillis(): UnixTimestampMillisNumber;
+    get unixMillis(): UnixTimestampMillis;
     toJSON(): IsoDateString;
     format(fmt: Intl.DateTimeFormat | LocalDateFormatter): string;
 }

package/dist/datetime/localTime.d.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestampMillisNumber, UnixTimestampNumber } from '../types';
+import type { Inclusiveness, IsoDateString, IsoDateTimeString, MonthId, NumberOfHours, NumberOfMinutes, SortDirection, UnixTimestamp, UnixTimestampMillis } from '../types';
 import { LocalDate } from './localDate';
 import { WallTime } from './wallTime';
 export type LocalTimeUnit = 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
@@ -11,7 +11,7 @@ export declare enum ISODayOfWeek {
     SATURDAY = 6,
     SUNDAY = 7
 }
-export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber;
+export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestamp;
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined;
 export type LocalTimeFormatter = (ld: LocalTime) => string;
 export type DateTimeObject = DateObject & TimeObject;
@@ -186,9 +186,9 @@ export declare class LocalTime {
     toFromNowString(now?: LocalTimeInput): string;
     toDate(): Date;
     clone(): LocalTime;
-    get unix(): UnixTimestampNumber;
-    get unixMillis(): UnixTimestampMillisNumber;
-    valueOf(): UnixTimestampNumber;
+    get unix(): UnixTimestamp;
+    get unixMillis(): UnixTimestampMillis;
+    valueOf(): UnixTimestamp;
     toLocalDate(): LocalDate;
     /**
      * Returns e.g: `1984-06-21 17:56:21`
@@ -213,7 +213,7 @@ export declare class LocalTime {
      */
     toStringCompact(seconds?: boolean): string;
     toString(): string;
-    toJSON(): UnixTimestampNumber;
+    toJSON(): UnixTimestamp;
     toMonthId(): MonthId;
     format(fmt: Intl.DateTimeFormat | LocalTimeFormatter): string;
 }
@@ -233,7 +233,11 @@ declare class LocalTimeFactory {
      Convenience function to return current Unix timestamp in seconds.
      Like Date.now(), but in seconds.
      */
-    nowUnix(): UnixTimestampNumber;
+    nowUnix(): UnixTimestamp;
+    /**
+     Convenience function that retuns the same as Date.now(), but with proper type of UnixTimestampMillis.
+     */
+    nowUnixMillis(): UnixTimestampMillis;
     /**
      * Create LocalTime from LocalTimeInput.
      * Input can already be a LocalTime - it is returned as-is in that case.
@@ -277,11 +281,11 @@ declare class LocalTimeFactory {
     isDateTimeObjectValid(o: DateTimeObject): boolean;
     isTimeObjectValid({ hour, minute, second }: TimeObject): boolean;
     fromDate(date: Date): LocalTime;
-    fromUnix(ts: UnixTimestampNumber): LocalTime;
+    fromUnix(ts: UnixTimestamp): LocalTime;
     /**
      * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
      */
-    fromMillis(millis: UnixTimestampMillisNumber): LocalTime;
+    fromMillis(millis: UnixTimestampMillis): LocalTime;
     fromDateTimeObject(o: DateTimeObjectInput): LocalTime;
     private createDateFromDateTimeObject;
     /**

package/dist/datetime/localTime.js

@@ -647,6 +647,12 @@ class LocalTimeFactory {
     nowUnix() {
         return Math.floor(Date.now() / 1000);
     }
+    /**
+     Convenience function that retuns the same as Date.now(), but with proper type of UnixTimestampMillis.
+     */
+    nowUnixMillis() {
+        return Date.now();
+    }
     /**
      * Create LocalTime from LocalTimeInput.
      * Input can already be a LocalTime - it is returned as-is in that case.

package/dist/datetime/timeInterval.d.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, UnixTimestampNumber } from '../types';
+import type { Inclusiveness, UnixTimestamp } from '../types';
 import { LocalTime, LocalTimeInput } from './localTime';
 export type TimeIntervalConfig = TimeInterval | TimeIntervalString;
 export type TimeIntervalString = string;
@@ -13,8 +13,8 @@ export declare class TimeInterval {
     private $end;
     private constructor();
     static of(start: LocalTimeInput, end: LocalTimeInput): TimeInterval;
-    get start(): UnixTimestampNumber;
-    get end(): UnixTimestampNumber;
+    get start(): UnixTimestamp;
+    get end(): UnixTimestamp;
     get startTime(): LocalTime;
     get endTime(): LocalTime;
     /**

package/dist/decorators/memo.util.d.ts

@@ -1,4 +1,4 @@
-import type { UnixTimestampNumber } from '../types';
+import type { UnixTimestamp } from '../types';
 import { MISS } from '../types';
 export type MemoSerializer = (args: any[]) => any;
 export declare const jsonMemoSerializer: MemoSerializer;
@@ -7,7 +7,7 @@ export interface MemoCacheOptions {
      * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
      * E.g EXAT in Redis.
      */
-    expireAt?: UnixTimestampNumber;
+    expireAt?: UnixTimestamp;
 }
 export interface MemoCache<KEY = any, VALUE = any> {
     has: (k: KEY) => boolean;

package/dist/env/buildInfo.d.ts

@@ -1,13 +1,13 @@
-import type { UnixTimestampNumber } from '../types';
+import type { UnixTimestamp } from '../types';
 export interface BuildInfo {
     /**
      * Unix timestamp of when the build was made.
      */
-    ts: UnixTimestampNumber;
+    ts: UnixTimestamp;
     /**
      * Unix timestamp of commit ("committer date", not "author date")
      */
-    tsCommit: UnixTimestampNumber;
+    tsCommit: UnixTimestamp;
     repoName: string;
     branchName: string;
     /**

package/dist/error/assert.d.ts

@@ -1,4 +1,5 @@
 import type { Class } from '../typeFest';
+import type { UnixTimestamp } from '../types';
 import type { BackendErrorResponseObject, ErrorData, ErrorObject } from './error.model';
 /**
  * Evaluates the `condition` (casts it to Boolean).
@@ -44,3 +45,15 @@ export declare function _assertIsBackendErrorResponseObject<DATA_TYPE extends Er
 export declare function _assertIsString(v: any, message?: string): asserts v is string;
 export declare function _assertIsNumber(v: any, message?: string): asserts v is number;
 export declare function _assertTypeOf<T>(v: any, expectedType: string, message?: string): asserts v is T;
+/**
+ * Casts an arbitrary number as UnixTimestamp.
+ * Right now does not perform any validation (unlike `asUnixTimestamp2000`),
+ * but only type casting.
+ */
+export declare function asUnixTimestamp(n: number): UnixTimestamp;
+/**
+ * Casts an arbitrary number as UnixTimestamp2000.
+ * Throws if the number is not inside 2000-01-01 and 2500-01-01 time interval,
+ * which would indicate a bug.
+ */
+export declare function asUnixTimestamp2000(n: number): UnixTimestamp;

package/dist/error/assert.js

@@ -10,8 +10,11 @@ exports._assertIsBackendErrorResponseObject = _assertIsBackendErrorResponseObjec
 exports._assertIsString = _assertIsString;
 exports._assertIsNumber = _assertIsNumber;
 exports._assertTypeOf = _assertTypeOf;
+exports.asUnixTimestamp = asUnixTimestamp;
+exports.asUnixTimestamp2000 = asUnixTimestamp2000;
 const deepEquals_1 = require("../object/deepEquals");
 const stringify_1 = require("../string/stringify");
+const zod_shared_schemas_1 = require("../zod/zod.shared.schemas");
 const error_util_1 = require("./error.util");
 /**
  * Evaluates the `condition` (casts it to Boolean).
@@ -110,3 +113,24 @@ function _assertTypeOf(v, expectedType, message) {
         throw new error_util_1.AssertionError(msg);
     }
 }
+/**
+ * Casts an arbitrary number as UnixTimestamp.
+ * Right now does not perform any validation (unlike `asUnixTimestamp2000`),
+ * but only type casting.
+ */
+function asUnixTimestamp(n) {
+    return n;
+}
+/**
+ * Casts an arbitrary number as UnixTimestamp2000.
+ * Throws if the number is not inside 2000-01-01 and 2500-01-01 time interval,
+ * which would indicate a bug.
+ */
+function asUnixTimestamp2000(n) {
+    if (!n || n < zod_shared_schemas_1.TS_2000 || n > zod_shared_schemas_1.TS_2500) {
+        throw new error_util_1.AssertionError(`Number is not a valid UnixTimestamp2000: ${n}`, {
+            fingerprint: 'asUnixTimestamp2000',
+        });
+    }
+    return n;
+}

package/dist/http/fetcher.model.d.ts

@@ -3,7 +3,7 @@
 import type { ErrorData } from '../error/error.model';
 import type { CommonLogger } from '../log/commonLogger';
 import type { Promisable } from '../typeFest';
-import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types';
+import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillis } from '../types';
 import type { HttpMethod, HttpStatusFamily } from './http.model';
 export interface FetcherNormalizedCfg extends Required<FetcherCfg>, Omit<FetcherRequest, 'started' | 'fullUrl' | 'logRequest' | 'logRequestBody' | 'logResponse' | 'logResponseBody' | 'debug' | 'redirect' | 'credentials' | 'throwHttpErrors' | 'errorData'> {
     logger: CommonLogger;
@@ -114,7 +114,7 @@ export interface FetcherRequest extends Omit<FetcherOptions, 'method' | 'headers
     retry3xx: boolean;
     retry4xx: boolean;
     retry5xx: boolean;
-    started: UnixTimestampMillisNumber;
+    started: UnixTimestampMillis;
 }
 export interface FetcherOptions {
     method?: HttpMethod;

package/dist/time/time.util.d.ts

@@ -1,3 +1,4 @@
+import type { NumberOfMilliseconds, UnixTimestampMillis } from '../types';
 /**
  * using _ = blockTimer()
  * // will log "took 1.234 sec" on dispose
@@ -11,7 +12,7 @@ export declare function _blockTimer(name?: string): Disposable;
 /**
  * Returns time passed since `from` until `until` (default to Date.now())
  */
-export declare function _since(from: number, until?: number): string;
+export declare function _since(from: UnixTimestampMillis, until?: UnixTimestampMillis): string;
 /**
  * Returns, e.g:
  * 125 ms
@@ -21,4 +22,4 @@ export declare function _since(from: number, until?: number): string;
  * 59m2s
  * 1h3m12s
  */
-export declare function _ms(millis: number): string;
+export declare function _ms(millis: NumberOfMilliseconds): string;

package/dist/types.d.ts

@@ -54,24 +54,24 @@ export type BaseDBEntity = {
     /**
      * unixTimestamp of when the entity was first created (in the DB).
      */
-    created: UnixTimestampNumber;
+    created: UnixTimestamp;
     /**
      * unixTimestamp of when the entity was last updated (in the DB).
      */
-    updated: UnixTimestampNumber;
+    updated: UnixTimestamp;
 };
 export type Saved<T> = T & {
     id: string;
-    created: UnixTimestampNumber;
-    updated: UnixTimestampNumber;
+    created: UnixTimestamp;
+    updated: UnixTimestamp;
 };
 export type SavedId<T> = T & {
     id: string;
 };
 export type Unsaved<T> = Omit<T, 'id' | 'created' | 'updated'> & {
     id?: string;
-    created?: UnixTimestampNumber;
-    updated?: UnixTimestampNumber;
+    created?: UnixTimestamp;
+    updated?: UnixTimestamp;
 };
 export type UnsavedId<T> = Omit<T, 'id'> & {
     id?: string;
@@ -191,17 +191,19 @@ export type IsoDateTimeString = string;
  */
 export type MonthId = string;
 /**
- * Interface explicitly states that the value is a Unix timestamp (in seconds).
+ * Branded UnixTimestamp in seconds.
+ * Extends (compatible with) `number`.
  *
  * @example 1628945450
  */
-export type UnixTimestampNumber = number;
+export type UnixTimestamp = Branded<number, 'UnixTimestamp'>;
 /**
- * Interface explicitly states that the value is a "Unix timestamp in **milleseconds**" (not seconds)
+ * Branded UnixTimestamp in milliseconds (not seconds).
+ * Extends (compatible with) `number`.
  *
  * @example 1628945450000
  */
-export type UnixTimestampMillisNumber = number;
+export type UnixTimestampMillis = Branded<number, 'UnixTimestampMillis'>;
 export type NumberOfHours = number;
 export type NumberOfMinutes = number;
 export type NumberOfSeconds = number;

package/dist-esm/datetime/localTime.js

@@ -643,6 +643,12 @@ class LocalTimeFactory {
     nowUnix() {
         return Math.floor(Date.now() / 1000);
     }
+    /**
+     Convenience function that retuns the same as Date.now(), but with proper type of UnixTimestampMillis.
+     */
+    nowUnixMillis() {
+        return Date.now();
+    }
     /**
      * Create LocalTime from LocalTimeInput.
      * Input can already be a LocalTime - it is returned as-is in that case.

package/dist-esm/error/assert.js

@@ -1,5 +1,6 @@
 import { _deepEquals } from '../object/deepEquals';
 import { _stringify } from '../string/stringify';
+import { TS_2000, TS_2500 } from '../zod/zod.shared.schemas';
 import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util';
 /**
  * Evaluates the `condition` (casts it to Boolean).
@@ -98,3 +99,24 @@ export function _assertTypeOf(v, expectedType, message) {
         throw new AssertionError(msg);
     }
 }
+/**
+ * Casts an arbitrary number as UnixTimestamp.
+ * Right now does not perform any validation (unlike `asUnixTimestamp2000`),
+ * but only type casting.
+ */
+export function asUnixTimestamp(n) {
+    return n;
+}
+/**
+ * Casts an arbitrary number as UnixTimestamp2000.
+ * Throws if the number is not inside 2000-01-01 and 2500-01-01 time interval,
+ * which would indicate a bug.
+ */
+export function asUnixTimestamp2000(n) {
+    if (!n || n < TS_2000 || n > TS_2500) {
+        throw new AssertionError(`Number is not a valid UnixTimestamp2000: ${n}`, {
+            fingerprint: 'asUnixTimestamp2000',
+        });
+    }
+    return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/js-lib",
-  "version": "14.258.0",
+  "version": "14.260.0",
   "scripts": {
     "prepare": "husky",
     "build": "dev-lib build-esm-cjs",

package/src/datetime/localDate.ts

@@ -6,8 +6,8 @@ import type {
   IsoDateTimeString,
   MonthId,
   SortDirection,
-  UnixTimestampMillisNumber,
-  UnixTimestampNumber,
+  UnixTimestamp,
+  UnixTimestampMillis,
 } from '../types'
 import { DateObject, ISODayOfWeek, LocalTime, localTime } from './localTime'
 
@@ -491,15 +491,15 @@ export class LocalDate {
   /**
    * Returns unix timestamp of 00:00:00 of that date (in UTC, because unix timestamp always reflects UTC).
    */
-  get unix(): UnixTimestampNumber {
-    return Math.floor(this.toDate().valueOf() / 1000)
+  get unix(): UnixTimestamp {
+    return Math.floor(this.toDate().valueOf() / 1000) as UnixTimestamp
   }
 
   /**
    * Same as .unix(), but in milliseconds.
    */
-  get unixMillis(): UnixTimestampMillisNumber {
-    return this.toDate().valueOf()
+  get unixMillis(): UnixTimestampMillis {
+    return this.toDate().valueOf() as UnixTimestampMillis
   }
 
   toJSON(): IsoDateString {

package/src/datetime/localTime.ts

@@ -8,8 +8,8 @@ import type {
   NumberOfHours,
   NumberOfMinutes,
   SortDirection,
-  UnixTimestampMillisNumber,
-  UnixTimestampNumber,
+  UnixTimestamp,
+  UnixTimestampMillis,
 } from '../types'
 import { LocalDate, localDate } from './localDate'
 import { WallTime } from './wallTime'
@@ -26,7 +26,7 @@ export enum ISODayOfWeek {
   SUNDAY = 7,
 }
 
-export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestampNumber
+export type LocalTimeInput = LocalTime | Date | IsoDateTimeString | UnixTimestamp
 export type LocalTimeInputNullable = LocalTimeInput | null | undefined
 export type LocalTimeFormatter = (ld: LocalTime) => string
 
@@ -638,16 +638,16 @@ export class LocalTime {
     return new LocalTime(new Date(this.$date))
   }
 
-  get unix(): UnixTimestampNumber {
-    return Math.floor(this.$date.valueOf() / 1000)
+  get unix(): UnixTimestamp {
+    return Math.floor(this.$date.valueOf() / 1000) as UnixTimestamp
   }
 
-  get unixMillis(): UnixTimestampMillisNumber {
-    return this.$date.valueOf()
+  get unixMillis(): UnixTimestampMillis {
+    return this.$date.valueOf() as UnixTimestampMillis
   }
 
-  valueOf(): UnixTimestampNumber {
-    return Math.floor(this.$date.valueOf() / 1000)
+  valueOf(): UnixTimestamp {
+    return Math.floor(this.$date.valueOf() / 1000) as UnixTimestamp
   }
 
   toLocalDate(): LocalDate {
@@ -730,7 +730,7 @@ export class LocalTime {
     return this.toISODateTime()
   }
 
-  toJSON(): UnixTimestampNumber {
+  toJSON(): UnixTimestamp {
     return this.unix
   }
 
@@ -772,8 +772,15 @@ class LocalTimeFactory {
    Convenience function to return current Unix timestamp in seconds.
    Like Date.now(), but in seconds.
    */
-  nowUnix(): UnixTimestampNumber {
-    return Math.floor(Date.now() / 1000)
+  nowUnix(): UnixTimestamp {
+    return Math.floor(Date.now() / 1000) as UnixTimestamp
+  }
+
+  /**
+   Convenience function that retuns the same as Date.now(), but with proper type of UnixTimestampMillis.
+   */
+  nowUnixMillis(): UnixTimestampMillis {
+    return Date.now() as UnixTimestampMillis
   }
 
   /**
@@ -925,14 +932,14 @@ class LocalTimeFactory {
     return new LocalTime(date)
   }
 
-  fromUnix(ts: UnixTimestampNumber): LocalTime {
+  fromUnix(ts: UnixTimestamp): LocalTime {
     return new LocalTime(new Date(ts * 1000))
   }
 
   /**
    * Create LocalTime from unixTimestamp in milliseconds (not in seconds).
    */
-  fromMillis(millis: UnixTimestampMillisNumber): LocalTime {
+  fromMillis(millis: UnixTimestampMillis): LocalTime {
     return new LocalTime(new Date(millis))
   }
 

package/src/datetime/timeInterval.ts

@@ -1,4 +1,4 @@
-import type { Inclusiveness, UnixTimestampNumber } from '../types'
+import type { Inclusiveness, UnixTimestamp } from '../types'
 import { LocalTime, localTime, LocalTimeInput } from './localTime'
 
 export type TimeIntervalConfig = TimeInterval | TimeIntervalString
@@ -12,19 +12,19 @@ export type TimeIntervalString = string
  */
 export class TimeInterval {
   private constructor(
-    private $start: UnixTimestampNumber,
-    private $end: UnixTimestampNumber,
+    private $start: UnixTimestamp,
+    private $end: UnixTimestamp,
   ) {}
 
   static of(start: LocalTimeInput, end: LocalTimeInput): TimeInterval {
     return new TimeInterval(localTime.fromInput(start).unix, localTime.fromInput(end).unix)
   }
 
-  get start(): UnixTimestampNumber {
+  get start(): UnixTimestamp {
     return this.$start
   }
 
-  get end(): UnixTimestampNumber {
+  get end(): UnixTimestamp {
     return this.$end
   }
 
@@ -42,7 +42,7 @@ export class TimeInterval {
   static parse(d: TimeIntervalConfig): TimeInterval {
     if (d instanceof TimeInterval) return d
 
-    const [start, end] = d.split('/').map(Number)
+    const [start, end] = d.split('/').map(Number) as UnixTimestamp[]
 
     if (!end || !start) {
       throw new Error(`Cannot parse "${d}" into TimeInterval`)

package/src/decorators/memo.util.ts

@@ -1,6 +1,6 @@
 import { _isPrimitive } from '../is.util'
 import { pDelay } from '../promise/pDelay'
-import type { UnixTimestampNumber } from '../types'
+import type { UnixTimestamp } from '../types'
 import { MISS } from '../types'
 
 export type MemoSerializer = (args: any[]) => any
@@ -16,7 +16,7 @@ export interface MemoCacheOptions {
    * If set (and if it's implemented by the driver) - will set expiry TTL for each key of the batch.
    * E.g EXAT in Redis.
    */
-  expireAt?: UnixTimestampNumber
+  expireAt?: UnixTimestamp
 }
 
 export interface MemoCache<KEY = any, VALUE = any> {

package/src/env/buildInfo.ts

@@ -1,16 +1,16 @@
 import { localTime } from '../datetime/localTime'
-import type { UnixTimestampNumber } from '../types'
+import type { UnixTimestamp } from '../types'
 
 export interface BuildInfo {
   /**
    * Unix timestamp of when the build was made.
    */
-  ts: UnixTimestampNumber
+  ts: UnixTimestamp
 
   /**
    * Unix timestamp of commit ("committer date", not "author date")
    */
-  tsCommit: UnixTimestampNumber
+  tsCommit: UnixTimestamp
 
   repoName: string
   branchName: string

package/src/error/assert.ts

@@ -1,6 +1,8 @@
 import { _deepEquals } from '../object/deepEquals'
 import { _stringify } from '../string/stringify'
 import type { Class } from '../typeFest'
+import type { UnixTimestamp } from '../types'
+import { TS_2000, TS_2500 } from '../zod/zod.shared.schemas'
 import type { BackendErrorResponseObject, ErrorData, ErrorObject } from './error.model'
 import { _isBackendErrorResponseObject, _isErrorObject, AssertionError } from './error.util'
 
@@ -141,3 +143,26 @@ export function _assertTypeOf<T>(v: any, expectedType: string, message?: string)
     throw new AssertionError(msg)
   }
 }
+
+/**
+ * Casts an arbitrary number as UnixTimestamp.
+ * Right now does not perform any validation (unlike `asUnixTimestamp2000`),
+ * but only type casting.
+ */
+export function asUnixTimestamp(n: number): UnixTimestamp {
+  return n as UnixTimestamp
+}
+
+/**
+ * Casts an arbitrary number as UnixTimestamp2000.
+ * Throws if the number is not inside 2000-01-01 and 2500-01-01 time interval,
+ * which would indicate a bug.
+ */
+export function asUnixTimestamp2000(n: number): UnixTimestamp {
+  if (!n || n < TS_2000 || n > TS_2500) {
+    throw new AssertionError(`Number is not a valid UnixTimestamp2000: ${n}`, {
+      fingerprint: 'asUnixTimestamp2000',
+    })
+  }
+  return n as UnixTimestamp
+}

package/src/error/tryCatch.ts

@@ -1,4 +1,4 @@
-import type { CommonLogger } from '../index'
+import type { CommonLogger, UnixTimestampMillis } from '../index'
 import { _anyToError, _since } from '../index'
 import type { AnyFunction } from '../types'
 
@@ -39,7 +39,7 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
   const fname = fn.name || 'anonymous'
 
   return async function (this: any, ...args: any[]) {
-    const started = Date.now()
+    const started = Date.now() as UnixTimestampMillis
 
     try {
       const r = await fn.apply(this, args)

package/src/http/fetcher.model.ts

@@ -4,7 +4,7 @@
 import type { ErrorData } from '../error/error.model'
 import type { CommonLogger } from '../log/commonLogger'
 import type { Promisable } from '../typeFest'
-import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillisNumber } from '../types'
+import type { AnyObject, NumberOfMilliseconds, Reviver, UnixTimestampMillis } from '../types'
 import type { HttpMethod, HttpStatusFamily } from './http.model'
 
 export interface FetcherNormalizedCfg
@@ -149,7 +149,7 @@ export interface FetcherRequest
   retry3xx: boolean
   retry4xx: boolean
   retry5xx: boolean
-  started: UnixTimestampMillisNumber
+  started: UnixTimestampMillis
 }
 
 export interface FetcherOptions {

package/src/http/fetcher.ts

@@ -28,7 +28,7 @@ import { pTimeout } from '../promise/pTimeout'
 import { _jsonParse, _jsonParseIfPossible } from '../string/json.util'
 import { _stringify } from '../string/stringify'
 import { _ms, _since } from '../time/time.util'
-import { ErrorDataTuple, NumberOfMilliseconds } from '../types'
+import { ErrorDataTuple, NumberOfMilliseconds, UnixTimestampMillis } from '../types'
 import type {
   FetcherAfterResponseHook,
   FetcherBeforeRequestHook,
@@ -262,7 +262,7 @@ export class Fetcher {
     } as FetcherResponse<any>
 
     while (!res.retryStatus.retryStopped) {
-      req.started = Date.now()
+      req.started = Date.now() as UnixTimestampMillis
 
       // setup timeout
       let timeoutId: number | undefined
@@ -708,7 +708,7 @@ export class Fetcher {
         'throwHttpErrors',
         'errorData',
       ]),
-      started: Date.now(),
+      started: Date.now() as UnixTimestampMillis,
       ..._omit(opt, ['method', 'headers', 'credentials']),
       inputUrl: opt.url || '',
       fullUrl: opt.url || '',

package/src/promise/pRetry.ts

@@ -1,4 +1,4 @@
-import type { AnyFunction, CommonLogger, ErrorData } from '..'
+import type { AnyFunction, CommonLogger, ErrorData, UnixTimestampMillis } from '..'
 import { _errorDataAppend, _since, pDelay, pTimeout } from '..'
 
 export interface PRetryOptions {
@@ -129,7 +129,7 @@ export async function pRetry<T>(
   let attempt = 0
 
   while (true) {
-    const started = Date.now()
+    const started = Date.now() as UnixTimestampMillis
 
     try {
       attempt++

package/src/time/time.util.ts

@@ -1,3 +1,5 @@
+import type { NumberOfMilliseconds, UnixTimestampMillis } from '../types'
+
 /**
  * using _ = blockTimer()
  * // will log "took 1.234 sec" on dispose
@@ -8,7 +10,7 @@
  * @experimental
  */
 export function _blockTimer(name?: string): Disposable {
-  const started = Date.now()
+  const started = Date.now() as UnixTimestampMillis
   return {
     [Symbol.dispose](): void {
       console.log(`${name ? name + ' ' : ''}took ${_since(started)}`)
@@ -19,7 +21,10 @@ export function _blockTimer(name?: string): Disposable {
 /**
  * Returns time passed since `from` until `until` (default to Date.now())
  */
-export function _since(from: number, until = Date.now()): string {
+export function _since(
+  from: UnixTimestampMillis,
+  until: UnixTimestampMillis = Date.now() as UnixTimestampMillis,
+): string {
   return _ms(until - from)
 }
 
@@ -32,7 +37,7 @@ export function _since(from: number, until = Date.now()): string {
  * 59m2s
  * 1h3m12s
  */
-export function _ms(millis: number): string {
+export function _ms(millis: NumberOfMilliseconds): string {
   // <1 sec
   if (millis < 1000) return `${Math.round(millis)} ms`
 

package/src/types.ts

@@ -70,18 +70,18 @@ export type BaseDBEntity = {
   /**
    * unixTimestamp of when the entity was first created (in the DB).
    */
-  created: UnixTimestampNumber
+  created: UnixTimestamp
 
   /**
    * unixTimestamp of when the entity was last updated (in the DB).
    */
-  updated: UnixTimestampNumber
+  updated: UnixTimestamp
 }
 
 export type Saved<T> = T & {
   id: string
-  created: UnixTimestampNumber
-  updated: UnixTimestampNumber
+  created: UnixTimestamp
+  updated: UnixTimestamp
 }
 
 export type SavedId<T> = T & {
@@ -90,8 +90,8 @@ export type SavedId<T> = T & {
 
 export type Unsaved<T> = Omit<T, 'id' | 'created' | 'updated'> & {
   id?: string
-  created?: UnixTimestampNumber
-  updated?: UnixTimestampNumber
+  created?: UnixTimestamp
+  updated?: UnixTimestamp
 }
 
 export type UnsavedId<T> = Omit<T, 'id'> & {
@@ -249,18 +249,20 @@ export type IsoDateTimeString = string
 export type MonthId = string
 
 /**
- * Interface explicitly states that the value is a Unix timestamp (in seconds).
+ * Branded UnixTimestamp in seconds.
+ * Extends (compatible with) `number`.
  *
  * @example 1628945450
  */
-export type UnixTimestampNumber = number
+export type UnixTimestamp = Branded<number, 'UnixTimestamp'>
 
 /**
- * Interface explicitly states that the value is a "Unix timestamp in **milleseconds**" (not seconds)
+ * Branded UnixTimestamp in milliseconds (not seconds).
+ * Extends (compatible with) `number`.
  *
  * @example 1628945450000
  */
-export type UnixTimestampMillisNumber = number
+export type UnixTimestampMillis = Branded<number, 'UnixTimestampMillis'>
 
 export type NumberOfHours = number
 export type NumberOfMinutes = number