createFileAuditSink — @gj-kit/toss-payments

@gj-kit/toss-payments/server에서 공개하는 function입니다. package version 0.6.1의 release declaration을 그대로 표시합니다.

검증된 import 예제

import { createFileAuditSink } from '@gj-kit/toss-payments/server';

시그니처, 매개변수, 반환 타입

/**
 * createFileAuditSink — JSONL append 파일 싱크 참조 구현 (설계 §3.2).
 *
 * 코어 "런타임 의존성 0·플랫폼 중립" 원칙과의 공존:
 * - `node:fs/promises`는 **최초 record 시 지연 동적 import** — 정적 `node:` import가 없어
 *   번들에 node 의존이 각인되지 않는다(tsup `external: [/^node:/]` + platform neutral 유지).
 * - Edge에서 createFileAuditSink를 호출하지 않는 한 "./server"의 Edge 호환은 불변이다.
 *
 * 운영 계약:
 * - Promise 체이닝 직렬화 큐 — record 호출 순서 = 파일 append 순서(엔트리 교차 없음).
 *   한 append의 실패는 그 record의 반환 Promise로만 전파되고 큐는 계속 살아있다.
 * - fire-and-forget(클라이언트가 await하지 않음)이라 프로세스 즉사 시 마지막 엔트리가
 *   유실될 수 있다 — `flush()`/`close()`를 graceful shutdown 훅에 연결하라.
 * - ⚠ 다중 프로세스 병행 쓰기 무방비 — 단일 인스턴스(프로세스당 파일 1개) 전제.
 */
declare function createFileAuditSink(filePath: string, options?: {
    /** 엔트리 → 1행 문자열(개행 미포함). 기본 JSONL 1행(JSON.stringify). */
    readonly formatter?: (entry: AuditEntry) => string;
}): AuditSink & {
    flush(): Promise<void>;
    close(): Promise<void>;
};

이 선언은 매개변수, optionality, 제네릭, 반환값, 공개 union/type 계약의 정본입니다. 호출 전 필요한 환경·권한·오류 경계는 패키지 Golden path와 이 subpath의 import 조건을 함께 확인하세요.

Release context

• 패키지: @gj-kit/toss-payments
• 버전: 0.6.1
• 공개 entry: ./server
• 소스: GitHub

구현 주석

createFileAuditSink — JSONL append 파일 싱크 참조 구현 (설계 §3.2).

코어 “런타임 의존성 0·플랫폼 중립” 원칙과의 공존:

• node:fs/promises는 최초 record 시 지연 동적 import — 정적 node: import가 없어 번들에 node 의존이 각인되지 않는다(tsup external: [/^node:/] + platform neutral 유지).
• Edge에서 createFileAuditSink를 호출하지 않는 한 “./server”의 Edge 호환은 불변이다.

운영 계약:

• Promise 체이닝 직렬화 큐 — record 호출 순서 = 파일 append 순서(엔트리 교차 없음). 한 append의 실패는 그 record의 반환 Promise로만 전파되고 큐는 계속 살아있다.
• fire-and-forget(클라이언트가 await하지 않음)이라 프로세스 즉사 시 마지막 엔트리가 유실될 수 있다 — flush()/close()를 graceful shutdown 훅에 연결하라.
• ⚠ 다중 프로세스 병행 쓰기 무방비 — 단일 인스턴스(프로세스당 파일 1개) 전제.