docs: v3 docs structure #479
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds Docusaurus docs version “3.0 Alpha” (3.x), introduces embed/display React components for StackBlitz and GitHub code, and adds extensive new v3.x documentation (ORM, modeling, plugins, reference, utilities, samples/welcome/FAQ), plus helper TSX components used by docs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ 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. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
🔭 Outside diff range comments (5)
versioned_docs/version-3.x/migration/introduction.md (1)
1-7: Placeholder intro needs substanceThis page is the first stop for users looking to migrate, yet it contains only a header. At minimum, outline:
- Target audience & prerequisites
- A high-level overview of the migration path (v2 ➜ v3 breaking changes, tooling updates, timelines)
- Links to subsequent migration chapters
# Introduction + +ZenStack 3.x introduces several breaking changes and new capabilities. +This section helps you **upgrade an existing 2.x project** or **start a green-field 3.x project** safely. + +## What’s covered +* Breaking schema changes +* CLI compatibility matrix +* Step-by-step upgrade checklist + +> Looking for a quick start instead? Head over to the **Getting Started** guide.versioned_docs/version-3.x/orm/zmodel/datasource.md (1)
1-8: Inconsistent naming & stray character; add content outline
- Front-matter uses “Datasource” (one word) while the H1 uses “Data Source” (two words). Pick one to avoid broken anchor links.
- There’s an orphan
8on Line 8 – likely a copy-paste artefact.- Page is otherwise empty; consider at least listing the directive syntax (
datasource <name> { provider = … url = … }).-description: Datasource in ZModel +# description: Datasource in ZModel --- -# Data Source +# Datasource + +<!-- TODO: Explain provider/url, env(), supported databases, examples --> - -8versioned_docs/version-3.x/orm/validation.md (1)
1-9: Validation doc missing narrative and examplesGiven how often users trip over validation rules, an empty page is worse than no page. Either populate with:
- Declarative validators syntax
- Runtime API (
validate()/safeValidate())- Error objects & typical patterns
…or exclude from the published set until ready.
versioned_docs/version-3.x/orm/plugins/introduction.md (1)
1-7: Introduce plugins concept, goals, and hello-world sampleA bare heading does not help users understand why or how to write plugins. At minimum, outline:
• What problems plugins solve
• Lifecycle hooks diagram
• Simple “logger” plugin example
• Link to API referenceHappy to provide a draft if useful.
docusaurus.config.js (1)
38-51: Version entry added without generated sidebars – build may fail
Adding'3.x'here requires:
versioned_docs/version-3.x/(done)versioned_sidebars/version-3.x-sidebars.jsonDocusaurus will crash at build time if the sidebar file is missing. Generate it via
pnpm docs:version 3.xor add a handcrafted JSON.
♻️ Duplicate comments (2)
src/components/StackBlitzGithubEmbed.tsx (1)
1-2: Verify StackBlitz SDK dependency is installed.Same issue as in StackBlitzEmbed - ensure '@stackblitz/sdk' is properly listed as a dependency.
versioned_docs/version-3.x/reference/server-adapters/express.mdx (1)
7-9: Verify imported component file paths exist.Same shared components as Hono adapter - ensure these files exist.
🧹 Nitpick comments (60)
versioned_docs/version-3.x/service/introduction.md (1)
1-3: Avoid releasing docs with placeholder contentThe page is visible in the sidebar yet only contains “Coming soon 🚧”. Either hide it (e.g.
_draft: trueor prefix file/dir name with_) or land a minimal meaningful introduction before publishing.versioned_docs/version-3.x/orm/access-control/introduction.md (1)
1-3: Same placeholder issue as the Service introConsider hiding this doc or adding at least a 1-paragraph overview so readers aren’t met with an empty page.
versioned_docs/version-3.x/reference/server-adapters/_error-handling.md (1)
1-3: Heading level & relative links
- Using
### Error Handlingmakes this an H3 while the page has no H1/H2. Change to# Error Handlingfor hierarchy consistency.- Verify the relative links (
./api-handlers/rpc,./api-handlers/rest) resolve from this file’s location (reference/server-adapters). If the target path is actuallyreference/server-adapters/api-handlers/..., the links are correct; otherwise they’ll 404.versioned_docs/version-3.x/orm/zmodel/models.md (1)
1-8: Populate stub or hideThe front-matter is fine, but the page has no body beyond the H1. Either flesh out a short description of ZModel models (fields, id, relations) or hide until content is ready.
versioned_docs/version-3.x/orm/query-builder.md (1)
1-6: Add at least a skeletal outlineGiven this is linked from the sidebar, readers expect guidance. Suggest adding a brief overview (purpose, key concepts, example snippet) or keep the file hidden until ready.
versioned_docs/version-3.x/reference/server-adapters/api-handlers/_data_type_serialization.md (1)
1-16: Expand content and harmonise formatting for better readabilityThe file currently lists the serialization formats but gives no background, rationale, or concrete examples. Consider:
- Adding a brief preamble explaining why these formats are chosen (e.g. alignment with superjson, cross-language compatibility, precision, etc.).
- Converting the list into a table so readers can scan the information faster.
- Providing at least one concrete request/response JSON snippet for each type.
Example patch:
- - `DateTime` - - ISO 8601 string +| Type | Serialized form | Example | +|-----------|-----------------|---------| +| `DateTime`| ISO-8601 string | `"2025-08-12T10:43:21.123Z"` |Applying the same pattern to the remaining rows keeps the doc self-contained and actionable.
versioned_docs/version-3.x/orm/zmodel/components.md (1)
1-7: Add overview & navigation pointers
components.mdis set as sidebar position 1 but offers no narrative content. Recommend:
- A short paragraph describing what “schema components” means in the context of ZModel.
- A bullet list linking out to the deeper pages (models, datasource, attributes, etc.) so readers understand the structure.
Doing so also prevents an empty page from appearing at the top of the ZModel section.
versioned_docs/version-3.x/orm/zmodel/custom-types.md (1)
1-7: Document usage semantics & sample declarationCustom types are a powerful feature but the page is currently blank. Consider including:
- When to create a custom type vs. using built-ins
- Syntax recap (
type <Name> { ... })- Limitations (e.g., not supported in certain adapters)
- End-to-end example showing definition, model usage, generated TS type
This will turn the placeholder into actionable documentation.
versioned_docs/version-3.x/orm/zmodel/builtin-types.md (1)
1-7: Provide exhaustive list with notes on cross-adapter behaviourReaders expect this page to enumerate every built-in scalar (String, Int, BigInt, DateTime, Bytes, Decimal, Boolean, Json) plus any composite types, each with:
- Prisma equivalence (if any)
- Default value support
- Caveats per database adapter
A table format similar to:
| Type | Prisma scalar | Default allowed | Notes | |------|---------------|-----------------|-------| | String | `String` | ✅ | — |would greatly improve usability.
versioned_docs/version-3.x/utilities/zod.md (1)
5-6: Add integration details or hide the pageReaders will expect examples such as:
import { getZodSchema } from '@zenstackhq/runtime'; const userSchema = getZodSchema(prisma).user;and guidance on server-side validation vs. client-side inference. Add these sections or set
draft: true.versioned_docs/version-3.x/orm/cli.md (1)
5-6: Bare heading only – link or import from reference docGiven you already have a full CLI reference under
reference/cli.md, consider:• Converting this file to an index that links there, or
• Importing that file via MDXimport Doc from '../../reference/cli.md'; <Doc />.Leaving an empty page hurts navigation UX.
versioned_docs/version-3.x/orm/api/create.md (1)
1-6: Documentation skeleton is empty – flesh out before publishingThe file currently contains only front-matter and a heading. Before this ships, please add at least:
• A short intro sentence (what “create” does, link to spec)
• Signature / options table
• Minimum working example
• Common pitfalls / FAQOtherwise the published docs will look broken.
versioned_docs/version-3.x/orm/api/find.md (1)
1-6: Add substantive content to avoid blank “Find” pageSame issue as
create.md: heading without body will surface as an empty page in the sidebar. Consider copying the 2.x content as a starting point or mark the file_draft.mduntil ready.versioned_docs/version-3.x/orm/zmodel/attributes.md (1)
1-7: Add minimum front-matter metadata and placeholder contentThe page is currently an empty stub.
At least add atitlefield in the front-matter (keeps navigation labels consistent) and drop in a short intro paragraph so the page doesn’t look broken when published.--- sidebar_position: 4 description: Attributes in ZModel +title: Attributes --- # Attributes +This page introduces ZModel attributes, explains how they’re declared, +what built-in attributes are available, and how to create custom ones. +See the “ZModel Language Reference” for the full grammar.versioned_docs/version-3.x/orm/api/count.md (1)
1-6: Provide atitleand a one-sentence descriptionSame as the other API stubs – without a
titleand a short paragraph the generated page is almost blank, which hurts discoverability.--- sidebar_position: 5 description: Count API +title: Count --- # Count + +Explain what the `count` operation does, which filters it accepts, +and link to an example.versioned_docs/version-3.x/orm/computed-fields.md (1)
1-8: Fill in basic content & front-matterAdd
titleand a short intro so the page is not empty.description: Computed fields in ZModel +title: Computed Fields @@ # Computed Fields +Describe how to declare computed fields, how recalculation works, +and any limitations (e.g. no circular dependencies).versioned_docs/version-3.x/orm/api/aggregate.md (1)
1-6: Stub needs a title and minimal guidancedescription: Aggregate API +title: Aggregate @@ # Aggregate + +Outline supported aggregate functions (`sum`, `avg`, `min`, `max`, etc.) +and link to query examples.versioned_docs/version-3.x/samples.md (1)
6-9: Replace placeholder sentence with actual linksListing the sample project series (and linking to their repositories) makes the page immediately useful.
-The ZenStack team maintains the following three series of sample projects. +The ZenStack team maintains three sample-project series: + +- **Todo apps** – progressively showcase features from basic CRUD to multi-tenant auth. +- **AI assistants** – demonstrate streaming & function-calling with LangChain. +- **SaaS starter kits** – production-ready boilerplates with Next.js, tRPC, and Stripe. + +Each repo lives under `github.com/zenstackhq/samples` – link directly so readers can +clone and run them.versioned_docs/version-3.x/welcome.md (1)
1-7: Add explicittitleto front-matter for consistencyOther files rely on the
titlekey to drive the sidebar & page title; leaving it implicit may harm search / SEO.--- +title: Welcome to ZenStack V3 description: Welcome to ZenStack slug: /welcome sidebar_label: Welcome sidebar_position: 1 ---versioned_docs/version-3.x/orm/zmodel/reusing-fields.md (1)
1-6: Populate page and align metadataConsider illustrating the
@@includedirective (or whichever mechanism exists in v3) with a concrete example showing how to reusecreatedAt,updatedAt, etc.--- +title: Reusing Common Fields sidebar_position: 8 description: Reusing common fields across models in ZModel ---versioned_docs/version-3.x/faq.md (1)
9-10: Document is an empty stub – add at least one FAQ entry before merging
Shipping an empty page degrades user experience and SEO. If content is not ready, mark the filedraft: trueor keep it on a working branch.versioned_docs/version-3.x/orm/zmodel/multi-file.md (1)
6-10: Content placeholder only – readers get no value
Before publishing v3 docs, provide at least a short paragraph and one code snippet that demonstrates breaking a schema into two files. Otherwise mark as draft.versioned_docs/version-3.x/upgrade.md (1)
9-10: Needs minimal upgrade instructions before release
An empty upgrade guide frustrates users migrating to v3. Provide at least a bullet list of breaking changes or link to a WIP PR before publishing.docusaurus.config.js (1)
38-51:lastVersionstill points tocurrent (2.x)
If v3 is publicly available, consider switchinglastVersion: '3.x'and marking 2.x as LTS to surface the new docs by default.versioned_docs/version-3.x/_components/PackageExec.tsx (2)
9-14: Component/file naming mismatch causes confusion
File isPackageExec.tsxbut exported component isPackageInstall. Either rename the file or the component for discoverability.// Option 1 – rename component -const PackageInstall = ({ command }: Props) => { +const PackageExec = ({ command }: Props) => { -export default PackageInstall; +export default PackageExec;
16-26: Provide a default tab to avoid React key warnings
<Tabs>withoutdefaultValuelogs a warning in strict mode. Add:- <Tabs> + <Tabs defaultValue={pkgManagers[0].name}>src/components/StackBlitzEmbed.tsx (2)
12-21: Consider adding error handling for SDK operations.The useEffect doesn't handle potential errors from the StackBlitz SDK embedding operation. Consider wrapping the SDK call in a try-catch block.
useEffect(() => { if (containerRef.current) { - sdk.embedProjectId(containerRef.current, projectId, { - openFile: 'main.ts', - height, - view: 'editor', - forceEmbedLayout: true, - }); + try { + sdk.embedProjectId(containerRef.current, projectId, { + openFile: 'main.ts', + height, + view: 'editor', + forceEmbedLayout: true, + }); + } catch (error) { + console.error('Failed to embed StackBlitz project:', error); + } } }, [projectId, height]);
15-15: Consider making openFile configurable.The component hardcodes 'main.ts' as the file to open. Consider making this configurable via props for more flexibility.
interface StackBlitzEmbedProps { projectId: string; height?: string; + openFile?: string; } -const StackBlitzEmbed: React.FC<StackBlitzEmbedProps> = ({ projectId, height = '600px' }) => { +const StackBlitzEmbed: React.FC<StackBlitzEmbedProps> = ({ projectId, height = '600px', openFile = 'main.ts' }) => { const containerRef = useRef<HTMLDivElement>(null); useEffect(() => { if (containerRef.current) { sdk.embedProjectId(containerRef.current, projectId, { - openFile: 'main.ts', + openFile, height, view: 'editor', forceEmbedLayout: true, }); } - }, [projectId, height]); + }, [projectId, height, openFile]);src/components/StackBlitzGithubEmbed.tsx (1)
15-15: Consider making openFile configurable.Same suggestion as StackBlitzEmbed - consider making the openFile prop configurable instead of hardcoding 'main.ts'.
versioned_docs/version-3.x/reference/limitations.md (1)
35-36: Consider more concise wording.The phrase "Right now" could be replaced with "Currently" for more professional documentation tone.
-Right now, the focus of this project is SQL databases, and there's no plan to support MongoDB in the near future. +Currently, the focus of this project is SQL databases, and there's no plan to support MongoDB in the near future.versioned_docs/version-3.x/reference/server-adapters/nuxt.mdx (1)
44-45: Missing trailing newline.The file should end with a newline character for consistency with standard formatting practices.
You can find a fully working example [here](https://github.com/zenstackhq/sample-todo-nuxt). +versioned_docs/version-3.x/reference/server-adapters/elysia.mdx (2)
47-50: Improve placeholder code clarity.The ellipsis (
...) could be replaced with a more descriptive comment to better guide users.function getCurrentUser(context: Context) { // the implementation depends on your authentication mechanism - ... + // return user object based on your auth strategy + // e.g., return context.headers.authorization ? parseToken() : null; }
69-70: Missing trailing newline.The file should end with a newline character for consistency.
<ErrorHandling /> +versioned_docs/version-3.x/_components/PackageInstall.tsx (2)
22-26: Consider improving template literal readability.The nested template literal is functional but could be more readable with better formatting or extraction to helper functions.
<TabItem key={pkg.name} value={pkg.name} label={pkg.name}> <CodeBlock language="bash"> - {`${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}${ - dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : '' - }`} + {[ + devDependencies?.length && `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}`, + dependencies?.length && `${pkg.command} ${dependencies.join(' ')}` + ].filter(Boolean).join('\n')} </CodeBlock> </TabItem>
33-34: Missing trailing newline.The file should end with a newline character for consistency.
export default PackageInstall; +versioned_docs/version-3.x/reference/server-adapters/api-handlers/index.mdx (1)
31-32: Missing trailing newline.The file should end with a newline character for consistency with standard formatting practices.
- [RESTful API Handler](./rest) +versioned_docs/version-3.x/orm/database-client.mdx (2)
12-15: Fix two small grammar slips (“initialize” → “initialized”, “shows” → “show”)-The `zen generate` command compiles the ZModel schema into TypeScript code, which we can in turn use to initialize a type-safe database client. ZenStack uses Kysely to handle the low-level database operations, so the client is initialize with a Kysely dialect - an object that encapsulates database details. - -The samples below only shows creating a client using SQLite (via ... +The `zen generate` command compiles the ZModel schema into TypeScript code, which we can in turn use to initialize a type-safe database client. ZenStack uses Kysely to handle the low-level database operations, so the client is **initialized** with a Kysely dialect — an object that encapsulates database details. + +The samples below only **show** creating a client using SQLite (via ...
22-27: Mention the “@/” path alias prerequisiteThe snippet relies on the
@path alias (import { schema } from '@/zenstack/schema';).
Readers who copy-paste this may hit a module-resolution error if they haven’t configuredpathsintsconfig.json.
Consider adding a short note or foot-link pointing to the alias setup instructions.versioned_docs/version-3.x/reference/server-adapters/_using-api.mdx (1)
14-16: Subject/verb agreement (“hooks assumes”)-The generated client hooks assumes the server adapter uses [RPC-style API handler](./api-handlers/rpc) (which is the default setting). +The generated client hooks **assume** the server adapter uses an [RPC-style API handler](./api-handlers/rpc) (which is the default setting).versioned_docs/version-3.x/reference/error-handling.md (2)
13-14: Minor wording tweak – extra “is” after the link-... a `PrismaClientKnownRequestError` is thrown with code [`P2004`](https://www.prisma.io/docs/reference/api-reference/error-reference#p2004) is used in such cases: +... a `PrismaClientKnownRequestError` is thrown with code [`P2004`](https://www.prisma.io/docs/reference/api-reference/error-reference#p2004) in such cases:
23-23: “follow” → “following” (LanguageTool hint)-... providing more information about the error. It contains the follow... +... providing more information about the error. It contains the following...versioned_docs/version-3.x/reference/server-adapters/sveltekit.mdx (2)
24-39: Example is missing theRequestEventimport
RequestEventis referenced in thegetPrismasignature but isn’t imported, which may confuse readers.-import { getSessionUser } from '$lib/auth.ts'; +import { getSessionUser } from '$lib/auth.ts'; +import type { RequestEvent } from '@sveltejs/kit';
17-20: Package install command omits the sub-path hintThe installation block shows
npm install @zenstackhq/server, yet the code uses@zenstackhq/server/sveltekit.
A quick parenthetical note (e.g. “the adapter is exported via a sub-path export”) can prevent confusion.versioned_docs/version-3.x/reference/server-adapters/fastify.mdx (1)
34-39: Comment wording: the plugin mounts CRUD routes, not “serve OpenAPI”The inline comment says “serve OpenAPI at /api/model” but the example config mounts CRUD API routes. Unless the plugin also auto-generates & serves OpenAPI docs at that path, tweak the comment to avoid misleading readers.
versioned_docs/version-3.x/reference/cli.md (2)
11-14: Add a language identifier to satisfy MD040 and enable syntax-highlightingThe fenced block that shows the basic CLI invocation lacks a language tag.
Addingbash(ortext) will silence the markdown-lint warning and improve readability.-``` +```bash zenstack [options] [command] ζ ZenStack is a Prisma power pack for building full-stack apps. ...
154-160: Minor style: convert sentence fragments in the options table to full sentencesThe descriptions for
--debugand--tablestart with a verb but miss a subject, triggering LanguageTool’s MISSING_IT_THERE rule.
Example:“Enable debug output. Can be toggled …”
Consider merging into one sentence:
“Enables debug output, which can be toggled on the fly …”
Purely a wording issue; feel free to ignore if you prefer the current terse style.
versioned_docs/version-3.x/reference/server-adapters/next.mdx (1)
123-124: Consistent naming: use “App router” (singular) everywhereEarlier in the doc the tab label is “App Router”, but the bullet list says “Apps router”.
Recommend singular form for consistency.-- [Apps router](https://github.com/zenstackhq/docs-tutorial-nextjs-app-dir) +- [App router](https://github.com/zenstackhq/docs-tutorial-nextjs-app-dir)versioned_docs/version-3.x/orm/introduction.md (2)
8-10: Tone & wording“learnt from the prior arts” → “learned from prior art” is more standard technical English.
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and aims to provide an awesome developer experience ... +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It has learned from prior art and aims to provide an exceptional developer experience ...
86-87: Grammar: subject–verb agreement“Real-world applications often involves storing …”
Should be “often involve”.
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rpc.mdx (1)
81-85: Minor wording – “Http” → “HTTP”
Use the conventional capitalisation for the acronym.versioned_docs/version-3.x/reference/runtime-api.md (2)
31-35: Grammar nit – drop the extra “to”
The context to for evaluating …→The context for evaluating …
83-90: Consider adding language identifiers to unlabeled fenced blocks
Some code blocks (e.g. within the options table) omit a language tag, triggering MD040 warnings. Addts,json, etc., to keep markdown-lint clean.versioned_docs/version-3.x/reference/zmodel-language.md (1)
211-215: Typo in fenced-block language tag
```prsimashould be```zmodel(orprisma) – typo breaks syntax highlighting.versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx (7)
15-16: Tighten wording in introduction
- “transportation format” ➜ “transport format”
- “can be created as the following” ➜ “can be created as follows”
-The RESTful-style API handler exposes CRUD APIs as RESTful endpoints using [JSON:API](https://jsonapi.org/) as transportation format. The API handler is not meant to be used directly; instead, you should use it together with a [server adapter](../../../category/server-adapters) which handles the request and response API for a specific framework. +The RESTful-style API handler exposes CRUD APIs as RESTful endpoints using [JSON:API](https://jsonapi.org/) as the transport format. The API handler isn’t meant to be used directly; instead, use it with a [server adapter](../../../category/server-adapters) that handles the request/response API for a specific framework.
105-106: Remove duplicate word and clarify sentence-The RESTful API handler conforms to the the [JSON:API](https://jsonapi.org/format/) v1.1 specification for its URL design and input/output format. The following sections list the endpoints and features are implemented. +The RESTful API handler conforms to the [JSON:API](https://jsonapi.org/format/) v1.1 specification for its URL design and I/O format. The following sections list the implemented endpoints and features.
668-669: Reduce wordiness and fix plural agreement-Both `PUT` and `PATCH` do partial update and has exactly the same behavior. +Both `PUT` and `PATCH` perform partial updates and behave the same.
671-673: Grammar tweak – “it only replaces”-Please note that this won't update the related resource; instead if only replaces the relationships. +Note that this doesn’t update the related resource; it only replaces the relationships.
396-404: Spelling: “statisfying” ➜ “satisfying”; plural “comma” ➜ “commas”-Multiple filter values can be separated by comma. Items statisfying any of the values will be returned. +Multiple filter values can be separated by commas. Items satisfying any of the values are returned. ... -Only items statisfying all filters will be returned. +Only items satisfying all filters are returned.
804-804: Typo and wording-`PUT` and `PATCH` has exactly the same behavior and both relace the existing relationships with the new ones entirely. +`PUT` and `PATCH` behave the same and completely replace existing relationships with the new ones.
885-885: Spelling: “convension” ➜ “convention”-You can use this ID value convension in places where an ID is needed +You can use this ID value convention wherever an ID is required
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (15)
package.jsonis excluded by!**/*.jsonpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml,!**/*.yamlversioned_docs/version-3.x/migration/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/access-control/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/api/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/plugins/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/zmodel/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/recipes/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/reference/_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/utilities/_category_.ymlis excluded by!**/*.ymlversioned_sidebars/version-3.x-sidebars.jsonis excluded by!**/*.jsonversions.jsonis excluded by!**/*.json
📒 Files selected for processing (60)
docusaurus.config.js(1 hunks)src/components/StackBlitzEmbed.tsx(1 hunks)src/components/StackBlitzGithubEmbed.tsx(1 hunks)versioned_docs/version-3.x/_components/PackageExec.tsx(1 hunks)versioned_docs/version-3.x/_components/PackageInstall.tsx(1 hunks)versioned_docs/version-3.x/_components/_zmodel-starter.md(1 hunks)versioned_docs/version-3.x/faq.md(1 hunks)versioned_docs/version-3.x/migration/introduction.md(1 hunks)versioned_docs/version-3.x/orm/access-control/introduction.md(1 hunks)versioned_docs/version-3.x/orm/api/aggregate.md(1 hunks)versioned_docs/version-3.x/orm/api/count.md(1 hunks)versioned_docs/version-3.x/orm/api/create.md(1 hunks)versioned_docs/version-3.x/orm/api/delete.md(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)versioned_docs/version-3.x/orm/api/transaction.md(1 hunks)versioned_docs/version-3.x/orm/api/update.md(1 hunks)versioned_docs/version-3.x/orm/cli.md(1 hunks)versioned_docs/version-3.x/orm/computed-fields.md(1 hunks)versioned_docs/version-3.x/orm/database-client.mdx(1 hunks)versioned_docs/version-3.x/orm/introduction.md(1 hunks)versioned_docs/version-3.x/orm/plugins/introduction.md(1 hunks)versioned_docs/version-3.x/orm/query-builder.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.mdx(1 hunks)versioned_docs/version-3.x/orm/ts-types.md(1 hunks)versioned_docs/version-3.x/orm/validation.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/attributes.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/builtin-types.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/components.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/custom-types.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/datasource.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/models.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/multi-file.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/polymorphism.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/relations.md(1 hunks)versioned_docs/version-3.x/orm/zmodel/reusing-fields.md(1 hunks)versioned_docs/version-3.x/reference/cli.md(1 hunks)versioned_docs/version-3.x/reference/error-handling.md(1 hunks)versioned_docs/version-3.x/reference/limitations.md(1 hunks)versioned_docs/version-3.x/reference/runtime-api.md(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_error-handling.md(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_options.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/_using-api.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/api-handlers/_data_type_serialization.md(1 hunks)versioned_docs/version-3.x/reference/server-adapters/api-handlers/index.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx(1 hunks)versioned_docs/version-3.x/reference/server-adapters/api-handlers/rpc.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/nestjs.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/zmodel-language.md(1 hunks)versioned_docs/version-3.x/samples.md(1 hunks)versioned_docs/version-3.x/service/introduction.md(1 hunks)versioned_docs/version-3.x/upgrade.md(1 hunks)versioned_docs/version-3.x/utilities/zod.md(1 hunks)versioned_docs/version-3.x/welcome.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/reference/limitations.md
[style] ~35-~35: For conciseness, consider replacing this expression with an adverb.
Context: ... }); ``` ### MongoDB is not supported Right now, the focus of this project is SQL datab...
(AT_THE_MOMENT)
versioned_docs/version-3.x/orm/introduction.md
[style] ~8-~8: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...from the prior arts and aims to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~33-~33: Consider using a different adverb to strengthen your wording.
Context: ...atible Query API Although ZenStack has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~33-~33: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
versioned_docs/version-3.x/reference/error-handling.md
[style] ~23-~23: Consider using a more formal alternative.
Context: ...error contains a meta field providing more information about the error. It contains the follow...
(MORE_INFO)
versioned_docs/version-3.x/reference/cli.md
[style] ~158-~158: To form a complete sentence, be sure to include a subject.
Context: ...---- | | --debug | Enable debug output. Can be toggled on the fly in the repl sessi...
(MISSING_IT_THERE)
[style] ~159-~159: To form a complete sentence, be sure to include a subject.
Context: ...alse | | --table | Enable table format. Can be toggled on the fly in the repl sessi...
(MISSING_IT_THERE)
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx
[style] ~596-~596: Consider a different adjective to strengthen your wording.
Context: ...?include=author 1. Including a deep relationship ts GET /api/po...
(DEEP_PROFOUND)
[style] ~668-~668: ‘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] ~804-~804: ‘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)
versioned_docs/version-3.x/reference/runtime-api.md
[style] ~86-~86: Consider using a different verb to strengthen your wording.
Context: ...be emitted with "info" level, so please make sure you [turn that level on](https://www.pr...
(MAKE_SURE_ENSURE)
[style] ~92-~92: ‘prior to’ might be wordy. Consider a shorter alternative.
Context: ... under update doesn't satisfy the rules prior to update, the update operation will fail ...
(EN_WORDINESS_PREMIUM_PRIOR_TO)
versioned_docs/version-3.x/reference/zmodel-language.md
[style] ~26-~26: Consider replacing this phrase with the adverb “naturally” to avoid wordiness.
Context: ...us to build the functionalities we want in a natural way, so we made several extensions to the l...
(IN_A_X_MANNER)
[style] ~178-~178: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...AST representation than generators. - They have access to language features that Z...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1056-~1056: To form a complete sentence, be sure to include a subject.
Context: ...on`: The operation to check access for. Can be "read", "create", "update", or "dele...
(MISSING_IT_THERE)
[style] ~1188-~1188: To form a complete sentence, be sure to include a subject.
Context: ...tModel(casing: String?): String {} ``` Can only be used in access policy expressio...
(MISSING_IT_THERE)
[style] ~1198-~1198: To form a complete sentence, be sure to include a subject.
Context: ...ration(casing: String?): String {} ``` Can only be used in access policy expressio...
(MISSING_IT_THERE)
[style] ~1204-~1204: The contraction ‘Here’re’ is uncommon in written English.
Context: ... Defaults to "original". ### Examples Here're some examples on using field and model ...
(THERE_RE_CONTRACTION_UNCOMMON)
[style] ~1272-~1272: To form a complete sentence, be sure to include a subject or ‘there’.
Context: ...*[FIELD_TYPE]** Type of the field. Can be a scalar type, a reference to anothe...
(MISSING_IT_THERE)
[style] ~1322-~1322: The contraction ‘There’re’ is uncommon in written English.
Context: ...Relations are connections among models. There're three types of relations: - One-to-o...
(THERE_RE_CONTRACTION_UNCOMMON)
[style] ~1605-~1605: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... true, the operation is rejected. - Otherwise, the operation is permitted. Please no...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1758-~1758: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...text: String, _ message: String?)` Validates a string field value ends with the give...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1762-~1762: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...text: String, _ message: String?)` Validates a string field value contains the given...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1766-~1766: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... - @email(_ message: String?) Validates a string field value is a valid email a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1770-~1770: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s. - @url(_ message: String?) Validates a string field value is a valid url. -...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1774-~1774: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... @datetime(_ message: String?) Validates a string field value is a valid ISO dat...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1778-~1778: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...egex: String, _ message: String?)` Validates a string field value matches a regex. ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1808-~1808: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ..._ value: Int, _ message: String?)` Validates a number field is less than the given v...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1812-~1812: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ..._ value: Int, _ message: String?)` Validates a number field is less than or equal to...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1834-~1834: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ion email(field: String): Boolean` Validates a string field value is a valid email a...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1838-~1838: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... datetime(field: String): Boolean` Validates a string field value is a valid ISO dat...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1842-~1842: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... - function url(field: String) Validates a string field value is a valid url. -...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1846-~1846: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...seInSensitive: Boolean?): Boolean` Validates a string field contains the search stri...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1850-~1850: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... String, search: String): Boolean` Validates a string field starts with the search s...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1854-~1854: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... String, search: String): Boolean` Validates a string field ends with the search str...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1858-~1858: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...eld: Any[], search: Any): Boolean` Validates a list field contains the search value....
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1862-~1862: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...d: Any[], search: Any[]): Boolean` Validates a list field contains every element in ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1866-~1866: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...d: Any[], search: Any[]): Boolean` Validates a list field contains some elements in ...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~1870-~1870: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...on isEmpty(field: Any[]): Boolean` Validates a list field is null or empty. ### Exa...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.17.2)
versioned_docs/version-3.x/reference/limitations.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
versioned_docs/version-3.x/reference/error-handling.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
versioned_docs/version-3.x/reference/cli.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
versioned_docs/version-3.x/reference/runtime-api.md
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
versioned_docs/version-3.x/reference/zmodel-language.md
51-51: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
52-52: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
53-53: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
86-86: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
87-87: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
88-88: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
89-89: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
90-90: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
656-656: Spaces inside code span elements
(MD038, no-space-in-code)
671-671: Spaces inside code span elements
(MD038, no-space-in-code)
672-672: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
881-881: Spaces inside code span elements
(MD038, no-space-in-code)
896-896: Spaces inside code span elements
(MD038, no-space-in-code)
907-907: Multiple headings with the same content
(MD024, no-duplicate-heading)
972-972: Heading levels should only increment by one level at a time
Expected: h4; Actual: h5
(MD001, heading-increment)
1053-1053: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1058-1058: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
1276-1276: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1277-1277: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1278-1278: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1279-1279: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1280-1280: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1281-1281: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1282-1282: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1283-1283: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1284-1284: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1429-1429: Spaces inside code span elements
(MD038, no-space-in-code)
1442-1442: Spaces inside code span elements
(MD038, no-space-in-code)
1463-1463: Spaces inside code span elements
(MD038, no-space-in-code)
1484-1484: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
1554-1554: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
1562-1562: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
1570-1570: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
1818-1818: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
1917-1917: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1919-1919: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1923-1923: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1924-1924: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1934-1934: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1935-1935: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1938-1938: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
1939-1939: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (28)
versioned_docs/version-3.x/orm/api/update.md (1)
1-6: “Update” API page is currently blankReplicate the structure you intend for the other CRUD docs (intro, parameters, example, gotchas). Otherwise users will find an empty page behind the sidebar link.
versioned_docs/version-3.x/orm/computed-fields.md (1)
1-8: No duplicate “Computed Fields” doc detectedVerified that only
versioned_docs/version-3.x/orm/computed-fields.mdcontains the “# Computed Fields” heading. There are no other pages with the same slug, so no routing conflicts will occur.versioned_docs/version-3.x/welcome.md (1)
3-5: Possible slug collision with existing V2/welcomepageBecause Docusaurus prefixes versioned docs with the version path only in routing, keeping the same
/welcomeslug in multiple versions will generate identical routes (e.g./docs/welcome) and the build will warn / overwrite one of them. Confirm whether an earlier version already defines this slug and, if so, add a version-specific slug such asv3-welcome.No code change proposed until the collision is confirmed.
versioned_docs/version-3.x/faq.md (1)
1-7: Front-matter looks fine but verify slug collision with existing versions
slug: /faqis already used in v2 docs. Duplicate absolute slugs across versions break Docusaurus routing (the first match wins). Either make the slug version-specific (e.g./v3/faq) or remove the custom slug and rely on the default one.versioned_docs/version-3.x/orm/zmodel/multi-file.md (1)
1-5: Same slug-duplication risk as above
No explicit slug, so the generated slug will be/orm/zmodel/multi-file. Make sure the same path doesn’t exist in older versions; otherwise add a version prefix.versioned_docs/version-3.x/upgrade.md (1)
1-7: Check upgrade guide placement
sidebar_position: 8puts the page above most ORM topics. Confirm that’s intentional; the upgrade guide is usually placed at the bottom of the sidebar to avoid distracting newcomers.versioned_docs/version-3.x/reference/server-adapters/hono.mdx (3)
25-47: LGTM! Code example demonstrates proper Hono integration.The code example correctly shows how to integrate ZenStack with Hono using the
createHonoHandlermiddleware factory. The pattern of usingenhancewith user context and the middleware mounting approach is consistent with other server adapters.
7-9: Imported component file paths verified successfullyAll referenced files exist in
versioned_docs/version-3.x/reference/server-adapters/:
_error-handling.md_options.mdx_using-api.mdxNo further action required.
51-51: Verify HonogetPrismaProp Signature in AdapterOptionsThis MDX-driven component renders your callback type as a string, so you’ll need to confirm it by hand:
• File:
versioned_docs/version-3.x/reference/server-adapters/hono.mdx(line 51)
• Make sureContextmatches the Hono context type you’re importing.
• Ensure the return type (unknown | Promise<unknown>) reflects your actual PrismaClient initializer’s signature.
• Cross-check against other adapters (Express, Fastify, etc.) to keep the syntax uniform.versioned_docs/version-3.x/orm/quick-start.mdx (4)
13-15: LGTM! Clear version information provided.The info callout clearly communicates that v3 packages are under the "@next" tag, which is important for users to understand the pre-release nature.
64-67: LGTM! Comprehensive configuration options documented.The documentation appropriately covers custom schema paths, output options, and source control considerations for generated files.
29-29: GitHub repository path verifiedThe
zenstackhq/v3-doc-quick-startrepository returns HTTP 200, so theStackBlitzGithubEmbedreference is valid and accessible.
6-9: All referenced components exist at their import pathsThe following imports have been verified and correspond to actual files in the codebase:
- src/components/StackBlitzGithubEmbed.tsx
- versioned_docs/version-3.x/_components/_zmodel-starter.md
- versioned_docs/version-3.x/_components/PackageInstall.tsx
- versioned_docs/version-3.x/_components/PackageExec.tsx
No changes required.
src/components/StackBlitzEmbed.tsx (2)
4-7: LGTM! Well-defined TypeScript interface.The interface properly defines required and optional props with appropriate types.
1-2: It appears nopackage.jsonfile was found in the repository. Please confirm manually that:
- A
package.jsonexists at the project root (or appropriate workspace root).- The
@stackblitz/sdkpackage is declared underdependenciesordevDependencies.src/components/StackBlitzGithubEmbed.tsx (1)
4-7: LGTM! Well-defined TypeScript interface.The interface appropriately defines the repoPath prop for GitHub repository embedding.
versioned_docs/version-3.x/reference/server-adapters/express.mdx (4)
25-44: LGTM! Express.js integration example is accurate.The code example correctly demonstrates Express middleware integration with proper request/response handling and Prisma enhancement patterns.
50-56: LGTM! Express-specific sendResponse option well documented.The documentation clearly explains the sendResponse boolean option and its impact on middleware behavior, which is specific to Express.js patterns.
66-66: External GitHub repository link verifiedThe link to https://github.com/zenstackhq/docs-tutorial-express returns HTTP 200 and is accessible. No further action required.
48-48: Express AdapterOptions.getPrisma signature is correctVerified in
src/components/ZenStackInStack.tsx(line 83) that the Express adapter’sgetPrismais indeed defined as(req, res) => …. The documentation’s signature<AdapterOptions getPrisma='(request: Request, response: Response) => unknown | Promise<unknown>' />matches the actual interface. No changes required.
versioned_docs/version-3.x/reference/limitations.md (1)
1-41: Well-structured limitations documentation.The documentation clearly outlines the current constraints and provides helpful workarounds. The code examples for transaction isolation levels are accurate and practical.
versioned_docs/version-3.x/reference/server-adapters/nuxt.mdx (1)
13-30: Excellent adapter documentation with clear examples.The documentation provides a clear integration example with proper TypeScript typing and follows the established pattern for server adapters. The
getPrismafunction properly demonstrates user context enhancement.versioned_docs/version-3.x/reference/server-adapters/elysia.mdx (1)
11-53: Well-structured Elysia adapter documentation.The documentation effectively demonstrates the middleware pattern with proper TypeScript typing and includes helpful installation instructions for Bun users. The code example shows correct usage of the Elysia framework integration.
versioned_docs/version-3.x/_components/PackageInstall.tsx (1)
10-15: Comprehensive package manager support.The package manager configuration correctly handles the different dev dependency flags across npm, pnpm, bun, and yarn. This provides excellent user experience for different development environments.
versioned_docs/version-3.x/reference/server-adapters/api-handlers/index.mdx (1)
10-16: Clear and comprehensive API styles explanation.The documentation effectively distinguishes between RPC and REST API styles, providing users with a clear understanding of their options. The explanation of framework-agnostic handlers with server adapter translation is particularly helpful.
versioned_docs/version-3.x/reference/cli.md (1)
24-28: Command summary forgenerateis inconsistent with the detailed sectionLine 25 claims the command “Generates RESTful API and Typescript client”, whereas the later generate section (Line 86+) explains it produces Prisma schema and runs plugins.
Please align the short description with the detailed one to avoid confusion for readers.versioned_docs/version-3.x/_components/_zmodel-starter.md (1)
1-23: LGTM – concise, valid starter schemaThe starter ZModel is syntactically correct, uses reasonable defaults, and demonstrates key features clearly.
versioned_docs/version-3.x/reference/server-adapters/nestjs.mdx (1)
124-131: Verify correct import style for REST handler
Here the REST handler is imported as a default export:import RESTApiHandler from '@zenstackhq/server/api/rest';Elsewhere in the docs (
Next.jssection) it’s imported as a named export{ RestApiHandler }. Please confirm the actual library export and make the samples consistent.
| const pkgManagers = [ | ||
| { name: 'npm', command: 'npx' }, | ||
| { name: 'pnpm', command: 'pnpm' }, | ||
| { name: 'bun', command: 'bunx' }, | ||
| { name: 'yarn', command: 'npx' }, | ||
| ]; |
There was a problem hiding this comment.
Incorrect Yarn command; will copy-paste fail
yarn users need yarn dlx (Yarn ≥2) or yarn create (Yarn 1), not npx. Suggest:
- { name: 'yarn', command: 'npx' },
+ { name: 'yarn', command: 'yarn dlx' },📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const pkgManagers = [ | |
| { name: 'npm', command: 'npx' }, | |
| { name: 'pnpm', command: 'pnpm' }, | |
| { name: 'bun', command: 'bunx' }, | |
| { name: 'yarn', command: 'npx' }, | |
| ]; | |
| const pkgManagers = [ | |
| { name: 'npm', command: 'npx' }, | |
| { name: 'pnpm', command: 'pnpm' }, | |
| { name: 'bun', command: 'bunx' }, | |
| { name: 'yarn', command: 'yarn dlx' }, | |
| ]; |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/_components/PackageExec.tsx between lines 9 and
14, the command for the yarn package manager is incorrectly set to 'npx', which
will cause copy-paste failures. Update the yarn command to 'yarn dlx' for Yarn
version 2 or higher, or 'yarn create' for Yarn version 1, depending on the
target environment. Adjust the code to reflect the correct command for yarn
users instead of using 'npx'.
| --- | ||
| sidebar_position: 7 | ||
| description: Transaction API | ||
| --- | ||
|
|
||
| # Transaction |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Transaction API page is empty – add content or mark WIP
Transactions are non-trivial; before publishing, document:
• how to start / commit / rollback
• nested transactions support
• limitations per adapter (e.g., SQLite)
• code sample with db.$transaction
Add the title field as well:
---
+title: Transaction
sidebar_position: 7
description: Transaction API
---📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| sidebar_position: 7 | |
| description: Transaction API | |
| --- | |
| # Transaction | |
| --- | |
| title: Transaction | |
| sidebar_position: 7 | |
| description: Transaction API | |
| --- | |
| # Transaction |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/transaction.md at lines 1 to 6, the
Transaction API page is currently empty and lacks essential documentation. Add
detailed content explaining how to start, commit, and rollback transactions,
describe support for nested transactions, note any adapter-specific limitations
such as with SQLite, and include a code sample demonstrating usage of
db.$transaction. Also, add a title field in the front matter for proper page
metadata.
| model Post { | ||
| id String @id @default(cuid()) | ||
| title. String @length(1, 256) | ||
| published Boolean @default(false) | ||
| author User @relation(fields: [authorId], references: [id]) |
There was a problem hiding this comment.
Schema typo: stray dot after title breaks ZModel parsing
title. String @length(1, 256)The dot makes the field name invalid. Remove it:
- title. String @length(1, 256)
+ title String @length(1, 256)🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/introduction.md around lines 66 to 70, there
is a typo in the schema where the field name "title." has an extra dot after it,
which breaks ZModel parsing. Remove the stray dot after "title" so the field
name is just "title" followed by the type declaration.
| export default createEventHandler({ | ||
| handler: RestApiHandler({ endpoint: 'http://myhost/api/model' }) | ||
| getPrisma | ||
| }); |
There was a problem hiding this comment.
Nuxt code snippet is syntactically invalid – missing comma between object properties
The example object passed to createEventHandler omits the comma after the handler property, making the snippet uncompilable/copypaste-unsafe.
-export default createEventHandler({
- handler: RestApiHandler({ endpoint: 'http://myhost/api/model' })
- getPrisma
-});
+export default createEventHandler({
+ handler: RestApiHandler({ endpoint: 'http://myhost/api/model' }),
+ getPrisma,
+});📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| export default createEventHandler({ | |
| handler: RestApiHandler({ endpoint: 'http://myhost/api/model' }) | |
| getPrisma | |
| }); | |
| export default createEventHandler({ | |
| handler: RestApiHandler({ endpoint: 'http://myhost/api/model' }), | |
| getPrisma, | |
| }); |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx
around lines 67 to 70, the object passed to createEventHandler is missing a
comma between the handler and getPrisma properties. Add a comma after the
handler property to separate the object properties correctly and fix the syntax
error.
| "links": { | ||
| "related": "http://myhost/api/post/1/author/1", | ||
| "self": "http://myhost/api/post/1/relationships/author/1" | ||
| } |
There was a problem hiding this comment.
self and related links in example violate JSON:API URL structure
/post/1/relationships/author/1 adds the resource id twice.
According to the spec and to your own endpoint list, the correct paths are:
-"related": "http://myhost/api/post/1/author/1",
-"self": "http://myhost/api/post/1/relationships/author/1"
+"related": "http://myhost/api/post/1/author",
+"self": "http://myhost/api/post/1/relationships/author"Keeping example URLs spec-compliant avoids confusing readers and tooling implementors.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "links": { | |
| "related": "http://myhost/api/post/1/author/1", | |
| "self": "http://myhost/api/post/1/relationships/author/1" | |
| } | |
| "links": { | |
| - "related": "http://myhost/api/post/1/author/1", | |
| - "self": "http://myhost/api/post/1/relationships/author/1" | |
| + "related": "http://myhost/api/post/1/author", | |
| + "self": "http://myhost/api/post/1/relationships/author" | |
| } |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx
around lines 181 to 184, the example URLs for "self" and "related" links
incorrectly include the resource ID twice, violating JSON:API URL structure.
Update the "self" link to use the correct path format without repeating the
resource ID, matching the spec and your endpoint list, so the URLs are
spec-compliant and clear for readers and tooling.
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rpc.mdx
Outdated
Show resolved
Hide resolved
| ```ts | ||
| import { enhance } from '@zenstackhq/runtime'; | ||
| import { ZenStackFastifyPlugin } from '@zenstackhq/server/fastify'; | ||
| import { prisma } from './db.ts'; | ||
| import { getSessionUser } from './auth.ts'; | ||
|
|
||
| const server = fastify(); | ||
|
|
||
| // serve OpenAPI at /api/model |
There was a problem hiding this comment.
Missing fastify import in sample code
The snippet instantiates fastify() without importing it:
-import { prisma } from './db.ts';
-import { getSessionUser } from './auth.ts';
+import fastify from 'fastify';
+import { prisma } from './db.ts';
+import { getSessionUser } from './auth.ts';Without this, readers copy-pasting will run into a fastify is not defined error.
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/server-adapters/fastify.mdx around lines
25 to 33, the sample code uses fastify() to create a server instance but does
not import fastify itself. To fix this, add an import statement for fastify at
the top of the snippet, such as "import fastify from 'fastify';" so that the
fastify function is defined and the example runs without errors.
| The generated prisma file only contains one `User` model: | ||
| ```zmodel | ||
| model User { | ||
| id String @id | ||
| createdAt DateTime @default(now()) | ||
| updatedAt DateTime @updatedAt | ||
| name String @id | ||
| } |
There was a problem hiding this comment.
Generated Prisma example shows duplicate @id – invalid schema
The name field is erroneously marked @id, producing two primary keys.
- name String @id
+ name String📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The generated prisma file only contains one `User` model: | |
| ```zmodel | |
| model User { | |
| id String @id | |
| createdAt DateTime @default(now()) | |
| updatedAt DateTime @updatedAt | |
| name String @id | |
| } | |
| model User { | |
| id String @id | |
| createdAt DateTime @default(now()) | |
| updatedAt DateTime @updatedAt | |
| name String | |
| } |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/zmodel-language.md around lines 280 to
287, the Prisma schema example incorrectly marks both the `id` and `name` fields
with `@id`, which is invalid as a model can only have one primary key. Remove
the `@id` attribute from the `name` field to ensure only the `id` field is the
primary key.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (15)
versioned_docs/version-3.x/modeling/mixin.md (2)
10-12: Grammar: singular/plural mismatch in sentence“Mixin is a ZModel concept and don't exist in PSL.” → should read “… and doesn't exist…”.
-Mixin is a ZModel concept and don't exist in PSL. +Mixin is a ZModel concept and doesn't exist in PSL.
14-16: Use “formerly” instead of “previously” for smoother wordingThe info call-out will read more naturally with “formerly”.
-Mixin was previously known as "abstract inheritance" in ZenStack v2. +Mixin was formerly known as "abstract inheritance" in ZenStack v2.versioned_docs/version-3.x/modeling/attribute.md (1)
29-33: Missing verb in sentence“Parameters can named (default) or positional.” is missing “be”.
-Parameters can named (default) or positional. +Parameters can be named (default) or positional.versioned_docs/version-3.x/modeling/overview.md (1)
18-19: Typo: “Prima” → “Prisma”-Don't worry if you've never used Prima before. +Don't worry if you've never used Prisma before.versioned_docs/version-3.x/welcome.md (1)
14-27: Heading-level jump inside list breaks MD001 ruleUsing
####inside list items skips a level and triggers markdown-lint.
Switch to bold text or###headings:- - #### An intuitive schema language + - ### An intuitive schema languageApply to all four list items for consistency.
versioned_docs/version-3.x/modeling/strong-typed-json.md (1)
14-18: Style: over-used phrase “in many cases”Consider replacing with a less common alternative, e.g., “often” or “frequently”, to keep the prose fresh.
versioned_docs/version-3.x/modeling/model.md (3)
106-107: Fix broken intra-doc linkThe target file is
relations.md, but the link points to./relation, which will 404.- It'll then form a relation. We'll cover that topic [later](./relation). +It'll then form a relation. We'll cover that topic [later](./relations).
166-171: Grammar polish: “give a field a type”Minor wording issue that reads awkwardly.
-Besides giving field a type, you can also specify the native database type to use with the `@db.` series of attributes. +Besides giving a field a type, you can also specify the native database type to use with the `@db.*` attributes.
180-182: Typo: “when generation queries” → “when generating queries”-The ORM respects the mapping when generation queries, and the migration engine uses it to generate the DDL. +The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL.versioned_docs/version-3.x/orm/overview.md (4)
8-15: Tone & grammar adjustments for the openerThe first paragraph contains informal wording and a grammar slip (“learnt from the prior arts”).
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and aims to provide an awesome developer experience by combining the best ingredients into a cohesive package. +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It builds on prior art and aims to provide an excellent developer experience by combining proven ideas into a cohesive package.
31-34: Replace informal phrase “pretty much”-… so that you can use it pretty much as a drop-in replacement. +… so that you can use it almost as a drop-in replacement.
66-70: Stray dot breaks the ZModel sample
title.(with a trailing dot) is invalid identifier syntax and will confuse readers.- title. String @length(1, 256) + title String @length(1, 256)
114-118: Grammar: subject-verb agreement-Real-world applications often involves storing polymorphic data … +Real-world applications often involve storing polymorphic data …versioned_docs/version-3.x/modeling/relations.md (2)
8-10: Grammar fixes in introduction-Relation is a fundamental concept in relational databases. It connect models into a graph, and allows you to query interconnected data efficiently. +A relation is a fundamental concept in relational databases. It connects models into a graph and allows you to query interconnected data efficiently.
83-86: Tone: drop informal “pretty much”-It's modeled pretty much the same way as one-to-one relations, except that… +It's modeled in the same way as one-to-one relations, except that…
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
versioned_docs/version-3.x/migration/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/modeling/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/reference/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/service/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/utilities/_category_.ymlis excluded by!**/*.yml
📒 Files selected for processing (22)
versioned_docs/version-3.x/_components/ZModelVsPSL.tsx(1 hunks)versioned_docs/version-3.x/migration/overview.md(1 hunks)versioned_docs/version-3.x/modeling/attribute.md(1 hunks)versioned_docs/version-3.x/modeling/custom-type.md(1 hunks)versioned_docs/version-3.x/modeling/datasource.md(1 hunks)versioned_docs/version-3.x/modeling/enum.md(1 hunks)versioned_docs/version-3.x/modeling/mixin.md(1 hunks)versioned_docs/version-3.x/modeling/model.md(1 hunks)versioned_docs/version-3.x/modeling/multi-file.md(1 hunks)versioned_docs/version-3.x/modeling/overview.md(1 hunks)versioned_docs/version-3.x/modeling/plugin.md(1 hunks)versioned_docs/version-3.x/modeling/polymorphism.md(1 hunks)versioned_docs/version-3.x/modeling/relations.md(1 hunks)versioned_docs/version-3.x/modeling/strong-typed-json.md(1 hunks)versioned_docs/version-3.x/orm/overview.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.mdx(1 hunks)versioned_docs/version-3.x/samples.md(1 hunks)versioned_docs/version-3.x/service/overview.md(1 hunks)versioned_docs/version-3.x/upgrade.md(1 hunks)versioned_docs/version-3.x/utilities/tanstack-query.md(1 hunks)versioned_docs/version-3.x/utilities/zod.md(1 hunks)versioned_docs/version-3.x/welcome.md(1 hunks)
✅ Files skipped from review due to trivial changes (10)
- versioned_docs/version-3.x/migration/overview.md
- versioned_docs/version-3.x/utilities/tanstack-query.md
- versioned_docs/version-3.x/service/overview.md
- versioned_docs/version-3.x/modeling/multi-file.md
- versioned_docs/version-3.x/modeling/plugin.md
- versioned_docs/version-3.x/modeling/custom-type.md
- versioned_docs/version-3.x/modeling/enum.md
- versioned_docs/version-3.x/_components/ZModelVsPSL.tsx
- versioned_docs/version-3.x/modeling/polymorphism.md
- versioned_docs/version-3.x/modeling/datasource.md
🚧 Files skipped from review as they are similar to previous changes (4)
- versioned_docs/version-3.x/utilities/zod.md
- versioned_docs/version-3.x/samples.md
- versioned_docs/version-3.x/upgrade.md
- versioned_docs/version-3.x/orm/quick-start.mdx
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
versioned_docs/version-3.x/welcome.md
16-16: Heading levels should only increment by one level at a time
Expected: h2; Actual: h4
(MD001, heading-increment)
🪛 LanguageTool
versioned_docs/version-3.x/modeling/mixin.md
[style] ~15-~15: Consider using “formerly” to strengthen your wording.
Context: ... PSL. :::info Mixin was previously known as "abstract inheritance" in ZenS...
(PREVIOUSLY_FORMERLY)
versioned_docs/version-3.x/modeling/overview.md
[style] ~10-~10: Consider shortening this phrase to avoid wordiness.
Context: ...nvince people to learn a new one. So we made the decision to design ZModel as a superset of the [...
(MAKE_THE_CHOICE_TO)
[style] ~19-~19: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...el, so no prior knowledge is required. A very simple ZModel schema looks like this: ```zmod...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/modeling/relations.md
[style] ~84-~84: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ...) authorId Int } ``` It's modeled pretty much the same way as one-to-one relations, e...
(PRETTY_MUCH)
versioned_docs/version-3.x/modeling/strong-typed-json.md
[style] ~14-~14: The phrase ‘in many cases’ is used quite frequently. Consider using a less frequent alternative to set your writing apart.
Context: ... usage has become more common. However, in many cases your JSON fields still follow a specifi...
(IN_MANY_STYLE_CASES)
versioned_docs/version-3.x/orm/overview.md
[style] ~8-~8: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...from the prior arts and aims to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~33-~33: Consider using a different adverb to strengthen your wording.
Context: ...atible Query API Although ZenStack has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~33-~33: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
🔇 Additional comments (1)
versioned_docs/version-3.x/modeling/overview.md (1)
28-43: Inconsistent types in example schema
authorIdis declared asString, but it referencesUser.id, which isInt.
Either changeauthorIdtoIntor adjustUser.idaccordingly to avoid confusion in docs examples.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (18)
versioned_docs/version-3.x/welcome.md (3)
16-27: Fix heading-level jump inside list itemsUsing
####directly after a top-level#violates MD001 (expected increment by one level).
Switching to##(or restructuring the list to plain paragraphs) keeps the hierarchy clean and avoids markdown-lint noise.- - #### An intuitive schema language + - ## An intuitive schema language That helps you model data, relation, access control, and more, in one place. [🔗](./modeling/) - - #### A powerful ORM + - ## A powerful ORM With awesomely-typed API, built-in access control, and unmatched flexibility. [🔗](./orm/) - - #### A Query-as-a-Service layer + - ## A Query-as-a-Service layer That provides a full-fledged data API without the need to code it up. [🔗](./service/) - - #### Utilities + - ## Utilities For deriving artifacts like Zod schemas, frontend hooks, OpenAPI specs, etc., from the schema. [🔗](./category/utilities)
3-3: Drop the leading slash inslugfor consistencyDocusaurus treats
slugvalues starting with/as absolute.
For versioned docs it’s conventional to use a relative slug (welcome) so the final URL becomes/docs/3.x/welcome, aligning with other pages.-slug: /welcome +slug: welcome
28-28: Consider using a proper admonition blockInstead of a blockquote, use Docusaurus admonition for clearer styling and automatic theming.
-> *ZenStack originated ... +:::note +ZenStack originated as an extension to Prisma ORM. V3 is a complete rewrite that removed Prisma as a runtime dependency and replaced it with an implementation built from scratch (“scratch” = [Kysely](https://kysely.dev/) 😆). On its surface, it continues to use a “Prisma-superset” schema language and a query API compatible with PrismaClient. +:::versioned_docs/version-3.x/modeling/multi-file.md (3)
2-2: Duplicatesidebar_positionmay cause ordering collision
sidebar_position: 11is also used bymodeling/plugin.md. Docusaurus resolves identical positions unpredictably, so one of the pages may jump around when new items are inserted.-sidebar_position: 11 +sidebar_position: 12 # pick a unique position
14-14: Minor grammar – plural pronoun doesn’t match singular antecedent“break them down” refers back to the singular noun schema.
-When your schema grows large, you can break them down to smaller files +When your schema grows large, you can break it down into smaller files
41-41: Wording – missing preposition“before passed to” reads awkwardly.
-… merged into a single schema AST before passed to the downstream tools. +… merged into a single schema AST before being passed on to downstream tools.versioned_docs/version-3.x/modeling/plugin.md (2)
2-2: Duplicatesidebar_positionwith multi-file docSame ordering clash as noted in
multi-file.md. Assign a unique value.
20-24: Example/description mismatchBullet 2 later references “
@core/prisma” as if it were shown in the snippet, but the snippet’sprovideris'my-zenstack-plugin'.Either change the snippet or adjust the wording:
-2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here)… +2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (for example `@core/prisma`), a local folder, or an npm package.versioned_docs/version-3.x/modeling/index.md (1)
10-10: Style – wordy phrasing“To design ZModel as a superset” already implies a decision; “made the decision to” is redundant. Optional tightening:
-So we made the decision to design ZModel as a superset of the … +Therefore, we designed ZModel as a superset of the …versioned_docs/version-3.x/orm/index.md (3)
8-8: Tone – informal adjective“Awesome” feels promotional. Prefer neutral technical tone:
-… aims to provide an awesome developer experience … +… aims to provide an excellent developer experience …
86-86: Grammar – subject-verb agreement-Real-world applications often involves storing polymorphic data … +Real-world applications often involve storing polymorphic data …
116-116: Word choice – “light-weighted”The common adjective is “lightweight”.
-… v3 is more straightforward and light-weighted. +… v3 is more straightforward and lightweight.versioned_docs/version-3.x/modeling/polymorphism.md (2)
28-28: Article usage-… having a in-database model of polymorphism … +… having an in-database model of polymorphism …
72-100: Hard tabs violate MD010The Mermaid ER diagram block contains literal tab characters that break some markdown linters and can shift rendering.
Replace tabs with 4 spaces (or whatever indentation you prefer) inside the diagram block.
versioned_docs/version-3.x/modeling/relation.md (4)
8-8: Grammar & style cleanup for opening paragraph
Minor wording issues slip in here (“Relation … connect …”, comma splice). Tightening this up improves readability without altering meaning.-Relation is a fundamental concept in relational databases. It connect models into a graph, and allows you to query interconnected data efficiently. +Relations are a fundamental concept in relational databases. They connect models into a graph and allow you to query interconnected data efficiently.
27-27: Singular/plural mismatch in ‘fields’ explanation
“fieldsparameters specifies” mixes plural and singular; makes the sentence stumble.-where the `fields` parameters specifies the foreign key field(s) and the `references` parameter specifies +where the `fields` parameter specifies the foreign key field(s) and the `references` parameter specifies
48-48: Small wording tweak for composite-PK note
“In matching order” is the idiomatic phrasing.-must be specified with those field tuples with matching order. +must be specified with those field tuples in matching order.
84-84: Informal phrasing and typo in one-to-many section
Removes informal “pretty much” (flagged by LanguageTool) and fixes “is a of list …”.-It's modeled pretty much the same way as one-to-one relations, except that the "non-owner" side (here `User.posts`) is a of list of the other side's model type. +It’s modeled essentially the same way as one-to-one relations, except that the “non-owner” side (here `User.posts`) is a list of the other side’s model type.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (6)
versioned_docs/version-3.x/migration/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/modeling/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/plugins/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/reference/plugins/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/service/_category_.ymlis excluded by!**/*.yml
📒 Files selected for processing (14)
versioned_docs/version-3.x/_components/ZModelVsPSL.tsx(1 hunks)versioned_docs/version-3.x/migration/index.md(1 hunks)versioned_docs/version-3.x/modeling/index.md(1 hunks)versioned_docs/version-3.x/modeling/multi-file.md(1 hunks)versioned_docs/version-3.x/modeling/plugin.md(1 hunks)versioned_docs/version-3.x/modeling/polymorphism.md(1 hunks)versioned_docs/version-3.x/modeling/relation.md(1 hunks)versioned_docs/version-3.x/orm/index.md(1 hunks)versioned_docs/version-3.x/orm/inferred-types.md(1 hunks)versioned_docs/version-3.x/orm/plugins/index.md(1 hunks)versioned_docs/version-3.x/reference/plugin-dev.md(1 hunks)versioned_docs/version-3.x/reference/runtime-api.md(1 hunks)versioned_docs/version-3.x/service/index.md(1 hunks)versioned_docs/version-3.x/welcome.md(1 hunks)
✅ Files skipped from review due to trivial changes (5)
- versioned_docs/version-3.x/service/index.md
- versioned_docs/version-3.x/orm/plugins/index.md
- versioned_docs/version-3.x/reference/plugin-dev.md
- versioned_docs/version-3.x/orm/inferred-types.md
- versioned_docs/version-3.x/migration/index.md
🚧 Files skipped from review as they are similar to previous changes (2)
- versioned_docs/version-3.x/reference/runtime-api.md
- versioned_docs/version-3.x/_components/ZModelVsPSL.tsx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/modeling/index.md
[style] ~10-~10: Consider shortening this phrase to avoid wordiness.
Context: ...nvince people to learn a new one. So we made the decision to design ZModel as a superset of the [...
(MAKE_THE_CHOICE_TO)
[style] ~19-~19: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...el, so no prior knowledge is required. A very simple ZModel schema looks like this: ```zmod...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/modeling/relation.md
[style] ~84-~84: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ...) authorId Int } ``` It's modeled pretty much the same way as one-to-one relations, e...
(PRETTY_MUCH)
versioned_docs/version-3.x/orm/index.md
[style] ~8-~8: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...from the prior arts and aims to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~33-~33: Consider using a different adverb to strengthen your wording.
Context: ...atible Query API Although ZenStack has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~33-~33: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
🪛 markdownlint-cli2 (0.17.2)
versioned_docs/version-3.x/modeling/polymorphism.md
74-74: Hard tabs
Column: 1
(MD010, no-hard-tabs)
76-76: Hard tabs
Column: 1
(MD010, no-hard-tabs)
79-79: Hard tabs
Column: 1
(MD010, no-hard-tabs)
versioned_docs/version-3.x/welcome.md
16-16: Heading levels should only increment by one level at a time
Expected: h2; Actual: h4
(MD001, heading-increment)
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
versioned_docs/version-3.x/modeling/index.md (1)
10-10: Optional: Consider simplifying the phrase for better readability.The phrase "made the decision to design" could be simplified to "decided to design" for more concise writing.
-So we made the decision to design ZModel as a superset of the [Prisma Schema Language (PSL)](https://www.prisma.io/docs/orm/prisma-schema), which is one of the best data modeling language out there. +So we decided to design ZModel as a superset of the [Prisma Schema Language (PSL)](https://www.prisma.io/docs/orm/prisma-schema), which is one of the best data modeling language out there.versioned_docs/version-3.x/orm/api/find.md (1)
1-32: Well-documented API methods with minor style improvement opportunity.The find API methods are clearly documented. Consider varying the sentence beginnings for better readability:
- `findFirst` - Find the first record that matches the query criteria. + Returns the first record that matches the query criteria.versioned_docs/version-3.x/orm/api/create.md (1)
1-21: Clear API documentation with minor style improvement opportunity.The create API methods are well-documented with accurate technical details and good use of the StackBlitz embed for interactive examples.
Consider simplifying "new records" to "records" for more concise writing:
-The `create` series of APIs are used to create new records in the database. +The `create` series of APIs are used to create records in the database.versioned_docs/version-3.x/orm/index.md (2)
97-103: Use the standard term “lightweight”
Both the heading and paragraph use “light-Weighted/light-weighted”, which feels awkward. Replace with the single word “lightweight”.-### Straightforward and light-Weighted +### Straightforward and lightweight ... -Compared to Prisma and previous versions of ZenStack, v3 is more straightforward and light-weighted. +Compared to Prisma and previous versions of ZenStack, v3 is more straightforward and lightweight.
10-17: Tighten informal language
Phrases like “awesome”, “completely different”, and “pretty much” read informally for technical docs. Consider trimming or replacing for a more professional tone.-... strives to provide an awesome developer experience ... +... strives to provide a great developer experience ... -... has a completely different implementation ... +... has an entirely different implementation ... -... so that you can use it pretty much as a drop-in replacement. +... so that you can use it almost as a drop-in replacement.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
src/components/StackBlitzGithubEmbed.tsx(1 hunks)versioned_docs/version-3.x/_components/ZenStackVsPrisma.tsx(1 hunks)versioned_docs/version-3.x/_components/_zmodel-starter.md(1 hunks)versioned_docs/version-3.x/faq.md(1 hunks)versioned_docs/version-3.x/modeling/conclusion.md(1 hunks)versioned_docs/version-3.x/modeling/index.md(1 hunks)versioned_docs/version-3.x/orm/api/_select-include-omit.md(1 hunks)versioned_docs/version-3.x/orm/api/aggregate.md(1 hunks)versioned_docs/version-3.x/orm/api/count.md(1 hunks)versioned_docs/version-3.x/orm/api/create.md(1 hunks)versioned_docs/version-3.x/orm/api/delete.md(1 hunks)versioned_docs/version-3.x/orm/api/filter.md(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)versioned_docs/version-3.x/orm/api/transaction.md(1 hunks)versioned_docs/version-3.x/orm/api/update.md(1 hunks)versioned_docs/version-3.x/orm/cli.md(1 hunks)versioned_docs/version-3.x/orm/database-client.md(1 hunks)versioned_docs/version-3.x/orm/index.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.md(1 hunks)
✅ Files skipped from review due to trivial changes (4)
- versioned_docs/version-3.x/orm/api/filter.md
- versioned_docs/version-3.x/modeling/conclusion.md
- versioned_docs/version-3.x/orm/database-client.md
- versioned_docs/version-3.x/orm/api/_select-include-omit.md
🚧 Files skipped from review as they are similar to previous changes (9)
- versioned_docs/version-3.x/orm/api/delete.md
- versioned_docs/version-3.x/orm/api/count.md
- versioned_docs/version-3.x/orm/api/update.md
- versioned_docs/version-3.x/orm/api/transaction.md
- versioned_docs/version-3.x/orm/api/aggregate.md
- versioned_docs/version-3.x/faq.md
- versioned_docs/version-3.x/orm/cli.md
- versioned_docs/version-3.x/_components/_zmodel-starter.md
- src/components/StackBlitzGithubEmbed.tsx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/find.md
[style] ~23-~23: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nique criteria. - findFirst Find the first record that matches the query...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
versioned_docs/version-3.x/orm/api/create.md
[style] ~10-~10: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ...eate` series of APIs are used to create new records in the database. It has the following m...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
versioned_docs/version-3.x/modeling/index.md
[style] ~10-~10: Consider shortening this phrase to avoid wordiness.
Context: ...nvince people to learn a new one. So we made the decision to design ZModel as a superset of the [...
(MAKE_THE_CHOICE_TO)
[style] ~19-~19: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...el, so no prior knowledge is required. A very simple ZModel schema looks like this: ```zmod...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/orm/index.md
[style] ~10-~10: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...m the prior arts and strives to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~16-~16: Consider using a different adverb to strengthen your wording.
Context: ...v3 is inspired by Prisma ORM but it has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~16-~16: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
[style] ~109-~109: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...ntainers](https://webcontainers.io/) is an awesome technology that allows you to run a Nod...
(AWESOME)
🔇 Additional comments (11)
versioned_docs/version-3.x/_components/ZenStackVsPrisma.tsx (1)
1-16: LGTM! Well-structured documentation component.The component follows React and TypeScript best practices with proper typing, clean imports, and appropriate use of the Docusaurus Admonition theme component for consistent documentation styling.
versioned_docs/version-3.x/modeling/index.md (2)
1-7: LGTM! Proper document structure.The frontmatter and imports are correctly configured for Docusaurus documentation.
22-52: Excellent schema example and explanation.The ZModel schema example effectively demonstrates key concepts including datasource configuration, model definitions, attributes, and relations. The comparison with Prisma's generator concept provides valuable context for users transitioning from Prisma.
versioned_docs/version-3.x/orm/quick-start.md (4)
1-18: Well-structured introduction with clear guidance.The document setup is excellent with proper imports and a helpful info callout about the @next tag for v3 packages. The introduction clearly outlines multiple approaches for getting started.
19-44: Clear and practical setup instructions.Both approaches for new and existing projects are well-documented with appropriate use of interactive components. The StackBlitz embed provides immediate hands-on experience.
45-62: Comprehensive manual setup guide.The three-step manual setup process is clear and well-organized. Proper separation of dev and runtime dependencies shows good understanding of the package structure.
63-68: Valuable operational guidance.The explanation of path customization and source control considerations provides important practical information for real-world usage and deployment scenarios.
versioned_docs/version-3.x/orm/api/find.md (2)
33-52: Excellent use of interactive examples and logical progression.The documentation effectively combines explanatory text with StackBlitz embeds, and the clickToLoad feature helps with page performance. The logical flow from basic usage to advanced features like sorting and pagination is well-structured.
53-66: Comprehensive coverage of advanced query features.The field selection documentation using the SelectIncludeOmit component is well-integrated, and the distinct rows explanation with SQL implementation details provides valuable technical insight for developers.
versioned_docs/version-3.x/orm/api/create.md (2)
22-40: Comprehensive input documentation with clear technical details.The input object documentation thoroughly covers all aspects including nested relations, batch operations, and the skipDuplicates flag. The reference to field selection documentation provides good cross-linking.
41-44: Accurate and concise output documentation.The output section clearly distinguishes between the different return types of the create methods and appropriately references field selection options.
| ```zmodel" | ||
| model Post { |
There was a problem hiding this comment.
Fix malformed code-block fence – remove stray quote
The extra double quote after zmodel breaks Markdown parsing and syntax highlighting.
-```zmodel"
+```zmodel🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/index.md at lines 48 to 49, the code block
fence for the zmodel code block is malformed due to an extra double quote after
zmodel. Remove the stray double quote so the fence reads ```zmodel instead of
```zmodel". This will fix Markdown parsing and syntax highlighting issues.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
src/components/GithubCodeBlock.tsx (2)
24-32: Consider expanding language support and using a more robust detection method.The current language detection is quite limited and hardcoded. Consider using a library like
linguist-jsor maintaining a more comprehensive mapping for better syntax highlighting support.const getLanguage = (file: string): string => { - if (file.endsWith('.ts')) { - return 'typescript'; - } else if (file.endsWith('.zmodel')) { - return 'zmodel'; - } else { - return 'plaintext'; - } + const extension = file.split('.').pop()?.toLowerCase(); + const languageMap: Record<string, string> = { + 'ts': 'typescript', + 'tsx': 'typescript', + 'js': 'javascript', + 'jsx': 'javascript', + 'json': 'json', + 'md': 'markdown', + 'yml': 'yaml', + 'yaml': 'yaml', + 'zmodel': 'zmodel', + }; + return languageMap[extension || ''] || 'plaintext'; };
9-11: Consider using a more descriptive initial loading state.The current "Loading..." text is functional but could be more informative for better user experience.
-const [code, setCode] = useState<string>('Loading...'); +const [code, setCode] = useState<string>(`Loading ${file}...`);versioned_docs/version-3.x/orm/api/find.md (1)
14-32: Address the style issue with repetitive sentence beginnings.The static analysis tool correctly identified that three consecutive sentences begin with "Find". This affects readability.
- `findMany` - Find multiple records that match the query criteria. + Retrieves multiple records that match the query criteria. - `findUnique` - Find a single record with a unique criteria. + Retrieves a single record with a unique criteria. - `findFirst` - Find the first record that matches the query criteria. + Returns the first record that matches the query criteria.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
package.jsonis excluded by!**/*.jsonpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml,!**/*.yaml
📒 Files selected for processing (3)
src/components/GithubCodeBlock.tsx(1 hunks)src/components/StackBlitzGithubEmbed.tsx(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- src/components/StackBlitzGithubEmbed.tsx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/find.md
[style] ~24-~24: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nique criteria. - findFirst Find the first record that matches the query...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (4)
src/components/GithubCodeBlock.tsx (1)
1-7: LGTM: Clean imports and well-defined interface.The imports are minimal and appropriate, and the props interface clearly defines the expected inputs with proper TypeScript typing.
versioned_docs/version-3.x/orm/api/find.md (3)
1-8: LGTM: Proper documentation structure with appropriate imports.The frontmatter is well-structured with sidebar positioning and description. The component imports are correctly referenced and will provide good interactive documentation experience.
40-70: LGTM: Excellent use of interactive documentation components.The integration of StackBlitzGithubEmbed components with appropriate configuration (clickToLoad for performance, proper file references) demonstrates thoughtful documentation design. The combination of live examples and static code blocks provides comprehensive learning resources.
36-36: Verified GitHub repository path and file accessibilityThe referenced
zenstackhq/v3-doc-orm-findrepository and itszenstack/schema.zmodelfile return HTTP 200 via jsDelivr, confirming they exist and are publicly accessible. No changes required.
| useEffect(() => { | ||
| (async function () { | ||
| const response = await fetch(`https://cdn.jsdelivr.net/gh/${repoPath}/${file}`); | ||
| if (!response.ok) { | ||
| setCode(`Unable to load "${repoPath}/${file}"`); | ||
| return; | ||
| } | ||
| const text = await response.text(); | ||
| setCode(text); | ||
| })(); | ||
| }, [repoPath, file]); |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add error handling for network failures and consider loading states.
The current implementation has basic error handling for HTTP errors but lacks comprehensive error handling for network failures, timeouts, or other fetch-related issues.
useEffect(() => {
- (async function () {
+ (async function () {
+ try {
const response = await fetch(`https://cdn.jsdelivr.net/gh/${repoPath}/${file}`);
if (!response.ok) {
setCode(`Unable to load "${repoPath}/${file}"`);
return;
}
const text = await response.text();
setCode(text);
- })();
+ } catch (error) {
+ setCode(`Failed to fetch "${repoPath}/${file}": ${error instanceof Error ? error.message : 'Unknown error'}`);
+ }
+ })();
}, [repoPath, file]);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| useEffect(() => { | |
| (async function () { | |
| const response = await fetch(`https://cdn.jsdelivr.net/gh/${repoPath}/${file}`); | |
| if (!response.ok) { | |
| setCode(`Unable to load "${repoPath}/${file}"`); | |
| return; | |
| } | |
| const text = await response.text(); | |
| setCode(text); | |
| })(); | |
| }, [repoPath, file]); | |
| useEffect(() => { | |
| (async function () { | |
| try { | |
| const response = await fetch(`https://cdn.jsdelivr.net/gh/${repoPath}/${file}`); | |
| if (!response.ok) { | |
| setCode(`Unable to load "${repoPath}/${file}"`); | |
| return; | |
| } | |
| const text = await response.text(); | |
| setCode(text); | |
| } catch (error) { | |
| setCode( | |
| `Failed to fetch "${repoPath}/${file}": ${ | |
| error instanceof Error ? error.message : 'Unknown error' | |
| }` | |
| ); | |
| } | |
| })(); | |
| }, [repoPath, file]); |
🤖 Prompt for AI Agents
In src/components/GithubCodeBlock.tsx around lines 12 to 22, the fetch call
lacks error handling for network failures and does not manage loading states.
Wrap the fetch logic inside a try-catch block to catch network errors and update
the state accordingly. Additionally, introduce a loading state variable to
indicate when the fetch is in progress and update it before and after the fetch
operation to reflect the loading status.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
versioned_docs/version-3.x/orm/api/find.md (2)
1-4: Addtitleto the front-matter for improved navigation & SEOMost docs in this folder specify an explicit
titlein the front-matter. Omitting it falls back to the filename, which renders as “find” (lower-case) in the sidebar and HTML<title>. Adding a proper title keeps style consistent and helps search engines.--- +title: Find sidebar_position: 2 description: Find API ---
14-32: Rephrase bullet descriptions to avoid repetitive sentence startsLanguageTool flagged three consecutive sentences beginning with “Find”. Consider sleeker phrasing:
- `findMany` - - Find multiple records that match the query criteria. + + Returns multiple records matching the specified criteria. - `findUnique` - - Find a single record with a unique criteria. + + Retrieves a single record identified by a unique field. - `findFirst` - - Find the first record that matches the query criteria. + + Returns the first record that satisfies the query criteria.This improves readability without altering the meaning.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
src/components/StackBlitzGithubEmbed.tsx(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- src/components/StackBlitzGithubEmbed.tsx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/find.md
[style] ~24-~24: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nique criteria. - findFirst Find the first record that matches the query...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (2)
versioned_docs/version-3.x/orm/api/find.md (2)
6-8: Double-check MDX import paths and extensions
./_select-include-omit.mdis imported as a React component. Docusaurus requires the target to be processed as MDX, so the file should have a.mdxextension, or you should rename the import accordingly.- Verify that both
@site/src/components/StackBlitzGithubEmbedand@site/src/components/GithubCodeBlockexist on the v3 docs site build path; broken imports will fail the build.
48-50: Confirm the parameter namesortis correctIn earlier ZenStack examples (and in Prisma) the option is commonly called
orderBy. If the actual client still expectsorderBy, the examples here will confuse users.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (8)
versioned_docs/version-3.x/orm/api/filter.md (8)
2-4: Title/description polish and consistency
- Use a more descriptive H1 and title-case description.
- Current H1 “Filter” reads a bit odd compared to sections (“Basic filters”, etc.).
--- sidebar_position: 3 -description: how to filter entities +description: How to Filter Entities --- -# Filter +# FilteringAlso applies to: 9-9
11-11: Fix parallelism and clarityImprove the sentence flow and verb agreement.
-Filtering is an important topic because it's involved in many ORM operations, for example when you find records, selecting relations, and updating or deleting multiple records. +Filtering is important because it’s involved in many ORM operations, for example when you find records, select relations, and update or delete multiple records.
13-15: Minor wordingAdd a comma after the introductory clause.
-Throughout this section all samples are based on the following ZModel schema: +Throughout this section, all samples are based on the following ZModel schema:
19-26: Operator list formatting + semantics wording
- Add commas/backticks for consistency.
- “AND semantic” → “AND semantics”.
- Consider noting case sensitivity for string operators and DB collation differences.
-You can filter on scalar fields with values or operators as supported by the field type. The following filter operators are available. +You can filter on scalar fields with values or operators as supported by the field type. The following filter operators are available: -- `equals` `not`: all scalar fields. -- `in` `notIn`: all scalar fields -- `contains` `startsWith` `endsWith`: String fields -- `lt` `lte` `gt` `gte`: String, Int, BigInt, Float, Decimal, and Date fields +- `equals`, `not`: all scalar fields +- `in`, `notIn`: all scalar fields +- `contains`, `startsWith`, `endsWith`: `String` fields (case sensitivity depends on DB/collation) +- `lt`, `lte`, `gt`, `gte`: `String`, `Int`, `BigInt`, `Float`, `Decimal`, and `Date` fields -A filter object can contain multiple field filters, and they are combined with `AND` semantic. You can also use the `AND`, `OR`, and `NOT` logical operators to combine filter objects to form a complex filter. +A filter object can contain multiple field filters, and they are combined with `AND` semantics. You can also use the `AND`, `OR`, and `NOT` logical operators to combine filter objects to form complex filters.
32-34: Add a note oneveryover empty relationsIn many ORMs/SQL translations,
everyover an empty relation can evaluate to true, which surprises users. Consider adding a one-liner note to set expectations.
45-47: Wording tweak for list supportSmall phrasing improvement.
-List type is only supported for PostgreSQL. +List (array) fields are supported only on PostgreSQL.
78-83: Consistent capitalization and wordingUse “JSON” and harmonize the admonition title casing.
-## Json filters +## JSON filters -:::info WORK IN PROGRESS -Filtering on Json fields is work in progress and will be available soon. +:::info Work in progress +Filtering on JSON fields is a work in progress and will be available soon. :::
86-89: Great overview of$expr; consider a one-liner safety noteKysely builds parameterized SQL, which mitigates injection risks. A short note stating that
$exprremains parameterized via Kysely would reassure readers.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
versioned_docs/version-3.x/orm/api/filter.md(1 hunks)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/api/filter.md (3)
49-54: Syntax highlighting forzmodelEnsure Prism is configured with a language definition for
zmodel; otherwise this will render as plain text. If not configured, consider```zmodel→```txtor add the language to Prism config.
6-8: Embeds look goodImports and embeds are consistent and align with the content flow.
Also applies to: 15-16, 28-28, 34-34, 90-90
28-28: StackBlitz start scripts verifiedI’ve confirmed that the
zenstackhq/v3-doc-orm-filterrepo’s package.json defines bothgenerateandbasicscripts, along withrelation,query-builder, anddev. No changes are needed.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
versioned_docs/version-3.x/orm/api/delete.md (1)
1-4: Frontmatter description can be more informative for SEO/UXConsider making the description action-oriented and include the method names to help users and search engines understand scope at a glance.
--- sidebar_position: 5 -description: Delete API +description: Delete records with delete, deleteMany, and deleteManyAndReturn ---
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
versioned_docs/version-3.x/orm/api/delete.md(1 hunks)
🔇 Additional comments (4)
versioned_docs/version-3.x/orm/api/delete.md (4)
8-20: Nice addition; concise and clearGood structure, helpful cross-link, and a runnable sample. Once the above verifications and clarifications are addressed, this page is in solid shape.
16-16: Anchor exists; link is valid.
- The
## Manipulating relationsheading is defined in versioned_docs/version-3.x/orm/api/update.md (line 42), which generates the#manipulating-relationsanchor.- No changes are needed.
20-20: StackBlitz embed validatedThe embedded repository, scripts, and entry file are all present and correctly configured:
- Repository zenstackhq/v3-doc-orm-delete exists
- package.json defines both generate and main scripts
- main.ts is present at the repo root
No updates to the
<StackBlitzGithubEmbed>are needed.
6-6: Component import and MDX processing verified
src/components/StackBlitzGithubEmbed.tsxexportsdefault StackBlitzGithubEmbed(line 84).docusaurus.config.jsis present at the repo root, confirming MDX support for.mdfiles.No changes required.
| - `delete` - Delete a single, unique record. | ||
| - `deleteMany` - Delete multiple records that match the query criteria. | ||
| - `deleteManyAndReturn` - Similar to `deleteMany`, but returns the deleted records | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add signatures, parameters, and return semantics
Great overview. To reduce ambiguity, add concise signatures, parameter shapes, and return values. Also call out error/constraint behavior.
- `delete` - Delete a single, unique record.
- `deleteMany` - Delete multiple records that match the query criteria.
- `deleteManyAndReturn` - Similar to `deleteMany`, but returns the deleted records
+
+## Signatures
+
+```ts
+// delete a single unique record
+client.<model>.delete(args: {
+ where: <UniqueWhere>
+ select?: <Select>
+ include?: <Include>
+})
+
+// delete many records matching a filter
+client.<model>.deleteMany(args?: {
+ where?: <Where>
+})
+
+// delete many records and return them
+client.<model>.deleteManyAndReturn(args: {
+ where?: <Where>
+ select?: <Select>
+ include?: <Include>
+})
+```
+
+## Return values
+- `delete`: returns the deleted record (respecting `select`/`include`).
+- `deleteMany`: returns a summary (e.g., affected count).
+- `deleteManyAndReturn`: returns the deleted records (respecting `select`/`include`).
+
+## Notes
+- If behavior (e.g., returning deleted rows) varies by database/provider, add a short compatibility note.
+- Document common errors (e.g., unique mismatch, referential constraints) and how to handle them.🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/delete.md around lines 12 to 15, the
current descriptions of delete methods lack detailed signatures, parameter
definitions, and return value explanations. Enhance the documentation by adding
concise TypeScript method signatures for delete, deleteMany, and
deleteManyAndReturn, specifying their parameters and optional fields. Include a
section describing the return values for each method, note any database/provider
compatibility differences, and document common errors and constraint behaviors
to clarify usage and error handling.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
versioned_docs/version-3.x/orm/api/count.md (1)
10-10: Fix grammar in sentence about counting non-null fieldsUse “allows you to” and “a
selectclause.”-You can use the `count` method to count the number of records that match a query. It also allows to count non-null field values with an `select` clause. +You can use the `count` method to count the number of records that match a query. It also allows you to count non-null field values with a `select` clause.versioned_docs/version-3.x/orm/api/create.md (1)
10-11: Tighten phrasing and fix subject-verb agreementMore concise wording and correct plurality.
-The `create` series of APIs are used to create new records in the database. It has the following methods: +The `create` APIs create records in the database. They include:versioned_docs/version-3.x/orm/api/find.md (3)
11-11: Tighten phrasing and fix subject-verb agreementMake it concise and grammatically consistent with Create.
-The `find` series of APIs are used to query records from the database. It has the following methods: +The `find` APIs query records from the database. They include:
15-31: Reduce repetition in method descriptionsAvoid starting multiple sentences with “Find…”. More concise wording improves readability.
- Find multiple records that match the query criteria. + Return multiple records matching the criteria. @@ - Find a single record with a unique criteria. + Return a single record by a unique criterion. @@ - Find the first record that matches the query criteria. + Return the first record matching the criteria. @@ - Similar to `findUnique`, but throws an error if no record is found. + As `findUnique`, but throws if no record is found. @@ - Similar to `findFirst`, but throws an error if no record is found. + As `findFirst`, but throws if no record is found.
43-43: Clarify sorting sentence and avoid repetitionUse “option” and “nulls placement” for clarity.
-Use the `sort` field to control the sort field, direction, and null field placement. Sorting is not supported for `findUnique` and `findUniqueOrThrow`. +Use the `sort` option to control field, direction, and nulls placement. Sorting is not supported for `findUnique` and `findUniqueOrThrow`.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
versioned_docs/version-3.x/orm/api/aggregate.md(1 hunks)versioned_docs/version-3.x/orm/api/count.md(1 hunks)versioned_docs/version-3.x/orm/api/create.md(1 hunks)versioned_docs/version-3.x/orm/api/filter.md(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)versioned_docs/version-3.x/orm/api/group-by.md(1 hunks)versioned_docs/version-3.x/orm/api/index.md(1 hunks)versioned_docs/version-3.x/orm/api/transaction.md(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- versioned_docs/version-3.x/orm/api/group-by.md
- versioned_docs/version-3.x/orm/api/index.md
🚧 Files skipped from review as they are similar to previous changes (2)
- versioned_docs/version-3.x/orm/api/transaction.md
- versioned_docs/version-3.x/orm/api/filter.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/create.md
[style] ~10-~10: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ...eate` series of APIs are used to create new records in the database. It has the following m...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
versioned_docs/version-3.x/orm/api/find.md
[style] ~23-~23: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nique criteria. - findFirst Find the first record that matches the query...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (2)
versioned_docs/version-3.x/orm/api/create.md (1)
2-2: Verify sidebar ordering (duplicate position with Find)This page and Find both use
sidebar_position: 2. Confirm intended ordering or adjust to avoid ambiguity in sidebar sorting.versioned_docs/version-3.x/orm/api/find.md (1)
2-2: Verify sidebar ordering (duplicate position with Create)This page and Create both use
sidebar_position: 2. Confirm intended ordering or adjust to avoid ambiguity in sidebar sorting.
| - `_min` - minimum value of a field. | ||
| - `_max` - maximum value of a field. | ||
|
|
||
| You can also use `where`, `orderBy`, `skip`, and `take` to control what records are included in the aggregation. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Use sort instead of orderBy for consistency with Find docs
Other docs (e.g., Find) use sort. Using orderBy here is inconsistent and may confuse users.
-You can also use `where`, `orderBy`, `skip`, and `take` to control what records are included in the aggregation.
+You can also use `where`, `sort`, `skip`, and `take` to control what records are included in the aggregation. See [Filter](./filter.md) and [Find → Sorting](./find.md#sorting).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| You can also use `where`, `orderBy`, `skip`, and `take` to control what records are included in the aggregation. | |
| You can also use `where`, `sort`, `skip`, and `take` to control what records are included in the aggregation. See [Filter](./filter.md) and [Find → Sorting](./find.md#sorting). |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/aggregate.md at line 18, replace the term
`orderBy` with `sort` to maintain consistency with the Find documentation. This
change ensures the terminology aligns across related docs and avoids user
confusion.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
versioned_docs/version-3.x/orm/api/transaction.md (2)
1-4: Add explicit title to frontmatter (follow-up on earlier review)Frontmatter is missing
title. Prior review requested this. Add for consistency and proper page metadata.--- +title: Transaction sidebar_position: 9 description: Transaction API ---
8-41: Consider adding coverage for nested transactions and adapter-specific limitations (follow-up)Previously requested but still missing: nested transactions support semantics and adapter limitations (e.g., SQLite), plus rollback examples. I can help draft these sections if desired.
🧹 Nitpick comments (5)
versioned_docs/version-3.x/orm/api/group-by.md (3)
1-4: Add explicit title to frontmatter for consistency and clearer metadataDocusaurus will infer the title from the H1, but using an explicit
titlein frontmatter keeps metadata consistent across pages.--- +title: GroupBy sidebar_position: 8 description: GroupBy API ---
32-33: Fix grammar in explanatory sentenceSubject-verb agreement and phrasing.
- In this case, the fields of aggregation doesn't need to be in the `by` clause. + In this case, the aggregated field does not need to be included in the `by` clause.
35-39: Verify thehavingsyntax andbysingle-string formEnsure the
havingstructure and the single-stringbyform match the ORM’s contract. Some ORMs expect aggregation keys nested under the aggregator (e.g.,_sum: { viewCount: ... }) and requirebyto be an array. If both forms are supported, consider adding an example with multiple fields (e.g.,by: ['authorId', 'published']) for completeness.versioned_docs/version-3.x/orm/api/transaction.md (2)
31-31: Tighten grammar and wording (“so as to”, “allows”, “it’s/its”)Apply minor edits for clarity and correctness.
-Interactive transactions allows you to write imperative code that can access the results of previous operations and use them to influence later operations. Albeit it's flexibility, you should make the transaction callback run as fast as possible so as to reduce the performance impact of the transaction on the database. +Interactive transactions allow you to write imperative code that can access the results of previous operations and use them to influence later operations. Despite its flexibility, make the transaction callback run as fast as possible to reduce the performance impact on the database.
25-26: Clarify result ordering and add a cautionReinforce that the array form returns results in order, but operations should not depend on each other. Optional but helps avoid misuse.
-The result of each operation is returned in the same order as the input. +The result of each operation is returned in the same order as the input. Do not rely on previous results in this form; use an interactive transaction when you need dependent logic.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
versioned_docs/version-3.x/orm/api/group-by.md(1 hunks)versioned_docs/version-3.x/orm/api/index.md(1 hunks)versioned_docs/version-3.x/orm/api/transaction.md(1 hunks)versioned_docs/version-3.x/orm/cli.md(1 hunks)versioned_docs/version-3.x/orm/database-client.md(1 hunks)versioned_docs/version-3.x/orm/inferred-types.md(1 hunks)versioned_docs/version-3.x/orm/polymorphism.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.md(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- versioned_docs/version-3.x/orm/polymorphism.md
- versioned_docs/version-3.x/orm/inferred-types.md
- versioned_docs/version-3.x/orm/database-client.md
🚧 Files skipped from review as they are similar to previous changes (3)
- versioned_docs/version-3.x/orm/api/index.md
- versioned_docs/version-3.x/orm/cli.md
- versioned_docs/version-3.x/orm/quick-start.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/transaction.md
[style] ~31-~31: ‘So as to’ expresses purpose and is used in formal texts. Consider using “to”.
Context: ...action callback run as fast as possible so as to reduce the performance impact of the tr...
(SO_AS_TO)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/api/group-by.md (1)
43-43: StackBlitz embed path verified as validThe GitHub repo at zenstackhq/v3-doc-orm-groupBy returns HTTP 200, so the mixed-case repo name is correct and accessible. No changes needed.
• File: versioned_docs/version-3.x/orm/api/group-by.md
Line: 43versioned_docs/version-3.x/orm/api/transaction.md (2)
14-15: Reword “sequential” claim; array form may not guarantee ordered executionDepending on the underlying engine, array-form
$transaction([...])operations execute in a single transaction and return results in order, but not necessarily “sequentially.” They must be independent since you can't use prior results. Suggest neutral wording.-This overload takes an array of promises as input. The operations are executed sequentially in the order they are provided. The operations are independent of each other, because there's no way to access the result of a previous operation and use it to influence the later operations. +This overload takes an array of database operations as input and runs them in a single transaction. Results are returned in the same order as the input. Operations should be independent, since there's no way to access the result of a previous operation to influence a later one.
43-43: StackBlitz GitHub repo path verified
Thezenstackhq/v3-doc-orm-transactionrepository returns HTTP 200 and is accessible for embedding. No changes needed.
| // Note that the `db.user.create` and `db.post.create` calls are not awaited. They | ||
| // are passed to the `$transaction` method to execute. | ||
| const [user, post] = await db.$transaction([ | ||
| db.user.create({ data: { name: 'Alice' } }), | ||
| db.user.create({ data: { name: 'Bob' } }), | ||
| ]); |
There was a problem hiding this comment.
Fix example: mismatch between description and code; avoid dependent ops in array form
The comment mentions db.user.create and db.post.create, but the code creates two users. Also, array form shouldn’t show dependent operations. Make both operations independent and rename variables to reflect that.
-// Note that the `db.user.create` and `db.post.create` calls are not awaited. They
-// are passed to the `$transaction` method to execute.
-const [user, post] = await db.$transaction([
- db.user.create({ data: { name: 'Alice' } }),
- db.user.create({ data: { name: 'Bob' } }),
-]);
+// Note: operations are not awaited individually; they are passed into $transaction.
+const [alice, bob] = await db.$transaction([
+ db.user.create({ data: { name: 'Alice' } }),
+ db.user.create({ data: { name: 'Bob' } }),
+]);📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // Note that the `db.user.create` and `db.post.create` calls are not awaited. They | |
| // are passed to the `$transaction` method to execute. | |
| const [user, post] = await db.$transaction([ | |
| db.user.create({ data: { name: 'Alice' } }), | |
| db.user.create({ data: { name: 'Bob' } }), | |
| ]); | |
| // Note: operations are not awaited individually; they are passed into $transaction. | |
| const [alice, bob] = await db.$transaction([ | |
| db.user.create({ data: { name: 'Alice' } }), | |
| db.user.create({ data: { name: 'Bob' } }), | |
| ]); |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/transaction.md around lines 17 to 22, the
comment and code are inconsistent and show a dependent operation pattern in the
array form; update the example so both operations are independent and names
match the resources: change the comment to mention db.user.create and
db.post.create, replace the second db.user.create with db.post.create (or
otherwise show two independent creates), and rename the destructured result
variables to [user, post] (or [user1, user2] if you keep two users) so variable
names reflect the actual created records.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
versioned_docs/version-3.x/orm/index.md (2)
48-49: Fix malformed code-fence: remove stray double quote after zmodelThe extra " breaks MDX/Markdown parsing and syntax highlighting.
-```zmodel" +```zmodel model Post {
87-95: Incorrect model referenced in TypeScript example (db.asset vs db.content)The schema defines Content/Post, but the example queries db.asset. This won’t compile and confuses readers.
-```ts title="main.ts" -const asset = await db.asset.findFirst(); -if (asset.type === 'Post') { - // asset's type is narrowed down to `Post` - console.log(asset.content); -} else { - // other asset type -} -``` +```ts title="main.ts" +const content = await db.content.findFirst(); +if (content?.type === 'Post') { + // `content` is now narrowed to `Post` + console.log(content.content); +} else { + // other content type +} +```
🧹 Nitpick comments (8)
versioned_docs/version-3.x/orm/index.md (7)
10-10: Tighten wording: “learnt from the prior arts” and informal toneSmall grammar/style cleanup for clarity and formality.
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an awesome developer experience by combining the best ingredients into a cohesive package. +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It has learned from prior art and aims to provide an excellent developer experience by combining proven ideas into a cohesive package.
16-16: Improve formality and tense consistencyUse “entirely,” present tense for “replicates,” and avoid “pretty much.”
-ZenStack v3 is inspired by Prisma ORM but it has a completely different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicated Prisma ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you're not a Prisma user, the query API is very intuitive and easy to learn. +ZenStack v3 is inspired by Prisma ORM but has an entirely different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicates Prisma ORM's query API so that you can use it as a drop-in replacement. Even if you're not a Prisma user, the query API is intuitive and easy to learn.
46-47: Hyphenation: “database-specific”Minor grammar fix.
-The rules are enforced at runtime via query injection, so it doesn't rely on any database specific row-level security features. +The rules are enforced at runtime via query injection, so it doesn't rely on any database-specific row-level security features.
67-69: Subject–verb agreement“Applications … involve,” not “involves.”
-Real-world applications often involves storing polymorphic data which is notoriously complex to model and query. +Real-world applications often involve storing polymorphic data, which is notoriously complex to model and query.
97-97: Title case and terminology: “lightweight,” not “light-Weighted”Use standard term “lightweight.”
-### Straightforward and light-Weighted +### Straightforward and lightweight
102-102: Wording: “generation,” not “generating”Minor readability improvement.
-- No magic generating into `node_modules`. You fully control how the generated code is compiled and bundled. +- No magic generation into `node_modules`. You fully control how the generated code is compiled and bundled.
109-109: Tone: replace informal “awesome”Make tone more formal.
-Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive code samples. StackBlitz's [WebContainers](https://webcontainers.io/) is an awesome technology that allows you to run a Node.js environment inside the browser. The embedded samples use the [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use. +Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive code samples. StackBlitz's [WebContainers](https://webcontainers.io/) is a powerful technology that allows you to run a Node.js environment inside the browser. The embedded samples use [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use.versioned_docs/version-3.x/orm/polymorphism.md (1)
12-14: Grammar: “Polymorphic models are …”Subject–verb agreement inside the callout.
-Polymorphic models is a major feature that sets ZenStack apart from Prisma. +Polymorphic models are a major feature that sets ZenStack apart from Prisma.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
versioned_docs/version-3.x/faq.md(1 hunks)versioned_docs/version-3.x/migrate-prisma.md(1 hunks)versioned_docs/version-3.x/orm/index.md(1 hunks)versioned_docs/version-3.x/orm/inferred-types.md(1 hunks)versioned_docs/version-3.x/orm/logging.md(1 hunks)versioned_docs/version-3.x/orm/polymorphism.md(1 hunks)versioned_docs/version-3.x/samples.md(1 hunks)
✅ Files skipped from review due to trivial changes (3)
- versioned_docs/version-3.x/migrate-prisma.md
- versioned_docs/version-3.x/orm/logging.md
- versioned_docs/version-3.x/samples.md
🚧 Files skipped from review as they are similar to previous changes (2)
- versioned_docs/version-3.x/orm/inferred-types.md
- versioned_docs/version-3.x/faq.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/index.md
[style] ~10-~10: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...m the prior arts and strives to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~16-~16: Consider using a different adverb to strengthen your wording.
Context: ...v3 is inspired by Prisma ORM but it has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~16-~16: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
[style] ~109-~109: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...ntainers](https://webcontainers.io/) is an awesome technology that allows you to run a Nod...
(AWESOME)
🔇 Additional comments (2)
versioned_docs/version-3.x/orm/index.md (1)
1-118: Overall: strong overview and structureThe page reads well, examples are helpful, and the Kysely builder sample balances the ORM API nicely. Once the small fixes above are applied, it’ll be in great shape.
versioned_docs/version-3.x/orm/polymorphism.md (1)
1-37: LGTM overallClear explanation of CRUD semantics, good use of live sample embeds, and the constraints are called out succinctly.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (8)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (3)
15-21: Name the “proceed” function precisely to avoid ambiguity“proceed query” is vague; readers need the exact function name they should call (e.g., proceed()).
Apply this diff:
-- A "proceed query" function, which you can call to continue executing the operation +- A proceed() function, which you can call to continue executing the operation
26-26: Clarify “query builder API” by naming and linking to KyselyMake it explicit which query builder you mean to avoid confusion.
Apply this diff:
-As its name suggests, query API hooks are only triggered by ORM query calls, not by query builder API calls. +As its name suggests, query API hooks are only triggered by ORM query calls, not by query builder API calls (e.g., Kysely).Optionally add a link:
- (e.g., Kysely). + (e.g., [Kysely](https://koskimas.github.io/kysely/)).
1-3: Ensure unique sidebar positions within the “plugins” folderBoth this page and the plugins index page use sidebar_position: 1. Duplicate positions can lead to unstable ordering.
If you intend index to be 1, consider:
---- -sidebar_position: 1 +sidebar_position: 3 ----Or adjust according to the desired order of all plugin pages.
versioned_docs/version-3.x/orm/plugins/index.md (1)
34-34: Tighten wording (“very powerful”)Avoid weak intensifiers and improve precision.
Apply this diff:
- Kysely query hooks give you the ultimate power to inspect and alter the SQL query (in AST form) before it's sent to the database. This is a very powerful low-level extensibility that should be used with care. See [Kysely Query Hooks](./kysely-query-hooks.md) for details. + Kysely query hooks let you inspect and alter the SQL query (in AST form) before it's sent to the database. This is a powerful low-level extension point and should be used with care. See [Kysely Query Hooks](./kysely-query-hooks.md) for details.versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (4)
41-43: Streamline warning language and avoid weak intensifiersImprove clarity and reduce wordiness.
Apply this diff:
:::warning -Be very careful about opting in to load before and after mutation entities. Batch mutations can result in a large number of entities being loaded and incur significant performance overhead. +Use caution when opting to load entities before and after mutations. Batch mutations can load many entities and incur significant performance overhead. :::
20-21: Cross-reference where to opt in for entitiesHelp readers connect “opt-in” to the specific configuration.
Apply this diff:
- - The entities being mutated (only available when opted in) + - The entities being mutated (only available when opted in; see mutationInterceptionFilter below)
27-29: Cross-reference “opt-in” for before/after entitiesSame clarity improvement for afterEntityMutation.
Apply this diff:
- - The entities before the mutation (only available when opted in) - - The entities after the mutation (only available when opted in) + - The entities before the mutation (only available when opted in; see mutationInterceptionFilter below) + - The entities after the mutation (only available when opted in; see mutationInterceptionFilter below)
39-40: Clarify rollback behavior for afterEntityMutationExplicitly stating rollback behavior reduces ambiguity.
Apply this diff if accurate:
-If a mutation happens inside a transaction, the `afterEntityMutation` callback is called after the transaction is committed. +If a mutation happens inside a transaction, the `afterEntityMutation` callback is called after the transaction is committed (it is not invoked if the transaction rolls back).If this is not accurate, please adjust the wording to reflect the actual behavior.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md(1 hunks)versioned_docs/version-3.x/orm/plugins/index.md(1 hunks)versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md(1 hunks)versioned_docs/version-3.x/orm/plugins/query-api-hooks.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/plugins/index.md
[style] ~34-~34: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...fore it's sent to the database. This is a very powerful low-level extensibility that should be ...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md
[style] ~42-~42: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...ransaction is committed. :::warning Be very careful about opting in to load before and afte...
(EN_WEAK_ADJECTIVE)
[style] ~42-~42: To reduce wordiness, try specifying a number or using “many” or “numerous” instead.
Context: ...entities. Batch mutations can result in a large number of entities being loaded and incur signifi...
(LARGE_NUMBER_OF)
🔇 Additional comments (2)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (1)
5-5: Verified prop names for StackBlitzGithubEmbed are correct
TheStackBlitzGithubEmbedPropsinterface definesrepoPath,openFile, andstartScriptexactly as expected—no changes needed.versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (1)
5-5: Embed prop names verified – no changes required
The MDX usage of<StackBlitzGithubEmbed repoPath="…" openFile="…" startScript="…"/>exactly matches the component’sStackBlitzGithubEmbedProps(repoPath, openFile, startScript), so no prop-name updates are needed.
| ```ts | ||
| const db = new ZenStackClient({ ... }); | ||
| const withPlugin = $db.use({ ... }); | ||
| const noPlugin = withPlugin.$unuseAll(); | ||
| ``` |
There was a problem hiding this comment.
Fix code sample: variable name and method name are incorrect
- Use db, not $db.
- Use .$use per your API description.
Apply this diff:
```ts
const db = new ZenStackClient({ ... });
-const withPlugin = $db.use({ ... });
+const withPlugin = db.$use({ ... });
const noPlugin = withPlugin.$unuseAll();
<details>
<summary>🤖 Prompt for AI Agents</summary>
In versioned_docs/version-3.x/orm/plugins/index.md around lines 38 to 42, the
sample uses the wrong variable and method names; change the second line to call
.$use on the db instance instead of $db.use (i.e., replace "$db.use" with
"db.$use") so the snippet reads: const db = new ZenStackClient({ ... }); const
withPlugin = db.$use({ ... }); const noPlugin = withPlugin.$unuseAll(); and keep
the rest of the snippet unchanged.
</details>
<!-- fingerprinting:phantom:triton:chinchilla -->
<!-- This is an auto-generated comment by CodeRabbit -->
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (1)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (1)
25-25: Fix sample embed to target the Query API Hooks example, not the Kysely hooks oneThe embed points to the Kysely hooks sample, which is unrelated to this page and will confuse readers.
Apply this diff:
-<StackBlitzGithubEmbed repoPath="zenstackhq/v3-doc-orm" openFile="plugins/kysely-query-hooks.ts" startScript="generate,kysely-query-hooks" /> +<StackBlitzGithubEmbed repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate,query-api-hooks" />
🧹 Nitpick comments (6)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (1)
15-20: Tighten bullet wording and align terminology for the callback context
- Remove unnecessary “The …” articles for conciseness.
- Prefer consistent terminology and code formatting for identifiers (e.g., proceed function).
Apply this diff:
-- The model -- The operation -- The query args -- The ORM client that triggered the query -- A "proceed query" function, which you can call to continue executing the operation +- model +- operation +- query args +- ORM client that triggered the query +- a `proceed` function you can call to continue executing the operationPlease verify the actual function name exposed to plugin authors (is it
proceed,proceedQuery, or something else?) and adjust the backticked identifier accordingly across docs for consistency.versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md (2)
15-16: Grammar: use “an” before “onKyselyQuery”Minor grammar fix improves readability.
Apply this diff:
-To create a Kysely query hook plugin, call the `$use` method with an object containing a `onKyselyQuery` callback. The callback is triggered before each Kysely query is executed. It receives a context object containing: +To create a Kysely query hook plugin, call the `$use` method with an object containing an `onKyselyQuery` callback. The callback is triggered before each Kysely query is executed. It receives a context object containing:
17-20: Clarify and format context fields; align naming for the proceed function
- Use code formatting for identifiers and remove leading “The …”.
- If the function is named differently (e.g.,
proceedQuery), update accordingly across docs.Apply this diff:
-- The Kysely instance -- The Kysely query node (SQL AST) -- The ORM client that triggered the query -- A "proceed query" function, which you can call to send the query to the database +- Kysely instance +- Kysely query node (SQL AST) +- ORM client that triggered the query +- a `proceed` function you can call to send the query to the databasePlease confirm the exact function name surfaced in the hook context and standardize it across plugin docs.
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (3)
11-12: Tighten terminology and formatting for operationsUse code formatting for operation names and be explicit that both ORM and Query Builder paths trigger the hooks to avoid ambiguity.
Apply this edit:
-Entity mutation hooks allow you to intercept entity mutation operations, i.e., "create", "update", and "delete". They are triggered regardless of whether the operations are performed through the ORM queries or the query builder API. +Entity mutation hooks allow you to intercept entity mutation operations, i.e., `create`, `update`, and `delete`. They are triggered regardless of whether the operations are performed through ORM APIs or the Query Builder API.
41-43: Be explicit that database-level cascades are not capturedMinor clarification to avoid confusion with ORM-level cascades.
-Update and delete triggered by cascading operations are not captured by the entity mutation hooks. +Update and delete triggered by database-level cascading operations (e.g., `ON UPDATE/DELETE CASCADE`) are not captured by the entity mutation hooks.
45-47: Tighten language and reduce wordiness in the performance warningImprove clarity and style while keeping the warning strong.
-:::warning -Be very careful about opting in to load before and after mutation entities. Batch mutations can result in a large number of entities being loaded and incur significant performance overhead. -::: +:::warning +Use caution when enabling entity loading for `before`/`after` hooks. Batch mutations can load many entities and introduce significant performance overhead. +:::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these settings in your CodeRabbit configuration.
📒 Files selected for processing (3)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md(1 hunks)versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md(1 hunks)versioned_docs/version-3.x/orm/plugins/query-api-hooks.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md
[style] ~46-~46: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...tity mutation hooks. ::: :::warning Be very careful about opting in to load before and afte...
(EN_WEAK_ADJECTIVE)
[style] ~46-~46: To reduce wordiness, try specifying a number or using “many” or “numerous” instead.
Context: ...entities. Batch mutations can result in a large number of entities being loaded and incur signifi...
(LARGE_NUMBER_OF)
versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md
[grammar] ~17-~17: There might be a mistake here.
Context: ...bject containing: - The Kysely instance - The Kysely query node (SQL AST) - The OR...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ...stance - The Kysely query node (SQL AST) - The ORM client that triggered the query ...
(QB_NEW_EN)
[grammar] ~19-~19: There might be a mistake here.
Context: ... The ORM client that triggered the query - A "proceed query" function, which you ca...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md
[grammar] ~15-~15: There might be a mistake here.
Context: ...ining the following fields: - The model - The operation - The query args - The ORM...
(QB_NEW_EN)
[grammar] ~16-~16: There might be a mistake here.
Context: ...ing fields: - The model - The operation - The query args - The ORM client that tri...
(QB_NEW_EN)
[grammar] ~17-~17: There might be a mistake here.
Context: ...e model - The operation - The query args - The ORM client that triggered the query ...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ... The ORM client that triggered the query - A "proceed query" function, which you ca...
(QB_NEW_EN)
🔇 Additional comments (5)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (1)
21-21: LGTM: clear scoping noteGood callout that Query API hooks do not apply to the query builder API.
versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md (1)
24-26: LGTM: helpful admonition about low-level QueryNodeThe note sets the right expectation for readers working at this level.
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (3)
1-3: Frontmatter looks goodSidebar position is set; relying on the H1 for the page title is consistent with Docusaurus defaults.
39-40: Clarify transaction semantics (nested transactions, savepoints)You note post-commit execution, which is good. Please specify behavior for nested transactions/savepoints and what happens if the transaction rolls back (hooks not fired).
Proposed addition:
If a mutation happens inside a transaction, the `afterEntityMutation` callback is called after the transaction is committed. +If the transaction is rolled back, `afterEntityMutation` is not called. In nested transactions/savepoints, callbacks run only after the outermost commit.
49-51: Confirm StackBlitz embed props & external file pathChecked the code: the component uses startScript (optional string) and forwards it to the StackBlitz SDK; docs consistently use comma-separated startScript values. I cannot access external GitHub repos from this environment — please manually confirm the sample file exists.
- Component: src/components/StackBlitzGithubEmbed.tsx — defines startScript?: string and passes startScript in options to sdk.embedGithubProject / sdk.openGithubProject.
- Doc: versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (around line 51) — embed line (unchanged):
- Action required: verify that the repository zenstackhq/v3-doc-orm contains plugins/entity-mutation-hooks.ts (or update repoPath / openFile if the file path differs).
| sidebar_position: 2 | ||
| --- | ||
|
|
||
| import StackBlitzGithubEmbed from '@site/src/components/StackBlitzGithubEmbed'; |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify StackBlitzGithubEmbed props and availability in versioned docs
Ensure the component exists at the imported path and that it supports the props used here.
Run this script to confirm the component and its prop names:
🏁 Script executed:
#!/bin/bash
# Verify the component file exists
fd -a 'StackBlitzGithubEmbed' -t f
# Inspect the component to confirm supported props
rg -n -A3 -B3 'interface\s+\w*Props|type\s+\w*Props' | sed -n '1,200p'
# Grep for prop usages of StackBlitzGithubEmbed across docs to ensure consistency
rg -n "StackBlitzGithubEmbed.*(repoPath|openFile|startScript)"Length of output: 14180
StackBlitzGithubEmbed: component exists but missing startScript prop (used in v3 docs)
src/components/StackBlitzGithubEmbed.tsx defines props { repoPath: string; height?: string; openFile?: string } — there is no startScript prop, but multiple versioned docs pass startScript. Either add startScript to the component and propagate it to the embed logic, or remove/replace its usages in docs.
Files to update:
- Component: src/components/StackBlitzGithubEmbed.tsx — add startScript?: string and handle it.
- Docs using startScript:
- versioned_docs/version-3.x/orm/api/group-by.md:43
- versioned_docs/version-3.x/orm/query-builder.md:27
- versioned_docs/version-3.x/orm/api/filter.md:24,30,90
- versioned_docs/version-3.x/orm/api/find.md:35,45,51,59,65
- versioned_docs/version-3.x/orm/api/count.md:12
- versioned_docs/version-3.x/orm/api/aggregate.md:22
- versioned_docs/version-3.x/orm/api/update.md:48
- versioned_docs/version-3.x/orm/api/delete.md:20
- versioned_docs/version-3.x/orm/polymorphism.md:36
- versioned_docs/version-3.x/orm/computed-fields.md:50
- versioned_docs/version-3.x/orm/api/transaction.md:43
- versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md:28
- versioned_docs/version-3.x/orm/plugins/query-api-hooks.md:25
- versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md:51
Suggested minimal change (add to the component props):
interface StackBlitzGithubEmbedProps {
repoPath: string;
height?: string;
openFile?: string;
startScript?: string;
}
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md around lines
5-5: the docs pass a startScript prop to StackBlitzGithubEmbed but the component
at src/components/StackBlitzGithubEmbed.tsx lacks this prop; add startScript?:
string to the component's props interface and wire it through to whatever embed
logic builds the StackBlitz parameters (include it in the generated embed URL or
payload so the sandbox runs the specified script), then update the listed
versioned docs to either pass the prop or remove it as appropriate; ensure
TypeScript types are updated and no unused vars remain.
| To create an entity mutation hook plugin, call the `$use` method with an `onEntityMutation` key containing an object with the following fields (all optional): | ||
|
|
||
| - `beforeEntityMutation` | ||
| A callback function that is called before the entity mutation operation. It receives a context object containing: | ||
| - The model | ||
| - The action (create, update, delete) | ||
| - The Kysely query node (SQL AST) | ||
| - The entities being mutated (only available when opted in) | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Clarify what “entities being mutated” means and the data shape
Ambiguity here can cause misuse. Explicitly document whether a single entity vs. an array is passed, and what’s available for each action.
Consider revising as:
-- `beforeEntityMutation`
- A callback function that is called before the entity mutation operation. It receives a context object containing:
- - The model
- - The action (create, update, delete)
- - The Kysely query node (SQL AST)
- - The entities being mutated (only available when opted in)
+- `beforeEntityMutation`
+ A callback function that is called before the entity mutation operation. It receives a context object containing:
+ - `model`: the model name
+ - `action`: one of `create` | `update` | `delete`
+ - `ast`: the Kysely query node (SQL AST)
+ - `entities`: when entity loading is enabled, the target entities to be mutated
+ - For `create`: the input payload(s) to be inserted
+ - For `update`/`delete`: the matched entity/entities before mutation
+ - Type: a single object or an array for batch mutations (document the exact type used)If the actual property names differ (e.g., model vs table, ast vs queryNode), please align the docs with the real API.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| To create an entity mutation hook plugin, call the `$use` method with an `onEntityMutation` key containing an object with the following fields (all optional): | |
| - `beforeEntityMutation` | |
| A callback function that is called before the entity mutation operation. It receives a context object containing: | |
| - The model | |
| - The action (create, update, delete) | |
| - The Kysely query node (SQL AST) | |
| - The entities being mutated (only available when opted in) | |
| To create an entity mutation hook plugin, call the `$use` method with an `onEntityMutation` key containing an object with the following fields (all optional): | |
| - `beforeEntityMutation` | |
| A callback function that is called before the entity mutation operation. It receives a context object containing: | |
| - `model`: the model name | |
| - `action`: one of `create` | `update` | `delete` | |
| - `ast`: the Kysely query node (SQL AST) | |
| - `entities`: when entity loading is enabled, the target entities to be mutated | |
| - For `create`: the input payload(s) to be inserted | |
| - For `update`/`delete`: the matched entity/entities before mutation | |
| - Type: a single object or an array for batch mutations (document the exact type used) |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md around lines
13 to 21, the phrase “entities being mutated” is ambiguous; update the docs to
explicitly state the property name(s) and data shape for each action (create,
update, delete) — e.g., whether a single entity or an array is passed, the exact
field names (e.g., entities vs entity), and for each action list the object
shape (inserted values for create, changed fields and primary key for update,
deleted row or key for delete). Also verify and align the doc property names
(model/table, ast/queryNode) to match the actual API and update examples
accordingly.
| - `mutationInterceptionFilter` | ||
|
|
||
| A callback used to determine if an operation should be intercepted, and if so, whether entities should be loaded and passed to the `beforeEntityMutation` and `afterEntityMutation` hooks. It receives a context object containing: | ||
| - The model | ||
| - The action (create, update, delete) | ||
| - The Kysely query node (SQL AST) | ||
|
|
||
| The callback should return an object indicating if the operation should be intercepted and whether entities should be loaded. If this callback is not provided, by default, all mutation operations are intercepted, but entities are not loaded. | ||
|
|
There was a problem hiding this comment.
Document the exact return shape of mutationInterceptionFilter
The contract omits the explicit return fields and their types. This is critical for implementers.
Suggested expansion:
- `mutationInterceptionFilter`
A callback used to determine if an operation should be intercepted, and if so, whether entities should be loaded and passed to the `beforeEntityMutation` and `afterEntityMutation` hooks. It receives a context object containing:
- The model
- The action (create, update, delete)
- The Kysely query node (SQL AST)
- The callback should return an object indicating if the operation should be intercepted and whether entities should be loaded. If this callback is not provided, by default, all mutation operations are intercepted, but entities are not loaded.
+ The callback must return:
+ - `intercept: boolean` — whether to invoke the hooks for this mutation
+ - `loadEntities?: boolean | 'before' | 'after' | 'both'` — whether to load entities and at which phase
+ - `true`/`'both'`: load for both `before` and `after`
+ - `'before'`: only load for `beforeEntityMutation`
+ - `'after'`: only load for `afterEntityMutation`
+ - `false`/omitted: do not load entities
+
+ Defaults when the callback is not provided:
+ - `intercept = true` (all mutations are intercepted)
+ - `loadEntities = false` (entities are not loaded)If your actual API differs, please update the doc to reflect the precise shape and defaults.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `mutationInterceptionFilter` | |
| A callback used to determine if an operation should be intercepted, and if so, whether entities should be loaded and passed to the `beforeEntityMutation` and `afterEntityMutation` hooks. It receives a context object containing: | |
| - The model | |
| - The action (create, update, delete) | |
| - The Kysely query node (SQL AST) | |
| The callback should return an object indicating if the operation should be intercepted and whether entities should be loaded. If this callback is not provided, by default, all mutation operations are intercepted, but entities are not loaded. | |
| - `mutationInterceptionFilter` | |
| A callback used to determine if an operation should be intercepted, and if so, whether entities should be loaded and passed to the `beforeEntityMutation` and `afterEntityMutation` hooks. It receives a context object containing: | |
| - The model | |
| - The action (create, update, delete) | |
| - The Kysely query node (SQL AST) | |
| The callback must return: | |
| - `intercept: boolean` — whether to invoke the hooks for this mutation | |
| - `loadEntities?: boolean | 'before' | 'after' | 'both'` — whether to load entities and at which phase | |
| - `true`/`'both'`: load for both `before` and `after` | |
| - `'before'`: only load for `beforeEntityMutation` | |
| - `'after'`: only load for `afterEntityMutation` | |
| - `false`/omitted: do not load entities | |
| Defaults when the callback is not provided: | |
| - `intercept = true` (all mutations are intercepted) | |
| - `loadEntities = false` (entities are not loaded) |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md around lines
30 to 38, the description of mutationInterceptionFilter omits the exact return
shape and defaults; update the docs to explicitly state the return object's
fields, their types and default values (e.g., { intercept: boolean,
loadEntities?: boolean } or the actual API shape), document what each field
does, and show the default behavior when the filter is omitted; if the real API
differs, replace the example with the precise property names, types, and
defaults and ensure the prose explains when entities are loaded and when hooks
run.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (3)
13-20: Tighten wording and standardize field names (queryArgs, ormClient, proceed).Clarifies phrasing and aligns field names with code-style conventions. Also avoids the awkward “object with … key” wording.
Apply this diff:
-To create a query API hook plugin, call the `$use` method with an object with the `onQuery` key providing a callback. The callback is invoked with an argument containing the following fields: - -- The model -- The operation -- The query args -- The ORM client that triggered the query -- A "proceed query" function, which you can call to continue executing the operation +To create a query API hook plugin, call `$use` and pass an object that defines an `onQuery` callback. The callback receives a context object with: + +- `model` — the model being queried +- `operation` — the operation (e.g., `create`, `findUnique`, etc.) +- `queryArgs` — the arguments of the query +- `ormClient` — the ORM client instance that triggered the query +- `proceed` — a function to call to continue executing the operation
21-21: Clarify scope and add cross-reference to builder-level hooks.Adds a quick “See also” link to the builder-level (Kysely) hooks page to prevent confusion about where hooks are applied.
-As its name suggests, query API hooks are only triggered by ORM query calls, not by query builder API calls. +As its name suggests, query API hooks are only triggered by ORM query calls, not by query builder API calls. See also: [Kysely Query Hooks](./kysely-query-hooks).
5-5: Verify StackBlitz start script name in the sample repoI couldn't complete the check because the local clone ~/dev/v3-doc-orm was not found (script output: "Local clone of zenstackhq/v3-doc-orm not found; skip verification.").
- File to check: versioned_docs/version-3.x/orm/plugins/query-api-hooks.md
Context (line ~5):import StackBlitzGithubEmbed from '@site/src/components/StackBlitzGithubEmbed';
The embedded StackBlitz must reference the sample repo's npm script (expected name:query-api-hooks).Quick local checks (run in the sample repo root):
- Show the script value (fails non‑zero if missing):
jq -e -r '.scripts["query-api-hooks"]' package.json || echo "script not found"- Or list scripts and search:
jq -r '.scripts | keys[]' package.json | rg -x 'query-api-hooks' || echo "script not found"If the script is missing or renamed, either add/restore
query-api-hooksto package.json or update the embed to use the actual script name so the StackBlitz boots correctly.versioned_docs/version-3.x/orm/inferred-types.md (2)
1-4: Frontmatter looks good; consider explicit title/keywords for consistency and SEOOptional: add
titleandkeywordsto keep consistency with other docs and help search.--- sidebar_position: 14 description: TypeScript types derived from the ZModel schema --- +title: Schema-Inferred Types +keywords: + - typescript + - types + - orm + - zenstack
24-26: Add a fallback link for non-JS/blocked-embed environmentsProvide a plain link so users can access the sample when embeds fail or JS is disabled.
<StackBlitzGithubEmbed repoPath="zenstackhq/v3-doc-orm" openFile="inferred-types.ts" startScript="generate" /> + +If the embed doesn't load, view the sample on GitHub: +[inferred-types.ts](https://github.com/zenstackhq/v3-doc-orm/blob/main/inferred-types.ts).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
versioned_docs/version-3.x/orm/inferred-types.md(1 hunks)versioned_docs/version-3.x/orm/plugins/query-api-hooks.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md
[grammar] ~15-~15: There might be a mistake here.
Context: ...ining the following fields: - The model - The operation - The query args - The ORM...
(QB_NEW_EN)
[grammar] ~16-~16: There might be a mistake here.
Context: ...ing fields: - The model - The operation - The query args - The ORM client that tri...
(QB_NEW_EN)
[grammar] ~17-~17: There might be a mistake here.
Context: ...e model - The operation - The query args - The ORM client that triggered the query ...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ... The ORM client that triggered the query - A "proceed query" function, which you ca...
(QB_NEW_EN)
🔇 Additional comments (2)
versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (1)
25-25: StackBlitz sample now points to the correct Query API Hooks example — LGTMThe embed correctly targets plugins/query-api-hooks.ts with startScript generate,query-api-hooks, resolving the earlier mismatch with the Kysely hooks sample.
versioned_docs/version-3.x/orm/inferred-types.md (1)
6-6: No action needed — .md files already support MDX imports hereStackBlitzGithubEmbed exists and is default-exported, and multiple .md docs in the same directory already import site components, so leaving this file as .md is fine.
- src/components/StackBlitzGithubEmbed.tsx — contains
export default StackBlitzGithubEmbed;(line ~84)- versioned_docs/version-3.x/orm/*.md — several files (e.g., quick-start.md, query-builder.md, polymorphism.md, inferred-types.md) import StackBlitzGithubEmbed
| - `zenstack/models` | ||
|
|
||
| The `zen generate` command generates a `models` module that exports types for all models, types, and enums. The model types include all scalar fields (including computed ones). | ||
|
|
||
| - `zenstack/input` | ||
|
|
||
| The `zen generate` command generates an `input` module that exports types for input arguments of the ORM methods, such as `UserCreateArgs`, `PostUpsertArgs`, etc. You can use them to type intermediary variables that are later passed to the ORM methods. | ||
|
|
||
| - `ModelResult` | ||
|
|
||
| The `ModelResult` generic type from `@zenstackhq/runtime` allows you to infer the exact model type given field selection and relation inclusion information. | ||
|
|
There was a problem hiding this comment.
Fix list item formatting: 4-space indent renders as code blocks, not paragraphs
The descriptions under each bullet are indented by 4 spaces, which CommonMark treats as code blocks. Inline the descriptions or use 2-space indent under the list item.
Apply:
-- `zenstack/models`
-
- The `zen generate` command generates a `models` module that exports types for all models, types, and enums. The model types include all scalar fields (including computed ones).
+- `zenstack/models`: The `zen generate` command generates a `models` module that exports types for all models, types, and enums. The model types include all scalar fields (including computed ones).
-- `zenstack/input`
-
- The `zen generate` command generates an `input` module that exports types for input arguments of the ORM methods, such as `UserCreateArgs`, `PostUpsertArgs`, etc. You can use them to type intermediary variables that are later passed to the ORM methods.
+- `zenstack/input`: The `zen generate` command generates an `input` module that exports types for input arguments of the ORM methods, such as `UserCreateArgs`, `PostUpsertArgs`, etc. You can use them to type intermediary variables that are later passed to the ORM methods.
-- `ModelResult`
-
- The `ModelResult` generic type from `@zenstackhq/runtime` allows you to infer the exact model type given field selection and relation inclusion information.
+- `ModelResult`: The `ModelResult` generic type from `@zenstackhq/runtime` allows you to infer the exact model type given field selection and relation inclusion information.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `zenstack/models` | |
| The `zen generate` command generates a `models` module that exports types for all models, types, and enums. The model types include all scalar fields (including computed ones). | |
| - `zenstack/input` | |
| The `zen generate` command generates an `input` module that exports types for input arguments of the ORM methods, such as `UserCreateArgs`, `PostUpsertArgs`, etc. You can use them to type intermediary variables that are later passed to the ORM methods. | |
| - `ModelResult` | |
| The `ModelResult` generic type from `@zenstackhq/runtime` allows you to infer the exact model type given field selection and relation inclusion information. | |
| - `zenstack/models`: The `zen generate` command generates a `models` module that exports types for all models, types, and enums. The model types include all scalar fields (including computed ones). | |
| - `zenstack/input`: The `zen generate` command generates an `input` module that exports types for input arguments of the ORM methods, such as `UserCreateArgs`, `PostUpsertArgs`, etc. You can use them to type intermediary variables that are later passed to the ORM methods. | |
| - `ModelResult`: The `ModelResult` generic type from `@zenstackhq/runtime` allows you to infer the exact model type given field selection and relation inclusion information. |
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/inferred-types.md around lines 12 to 23: The list
item descriptions are indented by 4 spaces causing them to be rendered as code
blocks; change the formatting by removing the 4-space indentation and either
inline each description on the same line as its bullet or use a 2-space indent
under each bullet so they render as normal paragraph text in CommonMark.
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (3)
versioned_docs/version-3.x/orm/api/filter.md (1)
36-39: Previous “hasNone” inconsistency appears resolvedThe bullet list now omits “hasNone” and examples align with supported operators. This addresses the earlier inconsistency flagged in prior review comments.
versioned_docs/version-3.x/orm/index.md (1)
48-48: Fix malformed code fence for zmodel block (breaks MDX parsing)The extra double quote after zmodel breaks Markdown/MDX parsing and syntax highlighting.
-```zmodel" +```zmodelversioned_docs/version-3.x/modeling/index.md (1)
18-18: Previous typo resolved (“Prisma”)The earlier “Prima” typo noted in a prior review is fixed here. All good.
🧹 Nitpick comments (39)
versioned_docs/version-3.x/orm/migration.md (9)
8-8: Tighten wording and punctuation for the intro sentenceMinor phrasing/punctuation improvement for flow.
-Database schema migration is a crucial aspect of application development. It helps you keep your database schema in sync with your data model, and ensures deployments are smooth and predictable. ZenStack provides migration tools that create migration scripts based on the ZModel schema and apply them to the database. +Database schema migration is a crucial aspect of application development. It helps keep your database schema in sync with your data model and ensures deployments are smooth and predictable. ZenStack provides tools that create migration scripts based on your ZModel schema and apply them to the database.
12-13: Clarify “Prisma CLI” phrasingAdd “command” to make the sentence precise.
-ZenStack migration is built on top of [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate). The `zen` CLI provides a set of migration-related commands that are simple wrappers around Prisma CLI. When running these commands, the CLI automatically generates a Prisma schema from ZModel, and then executes the corresponding Prisma CLI. +ZenStack migration is built on top of [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate). The `zen` CLI provides a set of migration-related commands that are simple wrappers around the Prisma CLI. When running these commands, the CLI automatically generates a Prisma schema from your ZModel, and then executes the corresponding Prisma CLI command.
14-19: Grammar: “Basing on” and “wheels”Fix awkward phrasing and pluralization.
-Basing on Prisma Migrate brings the following benefits: +Building on top of Prisma Migrate brings the following benefits: -- **No reinventing the wheels**: Prisma Migrate is a mature and widely used migration tool, ensuring reliability and stability. +- **No reinventing the wheel**: Prisma Migrate is a mature and widely used migration tool, ensuring reliability and stability. - **Backward compatibility**: When migrating from Prisma to ZenStack, you can continue using your existing migration scripts without any changes.
20-21: Style: minor polish to closing phraseSmoother phrasing.
-If you are already familiar with Prisma Migrate, you can continue using your current workflow with ZenStack, simply swapping `prisma` CLI with `zen`. If not, this section will guide you through the commands and common workflows, but it's strongly recommended to check [Prisma Migrate documentation](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/overview) for in-depth information too. +If you are already familiar with Prisma Migrate, you can continue using your current workflow with ZenStack by simply swapping the `prisma` CLI with `zen`. If not, this section will guide you through the commands and common workflows, but it's strongly recommended to check the [Prisma Migrate documentation](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/overview) for in-depth information as well.
28-29: Call out production caveat more prominentlyThe “never use in production” warning is important; consider a Docusaurus admonition to make it stand out.
-The `zen db push` command is used to push your ZModel schema changes to the database without creating a migration file. This is useful for development and testing purposes. Never use it in production. +The `zen db push` command is used to push your ZModel schema changes to the database without creating a migration file. This is useful for development and testing purposes. + +:::caution +Never use `zen db push` in production. It can make destructive changes without generating a migration history. +:::
32-33: Mention create-only flow for code reviewAdd a tip about creating a migration without applying it, which helps teams review SQL before it touches dev DBs.
-The `zen migrate dev` command is used to create a new migration file based on your ZModel schema changes. It will also apply the migration to your database. The command is for development only and should never be used in production. +The `zen migrate dev` command is used to create a new migration file based on your ZModel schema changes. It will also apply the migration to your database. The command is for development only and should never be used in production. + +Tip: To generate a migration without applying it (useful for code review), run: +``` +zen migrate dev --create-only +```
40-41: Emphasize that reset is destructiveAdd a danger admonition to make the data-loss risk unmistakable.
-The `zen migrate reset` command is used to reset your database to a clean state by dropping all tables and reapplying all migrations. This is useful for testing and development purposes. +The `zen migrate reset` command resets your database to a clean state by dropping all tables and reapplying all migrations. This is useful for testing and development. + +:::danger +This is a destructive operation that permanently deletes all data in the database. Use only in development or ephemeral test environments. +:::
54-58: Fix typo: “promoted” → “prompted”; tighten step phrasingAlso aligns with the style hint to make the step more direct.
-1. Make changes to your ZModel schema. +1. Edit your ZModel schema. 2. Run `zen db push` to push the changes to your database without creating a migration file. 3. Test the changes locally. -4. Run `zen migrate dev` to create a migration file. You'll be promoted if a full reset is needed. +4. Run `zen migrate dev` to create a migration file. You'll be prompted if a full reset is needed. 5. Carefully review the migration file, make changes as needed, and commit it to source control.
62-63: Optional: Mention env/config prerequisites for deployA small addition can help users avoid common CI/CD pitfalls.
-The most common practice is to run `zen migrate deploy` as part of your production deployment pipeline, which simply applies all pending migrations to the database. +The most common practice is to run `zen migrate deploy` as part of your production deployment pipeline, which simply applies all pending migrations to the database. Ensure the correct `DATABASE_URL` (or equivalent connection config) is provided and that migration files are checked into version control.versioned_docs/version-3.x/orm/api/filter.md (7)
11-11: Tighten wording and fix parallelism in intro sentenceCurrent sentence mixes clauses (“find records, selecting relations...”). Suggested rewrite for clarity and parallel structure.
-Filtering is an important topic because it's involved in many ORM operations, for example when you find records, selecting relations, and updating or deleting multiple records. +Filtering is important because it’s involved in many ORM operations—for example, finding records, selecting relations, and updating or deleting multiple records.
17-22: Polish operators list formatting; fix “AND semantic” → “AND semantics”
- Use commas between operators for readability.
- Ensure punctuation consistency.
- “AND semantics” is the conventional phrasing.
-- `equals` `not`: all scalar fields. - - `in` `notIn`: all scalar fields +- `equals`, `not`: all scalar fields. +- `in`, `notIn`: all scalar fields. - `contains` `startsWith` `endsWith`: String fields - `lt` `lte` `gt` `gte`: String, Int, BigInt, Float, Decimal, and Date fields @@ -A filter object can contain multiple field filters, and they are combined with `AND` semantic. You can also use the `AND`, `OR`, and `NOT` logical operators to combine filter objects to form a complex filter. +A filter object can contain multiple field filters, and they are combined with `AND` semantics. You can also use the `AND`, `OR`, and `NOT` logical operators to combine filter objects to form a complex filter.Please confirm whether the type should be “Date” or “DateTime” in ZenStack v3’s zmodel terminology here to stay consistent with the rest of the docs and API.
28-29: Format relation operators with code-style backticks (consistency with elsewhere)Operators are currently quoted with ASCII quotes; elsewhere you use backticks.
-Filters can be defined on conditions over relations. For one-to-one relations, you can filter on their fields directly. For one-to-many relations, use the "some", "every", or "none" operators to build a condition over a list of records. +Filters can be defined on conditions over relations. For one-to-one relations, you can filter on their fields directly. For one-to-many relations, use the `some`, `every`, or `none` operators to build a condition over a list of records.
41-43: Minor grammar: pluralize “type” and prefer “on PostgreSQL”Small wording tweak for natural phrasing.
-List type is only supported for PostgreSQL. +List types are only supported on PostgreSQL.
70-74: Capitalize JSON and improve WIP notice grammarUse “JSON” consistently and add “a” before “work in progress”.
-## Json filters +## JSON filters @@ -:::info WORK IN PROGRESS -Filtering on Json fields is work in progress and will be available soon. +:::info WORK IN PROGRESS +Filtering on JSON fields is a work in progress and will be available soon. :::
82-84: Avoid repetition in sentence about $exprSmoother phrasing without repeating “express.”
-ZenStack v3 is implemented on top of [Kysely](https://kysely.dev/), and it leverages Kysely's powerful query builder API to extend the filtering capabilities. You can use the `$expr` operator to define a boolean expression that can express almost everything that can be expressed in SQL. +ZenStack v3 is implemented on top of [Kysely](https://kysely.dev/), and it leverages Kysely’s powerful query builder API to extend filtering capabilities. You can use the `$expr` operator to define boolean expressions covering nearly everything expressible in SQL.
52-68: Optional: add a “none of these values” example using NOT + hasSomeSince “hasNone” isn’t listed/supported, consider including the common pattern for “none of these values” to help users discover it.
await db.post.findMany({ where: { topics: { hasEvery: ['webdev', 'typescript'] } } }); await db.post.findMany({ where: { topics: { isEmpty: true } } }); + +// posts that do not contain any of the given topics +await db.post.findMany({ + where: { NOT: { topics: { hasSome: ['webdev', 'typescript'] } } } +});versioned_docs/version-3.x/orm/api/create.md (3)
1-4: Optional frontmatter enhancements for SEO/consistencyConsider explicitly setting a page title and adding keywords to improve discoverability and keep frontmatter consistent across the v3 API docs pages.
--- sidebar_position: 2 description: Create API +title: Create +keywords: + - orm + - create + - createMany + - batch + - api ---
10-17: Tighten wording and fix subject-verb agreementSimplify wording and fix “series of APIs are … It has …” mismatch. Also avoids the “new records” verbosity flagged by static analysis.
-The `create` series of APIs are used to create new records in the database. It has the following methods: +The Create API provides the following methods:
12-17: Consistent punctuation/style in list itemsAll bullet descriptions already end with periods—nice. Consider capitalizing consistently (“Create …” vs “Similar …”) or switch to sentence case for all. Minor, but improves polish across API pages.
versioned_docs/version-3.x/orm/index.md (7)
69-69: Grammar: subject–verb agreement (“involve” not “involves”)Minor grammar fix for clarity.
-Real-world applications often involves storing polymorphic data which is notoriously complex to model and query. ZenStack does the heavy-lifting for you so you can model an inheritance hierarchy with simple annotations, and query them with perfect type safety. +Real-world applications often involve storing polymorphic data, which is notoriously complex to model and query. ZenStack does the heavy lifting for you so you can model an inheritance hierarchy with simple annotations and query them with perfect type safety.
46-46: Hyphenation: “database-specific”Use a hyphen for the compound modifier.
-ZenStack ORM comes with a powerful built-in access control system. You can define access rules right inside the schema. The rules are enforced at runtime via query injection, so it doesn't rely on any database specific row-level security features. +ZenStack ORM comes with a powerful built-in access control system. You can define access rules right inside the schema. The rules are enforced at runtime via query injection, so it doesn't rely on any database-specific row-level security features.
97-99: Use “lightweight” (heading and body)“Light-Weighted/light-weighted” reads awkwardly; “lightweight” is the conventional term.
-### Straightforward and light-Weighted +### Straightforward and lightweight-Compared to Prisma and previous versions of ZenStack, v3 is more straightforward and light-weighted. +Compared to Prisma and previous versions of ZenStack, v3 is more straightforward and lightweight.
93-93: Consistent terminology: change “asset” to “content”Aligns the comment with the model and variable name used in the example.
- // other asset type + // other content type
16-16: Tighten tone and wording; avoid informal phrasingRemoves “pretty much,” uses present tense for “replicates,” and streamlines wording.
-ZenStack v3 is inspired by Prisma ORM but it has a completely different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicated Prisma ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you're not a Prisma user, the query API is very intuitive and easy to learn. +ZenStack v3 is inspired by Prisma ORM but has a different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicates Prisma ORM's query API so that you can use it as a drop-in replacement. Even if you're not a Prisma user, the query API is intuitive and easy to learn.
10-10: Prefer a more formal tone (“learned”, avoid “awesome”)Polish wording for a more professional docs tone.
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an awesome developer experience by combining the best ingredients into a cohesive package. +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It has learned from prior art and strives to provide an excellent developer experience by combining the best ingredients into a cohesive package.-Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive code samples. StackBlitz's [WebContainers](https://webcontainers.io/) is an awesome technology that allows you to run a Node.js environment inside the browser. The embedded samples use the [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use. +Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive code samples. StackBlitz's [WebContainers](https://webcontainers.io/) is an impressive technology that allows you to run a Node.js environment inside the browser. The embedded samples use [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use.Also applies to: 109-109
102-102: Clarify phrasing: “No magic generation into node_modules”Reads more naturally.
-- No magic generating into `node_modules`. You fully control how the generated code is compiled and bundled. +- No magic generation into `node_modules`. You fully control how the generated code is compiled and bundled.versioned_docs/version-3.x/orm/api/find.md (5)
11-11: Grammar: subject-verb agreement and clarity.Use singular agreement with “series” or simplify the subject.
-The `find` series of APIs are used to query records from the database. It has the following methods: +The `find` series of APIs is used to query records from the database. It includes the following methods:
17-20: Word choice: “criteria” (plural) vs “criterion” (singular).A single unique key/constraint is a “criterion”.
- Find a single record with a unique criteria. + Find a single record with a unique criterion.
25-31: Document error type for OrThrow variants.It’s useful to specify the exact error class (and code) these methods throw so users can catch/handle it reliably.
Example addition (adjust to actual runtime behavior):
- “Throws NotFoundError (code: 'P2025') when no record is found.”
43-46: Clarify nulls sort semantics and provider support.You mention controlling “null field placement.” Consider adding a brief example for nullsFirst/nullsLast and note provider-specific behavior if any, since NULLS FIRST/LAST support differs across SQL dialects.
Optional example to append:
- “Example: sort: [{ createdAt: { direction: 'desc', nulls: 'last' } }]”
49-52: Cursor pagination usually requires a deterministic sort; call it out.Cursor-based pagination typically assumes a unique and deterministic ordering (e.g., sort by a unique field). Mentioning this avoids subtle paging bugs.
Suggested addition:
- “When using cursor-based pagination, specify a deterministic sort (e.g., by a unique field) to ensure stable page boundaries.”
versioned_docs/version-3.x/modeling/index.md (3)
10-10: Tighten wording and fix minor grammarStreamline phrasing and fix pluralization.
-ZenStack uses a schema language named **ZModel** to define data models and their related aspects. We know that designing a good schema language is difficult, and we know it's even more difficult to convince people to learn a new one. So we made the decision to design ZModel as a superset of the [Prisma Schema Language (PSL)](https://www.prisma.io/docs/orm/prisma-schema), which is one of the best data modeling language out there. +ZenStack uses a schema language named **ZModel** to define data models and their related aspects. We know that designing a good schema language is difficult, and it's even more difficult to convince people to learn a new one. So we decided to design ZModel as a superset of the [Prisma Schema Language (PSL)](https://www.prisma.io/docs/orm/prisma-schema), which is one of the best data modeling languages out there.
15-16: Pluralization: “quotes”Small grammar tweak for clarity.
-ZModel allows both single quote and double quote for string literals. +ZModel allows both single and double quotes for string literals.
47-50: Verify link targets and present-tense wording
- Confirm the relative link to the Plugin section is correct:
./pluginshould resolve to the intended page withinmodeling/.- Optional: present-tense reads a bit smoother for general docs (“replaces” instead of “replaced”).
-ZenStack CLI always generates a TypeScript schema without needing any configuration. Also, it replaced PSL's "generator" with a more generalized "plugin" construct that allows you to extend the system both at the schema level and the runtime level. Read more in the [Plugin](./plugin) section. +ZenStack CLI always generates a TypeScript schema without needing any configuration. Also, it replaces PSL's "generator" with a more generalized "plugin" construct that allows you to extend the system both at the schema level and the runtime level. Read more in the [Plugin](./plugin) section.versioned_docs/version-3.x/modeling/datasource.md (2)
10-10: Title consistency with block nameUse “Datasource” to align with the ZModel block name and related docs.
-# Data Source +# Datasource
38-38: Fix brand casing and wording“MySql” → “MySQL”; also use plural for “plans.”
-Currently only PostgreSQL and SQLite are supported. MySql will be supported in a future release. There's no plan for other relational database types or NoSQL databases. +Currently, only PostgreSQL and SQLite are supported. MySQL will be supported in a future release. There are no plans for other relational database types or NoSQL databases.versioned_docs/version-3.x/orm/computed-fields.md (3)
21-21: Grammar: “a computed fields” → “a computed field”Small fix for readability.
Apply this diff:
-Defining a computed fields involves two steps. First, add the field in the ZModel schema to a model and annotate it with an extra `@computed` attribute. +Defining a computed field involves two steps. First, add the field to a model in the ZModel schema and annotate it with the `@computed` attribute.
39-43: Align computed field alias with field name (“postCount”)The example aliases the count as "count" while the field is named "postCount". Aligning the alias avoids confusion and better reflects how most ORMs map computed selections.
Apply this diff:
- .select(({fn}) => fn.countAll<number>().as('count')), + .select(({ fn }) => fn.countAll<number>().as('postCount')),
12-15: List rendering inside custom component: add a blank line for reliable markdown parsingAdding a blank line before the numbered list helps MDX consistently render the list within the component.
Apply this diff:
-Prisma client extensions allow you to define computed fields. ZenStack's approach is very different in two aspects: +Prisma client extensions allow you to define computed fields. ZenStack's approach is very different in two aspects: + 1. Computed fields are evaluated on the database side, not in the client. 2. Computed fields are defined in the schema and can be used in most places where regular fields are used.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (11)
versioned_docs/version-3.x/modeling/datasource.md(1 hunks)versioned_docs/version-3.x/modeling/index.md(1 hunks)versioned_docs/version-3.x/orm/api/create.md(1 hunks)versioned_docs/version-3.x/orm/api/filter.md(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)versioned_docs/version-3.x/orm/computed-fields.md(1 hunks)versioned_docs/version-3.x/orm/index.md(1 hunks)versioned_docs/version-3.x/orm/migration.md(1 hunks)versioned_docs/version-3.x/reference/plugin-dev.md(1 hunks)versioned_docs/version-3.x/utilities/zod.md(1 hunks)versioned_docs/version-3.x/welcome.md(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- versioned_docs/version-3.x/reference/plugin-dev.md
- versioned_docs/version-3.x/utilities/zod.md
🚧 Files skipped from review as they are similar to previous changes (1)
- versioned_docs/version-3.x/welcome.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/migration.md
[style] ~54-~54: Consider shortening or rephrasing this to strengthen your wording.
Context: ...w ### Typical development workflow 1. Make changes to your ZModel schema. 2. Run `zen db push...
(MAKE_CHANGES)
versioned_docs/version-3.x/modeling/index.md
[style] ~10-~10: Consider shortening this phrase to avoid wordiness.
Context: ...nvince people to learn a new one. So we made the decision to design ZModel as a superset of the [...
(MAKE_THE_CHOICE_TO)
[style] ~19-~19: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...el, so no prior knowledge is required. A very simple ZModel schema looks like this: ```zmod...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/modeling/datasource.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...del --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; im...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...'; import TabItem from '@theme/TabItem'; import ZModelVsPSL from '../_components/...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/api/create.md
[style] ~10-~10: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ...eate` series of APIs are used to create new records in the database. It has the following m...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
versioned_docs/version-3.x/orm/api/filter.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...om '../../_components/ZenStackVsPrisma'; import StackBlitzGithubEmbed from '@site...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...# Json filters :::info WORK IN PROGRESS Filtering on Json fields is work in prog...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ... in progress and will be available soon. ::: ## Query builder filters <ZenStack...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/api/find.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...e/src/components/StackBlitzGithubEmbed'; import SelectIncludeOmit from './_select...
(QB_NEW_EN)
[style] ~23-~23: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...nique criteria. - findFirst Find the first record that matches the query...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~63-~63: There might be a mistake here.
Context: ...QL DISTINCT ON, so it's not available for SQLite provider. ```ts // returns one ...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/computed-fields.md
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithubEmbed from '@site...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/index.md
[style] ~10-~10: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...m the prior arts and strives to provide an awesome developer experience by combining the b...
(AWESOME)
[style] ~16-~16: Consider using a different adverb to strengthen your wording.
Context: ...v3 is inspired by Prisma ORM but it has a completely different implementation (based on [Kys...
(COMPLETELY_ENTIRELY)
[style] ~16-~16: The phrase ‘pretty much’ can be informal. To strengthen your writing, consider removing it or replacing it with an adverb.
Context: ... ORM's query API so that you can use it pretty much as a drop-in replacement. Even if you'r...
(PRETTY_MUCH)
[grammar] ~101-~101: There might be a mistake here.
Context: ... no overhead of Rust/WASM query engines. - No magic generating into node_modules....
(QB_NEW_EN)
[style] ~109-~109: Consider using a more formal and expressive alternative to ‘awesome’.
Context: ...ntainers](https://webcontainers.io/) is an awesome technology that allows you to run a Nod...
(AWESOME)
🔇 Additional comments (10)
versioned_docs/version-3.x/orm/migration.md (2)
22-49: Commands section reads well and matches Prisma semanticsGood coverage and accurate high-level guidance for each command.
24-25: CLI reference and "Migrating from Prisma" pages verified for version-3.x — no action neededConfirmed the referenced CLI page and migration doc exist and the cross-links are correct.
- versioned_docs/version-3.x/reference/cli.md — FOUND (CLI Reference content present)
- versioned_docs/version-3.x/orm/migration.md:24 — links to ../reference/cli.md
- versioned_docs/version-3.x/orm/cli.md:24 — links to ../reference/cli.md
- versioned_docs/version-3.x/migrate-prisma.md — "Migrating From Prisma" page FOUND
Original snippet is valid:
Please refer to the [CLI Reference](../reference/cli.md) for the full list of commands and options.versioned_docs/version-3.x/orm/api/filter.md (1)
6-8: MDX imports look correctMDX-style imports for local components and site aliasing are valid here. The LanguageTool grammar hints can be ignored for these lines.
versioned_docs/version-3.x/orm/api/create.md (1)
8-18: Overall: concise and clear—nice additionContent accurately distinguishes single vs. batch creates and return shapes. The embedded sample is a good touch for quick verification.
versioned_docs/version-3.x/orm/index.md (1)
87-95: Good fix: TypeScript example now matches the schemaThe example now queries db.content and uses findFirstOrThrow(), which aligns with the declared models and removes the earlier inconsistency.
versioned_docs/version-3.x/orm/api/find.md (3)
63-68: Provider support for DISTINCT ON likely broader issue; please verify and correct.The text states implementation “relies on SQL DISTINCT ON” and is “not available for SQLite provider.” DISTINCT ON is PostgreSQL-specific; MySQL and SQL Server don’t support DISTINCT ON, and SQLite supports DISTINCT but not DISTINCT ON. Unless your ORM emulates this behavior on non-PG providers, this statement is likely incomplete/misleading.
Proposed safer wording (adjust based on actual support):
-You can use the `distinct` field to find distinct rows based on specific fields. One row for each unique combination of the specified fields will be returned. The implementation relies on SQL `DISTINCT ON`, so it's not available for SQLite provider. +You can use the `distinct` field to return one row for each unique combination of the specified fields. +On PostgreSQL-compatible providers, this is implemented via `DISTINCT ON` (optionally combined with `orderBy` to control which row is kept). +This option is not available on providers that don't support `DISTINCT ON` (e.g., SQLite, MySQL), unless otherwise emulated by the ORM.Also minor grammar:
-... it's not available for SQLite provider. +... it's not available for the SQLite provider.If emulation exists for other providers (via window functions or GROUP BY/ANY_VALUE), please document the exact semantics and limitations (e.g., which row is chosen).
33-36: Nice use of live StackBlitz embeds for examples.The embedded samples for basic usage, sorting, pagination, and selection make the docs actionable.
Also applies to: 41-46, 47-52, 53-60
6-7: Script queued. Run results will be provided.versioned_docs/version-3.x/modeling/datasource.md (1)
41-42: Verify cross-reference to ORM sectionConfirm
../orm/resolves correctly within the v3.x docs structure and points to the intended page.versioned_docs/version-3.x/orm/computed-fields.md (1)
32-46: Double-check cross-table reference in Kysely snippetThe example uses whereRef('Post.authorId', '=', 'User.id') while selecting only from Post. This likely relies on ZenStack’s runtime to provide an outer User scope (e.g., via a lateral join). If that context isn’t present, Kysely would normally require both tables in scope.
Please confirm that the computedFields callback receives an expression builder with the outer User reference in scope. If not, consider joining/using a correlated subquery explicitly in the snippet so users can copy-paste successfully.
| author User @relation(fields: [authorId], references: [id]) | ||
| authorId String | ||
| } |
There was a problem hiding this comment.
Fix schema example: relation field type mismatch
User.id is Int, but Post.authorId is String. This mismatch will break the relation in practice and can confuse readers.
model Post {
id Int @id @default(autoincrement())
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
title String
content String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
- authorId String
+ authorId Int
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| author User @relation(fields: [authorId], references: [id]) | |
| authorId String | |
| } | |
| model Post { | |
| id Int @id @default(autoincrement()) | |
| createdAt DateTime @default(now()) | |
| updatedAt DateTime @updatedAt | |
| title String | |
| content String | |
| published Boolean @default(false) | |
| author User @relation(fields: [authorId], references: [id]) | |
| authorId Int | |
| } |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/modeling/index.md around lines 41 to 43, the
Prisma schema example has a type mismatch where User.id is Int but Post.authorId
is String; update the schema so the relation types match (e.g., change
Post.authorId to Int to match User.id) and ensure the @relation declaration
still references the correct field names.
| - `create` | ||
| Create a single record, optionally with nested relations. | ||
| - `createMany` | ||
| Create multiple records in a single operation. Nested relations are not supported. Only the number of records created is returned. | ||
| - `createManyAndReturn` | ||
| Similar to `createMany`, but returns the created records. |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Add limitations/notes to set expectations (batch behavior, nested writes, return values)
A short “Notes” section helps prevent misuse (e.g., expecting nested writes in createMany or returning large payloads from createManyAndReturn). Place it after the list.
- `createManyAndReturn`
Similar to `createMany`, but returns the created records.
+### Notes
+
+- `createMany` does not support nested writes.
+- `createMany` returns only the count of created records.
+- `createManyAndReturn` returns created records; for large batches, consider performance and payload size.
+- Connector support and available fields for `createManyAndReturn` may vary; verify the behavior for your database/ORM version.
+If you want to verify connector/feature coverage within this repo’s docs or code, run:
🏁 Script executed:
#!/bin/bash
# Find references to `createManyAndReturn` to ensure behavior is consistently documented.
rg -n -C3 '\bcreateManyAndReturn\b'
# Cross-check other API pages to keep terminology aligned (e.g., "nested writes" vs "nested relations").
rg -n -C2 -g 'versioned_docs/**/orm/api/*.md' -e 'nested (writes|relations)'Length of output: 1895
Add a short "Notes" section to clarify createMany / createManyAndReturn behavior
Verified with ripgrep: create.md already states nested relations are not supported and that createMany returns a count; createManyAndReturn appears only in versioned_docs/version-3.x/orm/api/create.md. Add a consolidated Notes block after the list (before "## Samples") to set expectations.
- File to update:
- versioned_docs/version-3.x/orm/api/create.md — insert after the create/createMany/createManyAndReturn list
Suggested diff to add:
- `createManyAndReturn`
Similar to `createMany`, but returns the created records.
+### Notes
+
+- `createMany` does not support nested relations.
+- `createMany` returns only the count of created records.
+- `createManyAndReturn` returns created records; for large batches, consider performance and payload size.
+- Connector support and available fields for `createManyAndReturn` may vary; verify behavior for your database/connector.
+📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - `create` | |
| Create a single record, optionally with nested relations. | |
| - `createMany` | |
| Create multiple records in a single operation. Nested relations are not supported. Only the number of records created is returned. | |
| - `createManyAndReturn` | |
| Similar to `createMany`, but returns the created records. | |
| - `create` | |
| Create a single record, optionally with nested relations. | |
| - `createMany` | |
| Create multiple records in a single operation. Nested relations are not supported. Only the number of records created is returned. | |
| - `createManyAndReturn` | |
| Similar to `createMany`, but returns the created records. | |
| ### Notes | |
| - `createMany` does not support nested relations. | |
| - `createMany` returns only the count of created records. | |
| - `createManyAndReturn` returns created records; for large batches, consider performance and payload size. | |
| - Connector support and available fields for `createManyAndReturn` may vary; verify behavior for your database/connector. |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/create.md around lines 12 to 17, add a
short "Notes" section immediately after the
create/createMany/createManyAndReturn list (and before the "## Samples" heading)
that clearly states: createMany does not support nested relations and returns
only the number of records created, createManyAndReturn returns the created
records while likewise not supporting nested relations, and any constraints or
performance considerations (briefly) such as transactional/atomic differences;
insert the Notes block as plain markdown with a heading "Notes" and 2–4 concise
bullet points summarizing these behaviors.
|
|
||
| ## Samples | ||
|
|
||
| <StackBlitzGithubEmbed repoPath="zenstackhq/v3-doc-orm" openFile="create.ts" startScript="generate,create" /> |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify StackBlitz embed props and startScript behavior
Double-check that StackBlitzGithubEmbed supports:
openFileas a single file path string.startScriptas a comma-separated string to run multiple scripts in sequence.
If the component expects different prop names or types (e.g., an array for scripts), the embed may fail at runtime.
Run this to confirm the prop interface and usage:
If needed, I can adjust this page and others to match the component’s expected props.
🏁 Script executed:
#!/bin/bash
# Inspect the component’s prop typings/usage.
fd 'StackBlitzGithubEmbed.tsx' src | xargs -I{} sh -c 'echo "=== {} ==="; nl -ba "{}" | sed -n "1,200p"'
# Find where it's used to compare prop shapes across pages.
rg -n -C2 '<StackBlitzGithubEmbed' --type mdx --type md --type tsxLength of output: 273
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== locating component file ==="
fd -HI --hidden --follow 'StackBlitzGithubEmbed.tsx' || true
echo
for f in $(fd -HI --hidden --follow 'StackBlitzGithubEmbed.tsx' || true); do
echo "=== $f ==="
sed -n '1,240p' "$f" || true
done
echo
echo "=== searching for usages of the component ==="
rg -n -C2 'StackBlitzGithubEmbed' --hidden --glob '!**/node_modules/**' --glob '!**/dist/**' || trueLength of output: 20603
I'll fetch additional docs if needed based on the results.
Verify StackBlitz embed props and startScript behavior
The component props are defined as:
- openFile?: string
- startScript?: string
I confirmed src/components/StackBlitzGithubEmbed.tsx passes those values directly to sdk.embedGithubProject.
However, the StackBlitz SDK documents startScript as a single script name (string). There is no documented support for a comma-separated list of scripts. Passing "generate,create" is therefore unsupported and likely won't run both scripts in sequence.
Actions:
- Replace comma-separated startScript values with a single script name, or use a single command that chains scripts (e.g. "npm run generate && npm run create") if the SDK accepts full commands — otherwise create a single npm script in the sample repo that runs both steps.
- Files to update:
- versioned_docs/version-3.x/orm/api/create.md (line with startScript="generate,create")
- versioned_docs/version-3.x/orm/query-builder.md (and other docs that use comma-separated startScript values; ripgrep shows many occurrences)
Suggested edit example (update the embed props):
- From:
- To (option A, preferred — single npm script in the project):
- Or (option B, if SDK accepts shell commands — verify manually):
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/create.md around line 21, the StackBlitz
embed uses startScript="generate,create" which passes a comma-separated list
unsupported by the StackBlitz SDK; change the embed to use a single startScript
value (preferred: a single npm script name like "generate-and-create") and
add/update the corresponding npm script in the zenstackhq/v3-doc-orm sample repo
to run both steps, or if you verify the SDK accepts full shell commands, replace
it with a single chained command (e.g., "npm run generate && npm run create");
also search and fix other docs (e.g.,
versioned_docs/version-3.x/orm/query-builder.md) that use comma-separated
startScript values and standardize them to a single script name or chained
command.
| import ZenStackVsPrisma from '../_components/ZenStackVsPrisma'; | ||
| import StackBlitzGithubEmbed from '@site/src/components/StackBlitzGithubEmbed'; | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
MDX features used in a .md file — this will not compile in Docusaurus
This file uses imports and JSX components, which require an .mdx extension. With a .md extension, Docusaurus won’t process the imports/components and the page will break.
- Rename the file to computed-fields.mdx.
- Alternatively (not recommended), replace components with Markdown/admonitions, but you’d lose interactivity.
If you want to keep it as Markdown, I can propose an admonition-based rewrite; otherwise, confirm the rename so I can scan other v3 docs for similar cases.
Also applies to: 11-15, 50-50
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Locate computed-fields.md ==="
rg -n --hidden -S 'computed-fields.md' || true
echo
echo "=== Show top of versioned_docs/version-3.x/orm/computed-fields.md ==="
sed -n '1,200p' versioned_docs/version-3.x/orm/computed-fields.md || true
echo
echo "=== Search for MDX-like usage (imports or JSX) in versioned_docs/**/*.md ==="
rg -n --hidden --no-ignore -S --glob 'versioned_docs/**/*.md' -n -C2 '^(import |<\s*[A-Za-z])' || true
echo
echo "=== Files with 'import' in versioned_docs ==="
rg -n --hidden --no-ignore -S --glob 'versioned_docs/**/*.md' '^import ' -n -C2 || trueLength of output: 111610
Action required — MDX features detected in .md files: rename to .mdx
This file imports components and uses JSX; Docusaurus requires an .mdx extension for imports/JSX or the page will break.
Files to fix:
- versioned_docs/version-3.x/orm/computed-fields.md — imports at lines ~6–7 and JSX (, ) in the file.
- Other affected v3 docs (use .mdx): versioned_docs/version-3.x/orm/{quick-start.md,client.md,query-builder.md,polymorphism.md,cli.md,api/.md,plugins/.md,index.md,inferred-types.md,computed-fields.md} and versioned_docs/version-3.x/modeling/{index.md,datasource.md,multi-file.md,polymorphism.md,custom-type.md,attribute.md,mixin.md,strong-typed-json.md}.
Example snippet from computed-fields.md:
import ZenStackVsPrisma from '../_components/ZenStackVsPrisma';
import StackBlitzGithubEmbed from '@site/src/components/StackBlitzGithubEmbed';
Recommended action:
- Rename the above .md files to .mdx.
- If you prefer to keep any file as .md, request an admonition/markdown-only rewrite (I can produce one for computed-fields.md).
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithubEmbed from '@site...
(QB_NEW_EN)
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/computed-fields.md lines ~6–8: this .md file
imports React/MDX components and contains JSX which Docusaurus requires to live
in a .mdx file; rename computed-fields.md to computed-fields.mdx (and update any
internal links or references) so the imports (ZenStackVsPrisma,
StackBlitzGithubEmbed) and JSX render correctly; apply the same rename for the
other listed v3 docs that import components or use JSX (move .md → .mdx) or, if
you must keep a file as pure Markdown, remove imports/JSX and request a
markdown-only rewrite/admonition as noted.
Summary by CodeRabbit
New Features
Documentation