feat: add TypeScript definitions for byte utility

index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Unit identifiers for byte sizes (lowercase).
+ */
+type BytesUnit = "b" | "kb" | "mb" | "gb" | "tb" | "pb";
+
+/**
+ * Unit identifiers for byte sizes (uppercase).
+ */
+type BytesUnitUpper = "B" | "KB" | "MB" | "GB" | "TB" | "PB";
+
+/**
+ * All valid unit identifier variations.
+ */
+type BytesUnitAny = BytesUnit | BytesUnitUpper;
+
+/**
+ * Valid byte size string formats that can be parsed.
+ *
+ * @example
+ * '50mb'
+ * '1.5gb'
+ * '100 KB'
+ * '-5mb'
+ * '+10gb'
+ */
+type BytesString =
+  | `${number}${BytesUnitAny}`
+  | `${number} ${BytesUnitAny}`
+  | `${number}.${number}${BytesUnitAny}`
+  | `${number}.${number} ${BytesUnitAny}`
+  | `+${number}${BytesUnitAny}`
+  | `+${number} ${BytesUnitAny}`
+  | `+${number}.${number}${BytesUnitAny}`
+  | `+${number}.${number} ${BytesUnitAny}`
+  | `-${number}${BytesUnitAny}`
+  | `-${number} ${BytesUnitAny}`
+  | `-${number}.${number}${BytesUnitAny}`
+  | `-${number}.${number} ${BytesUnitAny}`;
+
+/**
+ * Options for formatting bytes into a human-readable string.
+ */
+interface BytesOptions {
+  /**
+   * Number of decimal places to include in the output.
+   *
+   * @default 2
+   *
+   * @example
+   * bytes(1024, { decimalPlaces: 0 }); // '1KB'
+   * bytes(1024, { decimalPlaces: 2 }); // '1.00KB'
+   */
+  decimalPlaces?: number;
+
+  /**
+   * Whether to always include the specified number of decimal places,
+   * even if they are zero.
+   *
+   * @default false
+   *
+   * @example
+   * bytes(1024, { fixedDecimals: true, decimalPlaces: 2 }); // '1.00KB'
+   * bytes(1024, { fixedDecimals: false, decimalPlaces: 2 }); // '1KB'
+   */
+  fixedDecimals?: boolean;
+
+  /**
+   * Character to use as a thousands separator in the output.
+   *
+   * @default ''
+   *
+   * @example
+   * bytes(1000000, { thousandsSeparator: ',' }); // '976.56KB' or '1,000,000B'
+   */
+  thousandsSeparator?: string;
+
+  /**
+   * The unit to use for formatting.
+   * If not specified, the most appropriate unit is chosen automatically.
+   *
+   * @example
+   * bytes(1024, { unit: 'kb' }); // '1KB'
+   * bytes(1048576, { unit: 'kb' }); // '1024KB'
+   */
+  unit?: BytesUnitAny;
+
+  /**
+   * Character to use as a separator between the numeric value and the unit.
+   *
+   * @default ''
+   *
+   * @example
+   * bytes(1024, { unitSeparator: ' ' }); // '1 KB'
+   * bytes(1024, { unitSeparator: '' }); // '1KB'
+   */
+  unitSeparator?: string;
+}
+
+/**
+ * Convert a human-readable byte size string to bytes as an integer.
+ *
+ * If the input is a number, it is returned as-is.
+ * If the input is an invalid string format, returns `null`.
+ *
+ * @param value - The value to parse (e.g., '5MB', '1.5GB', 1024)
+ * @returns The number of bytes, or `null` if parsing fails
+ *
+ * @example
+ * bytes.parse('1KB'); // 1024
+ * bytes.parse('1MB'); // 1048576
+ * bytes.parse('1GB'); // 1073741824
+ * bytes.parse('invalid'); // null
+ * bytes.parse(1024); // 1024
+ */
+declare function parse(value: BytesString): number | null;
+declare function parse(value: number): number;
+declare function parse(value: BytesString | number): number | null;
+
+/**
+ * Format bytes as a human-readable string.
+ *
+ * If the value is not a finite number, returns `null`.
+ *
+ * @param value - The number of bytes to format
+ * @param options - Formatting options
+ * @returns A human-readable string (e.g., '5MB', '1.5GB'), or `null` if the value is invalid
+ *
+ * @example
+ * bytes.format(1024); // '1KB'
+ * bytes.format(1048576); // '1MB'
+ * bytes.format(1073741824, { decimalPlaces: 2 }); // '1.00GB'
+ * bytes.format(Infinity); // null
+ */
+declare function format(
+  value: number,
+  options?: BytesOptions
+): BytesString | null;
+
+/**
+ * Convert the given value to/from bytes.
+ *
+ * - If `value` is a string, it is parsed to bytes (integer).
+ * - If `value` is a number, it is formatted to a human-readable string.
+ * - Returns `null` if the conversion fails.
+ *
+ * @param value - A string to parse or a number to format
+ * @param options - Options for formatting (only used when `value` is a number)
+ * @returns The converted value, or `null` if conversion fails
+ *
+ * @example
+ * // Parsing string to bytes
+ * bytes('1KB'); // 1024
+ * bytes('1MB'); // 1048576
+ * bytes('invalid'); // null
+ *
+ * // Formatting number to string
+ * bytes(1024); // '1KB'
+ * bytes(1048576); // '1MB'
+ * bytes(1073741824, { decimalPlaces: 2, unitSeparator: ' ' }); // '1.00 GB'
+ */
+declare function bytes(value: BytesString): number | null;
+declare function bytes(
+  value: number,
+  options?: BytesOptions
+): BytesString | null;
+declare function bytes(
+  value: BytesString | number,
+  options?: BytesOptions
+): BytesString | number | null;
+
+declare namespace bytes {
+  export {
+    parse,
+    format,
+    BytesOptions,
+    BytesString,
+    BytesUnit,
+    BytesUnitUpper,
+    BytesUnitAny,
+  };
+}
+
+export = bytes;

package.json

@@ -18,6 +18,7 @@
     "converter"
   ],
   "repository": "visionmedia/bytes.js",
+  "types": "index.d.ts",
   "devDependencies": {
     "eslint": "7.32.0",
     "eslint-plugin-markdown": "2.2.1",
@@ -28,7 +29,8 @@
     "History.md",
     "LICENSE",
     "Readme.md",
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "engines": {
     "node": ">= 0.8"