stringzy 4.0.0 → 4.2.0

package/dist/formatting/creditCard.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCreditCard = formatCreditCard;
+/**
+ * Formats a credit card number by grouping digits into readable parts.
+ *
+ * @param {string} cardNumber - The credit card number to format.
+ * @returns {string} The formatted credit card number.
+ * @throws {TypeError} If the input is not a string.
+ */
+function formatCreditCard(cardNumber) {
+    if (typeof cardNumber !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    // Remove all non-digit characters
+    const cleaned = cardNumber.replace(/\D/g, '');
+    // Only accept 15 or 16 digit card numbers
+    if (cleaned.length !== 15 && cleaned.length !== 16) {
+        return '';
+    }
+    // Format based on length:
+    // 16 digits → 4-4-4-4 (Visa, MasterCard)
+    if (cleaned.length === 16) {
+        return cleaned.replace(/(\d{4})(?=\d)/g, '$1 ').trim();
+    }
+    // 15 digits → 4-6-5 (AmEx)
+    return cleaned.replace(/(\d{4})(\d{6})(\d{5})/, '$1 $2 $3');
+}

package/dist/formatting/decimal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Converts a string in base 2, 8, or 16 to its decimal (base-10) number.
+ *
+ * - Supports optional standard prefixes: 0b, 0o, 0x (case-insensitive)
+ * - Trims leading/trailing whitespace
+ * - Supports uppercase and lowercase characters for hexadecimal
+ *
+ * Examples:
+ * formatToDecimal('1010', { base: 2 }) → 10
+ * formatToDecimal('12', { base: 8 })   → 10
+ * formatToDecimal('FF', { base: 16 })  → 255
+ * formatToDecimal('0xFF', { base: 16 })→ 255
+ *
+ * @param {string} value - The input string representing a number in the given base.
+ * @param {{ base: 2 | 8 | 16 }} options - Options containing the base of the input string.
+ * @returns {number} The decimal (base-10) representation.
+ * @throws {TypeError} For non-string inputs, unsupported bases, or malformed values.
+ */
+export declare function formatToDecimal(value: string, options: {
+    base: 2 | 8 | 16;
+}): number;

package/dist/formatting/decimal.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToDecimal = formatToDecimal;
+/**
+ * Converts a string in base 2, 8, or 16 to its decimal (base-10) number.
+ *
+ * - Supports optional standard prefixes: 0b, 0o, 0x (case-insensitive)
+ * - Trims leading/trailing whitespace
+ * - Supports uppercase and lowercase characters for hexadecimal
+ *
+ * Examples:
+ * formatToDecimal('1010', { base: 2 }) → 10
+ * formatToDecimal('12', { base: 8 })   → 10
+ * formatToDecimal('FF', { base: 16 })  → 255
+ * formatToDecimal('0xFF', { base: 16 })→ 255
+ *
+ * @param {string} value - The input string representing a number in the given base.
+ * @param {{ base: 2 | 8 | 16 }} options - Options containing the base of the input string.
+ * @returns {number} The decimal (base-10) representation.
+ * @throws {TypeError} For non-string inputs, unsupported bases, or malformed values.
+ */
+function formatToDecimal(value, options) {
+    if (typeof value !== 'string') {
+        throw new TypeError('Input must be a string');
+    }
+    const base = options === null || options === void 0 ? void 0 : options.base;
+    if (base !== 2 && base !== 8 && base !== 16) {
+        throw new TypeError('Base must be one of 2, 8, or 16');
+    }
+    let trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new TypeError('Input must be a non-empty string');
+    }
+    // Optional sign support; not required by spec but harmless and intuitive
+    let isNegative = false;
+    if (trimmed.startsWith('+') || trimmed.startsWith('-')) {
+        isNegative = trimmed[0] === '-';
+        trimmed = trimmed.slice(1);
+        if (trimmed.length === 0) {
+            throw new TypeError('Malformed numeric string');
+        }
+    }
+    // Strip standard prefixes if present and base matches
+    const prefix = trimmed.slice(0, 2).toLowerCase();
+    if (prefix === '0b' && base === 2) {
+        trimmed = trimmed.slice(2);
+    }
+    else if (prefix === '0o' && base === 8) {
+        trimmed = trimmed.slice(2);
+    }
+    else if (prefix === '0x' && base === 16) {
+        trimmed = trimmed.slice(2);
+    }
+    if (trimmed.length === 0) {
+        throw new TypeError('Malformed numeric string');
+    }
+    // Validate characters for the specified base
+    let pattern;
+    if (base === 2) {
+        pattern = /^[01]+$/;
+    }
+    else if (base === 8) {
+        pattern = /^[0-7]+$/;
+    }
+    else {
+        pattern = /^[0-9a-fA-F]+$/;
+    }
+    if (!pattern.test(trimmed)) {
+        throw new TypeError('Input contains invalid characters for the specified base');
+    }
+    const parsed = parseInt(trimmed, base);
+    return isNegative ? -parsed : parsed;
+}

