Filesize

import { filesize, partial } from "filesize";

const { filesize, partial } = require("filesize");

import { filesize } from "filesize";

// Basic usage - converts bytes to human-readable format
filesize(1000)        // "1 kB" (decimal by default)
filesize(1024)        // "1.02 kB"
filesize(1048576)     // "1.05 MB"

// Use binary standard (1024-based)
filesize(1024, { standard: "iec" })     // "1 KiB"
filesize(1048576, { standard: "iec" })  // "1 MiB"

// Convert to bits instead of bytes
filesize(1000, { bits: true })   // "8 kbit"

// Custom formatting
filesize(1536, { round: 1 })     // "1.5 kB"
filesize(1536, { round: 0 })     // "2 kB"

// Different output formats
filesize(1000, { output: "array" })   // [1, "kB"]
filesize(1000, { output: "object" })  // {value: 1, symbol: "kB", exponent: 1, unit: "kB"}

/**
 * Converts a file size in bytes to a human-readable string with appropriate units
 * @param arg - The file size in bytes to convert
 * @param options - Configuration options for formatting
 * @returns Formatted file size based on output option
 * @throws {TypeError} When arg is not a valid number or roundingMethod is invalid
 */
function filesize<T extends FilesizeOptions = {}>(
  arg: number | string | bigint,
  options?: T
): FilesizeReturn<T>;

// Basic conversions
filesize(1024)                    // "1.02 kB"
filesize(1000000)                 // "1 MB"
filesize(1073741824)              // "1.07 GB"

// Negative numbers
filesize(-1000)                   // "-1 kB"

// Different standards
filesize(1024, { standard: "iec" })    // "1 KiB" (binary)
filesize(1000, { standard: "si" })     // "1 kB" (decimal)
filesize(1024, { standard: "jedec" })  // "1 KB" (binary with decimal symbols)

// Bits vs bytes
filesize(1000, { bits: true })         // "8 kbit"
filesize(1024, { bits: true, standard: "iec" }) // "8 Kibit"

// Precision control
filesize(1536, { round: 0 })           // "2 kB"
filesize(1536, { round: 1 })           // "1.5 kB"
filesize(1536, { round: 3 })           // "1.536 kB"

// Rounding methods
filesize(1536, { roundingMethod: "floor" })  // "1.53 kB"
filesize(1536, { roundingMethod: "ceil" })   // "1.54 kB"

// Different output formats
filesize(1000, { output: "string" })   // "1 kB" (default)
filesize(1000, { output: "array" })    // [1, "kB"]
filesize(1000, { output: "object" })   // {value: 1, symbol: "kB", exponent: 1, unit: "kB"}
filesize(1000, { output: "exponent" }) // 1

// Localization
filesize(1536.7, { locale: "de-DE" })  // "1,54 kB"
filesize(1536.7, { locale: true })     // Uses system locale

// Custom separators and spacing
filesize(1536, { separator: "," })     // "1,54 kB"
filesize(1536, { spacer: "_" })        // "1.54_kB"

// Full unit names
filesize(1024, { fullform: true, standard: "iec" })  // "1 kibibyte"
filesize(2048, { fullform: true, standard: "iec" })  // "2 kibibytes"

// Custom symbols
filesize(1024, { symbols: { "kB": "kilobytes" } })   // "1.02 kilobytes"

// Padding decimal places
filesize(1000, { pad: true, round: 2 }) // "1.00 kB"

/**
 * Creates a partially applied version of filesize with preset options
 * @param options - Default options to apply to the returned function
 * @returns A function that takes a file size and returns formatted output
 */
function partial<T extends FilesizeOptions = {}>(
  options?: T
): (arg: number | string | bigint) => FilesizeReturn<T>;

import { partial } from "filesize";

// Create formatters with preset options
const formatBinary = partial({ standard: "iec", round: 1 });
const formatBits = partial({ bits: true, round: 0 });
const formatCompact = partial({ round: 0, spacer: "" });

// Use preset formatters
formatBinary(1024)    // "1.0 KiB"
formatBinary(2048)    // "2.0 KiB"

formatBits(1000)      // "8 kbit"
formatBits(2000)      // "16 kbit"

formatCompact(1536)   // "2kB"
formatCompact(2048)   // "2kB"

// Create object output formatter
const toObject = partial({ output: "object" });
toObject(1000);       // {value: 1, symbol: "kB", exponent: 1, unit: "kB"}

/**
 * Options interface for configuring filesize behavior
 */
interface FilesizeOptions {
  /** If true, calculates bits instead of bytes */
  bits?: boolean;
  /** If true, pads decimal places to match round parameter */
  pad?: boolean;
  /** Number base (2 for binary, 10 for decimal, -1 for auto) */
  base?: number;
  /** Number of decimal places to round to */
  round?: number;
  /** Locale for number formatting, true for system locale */
  locale?: string | boolean;
  /** Additional options for locale formatting */
  localeOptions?: Intl.NumberFormatOptions;
  /** Custom decimal separator */
  separator?: string;
  /** String to separate value and unit */
  spacer?: string;
  /** Custom unit symbols */
  symbols?: Record<string, string>;
  /** Unit standard to use (SI, IEC, JEDEC) */
  standard?: "si" | "iec" | "jedec" | "";
  /** Output format: "string", "array", "object", or "exponent" */
  output?: "string" | "array" | "object" | "exponent";
  /** If true, uses full unit names instead of abbreviations */
  fullform?: boolean;
  /** Custom full unit names */
  fullforms?: string[];
  /** Force specific exponent (-1 for auto) */
  exponent?: number;
  /** Math rounding method to use */
  roundingMethod?: "round" | "floor" | "ceil";
  /** Number of significant digits (0 for auto) */
  precision?: number;
}

/**
 * Object format return type when output is "object"
 */
interface FilesizeObject {
  /** The numeric value */
  value: number | string;
  /** The unit symbol */
  symbol: string;
  /** The exponent used in calculation */
  exponent: number;
  /** The original unit before symbol customization */
  unit: string;
}

/**
 * Array format return type when output is "array"
 */
type FilesizeArray = [number | string, string];

/**
 * Return type based on output option
 */
type FilesizeReturn<T extends FilesizeOptions = {}> =
  T['output'] extends "object" ? FilesizeObject :
  T['output'] extends "array" ? FilesizeArray :
  T['output'] extends "exponent" ? number :
  string;