@cp949/js-util

@cp949/js-util

유지보수 중단

이 라이브러리는 더 이상 버그 수정이나 기능 추가를 하지 않습니다. 보안 취약점 관련 업데이트만 유지합니다. 새로 시작하는 프로젝트에서는 lodash-es나 es-toolkit을 사용하세요.

브라우저에서 사용하는 TypeScript 유틸리티 모음입니다. 19개 서브모듈을 개별 진입점으로 제공하며, 각 모듈은 독립적으로 import 합니다.

설치

npm install @cp949/js-util

pnpm add @cp949/js-util

yarn add @cp949/js-util

지원 환경

이 라이브러리는 브라우저 전용입니다. btoa, TextEncoder, document 같은 브라우저 API를 사용하므로 Node.js 런타임에서는 동작을 보장하지 않습니다.

항목	값
브라우저	Chrome 75+, Edge 79+, Firefox 68+, Safari 14.1+
모듈 형식	ESM, CJS
타입 선언	포함 (.d.ts, .d.cts)
소스맵	포함

빌드 타겟은 ['chrome75', 'safari14.1', 'firefox68', 'edge79']입니다. ?., ?? 같은 문법은 빌드 시점에 다운레벨되며, 런타임 폴리필은 포함하지 않습니다.

import

루트 진입점 @cp949/js-util은 export를 제공하지 않습니다. 서브패스로 import 하세요.

import { chunks, groupBy } from '@cp949/js-util/array';
import { camelCase, isBlank } from '@cp949/js-util/string';
import { clamp } from '@cp949/js-util/math';

서브패스별로 진입점이 분리되어 있어, import 하지 않은 모듈은 번들에 포함되지 않습니다.

모듈

서브패스	export	대표 함수
@cp949/js-util/array	50	append/$append, chunks, groupBy, uniqBy, zipWith
@cp949/js-util/string	57	camelCase, isBlank, truncMiddle, formatByteCount, chosung
@cp949/js-util/math	39	clamp, degToRad, cycle, atLeast, atMost
@cp949/js-util/easing	31	backIn, bounceOut, circInOut 등 이징 함수
@cp949/js-util/misc	30	deepEq, shallowEq, sleepAsync, isNullish, pathUtil
@cp949/js-util/random	27	randomInt, randomBoolean, randomUint8Array, suid
@cp949/js-util/color	17	hex2rgb, rgb2hsl, blend, darken
@cp949/js-util/uint8-array	17	stringToBase64, base64ToString, uint8ArrayToHex, concatUint8Arrays
@cp949/js-util/dataurl	11	extractMimeType, getDataURLSize, convertBlobToDataURL
@cp949/js-util/base64	6	encode, decode, uint8ArrayToBase64, base64ToUint8Array
@cp949/js-util/date	6	formatByEpochMillis, formatByEpochSeconds, formatter, parser
@cp949/js-util/http	5	joinUrl, objectToQueryString, queryParams
@cp949/js-util/usermedia	5	hasGetUserMedia, closeUserMedia, fixUserMedia
@cp949/js-util/dom	4	qs, qsa, createElement, addGlobalEventListener
@cp949/js-util/browser	3	isTouchDevice, isWebSerialSupport, isWebBluetoothSupport
@cp949/js-util/web	3	downloadBlob, downloadLink, downloadText
@cp949/js-util/file	2	fileExtension, fileNamePart
@cp949/js-util/eventemitter	1	EventEmitter
@cp949/js-util/fn	1	debounce

사용 예시

아래 출력값은 실제 실행 결과입니다.

배열

import { append, $append, chunks, groupBy, uniqBy } from '@cp949/js-util/array';

chunks([1, 2, 3, 4, 5], 2);
// [[1, 2], [3, 4], [5]]

uniqBy([{ id: 1 }, { id: 1 }, { id: 2 }], 'id');
// [{ id: 1 }, { id: 2 }]

groupBy([{ t: 'a', v: 1 }, { t: 'b', v: 2 }, { t: 'a', v: 3 }], 't');
// { a: [{ t: 'a', v: 1 }, { t: 'a', v: 3 }], b: [{ t: 'b', v: 2 }] }