package/dist/formatting/duration.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Converts a duration in seconds or milliseconds into a human-readable string.
+ * Intelligently displays hours, minutes, seconds, and optionally milliseconds,
+ * while skipping zero-value units unless the entire duration is zero.
+ *
+ * @param {number} input - The duration in seconds or milliseconds.
+ * @param {object} [options] - Configuration options.
+ * @param {string} [options.unit='seconds'] - The input unit: 'seconds' or 'milliseconds'.
+ * @param {string} [options.format='short'] - Output format: 'short', 'medium', or 'long'.
+ * @param {boolean} [options.includeMs=false] - Whether to include milliseconds in the output.
+ * @param {string} [options.delimiter=' '] - The delimiter between time units.
+ * @returns {string} The formatted duration string.
+ * @throws {TypeError} If input is not a number or is negative.
+ *
+ * @example
+ * formatDuration(60);        // "1m"
+ * formatDuration(61);        // "1m 1s"
+ * formatDuration(3661);      // "1h 1m 1s"
+ * formatDuration(1234567, { unit: 'milliseconds', includeMs: true }); // "20m 34s 567ms"
+ * formatDuration(3600, { format: 'long' }); // "1 hour"
+ */
+export declare function formatDuration(input: number, options?: {
+    unit?: 'seconds' | 'milliseconds';
+    format?: 'short' | 'medium' | 'long';
+    includeMs?: boolean;
+    delimiter?: string;
+}): string;

