doc: v3 query as a service #500
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds comprehensive v3 documentation: new RPC and REST API handler references (including data-type serialization and error shapes), a Server Adapter concept page with eight framework adapter guides and shared MDX fragments, multiple versioned reference pages and roadmap updates, minor typo/prose fixes across REST docs, and a new git submodule update. No code or public API changes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Client
participant Framework
participant Adapter as ServerAdapter
participant ApiHandler
participant ORM
rect rgba(0,128,128,0.06)
Note over Client,Framework: Incoming HTTP request (REST or RPC)
end
Client->>Framework: HTTP request
Framework->>Adapter: framework-specific request object
Adapter->>ApiHandler: normalized request (path, params, body, user)
alt RPC or REST handling
ApiHandler->>ORM: translate to ORM call(s)
ORM-->>ApiHandler: result (with serialized types)
end
ApiHandler->>Adapter: response payload (with superjson/meta if needed)
Adapter->>Framework: framework-specific response
Framework->>Client: HTTP response
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (8)
✅ Files skipped from review due to trivial changes (8)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (5)
versioned_docs/version-3.x/reference/package.md (1)
1-5: Placeholder page structure is correct.The file is set up appropriately as a placeholder for future package documentation. Consider adding a brief description or TODO comment explaining what will be documented here to guide future contributors.
versioned_docs/version-3.x/service/server-adapter.md (1)
25-27: Empty Example section is a placeholder.The Example section (lines 25–27) is empty. Consider adding representative content or marking it explicitly as a placeholder/TODO for future completion.
versioned_docs/version-3.x/service/api-handler/rpc.md (1)
196-199: Improve readability by varying sentence structure for status codes.The four successive status code explanations (lines 196-199) all begin with "[status] is used", which reduces readability. Consider rephrasing for variety:
- `400` is used for generic invalid requests, e.g., malformed request body. - `403` is used for to indicate the request is denied due to lack of permissions, usually caused by access policy violation. - `404` is used to indicate the requested record is not found. - `422` is used for input validation errors. - `500` is used for other unexpected errors. + `400`: Generic invalid requests (e.g., malformed request body) + `403`: Request denied due to insufficient permissions or access policy violation + `404`: Requested record not found + `422`: Input validation errors + `500`: Other unexpected errorsversioned_docs/version-3.x/service/api-handler/rest.md (2)
654-654: Simplify wordy phrasing: replace "exactly the same" with "identical".Lines 654 and 790 use the verbose phrase "exactly the same":
- Both `PUT` and `PATCH` do partial update and has exactly the same behavior. + Both `PUT` and `PATCH` perform partial updates with identical behavior.And:
- `PUT` and `PATCH` has exactly the same behavior and both relace the existing relationships with the new ones entirely. + `PUT` and `PATCH` have identical behavior and both replace existing relationships entirely.Note: Line 790 also has a typo: "relace" → "replace".
Also applies to: 790-790
945-953: Fix unordered list indentation in error response format.Lines 945-953 have inconsistent indentation. Change from 4 spaces to 2 spaces:
- An array of error objects, each containing the following fields: + An array of error objects, each containing the following fields: - - code: `string`, error code - - status: `number`, HTTP status code - - title: `string`, error title - - detail: `string`, detailed error message - - reason: `string`, extra reason for the error + - code: `string`, error code + - status: `number`, HTTP status code + - title: `string`, error title + - detail: `string`, detailed error message + - reason: `string`, extra reason for the error
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (4)
versioned_docs/version-3.x/reference/plugins/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/reference/server-adapters/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/service/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/service/api-handler/_category_.ymlis excluded by!**/*.yml
📒 Files selected for processing (22)
docs/reference/server-adapters/api-handlers/rest.mdx(2 hunks)versioned_docs/version-3.x/reference/package.md(1 hunks)versioned_docs/version-3.x/reference/plugin-dev.md(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_error-handling.md(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_intro.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_options.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/elysia.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/express.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/fastify.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/hono.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/next.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/nuxt.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/sveltekit.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/tanstack-start.mdx(1 hunks)versioned_docs/version-3.x/roadmap.md(1 hunks)versioned_docs/version-3.x/service/api-handler/_data_type_serialization.md(1 hunks)versioned_docs/version-3.x/service/api-handler/index.md(1 hunks)versioned_docs/version-3.x/service/api-handler/rest.md(1 hunks)versioned_docs/version-3.x/service/api-handler/rpc.md(1 hunks)versioned_docs/version-3.x/service/client-sdk.md(1 hunks)versioned_docs/version-3.x/service/index.md(1 hunks)versioned_docs/version-3.x/service/server-adapter.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/service/api-handler/rest.md
[style] ~51-~51: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...eed to specify the model names that you want to override. If a mapping is provided, onl...
(REP_WANT_TO_VB)
[grammar] ~362-~362: Ensure spelling is correct
Context: ...values can be separated by comma. Items statisfying any of the values will be returned. ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~370-~370: Ensure spelling is correct
Context: ... can carry multiple filters. Only items statisfying all filters will be returned. ```t...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~562-~562: Consider a different adjective to strengthen your wording.
Context: ...?include=author 1. Including a deep relationship ts GET /api/po...
(DEEP_PROFOUND)
[style] ~654-~654: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...andPATCH` do partial update and has exactly the same behavior. :::info Besides plain fields...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
[style] ~790-~790: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...ship ``` :::info PUT and `PATCH` has exactly the same behavior and both relace the existing r...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
[grammar] ~871-~871: Ensure spelling is correct
Context: ... } } ``` You can use this ID value convension in places where an ID is needed, e.g., ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
versioned_docs/version-3.x/service/api-handler/rpc.md
[style] ~197-~197: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sed by access policy violation. - 404 is used to indicate the requested record i...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~198-~198: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... requested record is not found. - 422 is used for input validation errors. - `50...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~199-~199: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ed for input validation errors. - 500 is used for other unexpected errors. ### ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.18.1)
versioned_docs/version-3.x/service/api-handler/rest.md
9-9: Multiple headings with the same content
(MD024, no-duplicate-heading)
109-109: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
386-386: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
598-598: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
706-706: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
949-949: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
950-950: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
951-951: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
952-952: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
953-953: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (16)
versioned_docs/version-3.x/roadmap.md (2)
11-12: Roadmap updates accurately reflect feature completion.The changes correctly mark "Performance benchmark" and "Query-as-a-Service (automatic CRUD API)" as complete, which aligns with the comprehensive documentation introduced in this PR covering API handlers, server adapters, and integration guides.
14-15: New roadmap items properly added."Zod utility" and "Custom functions" are appropriately added as not-yet-started items, maintaining logical ordering and clarity around future work.
versioned_docs/version-3.x/service/client-sdk.md (1)
1-7: Well-formed placeholder documentation.The file is properly structured with correct YAML front matter and clear work-in-progress signaling via the 🚧 emoji. The "Coming soon." message sets appropriate expectations for readers.
versioned_docs/version-3.x/reference/plugin-dev.md (1)
1-3: Sidebar reordering looks good.The sidebar position adjustment is appropriate given the new documentation pages added in this PR.
docs/reference/server-adapters/api-handlers/rest.mdx (1)
104-115: Typo corrections are accurate.The three spelling corrections ("contraint"→"constraint", "Currentlly"→"Currently", and related corrections) improve clarity in important option descriptions. The REST API handler reference documentation is comprehensive and well-structured.
versioned_docs/version-3.x/reference/server-adapters/_options.mdx (1)
1-11: Reusable component is well-structured.The adapter options are clearly documented and the use of props for rendering enables effective reuse across framework-specific adapter pages.
versioned_docs/version-3.x/reference/server-adapters/_error-handling.md (1)
1-3: Error handling reference structure is appropriate.The reusable component correctly directs readers to framework-agnostic error handling documentation. Verify that the anchor links (
#http-status-code-and-error-responsesand#error-handling) exist in the referenced RPC and REST API handler documentation pages.versioned_docs/version-3.x/service/api-handler/_data_type_serialization.md (1)
1-16: Data type serialization reference is clear and complete.The documentation accurately lists serialization formats for special data types. The standards chosen (ISO 8601 for DateTime, Base64 for Bytes, etc.) are appropriate and widely recognized.
versioned_docs/version-3.x/reference/server-adapters/_intro.mdx (1)
1-1: Reusable intro component is well-designed.The prop-based component enables effective content reuse across the eight framework-specific server adapter pages while maintaining clarity about the value proposition (secure data backend with access policies).
versioned_docs/version-3.x/reference/server-adapters/hono.mdx (1)
18-18: Verify package version consistency across adapter docs.Line 18 specifies
@zenstackhq/server@next, while other adapters (SvelteKit, Nuxt, Next.js) use@zenstackhq/server. Please confirm whether this version difference is intentional or should be aligned for consistency.versioned_docs/version-3.x/reference/server-adapters/next.mdx (1)
1-110: Well-structured adapter documentation with good coverage of both router patterns.The Next.js adapter documentation is comprehensive, covering both App Router and Pages Router with appropriate examples and the middleware pattern for endpoint access control. The different getClient signatures for each router are properly documented in the AdapterOptions sections.
versioned_docs/version-3.x/reference/server-adapters/nuxt.mdx (1)
1-43: SolidAdapter documentation with appropriate Nuxt/H3 patterns.The Nuxt adapter documentation correctly uses the Nuxt server event handler pattern and the H3 event type in the getClient signature. The catch-all route pattern with
[...].tsis correct for Nuxt.versioned_docs/version-3.x/reference/server-adapters/express.mdx (2)
18-18: Confirm package version strategy across adapters.Line 18 uses
@zenstackhq/server@next, which is also used in hono.mdx. Other adapters (SvelteKit, Nuxt, Next.js) use@zenstackhq/serverwithout the@nextversion specifier. Please verify whether this is intentional (e.g., these adapters require a pre-release version) or should be standardized.
51-57: Express-specific sendResponse option is well documented.The optional
sendResponseflag and its behavior (including default value) are clearly explained, providing good guidance for advanced use cases where middleware chaining is needed.versioned_docs/version-3.x/reference/server-adapters/fastify.mdx (1)
1-53: Documentation structure and completeness look solid.This adapter documentation follows a clean component-based structure with all essential sections (installation, mounting, options, error handling). The code example clearly demonstrates the integration pattern with authentication context.
versioned_docs/version-3.x/reference/server-adapters/elysia.mdx (1)
1-67: Well-structured documentation with good practices.The documentation follows the same component-based pattern as the Fastify adapter, with appropriate contributor attribution (line 16). The incomplete
getCurrentUserfunction (lines 49-52) correctly indicates this is implementation-specific and must be completed by the developer.
versioned_docs/version-3.x/reference/server-adapters/sveltekit.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-3.x/reference/server-adapters/tanstack-start.mdx
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/reference/server-adapters/api-handlers/rest.mdx (1)
831-840: Typo in the PUT/PATCH info box.Line 839 contains "relace" which should be "replace".
-`PUT` and `PATCH` has exactly the same behavior and both relace the existing relationships with the new ones entirely. +`PUT` and `PATCH` has exactly the same behavior and both replace the existing relationships with the new ones entirely.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs/reference/server-adapters/api-handlers/rest.mdx(4 hunks)versioned_docs/version-1.x/reference/server-adapters/api-handlers/rest.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/sveltekit.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/tanstack-start.mdx(1 hunks)versioned_docs/version-3.x/service/api-handler/index.md(1 hunks)versioned_docs/version-3.x/service/api-handler/rest.md(1 hunks)versioned_docs/version-3.x/service/server-adapter.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- versioned_docs/version-1.x/reference/server-adapters/api-handlers/rest.mdx
🚧 Files skipped from review as they are similar to previous changes (3)
- versioned_docs/version-3.x/service/api-handler/index.md
- versioned_docs/version-3.x/service/server-adapter.md
- versioned_docs/version-3.x/reference/server-adapters/tanstack-start.mdx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/service/api-handler/rest.md
[style] ~49-~49: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...eed to specify the model names that you want to override. If a mapping is provided, onl...
(REP_WANT_TO_VB)
[style] ~560-~560: Consider a different adjective to strengthen your wording.
Context: ...?include=author 1. Including a deep relationship ts GET /api/po...
(DEEP_PROFOUND)
[style] ~652-~652: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...andPATCH` do partial update and has exactly the same behavior. :::info Besides plain fields...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
[style] ~788-~788: ‘exactly the same’ might be wordy. Consider a shorter alternative.
Context: ...ship ``` :::info PUT and `PATCH` has exactly the same behavior and both relace the existing r...
(EN_WORDINESS_PREMIUM_EXACTLY_THE_SAME)
🪛 markdownlint-cli2 (0.18.1)
versioned_docs/version-3.x/service/api-handler/rest.md
107-107: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
384-384: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
596-596: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
704-704: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
947-947: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
948-948: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
949-949: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
950-950: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
951-951: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (4)
docs/reference/server-adapters/api-handlers/rest.mdx (1)
104-120: Typo corrections look good overall.The documentation improvements in lines 104, 115, 411, 419, and 920 correctly address spelling and grammar issues ("constraint", "Currently", "satisfying", "convention"). These changes improve readability without altering API behavior or meaning.
Also applies to: 411-423, 920-924
versioned_docs/version-3.x/reference/server-adapters/sveltekit.mdx (3)
20-38: Grammatical issue from past review has been resolved.The previous comment flagged "creating a SvelteKit server hooks" as grammatically incorrect. Line 22 now correctly reads "creating SvelteKit server hooks like:" with proper plural agreement.
24-38: Code example and mounting pattern look appropriate.The SvelteKit hooks.server.ts example is clear, includes helpful comments, and demonstrates the expected integration pattern with RPCApiHandler, session extraction, and auth setup. The code aligns with typical SvelteKit hook patterns.
7-10: All imported shared components are available and correctly structured.Verification confirms that all four components imported in sveltekit.mdx exist at their expected locations:
PackageInstallresolves toversioned_docs/version-3.x/_components/PackageInstall.tsxErrorHandling,Intro, andAdapterOptionsare present in the same server-adapters directoryThe import pattern is consistent with all other adapter files in the same directory (express, fastify, hono, next, nuxt, elysia, tanstack-start), confirming this is the established convention.
Summary by CodeRabbit
Documentation
Chores