State parameter type design: String vs union type for API query parameters

[SeanTAllen]

Several GitHub API endpoints accept a state query parameter that filters results by their status. The library currently passes these as plain String values. This discussion explores whether introducing a union type (or similar mechanism) would be worthwhile.

Where state-like parameters appear

Currently implemented

Operation	Parameter	Valid values
GetRepositoryIssues	state	"open", "closed", "all"

Not yet implemented but will need this

Endpoint	Parameter	Valid values
GET /repos/{owner}/{repo}/pulls (list PRs)	state	"open", "closed", "all"
GET /repos/{owner}/{repo}/milestones (list milestones)	state	"open", "closed", "all"
GET /repos/{owner}/{repo}/issues	sort	"created", "updated", "comments"
GET /repos/{owner}/{repo}/issues	direction	"asc", "desc"
GET /repos/{owner}/{repo}/pulls	sort	"created", "updated", "popularity", "long-running"
GET /repos/{owner}/{repo}/pulls	direction	"asc", "desc"

Response fields

The Issue model already stores state as (String | None) in the response. If we introduce a type for query params, should response fields use it too?

Options

1. Keep as String (current approach)

Pros:

• Simple, no new types
• Matches the raw API surface
• GitHub silently defaults invalid values (e.g., invalid state defaults to "open")

Cons:

• No compile-time protection against typos ("opne" compiles fine)
• Every endpoint that adds a state param repeats the same stringly-typed pattern

2. Union type per parameter kind

primitive Open
primitive Closed
primitive All
type IssueState is (Open | Closed | All)

Pros:

• Compile-time safety
• Self-documenting API

Cons:

• Open/Closed/All are very generic names; risk of collision with user code or future stdlib additions
• Need a way to convert to string for URL construction
• Different endpoints have different valid values for similar concepts (issues have "all", but sort values differ between issues and PRs)

3. Namespaced primitives

primitive StateOpen
primitive StateClosed
primitive StateAll
type IssueState is (StateOpen | StateClosed | StateAll)

Pros:

• Avoids name collision
• Still compile-time safe

Cons:

• Verbose
• Proliferates types

4. String with validation at construction boundary

Keep String as the parameter type but validate in apply() and return a RequestError for invalid values.

Pros:

• No new types
• Still catches errors, just at runtime rather than compile time

Cons:

• Runtime rather than compile-time safety
• Adds validation code to every endpoint

Questions

1. Is the compile-time safety worth the type proliferation?
2. Should sort and direction parameters follow the same pattern, or is this only for state?
3. Should response fields (Issue.state) use the same type as query parameters?

[SeanTAllen]

PR #85 implemented sort and direction as union types for GetRepositoryIssues using the namespaced primitives approach (option 3): SortCreated/SortUpdated/SortComments for IssueSort, and SortAscending/SortDescending for SortDirection.

The state typing question, PR-specific sort values, and whether response fields should use the same types remain open.