umt 2.15.0 → 2.17.0

package/README.md

@@ -64,10 +64,15 @@ bun add umt
 
 | name | type | description | example |
 |------|------|-------------|---------|
+| debounceAsync | `<A, R>(function_: (...args: A) => Promise<R>, wait: number) => DebouncedAsyncFunction<A, R>` | Debounced async function; latest args win and callers in the window share resolution | `const d = debounceAsync(search, 300); await d("foo");` |
 | defer | `<T>() => Deferred<T>` | Creates a deferred promise with externally accessible resolve and reject | `const d = defer<number>(); d.resolve(42); await d.promise; // 42` |
 | parallel | `<T, U>(limit: number, items: T[], function_: (item: T, index: number) => Promise<U>) => Promise<U[]>` | Executes async functions in parallel with a concurrency limit | `await parallel(2, [1, 2, 3], async (n) => n * 2); // [2, 4, 6]` |
+| pSettled | `<T>(tasks: Iterable<Promise<T> \| (() => Promise<T>)>, limit?: number) => Promise<SettledResult<T>[]>` | Awaits all promises and returns settled results with optional concurrency limit | `await pSettled([Promise.resolve(1), Promise.reject(new Error("x"))]);` |
+| retry | `<T>(function_: () => Promise<T>, options?: RetryOptions) => Promise<T>` | Retries an async function with fixed/linear/exponential backoff, jitter, and AbortSignal | `await retry(() => fetch("/api"), { retries: 5, backoff: "exponential" });` |
 | sleep | `(ms: number) => Promise<void>` | Returns a promise that resolves after the specified milliseconds | `await sleep(1000);` |
+| throttleAsync | `<A, R>(function_: (...args: A) => Promise<R>, wait: number) => ThrottledAsyncFunction<A, R>` | Throttled async function; coalesces concurrent calls into a single inflight promise | `const t = throttleAsync(loadUser, 1000); await t();` |
 | timeout | `<T>(promise: Promise<T>, ms: number) => Promise<T>` | Wraps a promise with a timeout, rejecting if it does not resolve in time | `await timeout(fetch("/api"), 5000);` |
+| waitFor | `<T>(condition: () => T \| Promise<T>, options?: WaitForOptions) => Promise<NonNullable<T>>` | Polls a condition until truthy or timeout | `await waitFor(() => document.querySelector("#root"));` |
 
 ### DataStructure
 
@@ -103,6 +108,15 @@ bun add umt
 
 | name | type | description | example |
 |------|------|-------------|---------|
+| addDuration | `(date: Date, amount: number, unit: DurationUnit) => Date` | Adds a duration to a date; calendar-aware for months and years | `addDuration(new Date("2025-01-31"), 1, "M"); // 2025-02-28` |
+| diff | `(left: Date, right: Date, unit: DurationUnit) => number` | Returns the difference between two dates in the given unit | `diff(new Date("2025-12-31"), new Date("2025-01-01"), "d"); // 364` |
+| endOf | `(date: Date, unit: DateBoundaryUnit) => Date` | Returns a new Date set to the end of the given unit | `endOf(new Date("2025-04-15"), "month"); // 2025-04-30T23:59:59.999` |
+| formatRelative | `(date: Date, baseDate?: Date, locale?: string) => string` | Formats a date relative to a base date using Intl.RelativeTimeFormat | `formatRelative(new Date(Date.now() - 3600_000), new Date(), "en"); // "1 hour ago"` |
+| isBusinessDay | `(date: Date, holidays?: Date[]) => boolean` | Returns true when a weekday and not in the holiday list | `isBusinessDay(new Date("2025-04-21")); // true` |
+| isSameDay | `(left: Date, right: Date) => boolean` | Returns true when two dates are the same calendar day | `isSameDay(new Date("2025-04-15T01:00"), new Date("2025-04-15T23:00")); // true` |
+| isWeekend | `(date: Date) => boolean` | Returns true when Saturday or Sunday | `isWeekend(new Date("2025-04-19")); // true` |
+| startOf | `(date: Date, unit: DateBoundaryUnit) => Date` | Returns a new Date set to the start of the given unit | `startOf(new Date("2025-04-15"), "month"); // 2025-04-01T00:00:00` |
+| subDuration | `(date: Date, amount: number, unit: DurationUnit) => Date` | Subtracts a duration from a date | `subDuration(new Date("2025-03-31"), 1, "M"); // 2025-02-28` |
 | birthday | `<T extends MonTypeInt>(year: number, mon: T, day: DayTypeInt<T>, timeDifference?: HoursTypeInt) => number` | Calculate age based on birthdate | `birthday(2000, 1, 1); // Returns age of someone born on Jan 1, 2000` |
 | dateRange | `(startDate: Date, endDate: Date) => Date[]` | Generate an array containing all dates between the specified start and end dates | `dateRange(new Date('2025-01-01'), new Date('2025-01-03'))` |
 | dayOfWeek | `<T extends MonTypeInt>(properties?: { year?: number; mon?: T; day?: DayTypeInt<T> }, timeDifference?: HoursTypeInt) => number` | Get the day of the week | `dayOfWeek({ year: 2000, mon: 1, day: 1 });` |
