본문으로 건너뛰기

Object 확장 사용법 ($object)

개요​

$object는 일반 객체를 다루기 위한 확장 함수를 제공합니다. 값의 타입 판별(isString, isNumber, isDate 등), 깊은 복사, 객체 병합, CSV/파라미터 문자열 변환, JSON 값 캐스팅 등 여러 모듈에서 공통으로 사용하는 유틸리티가 모여 있습니다.

로드 방법​

syn.js가 로드되면 전역에 $object로 즉시 사용할 수 있습니다. (syn. 접두사 없이 전역 변수로 노출됨에 유의)

빠른 시작​

$object.isString('hello');   // true
$object.clone({ a: 1 });     // { a: 1 } (새 객체)

주요 시나리오​

값의 타입 판별​

isNullOrUndefined, isDefined, isNull, isArray, isDate, isString, isNumber, isFunction, isObject, isObjectEmpty, isBoolean, isEmpty 등으로 값의 타입과 상태를 판별합니다.

$object.isEmpty([]);        // true
$object.isBoolean('Y');     // true ('TRUE'/'FALSE'/'T'/'F'/'Y'/'N'/'1'/'0' 문자열도 인식)

깊은 복사와 객체 병합​

clone(val, isNested)은 객체/배열/Date/HTMLElement를 복사하고, extend(to, from, overwrite)는 중첩 객체까지 재귀적으로 병합합니다.

const copy = $object.clone({ a: { b: 1 } });
$object.extend({ a: 1 }, { a: 2, b: 3 }); // { a: 2, b: 3 }

객체를 CSV/파라미터 문자열로 변환​

toCSV(obj, options)는 중첩 객체를 평탄화하여 CSV 문자열로, toParameterString(jsonObject)는 @key:value; 형태의 파라미터 문자열로 변환합니다.

$object.toCSV([{ a: 1, b: 2 }], { delimiter: ';' });
$object.toParameterString({ name: 'hong', age: 20 });

타입 기본값과 JSON 값 캐스팅​

defaultValue(type)로 타입별 기본값을 얻고, parseJsonValue(value, jsonType)로 문자열 값을 지정한 타입으로 캐스팅합니다.

$object.defaultValue('number');            // 0
$object.parseJsonValue('123', 'integer');  // 123

특정 키를 제외한 객체 만들기​

excludeKeys(sourceObject, keysToExclude)로 민감한 필드나 불필요한 속성을 제외한 새 객체를 만들 수 있습니다.

$object.excludeKeys({ a: 1, password: '*' }, ['password']);

실전 예제 페이지​

/sample/syn/extension_object.html 예제에서 다음 항목을 실습할 수 있습니다.

  • $object.version 속성 조회
  • isNullOrUndefined(), toCSV(), toParameterString(), getType(), defaultValue()
  • isDefined(), isNull(), isArray(), isDate(), isString(), isNumber(), isFunction(), isObject(), isObjectEmpty(), isBoolean()
  • isEmpty(), clone(), extend(), excludeKeys(), parseJsonValue()

주의 사항​

  • clone(val, isNested)은 isNested가 false이면 얕은 복사(1단계)만 수행합니다. 중첩 객체까지 완전히 분리하려면 기본값(true)을 그대로 사용하세요.
  • extend(to, from, overwrite)는 overwrite가 false이면 to에 이미 존재하는 키는 덮어쓰지 않습니다.
  • isBoolean()은 실제 boolean 타입 외에도 'TRUE'/'FALSE'/'T'/'F'/'Y'/'N'/'1'/'0' 문자열을 boolean으로 인식할 수 있는지 여부를 판별하는 함수이지 boolean 값 자체를 반환하는 변환 함수가 아닙니다.
  • toCSV()는 두 번째 인자로 배열이 아닌 { scopechar, delimiter, newline } 형태의 옵션 객체를 받습니다(과거 예제처럼 배열/구분자를 개별 인자로 넘기지 않도록 주의).

관련 모듈​

  • API 상세는 아래 API 참조 섹션을 확인하세요.

API 참조​

모듈 정보​

항목내용
전역 별칭$object (syn.$ 접두사 없음, 전역 변수)
소스 위치2.Modules/wwwroot/wwwroot/js/syn.js (약 4165~4385번째 줄)
예제 페이지/sample/syn/extension_object.html
의존 모듈$string(toValue, toDynamic, toBoolean)

메서드​

$object.isNullOrUndefined(val)​

  • 설명: 값이 undefined 또는 null인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isNullOrUndefined(null); // true

$object.toCSV(obj, options = {})​

  • 설명: 객체 또는 객체 배열을 중첩 속성까지 평탄화하여 CSV 문자열로 변환합니다.
  • 매개변수
    이름타입필수설명
    objobject | Array<object>Y변환할 객체 또는 객체 배열
    optionsobjectN{ scopechar = '/', delimiter = ',', newline = '\n' }
  • 반환값: string | null — obj가 객체가 아니면 null
  • 예시 
    const result = $object.toCSV([{ a: 1, b: 2 }, { a: 3, b: 4 }], { delimiter: ';' });

