docs: v3 docs structure #479
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughAdds a new v3 documentation site: Docusaurus config updates, v3 landing pages and styles, many versioned v3 docs and helper components, StackBlitz/GitHub embedding components, Prism ZModel syntax updates, and git submodule registrations for sample repos. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Doc as Doc Page
participant SB as StackBlitzGithub
participant SDK as StackBlitz SDK
participant GH as GithubCodeBlock
User->>Doc: click "Open Playground" / interact with sample
Doc->>SB: open project (repoPath, openFile, startScript)
SB->>SDK: sdk.openGithubProject(repoPath, { openFile, view: "editor", startScript })
Note over SDK: StackBlitz opens editor/playground in new tab
par Render file previews
Doc->>GH: request raw file(s) for preview
GH->>GH: require("!!raw-loader!@site/code-repos/.../file") => code
GH->>Doc: render CodeBlock(code)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
✨ 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 (
|
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: 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.
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" } }
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.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (2)
15-23: Document exact property names and loader return shape for “before” hook.Please name the properties explicitly (e.g., model, action, query AST node, client, queryId) and document the loader’s return type and semantics: single entity vs array, and per-action behavior (create/update/delete). This avoids ambiguity for implementers and aligns the prose with the actual API.
If helpful, extract the source-of-truth types and surface them into the docs:
#!/bin/bash # Find the type(s) that define onEntityMutation contexts and filter names/shapes rg -n -C3 -P '\bonEntityMutation\b|\bEntityMutation\b|\b(before|after)EntityMutation\b|\bmutationInterceptionFilter\b' --type ts --type tsx rg -n -A4 -B4 -P 'interface\s+\w*EntityMutation\w*Context|type\s+\w*EntityMutation\w*Context' --type ts --type tsxPlease update the bullets with backticked, exact property names and clarify the loader signature, e.g., () => Promise<Entity | Entity[]> (or the accurate type) and whether it’s preloaded or must be invoked.
24-31: Clarify “after” hook entity loading, batch shape, and delete behavior.Explicitly state whether the loader returns an array for batch mutations, what is returned for deletes (undefined/null/empty array/not available), and use the precise property names that the API exposes.
Consider adding a short table or code sample that shows:
- create: entitiesBefore = inputs? entitiesAfter = inserted rows?
- update: entitiesBefore = matched rows; entitiesAfter = updated rows
- delete: entitiesBefore = deleted rows; entitiesAfter = (omitted|empty|undefined)
You can verify the intended behavior in types/tests and reflect it here.
#!/bin/bash # Grep tests/usages to confirm expected delete semantics for after-mutation loader rg -n -C2 -P 'afterEntityMutation|entitiesAfter|load(After|Post)Entities' --type ts --type tsx
🧹 Nitpick comments (4)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (4)
21-21: Fix article usage: “A ZenStackClient”, not “An ZenStackClient.”Minor grammar and a small tightening of the second sentence.
- - An `ZenStackClient` instance to perform further queries or mutations. Mutation operations initiated with this client will not trigger the entity mutation hooks again. + - A `ZenStackClient` instance to perform further queries or mutations. Mutations initiated with this client will not trigger the entity mutation hooks again.- - An `ZenStackClient` instance to perform further queries or mutations. Mutation operations initiated with this client will not trigger the entity mutation hooks again. + - A `ZenStackClient` instance to perform further queries or mutations. Mutations initiated with this client will not trigger the entity mutation hooks again.Also applies to: 30-30
33-40: Tighten wording and fix nested list indentation (MD007).Reduces repetition (“If set to…”) and adjusts indentation from 4 to 2 spaces for nested bullets to satisfy markdownlint.
A boolean option that controls whether to run after-mutation hooks within the transaction that performs the mutation. - - If set to `true`, if the mutation already runs inside a transaction, the callbacks are executed immediately after the mutation within the transaction boundary. If the mutation is not running inside a transaction, a new transaction is created to wrap both the mutation and the callbacks. If your hooks make further mutations, they will succeed or fail atomically with the original mutation. - - If set to `false`, the callbacks are executed after the mutation transaction is committed. + - When `true`: if the mutation already runs inside a transaction, callbacks execute immediately after the mutation within the same boundary. Otherwise, a new transaction wraps both the mutation and the callbacks. Hooks that perform additional mutations will succeed or fail atomically with the original mutation. + - When `false`: callbacks execute after the mutation transaction commits. Defaults to `false`.
42-44: Pluralize for accuracy and improve brevity in the info admonition.Small grammar fix and simpler reference to the subject.
-Update and delete triggered by cascading operations are not captured by the entity mutation hooks. +Updates and deletes triggered by cascading operations are not captured by these hooks.
46-48: Rephrase warning to avoid weak intensifier and wordiness.Clearer and more concise language without losing the cautionary tone.
-:::warning -Be very careful about loading before and after mutation entities. Batch mutations can result in a large number of entities being loaded and incur significant performance overhead. -::: +:::warning +Use caution when loading pre- and post-mutation entities. Batch mutations can load many entities and may introduce significant performance overhead. +:::
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
code-repos/zenstackhq/v3-doc-orm(1 hunks)versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- code-repos/zenstackhq/v3-doc-orm
🧰 Additional context used
🪛 LanguageTool
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md
[style] ~36-~36: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ap both the mutation and the callbacks. If your hooks make further mutations, they...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[style] ~37-~37: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...cally with the original mutation. - If set to false, the callbacks are execu...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~43-~43: There might be a mistake here.
Context: ...t captured by the entity mutation hooks. ::: :::warning Be very careful about lo...
(QB_NEW_EN)
[style] ~47-~47: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...tity mutation hooks. ::: :::warning Be very careful about loading before and after mutation...
(EN_WEAK_ADJECTIVE)
[style] ~47-~47: 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)
🪛 markdownlint-cli2 (0.17.2)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md
36-36: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
37-37: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
🔇 Additional comments (1)
versioned_docs/version-3.x/orm/plugins/entity-mutation-hooks.md (1)
52-53: No changes needed for thestartScriptprop
- The
StackBlitzGithubcomponent lives in@site/src/components/StackBlitzGithub.tsxand its props includeso it already supports ainterface StackBlitzGithubProps { repoPath: string; openFile?: string; codeFiles?: string[]; startScript?: string; }startScriptprop.- The component simply passes that string through to the StackBlitz SDK’s embed method:
const options = { openFile, view: 'editor', startScript } as const; sdk.embedProject(containerRef.current, { /* … */, ...options });- The StackBlitz service accepts comma-separated script names in its
startScriptquery parameter to run multiple npm scripts sequentially (e.g.?startScript=build,serve).Because the component’s
startScript: stringsignature aligns with the SDK’sstringParams('startScript', value)behavior and the StackBlitz URL conventions, passing"generate,entity-mutation-hooks"is valid. No updates to the component or docs are required here.
There was a problem hiding this comment.
Actionable comments posted: 8
🧹 Nitpick comments (7)
src/pages/v3/AICoding.tsx (1)
63-65: Prefer stable keys over array indexUse title as key for stability.
- {FeatureList.map((props, idx) => ( - <Proposition key={idx} {...props} /> + {FeatureList.map((props) => ( + <Proposition key={props.title} {...props} /> ))}src/pages/v3/ORM.tsx (1)
36-38: Minor copy tweak (optional)Consider “An ORM derived from your schema that gives you” for smoother phrasing.
- <span className="text-2xl font-semibold text-gray-800"> - An ORM is derived from the schema that gives you - </span> + <span className="text-2xl font-semibold text-gray-800"> + An ORM derived from your schema that gives you + </span>src/pages/v3/SchemaLanguage.tsx (1)
23-26: Add rel/target on external link for security and UXOpen Prisma docs in a new tab and prevent reverse tabnabbing.
- <a href="https://www.prisma.io/docs/orm/prisma-schema/overview">Prisma Schema Language</a>. + <a href="https://www.prisma.io/docs/orm/prisma-schema/overview" target="_blank" rel="noopener noreferrer"> + Prisma Schema Language + </a>.src/pages/v3/Service.tsx (2)
26-27: Add rel/target to external linksEnsure new-tab behavior and mitigate tabnabbing.
- 🚀 Type-safe client SDK powered by <a href="https://tanstack.com/query">TanStack Query</a> + 🚀 Type-safe client SDK powered by <a href="https://tanstack.com/query" target="_blank" rel="noopener noreferrer">TanStack Query</a>- Client hooks based on <a href="https://tanstack.com/query">TanStack Query</a> can also be + Client hooks based on <a href="https://tanstack.com/query" target="_blank" rel="noopener noreferrer">TanStack Query</a> can also beAlso applies to: 37-38
43-43: Set a default tab for deterministic initial renderPrevents hydration surprises and improves UX.
- <Tabs> + <Tabs defaultValue="server">src/pages/v3/index.tsx (1)
13-14: Avoid duplicating site description stringsConsider sourcing meta description from a single place to keep messaging consistent.
If you want to reuse the global description:
+import { description as siteDescription } from '../../lib/content'; - -const description = `ZenStack v3 is a powerful data layer for modern TypeScript applications. It provides an intuitive data modeling language, a fully type-safe ORM, built-in access control and data validation, and automatic data query service that seamlessly integrates with popular frameworks like Next.js and Nuxt.`; +const description = siteDescription;Verify the desired V3-specific copy vs global copy before changing.
Also applies to: 60-60
src/lib/prism-zmodel.js (1)
12-13: No JSON5 code fences detected in docs — aliasingjson5tojsdoes not regress current usage. If JSON5 highlighting is ever needed, load Prism’s JSON5 component or alias toPrism.languages.jsoninstead.
📜 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 (9)
docusaurus.config.js(2 hunks)src/lib/prism-zmodel.js(1 hunks)src/pages/v3/AICoding.tsx(1 hunks)src/pages/v3/Notes.tsx(1 hunks)src/pages/v3/ORM.tsx(1 hunks)src/pages/v3/SchemaLanguage.tsx(1 hunks)src/pages/v3/Service.tsx(1 hunks)src/pages/v3/index.module.css(1 hunks)src/pages/v3/index.tsx(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (2)
src/pages/v3/AICoding.tsx (1)
src/lib/content.ts (1)
description(1-2)
src/pages/v3/index.tsx (6)
src/lib/content.ts (1)
description(1-2)src/pages/v3/SchemaLanguage.tsx (1)
SchemaLanguage(3-55)src/pages/v3/ORM.tsx (1)
ORM(3-56)src/pages/v3/Service.tsx (1)
Service(5-107)src/pages/v3/AICoding.tsx (1)
AICoding(54-69)src/pages/v3/Notes.tsx (1)
Notes(1-20)
🔇 Additional comments (1)
docusaurus.config.js (1)
107-111: Navbar route to /v3Adding the V3 Beta entry is good. I couldn’t find a corresponding landing page (e.g. src/pages/v3/index.tsx or docs/v3). Please confirm that the
/v3route is implemented and builds correctly.
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (5)
src/pages/v3/_components/ORM.tsx (3)
18-23: Clarify top-level await in the sampleAdd a brief note so copy-paste users understand the ESM/top-level-await assumption.
-// high-level query API +// high-level query API (assumes ESM + top-level await) const usersWithPosts = await db.user.findUnique({
36-37: Polish phrasingMore direct phrasing reads better.
- An ORM is derived from the schema that gives you + An ORM derived from your schema gives you
47-51: Unify Kysely link domain
In src/pages/v3/_components/Notes.tsx (line 12), update the<a href="https://kysely.org">tohttps://kysely.devto match the canonical domain used elsewhere.src/pages/v3/_components/AICoding.tsx (1)
63-65: Avoid array index as React key; use a stable identifier- {FeatureList.map((props, idx) => ( - <Proposition key={idx} {...props} /> + {FeatureList.map((props) => ( + <Proposition key={props.title} {...props} /> ))}src/pages/v3/_components/SchemaLanguage.tsx (1)
23-26: Soften migration claim to set accurate expectations- The schema language is a superset of{' '} - <a href="https://www.prisma.io/docs/orm/prisma-schema/overview">Prisma Schema Language</a>. - Migrating a Prisma schema is as simple as file renaming. + The schema language is a superset of{' '} + <a href="https://www.prisma.io/docs/orm/prisma-schema/overview">Prisma Schema Language</a>. + Migrating a Prisma schema is often as simple as renaming the file.
📜 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 (6)
src/pages/v3/_components/AICoding.tsx(1 hunks)src/pages/v3/_components/Notes.tsx(1 hunks)src/pages/v3/_components/ORM.tsx(1 hunks)src/pages/v3/_components/SchemaLanguage.tsx(1 hunks)src/pages/v3/_components/Service.tsx(1 hunks)src/pages/v3/index.tsx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- src/pages/v3/index.tsx
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (3)
versioned_docs/version-3.x/orm/computed-fields.md (2)
1-8: MDX features in a .md file — rename to .mdx or remove JSX/importsThis page imports components and uses JSX; Docusaurus requires an .mdx extension or it will fail to compile/render.
Action:
- Rename: versioned_docs/version-3.x/orm/computed-fields.md → computed-fields.mdx.
- After rename, ensure sidebar IDs/links are still valid.
Optional repo check:
#!/bin/bash # Find .md files under v3 docs that use MDX features (imports/JSX) rg -n --glob 'versioned_docs/version-3.x/**/*.md' -C2 -e '^import ' -e '^\s*<\w'Also applies to: 11-15
32-47: Fix ambiguous whereRef target — qualify RHS as User.id and add missing importUnqualified 'id' is ambiguous/wrong. Use an explicit ref to User.id and include the sql import for completeness.
```ts +import { sql } from 'kysely'; const db = new ZenStackClient(schema, { ... computedFields: { User: { // equivalent SQL: // `(SELECT COUNT(*) AS "count" FROM "Post" WHERE "Post"."authorId" = "User"."id")` - postCount: (eb) => + postCount: (eb) => eb.selectFrom('Post') - .whereRef('Post.authorId', '=', 'id') + .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')), + .select(({ fn }) => fn.countAll<number>().as('count')), }, }, });</blockquote></details> <details> <summary>src/pages/v3/index.tsx (1)</summary><blockquote> `26-26`: **Tailwind class typo: font-semi-bold → font-semibold** ```diff - <p className="hero__subtitle font-semi-bold text-sm sm:text-base md:text-lg lg:text-xl xl:text-2xl mb-6 sm:mb-8 lg:mb-12 leading-relaxed text-gray-100 dark:text-gray-700 max-w-none sm:max-w-2xl text-center"> + <p className="hero__subtitle font-semibold text-sm sm:text-base md:text-lg lg:text-xl xl:text-2xl mb-6 sm:mb-8 lg:mb-12 leading-relaxed text-gray-100 dark:text-gray-700 max-w-none sm:max-w-2xl text-center">
🧹 Nitpick comments (4)
versioned_docs/version-3.x/orm/computed-fields.md (2)
21-22: Tighten the wording for clarityMinor phrasing nit to improve readability.
-Defining a computed field involves two steps. First, add the field in the ZModel schema to a model and annotate it with the `@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.
53-68: LGTM on context-aware example; optional style nitThe
sql.ref(currentModel, 'id')usage is correct. Style nit below for consistency.- .select(({fn}) => fn.countAll<number>().as('count')), + .select(({ fn }) => fn.countAll<number>().as('count')),src/pages/v3/_components/ValueProps.tsx (2)
38-38: Defer image loading for performanceAdd loading/decoding hints.
- <img className="w-48 p-10" src={img} alt={title} /> + <img className="w-48 p-10" src={img} alt={title} loading="lazy" decoding="async" />
51-53: Avoid index as React keyUse a stable identifier to prevent subtle re-render issues.
- {FeatureList.map((props, idx) => ( - <Proposition key={idx} {...props} /> + {FeatureList.map((props) => ( + <Proposition key={props.title} {...props} /> ))}
📜 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)
static/img/diagram.pngis excluded by!**/*.png,!**/*.pngstatic/img/search.pngis excluded by!**/*.png,!**/*.pngstatic/img/versatility.pngis excluded by!**/*.png,!**/*.png
📒 Files selected for processing (8)
docusaurus.config.js(3 hunks)src/pages/v3/_components/AICoding.tsx(1 hunks)src/pages/v3/_components/ORM.tsx(1 hunks)src/pages/v3/_components/Schema.tsx(1 hunks)src/pages/v3/_components/Service.tsx(1 hunks)src/pages/v3/_components/ValueProps.tsx(1 hunks)src/pages/v3/index.tsx(1 hunks)versioned_docs/version-3.x/orm/computed-fields.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (4)
- src/pages/v3/_components/AICoding.tsx
- src/pages/v3/_components/ORM.tsx
- docusaurus.config.js
- src/pages/v3/_components/Service.tsx
🧰 Additional context used
🪛 Biome (2.1.2)
src/pages/v3/index.tsx
[error] 39-40: Avoid using target="_blank" without rel="noopener" or rel="noreferrer".
Opening external links in new tabs without rel="noopener" is a security risk. See the explanation for more details.
Safe fix: Add the rel="noopener" attribute.
(lint/security/noBlankTarget)
🪛 LanguageTool
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)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/computed-fields.md (1)
72-73: StackBlitz embed wiring verified Component exists, submodule initialized, andrepoPath="zenstackhq/v3-doc-orm-computed-fields"matches the submodule directory—no further changes needed.src/pages/v3/_components/Schema.tsx (1)
3-11: Component structure and styling look solidClean, self-contained component; props-free and SSR-safe. Good use of CodeBlock and responsive layout.
src/pages/v3/index.tsx (1)
64-101: Overall page composition looks goodImports, Section wrapper, and alternating backgrounds are consistent and SSR-safe.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
src/pages/v3/index.tsx (2)
26-29: Tailwind class typo: usefont-semibold- <p className="hero__subtitle font-semi-bold text-base sm:text-base md:text-lg lg:text-xl xl:text-2xl mb-6 sm:mb-8 lg:mb-12 leading-relaxed text-gray-100 dark:text-gray-700 max-w-none sm:max-w-2xl text-center"> + <p className="hero__subtitle font-semibold text-base sm:text-base md:text-lg lg:text-xl xl:text-2xl mb-6 sm:mb-8 lg:mb-12 leading-relaxed text-gray-100 dark:text-gray-700 max-w-none sm:max-w-2xl text-center">
37-43: Addrel="noopener noreferrer"to external link opened in new tabPrevents
window.openerleaks and matches lint rule.- <a + <a href="https://stackblitz.com/~/github.com/zenstackhq/v3-doc-quick-start?file=zenstack%2fschema.zmodel&file=main.ts&view=editor&showSidebar=0&hideNavigation=1&hideExplorer=1" - target="_blank" + target="_blank" rel="noopener noreferrer" className="button button--outline button--lg border-solid lg:text-2xl lg:px-8 lg:py-4 hover:text-gray-200 dark:hover:text-gray-600" >
🧹 Nitpick comments (3)
src/css/custom.css (2)
78-81: Selector likely a no-op:.navbar__item--rightdoesn't exist in Docusaurus markupMobile menu items render as
.menu__item/.menu__linkunder.navbar-sidebar, notnavbar__item--right. This rule won’t affect anything; drop it or target the sidebar classes.- /* force display of right items in the toggle menu */ - .navbar__item.navbar__item--right { - display: block !important; - } + /* mobile sidebar already displays items; no override needed */ + /* If you must target sidebar items, use: + .navbar-sidebar .menu__link { display: block; } + */
83-85: Use explicit display value for the toggle
display: inheritcan be inconsistent; setinline-flexto match Docusaurus’ toggle intent.- .navbar__toggle { - display: inherit; - } + .navbar__toggle { + display: inline-flex; + }src/pages/v3/index.tsx (1)
55-58: Avoid conflicting background utilities inSection
dark:bg-gray-900in the wrapper conflicts with per-sectiondark:bg-slate-800. Let callers control background.- <section - className={`flex justify-center px-8 py-16 lg:px-16 lg:py-32 text-gray-800 dark:bg-gray-900 dark:text-gray-200 ${ + <section + className={`flex justify-center px-8 py-16 lg:px-16 lg:py-32 text-gray-800 dark:text-gray-200 ${ className ?? '' }`} >
📜 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 (6)
src/css/custom.css(1 hunks)src/pages/v3/_components/AICoding.tsx(1 hunks)src/pages/v3/_components/ORM.tsx(1 hunks)src/pages/v3/_components/Schema.tsx(1 hunks)src/pages/v3/_components/Service.tsx(1 hunks)src/pages/v3/index.tsx(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (4)
- src/pages/v3/_components/Schema.tsx
- src/pages/v3/_components/ORM.tsx
- src/pages/v3/_components/Service.tsx
- src/pages/v3/_components/AICoding.tsx
🧰 Additional context used
🧬 Code graph analysis (1)
src/pages/v3/index.tsx (6)
src/lib/content.ts (1)
description(1-2)src/pages/v3/_components/ValueProps.tsx (1)
ValueProps(48-56)src/pages/v3/_components/Schema.tsx (1)
SchemaLanguage(3-55)src/pages/v3/_components/ORM.tsx (1)
ORM(3-56)src/pages/v3/_components/Service.tsx (1)
Service(5-109)src/pages/v3/_components/AICoding.tsx (1)
AICoding(54-69)
🪛 Biome (2.1.2)
src/pages/v3/index.tsx
[error] 39-40: Avoid using target="_blank" without rel="noopener" or rel="noreferrer".
Opening external links in new tabs without rel="noopener" is a security risk. See the explanation for more details.
Safe fix: Add the rel="noopener" attribute.
(lint/security/noBlankTarget)
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (2)
versioned_docs/version-3.x/modeling/polymorphism.md (2)
16-19: Tighten intro wording and fix capitalization/pluralizationUse plain case for object-oriented terms and clearer phrasing.
-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" form of polymorphism often arises: +- Something **is-a** a more abstract type. +- Something **has a/has many** relationship with a more abstract type.
72-100: Mermaid ER diagram: replace hard tabs (MD010) and normalize indentationTabs trigger markdownlint and render inconsistently. Also align indentation uniformly.
```mermaid erDiagram - 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 + 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</blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (27)</summary><blockquote> <details> <summary>versioned_docs/version-3.x/orm/quick-start.md (6)</summary><blockquote> `6-9`: **Confirm TSX components under versioned_docs build correctly** Importing TSX from versioned_docs can be brittle depending on Docusaurus config. Please confirm build/TypeScript settings transpile these .tsx files when imported from docs. If not, consider moving PackageInstall/PackageExec to src/components or converting them to MDX snippets. --- `23-25`: **Offer pnpm/yarn equivalents for scaffolding** Add alternatives to reduce friction for non-npm users. Apply this diff: ```diff ```bash npm create zenstack@next my-project
+Alternatively:
+
+bash +# pnpm +pnpm create zenstack@next my-project +# yarn (classic) +yarn create zenstack@next my-project +--- `27-28`: **Use embedded StackBlitz for a smoother UX (or fix minor grammar)** Embedding avoids context-switching and clarifies repo origin. Also tweak “inside the browser” -> “in the browser.” Option A (embed): ```diff -Or simply use the [interactive playground](https://stackblitz.com/~/github.com/zenstackhq/v3-doc-quick-start) to experience it inside the browser. +Or try it right here: + +<StackBlitzGithub repo="zenstackhq/v3-doc-quick-start" />Option B (grammar only):
-Or simply use the [interactive playground](https://stackblitz.com/~/github.com/zenstackhq/v3-doc-quick-start) to experience it inside the browser. +Or simply use the [interactive playground](https://stackblitz.com/~/github.com/zenstackhq/v3-doc-quick-start) to experience it in the browser.
35-37: Clarify schema file location wordingSlight rephrase improves precision.
-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 `zenstack/schema.zmodel` at the project root. You can use the following sample schema to get started:
49-55: Confirm required peer deps (Prisma?) are covered or linkedIf ZenStack v3 runtime/CLI relies on Prisma (
prisma,@prisma/client) for DB operations, consider listing them here or linking to a prerequisites section.
61-67: Augment CLI options with a concrete example + CI tipAdding an example reduces ambiguity and helps CI consumers.
:::info 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. ::: + +Example: + +```bash +# Use a custom schema path and output directory +zen generate --schema ./db/schema.zmodel --output ./src/zenstack +``` + +CI tip: + +```bash +# Ensure codegen runs before build/test +zen generate +npm run build +```versioned_docs/version-3.x/reference/cli.md (3)
32-32: Use “Subcommands” (one word).Minor wording consistency improvement for headings.
-## Sub Commands +## Subcommands
2-2: Tighten front matter description (singular).Doc describes a single CLI reference page.
-description: CLI references +description: CLI reference
201-201: Grammar: “information about …”Adjust prose (outside code blocks) while keeping CLI output blocks verbatim.
-Get information of installed ZenStack packages. +Get information about installed ZenStack packages.versioned_docs/version-3.x/prerequisite.md (6)
5-5: Pluralize the page title.“Prerequisites” reads better and matches common docs style.
-# Prerequisite +# Prerequisites
9-14: Standardize version wording; recommend LTS; confirm TS minimum.Tweak phrasing and verify that 5.8 is indeed the minimum required.
-Node.js v20 or above. +Node.js 20+ (LTS recommended). -TypeScript v5.8.0 or above. +TypeScript 5.8+.Would you confirm that TS 5.8 is the true minimum for v3?
17-21: Capitalize “IDs” and prefer “VS Code”; minor wording polish.Also keeps terminology consistent across docs.
-If you use VSCode, please install the [ZenStack V3 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=zenstack.zenstack-v3) for syntax highlighting, auto-completion, and error reporting. +If you use VS Code, please install the [ZenStack V3 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=zenstack.zenstack-v3) for syntax highlighting, auto-completion, and error reporting. -If you use both ZenStack v2 and v3 in different projects, you can install the original [ZenStack VSCode Extension](https://marketplace.visualstudio.com/items?itemName=zenstack.zenstack) side-by-side with the v3 extension. The two extensions have different language ids (v2: `zmodel`, v3: `zmodel-v3`) but handle the same `.zmodel` file extension. To avoid conflicts, make sure you specify the language id explicitly in the `.vscode/settings.json` file in your project: +If you use both ZenStack v2 and v3 in different projects, you can install the original [ZenStack VSCode Extension](https://marketplace.visualstudio.com/items?itemName=zenstack.zenstack) side-by-side with the v3 extension. The two extensions have different language IDs (v2: `zmodel`, v3: `zmodel-v3`) but handle the same `.zmodel` file extension. To avoid conflicts, specify the language ID explicitly in the `.vscode/settings.json` file of your project:
19-19: Use more descriptive alt text for accessibility.- +
23-29: Use jsonc code fence since the snippet contains comments.Prevents “invalid JSON” highlighting.
-```json +```jsonc { "files.associations": { "*.zmodel": "zmodel-v3" // use "zmodel" for ZenStack v2 projects } }--- `31-31`: **Softer, clearer IDE support note.** ```diff -Other IDEs are not supported at this time. +Currently, only the VS Code extension is supported.src/components/ValueProposition.tsx (5)
36-37: Micro-copy polish for flow/grammarSmall tweak improves readability.
- Schema-first reduces code complexity, helping AI understand better with fewer hallucinations. Schema - serves as a single source of truth for AI integration. + Schema-first reduces code complexity, helping AI understand your code with fewer hallucinations. The schema + serves as a single source of truth for AI integration.
50-50: Heading lost weight (Tailwind preflight sets h font-weight: inherit)*If boldness was intended, add an explicit weight.
- <h3 className="text-xl text-center lg:text-2xl text-gray-700 dark:text-gray-300">{title}</h3> + <h3 className="text-xl lg:text-2xl font-semibold text-center text-gray-700 dark:text-gray-300">{title}</h3>
45-45: Non-standard Tailwind class: lg:max-w-1/3Tailwind doesn’t ship max-w-1/3 by default; consider a supported pattern.
- <div className="lg:max-w-1/3 w-full"> + <div className="w-full lg:basis-1/3 lg:max-w-none">Alternatively:
lg:w-1/3orlg:max-w-[33%](arbitrary value).
47-47: Defer image work for faster LCPLazy-load and async-decode non-critical images.
- <img className="w-48 p-10" src={img} alt={title} /> + <img className="w-48 p-10" src={img} alt={title} loading="lazy" decoding="async" />
76-79: Prefer stable keys over array indexAvoids unnecessary remounts if the list changes.
- {FeatureList.map((props, idx) => ( - <Proposition key={idx} {...props} /> - ))} + {FeatureList.map((props) => ( + <Proposition key={props.title} {...props} /> + ))}src/pages/v3/index.module.css (1)
6-11: Drop unnecessary !important (CSS Modules already scope strongly)Unless you’re overriding third-party inline styles, these can be removed for easier theming/overrides.
.heroBanner { - padding: 8rem 2rem !important; - text-align: center !important; - position: relative !important; - overflow: hidden !important; + padding: 8rem 2rem; + text-align: center; + position: relative; + overflow: hidden; } @media screen and (max-width: 996px) { .heroBanner { - padding-top: 4rem !important; - padding-bottom: 4rem !important; + padding-top: 4rem; + padding-bottom: 4rem; } }Also applies to: 13-18
versioned_docs/version-3.x/modeling/polymorphism.md (6)
30-32: Minor style: “aka” punctuationPrefer parenthetical “aka” without a trailing period.
-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's implementation follows the MTI pattern.
104-105: Grammar: type phrasingReads smoother as “of type …”.
-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. +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 type `String` or an enum.
107-108: Avoid sentence fragment; tighten guidance-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. Make sure each base model has its own discriminator field and `@@delegate` attribute. Extending from multiple base models directly is not supported.
111-114: Grammar: “querying”, ID capitalization, 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 querying and conserve space, the base and concrete models 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`.
119-121: Clarity: discriminator “value”, ID capitalization-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 base model record with the same ID and the appropriate discriminator value. +2. Querying the base model returns entities with their concrete model fields.
122-122: Grammar: “in detail”-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.
📜 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 (1)
versioned_docs/version-3.x/vscode.pngis excluded by!**/*.png,!**/*.png
📒 Files selected for processing (14)
code-repos/zenstackhq/v3-doc-orm(1 hunks)code-repos/zenstackhq/v3-doc-quick-start(1 hunks)src/components/ValueProposition.tsx(2 hunks)src/pages/v3/_components/AICoding.tsx(1 hunks)src/pages/v3/_components/Notes.tsx(1 hunks)src/pages/v3/_components/ORM.tsx(1 hunks)src/pages/v3/_components/Schema.tsx(1 hunks)src/pages/v3/_components/Service.tsx(1 hunks)src/pages/v3/_components/ValueProps.tsx(1 hunks)src/pages/v3/index.module.css(1 hunks)versioned_docs/version-3.x/modeling/polymorphism.md(1 hunks)versioned_docs/version-3.x/orm/quick-start.md(1 hunks)versioned_docs/version-3.x/prerequisite.md(1 hunks)versioned_docs/version-3.x/reference/cli.md(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- code-repos/zenstackhq/v3-doc-orm
🚧 Files skipped from review as they are similar to previous changes (7)
- src/pages/v3/_components/ORM.tsx
- code-repos/zenstackhq/v3-doc-quick-start
- src/pages/v3/_components/ValueProps.tsx
- src/pages/v3/_components/AICoding.tsx
- src/pages/v3/_components/Notes.tsx
- src/pages/v3/_components/Service.tsx
- src/pages/v3/_components/Schema.tsx
🧰 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
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🪛 LanguageTool
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/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)
🔇 Additional comments (3)
versioned_docs/version-3.x/orm/quick-start.md (1)
33-33: Validate PackageExec rendering/execution across package managersPlease confirm renders usable commands for npm/pnpm/yarn (e.g., npx/pnpm dlx) and works on Windows shells. Same for “zen generate” below.
src/pages/v3/index.module.css (1)
20-24: LGTM: simple and clear button layoutCentered flex for CTA cluster looks good.
versioned_docs/version-3.x/modeling/polymorphism.md (1)
1-122: Run markdownlint fixes and verify component & link paths
- Fix lint issues in versioned_docs/version-3.x/modeling/polymorphism.md: MD041, MD033, MD013, MD032; remove hard tabs (MD010) at lines 74 and 76; add fenced-code languages where missing (MD040) as needed.
- Verify the imported component path ../_components/ZModelVsPSL exists (add or correct file under versioned_docs/version-3.x/_components or update the import).
- Confirm the relative ORM link target is present: versioned_docs/version-3.x/orm/polymorphism.md (already exists).
- Re-run: npx -y markdownlint-cli2 'versioned_docs/**/.md' and iterate until no remaining MD010/MD040/MD033/MD041 failures.
|
|
||
| If you use VSCode, please install the [ZenStack V3 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=zenstack.zenstack-v3) for syntax highlighting, auto-completion, and error reporting. | ||
|
|
||
|  |
There was a problem hiding this comment.
💡 Verification agent
❓ Verification inconclusive
Verify the image asset exists at the referenced path.
Avoids a broken image in the rendered docs.
Expected: one match under versioned_docs/version-3.x/.
🏁 Script executed:
#!/bin/bash
# Confirm the image file is present next to prerequisite.md
fd -H -a -t f '^vscode\.png$' | sed -n '1,5p'Length of output: 45
🏁 Script executed:
#!/bin/bash
# Search for any file with 'vscode' in the name across the repository (case-insensitive)
fd -H -a -t f -i vscodeLength of output: 25
🏁 Script executed:
#!/bin/bash
# Search for any .png files in the versioned_docs/version-3.x directory
fd -H -a -t f -e png versioned_docs/version-3.x | sed -n '1,10p'Length of output: 474
🏁 Script executed:
#!/bin/bash
# List any .png files under versioned_docs/version-3.x to verify presence of vscode.png
fd --full-path 'versioned_docs/version-3.x/.*\.png$' | sed -n '1,5p'Length of output: 68
Add missing vscode.png asset or correct its path
versioned_docs/version-3.x/prerequisite.md:19 references ./vscode.png, but no such file exists; add the image to that folder or update the link to the correct location.
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/prerequisite.md around line 19, the document
references ./vscode.png which does not exist; either add the vscode.png image
file to versioned_docs/version-3.x or update the image link to the correct
existing path (e.g., assets/images/vscode.png or ../images/vscode.png) and
verify the relative path works in the built site; ensure the file is committed
to the repo if added.
| ``` | ||
| zen [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 | ||
| ``` |
There was a problem hiding this comment.
Fix markdownlint MD040: add a language to the fenced block.
The unlabeled fence triggers MD040 and can fail docs CI. Use "text" to reflect CLI output.
-```
+```text
zen [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
-```
+```🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
11-11: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/cli.md around lines 11 to 30 the fenced
code block is unlabeled which triggers markdownlint MD040; update the opening
fence from ``` to ```text (leaving the block content and closing fence
unchanged) so the snippet is marked as plain text for linting and CI.
| --schema <file> schema file (with extension .zmodel). Defaults to "zenstack/schema.zmodel" unless | ||
| specified in package.json. | ||
| -o, --output <path> default output directory for code generation | ||
| --silent suppress all output except errors (default: false) |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Request verification: confirm option names/paths match v3 CLI.
CLI flags and defaults can drift between releases (e.g., default schema path, migrations path flags). Please verify against the current v3 zen help to avoid stale docs.
Also applies to: 86-91, 108-113, 125-129, 141-145, 157-163, 192-197, 241-244
🌐 Web query:
Please confirm the current ZenStack v3 CLI help for:
- `zen generate` options (schema default path and `--output`)
- `zen migrate dev/reset/deploy/status/resolve` options (including `--migrations`, `--create-only`, `--rolled-back`, etc.)
- `zen db push` options (`--accept-data-loss`, `--force-reset`)
- Default schema path (“zenstack/schema.zmodel”) and `package.json` overrides (“zenstack.schema”, “zenstack.output”)
Look up the official docs or run `npx zen --help`, `npx zen migrate --help`, and subcommand helps, then confirm any differences.
💡 Result:
Summary of findings (checked official ZenStack docs and Prisma docs):
- zen generate
- Options (from ZenStack CLI reference): --schema (schema .zmodel file, default ./schema.zmodel), -o / --output (default node_modules/.zenstack), --with-plugins, --without-plugins, --no-default-plugins, --no-compile, --no-version-check. Example package.json override shown for schema under "zenstack". [1][4]
- Default schema path and package.json overrides
- Default ZModel schema path: ./schema.zmodel (ZenStack CLI docs). You may set schema path in package.json under "zenstack": { "schema": "./path/schema.zmodel" }. The docs show the schema override; an "output" override in package.json is not shown in the official docs (the CLI supports an --output flag on the command line). [1][4]
- zen migrate / zen db push
-
ZenStack CLI does not reimplement Prisma Migrate/DB commands; ZenStack generates prisma/schema.prisma and instructs you to use the Prisma CLI (npx prisma ...) for migrations and db operations. So there is no separate full-featured "zen migrate" or "zen db push" in ZenStack docs — use prisma commands. [4]
-
Prisma migrate options (relevant ones referenced by ZenStack docs and Prisma docs):
- prisma migrate dev: --create-only, --name/-n, --skip-seed, --skip-generate, --schema . [3]
- prisma migrate reset / dev / deploy / status / resolve: migrate reset is a development reset command; migrate resolve accepts --applied or --rolled-back to mark migrations. See Prisma docs for full subcommand options. [3][5]
-
prisma db push options (relevant flags):
- --accept-data-loss (required to ignore data-loss warnings),
- --force-reset (reset DB then push),
- --skip-generate,
- --schema .
(These are Prisma CLI options; use npx prisma db push ...). [3][4][6]
- Confirmation about running npx zen --help / npx zen migrate --help
- The ZenStack docs show the CLI help for zenstack (commands like generate, repl, format, check). They instruct using Prisma for migrate/db commands. If you run npx zenstack --help (or npx zenstack generate --help) you will see the same options listed in the docs above. For migrate/db push help, run the Prisma CLI help (npx prisma migrate --help, npx prisma db push --help) to see the migrate/db options described in the Prisma docs cited here. [1][4][3]
Sources
- ZenStack CLI reference / docs (generate, defaults, package.json example). [1] https://zenstack.dev/docs/reference/cli and [4] https://zenstack.dev/docs/the-complete-guide/part1/cli
- ZenStack guide noting CLI produces prisma/schema.prisma and delegates migrations to Prisma. [4]
- Prisma CLI / Migrate / db push docs (flags: --create-only, --applied/--rolled-back for resolve, --accept-data-loss, --force-reset, --schema, etc.). [3] https://www.prisma.io/docs/orm/reference/prisma-cli-reference
- Fig/manual and Prisma changelog references for db push flags. [6][5]
If you want, I can:
- run npx zenstack generate --help and npx prisma migrate --help in a shell and paste the exact CLI output (requires me to run those commands in your environment), or
- paste the exact help text from npx zenstack@latest (I can fetch and show it if you want). Which would you prefer?
Align CLI docs with ZenStack v3 & Prisma CLI delegation
- Update
--schemadefault to./schema.zmodel(override viazenstack.schemaonly), removing “zenstack/schema.zmodel” reference. - Change
--outputdefault tonode_modules/.zenstackand drop any package.json override for output. - Only document
zen generateflags (--with-plugins,--without-plugins,--no-default-plugins,--no-compile,--no-version-check). - Remove
zen migrate/zen db pushsubcommand docs; add note to runnpx prisma migrate [dev|reset|deploy|status|resolve](with flags like--create-only,--rolled-back) andnpx prisma db push(with--accept-data-loss,--force-reset,--schema).
🤖 Prompt for AI Agents
In versioned_docs/version-3.x/reference/cli.md around lines 44 to 47, update the
CLI docs to match ZenStack v3 and Prisma CLI delegation: change the --schema
default to "./schema.zmodel" and note it can only be overridden via
zenstack.schema (remove any reference to "zenstack/schema.zmodel"); change the
--output default to "node_modules/.zenstack" and remove any package.json
override mention; restrict listed documented flags to only the zen generate
flags (--with-plugins, --without-plugins, --no-default-plugins, --no-compile,
--no-version-check); remove the sections describing zen migrate / zen db push
subcommands and instead add a short note instructing users to run the
corresponding Prisma commands (npx prisma migrate
[dev|reset|deploy|status|resolve] with flags like --create-only, --rolled-back,
and npx prisma db push with flags like --accept-data-loss, --force-reset,
--schema).
Summary by CodeRabbit
New Features
Documentation
Style
Chores