doc: custom procedures #548
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Rate limit exceeded@ymc9 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 31 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 (3)
WalkthroughAdds documentation and docs navigation updates for ZenStack custom procedures, introduces $procs REST/RPC endpoints and examples, extends TanStack Query docs for procedures, and updates ZModel syntax highlighting to recognize Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client SDK / Browser
participant API as API Handler (REST/RPC)
participant ORM as ZenStack ORM Client
participant Proc as Custom Procedure Impl
participant DB as Database
Client->>API: GET/POST /[$procs]/[name] with args
API->>ORM: call ORM.$procs.[name](args)
ORM->>Proc: invoke procedure implementation (context: client, args)
Proc->>DB: read/write data
DB-->>Proc: return data
Proc-->>ORM: return result
ORM-->>API: return result or throw ORMError
API-->>Client: HTTP 200 / 400 / 500 + payload
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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: 3
🤖 Fix all issues with AI agents
In @docs/modeling/custom-proc.md:
- Around line 31-37: The indented list is being parsed as an indented code
block; remove the extra leading indentation so the bullet list is a normal
markdown list (e.g., start each line with "-" at column 0: "- Primitive types
like `Int`, `String`", "- Models", "- Enums", "- Custom types", "- Array of the
types above") and ensure there are no leading tabs or spaces before the bullets;
do not wrap this section in a fenced code block.
In @docs/orm/custom-proc.md:
- Around line 71-72: The markdown uses indented code-style for the `client` and
`args` lines which violates MD046; replace the indented/code-like lines with a
fenced code block (triple backticks) containing the two lines `client`: an
instance of `ZenStackClient` used to invoke the procedure. and `args`: an object
that contains the procedure arguments. so the snippet uses fenced code blocks
consistently with the rest of the document.
In @docs/service/api-handler/rest.md:
- Around line 842-881: Fix the minor grammar by hyphenating the compound
adjective: change the phrase "URL encoded object" in the $procs GET description
to "URL-encoded object" (the sentence describing GET
/$procs/:procName?args=<encoded arguments> that references the args query
parameter), leaving the rest of the GET/POST and examples intact.
🧹 Nitpick comments (1)
docs/service/client-sdk/tanstack-query/index.md (1)
524-529: Add a minimal$procsusage snippet (query + mutation) to make this actionable.
Right now it’s conceptual; a tiny example with the exact generated hook names (and whether config overrides apply) would prevent misreads.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
docs/orm/plugins/_category_.ymlis excluded by!**/*.yml
📒 Files selected for processing (9)
docs/modeling/custom-proc.mddocs/modeling/plugin.mddocs/orm/custom-proc.mddocs/orm/logging.mddocs/recipe/plugin-dev.mddocs/service/api-handler/rest.mddocs/service/api-handler/rpc.mddocs/service/client-sdk/tanstack-query/index.mdsrc/lib/prism-zmodel.js
🧰 Additional context used
🪛 LanguageTool
docs/service/api-handler/rest.md
[grammar] ~846-~846: Use a hyphen to join words.
Context: ...ocedures and pass the arguments as a URL encoded object in the args query param...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/orm/custom-proc.md
71-71: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/modeling/custom-proc.md
33-33: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (11)
docs/recipe/plugin-dev.md (1)
1-4: Sidebar position change looks fine.
No content changes; just ensure the new position doesn’t conflict with adjacent pages in the sidebar ordering.docs/modeling/plugin.md (1)
1-4: Sidebar position change looks fine.
No content changes; just confirm ordering is consistent across the “Modeling” section.docs/orm/logging.md (1)
1-4: Sidebar position change looks fine.
No doc content changes.src/lib/prism-zmodel.js (1)
3-5: No action needed. The documentation has already fully migrated to using theprocedureandmutation procedurekeywords; noprockeyword usage was found in any code examples or snippets. The removal ofprocfrom the keyword regex aligns with the current state of the codebase.docs/service/api-handler/rpc.md (1)
184-195: Custom procedure endpoints are well-documented.The new endpoints follow the established documentation pattern and clearly differentiate between query (GET) and mutation (POST) procedures. The inline examples are helpful for users understanding the URL patterns.
docs/modeling/custom-proc.md (1)
1-42: New modeling documentation is comprehensive and well-structured.The page effectively introduces custom procedures at the modeling layer, covers syntax, supported types, and references implementation details in the ORM documentation. The PreviewFeature indicator is appropriately included. Content aligns well with the ecosystem (references to ORM, RPC/REST APIs, and Client SDKs).
docs/service/api-handler/rest.md (2)
53-53: Clarified externalIdMapping documentation.The updated wording "to the model's unique field name" is more precise than the original phrasing.
101-104: Example schema properly includes custom procedures.The added custom procedure declarations align with the modeling documentation and provide concrete context for the API examples that follow.
docs/orm/custom-proc.md (3)
1-10: Comprehensive and well-structured documentation.The page provides clear, practical guidance on implementing and using custom procedures at the ORM layer, with good progression from ZModel definitions through TypeScript implementation to calling and error handling. The examples are concrete and illustrative.
36-67: Strong implementation examples.The TypeScript examples effectively demonstrate:
- Wiring procedures in
ZenStackClientconfiguration- Accessing
clientandargsfrom the context object- Practical nested entity creation pattern (user with workspace and memberships)
- Clear mapping between procedure arguments and database operations
76-88: Clear calling conventions.The examples properly illustrate:
- Access via
$procsnamespace- Required
argswrapper object structure- Return value handling
- Realistic parameter passing patterns
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the new custom procedures feature in ZenStack. Custom procedures allow developers to define reusable, type-safe database operations in ZModel and implement them in TypeScript, accessible via the ORM client, REST/RPC APIs, and client SDKs.
Key changes:
- Added syntax highlighting support for
procedureandmutationkeywords in ZModel - Created comprehensive documentation for defining and using custom procedures
- Added API endpoint documentation for invoking custom procedures via REST and RPC
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| src/lib/prism-zmodel.js | Updated syntax highlighter to recognize procedure and mutation keywords, replacing deprecated proc keyword |
| docs/modeling/custom-proc.md | New documentation explaining how to define custom procedures in ZModel, including syntax, parameter types, and return types |
| docs/orm/custom-proc.md | New documentation covering implementation and invocation of custom procedures at the ORM level |
| docs/service/api-handler/rest.md | Added endpoint documentation and examples for calling custom procedures via RESTful API; also clarified externalIdMapping description |
| docs/service/api-handler/rpc.md | Added endpoint documentation for invoking custom procedures via RPC-style API |
| docs/service/client-sdk/tanstack-query/index.md | Added section explaining how custom procedures are accessed via TanStack Query client SDK |
| docs/modeling/plugin.md | Updated sidebar position from 12 to 13 |
| docs/recipe/plugin-dev.md | Updated sidebar position from 5 to 6 |
| docs/orm/plugins/category.yml | Updated sidebar position from 13 to 14 |
| docs/orm/logging.md | Updated sidebar position from 14 to 15 |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
@copilot , help me add "" component to modeling/custom-proc and "ORM/custom-procs". Version number should be 3.2.0. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @docs/modeling/custom-proc.md:
- Around line 34-42: The bullet list under the "You can use all types supported
by ZModel..." section is currently formatted as a fenced code block due to
leading indentation; remove the leading four-space indentation from the list
items (the lines starting with "- Primitive types like `Int`, `String`" through
"- Array of the types above") so they become normal Markdown list bullets, keep
inline code ticks for types, ensure the subsequent sentence about optional
parameter types and using `Void` remains at normal paragraph indentation.
In @docs/orm/custom-proc.md:
- Around line 72-77: The three lines describing the implementation callback
context are formatted as indented code blocks; change them to a proper Markdown
bulleted list so the fields render as list items (e.g., convert the indented
lines that mention `client`: an instance of `ZenStackClient` and `args`: an
object that contains the procedure arguments, and the surrounding explanatory
sentence about runtime validation by ZenStack into normal list items) ensuring
the backticks remain for code spans but the leading spaces are removed so they
render as Markdown bullets.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json,!**/*.json
📒 Files selected for processing (2)
docs/modeling/custom-proc.mddocs/orm/custom-proc.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/orm/custom-proc.md
36-36: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
docs/modeling/custom-proc.md
36-36: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (1)
docs/modeling/custom-proc.md (1)
34-42:
|
@copilot in the modeling/custom-proc doc, please add anchor "#custom-procedures" to the link to the tanstack query doc. |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @docs/modeling/custom-proc.md:
- Around line 36-40: The markdown list uses indented lines without bullet
markers (e.g., "Primitive types like `Int`, `String`", "Models", "Enums",
"Custom types", "Array of the types above"); update these lines to use explicit
markdown bullet syntax (prepend each line with "-" or "*") so the list becomes a
proper bulleted list and resolves markdownlint MD046 warnings.
📜 Review details
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/modeling/custom-proc.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/modeling/custom-proc.md
36-36: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (3)
docs/modeling/custom-proc.md (3)
1-18: AvailableSince component correctly added. ✓The
<AvailableSince version="v3.2.0" />component at line 14 is properly imported and used, fulfilling the PR objective to add version information. The document structure with PreviewFeature and ZModelVsPSL components follows the expected documentation pattern.
24-32: Code examples are properly formatted and illustrative. ✓Both procedure examples use correct ZModel syntax and are clearly presented with appropriate language identifiers and titles.
44-46: Cross-references and anchor links are correctly placed. ✓The documentation includes comprehensive links to related content (ORM implementation, RPC/REST APIs, and TanStack Query integration) with the required
#custom-proceduresanchor for the TanStack Query reference. All referenced files exist and anchors resolve correctly.
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Summary by CodeRabbit
Documentation
Style
✏️ Tip: You can customize this high-level summary in your review settings.