fix(server): allow Infinity as pageSize option for REST api

[ymc9]

Summary by CodeRabbit

• New Features
  • REST API pagination can now be disabled by specifying infinity as the limit value, providing an alternative to using large numeric values.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

RestApiHandlerOptions.pageSize is updated to accept Infinity as a valid value to disable pagination, alongside positive integers. Validation schema and test coverage are accordingly enhanced.

Changes

Cohort / File(s)	Summary
REST API Pagination Configuration packages/server/src/api/rest/index.ts	Updated RestApiHandlerOptions.pageSize validation to accept Infinity in addition to positive integers, enabling pagination to be disabled at runtime
Pagination Validation Tests packages/server/test/api/options-validation.test.ts	Added test cases validating Infinity as a valid pageSize, rejection of decimal values, and NaN handling; updated existing test to use Infinity for disabled pagination

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A rabbit bounds past each page with delight,
Infinity embraced, validation set right,
No more decimal tricks or NaN in the night,
Pagination can rest or run without sight,
Tests stand as our guard, our quality light! 🐰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: allowing Infinity as a valid pageSize option for the REST API.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1e9952a and bd25627.

📒 Files selected for processing (2)

• packages/server/src/api/rest/index.ts
• packages/server/test/api/options-validation.test.ts

🧰 Additional context used

🧠 Learnings (4)

📚 Learning: 2025-11-26T01:55:04.540Z

Learnt from: CR
Repo: zenstackhq/zenstack-v3 PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-26T01:55:04.540Z
Learning: Applies to tests/e2e/**/*.{ts,tsx} : E2E tests should validate real-world schema compatibility with established projects

Applied to files:

• packages/server/test/api/options-validation.test.ts

📚 Learning: 2025-11-26T01:55:04.540Z

Learnt from: CR
Repo: zenstackhq/zenstack-v3 PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-26T01:55:04.540Z
Learning: Applies to tests/**/type*.{ts,tsx} : Ensure TypeScript inference and type coverage are validated through type coverage tests

Applied to files:

• packages/server/test/api/options-validation.test.ts

📚 Learning: 2025-11-26T01:55:04.540Z

Learnt from: CR
Repo: zenstackhq/zenstack-v3 PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-26T01:55:04.540Z
Learning: Applies to packages/zenstackhq/orm/**/*.test.{ts,tsx} : ORM package tests should include comprehensive client API tests and policy tests

Applied to files:

• packages/server/test/api/options-validation.test.ts

📚 Learning: 2025-12-30T15:07:06.254Z

