@digitalwalletcorp/utils 0.2.0 → 0.4.0

package/src/decimal.ts

@@ -0,0 +1,294 @@
+/**
+ * このクラス Decimal の役割は、算術演算の実体としての Big を内部に閉じ込め、利用者側に露出させないことにある。
+ * 2026-10-08時点では big.js に依存しているが、将来的に演算演算のライブラリを変更した場合に
+ * 安全・簡単に移行できることを目的としている。
+ */
+import { Big } from 'big.js';
+
+/**
+ * 数値として扱える値の型
+ */
+export type NumberSource = number | string | bigint;
+
+/**
+ * 丸めモード
+ */
+export const ROUNDING_MODE = {
+  /**
+   * Rounds towards zero.
+   * I.e. truncate, no rounding.
+   */
+  roundDown: 0,
+  /**
+   * Rounds towards nearest neighbour.
+   * If equidistant, rounds away from zero.
+   */
+  roundHalfUp: 1,
+  /**
+   * Rounds towards nearest neighbour.
+   * If equidistant, rounds towards even neighbour.
+   */
+  roundHalfEven: 2,
+  /**
+   * Rounds away from zero.
+   */
+  roundUp: 3
+} as const;
+
+export type RoundingMode = typeof ROUNDING_MODE[keyof typeof ROUNDING_MODE];
+
+/**
+ * Decimalの生成・演算に渡せる値の型
+ * null/undefined/空文字/NaNは0とみなす(divの割る値は1とみなす)
+ */
+export type DecimalSource = NumberSource | Decimal | null | undefined;
+
+/** 除算で保持する小数桁数 */
+const DIVISION_SCALE = 20;
+
+/** 数値として解釈できる文字列のパターン(符号・小数点・指数表記) */
+const NUMERIC_STRING_PATTERN = /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+
+// 独立したコンストラクタにすることで、利用側がグローバルの Big.DP / Big.RM を書き換えても影響を受けないようにする
+const BigNumber = Big();
+BigNumber.DP = DIVISION_SCALE;
+BigNumber.RM = ROUNDING_MODE.roundHalfUp;
+
+// null/undefined/空文字/NaNはtrueを返す
+const isEmpty = (value: DecimalSource): value is null | undefined | '' => value == null || value === '' || (typeof value === 'number' && Number.isNaN(value));
+
+/**
+ * 任意精度の10進数を表す不変オブジェクト
+ * 演算メソッドは自身を変更せず、結果を新しいインスタンスで返す
+ * 除算は小数20桁(roundHalfUp)まで保持し、それ以降の桁は切り捨てではなく丸める
+ */
+export class Decimal {
+  /** 丸めモード */
+  public static readonly ROUNDING_MODE = ROUNDING_MODE;
+
+  /**
+   * 算術演算インスタンス
+   */
+  private big: Big;
+
+  /**
+   * @param {DecimalSource} value 数値、数値文字列、bigint、Decimal
+   *   null/undefined/空文字/NaNは0とみなす
+   *   数値として解釈できない文字列・Infinityは TypeError をスローする
+   */
+  constructor(value: DecimalSource) {
+    this.big = Decimal.toBig(value);
+  }
+
+  private static toBig(value: DecimalSource): Big {
+    if (isEmpty(value)) {
+      return BigNumber(0);
+    }
+    if (value instanceof Decimal) {
+      return value.big;
+    }
+    switch (typeof value) {
+      case 'number':
+        if (!Number.isFinite(value)) {
+          throw new TypeError(`Invalid number: ${value}`);
+        }
+        return BigNumber(value);
+      case 'bigint':
+        return BigNumber(value.toString());
+      default: {
+        const trimmed = value.trim();
+        if (!NUMERIC_STRING_PATTERN.test(trimmed)) {
+          throw new TypeError(`Invalid number: ${value}`);
+        }
+        // 先頭の '+' は数値として解釈できる表記だが、内部の算術ライブラリが受け付けないため取り除く
+        return BigNumber(trimmed.replace(/^\+/, ''));
+      }
+    }
+  }
+
+  private static wrap(big: Big): Decimal {
+    const decimal = new Decimal(0);
+    decimal.big = big;
+    return decimal;
+  }
+
+  /**
+   * 加算した結果を返す
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {Decimal}
+   */
+  public add(value: DecimalSource): Decimal {
+    return Decimal.wrap(this.big.add(Decimal.toBig(value)));
+  }
+
+  /**
+   * 減算した結果を返す
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {Decimal}
+   */
+  public sub(value: DecimalSource): Decimal {
+    return Decimal.wrap(this.big.sub(Decimal.toBig(value)));
+  }
+
+  /**
+   * 乗算した結果を返す
+   * null/undefined/空文字/NaNは0とみなすため、結果は0になる
+   * 元の値を保持したい場合は times(discount ?? 1) のようにフォールバック値を指定する
+   *
+   * @param {DecimalSource} value
+   * @returns {Decimal}
+   */
+  public times(value: DecimalSource): Decimal {
+    // 掛ける値が空のとき、0とみなすべきか元の値を保持すべきかは計算対象によって異なる
+    //   手数料 x 件数: 件数が未定義なら総額は0が適切
+    //   商品価格 x 割引率: 割引率が未定義なら元の価格が適切
+    // 1とみなすと、new Decimal(null).times(3) は 0、new Decimal(3).times(null) は 3 になり、引数の順序で結果が変わる
+    // そのため常に0とみなし、元の値を保持したい場合は呼び出し側でフォールバック値を指定する
+    return Decimal.wrap(this.big.times(Decimal.toBig(value)));
+  }
+
+  /**
+   * 除算した結果を返す
+   * 結果は小数20桁(roundHalfUp)まで保持する
+   * 割る値のnull/undefined/空文字/NaNは1とみなすため、結果は元の値と同じになる
+   * 割る値に0を指定した場合は RangeError をスローする
+   *
+   * @param {DecimalSource} value
+   * @returns {Decimal}
+   */
+  public div(value: DecimalSource): Decimal {
+    // 割る値が空のとき、0とみなすとすべてゼロ除算エラーになり計算が成り立たないため1とみなす
+    if (isEmpty(value)) {
+      return Decimal.wrap(this.big);
+    }
+    const divisor = Decimal.toBig(value);
+    if (divisor.eq(0)) {
+      throw new RangeError('Division by zero');
+    }
+    return Decimal.wrap(this.big.div(divisor));
+  }
+
+  /**
+   * 指定した小数桁で丸めた結果を返す
+   * 負の桁数を指定すると整数部を丸める(-2 なら百の位)
+   *
+   * @param {number} [scale] 小数桁数 デフォルトは0
+   * @param {RoundingMode} [roundingMode] 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+   * @returns {Decimal}
+   */
+  public round(scale: number = 0, roundingMode: RoundingMode = ROUNDING_MODE.roundHalfUp): Decimal {
+    return Decimal.wrap(this.big.round(scale, roundingMode));
+  }
+
+  /**
+   * 絶対値を返す
+   *
+   * @returns {Decimal}
+   */
+  public abs(): Decimal {
+    return Decimal.wrap(this.big.abs());
+  }
+
+  /**
+   * 値を比較する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {-1 | 0 | 1} 自身が小さければ-1、等しければ0、大きければ1
+   */
+  public compareTo(value: DecimalSource): -1 | 0 | 1 {
+    return this.big.cmp(Decimal.toBig(value));
+  }
+
+  /**
+   * 等しいか判定する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {boolean}
+   */
+  public eq(value: DecimalSource): boolean {
+    return this.compareTo(value) === 0;
+  }
+
+  /**
+   * 自身が小さいか判定する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {boolean}
+   */
+  public lt(value: DecimalSource): boolean {
+    return this.compareTo(value) < 0;
+  }
+
+  /**
+   * 自身が小さいか等しいか判定する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {boolean}
+   */
+  public lte(value: DecimalSource): boolean {
+    return this.compareTo(value) <= 0;
+  }
+
+  /**
+   * 自身が大きいか判定する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {boolean}
+   */
+  public gt(value: DecimalSource): boolean {
+    return 0 < this.compareTo(value);
+  }
+
+  /**
+   * 自身が大きいか等しいか判定する
+   * null/undefined/空文字/NaNは0とみなす
+   *
+   * @param {DecimalSource} value
+   * @returns {boolean}
+   */
+  public gte(value: DecimalSource): boolean {
+    return 0 <= this.compareTo(value);
+  }
+
+  /**
+   * numberに変換する
+   * Number.MAX_SAFE_INTEGERを超える値や、numberで表現できない桁数の小数は精度が落ちる
+   *
+   * @returns {number}
+   */
+  public toNumber(): number {
+    return this.big.toNumber();
+  }
+
+  /**
+   * 指定した小数桁で丸め、小数桁を0で埋めた文字列に変換する
+   * 指数表記にはならず、通常の表記で返す
+   * 丸めた結果が0になる場合は符号を付けない
+   *
+   * @param {number} scale 小数桁数
+   * @param {RoundingMode} [roundingMode] 丸めモード デフォルトはROUNDING_MODE.roundHalfUp(四捨五入・half-away-from-zero)
+   * @returns {string}
+   */
+  public toFixed(scale: number, roundingMode: RoundingMode = ROUNDING_MODE.roundHalfUp): string {
+    return this.big.round(scale, roundingMode).toFixed(scale);
+  }
+
+  /**
+   * 文字列に変換する
+   * 指数表記にはならず、通常の表記で返す
+   *
+   * @returns {string}
+   */
+  public toString(): string {
+    return this.big.toFixed();
+  }
+}

