@flightlesslabs/time-utils 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0
+- First release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhesh Mangela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @flightlesslabs/time-utils
+
+Date and time utilities at your disposable
+
+## 🔗 Links
+
+- 📚 Docs: https://flightlesslabs.github.io/time-utils
+- 💻 GitHub: https://github.com/flightlesslabs/time-utils
+- 📦 npm: https://www.npmjs.com/package/@flightlesslabs/time-utils
+- 🧩 JSR: https://jsr.io/@flightlesslabs/time-utils
+
+## 🚀 Installation
+
+JSR
+
+```bash
+deno add jsr:@flightlesslabs/time-utils
+```
+
+pnpm
+
+```bash
+pnpm add @flightlesslabs/time-utils
+```
+
+npm
+
+```bash
+npm i @flightlesslabs/time-utils
+```
+
+---
+
+## Docs
+
+Build docs
+
+```bash
+deno task docs
+```
+
+Preview docs
+
+```bash
+deno task preview
+```
+
+## Develop
+
+Publish to npm
+
+```bash
+deno task publish
+```

package/esm/date-creator/createDate/createDate.d.ts

@@ -0,0 +1,19 @@
+declare const createDate: {
+    (): ReturnType<typeof import("dayjs")>;
+    (date: import("../createDateFactory/types.js").CreateDateInput, format?: import("../createDateFactory/types.js").CreateDateFormat, options?: import("../createDateFactory/types.js").CreateDateOptions): ReturnType<typeof import("dayjs")>;
+};
+/**
+ * Default preconfigured `createDate` function using a shared Dayjs instance.
+ *
+ * Provides a ready-to-use API with UTC, timezone, and custom parsing support
+ * without requiring users to configure Dayjs manually.
+ *
+ * @example
+ * ```ts
+ * createDate();
+ * createDate('2024-01-01');
+ * createDate('2024-01-01', undefined, { utc: true });
+ * ```
+ */
+export { createDate };
+//# sourceMappingURL=createDate.d.ts.map

package/esm/date-creator/createDate/createDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDate.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDate/createDate.ts"],"names":[],"mappings":"AAGA,QAAA,MAAQ,UAAU;;;CAAoC,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/esm/date-creator/createDate/createDate.js

@@ -0,0 +1,17 @@
+import { createDateFactory } from '../createDateFactory/createDateFactory.js';
+import defaultDayjs from '../createDateFactory/dayjs.js';
+const { createDate } = createDateFactory(defaultDayjs);
+/**
+ * Default preconfigured `createDate` function using a shared Dayjs instance.
+ *
+ * Provides a ready-to-use API with UTC, timezone, and custom parsing support
+ * without requiring users to configure Dayjs manually.
+ *
+ * @example
+ * ```ts
+ * createDate();
+ * createDate('2024-01-01');
+ * createDate('2024-01-01', undefined, { utc: true });
+ * ```
+ */
+export { createDate };

package/esm/date-creator/createDateFactory/createDateFactory.d.ts

@@ -0,0 +1,39 @@
+import defaultDayjs from './dayjs.js';
+import type { CreateDateFormat, CreateDateInput, CreateDateOptions } from './types.js';
+type Dayjs = typeof defaultDayjs;
+/**
+ * Creates a date factory bound to a specific Dayjs instance.
+ *
+ * This factory wraps a configured Dayjs instance and provides a unified
+ * `createDate` function that supports:
+ *
+ * - UTC parsing (highest priority)
+ * - Timezone-aware parsing
+ * - Local parsing
+ * - Optional strict parsing
+ * - Optional invalid-date throwing
+ *
+ * @param customDayjs - Optional custom Dayjs instance (useful for testing or plugin overrides)
+ *
+ * @returns An object containing:
+ * - `createDate`: Unified date creation function
+ * - `dayjs`: The underlying Dayjs instance used by the factory
+ *
+ * @example
+ * ```ts
+ * const { createDate } = createDateFactory();
+ *
+ * const date = createDate('2024-01-01');
+ * const utcDate = createDate('2024-01-01', undefined, { utc: true });
+ * const tzDate = createDate('2024-01-01', undefined, { timezone: 'Asia/Kolkata' });
+ * ```
+ */
+export declare function createDateFactory(customDayjs?: Dayjs): {
+    createDate: {
+        (): ReturnType<Dayjs>;
+        (date: CreateDateInput, format?: CreateDateFormat, options?: CreateDateOptions): ReturnType<Dayjs>;
+    };
+    dayjs: typeof import("dayjs");
+};
+export {};
+//# sourceMappingURL=createDateFactory.d.ts.map

