공통 라이브러리 사용법 (syn.$l)
개요
syn.$l(별칭: syn.$library)은 HandStack 클라이언트 스크립트(syn.js) 전반에서 사용하는 공통 유틸리티 모듈입니다. GUID/난수 생성, DOM 엘리먼트 조회 및 이벤트 바인딩, CSV·TSD·트리 형태의 데이터 변환, Blob/DataURI/Base64/File 상호 변환, 그리고 syn.js 내부 로깅(eventLog)까지 폭넓은 범용 기능을 제공합니다.
이 모듈은 브라우저와 Node.js 두 실행 환경을 모두 지원합니다. 다만 addEvent, get, querySelector 등 DOM 관련 메서드는 Node.js 환경에서 제거되며, 반대로 getBasePath, moduleEventLog는 Node.js 전용 메서드로 브라우저 환경에서는 제공되지 않습니다.
로드 방법
syn.$l은 syn.js가 로드되는 즉시 전역에 등록됩니다. 별도의 초기화 없이 페이지에 syn.js(또는 이를 번들링한 syn.loader.js)만 포함하면 바로 사용할 수 있습니다.
<script src="/js/syn.loader.js"></script>
<script>
syn.$l.eventLog('page', 'syn.$l 로드 완료', 'Information');
</script>
동적 모듈 페이지(예: 이 저장소의 sample/syn/*.html)에서는 $library 전역 객체를 통해 hook/event/method를 선언하고 syn.loader.js가 이를 자동으로 syn.$l과 연결/실행합니다.
빠른 시작
// 1) 고유 식별자 생성
var id = syn.$l.guid();
// 2) DOM 조회 + 이벤트 바인딩
syn.$l.addEvent('btn_save', 'click', (evt) => {
var el = syn.$l.get('txt_name');
syn.$l.eventLog('btn_save.click', `저장 값: ${el.value}`, 'Information');
});
// 3) CSV 문자열 <-> JSON 변환
var json = syn.$l.text2Json('AAA,BBB\n1,2');
var csv = syn.$l.json2Text(json, ['AAA', 'BBB']);
주요 시나리오
1. GUID 생성
var id = syn.$l.guid();
// crypto.randomUUID -> crypto.getRandomValues -> Math.random 순서로 폴백하며
// 항상 RFC 4122 형식(8-4-4-4-12)의 문자열을 반환합니다.
2. DOM 이벤트 바인딩 (addEvent / addLive / trigger)
// 특정 노드에 이벤트 등록 (체이닝 지원)
syn.$l
.addEvent('txt_addEvent', 'click', (evt) => { /* ... */ })
.addEvent('txt_addEvent', 'blur', (evt) => { /* ... */ });
// 여러 노드에 동일 이벤트 등록
syn.$l.addEvents('input[type="text"]', 'click', (evt) => { /* ... */ });
// 동적으로 추가되는 노드까지 반응하는 위임(delegation) 이벤트
syn.$l.addLive('.dynamic-row', 'click', (evt) => { /* ... */ });
// 등록된 핸들러 존재 여부 확인 및 강제 실행
if (syn.$l.hasEvent('txt_addEvent', 'change')) {
syn.$l.trigger('txt_addEvent', 'change');
}
// 브라우저 CustomEvent 디스패치
syn.$l.triggerEvent('txt_addEvent', 'change');
// 이벤트 해제
syn.$l.removeEvent('txt_addEvent', 'change', handler);
내부적으로 addEvent/removeEvent는 등록된 (엘리먼트, 타입, 핸들러) 조합을 자체 레지스트리에서 관리하므로, 중복 등록을 막고 pagehide 시점에 일괄 해제(flush)할 수 있습니다. (모바일 브라우저의 BFCache 대응을 위해 unload 대신 pagehide를 사용합니다.)
3. CSV ↔ JSON 변환
var json = syn.$l.text2Json('AAA,BBB,CCC\n111,222,333', ',', '\n');
// [{ AAA: '111', BBB: '222', CCC: '333' }]
var csv = syn.$l.json2Text(json, ['AAA', 'BBB', 'CCC'], ',', '\n');
// 'AAA,BBB,CCC\n111,222,333'
값에 구분자/줄바꿈/큰따옴표가 포함되면 json2Text가 자동으로 큰따옴표로 감싸고 이스케이프 처리합니다.
4. 트리 데이터 변환 (flat2Nested / nested2Flat)
// 평면(Flat) 배열 -> 트리(Nested) 구조
var tree = syn.$l.flat2Nested(flatArray, 'id', 'parentId', 'items');
// 트리(Nested) 구조 -> 평면(Flat) 배열
var flat = syn.$l.nested2Flat(tree, 'id', 'parentId', 'items');
// 트리에서 ID로 노드 검색
var node = syn.$l.findNestedByID(tree, 10, 'id', 'items');
조직도, 트리 메뉴, 폴더 구조와 같이 부모-자식 관계를 가지는 데이터를 다룰 때 사용합니다. flat2Nested는 parentId가 null인 항목을 루트로 인식합니다.
5. Blob / DataURI 변환
var blob = syn.$l.createBlob('hello world', 'text/plain');
syn.$l.blobToDataUri(blob, (dataUri) => {
console.log(dataUri); // data:text/plain;base64,...
});
var restoredBlob = syn.$l.dataUriToBlob('data:text/plain;base64,aGVsbG8=');
syn.$l.blobToDownload(blob, 'hello.txt'); // 브라우저에서 파일 다운로드
var base64 = await syn.$l.blobToBase64(blob, true); // base64Only = true
var blobAgain = syn.$l.base64ToBlob(base64, 'text/plain');
File ↔ Base64/Blob 상호 변환(fileToBase64, fileToBlob, blobToFile), 원격 URL 다운로드(urlToBase64, blobUrlToBlob, blobUrlToDataUri), 이미지 리사이즈(resizeImage)도 함께 제공됩니다.
6. eventLog를 이용한 로깅
syn.$l.eventLog('moduleName.methodName', '처리 완료', 'Information');
syn.$l.eventLog('moduleName.methodName', error, 'Error');
eventLog(event, data, logLevel, logStyle)는 syn.js 내부 전반(약 각 모듈의 catch 블록)에서 오류/경고를 표준화된 형식으로 기록하는 중앙 로거입니다. 로그 레벨은 syn.$l.logLevel(Verbose=0 ~ Fatal=5) 열거자를 사용하며, syn.Config.UIEventLogLevel보다 낮은 레벨은 출력되지 않습니다. 브라우저에서는 console에 출력하고(레벨에 따라 log/info/warn/error 자동 매핑), id="eventlogs" 엘리먼트가 있으면 화면에도 로그를 append합니다. Node.js 환경에서는 globalRoot.$logger로 위임되고, moduleEventLog(moduleID, event, data, logLevel)을 통해 모듈별 로거로 기록할 수 있습니다(Node.js 전용).
실전 예제 페이지
2.Modules/wwwroot/wwwroot/sample/syn/library.html, library.js 파일에 위 시나리오를 포함한 40여 개 메서드의 인터랙티브 데모가 구현되어 있습니다. 브라우저에서 해당 페이지를 열어 각 버튼을 클릭하며 실제 동작을 확인할 수 있습니다.
주의 사항
getValue(elID, defaultValue)는 웹폼 런타임의synControls컨텍스트가 존재할 때만 컨트롤 모듈을 통해 값을 조회합니다.synControls가 없는 일반 페이지(이 샘플 포함)에서는 DOM 값을 조회하지 않고 항상defaultValue를 반환하므로, 값이 기대와 다르면 우선 웹폼 컨텍스트 여부를 확인하십시오.getBasePath(),moduleEventLog()는 Node.js 런타임 전용 메서드입니다. 이 두 메서드는 브라우저 환경에서는 로드 시점에$library객체에서 삭제되어 존재하지 않으므로 클라이언트 스크립트에서 호출하면 오류가 발생합니다.- 반대로
addEvent,addEvents,addLive,removeEvent,hasEvent,trigger,triggerEvent,getValue,get,querySelector,getTagName,querySelectorAll,dispatchClick는 브라우저 전용 메서드로, Node.js 실행 환경에서는 제거됩니다. prettyTSD(tsd, isFormat)가 사용하는 TSD 포맷은＾(메타 구분자),｜(컬럼 구분자),↵(줄바꿈 구분자)라는 특수 유니코드 문자를 사용합니다. 일반적인 콤마/개행이 아니므로 데이터 원본 포맷을 확인하십시오.deepFreeze()로 고정한 객체는 strict mode에서 속성 변경 시TypeError가 발생할 수 있습니다(비-strict 모드에서는 조용히 무시됩니다).- Blob/File 관련 비동기 메서드(
blobToBase64,blobToFile,fileToBase64,fileToBlob,urlToBase64,resizeImage)는 모두 Promise를 반환하므로await또는.then()으로 처리해야 합니다.
관련 모듈
- DOM 조작:
syn.$m(manipulation) - 웹폼 컨트롤:
syn.$w(webform) - 네트워크 요청/Blob URL:
syn.$r(request) - 문자열 파싱(TSD 등):
syn.$string - API 상세는 아래 API 참조 섹션을 확인하세요.
API 참조
모듈 정보
| 항목 | 내용 |
|---|---|
| 별칭 | syn.$l, syn.$library, context.$library |
| 예제 경로 | 2.Modules/wwwroot/wwwroot/sample/syn/library.html, library.js |
| 의존 모듈 | $object(존재/타입 판별), $string(TSD 파싱, Boolean 변환), $date(파일명 타임스탬프), syn.$r(내부 urlToBase64가 httpFetch 사용), syn.getModuleLibrary(moduleEventLog) |
| 실행 환경 제약 | DOM 계열 메서드(addEvent, addEvents, addLive, removeEvent, hasEvent, trigger, triggerEvent, getValue, get, querySelector, getTagName, querySelectorAll, dispatchClick)는 Node.js에서 제거됨. getBasePath, moduleEventLog는 브라우저에서 제거됨(Node.js 전용) |
식별자 / 유틸리티
syn.$l.guid()
설명: RFC 4122 형식(8-4-4-4-12)을 준수하는 고유 식별자를 생성합니다. crypto.randomUUID → crypto.getRandomValues → Math.random 순으로 폴백합니다.
매개변수: 없음
반환값: string — 예: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
예시
var id = syn.$l.guid();
syn.$l.random(len = 8, toLower = false)
설명: 영문 대소문자와 숫자로 구성된 랜덤 문자열을 생성합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| len | number | 8 | 생성할 문자열 길이 |
| toLower | boolean | false | true면 소문자, false면 대문자로 반환 |
반환값: string
예시
var token = syn.$l.random(32, true);
syn.$l.getElement(el)
설명: 문자열 ID 또는 엘리먼트/EventTarget 계열 객체를 받아 실제 DOM 노드로 정규화합니다. 문자열이면 get()으로 우선 조회하고 실패 시 querySelector()로 재조회합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | string | Element | Window | Document | 엘리먼트 ID 또는 엘리먼트/윈도우/문서 객체 |
반환값: Element | null
예시
var el = syn.$l.getElement('txt_name');
syn.$l.execPrefixFunc(el, funcName)
설명: 브라우저 벤더 접두사(webkit, moz, ms, o, 무접두사) 순서로 el에서 funcName에 해당하는 속성/메서드를 찾아 값을 반환하거나 실행합니다. requestFullscreen처럼 벤더별로 이름이 다른 API를 다룰 때 사용합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | object | 대상 객체(DOM 엘리먼트 등) |
| funcName | string | 접두사를 제외한 기준 이름(첫 글자 대문자 기준으로 결합) |
반환값: 실행 결과 값 또는 속성 값, 매칭 실패 시 undefined
예시
var value = syn.$l.execPrefixFunc(document, 'Hidden'); // webkitHidden, mozHidden, hidden 순 탐색
인코딩 / 버퍼 변환
syn.$l.stringToArrayBuffer(value)
설명: 문자열을 UTF-8 ArrayBuffer로 인코딩합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| value | string | 변환할 문자열 |
반환값: ArrayBuffer
예시
var buffer = syn.$l.stringToArrayBuffer('hello world');
syn.$l.arrayBufferToString(buffer)
설명: ArrayBuffer를 UTF-8 문자열로 디코딩합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| buffer | ArrayBuffer | 변환할 버퍼 |
반환값: string (실패 시 빈 문자열)
예시
var text = syn.$l.arrayBufferToString(buffer);
DOM 이벤트
syn.$l.dispatchClick(el, options = {})
설명: 지정된 노드에 MouseEvent('click')을 생성하여 디스패치합니다. Node.js 환경 또는 document.createEvent가 없으면 무시됩니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| el | string | Element | - | 대상 엘리먼트 또는 ID |
| options | object | {} | MouseEvent 생성자 옵션(override) |
반환값: 없음
예시
syn.$l.dispatchClick('btn_submit');
syn.$l.addEvent(el, type, handler, options = {})
설명: 지정된 노드에 이벤트 핸들러를 등록합니다. 내부 레지스트리에 (엘리먼트, 타입, 핸들러) 조합이 없을 때만 실제 addEventListener를 호출하여 중복 등록을 방지합니다. type이 'resize'이면 등록 즉시 핸들러를 1회 호출합니다. 메서드 체이닝을 지원합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| el | string | Element | - | 대상 엘리먼트 또는 ID |
| type | string | - | 이벤트 타입 |
| handler | function | - | 이벤트 핸들러 |
| options | object | { capture: false, once: false, passive: false } | addEventListener 옵션 |
반환값: this(체이닝용)
예시
syn.$l.addEvent('txt_name', 'change', (evt) => { /* ... */ })
.addEvent('txt_name', 'blur', (evt) => { /* ... */ });
syn.$l.addEvents(query, type, handler, options = {})
설명: 셀렉터 문자열, 셀렉터/엘리먼트 배열, 단일 엘리먼트 중 하나를 받아 매칭되는 모든 노드에 동일한 이벤트 핸들러를 등록합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| query | string | Array | Element | 대상 셀렉터, 셀렉터/엘리먼트 배열 또는 엘리먼트 |
| type | string | 이벤트 타입 |
| handler | function | 이벤트 핸들러 |
| options | object | addEventListener 옵션 |
반환값: this
예시
syn.$l.addEvents(['input[type="text"]', 'textarea'], 'focus', (evt) => { /* ... */ });
syn.$l.addLive(query, type, handler, options = {})
설명: document에 이벤트를 위임 등록하여, 등록 시점 이후 동적으로 추가된 노드라도 query에 매칭되면 핸들러를 실행합니다(이벤트 위임/Live 바인딩).
| 매개변수 | 타입 | 설명 |
|---|---|---|
| query | string | evt.target.closest()에 사용할 셀렉터 |
| type | string | 이벤트 타입 |
| handler | function | 이벤트 핸들러(this가 매칭된 엘리먼트로 바인딩됨) |
| options | object | addEventListener 옵션 |
반환값: this
예시
syn.$l.addLive('.dynamic-row', 'click', function (evt) { console.log(this); });
syn.$l.removeEvent(el, type, handler, options = {})
설명: addEvent로 등록한 이벤트 핸들러를 해제합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | string | Element | 대상 엘리먼트 또는 ID |
| type | string | 이벤트 타입 |
| handler | function | 등록 시 사용한 핸들러 참조(동일 참조여야 함) |
| options | object | addEventListener 옵션 |
반환값: this
예시
syn.$l.removeEvent('txt_name', 'change', handlerRef);
syn.$l.hasEvent(el, type, handler)
설명: 지정된 노드에 특정 타입(및 선택적으로 특정 핸들러)의 이벤트가 등록되어 있는지 확인합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | string | Element | 대상 엘리먼트 또는 ID |
| type | string | 이벤트 타입 |
| handler | function (선택) | 특정 핸들러까지 일치하는지 확인 |
반환값: boolean
예시
if (syn.$l.hasEvent('txt_name', 'change')) { /* ... */ }
syn.$l.trigger(el, type, value)
설명: addEvent로 등록된(자체 레지스트리 기반) 핸들러들을 직접 호출합니다. 실제 브라우저 이벤트를 디스패치하지 않고 등록된 콜백만 실행합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | string | Element | 대상 엘리먼트 또는 ID |
| type | string | 이벤트 타입 |
| value | any | 핸들러에 전달할 값(evt 자리에 전달) |
반환값: boolean — 하나 이상 실행되면 true
예시
syn.$l.trigger('txt_name', 'change');
syn.$l.triggerEvent(el, type, customData)
설명: 실제 CustomEvent(또는 HTMLEvents)를 생성하여 노드에 디스패치합니다. trigger()와 달리 브라우저 이벤트 버블링/캡처링 체계를 따릅니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| el | string | Element | 대상 엘리먼트 또는 ID |
| type | string | 이벤트 타입 |
| customData | any | CustomEvent.detail로 전달될 데이터 |
반환값: this
예시
syn.$l.triggerEvent('txt_name', 'change', { source: 'api' });
DOM 조회
syn.$l.getValue(elID, defaultValue = '')
설명: 엘리먼트 ID로 값을 조회합니다. 웹폼 런타임 컨텍스트($this.context.synControls)가 있으면 해당 컨트롤 모듈의 getValue()를 통해 값을 가져오고, 그렇지 않으면 항상 defaultValue를 반환합니다(일반 DOM 페이지에서는 DOM 값을 직접 읽지 않는 구현상의 제약이 있습니다).
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| elID | string | - | 컨트롤/엘리먼트 ID |
| defaultValue | any | '' | 조회 실패 시 반환할 기본값 |
반환값: 조회된 값 또는 defaultValue
예시
var name = syn.$l.getValue('txt_name', '');
syn.$l.get(...ids)
설명: 하나 이상의 엘리먼트 ID로 document.getElementById를 수행합니다. 인자가 1개면 단일 노드(Element | null)를, 2개 이상이면 배열을 반환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| ids | ...string | 조회할 엘리먼트 ID 목록 |
반환값: Element | null (단일) 또는 Element[] (다중)
예시
var el = syn.$l.get('txt_name');
var [a, b] = syn.$l.get('txt_a', 'txt_b');
syn.$l.querySelector(...queries)
설명: 하나 이상의 CSS 셀렉터(또는 //, .//로 시작하는 XPath)로 각각 첫 번째 매칭 노드를 조회합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| queries | ...string | CSS 셀렉터 또는 XPath 문자열 목록 |
반환값: Element | null (단일 쿼리) 또는 Element[] (다중 쿼리)
예시
var el = syn.$l.querySelector('#txt_name');
syn.$l.getTagName(...tagNames)
설명: 하나 이상의 태그 이름으로 getElementsByTagName 결과를 모두 합쳐 반환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| tagNames | ...string | 조회할 태그 이름 목록 |
반환값: Element[]
예시
var buttons = syn.$l.getTagName('button', 'input');
syn.$l.querySelectorAll(...queries)
설명: 하나 이상의 CSS 셀렉터(또는 XPath)로 매칭되는 모든 노드를 조회하여 합쳐서 반환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| queries | ...string | CSS 셀렉터 또는 XPath 문자열 목록 |
반환값: Element[]
예시
var textInputs = syn.$l.querySelectorAll('input[type="text"]');
Enum 변환
syn.$l.toEnumValue(enumObject, value)
설명: enum 형태의 객체에서 키(value로 전달한 문자열)와 일치하는 항목의 값을 조회합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| enumObject | object | enum 객체 |
| value | string | 찾을 키 |
반환값: 매칭된 값 또는 null
예시
var value = syn.$l.toEnumValue(syn.$v.valueType, 'String');
syn.$l.toEnumText(enumObject, value)
설명: enum 형태의 객체에서 값(value)과 일치하는 항목의 키를 조회합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| enumObject | object | enum 객체 |
| value | any | 찾을 값 |
반환값: 매칭된 키(string) 또는 null
예시
var key = syn.$l.toEnumText(syn.$v.valueType, 0);
CSV / TSD 데이터 변환
syn.$l.prettyTSD(tsd, isFormat = false)
설명: ＾(메타 구분자) / ｜(컬럼 구분자) / ↵(줄바꿈 구분자)로 이루어진 TSD 문자열을 JSON으로 파싱합니다. ＾가 있으면 앞부분을 column:type;... 형태의 메타 정보로 해석하여 타입 변환에 사용합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| tsd | string | - | TSD 형식 문자열 |
| isFormat | boolean | false | true면 들여쓰기된 JSON 문자열로, false면 JS 객체로 반환 |
반환값: object[] | string
예시
var json = syn.$l.prettyTSD('AAA:string;BBB:number＾AAA｜BBB↵hello｜123', true);
syn.$l.text2Json(data, delimiter = ',', newLine = '\n')
설명: CSV 형식 문자열(첫 줄 헤더)을 JSON 객체 배열로 변환합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| data | string | - | CSV 문자열 |
| delimiter | string | , | 컬럼 구분자 |
| newLine | string | \n | 줄 구분자 |
반환값: object[]
예시
var json = syn.$l.text2Json('AAA,BBB\n1,2');
syn.$l.json2Text(arr, columns, delimiter = ',', newLine = '\n')
설명: JSON 객체 배열을 CSV 형식 문자열로 변환합니다. 값에 구분자/줄바꿈/큰따옴표가 있으면 자동으로 이스케이프 처리합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| arr | object[] | - | 변환할 객체 배열 |
| columns | string[] | - | 출력할 컬럼(키) 목록과 순서 |
| delimiter | string | , | 컬럼 구분자 |
| newLine | string | \n | 줄 구분자 |
반환값: string
예시
var csv = syn.$l.json2Text(json, ['AAA', 'BBB']);
트리 데이터 변환
syn.$l.nested2Flat(data, itemID, parentItemID, childrenID = 'items')
설명: 트리(중첩) 구조 객체를 평면 배열로 변환합니다. 루트 객체도 결과 배열에 포함되며 parentItemID 값은 null로 설정됩니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| data | object | - | 루트 트리 객체 |
| itemID | string | - | 각 항목의 고유 키 이름 |
| parentItemID | string | - | 부모 참조 키로 사용할 이름(결과에 추가됨) |
| childrenID | string | items | 자식 배열 속성 이름 |
반환값: object[]
예시
var flat = syn.$l.nested2Flat(tree, 'id', 'parentId', 'items');
syn.$l.flat2Nested(data, itemID, parentItemID, childrenID = 'items')
설명: 평면 배열을 트리(중첩) 구조로 변환합니다. parentItemID 값이 null인 항목을 루트로 인식합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| data | object[] | - | 평면 배열 |
| itemID | string | - | 각 항목의 고유 키 이름 |
| parentItemID | string | - | 부모 참조 키 이름 |
| childrenID | string | items | 결과에 채워질 자식 배열 속성 이름 |
반환값: object — 루트 노드(자식은 childrenID 속성에 중첩)
예시
var tree = syn.$l.flat2Nested(flatArray, 'id', 'parentId');
syn.$l.findNestedByID(data, findID, itemID, childrenID = 'items')
설명: 트리(또는 트리 배열)에서 itemID 값이 findID와 일치하는 첫 번째 노드를 재귀적으로 검색합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| data | object | object[] | - | 검색 대상 트리 또는 트리 배열 |
| findID | any | - | 찾을 ID 값 |
| itemID | string | - | 각 항목의 고유 키 이름 |
| childrenID | string | items | 자식 배열 속성 이름 |
반환값: 매칭된 노드 객체 또는 null
예시
var node = syn.$l.findNestedByID(tree, 10, 'id', 'items');
객체 고정
syn.$l.deepFreeze(object)
설명: 객체와 그 하위 객체 속성 전체를 재귀적으로 Object.freeze() 처리합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| object | object | 고정할 객체 |
반환값: 고정된 동일 객체(참조 유지)
예시
var frozen = syn.$l.deepFreeze({ value: 'hello' });
Blob / DataURI / Base64 / File 변환
syn.$l.createBlob(data, type)
설명: 데이터로부터 Blob을 생성합니다. Blob 생성자가 없는 구형 환경에서는 BlobBuilder 폴백을 시도합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| data | any | Blob 내용(문자열, ArrayBuffer 등) |
| type | string | MIME 타입 |
반환값: Blob | null
예시
var blob = syn.$l.createBlob('hello world', 'text/plain');
syn.$l.dataUriToBlob(dataUri)
설명: data: DataURI 문자열을 Blob으로 변환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| dataUri | string | data:mime;base64,... 형식 문자열 |
반환값: Blob | null
예시
var blob = syn.$l.dataUriToBlob('data:text/plain;base64,aGVsbG8=');
syn.$l.dataUriToText(dataUri)
설명: DataURI 문자열을 디코딩하여 { value, mime } 형태로 반환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| dataUri | string | data:mime;base64,... 형식 문자열 |
반환값: { value: string, mime: string } | null
예시
var { value, mime } = syn.$l.dataUriToText('data:text/plain;base64,aGVsbG8=');
syn.$l.blobToDataUri(blob, callback)
설명: FileReader를 사용해 Blob을 DataURI 문자열로 변환합니다. callback을 생략하면 Promise를 반환합니다(변환 실패 시 null resolve, 잘못된 입력이면 reject).
| 매개변수 | 타입 | 설명 |
|---|---|---|
| blob | Blob | 변환할 Blob |
| callback | function | (dataUri) => void (생략 가능) |
반환값: callback 전달 시 없음 / 생략 시 Promise<string \| null>
예시
syn.$l.blobToDataUri(blob, (dataUri) => console.log(dataUri));
const dataUri = await syn.$l.blobToDataUri(blob);
syn.$l.blobToDownload(blob, fileName)
설명: Blob을 파일로 즉시 다운로드합니다(IE의 msSaveOrOpenBlob 폴백 포함). Node.js 환경에서는 동작하지 않습니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| blob | Blob | 다운로드할 Blob |
| fileName | string | 저장 파일 이름 |
반환값: 없음
예시
syn.$l.blobToDownload(blob, 'hello.txt');
syn.$l.blobUrlToBlob(url, callback)
설명: Blob URL(blob:...)이나 일반 URL을 fetch로 조회하여 Blob으로 반환합니다. callback을 생략하면 Promise를 반환합니다(조회 실패 시 null resolve).
| 매개변수 | 타입 | 설명 |
|---|---|---|
| url | string | 조회할 URL |
| callback | function | (blob) => void (생략 가능) |
반환값: callback 전달 시 없음 / 생략 시 Promise<Blob \| null>
예시
syn.$l.blobUrlToBlob(blobUrl, (blob) => console.log(blob.size));
const blob = await syn.$l.blobUrlToBlob(blobUrl);
syn.$l.blobUrlToDataUri(url, callback)
설명: blobUrlToBlob + blobToDataUri를 연달아 수행하여 URL을 DataURI로 변환합니다. callback을 생략하면 Promise를 반환합니다(실패 시 null resolve).
| 매개변수 | 타입 | 설명 |
|---|---|---|
| url | string | 조회할 URL |
| callback | function | (dataUri) => void (생략 가능) |
반환값: callback 전달 시 없음 / 생략 시 Promise<string \| null>
예시
syn.$l.blobUrlToDataUri(blobUrl, (dataUri) => console.log(dataUri));
const dataUri = await syn.$l.blobUrlToDataUri(blobUrl);
syn.$l.blobToBase64(blob, base64Only = false)
설명: Blob을 Base64(또는 전체 DataURI) 문자열로 변환합니다. Node.js에서는 Buffer, 브라우저에서는 FileReader를 사용합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| blob | Blob | - | 변환할 Blob |
| base64Only | boolean | false | true면 순수 Base64만, false면 data:...;base64,... 전체 문자열 반환 |
반환값: Promise<string | null>
예시
var base64 = await syn.$l.blobToBase64(blob, true);
syn.$l.base64ToBlob(b64Data, contentType = '', sliceSize = 512)
설명: 순수 Base64 문자열을 Blob으로 변환합니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| b64Data | string | - | Base64 인코딩 문자열(DataURI 접두사 제외) |
| contentType | string | '' | 생성할 Blob의 MIME 타입 |
| sliceSize | number | 512 | 내부 청크 처리 크기(바이트) |
반환값: Blob | null
예시
var blob = syn.$l.base64ToBlob(base64Data, 'text/plain');
syn.$l.blobToFile(blob, fileName, mimeType)
설명: Blob을 File 객체로 변환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| blob | Blob | 변환할 Blob |
| fileName | string | 파일 이름(생략 시 blob-<timestamp>) |
| mimeType | string | MIME 타입(생략 시 blob.type) |
반환값: Promise<File | null>
예시
var file = await syn.$l.blobToFile(blob, 'hello.txt');
syn.$l.fileToBase64(file)
설명: File 객체(브라우저) 또는 로컬 경로/URL 문자열(Node.js)을 Base64 DataURI 문자열로 변환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| file | File | string | 브라우저에서는 File 객체, Node.js에서는 파일 경로 또는 http(s) URL |
반환값: Promise<string | null>
예시
var base64 = await syn.$l.fileToBase64(fileObject);
syn.$l.fileToBlob(file)
설명: fileToBase64 결과를 다시 base64ToBlob으로 변환하여 Blob을 반환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| file | File | string | fileToBase64와 동일 |
반환값: Promise<Blob | null>
예시
var blob = await syn.$l.fileToBlob(fileObject);
syn.$l.urlToBase64(url)
설명: syn.$r.httpFetch(url).send()로 원격 리소스를 조회한 뒤 Base64 문자열(순수 Base64)로 변환합니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| url | string | 조회할 URL |
반환값: Promise<string | null>
예시
var base64 = await syn.$l.urlToBase64('/images/logo.png');
syn.$l.resizeImage(blob, maxSize)
설명: 이미지 Blob을 <canvas>로 그려 긴 변 기준 maxSize 이하로 축소한 새 Blob(JPEG, 품질 0.9)을 반환합니다. Node.js 환경 또는 이미지가 아닌 Blob에는 사용할 수 없습니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| blob | Blob | - | image/* 타입의 Blob |
| maxSize | number | 80 | 축소 기준이 되는 최대 변 길이(px) |
반환값: Promise<{ blob: Blob, width: number, height: number }>
예시
var result = await syn.$l.resizeImage(imageBlob, 120);
로깅
syn.$l.logLevel
설명: eventLog/moduleEventLog에서 사용하는 로그 레벨 열거자입니다. { Verbose: 0, Debug: 1, Information: 2, Warning: 3, Error: 4, Fatal: 5 }
syn.$l.eventLog(event, data, logLevelInput = 'Verbose', logStyle = null)
설명: syn.js 전반에서 사용하는 중앙 로거입니다. 지정한 로그 레벨이 syn.Config.UIEventLogLevel보다 낮으면 무시됩니다. 브라우저에서는 레벨에 따라 console.log/info/warn/error로 출력하고(logStyle 지정 시 %c 스타일 적용), id="eventlogs" 엘리먼트가 있으면 로그 내용을 해당 엘리먼트에 append합니다. Node.js에서는 globalRoot.$logger로 위임됩니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| event | string | - | 로그 출처(모듈.메서드 등) |
| data | string | Error | - | 로그 메시지 또는 Error 객체 |
| logLevelInput | string | number | 'Verbose' | logLevel 열거자의 키 또는 값 |
| logStyle | string | null | 브라우저 콘솔용 CSS 스타일 문자열 |
반환값: 없음
예시
syn.$l.eventLog('library.html', '경고 메시지', 'Warning');
syn.$l.getBasePath(basePathInput, defaultPath) (Node.js 전용)
설명: Node.js 실행 환경에서 상대/절대 경로를 현재 작업 디렉터리(process.cwd()) 기준의 절대 경로로 정규화합니다. 브라우저 환경에서는 basePathInput || defaultPath || ''를 그대로 반환하지만, 브라우저에서는 이 메서드 자체가 로드 시 삭제되어 존재하지 않습니다.
| 매개변수 | 타입 | 설명 |
|---|---|---|
| basePathInput | string | 기준이 될 입력 경로(상대/절대) |
| defaultPath | string | basePathInput이 없을 때 사용할 기본 경로 |
반환값: string — 정규화된 절대 경로
syn.$l.moduleEventLog(moduleID, event, data, logLevelInput = 'Verbose') (Node.js 전용)
설명: syn.getModuleLibrary(moduleID)로 조회한 모듈 전용 로거(logger.debug/info/warn/error/fatal/trace)에 로그를 기록합니다. Node.js 실행 환경에서만 동작하며, 브라우저에서는 이 메서드가 로드 시 삭제되어 존재하지 않습니다.
| 매개변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| moduleID | string | - | 대상 모듈 ID |
| event | string | - | 로그 출처 |
| data | string | object | - | 로그 메시지 또는 message/stack을 가진 객체 |
| logLevelInput | string | 'Verbose' | logLevel 열거자의 키 |
반환값: 없음