@naturalcycles/js-lib 14.257.0 → 14.259.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,7 @@ declare class LocalTimeFactory {
      Convenience function to return current Unix timestamp in seconds.
      Like Date.now(), but in seconds.
      */
-    nowUnix(): UnixTimestampNumber;
+    nowUnix(): UnixTimestamp;
     /**
      * Create LocalTime from LocalTimeInput.
      * Input can already be a LocalTime - it is returned as-is in that case.
@@ -277,11 +277,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/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/deviceIdService.d.ts

@@ -0,0 +1,65 @@
+/// <reference lib="dom" preserve="true" />
+/**
+ * Service to generate, maintain, persist a stable "device id".
+ *
+ * It's called "device id" and not userId/visitorId, to indicate that it only identifies a device,
+ * and has nothing to do with user identification.
+ * User might be logged in or not.
+ * User id can be the same on multiple devices.
+ * DeviceId is unique per device, same User or not.
+ *
+ * Service provides methods to deterministically select fraction of devices.
+ * For example, select 10% of devices that visit the website to be tracked by Analytics
+ * (to reduce Analytics quota usage).
+ * DeviceId persistence will ensure that recurring visits from the same device will yield the same
+ * DeviceId, and same "selection assignment" (like an assignment in an AB test).
+ *
+ * @experimental
+ */
+export declare class DeviceIdService {
+    constructor(cfg?: DeviceIdServiceCfg);
+    cfg: Required<DeviceIdServiceCfg>;
+    /**
+     * `deviceId` is null only in anomalous cases, e.g when localStorage is not available (due to e.g "out of disk space" on device).
+     * In all other cases it should be defined and stable (persisted indefinitely between multiple visits).
+     *
+     * It is null if the service is run on the server side.
+     */
+    deviceId: string | null;
+    /**
+     * Selects this device based on "deterministic random selection", according to the defined `rate`.
+     * Rate is a floating number between 0 and 1.
+     * E.g rate of 0.1 means 10% chance of being selected.
+     *
+     * Selection is based on deviceId, which is generated random and persisted between visits.
+     * Persistence ensures that the selection (similar to an AB-test assignment) "sticks" to the device.
+     *
+     * If deviceId failed to be generated, e.g due to Device running out-of-space to save a string to localStorage,
+     * it will NOT be selected.
+     *
+     * @returns true if the device is selected.
+     */
+    select(rate: number): boolean;
+    /**
+     * Deletes the persisted deviceId.
+     * Keeps it in the service.
+     * To remove it from the service, assign deviceIdService.deviceId = null.
+     */
+    clearPersistence(): void;
+    /**
+     * Generates a stable Device id if it wasn't previously generated on this device.
+     * Otherwise, reads a Device id from persistent storage.
+     */
+    private init;
+    private debug;
+}
+export interface DeviceIdServiceCfg {
+    /**
+     * Default: deviceId
+     */
+    localStorageKey?: string;
+    /**
+     * Set to true to enable debug logging.
+     */
+    debug?: boolean;
+}

package/dist/deviceIdService.js

@@ -0,0 +1,109 @@
+"use strict";
+/// <reference lib="dom" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceIdService = void 0;
+const env_1 = require("./env");
+const nanoid_1 = require("./nanoid");
+const hash_util_1 = require("./string/hash.util");
+// This is in sync with the default length in Nanoid.
+const deviceIdLength = 21;
+/**
+ * Service to generate, maintain, persist a stable "device id".
+ *
+ * It's called "device id" and not userId/visitorId, to indicate that it only identifies a device,
+ * and has nothing to do with user identification.
+ * User might be logged in or not.
+ * User id can be the same on multiple devices.
+ * DeviceId is unique per device, same User or not.
+ *
+ * Service provides methods to deterministically select fraction of devices.
+ * For example, select 10% of devices that visit the website to be tracked by Analytics
+ * (to reduce Analytics quota usage).
+ * DeviceId persistence will ensure that recurring visits from the same device will yield the same
+ * DeviceId, and same "selection assignment" (like an assignment in an AB test).
+ *
+ * @experimental
+ */
+class DeviceIdService {
+    constructor(cfg = {}) {
+        this.cfg = {
+            localStorageKey: 'deviceId',
+            debug: false,
+            ...cfg,
+        };
+        this.init();
+    }
+    /**
+     * Selects this device based on "deterministic random selection", according to the defined `rate`.
+     * Rate is a floating number between 0 and 1.
+     * E.g rate of 0.1 means 10% chance of being selected.
+     *
+     * Selection is based on deviceId, which is generated random and persisted between visits.
+     * Persistence ensures that the selection (similar to an AB-test assignment) "sticks" to the device.
+     *
+     * If deviceId failed to be generated, e.g due to Device running out-of-space to save a string to localStorage,
+     * it will NOT be selected.
+     *
+     * @returns true if the device is selected.
+     */
+    select(rate) {
+        if (!this.deviceId) {
+            this.debug(`deviceId is null, skipping selection`);
+            return false;
+        }
+        const mod = Math.trunc(rate * 1000);
+        // console.log('hash: ', hashCode(this.deviceId)) // todo
+        return (0, hash_util_1.hashCode)(this.deviceId) % 1000 < mod;
+    }
+    /**
+     * Deletes the persisted deviceId.
+     * Keeps it in the service.
+     * To remove it from the service, assign deviceIdService.deviceId = null.
+     */
+    clearPersistence() {
+        try {
+            globalThis.localStorage.removeItem(this.cfg.localStorageKey);
+        }
+        catch (err) {
+            console.log(err);
+        }
+    }
+    /**
+     * Generates a stable Device id if it wasn't previously generated on this device.
+     * Otherwise, reads a Device id from persistent storage.
+     */
+    init() {
+        this.deviceId = null;
+        if ((0, env_1.isServerSide)())
+            return;
+        try {
+            this.deviceId = globalThis.localStorage.getItem(this.cfg.localStorageKey);
+            if (this.deviceId)
+                this.debug(`loaded deviceId: ${this.deviceId}`);
+        }
+        catch (err) {
+            console.log(err);
+            this.deviceId = null;
+        }
+        if (this.deviceId && this.deviceId.length !== deviceIdLength) {
+            console.warn(`[DeviceIdService] unexpected deviceIdLength (${this.deviceId.length}), will re-generate the id`, { deviceId: this.deviceId });
+            this.deviceId = null;
+        }
+        if (!this.deviceId) {
+            try {
+                this.deviceId = (0, nanoid_1.nanoidBrowser)(deviceIdLength);
+                this.debug(`generated new deviceId: ${this.deviceId}`);
+                globalThis.localStorage.setItem(this.cfg.localStorageKey, this.deviceId);
+            }
+            catch (err) {
+                console.log(err);
+                this.deviceId = null;
+            }
+        }
+    }
+    debug(...args) {
+        if (this.cfg.debug)
+            console.log('[DeviceIdService]', ...args);
+    }
+}
+exports.DeviceIdService = DeviceIdService;

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/index.d.ts

@@ -27,6 +27,7 @@ export * from './decorators/memoFnAsync';
 export * from './decorators/retry.decorator';
 export * from './decorators/timeout.decorator';
 export * from './define';
+export * from './deviceIdService';
 export * from './enum.util';
 export * from './env';
 export * from './env/buildInfo';
@@ -52,6 +53,7 @@ export * from './log/commonLogger';
 export * from './math/math.util';
 export * from './math/sma';
 export * from './math/stack.util';
+export * from './nanoid';
 export * from './number/createDeterministicRandom';
 export * from './number/number.util';
 export * from './object/deepEquals';

package/dist/index.js

@@ -31,6 +31,7 @@ tslib_1.__exportStar(require("./decorators/memoFnAsync"), exports);
 tslib_1.__exportStar(require("./decorators/retry.decorator"), exports);
 tslib_1.__exportStar(require("./decorators/timeout.decorator"), exports);
 tslib_1.__exportStar(require("./define"), exports);
+tslib_1.__exportStar(require("./deviceIdService"), exports);
 tslib_1.__exportStar(require("./enum.util"), exports);
 tslib_1.__exportStar(require("./env"), exports);
 tslib_1.__exportStar(require("./env/buildInfo"), exports);
@@ -56,6 +57,7 @@ tslib_1.__exportStar(require("./log/commonLogger"), exports);
 tslib_1.__exportStar(require("./math/math.util"), exports);
 tslib_1.__exportStar(require("./math/sma"), exports);
 tslib_1.__exportStar(require("./math/stack.util"), exports);
+tslib_1.__exportStar(require("./nanoid"), exports);
 tslib_1.__exportStar(require("./number/createDeterministicRandom"), exports);
 tslib_1.__exportStar(require("./number/number.util"), exports);
 tslib_1.__exportStar(require("./object/deepEquals"), exports);

package/dist/nanoid.d.ts

@@ -0,0 +1,7 @@
+/// <reference lib="dom" preserve="true" />
+/**
+ * Function that takes a length (defaults to 21) and generates a random string id of that length.
+ */
+export type NanoidFunction = (length?: number) => string;
+export declare function nanoidBrowser(length?: number): string;
+export declare function nanoidBrowserCustomAlphabet(alphabet: string, length?: number): NanoidFunction;

package/dist/nanoid.js

@@ -0,0 +1,61 @@
+"use strict";
+// Vendored from https://github.com/ai/nanoid/blob/main/index.browser.js
+// All credit to nanoid authors: https://github.com/ai/nanoid
+// Reason for vendoring: (still) cannot import esm, and Nanoid went ESM-only since 4.0
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nanoidBrowser = nanoidBrowser;
+exports.nanoidBrowserCustomAlphabet = nanoidBrowserCustomAlphabet;
+/// <reference lib="dom" preserve="true" />
+/* eslint-disable no-bitwise */
+// "0-9a-zA-Z-_", same as base64url alphabet
+const urlAlphabet = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict';
+function nanoidBrowser(length = 21) {
+    let id = '';
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(length));
+    while (length--) {
+        // Using the bitwise AND operator to "cap" the value of
+        // the random byte from 255 to 63, in that way we can make sure
+        // that the value will be a valid index for the "chars" string.
+        id += urlAlphabet[bytes[length] & 63];
+    }
+    return id;
+}
+const defaultRandomFunction = (bytes) => globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+function nanoidBrowserCustomAlphabet(alphabet, length = 21) {
+    return customRandom(alphabet, length, defaultRandomFunction);
+}
+function customRandom(alphabet, defaultSize, getRandom) {
+    // First, a bitmask is necessary to generate the ID. The bitmask makes bytes
+    // values closer to the alphabet size. The bitmask calculates the closest
+    // `2^31 - 1` number, which exceeds the alphabet size.
+    // For example, the bitmask for the alphabet size 30 is 31 (00011111).
+    // `Math.clz32` is not used, because it is not available in browsers.
+    const mask = (2 << Math.log2(alphabet.length - 1)) - 1;
+    // Though, the bitmask solution is not perfect since the bytes exceeding
+    // the alphabet size are refused. Therefore, to reliably generate the ID,
+    // the random bytes redundancy has to be satisfied.
+    // Note: every hardware random generator call is performance expensive,
+    // because the system call for entropy collection takes a lot of time.
+    // So, to avoid additional system calls, extra bytes are requested in advance.
+    // Next, a step determines how many random bytes to generate.
+    // The number of random bytes gets decided upon the ID size, mask,
+    // alphabet size, and magic number 1.6 (using 1.6 peaks at performance
+    // according to benchmarks).
+    // `-~f => Math.ceil(f)` if f is a float
+    // `-~i => i + 1` if i is an integer
+    const step = -~((1.6 * mask * defaultSize) / alphabet.length);
+    return (size = defaultSize) => {
+        let id = '';
+        while (true) {
+            const bytes = getRandom(step);
+            // A compact alternative for `for (var i = 0; i < step; i++)`.
+            let j = step;
+            while (j--) {
+                // Adding `|| ''` refuses a random byte that exceeds the alphabet size.
+                id += alphabet[bytes[j] & mask] || '';
+                if (id.length === size)
+                    return id;
+            }
+        }
+    };
+}