package/esm/date-creator/createDateFactory/createDateFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDateFactory.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/createDateFactory.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,KAAK,KAAK,GAAG,OAAO,YAAY,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,KAAK;;YAG5B,UAAU,CAAC,KAAK,CAAC;eAEhC,eAAe,WACZ,gBAAgB,YACf,iBAAiB,GAC1B,UAAU,CAAC,KAAK,CAAC;;;EA6DrB"}

package/esm/date-creator/createDateFactory/createDateFactory.js

@@ -0,0 +1,80 @@
+import defaultDayjs from './dayjs.js';
+/**
+ * Creates a date factory bound to a specific Dayjs instance.
+ *
+ * This factory wraps a configured Dayjs instance and provides a unified
+ * `createDate` function that supports:
+ *
+ * - UTC parsing (highest priority)
+ * - Timezone-aware parsing
+ * - Local parsing
+ * - Optional strict parsing
+ * - Optional invalid-date throwing
+ *
+ * @param customDayjs - Optional custom Dayjs instance (useful for testing or plugin overrides)
+ *
+ * @returns An object containing:
+ * - `createDate`: Unified date creation function
+ * - `dayjs`: The underlying Dayjs instance used by the factory
+ *
+ * @example
+ * ```ts
+ * const { createDate } = createDateFactory();
+ *
+ * const date = createDate('2024-01-01');
+ * const utcDate = createDate('2024-01-01', undefined, { utc: true });
+ * const tzDate = createDate('2024-01-01', undefined, { timezone: 'Asia/Kolkata' });
+ * ```
+ */
+export function createDateFactory(customDayjs) {
+    const d = customDayjs ?? defaultDayjs;
+    /**
+     * Creates a Dayjs date instance with optional parsing rules.
+     *
+     * Overloads:
+     * - `createDate()` → current date/time
+     * - `createDate(input, format?, options?)` → parsed date
+     *
+     * @param date - Date input (string, number, Date, Dayjs, etc.)
+     * @param format - Optional format string for parsing
+     * @param options - Parsing and behavior options
+     *
+     * @returns A Dayjs instance
+     *
+     * @throws Error if `throwOnInvalid` is true and the date is invalid
+     *
+     * @example
+     * ```ts
+     * createDate(); // now
+     * createDate('2024-01-01');
+     * createDate('01-01-2024', 'DD-MM-YYYY');
+     *
+     * createDate('2024-01-01', undefined, { utc: true });
+     * createDate('2024-01-01', undefined, { timezone: 'UTC' });
+     * ```
+     */
+    function createDate(date, format, options = {}) {
+        const { timezone, utc, strict = false, throwOnInvalid = false } = options;
+        const input = date ?? undefined;
+        let instance;
+        // 1. UTC takes highest priority
+        if (utc) {
+            instance = format ? d.utc(input, format, strict) : d.utc(input);
+        } // 2. Timezone
+        else if (timezone) {
+            instance = format ? d.tz(input, format, timezone) : d.tz(input, timezone);
+        } // 3. Local
+        else {
+            instance = format ? d(input, format, strict) : d(input);
+        }
+        // 4. Validation
+        if (throwOnInvalid && !instance.isValid()) {
+            throw new Error('Invalid date input');
+        }
+        return instance;
+    }
+    return {
+        createDate,
+        dayjs: d,
+    };
+}

package/esm/date-creator/createDateFactory/dayjs.d.ts

@@ -0,0 +1,4 @@
+import dayjsFactory from 'dayjs';
+declare const dayjs: typeof dayjsFactory;
+export default dayjs;
+//# sourceMappingURL=dayjs.d.ts.map

package/esm/date-creator/createDateFactory/dayjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dayjs.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/dayjs.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,OAAO,CAAC;AAMjC,QAAA,MAAM,KAAK,EAAmB,OAAO,YAAY,CAAC;AA8BlD,eAAe,KAAK,CAAC"}

package/esm/date-creator/createDateFactory/dayjs.js