@@ -234,6 +248,13 @@ bun add umt
 | omit | `<T extends Record<string, unknown>, K extends keyof T>(object: T, ...keys: K[]) => Omit<T, K>` | Creates an object without the specified keys | `omit({a: 1, b: 2, c: 3}, 'b'); // {a: 1, c: 3}` |
 | pick | `<T extends object, K extends keyof T>(object: T, ...keys: K[]) => Pick<T, K>` | Creates a new object with only the specified properties from the source object | `pick({ id: 1, name: 'Alice', age: 30 }, 'id', 'name'); // { id: 1, name: 'Alice' }` |
 | pickDeep | `<T extends object, K extends PickDeepKey<T>>(object: T, ...keys: K[]) => PickDeep<T>` | Creates a new object by deeply selecting properties from the source object based on specified keys | `pickDeep({ a: { b: { c: 1, d: 2 }, e: 3 }, f: 4 }, 'a.b.c', 'f'); // { a: { b: { c: 1 } }, f: 4 }` |
+| flattenObject | `<T extends Record<string, unknown>>(object: T, separator?: string) => Record<string, unknown>` | Flattens a nested object into path-keyed entries | `flattenObject({ a: { b: { c: 1 } } }); // { "a.b.c": 1 }` |
+| get | `<T>(object: unknown, path: string \| string[], defaultValue?: T) => T \| undefined` | Reads a deeply nested property by path | `get({ a: { b: 1 } }, "a.b"); // 1` |
+| invert | `<K, V>(object: Record<K, V>) => Record<V, K>` | Creates a new object with keys and values swapped | `invert({ a: 1, b: 2 }); // { 1: "a", 2: "b" }` |
+| omitBy | `<T>(object: T, predicate: (value, key) => boolean) => Partial<T>` | Removes entries for which the predicate returns true | `omitBy({ a: 1, b: undefined }, (v) => v === undefined); // { a: 1 }` |
+| pickBy | `<T>(object: T, predicate: (value, key) => boolean) => Partial<T>` | Selects entries for which the predicate returns true | `pickBy({ a: 1, b: 2 }, (v) => v > 1); // { b: 2 }` |
+| set | `<T extends object>(object: T, path: string \| string[], value: unknown) => T` | Sets a deeply nested property by path, mutating the object | `set({}, "a.b.c", 1); // { a: { b: { c: 1 } } }` |
+| unflattenObject | `(flat: Record<string, unknown>, separator?: string) => Record<string, unknown>` | Reconstructs a nested object from path-keyed input | `unflattenObject({ "a.b": 1 }); // { a: { b: 1 } }` |
 
 ### Predicate
 
@@ -245,6 +266,18 @@ bun add umt
 | not | `<T extends unknown[]>(function_: (...args: T) => boolean) => (...args: T) => boolean` | Creates a predicate that negates the given predicate | `const isOdd = not((n: number) => n % 2 === 0); isOdd(3); // true` |
 | some | `<T extends unknown[]>(...predicates: ((...args: T) => boolean)[]) => (...args: T) => boolean` | Creates a predicate that returns true when at least one predicate returns true | `some((n: number) => n === 0, (n) => n < 0)(0); // true` |
 
+### Random
+
+| name | type | description | example |
+|------|------|-------------|---------|
+| randomBoolean | `(probability?: number) => boolean` | Random boolean with optional weight | `randomBoolean(0.9); // true ~90% of the time` |
+| randomChoice | `<T>(items: readonly T[]) => T` | Uniformly random element from an array | `randomChoice(["a", "b", "c"]);` |
+| randomFloat | `(min: number, max: number) => number` | Random float in `[min, max)` | `randomFloat(0, 1);` |
+| randomInt | `(min: number, max: number) => number` | Random integer in `[min, max]` | `randomInt(1, 6); // 1..6` |
+| randomUUID | `() => string` | UUID v4, prefers `crypto.randomUUID` | `randomUUID();` |
+| seededRandom | `(seed: number \| string) => () => number` | Deterministic PRNG (SplitMix32) | `const rand = seededRandom("hello"); rand();` |
+| weightedChoice | `<T>(items: readonly { value: T; weight: number }[]) => T` | Weighted random pick using cumulative binary search | `weightedChoice([{ value: "a", weight: 1 }, { value: "b", weight: 4 }]);` |
+
 ### Simple
 
 | name | type | description | example |
@@ -260,6 +293,15 @@ bun add umt
 | name | type | description | example |
 |------|------|-------------|---------|
 | camelCase | `(str: string) => string` | Converts a string to camelCase | `camelCase("hello-world"); // "helloWorld"` |
