@rtorcato/js-common 1.8.1 → 2.0.1

package/dist/currency/index.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Returns the currency symbol for a given ISO 4217 currency code.
+ *
+ * Utilizes the `Intl.NumberFormat` API to format a number as currency and extract the symbol.
+ *
+ * @param currency - The ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').
+ * @returns The currency symbol as a string (e.g., '$', '€', '¥'), or `undefined` if the symbol cannot be determined.
+ *
+ * @example
+ * ```typescript
+ * getCurrencySymbol('USD') // '$'
+ * getCurrencySymbol('EUR') // '€'
+ * getCurrencySymbol('JPY') // '¥'
+ * ```
+ */
+export declare const getCurrencySymbol: (currency: string) => string | undefined;
+/**
+ * Returns the full display name of a currency.
+ *
+ * @param currency - The ISO 4217 currency code (e.g., 'USD', 'EUR').
+ * @param locale - The locale to use for the display name. Defaults to 'en'.
+ * @returns The full currency name (e.g., 'US Dollar'), or `undefined` if invalid.
+ *
+ * @example
+ * ```typescript
+ * getCurrencyName('USD') // 'US Dollar'
+ * getCurrencyName('EUR') // 'Euro'
+ * getCurrencyName('JPY', 'ja') // '日本円'
+ * ```
+ */
+export declare function getCurrencyName(currency: string, locale?: string): string | undefined;
+/**
+ * Returns the default locale typically associated with a currency.
+ *
+ * @param currency - The ISO 4217 currency code.
+ * @returns The locale string (e.g., 'en-US' for USD), or 'en' as fallback.
+ *
+ * @example
+ * ```typescript
+ * getCurrencyLocale('USD') // 'en-US'
+ * getCurrencyLocale('EUR') // 'de-DE'
+ * getCurrencyLocale('JPY') // 'ja-JP'
+ * ```
+ */
+export declare function getCurrencyLocale(currency: string): string;
+/**
+ * Formats a given price value into a localized currency string.
+ *
+ * @param price - The numeric value or string representation of the price to format.
+ * @param currency - The ISO 4217 currency code. Defaults to 'USD'.
+ * @param locale - The locale to use for formatting. If not provided, uses the currency's default locale.
+ * @returns The formatted currency string.
+ *
+ * @example
+ * ```typescript
+ * formatPrice(1234.56, 'USD') // '$1,234.56'
+ * formatPrice(1234.56, 'EUR') // '1.234,56 €'
+ * formatPrice(1234.56, 'JPY') // '¥1,235'
+ * ```
+ */
+export declare function formatPrice(price: number | string, currency?: string, locale?: string): string;
+/**
+ * Formats a price in compact notation (e.g., $1.2K, $1.5M).
+ *
+ * @param price - The numeric value to format.
+ * @param currency - The ISO 4217 currency code. Defaults to 'USD'.
+ * @param locale - The locale to use for formatting.
+ * @returns The formatted compact currency string.
+ *
+ * @example
+ * ```typescript
+ * formatPriceCompact(1234) // '$1.2K'
+ * formatPriceCompact(1234567) // '$1.2M'
+ * formatPriceCompact(1234567890) // '$1.2B'
+ * formatPriceCompact(1500, 'EUR') // '1,5 Tsd. €'
+ * ```
+ */
+export declare function formatPriceCompact(price: number | string, currency?: string, locale?: string): string;
+/**
+ * Parses a given price string and returns its numeric value.
+ *
+ * @param value - The price string to parse.
+ * @returns The numeric value of the price, or `null` if the value cannot be parsed.
+ *
+ * @example
+ * ```typescript
+ * parsePrice('$1,234.56') // 1234.56
+ * parsePrice('€1.234,56') // 1234.56
+ * parsePrice('invalid') // null
+ * ```
+ */
+export declare function parsePrice(value: string): number | null;
+/**
+ * Parses a currency string and extracts both the amount and currency code.
+ *
+ * @param value - The currency string to parse (e.g., '$1,234.56', 'EUR 100').
+ * @returns An object with `amount` and `currency`, or `null` if parsing fails.
+ *
+ * @example
+ * ```typescript
+ * parseCurrencyString('$1,234.56') // { amount: 1234.56, currency: 'USD' }
+ * parseCurrencyString('€100') // { amount: 100, currency: 'EUR' }
+ * parseCurrencyString('1000 JPY') // { amount: 1000, currency: 'JPY' }
+ * parseCurrencyString('invalid') // null
+ * ```
+ */
+export declare function parseCurrencyString(value: string): {
+    amount: number;
+    currency: string;
+} | null;
+/**
+ * Converts a given amount from one currency to another using the provided exchange rate.
+ *
+ * @param amount - The amount of money to convert.
+ * @param rate - The exchange rate to use for the conversion.
+ * @param decimals - The number of decimal places to include in the result. Defaults to 2.
+ * @returns The converted amount as a number.
+ *
+ * @example
+ * ```typescript
+ * convertCurrency(100, 0.85) // 85 (e.g., USD to EUR)
+ * convertCurrency(100, 110.5, 0) // 11050 (e.g., USD to JPY)
+ * ```
+ */
+export declare function convertCurrency(amount: number, rate: number, decimals?: number): number;
+/**
+ * Checks if the provided currency code is valid.
+ *
+ * This function lazily loads the currencies list to minimize bundle size impact.
+ *
+ * @param code - The currency code to validate (e.g., 'USD', 'eur').
+ * @returns Promise resolving to `true` if the currency code is valid; otherwise, `false`.
+ *
+ * @example
+ * ```typescript
+ * await isValidCurrencyCode('USD') // true
+ * await isValidCurrencyCode('INVALID') // false
+ * ```
+ */
+export declare function isValidCurrencyCode(code: string): Promise<boolean>;
+/**
+ * Synchronously checks if a currency code is valid using the Intl API.
+ *
+ * This does not require loading the currencies list and has zero bundle size impact.
+ *
+ * @param code - The currency code to validate.
+ * @returns `true` if the currency code is valid; otherwise, `false`.
+ *
+ * @example
+ * ```typescript
+ * isValidCurrency('USD') // true
+ * isValidCurrency('INVALID') // false
+ * ```
+ */
+export declare function isValidCurrency(code: string): boolean;
+/**
+ * Rounds a given number to a specified number of decimal places.
+ *
+ * @param value - The number to be rounded.
+ * @param decimals - The number of decimal places to round to. Defaults to 2.
+ * @returns The rounded number.
+ *
+ * @example
+ * ```typescript
+ * roundTo(3.14159, 2) // 3.14
+ * roundTo(10.5, 0) // 11
+ * ```
+ */
+export declare function roundTo(value: number, decimals?: number): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/currency/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/currency/index.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,MAAM,GAAG,SAY7D,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAO,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkC1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,SAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,QAAQ,SAAQ,EAChB,MAAM,CAAC,EAAE,MAAM,GACb,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAavD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2C9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAElF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAG3D"}

