docs: v3 docs structure #479
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a v3 documentation set and site components: new versioned docs (modeling, ORM, reference, plugins, utilities), doc UI components and StackBlitz/GitHub embed components, Prism ZModel syntax update, Docusaurus versions update (add 3.x), and git submodule entries for sample repos. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant Doc as Doc Page
participant SB as StackBlitzGithub
participant SDK as StackBlitz SDK
User->>Doc: Click "Open in StackBlitz"
Doc->>SB: invoke onClick(repoPath, openFile, startScript)
SB->>SDK: openGithubProject(repoPath, { openFile, view: "editor", startScript })
SDK-->>User: Opens interactive editor (new tab/window)
sequenceDiagram
autonumber
participant Doc as Doc Page
participant Embed as StackBlitzEmbed
participant SDK as StackBlitz SDK
participant Div as Container Div
Doc->>Embed: render(projectId, height)
Embed->>Div: createRef()
Embed->>Embed: useEffect()
Embed->>SDK: embedProjectId(div, projectId, { openFile:'main.ts', view:'editor', height, forceEmbedLayout:true })
SDK-->>Div: Renders inline embedded editor
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 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.
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rest.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-3.x/reference/server-adapters/api-handlers/rpc.mdx
Outdated
Show resolved
Hide resolved
versioned_docs/version-3.x/reference/server-adapters/fastify.mdx
Outdated
Show resolved
Hide resolved
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.
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.
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: 5> [!CAUTION]
Some comments are outside the diff and can’t be posted inline due to platform limits.
🔭 Outside diff range comments (1)
versioned_docs/version-3.x/modeling/model.md (1)
181-183: “Name mapping” section is incomplete; add examples for @Map and @@MapThe section ends without examples, leaving readers unsure how to apply @map/@@Map. Please add minimal, practical snippets.
Apply this diff to complete the section with examples:
## Name mapping -Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` attribute. The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL. +Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` attribute (field-level) and `@@map` (model-level). The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL. + +```zmodel +model User { + id Int @id @map("user_id") + fullName String @map("full_name") + createdAt DateTime @default(now()) + @@map("app_user") +} +``` + +In this example: +- `User` maps to table `app_user` +- `id` maps to column `user_id` +- `fullName` maps to column `full_name`
♻️ Duplicate comments (3)
versioned_docs/version-3.x/modeling/custom-type.md (1)
45-46: Broken link fixed — thanksThe link now correctly points to typed-json.md. This addresses the earlier review comment.
versioned_docs/version-3.x/reference/zmodel/model.md (2)
19-20: Fix identifier regex typo- Name of the model. Needs to be unique in the entire schema. Needs to be a valid identifier matching regular expression `[A-Za-z][a-za-z0-9_]\*`. + Name of the model. Needs to be unique in the entire schema. Needs to be a valid identifier matching regular expression `[A-Za-z][A-Za-z0-9_]*`.
39-41: Polish “identifier” wording for clarity and grammar-A model must be uniquely identifiable by one or several of its fields. For most cases, you'll have a field marked with the `@id` attribute. If needed, you can use multiple fields as unique identifier by using the `@@id` model-level attribute. +A model must be uniquely identifiable by one or more of its fields. In most cases, you'll have a field marked with the `@id` attribute. If needed, you can use multiple fields as a composite identifier by using the `@@id` model-level attribute. @@ -If no `@id` or `@@id` is specified, field(s) marked with the `@unique` or `@@unique` attribute will be used as fallback identifier. +If no `@id` or `@@id` is specified, the field(s) marked with `@unique` or `@@unique` will be used as the fallback identifier.
🧹 Nitpick comments (4)
versioned_docs/version-3.x/modeling/custom-type.md (4)
11-11: Grammar: pluralize “Custom type”Minor copy edit for correctness/consistency.
-Custom type is a ZModel concept and doesn't exist in PSL. +Custom types are a ZModel concept and don't exist in PSL.
27-28: Terminology: “relation fields” reads more naturallyUse the PSL/ZModel term “relation fields” for consistency.
-Custom types are defined exactly like models, with the exception that they cannot contain fields that are relations to other models. They can, however, contain fields that are other custom types. +Custom types are defined exactly like models, except they cannot contain relation fields to other models. They can, however, contain fields that are other custom types.
18-25: Avoid repeating the Address snippet twiceThe Address type is shown in full in both examples. Consider keeping only the second block (with UserProfile), or referencing the earlier snippet, to reduce duplication and keep the page tighter.
Also applies to: 29-41
8-8: Title casing/plural consistencyHeading reads better as plural to match the concept name used elsewhere.
-# Custom Type +# Custom types
📜 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 (5)
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/model.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/model.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/type.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- versioned_docs/version-3.x/modeling/attribute.md
- versioned_docs/version-3.x/reference/zmodel/type.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/modeling/custom-type.md
[grammar] ~46-~46: There might be a mistake here.
Context: .../mixin.md) - Strongly typed JSON fields
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/model.md
[grammar] ~64-~64: There might be a mistake here.
Context: ...ing ways: 1. Built-in types, including: - String - Boolean - Int - BigInt...
(QB_NEW_EN)
[grammar] ~65-~65: There might be a mistake here.
Context: .... Built-in types, including: - String - Boolean - Int - BigInt - Float ...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...pes, including: - String - Boolean - Int - BigInt - Float - Decimal ...
(QB_NEW_EN)
[grammar] ~67-~67: There might be a mistake here.
Context: ...uding: - String - Boolean - Int - BigInt - Float - Decimal - Date...
(QB_NEW_EN)
[grammar] ~68-~68: There might be a mistake here.
Context: ...String - Boolean - Int - BigInt - Float - Decimal - DateTime - Js...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ... Boolean - Int - BigInt - Float - Decimal - DateTime - Json - Byt...
(QB_NEW_EN)
[grammar] ~70-~70: There might be a mistake here.
Context: ... Int - BigInt - Float - Decimal - DateTime - Json - Bytes - Unsup...
(QB_NEW_EN)
[grammar] ~71-~71: There might be a mistake here.
Context: ...nt - Float - Decimal - DateTime - Json - Bytes - Unsupported T...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...oat - Decimal - DateTime - Json - Bytes - Unsupported The `Unsupp...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...cimal - DateTime - Json - Bytes - Unsupported The Unsupported type...
(QB_NEW_EN)
[grammar] ~149-~149: There might be a mistake here.
Context: ...- now(): returns the current timestamp - cuid(): returns a CUID - uuid(): returns a U...
(QB_NEW_EN)
[grammar] ~150-~150: There might be a mistake here.
Context: ...ent timestamp - cuid(): returns a CUID - uuid(): returns a UUID - ulid(): returns a U...
(QB_NEW_EN)
[grammar] ~151-~151: There might be a mistake here.
Context: ...eturns a CUID - uuid(): returns a UUID - ulid(): returns a ULID - nanoid(): returns a...
(QB_NEW_EN)
[grammar] ~152-~152: There might be a mistake here.
Context: ...eturns a UUID - ulid(): returns a ULID - nanoid(): returns a Nano ID - autoincrement():...
(QB_NEW_EN)
[grammar] ~153-~153: There might be a mistake here.
Context: ...s a ULID - nanoid(): returns a Nano ID - autoincrement(): returns an auto-incrementing integer (...
(QB_NEW_EN)
[grammar] ~154-~154: There might be a mistake here.
Context: ...enting integer (only for integer fields) - dbgenerated("..."): calls a native db function ```zmodel ...
(QB_NEW_EN)
versioned_docs/version-3.x/reference/zmodel/model.md
[grammar] ~39-~39: There might be a mistake here.
Context: ... If needed, you can use multiple fields as unique identifier by using the @@id m...
(QB_NEW_EN)
[grammar] ~41-~41: There might be a mistake here.
Context: ...eor@@unique` attribute will be used as fallback identifier. ## Example ```zm...
(QB_NEW_EN)
🔇 Additional comments (10)
versioned_docs/version-3.x/reference/zmodel/model.md (3)
12-15: If multiple base models are intended, update grammar accordinglyIf polymorphism supports multiple bases, reflect that in the syntax.
-model NAME (with MIXIN_NAME(,MIXIN_NAME)*)? (extends BASE_NAME)? { +model NAME (with MIXIN_NAME(,MIXIN_NAME)*)? (extends BASE_NAME(,BASE_NAME)*)? {
33-36: Keep BASE_NAME description consistent with chosen multiplicityMatch the description with either single or multiple base models.
- If single base model (no change needed).
- If multiple base models:
- Name of a polymorphic base model. + Name of one or more polymorphic base models.
45-56: Example looks good and aligns with the described syntaxversioned_docs/version-3.x/modeling/model.md (7)
6-22: Solid introduction and exemplar model snippetClear, accurate overview of ZModel’s purpose with a concise example that uses common attributes (@id, @default, @updatedat, @unique). Nicely sets the context for the rest of the page.
33-42: Composite ID example looks goodUsing @@id for composite keys is correct and the example is clear and minimal. No issues here.
64-86: Built-in types and Unsupported are documented correctlyGood coverage and a useful example for Unsupported with dbgenerated, properly attributed to Prisma docs.
135-145: Optional vs list clarification is correctClear illustration that
?and[]are mutually exclusive, with a compact, accurate code sample.
165-176: Native type mapping section looks goodAccurate description and a clear example with @db.VarChar(64). No changes needed.
104-116: No action needed: link target existsThe file
versioned_docs/version-3.x/modeling/relation.mdis present, so the./relationlink is correct and will not 404.
44-58: Clarify fallback identifier behavior for models without @idThe documentation currently states that if no
@id/@@idis specified, fields marked with@unique/@@uniquewill be used as the model’s identifier. Please verify whether ZenStack v3 truly supports this fallback in all contexts (migrations, database backends, Prisma client, etc.).Two possible paths:
- If unique-only models are supported, add an explicit NOTE outlining which features/backends support this fallback and any limitations (e.g. migration behavior, unsupported connectors).
- If they are not supported, replace the sentence with a caution that every model needs a primary key (
@id/@@id).Locations to address:
- versioned_docs/version-3.x/modeling/model.md (around line 44)
- versioned_docs/version-3.x/reference/zmodel/model.md (around line 41)
Proposed diff for the modeling guide (assuming primary keys are required):
-If no `@id` or `@@id` is specified, the ORM will resort to using a field (or fields) marked with the `@unique` or `@@unique` attribute as the identifier. +:::caution +Every model must define a primary key using `@id` or `@@id`. +Fields marked with `@unique`/`@@unique` are _not_ treated as true primary keys—use them only for lookup constraints. +:::Please confirm the actual behavior in the ORM and update both guides accordingly.
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (16)
versioned_docs/version-3.x/reference/zmodel/function.md (4)
35-38: Clarify RETURN_TYPE to allow ZModel object types (models/types), not just scalar-likeThe current wording excludes cases like auth() returning a model/type.
Apply this diff:
- **RETURN_TYPE** - Return type. Must be a valid type as described in [Parameters](#parameters). + Return type. Must be a valid ZModel type. In addition to the scalar forms described in + [Parameters](#parameters), functions may return object types (e.g., a model or a named type).
41-43: Fix incorrect example: uuid doesn’t take a version parameter; use cuidThis contradicts the predefined uuid() signature below.
Apply this diff:
```zmodel -function uuid(version: Int?): String {} +function cuid(version: Int?): String {}--- `61-62`: **Fix invalid usage example: uuid(4) is not supported** Use cuid(2) for cuid2 or uuid() with no args. Apply this diff: ```diff ```zmodel -id String @default(uuid(4)) +id String @default(cuid(2))--- `68-82`: **Lists render as code blocks due to 4-space indentation; unindent and tweak lead-ins** As-is, Docusaurus will render these as code blocks, not bullets. Apply this diff: ```diff -A function can have zero or more parameters. A parameter has a name and a type. - -Valid parameter types include: - - `String` - - `Boolean` - - `Int` - - `BigInt` - - `Float` - - `Decimal` - - `DateTime` - - `Bytes` - - `Any` +A function can have zero or more parameters. A parameter has a name and a type. + +A parameter can use the following scalar types: +- `String` +- `Boolean` +- `Int` +- `BigInt` +- `Float` +- `Decimal` +- `DateTime` +- `Bytes` +- `Any` -Parameter's type can also carry the following suffix: - - `[]` to indicate it's a list type - - `?` to indicate it's optional +A parameter type can also carry the following suffixes: +- `[]` to indicate it's a list type +- `?` to indicate it's optionalversioned_docs/version-3.x/reference/zmodel/import.md (2)
15-23: Fix list indentation (MD007), wording, and minor formatting.
- Align nested content to 2 spaces (currently 4), per markdownlint MD007.
- Use “module path” and lowercase “npm”.
- Use “build process”.
- Remove stray trailing space after the bold term.
This matches the earlier feedback and addresses current linter hints.
- - **IMPORT_SPEC**: +- **IMPORT_SPEC**: - - Path to the ZModel file to be imported. It can be: - - - An absolute path, e.g., "/path/to/user". - - A relative path, e.g., "./user". - - A module resolved to an installed NPM package, e.g., "my-package/base". - - If the import specification doesn't end with ".zmodel", the resolver will automatically append it. Once a file is imported, all the declarations in that file will be included in the building process. + Path to the ZModel file to be imported. It can be: + - An absolute path, e.g., "/path/to/user". + - A relative path, e.g., "./user". + - A module path resolved to an installed npm package, e.g., "my-package/base". + If the import specification doesn't end with ".zmodel", the resolver will automatically append it. Once a file is imported, all the declarations in that file will be included in the build process.
7-7: Grammar: “allows to import” → “allows importing”.Fix awkward phrasing in the intro sentence.
-ZModel allows to import other ZModel files. This is useful when you want to split your schema into multiple files for better organization. +ZModel allows importing other ZModel files. This is useful when you want to split your schema into multiple files for better organization.versioned_docs/version-3.x/orm/index.md (1)
93-93: Wording consistency: “content” vs “asset”Leftover term from earlier edits; use “content” to match the schema and variable name.
- // other asset type + // other content typeversioned_docs/version-3.x/modeling/polymorphism.md (5)
16-19: Fix wording/grammar in the intro and bulletsImproves grammar and consistency.
-When modeling non-trivial applications, the need of an "Object-Oriented" kind of polymorphism often arises: -- Something **IS-A** more abstract type of thing. -- Something **HAS-A/HAS-many** a more abstract type of thing(s). +When modeling non-trivial applications, the need for an "object-oriented" kind of polymorphism often arises: +- Something **is-a** more abstract type of thing. +- Something **has a/has many** relationship with a more abstract type.
28-28: Article usage: “an in-database” (not “a in-database”)Minor but user-facing.
-A true solution involves having a in-database model of polymorphism, where we really have a `Content` table that serves as an intermediary between `User` and the concrete content types. This is what ZModel polymorphism is about. +A true solution involves having an in-database model of polymorphism, where we really have a `Content` table that serves as an intermediary between `User` and the concrete content types. This is what ZModel polymorphism is about.
72-100: Fix markdownlint hard tabs and align ER diagram types with the code
- Replace hard tabs with spaces (MD010).
- Use DateTime for createdAt to match the model.
```mermaid erDiagram - User { - id Int PK - } - Content { - id Int PK - name String - createdAt Date - ownerId Int FK - type String - } - User ||--o{ Content: owns - Post { - id Int PK,FK - content String - } - Post ||--|| Content: delegates - Image { - id Int PK,FK - data Bytes - } - Image ||--|| Content: delegates - Video { - id Int PK,FK - url String - } - Video ||--|| Content: delegates + User { + id Int PK + } + Content { + id Int PK + name String + createdAt DateTime + ownerId Int FK + type String + } + User ||--o{ Content: owns + Post { + id Int PK,FK + content String + } + Post ||--|| Content: delegates + Image { + id Int PK,FK + data Bytes + } + Image ||--|| Content: delegates + Video { + id Int PK,FK + url String + } + Video ||--|| Content: delegates--- `102-102`: **Grammar: add the article “a”** ```diff -There are two special things about polymorphic base model: +There are two special things about a polymorphic base model:
107-108: Pluralization and sentence tightening-You can also have a deep hierarchy involving multiple level of base models. Just need to make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported. +You can also have a deep hierarchy involving multiple levels of base models. Just make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported.versioned_docs/version-3.x/modeling/model.md (2)
118-119: Fix likely broken link: point to Typed JSON docUpdates link target and text to the v3 page that exists.
-ZenStack allows you to define custom types in the schema and use them to type JSON fields. This will be covered in more detail in the [Custom Type](./custom-type) section. +ZenStack allows you to define custom types in the schema and use them to type JSON fields. This is covered in more detail in the [Typed JSON](./typed-json) section.
159-161: Enum default literal: remove quotes around enum valueEnum defaults should use the enum literal, not a string.
model User { id Int @id @default(autoincrement()) - role Role @default("USER") + role Role @default(USER) createdAt DateTime @default(now()) }If v3 intentionally supports quoted enum defaults, add a short note clarifying it and how it maps to the underlying DB.
versioned_docs/version-3.x/modeling/datasource.md (1)
38-38: Fix capitalization/wording for supported databases noteMatches prior feedback and improves clarity; avoids absolute phrasing.
-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 support is planned for a future release. There are currently no plans to support other relational databases or NoSQL databases.versioned_docs/version-3.x/modeling/index.md (1)
41-43: Fix relation field type mismatch in example
User.idisInt, soPost.authorIdmust also beIntto make the relation valid. This mismatch will confuse readers and break the example in practice.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 }
🧹 Nitpick comments (39)
versioned_docs/version-3.x/reference/zmodel/function.md (2)
131-133: Grammar: “assign” → “assigns”; tighten phrasingMinor readability fix flagged by lint.
Apply this diff:
-Creates a sequence of integers in the underlying database and assign the incremented -values to the ID values of the created records based on the sequence. +Creates a sequence of integers in the underlying database and assigns the incremented +values to the id fields of the created records.
148-148: Grammar: “login user” → “logged-in user”Minor wording polish.
Apply this diff:
-Gets the current login user. The return type is resolved to a model or type annotated with the `@@auth` attribute, and if not available, a model or type named `User`. +Gets the current logged-in user. The return type is resolved to a model or type annotated with the `@@auth` attribute, and if not available, a model or type named `User`.versioned_docs/version-3.x/reference/cli.md (8)
2-2: Use singular: “CLI reference”Minor grammar tweak for frontmatter description.
-description: CLI references +description: CLI reference
11-30: Add a language to this fenced code block (MD040)markdownlint flags code fences without a language. This block is CLI output; “text” fits best.
-``` +```text zenstack [options] [command] ζ ZenStack is the data layer for modern TypeScript apps. Documentation: https://zenstack.dev. Options: -v --version display CLI version -h, --help display help for command Commands: generate [options] Run code generation. migrate Run database schema migration related tasks. db Manage your database schema during development. info [path] Get information of installed ZenStack packages. init [path] Initialize an existing project for ZenStack. check [options] Check a ZModel schema for syntax or semantic errors. help [command] display help for command--- `32-32`: **Spell as a single word: “Subcommands”** Conventional CLI docs prefer “Subcommands”. ```diff -## Sub Commands +## Subcommands
63-69: Punctuation consistencyEnd the “resolve” command description with a period to match neighboring entries.
- resolve [options] Resolve issues with database migrations in deployment databases + resolve [options] Resolve issues with database migrations in deployment databases.
181-196: Consider adding a caution for --force-reset“--force-reset” will reset the database before push. A brief caution or warning helps avoid accidental data loss.
You could add:
:::warning
Using --force-reset will reset the database before applying changes and may lead to data loss. Use with caution.
:::
198-212: Make “info” wording consistentTwo slightly different descriptions are used. Standardize on “Get information about installed ZenStack packages.”
-Get information of installed ZenStack packages. +Get information about installed ZenStack packages. @@ -Get information of installed ZenStack. +Get information about installed ZenStack packages.
146-162: “migrate resolve” phrasing nit“In deployment databases” reads a bit awkward. “On deployed databases” is smoother, if that matches product wording.
-Resolve issues with database migrations in deployment databases. +Resolve issues with database migrations on deployed databases.
34-48: Add a concrete example forgenerateA short example helps newcomers succeed quickly.
Example to append after options:
# Generate with default output npx zenstack generate --schema zenstack/schema.zmodel # Generate to a custom output directory npx zenstack generate --schema zenstack/schema.zmodel -o src/generatedversioned_docs/version-3.x/_components/_zmodel-starter.md (2)
13-22: Consider adding onDelete behavior and indexing the FKFor relational integrity and typical query performance, it’s useful to:
- Cascade deletes from User to Post, if that matches docs expectations.
- Index
authorId(Prisma recommends indexing relation scalar fields).model Post { id String @id @default(cuid()) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt title String content String published Boolean @default(false) - author User @relation(fields: [authorId], references: [id]) + author User @relation(fields: [authorId], references: [id], onDelete: Cascade) authorId String + @@index([authorId]) }
1-1: Remove leading indentation before fenced code blocksLeading spaces before the opening/closing ``` fences can be brittle when this partial is embedded in different MDX contexts. Safer to start fences at column 0.
- ```zmodel +```zmodel ... - ``` +```Also applies to: 23-23
versioned_docs/version-3.x/orm/index.md (8)
10-10: Tighten phrasing: “learned from prior art”Use more idiomatic wording.
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an excellent developer experience and incredible flexibility by combining the best ingredients into a cohesive package. +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learned from prior art and strives to provide an excellent developer experience and incredible flexibility by combining the best ingredients into a cohesive package.
16-16: Grammar/tone: present tense, remove informalityPrefer present tense and less casual phrasing.
-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 it has an entirely different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicates Prisma ORM's query API so you can largely 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-46: Hyphenation: “database-specific”Compound adjectives before nouns should be hyphenated.
-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.
69-69: Grammar: subject–verb agreement and punctuationPlural subject “applications” → “involve”; add comma for readability.
-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.
97-97: Title case and word choice: “Lightweight”Use the standard single word “Lightweight”.
-### Straightforward and light-Weighted +### Straightforward and Lightweight
99-99: Word choice: “lightweight”Use “lightweight” instead of “light-weighted”.
-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.
101-102: Grammar: preposition and clearer phrasing
- “dependency on”, not “to”.
- Clarify “magic generating” phrasing.
-- No runtime dependency to Prisma, thus no overhead of Rust/WASM query engines. -- No magic generating into `node_modules`. You fully control how the generated code is compiled and bundled. +- No runtime dependency on Prisma, thus no overhead of Rust/WASM query engines. +- No code is generated into `node_modules`. You fully control how the generated code is compiled and bundled.
109-109: Tone and wording: “alongside”, avoid “awesome”More formal, concise phrasing.
-Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside with static code snippets. 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. Feel free to make changes and try things out in the playground. +Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside static code snippets. 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. Feel free to make changes and try things out in the playground.versioned_docs/version-3.x/reference/api.md (3)
14-21: Consider hiding the internalthis: anyfrom the public signatureExposing a
thisparameter in public docs is unusual and confuses consumers about how to construct/use the client. If this is a constructor function under the hood, documenting it as a class or a construct signature is clearer. Alternatively, document a factory function API.Please confirm the intended public shape:
- If it should be used with
new, document it as a class or with anew (...) => ...construct signature.- If it's called without
new, drop thethisparameter in the doc snippet and show the return type.I can help rewrite the snippet once you confirm which shape is correct.
26-47: Add cross-links for referenced types for discoverabilityLink Dialect (Kysely), RuntimePlugin, KyselyConfig['log'], and ComputedFieldsOptions to their respective docs (or your own reference pages). This helps readers navigate without guessing definitions.
Example additions (MDX style), placed after the code block:
- See Kysely Dialect: https://kysely-org.github.io/kysely/interfaces/Dialect.html
- See Computed fields: ../orm/computed-fields
- See Plugins: ../plugins/overview (or the correct path in this version)
2-2: Grammar: use singular “API reference”Minor copy edit.
Apply this diff:
-description: API references +description: API referenceversioned_docs/version-3.x/modeling/mixin.md (2)
15-16: Tighten wording: “formerly” + clarify the renameImproves clarity and flow in the info callout.
-Mixin was previously known as "abstract inheritance" in ZenStack v2. It's renamed and changed to use the `with` keyword to distinguish from polymorphic model inheritance. +Mixins were formerly known as "abstract inheritance" in ZenStack v2. They have been renamed and now use the `with` keyword to distinguish them from polymorphic model inheritance.
18-18: Polish intro sentence and link to Custom Types; avoid “mix-in” hyphenationMore concise, aligns terminology, and adds a helpful cross-link.
-Very often you'll find many of your models share quite a few common fields. It's tedious and error-prone to repeat them. As a rescue, you can put those fields into custom types and "mix-in" them into your models. +Often, many models share common fields. It's tedious and error-prone to repeat them. As a remedy, extract them into a mixin type (a ZModel [custom type](./custom-type)) and mix them into your models with `with`.versioned_docs/version-3.x/modeling/polymorphism.md (3)
113-114: Nit: “query” → “queries”; tighten sentenceMinor readability improvement.
-To simplify query and conserve space, the base and the concrete are assumed to share the same id values (this is guaranteed by the ORM when creating the records), and consequently, the concrete model's id field is also reused as the foreign key to the base model. So, for a `Post` record with id `1`, the base `Content` record also has id `1`. +To simplify queries and conserve space, the base and the concrete are assumed to share the same id values (guaranteed by the ORM when creating records). Consequently, the concrete model’s id is reused as the foreign key to the base model. For a `Post` with id `1`, the base `Content` record also has id `1`.
119-121: Polish: clarify ORM behavior phrasingImproves precision and readability.
-1. Creating a concrete model record automatically creates the base model record with the same id and proper discriminator field. -2. Querying with the base model will return entities with concrete model fields. +1. Creating a concrete model record automatically creates the corresponding base model record with the same id and the correct discriminator value. +2. Querying the base model returns entities that include their concrete model fields.
122-122: Grammar: “in detail” (not “in details”)-We'll revisit the topic in details in the [ORM](../orm/polymorphism.md) part. +We'll revisit the topic in detail in the [ORM](../orm/polymorphism.md) section.versioned_docs/version-3.x/modeling/model.md (1)
181-181: Plural noun: “attributes”-Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` and `@@map` attribute. The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL. +Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` and `@@map` attributes. The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL.versioned_docs/version-3.x/modeling/plugin.md (4)
14-14: Grammar: add article “A”-Plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. This section only focuses on how to add plugins to your ZModel. Please refer to the [Plugin Development](../reference/plugin-dev.md) section for more details on how to develop plugins. +A plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. This section focuses on how to add plugins to your ZModel. Please refer to the [Plugin Development](../reference/plugin-dev.md) section for more details on how to develop plugins.
27-35: Standardize CLI command: “zenstack generate” vs “zen generate”Use a single, consistent command form across the docs. This file mixes both.
-In fact, the `zen generate` command is entirely implemented with plugins. The ZModel -> TypeScript generation is supported by the built-in `@core/typescript` plugin which runs automatically. You can explicitly declare it if you wish: +In fact, the `zenstack generate` command is entirely implemented with plugins. The ZModel → TypeScript generation is supported by the built-in `@core/typescript` plugin which runs automatically. You can explicitly declare it if you wish:If the project standard is actually
zen generate, apply that form consistently (including lines 49–50 below).
42-44: Clarify provider examples; avoid “here” referenceMake the example list general and align with the examples shown.
-2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here), a local JavaScript module, or an NPM package name. +2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (for example, `@core/typescript` or `@core/prisma`), a local JavaScript module, or an NPM package.
46-50: Preposition: “effects on ZModel” (not “to”)-A plugin can have the following effects to ZModel: +A plugin can have the following effects on ZModel:versioned_docs/version-3.x/modeling/typed-json.md (2)
14-18: Tighten intro and parallelize bullet phrasingMinor readability polish.
-With relational databases providing better and better JSON support, their usage has become more common. However, in many cases, your JSON fields still follow a specific structure, and when so, you can make the fields strongly typed so that: +As relational databases add better JSON support, JSON usage has become more common. When a JSON field follows a specific structure, you can make it strongly typed so that: -- When mutating the field, its structure is validated. -- When querying the field, its result is strongly typed. +- Mutations validate the field’s structure. +- Queries return strongly typed results.
50-50: Polish: “ORM section” and remove filler-The migration engine still sees the field as a plain JSON field. However, the ORM client enforces its structure and takes care of properly typing the query results. We'll revisit this topic in the [ORM part](../orm/typed-json.md). +The migration engine still treats it as a plain JSON field. The ORM client enforces the structure and properly types query results. See the [ORM section](../orm/typed-json.md) for details.versioned_docs/version-3.x/modeling/datasource.md (2)
12-12: Tighten wording and improve clarity in the intro paragraphMinor polish to make the sentence flow better and be more concise without changing meaning.
-The `datasource` block provides information about the database your application uses. The ORM relies on it to determine the proper SQL dialect to use when generating queries. If you use [Migration](../orm/migration.md), it must also have a `url` field that specifies the database connection string, so that the migration engine knows how to connect to the database. The `env` function can be used to reference environment variables so you can keep sensitive information out of the code. +The `datasource` block describes the database your application uses. The ORM relies on it to determine the SQL dialect when generating queries. If you use [Migration](../orm/migration.md), it must also include a `url` field that specifies the database connection string so the migration engine knows how to connect. You can use the `env` function to reference environment variables and keep sensitive information out of your code.
41-42: Clarify wording and link target phrasingSlightly clearer phrasing for readers; the link target remains the same.
-ZenStack's ORM runtime doesn't rely on the `url` information to connect to the database. Instead, you provide the information when constructing an ORM client — more on this in the [ORM](../orm/) part. +ZenStack’s ORM runtime doesn’t rely on the `url` to connect to the database. Instead, you provide the connection information when constructing an ORM client — see the [ORM](../orm/) section for details.versioned_docs/version-3.x/modeling/index.md (2)
18-18: Fix grammar: “part of the documentation”Corrects a small grammar issue.
-Don't worry if you've never used Prisma before. This part of documentation will introduce all aspects of ZModel, so no prior knowledge is required. +Don't worry if you've never used Prisma before. This part of the documentation introduces all aspects of ZModel, so no prior knowledge is required.
20-20: Fix article usage: “The simplest” or “A simple”Choose either wording; “The simplest” reads best here.
-A simplest ZModel schema looks like this: +The simplest ZModel schema looks like this:
📜 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 (15)
versioned_docs/version-3.x/_components/_zmodel-starter.md(1 hunks)versioned_docs/version-3.x/modeling/attribute.md(1 hunks)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/modeling/mixin.md(1 hunks)versioned_docs/version-3.x/modeling/model.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/typed-json.md(1 hunks)versioned_docs/version-3.x/orm/index.md(1 hunks)versioned_docs/version-3.x/reference/api.md(1 hunks)versioned_docs/version-3.x/reference/cli.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/function.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/import.md(1 hunks)versioned_docs/version-3.x/welcome.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- versioned_docs/version-3.x/modeling/attribute.md
- versioned_docs/version-3.x/welcome.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
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/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/reference/zmodel/import.md
19-19: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
20-20: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
21-21: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🪛 LanguageTool
versioned_docs/version-3.x/modeling/model.md
[grammar] ~64-~64: There might be a mistake here.
Context: ...ing ways: 1. Built-in types, including: - String - Boolean - Int - BigInt...
(QB_NEW_EN)
[grammar] ~65-~65: There might be a mistake here.
Context: .... Built-in types, including: - String - Boolean - Int - BigInt - Float ...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...pes, including: - String - Boolean - Int - BigInt - Float - Decimal ...
(QB_NEW_EN)
[grammar] ~67-~67: There might be a mistake here.
Context: ...uding: - String - Boolean - Int - BigInt - Float - Decimal - Date...
(QB_NEW_EN)
[grammar] ~68-~68: There might be a mistake here.
Context: ...String - Boolean - Int - BigInt - Float - Decimal - DateTime - Js...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ... Boolean - Int - BigInt - Float - Decimal - DateTime - Json - Byt...
(QB_NEW_EN)
[grammar] ~70-~70: There might be a mistake here.
Context: ... Int - BigInt - Float - Decimal - DateTime - Json - Bytes - Unsup...
(QB_NEW_EN)
[grammar] ~71-~71: There might be a mistake here.
Context: ...nt - Float - Decimal - DateTime - Json - Bytes - Unsupported T...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...oat - Decimal - DateTime - Json - Bytes - Unsupported The `Unsupp...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...cimal - DateTime - Json - Bytes - Unsupported The Unsupported type...
(QB_NEW_EN)
[grammar] ~149-~149: There might be a mistake here.
Context: ...- now(): returns the current timestamp - cuid(): returns a CUID - uuid(): returns a U...
(QB_NEW_EN)
[grammar] ~150-~150: There might be a mistake here.
Context: ...ent timestamp - cuid(): returns a CUID - uuid(): returns a UUID - ulid(): returns a U...
(QB_NEW_EN)
[grammar] ~151-~151: There might be a mistake here.
Context: ...eturns a CUID - uuid(): returns a UUID - ulid(): returns a ULID - nanoid(): returns a...
(QB_NEW_EN)
[grammar] ~152-~152: There might be a mistake here.
Context: ...eturns a UUID - ulid(): returns a ULID - nanoid(): returns a Nano ID - autoincrement():...
(QB_NEW_EN)
[grammar] ~153-~153: There might be a mistake here.
Context: ...s a ULID - nanoid(): returns a Nano ID - autoincrement(): returns an auto-incrementing integer (...
(QB_NEW_EN)
[grammar] ~154-~154: There might be a mistake here.
Context: ...enting integer (only for integer fields) - dbgenerated("..."): calls a native db function ```zmodel ...
(QB_NEW_EN)
versioned_docs/version-3.x/_components/_zmodel-starter.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: zmodel datasource db { provider = 'sqlite' url = "file:./dev.db" } model User { id String @id @default(cuid()) email String @unique posts Post[] } model Post { id String @id @default(cuid()) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt title String content String published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId String }
(QB_NEW_DE)
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/modeling/index.md
[grammar] ~18-~18: There might be a mistake here.
Context: ...'ve never used Prisma before. This part of documentation will introduce all aspect...
(QB_NEW_EN)
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)
[grammar] ~15-~15: There might be a mistake here.
Context: ...uish from polymorphic model inheritance. ::: Very often you'll find many of your...
(QB_NEW_EN)
[grammar] ~18-~18: There might be a mistake here.
Context: ... those fields into custom types and "mix-in" them into your models. Before: ...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/plugin.md
[grammar] ~42-~42: There might be a mistake here.
Context: ... involves three parts: 1. A unique name 2. A provider field that specifies where t...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/polymorphism.md
[grammar] ~17-~17: There might be a mistake here.
Context: ...ng IS-A more abstract type of thing. - Something HAS-A/HAS-many a more abst...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...gates ``` There are two special things about polymorphic base model: 1. It must hav...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...e, but must be of String or enum type. 2. It must have a @@delegate attribute. T...
(QB_NEW_EN)
[grammar] ~113-~113: There might be a mistake here.
Context: ...e base and each of its derivations. To simplify query and conserve space, the base and ...
(QB_NEW_EN)
[grammar] ~119-~119: There might be a mistake here.
Context: ... same id and proper discriminator field. 2. Querying with the base model will return...
(QB_NEW_EN)
[grammar] ~122-~122: There might be a mistake here.
Context: ... the ORM part.
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/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 specif...
(IN_MANY_STYLE_CASES)
versioned_docs/version-3.x/orm/index.md
[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)
[style] ~109-~109: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...ich is not suitable for production use. Feel free to make changes and try things out in the ...
(FEEL_FREE_TO_STYLE_ME)
versioned_docs/version-3.x/reference/zmodel/function.md
[grammar] ~68-~68: There might be a mistake here.
Context: ... a type. Valid parameter types include: - String - Boolean - `...
(QB_NEW_EN)
[grammar] ~79-~79: There might be a mistake here.
Context: ...ype can also carry the following suffix: - [] to indicate it's a list type ...
(QB_NEW_EN)
[grammar] ~131-~131: There might be a mistake here.
Context: ...ying database and assign the incremented values to the ID values of the created r...
(QB_NEW_EN)
🔇 Additional comments (10)
versioned_docs/version-3.x/reference/zmodel/function.md (1)
83-127: Predefined functions section reads well and is consistent with the signaturesThe code fences, headings, and brief descriptions are clear and helpful.
Also applies to: 134-147
versioned_docs/version-3.x/reference/zmodel/import.md (1)
27-30: Example looks good.Clear, minimal example that matches the described behavior.
versioned_docs/version-3.x/reference/cli.md (5)
22-30: Confirm top-level command names/options match v3 CLI help outputPlease verify this list is synchronized with the actual CLI (names, punctuation, and descriptions), to avoid drift.
Quick check:
- Run: npx zenstack --help
- Compare top-level commands and their descriptions against this section.
- If the binary is “zen” in v3, update all examples accordingly throughout the page.
71-92: Good warning for dev-only commandThe admonition for “migrate dev” is appropriate and clear.
93-112: Strong warning for destructive reset is appropriateThe danger admonition and wording properly communicate risk.
245-269: Config overrides look goodClear and actionable package.json snippets for schema and output overrides.
50-129: Double-check subcommand options against current CLITo ensure accuracy, please validate flags like --migrations, --create-only, and naming conventions for all migrate subcommands against v3.
Suggested checklist:
- npx zenstack migrate dev --help
- npx zenstack migrate reset --help
- npx zenstack migrate deploy --help
- npx zenstack migrate status --help
- npx zenstack migrate resolve --help
Confirm option names, default paths, and descriptions match exactly.versioned_docs/version-3.x/_components/_zmodel-starter.md (1)
7-11: Nice, minimal User model with unique email and back-relationThe starter captures the essentials cleanly and mirrors common blog samples. Good baseline for quick-start docs.
versioned_docs/version-3.x/orm/index.md (1)
1-118: Overall: strong page structure and accurate examplesGood introduction, clear feature breakdown, and consistent examples. The Prisma-compatible API and Kysely snippets align well with the narrative. Only minor wording/grammar tweaks are suggested above.
versioned_docs/version-3.x/modeling/plugin.md (1)
51-51: Verify target path for ORM plugin docsEnsure the target exists and matches Docusaurus routing for v3.
You link to “ORM”. Please verify the index route resolves. If the concrete page is plugins.md, prefer linking directly: ../orm/plugins.md
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (11)
versioned_docs/version-3.x/_components/_zmodel-starter.md (2)
3-4: Use double quotes for ZModel/Prisma string literals (provider/url).Prisma/ZModel requires double-quoted string literals. Single quotes can break parsing in some versions.
Apply:
- provider = 'sqlite' - url = 'file:./dev.db' + provider = "sqlite" + url = "file:./dev.db"
1-1: Ensure Prism highlights ```zmodel fences (alias zmodel → prisma).Unless Docusaurus Prism is configured to alias zmodel to prisma, this block won’t be highlighted.
Action: In docusaurus.config, set prism.languageAliases = { zmodel: 'prisma' } and include prisma in additionalLanguages.
versioned_docs/version-3.x/reference/zmodel/datasource.md (3)
18-21: Polish NAME description; optionally include identifier regex.Improves grammar and adds the common identifier pattern for precision.
- Name of the data source. Must be a valid identifier. Name is only informational and serves no other purposes. + Name of the data source. Must be a valid identifier (e.g., matches `[A-Za-z][A-Za-z0-9_]*`). The name is informational and serves no other purpose.
22-28: Fix list indentation (MD007), wording, and spacing.
- Adjust to 2-space indentation for the nested list so markdownlint passes.
- Improve wording for the provider description.
- Name of database connector. Valid values: - - - sqlite - - postgresql + Database connector name. Valid values: + + - sqlite + - postgresql
31-33: Grammar/style: articles, capitalization, and contractions.Refines phrasing and uses “PostgreSQL” consistently.
- Database connection string. Either a plain string or an invocation of `env` function to fetch from an environment variable. For SQLite provider, the URL should be a file protocol, like `file:./dev.db`. For PostgreSQL provider, it should be a postgres connection string, like `postgresql://user:password@localhost:5432/dbname`. + Database connection string. Either a plain string or an invocation of the `env` function to fetch from an environment variable. For the SQLite provider, the URL should use the file protocol, like `file:./dev.db`. For the PostgreSQL provider, it should be a PostgreSQL connection string, like `postgresql://user:password@localhost:5432/dbname`. @@ - The `url` option is only used by the migration engine to connect to the database. The ORM runtime doesn't rely on it. Instead, you provide the connection information when constructing an ORM client. + The `url` option is used only by the migration engine to connect to the database. The ORM runtime does not rely on it. Instead, you provide the connection information when constructing an ORM client.versioned_docs/version-3.x/migrate-prisma.md (4)
30-33: Fix contradictory Prisma peer-dependency guidance; don’t tell users to removeprismaif they run migrationsThe text simultaneously states the CLI has a peer dependency on Prisma and instructs users to remove it, then says they don't need to install it. This will break migration commands for many package managers that do not auto-install peers.
Align the guidance to:
- Remove only
@prisma/client- Keep (or add)
prismaas a devDependency when using migration commands- Use “migration-related” (hyphenated)
Apply:
-ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration related commands. The most straightforward way is to follow these steps: +ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration-related commands. The most straightforward way is to follow these steps: -- Remove `prisma` and `@prisma/client` from your project dependencies. +- Remove `@prisma/client` from your project dependencies. +- Keep (or add) `prisma` as a devDependency if you plan to run migrations with `zen`. @@ -You don't need to explicitly install `prisma` package because the `@zenstackhq/cli` has a peer dependency on it. +Note: You still need the `prisma` package in your project (typically as a devDependency) to satisfy the CLI's peer dependency; package managers differ in whether they auto-install peers.Also applies to: 55-55
44-49: Examples import Kysely but it’s not installed; addkyselyto dependenciesCode below uses
PostgresDialect/SqliteDialectfromkysely, but the install instructions omit it. This will cause module resolution errors.Apply:
- <PackageInstall dependencies={['pg']} devDependencies={['@types/pg']} /> + <PackageInstall dependencies={['kysely', 'pg']} devDependencies={['@types/pg']} /> @@ - <PackageInstall dependencies={['better-sqlite3']} devDependencies={['@types/better-sqlite3']} /> + <PackageInstall dependencies={['kysely', 'better-sqlite3']} devDependencies={['@types/better-sqlite3']} />
155-160: Make Prisma plugin output path consistent with theprisma generatecommand and fix capitalizationThe plugin outputs
./schema.prisma, but theprisma generatestep referenceszenstack/schema.prisma. Pick one path and use it consistently. Also capitalize “Prisma” in the sentence.Apply:
plugin prisma { provider = '@core/prisma' - output = './schema.prisma' + output = './zenstack/schema.prisma' }-2. Run a `prisma generate` command after `zen generate` with the prisma schema as input. +2. Run a `prisma generate` command after `zen generate` with the Prisma schema as input.The script already references
zenstack/schema.prisma, so once the output path is updated, they’ll be aligned:{ "scripts": { "generate": "zen generate && prisma generate --schema=zenstack/schema.prisma" } }Also applies to: 162-170
261-261: Grammar: add missing “is”“…which much more efficient…” → “…which is much more efficient…”.
Apply:
-A key difference is that ZenStack's computed fields are evaluated on the database side, which much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation. +A key difference is that ZenStack's computed fields are evaluated on the database side, which is much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation.versioned_docs/version-3.x/reference/zmodel/model.md (1)
39-41: Tighten identifier wording and fix pluralizationClarify plurality and use the correct terminology for composite identifiers; also add the missing article in the fallback sentence.
-A model must be uniquely identifiable by one or several of its fields. In most cases, you'll have a field marked with the `@id` attribute. If needed, you can use multiple fields as unique identifier by using the `@@id` model-level attribute. +A model must be uniquely identifiable by one or more of its fields. In most cases, you'll have a field marked with the `@id` attribute. If needed, you can use multiple fields as a composite identifier by using the `@@id` model-level attribute. @@ -If no `@id` or `@@id` is specified, the field(s) marked with the `@unique` or `@@unique` attribute will be used as fallback identifier. +If no `@id` or `@@id` is specified, the field(s) marked with `@unique` or `@@unique` will be used as the fallback identifier.versioned_docs/version-3.x/modeling/model.md (1)
118-119: Fix likely broken link: point to “Typed JSON” docUpdate the anchor text and target to match the v3 doc that covers typing JSON fields.
- ZenStack allows you to define custom types in the schema and use them to type JSON fields. This is covered in more detail in the [Custom Type](./custom-type) section. + ZenStack allows you to define custom types in the schema and use them to type JSON fields. This is covered in more detail in the [Typed JSON](./typed-json) section.
🧹 Nitpick comments (22)
versioned_docs/version-3.x/_components/_zmodel-starter.md (1)
1-23: Optional: remove leading indentation inside the fenced code block.The extra two-space left padding is preserved by the fence and slightly degrades copy/paste experience.
If you keep indentation for MDX layout reasons, no change needed. Otherwise, left-trim the lines inside the fence.
versioned_docs/version-3.x/reference/zmodel/plugin.md (4)
22-25: Use “npm” (lowercase) and keep terminology consistentThe official spelling is “npm.”
Apply this diff:
- The JavaScript module that provides the plugin's implementation. It can be a built-in plugin (like `@core/typescript`), a local JavaScript file, or an installed NPM package that exports a plugin. + The JavaScript module that provides the plugin's implementation. It can be a built-in plugin (like `@core/typescript`), a local JavaScript file, or an installed npm package that exports a plugin.
18-21: Consider specifying identifier rules (or link to the identifier spec)Adding a concrete rule prevents ambiguity. If you choose to inline a regex, ensure it’s correct.
Apply this diff (verify the pattern matches ZModel’s identifier spec before merging):
- Name of the plugin. Needs to be unique in the entire model. Must be a valid identifier. + Name of the plugin. Needs to be unique in the entire model. Must be a valid identifier. For example, it can match the pattern `[A-Za-z][A-Za-z0-9_]*`.
11-16: Explain the “OPTION” quantifier*A short note helps readers unfamiliar with the notation.
Apply this diff to insert a clarification right after the syntax block:
}+- Note:
OPTION*means zero or more option assignments.
+
- PLUGIN_NAME
--- `30-37`: **Add a second example showing an npm-provided plugin** You mention npm packages above; mirroring that here improves completeness. You can append this example below the existing one: ```zmodel plugin types { provider = '@core/typescript' outDir = './generated' }versioned_docs/version-3.x/reference/zmodel/datasource.md (1)
5-7: Tighten terminology: “Datasource” and “schema” wording.Minor clarity and consistency improvements with the
datasourcekeyword.-# Data Source +# Datasource @@ -Every model needs to include exactly one `datasource` declaration, providing information on how to connect to the underlying database. +Each schema must include exactly one `datasource` declaration, providing information on how to connect to the underlying database.versioned_docs/version-3.x/orm/index.md (7)
10-10: Polish phrasing: “learnt from the prior arts” → “learned from prior art”Improves clarity and correctness (US English and idiomatic use of “prior art”).
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an excellent developer experience and incredible flexibility by combining the best ingredients into a cohesive package. +ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learned from prior art and strives to provide an excellent developer experience and incredible flexibility by combining the best ingredients into a cohesive package.
16-16: Tighten wording and fix tense (“replicated” → “replicates”)Also removes informal “pretty much” and uses “entirely” instead of “completely” per style hint.
-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 it has an entirely different implementation (based on [Kysely](https://kysely.dev/)). On the surface, it replicates Prisma ORM's query API, so 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-46: Hyphenation: “database specific” → “database-specific”Correct compound modifier usage.
-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.
69-69: Subject–verb agreement and comma usage“Involves” → “involve”; add comma before nonrestrictive clause.
-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.
93-93: Terminology consistency: “asset” → “content”The schema uses Content/Post; keep wording consistent.
- // other asset type + // other content type
97-103: Use “Lightweight” and polish bullets for clarityStandard terminology is “lightweight”; minor grammar/style tweaks to bullets.
-### 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. @@ -- No runtime dependency to Prisma, thus no overhead of Rust/WASM query engines. +- No runtime dependency on Prisma, thus no overhead from Rust/WASM query engines. -- No magic generating into `node_modules`. You fully control how the generated code is compiled and bundled. +- No code is generated into `node_modules`. You fully control how the generated code is compiled and bundled.
109-109: Tone and formality: avoid “awesome”, “Feel free to …”More neutral/professional phrasing for docs.
-Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside with static code snippets. 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. Feel free to make changes and try things out in the playground. +Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside static code snippets. 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. You can make changes and try things out in the playground.versioned_docs/version-3.x/migrate-prisma.md (1)
90-94: Avoid assuming a path alias for@/zenstack/schemain examplesUsing
@/…assumes a TS/webpack/Vite path alias that many projects don’t have by default. Either show a relative import or add a short note that an alias is assumed.Example alternatives:
- Use a relative path:
import { schema } from './zenstack/schema'- Or add a note: “Note: The
@/alias assumes you’ve configured path aliases (e.g., tsconfig paths). Adjust the import as needed.”Also applies to: 107-112
versioned_docs/version-3.x/modeling/index.md (1)
18-21: Polish grammar: add article and fix “A simplest”Minor readability/grammar improvements.
-Don't worry if you've never used Prisma before. This part of documentation will introduce all aspects of ZModel, so no prior knowledge is required. +Don't worry if you've never used Prisma before. This part of the documentation will introduce all aspects of ZModel, so no prior knowledge is required. @@ -A simplest ZModel schema looks like this: +A simple ZModel schema looks like this:versioned_docs/version-3.x/modeling/polymorphism.md (4)
16-19: Fix intro phrasing and bullet grammar/capitalizationUse “need for,” lowercase the emphasis terms, and smooth the wording.
-When modeling non-trivial applications, the need of an "Object-Oriented" kind of polymorphism often arises: -- Something **IS-A** more abstract type of thing. -- Something **HAS-A/HAS-many** a more abstract type of thing(s). +When modeling non-trivial applications, the need for an "object-oriented" kind of polymorphism often arises: +- Something **is-a** more abstract type of thing. +- Something **has a/has many** relationship with a more abstract type.
107-107: Grammar: imperative phrasingTighten the sentence and avoid the fragment.
-You can also have a deep hierarchy involving multiple levels of base models. Just need to make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported. +You can also have a deep hierarchy involving multiple levels of base models. Just make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported.
113-114: Grammar: pluralization and clarityUse “queries” and streamline the sentence.
-To simplify query and conserve space, the base and the concrete are assumed to share the same id values (this is guaranteed by the ORM when creating the records), and consequently, the concrete model's id field is also reused as the foreign key to the base model. So, for a `Post` record with id `1`, the base `Content` record also has id `1`. +To simplify queries and conserve space, the base and the concrete are assumed to share the same id values (this is guaranteed by the ORM when creating records). Consequently, the concrete model's id field is also reused as the foreign key to the base model. For example, for a `Post` record with id `1`, the base `Content` record also has id `1`.
122-122: Grammar: “in detail”Minor polish.
-We'll revisit the topic in details in the [ORM](../orm/polymorphism.md) part. +We'll revisit the topic in detail in the [ORM](../orm/polymorphism.md) part.versioned_docs/version-3.x/modeling/relation.md (3)
27-27: Use standard capitalization for PK–FK and clarify phrasingPrefer “PK–FK” and keep consistent terminology across docs.
-The `Profile` model holds the foreign key `userId` and is the owner of the relation. The pk-fk association is established by the `@relation` attribute, where the `fields` parameter specifies the foreign key field(s) and the `references` parameter specifies the primary key field(s) of the other side. +The `Profile` model holds the foreign key `userId` and is the owner of the relation. The PK–FK association is established by the `@relation` attribute, where the `fields` parameter specifies the foreign key field(s) and the `references` parameter specifies the primary key field(s) of the other side.
84-84: Tone: remove informal “pretty much”Trim to keep a formal docs tone.
-It's modeled pretty much 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. +It's modeled 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.
221-224: Pluralize “referential actions”Use plural when referring to the set of actions.
-When defining a relation, you can use referential action to control what happens when one side of a relation is updated or deleted by setting the `onDelete` and `onUpdate` parameters in the `@relation` attribute. +When defining a relation, you can use referential actions to control what happens when one side of a relation is updated or deleted by setting the `onDelete` and `onUpdate` parameters in the `@relation` attribute.
📜 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/_components/_zmodel-starter.md(1 hunks)versioned_docs/version-3.x/migrate-prisma.md(1 hunks)versioned_docs/version-3.x/modeling/index.md(1 hunks)versioned_docs/version-3.x/modeling/model.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/reference/zmodel/datasource.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/model.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/plugin.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/type.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- versioned_docs/version-3.x/reference/zmodel/type.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/_components/_zmodel-starter.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: zmodel datasource db { provider = 'sqlite' url = 'file:./dev.db' } model User { id String @id @default(cuid()) email String @unique posts Post[] } model Post { id String @id @default(cuid()) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt title String content String published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId String }
(QB_NEW_DE)
versioned_docs/version-3.x/migrate-prisma.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...all from './_components/PackageInstall'; 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 Tabs from '@theme/Tabs'; # Migra...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/index.md
[grammar] ~18-~18: There might be a mistake here.
Context: ...'ve never used Prisma before. This part of documentation will introduce all aspect...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/model.md
[grammar] ~64-~64: There might be a mistake here.
Context: ...ing ways: 1. Built-in types, including: - String - Boolean - Int - BigInt...
(QB_NEW_EN)
[grammar] ~65-~65: There might be a mistake here.
Context: .... Built-in types, including: - String - Boolean - Int - BigInt - Float ...
(QB_NEW_EN)
[grammar] ~66-~66: There might be a mistake here.
Context: ...pes, including: - String - Boolean - Int - BigInt - Float - Decimal ...
(QB_NEW_EN)
[grammar] ~67-~67: There might be a mistake here.
Context: ...uding: - String - Boolean - Int - BigInt - Float - Decimal - Date...
(QB_NEW_EN)
[grammar] ~68-~68: There might be a mistake here.
Context: ...String - Boolean - Int - BigInt - Float - Decimal - DateTime - Js...
(QB_NEW_EN)
[grammar] ~69-~69: There might be a mistake here.
Context: ... Boolean - Int - BigInt - Float - Decimal - DateTime - Json - Byt...
(QB_NEW_EN)
[grammar] ~70-~70: There might be a mistake here.
Context: ... Int - BigInt - Float - Decimal - DateTime - Json - Bytes - Unsup...
(QB_NEW_EN)
[grammar] ~71-~71: There might be a mistake here.
Context: ...nt - Float - Decimal - DateTime - Json - Bytes - Unsupported T...
(QB_NEW_EN)
[grammar] ~72-~72: There might be a mistake here.
Context: ...oat - Decimal - DateTime - Json - Bytes - Unsupported The `Unsupp...
(QB_NEW_EN)
[grammar] ~73-~73: There might be a mistake here.
Context: ...cimal - DateTime - Json - Bytes - Unsupported The Unsupported type...
(QB_NEW_EN)
[grammar] ~149-~149: There might be a mistake here.
Context: ...- now(): returns the current timestamp - cuid(): returns a CUID - uuid(): returns a U...
(QB_NEW_EN)
[grammar] ~150-~150: There might be a mistake here.
Context: ...ent timestamp - cuid(): returns a CUID - uuid(): returns a UUID - ulid(): returns a U...
(QB_NEW_EN)
[grammar] ~151-~151: There might be a mistake here.
Context: ...eturns a CUID - uuid(): returns a UUID - ulid(): returns a ULID - nanoid(): returns a...
(QB_NEW_EN)
[grammar] ~152-~152: There might be a mistake here.
Context: ...eturns a UUID - ulid(): returns a ULID - nanoid(): returns a Nano ID - autoincrement():...
(QB_NEW_EN)
[grammar] ~153-~153: There might be a mistake here.
Context: ...s a ULID - nanoid(): returns a Nano ID - autoincrement(): returns an auto-incrementing integer (...
(QB_NEW_EN)
[grammar] ~154-~154: There might be a mistake here.
Context: ...enting integer (only for integer fields) - dbgenerated("..."): calls a native db function ```zmodel ...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/polymorphism.md
[grammar] ~17-~17: There might be a mistake here.
Context: ...ng IS-A more abstract type of thing. - Something HAS-A/HAS-many a more abst...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...e, but must be of String or enum type. 2. It must have a @@delegate attribute. T...
(QB_NEW_EN)
[grammar] ~113-~113: There might be a mistake here.
Context: ...e base and each of its derivations. To simplify query and conserve space, the base and ...
(QB_NEW_EN)
[grammar] ~119-~119: There might be a mistake here.
Context: ... same id and proper discriminator field. 2. Querying with the base model will return...
(QB_NEW_EN)
[grammar] ~122-~122: There might be a mistake here.
Context: ... the ORM part.
(QB_NEW_EN)
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)
[grammar] ~249-~249: There might be a mistake here.
Context: ...renced record will trigger the deletion of referencing record. - **onUpdate...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/index.md
[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)
[style] ~109-~109: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...ich is not suitable for production use. Feel free to make changes and try things out in the ...
(FEEL_FREE_TO_STYLE_ME)
versioned_docs/version-3.x/reference/zmodel/datasource.md
[grammar] ~26-~26: There might be a mistake here.
Context: ...connector. Valid values: - sqlite - postgresql - url: Database...
(QB_NEW_EN)
[grammar] ~31-~31: There might be a mistake here.
Context: ... to fetch from an environment variable. For SQLite provider, the URL should be a fi...
(QB_NEW_EN)
versioned_docs/version-3.x/reference/zmodel/model.md
[grammar] ~39-~39: There might be a mistake here.
Context: ... If needed, you can use multiple fields as unique identifier by using the @@id m...
(QB_NEW_EN)
[grammar] ~41-~41: There might be a mistake here.
Context: ...eor@@unique` attribute will be used as fallback identifier. ## Example ```zm...
(QB_NEW_EN)
versioned_docs/version-3.x/reference/zmodel/plugin.md
[grammar] ~28-~28: There might be a mistake here.
Context: ...N** A plugin configuration option, in form of "[NAME] = [VALUE]". Option valu...
(QB_NEW_EN)
🪛 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/modeling/relation.md
249-249: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
251-251: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
255-255: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
256-256: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
264-264: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
265-265: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
268-268: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
269-269: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
versioned_docs/version-3.x/reference/zmodel/datasource.md
26-26: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
27-27: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/index.md (1)
8-45: Strong overview and examples — good structureThe page reads well, imports the MDX component correctly, and the Prisma-compatible and Kysely builder examples are coherent. Nice balance of concepts and code.
versioned_docs/version-3.x/modeling/model.md (2)
157-163: Enum default literal looks correct nowThanks for switching to the unquoted enum literal in the example; this aligns with expected syntax.
177-177: Reference link LGTMThe link to native type mapping attributes under the ZModel Language Reference looks correct and resolves to the right anchor.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
versioned_docs/version-3.x/reference/zmodel/plugin.md (1)
26-29: Grammar and formatting for OPTION definitionUse code formatting and fix articles; aligns with prior feedback.
-- **OPTION** +- **`OPTION`** @@ - A plugin configuration option, in form of "NAME = VALUE". Option values can be literal, array, or object. + A plugin configuration option, in the form `NAME = VALUE`. Option values can be a literal, an array, or an object.
🧹 Nitpick comments (3)
versioned_docs/version-3.x/reference/zmodel/plugin.md (3)
18-18: Format identifiers consistently as codeUse code formatting for the symbol name to match the style used for
providerand improve scannability.-- **PLUGIN_NAME** +- **`PLUGIN_NAME`**
20-20: Tighten phrasing for uniqueness/validityMinor style improvement for clarity and concision.
- Name of the plugin. Needs to be unique in the entire model. Must be a valid identifier. + Name of the plugin. Must be unique across the model and a valid identifier.
22-24: Lowercase “npm” per official stylingFollow npm’s preferred lowercase branding.
- The JavaScript module that provides the plugin's implementation. It can be a built-in plugin (like `@core/typescript`), a local JavaScript file, or an installed NPM package that exports a plugin. + The JavaScript module that provides the plugin's implementation. It can be a built-in plugin (like `@core/typescript`), a local JavaScript file, or an installed npm package that exports a plugin.
📜 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 (1)
versioned_docs/version-3.x/reference/zmodel/plugin.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/reference/zmodel/plugin.md
[grammar] ~28-~28: There might be a mistake here.
Context: ...N** A plugin configuration option, in form of "NAME = VALUE". Option values c...
(QB_NEW_EN)
🔇 Additional comments (1)
versioned_docs/version-3.x/reference/zmodel/plugin.md (1)
11-16: Syntax section looks solidThe grammar and structure of the plugin syntax are clear and consistent with the example below.
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
versioned_docs/version-3.x/orm/computed-fields.md (1)
6-8: This page uses MDX features but has a .md extension — rename to .mdxImports and JSX components require an .mdx file in Docusaurus, otherwise the page won’t compile/render.
Suggested action:
- Rename versioned_docs/version-3.x/orm/computed-fields.md → versioned_docs/version-3.x/orm/computed-fields.mdx
- Update any internal links if they point to the .md file
🧹 Nitpick comments (1)
versioned_docs/version-3.x/orm/computed-fields.md (1)
46-46: Wording nit: “is also passed with” → “is also called with”Slightly improves readability.
-The computed field callback is also passed with a second `context` argument containing other useful information related to the current query. +The computed field callback is also called with a second `context` argument containing other useful information related to the current query.
📜 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 (1)
versioned_docs/version-3.x/orm/computed-fields.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
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)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/computed-fields.md (3)
1-4: Frontmatter looks goodNo issues with sidebar positioning or description.
68-69: Embed Validated: Sample Repository is PublicVerified that
zenstackhq/v3-doc-orm-computed-fieldsexists, is public, and the default branch ismain. The StackBlitz/GitHub embed at versioned_docs/version-3.x/orm/computed-fields.md (lines 68–69) will render correctly. No changes required.
49-60: Verify Kyselysql.refsignature
Kysely’ssql.refoften expects a single string argument ('Table.column') rather than two separate arguments. Please confirm which signature your Kysely version supports and update both the static and context-aware examples accordingly. For example:
- Using
sql.ref:.whereRef( 'Post.authorId', '=', sql.ref('User.id') )- Or, for a typed expression builder:
.whereRef( 'Post.authorId', '=', eb.ref('User.id') )Once you’ve verified the correct API, apply the appropriate diff to replace
-.whereRef('Post.authorId', '=', sql.ref(currentModel, 'id')) +.whereRef('Post.authorId', '=', sql.ref(`${currentModel}.id`))or, if you prefer the expression builder:
-.whereRef('Post.authorId', '=', sql.ref(`${currentModel}.id`)) +.whereRef('Post.authorId', '=', eb.ref(`${currentModel}.id`))
| 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. | ||
|
|
There was a problem hiding this comment.
Grammar fix: “a computed fields” → “a computed field”
Tweak the sentence for number agreement and clarity.
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.📝 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.
| 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. |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/computed-fields.md around lines 21 to 22, the
phrase "a computed fields" is grammatically incorrect; change it to "a computed
field" and revise the sentence for clarity (e.g., "First, add the field to the
ZModel schema of a model and annotate it with an extra `@computed` attribute.")
so number agreement and phrasing are correct.
| postCount: (eb) => | ||
| eb.selectFrom('Post') | ||
| .whereRef('Post.authorId', '=', 'id') | ||
| .select(({fn}) => fn.countAll<number>().as('count')), | ||
| }, |
There was a problem hiding this comment.
Incorrect Kysely reference in example — ‘id’ refers to the wrong table
In the first snippet, whereRef('Post.authorId', '=', 'id') likely refers to Post.id (or an unknown column) rather than User.id. Use an explicit reference. Since you don’t have context in this snippet, hardcode the model name or show only the context-aware example to avoid confusion.
Apply this diff within the snippet and add the import:
- postCount: (eb) =>
- eb.selectFrom('Post')
- .whereRef('Post.authorId', '=', 'id')
- .select(({fn}) => fn.countAll<number>().as('count')),
+ postCount: (eb) =>
+ eb.selectFrom('Post')
+ .whereRef('Post.authorId', '=', sql.ref('User.id'))
+ .select(({ fn }) => fn.countAll<number>().as('count')),Add the missing import at the top of the snippet:
import { sql } from 'kysely';Alternatively, remove the first snippet and keep only the context-aware version that uses sql.ref(currentModel, 'id') (after correcting its signature as noted below).
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/computed-fields.md around lines 37 to 41, the
whereRef call incorrectly references 'id' (ambiguous/wrong table); replace it
with an explicit reference to the User id using Kysely's sql.ref (e.g.
whereRef('Post.authorId', '=', sql.ref('User', 'id'))), and add the missing
import "import { sql } from 'kysely';" at the top of the snippet; alternatively
remove this non-context-aware snippet and keep only the context-aware example
that uses sql.ref(currentModel, 'id').
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
versioned_docs/version-3.x/orm/migration.md (1)
53-57: Fix typo (“promoted” → “prompted”) and tighten workflow wordingMatches a prior comment on this exact section; carrying it forward with concrete edits.
-1. Make changes to your ZModel schema. -2. Run `zen db push` to push the changes to your database without creating a migration file. +1. Modify your ZModel schema. +2. Run `zen db push` to apply changes 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. -5. Carefully review the migration file, make changes as needed, and commit it to source control. +4. Run `zen migrate dev` to create a migration file; you'll be prompted if a full reset is needed. +5. Review the migration file, make any necessary edits, and commit it to source control.
🧹 Nitpick comments (8)
versioned_docs/version-3.x/roadmap.md (3)
1-3: Add description metadata for SEO/contextOptional but recommended: add a short description to the front matter so search and previews show useful context.
Apply this diff:
--- sidebar_position: 11 +description: High-level plan for ZenStack 3.x features and documentation milestones. ---
5-5: Add a one-line intro for clarityA short sentence helps set expectations (scope, tentativeness) and improves scannability.
Apply this diff:
# Roadmap + +This page tracks planned and in-progress items for the 3.x release and docs. Timelines and scope are tentative.
7-13: Normalize capitalization and acronyms; optionally add cross-links to relevant docs
- Use Title Case consistently and capitalize acronyms (JSON).
- If these items already have v3 pages, linking them from the roadmap reduces friction.
- Verify the preferred naming: “Query-as-a-Service,” “Query API,” or “Automatic CRUD API,” and align with the page title used under service/.
Apply this diff:
-- [ ] Access Control -- [ ] Data Validation -- [ ] Zod integration -- [ ] Performance benchmark -- [ ] Query-as-a-Service (automatic CRUD API) -- [ ] Json filter -- [ ] Custom procedures +- [ ] Access Control +- [ ] Data Validation +- [ ] Zod Integration +- [ ] Performance Benchmark +- [ ] Query-as-a-Service (Automatic CRUD API) +- [ ] JSON Filter ([docs](./orm/api/filter)) +- [ ] Custom Procedures ([docs](./orm/plugins/))Follow-ups:
- If “JSON Filter” and “Custom Procedures” already have content in this PR, consider adding a short status note (e.g., “Docs stub added,” “Spec stabilizing,” etc.). I can update the checklist with status sub-bullets if you confirm the desired wording.
versioned_docs/version-3.x/orm/migration.md (5)
11-12: Tighten phrasing and fix “CLI” wordingMinor clarity/grammar improvements.
-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 migrations are 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 thin wrappers around the Prisma CLI. When running these commands, the CLI automatically generates a Prisma schema from ZModel and then runs the corresponding Prisma CLI command.
13-15: “Basing on” → “Building on”Reads more naturally in English.
-Basing on Prisma Migrate brings the following benefits: +Building on Prisma Migrate brings the following benefits:
27-41: Elevate production-safety warnings with admonitionsYou repeatedly say “should never be used in production” for db push, migrate dev, and migrate reset. Highlight this with admonitions to make it hard to miss.
### db push -The `zen db push` command is used to push your ZModel schema changes to the database without creating a migration file. It's useful for development and testing purposes, but should never be used in production. +The `zen db push` command is used to apply your ZModel schema changes to the database without creating a migration file. It's useful for development and testing purposes. + +:::caution +Do not use `zen db push` in production. +::: @@ ### migrate dev @@ -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 creates a new migration from your ZModel schema changes and applies it to your database. For development only. + +:::caution +Do not use `zen migrate dev` in production. +::: @@ ### migrate reset @@ -The `zen migrate reset` command is used to reset your database to a clean state by dropping all tables and reapplying all migrations. It's useful for testing and development purposes, but should never be used in production. +The `zen migrate reset` command resets your database to a clean state by dropping all tables and reapplying all migrations. Useful for testing and development only. + +:::caution +Do not use `zen migrate reset` in production. +:::
45-47: Clarify that “resolve” does not execute SQLMake the safety implication explicit.
-The `zen migrate resolve` command is used to mark a migration as applied or rolled back without changing the database schema. This is useful for situations where you need to manually intervene in the migration process. +The `zen migrate resolve` command marks a migration as applied or rolled back without executing any SQL or changing the database schema. Useful when you need to manually intervene in the migration history.
61-62: Minor tone tweakRemove “simply” to keep a neutral, precise tone.
-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 applies all pending migrations to the database.
📜 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 ignored due to path filters (3)
versioned_docs/version-3.x/modeling/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/orm/_category_.ymlis excluded by!**/*.ymlversioned_docs/version-3.x/vscode.pngis excluded by!**/*.png,!**/*.png
📒 Files selected for processing (4)
versioned_docs/version-3.x/orm/errors.md(1 hunks)versioned_docs/version-3.x/orm/migration.md(1 hunks)versioned_docs/version-3.x/prerequisite.md(1 hunks)versioned_docs/version-3.x/roadmap.md(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- versioned_docs/version-3.x/prerequisite.md
- versioned_docs/version-3.x/orm/errors.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/migration.md
[style] ~53-~53: 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/roadmap.md
[grammar] ~7-~7: There might be a mistake here.
Context: ... 11 --- # Roadmap - [ ] Access Control - [ ] Data Validation - [ ] Zod integratio...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...[ ] Access Control - [ ] Data Validation - [ ] Zod integration - [ ] Performance be...
(QB_NEW_EN)
[grammar] ~11-~11: There might be a mistake here.
Context: ... Query-as-a-Service (automatic CRUD API) - [ ] Json filter - [ ] Custom procedures
(QB_NEW_EN)
[grammar] ~12-~12: There might be a mistake here.
Context: ...Service (automatic CRUD API) - [ ] Json filter - [ ] Custom procedures
(QB_NEW_EN)
🔇 Additional comments (1)
versioned_docs/version-3.x/orm/migration.md (1)
23-24: Update link phrasing and casing in migration docsThe CLI reference file exists at both
versioned_docs/version-3.x/reference/cli.mdanddocs/reference/cli.md, so the relative link../reference/cli.mdis valid. Applying the suggested phrasing will keep consistency with the rest of the docs.--- a/versioned_docs/version-3.x/orm/migration.md +++ b/versioned_docs/version-3.x/orm/migration.md @@ -23,1 +23,1 @@ -Please refer to the [CLI Reference](../reference/cli.md) for the complete list of commands and options. +See the [CLI reference](../reference/cli.md) for the complete list of commands and options.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
versioned_docs/version-3.x/migrate-prisma.md (5)
176-179: Use heading level for subsections and fix verb agreementMarkdownlint flags emphasis-as-heading; also correct “intercepts” → “intercept”.
Apply:
-**1. Query extension** +#### Query extension ... -[Query extension](https://www.prisma.io/docs/orm/prisma-client/client-extensions/query) allows you to intercept ORM query calls. +[Query extension](https://www.prisma.io/docs/orm/prisma-client/client-extensions/query) allows you to intercept ORM query calls.
261-261: Grammar and tone: add missing “is” and soften phrasingMinor but user-facing.
Apply:
-A key difference is that ZenStack's computed fields are evaluated on the database side, which much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation. +A key difference is that ZenStack's computed fields are evaluated on the database side, which is much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation.
30-56: Contradictory Prisma peer-dependency guidance; clarify and fix stepsYou say the CLI has a peer dependency on prisma, then advise removing prisma and also say it needn’t be installed. Projects must install peer deps themselves; keep/add prisma as a devDependency when running migrations.
Apply this diff to clarify and correct the instructions and grammar:
-ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration related commands. The most straightforward way is to follow these steps: +ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration-related commands. The most straightforward way is to follow these steps: -- Remove `prisma` and `@prisma/client` from your project dependencies. +- Remove `@prisma/client` from your project dependencies. +- Keep (or add) `prisma` as a devDependency if you plan to run migrations with `zen`. ... -You don't need to explicitly install `prisma` package because the `@zenstackhq/cli` has a peer dependency on it. +Note: You still need the `prisma` package installed in your project (typically as a devDependency) to satisfy the CLI's peer dependency. Package managers differ in whether they auto-install peers.
41-52: Add Kysely to dependencies for the examples to workYour code samples import PostgresDialect/SqliteDialect from 'kysely', but the install snippets don’t include it. Add 'kysely' to prevent resolution errors.
Apply:
<TabItem value="postgres" label="PostgreSQL"> - <PackageInstall dependencies={['pg']} devDependencies={['@types/pg']} /> + <PackageInstall dependencies={['kysely', 'pg']} devDependencies={['@types/pg']} /> ... <TabItem value="sqlite" label="SQLite"> - <PackageInstall dependencies={['better-sqlite3']} devDependencies={['@types/better-sqlite3']} /> + <PackageInstall dependencies={['kysely', 'better-sqlite3']} devDependencies={['@types/better-sqlite3']} />
155-170: Prisma plugin output path and generate command are inconsistentThe plugin outputs ./schema.prisma but the generate script uses zenstack/schema.prisma. Align them to avoid confusion.
Apply:
plugin prisma { provider = '@core/prisma' - output = './schema.prisma' + output = './zenstack/schema.prisma' }The script already references zenstack/schema.prisma, so it will be consistent after this change.
🧹 Nitpick comments (1)
versioned_docs/version-3.x/migrate-prisma.md (1)
215-217: Use heading level for result extension subsectionConsistent with the previous change and to satisfy markdownlint.
Apply:
-**2. Result extension** +#### Result extension
📜 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 (1)
versioned_docs/version-3.x/migrate-prisma.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/migrate-prisma.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...all from './_components/PackageInstall'; 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 Tabs from '@theme/Tabs'; # Migra...
(QB_NEW_EN)
[grammar] ~267-~267: There might be a mistake here.
Context: ...Stack v3: | Feature | Planned | Notes | |---------|-------------| --- | | [Clien...
(QB_NEW_EN)
[grammar] ~268-~268: There might be a mistake here.
Context: ... Notes | |---------|-------------| --- | | [Client Extensions](https://www.prisma...
(QB_NEW_EN)
[grammar] ~269-~269: There might be a mistake here.
Context: ...Replaced with ZenStack runtime plugins | | [JSON Filters](https://www.prisma.io/d...
(QB_NEW_EN)
[grammar] ~270-~270: There might be a mistake here.
Context: ...client-reference#json-filters) | Yes | | | [Full-Text Search](https://www.prisma....
(QB_NEW_EN)
[grammar] ~271-~271: There might be a mistake here.
Context: ...ient/queries/full-text-search) | Yes | | | [Comparing Columns](https://www.prisma...
(QB_NEW_EN)
[grammar] ~272-~272: There might be a mistake here.
Context: ...are-columns-in-the-same-table) | Yes | | | [Postgres Multi-Schema](https://www.pr...
(QB_NEW_EN)
🪛 markdownlint-cli2 (0.17.2)
versioned_docs/version-3.x/migrate-prisma.md
176-176: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
215-215: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
| import PackageInstall from './_components/PackageInstall'; | ||
| import TabItem from '@theme/TabItem'; | ||
| import Tabs from '@theme/Tabs'; | ||
|
|
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
MDX import usage requires .mdx extension; .md will not compile
This file uses MDX imports/components (Tabs, TabItem, custom PackageInstall) but has a .md extension. Docusaurus processes imports/JSX only in .mdx. Rename the file to migrate-prisma.mdx (and update any links), or remove imports and rely on pure Markdown.
To verify other pages aren’t affected, run this repo-local scan:
I can generate a follow-up commit that renames this file and fixes inbound links. Want me to draft it?
🏁 Script executed:
#!/bin/bash
# Find Markdown files that contain `import` or JSX-like tags which require MDX
rg -n --type=md -e '^\s*import\s' -e '<\s*(Tabs|TabItem|PackageInstall)\b' -C2Length of output: 106504
Rename MD files using MDX imports to .mdx
Files under versioned_docs/version-3.x/ that include import statements or JSX (Tabs, TabItem, PackageInstall, etc.) will fail to compile with a .md extension. To fix, rename these to .mdx (and update any links), or remove MDX-specific imports/JSX.
Affected files include, but are not limited to:
- versioned_docs/version-3.x/migrate-prisma.md
- versioned_docs/version-3.x/orm/cli.md
- versioned_docs/version-3.x/reference/zmodel/import.md
- versioned_docs/version-3.x/orm/query-builder.md
- versioned_docs/version-3.x/orm/quick-start.md
- versioned_docs/version-3.x/orm/client.md
- …and all other
.mdfiles found by the scan that import components or embed JSX
To identify all affected files, re-run:
rg -n --type=md -e '^\s*import\s' -e '<\s*(Tabs|TabItem|PackageInstall)\b' -C2 versioned_docs/version-3.xWould you like me to draft a commit that renames these files to .mdx and updates inbound links?
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: There might be a mistake here.
Context: ...all from './_components/PackageInstall'; 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 Tabs from '@theme/Tabs'; # Migra...
(QB_NEW_EN)
🤖 Prompt for AI Agents
versioned_docs/version-3.x/migrate-prisma.md lines 6-9: The file contains MDX
imports/JSX (PackageInstall, TabItem, Tabs) but has a .md extension which breaks
compilation; rename the file to migrate-prisma.mdx and update any inbound
links/TOC references accordingly (and ensure the filesystem and any references
in sidebars or cross-doc links point to the new .mdx path). Repeat for other
affected files listed (orm/cli.md, reference/zmodel/import.md,
orm/query-builder.md, orm/quick-start.md, orm/client.md, etc.) or remove
MDX-specific imports/JSX if you prefer to keep .md; rerun the provided ripgrep
command to find all offending files and update links/sidebars in the repo to the
new .mdx filenames.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
versioned_docs/version-3.x/index.md (4)
1-5: Frontmatter: add a title and optional SEO keywordsAdding an explicit title improves consistency across versioned docs. Keywords help site search/SEO.
Apply this diff:
--- -description: Welcome to ZenStack +title: Welcome to ZenStack v3 +description: Welcome to ZenStack sidebar_label: Welcome sidebar_position: 1 +keywords: + - ZenStack + - v3 + - TypeScript ORM + - Prisma compatibility ---
11-12: Tighten phrasing: “central pillar”; “codebase”Minor language polish for clarity and consistency.
-ZenStack is built with the belief that most applications should use the data model as their center pillar. If that model is well-designed, it can serve as the single source of truth throughout the app's lifecycle and be used to derive many other aspects of the app. The result is a smaller, more cohesive code base that scales well as your team grows while maintaining a high level of developer experience. +ZenStack is built with the belief that most applications should use the data model as their central pillar. If that model is well-designed, it can serve as the single source of truth throughout the app's lifecycle and be used to derive many other aspects of the app. The result is a smaller, more cohesive codebase that scales well as your team grows while maintaining a high level of developer experience.
13-30: Make list links accessible, reduce redundancy, and tone down colloquialisms
- Replace “Inside the package” with “In ZenStack v3” (this is a docs landing page, not a package).
- Use descriptive link text instead of a “🔗” emoji-only link for accessibility.
- Prefer neutral tone: “awesomely-typed” → “richly typed”.
- Collapse the two-line bullets into a single line each for scannability.
-Inside the package you'll find: +In ZenStack v3, you'll find: -- **Intuitive schema language** - - That helps you model data, relations, access control, and more, in one place. [🔗](./modeling/) +- [Intuitive schema language](./modeling/): Model data, relations, access control, and more in one place. -- **Powerful ORM** - - With awesomely-typed API, built-in access control, and unmatched flexibility. [🔗](./orm/) +- [Powerful ORM](./orm/): Richly typed API, built-in access control, and high flexibility. -- **Query-as-a-Service** - - That provides a full-fledged data API without the need to code it up. [🔗](./service/) +- [Query as a Service](./service/): Full‑fledged data API without writing server boilerplate. -- **Utilities** - - For deriving artifacts like Zod schemas, frontend hooks, OpenAPI specs, etc., from the schema. [🔗](./category/utilities) +- [Utilities](./category/utilities): Generate Zod schemas, frontend hooks, OpenAPI specs, and more from your schema.
31-31: Neutralize tone, standardize casing, and use official naming (“Prisma Client”)Keeps the messaging crisp and formal for a landing page.
-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. [This blog post](https://zenstack.dev/blog/next-chapter-1) contains more background about the thoughts behind the v3 refactor. +ZenStack originated as an extension to Prisma ORM. v3 is a complete rewrite that removes Prisma as a runtime dependency and is built on [Kysely](https://kysely.dev/). On the surface, it continues to use a "Prisma‑superset" schema language and offers a query API compatible with Prisma Client. See this blog post for background on the v3 refactor.
📜 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)
docusaurus.config.js(1 hunks)versioned_docs/version-3.x/index.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docusaurus.config.js
🔇 Additional comments (1)
versioned_docs/version-3.x/index.md (1)
7-31: Overall: solid v3 landing page structure and messagingClear value props, concise layout, and accurate positioning relative to Prisma/Kysely. With the small tone and a11y tweaks above, this looks ready.
| - **Intuitive schema language** | ||
|
|
||
| That helps you model data, relations, access control, and more, in one place. [🔗](./modeling/) | ||
|
|
||
| - **Powerful ORM** | ||
|
|
||
| With awesomely-typed API, built-in access control, and unmatched flexibility. [🔗](./orm/) | ||
|
|
||
| - **Query-as-a-Service** | ||
|
|
||
| That provides a full-fledged data API without the need to code it up. [🔗](./service/) | ||
|
|
||
| - **Utilities** | ||
|
|
||
| For deriving artifacts like Zod schemas, frontend hooks, OpenAPI specs, etc., from the schema. [🔗](./category/utilities) |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify internal links resolve within versioned 3.x docs
Check that the linked targets exist and render (modeling, orm, service) and that the “Utilities” category page is present.
Run from repo root:
🏁 Script executed:
#!/bin/bash
set -euo pipefail
base="versioned_docs/version-3.x"
echo "Checking linked doc targets under $base"
# modeling
echo -e "\n[modeling]"
fd -a --strip-cwd-prefix '^index\.md$' "$base/modeling" -x echo FOUND: {} || echo "MISSING: $base/modeling/index.md"
rg -n --type md -C0 '^# ' "$base/modeling" | head -n 5 || true
# orm
echo -e "\n[orm]"
fd -a --strip-cwd-prefix '^index\.md$' "$base/orm" -x echo FOUND: {} || echo "MISSING: $base/orm/index.md"
rg -n --type md -C0 '^# ' "$base/orm" | head -n 5 || true
# service
echo -e "\n[service]"
fd -a --strip-cwd-prefix '^index\.md$' "$base/service" -x echo FOUND: {} || echo "MISSING: $base/service/index.md"
rg -n --type md -C0 '^# ' "$base/service" | head -n 5 || true
# utilities category page (generated from _category_.json)
echo -e "\n[category/utilities]"
fd -a --strip-cwd-prefix '_category_.json' "$base" \
| xargs -I{} jq -r 'select(.label|ascii_downcase=="utilities") | "FOUND category: \(.label) at {}"' 2>/dev/null \
|| echo "MISSING: _category_.json with label \"Utilities\" under $base/**"
echo -e "\nDone. If any target is missing, update the link or add the doc."Length of output: 3154
🏁 Script executed:
#!/bin/bash
set -euo pipefail
base="versioned_docs/version-3.x"
echo "Directories under $base:"
ls -1 "$base" || { echo "Base directory not found: $base"; exit 1; }
echo
echo "[modeling]"
if [[ -f "$base/modeling/index.md" ]]; then
echo "FOUND: modeling/index.md"
else
echo "MISSING: modeling/index.md"
fi
echo "Contents of modeling:"
ls -1 "$base/modeling" || echo "modeling directory not found"
echo
echo "[orm]"
if [[ -f "$base/orm/index.md" ]]; then
echo "FOUND: orm/index.md"
else
echo "MISSING: orm/index.md"
fi
echo "Contents of orm:"
ls -1 "$base/orm" || echo "orm directory not found"
echo
echo "[service]"
if [[ -f "$base/service/index.md" ]]; then
echo "FOUND: service/index.md"
else
echo "MISSING: service/index.md"
fi
echo "Contents of service:"
ls -1 "$base/service" || echo "service directory not found"
echo
echo "[category]"
if [[ -d "$base/category" ]]; then
echo "FOUND: category directory"
echo "Contents of category:"
ls -R "$base/category"
else
echo "MISSING: category directory"
fiLength of output: 1536
🏁 Script executed:
#!/bin/bash
set -euo pipefail
utilities_dir="versioned_docs/version-3.x/utilities"
echo "Inspecting $utilities_dir"
if [[ -d "$utilities_dir" ]]; then
echo "Directory exists"
echo "Files:"
ls -1 "$utilities_dir"
echo
echo "Checking for index.md:"
if [[ -f "$utilities_dir/index.md" ]]; then
echo "FOUND: index.md"
echo "Headings in index.md:"
rg -n '^# ' "$utilities_dir/index.md" | head -n5 || true
else
echo "MISSING: index.md"
fi
else
echo "MISSING: utilities directory"
fiLength of output: 506
Fix broken “Utilities” documentation link
The links to modeling, orm, and service all resolve correctly (each has an index.md under versioned_docs/version-3.x/{modeling,orm,service}). However, the Utilities link points to ./category/utilities, but no such directory or _category_.json entry exists. Instead, there is a versioned_docs/version-3.x/utilities folder containing only zod.md, with no index.md.
Please address this by:
- Adding a landing page at
versioned_docs/version-3.x/utilities/index.mdthat lists available utilities (e.g. zod.md), or - Updating the link in
versioned_docs/version-3.x/index.md(lines 15–29) to point directly at./utilities/zod.md(or other appropriate utilities pages).
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/index.md around lines 15–29 the "Utilities" link
points to ./category/utilities which doesn't exist; either create a landing page
at versioned_docs/version-3.x/utilities/index.md that lists available utilities
(e.g. links to zod.md) with appropriate frontmatter and title, or change the
link in this file to point directly to ./utilities/zod.md (or other specific
utility pages) so the link resolves; pick one approach and update the file(s)
accordingly, ensuring the relative path is correct and the new index.md (if
added) includes links to all utilities present.
There was a problem hiding this comment.
Actionable comments posted: 7
♻️ Duplicate comments (9)
versioned_docs/version-3.x/orm/api/create.md (1)
12-17: Add a concise “Notes” section for batch behavior and return valuesConsolidate expectations for
createManyandcreateManyAndReturnright after this list to avoid misuse and set performance expectations.Suggested insertion immediately below this list:
- `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 against your database/connector.versioned_docs/version-3.x/orm/api/delete.md (1)
12-16: Add concise signatures and return semanticsReaders benefit from explicit method shapes and return values; also call out constraint behavior.
Suggested insertion after this list:
+## 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 +- Behavior (e.g., returning deleted rows) may vary by database/provider; verify for your connector. +- Common errors: unique mismatch, referential constraints (e.g., FK violations).versioned_docs/version-3.x/orm/api/transaction.md (1)
17-22: Fix example mismatch: comment mentions user+post but code creates two usersAlso, the array-form example should only show independent operations. Rename variables and keep both operations independent, or change the comment to not reference post creation.
Apply one of the two options below.
Option A (recommended: two independent user creates)
-// 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' } }), +]);Option B (user + post, still independent: only if your sample repo supports a preexisting authorId)
-// 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 [user, post] = await db.$transaction([ + db.user.create({ data: { name: 'Alice' } }), + // ensure authorId refers to an existing user; do not depend on the first create + db.post.create({ data: { title: 'Hello', authorId: 1 } }), +]);versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (3)
15-21: Clarify “entities being mutated”: name and shape are ambiguousExplicitly document the property name and whether it’s a single object or an array for batch mutations.
- - The entities being mutated (only available when opted in) + - `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 for single-row mutations, or an array for batch mutations (document the exact type used)If actual property names differ (e.g.,
entityvsentities), align the docs to the real API.
22-29: Name the before/after fields and note array vs single behaviorState exact property names and behavior for deletes.
- - The entities before the mutation (only available when opted in) - - The entities after the mutation (only available when opted in) + - `entitiesBefore`: entities as they were before the mutation (when enabled) + - `entitiesAfter`: entities as they are after the mutation (when enabled) + - For batch mutations, both are arrays. For `delete`, `entitiesAfter` is omitted (or explicitly `null`/`undefined`) — document the actual behavior.
30-38: Document the exact return shape and defaults of mutationInterceptionFilterCallers need concrete types and defaults to implement correctly.
- 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 an object indicating whether to intercept and whether to load entities: + - `intercept: boolean` — invoke the hooks for this mutation + - `loadEntities?: boolean | 'before' | 'after' | 'both'` — load entities for the specified phase(s) + - `true`/`'both'`: load for both `before` and `after` + - `'before'`: only for `beforeEntityMutation` + - `'after'`: only for `afterEntityMutation` + - `false`/omitted: do not load entities + + Defaults when omitted: + - `intercept = true` (all mutations are intercepted) + - `loadEntities = false` (entities are not loaded)If the real API differs, please replace with the exact property names and types.
versioned_docs/version-3.x/orm/computed-fields.md (3)
21-22: Grammar fix: “a computed fields” → “a computed field”Minor copy edit for number agreement and clarity.
-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.
6-8: MDX features used in a .md file — this won’t compile in DocusaurusThis page imports components and uses JSX. With a .md extension, Docusaurus won’t process imports/components, and the page will break. Rename to computed-fields.mdx (and update any inbound links). If you must keep Markdown, replace components with plain Markdown/admonitions, but you’ll lose interactivity.
Run a quick scan to catch any other .md files that contain MDX features:
#!/bin/bash set -euo pipefail # Find .md files under versioned v3 docs that contain imports or JSX-ish tags rg -n --hidden --no-ignore -S --glob 'versioned_docs/version-3.x/**/*.md' -C2 $'^(import\\s|<\\s*[A-Za-z])' || trueAlso applies to: 11-15, 68-69
32-41: Incorrect Kysely reference: whereRef compares to an unqualified 'id'The first snippet uses
whereRef('Post.authorId', '=', 'id'), which is ambiguous/wrong (points to no table). Qualify it with the correct table column and add the missing import.```ts +import { sql } from 'kysely'; const db = new ZenStackClient(schema, { ... computedFields: { User: { - postCount: (eb) => + postCount: (eb) => eb.selectFrom('Post') - .whereRef('Post.authorId', '=', 'id') - .select(({fn}) => fn.countAll<number>().as('count')), + .whereRef('Post.authorId', '=', sql.ref('User.id')) + .select(({ fn }) => fn.countAll<number>().as('count')), }, }, });
🧹 Nitpick comments (35)
versioned_docs/version-3.x/orm/typed-json.md (5)
6-7: Standardize component import paths for reliability across versioned docsMixing relative (
../_components/...) and alias (@site/...) imports can break when docs are versioned/moved. Prefer site-level aliases for both, or ensure a stable docs-local components directory exists for all versions.Apply if
ZenStackVsPrismalives undersrc/components:-import ZenStackVsPrisma from '../_components/ZenStackVsPrisma'; +import ZenStackVsPrisma from '@site/src/components/ZenStackVsPrisma';If it’s intentionally under
versioned_docs/version-3.x/_components, keep the relative path but consider mirroring this pattern across v3 pages for consistency.
11-13: Avoid absolute/evergreen statements; de-contract and time-boundDocs age better if we time-bound comparisons and avoid contractions.
Apply:
-Strongly typed JSON is a ZModel feature and doesn't exist in Prisma. +Strongly typed JSON is a ZModel feature and is not available in Prisma (as of ZenStack v3.0).
15-19: Tighten wording and clarify “loose” validation semantics
- Singular/plural agreement for the return type.
- “Loosely validates” is vague; clarify what happens to unknown keys and when validation occurs.
Proposed rewrite (please verify the behavior around extra fields before merging):
-ZModel allows you to define custom types and use them to [type JSON fields](../modeling/typed-json.md). The ORM respects such fields in two ways: +ZModel allows you to define custom types and use them to [type JSON fields](../modeling/typed-json.md). The ORM respects such fields in two ways: -1. The return type of such fields is typed as TypeScript types derived from the ZModel custom type definition. -2. When creating or updating such fields, the ORM validates the input against the custom type definition. The engine "loosely" validates the mutation input and doesn't prevent you from including fields not defined in the custom type. +1. The return value of such fields is a TypeScript type derived from the ZModel custom type definition. +2. On create/update, the ORM validates input against the custom type definition. Validation is intentionally “loose”: unknown fields (not defined in the custom type) are allowed and are not rejected by the validator. Consider whether they are persisted as-is in your store and document accordingly.Optionally add a short note to preempt questions:
+:::note +“Loose” validation helps with forward-compatible payloads. If you need to strictly reject unknown keys, link to the recommended approach (if any) in ZenStack v3. +:::
20-23: Add a one-line lead-in for the sampleA short sentence improves scannability and SEO snippets.
-## Samples +## Samples +Try the interactive sample that models a typed JSON field and shows runtime validation and typed readbacks:
23-23: Ensure the StackBlitz embed is deterministic and files exist
- Confirm
zenstack/schema.zmodelandmain.tsexist inzenstackhq/v3-doc-orm-typed-json.- If the
StackBlitzGithubcomponent supports pinning (branch/tag/commit), consider pinning to avoid future breakage when the sample repo updates.If supported by the component, for example:
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-typed-json" codeFiles={['zenstack/schema.zmodel', 'main.ts']} /> +<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-typed-json" branchOrTag="v3.0" codeFiles={['zenstack/schema.zmodel', 'main.ts']} />If pinning isn’t supported, consider referencing a specific commit SHA in the component props (if available) or documenting the expected repo state.
versioned_docs/version-3.x/orm/api/create.md (2)
10-10: Minor style: tighten wording“create new records in the database” → “create records”.
-The `create` series of APIs are used to create new records in the database. It has the following methods: +The `create` series of APIs create records. It includes the following methods:
1-23: Normalize comma-separatedstartScriptusage inStackBlitzGithubembeds
Several of our docs currently pass comma-separated scripts (e.g.startScript="generate,dev") to theStackBlitzGithubcomponent. Only the first script in that list ever runs, causing the second command to silently no-op. To ensure all steps execute, please consolidate each pair into a single named script (or chained command) in your project’spackage.json, then update the embeds to reference that script.Affected embeds (all use comma-separated
startScript):
- versioned_docs/version-3.x/orm/polymorphism.md:33 (
startScript="generate,dev")- versioned_docs/version-3.x/orm/query-builder.md:27 (
startScript="generate,query-builder")- versioned_docs/version-3.x/orm/plugins/query-api-hooks.md:25 (
startScript="generate,query-api-hooks")- versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md:51 (
startScript="generate,entity-mutation-hooks")- versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md:28 (
startScript="generate,kysely-query-hooks")- versioned_docs/version-3.x/orm/api/find.md:
• line 35 (startScript="generate,find:basic")
• line 45 (startScript="generate,find:sort")
• line 51 (startScript="generate,find:pagination")
• line 59 (startScript="generate,find:selection")- versioned_docs/version-3.x/orm/api/filter.md:
• line 24 (startScript="generate,filter:basic")
• line 30 (startScript="generate,filter:relation")
• line 86 (startScript="generate,filter:query-builder")- versioned_docs/version-3.x/orm/api/update.md:
• line 19 (startScript="generate,update:scalar")
• line 48 (startScript="generate,update:relation")- versioned_docs/version-3.x/orm/api/transaction.md:43 (
startScript="generate,transaction")- versioned_docs/version-3.x/orm/api/group-by.md:43 (
startScript="generate,group-by")- versioned_docs/version-3.x/orm/api/delete.md:20 (
startScript="generate,delete")- versioned_docs/version-3.x/orm/api/count.md:12 (
startScript="generate,count")- versioned_docs/version-3.x/orm/api/aggregate.md:22 (
startScript="generate,aggregate")- versioned_docs/version-3.x/orm/api/create.md:21 (
startScript="generate,create")Suggested approach:
- In your repo’s
package.json, add combined scripts, e.g.:{ "scripts": { "start:generate-dev": "npm run generate && npm run dev", "start:generate-query-builder": "npm run generate && npm run query-builder", … } }- Update each embed to use the new script key, e.g.:
<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="start:generate-query-builder"/>
3. Remove all comma-separated props once replaced. This ensures every required command runs in sequence rather than silently skipping. </blockquote></details> <details> <summary>versioned_docs/version-3.x/orm/plugins/query-api-hooks.md (2)</summary><blockquote> `13-20`: **Clarify hook callback parameters and naming** Use code-styled parameter names and tighten phrasing for easier scanning. ```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({ onQuery(...) { ... } })`. The callback receives: + +- `model`: the model being queried +- `operation`: e.g. `create`, `findUnique`, etc. +- `args`: the query arguments (you may read/modify) +- `client`: the ORM client that initiated the call +- `proceed`: a function to continue the operation (call it to execute)
21-21: Cross-reference the query builder pageLinking helps readers understand why query-builder calls don’t trigger these hooks.
-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 [Query Builder API](../query-builder.md)).versioned_docs/version-3.x/orm/api/group-by.md (2)
32-33: Grammar: fix agreement and clarity for aggregation note- In this case, the fields of aggregation doesn't need to be in the `by` clause. + In this case, the fields used for aggregation don't need to be in the `by` clause.
20-23: Clarify where vs having semanticsA short note helps users reason about filter placement.
-You can also use `where`, `orderBy`, `skip`, and `take` to control what records are included in the aggregation. +You can also use `where`, `orderBy`, `skip`, and `take` to control what records are included. +Use `where` to filter rows before grouping; use `having` to filter groups after aggregation.versioned_docs/version-3.x/orm/query-builder.md (1)
19-19: Grammar: “its typing”, not “it’s typing”-No extra setup is needed to use the query builder API. The ORM client has a `$qb` property that provides the Kysely query builder, and it's typing is inferred from the ZModel schema. +No extra setup is needed to use the query builder API. The ORM client has a `$qb` property that provides the Kysely query builder, and its typing is inferred from the ZModel schema.versioned_docs/version-3.x/orm/api/delete.md (1)
14-14: Punctuation: end the list item with a period-- `deleteManyAndReturn` - Similar to `deleteMany`, but returns the deleted records +- `deleteManyAndReturn` - Similar to `deleteMany`, but returns the deleted records.src/components/GithubCodeBlock.tsx (1)
3-6: Nit: clarify prop name for intentConsider renaming
filetofilePathto better convey that nested paths are allowed (e.g.,find/basic.ts), which improves self-documentation at call sites.versioned_docs/version-3.x/orm/api/update.md (3)
10-16: Tighten wording and punctuation for the methods listMinor copyedits for consistency and readability.
-Update to records can be done with the following methods: +Updates to records can be done with the following methods: @@ -- `updateManyAndReturn` - Similar to `updateMany`, but returns the updated records +- `updateManyAndReturn` - Similar to `updateMany`, but returns the updated records.
21-25: Fix typo and add provider support note for list operators
- “In additional” → “In addition”.
- Since list fields are PostgreSQL-only (as mentioned elsewhere), call it out here to avoid confusion.
-In additional to the standard way of updating fields, list fields support the following operators: +In addition to the standard way of updating fields, list fields support the following operators: @@ - `set`: Replace the entire list with a new list (equivalent to setting the field directly). + +:::info +List fields are currently supported only by the PostgreSQL provider. +:::
44-46: Fix capitalization and soften intensifierTypo “THe” and avoid overusing “very”.
-THe `update` and `upsert` methods are very powerful in that they allow you to freely manipulate relations. You can create, connect, disconnect, update, and delete relations in a single operation. You can also reach deeply into indirect relations. +The `update` and `upsert` methods are powerful: they allow you to freely manipulate relations. You can create, connect, disconnect, update, and delete relations in a single operation. You can also reach deeply into indirect relations.versioned_docs/version-3.x/orm/api/find.md (2)
17-31: Copyedit: method descriptions and grammarImprove clarity and correctness (“criterion” vs. “criteria”).
- Find a single record with a unique criteria. + Find a single record with a unique criterion. @@ - Similar to `findUnique`, but throws an error if no record is found. + Similar to `findUnique`, but throws an error if no record is found. @@ - Similar to `findFirst`, but throws an error if no record is found. + Similar to `findFirst`, but throws an error if no record is found.
41-45: Clarify sorting sentenceAvoid repeating “sort field” and make the option name explicit.
-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 the field, direction, and null placement. Sorting is not supported for `findUnique` and `findUniqueOrThrow`.versioned_docs/version-3.x/orm/api/filter.md (3)
11-12: Improve parallelism in the introductory sentenceKeep verb forms parallel.
-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.
41-43: Consistency with list-field provider noteGood call-out that list type is PostgreSQL-only. Consider cross-linking to the Update page’s list-operator note once updated, for consistency.
70-75: Use “JSON” capitalization and tidy wordingUse standard “JSON” capitalization in headings and content.
-## Json filters +## JSON filters @@ -Filtering on Json fields is work in progress and will be available soon. +Filtering on JSON fields is work in progress and will be available soon.versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md (3)
11-14: Tighten phrasing; avoid absolute claimsSlightly soften language and improve flow.
-Kysely query hooks are the lowest level of interceptors in the plugin system. Since ZenStack eventually delegates all database access to Kysely, these hooks allow you to inspect and modify all SQL queries before they are sent to the database, regardless of whether they originate from the ORM query API or the query builder API. -This mechanism gives you great power to control the ORM's behavior entirely. One good example is the [access policy](../access-control/) - the access policy enforcement is entirely achieved via intercepting the Kysely queries. +Kysely query hooks are the lowest-level interceptors in the plugin system. Since ZenStack delegates database access to Kysely, these hooks let you inspect and modify SQL queries before they are sent to the database—regardless of whether they originate from the ORM query API or the query builder API. +This mechanism gives you fine-grained control over ORM behavior. For example, [access policy](../access-control/) enforcement is implemented by intercepting Kysely queries.
15-21: Bullet list consistency and clarityMake the list parallel and add brief clarifications.
-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: - -- 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 +To create a Kysely query hook plugin, call `$use` with an object containing an `onKyselyQuery` callback. The callback runs before each Kysely query and receives a context object containing: + +- Kysely instance +- Kysely query node (SQL AST) +- ORM client that triggered the query +- Proceed function to send the query to the database
24-26: Add a caution about AST manipulation costA short cautionary note can set expectations for users poking at
QueryNodetrees.:::info Kysely's `QueryNode` objects are low-level and not easy to process. ZenStack will provide helpers to facilitate common tasks in the future. ::: + +:::caution +Modifying SQL ASTs can have wide-reaching effects and performance implications. Prefer helper utilities where possible and keep transformations minimal and well-tested. +:::versioned_docs/version-3.x/orm/api/transaction.md (2)
1-4: Add a front-matter title for consistency and sidebar labelingDocusaurus benefits from an explicit title; several pages in this PR already include one.
Apply:
--- +title: Transaction sidebar_position: 9 description: Transaction API ---
31-31: Tighten grammar: “so as to” → “to”-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, keep the transaction callback fast to reduce the transaction’s performance impact on the database.versioned_docs/version-3.x/orm/quick-start.md (1)
1-4: Add a front-matter title for consistency--- +title: Quick Start sidebar_position: 1 description: Quick start guide ---src/components/StackBlitzGithub.tsx (2)
24-26: Avoid parameter reassignment; derive a local files array- if (!plainCodeFiles) { - plainCodeFiles = [openFile]; - } + const files = plainCodeFiles ?? [openFile]; ... - {plainCodeFiles.map((file) => ( + {files.map((file) => ( <GithubCodeBlock key={file} repoPath={repoPath} file={file} /> ))}Benefits: clearer intent, no param mutation, plays nicer with lint rules like no-param-reassign.
Also applies to: 37-39
18-23: Type options from the SDK for forward compatibility and include startScript conditionally- const options = { - openFile, - view: 'editor', - startScript, - } as const; + type OpenGithubOptions = Parameters<typeof sdk.openGithubProject>[1]; + const options: OpenGithubOptions = { + openFile, + view: 'editor', + ...(startScript ? { startScript } as OpenGithubOptions : {}), + };versioned_docs/version-3.x/orm/polymorphism.md (1)
11-13: Grammar: plural agreementUse “are” with the plural subject.
-Polymorphic models is a major feature that sets ZenStack apart from Prisma. +Polymorphic models are a major feature that set ZenStack apart from Prisma.versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (3)
39-39: Clarify rollback behaviorState explicitly that
afterEntityMutationis not called if the transaction is rolled back.-If a mutation happens inside a transaction, the `afterEntityMutation` callback is called after the transaction is committed. +If a mutation happens inside a transaction, `afterEntityMutation` is called after commit. It is not called if the transaction rolls back.
45-47: Tone and concision in warningMinor copy edit for clarity and concision.
-:::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 +Enabling entity loading for both “before” and “after” can be expensive. Batch mutations may load many entities and incur significant overhead. +:::
11-12: Confirm coverage: hooks triggered for both ORM queries and query builderIf there are edge cases where only one path triggers hooks, call them out here.
I can help add a short table clarifying which operations fire the hooks (ORM, query builder, raw SQL, cascading actions, bulk ops).
versioned_docs/version-3.x/orm/computed-fields.md (1)
32-44: Reduce duplication and potential confusion: keep only the context-aware snippetThe second example demonstrates the preferred, context-aware approach (
sql.ref(currentModel, 'id')). Consider removing the first snippet to avoid maintaining two similar variants and reduce the chance of inconsistencies.Also applies to: 48-64
📜 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 ignored due to path filters (2)
package.jsonis excluded by!**/*.jsonpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml,!**/*.yaml
📒 Files selected for processing (27)
.gitmodules(1 hunks)code-repos/zenstackhq/v3-doc-orm(1 hunks)code-repos/zenstackhq/v3-doc-orm-computed-fields(1 hunks)code-repos/zenstackhq/v3-doc-orm-polymorphism(1 hunks)code-repos/zenstackhq/v3-doc-orm-typed-json(1 hunks)code-repos/zenstackhq/v3-doc-quick-start(1 hunks)src/components/GithubCodeBlock.tsx(1 hunks)src/components/StackBlitzGithub.tsx(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/group-by.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/inferred-types.md(1 hunks)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)versioned_docs/version-3.x/orm/polymorphism.md(1 hunks)versioned_docs/version-3.x/orm/query-builder.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.md(1 hunks)versioned_docs/version-3.x/orm/typed-json.md(1 hunks)
✅ Files skipped from review due to trivial changes (7)
- code-repos/zenstackhq/v3-doc-quick-start
- code-repos/zenstackhq/v3-doc-orm
- code-repos/zenstackhq/v3-doc-orm-computed-fields
- code-repos/zenstackhq/v3-doc-orm-typed-json
- code-repos/zenstackhq/v3-doc-orm-polymorphism
- versioned_docs/version-3.x/orm/api/count.md
- .gitmodules
🚧 Files skipped from review as they are similar to previous changes (3)
- versioned_docs/version-3.x/orm/api/aggregate.md
- versioned_docs/version-3.x/orm/inferred-types.md
- versioned_docs/version-3.x/orm/cli.md
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md
[grammar] ~16-~16: There might be a mistake here.
Context: ...It receives a context object containing: - The model - The action (create, ...
(QB_NEW_EN)
[grammar] ~23-~23: There might be a mistake here.
Context: ...It receives a context object containing: - The model - The action (create, ...
(QB_NEW_EN)
[grammar] ~32-~32: There might be a mistake here.
Context: ...It receives a context object containing: - The model - The action (create, ...
(QB_NEW_EN)
[grammar] ~42-~42: There might be a mistake here.
Context: ...t captured by the entity mutation hooks. ::: :::warning Be very careful about op...
(QB_NEW_EN)
[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/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 StackBlitzGithub from '@site/src/...
(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: ...'@site/src/components/StackBlitzGithub'; 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/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)
versioned_docs/version-3.x/orm/api/update.md
[style] ~44-~44: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... THe update and upsert methods are very powerful in that they allow you to freely manipu...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/orm/computed-fields.md
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
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)
versioned_docs/version-3.x/orm/polymorphism.md
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
[grammar] ~21-~21: There might be a mistake here.
Context: ...out an associated concrete model entity. 2. When querying a base model (either top-l...
(QB_NEW_EN)
[grammar] ~25-~25: There might be a mistake here.
Context: ...ts base entity is automatically created. - When querying a base entity, the ORM fet...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/query-builder.md
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/quick-start.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...'@site/src/components/StackBlitzGithub'; import ZModelStarter from '../_component...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...rom '../_components/_zmodel-starter.md'; import PackageInstall from '../_componen...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...rom '../_components/PackageInstall.tsx'; import PackageExec from '../_components/...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/typed-json.md
[grammar] ~6-~6: There might be a mistake here.
Context: ... from '../_components/ZenStackVsPrisma'; import StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
🔇 Additional comments (9)
src/components/GithubCodeBlock.tsx (1)
8-25: Use a webpack context for raw‐loader and add a graceful fallbackHoist a single
require.contextso webpack can statically include all files under@site/code-repos, replace the inline dynamicrequirewith a context lookup wrapped intry/catch, and expand your file‐extension–to–language mapping.• In
src/components/GithubCodeBlock.tsx, before your component definition, add:// Hoist a raw-loader context so webpack can statically include all files under @site/code-repos // Leading '!' forces raw-loader for every matched file. const RAW_CTX = require.context('!raw-loader!@site/code-repos', true, /.+/);• Replace the inline require inside your component with:
- const code = require(`!!raw-loader!@site/code-repos/${repoPath}/${file}`).default; + let code: string; + try { + // prepend './' because context keys are relative to the context root + code = RAW_CTX(`./${repoPath}/${file}`).default as string; + } catch (err) { + code = `Unable to load "${repoPath}/${file}": ${ + err instanceof Error ? err.message : String(err) + }`; + }• Update
getLanguageto recognize a broader set of extensions:- const getLanguage = (file: string): string => { - if (file.endsWith('.ts')) { - return 'typescript'; - } else if (file.endsWith('.zmodel')) { - return 'zmodel'; - } else { - return 'plaintext'; - } - }; + const getLanguage = (file: string): string => { + if (file.endsWith('.ts')) return 'typescript'; + if (file.endsWith('.tsx')) return 'tsx'; + if (file.endsWith('.js')) return 'javascript'; + if (file.endsWith('.jsx')) return 'jsx'; + if (file.endsWith('.zmodel')) return 'zmodel'; + if (file.endsWith('.json')) return 'json'; + if (file.endsWith('.md')) return 'markdown'; + if (/\.(ya?ml)$/.test(file)) return 'yaml'; + if (file.endsWith('.sql')) return 'sql'; + return 'plaintext'; + };Next steps:
- Verify that
raw-loaderis listed in yourdevDependenciesand compatible with your Docusaurus (Webpack 5) setup.- If you prefer to move away from inline loaders in the future, consider using Webpack 5’s
asset/sourcefor raw imports.versioned_docs/version-3.x/orm/api/find.md (1)
61-68: Confirm provider support fordistinctand adjust wordingThe note says it’s “not available for SQLite,” but
DISTINCT ONis a PostgreSQL-specific feature; MySQL also doesn’t supportDISTINCT ON. If the implementation truly relies onDISTINCT ON, this is likely PostgreSQL-only.Proposed wording (pending verification):
-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 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 currently only supported for the PostgreSQL provider.If MySQL is supported through a different strategy, please update the note accordingly.
versioned_docs/version-3.x/orm/api/filter.md (1)
20-21: Verify string comparatorsYou list
lt/lte/gt/gtefor “String” fields. Are lexical comparisons on strings officially supported across providers? If not, consider removing “String” from this bullet to avoid implying cross-provider support.versioned_docs/version-3.x/orm/plugins/kysely-query-hooks.md (1)
13-13: Verify link targetPlease confirm
../access-control/resolves correctly from this page’s location in the built docs.versioned_docs/version-3.x/orm/api/transaction.md (1)
43-43: Verify startScript semantics: comma-separated scripts likely won’t runThe StackBlitz SDK’s openGithubProject typically accepts a single start script. Passing "generate,transaction" will be treated as one script name, not two.
Proposed fixes:
- Prefer a single script that chains tasks in package.json, e.g.,
"transaction": "npm run generate && node transaction.ts", then usestartScript="transaction".- Or update the StackBlitzGithub component to support multiple scripts (see component review).
If you want me to sweep the repo for other comma-separated startScript usages and prepare a unified patch, I can do that.
versioned_docs/version-3.x/orm/quick-start.md (1)
13-15: Time-bound the “@next” note to avoid staleness after release-:::info -All v3 packages are currently published under the "@next" tag. -::: +:::info +As of August 2025, all v3 packages are published under the "@next" tag. +:::If v3 GA happens, remember to remove this note and update commands accordingly.
src/components/StackBlitzGithub.tsx (1)
5-10: Address startScript prop consistency and migration planWe’ve identified 18 occurrences of comma-separated
startScriptvalues in theversioned_docs/version-3.x/orm/…files, for example:
- versioned_docs/version-3.x/orm/polymorphism.md:
<StackBlitzGithub … startScript="generate,dev" />- versioned_docs/version-3.x/orm/query-builder.md:
<StackBlitzGithub … startScript="generate,query-builder" />- versioned_docs/version-3.x/orm/plugins/query-api-hooks.md:
<StackBlitzGithub … startScript="generate,query-api-hooks" />
… (and 15 more)These all assume two commands chained via commas, but the SDK’s
startScriptexpects a single npm script name, so passing"generate,dev"will be interpreted literally (and fail).Recommend choosing one of two migration paths:
Enhance component to accept multiple scripts
• Change prop tostartScripts?: string[]
• Internally join them (e.g.npm run generate && npm run dev) via a small bootstrap wrapper shipped with sample repos
• Update usage sites to pass arrays:startScripts={['generate','dev']}Enforce a single script convention
• ConstrainstartScript?: stringto a single name
• Sweep all docs and sample-repopackage.jsonfiles to define combined scripts (e.g."dev:full": "npm run generate && npm run dev")
• ReplacestartScript="generate,dev"withstartScript="dev:full"across docsTo locate all remaining comma-separated usages (including outside versioned_docs), run:
rg -nP 'StackBlitzGithub[^\n]*startScript\s*=\s*"[^\"]+,[^\"]+"'Please review and confirm which path you’d like to take, so we can proceed with the corresponding implementation and doc updates.
versioned_docs/version-3.x/orm/polymorphism.md (1)
33-33: Verify startScript usage with StackBlitzGithubThis passes "generate,dev". Ensure the component supports multiple scripts, or switch to a single script that chains tasks in package.json.
Suggested change if you use a single chained script:
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-polymorphism" codeFiles={['zenstack/schema.zmodel', 'main.ts']} startScript="generate,dev" /> +<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-polymorphism" codeFiles={['zenstack/schema.zmodel', 'main.ts']} startScript="dev" />And in the sample repo’s package.json:
{ "scripts": { "dev": "npm run generate && node main.ts" } }versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (1)
51-51: Verify StackBlitz startScript usageAs with other pages, confirm that multiple scripts are supported or switch to a single chained script in the sample repo.
Proposed:
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/entity-mutation-hooks.ts" startScript="generate,entity-mutation-hooks" /> +<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/entity-mutation-hooks.ts" startScript="entity-mutation-hooks" />And in the sample repo:
{ "scripts": { "entity-mutation-hooks": "npm run generate && node plugins/entity-mutation-hooks.ts" } }
| Click{' '} | ||
| <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}> | ||
| here | ||
| </a>{' '} | ||
| to open an interactive playground. | ||
| </div> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Prevent default navigation and add a non-JS fallback URL
href="#" causes a jump to top. Provide a real link (good for accessibility and no-JS users), open in a new tab, and prevent default when JS is available.
- <div className="mb-1">
- Click{' '}
- <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}>
- here
- </a>{' '}
- to open an interactive playground.
- </div>
+ <div className="mb-1">
+ Click{' '}
+ <a
+ href={`https://stackblitz.com/github/${repoPath}?file=${encodeURIComponent(openFile)}&view=editor`}
+ target="_blank"
+ rel="noopener noreferrer"
+ onClick={(e) => {
+ e.preventDefault();
+ void sdk.openGithubProject(repoPath, options);
+ }}
+ >
+ here
+ </a>{' '}
+ to open an interactive playground.
+ </div>📝 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.
| Click{' '} | |
| <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}> | |
| here | |
| </a>{' '} | |
| to open an interactive playground. | |
| </div> | |
| <div className="mb-1"> | |
| Click{' '} | |
| <a | |
| href={`https://stackblitz.com/github/${repoPath}?file=${encodeURIComponent(openFile)}&view=editor`} | |
| target="_blank" | |
| rel="noopener noreferrer" | |
| onClick={(e) => { | |
| e.preventDefault(); | |
| void sdk.openGithubProject(repoPath, options); | |
| }} | |
| > | |
| here | |
| </a>{' '} | |
| to open an interactive playground. | |
| </div> |
🤖 Prompt for AI Agents
In src/components/StackBlitzGithub.tsx around lines 31 to 36, the anchor uses
href="#" which causes a jump-to-top and provides no non-JS fallback; change the
anchor to use a real URL (e.g. construct the GitHub project URL from repoPath
like https://github.com/{repoPath} or use repoPath if it is already a full URL),
add target="_blank" and rel="noopener noreferrer" for a safe new tab, and update
the onClick to preventDefault before calling sdk.openGithubProject(repoPath,
options) so JS users get the SDK behavior while non-JS users can still open the
project via the link.
|
|
||
| ## Samples | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="create.ts" startScript="generate,create" /> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix StackBlitz startScript: comma-separated values are not supported
Passing startScript="generate,create" is likely ignored by the StackBlitz SDK, which expects a single script name. Use one script that runs both steps, or chain commands if supported by your embed helper.
Apply one of the following:
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="create.ts" startScript="generate,create" />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="create.ts" startScript="generate-and-create" />And in the sample repo (zenstackhq/v3-doc-orm), define:
{
"scripts": {
"generate-and-create": "npm run generate && npm run create"
}
}If your embed supports shell chaining directly, an alternative is:
- startScript="generate,create"
+ startScript="npm run generate && npm run create"🤖 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 is invalid because the SDK
accepts a single script name; change the embed to reference a single script that
runs both steps (e.g., startScript="generate-and-create"), and update the sample
repo (zenstackhq/v3-doc-orm) package.json to add a scripts entry that runs both
commands (or, if the embed supports it, use a single chained shell command
instead).
|
|
||
| ## Samples | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="delete.ts" startScript="generate,delete" /> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix StackBlitz startScript: use a single script
startScript="generate,delete" should be one script or a chained command.
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="delete.ts" startScript="generate,delete" />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="delete.ts" startScript="generate-and-delete" />Add generate-and-delete in the sample repo, or use a chained command if supported.
📝 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.
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="delete.ts" startScript="generate,delete" /> | |
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="delete.ts" startScript="generate-and-delete" /> |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/api/delete.md around line 20 the
StackBlitzGithub component uses startScript="generate,delete" which is invalid
because startScript must be a single script name; change the attribute to
reference a single script that runs both steps (either add a new script name
like "generate-and-delete" to the sample repo and use that here, or replace with
a chained command supported by the environment such as "generate && delete" and
ensure the repo's package.json has the corresponding script).
|
|
||
| ## Samples | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="group-by.ts" startScript="generate,group-by" /> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix StackBlitz startScript: use a single script
startScript="generate,group-by" should be a single script or a chained command.
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="group-by.ts" startScript="generate,group-by" />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="group-by.ts" startScript="generate-and-group-by" />Add generate-and-group-by in the sample repo (or chain with npm run generate && npm run group-by).
📝 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.
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="group-by.ts" startScript="generate,group-by" /> | |
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="group-by.ts" startScript="generate-and-group-by" /> |
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/api/group-by.md around line 43: the StackBlitz
component uses startScript="generate,group-by" which is invalid because
startScript must be a single script name or a chained command; update the
attribute to reference a single script that runs both steps (e.g.,
startScript="generate-and-group-by") and add that script to the sample repo
package.json (or replace with a chained command like startScript="npm run
generate && npm run group-by") so the StackBlitz start command executes both
generate and group-by in one step.
|
|
||
| ## Samples | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate,query-api-hooks" /> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix StackBlitz startScript: use a single script
Same issue as other pages: startScript="generate,query-api-hooks" should be a single script or a chained command.
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate,query-api-hooks" />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate-and-query-api-hooks" />Add generate-and-query-api-hooks in the sample repo, or chain with npm run.
📝 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.
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate,query-api-hooks" /> | |
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="plugins/query-api-hooks.ts" startScript="generate-and-query-api-hooks" /> |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/plugins/query-api-hooks.md around line 25, the
StackBlitz component uses startScript="generate,query-api-hooks" which is
invalid; change it to a single script or a chained command. Either add a new npm
script in the sample repo named "generate-and-query-api-hooks" that runs the
generate step then query-api-hooks, and update startScript to
"generate-and-query-api-hooks", or replace the value with a chained command
using npm run (for example startScript="npm run generate && npm run
query-api-hooks") so StackBlitz can execute the steps in sequence.
|
|
||
| The samples assume you have a basic understanding of Kysely. | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="generate,query-builder" /> |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fix StackBlitz startScript: use a single script
startScript="generate,query-builder" should be a single script or a chained command.
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="generate,query-builder" />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="generate-and-query-builder" />Define generate-and-query-builder in the sample repo, or chain via npm run.
📝 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.
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="generate,query-builder" /> | |
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-orm" openFile="query-builder.ts" startScript="generate-and-query-builder" /> |
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/query-builder.md around line 27: the StackBlitz
open tag uses startScript="generate,query-builder" which is invalid because
startScript must be a single script name or a single shell command; update the
tag to reference a single script name (e.g., generate-and-query-builder) or
replace it with a chained command that runs both scripts (e.g., run the generate
script then run the query-builder script via npm run chaining), and ensure the
referenced script is added to the sample repo's package.json so StackBlitz can
execute it.
|
|
||
| Or simply use the following playground to experience it inside the browser. | ||
|
|
||
| <StackBlitzGithub repoPath="zenstackhq/v3-doc-quick-start" /> |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Confirm sample repo availability and submodule state
Ensure zenstackhq/v3-doc-quick-start is available and, if referenced as a submodule, it is added and pinned to a working commit.
Run:
If not vendored, consider adding a fallback link text explaining it opens on StackBlitz and may take time to provision.
🏁 Script executed:
#!/bin/bash
# From repo root: check for the sample repo/submodule references
rg -n "v3-doc-quick-start"
fd -a "v3-doc-quick-start" -t d
git submodule status || trueLength of output: 813
Confirm v3-doc-quick-start submodule initialization
- Files:
versioned_docs/version-3.x/orm/quick-start.md(line 29)versioned_docs/version-3.x/orm/cli.md(line 16)
The sample repo is declared as a submodule but currently uninitialized (git submodule status shows -81b6de5c65ec8dbbd53d174644c4e8516ee9e1f6 code-repos/zenstackhq/v3-doc-quick-start). To resolve:
- Run
git submodule update --init code-repos/zenstackhq/v3-doc-quick-start git add .gitmodules code-repos/zenstackhq/v3-doc-quick-start git commit -m "Initialize v3-doc-quick-start submodule" - If you prefer not to vendor the sample repo, add fallback link text next to
<StackBlitzGithub>noting that it opens in StackBlitz and may take a moment to provision.
🤖 Prompt for AI Agents
versioned_docs/version-3.x/orm/quick-start.md (line 29) and
versioned_docs/version-3.x/orm/cli.md (line 16): the sample repo submodule
code-repos/zenstackhq/v3-doc-quick-start is uninitialized; either initialize and
commit the submodule and .gitmodules in the repo (update the submodule at that
path and add/commit the changes) so the StackBlitzGithub component can reference
the vendored sample, or if you prefer not to vendor it, leave the component
as-is and add a short fallback note immediately next to the <StackBlitzGithub>
reference indicating that the sample opens in StackBlitz and may take a moment
to provision (so users aren’t blocked by the missing submodule).
There was a problem hiding this comment.
Actionable comments posted: 6
♻️ Duplicate comments (20)
versioned_docs/version-3.x/modeling/polymorphism.md (2)
16-19: Tighten intro wording and normalize casing (“object-oriented”, “is-a/has a/has many”)Polish for grammar and consistency; mirrors prior feedback.
-When modeling non-trivial applications, the need of an "Object-Oriented" kind of polymorphism often arises: -- Something **IS-A** more abstract type of thing. -- Something **HAS-A/HAS-many** a more abstract type of thing(s). +When modeling non-trivial applications, the need for an "object-oriented" kind of polymorphism often arises: +- Something **is-a** more abstract type. +- Something **has a/has many** relationship with a more abstract type.
107-108: Tighten wording and fix pluralizationMatches prior feedback; removes “Just need to” phrasing.
-You can also have a deep hierarchy involving multiple levels of base models. Just need to make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported. +You can also have a deep hierarchy involving multiple levels of base models. Just make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported.versioned_docs/version-3.x/orm/api/filter.md (1)
26-34: List operators section looks consistent now (no strayhasNone).Previous inconsistency around
hasNoneseems resolved. The operators listed match the examples below. LGTM.versioned_docs/version-3.x/orm/quick-start.md (1)
27-30: Add a fallback link/caption for StackBlitz and address submodule initialization.
- Provide a visible fallback link/caption so users have a clear path if the embed doesn’t load or when browsing offline.
- Also confirm the
code-repos/zenstackhq/v3-doc-quick-startsubmodule is initialized and pinned; otherwise, the embed may break locally.Or simply use the interactive playground to experience it inside the browser. <StackBlitzGithub repoPath="zenstackhq/v3-doc-quick-start" /> +<p> +If the embed doesn't load, open the sample directly on StackBlitz: +<a href="https://stackblitz.com/github/zenstackhq/v3-doc-quick-start" target="_blank" rel="noopener">zenstackhq/v3-doc-quick-start</a>. +It may take a moment to provision. +</p>Run the following to verify submodule state from repo root:
#!/bin/bash set -euo pipefail echo "Searching for v3 quick start submodule..." rg -n "v3-doc-quick-start" -S || true echo echo "Listing candidate directories:" fd -a "v3-doc-quick-start" -t d || true echo echo "Submodule status:" git submodule status || true echo echo "If uninitialized, run:" echo "git submodule update --init code-repos/zenstackhq/v3-doc-quick-start"versioned_docs/version-3.x/migrate-prisma.md (5)
261-261: Grammar: “which much more efficient” → “which is much more efficient”Small but user-facing; fix agreement.
-A key difference is that ZenStack's computed fields are evaluated on the database side, which much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation. +A key difference is that ZenStack's computed fields are evaluated on the database side, which is much more efficient and flexible than client-side computation. Read more in the [Computed Fields](./orm/computed-fields.md) documentation.
6-9: Rename to .mdx: MDX imports won’t compile in a .md fileThis page imports MDX components (PackageInstall, Tabs/TabItem) but uses a
.mdextension. Docusaurus only parses JSX/MDX in.mdxfiles. Rename tomigrate-prisma.mdxand update any inbound links.I can draft a follow-up commit to rename this file (and other affected pages) and update links if you want.
30-35: Peer-dependency guidance is contradictory; keep/install prisma as devDependency for migrationsYou say the CLI has a peer dep on
prismabut then advise removing it and later claim it needn’t be installed. Peer dependencies are not auto-installed consistently across package managers. Recommend keeping (or adding)prismaas a devDependency when using migration commands. Also fix “migration related” → “migration-related”.Apply:
-ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration related commands. The most straightforward way is to follow these steps: +ZenStack v3 doesn't depend on Prisma at runtime. Its CLI has a peer dependency on the `prisma` package for migration-related commands. The most straightforward way is to follow these steps: -- Remove `prisma` and `@prisma/client` from your project dependencies. +- Remove `@prisma/client` from your project dependencies. - Install ZenStack packages <PackageInstall dependencies={['@zenstackhq/runtime@next']} devDependencies={['@zenstackhq/cli@next']} /> +- Keep (or add) `prisma` as a devDependency if you plan to run migrations with `zen`. + ... -You don't need to explicitly install `prisma` package because the `@zenstackhq/cli` has a peer dependency on it. +Note: You still need `prisma` installed in your project (typically as a devDependency) to satisfy the CLI's peer dependency; package managers differ in whether they auto-install peers.Also applies to: 55-55
41-52: Examples import Kysely but it’s not installed; addkyselyto dependenciesBoth examples use
PostgresDialect/SqliteDialectfromkysely. Addkyselyso users can run the snippets without resolution errors.<TabItem value="postgres" label="PostgreSQL"> - <PackageInstall dependencies={['pg']} devDependencies={['@types/pg']} /> + <PackageInstall dependencies={['kysely', 'pg']} devDependencies={['@types/pg']} /> </TabItem> <TabItem value="sqlite" label="SQLite"> - <PackageInstall dependencies={['better-sqlite3']} devDependencies={['@types/better-sqlite3']} /> + <PackageInstall dependencies={['kysely', 'better-sqlite3']} devDependencies={['@types/better-sqlite3']} />
153-170: Align Prisma plugin output path with prisma generate command; capitalize “Prisma”The plugin writes
./schema.prismabut the generate script readszenstack/schema.prisma. Make them consistent (and fix wording).```zmodel plugin prisma { provider = '@core/prisma' - output = './schema.prisma' + output = './zenstack/schema.prisma' } ``` -2. Run a `prisma generate` command after `zen generate` with the prisma schema as input. +2. Run a `prisma generate` command after `zen generate` with the Prisma schema as input. ```json { "scripts": { "generate": "zen generate && prisma generate --schema=zenstack/schema.prisma" } }versioned_docs/version-3.x/reference/zmodel/attribute.md (8)
39-41: Fix field attribute application example: missing “@” prefix.Readers will copy/paste this and get invalid syntax.
Apply this diff:
-id String ATTR_NAME(ARGS)? +id String @ATTR_NAME(ARGS)?
63-63: Wrong subject: should say “Model attribute”, not “Field attribute”.This is in the Model attribute section.
Apply this diff:
-Field attribute name is prefixed by double `@@`. +Model attribute name is prefixed by double `@@`.
85-89: Fix model attribute application example: missing “@@” prefix.As written it suggests a plain identifier, not a model attribute.
Apply this diff:
-model Model { - ATTR_NAME(ARGS)? -} +model Model { + @@ATTR_NAME(ARGS)? +}
219-225: Complete the example: add a scalar type forownerId.The snippet is invalid ZModel without a type.
Apply this diff:
- owner Owner @relation(fields: [ownerId], references: [id]) - ownerId + owner Owner @relation(fields: [ownerId], references: [id]) + ownerId Int
411-414: Correct description for@unique(map:): it maps a unique constraint, not a primary key.Apply this diff:
-| map | The name of the underlying primary key constraint in the database | +| map | The name of the underlying unique constraint in the database |
436-438: Replace broken self-links for referential actions with a reference to the enum.The
#referential-actionanchor doesn’t exist on this page.Apply this diff:
-| onDelete | Referential action to take on delete. See details [here](#referential-action). | -| onUpdate | Referential action to take on update. See details [here](#referential-action). | +| onDelete | Referential action to take on delete. See the ReferentialAction enum for available options. | +| onUpdate | Referential action to take on update. See the ReferentialAction enum for available options. |
449-451: Parameter name in@maptable should bename, notmap.Aligns with
attribute @map(_ name: String).Apply this diff:
-| map | The name of the underlying column in the database | +| name | The name of the underlying column in the database |
533-537: Fix PostgreSQL type names:timestamptzandtimetz.Typo in both cells.
Apply this diff:
-| `@db.Timestamptz(x)` | `DateTime` | - | `timestampz(x)` | +| `@db.Timestamptz(x)` | `DateTime` | - | `timestamptz(x)` | @@ -| `@db.Timetz` | `DateTime` | - | `timez(x)` | +| `@db.Timetz` | `DateTime` | - | `timetz` |versioned_docs/version-3.x/modeling/relation.md (1)
27-27: Capitalize PK–FK and tighten phrasingUse the standard capitalization and improve clarity.
-The `Profile` model holds the foreign key `userId` and is the owner of the relation. The pk-fk association is established by the `@relation` attribute, where the `fields` parameter specifies the foreign key field(s) and the `references` parameter specifies the primary key field(s) of the other side. +The `Profile` model holds the foreign key `userId` and is the owner of the relation. The PK–FK association is established by the `@relation` attribute, where the `fields` parameter specifies the foreign key field(s) and the `references` parameter specifies the primary key field(s) on the other side.versioned_docs/version-3.x/orm/computed-fields.md (2)
21-22: Grammar: “a computed fields” → “a computed field” and streamlineNumber agreement and clearer phrasing.
-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.
6-8: MDX components in a .md file — rename to .mdxThis page imports MDX components and uses JSX, but the file extension is .md. It will not render in Docusaurus unless renamed.
Action:
- Rename versioned_docs/version-3.x/orm/computed-fields.md to versioned_docs/version-3.x/orm/computed-fields.mdx.
- Update any inbound links.
Also applies to: 11-15, 70-73
🧹 Nitpick comments (38)
versioned_docs/version-3.x/modeling/polymorphism.md (6)
30-32: Minor style: fix “aka.” punctuation and clarity around MTISmall editorial cleanup; keeps the same meaning.
-There are [two main ways](https://www.prisma.io/docs/orm/prisma-schema/data-model/table-inheritance) to model polymorphism in relational databases: single-table inheritance (STI) and multi-table inheritance (MTI, aka. "Delegate Types"). ZModel's implementation follows the MTI pattern. +There are [two main ways](https://www.prisma.io/docs/orm/prisma-schema/data-model/table-inheritance) to model polymorphism in relational databases: single-table inheritance (STI) and multi-table inheritance (MTI, aka "Delegate Types"). ZModel follows the MTI pattern.
40-57: Optional: demonstrate enum-based discriminator for stronger modeling guaranteesDefining the discriminator as an enum prevents typos and communicates allowed variants at the schema level.
model Content { id Int @id name String createdAt DateTime @default(now()) owner User @relation(fields: [ownerId], references: [id]) ownerId Int // highlight-next-line - type String + type ContentType @@ // highlight-next-line @@delegate(type) } + +enum ContentType { + Post + Image + Video +}
102-106: Grammar nits: clarify discriminator sentence and flowLight edits for readability; aligns with LanguageTool hints.
-1. It must have a "discriminator" field that stores the concrete model type that it should "delegate" to. In the example above, the `type` field serves this purpose. It can be named anything you like, but must be of `String` or enum type. -2. It must have a `@@delegate` attribute. The attribute serves two purposes: it indicates that the model is a base model, and it designates the discriminator field with its parameter. +1. It must have a discriminator field that stores the concrete model type to delegate to. In the example above, the `type` field serves this purpose. It can be named anything you like, but it must be a `String` or an enum. +2. It must have a `@@delegate` attribute. The attribute serves two purposes: it indicates that the model is a base model and designates the discriminator field via its parameter.
111-114: Grammar: “queries”, and minor tighteningSmall editorial tweaks for clarity.
-The migration engine takes care of mapping both the base model and the concrete ones to tables, and creates one-to-one relations between the base and each of its derivations. - -To simplify query and conserve space, the base and the concrete are assumed to share the same id values (this is guaranteed by the ORM when creating the records), and consequently, the concrete model's id field is also reused as the foreign key to the base model. So, for a `Post` record with id `1`, the base `Content` record also has id `1`. +The migration engine maps both the base model and the concrete ones to tables and creates one-to-one relations between the base and each of its derivations. + +To simplify queries and conserve space, the base and the concrete are assumed to share the same id values (guaranteed by the ORM when creating records). Consequently, the concrete model's id field is reused as the foreign key to the base model. For example, for a `Post` record with id `1`, the base `Content` record also has id `1`.
117-121: Wording: “delegation” and specificity on discriminatorMicro-edits for precision.
-The ORM hides the delegate complexities and provides a simple polymorphic view to the developers: +The ORM hides the complexities of delegation and provides a simple polymorphic view: @@ -1. Creating a concrete model record automatically creates the base model record with the same id and proper discriminator field. -2. Querying with the base model will return entities with concrete model fields. +1. Creating a concrete model record automatically creates the corresponding base model record with the same id and sets the discriminator field. +2. Querying via the base model returns entities that include their concrete model fields.
122-123: Grammar: “in detail”Single-word tweak.
-We'll revisit the topic in details in the [ORM](../orm/polymorphism.md) part. +We'll revisit the topic in detail in the [ORM](../orm/polymorphism.md) part.versioned_docs/version-3.x/orm/api/filter.md (3)
22-22: Grammar: “AND semantics”Minor English tweak.
-A filter object can contain multiple field filters, and they are combined with `AND` semantic. +A filter object can contain multiple field filters, and they are combined with `AND` semantics.
64-69: Heading capitalization and phrasing for JSONPrefer “JSON” (all caps) and a smoother sentence. Consider linking a tracking issue if available.
-## 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 JSON fields is a work in progress and will be available soon. :::If you have a GitHub issue tracking this, I can add the link.
72-72: Inline code formatting for relation operatorsUse backticks for consistency with the rest of the doc.
-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.versioned_docs/version-3.x/orm/api/find.md (3)
17-20: Grammar: “unique criterion” (singular)Minor English fix.
-- `findUnique` - - Find a single record with a unique criteria. +- `findUnique` + + Find a single record with a unique criterion.
66-68: Make thedistinctexample deterministic withorderBy.Without an explicit ordering, which row is returned per group is arbitrary. Recommend demonstrating a stable sort.
-// returns one Post for each unique authorId -await db.post.findMany({ distinct: ['authorId'] }); +// returns one Post (latest) for each unique authorId +await db.post.findMany({ + distinct: ['authorId'], + orderBy: [{ createdAt: { direction: 'desc' } }] +});If your API supports provider-specific ordering requirements for
DISTINCT ON, consider noting them.
11-32: Tighten the method descriptions to reduce repetition.Optional style pass to make the list more concise.
-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: @@ -- `findMany` - - Find multiple records that match the query criteria. +- `findMany`: return all records matching the criteria. @@ -- `findUnique` - - Find a single record with a unique criteria. +- `findUnique`: return a single record by a unique criterion. @@ -- `findFirst` - - Find the first record that matches the query criteria. +- `findFirst`: return the first record matching the criteria. @@ -- `findUniqueOrThrow` - - Similar to `findUnique`, but throws an error if no record is found. +- `findUniqueOrThrow`: like `findUnique`, but throws if no record is found. @@ -- `findFirstOrThrow` - - Similar to `findFirst`, but throws an error if no record is found. +- `findFirstOrThrow`: like `findFirst`, but throws if no record is found.versioned_docs/version-3.x/orm/api/update.md (5)
10-16: Clarify return types for each method and verify API parity (especially updateManyAndReturn).To reduce ambiguity for readers, explicitly document what each method returns and confirm that updateManyAndReturn is available and stable in v3.
Suggested addition right after the list:
+### Return values + +- `update` → the updated record. +- `updateMany` → `{ count: number }`. +- `updateManyAndReturn` → an array of the updated records. +- `upsert` → the created or updated record.Also, if updateManyAndReturn has notable limitations (e.g., projections, includes, or relation writes), call them out here.
21-25: Fix grammar (“In additional” → “In addition”).Small copy edit for polish.
-In additional to the standard way of updating fields, list fields support the following operators: +In addition to the standard way of updating fields, list fields support the following operators:
26-40: Consider demonstrating pushing multiple values and clarifying deduplication behavior.Readers often ask whether push deduplicates and how to append multiple items.
- If the ORM does not deduplicate, add a short note: “push appends as-is; no deduplication.”
- Optionally add a second example showing an array push:
await db.post.update({ where: { id: '1' }, data: { topics: { push: ['db', 'orm'] }, }, });
42-47: Tighten language and tone; avoid “very powerful” and be precise.Replace the intensifier and make the statement more direct. Also, consider linking to the relations/nested writes reference for constraints and referential actions.
-The `update` and `upsert` methods are very powerful in that they allow you to freely manipulate relations. You can create, connect, disconnect, update, and delete relations in a single operation. You can also reach deeply into indirect relations. +The `update` and `upsert` methods let you manipulate relations—create, connect, disconnect, update, and delete—in a single operation. You can also target nested (indirect) relations. + +> Note: Nested writes are subject to model constraints and referential actions. See the Relations guide for details.This also addresses the style hint about overusing “very.”
48-48: Second embed: confirm startScript contract and provide fallback.Same concern as above for startScript="generate,update:relation". If the component doesn’t support multiple scripts, define a single script in the sample repo and reference that. Consider adding a short inline code sample as a fallback in case the embed fails to load.
versioned_docs/version-3.x/orm/quick-start.md (8)
13-15: Consider pinning example commands to a specific pre-release for reproducibility.Keeping the info box about “@next” is fine, but for copy/paste determinism you might want to show pinned examples (e.g.,
@3.0.0-beta.X) in at least one place.- All v3 packages are currently published under the "@next" tag. + All v3 packages are currently published under the "@next" tag. For reproducible setups, you can pin versions (e.g., `@3.0.0-beta.X`) instead of `@next`.
21-26: Offer package-manager variants for project scaffolding.Many users prefer pnpm/yarn. Consider adding alternatives for
npm create, or a short note showingpnpm dlx/yarn dlxequivalents to reduce friction.-```bash -npm create zenstack@next my-project -``` +```bash +# npm +npm create zenstack@next my-project + +# pnpm +pnpm dlx create-zenstack@next my-project + +# yarn +yarn dlx create-zenstack@next my-project +```
33-39: Init command usage looks good; clarify where the schema file lives.The path “zenstack/schema.zmodel” is correct; add a note that the CLI creates the
zenstack/folder if missing, and that this is the default lookup path used byzen generate.-Then create a `zenstack/schema.zmodel` file in the root of your project. You can use the following sample schema to get started: +Then create a `zenstack/schema.zmodel` file in the project root (the `zenstack/` folder will be created if it doesn't exist). This is the default path used by the CLI. You can use the following sample schema to get started:
41-44: Add a runnable command for the optional db push.You mention
zen db pushin prose; make it copy/paste friendly with a component block like the one forzen generate.<PackageExec command="zen generate" /> + +<PackageExec command="zen db push" />
49-52: Double-check peer/runtime deps; add Prisma if required for v3 ORM.If v3 ORM still depends on Prisma, add
prisma(dev) and@prisma/client(runtime). If not, ignore this. Please confirm and update the install block accordingly.- <PackageInstall devDependencies={['@zenstackhq/cli@next']} dependencies={['@zenstackhq/runtime@next']} /> + <PackageInstall + devDependencies={['@zenstackhq/cli@next', 'prisma@latest']} + dependencies={['@zenstackhq/runtime@next', '@prisma/client@latest']} + />
59-62: Nudge: remind users to re-run generate after schema updates.A small tip reduces “why isn’t my code updated?” questions.
- <PackageExec command="zen generate" /> + <PackageExec command="zen generate" /> + <p><em>Tip:</em> Re-run <code>zen generate</code> whenever you change the schema.</p>
63-69: Link to CLI reference and show a .gitignore snippet for generated files.Make the options discoverable and give users a safe default for ignoring generated outputs when preferred.
By default, ZenStack CLI loads the schema from `zenstack/schema.zmodel`. You can change this by passing the `--schema` option. TypeScript files are by default generated to the same directory as the schema file. You can change this by passing the `--output` option. You can choose to either commit the generated TypeScript files to your source control, or add them to `.gitignore` and generate them on the fly in your CI/CD pipeline. ::: +See the <a href="../cli" target="_self">CLI reference</a> for all options. + +If you prefer not to commit generated files, add a rule like: + +```gitignore +# ZenStack generated code (adjust to your actual output dir) +zenstack/**/*.ts +```
1-69: Overall: clear and actionable quick start.Structure reads well, componentized examples are consistent, and the starter schema inclusion is helpful. With the minor tweaks above (fallback link, optional db push command block, and dependency confirmation), this page is ready.
I can open a follow-up PR with the proposed content edits if you prefer.
versioned_docs/version-3.x/modeling/plugin.md (5)
14-14: Pluralize “Plugin” for grammatical correctnessUse “Plugins are …” or “The plugin system is …” to avoid the singular/plural mismatch.
-Plugin is a powerful mechanism that allows you to extend ZenStack at the schema, CLI, and runtime levels. +Plugins are a powerful mechanism that allow you to extend ZenStack at the schema, CLI, and runtime levels.
27-35: Tighten wording; avoid arrow notationMinor clarity/style improvements in the info note.
-In fact, the `zen generate` command is entirely implemented with plugins. The ZModel -> TypeScript generation is supported by the built-in `@core/typescript` plugin which runs automatically. You can explicitly declare it if you wish: +In fact, the `zen generate` command is entirely implemented with plugins. The ZModel-to-TypeScript generation is handled by the built-in `@core/typescript` plugin, which runs automatically. You can explicitly declare it if you wish:
42-44: Make the built-in plugin example consistent with earlier contextYou previously used @core/typescript; referencing @core/prisma “here” is inconsistent. Either mention both or stick with the same example.
-2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here), a local JavaScript module, or an NPM package name. +2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/typescript` or `@core/prisma`), a local JavaScript module, or an NPM package name.
46-50: Preposition and tense fixesMinor grammar for natural phrasing.
-A plugin can have the following effects to ZModel: +A plugin can have the following effects on ZModel: @@ -- It can contribute code generation logic that's executed when you run the `zenstack generate` command. +- It can contribute code generation logic that runs when you execute the `zenstack generate` command.
51-51: Clarify cross-reference wording and link textMore direct phrasing and explicit link text.
-Plugins can also contribute to the ORM runtime behavior, and we'll leave it to the [ORM](../orm/plugins/) part to explain it in detail. +Plugins can also contribute to ORM runtime behavior; we cover this in detail in the [ORM plugins](../orm/plugins/) section.versioned_docs/version-3.x/reference/zmodel/attribute.md (1)
113-113: Nit: remove stray space in code font_.Minor readability fix.
Apply this diff:
-Arguments are mapped to parameters by position or by name. Parameter names prefixed with `_ ` are positional and arguments for such parameters can be provided without their names. For example, for the `@default` attribute declared as: +Arguments are mapped to parameters by position or by name. Parameter names prefixed with `_` are positional and arguments for such parameters can be provided without their names. For example, for the `@default` attribute declared as:versioned_docs/version-3.x/orm/client.md (3)
14-15: Tighten grammar and clarify dialect supportMinor copyedits and a more accurate statement about dialects.
- Unlike Prisma, ZenStack doesn't bundle any database driver. You're responsible for installing a compatible one. Also it doesn't read database connection string from the schema. Instead, you pass in the connection information when creating the client. + Unlike Prisma, ZenStack doesn't bundle any database driver. You're responsible for installing a compatible one. Also, it doesn't read the database connection string from the schema. Instead, you pass the connection information when creating the client. - 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](https://kysely.dev/docs/dialects) - an object that encapsulates database details. + The `zen generate` command compiles the ZModel schema to TypeScript, which you use to initialize a type-safe database client. ZenStack uses Kysely for low-level database operations, so the client is initialized with a [Kysely dialect](https://kysely.dev/docs/dialects)—an object that encapsulates database details. - The samples below only show creating a client using SQLite (via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) and PostgreSQL (via [node-postgres](https://github.com/brianc/node-postgres)), however you can also use any other Kysely dialects for these two types of databases. + The samples below demonstrate SQLite (via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) and PostgreSQL (via [node-postgres](https://github.com/brianc/node-postgres)). You can use any Kysely dialect that matches your database.Also applies to: 17-19
63-70: Path alias in type import may not resolve in readers’ projectsThe alias import
@/zenstack/schemaassumes a paths/baseUrl setup in tsconfig. For consistency with earlier examples in this page (relative pathing), consider switching to a relative import or add a note about configuring path aliases.-import type { SchemaType } from '@/zenstack/schema'; +import type { SchemaType } from './zenstack/schema';If you intend to use
@/, please add a short note showing the required tsconfig.json paths configuration.
53-57: Optional: mention DATABASE_URL requirementThe PostgreSQL example relies on
process.env.DATABASE_URL. Consider adding a one-line note indicating the expected format and that the environment variable must be set before instantiating the client.versioned_docs/version-3.x/modeling/relation.md (3)
87-87: Tone: replace informal “pretty much”Small style improvement for a docs tone.
-It's modeled pretty much 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. +It's modeled similarly to one-to-one relations, except that the "non-owner" side (here `User.posts`) is a list of the other side's model type.
154-156: Section title: prefer “Self-relations”Pluralized/standardized heading.
-## Self relation +## Self-relations
250-271: Fix nested list indentation (MD007) and clarify bulletsMarkdown sublist indentation is off and some bullets are awkwardly worded. This affects rendering and linting.
-- `Cascade` - - - **onDelete**: deleting a referenced record will trigger the deletion of referencing record. - - **onUpdate**: updates the relation scalar fields if the referenced scalar fields of the dependent record are updated. +- `Cascade` + - onDelete: Deleting the referenced record triggers deletion of the referencing record. + - onUpdate: Updates the relation’s scalar fields when the referenced record’s scalar fields change. @@ -- `Restrict` - - **onDelete**: prevents the deletion if any referencing records exist. - - **onUpdate**: prevents the identifier of a referenced record from being changed. +- `Restrict` + - onDelete: Prevents deletion if any referencing records exist. + - onUpdate: Prevents changing the identifier of a referenced record. @@ -- `NoAction` - - Similar to 'Restrict', the difference between the two is dependent on the database being used. +- `NoAction` + - Similar to `Restrict`; behavior differences depend on the database. @@ -- `SetNull` - - - **onDelete**: the scalar field of the referencing object will be set to NULL. - - **onUpdate**: when updating the identifier of a referenced object, the scalar fields of the referencing objects will be set to NULL. +- `SetNull` + - onDelete: Sets the referencing field(s) to NULL. + - onUpdate: When the referenced identifier changes, sets the referencing field(s) to NULL. @@ -- `SetDefault` - - **onDelete**: the scalar field of the referencing object will be set to the fields default value. - - **onUpdate**: the scalar field of the referencing object will be set to the fields default value. +- `SetDefault` + - onDelete: Sets the referencing field(s) to the field’s default value. + - onUpdate: Sets the referencing field(s) to the field’s default value.versioned_docs/version-3.x/orm/index.md (1)
10-10: Light copyedits for clarity, consistency, and tonePolish phrasing; keep technical meaning unchanged.
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an excellent developer experience and incredible flexibility 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 and strong flexibility by combining proven ideas into a cohesive package. @@ -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. +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 often use it as a drop‑in replacement. @@ -... via query injection, so it doesn't rely on any database specific row-level security features. +... via query injection, so it doesn't rely on any database‑specific row‑level security features. @@ -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. @@ -### Straightforward, light-weighted, flexible +### Straightforward, lightweight, flexible @@ -Compared to Prisma and previous versions of ZenStack, v3 is more straightforward, light-weighted, and flexible. +Compared to Prisma and previous versions of ZenStack, v3 is more straightforward, lightweight, and flexible. - No runtime dependency to Prisma, thus no overhead of Rust/WASM query engines. -- No magic generating into `node_modules`. You fully control how the generated code is compiled and bundled. + - No runtime dependency on Prisma, thus no overhead from Rust/WASM query engines. + - No magic code generated into `node_modules`. You fully control how the generated code is compiled and bundled. @@ -Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside with static code snippets. StackBlitz's [WebContainers](https://webcontainers.io/) is an awesome technology that allows you to run a Node.js environment inside the browser. +Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside static code snippets. StackBlitz's [WebContainers](https://webcontainers.io/) let you run a Node.js environment inside the browser. @@ -```ts title="main.ts" -const content = await db.content.findFirstOrThrow(); -if (content.type === 'Post') { - // content's type is narrowed down to `Post` - console.log(content.content); -} else { - // other asset type -} -``` +```ts title="main.ts" +const content = await db.content.findFirstOrThrow(); +if (content.type === 'Post') { + // `content` is narrowed to `Post` + console.log(content.content); +} else { + // other content type +} +```Also applies to: 16-16, 46-46, 69-69, 101-109, 114-114, 91-99
📜 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 (13)
src/components/StackBlitzGithub.tsx(1 hunks)versioned_docs/version-3.x/migrate-prisma.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/api/filter.md(1 hunks)versioned_docs/version-3.x/orm/api/find.md(1 hunks)versioned_docs/version-3.x/orm/api/update.md(1 hunks)versioned_docs/version-3.x/orm/client.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/quick-start.md(1 hunks)versioned_docs/version-3.x/reference/zmodel/attribute.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- src/components/StackBlitzGithub.tsx
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/api/filter.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...om '../../_components/ZenStackVsPrisma'; import StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
[grammar] ~66-~66: 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] ~67-~67: There might be a mistake here.
Context: ... in progress and will be available soon. ::: ## Relation filters Filters can be...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/index.md
[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] ~105-~105: There might be a mistake here.
Context: ... no overhead of Rust/WASM query engines. - No magic generating into node_modules....
(QB_NEW_EN)
[style] ~114-~114: 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)
[style] ~114-~114: Consider using a less common alternative to make your writing sound more unique and professional.
Context: ...ich is not suitable for production use. Feel free to make changes and try things out in the ...
(FEEL_FREE_TO_STYLE_ME)
versioned_docs/version-3.x/migrate-prisma.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...all from './_components/PackageInstall'; 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 Tabs from '@theme/Tabs'; # Migra...
(QB_NEW_EN)
[grammar] ~267-~267: There might be a mistake here.
Context: ...Stack v3: | Feature | Planned | Notes | |---------|-------------| --- | | [Clien...
(QB_NEW_EN)
[grammar] ~268-~268: There might be a mistake here.
Context: ... Notes | |---------|-------------| --- | | [Client Extensions](https://www.prisma...
(QB_NEW_EN)
[grammar] ~269-~269: There might be a mistake here.
Context: ...Replaced with ZenStack runtime plugins | | [JSON Filters](https://www.prisma.io/d...
(QB_NEW_EN)
[grammar] ~270-~270: There might be a mistake here.
Context: ...client-reference#json-filters) | Yes | | | [Full-Text Search](https://www.prisma....
(QB_NEW_EN)
[grammar] ~271-~271: There might be a mistake here.
Context: ...ient/queries/full-text-search) | Yes | | | [Comparing Columns](https://www.prisma...
(QB_NEW_EN)
[grammar] ~272-~272: There might be a mistake here.
Context: ...are-columns-in-the-same-table) | Yes | | | [Postgres Multi-Schema](https://www.pr...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/plugin.md
[grammar] ~42-~42: There might be a mistake here.
Context: ... involves three parts: 1. A unique name 2. A provider field that specifies where t...
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/polymorphism.md
[grammar] ~17-~17: There might be a mistake here.
Context: ...ng IS-A more abstract type of thing. - Something HAS-A/HAS-many a more abst...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...e, but must be of String or enum type. 2. It must have a @@delegate attribute. T...
(QB_NEW_EN)
[grammar] ~113-~113: There might be a mistake here.
Context: ...e base and each of its derivations. To simplify query and conserve space, the base and ...
(QB_NEW_EN)
[grammar] ~119-~119: There might be a mistake here.
Context: ... same id and proper discriminator field. 2. Querying with the base model will return...
(QB_NEW_EN)
[grammar] ~122-~122: There might be a mistake here.
Context: ... the ORM part.
(QB_NEW_EN)
versioned_docs/version-3.x/modeling/relation.md
[style] ~87-~87: 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/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/update.md
[style] ~44-~44: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ... The update and upsert methods are very powerful in that they allow you to freely manipu...
(EN_WEAK_ADJECTIVE)
versioned_docs/version-3.x/orm/client.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...- import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; import P...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...abItem'; import Tabs from '@theme/Tabs'; import PackageInstall from '../_componen...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...ll from '../_components/PackageInstall'; import ZenStackVsPrisma from '../_compon...
(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 StackBlitzGithub from '@site/src/...
(QB_NEW_EN)
versioned_docs/version-3.x/orm/quick-start.md
[grammar] ~6-~6: There might be a mistake here.
Context: ...'@site/src/components/StackBlitzGithub'; import ZModelStarter from '../_component...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...rom '../_components/_zmodel-starter.md'; import PackageInstall from '../_componen...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...rom '../_components/PackageInstall.tsx'; import PackageExec from '../_components/...
(QB_NEW_EN)
versioned_docs/version-3.x/reference/zmodel/attribute.md
[grammar] ~135-~135: There might be a mistake here.
Context: ... Int Integer literal can be passed as argument. E.g., declaration: ...
(QB_NEW_EN)
[grammar] ~168-~168: There might be a mistake here.
Context: ...ean literal or expression can be passed as argument. E.g., declaration: ...
(QB_NEW_EN)
[grammar] ~277-~277: There might be a mistake here.
Context: ... | | ------ | -----------------------------...
(QB_NEW_EN)
[grammar] ~278-~278: There might be a mistake here.
Context: ...-------------------------------------- | | fields | A list of fields defined in t...
(QB_NEW_EN)
[grammar] ~279-~279: There might be a mistake here.
Context: ... model | | name | The name that the Client API ...
(QB_NEW_EN)
[grammar] ~280-~280: There might be a mistake here.
Context: ...e for the argument covering all fields | | map | The name of the underlying pr...
(QB_NEW_EN)
[grammar] ~293-~293: There might be a mistake here.
Context: ... | | ------ | -----------------------------...
(QB_NEW_EN)
[grammar] ~294-~294: There might be a mistake here.
Context: ...-------------------------------------- | | fields | A list of fields defined in t...
(QB_NEW_EN)
[grammar] ~295-~295: There might be a mistake here.
Context: ...ed in the current model | | name | The name of the unique combin...
(QB_NEW_EN)
[grammar] ~296-~296: There might be a mistake here.
Context: ... combination of fields | | map | The name of the underlying un...
(QB_NEW_EN)
[grammar] ~309-~309: There might be a mistake here.
Context: ...n | | ------ | -----------------------------...
(QB_NEW_EN)
[grammar] ~310-~310: There might be a mistake here.
Context: ...-------------------------------------- | | fields | A list of fields defined in t...
(QB_NEW_EN)
[grammar] ~311-~311: There might be a mistake here.
Context: ...fields defined in the current model | | map | The name of the underlying in...
(QB_NEW_EN)
[grammar] ~324-~324: There might be a mistake here.
Context: ... | | ---- | -------------------------------...
(QB_NEW_EN)
[grammar] ~325-~325: There might be a mistake here.
Context: ...-------------------------------------- | | name | The name of the underlying tabl...
(QB_NEW_EN)
[grammar] ~354-~354: There might be a mistake here.
Context: ... | | ------------- | ----------------------...
(QB_NEW_EN)
[grammar] ~355-~355: There might be a mistake here.
Context: ...-------------------------------------- | | discriminator | A String or enum f...
(QB_NEW_EN)
[grammar] ~383-~383: There might be a mistake here.
Context: ... | | ---- | -------------------------------...
(QB_NEW_EN)
[grammar] ~384-~384: There might be a mistake here.
Context: ...-------------------------------------- | | map | The name of the underlying prim...
(QB_NEW_EN)
[grammar] ~397-~397: There might be a mistake here.
Context: ...| Name | Description | | ----- | ---------------------------- |...
(QB_NEW_EN)
[grammar] ~398-~398: There might be a mistake here.
Context: ...| ----- | ---------------------------- | | value | The default value expression |...
(QB_NEW_EN)
[grammar] ~411-~411: There might be a mistake here.
Context: ... | | ---- | -------------------------------...
(QB_NEW_EN)
[grammar] ~412-~412: There might be a mistake here.
Context: ...-------------------------------------- | | map | The name of the underlying prim...
(QB_NEW_EN)
[grammar] ~449-~449: There might be a mistake here.
Context: ... | | ---- | -------------------------------...
(QB_NEW_EN)
[grammar] ~450-~450: There might be a mistake here.
Context: ...-------------------------------------- | | map | The name of the underlying colu...
(QB_NEW_EN)
[grammar] ~496-~496: There might be a mistake here.
Context: ...e | SQLite Type | PostgreSQL Type | |-------------|-------------|-----------...
(QB_NEW_EN)
[grammar] ~497-~497: There might be a mistake here.
Context: ...--|-------------|----------------------| | String | TEXT | text ...
(QB_NEW_EN)
[grammar] ~498-~498: There might be a mistake here.
Context: ... | TEXT | text | | Boolean | INTEGER | boolean ...
(QB_NEW_EN)
[grammar] ~499-~499: There might be a mistake here.
Context: ... | INTEGER | boolean | | Int | INTEGER | integer ...
(QB_NEW_EN)
[grammar] ~500-~500: There might be a mistake here.
Context: ... | INTEGER | integer | | BigInt | INTEGER | bigint ...
(QB_NEW_EN)
[grammar] ~501-~501: There might be a mistake here.
Context: ... | INTEGER | bigint | | Float | REAL | `double pr...
(QB_NEW_EN)
[grammar] ~502-~502: There might be a mistake here.
Context: ... | REAL | double precision | | Decimal | DECIMAL | `decimal(6...
(QB_NEW_EN)
[grammar] ~503-~503: There might be a mistake here.
Context: ... | DECIMAL | decimal(65,30) | | DateTime | NUMERIC | `timestamp...
(QB_NEW_EN)
[grammar] ~504-~504: There might be a mistake here.
Context: ... | NUMERIC | timestamp(3) | | Json | JSONB | jsonb ...
(QB_NEW_EN)
[grammar] ~505-~505: There might be a mistake here.
Context: ... | JSONB | jsonb | | Bytes | BLOB | bytea ...
(QB_NEW_EN)
[grammar] ~525-~525: There might be a mistake here.
Context: ... | - | smallint int2 | | @db.Oid | Int ...
(QB_NEW_EN)
[grammar] ~536-~536: There might be a mistake here.
Context: ... | - | timez(x) | | @db.Json | Json ...
(QB_NEW_EN)
🔇 Additional comments (10)
versioned_docs/version-3.x/modeling/polymorphism.md (1)
28-28: Good catch: “an in-database” is correct nowThis fixes the article usage noted earlier. No further change needed.
versioned_docs/version-3.x/orm/api/filter.md (1)
20-20: Verify and fix type name: likelyDateTime(notDate).If ZenStack v3 follows Prisma/ZModel type names, the scalar should be
DateTime. Please confirm and update to avoid misleading users.Apply if correct:
- - `lt` `lte` `gt` `gte`: `String`, `Int`, `BigInt`, `Float`, `Decimal`, and `Date` fields + - `lt` `lte` `gt` `gte`: `String`, `Int`, `BigInt`, `Float`, `Decimal`, and `DateTime` fieldsversioned_docs/version-3.x/orm/api/find.md (2)
43-45: Document how to control NULLS placement (syntax + provider support).You mention “null field placement,” but the API shape isn’t shown and provider support may vary. Please add a concrete example and note supported databases.
Suggested addition after the sentence:
Use the `orderBy` field to control the sort field, direction, and null field placement. Sorting is not supported for `findUnique` and `findUniqueOrThrow`. + +Example: +```ts +await db.post.findMany({ + orderBy: [{ createdAt: { direction: 'asc', nulls: 'last' } }] +}); +``` + +Supported providers: please confirm (e.g., PostgreSQL ✅; MySQL/SQLite behavior may differ).If the API shape differs, replace with the correct structure.
63-64: Provider support fordistinct: likely PostgreSQL-only withDISTINCT ON.The text says “not available for SQLite,” but
DISTINCT ONis a PostgreSQL feature and typically not supported by MySQL/SQLite. Please verify actual support in ZenStack v3 and document precisely (e.g., “PostgreSQL only”).-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 per unique combination of the specified fields. Implementation relies on SQL `DISTINCT ON`, so it is available for PostgreSQL only. Other providers are currently not supported.versioned_docs/version-3.x/orm/api/update.md (3)
1-4: Frontmatter looks good; confirm sidebar ordering uniqueness.sidebar_position: 4 and description are fine. Please verify there are no duplicate sidebar_position values within the same sidebar to avoid ordering collisions.
6-6: Confirm MDX import path resolves under versioned docs.Using JSX in a .md file is fine with Docusaurus MDX. Please double‑check that the alias @site/src/components/StackBlitzGithub resolves correctly from versioned_docs to avoid broken imports after versioning.
19-19: Ensure StackBlitzGithub supports multiple scripts in startScript.You’re passing startScript="generate,update:scalar". Please confirm the component intentionally supports comma‑separated scripts and runs them sequentially. If not, consider a single npm script that chains the steps (e.g., "docs:update:scalar") and reference that instead.
versioned_docs/version-3.x/orm/quick-start.md (1)
6-9: Imports look correct and version-pinned components are a good call.MDX imports for StackBlitzGithub and versioned local components under
_componentsare consistent with Docusaurus conventions and help freeze content per doc version.versioned_docs/version-3.x/modeling/plugin.md (2)
6-13: Good use of MDX component and relative import pathImporting ZModelVsPSL from ../_components is correct for a versioned doc; the component usage reads well.
6-6: Component import path confirmedThe file
versioned_docs/version-3.x/_components/ZModelVsPSL.tsxexists, so the MDX import is valid and no further changes are needed.
| Please refer to the [Plugin References](../category/plugins) for the full list of built-in plugins. | ||
| ::: |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Verify the “Plugin References” link target (category routes can vary for versioned docs)
Relative links to category pages may differ under Docusaurus versioned routes. Please verify that ../category/plugins resolves for the 3.x version; otherwise link to the concrete doc (e.g., ../reference/plugins/) or the versioned category slug.
You can run this to check existence of the target docs and category config:
If the category route differs, consider:
-Please refer to the [Plugin References](../category/plugins) for the full list of built-in plugins.
+Please refer to the [Plugin References](../reference/plugins/) for the full list of built-in plugins.🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Check plugin reference docs exist:"
fd -t f -a 'plugins' versioned_docs/version-3.x/reference | sed -n '1,50p'
echo "Check for category config and slug/label:"
fd '_category_.json' versioned_docs/version-3.x -a | xargs -I{} sh -c 'echo "--- {}; ---"; cat "{}"; echo;'
echo "Grepping for an explicit Plugins category under reference:"
rg -nC2 -i '"label"\s*:\s*"Plugins"|"/category/plugins' versioned_docs/version-3.xLength of output: 586
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Top-level directories in versioned_docs/version-3.x:"
find versioned_docs/version-3.x -maxdepth 1 -mindepth 1 -type d
if [ -d versioned_docs/version-3.x/reference ]; then
echo -e "\nFiles matching '*plugin*' under versioned_docs/version-3.x/reference:"
find versioned_docs/version-3.x/reference -type f -iname "*plugin*.md" || echo " (none found)"
echo -e "\nDirectories matching '*plugin*' under versioned_docs/version-3.x/reference:"
find versioned_docs/version-3.x/reference -maxdepth 1 -type d -iname "*plugin*" || echo " (none found)"
else
echo -e "\nNo reference directory found at versioned_docs/version-3.x/reference"
fi
echo -e "\nAll files matching '*plugin*' under versioned_docs/version-3.x:"
find versioned_docs/version-3.x -type f -iname "*plugin*"Length of output: 1464
Fix broken “Plugin References” link in versioned 3.x docs
The link ../category/plugins does not resolve under versioned_docs/version-3.x; the actual directory is versioned_docs/version-3.x/reference/plugins. Update the link to point directly at that folder.
• File: versioned_docs/version-3.x/modeling/plugin.md
• Lines: 37–38
-Please refer to the [Plugin References](../category/plugins) for the full list of built-in plugins.
+Please refer to the [Plugin References](../reference/plugins/) for the full list of built-in plugins.📝 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.
| Please refer to the [Plugin References](../category/plugins) for the full list of built-in plugins. | |
| ::: | |
| Please refer to the [Plugin References](../reference/plugins/) for the full list of built-in plugins. | |
| ::: |
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/modeling/plugin.md around lines 37–38, the
relative link currently points to ../category/plugins which doesn't exist for
versioned_docs/version-3.x; update the link target to ../reference/plugins so it
resolves to versioned_docs/version-3.x/reference/plugins (leave the link text
unchanged).
| ```mermaid | ||
| erDiagram | ||
| User { | ||
| id Int PK | ||
| } | ||
| Content { | ||
| id Int PK | ||
| name String | ||
| createdAt Date | ||
| ownerId Int FK | ||
| type String | ||
| } | ||
| User ||--o{ Content: owns | ||
| Post { | ||
| id Int PK,FK | ||
| content String | ||
| } | ||
| Post ||--|| Content: delegates | ||
| Image { | ||
| id Int PK,FK | ||
| data Bytes | ||
| } | ||
| Image ||--|| Content: delegates | ||
| Video { | ||
| id Int PK,FK | ||
| url String | ||
| } | ||
| Video ||--|| Content: delegates | ||
| ``` |
There was a problem hiding this comment.
Fix Mermaid ER diagram: tabs (MD010) and type mismatch with model
The diagram uses hard tabs and shows createdAt Date while the model defines DateTime. This causes linter noise and confuses readers.
```mermaid
erDiagram
- User {
- id Int PK
- }
- Content {
- id Int PK
- name String
- createdAt Date
- ownerId Int FK
- type String
- }
- User ||--o{ Content: owns
- Post {
- id Int PK,FK
- content String
- }
- Post ||--|| Content: delegates
- Image {
- id Int PK,FK
- data Bytes
- }
- Image ||--|| Content: delegates
- Video {
- id Int PK,FK
- url String
- }
- Video ||--|| Content: delegates
+ User {
+ id Int PK
+ }
+ Content {
+ id Int PK
+ name String
+ createdAt DateTime
+ ownerId Int FK
+ type String
+ }
+ User ||--o{ Content: owns
+ Post {
+ id Int PK,FK
+ content String
+ }
+ Post ||--|| Content: delegates
+ Image {
+ id Int PK,FK
+ data Bytes
+ }
+ Image ||--|| Content: delegates
+ Video {
+ id Int PK,FK
+ url String
+ }
+ Video ||--|| Content: delegates
Note: This appears to reintroduce issues flagged earlier; please ensure the committed version matches the model and linter rules.
<details>
<summary>🤖 Prompt for AI Agents</summary>
In versioned_docs/version-3.x/modeling/polymorphism.md around lines 72 to 100,
the Mermaid ER diagram uses hard tabs and the Content.createdAt type is Date
(mismatches the model); replace all hard tabs with spaces (use consistent
2-space indentation), change createdAt from Date to DateTime to match the model,
and ensure the rest of the diagram spacing/indentation is consistent with the
repo linter rules so the committed code block passes MD010 and type checks.
</details>
<!-- fingerprinting:phantom:triton:chinchilla -->
<!-- This is an auto-generated comment by CodeRabbit -->
| import TabItem from '@theme/TabItem'; | ||
| import Tabs from '@theme/Tabs'; | ||
| import PackageInstall from '../_components/PackageInstall'; | ||
| import ZenStackVsPrisma from '../_components/ZenStackVsPrisma'; | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
MDX components in a .md file will not compile — rename to .mdx
This page imports and uses MDX/JSX components (Tabs, TabItem, PackageInstall, ZenStackVsPrisma) but has a .md extension. Docusaurus requires .mdx for component usage; otherwise the page will break at build time.
Apply the following action:
- Rename versioned_docs/version-3.x/orm/client.md to versioned_docs/version-3.x/orm/client.mdx.
- Update any inbound links if they reference the .md path.
Also applies to: 21-26, 41-44, 61-62
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: There might be a mistake here.
Context: ...- import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; import P...
(QB_NEW_EN)
[grammar] ~7-~7: There might be a mistake here.
Context: ...abItem'; import Tabs from '@theme/Tabs'; import PackageInstall from '../_componen...
(QB_NEW_EN)
[grammar] ~8-~8: There might be a mistake here.
Context: ...ll from '../_components/PackageInstall'; import ZenStackVsPrisma from '../_compon...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/client.md around lines 6 to 10 (and similarly
for lines 21-26, 41-44, 61-62), the file imports MDX/JSX components but has a
.md extension which will break the Docusaurus build; rename
versioned_docs/version-3.x/orm/client.md to
versioned_docs/version-3.x/orm/client.mdx and update any inbound links or
references (site/content, sidebars, docs metadata, versioned config, and README
links) that point to the .md path to use .mdx so the components are recognized
and the page compiles.
| postCount: (eb) => | ||
| eb.selectFrom('Post') | ||
| .whereRef('Post.authorId', '=', 'id') | ||
| // the `as('count')` part is required because every Kysely selection | ||
| // needs to have a name | ||
| .select(({fn}) => fn.countAll<number>().as('count')), | ||
| }, |
There was a problem hiding this comment.
Fix ambiguous whereRef target — qualify the right-hand reference
The snippet uses .whereRef('Post.authorId', '=', 'id'), which is ambiguous and likely incorrect. Qualify the right-hand side with an explicit ref to User.id, and add the missing sql import in the snippet for completeness.
- postCount: (eb) =>
- eb.selectFrom('Post')
- .whereRef('Post.authorId', '=', 'id')
- // the `as('count')` part is required because every Kysely selection
- // needs to have a name
- .select(({fn}) => fn.countAll<number>().as('count')),
+ postCount: (eb) =>
+ eb.selectFrom('Post')
+ .whereRef('Post.authorId', '=', sql.ref('User', 'id'))
+ // the `as('count')` part is required because every Kysely selection
+ // needs to have a name
+ .select(({ fn }) => fn.countAll<number>().as('count')),And at the top of the snippet, add:
-```ts
+```ts
+import { sql } from 'kysely';Alternatively, remove this first snippet and keep only the context-aware version below that uses sql.ref(currentModel, 'id').
| description: ZenStack ORM overview | ||
| --- | ||
|
|
||
| import ZenStackVsPrisma from '../_components/ZenStackVsPrisma'; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
MDX components in a .md file will not compile — rename to .mdx
This page imports and uses an MDX component () with a .md extension. Docusaurus needs .mdx for JSX/MDX.
Action:
- Rename versioned_docs/version-3.x/orm/index.md to versioned_docs/version-3.x/orm/index.mdx.
- Update any references targeting the .md path.
Also applies to: 120-122
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/orm/index.md around line 6 (and also affecting
lines 120-122), the file imports an MDX component but is named .md which will
not compile; rename the file to versioned_docs/version-3.x/orm/index.mdx and
update all internal and external references (links, sidebar entries, cross-doc
imports) that point to the .md path to use the new .mdx path so Docusaurus can
process the MDX/JSX content correctly.
| | `Float` | `REAL` | `double precision` | | ||
| | `Decimal` | `DECIMAL` | `decimal(65,30)` | | ||
| | `DateTime` | `NUMERIC` | `timestamp(3)` | | ||
| | `Json` | `JSONB` | `jsonb` | |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
SQLite mapping for Json is incorrect; SQLite doesn’t have JSONB.
Default mapping should be TEXT (SQLite has no native JSONB; JSON values are stored as text with JSON1 semantics).
Apply this diff:
-| `Json` | `JSONB` | `jsonb` |
+| `Json` | `TEXT` | `jsonb` |If you intended to surface the presence of the JSON1 extension, we can add a footnote instead (e.g., “SQLite stores JSON as TEXT; JSON1 extension enables JSON functions”).
🏁 Script executed:
#!/bin/bash
# Display the context around line 505 in the attribute.md to verify the Json mapping
sed -n '490,520p' versioned_docs/version-3.x/reference/zmodel/attribute.mdLength of output: 2030
Fix SQLite Json Mapping in Documentation
The default mapping for Json in SQLite should be TEXT, as SQLite does not support a native JSONB column type—JSON values are stored as ordinary text under the JSON1 extension (sqlite.org).
Please update the default mapping table in versioned_docs/version-3.x/reference/zmodel/attribute.md:
- File: versioned_docs/version-3.x/reference/zmodel/attribute.md
- Location: Default mapping table under “Without native type mappings”
-| `Json` | `JSONB` | `jsonb` |
+| `Json` | `TEXT` | `jsonb` |If you’d like to highlight the availability of SQLite’s JSON1/JSONB internal format (introduced in SQLite 3.45.0), consider adding a footnote, for example:
SQLite stores JSON as TEXT (JSON1 extension provides JSON functions; internal JSONB format exists but is not a declared column type).
📝 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.
| | `Json` | `JSONB` | `jsonb` | | |
| | `Json` | `TEXT` | `jsonb` | |
🧰 Tools
🪛 LanguageTool
[grammar] ~505-~505: There might be a mistake here.
Context: ... | JSONB | jsonb | | Bytes | BLOB | bytea ...
(QB_NEW_EN)
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/zmodel/attribute.md around line 505, the
default mapping row currently lists `Json` -> `JSONB` for SQLite which is
incorrect; update the SQLite column mapping from `JSONB` to `TEXT` (since SQLite
stores JSON as plain text via JSON1 and has no declared JSONB type). Also
optionally add a short footnote after the table noting that SQLite stores JSON
as TEXT and that JSON1 provides functions (internal JSONB-like storage exists
but is not a declared column type).
Summary by CodeRabbit
New Features
Documentation
Chores