+| capitalize | `(str: string) => string` | Capitalizes the first grapheme of a string | `capitalize("hello"); // "Hello"` |
+| dedent | `(str: string \| TemplateStringsArray, ...values: unknown[]) => string` | Removes minimum common leading whitespace; works as a tag | `` dedent`  line` // "line"`` |
+| mask | `(str: string, options?: MaskOptions) => string` | Masks the middle of a string preserving leading/trailing characters | `mask("1234567890", { start: 2, end: 4 }); // "12****7890"` |
+| pascalCase | `(str: string) => string` | Converts a string to PascalCase | `pascalCase("hello-world"); // "HelloWorld"` |
+| snakeCase | `(str: string) => string` | Converts a string to snake_case | `snakeCase("helloWorld"); // "hello_world"` |
+| titleCase | `(str: string) => string` | Converts a string to Title Case | `titleCase("hello world"); // "Hello World"` |
+| uncapitalize | `(str: string) => string` | Lowercases the first grapheme of a string | `uncapitalize("Hello"); // "hello"` |
+| wordCount | `(str: string) => number` | Counts words using `words` boundaries | `wordCount("hello world"); // 2` |
+| words | `(str: string, pattern?: RegExp) => string[]` | Splits a string into words on case boundaries and non-alphanumeric separators | `words("XMLHttpRequest"); // ["XML", "Http", "Request"]` |
 | deleteSpaces | `(string_: string) => string` | Removes all whitespace characters from a string | `deleteSpaces("Hello World"); // "HelloWorld"` |
 | escapeHtml | `(str: string) => string` | Escapes HTML special characters in a string | `escapeHtml("<script>alert('XSS')</script>"); // "&lt;script&gt;alert(&#39;XSS&#39;)&lt;/script&gt;"` |
 | formatString | `(template: string, ...values: unknown[]) => string` | Replaces placeholders in a template string with specified values | `formatString("Hello, {0}!", "World"); // "Hello, World!"` |

