@bytebury/toolkit 1.0.0

package/script/src/duration.d.ts

@@ -0,0 +1,102 @@
+import type { Brand } from "./utility_types.js";
+/**
+ * Represents a duration of time in milliseconds. You should
+ * always use this type when working with durations of time in milliseconds.
+ * It helps ensure that you're working with durations of time in milliseconds,
+ * and not accidentally using a different unit of time.
+ *
+ * @example
+ * ```ts
+ * setTimeout(() => {}, 1_000 as Milliseconds);
+ * ```
+ */
+export type Milliseconds = Brand<number, "milliseconds">;
+/** Represents a duration of time in seconds. */
+export type Seconds = Brand<number, "seconds">;
+/** Represents a duration of time in minutes. */
+export type Minutes = Brand<number, "minutes">;
+/** Represents a duration of time in hours. */
+export type Hours = Brand<number, "hours">;
+/** Represents a duration of time in days. */
+export type Days = Brand<number, "days">;
+/** Represents a duration of time in weeks. */
+export type Weeks = Brand<number, "weeks">;
+/** Represents a duration of time in years. */
+export type Years = Brand<number, "years">;
+/**
+ * A representation of a duration of time within a codebase.
+ * This class provides a way to work with durations of time in a type-safe manner.
+ *
+ * @see milliseconds to quickly create a millisecond duration.
+ *
+ * @example Converting seconds to milliseconds
+ * ```ts
+ * setTimeout(() => {}, Duration.seconds(1 as Seconds).toMilliseconds());
+ * ```
+ * @example Converting minutes to milliseconds
+ * ```ts
+ * setTimeout(() => {}, Duration.minutes(1 as Minutes).toMilliseconds());
+ * ```
+ * @example Converting to milliseconds
+ */
+export declare class Duration {
+    private readonly milliseconds;
+    private constructor();
+    /**
+     * Creates a Duration from milliseconds.
+     */
+    static milliseconds(milliseconds: Milliseconds): Duration;
+    /**
+     * Creates a Duration from seconds.
+     */
+    static seconds(seconds: Seconds): Duration;
+    /**
+     * Creates a Duration from minutes.
+     */
+    static minutes(minutes: Minutes): Duration;
+    /**
+     * Creates a Duration from hours.
+     */
+    static hours(hours: Hours): Duration;
+    /**
+     * Creates a Duration from days.
+     */
+    static days(days: Days): Duration;
+    /**
+     * Creates a Duration from weeks.
+     */
+    static weeks(weeks: Weeks): Duration;
+    /**
+     * Creates a Duration from years.
+     */
+    static years(years: Years): Duration;
+    /**
+     * Converts the duration to milliseconds.
+     */
+    toMilliseconds(): Milliseconds;
+    /**
+     * Converts the duration to seconds.
+     */
+    toSeconds(): Seconds;
+    /**
+     * Converts the duration to minutes.
+     */
+    toMinutes(): Minutes;
+    /**
+     * Converts the duration to hours.
+     */
+    toHours(): Hours;
+    /**
+     * Converts the duration to days.
+     */
+    toDays(): Days;
+    /**
+     * Converts the duration to weeks.
+     */
+    toWeeks(): Weeks;
+    /**
+     * Converts the duration to years.
+     */
+    toYears(): Years;
+}
+//# sourceMappingURL=duration.d.ts.map

package/script/src/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../../src/src/duration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AACzD,gDAAgD;AAChD,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC/C,gDAAgD;AAChD,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC/C,8CAA8C;AAC9C,MAAM,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,6CAA6C;AAC7C,MAAM,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACzC,8CAA8C;AAC9C,MAAM,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC3C,8CAA8C;AAC9C,MAAM,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,QAAQ;IACC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAAjD,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,QAAQ;IAIzD;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ;IAI1C;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ;IAI1C;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ;IAIpC;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ;IAIjC;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ;IAIpC;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ;IAIpC;;OAEG;IACH,cAAc,IAAI,YAAY;IAI9B;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,IAAI,KAAK;IAIhB;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,OAAO,IAAI,KAAK;IAIhB;;OAEG;IACH,OAAO,IAAI,KAAK;CAGjB"}