package/dist/formatting/duration.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDuration = formatDuration;
+/**
+ * Converts a duration in seconds or milliseconds into a human-readable string.
+ * Intelligently displays hours, minutes, seconds, and optionally milliseconds,
+ * while skipping zero-value units unless the entire duration is zero.
+ *
+ * @param {number} input - The duration in seconds or milliseconds.
+ * @param {object} [options] - Configuration options.
+ * @param {string} [options.unit='seconds'] - The input unit: 'seconds' or 'milliseconds'.
+ * @param {string} [options.format='short'] - Output format: 'short', 'medium', or 'long'.
+ * @param {boolean} [options.includeMs=false] - Whether to include milliseconds in the output.
+ * @param {string} [options.delimiter=' '] - The delimiter between time units.
+ * @returns {string} The formatted duration string.
+ * @throws {TypeError} If input is not a number or is negative.
+ *
+ * @example
+ * formatDuration(60);        // "1m"
+ * formatDuration(61);        // "1m 1s"
+ * formatDuration(3661);      // "1h 1m 1s"
+ * formatDuration(1234567, { unit: 'milliseconds', includeMs: true }); // "20m 34s 567ms"
+ * formatDuration(3600, { format: 'long' }); // "1 hour"
+ */
+function formatDuration(input, options) {
+    // Validate input
+    if (typeof input !== 'number' || isNaN(input)) {
+        throw new TypeError('Input must be a number');
+    }
+    if (input < 0) {
+        throw new TypeError('Input must be non-negative');
+    }
+    // Default options
+    const opts = {
+        unit: (options === null || options === void 0 ? void 0 : options.unit) || 'seconds',
+        format: (options === null || options === void 0 ? void 0 : options.format) || 'short',
+        includeMs: (options === null || options === void 0 ? void 0 : options.includeMs) || false,
+        delimiter: (options === null || options === void 0 ? void 0 : options.delimiter) || ' '
+    };
+    // Convert to milliseconds
+    const totalMs = opts.unit === 'seconds' ? input * 1000 : input;
+    // Handle zero case
+    if (totalMs === 0) {
+        return '0s';
+    }
+    // Calculate time components
+    let remaining = Math.floor(totalMs);
+    const ms = remaining % 1000;
+    remaining = Math.floor(remaining / 1000);
+    const seconds = remaining % 60;
+    remaining = Math.floor(remaining / 60);
+    const minutes = remaining % 60;
+    const hours = Math.floor(remaining / 60);
+    // Build the output parts
+    const parts = [];
+    // Add non-zero units
+    if (hours > 0) {
+        parts.push(formatTimeUnit(hours, 'h', opts.format));
+    }
+    if (minutes > 0) {
+        parts.push(formatTimeUnit(minutes, 'm', opts.format));
+    }
+    if (seconds > 0 || (parts.length === 0 && !opts.includeMs)) {
+        parts.push(formatTimeUnit(seconds, 's', opts.format));
+    }
+    if (opts.includeMs && ms > 0) {
+        parts.push(formatTimeUnit(ms, 'ms', opts.format));
+    }
+    return parts.join(opts.delimiter);
+}
+/**
+ * Formats a single time unit according to the specified format.
+ * @private
+ */
+function formatTimeUnit(value, unit, format) {
+    switch (format) {
+        case 'long':
+            const unitNames = {
+                'h': ['hour', 'hours'],
+                'm': ['minute', 'minutes'],
+                's': ['second', 'seconds'],
+                'ms': ['millisecond', 'milliseconds']
+            };
+            const [singular, plural] = unitNames[unit];
+            return `${value} ${value === 1 ? singular : plural}`;
+        case 'medium':
+            const paddedValue = unit === 'h' ? value : value.toString().padStart(2, '0');
+            return `${paddedValue}${unit}`;
+        default: // 'short'
+            return `${value}${unit}`;
+    }
+}

package/dist/formatting/fileSize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts a number of bytes into a human-readable file size string (B, KB, MB, GB, TB).
+ *
+ * Supports values from bytes up to terabytes, with automatic unit scaling and correct rounding.
+ *
+ * Examples:
+ * 123 → "123 B"
+ * 1024 → "1 KB"
+ * 1048576 → "1 MB"
+ * 1073741824 → "1 GB"
+ * 1572864 → "1.5 MB"
+ *
+ * @param {number} bytes - The number of bytes to convert.
+ * @param {number} [precision=2] - The number of decimal places to include for non-integer conversions.
+ * @returns {string} The formatted file size string with units.
+ * @throws {TypeError} If the input is not a number or precision is not a valid number.
+ */
+export declare function formatFileSize(bytes: number, precision?: number): string;

package/dist/formatting/fileSize.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFileSize = formatFileSize;
+/**
+ * Converts a number of bytes into a human-readable file size string (B, KB, MB, GB, TB).
+ *
+ * Supports values from bytes up to terabytes, with automatic unit scaling and correct rounding.
+ *
+ * Examples:
+ * 123 → "123 B"
+ * 1024 → "1 KB"
+ * 1048576 → "1 MB"
+ * 1073741824 → "1 GB"
+ * 1572864 → "1.5 MB"
+ *
+ * @param {number} bytes - The number of bytes to convert.
+ * @param {number} [precision=2] - The number of decimal places to include for non-integer conversions.
+ * @returns {string} The formatted file size string with units.
+ * @throws {TypeError} If the input is not a number or precision is not a valid number.
+ */
+function formatFileSize(bytes, precision = 2) {
+    if (typeof bytes !== 'number' || Number.isNaN(bytes)) {
+        throw new TypeError('Input must be a number');
+    }
+    if (typeof precision !== 'number' || Number.isNaN(precision) || precision < 0) {
+        throw new TypeError('Precision must be a non-negative number');
+    }
+    if (bytes < 0) {
+        throw new RangeError('File size cannot be negative');
+    }
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    if (bytes === 0)
+        return `0 B`;
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    // ✅ Fix: trim trailing zeros by converting to number before string
+    const rounded = value % 1 === 0 ? value.toString() : parseFloat(value.toFixed(precision)).toString();
+    return `${rounded} ${units[i]}`;
+}