package/module/Array/chunk.js.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/Array/chunk.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,KAAQ,EACR,CAAI,EACkB,EAAE;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAE7D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3D,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAmB,CAAC;IAC9D,CAAC;IAED,OAAO,MAA8B,CAAC;AACxC,CAAC,CAAC"}
+{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../src/Array/chunk.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,KAAQ,EACR,CAAI,EACkB,EAAE;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IAE7D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3D,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,MAA8B,CAAC;AACxC,CAAC,CAAC"}

package/module/Array/uniqBy.js.map

@@ -1 +1 @@
-{"version":3,"file":"uniqBy.js","sourceRoot":"","sources":["../../src/Array/uniqBy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,KAAQ,EACR,QAAgC,EAC7B,EAAE;IACL,MAAM,IAAI,GAAG,IAAI,GAAG,EAAK,CAAC;IAC1B,MAAM,MAAM,GAAM,EAAkB,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAS,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}
+{"version":3,"file":"uniqBy.js","sourceRoot":"","sources":["../../src/Array/uniqBy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,KAAQ,EACR,QAAgC,EAC7B,EAAE;IACL,MAAM,IAAI,GAAG,IAAI,GAAG,EAAK,CAAC;IAC1B,MAAM,MAAM,GAAM,EAAkB,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/module/Async/debounceAsync.d.ts

@@ -0,0 +1,18 @@
+export interface DebouncedAsyncFunction<A extends unknown[], R> {
+    (...arguments_: A): Promise<R>;
+    cancel: () => void;
+}
+/**
+ * Creates a debounced async function. Subsequent calls within `wait` ms reset
+ * the timer and share a single resolution; the latest arguments win.
+ *
+ * @template A - Argument tuple type
+ * @template R - Resolved value type
+ * @param {(...args: A) => Promise<R>} function_ - Async function to debounce
+ * @param {number} wait - Debounce window in milliseconds
+ * @returns {DebouncedAsyncFunction<A, R>} Debounced wrapper with cancel support
+ * @example
+ * const search = debounceAsync(query, 300);
+ * await search("foo");
+ */
+export declare const debounceAsync: <A extends unknown[], R>(function_: (...arguments_: A) => Promise<R>, wait: number) => DebouncedAsyncFunction<A, R>;

package/module/Async/debounceAsync.js

@@ -0,0 +1,59 @@
+/**
+ * Creates a debounced async function. Subsequent calls within `wait` ms reset
+ * the timer and share a single resolution; the latest arguments win.
+ *
+ * @template A - Argument tuple type
+ * @template R - Resolved value type
+ * @param {(...args: A) => Promise<R>} function_ - Async function to debounce
+ * @param {number} wait - Debounce window in milliseconds
+ * @returns {DebouncedAsyncFunction<A, R>} Debounced wrapper with cancel support
+ * @example
+ * const search = debounceAsync(query, 300);
+ * await search("foo");
+ */
+export const debounceAsync = (function_, wait) => {
+    let timer;
+    let pendingResolvers = [];
+    let pendingRejecters = [];
+    const flushPromises = () => {
+        const resolvers = pendingResolvers;
+        const rejecters = pendingRejecters;
+        pendingResolvers = [];
+        pendingRejecters = [];
+        return { resolvers, rejecters };
+    };
+    const debounced = ((...arguments_) => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        return new Promise((resolve, reject) => {
+            pendingResolvers.push(resolve);
+            pendingRejecters.push(reject);
+            timer = setTimeout(() => {
+                timer = undefined;
+                const { resolvers, rejecters } = flushPromises();
+                function_(...arguments_).then((value) => {
+                    for (const resolver of resolvers) {
+                        resolver(value);
+                    }
+                }, (error) => {
+                    for (const rejecter of rejecters) {
+                        rejecter(error);
+                    }
+                });
+            }, wait);
+        });
+    });
+    debounced.cancel = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        const { rejecters } = flushPromises();
+        for (const rejecter of rejecters) {
+            rejecter(new Error("debounceAsync cancelled"));
+        }
+    };
+    return debounced;
+};
+//# sourceMappingURL=debounceAsync.js.map

package/module/Async/debounceAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounceAsync.js","sourceRoot":"","sources":["../../src/Async/debounceAsync.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,SAA2C,EAC3C,IAAY,EACkB,EAAE;IAChC,IAAI,KAAgD,CAAC;IACrD,IAAI,gBAAgB,GAA2B,EAAE,CAAC;IAClD,IAAI,gBAAgB,GAAkC,EAAE,CAAC;IAEzD,MAAM,aAAa,GAAG,GAGpB,EAAE;QACF,MAAM,SAAS,GAAG,gBAAgB,CAAC;QACnC,MAAM,SAAS,GAAG,gBAAgB,CAAC;QACnC,gBAAgB,GAAG,EAAE,CAAC;QACtB,gBAAgB,GAAG,EAAE,CAAC;QACtB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;IAClC,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,UAAa,EAAc,EAAE;QAClD,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9B,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,KAAK,GAAG,SAAS,CAAC;gBAClB,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,aAAa,EAAE,CAAC;gBACjD,SAAS,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAC3B,CAAC,KAAK,EAAE,EAAE;oBACR,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;wBACjC,QAAQ,CAAC,KAAK,CAAC,CAAC;oBAClB,CAAC;gBACH,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;oBACR,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;wBACjC,QAAQ,CAAC,KAAK,CAAC,CAAC;oBAClB,CAAC;gBACH,CAAC,CACF,CAAC;YACJ,CAAC,EAAE,IAAI,CAAC,CAAC;QACX,CAAC,CAAC,CAAC;IACL,CAAC,CAAiC,CAAC;IAEnC,SAAS,CAAC,MAAM,GAAG,GAAS,EAAE;QAC5B,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,GAAG,aAAa,EAAE,CAAC;QACtC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/module/Async/index.d.ts

@@ -1,4 +1,9 @@
+export * from "./debounceAsync";
 export * from "./defer";
 export * from "./parallel";
+export * from "./pSettled";
+export * from "./retry";
 export * from "./sleep";
+export * from "./throttleAsync";
 export * from "./timeout";
+export * from "./waitFor";

package/module/Async/index.js

@@ -1,5 +1,10 @@
+export * from "./debounceAsync";
 export * from "./defer";
 export * from "./parallel";
+export * from "./pSettled";
+export * from "./retry";
 export * from "./sleep";
+export * from "./throttleAsync";
 export * from "./timeout";
+export * from "./waitFor";
 //# sourceMappingURL=index.js.map

package/module/Async/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Async/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/Async/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}

package/module/Async/pSettled.d.ts

@@ -0,0 +1,19 @@
+export type SettledResult<T> = {
+    status: "fulfilled";
+    value: T;
+} | {
+    status: "rejected";
+    reason: unknown;
+};
+/**
+ * Awaits all promises and returns their settled results, with an optional
+ * concurrency limit applied during execution.
+ *
+ * @template T - Resolved value type
+ * @param {Iterable<Promise<T> | (() => Promise<T>)>} tasks - Promises or thunks
+ * @param {number} [limit] - Maximum concurrent in-flight tasks; unlimited when omitted
+ * @returns {Promise<SettledResult<T>[]>} Settled results in input order
+ * @example
+ * await pSettled([Promise.resolve(1), Promise.reject(new Error("x"))]);
+ */
+export declare const pSettled: <T>(tasks: Iterable<Promise<T> | (() => Promise<T>)>, limit?: number) => Promise<SettledResult<T>[]>;

package/module/Async/pSettled.js

@@ -0,0 +1,54 @@
+/**
+ * Awaits all promises and returns their settled results, with an optional
+ * concurrency limit applied during execution.
+ *
+ * @template T - Resolved value type
+ * @param {Iterable<Promise<T> | (() => Promise<T>)>} tasks - Promises or thunks
+ * @param {number} [limit] - Maximum concurrent in-flight tasks; unlimited when omitted
+ * @returns {Promise<SettledResult<T>[]>} Settled results in input order
+ * @example
+ * await pSettled([Promise.resolve(1), Promise.reject(new Error("x"))]);
+ */
+export const pSettled = (tasks, limit) => {
+    const items = [...tasks];
+    const results = Array.from({ length: items.length });
+    if (items.length === 0) {
+        return Promise.resolve(results);
+    }
+    const effectiveLimit = limit && limit > 0 ? limit : items.length;
+    let nextIndex = 0;
+    let resolvedCount = 0;
+    return new Promise((resolve) => {
+        const runNext = () => {
+            if (nextIndex >= items.length) {
+                return;
+            }
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            const task = items[currentIndex];
+            const promise = typeof task === "function"
+                ? Promise.resolve().then(task)
+                : Promise.resolve(task);
+            promise
+                .then((value) => {
+                results[currentIndex] = { status: "fulfilled", value };
+            }, (error) => {
+                results[currentIndex] = { status: "rejected", reason: error };
+            })
+                .then(() => {
+                resolvedCount += 1;
+                if (resolvedCount === items.length) {
+                    resolve(results);
+                }
+                else {
+                    runNext();
+                }
+            });
+        };
+        const initialBatch = Math.min(effectiveLimit, items.length);
+        for (let index = 0; index < initialBatch; index += 1) {
+            runNext();
+        }
+    });
+};
+//# sourceMappingURL=pSettled.js.map

package/module/Async/pSettled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pSettled.js","sourceRoot":"","sources":["../../src/Async/pSettled.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,KAAgD,EAChD,KAAc,EACe,EAAE;IAC/B,MAAM,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;IACzB,MAAM,OAAO,GAAuB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IACjE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,aAAa,GAAG,CAAC,CAAC;IAEtB,OAAO,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,EAAE;QACjD,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,SAAS,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBAC9B,OAAO;YACT,CAAC;YACD,MAAM,YAAY,GAAG,SAAS,CAAC;YAC/B,SAAS,IAAI,CAAC,CAAC;YACf,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;YACjC,MAAM,OAAO,GACX,OAAO,IAAI,KAAK,UAAU;gBACxB,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;gBAC9B,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAE5B,OAAO;iBACJ,IAAI,CACH,CAAC,KAAK,EAAE,EAAE;gBACR,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YACzD,CAAC,EACD,CAAC,KAAK,EAAE,EAAE;gBACR,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;YAChE,CAAC,CACF;iBACA,IAAI,CAAC,GAAG,EAAE;gBACT,aAAa,IAAI,CAAC,CAAC;gBACnB,IAAI,aAAa,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;oBACnC,OAAO,CAAC,OAAO,CAAC,CAAC;gBACnB,CAAC;qBAAM,CAAC;oBACN,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,CAAC;QACP,CAAC,CAAC;QAEF,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5D,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,YAAY,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACrD,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/module/Async/retry.d.ts

@@ -0,0 +1,22 @@
+export interface RetryOptions {
+    retries?: number;
+    delay?: number;
+    backoff?: "fixed" | "exponential" | "linear";
+    jitter?: boolean;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    onRetry?: (error: unknown, attempt: number) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Retries an async function until it succeeds or the retry budget is exhausted.
+ * Supports fixed, linear, or exponential backoff, optional jitter, and
+ * AbortSignal cancellation.
+ *
+ * @template T - Return type of the function
+ * @param {() => Promise<T>} function_ - The async function to invoke
+ * @param {RetryOptions} [options] - Retry configuration
+ * @returns {Promise<T>} Result of the first successful invocation
+ * @example
+ * await retry(() => fetch("/api"), { retries: 5, backoff: "exponential", jitter: true });
+ */
+export declare const retry: <T>(function_: () => Promise<T>, options?: RetryOptions) => Promise<T>;

package/module/Async/retry.js

@@ -0,0 +1,49 @@
+import { sleep } from "./sleep";
+const computeDelay = (baseDelay, attemptNumber, backoff, jitter) => {
+    let waitMs = baseDelay;
+    if (backoff === "linear") {
+        waitMs = baseDelay * attemptNumber;
+    }
+    else if (backoff === "exponential") {
+        waitMs = baseDelay * 2 ** (attemptNumber - 1);
+    }
+    if (jitter) {
+        waitMs *= Math.random();
+    }
+    return waitMs;
+};
+/**
+ * Retries an async function until it succeeds or the retry budget is exhausted.
+ * Supports fixed, linear, or exponential backoff, optional jitter, and
+ * AbortSignal cancellation.
+ *
+ * @template T - Return type of the function
+ * @param {() => Promise<T>} function_ - The async function to invoke
+ * @param {RetryOptions} [options] - Retry configuration
+ * @returns {Promise<T>} Result of the first successful invocation
+ * @example
+ * await retry(() => fetch("/api"), { retries: 5, backoff: "exponential", jitter: true });
+ */
+export const retry = async (function_, options = {}) => {
+    const { retries = 3, delay = 1000, backoff = "fixed", jitter = false, shouldRetry = () => true, onRetry, signal, } = options;
+    let attemptNumber = 0;
+    while (true) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Aborted");
+        }
+        try {
+            // biome-ignore lint/performance/noAwaitInLoops: retry must await sequentially
+            return await function_();
+        }
+        catch (error) {
+            const remaining = retries - attemptNumber;
+            if (remaining <= 0 || !shouldRetry(error, attemptNumber)) {
+                throw error;
+            }
+            onRetry?.(error, attemptNumber);
+            await sleep(computeDelay(delay, attemptNumber + 1, backoff, jitter));
+            attemptNumber += 1;
+        }
+    }
+};
+//# sourceMappingURL=retry.js.map

package/module/Async/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/Async/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYhC,MAAM,YAAY,GAAG,CACnB,SAAiB,EACjB,aAAqB,EACrB,OAA6C,EAC7C,MAAe,EACP,EAAE;IACV,IAAI,MAAM,GAAG,SAAS,CAAC;IACvB,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzB,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC;IACrC,CAAC;SAAM,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;QACrC,MAAM,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,EACxB,SAA2B,EAC3B,UAAwB,EAAE,EACd,EAAE;IACd,MAAM,EACJ,OAAO,GAAG,CAAC,EACX,KAAK,GAAG,IAAI,EACZ,OAAO,GAAG,OAAO,EACjB,MAAM,GAAG,KAAK,EACd,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,EACxB,OAAO,EACP,MAAM,GACP,GAAG,OAAO,CAAC;IAEZ,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC;YACH,8EAA8E;YAC9E,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;YAC1C,IAAI,SAAS,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;gBACzD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;YAChC,MAAM,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YACrE,aAAa,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC,CAAC"}

package/module/Async/throttleAsync.d.ts

@@ -0,0 +1,18 @@
+export interface ThrottledAsyncFunction<A extends unknown[], R> {
+    (...arguments_: A): Promise<R>;
+    cancel: () => void;
+}
+/**
+ * Creates a throttled async function. Coalesces concurrent calls within the
+ * `wait` window so only one underlying invocation runs; all callers in the
+ * window receive the same result.
+ *
+ * @template A - Argument tuple type
+ * @template R - Resolved value type
+ * @param {(...args: A) => Promise<R>} function_ - Async function to throttle
+ * @param {number} wait - Window length in milliseconds
+ * @returns {ThrottledAsyncFunction<A, R>} Throttled wrapper with cancel support
+ * @example
+ * const fetchUser = throttleAsync(loadUser, 1000);
+ */
+export declare const throttleAsync: <A extends unknown[], R>(function_: (...arguments_: A) => Promise<R>, wait: number) => ThrottledAsyncFunction<A, R>;

package/module/Async/throttleAsync.js

@@ -0,0 +1,41 @@
+/**
+ * Creates a throttled async function. Coalesces concurrent calls within the
+ * `wait` window so only one underlying invocation runs; all callers in the
+ * window receive the same result.
+ *
+ * @template A - Argument tuple type
+ * @template R - Resolved value type
+ * @param {(...args: A) => Promise<R>} function_ - Async function to throttle
+ * @param {number} wait - Window length in milliseconds
+ * @returns {ThrottledAsyncFunction<A, R>} Throttled wrapper with cancel support
+ * @example
+ * const fetchUser = throttleAsync(loadUser, 1000);
+ */
+export const throttleAsync = (function_, wait) => {
+    let inflight;
+    let lockedUntil = 0;
+    const throttled = ((...arguments_) => {
+        if (inflight) {
+            return inflight;
+        }
+        if (Date.now() < lockedUntil) {
+            return Promise.reject(new Error("throttleAsync window not elapsed"));
+        }
+        const current = function_(...arguments_);
+        inflight = current;
+        const cleanup = () => {
+            if (inflight === current) {
+                inflight = undefined;
+                lockedUntil = Date.now() + wait;
+            }
+        };
+        current.then(cleanup, cleanup);
+        return current;
+    });
+    throttled.cancel = () => {
+        inflight = undefined;
+        lockedUntil = 0;
+    };
+    return throttled;
+};
+//# sourceMappingURL=throttleAsync.js.map

package/module/Async/throttleAsync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"throttleAsync.js","sourceRoot":"","sources":["../../src/Async/throttleAsync.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,SAA2C,EAC3C,IAAY,EACkB,EAAE;IAChC,IAAI,QAAgC,CAAC;IACrC,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,UAAa,EAAc,EAAE;QAClD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,EAAE,CAAC;YAC7B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,UAAU,CAAC,CAAC;QACzC,QAAQ,GAAG,OAAO,CAAC;QACnB,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACzB,QAAQ,GAAG,SAAS,CAAC;gBACrB,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;YAClC,CAAC;QACH,CAAC,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,OAAO,CAAC;IACjB,CAAC,CAAiC,CAAC;IAEnC,SAAS,CAAC,MAAM,GAAG,GAAS,EAAE;QAC5B,QAAQ,GAAG,SAAS,CAAC;QACrB,WAAW,GAAG,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC"}

package/module/Async/waitFor.d.ts

@@ -0,0 +1,18 @@
+export interface WaitForOptions {
+    timeout?: number;
+    interval?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Repeatedly evaluates a condition until it returns a truthy value or the
+ * timeout elapses. Resolves with the final truthy value.
+ *
+ * @template T - Truthy result type
+ * @param {() => T | Promise<T>} condition - Condition predicate
+ * @param {WaitForOptions} [options] - Polling configuration
+ * @returns {Promise<NonNullable<T>>} The first truthy value
+ * @throws {Error} When the timeout elapses or the signal aborts
+ * @example
+ * await waitFor(() => document.querySelector("#root"), { interval: 100 });
+ */
+export declare const waitFor: <T>(condition: () => T | Promise<T>, options?: WaitForOptions) => Promise<NonNullable<T>>;

package/module/Async/waitFor.js

@@ -0,0 +1,32 @@
+import { sleep } from "./sleep";
+/**
+ * Repeatedly evaluates a condition until it returns a truthy value or the
+ * timeout elapses. Resolves with the final truthy value.
+ *
+ * @template T - Truthy result type
+ * @param {() => T | Promise<T>} condition - Condition predicate
+ * @param {WaitForOptions} [options] - Polling configuration
+ * @returns {Promise<NonNullable<T>>} The first truthy value
+ * @throws {Error} When the timeout elapses or the signal aborts
+ * @example
+ * await waitFor(() => document.querySelector("#root"), { interval: 100 });
+ */
+export const waitFor = async (condition, options = {}) => {
+    const { timeout = 5000, interval = 100, signal } = options;
+    const startTime = Date.now();
+    while (true) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Aborted");
+        }
+        // biome-ignore lint/performance/noAwaitInLoops: waitFor polls sequentially
+        const value = await condition();
+        if (value) {
+            return value;
+        }
+        if (Date.now() - startTime >= timeout) {
+            throw new Error(`waitFor timed out after ${timeout}ms`);
+        }
+        await sleep(interval);
+    }
+};
+//# sourceMappingURL=waitFor.js.map

