parsePaymentStateSnapshot — @gj-kit/toss-payments

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

검증된 import 예제

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

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

/**
 * Validates an untrusted value (a stored/transported
 * {@link SerializedPaymentStateSnapshot}) back into a branded {@link PaymentStateSnapshot}.
 *
 * Structure is checked exhaustively — `schemaVersion: 1`, every field's type, every literal
 * against its closed union (status, lifecycle, amountState, cancelStatus, issue kinds and
 * their per-kind fields) — and `paymentKey`/`orderId` are re-branded through the existing
 * {@link paymentKey}/{@link orderId} smart constructors, keeping validation-as-the-only-path
 * to a brand intact. The first failing location is reported in `error.path`.
 *
 * Two hardening rules beyond the per-field checks:
 *
 * - **Single read.** Every own enumerable property of the untrusted value is read exactly
 *   once (a one-shot shallow copy per level) before validation, so the value that was
 *   type-checked is the value placed in the branded result — an accessor property cannot
 *   return a valid value to the check and a different one to the constructor. Inherited
 *   (prototype-supplied) properties are ignored.
 * - **Pinned arithmetic.** `canceledAmount` must equal `totalAmount - balanceAmount`
 *   whenever both amounts are safe integers — the one derivation `schemaVersion: 1` pins
 *   that {@link compareLedgerRefund}'s verdict hangs on. Snapshots whose amounts already
 *   carry `invalid-amount` issues are left to the comparison's indeterminate gate instead.
 *
 * Otherwise this is a *shape* gate, not a re-summarization: the remaining derived fields
 * (`lifecycle`, `amountState`, `isCancelable`, `consistencyIssues`, …) are trusted as data
 * produced by an earlier {@link summarizePaymentState} and are not re-derived here.
 */
declare function parsePaymentStateSnapshot(value: unknown): Result<PaymentStateSnapshot, InvalidPaymentStateSnapshot>;

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

Release context

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

구현 주석

Validates an untrusted value (a stored/transported {@link SerializedPaymentStateSnapshot}) back into a branded {@link PaymentStateSnapshot}.

Structure is checked exhaustively — schemaVersion: 1, every field’s type, every literal against its closed union (status, lifecycle, amountState, cancelStatus, issue kinds and their per-kind fields) — and paymentKey/orderId are re-branded through the existing {@link paymentKey }/{@link orderId } smart constructors, keeping validation-as-the-only-path to a brand intact. The first failing location is reported in error.path.

Two hardening rules beyond the per-field checks:

• Single read. Every own enumerable property of the untrusted value is read exactly once (a one-shot shallow copy per level) before validation, so the value that was type-checked is the value placed in the branded result — an accessor property cannot return a valid value to the check and a different one to the constructor. Inherited (prototype-supplied) properties are ignored.
• Pinned arithmetic. canceledAmount must equal totalAmount - balanceAmount whenever both amounts are safe integers — the one derivation schemaVersion: 1 pins that {@link compareLedgerRefund}’s verdict hangs on. Snapshots whose amounts already carry invalid-amount issues are left to the comparison’s indeterminate gate instead.

Otherwise this is a shape gate, not a re-summarization: the remaining derived fields (lifecycle, amountState, isCancelable, consistencyIssues, …) are trusted as data produced by an earlier {@link summarizePaymentState} and are not re-derived here.