package/dist/formatting/hexadecimal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Converts a decimal number to its hexadecimal (base-16) representation.
+ *
+ * @param {number} num - The decimal number to convert.
+ * @param {object} [options] - Optional formatting options.
+ * @param {boolean} [options.prefix=false] - Whether to add "0x" before the result.
+ * @param {boolean} [options.lowercase=false] - Whether to return hexadecimal in lowercase.
+ * @returns {string} The hexadecimal representation of the number.
+ * @throws {TypeError} If the input is not a valid number.
+ */
+export declare function formatToHexadecimal(num: number, options?: {
+    prefix?: boolean;
+    lowercase?: boolean;
+}): string;

package/dist/formatting/hexadecimal.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToHexadecimal = formatToHexadecimal;
+/**
+ * Converts a decimal number to its hexadecimal (base-16) representation.
+ *
+ * @param {number} num - The decimal number to convert.
+ * @param {object} [options] - Optional formatting options.
+ * @param {boolean} [options.prefix=false] - Whether to add "0x" before the result.
+ * @param {boolean} [options.lowercase=false] - Whether to return hexadecimal in lowercase.
+ * @returns {string} The hexadecimal representation of the number.
+ * @throws {TypeError} If the input is not a valid number.
+ */
+function formatToHexadecimal(num, options) {
+    if (typeof num !== 'number' || isNaN(num)) {
+        throw new TypeError('Input must be a valid number');
+    }
+    const { prefix = false, lowercase = false } = options || {};
+    // Convert number to hexadecimal (absolute value first to handle negatives)
+    let hex = Math.abs(num).toString(16).toUpperCase();
+    if (lowercase) {
+        hex = hex.toLowerCase();
+    }
+    // Add negative sign if original number was negative
+    if (num < 0) {
+        hex = '-' + hex;
+    }
+    // Add prefix (0x or -0x) if enabled
+    if (prefix) {
+        if (hex.startsWith('-')) {
+            hex = '-0x' + hex.slice(1);
+        }
+        else {
+            hex = '0x' + hex;
+        }
+    }
+    return hex;
+}

package/dist/formatting/index.d.ts

@@ -1,11 +1,53 @@
 export { capitalize } from './capitalize';
 export { formatNumber } from './number';
 export { formatPhone } from './phone';
+export { formatDuration } from './duration';
+export { trim } from './trim';
+export { formatRomanNumeral } from './romanNumerals';
+export { formatPercentage } from './percentage';
+export { formatFileSize } from './fileSize';
+export { formatOrdinal } from './ordinal';
+export { formatList } from './listToString';
+export { formatCreditCard } from './creditCard';
+export { formatToOctal } from './octal';
+export { formatTemperature } from './temperature';
+export { formatScientific } from './scientific';
+export { formatToBinary } from './binary';
+export { formatToHexadecimal } from './hexadecimal';
+export { formatToDecimal } from './decimal';
 import { capitalize } from './capitalize';
 import { formatNumber } from './number';
 import { formatPhone } from './phone';
