@rsdoctor/utils 1.5.10 → 1.5.12

package/compiled/filesize/index.d.ts

@@ -1,58 +1,98 @@
-interface FileSizeOptionsBase {
-    base?: 10 | 2;
-    bits?: boolean;
-    exponent?: number;
-    fullform?: boolean;
-    fullforms?: string[];
-    locale?: string | boolean;
-    localeOptions?: Intl.DateTimeFormatOptions;
-    pad?: boolean;
-    precision?: number;
-    round?: number;
-    roundingMethod?: 'round' | 'floor' | 'ceil';
-    separator?: string;
-    spacer?: string;
-    standard?: 'si' | 'iec' | 'jedec';
-    symbols?: {};
-}
-
-interface FileSizeOptionsArray extends FileSizeOptionsBase {
-    output: 'array'
-}
-
-interface FileSizeOptionsExponent extends FileSizeOptionsBase {
-    output: 'exponent'
-}
-
-interface FileSizeOptionsObject extends FileSizeOptionsBase {
-    output: 'object'
-}
-
-interface FileSizeOptionsString extends FileSizeOptionsBase {
-    output: 'string'
-}
-
-interface FileSizeReturnObject {
-    value: string,
-    symbol: string,
-    exponent: number,
-    unit: string,
-}
-
-type FileSizeReturnArray = [ number, string ]
-
-type FileSizeOptionStringOrBase = FileSizeOptionsString | FileSizeOptionsBase;
-type FileSizeOptions = FileSizeOptionsArray | FileSizeOptionsExponent | FileSizeOptionsObject | FileSizeOptionStringOrBase | undefined
-type FileSizeReturnType<Options extends FileSizeOptions> =
-    Options extends FileSizeOptionsArray
-        ? FileSizeReturnArray
-        : Options extends FileSizeOptionsExponent
-        ? number
-        : Options extends FileSizeOptionsObject
-        ? FileSizeReturnObject
-        : string;
-
-declare function filesize<Options extends FileSizeOptions = undefined>(byteCount: number | string | bigint, options?: Options): FileSizeReturnType<Options> 
-declare function partial<Options extends FileSizeOptions = undefined>(options?: Options): (byteCount: number | string | bigint) => FileSizeReturnType<Options>
+/**
+ * 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;
+
+/**
+ * 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
+ * @example
+ * filesize(1024) // "1.02 kB"
+ * filesize(1024, {bits: true}) // "8.19 kbit"
+ * filesize(1024, {output: "object"}) // {value: 1.02, symbol: "kB", exponent: 1, unit: "kB"}
+ */
+declare function filesize<T extends FilesizeOptions = {}>(
+  arg: number | string | bigint,
+  options?: T
+): FilesizeReturn<T>;
+
+/**
+ * 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
+ * @example
+ * const formatBytes = partial({round: 1, standard: "iec"});
+ * formatBytes(1024) // "1 KiB"
+ * formatBytes(2048) // "2 KiB"
+ * formatBytes(1536) // "1.5 KiB"
+ */
+declare function partial<T extends FilesizeOptions = {}>(
+  options?: T
+): (arg: number | string | bigint) => FilesizeReturn<T>;
 
 export { filesize, partial };
+export type { FilesizeArray, FilesizeObject, FilesizeOptions, FilesizeReturn };