package/script/src/duration.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Duration = void 0;
+/**
+ * A representation of a duration of time within a codebase.
+ * This class provides a way to work with durations of time in a type-safe manner.
+ *
+ * @see milliseconds to quickly create a millisecond duration.
+ *
+ * @example Converting seconds to milliseconds
+ * ```ts
+ * setTimeout(() => {}, Duration.seconds(1 as Seconds).toMilliseconds());
+ * ```
+ * @example Converting minutes to milliseconds
+ * ```ts
+ * setTimeout(() => {}, Duration.minutes(1 as Minutes).toMilliseconds());
+ * ```
+ * @example Converting to milliseconds
+ */
+class Duration {
+    constructor(milliseconds) {
+        Object.defineProperty(this, "milliseconds", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: milliseconds
+        });
+    }
+    /**
+     * Creates a Duration from milliseconds.
+     */
+    static milliseconds(milliseconds) {
+        return new Duration(milliseconds);
+    }
+    /**
+     * Creates a Duration from seconds.
+     */
+    static seconds(seconds) {
+        return new Duration(seconds * 1000);
+    }
+    /**
+     * Creates a Duration from minutes.
+     */
+    static minutes(minutes) {
+        return new Duration(minutes * 60 * 1000);
+    }
+    /**
+     * Creates a Duration from hours.
+     */
+    static hours(hours) {
+        return new Duration(hours * 60 * 60 * 1000);
+    }
+    /**
+     * Creates a Duration from days.
+     */
+    static days(days) {
+        return new Duration(days * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Creates a Duration from weeks.
+     */
+    static weeks(weeks) {
+        return new Duration(weeks * 7 * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Creates a Duration from years.
+     */
+    static years(years) {
+        return new Duration(years * 365 * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Converts the duration to milliseconds.
+     */
+    toMilliseconds() {
+        return this.milliseconds;
+    }
+    /**
+     * Converts the duration to seconds.
+     */
+    toSeconds() {
+        return this.milliseconds / 1000;
+    }
+    /**
+     * Converts the duration to minutes.
+     */
+    toMinutes() {
+        return this.milliseconds / (60 * 1000);
+    }
+    /**
+     * Converts the duration to hours.
+     */
+    toHours() {
+        return this.milliseconds / (60 * 60 * 1000);
+    }
+    /**
+     * Converts the duration to days.
+     */
+    toDays() {
+        return this.milliseconds / (24 * 60 * 60 * 1000);
+    }
+    /**
+     * Converts the duration to weeks.
+     */
+    toWeeks() {
+        return this.milliseconds / (7 * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Converts the duration to years.
+     */
+    toYears() {
+        return this.milliseconds / (365 * 24 * 60 * 60 * 1000);
+    }
+}
+exports.Duration = Duration;

package/script/src/duration_test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration_test.d.ts","sourceRoot":"","sources":["../../src/src/duration_test.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/script/src/numbers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Determines if a number is even.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `true`.
+ *
+ * @example
+ * ```ts
+ * isEven(null); // false
+ * isEven(1); // false
+ * isEven(2); // true
+ * isEven(3); // false
+ * isEven(4); // true
+ * isEven(11); // false
+ * isEven(21); // false
+ * isEven(112); // true
+ * ```
+ */
+export declare function isEven(num: number): boolean;
+/**
+ * Determines if a number is odd.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `false`.
+ *
+ * @example
+ * ```ts
+ * isOdd(null); // false
+ * isOdd(1); // true
+ * isOdd(2); // false
+ * isOdd(3); // true
+ * isOdd(4); // false
+ * isOdd(11); // true
+ * isOdd(21); // true
+ * isOdd(112); // false
+ * ```
+ */
+export declare function isOdd(num: number): boolean;
+/**
+ * Converts a number to "1st", "2nd", "3rd", etc.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `0th`.
+ *
+ * @example
+ * ```ts
+ * ordinalize(null); // "0th"
+ * ordinalize(1); // "1st"
+ * ordinalize(2); // "2nd"
+ * ordinalize(3); // "3rd"
+ * ordinalize(4); // "4th"
+ * ordinalize(11); // "11th"
+ * ordinalize(21); // "21st"
+ * ordinalize(112); // "112th"
+ * ```
+ */
+export declare function ordinalize(num: number): string;
+//# sourceMappingURL=numbers.d.ts.map

package/script/src/numbers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers.d.ts","sourceRoot":"","sources":["../../src/src/numbers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiB9C"}

package/script/src/numbers.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEven = isEven;
+exports.isOdd = isOdd;
+exports.ordinalize = ordinalize;
+/**
+ * Determines if a number is even.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `true`.
+ *
+ * @example
+ * ```ts
+ * isEven(null); // false
+ * isEven(1); // false
+ * isEven(2); // true
+ * isEven(3); // false
+ * isEven(4); // true
+ * isEven(11); // false
+ * isEven(21); // false
+ * isEven(112); // true
+ * ```
+ */
+function isEven(num) {
+    return (num || 0) % 2 === 0;
+}
+/**
+ * Determines if a number is odd.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `false`.
+ *
+ * @example
+ * ```ts
+ * isOdd(null); // false
+ * isOdd(1); // true
+ * isOdd(2); // false
+ * isOdd(3); // true
+ * isOdd(4); // false
+ * isOdd(11); // true
+ * isOdd(21); // true
+ * isOdd(112); // false
+ * ```
+ */
+function isOdd(num) {
+    return !isEven(num);
+}
+/**
+ * Converts a number to "1st", "2nd", "3rd", etc.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` this will return `0th`.
+ *
+ * @example
+ * ```ts
+ * ordinalize(null); // "0th"
+ * ordinalize(1); // "1st"
+ * ordinalize(2); // "2nd"
+ * ordinalize(3); // "3rd"
+ * ordinalize(4); // "4th"
+ * ordinalize(11); // "11th"
+ * ordinalize(21); // "21st"
+ * ordinalize(112); // "112th"
+ * ```
+ */
+function ordinalize(num) {
+    num || (num = 0);
+    const v = num % 100;
+    if (v >= 11 && v <= 13)
+        return num + "th";
+    switch (num % 10) {
+        case 1:
+            return num + "st";
+        case 2:
+            return num + "nd";
+        case 3:
+            return num + "rd";
+        default:
+            return num + "th";
+    }
+}

package/script/src/numbers_test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numbers_test.d.ts","sourceRoot":"","sources":["../../src/src/numbers_test.ts"],"names":[],"mappings":"AAAA,OAAO,2BAA2B,CAAC"}

package/script/src/strings.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Determines if the given text is only comprised of whitespace.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `true`.
+ *
+ * @example
+ * ```ts
+ * isWhitespace(null); // true
+ * isWhitespace("   "); // true
+ * isWhitespace("\n\t"); // true
+ * isWhitespace("Hello"); // false
+ * ```
+ */
+export declare function isWhitespace(text: string): boolean;
+/**
+ * Determines if the given text contains any non-whitespace characters.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `false`.
+ *
+ * @example
+ * ```ts
+ * isNotWhitespace(null); // false
+ * isNotWhitespace("   "); // false
+ * isNotWhitespace("Hello"); // true
+ * ```
+ */
+export declare function isNotWhitespace(text: string): boolean;
+/**
+ * Trims the whitespace from the beginning and the end. This is an
+ * alias for `.trim()`. Useful for when you're mapping over lists.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * trim(null); // ""
+ * trim(" HELLO WORLD    \n"); // "HELLO WORLD"
+ * [' hello ', ' world '].map(trim); // ['hello', 'world'];
+ * ```
+ */
+export declare function trim(text: string): string;
+/**
+ * Converts the string to Title Case. This will capitalize
+ * the letter of each word that is separated by a space. Underscores
+ * are considered spaces. Hyphens are respected.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * title(null); // ""
+ * title("hello world"); // Hello World
+ * title("hello-world"); // Hello-world
+ * title("hello_world"); // Hello World
+ * title("HELLO wORLD"); // Hello World
+ * ```
+ */
+export declare function title(text: string): string;
+/**
+ * Converts the string to lowercase.
+ * An alias for `toLowerCase()`.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * lower(null); // ""
+ * lower("Hello WORLD"); // "hello world"
+ * ```
+ */
+export declare function lower(text: string): Lowercase<string>;
+/**
+ * Converts the string to uppercase.
+ * An alias for `toUpperCase()`.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * upper(null); // ""
+ * upper("Hello world"); // "HELLO WORLD"
+ * ```
+ */
+export declare function upper(text: string): Uppercase<string>;
+/**
+ * Converts the string to `kebab-case` by removing punctuation,
+ * trimming extra spaces, converting to lowercase, and joining words with hyphens.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * kebab(null); // ""
+ * kebab("Hello World!"); // "hello-world"
+ * kebab("  Clean THIS_up!! "); // "clean-this-up"
+ * ```
+ */
+export declare function kebab(text: string): Lowercase<string>;
+/**
+ * Converts a string to `snake_case` by replacing spaces and punctuation with underscores.
+ * Uses `kebab()` internally, replacing hyphens with underscores.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * snake(null); // ""
+ * snake("Hello World"); // "hello_world"
+ * snake("User-Profile Page"); // "user_profile_page"
+ * ```
+ */
+export declare function snake(text: string): Lowercase<string>;
+/**
+ * Returns a copy of the given string with all non-alpha characters removed,
+ * except for spaces. Letters are preserved regardless of case.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * keepAlphabetical(null); // ""
+ * keepAlphabetical("Hello, World!"); // "Hello World"
+ * keepAlphabetical("123@#Test"); // "Test"
+ * ```
+ */
+export declare function keepAlphabetical(text: string): string;
+/**
+ * Returns a copy of the given string with all non-alphanumeric characters removed,
+ * except for spaces. Letters and digits are preserved regardless of case.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * keepAlphanumeric(null); // ""
+ * keepAlphanumeric("Hello, World!"); // "Hello World"
+ * keepAlphanumeric("123@#Test"); // "123Test"
+ * ```
+ */
+export declare function keepAlphanumeric(text: string): string;
+/**
+ * Removes any non-numeric characters. This includes spaces.
+ *
+ * @remarks
+ * This is `null | undefined` safe. If you pass `null | undefined` then this will return `""`.
+ *
+ * @example
+ * ```ts
+ * keepNumeric(null); // ""
+ * keepNumeric('(555) 555-5555'); // 5555555555
+ * ```
+ */
+export declare function keepNumeric(text: string): string;
+//# sourceMappingURL=strings.d.ts.map

package/script/src/strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/src/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAErD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAIrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}