사용 예시

// example.ts
import { DataWriter, DataReader, jsonSerializer, createSerializer } from '@elilee/index-file';

// ============================================
// 1. JSON 직렬화 (간단한 경우)
// ============================================

interface UserLog {
  userId: string;
  action: string;
  metadata: Record<string, unknown>;
}

// 쓰기
const logWriter = new DataWriter<UserLog>('./data/logs', {
  serializer: jsonSerializer<UserLog>(),
  maxEntries: 100_000,
});
logWriter.open();

logWriter.append({ userId: 'u1', action: 'login', metadata: { ip: '1.2.3.4' } });
logWriter.append({ userId: 'u2', action: 'purchase', metadata: { amount: 100 } });
logWriter.append({ userId: 'u3', action: 'logout', metadata: {} });

console.log(logWriter.getStats());
logWriter.close();

// 읽기
const logReader = new DataReader<UserLog>('./data/logs', jsonSerializer<UserLog>());
logReader.open();

// 단일 조회
const single = logReader.getBySequence(2);
console.log('Single:', single);
// { sequence: 2, timestamp: 1234567890n, data: { userId: 'u2', action: 'purchase', ... } }

// 범위 조회
const bulk = logReader.getBulkData(1, 3);
console.log('Bulk:', bulk);
// [{ sequence: 1, ... }, { sequence: 2, ... }, { sequence: 3, ... }]

// 전체 조회
const all = logReader.getAllData();
console.log('Total:', all.length);

logReader.close();


// ============================================
// 2. 커스텀 바이너리 직렬화 (고성능)
// ============================================

interface SensorData {
  sensorId: number;
  temperature: number;
  humidity: number;
}

const sensorSerializer = createSerializer<SensorData>(
  // serialize
  (data) => {
    const buf = Buffer.alloc(12);
    buf.writeUInt32LE(data.sensorId, 0);
    buf.writeFloatLE(data.temperature, 4);
    buf.writeFloatLE(data.humidity, 8);
    return buf;
  },
  // deserialize
  (buf) => ({
    sensorId: buf.readUInt32LE(0),
    temperature: buf.readFloatLE(4),
    humidity: buf.readFloatLE(8),
  })
);

const sensorWriter = new DataWriter<SensorData>('./data/sensors', {
  serializer: sensorSerializer,
  maxEntries: 1_000_000,
});
sensorWriter.open();

// 대량 추가
for (let i = 0; i < 10000; i++) {
  sensorWriter.append({
    sensorId: i % 100,
    temperature: 20 + Math.random() * 10,
    humidity: 40 + Math.random() * 30,
  });
}

sensorWriter.close();

const sensorReader = new DataReader<SensorData>('./data/sensors', sensorSerializer);
sensorReader.open();

// 범위 조회
const range = sensorReader.getBulkData(5000, 5010);
console.log('Range:', range.length, 'records');

// 타임스탬프 범위 조회
const now = BigInt(Date.now()) * 1000000n;
const oneHourAgo = now - 3600n * 1000000000n;
const byTime = sensorReader.getBulkDataByTime(oneHourAgo, now);
console.log('By time:', byTime.length, 'records');

sensorReader.close();


// ============================================
// 3. 벌크 추가
// ============================================

interface Order {
  orderId: string;
  amount: number;
  status: string;
}

const orderWriter = new DataWriter<Order>('./data/orders', {
  serializer: jsonSerializer<Order>(),
});
orderWriter.open();

const orders: Order[] = [
  { orderId: 'O-001', amount: 150, status: 'pending' },
  { orderId: 'O-002', amount: 250, status: 'completed' },
  { orderId: 'O-003', amount: 350, status: 'shipped' },
];

const sequences = orderWriter.appendBulk(orders);
console.log('Added sequences:', sequences);  // [1, 2, 3]

orderWriter.close();

---

API 요약

DataWriter

메서드	설명
open()	파일 열기 (없으면 생성)
append(data, timestamp?)	레코드 추가, 시퀀스 반환
appendBulk(records, timestamp?)	여러 레코드 추가, 시퀀스 배열 반환
getLastSequence()	마지막 시퀀스 번호
getNextSequence()	다음 시퀀스 번호
sync()	디스크에 동기화
close()	파일 닫기
getStats()	상태 정보

DataReader

메서드	설명
open()	파일 열기
getBySequence(seq)	시퀀스로 단일 조회
getByIndex(index)	인덱스로 단일 조회
getBulkData(startSeq, endSeq)	시퀀스 범위 조회
getBulkDataByTime(startTs, endTs)	타임스탬프 범위 조회
getAllData()	전체 조회
getRecordCount()	레코드 수
getLastSequence()	마지막 시퀀스
close()	파일 닫기

Serializers

// JSON (범용)
jsonSerializer<T>()

// MessagePack (빠름, npm install @msgpack/msgpack 필요)
msgpackSerializer<T>()

// 커스텀 바이너리
createSerializer<T>(serialize, deserialize)