comcigan-timetable

Node.js 환경에서 컴시간의 학교 시간표를 파싱하는 라이브러리입니다.

주요 개선점

• request(deprecated) -> axios (최신 HTTP 클라이언트)
• eval() -> Node.js vm 모듈 (격리된 샌드박스 실행)
• 변경된 시간표(노란색 셀) changed 플래그 감지
• 휴일 자동 감지 (모든 교시가 빈 요일)
• 체계적인 에러 처리 (TimetableError + 에러 코드)
• VM 스크립트 캐싱으로 성능 최적화

설치

npm i comcigan-timetable

Node.js 14+ 필요

사용법

1. 기본 사용

const Timetable = require('comcigan-timetable');

async function main() {
  const timetable = new Timetable();
  await timetable.init({ maxGrade: 3 });

  const list = await timetable.search('광명');
  const school = list.find(s => s.name === '광명고등학교');
  timetable.setSchool(school.code);

  const result = await timetable.getTimetable();
  console.log(result[1][1][0]);

  const times = await timetable.getClassTime();
  console.log(times);
}

main().catch(e => console.error(e.message));

2. async/await 패턴

const Timetable = require('comcigan-timetable');
const tt = new Timetable();

await tt.init({ cache: 1000 * 60 * 30 });
const schools = await tt.search('광명');
const school = schools.find(s => s.name === '광명고등학교');
tt.setSchool(school.code);

const [result, times] = await Promise.all([
  tt.getTimetable(),
  tt.getClassTime(),
]);

3. 에러 처리

const Timetable = require('comcigan-timetable');

try {
  const tt = new Timetable();
  await tt.init();
  await tt.search('');
} catch (e) {
  console.log(e.name);        // 'TimetableError'
  console.log(e.code);        // 'INVALID_KEYWORD'
  console.log(e.message);     // '검색어를 입력해주세요.'
}

에러 코드 목록:

| 코드 | 설명 | |------|------| | NOT_INITIALIZED | init() 미호출 | | SCHOOL_NOT_SET | setSchool() 미호출 | | INVALID_OPTION | init() 옵션 값 오류 | | INVALID_KEYWORD | 검색어가 비어있음 | | INVALID_SCHOOL_CODE | 학교 코드가 올바르지 않음 | | SCHOOL_NOT_FOUND | 검색 결과 없음 | | NETWORK_ERROR | 네트워크 요청 실패 | | PARSE_ERROR | 응답 데이터 파싱 실패 | | DATA_EMPTY | 시간표 데이터 없음 | | INIT_FAILED | 초기화 중 오류 발생 |

API

new Timetable()

인스턴스를 생성합니다.

const tt = new Timetable();

init(options?)

파서를 초기화합니다. 모든 메서드 호출 전에 반드시 실행해야 합니다.

await tt.init();
await tt.init({ maxGrade: 3, cache: 60000 });

| 옵션 | 타입 | 기본값 | 설명 | |------|------|--------|------| | maxGrade | number | 3 | 최대 학년 (초등: 6, 중/고: 3) | | cache | number | 0 | 캐시 지속시간(ms), 0=비활성 |

search(keyword)

학교를 검색합니다.

const list = await tt.search('광명');
// [
//   { _: 24966, region: '경기', name: '광명북중학교', code: 74350 },
//   { _: 24966, region: '경기', name: '광명고등학교', code: 31443 },
// ]

| 반환 필드 | 타입 | 설명 | |-----------|------|------| | _ | number | 내부 식별 코드 | | region | string | 지역명 | | name | string | 학교명 | | code | number | 학교 코드 (setSchool에 사용) |

setSchool(code)

시간표를 조회할 학교를 지정합니다.

tt.setSchool(74350);

getTimetable()

전체 시간표를 조회합니다.

const result = await tt.getTimetable();

접근 패턴: result[학년][반][요일][교시]

• 요일: 0(월) ~ 4(금)
• 교시: 0(1교시) ~ 7(8교시)

// 3학년 8반 화요일 2교시
result[3][8][1][1];
// 2학년 5반 금요일 3교시
result[2][5][4][2];

개별 교시 데이터:

{
  grade: 3,          // 학년
  class: 3,          // 반
  weekday: 0,        // 요일 (0=월)
  weekdayString: '월', // 요일 문자열
  classTime: 1,      // 교시
  subject: '수학',    // 과목명
  teacher: '한보*',   // 선생님
  changed: false      // 변경 여부 (true=노란색 변경 셀)
}

• changed: true -> 사이트에서 노란색으로 표시된 변경 시간표
• 요일 전체가 비어있으면 -> 휴일

getClassTime()

교시별 수업 시간 정보를 조회합니다.

const times = await tt.getClassTime();
// ['1(09:00)', '2(09:55)', '3(10:50)', ...]

getJsonData()

디버깅용 원본 JSON 데이터를 반환합니다.

const raw = tt.getJsonData();

데이터 구조

시간표 전체 구조

{
  "1": {               // 1학년
    "1": [             // 1반
      [ /* 월요일 */ ], [ /* 화요일 */ ],
      [ /* 수요일 */ ], [ /* 목요일 */ ],
      [ /* 금요일 */ ]
    ],
    "2": [ /* 2반 */ ],
    ...
  },
  "2": { /* 2학년 */ },
  "3": { /* 3학년 */ }
}

활용 예시

// 3학년 8반 전체 시간표 (월~금)
const class8 = result[3][8];

// 1학년 1반 월요일 (0) 시간표
const monday = result[1][1][0];

// 1학년 전체 출력
for (let cls = 1; cls <= 10; cls++) {
  const timetable = result[1][cls];
}

변경사항

2.0.0

• request -> axios 전환
• eval() -> vm 모듈 (샌드박스 실행)
• changed 플래그 (변경 시간표 감지)
• TimetableError + 에러 코드 시스템
• VM 스크립트 캐싱으로 성능 최적화
• 중복 네트워크 요청 제거
• 입력값 검증 강화
• 타임아웃 설정 (HTTP 15s, VM 2s)
• Node.js 14+ 지원