PgStoreOptions — @gj-kit/toss-payments-postgresql

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

검증된 import 예제

import { PgStoreOptions } from '@gj-kit/toss-payments-postgresql';

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

/**
 * OrderStore PostgreSQL 구현 — 금액 대조의 단일 진실 공급원 (설계 §3.1).
 *
 * 코어 계약의 핵심 불변식:
 * - `saveOrder`는 **insert-only + 동일값 재저장 무해**다. 조용한 upsert로 원본 금액을
 *   덮으면 confirm의 금액 대조 검증 전체가 무력화된다 — 다른 값 재저장은
 *   `order-conflict`로 throw하고, 동일값 재시도(네트워크 재시도 등)는 멱등하게 성공한다.
 *   동일값 판정은 **대조 원본인 amount·currency·orderName만** 본다 — createdAt은 코어
 *   createOrder가 호출마다 clock()으로 새로 찍으므로(confirm.ts), 비교에 넣으면
 *   소비자 orderId 재제출(더블클릭 등)이 항상 conflict가 되어 멱등 보장이 도달
 *   불가능해진다. 최초 저장본의 createdAt이 유지된다.
 * - `createdAt`은 코어가 string으로 준 원문을 text로 왕복 보존한다(재직렬화 손실 금지).
 * - pg 드라이버는 bigint를 string으로 반환한다 — `loadOrder`는 Number 변환 후
 *   `Number.isSafeInteger` 검증을 통과한 값만 내보낸다(정밀도 손실 거부).
 */
interface PgStoreOptions {
    /** 기본 'toss_payments'. `/^[a-z_][a-z0-9_]{0,62}$/` 위반 시 즉시 throw. */
    readonly schema?: string;
}

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

Release context

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

구현 주석

OrderStore PostgreSQL 구현 — 금액 대조의 단일 진실 공급원 (설계 §3.1).

코어 계약의 핵심 불변식:

• saveOrder는 insert-only + 동일값 재저장 무해다. 조용한 upsert로 원본 금액을 덮으면 confirm의 금액 대조 검증 전체가 무력화된다 — 다른 값 재저장은 order-conflict로 throw하고, 동일값 재시도(네트워크 재시도 등)는 멱등하게 성공한다. 동일값 판정은 대조 원본인 amount·currency·orderName만 본다 — createdAt은 코어 createOrder가 호출마다 clock()으로 새로 찍으므로(confirm.ts), 비교에 넣으면 소비자 orderId 재제출(더블클릭 등)이 항상 conflict가 되어 멱등 보장이 도달 불가능해진다. 최초 저장본의 createdAt이 유지된다.
• createdAt은 코어가 string으로 준 원문을 text로 왕복 보존한다(재직렬화 손실 금지).
• pg 드라이버는 bigint를 string으로 반환한다 — loadOrder는 Number 변환 후 Number.isSafeInteger 검증을 통과한 값만 내보낸다(정밀도 손실 거부).