package/dist/date/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Returns today's date as a YYYY-MM-DD string.
+ * @returns {string}
+ */
+export declare function today(): string;
+/**
+ * Returns a Date object from a YYYY-MM-DD string.
+ * @param dateStr The date string.
+ * @returns {Date}
+ */
+export declare function parseDate(dateStr: string): Date;
+/**
+ * Formats a Date object as YYYY-MM-DD.
+ * @param date The Date object.
+ * @returns {string}
+ */
+export declare function formatDate(date: Date): string;
+/**
+ * Returns the difference in days between two dates (date2 - date1).
+ * @param date1 The first date (string or Date).
+ * @param date2 The second date (string or Date).
+ * @returns {number}
+ */
+export declare function daysBetween(date1: string | Date, date2: string | Date): number;
+/**
+ * Checks if a year is a leap year.
+ * @param year The year (number or Date).
+ * @returns {boolean}
+ */
+export declare function isLeapYear(year: number | Date): boolean;
+/**
+ * Adds days to a date and returns a new Date object.
+ * @param date The date (string or Date).
+ * @param days Number of days to add.
+ * @returns {Date}
+ */
+export declare function addDays(date: string | Date, days: number): Date;
+/**
+ * Returns the day of the week for a date (0=Sunday, 6=Saturday).
+ * @param date The date (string or Date).
+ * @returns {number}
+ */
+export declare function getDayOfWeek(date: string | Date): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/date/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/date/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,KAAK,IAAI,MAAM,CAG9B;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAI9E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGxD"}

