Plugin: Restoring metadata example and examples props
#2841
Conversation
RobinTail
added
refactoring
|
Warning Rate limit exceeded@RobinTail has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 22 minutes and 30 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (1)
WalkthroughThis update documents a new patch release addressing compatibility with recent and legacy versions of Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~7 minutes Suggested labels
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
RobinTail
force-pushed
the
restore-metadata-examples
branch
from
e677752 to
1dd0546
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
CHANGELOG.md (1)
11-13: Minor wording correction for clarity
it will only array in v25reads awkwardly; consider rephrasing to something like
it will only support arrays in v25to clearly convey the intended breaking-change note.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
CHANGELOG.md(1 hunks)express-zod-api/src/metadata.ts(2 hunks)express-zod-api/src/zod-plugin.ts(1 hunks)
🧰 Additional context used
🧠 Learnings (4)
📓 Common learnings
Learnt from: RobinTail
PR: RobinTail/express-zod-api#2697
File: CHANGELOG.md:5-5
Timestamp: 2025-06-02T21:11:20.768Z
Learning: In the express-zod-api repository, RobinTail follows a release workflow where package.json version is only updated on the master branch after merging all planned release changes. Changelog entries may show future version numbers while package.json remains at the previous version during feature development, and this is intentional workflow, not a version inconsistency that needs to be flagged.
Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: example/factories.ts:35-42
Timestamp: 2025-05-27T20:03:34.213Z
Learning: The `./example` directory in the express-zod-api repository contains demonstration code for educational purposes only, not intended for production use. Example code can make simplified assumptions for brevity and clarity, and should not be flagged for missing production-level error handling, security measures, or edge case handling.
Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.
Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The `_zod` property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.
Learnt from: RobinTail
PR: RobinTail/express-zod-api#2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using `delete` to mutate `ctx.jsonSchema` is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with `undefined` values, especially for snapshot testing.
express-zod-api/src/metadata.ts (13)
Learnt from: RobinTail
PR: #2546
File: example/factories.ts:35-42
Timestamp: 2025-05-27T20:03:34.213Z
Learning: The ./example directory in the express-zod-api repository contains demonstration code for educational purposes only, not intended for production use. Example code can make simplified assumptions for brevity and clarity, and should not be flagged for missing production-level error handling, security measures, or edge case handling.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/io-schema.ts:5-8
Timestamp: 2025-05-28T05:04:40.327Z
Learning: The Base type object & { [Symbol.iterator]?: never } in express-zod-api correctly excludes arrays and other iterables from IOSchema. Arrays are properly rejected because they have a defined Symbol.iterator method which conflicts with the never constraint, as demonstrated by TypeScript compiler errors when attempting to assign z.array() to IOSchema.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:75-87
Timestamp: 2025-05-27T20:40:19.548Z
Learning: In express-zod-api's flattenIO function in json-schema-helpers.ts, the additionalProperties field is used as a template to generate property schemas for literal property names extracted from propertyNames.const and propertyNames.enum. Converting boolean additionalProperties values to empty objects {} via Object(entry.additionalProperties) is intentional behavior, as the function only needs property schema templates, not the boolean semantics of additionalProperties.
Learnt from: RobinTail
PR: #2736
File: express-zod-api/tsup.config.ts:12-26
Timestamp: 2025-06-14T16:42:52.972Z
Learning: In express-zod-api tsup configurations, the direct mutation of options.supported in the esbuildOptions callback is intentional behavior and should not be flagged as a side effect issue.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using delete to mutate ctx.jsonSchema is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with undefined values, especially for snapshot testing.
Learnt from: RobinTail
PR: #2428
File: express-zod-api/src/index.ts:44-44
Timestamp: 2025-05-28T18:58:10.064Z
Learning: The type-only import import type {} from "qs"; in express-zod-api/src/index.ts is necessary to avoid TS2742 errors for exported functions like attachRouting, makeRequestMock, testEndpoint, and testMiddleware that have types depending on @types/qs. This import provides the reference TypeScript needs to infer portable type names.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/tests/zts.spec.ts:160-162
Timestamp: 2025-05-27T20:22:30.428Z
Learning: In express-zod-api/tests/zts.spec.ts, the Fruits enum intentionally contains both string and numeric members (Apple = "apple", Banana = "banana", Cantaloupe = "cantaloupe", A = 5) and is used with z.enum(Fruits) to test how the system handles mixed enum types. This is by design for testing purposes.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.
Learnt from: RobinTail
PR: #2697
File: CHANGELOG.md:5-5
Timestamp: 2025-06-02T21:08:56.475Z
Learning: The cjs-test directory in the express-zod-api repository is a test workspace and should be excluded when checking for main project version consistency with changelog entries.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The _zod property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.
Learnt from: RobinTail
PR: #2833
File: express-zod-api/src/method.ts:3-3
Timestamp: 2025-07-20T11:09:58.980Z
Learning: In express-zod-api, the SomeMethod type (defined as Lowercase<string>) is intentionally broad to represent raw, unvalidated HTTP methods from requests. The narrower Method type is used after validation with isMethod(). This defensive programming pattern separates raw external input types from validated types, allowing graceful handling of unknown methods.
express-zod-api/src/zod-plugin.ts (10)
Learnt from: RobinTail
PR: #2546
File: example/factories.ts:35-42
Timestamp: 2025-05-27T20:03:34.213Z
Learning: The ./example directory in the express-zod-api repository contains demonstration code for educational purposes only, not intended for production use. Example code can make simplified assumptions for brevity and clarity, and should not be flagged for missing production-level error handling, security measures, or edge case handling.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.
Learnt from: RobinTail
PR: #2736
File: express-zod-api/tsup.config.ts:12-26
Timestamp: 2025-06-14T16:42:52.972Z
Learning: In express-zod-api tsup configurations, the direct mutation of options.supported in the esbuildOptions callback is intentional behavior and should not be flagged as a side effect issue.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The _zod property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using delete to mutate ctx.jsonSchema is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with undefined values, especially for snapshot testing.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:75-87
Timestamp: 2025-05-27T20:40:19.548Z
Learning: In express-zod-api's flattenIO function in json-schema-helpers.ts, the additionalProperties field is used as a template to generate property schemas for literal property names extracted from propertyNames.const and propertyNames.enum. Converting boolean additionalProperties values to empty objects {} via Object(entry.additionalProperties) is intentional behavior, as the function only needs property schema templates, not the boolean semantics of additionalProperties.
Learnt from: RobinTail
PR: #2428
File: express-zod-api/src/index.ts:44-44
Timestamp: 2025-05-28T18:58:10.064Z
Learning: The type-only import import type {} from "qs"; in express-zod-api/src/index.ts is necessary to avoid TS2742 errors for exported functions like attachRouting, makeRequestMock, testEndpoint, and testMiddleware that have types depending on @types/qs. This import provides the reference TypeScript needs to infer portable type names.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/result-handler.ts:154-168
Timestamp: 2025-05-27T21:03:26.944Z
Learning: In JavaScript object literals, spreading undefined or null does not cause runtime errors. { ...undefined } evaluates to {} and { ...meta, examples } where meta is undefined evaluates to { examples: [...] }. The spread operator gracefully ignores undefined and null values.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
CHANGELOG.md (11)
Learnt from: RobinTail
PR: #2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The _zod property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.
Learnt from: RobinTail
PR: #2697
File: CHANGELOG.md:5-5
Timestamp: 2025-06-02T21:11:20.768Z
Learning: In the express-zod-api repository, RobinTail follows a release workflow where package.json version is only updated on the master branch after merging all planned release changes. Changelog entries may show future version numbers while package.json remains at the previous version during feature development, and this is intentional workflow, not a version inconsistency that needs to be flagged.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using delete to mutate ctx.jsonSchema is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with undefined values, especially for snapshot testing.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.
Learnt from: RobinTail
PR: #2736
File: express-zod-api/tsup.config.ts:12-26
Timestamp: 2025-06-14T16:42:52.972Z
Learning: In express-zod-api tsup configurations, the direct mutation of options.supported in the esbuildOptions callback is intentional behavior and should not be flagged as a side effect issue.
Learnt from: RobinTail
PR: #2697
File: CHANGELOG.md:5-5
Timestamp: 2025-06-02T21:08:56.475Z
Learning: The cjs-test directory in the express-zod-api repository is a test workspace and should be excluded when checking for main project version consistency with changelog entries.
Learnt from: RobinTail
PR: #2546
File: example/factories.ts:35-42
Timestamp: 2025-05-27T20:03:34.213Z
Learning: The ./example directory in the express-zod-api repository contains demonstration code for educational purposes only, not intended for production use. Example code can make simplified assumptions for brevity and clarity, and should not be flagged for missing production-level error handling, security measures, or edge case handling.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: Ramda is correctly listed as a dependency in express-zod-api/package.json, so imports of ramda utilities are properly supported.
Learnt from: RobinTail
PR: #2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: Ramda is correctly listed as a dependency in express-zod-api/package.json, so imports of ramda utilities are properly supported.
🧬 Code Graph Analysis (1)
express-zod-api/src/metadata.ts (1)
express-zod-api/src/common-helpers.ts (1)
isObject(138-139)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: build (20.9.0)
- GitHub Check: build (22.0.0)
- GitHub Check: build (20.x)
🔇 Additional comments (5)
express-zod-api/src/zod-plugin.ts (1)
43-47: LGTM! Proper restoration of deprecated metadata properties.The implementation correctly restores the
examplesandexamplemetadata properties with appropriate backward compatibility support. The dual format support forexamples(both array and legacy object format) aligns with the changes inmetadata.tsand addresses the compatibility issues referenced in the commit.The deprecation warnings and planned removal in v25 provide clear migration guidance.
express-zod-api/src/metadata.ts (4)
3-3: LGTM! Necessary import for safe object type checking.The
isObjecthelper import is correctly added to support the new filtering logic for legacy example formats.
19-23: LGTM! Excellent documentation of version compatibility.The updated comments provide clear context about when these metadata properties were available in different Zod versions, including the specific commit reference that matches the PR objectives.
29-32: LGTM! Safe handling of legacy example format.The logic correctly handles the legacy object format where examples contained objects with
valueproperties. The implementation safely filters and extracts values while maintaining type safety with theisObjecthelper and proper'value' in onechecking.The TODO comment appropriately marks this for removal in v25.
34-35: LGTM! Proper deprecation handling for single example fallback.The TODO comment correctly marks the single
exampleproperty fallback for removal in v25, maintaining backward compatibility while documenting the deprecation timeline.
Due to colinhacks/zod@ee5615d
Summary by CodeRabbit
Documentation
Refactor
exampleand enhanceexampleshandling for compatibility, with clear deprecation notes for future versions.