@digitalwalletcorp/utils 0.1.0 → 0.4.0

package/src/object-util.ts

@@ -0,0 +1,482 @@
+import * as JsonUtil from './json-util';
+
+/** コンストラクタの型 */
+export type Constructor<T> = new (...args: any[]) => T;
+
+/**
+ * マージのオプション
+ */
+export interface MergeOptions {
+  /**
+   * 配列のマージ方法。既定は 'replace'
+   *   ├ replace source側の配列の複製で置き換える
+   *   ├ concat original側の配列にsource側の要素の複製を連結する
+   *   └ indexMerge 添字ごとにマージする。source側より長い部分はoriginal側の要素が残る
+   */
+  arrays?: 'replace' | 'concat' | 'indexMerge';
+}
+
+interface MergeContext {
+  arrays: NonNullable<MergeOptions['arrays']>;
+  /** trueの場合、original側が自身のプロパティとして持つキーだけをマージの対象にする */
+  existingKeysOnly: boolean;
+  /** source側のオブジェクトと、それをマージした先のオブジェクトの対応。循環参照・共有参照を結果に保つために使う */
+  merged: WeakMap<object, any>;
+}
+
+const ARRAY_INDEX_KEY = /^(.+)\[(\d+)\]$/;
+
+const isPlainObject = (value: unknown): value is Record<PropertyKey, any> => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const functionToString = (fn: (...args: any[]) => any): string => fn.name ? `[Function: ${fn.name}]` : '[Function (anonymous)]';
+
+/**
+ * 指定したクラスのインスタンスを生成する
+ *
+ * @param {Constructor<T>} creator クラス
+ * @param {any[]} args コンストラクタの引数
+ * @returns {T}
+ */
+export function create<T>(creator: Constructor<T>, ...args: any[]): T {
+  return new creator(...args);
+}
+
+/**
+ * オブジェクトに階層構造で値を設定する
+ * 引数の最後の要素が値、それ以外がキーの階層である。キーが1つもない場合は何もしない
+ * 途中の階層が存在しない、またはオブジェクトでない場合は、新しいオブジェクトで置き換えて先へ進む
+ * 設定先がすでに配列の場合は、値を置き換えずに配列へ追加する。値が配列の場合はその要素を追加する
+ *
+ * @example
+ *   const obj = {};
+ *   appendObjectHierarchy(obj, 'a', 'b', 'c', 100);   // { a: { b: { c: 100 } } }
+ *   appendObjectHierarchy(obj, 'a', 'b', 'd', [1]);   // { a: { b: { c: 100, d: [1] } } }
+ *   appendObjectHierarchy(obj, 'a', 'b', 'd', [2]);   // { a: { b: { c: 100, d: [1, 2] } } }
+ *
+ * @param {object} obj
+ * @param {any[]} args キーの階層と、最後に設定する値
+ */
+export function appendObjectHierarchy(obj: Record<PropertyKey, any>, ...args: any[]): void {
+  if (args.length < 2) {
+    return;
+  }
+  const [key, ...rest] = args;
+  if (rest.length === 1) {
+    const value = rest[0];
+    if (Array.isArray(obj[key])) {
+      obj[key].push(...Array.isArray(value) ? value : [value]);
+    } else {
+      obj[key] = value;
+    }
+    return;
+  }
+  if (typeof obj[key] !== 'object' || obj[key] === null) {
+    obj[key] = {};
+  }
+  appendObjectHierarchy(obj[key], ...rest);
+}
+
+/**
+ * オブジェクトの階層キーをドット(.)で繋いで指定して値を取得する
+ * 配列の要素は [n] で指定する
+ * 該当するキーがない場合、または途中の値が null / undefined の場合は undefined を返す
+ *
+ * @example
+ *   getValue({ a: { b: [1, 2, 3] } }, 'a.b[1]');   // 2
+ *
+ * @param {any} obj
+ * @param {string} key
+ * @returns {T | undefined}
+ */
+export function getValue<T = any>(obj: any, key: string): T | undefined {
+  let current = obj;
+  for (const segment of key.split('.')) {
+    if (current == null) {
+      return undefined;
+    }
+    const matcher = ARRAY_INDEX_KEY.exec(segment);
+    if (matcher && Array.isArray(current[matcher[1]])) {
+      current = current[matcher[1]][Number(matcher[2])];
+    } else {
+      current = current[segment];
+    }
+  }
+  return current;
+}
+
+const cloneDeep = (value: any, seen: WeakMap<object, any>): any => {
+  if (typeof value !== 'object' || value === null) {
+    // プリミティブと関数はそのまま返す
+    return value;
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  if (value instanceof WeakMap || value instanceof WeakSet || value instanceof Promise || value instanceof Error) {
+    // 中身を列挙できない、または複製する意味のないオブジェクトは参照のまま返す
+    return value;
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  if (value instanceof RegExp) {
+    const clone = new RegExp(value.source, value.flags);
+    clone.lastIndex = value.lastIndex;
+    return clone;
+  }
+  if (value instanceof ArrayBuffer) {
+    return value.slice(0);
+  }
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof DataView) {
+      return new DataView(value.buffer.slice(0), value.byteOffset, value.byteLength);
+    }
+    return new (value.constructor as new (source: ArrayBufferView) => ArrayBufferView)(value);
+  }
+  if (typeof globalThis.Node !== 'undefined' && value instanceof globalThis.Node) {
+    const clone = value.cloneNode(true);
+    seen.set(value, clone);
+    return clone;
+  }
+  if (value instanceof Map) {
+    const clone = new Map();
+    seen.set(value, clone);
+    for (const [k, v] of value) {
+      clone.set(cloneDeep(k, seen), cloneDeep(v, seen));
+    }
+    return clone;
+  }
+  if (value instanceof Set) {
+    const clone = new Set();
+    seen.set(value, clone);
+    for (const v of value) {
+      clone.add(cloneDeep(v, seen));
+    }
+    return clone;
+  }
+  if (Array.isArray(value)) {
+    const clone: any[] = [];
+    seen.set(value, clone);
+    for (let i = 0; i < value.length; i++) {
+      clone[i] = cloneDeep(value[i], seen);
+    }
+    return clone;
+  }
+  // プレーンオブジェクトとクラスのインスタンス。プロトタイプを引き継ぎ、列挙可能な自身のプロパティを複製する
+  const clone = Object.create(Object.getPrototypeOf(value));
+  seen.set(value, clone);
+  for (const key of Reflect.ownKeys(value)) {
+    if (Object.prototype.propertyIsEnumerable.call(value, key)) {
+      clone[key] = cloneDeep(value[key], seen);
+    }
+  }
+  return clone;
+};
+
+/**
+ * 値を深く複製する
+ * ・プリミティブと関数はそのまま返す
+ * ・Date / RegExp / Map / Set / 配列 / ArrayBuffer / 型付き配列は複製する
+ * ・プレーンオブジェクトとクラスのインスタンスは、プロトタイプを引き継いで列挙可能な自身のプロパティを複製する
+ * ・DOMのNodeは cloneNode(true) で複製する
+ * ・WeakMap / WeakSet / Promise / Error は参照のまま返す
+ * ・循環参照と、同じオブジェクトを複数箇所から参照している構造は、複製後も保たれる
+ *
+ * @param {T} value
+ * @returns {T}
+ */
+export function cloneObject<T>(value: T): T {
+  return cloneDeep(value, new WeakMap());
+}
+
+const mergeValue = (target: any, source: any, context: MergeContext): any => {
+  if (typeof source !== 'object' || source === null) {
+    // プリミティブ・関数・nullはsource側の値で置き換える
+    return source;
+  }
+  if (context.merged.has(source)) {
+    return context.merged.get(source);
+  }
+  if (isPlainObject(source) && isPlainObject(target)) {
+    mergeInto(target, source, context);
+    return target;
+  }
+  if (Array.isArray(source) && Array.isArray(target) && context.arrays !== 'replace') {
+    context.merged.set(source, target);
+    if (context.arrays === 'concat') {
+      for (const item of source) {
+        target.push(cloneObject(item));
+      }
+    } else {
+      for (let i = 0; i < source.length; i++) {
+        if (source[i] !== undefined) {
+          target[i] = mergeValue(target[i], source[i], context);
+        }
+      }
+    }
+    return target;
+  }
+  const clone = cloneObject(source);
+  context.merged.set(source, clone);
+  return clone;
+};
+
+const mergeInto = (target: Record<PropertyKey, any>, source: Record<PropertyKey, any>, context: MergeContext): void => {
+  context.merged.set(source, target);
+  for (const key of Object.keys(source)) {
+    if (source[key] === undefined) {
+      // undefinedは「指定なし」とみなしてoriginal側の値を残す
+      continue;
+    }
+    if (context.existingKeysOnly && !Object.hasOwn(target, key)) {
+      continue;
+    }
+    target[key] = mergeValue(target[key], source[key], context);
+  }
+};
+
+const mergeWithContext = <T extends object>(original: T, source: object | null | undefined, options: MergeOptions | undefined, existingKeysOnly: boolean): T => {
+  if (!isPlainObject(source)) {
+    return original;
+  }
+  mergeInto(original, source, {
+    arrays: options?.arrays ?? 'replace',
+    existingKeysOnly: existingKeysOnly,
+    merged: new WeakMap()
+  });
+  return original;
+};
+
+/**
+ * originalにsourceのプロパティを深くマージする(破壊)
+ * ・original側とsource側が両方プレーンオブジェクトの場合は再帰的にマージする
+ * ・source側が undefined のプロパティは「指定なし」とみなし、original側の値を残す
+ * ・それ以外はsource側の値の深い複製で置き換える。null は null を設定する
+ * ・配列は既定でsource側の複製で置き換える。options.arrays で連結・添字ごとのマージに変更できる
+ * ・source側の循環参照と、同じオブジェクトを複数箇所から参照している構造は、結果にも保たれる
+ * ・sourceが null / undefined / プレーンオブジェクト以外の場合は何もしない
+ *
+ * @param {T} original マージ先。この引数が書き換えられる
+ * @param {object | null | undefined} source マージするプロパティを持つオブジェクト
+ * @param {MergeOptions} [options]
+ * @returns {T} original
+ */
+export function merge<T extends object>(original: T, source: object | null | undefined, options?: MergeOptions): T {
+  return mergeWithContext(original, source, options, false);
+}
+
+/**
+ * originalの複製にsourceのプロパティを深くマージした新しいオブジェクトを返す(非破壊)
+ * マージの規則は merge と同じ
+ *
+ * @param {T} original マージ元。この引数は書き換えない
+ * @param {object | null | undefined} source マージするプロパティを持つオブジェクト
+ * @param {MergeOptions} [options]
+ * @returns {T} マージした新しいオブジェクト
+ */
+export function cloneMerge<T extends object>(original: T, source: object | null | undefined, options?: MergeOptions): T {
+  return mergeWithContext(cloneObject(original), source, options, false);
+}
+
+/**
+ * originalが自身のプロパティとして持つキーに限定して、sourceのプロパティを深くマージする(破壊)
+ * 値が undefined でもキーがあれば対象になる。入れ子のプレーンオブジェクトにも同じ限定を適用する
+ * original側が null やプリミティブで形を持たない場合は、source側の複製を設定する
+ * そのほかの規則は merge と同じ
+ *
+ * @param {T} original マージ先。この引数が書き換えられる
+ * @param {object | null | undefined} source マージするプロパティを持つオブジェクト
+ * @param {MergeOptions} [options]
+ * @returns {T} original
+ */
+export function transfer<T extends object>(original: T, source: object | null | undefined, options?: MergeOptions): T {
+  return mergeWithContext(original, source, options, true);
+}
+
+/**
+ * originalの複製に対して、originalが持つキーに限定してsourceのプロパティを深くマージした新しいオブジェクトを返す(非破壊)
+ * マージの規則は transfer と同じ
+ *
+ * @param {T} original マージ元。この引数は書き換えない
+ * @param {object | null | undefined} source マージするプロパティを持つオブジェクト
+ * @param {MergeOptions} [options]
+ * @returns {T} マージした新しいオブジェクト
+ */
+export function cloneTransfer<T extends object>(original: T, source: object | null | undefined, options?: MergeOptions): T {
+  return mergeWithContext(cloneObject(original), source, options, true);
+}
+
+const decodeBinary = (value: ArrayBuffer | ArrayBufferView): string => new TextDecoder().decode(value as any);
+
+const mapToObject = (map: Map<any, any>): Record<string, any> => {
+  const obj: Record<string, any> = {};
+  for (const [key, value] of map) {
+    // キーはプロパティ名になるため、オブジェクトのキーは改行を入れずに1行のJSONにする
+    obj[typeof key === 'object' && key !== null ? JsonUtil.stringify(key, toStringReplacer, undefined, { circular: 'replace' }) : toString(key)] = value;
+  }
+  return obj;
+};
+
+/**
+ * JSON化できない値を人が読める形に変換するreplacer。入れ子の値にも適用される
+ */
+function toStringReplacer(this: any, _key: string, value: any): any {
+  if (typeof value === 'function') {
+    return functionToString(value);
+  }
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  if (value instanceof Error) {
+    return String(value);
+  }
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+    return decodeBinary(value);
+  }
+  if (value instanceof Map) {
+    return mapToObject(value);
+  }
+  if (value instanceof Set) {
+    return Array.from(value);
+  }
+  return value;
+}
+
+/**
+ * 値を人が読める文字列にする。値の中身は変えない
+ * ・null / undefined は 'null' / 'undefined'
+ * ・文字列はそのまま
+ * ・number / boolean / bigint / symbol は String(value)
+ * ・関数は '[Function: name]'
+ * ・Error は 'name: message'。スタックは含めない
+ * ・ArrayBuffer / 型付き配列はUTF-8の文字列として復号する
+ * ・toJSON を持つオブジェクト(Dateなど)は toJSON() の結果を変換する
+ * ・Map は { key: value } のオブジェクト、Set は要素の配列としてJSON化する。Mapのキーもこの規則で文字列にする
+ * ・それ以外のオブジェクトと配列はインデント2のJSON。循環参照は '[Circular]' になる
+ * Error / 関数 / Map / Set / bigint の変換は、オブジェクトの中に入っている値にも適用する
+ *
+ * @param {any} value
+ * @returns {string}
+ */
+export function toString(value: any): string {
+  if (value == null) {
+    return String(value);
+  }
+  switch (typeof value) {
+    case 'string':
+      return value;
+    case 'number':
+    case 'boolean':
+    case 'bigint':
+    case 'symbol':
+      return String(value);
+    case 'function':
+      return functionToString(value);
+    default:
+  }
+  if (value instanceof Error) {
+    return String(value);
+  }
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+    return decodeBinary(value);
+  }
+  if (typeof value.toJSON === 'function') {
+    return toString(value.toJSON());
+  }
+  if (value instanceof Map) {
+    return toString(mapToObject(value));
+  }
+  if (value instanceof Set) {
+    return toString(Array.from(value));
+  }
+  return JsonUtil.stringify(value, toStringReplacer, 2, { circular: 'replace' });
+}
+
+/**
+ * 値の同一性を比較するための文字列を作るreplacer
+ * toStringReplacer と同じ変換を行ったうえで、プレーンオブジェクトはプロパティを名前順に並べ替える
+ */
+function stableReplacer(this: any, key: string, value: any): any {
+  const converted = toStringReplacer.call(this, key, value);
+  if (!isPlainObject(converted)) {
+    return converted;
+  }
+  const sorted: Record<string, any> = {};
+  for (const name of Object.keys(converted).sort()) {
+    sorted[name] = converted[name];
+  }
+  return sorted;
+}
+
+/**
+ * 値の同一性を比較するための文字列にする
+ * オブジェクトは改行なしのJSONで、プレーンオブジェクトのプロパティは名前順になる。配列の順序は区別する
+ */
+const toStableString = (value: any): string => {
+  return typeof value === 'object' && value !== null ? JsonUtil.stringify(value, stableReplacer, undefined, { circular: 'replace' }) : String(value);
+};
+
+const FNV_OFFSET_BASIS = 2166136261;
+const FNV_PRIME = 16777619;
+
+/**
+ * 値のハッシュ値を返す
+ * 値を toStableString で文字列にし、そのUTF-8のバイト列をFNV-1a(32bit)でハッシュ化する
+ * distinct で同じとみなされる値は同じハッシュ値になる
+ *
+ * @param {any} value
+ * @returns {number} 0 〜 4294967295 の整数
+ */
+export function hashCode(value: any): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (const byte of new TextEncoder().encode(toStableString(value))) {
+    hash = Math.imul(hash ^ byte, FNV_PRIME);
+  }
+  return hash >>> 0;
+}
+
+/**
+ * 配列から重複する要素を除いた新しい配列を返す
+ * ・null / undefined の要素は除く
+ * ・オブジェクトはJSON化した文字列で比較する。プロパティの順序は区別せず、配列の順序は区別する(hashCode と同じ文字列表現)
+ * ・プリミティブは型も区別する。'1' と 1 は別の要素として残る
+ *
+ * @example
+ *   distinct([1, 3, 3, 2, 1]);                                             // [1, 3, 2]
+ *   distinct([{ id: 1, name: 'a' }, { id: 1, name: 'b' }], { distinct: a => a.id });   // [{ id: 1, name: 'a' }]
+ *
+ * @param {T[]} array
+ * @param {*} [options]
+ *   ├ distinct 重複判定に使う値を返す関数。戻り値が null / undefined の要素は除く
+ *   └ exclude trueを返した要素は除く
+ * @returns {T[]}
+ */
+export function distinct<T>(array: T[], options?: {
+  distinct?: (a: T) => any;
+  exclude?: (a: T) => boolean;
+}): T[] {
+  const result: T[] = [];
+  const keys = new Set<string>();
+  for (const value of array) {
+    if (value == null || options?.exclude?.(value)) {
+      continue;
+    }
+    const target = options?.distinct ? options.distinct(value) : value;
+    if (target == null) {
+      continue;
+    }
+    // 文字列表現が同じになる '1' と 1 を区別するため、プリミティブは型を付けてキーにする
+    const key = typeof target === 'object' ? toStableString(target) : `${typeof target}:${String(target)}`;
+    if (!keys.has(key)) {
+      keys.add(key);
+      result.push(value);
+    }
+  }
+  return result;
+}