package/dist/datetime/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Returns the current date and time as an ISO string (YYYY-MM-DDTHH:mm:ss.sssZ).
+ */
+export declare function nowIso(): string;
+/**
+ * Parses an ISO date-time string to a Date object. Returns null if invalid.
+ * @param iso The ISO string.
+ */
+export declare function parseIsoDateTime(iso: string): Date | null;
+/**
+ * Formats a Date as YYYY-MM-DD HH:mm:ss (local time).
+ * @param date The Date object.
+ */
+export declare function formatDateTimeLocal(date: Date): string;
+/**
+ * Returns the timezone offset in minutes for a given date (local - UTC).
+ * @param date The Date object.
+ */
+export declare function getTimezoneOffset(date?: Date): number;
+/**
+ * Returns the UTC equivalent of a local Date.
+ * @param date The local Date object.
+ */
+export declare function toUtcDate(date: Date): Date;
+/**
+ * Returns the number of seconds since the Unix epoch (UTC).
+ */
+export declare function unixTimestamp(): number;
+/**
+ * Returns the number of milliseconds since the Unix epoch.
+ */
+export declare function unixMillis(): number;
+/**
+ * Returns the difference in seconds between two Date objects.
+ * @param a First date.
+ * @param b Second date.
+ */
+export declare function secondsBetween(a: Date, b: Date): number;
+/**
+ * Returns the ISO week number (1–53) of a given date using UTC.
+ * @param date A JavaScript Date object.
+ */
+export declare function getIsoWeek(date: Date): number;
+/**
+ * Returns ISO week number and ISO week year (which may differ from calendar year).
+ * @param date Date object (UTC-safe)
+ */
+export declare function getIsoWeekInfo(date: Date): {
+    week: number;
+    year: number;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/datetime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/datetime/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAGzD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CAEjE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAY1C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAEvD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAoB7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAmBzE"}

package/dist/emails/banned/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Checks if the domain part of the given email is present in a list of forbidden domains.
+ *
+ * @param email - The email address to check.
+ * @param forbiddenEmails - A newline-separated string of forbidden email domains.
+ * @throws Will throw an error if the email is not formatted properly or if the domain is forbidden.
+ */
+export declare const isEmailinBannedDomains: (email: string, forbiddenEmails: string) => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/emails/banned/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/emails/banned/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,EAAE,iBAAiB,MAAM,SAW5E,CAAA"}

package/dist/emails/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Validates if a string is a valid email address (simple regex).
+ * @param email The email address to validate.
+ * @returns True if valid, false otherwise.
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Normalizes an email address by trimming and converting to lowercase.
+ * @param email The email address to normalize.
+ * @returns The normalized email address.
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * Masks an email address for privacy (e.g., j***@domain.com).
+ * @param email The email address to mask.
+ * @returns The masked email address.
+ */
+export declare function maskEmail(email: string): string;
+/**
+ * Extracts the domain from an email address.
+ * @param email The email address.
+ * @returns The domain part of the email, or an empty string if invalid.
+ */
+export declare function getEmailDomain(email: string): string;
+export declare function isFreeEmailProvider(email: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/emails/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emails/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAiBD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/env/index.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+/**
+ * Retrieves the value of an environment variable by its key.
+ *
+ * @param key - The name of the environment variable to retrieve.
+ * @param defaultValue - An optional default value to return if the environment variable is not defined.
+ * @returns The value of the environment variable if it exists, otherwise the default value if provided.
+ * @throws {Error} If the environment variable is undefined and no default value is provided.
+ */
+export declare const getENV: (key: string, defaultValue?: string) => string;
+/**
+ * Determines if the current environment is set to development.
+ *
+ * @returns {boolean} `true` if `process.env.NODE_ENV` is `'development'`, otherwise `false`.
+ */
+export declare const isDev: () => boolean;
+/**
+ * Determines if the current environment is set to production.
+ *
+ * @returns {boolean} `true` if `process.env.NODE_ENV` is `'production'`, otherwise `false`.
+ */
+export declare const isProd: () => boolean;
+/**
+ * Determines if the current environment is set to test.
+ *
+ * @returns {boolean} `true` if `process.env.NODE_ENV` is `'test'`, otherwise `false`.
+ */
+export declare const isTest: () => boolean;
+/**
+ * Returns the current NODE_ENV value, or 'development' if not set.
+ *
+ * @returns {string}
+ */
+export declare const getNodeEnv: () => string;
+/**
+ *
+ * Validates the environment variables against a Zod schema.
+ * Throws an error if any required variables are missing or invalid.
+ * @param {z.ZodObject<T>} EnvSchema - The Zod schema to validate against.
+ * @param {Record<string, string | undefined>} buildEnv - The environment variables to validate, defaults to `process.env`.
+ * @throws {Error} If validation fails, an error with a message listing missing variables is thrown.
+ */
+export declare function checkEnv<T extends z.ZodRawShape>(EnvSchema: z.ZodObject<T>, buildEnv?: Record<string, string | undefined>): z.core.$InferObjectOutput<T, {}>;
+/**
+ * Schema for validating the root environment variables.
+ * It includes NODE_ENV, LOG_LEVEL, and PORT with their respective types and defaults.
+ */
+export declare const RootApiEnvSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+    }>>;
+    LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+    }>>;
+    PORT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type RootApiEnvSchema = z.infer<typeof RootApiEnvSchema>;
+//# sourceMappingURL=index.d.ts.map

