FormatBytesOptions — @gj-kit/format

A public type from @gj-kit/format. The signature below is taken directly from the 0.1.1 release declaration.

Verified import example

import { FormatBytesOptions } from '@gj-kit/format';

Signature, parameters, and return type

type FormatBytesOptions<TFallback = string> = {
    /** Required: `'1.5 GB'` vs `'1.5GB'` — the source apps disagreed. */
    readonly unitSpace: boolean;
    /**
     * Required policy for zero and negative input — the source apps disagreed and
     * the difference is visible: admin renders `'0 B'`/`'-5 B'`, mobile treats
     * anything `<= 0` as "size unknown" and hides the chip.
     * `'render'` formats the value; `'fallback'` returns `fallback`.
     */
    readonly nonPositive: 'render' | 'fallback';
    /**
     * How trailing zeros are handled. Default `'keep'`.
     * - `'keep'`       renders `'1.0 GB'` — fixed column width (`toFixed`).
     * - `'trim'`       renders `'1GB'` — drops trailing zeros after rounding.
     * - `'trim-exact'` drops the fraction only when the value was an exact
     *                  integer *before* rounding, so `1.04 GB` still renders
     *                  `'1.0GB'`. This is not the same as `'trim'`; it is what
     *                  `Number.isInteger(v) ? v : v.toFixed(1)` does.
     */
    readonly trailingZeros?: 'keep' | 'trim' | 'trim-exact' | undefined;
    /** Values >= this (in the chosen unit) render as integers (e.g. 10 gives `'12MB'`). */
    readonly wholeNumberFrom?: number | undefined;
    /** Rendered for null/undefined/non-finite input, and for non-positive input
     *  when `nonPositive` is `'fallback'`. Default `'-'`. */
    readonly fallback?: TFallback | undefined;
} & ({
    /** Decimal SI: 1 KB = 1000 B. Unit labels KB/MB/.../PB. */
    readonly system: 'decimal';
    /**
     * Exact fraction digits above the B unit — a single value, or a per-unit
     * map when the policy differs by unit. Default 1.
     * The per-unit form exists because a real source app rounds MB to whole
     * numbers while giving GB/TB one decimal, and no numeric threshold can
     * separate those two ranges (both span 1-999 in their own unit).
     */
    readonly fractionDigits?: ByteFractionDigits | Partial<Record<FormatDecimalByteUnit, ByteFractionDigits>> | undefined;
    readonly minUnit?: FormatDecimalByteUnit | undefined;
    readonly maxUnit?: FormatDecimalByteUnit | undefined;
} | {
    /** Binary: 1 KiB = 1024 B. Unit labels KiB/MiB/.../PiB. */
    readonly system: 'binary';
    readonly fractionDigits?: ByteFractionDigits | Partial<Record<FormatBinaryByteUnit, ByteFractionDigits>> | undefined;
    readonly minUnit?: FormatBinaryByteUnit | undefined;
    readonly maxUnit?: FormatBinaryByteUnit | undefined;
});

This declaration is the source of truth for parameters, optionality, generics, return values, and public union/type contracts. Check the package golden path and this subpath’s import conditions for required environment, permission, and error boundaries before calling it.

Release context

• Package: @gj-kit/format
• Version: 0.1.1
• Public entry: .
• Source: GitHub