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

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

검증된 import 예제

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

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

/**
 * 에러 모델 — 이 패키지가 스스로 만든 실패만 감싼다 (설계 §5).
 *
 * 코어 계약상 스토어는 **throw**하고, 코어가 store-failure Err로 감싼다(cause 체인 동봉).
 * 따라서 여기의 원칙은 둘뿐이다:
 * - 드라이버 에러는 감싸지 않고 그대로 통과시킨다 — cause 체인·드라이버 고유 필드
 *   (SQLSTATE 등)를 보존해야 소비자가 재시도/알림 정책을 세울 수 있다.
 * - 이 패키지가 직접 판정한 실패(식별자 위반·주문 충돌·안전하지 않은 금액·행 손상·
 *   마이그레이션 실패)만 안정적인 code를 가진 {@link TossPostgresError}로 던진다.
 *
 * ⚠ 보안 불변식: 어떤 에러 메시지에도 secret·billingKey 값을 싣지 않는다.
 * billingKey와 customerKey를 같은 문자열에 함께 두지 않는다(코어 stores.ts ⚠ 준수).
 */
type TossPostgresErrorCode =
/** 스키마 식별자가 `/^[a-z_][a-z0-9_]{0,62}$/` 위반 — SQL 보간 유일 지점의 봉쇄. */
'invalid-identifier'
/** saveOrder가 이미 저장된 orderId에 **다른 값**으로 재저장 시도 — 금액 대조 원본 보호. */
 | 'order-conflict'
/** bigint 컬럼 값이 Number.isSafeInteger 범위를 벗어남 — 금액 정밀도 손실 거부. */
 | 'unsafe-amount'
/** DB 행이 코어 계약 형태로 복원 불가(타입/유니언 위반·JSON 손상) — 조용한 오염 전파 거부. */
 | 'invalid-row'
/** migrate() 실패 — ROLLBACK 후 원인은 cause 체인으로 보존된다. */
 | 'migration-failed';

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

Release context

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

구현 주석

에러 모델 — 이 패키지가 스스로 만든 실패만 감싼다 (설계 §5).

코어 계약상 스토어는 throw하고, 코어가 store-failure Err로 감싼다(cause 체인 동봉). 따라서 여기의 원칙은 둘뿐이다:

• 드라이버 에러는 감싸지 않고 그대로 통과시킨다 — cause 체인·드라이버 고유 필드 (SQLSTATE 등)를 보존해야 소비자가 재시도/알림 정책을 세울 수 있다.
• 이 패키지가 직접 판정한 실패(식별자 위반·주문 충돌·안전하지 않은 금액·행 손상· 마이그레이션 실패)만 안정적인 code를 가진 {@link TossPostgresError}로 던진다.

⚠ 보안 불변식: 어떤 에러 메시지에도 secret·billingKey 값을 싣지 않는다. billingKey와 customerKey를 같은 문자열에 함께 두지 않는다(코어 stores.ts ⚠ 준수).