feat(params): typed enums across parameters; native $ref resolution#41
Open
MrRefactoring wants to merge 5 commits into
Open
feat(params): typed enums across parameters; native $ref resolution#41MrRefactoring wants to merge 5 commits into
MrRefactoring wants to merge 5 commits into
Conversation
…lution
Regenerated from a sweep of fixes in the upstream apis-code-gen plus
trello-specific transforms that widen schemas for backward compatibility.
Codegen fixes (apis-code-gen):
- createProperty now resolves $ref at the top → emits Type.reference (so
parameter $refs and body-property $refs become typed schema references
instead of falling through to z.unknown).
- createSchema handles top-level oneOf → emits z.union([...]) instead of an
empty object. The Trello-specific workaround that flattened
posStringOrNumber to z.number() is gone.
- createParameterModel filters extends to only in:'extends' params, so a
ref-typed property like id doesn't accidentally become an extends base
(which would crash with .extend(TrelloIDSchema.shape) on a primitive).
- mergePathParameters added to the Trello transform pipeline so path-level
shared params participate in normal generation.
Resulting parameter changes:
- Path-level {id} params: 200+ files now use TrelloIDSchema (z.string()).
- Field-style CSV query params (Action/Attachment/Board/Card/Notification/
Organization/Token): 4-branch union (string | string[] | enum | enum[]).
- Single-value $ref enums (Color, ViewFilter, *Field path params): 2-branch
union (string | enum) for backward compat + autocomplete.
- Inline JSDoc enums ("One of: a, b, c" / "Valid values: a, b, c"): same
2-branch shape applied to plain string params.
- Positioning params (pos): z.union([string, number, enum(['top','bottom'])])
— loose string preserved for backward compatibility.
- POST /checklists.name JSDoc now documents the server-side default
(**Defaults**: Checklist), verified empirically against the live API.
Build clean, lint clean, 71/71 tests pass.
The swagger declared Card.labels as array<TrelloID>, but the live API returns full Label objects. The codegen's previous z.array(z.unknown()) was loose enough to accept this; with the $ref now resolved natively, the strict schema rejected real responses. Patched in fixMismatchedSchemas (apis-code-gen/packages/trello) to override Card.labels.items to $ref Label. Live tests now: 223 passed, 78 skipped, 0 failed.
…omFields/tokens; expand members live Adds wire-shape unit tests for API modules with little or no live coverage — each test mocks the client and asserts URL/method/searchParams/body of the sent request. Coverage jumps: statements: 65.38% → 78.39% branches: 88.33% → 95.00% functions: 64.72% → 74.29% lines: 65.29% → 78.23% Per-file gains: src/core 67% → 100%, src/api 64% → 82%. The remaining uncovered surfaces in members.ts (44%) and organizations.ts (50%) are endpoints that need premium/enterprise accounts or session-auth. New unit test files: - tests/unit/core/batchRun.test.ts (7 tests for createBatchRun) - tests/unit/api/batch.test.ts (3 tests for batch.run) - tests/unit/api/customFields.test.ts (8 tests) - tests/unit/api/enterprises.test.ts (21 tests) - tests/unit/api/notifications.test.ts (11 tests) - tests/unit/api/plugins.test.ts (5 tests) - tests/unit/api/tokens.test.ts (8 tests) Members live tests: added individual fetches after listings (board backgrounds, custom emoji, custom stickers). dismissMemberOneTimeMessage documented as session-auth-only and skipped.
…xport
TrelloIDSchema was a one-line `z.string()` alias used everywhere via $ref —
no runtime value beyond ergonomics. Added an apis-code-gen transform
(\`inlineTrelloIDRefs\`) that walks the swagger doc and replaces every
\`{\$ref: '#/components/schemas/TrelloID'}\` with an inline
\`{type: 'string'}\` before the generator runs. As a result every parameter
and model field that was \`TrelloIDSchema\` (or \`TrelloIDSchema.nullish()\`)
is now plain \`z.string()\` — 265 files lose a redundant import.
The TrelloID component is kept in components.schemas so the codegen still
produces \`src/models/trelloID.ts\` for callers that imported \`TrelloIDSchema\`
/ \`TrelloID\` from the public API. The schema description is overwritten
with an \`@deprecated\` notice so IDEs surface the warning at the import
site.
71/71 unit tests pass, 223/223 live tests pass.
Adds a post-process step in apis-code-gen/packages/trello/src/index.ts
that, after generation, attaches an `@deprecated` JSDoc block to the
`export type TrelloID = z.infer<typeof TrelloIDSchema>;` line in
`models/trelloID.ts`. Same message style as the deprecation already
attached to `TrelloIDSchema` via the swagger description — IDE now
flags `import { TrelloID }` use sites too, not just `TrelloIDSchema`.
Local trello-only workaround; the codegen itself still attaches the
schema description to the const only. Lifting that to share descriptions
across const + type alias would be a separate apis-code-gen change.
MrRefactoring
force-pushed
the
chore/enum-field-parameters
branch
from
df1aeed to
c8ed0c0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
apis-code-genthat caused$refin parameter / body positions to fall through toz.unknown().createPropertynow top-level-checks$refand emitsType.reference;createSchemahandles top-leveloneOfand emitsz.union([...])schemas;createParameterModelfiltersextendsto onlyin: 'extends'parameters so primitive-aliased $refs don't crash with.extend(TrelloIDSchema.shape).mergePathParametersadded to the Trello pipeline so path-level params flow into operation-level generation.posStringOrNumbertoz.number()— the model now correctly emitsz.union([z.enum(['top','bottom']), z.number()]).fieldsparams for entities with a documented field enum (Action, Attachment, Board, Card, Notification, Organization, Token): accept either CSV string, array, or the typed enum (single or array).$refenums (Color,ViewFilter, path*Fieldparams):z.union([z.string(), z.enum([...])])— keeps loose-string callers compiling while adding autocomplete.One of: a, b, c/Valid values: a, b, c) on plainstringparams get the same 2-branch shape.pos) typed asz.union([z.string(), z.number(), z.enum(['top','bottom'])])— loose string preserved for backward compat.POST /checklists.nameJSDoc now documents the server-side default**Defaults**: \Checklist`` — verified empirically against the live API.Test plan
pnpm run build— clean.pnpm run lint— clean.pnpm vitest run— 71/71 unit tests pass.id: z.unknown()count insrc/parameters/: was 195, now 0. Remaining 5z.unknown()are nested body fields with no schema in swagger (updateCardCustomFields.idCustomField/idValue,getCardAttachment.fields,getEnterpriseBulkOrganizations.idOrganizations,updateEnterpriseJoinRequests) — out of scope for this PR.POST /checklistswithoutnamereturns a checklist withname: "Checklist"; withname: ''Trello applies the same default.import { createTrelloClient } from 'trello.js'andawait trello.cards.getCard({ id })should now typeidasstring(wasunknown).