자바스크립트 클라이언트(bareun)

자바스크립트·타입스크립트에서 바른 사용하기

npm 패키지 bareun 으로 형태소 분석·맞춤법 교정·동형이의어 의미 구분· 우리말샘 음소 검색을 씁니다.

• 저장소: bareun-js
• 현재 버전: 2.0.0
• Node 18 이상, 그리고 브라우저

2.0.0 은 배포 준비 중입니다

npm 에 아직 올라가지 않았습니다. 그전까지는 저장소를 받아 pnpm build 후 로컬에서 참조해 쓰세요.

이미 배포된 1.1.0 은 형태소 분석과 사용자 사전만 지원하고 Node 전용입니다. 맞춤법 교정·의미 구분·음소 검색과 브라우저 지원은 2.0.0 부터입니다.

설치

npm install bareun

타입 정의가 함께 들어 있어 타입스크립트에서 바로 씁니다.

준비물

• 실행 중인 바른 서버. 로컬 설치본은 5658, 도커는 5656 이 기본 포트입니다.
• API 키. koba- 로 시작합니다. 발급 방법

맞춤법 교정과 우리말샘 음소 검색은 맞춤법 교정 기능이 포함된 서버에서만 됩니다.

형태소 분석

import { createBareunClient, Tagger } from "bareun";

const client = createBareunClient({
  apiKey: "koba-...",
  host: "localhost",
  port: 5656,
});

const t = await new Tagger(client).tag("아버지가 방에 들어가신다.");

t.pos();     // ["아버지/NNG", "가/JKS", "방/NNG", "에/JKB", "들어가/VV", ...]
t.morphs();  // ["아버지", "가", "방", "에", "들어가", "시", "ㄴ다", "."]
t.nouns();   // ["아버지", "방"]
t.verbs();   // ["들어가"]

클라우드에 붙을 때는 주소를 통째로 줍니다.

createBareunClient({ apiKey: "koba-...", baseUrl: "https://api.bareun.ai" });

브라우저에서

서버가 CORS 를 직접 처리하므로 프록시 없이 부를 수 있습니다.

공개 페이지에서는 API 키가 노출됩니다

번들에 키가 그대로 들어갑니다. 공개 서비스라면 서버를 하나 두고 그쪽에서 바른을 부르세요. 사내 도구나 프로토타입에서는 편리합니다.

위치 정보

요청은 UTF-16 오프셋으로 보냅니다. 자바스크립트 문자열이 UTF-16 이라, 서버가 준 위치를 slice 에 그대로 넣을 수 있습니다.

const span = t.response.sentences[0].tokens[0].text;
text.slice(span.beginOffset, span.beginOffset + span.length);  // "아버지가"

사용자 사전

const tagger = new Tagger(client, ["mydict"]);

사전은 client.customDictionary 로 만들고 지웁니다. 여럿을 주면 앞에 온 것이 우선합니다. 사용자 사전 API 참고.

맞춤법 교정

import { Corrector } from "bareun";

const c = new Corrector(client);

await c.correct("이거 안되요. 학교에 갔읍니다.");
// "이거 안되요. 학교에 갔습니다."

for (const ch of await c.changes("이거 안되요. 학교에 갔읍니다.")) {
  console.log(`${ch.origin} → ${ch.revised} (${ch.category})`);
}
// 갔읍니다. → 갔습니다. (STANDARD)

beginOffset·length 도 자바스크립트 문자열 기준이라 slice 에 바로 씁니다. 중첩 교정이나 도움말까지 보려면 c.raw(text) 로 서버 응답을 그대로 받습니다.

자세한 내용은 맞춤법 검사 API 를 보세요.

동형이의어 의미 구분

const t = await tagger.tag("나는 밤에 밤을 먹었다.", { withSense: true });
for (const s of t.senses()) {
  console.log(`${s.morph}/${s.tag} ${s.senseNo} ${s.meaning}`);
}
// 밤/NNG 2 밤나무의 열매. ...
// 먹/VV 2 음식 따위를 입을 통하여 뱃속에 들여보내다.

조사·어미처럼 의미를 갖지 않는 형태소에는 원래 붙지 않으므로, 대부분의 형태소는 결과에 나오지 않습니다. 동형이의어 의미 구분 API 참고.

우리말샘 음소 검색

import { DictSearchAnchor } from "bareun";

const res = await client.dictSearch.searchDict({
  pattern: "{ㅅ//ㄴ}다",
  pos: ["동사"],
});
res.entries.map((e) => e.word);  // ["신다"]

const suffix = await client.dictSearch.searchDict({
  pattern: "아지",
  anchor: DictSearchAnchor.SUFFIX,
  limit: 5,
});
suffix.entries.map((e) => e.word);  // ["아지", "가아지", "강아지", "개아지", "갱아지"]

패턴 문법은 우리말샘 음소 검색 API 를 보세요.

오류 처리

import { Code, isBareunError, describeError } from "bareun";

try {
  await tagger.tag("문장");
} catch (e) {
  if (isBareunError(e)) {
    if (e.code === Code.PermissionDenied) console.error("API 키를 확인하세요");
    else console.error(describeError(e));
  }
}

코드	언제
Unavailable	서버에 닿지 못함. 주소 오타·미기동·CORS
PermissionDenied	API 키가 유효하지 않거나 라이선스 만료
Unimplemented	그 서버가 제공하지 않는 기능
ResourceExhausted	사용량 한도 초과

describeError(e) 는 무엇을 확인해야 하는지 붙인 한국어 문장을 돌려줍니다.

1.x 에서 옮겨오기

2.0.0 은 1.x 와 호환되지 않습니다.

1.x	2.0.0
@grpc/grpc-js, 실행 시점 .proto 파싱	Connect, 미리 만든 타입
Node 전용	Node 18+ 와 브라우저
타입 없음	타입스크립트로 작성, .d.ts 포함
CommonJS 만	ESM·CJS 모두
형태소 분석·사용자 사전	+ 교정·의미 구분·음소 검색

이 라이브러리가 감싸지 않은 기능

client.language·client.revision·client.dictSearch·client.customDictionary 가 서버의 모든 메서드를 그대로 노출합니다. 요청·응답 타입도 함께 내보냅니다.

import { EncodingType } from "bareun";

await client.language.analyzeSyntaxRaw({
  document: { content: "문장", language: "ko_KR" },
  encodingType: EncodingType.UTF16,
});

자주 묻는 질문

Q. 브라우저에서 바로 써도 되나요? A. 동작은 합니다. 서버가 CORS 를 직접 처리하므로 프록시가 필요 없습니다. 다만 공개 페이지라면 번들에 API 키가 노출되므로, 서버를 하나 두고 그쪽에서 부르세요.

Q. Node 16 에서 쓸 수 있나요? A. 전역 fetch 가 필요해 Node 18 이상을 권합니다. 16 에서는 fetch 구현을 직접 넘기면 동작할 수 있습니다(createBareunClient({ fetch })).

Q. 타입스크립트 없이 자바스크립트로만 써도 되나요? A. 됩니다. ESM 과 CommonJS 를 모두 내보내므로 import 와 require 양쪽에서 씁니다.

도움이 되었나요?

의견 보내기