@@ -0,0 +1,33 @@
+import dayjsFactory from 'dayjs';
+import utcPlugin from 'dayjs/plugin/utc.js';
+import timezonePlugin from 'dayjs/plugin/timezone.js';
+import customParseFormatPlugin from 'dayjs/plugin/customParseFormat.js';
+import isBetweenPlugin from 'dayjs/plugin/isBetween.js';
+const dayjs = dayjsFactory;
+// default plugin setup
+/**
+ * Preconfigured Dayjs instance with commonly used plugins enabled.
+ *
+ * Enabled plugins:
+ * - UTC support
+ * - Timezone support
+ * - Custom parsing formats
+ * - Range checking (`isBetween`)
+ *
+ * This instance is intended to be shared across the application to ensure
+ * consistent date handling behavior.
+ *
+ * @example
+ * ```ts
+ * import dayjs from './dayjs';
+ *
+ * dayjs().utc();
+ * dayjs().tz('Asia/Kolkata');
+ * dayjs('2024-01-01', 'YYYY-MM-DD', true);
+ * ```
+ */
+dayjs.extend(utcPlugin);
+dayjs.extend(timezonePlugin);
+dayjs.extend(customParseFormatPlugin);
+dayjs.extend(isBetweenPlugin);
+export default dayjs;