$object.toParameterString(jsonObject)​

  • 설명: JSON 객체를 @key:value; 형태의 파라미터 문자열로 변환합니다.
  • 매개변수
    이름타입필수설명
    jsonObjectobjectY변환할 객체
  • 반환값: string
  • 예시 
    const result = $object.toParameterString({ symbol: 'hello', price: 12345 });

$object.getType(val)​

  • 설명: 값의 타입을 문자열로 반환합니다('null', 'array', 'date', 'element', 'object'와 기본 typeof 결과를 포함).
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: string
  • 예시 
    const result = $object.getType(new Date()); // 'date'

$object.defaultValue(type)​

  • 설명: 지정한 타입 이름의 기본값을 반환합니다.
  • 매개변수
    이름타입필수설명
    typestringY'boolean', 'function', 'null', 'number'/'numeric'/'int', 'object', 'date'/'datetime', 'string', 'symbol', 'undefined', 'array' 중 하나
  • 반환값: any — 알 수 없는 타입은 빈 문자열('')
  • 예시 
    const result = $object.defaultValue('number'); // 0

$object.isDefined(val)​

  • 설명: 값이 undefined가 아닌지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isDefined(undefined); // false

$object.isNull(val)​

  • 설명: 값이 null인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isNull(null); // true

$object.isArray(val)​

  • 설명: 값이 배열인지 확인합니다(Array.isArray 래핑).
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isArray([]); // true

$object.isDate(val)​

  • 설명: 값이 유효한 Date 인스턴스인지 확인합니다(Invalid Date는 false).
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isDate(new Date()); // true

$object.isString(val)​

  • 설명: 값이 문자열 타입인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isString('hello'); // true

$object.isNumber(val)​

  • 설명: 값이 NaN이 아닌 숫자 타입인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isNumber(12345); // true

$object.isFunction(val)​

  • 설명: 값이 함수 타입인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isFunction(() => {}); // true

$object.isObject(val)​

  • 설명: 값이 null이 아닌 객체 타입인지 확인합니다(배열, Date 등도 포함).
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isObject({}); // true

$object.isObjectEmpty(val)​

  • 설명: 값이 순수 객체(plain object)이면서 속성이 하나도 없는지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isObjectEmpty({}); // true

$object.isBoolean(val)​

  • 설명: 값이 boolean 타입이거나, boolean으로 해석 가능한 문자열('TRUE', 'FALSE', 'T', 'F', 'Y', 'N', '1', '0', 대소문자 무관)인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isBoolean('Y'); // true

$object.isEmpty(val)​

  • 설명: 값이 undefined/null/NaN/공백 문자열/빈 배열/빈 순수 객체 중 하나인지 확인합니다.
  • 매개변수
    이름타입필수설명
    valanyY검사할 값
  • 반환값: boolean
  • 예시 
    const result = $object.isEmpty([]); // true

$object.clone(val, isNested = true)​

  • 설명: 객체, 배열, Date, HTMLElement를 복사합니다. isNested가 true이면 중첩 구조까지 재귀적으로 복사(깊은 복사)하고, false이면 최상위 속성만 복사(얕은 복사)합니다.
  • 매개변수
    이름타입필수설명
    valanyY복사할 값
    isNestedbooleanN재귀(깊은) 복사 여부(기본값 true)
  • 반환값: any — 객체가 아니면 원본 값을 그대로 반환
  • 예시 
    const result = $object.clone({ a: { b: 1 } });

$object.extend(to, from, overwrite = true)​

  • 설명: from 객체의 속성을 to 객체에 재귀적으로 병합합니다. 중첩 객체는 재귀적으로 병합되고, 배열/Date/HTMLElement는 병합 대상에서 제외되어 값 자체가 복제되어 대입됩니다.
  • 매개변수
    이름타입필수설명
    toobjectY병합 대상 객체
    fromobjectY병합할 원본 객체
    overwritebooleanN기존 키를 덮어쓸지 여부(기본값 true)
  • 반환값: object — 병합된 to 객체
  • 예시 
    const result = $object.extend({ a: 1 }, { a: 2, b: 3 }); // { a: 2, b: 3 }

$object.excludeKeys(sourceObject, keysToExclude)​

  • 설명: sourceObject에서 keysToExclude에 포함된 키를 제외한 나머지 속성만으로 새 객체를 만듭니다.
  • 매개변수
    이름타입필수설명
    sourceObjectobjectY원본 객체
    keysToExcludeArray<string>Y제외할 키 목록
  • 반환값: object
  • 예시 
    const result = $object.excludeKeys({ a: 1, b: 2, c: 3 }, ['b']); // { a: 1, c: 3 }

$object.parseJsonValue(value, jsonType)​

  • 설명: 문자열 등의 값을 지정한 JSON 타입으로 캐스팅합니다.
  • 매개변수
    이름타입필수설명
    valueanyY변환할 값
    jsonTypestringY'integer', 'number', 'boolean', 'object', 'array', 'string'(기본값)
  • 반환값: any — value가 null/undefined이면 그대로 반환
  • 예시 
    const result = $object.parseJsonValue('123', 'integer'); // 123