package/dist/env/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/env/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM,GAAI,KAAK,MAAM,EAAE,eAAe,MAAM,WAUxD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAO,OAExB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,QAAO,OAEzB,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAAO,MAE7B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAC/C,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACzB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,oCAc1D;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;iBAI3B,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA"}

package/dist/errors/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Creates a new Error with a custom name and message.
+ * @param name The error name.
+ * @param message The error message.
+ * @returns The custom Error object.
+ */
+export declare function createCustomError(name: string, message: string): Error;
+/**
+ * Checks if an error is an instance of a specific error name.
+ * @param error The error to check.
+ * @param name The error name to match.
+ * @returns True if the error matches the name, false otherwise.
+ */
+export declare function isErrorName(error: unknown, name: string): boolean;
+/**
+ * Gets the error message from an unknown error value.
+ * @param error The error value.
+ * @returns The error message, or a stringified version if not an Error.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Throws an error if the condition is false.
+ * @param condition The condition to check.
+ * @param message The error message to throw if the condition is false.
+ */
+export declare function assert(condition: unknown, message: string): asserts condition;
+/**
+ * Wraps a function and catches errors, returning a fallback value if an error occurs.
+ * Use this only when the fallback is genuinely safe and the error can be ignored.
+ * For typed error handling, prefer `tryCatch` from `@rtorcato/js-common/try`.
+ * @param fn The function to wrap.
+ * @param fallback The fallback value to return on error.
+ *
+ * @example
+ * const result = await tryWithFallback(async () => fetchData(), [])
+ * // result will be [] if fetchData throws
+ */
+export declare function tryWithFallback<T>(fn: () => Promise<T> | T, fallback: T): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAItE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAED;;;;GAIG;AAEH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAI7E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM1F"}

package/dist/errors/index.js

