@daiso-tech/core 0.40.0 → 0.41.1

package/dist/task/_module-exports.d.ts

@@ -0,0 +1 @@
+export * from "../task/task.js";

package/dist/task/_module-exports.js

@@ -0,0 +1,2 @@
+export * from "../task/task.js";
+//# sourceMappingURL=_module-exports.js.map

package/dist/task/_module-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_module-exports.js","sourceRoot":"","sources":["../../src/task/_module-exports.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/{async/utilities/abort-and-fail → task}/abort-and-fail.d.ts

@@ -1,5 +1,5 @@
 /**
- * @module Async
+ * @module Task
  */
 /**
  * @internal

package/dist/{async/utilities/abort-and-fail → task}/abort-and-fail.js

@@ -1,5 +1,5 @@
 /**
- * @module Async
+ * @module Task
  */
 /**
  * @internal

package/dist/task/abort-and-fail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-and-fail.js","sourceRoot":"","sources":["../../src/task/abort-and-fail.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,SAAS,oBAAoB,CACzB,WAAwB;IAKxB,IAAI,OAAO,GAAsC,IAAI,CAAC;IACtD,SAAS,KAAK;QACV,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO;QACX,CAAC;QACD,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO;YACH,2EAA2E;YAC3E,OAAO,EAAE,OAAO,CAAC,MAAM,CAAS,WAAW,CAAC,MAAM,CAAC;YACnD,KAAK;SACR,CAAC;IACN,CAAC;IAED,OAAO;QACH,OAAO,EAAE,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACtC,OAAO,GAAG,MAAM,CAAC;YACjB,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;gBACtB,KAAK,EAAE,CAAC;gBACR,OAAO;YACX,CAAC;YACD,WAAW,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE;gBACzC,IAAI,EAAE,IAAI;aACb,CAAC,CAAC;QACP,CAAC,CAAC;QACF,KAAK;KACR,CAAC;AACN,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAC9B,OAA4B,EAC5B,WAAwB;IAExB,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,WAAW,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,KAAK,EAAE,GACxC,oBAAoB,CAAS,WAAW,CAAC,CAAC;IAC9C,IAAI,CAAC;QACD,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC7D,CAAC;YAAS,CAAC;QACP,WAAW,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;AACL,CAAC"}

package/dist/task/task.d.ts

@@ -0,0 +1,194 @@
+/**
+ * @module Task
+ */
+import { type AsyncLazy, type Invokable, type InvokableFn, type OneOrMore, type Promisable } from "../utilities/_module-exports.js";
+import type { ITimeSpan } from "../time-span/contracts/_module-exports.js";
+import { type AsyncMiddleware } from "../hooks/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export type TaskResolve<TValue> = InvokableFn<[
+    value: Promisable<TValue>
+], void>;
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export type TaskReject = InvokableFn<[error: unknown], void>;
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export type TaskCallback<TValue> = InvokableFn<[
+    resolve: TaskResolve<TValue>,
+    reject: TaskReject
+], Promisable<void>>;
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export type TaskAllResult<T extends readonly unknown[]> = {
+    -readonly [P in keyof T]: Awaited<T[P]>;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export type TaskAllSettledResult<T extends readonly unknown[]> = {
+    -readonly [P in keyof T]: PromiseSettledResult<Awaited<T[P]>>;
+};
+/**
+ * The `Task` class is used for creating lazy {@link PromiseLike | `PromiseLike`} object that will only execute when awaited or when `then` method is called.
+ * Note the class is immutable.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export declare class Task<TValue> implements PromiseLike<TValue> {
+    /**
+     * The `wrapFn` is convience method used for wrapping async {@link Invokable | `Invokable`} with a `Task`.
+     * @example
+     * ```ts
+     * import { Task, retry } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     * import { readFile as readFileNodeJs } from "node:fs/promises";
+     *
+     * const readFile = Task.wrapFn(readFileNodeJs);
+     *
+     * const file = await readFile("none_existing_file.txt");
+     * ```
+     */
+    static wrapFn<TArgs extends unknown[], TReturn>(fn: Invokable<TArgs, Promisable<TReturn>>): InvokableFn<TArgs, Task<TReturn>>;
+    /**
+     * The `delay` method creates a {@link Task | `Task`} that will be fulfilled after given `time`.
+     *
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     *
+     * console.log("a");
+     * await Task.delay(TimeSpan.fromSeconds(2));
+     * console.log("b");
+     * ```
+     */
+    static delay(time: ITimeSpan, abortSignal?: AbortSignal): Task<void>;
+    /**
+     * The `resolve` method works similarly to {@link Promise.resolve | `Promise.resolve`} with the key distinction that it operates lazily.
+     */
+    static resolve<TValue>(value: TValue | Task<TValue>): Task<TValue>;
+    /**
+     * The `resolve` method works similarly to {@link Promise.resolve | `Promise.resolve`} with the key distinction that it operates lazily.
+     */
+    static resolve(): Task<void>;
+    /**
+     * The `reject` method works similarly to {@link Promise.reject | `Promise.reject`} with the key distinction that it operates lazily.
+     */
+    static reject<TValue = never, TError = unknown>(reason?: TError): Task<TValue>;
+    private static toTasks;
+    /**
+     * The `all` method works similarly to {@link Promise.all | `Promise.all`} with the key distinction that it operates lazily.
+     */
+    static all<TValue extends readonly unknown[] | []>(tasks: TValue): Task<TaskAllResult<TValue>>;
+    /**
+     * The `all` method works similarly to {@link Promise.all | `Promise.all`} with the key distinction that it operates lazily.
+     */
+    static all<TValue>(tasks: Iterable<TValue | Task<TValue>>): Task<Awaited<TValue>[]>;
+    /**
+     * The `allSettled` method works similarly to {@link Promise.allSettled | `Promise.allSettled`} with the key distinction that it operates lazily.
+     */
+    static allSettled<TValues extends readonly unknown[] | []>(tasks: TValues): Task<TaskAllSettledResult<TValues>>;
+    /**
+     * The `allSettled` method works similarly to {@link Promise.allSettled | `Promise.allSettled`} with the key distinction that it operates lazily.
+     */
+    static allSettled<TValue>(tasks: Iterable<Task<TValue>>): Task<PromiseSettledResult<TValue>[]>;
+    /**
+     * The `race` method works similarly to {@link Promise.race | `Promise.race`} with the key distinction that it operates lazily.
+     */
+    static race<T extends readonly unknown[] | []>(tasks: T): Task<Awaited<T[number]>>;
+    /**
+     * The `race` method works similarly to {@link Promise.race | `Promise.race`} with the key distinction that it operates lazily.
+     */
+    static race<TValue>(tasks: Iterable<TValue | Task<TValue>>): Task<TValue>;
+    /**
+     * The `any` method works similarly to {@link Promise.any | `Promise.any`} with the key distinction that it operates lazily.
+     */
+    static any<T extends readonly unknown[] | []>(tasks: T): Task<Awaited<T[number]>>;
+    /**
+     * The `any` method works similarly to {@link Promise.any | `Promise.any`} with the key distinction that it operates lazily.
+     */
+    static any<TValue>(tasks: Iterable<TValue | Task<TValue>>): Task<TValue>;
+    /**
+     * The `fromCallback` is convience method used for wrapping Node js callback functions with a `Task`.
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { readFile } from "node:fs";
+     *
+     * const task = Task.fromCallback<Buffer  | string>((resolve, reject) => {
+     *   readFile("FILE_PATH", (err, data) => {
+     *     if (err !== null) {
+     *       reject(err);
+     *       return;
+     *     }
+     *     resolve(data);
+     *   });
+     * });
+     * const file = await task;
+     * console.log(file);
+     * ```
+     */
+    static fromCallback<TValue>(callback: TaskCallback<TValue>): Task<TValue>;
+    private promise;
+    private readonly invokable;
+    /**
+     * @example
+     * ```ts
+     * import { Task, retry } from "@daiso-tech/core/task";
+     *
+     * const promise = new Task(async () => {
+     *   console.log("I am lazy");
+     * },
+     *   // You can also pass in one AsyncMiddleware or multiple (as an Array).
+     *   retry()
+     * );
+     *
+     * // "I am lazy" will only logged when awaited or then method i called.
+     * await promise;
+     * ```
+     *
+     * You can pass sync or async {@link Invokable | `Invokable`}.
+     */
+    constructor(invokable: AsyncLazy<TValue>, middlewares?: OneOrMore<AsyncMiddleware<[], TValue>>);
+    /**
+     * The `pipe` method returns a new `Task` instance with the additional `middlewares` applied.
+     */
+    pipe(middlewares: OneOrMore<AsyncMiddleware<[], TValue>>): Task<TValue>;
+    /**
+     * The `pipeWhen` method conditionally applies additional `middlewares`, returning a new `Task` instance only if the specified condition is met.
+     */
+    pipeWhen(condition: boolean, middlewares: OneOrMore<AsyncMiddleware<[], TValue>>): Task<TValue>;
+    then<TResult1 = TValue, TResult2 = never>(onfulfilled?: ((value: TValue) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * The `detach` method executes the `Task` without awaiting it.
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     *
+     * const promise =
+     *   new Task(async () => {
+     *     await Task.delay(TimeSpan.fromSeconds(1));
+     *     // Will be loged after one second
+     *     console.log("Done !");
+     *   });
+     *
+     * promise.detach();
+     *
+     * // Will be logged immediately
+     * console.log("Hello");
+     * await Task.delay(TimeSpan.fromSeconds(2));
+     * ```
+     */
+    detach(): void;
+}

package/dist/task/task.js

@@ -0,0 +1,212 @@
+/**
+ * @module Task
+ */
+import { callInvokable, isPromiseLike, resolveAsyncLazyable, } from "../utilities/_module-exports.js";
+import { abortAndFail } from "../task/abort-and-fail.js";
+import { TimeSpan } from "../time-span/implementations/_module-exports.js";
+import { AsyncHooks } from "../hooks/_module-exports.js";
+/**
+ * The `Task` class is used for creating lazy {@link PromiseLike | `PromiseLike`} object that will only execute when awaited or when `then` method is called.
+ * Note the class is immutable.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/task"`
+ */
+export class Task {
+    /**
+     * The `wrapFn` is convience method used for wrapping async {@link Invokable | `Invokable`} with a `Task`.
+     * @example
+     * ```ts
+     * import { Task, retry } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     * import { readFile as readFileNodeJs } from "node:fs/promises";
+     *
+     * const readFile = Task.wrapFn(readFileNodeJs);
+     *
+     * const file = await readFile("none_existing_file.txt");
+     * ```
+     */
+    static wrapFn(fn) {
+        return (...parameters) => new Task(() => callInvokable(fn, ...parameters));
+    }
+    /**
+     * The `delay` method creates a {@link Task | `Task`} that will be fulfilled after given `time`.
+     *
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     *
+     * console.log("a");
+     * await Task.delay(TimeSpan.fromSeconds(2));
+     * console.log("b");
+     * ```
+     */
+    static delay(time, abortSignal = new AbortController().signal) {
+        return new Task(async () => {
+            let timeoutId = null;
+            try {
+                await abortAndFail(new Promise((resolve) => {
+                    timeoutId = setTimeout(() => {
+                        resolve();
+                    }, TimeSpan.fromTimeSpan(time).toMilliseconds());
+                }), abortSignal);
+            }
+            finally {
+                if (timeoutId !== null) {
+                    clearTimeout(timeoutId);
+                }
+            }
+        });
+    }
+    /**
+     * The `resolve` method works similarly to {@link Promise.resolve | `Promise.resolve`} with the key distinction that it operates lazily.
+     */
+    static resolve(value) {
+        return new Task(async () => {
+            if (value === undefined) {
+                return;
+            }
+            return await value;
+        });
+    }
+    /**
+     * The `reject` method works similarly to {@link Promise.reject | `Promise.reject`} with the key distinction that it operates lazily.
+     */
+    static reject(reason) {
+        return new Task(async () => {
+            // eslint-disable-next-line @typescript-eslint/prefer-promise-reject-errors
+            return Promise.reject(reason);
+        });
+    }
+    static toTasks(promises) {
+        const tasks = [];
+        for (const promise of promises) {
+            if (promise instanceof Task) {
+                tasks.push(promise);
+            }
+            if (!isPromiseLike(promise)) {
+                tasks.push(Task.resolve(promise));
+            }
+            throw new TypeError("!!__MESSAGE__!!");
+        }
+        return tasks;
+    }
+    /**
+     * The `all` method works similarly to {@link Promise.all | `Promise.all`} with the key distinction that it operates lazily.
+     */
+    static all(tasks) {
+        return new Task(async () => Promise.all(Task.toTasks(tasks)));
+    }
+    /**
+     * The `allSettled` method works similarly to {@link Promise.allSettled | `Promise.allSettled`} with the key distinction that it operates lazily.
+     */
+    static allSettled(tasks) {
+        return new Task(async () => Promise.allSettled(Task.toTasks(tasks)));
+    }
+    /**
+     * The `race` method works similarly to {@link Promise.race | `Promise.race`} with the key distinction that it operates lazily.
+     */
+    static race(tasks) {
+        return new Task(async () => Promise.race(Task.toTasks(tasks)));
+    }
+    /**
+     * The `any` method works similarly to {@link Promise.any | `Promise.any`} with the key distinction that it operates lazily.
+     */
+    static any(tasks) {
+        return new Task(async () => Promise.any(Task.toTasks(tasks)));
+    }
+    /**
+     * The `fromCallback` is convience method used for wrapping Node js callback functions with a `Task`.
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { readFile } from "node:fs";
+     *
+     * const task = Task.fromCallback<Buffer  | string>((resolve, reject) => {
+     *   readFile("FILE_PATH", (err, data) => {
+     *     if (err !== null) {
+     *       reject(err);
+     *       return;
+     *     }
+     *     resolve(data);
+     *   });
+     * });
+     * const file = await task;
+     * console.log(file);
+     * ```
+     */
+    static fromCallback(callback) {
+        return new Task(() => new Promise((resolve, reject) => {
+            callback(resolve, reject);
+        }));
+    }
+    promise = null;
+    invokable;
+    /**
+     * @example
+     * ```ts
+     * import { Task, retry } from "@daiso-tech/core/task";
+     *
+     * const promise = new Task(async () => {
+     *   console.log("I am lazy");
+     * },
+     *   // You can also pass in one AsyncMiddleware or multiple (as an Array).
+     *   retry()
+     * );
+     *
+     * // "I am lazy" will only logged when awaited or then method i called.
+     * await promise;
+     * ```
+     *
+     * You can pass sync or async {@link Invokable | `Invokable`}.
+     */
+    constructor(invokable, middlewares = []) {
+        this.invokable = new AsyncHooks(async () => {
+            return await resolveAsyncLazyable(invokable);
+        }, middlewares);
+    }
+    /**
+     * The `pipe` method returns a new `Task` instance with the additional `middlewares` applied.
+     */
+    pipe(middlewares) {
+        return new Task(this.invokable.pipe(middlewares));
+    }
+    /**
+     * The `pipeWhen` method conditionally applies additional `middlewares`, returning a new `Task` instance only if the specified condition is met.
+     */
+    pipeWhen(condition, middlewares) {
+        return new Task(this.invokable.pipeWhen(condition, middlewares));
+    }
+    then(onfulfilled, onrejected) {
+        if (this.promise === null) {
+            this.promise = this.invokable.invoke();
+        }
+        // eslint-disable-next-line @typescript-eslint/use-unknown-in-catch-callback-variable
+        return this.promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * The `detach` method executes the `Task` without awaiting it.
+     * @example
+     * ```ts
+     * import { Task } from "@daiso-tech/core/task";
+     * import { TimeSpan } from "@daiso-tech/core/time-span" from "@daiso-tech/core/time-span";
+     *
+     * const promise =
+     *   new Task(async () => {
+     *     await Task.delay(TimeSpan.fromSeconds(1));
+     *     // Will be loged after one second
+     *     console.log("Done !");
+     *   });
+     *
+     * promise.detach();
+     *
+     * // Will be logged immediately
+     * console.log("Hello");
+     * await Task.delay(TimeSpan.fromSeconds(2));
+     * ```
+     */
+    detach() {
+        this.then(() => { });
+    }
+}
+//# sourceMappingURL=task.js.map

package/dist/task/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/task/task.ts"],"names":[],"mappings":"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"}

package/dist/time-span/contracts/_module-exports.d.ts

@@ -0,0 +1 @@
+export * from "../../time-span/contracts/time-span.contract.js";

package/dist/time-span/contracts/_module-exports.js

@@ -0,0 +1,2 @@
+export * from "../../time-span/contracts/time-span.contract.js";
+//# sourceMappingURL=_module-exports.js.map

package/dist/time-span/contracts/_module-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_module-exports.js","sourceRoot":"","sources":["../../../src/time-span/contracts/_module-exports.ts"],"names":[],"mappings":"AAAA,cAAc,6CAA6C,CAAC"}

package/dist/time-span/contracts/time-span.contract.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module TimeSpan
+ */
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/time-span/contracts"`
+ * @group Contracts
+ */
+export declare const TO_MILLISECONDS: unique symbol;
+/**
+ * The `ITimeSpan` contract enables interoperability with external time libraries (e.g., `Luxon`, `Dayjs`).
+ * To integrate, simply implement `ITimeSpan` on the duration objects of those libraries.
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/time-span/contracts"`
+ * @group Contracts
+ */
+export type ITimeSpan = {
+    [TO_MILLISECONDS](): number;
+};

package/dist/time-span/contracts/time-span.contract.js

@@ -0,0 +1,10 @@
+/**
+ * @module TimeSpan
+ */
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/time-span/contracts"`
+ * @group Contracts
+ */
+export const TO_MILLISECONDS = Symbol("TO_MILLISECONDS");
+//# sourceMappingURL=time-span.contract.js.map

package/dist/time-span/contracts/time-span.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-span.contract.js","sourceRoot":"","sources":["../../../src/time-span/contracts/time-span.contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC"}

package/dist/time-span/implementations/_module-exports.d.ts

@@ -0,0 +1 @@
+export * from "../../time-span/implementations/time-span.js";

package/dist/time-span/implementations/_module-exports.js

@@ -0,0 +1,2 @@
+export * from "../../time-span/implementations/time-span.js";
+//# sourceMappingURL=_module-exports.js.map

package/dist/time-span/implementations/_module-exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_module-exports.js","sourceRoot":"","sources":["../../../src/time-span/implementations/_module-exports.ts"],"names":[],"mappings":"AAAA,cAAc,0CAA0C,CAAC"}

package/dist/{utilities/classes/time-span → time-span/implementations}/time-span.d.ts

@@ -1,44 +1,82 @@
 /**
- * @module Utilities
+ * @module TimeSpan
  */
-import type { ISerializable } from "../../../serde/contracts/_module-exports.js";
+import type { ISerializable } from "../../serde/contracts/_module-exports.js";
+import { TO_MILLISECONDS, type ITimeSpan } from "../../time-span/contracts/_module-exports.js";
+import type { IComparable } from "../../utilities/_module-exports.js";
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/time-span"`
+ * @group Implementations
+ */
+export type SerializedTimeSpan = {
+    version: "1";
+    timeInMs: number;
+};
+/**
+ *
+ * IMPORT_PATH: `"@daiso-tech/core/time-span"`
+ * @group Implementations
+ */
+export type TimeSpanFromDateRangeSettings = {
+    /**
+     * @default
+     * ```ts
+     * new Date()
+     * ```
+     */
+    start?: Date;
+    /**
+     * @default
+     * ```ts
+     * new Date()
+     * ```
+     */
+    end?: Date;
+};
 /**
  * The `TimeSpan` class is used for representing time interval.
  * `TimeSpan` cannot be negative.
  *
- * IMPORT_PATH: `"@daiso-tech/core/utilities"`
- * @group TimeSpan
+ * IMPORT_PATH: `"@daiso-tech/core/time-span"`
+ * @group Implementations
  */
-export declare class TimeSpan implements ISerializable<number> {
+export declare class TimeSpan implements ITimeSpan, ISerializable<SerializedTimeSpan>, IComparable<ITimeSpan> {
     private readonly milliseconds;
     private static secondInMilliseconds;
     private static minuteInMilliseconds;
     private static hourInMilliseconds;
     private static dayInMilliseconds;
-    static deserialize(timeInMs: number): TimeSpan;
+    static deserialize(serializedValue: SerializedTimeSpan): TimeSpan;
     private constructor();
-    serialize(): number;
+    equals(value: ITimeSpan): boolean;
+    gt(value: ITimeSpan): boolean;
+    gte(value: ITimeSpan): boolean;
+    lt(value: ITimeSpan): boolean;
+    lte(value: ITimeSpan): boolean;
+    serialize(): SerializedTimeSpan;
     static fromMilliseconds(milliseconds: number): TimeSpan;
     static fromSeconds(seconds: number): TimeSpan;
     static fromMinutes(minutes: number): TimeSpan;
     static fromHours(hours: number): TimeSpan;
     static fromDays(days: number): TimeSpan;
-    static fromTimeSpan(timeSpan: TimeSpan): TimeSpan;
-    static fromDateRange(from: Date, to: Date): TimeSpan;
+    static fromTimeSpan(timeSpan: ITimeSpan): TimeSpan;
+    static fromDateRange({ start, end, }: TimeSpanFromDateRangeSettings): TimeSpan;
     addMilliseconds(milliseconds: number): TimeSpan;
     addSeconds(seconds: number): TimeSpan;
     addMinutes(minutes: number): TimeSpan;
     addHours(hours: number): TimeSpan;
     addDays(days: number): TimeSpan;
-    addTimeSpan(timeSpan: TimeSpan): TimeSpan;
+    addTimeSpan(timeSpan: ITimeSpan): TimeSpan;
     subtractMilliseconds(milliseconds: number): TimeSpan;
     subtractSeconds(seconds: number): TimeSpan;
     subtractMinutes(minutes: number): TimeSpan;
     subtractHours(hours: number): TimeSpan;
     subtractDays(days: number): TimeSpan;
-    subtractTimeSpan(timeSpan: TimeSpan): TimeSpan;
+    subtractTimeSpan(timeSpan: ITimeSpan): TimeSpan;
     multiply(value: number): TimeSpan;
     divide(value: number): TimeSpan;
+    [TO_MILLISECONDS](): number;
     toMilliseconds(): number;
     toSeconds(): number;
     toMinutes(): number;