package/esm/date-creator/createDateFactory/types.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigType } from 'dayjs';
+/**
+ * Supported input types for creating a date.
+ *
+ * Includes all native Dayjs-compatible input types such as:
+ * string, number, Date, Dayjs instance, etc.
+ */
+export type CreateDateInput = ConfigType;
+/**
+ * Optional format string used when parsing a date.
+ *
+ * If provided, Dayjs will parse the input using this format.
+ */
+export type CreateDateFormat = string | undefined;
+/**
+ * Options controlling how a date is parsed and interpreted.
+ */
+export interface CreateDateOptions {
+    /**
+     * Timezone identifier (e.g., "Asia/Kolkata").
+     * Requires Dayjs timezone plugin.
+     */
+    timezone?: string;
+    /**
+     * Forces UTC parsing.
+     * Takes priority over `timezone`.
+     */
+    utc?: boolean;
+    /**
+     * Enables strict parsing mode.
+     * When true, input must exactly match the format.
+     */
+    strict?: boolean;
+    /**
+     * If true, throws an error when the parsed date is invalid.
+     */
+    throwOnInvalid?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/date-creator/createDateFactory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/esm/date-creator/createDateFactory/types.js

@@ -0,0 +1 @@
+export {};

package/esm/mod.d.ts

@@ -0,0 +1,5 @@
+export { timeout } from './timeout/timeout.js';
+export { createDate } from './date-creator/createDate/createDate.js';
+export { createDateFactory } from './date-creator/createDateFactory/createDateFactory.js';
+export type { CreateDateFormat, CreateDateInput, CreateDateOptions, } from './date-creator/createDateFactory/types.js';
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAClB,MAAM,2CAA2C,CAAC"}

package/esm/mod.js

@@ -0,0 +1,3 @@
+export { timeout } from './timeout/timeout.js';
+export { createDate } from './date-creator/createDate/createDate.js';
+export { createDateFactory } from './date-creator/createDateFactory/createDateFactory.js';

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/timeout/timeout.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * Useful for pausing execution in async workflows,
+ * throttling operations, or simulating delays in tests.
+ *
+ * @group Time
+ *
+ * @param milliseconds - Time to wait in milliseconds.
+ * @param value - Optional value to resolve with.
+ *
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * await timeout(1000);
+ *
+ * @example
+ * const result = await timeout(1000, "done");
+ * console.log(result); // "done"
+ */
+export declare function timeout<T = void>(milliseconds: number, value?: T): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/esm/timeout/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/timeout/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ7E"}

package/esm/timeout/timeout.js

@@ -0,0 +1,28 @@
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * Useful for pausing execution in async workflows,
+ * throttling operations, or simulating delays in tests.
+ *
+ * @group Time
+ *
+ * @param milliseconds - Time to wait in milliseconds.
+ * @param value - Optional value to resolve with.
+ *
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * await timeout(1000);
+ *
+ * @example
+ * const result = await timeout(1000, "done");
+ * console.log(result); // "done"
+ */
+export function timeout(milliseconds, value) {
+    if (milliseconds < 0) {
+        return Promise.reject(new Error('Timeout duration must be >= 0'));
+    }
+    return new Promise((resolve) => {
+        setTimeout(() => resolve(value), milliseconds);
+    });
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@flightlesslabs/time-utils",
+  "version": "0.1.0",
+  "description": "Date and time utilities at your disposable",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flightlesslabs/time-utils.git"
+  },
+  "license": "MIT",
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "scripts": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "dayjs": "^1.11.20"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/date-creator/createDate/createDate.d.ts

@@ -0,0 +1,19 @@
+declare const createDate: {
+    (): ReturnType<typeof import("dayjs")>;
+    (date: import("../createDateFactory/types.js").CreateDateInput, format?: import("../createDateFactory/types.js").CreateDateFormat, options?: import("../createDateFactory/types.js").CreateDateOptions): ReturnType<typeof import("dayjs")>;
+};
+/**
+ * Default preconfigured `createDate` function using a shared Dayjs instance.
+ *
+ * Provides a ready-to-use API with UTC, timezone, and custom parsing support
+ * without requiring users to configure Dayjs manually.
+ *
+ * @example
+ * ```ts
+ * createDate();
+ * createDate('2024-01-01');
+ * createDate('2024-01-01', undefined, { utc: true });
+ * ```
+ */
+export { createDate };
+//# sourceMappingURL=createDate.d.ts.map

package/script/date-creator/createDate/createDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDate.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDate/createDate.ts"],"names":[],"mappings":"AAGA,QAAA,MAAQ,UAAU;;;CAAoC,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/script/date-creator/createDate/createDate.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDate = void 0;
+const createDateFactory_js_1 = require("../createDateFactory/createDateFactory.js");
+const dayjs_js_1 = __importDefault(require("../createDateFactory/dayjs.js"));
+const { createDate } = (0, createDateFactory_js_1.createDateFactory)(dayjs_js_1.default);
+exports.createDate = createDate;

package/script/date-creator/createDateFactory/createDateFactory.d.ts

@@ -0,0 +1,39 @@
+import defaultDayjs from './dayjs.js';
+import type { CreateDateFormat, CreateDateInput, CreateDateOptions } from './types.js';
+type Dayjs = typeof defaultDayjs;
+/**
+ * Creates a date factory bound to a specific Dayjs instance.
+ *
+ * This factory wraps a configured Dayjs instance and provides a unified
+ * `createDate` function that supports:
+ *
+ * - UTC parsing (highest priority)
+ * - Timezone-aware parsing
+ * - Local parsing
+ * - Optional strict parsing
+ * - Optional invalid-date throwing
+ *
+ * @param customDayjs - Optional custom Dayjs instance (useful for testing or plugin overrides)
+ *
+ * @returns An object containing:
+ * - `createDate`: Unified date creation function
+ * - `dayjs`: The underlying Dayjs instance used by the factory
+ *
+ * @example
+ * ```ts
+ * const { createDate } = createDateFactory();
+ *
+ * const date = createDate('2024-01-01');
+ * const utcDate = createDate('2024-01-01', undefined, { utc: true });
+ * const tzDate = createDate('2024-01-01', undefined, { timezone: 'Asia/Kolkata' });
+ * ```
+ */
+export declare function createDateFactory(customDayjs?: Dayjs): {
+    createDate: {
+        (): ReturnType<Dayjs>;
+        (date: CreateDateInput, format?: CreateDateFormat, options?: CreateDateOptions): ReturnType<Dayjs>;
+    };
+    dayjs: typeof import("dayjs");
+};
+export {};
+//# sourceMappingURL=createDateFactory.d.ts.map

package/script/date-creator/createDateFactory/createDateFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createDateFactory.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/createDateFactory.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,KAAK,KAAK,GAAG,OAAO,YAAY,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,KAAK;;YAG5B,UAAU,CAAC,KAAK,CAAC;eAEhC,eAAe,WACZ,gBAAgB,YACf,iBAAiB,GAC1B,UAAU,CAAC,KAAK,CAAC;;;EA6DrB"}

package/script/date-creator/createDateFactory/createDateFactory.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDateFactory = createDateFactory;
+const dayjs_js_1 = __importDefault(require("./dayjs.js"));
+/**
+ * Creates a date factory bound to a specific Dayjs instance.
+ *
+ * This factory wraps a configured Dayjs instance and provides a unified
+ * `createDate` function that supports:
+ *
+ * - UTC parsing (highest priority)
+ * - Timezone-aware parsing
+ * - Local parsing
+ * - Optional strict parsing
+ * - Optional invalid-date throwing
+ *
+ * @param customDayjs - Optional custom Dayjs instance (useful for testing or plugin overrides)
+ *
+ * @returns An object containing:
+ * - `createDate`: Unified date creation function
+ * - `dayjs`: The underlying Dayjs instance used by the factory
+ *
+ * @example
+ * ```ts
+ * const { createDate } = createDateFactory();
+ *
+ * const date = createDate('2024-01-01');
+ * const utcDate = createDate('2024-01-01', undefined, { utc: true });
+ * const tzDate = createDate('2024-01-01', undefined, { timezone: 'Asia/Kolkata' });
+ * ```
+ */
+function createDateFactory(customDayjs) {
+    const d = customDayjs ?? dayjs_js_1.default;
+    /**
+     * Creates a Dayjs date instance with optional parsing rules.
+     *
+     * Overloads:
+     * - `createDate()` → current date/time
+     * - `createDate(input, format?, options?)` → parsed date
+     *
+     * @param date - Date input (string, number, Date, Dayjs, etc.)
+     * @param format - Optional format string for parsing
+     * @param options - Parsing and behavior options
+     *
+     * @returns A Dayjs instance
+     *
+     * @throws Error if `throwOnInvalid` is true and the date is invalid
+     *
+     * @example
+     * ```ts
+     * createDate(); // now
+     * createDate('2024-01-01');
+     * createDate('01-01-2024', 'DD-MM-YYYY');
+     *
+     * createDate('2024-01-01', undefined, { utc: true });
+     * createDate('2024-01-01', undefined, { timezone: 'UTC' });
+     * ```
+     */
+    function createDate(date, format, options = {}) {
+        const { timezone, utc, strict = false, throwOnInvalid = false } = options;
+        const input = date ?? undefined;
+        let instance;
+        // 1. UTC takes highest priority
+        if (utc) {
+            instance = format ? d.utc(input, format, strict) : d.utc(input);
+        } // 2. Timezone
+        else if (timezone) {
+            instance = format ? d.tz(input, format, timezone) : d.tz(input, timezone);
+        } // 3. Local
+        else {
+            instance = format ? d(input, format, strict) : d(input);
+        }
+        // 4. Validation
+        if (throwOnInvalid && !instance.isValid()) {
+            throw new Error('Invalid date input');
+        }
+        return instance;
+    }
+    return {
+        createDate,
+        dayjs: d,
+    };
+}

package/script/date-creator/createDateFactory/dayjs.d.ts

@@ -0,0 +1,4 @@
+import dayjsFactory from 'dayjs';
+declare const dayjs: typeof dayjsFactory;
+export default dayjs;
+//# sourceMappingURL=dayjs.d.ts.map

package/script/date-creator/createDateFactory/dayjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dayjs.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/dayjs.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,OAAO,CAAC;AAMjC,QAAA,MAAM,KAAK,EAAmB,OAAO,YAAY,CAAC;AA8BlD,eAAe,KAAK,CAAC"}

package/script/date-creator/createDateFactory/dayjs.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const dayjs_1 = __importDefault(require("dayjs"));
+const utc_js_1 = __importDefault(require("dayjs/plugin/utc.js"));
+const timezone_js_1 = __importDefault(require("dayjs/plugin/timezone.js"));
+const customParseFormat_js_1 = __importDefault(require("dayjs/plugin/customParseFormat.js"));
+const isBetween_js_1 = __importDefault(require("dayjs/plugin/isBetween.js"));
+const dayjs = dayjs_1.default;
+// default plugin setup
+/**
+ * Preconfigured Dayjs instance with commonly used plugins enabled.
+ *
+ * Enabled plugins:
+ * - UTC support
+ * - Timezone support
+ * - Custom parsing formats
+ * - Range checking (`isBetween`)
+ *
+ * This instance is intended to be shared across the application to ensure
+ * consistent date handling behavior.
+ *
+ * @example
+ * ```ts
+ * import dayjs from './dayjs';
+ *
+ * dayjs().utc();
+ * dayjs().tz('Asia/Kolkata');
+ * dayjs('2024-01-01', 'YYYY-MM-DD', true);
+ * ```
+ */
+dayjs.extend(utc_js_1.default);
+dayjs.extend(timezone_js_1.default);
+dayjs.extend(customParseFormat_js_1.default);
+dayjs.extend(isBetween_js_1.default);
+exports.default = dayjs;

package/script/date-creator/createDateFactory/types.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigType } from 'dayjs';
+/**
+ * Supported input types for creating a date.
+ *
+ * Includes all native Dayjs-compatible input types such as:
+ * string, number, Date, Dayjs instance, etc.
+ */
+export type CreateDateInput = ConfigType;
+/**
+ * Optional format string used when parsing a date.
+ *
+ * If provided, Dayjs will parse the input using this format.
+ */
+export type CreateDateFormat = string | undefined;
+/**
+ * Options controlling how a date is parsed and interpreted.
+ */
+export interface CreateDateOptions {
+    /**
+     * Timezone identifier (e.g., "Asia/Kolkata").
+     * Requires Dayjs timezone plugin.
+     */
+    timezone?: string;
+    /**
+     * Forces UTC parsing.
+     * Takes priority over `timezone`.
+     */
+    utc?: boolean;
+    /**
+     * Enables strict parsing mode.
+     * When true, input must exactly match the format.
+     */
+    strict?: boolean;
+    /**
+     * If true, throws an error when the parsed date is invalid.
+     */
+    throwOnInvalid?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/script/date-creator/createDateFactory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/date-creator/createDateFactory/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IAEd;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/script/date-creator/createDateFactory/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/mod.d.ts

@@ -0,0 +1,5 @@
+export { timeout } from './timeout/timeout.js';
+export { createDate } from './date-creator/createDate/createDate.js';
+export { createDateFactory } from './date-creator/createDateFactory/createDateFactory.js';
+export type { CreateDateFormat, CreateDateInput, CreateDateOptions, } from './date-creator/createDateFactory/types.js';
+//# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,iBAAiB,GAClB,MAAM,2CAA2C,CAAC"}

package/script/mod.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDateFactory = exports.createDate = exports.timeout = void 0;
+var timeout_js_1 = require("./timeout/timeout.js");
+Object.defineProperty(exports, "timeout", { enumerable: true, get: function () { return timeout_js_1.timeout; } });
+var createDate_js_1 = require("./date-creator/createDate/createDate.js");
+Object.defineProperty(exports, "createDate", { enumerable: true, get: function () { return createDate_js_1.createDate; } });
+var createDateFactory_js_1 = require("./date-creator/createDateFactory/createDateFactory.js");
+Object.defineProperty(exports, "createDateFactory", { enumerable: true, get: function () { return createDateFactory_js_1.createDateFactory; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/timeout/timeout.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * Useful for pausing execution in async workflows,
+ * throttling operations, or simulating delays in tests.
+ *
+ * @group Time
+ *
+ * @param milliseconds - Time to wait in milliseconds.
+ * @param value - Optional value to resolve with.
+ *
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * await timeout(1000);
+ *
+ * @example
+ * const result = await timeout(1000, "done");
+ * console.log(result); // "done"
+ */
+export declare function timeout<T = void>(milliseconds: number, value?: T): Promise<T>;
+//# sourceMappingURL=timeout.d.ts.map

package/script/timeout/timeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/timeout/timeout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAQ7E"}

package/script/timeout/timeout.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.timeout = timeout;
+/**
+ * Creates a promise that resolves after a specified delay.
+ *
+ * Useful for pausing execution in async workflows,
+ * throttling operations, or simulating delays in tests.
+ *
+ * @group Time
+ *
+ * @param milliseconds - Time to wait in milliseconds.
+ * @param value - Optional value to resolve with.
+ *
+ * @returns A promise that resolves after the delay.
+ *
+ * @example
+ * await timeout(1000);
+ *
+ * @example
+ * const result = await timeout(1000, "done");
+ * console.log(result); // "done"
+ */
+function timeout(milliseconds, value) {
+    if (milliseconds < 0) {
+        return Promise.reject(new Error('Timeout duration must be >= 0'));
+    }
+    return new Promise((resolve) => {
+        setTimeout(() => resolve(value), milliseconds);
+    });
+}