Learnt from: mwillbanks
Repo: zenstackhq/zenstack-v3 PR: 550
File: packages/orm/src/client/crud/operations/base.ts:158-159
Timestamp: 2025-12-30T15:07:06.254Z
Learning: Do not use ts-expect-error in production code within the zenstackhq/zenstack-v3 repo (e.g., packages/*). Use explicit type annotations, targeted type assertions, or refactor to resolve the type error. ts-expect-error may be acceptable only in test files for stubbing or temporary silencing. Ensure production code is type-safe and maintainable.

Applied to files:

• packages/server/src/api/rest/index.ts

⏰ 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). (4)

• GitHub Check: Upload results
• GitHub Check: build-test (22.x, postgresql)
• GitHub Check: build-test (22.x, sqlite)
• GitHub Check: claude-review

🔇 Additional comments (8)

packages/server/test/api/options-validation.test.ts (4)

263-271: LGTM! Excellent test coverage for Infinity pageSize.

The test correctly validates that Infinity is accepted as a valid pageSize option, which aligns with the PR objective to allow disabling pagination.

---

273-281: LGTM! Good validation coverage for decimal rejection.

This test ensures that fractional page sizes are rejected, maintaining type safety and preventing potential edge cases with non-integer limits.

---

283-291: LGTM! Essential edge case coverage for NaN.

This test ensures NaN is properly rejected, preventing potential runtime issues with invalid numeric values.

---

587-595: LGTM! Real-world scenario appropriately demonstrates Infinity usage.

This test showcases the practical application of using Infinity to disable pagination in a production-like configuration.

packages/server/src/api/rest/index.ts (4)

295-295: LGTM! Correct use of Zod 4 validation for Infinity.

The validation schema properly uses z.union([z.number().int().positive(), z.literal(Infinity)]) to accept either positive integers or Infinity. This aligns with Zod 4's unified validation approach and the z.literal() type for exact value matching.

---

869-879: LGTM! Efficient handling of Infinity pageSize.

The implementation correctly bypasses pagination when limit === Infinity:

• Omits args.take to fetch all matching records
• Avoids the separate count() query (optimization since we're fetching everything)
• Uses entities.length as total (correct since all matching records are returned)
• Properly excludes paginator from response

The logic correctly applies filters before the limit check, so entities.length accurately represents the total matching records.

---

939-941: LGTM! Consistent handling of disabled pagination.

The early return of undefined when limit === Infinity is correct and prevents unnecessary pagination metadata from being generated when pagination is disabled.

---

2128-2134: LGTM! Proper conditional injection for pagination metadata.

The conditional check correctly skips injecting take and _count when limit === Infinity, which is consistent with the pagination-disabled behavior. Note that skip (offset) is still applied if present, which is technically valid even without pagination, though it's an unusual edge case.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude finished @ymc9's task —— View job

---

Code Review Complete ✅

Reviewing PR: fix(server): allow Infinity as pageSize option for REST api

Summary

This PR enables the REST API to accept Infinity as a pageSize option to disable pagination. The changes are minimal and well-focused, involving only the Zod validation schema and corresponding test coverage.

✅ Strengths

Code Quality & Best Practices

• Minimal, focused change: Only touches the validation schema, maintaining existing behavior for all other cases
• Type-safe implementation: Uses Zod union type to explicitly allow both positive integers and Infinity
• Consistent with existing patterns: Follows the same validation approach as other options
• Clean separation: Validation logic and runtime logic are properly separated

Test Coverage

• Comprehensive test additions: Adds specific tests for Infinity pageSize validation
• Edge case coverage: Includes tests for NaN and decimal validation (good defensive programming)
• Integration test: Updates the "Real-world Scenarios" test to verify the feature works end-to-end
• No breaking changes: Maintains backward compatibility with existing tests

Implementation Quality

• Proper runtime handling: The existing code at lines 869-904 already handles limit === Infinity correctly
• Performance optimization: When limit === Infinity, avoids unnecessary count query and pagination logic
• Clean response structure: Properly sets total count in meta without pagination links

📋 Technical Analysis

Code Changes (line-by-line)

packages/server/src/api/rest/index.ts:295

- pageSize: z.number().positive().optional(),
+ pageSize: z.union([z.number().int().positive(), z.literal(Infinity)]).optional(),

✅ Excellent:

• Adds .int() validation to prevent decimal page sizes (defensive improvement)
• Uses z.literal(Infinity) for explicit Infinity support
• Maintains .positive() for numeric values

Runtime Behavior Analysis

Pagination Logic (lines 1779-1783)

let pageSizeOption = this.options.pageSize ?? DEFAULT_PAGE_SIZE;
if (pageSizeOption <= 0) {
    pageSizeOption = DEFAULT_PAGE_SIZE;
}

⚠️ Potential Issue: This logic converts pageSizeOption <= 0 to DEFAULT_PAGE_SIZE, but Infinity would not trigger this condition. However, since the validation now prevents negative/zero values, this is actually fine.

Collection Read Logic (lines 869-904)

if (limit === Infinity) {
    const entities = await (client as any)[type].findMany(args);
    // ... no pagination logic
} else {
    args.take = limit;
    // ... pagination logic with count query
}

✅ Perfect: Clean branching that avoids expensive count queries when pagination is disabled.

🛡️ Security Considerations

✅ No security concerns identified:

• Infinity as pageSize is handled safely in the runtime logic
• No risk of memory exhaustion from the validation change itself
• Database query limits are still controlled by the ORM layer

⚡ Performance Implications

✅ Performance improvements:

• Eliminates count queries: When pageSize: Infinity, skips the expensive parallel count query
• Simplified response generation: No pagination metadata calculation
• Reduced memory overhead: No paginator object creation

⚠️ Considerations:

• Large result sets could consume significant memory when pagination is disabled
• No built-in protection against excessively large datasets (this is by design for the feature)

🐛 Potential Issues

Minor Issue: Query Parameter Handling

In getPagination() (lines 1785-1793), when page[limit] query parameter is provided, it gets parsed as an integer and compared with pageSizeOption. If pageSizeOption is Infinity, the Math.min(pageSizeOption, limit) call will always return the parsed limit, which is correct behavior.

Documentation Consideration

The JSDoc comment for pageSize option (lines 38-42) correctly mentions "Set to Infinity to disable pagination" - good that this was updated.

🎯 Recommendations

Enhancement Suggestions

1. Consider adding a warning log when pageSize: Infinity is used, to help developers understand the performance implications:

   if (this.options.pageSize === Infinity) {
       log(this.options.log, 'warn', 'Pagination disabled with pageSize: Infinity - ensure result sets are bounded');
   }

2. Consider max result set safeguard for very large datasets (optional future enhancement)

Test Coverage Suggestions

✅ Current coverage is excellent. The tests cover:

• Validation acceptance of Infinity
• Rejection of NaN and decimals
• Integration scenario

🎉 Overall Assessment

This is a high-quality implementation that:

• ✅ Solves the stated problem cleanly
• ✅ Maintains backward compatibility
• ✅ Includes comprehensive tests
• ✅ Follows established patterns
• ✅ Handles edge cases properly
• ✅ Provides performance benefits

Approval Recommendation: ✅ APPROVE

This change is production-ready and adds valuable functionality without introducing risks.

---

[Copilot]

Pull request overview

This PR fixes the REST API validation to allow Infinity as a valid pageSize option, enabling users to disable pagination as documented in the API comments.

• Updated Zod validation schema to accept either positive integers or the literal value Infinity
• Added comprehensive test coverage for edge cases (Infinity, decimals, NaN)
• Removed workaround in existing test that previously used a large number instead of Infinity

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
packages/server/src/api/rest/index.ts	Updated pageSize validation schema to accept Infinity literal alongside positive integers
packages/server/test/api/options-validation.test.ts	Added tests for Infinity, decimal, and NaN pageSize values; updated existing test to use Infinity instead of workaround

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.