normalize.ts の invoiceToRow のコメントが、stripe 22.6.2 の Invoice.payments の型と一致しない

Open Beginner friendly
#87 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
90/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
documentation

Research direction

Read the comment at the start of packages/api/src/payments/normalize.ts and verify the Stripe.Invoice declarations with the provided grep command in stripe 22.6.2. Update the comment so id and lines are distinguished from the already-optional payments field, while preserving the explanation for maybeAbsent. Done means the comment matches the reported types and behavior.

Written by the indexing model from the issue text.

Description

bug documentation

症状

packages/api/src/payments/normalize.ts の invoiceToRow の冒頭のコメントが、
Stripe's types declare id, linesandpayments as always present. と述べている。
このうち payments が、現在固定している stripe の型と一致しない。

packages/api/package.json は stripe を ^22.6.2 で宣言している。22.6.2 の
Stripe.Invoice の宣言を読むと次のとおりである。

  • id: string — 省略不可。コメントの記述と一致する。
  • lines: ApiList<InvoiceLineItem> — 省略不可。コメントの記述と一致する。
  • payments?: ApiList<InvoicePayment> — 省略可能。コメントの記述と一致しない。

つまり 3 つのうち payments だけが、型の上で既に「常に在る」ではない。

コメントはこの直後で「This normalizer still reads them as possibly-absent」と続き、
maybeAbsent で包む理由を「型は常に在ると言っているが、壊れた応答を 1 行の部分的な
行に落とすために、あえて不在として読む」と説明している。payments についてはこの
説明が成り立たない。型が既に省略可能だと言っているので、maybeAbsent は型に逆らう
読み方ではなく、型に従った読み方である。

誰が何を誤るか

このコメントを読んだ人が、invoice.payments を型の上で常に在るものとして扱ってよい
と判断する。実際には省略可能なので、maybeAbsent を外して直接読む書き換えをすると、
payments が無い応答で未定義参照になる。

逆方向の誤りもある。maybeAbsent が 3 つとも「型に逆らうための道具」だと読めるため、
payments についてだけは型が既に省略可能であることに気付かず、コメントが言うとおりの
型であると信じて別の箇所で同じ仮定を置く。

直す方向

payments を他の 2 つと分けて書く。id と lines は型の上で常に在るが、壊れた応答に
備えてあえて不在として読んでいること、payments は型の上で既に省略可能であることを、
それぞれ述べる。maybeAbsent が型に逆らう道具である説明は id と lines にだけ掛ける。

直さずに残した理由

見つけたのは fix/stale-version-references で、版を名指しした記述を現在の解決版に
合わせる作業の最中である。そのブランチは normalize.ts を触っておらず、触ると変更の
範囲が広がる。またこのコメントは版を名指ししていないので、そのブランチが直す対象の
条件にも当たらない。

確かめ方

$ grep -nE '^ {4}(id|lines|payments)(\?)?:' \
    node_modules/.pnpm/stripe@22.6.2_*/node_modules/stripe/esm/resources/Invoices.d.ts

Stripe.Invoice の宣言にある 3 つが出る。payments にだけ ? が付く。

Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1d 12h
Merged PRs (30d)
20

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from traPtitech/Checkin

All issues in traPtitech/Checkin

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.