package/src/string-util.ts

@@ -0,0 +1,115 @@
+/**
+ * URLのクエリに指定できる値
+ */
+export type QueryValue = string | number | boolean | undefined;
+
+/**
+ * URLのクエリをキーと値の組で表したもの
+ */
+export type QueryObject = Record<string, QueryValue | QueryValue[]>;
+
+/**
+ * 文字列の前後の空白を取り除く
+ * null, undefined, 空文字の場合はそのまま元の値を返す
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function trim(str: string): string {
+  if (!str) {
+    return str;
+  }
+  return str.trim();
+}
+
+/**
+ * 文字列の先頭が英小文字の場合、先頭文字を大文字にする
+ * null, undefined, 空文字の場合はそのまま元の値を返す
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function capitalize(str: string): string {
+  if (!str) {
+    return str;
+  }
+  return str.replace(/^[a-z]/, c => c.toUpperCase());
+}
+
+/**
+ * 文字列内の {0} {1} の部分を、配列の添字に該当するパラメータで置換する
+ *
+ * @param {string} str 元の文字列
+ * @param {(string | number | boolean | symbol)[]} [replacements] 置換パラメータ
+ * @returns {string}
+ */
+export function messageFormat(str: string, replacements?: (string | number | boolean | symbol)[]): string {
+  if (!str || !replacements || !replacements.length) {
+    return str;
+  }
+  let buf = str;
+  for (let i = 0; i < replacements.length; i++) {
+    const replacement = replacements[i];
+    const value = typeof replacement === 'symbol'
+      ? String(replacement.description)
+      : String(replacement);
+    buf = buf.replace(new RegExp(`\\{${i}\\}`, 'g'), value);
+  }
+  return buf;
+}
+
+/**
+ * base, segments, queryを連結してURLを生成する
+ *
+ * @param {*} options
+ *   ├ base {string} https://example.com のようなプロトコル付きURL
+ *   ├ segments {(string | number)[]} セグメント
+ *       baseが未指定で配列の先頭要素がスラッシュで始まる場合、生成されるパスはスラッシュで始まる絶対パスを示す
+ *       baseが未指定で配列の先頭要素がスラッシュで始まらない場合、生成されるパスはスラッシュで始まらない相対パスを示す
+ *       baseが指定されている場合は、先頭要素のスラッシュの有無に関わらずbaseに続くURLとして生成する。URLクラスの挙動とは異なる
+ *   ├ query {string | QueryObject}
+ *       文字列: ?date=2022-11-02&param=abc のようなクエリ。先頭に?がない場合は補完する。エンコードはしない
+ *       キーと値の組: { date: '2022-11-02', param: 'abc' }。値が配列の場合は同じキーで複数指定する
+ * @returns {string}
+ */
+export function buildUrl(options: {
+  base?: string;
+  segments?: (string | number)[];
+  query?: string | QueryObject;
+}): string {
+  const base = options.base?.replace(/\/+$/, '') ?? '';
+  const segments = options.segments?.map((seg, idx) => {
+    let normalizedSegment = String(seg);
+    if (!options.base && idx === 0) {
+      // 絶対パスか相対パスかを表すため、baseがない場合の先頭要素だけはスラッシュを1つ残す
+      normalizedSegment = normalizedSegment.replace(/^\/+/g, '/');
+    } else {
+      normalizedSegment = normalizedSegment.replace(/^\/+/g, '');
+    }
+    return normalizedSegment.replace(/\/+$/g, '');
+  }) ?? [];
+  const path = [base, ...segments].filter(Boolean).join('/');
+
+  let qs = '';
+  if (options.query) {
+    if (typeof options.query === 'string') {
+      qs = options.query.startsWith('?') ? options.query : `?${options.query}`;
+    } else {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.query)) {
+        if (Array.isArray(value)) {
+          for (const v of value) {
+            params.append(key, String(v));
+          }
+        } else if (value != null) {
+          params.append(key, String(value));
+        }
+      }
+      const strParams = params.toString();
+      if (strParams) {
+        qs = `?${strParams}`;
+      }
+    }
+  }
+  return `${path}${qs}`;
+}