package/module/Async/waitFor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waitFor.js","sourceRoot":"","sources":["../../src/Async/waitFor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAQhC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAC1B,SAA+B,EAC/B,UAA0B,EAAE,EACH,EAAE;IAC3B,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,2EAA2E;QAC3E,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;QAChC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,CAAC;AACH,CAAC,CAAC"}

package/module/Date/addDuration.d.ts

@@ -0,0 +1,15 @@
+import type { DurationUnit } from "./durationUnit";
+/**
+ * Adds a duration to a date and returns a new Date.
+ * Calendar-aware for "M" (months) and "y" (years), so end-of-month
+ * is preserved (e.g. Jan 31 + 1 month = Feb 28/29).
+ *
+ * @param {Date} date - Base date
+ * @param {number} amount - Amount to add (can be negative)
+ * @param {DurationUnit} unit - Unit of the amount
+ * @returns {Date} A new Date with the duration added
+ * @example
+ * addDuration(new Date("2025-01-31"), 1, "M"); // 2025-02-28
+ * addDuration(new Date("2025-01-01"), 7, "d"); // 2025-01-08
+ */
+export declare const addDuration: (date: Date, amount: number, unit: DurationUnit) => Date;

package/module/Date/addDuration.js

@@ -0,0 +1,40 @@
+import { msByUnit } from "./msByUnit";
+/**
+ * Adds a duration to a date and returns a new Date.
+ * Calendar-aware for "M" (months) and "y" (years), so end-of-month
+ * is preserved (e.g. Jan 31 + 1 month = Feb 28/29).
+ *
+ * @param {Date} date - Base date
+ * @param {number} amount - Amount to add (can be negative)
+ * @param {DurationUnit} unit - Unit of the amount
+ * @returns {Date} A new Date with the duration added
+ * @example
+ * addDuration(new Date("2025-01-31"), 1, "M"); // 2025-02-28
+ * addDuration(new Date("2025-01-01"), 7, "d"); // 2025-01-08
+ */
+export const addDuration = (date, amount, unit) => {
+    const ms = msByUnit[unit];
+    if (ms !== undefined) {
+        return new Date(date.getTime() + amount * ms);
+    }
+    const result = new Date(date);
+    if (unit === "M") {
+        const targetMonth = result.getMonth() + amount;
+        const day = result.getDate();
+        result.setDate(1);
+        result.setMonth(targetMonth);
+        const lastDayOfTargetMonth = new Date(result.getFullYear(), result.getMonth() + 1, 0).getDate();
+        result.setDate(Math.min(day, lastDayOfTargetMonth));
+        return result;
+    }
+    const targetYear = result.getFullYear() + amount;
+    const month = result.getMonth();
+    const day = result.getDate();
+    result.setDate(1);
+    result.setFullYear(targetYear);
+    result.setMonth(month);
+    const lastDayOfTargetMonth = new Date(targetYear, month + 1, 0).getDate();
+    result.setDate(Math.min(day, lastDayOfTargetMonth));
+    return result;
+};
+//# sourceMappingURL=addDuration.js.map