@@ -1 +1 @@
-import"../chunks/chunk-ANN5UYCF.js";function e(n,r){let t=new Error(r);return t.name=n,t}function o(n,r){return n instanceof Error&&n.name===r}function i(n){if(n instanceof Error)return n.message;if(typeof n=="string")return n;try{return JSON.stringify(n)}catch{return String(n)}}function s(n,r){if(!n)throw new Error(r)}async function a(n,r){try{return await n()}catch{return r}}export{s as assert,e as createCustomError,i as getErrorMessage,o as isErrorName,a as tryCatch};
+import"../chunks/chunk-ANN5UYCF.js";function e(n,r){let t=new Error(r);return t.name=n,t}function o(n,r){return n instanceof Error&&n.name===r}function i(n){if(n instanceof Error)return n.message;if(typeof n=="string")return n;try{return JSON.stringify(n)}catch{return String(n)}}function s(n,r){if(!n)throw new Error(r)}async function a(n,r){try{return await n()}catch{return r}}export{s as assert,e as createCustomError,i as getErrorMessage,o as isErrorName,a as tryWithFallback};

package/dist/events/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Adds an event listener and returns a function to remove it.
+ * @param target The event target.
+ * @param type The event type.
+ * @param handler The event handler.
+ * @param options Event listener options.
+ * @returns {() => void} Unsubscribe function.
+ */
+export declare function on<K extends keyof HTMLElementEventMap>(target: EventTarget, type: K, handler: (event: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): () => void;
+/**
+ * Dispatches a custom event on the target.
+ * @param target The event target.
+ * @param type The event type.
+ * @param detail Optional detail data.
+ * @returns {boolean} True if not canceled.
+ */
+export declare function emit(target: EventTarget, type: string, detail?: unknown): boolean;
+/**
+ * Waits for a single event to occur and resolves a promise.
+ * @param target The event target.
+ * @param type The event type.
+ * @returns {Promise<Event>} Resolves with the event object.
+ */
+export declare function once<K extends keyof HTMLElementEventMap>(target: EventTarget, type: K): Promise<HTMLElementEventMap[K]>;
+/**
+ * Prevents the default action for an event.
+ * @param event The event object.
+ */
+export declare function preventDefault(event: Event): void;
+/**
+ * Stops propagation for an event.
+ * @param event The event object.
+ */
+export declare function stopPropagation(event: Event): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,EAAE,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACrD,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,EAChD,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GACzC,MAAM,IAAI,CAGZ;AAED;;;;;;GAMG;AAEH,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,MAAM,mBAAmB,EACvD,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,GACL,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAQjC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEjD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAElD"}

package/dist/fetch/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fetches a resource with a timeout.
+ * @param url The URL to fetch.
+ * @param options Fetch options.
+ * @param timeout Timeout in milliseconds (default: 8000).
+ * @returns The parsed JSON response.
+ */
+export declare function fetchWithTimeout(url: string, options?: RequestInit, timeout?: number): Promise<unknown>;
+/**
+ * Sends a POST request with a JSON body.
+ * @param url The URL to post to.
+ * @param body The body to send.
+ * @param options Additional fetch options.
+ * @returns The parsed JSON response.
+ */
+export declare function postJson<T = unknown, R = unknown>(url: string, body: T, options?: RequestInit): Promise<R>;
+/**
+ * Sends a GET request and returns JSON.
+ * @param url The URL to fetch.
+ * @param options Additional fetch options.
+ * @returns The parsed JSON response.
+ */
+export declare function getJson<T = unknown>(url: string, options?: RequestInit): Promise<T>;
+/**
+ * Fetches a resource and returns the response as text.
+ * @param url The URL to fetch.
+ * @param options Fetch options.
+ * @returns The response as text.
+ */
+export declare function fetchText(url: string, options?: RequestInit): Promise<string>;
+/**
+ * Handles fetch errors and returns a fallback value or throws.
+ * @param promise The fetch promise.
+ * @param fallback The fallback value to return on error.
+ * @returns The resolved value or the fallback.
+ */
+export declare function handleApiError<T>(promise: Promise<T>, fallback?: T): Promise<T>;
+//# sourceMappingURL=index.d.ts.map

package/dist/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,EACzB,OAAO,SAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACtD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,CAAC,EACP,OAAO,GAAE,WAAgB,GACvB,OAAO,CAAC,CAAC,CAAC,CAQZ;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC,CAG7F;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAOrF"}

package/dist/file/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reads a file as a string (UTF-8).
+ * @param {string} filePath - The path to the file.
+ * @returns {Promise<string>} The file contents as a string.
+ */
+export declare function readFileAsString(filePath: string): Promise<string>;
+/**
+ * Writes a string to a file (UTF-8).
+ * @param {string} filePath - The path to the file.
+ * @param {string} data - The string data to write.
+ * @returns {Promise<void>}
+ */
+export declare function writeFileAsString(filePath: string, data: string): Promise<void>;
+/**
+ * Checks if a file exists.
+ * @param {string} filePath - The path to the file.
+ * @returns {Promise<boolean>} True if the file exists, false otherwise.
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Deletes a file.
+ * @param {string} filePath - The path to the file.
+ * @returns {Promise<void>}
+ */
+export declare function deleteFile(filePath: string): Promise<void>;
+/**
+ * Gets the file extension from a file path.
+ * @param {string} filePath - The path to the file.
+ * @returns {string} The file extension (including the dot), or an empty string if none.
+ */
+export declare function getFileExtension(filePath: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/file/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/file/index.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAExE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/formatting/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pads a string or number with leading zeros to a given length.
+ * @param value The value to pad.
+ * @param length The desired length.
+ * @returns The padded string.
+ */
+export declare function padZero(value: string | number, length?: number): string;
+/**
+ * Formats a number with thousands separators.
+ * @param num The number to format.
+ * @param locale Optional locale string (default: 'en-US').
+ * @returns The formatted string.
+ */
+export declare function formatNumber(num: number, locale?: string): string;
+/**
+ * Formats a number as a percentage string.
+ * @param value The value to format (e.g. 0.25 for 25%).
+ * @param fractionDigits Number of decimal places (default: 0).
+ * @returns The formatted percentage string.
+ */
+export declare function formatPercent(value: number, fractionDigits?: number): string;
+/**
+ * Formats a Date as YYYY-MM-DD.
+ * @param date The date to format.
+ * @returns The formatted date string.
+ */
+export declare function formatDate(date: Date): string;
+/**
+ * Formats a Date as HH:MM:SS.
+ * @param date The date to format.
+ * @returns The formatted time string.
+ */
+export declare function formatTime(date: Date): string;
+/**
+ * Formats a Date as YYYY-MM-DD HH:MM:SS.
+ * @param date The date to format.
+ * @returns The formatted date-time string.
+ */
+export declare function formatDateTime(date: Date): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/formatting/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatting/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAgB,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,SAAI,GAAG,MAAM,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEjD"}

package/dist/functions/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Returns a function that only calls the original function once.
+ * @param fn The function to wrap.
+ * @returns {Function}
+ */
+export declare function once<T extends (...args: any[]) => any>(fn: T): T;
+/**
+ * Returns a debounced version of a function.
+ * @param fn The function to debounce.
+ * @param wait Milliseconds to wait.
+ * @returns {Function}
+ */
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, wait: number): T;
+/**
+ * Returns a throttled version of a function.
+ * @param fn The function to throttle.
+ * @param wait Milliseconds to wait between calls.
+ * @returns {Function}
+ */
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, wait: number): T;
+/**
+ * Composes functions from right to left.
+ * @param fns Functions to compose.
+ * @returns {Function}
+ */
+export declare function compose<T>(...fns: Array<(arg: T) => T>): (arg: T) => T;
+/**
+ * Pipes functions from left to right.
+ * @param fns Functions to pipe.
+ * @returns {Function}
+ */
+export declare function pipe<T>(...fns: Array<(arg: T) => T>): (arg: T) => T;
+//# sourceMappingURL=index.d.ts.map

package/dist/functions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/functions/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAUhE;AAED;;;;;GAKG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAMnF;AAED;;;;;GAKG;AAEH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CASnF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAEnE"}