+import { formatDuration } from './duration';
+import { trim } from './trim';
+import { formatRomanNumeral } from './romanNumerals';
+import { formatPercentage } from './percentage';
+import { formatFileSize } from './fileSize';
+import { formatOrdinal } from './ordinal';
+import { formatList } from './listToString';
+import { formatCreditCard } from './creditCard';
+import { formatToOctal } from './octal';
+import { formatTemperature } from './temperature';
+import { formatScientific } from './scientific';
+import { formatToBinary } from './binary';
+import { formatToHexadecimal } from './hexadecimal';
+import { formatToDecimal } from './decimal';
 export declare const formatting: {
     capitalize: typeof capitalize;
     formatNumber: typeof formatNumber;
     formatPhone: typeof formatPhone;
+    formatDuration: typeof formatDuration;
+    trim: typeof trim;
+    formatRomanNumeral: typeof formatRomanNumeral;
+    formatPercentage: typeof formatPercentage;
+    formatFileSize: typeof formatFileSize;
+    formatOrdinal: typeof formatOrdinal;
+    formatList: typeof formatList;
+    formatTemperature: typeof formatTemperature;
+    formatScientific: typeof formatScientific;
+    formatCreditCard: typeof formatCreditCard;
+    formatToBinary: typeof formatToBinary;
+    formatToHexadecimal: typeof formatToHexadecimal;
+    formatToOctal: typeof formatToOctal;
+    formatToDecimal: typeof formatToDecimal;
 };

package/dist/formatting/index.js

@@ -1,17 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatting = exports.formatPhone = exports.formatNumber = exports.capitalize = void 0;
+exports.formatting = exports.formatToDecimal = exports.formatToHexadecimal = exports.formatToBinary = exports.formatScientific = exports.formatTemperature = exports.formatToOctal = exports.formatCreditCard = exports.formatList = exports.formatOrdinal = exports.formatFileSize = exports.formatPercentage = exports.formatRomanNumeral = exports.trim = exports.formatDuration = exports.formatPhone = exports.formatNumber = exports.capitalize = void 0;
 var capitalize_1 = require("./capitalize");
 Object.defineProperty(exports, "capitalize", { enumerable: true, get: function () { return capitalize_1.capitalize; } });
 var number_1 = require("./number");
 Object.defineProperty(exports, "formatNumber", { enumerable: true, get: function () { return number_1.formatNumber; } });
 var phone_1 = require("./phone");
 Object.defineProperty(exports, "formatPhone", { enumerable: true, get: function () { return phone_1.formatPhone; } });
+var duration_1 = require("./duration");
+Object.defineProperty(exports, "formatDuration", { enumerable: true, get: function () { return duration_1.formatDuration; } });
+var trim_1 = require("./trim");
+Object.defineProperty(exports, "trim", { enumerable: true, get: function () { return trim_1.trim; } });
+var romanNumerals_1 = require("./romanNumerals");
+Object.defineProperty(exports, "formatRomanNumeral", { enumerable: true, get: function () { return romanNumerals_1.formatRomanNumeral; } });
+var percentage_1 = require("./percentage");
+Object.defineProperty(exports, "formatPercentage", { enumerable: true, get: function () { return percentage_1.formatPercentage; } });
+var fileSize_1 = require("./fileSize");
+Object.defineProperty(exports, "formatFileSize", { enumerable: true, get: function () { return fileSize_1.formatFileSize; } });
+var ordinal_1 = require("./ordinal");
+Object.defineProperty(exports, "formatOrdinal", { enumerable: true, get: function () { return ordinal_1.formatOrdinal; } });
+var listToString_1 = require("./listToString");
+Object.defineProperty(exports, "formatList", { enumerable: true, get: function () { return listToString_1.formatList; } });
+var creditCard_1 = require("./creditCard");
+Object.defineProperty(exports, "formatCreditCard", { enumerable: true, get: function () { return creditCard_1.formatCreditCard; } });
+var octal_1 = require("./octal");
+Object.defineProperty(exports, "formatToOctal", { enumerable: true, get: function () { return octal_1.formatToOctal; } });
+var temperature_1 = require("./temperature");
+Object.defineProperty(exports, "formatTemperature", { enumerable: true, get: function () { return temperature_1.formatTemperature; } });
+var scientific_1 = require("./scientific");
+Object.defineProperty(exports, "formatScientific", { enumerable: true, get: function () { return scientific_1.formatScientific; } });
+var binary_1 = require("./binary");
+Object.defineProperty(exports, "formatToBinary", { enumerable: true, get: function () { return binary_1.formatToBinary; } });
+var hexadecimal_1 = require("./hexadecimal");
+Object.defineProperty(exports, "formatToHexadecimal", { enumerable: true, get: function () { return hexadecimal_1.formatToHexadecimal; } });
+var decimal_1 = require("./decimal");
+Object.defineProperty(exports, "formatToDecimal", { enumerable: true, get: function () { return decimal_1.formatToDecimal; } });
 const capitalize_2 = require("./capitalize");
 const number_2 = require("./number");
 const phone_2 = require("./phone");