package/module/Date/addDuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"addDuration.js","sourceRoot":"","sources":["../../src/Date/addDuration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,IAAU,EACV,MAAc,EACd,IAAkB,EACZ,EAAE;IACR,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,EAAE,GAAG,MAAM,CAAC;QAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAClB,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC7B,MAAM,oBAAoB,GAAG,IAAI,IAAI,CACnC,MAAM,CAAC,WAAW,EAAE,EACpB,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,EACrB,CAAC,CACF,CAAC,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACvB,MAAM,oBAAoB,GAAG,IAAI,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1E,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}

package/module/Date/diff.d.ts

@@ -0,0 +1,14 @@
+import type { DurationUnit } from "./durationUnit";
+/**
+ * Returns the difference between two dates in the given unit, truncated toward zero.
+ * Calendar-aware for "M" (months) and "y" (years).
+ *
+ * @param {Date} left - End date
+ * @param {Date} right - Start date
+ * @param {DurationUnit} unit - Unit of the result
+ * @returns {number} The difference, truncated toward zero
+ * @example
+ * diff(new Date("2025-12-31"), new Date("2025-01-01"), "d"); // 364
+ * diff(new Date("2026-01-01"), new Date("2025-01-01"), "y"); // 1
+ */
+export declare const diff: (left: Date, right: Date, unit: DurationUnit) => number;

package/module/Date/diff.js

@@ -0,0 +1,45 @@
+import { OneHourMs, OneMinuteMs, OneSecondMs } from "../Consts/clock";
+import { msByUnit } from "./msByUnit";
+/**
+ * Returns the difference between two dates in the given unit, truncated toward zero.
+ * Calendar-aware for "M" (months) and "y" (years).
+ *
+ * @param {Date} left - End date
+ * @param {Date} right - Start date
+ * @param {DurationUnit} unit - Unit of the result
+ * @returns {number} The difference, truncated toward zero
+ * @example
+ * diff(new Date("2025-12-31"), new Date("2025-01-01"), "d"); // 364
+ * diff(new Date("2026-01-01"), new Date("2025-01-01"), "y"); // 1
+ */
+export const diff = (left, right, unit) => {
+    const ms = msByUnit[unit];
+    if (ms !== undefined) {
+        return Math.trunc((left.getTime() - right.getTime()) / ms);
+    }
+    const yearsDelta = left.getFullYear() - right.getFullYear();
+    const monthsDelta = left.getMonth() - right.getMonth();
+    const dayDelta = left.getDate() - right.getDate();
+    const subDayDelta = left.getHours() * OneHourMs +
+        left.getMinutes() * OneMinuteMs +
+        left.getSeconds() * OneSecondMs +
+        left.getMilliseconds() -
+        (right.getHours() * OneHourMs +
+            right.getMinutes() * OneMinuteMs +
+            right.getSeconds() * OneSecondMs +
+            right.getMilliseconds());
+    let calendarMonths = yearsDelta * 12 + monthsDelta;
+    if (calendarMonths > 0 &&
+        (dayDelta < 0 || (dayDelta === 0 && subDayDelta < 0))) {
+        calendarMonths -= 1;
+    }
+    else if (calendarMonths < 0 &&
+        (dayDelta > 0 || (dayDelta === 0 && subDayDelta > 0))) {
+        calendarMonths += 1;
+    }
+    if (unit === "M") {
+        return calendarMonths;
+    }
+    return Math.trunc(calendarMonths / 12);
+};
+//# sourceMappingURL=diff.js.map

package/module/Date/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/Date/diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGtE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,IAAU,EAAE,KAAW,EAAE,IAAkB,EAAU,EAAE;IAC1E,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAC5D,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;IAClD,MAAM,WAAW,GACf,IAAI,CAAC,QAAQ,EAAE,GAAG,SAAS;QAC3B,IAAI,CAAC,UAAU,EAAE,GAAG,WAAW;QAC/B,IAAI,CAAC,UAAU,EAAE,GAAG,WAAW;QAC/B,IAAI,CAAC,eAAe,EAAE;QACtB,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,SAAS;YAC3B,KAAK,CAAC,UAAU,EAAE,GAAG,WAAW;YAChC,KAAK,CAAC,UAAU,EAAE,GAAG,WAAW;YAChC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC;IAE7B,IAAI,cAAc,GAAG,UAAU,GAAG,EAAE,GAAG,WAAW,CAAC;IACnD,IACE,cAAc,GAAG,CAAC;QAClB,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,EACrD,CAAC;QACD,cAAc,IAAI,CAAC,CAAC;IACtB,CAAC;SAAM,IACL,cAAc,GAAG,CAAC;QAClB,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,WAAW,GAAG,CAAC,CAAC,CAAC,EACrD,CAAC;QACD,cAAc,IAAI,CAAC,CAAC;IACtB,CAAC;IAED,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;QACjB,OAAO,cAAc,CAAC;IACxB,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,EAAE,CAAC,CAAC;AACzC,CAAC,CAAC"}