package/src/file-util.ts

@@ -0,0 +1,281 @@
+/** 先頭バイトの署名から判定したファイルの種類 */
+export interface FileType {
+  /** 拡張子(ドットなし) */
+  ext: string;
+  /** MIMEタイプ */
+  mime: string;
+}
+
+/** バイナリとして受け付ける値。Node.js の Buffer も ArrayBufferView として渡せる */
+export type BinaryInput = ArrayBuffer | ArrayBufferView;
+
+const DATA_URL_PATTERN = /^data:([^;,]+)?(?:;[^,]*)?;base64,(.*)$/s;
+
+const DEFAULT_MIME_TYPE = 'application/octet-stream';
+
+/** 種類の判定に使う先頭の base64 の文字数。ZIP の中のエントリ名を探すため数KB分を見る */
+const SIGNATURE_BASE64_LENGTH = 16384;
+
+const SVG_PATTERN = /^\ufeff?\s*(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*(?:<!DOCTYPE[^>]*>\s*)?<svg[\s>]/i;
+
+const OFFICE_FILE_TYPES: { entry: string; type: FileType; }[] = [
+  { entry: 'word/', type: { ext: 'docx', mime: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' } },
+  { entry: 'xl/', type: { ext: 'xlsx', mime: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' } },
+  { entry: 'ppt/', type: { ext: 'pptx', mime: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' } }
+];
+
+const toBytes = (data: BinaryInput): Uint8Array => {
+  return data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+};
+
+const toArrayBuffer = (data: BinaryInput): ArrayBuffer => toBytes(data).slice().buffer as ArrayBuffer;
+
+const startsWith = (bytes: Uint8Array, signature: number[] | string, offset: number = 0): boolean => {
+  const expected = typeof signature === 'string' ? Array.from(signature, c => c.charCodeAt(0)) : signature;
+  if (bytes.length < offset + expected.length) {
+    return false;
+  }
+  return expected.every((value, i) => bytes[offset + i] === value);
+};
+
+const detectFileType = (bytes: Uint8Array): FileType | null => {
+  if (startsWith(bytes, [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A])) {
+    return { ext: 'png', mime: 'image/png' };
+  }
+  if (startsWith(bytes, [0xFF, 0xD8, 0xFF])) {
+    return { ext: 'jpg', mime: 'image/jpeg' };
+  }
+  if (startsWith(bytes, 'GIF87a') || startsWith(bytes, 'GIF89a')) {
+    return { ext: 'gif', mime: 'image/gif' };
+  }
+  if (startsWith(bytes, 'RIFF') && startsWith(bytes, 'WEBP', 8)) {
+    return { ext: 'webp', mime: 'image/webp' };
+  }
+  if (startsWith(bytes, 'BM')) {
+    return { ext: 'bmp', mime: 'image/bmp' };
+  }
+  if (startsWith(bytes, [0x49, 0x49, 0x2A, 0x00]) || startsWith(bytes, [0x4D, 0x4D, 0x00, 0x2A])) {
+    return { ext: 'tif', mime: 'image/tiff' };
+  }
+  if (startsWith(bytes, '%PDF-')) {
+    return { ext: 'pdf', mime: 'application/pdf' };
+  }
+  if (startsWith(bytes, [0x50, 0x4B, 0x03, 0x04]) || startsWith(bytes, [0x50, 0x4B, 0x05, 0x06]) || startsWith(bytes, [0x50, 0x4B, 0x07, 0x08])) {
+    // Office Open XML も ZIP なので、ZIP に含まれるエントリ名で見分ける
+    const text = new TextDecoder('latin1').decode(bytes);
+    const office = OFFICE_FILE_TYPES.find(a => text.includes(a.entry));
+    return office ? office.type : { ext: 'zip', mime: 'application/zip' };
+  }
+  if (SVG_PATTERN.test(new TextDecoder().decode(bytes))) {
+    return { ext: 'svg', mime: 'image/svg+xml' };
+  }
+  return null;
+};
+
+/**
+ * base64 データと MIME タイプから DataURL を生成する
+ *
+ * @param {string} base64
+ * @param {string} [mimeType] 省略時は 'application/octet-stream'
+ * @returns {string}
+ */
+export function createDataURL(base64: string, mimeType?: string): string {
+  return `data:${mimeType || DEFAULT_MIME_TYPE};base64,${base64}`;
+}
+
+/**
+ * DataURL を base64 データと MIME タイプに分解する
+ * MIME タイプは DataURL に書かれた値ではなく、データの先頭バイトから判定した値を返す。判定できない場合は DataURL に書かれた値、それもなければ 'application/octet-stream'
+ * DataURL 形式でない文字列は base64 データとみなす
+ *
+ * @param {string} dataURL
+ * @returns {[string, string]} [base64, mimeType]
+ */
+export function parseDataURL(dataURL: string): [string, string] {
+  const matcher = DATA_URL_PATTERN.exec(dataURL);
+  const base64 = matcher ? matcher[2] : dataURL;
+  return [base64, analyzeFileType(base64)?.mime ?? matcher?.[1] ?? DEFAULT_MIME_TYPE];
+}
+
+/**
+ * データを読み込み DataURL を返す
+ * 文字列は、DataURL 形式ならそのまま、そうでなければ base64 データとみなす
+ * Blob は Blob の type を、それがなければ先頭バイトから判定した MIME タイプを使う
+ *
+ * @param {string | Blob | BinaryInput} data
+ * @returns {Promise<string>}
+ */
+export async function readAsDataURL(data: string | Blob | BinaryInput): Promise<string> {
+  if (typeof data === 'string') {
+    return DATA_URL_PATTERN.test(data) ? data : base64ToDataURL(data);
+  }
+  if (data instanceof Blob) {
+    const buffer = await data.arrayBuffer();
+    return arrayBufferToDataURL(buffer, data.type || analyzeFileType(buffer)?.mime);
+  }
+  return arrayBufferToDataURL(data, analyzeFileType(data)?.mime);
+}
+
+/**
+ * データを読み込み ArrayBuffer を返す
+ * 文字列は、DataURL 形式ならその base64 部分を、そうでなければ base64 データとみなして変換する
+ *
+ * @param {string | Blob | BinaryInput} data
+ * @returns {Promise<ArrayBuffer>}
+ */
+export async function readAsArrayBuffer(data: string | Blob | BinaryInput): Promise<ArrayBuffer> {
+  if (typeof data === 'string') {
+    return dataURLToArrayBuffer(data);
+  }
+  if (data instanceof Blob) {
+    return data.arrayBuffer();
+  }
+  return toArrayBuffer(data);
+}
+
+/**
+ * base64 データを DataURL に変換する
+ * MIME タイプを省略した場合はデータの先頭バイトから判定する
+ *
+ * @param {string} base64
+ * @param {string} [mimeType]
+ * @returns {string} base64 が空の場合はそのまま返す
+ */
+export function base64ToDataURL(base64: string, mimeType?: string): string {
+  if (!base64) {
+    return base64;
+  }
+  return createDataURL(base64, mimeType || analyzeFileType(base64)?.mime);
+}
+
+/**
+ * base64 データを ArrayBuffer に変換する
+ *
+ * @param {string} base64
+ * @returns {ArrayBuffer}
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+/**
+ * DataURL から base64 データを取り出す
+ *
+ * @param {string} dataURL
+ * @returns {string} DataURL 形式でない場合はそのまま返す
+ */
+export function dataURLToBase64(dataURL: string): string {
+  return DATA_URL_PATTERN.exec(dataURL)?.[2] ?? dataURL;
+}
+
+/**
+ * DataURL を ArrayBuffer に変換する
+ *
+ * @param {string} dataURL
+ * @returns {ArrayBuffer}
+ */
+export function dataURLToArrayBuffer(dataURL: string): ArrayBuffer {
+  return base64ToArrayBuffer(dataURLToBase64(dataURL));
+}
+
+/**
+ * バイナリを base64 データに変換する
+ *
+ * @param {BinaryInput} data
+ * @returns {string}
+ */
+export function arrayBufferToBase64(data: BinaryInput): string {
+  const bytes = toBytes(data);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * バイナリを DataURL に変換する
+ *
+ * @param {BinaryInput} data
+ * @param {string} [mimeType] 省略時は 'application/octet-stream'
+ * @returns {string}
+ */
+export function arrayBufferToDataURL(data: BinaryInput, mimeType?: string): string {
+  return createDataURL(arrayBufferToBase64(data), mimeType);
+}
+
+/**
+ * base64 データまたは DataURL が表すデータのバイト数を返す
+ *
+ * @param {string} data
+ * @returns {number}
+ */
+export function calcSize(data: string): number {
+  return dataURLToArrayBuffer(data).byteLength;
+}
+
+/**
+ * 文字列またはバイナリを、BOM 付き UTF-16 の CSV の Blob にする
+ * バイナリはすでに UTF-16LE で符号化されているものとして BOM だけを付ける
+ *
+ * @param {string | BinaryInput} data
+ * @returns {Blob}
+ */
+export function convertUTF16withBOM(data: string | BinaryInput): Blob {
+  if (!data) {
+    return new Blob([]);
+  }
+  let parts: BlobPart[];
+  if (typeof data === 'string') {
+    const text = `\ufeff${data}`;
+    const codes = new Uint16Array(text.length);
+    for (let i = 0; i < text.length; i++) {
+      codes[i] = text.charCodeAt(i);
+    }
+    parts = [codes];
+  } else {
+    // 文字列で BOM を渡すと Blob が UTF-8 で符号化してしまうため、UTF-16LE の BOM をバイト列で付ける
+    parts = [new Uint8Array([0xFF, 0xFE]), toArrayBuffer(data)];
+  }
+  return new Blob(parts, { type: 'text/csv;charset=utf-16;' });
+}
+
+/**
+ * データの先頭バイトの署名からファイルの種類を判定する
+ * 判定できる種類: PNG / JPEG / GIF / WebP / BMP / TIFF / SVG / PDF / ZIP / XLSX / DOCX / PPTX
+ * 文字列は、DataURL 形式ならその base64 部分を、そうでなければ base64 データとみなす
+ *
+ * @param {string | BinaryInput} data
+ * @returns {FileType | null} 判定できない場合は null
+ */
+export function analyzeFileType(data: string | BinaryInput): FileType | null {
+  let bytes: Uint8Array;
+  if (typeof data === 'string') {
+    const base64 = dataURLToBase64(data).slice(0, SIGNATURE_BASE64_LENGTH);
+    try {
+      // 判定に必要な先頭だけを復号する。4文字単位で切らないと末尾がパディング不正になる
+      bytes = toBytes(base64ToArrayBuffer(base64.slice(0, base64.length - base64.length % 4)));
+    } catch (error) {
+      // base64 として復号できない文字列は判定できない
+      return null;
+    }
+  } else {
+    bytes = toBytes(data);
+  }
+  return detectFileType(bytes);
+}
+
+/**
+ * ファイル名に使えない文字(\ / : * ? " < > |)を取り除く
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function sanitizeFileName(name: string): string {
+  return name.replace(/[\\/:*?"<>|]/g, '');
+}