package/dist/number/createDeterministicRandom.d.ts

@@ -1,6 +1,11 @@
+/**
+ * Function that returns a random number between 0 and 1.
+ * Exactly same signature as Math.random function.
+ */
+export type RandomFunction = () => number;
 /**
  * Returns a "deterministic Math.random() function"
  *
  * Based on: https://gist.github.com/mathiasbynens/5670917
  */
-export declare function _createDeterministicRandom(): () => number;
+export declare function _createDeterministicRandom(seed?: number): RandomFunction;

package/dist/number/createDeterministicRandom.js

@@ -7,8 +7,7 @@ exports._createDeterministicRandom = _createDeterministicRandom;
  *
  * Based on: https://gist.github.com/mathiasbynens/5670917
  */
-function _createDeterministicRandom() {
-    let seed = 0x2f6e2b1;
+function _createDeterministicRandom(seed = 0x2f6e2b1) {
     return () => {
         // Robert Jenkins’ 32 bit integer hash function
         seed = (seed + 0x7ed55d16 + (seed << 12)) & 0xffffffff;

package/dist/string/hash.util.d.ts

@@ -6,7 +6,7 @@ import { Integer } from '../types';
  *
  * 1. Performance
  * 2. For non-cryptographic use (where accidental collision is not the end-of-the-world)
- * 3. Compact size (32 bits max, versus 128 in md5; presented in less string json-safe characters)
+ * 3. Compact size (32 bits max, versus 128 in md5; presented in smaller number of string json-safe characters)
  *
  * Basically, these functions are as simple as they can be, but still "random enough" for
  * normal non-cryptographic use cases.

package/dist/string/hash.util.js

@@ -14,7 +14,7 @@ const BASE64URL = BASE62 + '-_';
  *
  * 1. Performance
  * 2. For non-cryptographic use (where accidental collision is not the end-of-the-world)
- * 3. Compact size (32 bits max, versus 128 in md5; presented in less string json-safe characters)
+ * 3. Compact size (32 bits max, versus 128 in md5; presented in smaller number of string json-safe characters)
  *
  * Basically, these functions are as simple as they can be, but still "random enough" for
  * normal non-cryptographic use cases.

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/web.d.ts

@@ -5,6 +5,12 @@ import { StringMap } from './types';
  * Implements WebStorage API by using in-memory storage.
  * Can be useful in SSR environment or unit tests.
  *
+ * This is how localStorage can be mocked in Node:
+ *
+ * Object.assign(globalThis, {
+ *  localStorage: new InMemoryWebStorage(),
+ * })
+ *
  * @experimental
  */
 export declare class InMemoryWebStorage implements Storage {

package/dist/web.js

@@ -7,6 +7,12 @@ exports.InMemoryWebStorage = void 0;
  * Implements WebStorage API by using in-memory storage.
  * Can be useful in SSR environment or unit tests.
  *
+ * This is how localStorage can be mocked in Node:
+ *
+ * Object.assign(globalThis, {
+ *  localStorage: new InMemoryWebStorage(),
+ * })
+ *
  * @experimental
  */
 class InMemoryWebStorage {