+const duration_2 = require("./duration");
+const trim_2 = require("./trim");
+const romanNumerals_2 = require("./romanNumerals");
+const percentage_2 = require("./percentage");
+const fileSize_2 = require("./fileSize");
+const ordinal_2 = require("./ordinal");
+const listToString_2 = require("./listToString");
+const creditCard_2 = require("./creditCard");
+const octal_2 = require("./octal");
+const temperature_2 = require("./temperature");
+const scientific_2 = require("./scientific");
+const binary_2 = require("./binary");
+const hexadecimal_2 = require("./hexadecimal");
+const decimal_2 = require("./decimal");
 exports.formatting = {
     capitalize: capitalize_2.capitalize,
     formatNumber: number_2.formatNumber,
     formatPhone: phone_2.formatPhone,
+    formatDuration: duration_2.formatDuration,
+    trim: trim_2.trim,
+    formatRomanNumeral: romanNumerals_2.formatRomanNumeral,
+    formatPercentage: percentage_2.formatPercentage,
+    formatFileSize: fileSize_2.formatFileSize,
+    formatOrdinal: ordinal_2.formatOrdinal,
+    formatList: listToString_2.formatList,
+    formatTemperature: temperature_2.formatTemperature,
+    formatScientific: scientific_2.formatScientific,
+    formatCreditCard: creditCard_2.formatCreditCard,
+    formatToBinary: binary_2.formatToBinary,
+    formatToHexadecimal: hexadecimal_2.formatToHexadecimal,
+    formatToOctal: octal_2.formatToOctal,
+    formatToDecimal: decimal_2.formatToDecimal
 };

package/dist/formatting/listToString.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Formats an array of strings into a human-readable list with proper commas and "and".
+ *
+ * Supports the Oxford comma for lists of three or more items.
+ * Returns an empty string for empty arrays.
+ *
+ * Examples:
+ * ["apples", "bananas", "cherries"] → "apples, bananas, and cherries"
+ * ["apples", "bananas"] → "apples and bananas"
+ * ["apple"] → "apple"
+ * [] → ""
+ *
+ * @param {string[]} arr - The array of strings to format into a readable list.
+ * @returns {string} The formatted human-readable list.
+ * @throws {TypeError} If the input is not an array of strings.
+ */
+export declare function formatList(arr: string[]): string;

package/dist/formatting/listToString.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatList = formatList;
+/**
+ * Formats an array of strings into a human-readable list with proper commas and "and".
+ *
+ * Supports the Oxford comma for lists of three or more items.
+ * Returns an empty string for empty arrays.
+ *
+ * Examples:
+ * ["apples", "bananas", "cherries"] → "apples, bananas, and cherries"
+ * ["apples", "bananas"] → "apples and bananas"
+ * ["apple"] → "apple"
+ * [] → ""
+ *
+ * @param {string[]} arr - The array of strings to format into a readable list.
+ * @returns {string} The formatted human-readable list.
+ * @throws {TypeError} If the input is not an array of strings.
+ */
+function formatList(arr) {
+    if (!Array.isArray(arr)) {
+        throw new TypeError('Input must be an array');
+    }
+    if (!arr.every(item => typeof item === 'string')) {
+        throw new TypeError('All elements in the array must be strings');
+    }
+    const len = arr.length;
+    if (len === 0)
+        return '';
+    if (len === 1)
+        return arr[0];
+    if (len === 2)
+        return `${arr[0]} and ${arr[1]}`;
+    return `${arr.slice(0, -1).join(', ')}, and ${arr[len - 1]}`;
+}