문자열

import { camelCase, isBlank, truncMiddle, formatByteCount } from '@cp949/js-util/string';

camelCase('hello', 'world');            // 'helloWorld'
isBlank('   ');                         // true
truncMiddle('abcdefghijklmnop', { length: 9 }); // 'abc...nop'
formatByteCount(1536);                  // '1.5 KB'

camelCase는 전달한 조각들을 이어 붙입니다. 하나의 문자열 안에 있는 _나 -를 변환하지는 않습니다.

base64와 Uint8Array

import { stringToBase64, base64ToString, uint8ArrayToHex, stringToUint8Array }
  from '@cp949/js-util/uint8-array';

stringToBase64('안녕 js-util');        // '7JWI64WVIGpzLXV0aWw='
base64ToString('7JWI64WVIGpzLXV0aWw='); // '안녕 js-util'
uint8ArrayToHex(stringToUint8Array('js')); // '6a73'

문자열만 다룰 때는 base64 모듈이 더 짧습니다.

import { encode, decode } from '@cp949/js-util/base64';

encode('안녕 js-util');          // '7JWI64WVIGpzLXV0aWw='
decode('7JWI64WVIGpzLXV0aWw='); // '안녕 js-util'

두 모듈 모두 TextEncoder/TextDecoder를 거치므로 비ASCII 문자열도 그대로 왕복합니다. base64는 문자열을, uint8-array는 바이트 배열을 중심으로 다룹니다.

URL과 숫자

import { joinUrl, objectToQueryString } from '@cp949/js-util/http';
import { clamp } from '@cp949/js-util/math';
import { fileExtension } from '@cp949/js-util/file';

joinUrl('https://api.test', '/v1/', 'users'); // 'https://api.test/v1/users'
objectToQueryString({ page: 2 });             // '?page=2'
clamp(15, 0, 10);                             // 10
fileExtension('report.final.PDF');            // 'PDF'
fileExtension('report.PDF', true, true);      // '.pdf'

objectToQueryString은 값을 URL 인코딩하지 않습니다. 인코딩이 필요한 값은 호출 전에 encodeURIComponent로 처리하세요. falsy 값(0, false, '', null, undefined)을 가진 항목은 결과에서 빠집니다.

mutable과 immutable

array 모듈은 같은 동작을 두 가지 형태로 제공합니다. $ 접두사가 붙은 함수는 원본을 두고 새 배열을 반환합니다.

import { append, $append } from '@cp949/js-util/array';

const a = [1, 2, 3];
append(a, [4, 5]);   // a 자체가 [1, 2, 3, 4, 5]로 바뀐다

const b = [1, 2, 3];
const c = $append(b, [4, 5]);
// b === [1, 2, 3]  (유지)
// c === [1, 2, 3, 4, 5]

$ 쌍이 있는 함수: append, prepend, insertAt, remove, removeAt, replace, replaceAt, move, swap, swapValue, shuffle, truncate, uniq, uniqBy, shiftRotateLeft, shiftRotateRight.

date 모듈과 dayjs

date 모듈은 dayjs를 optional peer dependency로 사용합니다. 이 모듈을 쓸 때만 설치하세요.

npm install dayjs

import { formatByEpochMillis } from '@cp949/js-util/date';

formatByEpochMillis(0, 'YYYY-MM-DD');
// ['1970-01-01', Date(1970-01-01T00:00:00.000Z)]

포맷 결과와 Date 객체를 튜플로 반환합니다. 입력이 유효하지 않으면 실행 시점에 [null, null]을 반환합니다. 타입 선언은 [string | undefined, Date | undefined]로 되어 있어 런타임 값과 다릅니다.

TypeScript

각 서브패스는 ESM(.d.ts)과 CJS(.d.cts) 타입 선언을 따로 제공합니다. tsconfig.json의 moduleResolution이 node16, nodenext, bundler 중 하나여야 서브패스 타입이 해석됩니다.

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

링크

• 저장소: https://github.com/cp949/js-util
• 이슈: https://github.com/cp949/js-util/issues
• npm: https://www.npmjs.com/package/@cp949/js-util

라이선스

MIT