@digitalwalletcorp/utils 0.1.0 → 0.2.0

package/lib/number-util.d.cts

@@ -0,0 +1,223 @@
+/**
+ * 数値として扱える値の型
+ */
+export type NumberSource = number | string | bigint;
+/**
+ * 丸めモード
+ * 公開APIに内部の算術ライブラリ(big.js)の型を出さないよう、値を直接定義する(big.jsの丸めモードと同じ値)
+ */
+export declare const ROUNDING_MODE: {
+    /**
+     * Rounds towards zero.
+     * I.e. truncate, no rounding.
+     */
+    readonly roundDown: 0;
+    /**
+     * Rounds towards nearest neighbour.
+     * If equidistant, rounds away from zero.
+     */
+    readonly roundHalfUp: 1;
+    /**
+     * Rounds towards nearest neighbour.
+     * If equidistant, rounds towards even neighbour.
+     */
+    readonly roundHalfEven: 2;
+    /**
+     * Rounds away from zero.
+     */
+    readonly roundUp: 3;
+};
+export type RoundingMode = typeof ROUNDING_MODE[keyof typeof ROUNDING_MODE];
+/**
+ * long(64bit)の範囲(-9223372036854775808〜9223372036854775807)の値か判定する
+ * Javascriptのnumberの範囲は(-9007199254740991〜9007199254740991)である
+ *
+ * @param {string | bigint} value
+ * @param {*} [options]
+ *   ├ minValue number 最小値を指定する場合(0を指定すると負数の場合falseを返す)
+ *       不正な値を指定した場合は無視される(最小値を-9223372036854775808とみなす)
+ * @returns {boolean}
+ * @see Number.MAX_SAFE_INTEGER
+ * @see Number.MIN_SAFE_INTEGER
+ */
+export declare function isLongValue(value: string | bigint, options?: {
+    minValue?: number;
+}): boolean;
+/**
+ * 3桁ごとカンマ区切りした文字列を返す
+ * 指数表記の値(1e21など)は通常の表記に展開してから区切る
+ * 数値として解釈できない文字列はそのまま返し、NaN/Infinityは "NaN"/"Infinity"/"-Infinity" を返す
+ *
+ * @param {NumberSource | null | undefined} value 値
+ * @param {number} [scale] 小数点桁数(補助桁数)
+ * @param {RoundingMode} [roundingMode] 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+ * @returns {string}
+ */
+export declare function formatComma(value: NumberSource | null | undefined, scale?: number, roundingMode?: RoundingMode): string;
+/**
+ * カンマを除去する
+ *
+ * @param {string} value 入力値
+ * @returns {string} カンマを取り除いた文字列
+ */
+export declare function removeComma(value: string): string;
+/**
+ * 数値を表示ロケールの短縮表記にする。
+ * en は 1.2K/3.4M/5.6B、ja は 12万/34億 のように単位が切り替わる。
+ *
+ * @param {number} value 値
+ * @param {string} locale 表示ロケール(例 'ja' / 'en')
+ * @returns {string} 短縮表記の文字列
+ */
+export declare function formatCompact(value: number, locale: string): string;
+export type Operator = 'add' | 'sub' | 'times' | 'div';
+export interface OperationItem {
+    operator: Operator;
+    value: NumberSource | null | undefined;
+}
+/**
+ * 複数の演算をまとめて計算する
+ * 計算途中は精度を保持し、最後にnumberへ変換する
+ * この関数では四則演算の優先順位はなく、与えられた配列の順で計算を行う
+ * * 優先順位やカッコの概念がある場合は事前に計算したうえでこの関数を利用する
+ *
+ * 例)
+ * calc(
+ *   '123',
+ *   [
+ *     { operator: 'add', value: '123' },
+ *     { operator: 'sub', value: 100 },
+ *     { operator: 'times', value: 2 },
+ *     { operator: 'div', value: 3 }
+ *   ]
+ * )
+ * 123 + 123 = 246
+ * 246 - 100 = 146
+ * 146 * 2 = 292
+ * 292 / 3 = 97.33333333
+ *
+ * 数学的な感覚だと 123 + 123 - ((100 * 2) / 3) = 229.33333333 となるが、この関数はそのような計算を行わない
+ * null等の扱いは add / sub / times / div と同じ
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} initialValue
+ * @param {OperationItem[]} operationItems
+ *   ├ operator: Operator
+ *   ├ value: NumberSource | null | undefined
+ * @param {*} [options]
+ *   ├ scale 計算結果を丸める小数桁数。指定しない場合は丸めない
+ *   ├ roundingMode 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+ * @returns {number}
+ */
+export declare function calc(initialValue: NumberSource | null | undefined, operationItems: OperationItem[], options?: {
+    scale?: number;
+    roundingMode?: RoundingMode;
+}): number;
+/**
+ * 加算を行う
+ * null/undefined/空文字/NaNは0と見做されるため、演算結果に影響しない
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} value1
+ * @param {(NumberSource | null | undefined)[]} value2
+ * @returns {number}
+ */
+export declare function add(value1: NumberSource | null | undefined, ...value2: (NumberSource | null | undefined)[]): number;
+/**
+ * 減算を行う
+ * null/undefined/空文字/NaNは0と見做されるため、演算結果に影響しない
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} value1
+ * @param {(NumberSource | null | undefined)[]} value2
+ * @returns {number}
+ */
+export declare function sub(value1: NumberSource | null | undefined, ...value2: (NumberSource | null | undefined)[]): number;
+/**
+ * 乗算を行う
+ * null/undefined/空文字/NaNは0と見做されるため、演算結果は0になる
+ * 元の値を保持したい場合は times(price, discount ?? 1) のようにフォールバック値を指定する
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} value1
+ * @param {(NumberSource | null | undefined)[]} value2
+ * @returns {number}
+ */
+export declare function times(value1: NumberSource | null | undefined, ...value2: (NumberSource | null | undefined)[]): number;
+/**
+ * 除算を行う
+ * 割る値のnull/undefined/空文字/NaNは1と見做されるため、演算結果に影響しない
+ * 割る値に0を指定した場合はゼロ除算エラーになる
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} value1
+ * @param {(NumberSource | null | undefined)[]} value2
+ * @returns {number}
+ */
+export declare function div(value1: NumberSource | null | undefined, ...value2: (NumberSource | null | undefined)[]): number;
+/**
+ * 数値を指定した桁で丸める
+ * null/undefined/空文字はnull、数値として解釈できない文字列はNaNを返す
+ * NaN/Infinityはそのまま返す
+ * 戻り値はnumberのため、Number.MAX_SAFE_INTEGERを超える結果は精度が落ちる
+ *
+ * @param {NumberSource | null | undefined} value
+ * @param {number} scale
+ * @param {RoundingMode} roundingMode
+ *   0 切り捨て
+ *   1 四捨五入
+ *   2 ISO丸め
+ *   3 切り上げ
+ * @returns {number | null}
+ * @see ROUNDING_MODE
+ */
+export declare function round(value: NumberSource | null | undefined, scale: number, roundingMode: RoundingMode): number | null;
+/**
+ * 数値文字列に変換する
+ * 指数表記にはならず、通常の表記で返す
+ * 数値として解釈できない値はString(value)を返す
+ *
+ * @param {NumberSource | null | undefined} value
+ * @param {*} [options]
+ *   ├ scale 小数桁数。指定しない場合は丸めずにすべての桁を返す
+ *   ├ roundingMode 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+ * @returns {string}
+ * @see ROUNDING_MODE
+ */
+export declare function toString(value: NumberSource | null | undefined, options?: {
+    scale?: number;
+    roundingMode?: RoundingMode;
+}): string;
+/**
+ * 数値型をビットの配列に変換する
+ * 例)
+ * 7 => [1, 2, 4]
+ *
+ * 第二引数に候補値の配列を渡した場合、対象リストの中から該当するもののうち、値の大きなものから抽出して配列で返す
+ * 例)
+ * 86, [2, 4, 80] => [2, 4, 80]
+ * この例で第二引数を渡さない場合は 86 => [2, 4, 16, 64] になる
+ * 候補値はそのビットがすべて立っている場合のみ該当とする(16, [80] => [])
+ * いずれの候補値にも分類できないビットは無視される
+ * 小数は切り捨て、0以下は空配列を返す
+ *
+ * @param {number} a
+ * @param {(number | string)[]} [candidates]
+ * @returns {number[]}
+ */
+export declare function bitArray(a: number, candidates?: (number | string)[]): number[];
+/**
+ * 渡されたバイト数値を桁数に応じてMB,GBなどに単位を変更する
+ *
+ * @param {NumberSource} bytes
+ * @param {*} [options]
+ *   ┝ scale 小数以下桁数 デフォルト:2
+ *   ┝ roundingMode 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+ *   ┝ format フォーマットするか。trueを指定した場合、3桁カンマ区切り＋小数末尾0の桁揃え
+ * @returns {[string, string]} 精度以下を丸めた数値(文字列)と単位をタプルで返す
+ */
+export declare function formatBytes(bytes: NumberSource, options?: {
+    scale?: number;
+    roundingMode?: RoundingMode;
+    format?: boolean;
+}): [string, string];