package/dist/formatting/octal.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Converts a decimal number to its octal (base-8) string representation.
+ *
+ * Supports negative numbers and an optional "0o" prefix.
+ *
+ * Examples:
+ * 8   → "10"
+ * 10  → "12"
+ * 255 → "377"
+ * 0   → "0"
+ *
+ * @param {number} num - The decimal number to convert.
+ * @param {{ prefix?: boolean }} [options] - Optional formatting options.
+ * @returns {string} The octal string representation, optionally prefixed with "0o".
+ * @throws {TypeError} If the input is not a number or is NaN.
+ */
+export declare function formatToOctal(num: number, options?: {
+    prefix?: boolean;
+}): string;

package/dist/formatting/octal.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToOctal = formatToOctal;
+/**
+ * Converts a decimal number to its octal (base-8) string representation.
+ *
+ * Supports negative numbers and an optional "0o" prefix.
+ *
+ * Examples:
+ * 8   → "10"
+ * 10  → "12"
+ * 255 → "377"
+ * 0   → "0"
+ *
+ * @param {number} num - The decimal number to convert.
+ * @param {{ prefix?: boolean }} [options] - Optional formatting options.
+ * @returns {string} The octal string representation, optionally prefixed with "0o".
+ * @throws {TypeError} If the input is not a number or is NaN.
+ */
+function formatToOctal(num, options) {
+    if (typeof num !== 'number' || Number.isNaN(num)) {
+        throw new TypeError('Input must be a number');
+    }
+    const includePrefix = (options === null || options === void 0 ? void 0 : options.prefix) === true;
+    const isNegative = num < 0;
+    const absoluteValue = Math.abs(num);
+    const octalCore = absoluteValue.toString(8);
+    const prefix = includePrefix ? '0o' : '';
+    const signedCore = `${prefix}${octalCore}`;
+    return isNegative ? `-${signedCore}` : signedCore;
+}

package/dist/formatting/ordinal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Converts a number into its ordinal string representation (e.g., 1 → "1st", 2 → "2nd").
+ *
+ * Handles special cases for 11, 12, and 13, which always use "th" regardless of their last digit.
+ * Supports both small and large numbers.
+ *
+ * Examples:
+ * 1 → "1st"
+ * 2 → "2nd"
+ * 3 → "3rd"
+ * 4 → "4th"
+ * 11 → "11th"
+ * 21 → "21st"
+ * 113 → "113th"
+ *
+ * @param {number} num - The number to convert to an ordinal string.
+ * @returns {string} The formatted ordinal string (e.g., "21st").
+ * @throws {TypeError} If the input is not a number.
+ */
+export declare function formatOrdinal(num: number): string;

package/dist/formatting/ordinal.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatOrdinal = formatOrdinal;
+/**
+ * Converts a number into its ordinal string representation (e.g., 1 → "1st", 2 → "2nd").
+ *
+ * Handles special cases for 11, 12, and 13, which always use "th" regardless of their last digit.
+ * Supports both small and large numbers.
+ *
+ * Examples:
+ * 1 → "1st"
+ * 2 → "2nd"
+ * 3 → "3rd"
+ * 4 → "4th"
+ * 11 → "11th"
+ * 21 → "21st"
+ * 113 → "113th"
+ *
+ * @param {number} num - The number to convert to an ordinal string.
+ * @returns {string} The formatted ordinal string (e.g., "21st").
+ * @throws {TypeError} If the input is not a number.
+ */
+function formatOrdinal(num) {
+    if (typeof num !== 'number' || Number.isNaN(num)) {
+        throw new TypeError('Input must be a number');
+    }
+    const absNum = Math.abs(num);
+    const lastTwoDigits = absNum % 100;
+    if (lastTwoDigits >= 11 && lastTwoDigits <= 13) {
+        return `${num}th`;
+    }
+    const lastDigit = absNum % 10;
+    switch (lastDigit) {
+        case 1:
+            return `${num}st`;
+        case 2:
+            return `${num}nd`;
+        case 3:
+            return `${num}rd`;
+        default:
+            return `${num}th`;
+    }
+}