docs: add README #27
docs: add README #27
Conversation
WalkthroughThe updates include a comprehensive rewrite and expansion of the README documentation, adjustments to the TODO list structure, and version bumps from Changes
Poem
✨ Finishing Touches
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. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (11)
packages/runtime/test/plugin/query-lifecycle.test.ts (1)
156-158: Good addition, but consider asserting the error contentAdding an explicit
// no-opclarifies the intentional swallowing of errors – nice touch.
Since the tests rely on the error to trigger rollback logic, it may be safer to capture the error object (catch (e) { /* ... */ }) and assert its message to avoid accidentally masking an unexpected failure source.Example (optional):
-} catch { - // no-op +} catch (e) { + expect((e as Error).message).toBe('trigger error'); }Also applies to: 185-187
README.md (10)
21-21: Shorten alpha warning for clarity.The current warning is wordy. Consider a more concise statement that still highlights the alpha status and support channel.
-> V3 is currently in alpha phase and not ready for production use. Feedback and bug reports are greatly appreciated. Please visit this dedicated [discord channel](https://discord.com/channels/1035538056146595961/1352359627525718056) for chat and support. +> **Alpha Release:** ZenStack V3 is in active alpha—use at your own risk. Join our [Discord support channel](https://discord.com/channels/1035538056146595961/1352359627525718056) for feedback and assistance.
37-37: Replace 'biggest' with 'most significant'.The word “biggest” is overused; use “most significant” for stronger impact.
-The biggest change is V3 doesn't have a runtime dependency to Prisma anymore. +The most significant change in V3 is the removal of the runtime dependency on Prisma.
47-47: Remove redundant hyphens in bullet.The hyphens in “Fully-typed” and “query-builder” are unnecessary; simplify for readability.
-3. Fully-typed query-builder API as a better escape hatch compared to Prisma's [raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries) or [typed SQL](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql). +3. Fully typed query builder API as a better escape hatch compared to Prisma's [raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries) or [typed SQL](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/typedsql).
89-89: Correct 'super set' to 'superset'.“Super set” should be a single word in this context.
-ZModel is a super set of [Prisma Schema Language](https://www.prisma.io/docs/orm/prisma-schema/overview), i.e., every valid Prisma schema is a valid ZModel. +ZModel is a superset of [Prisma Schema Language](https://www.prisma.io/docs/orm/prisma-schema/overview), i.e., every valid Prisma schema is a valid ZModel.
55-71: Remove numbering from section headings.Headings should remain semantic; use plain titles and list items for numbering.
-### 1. Creating a new project +### Creating a new project ... -### 2. Setting up an existing project +### Setting up an existing project ... -### 3. Manual setup +### Manual setup
176-176: Avoid uncommon contraction 'Here’re'.Replace with the more standard “Here are”.
-Please check [Kysely documentation](https://kysely.dev/docs/intro) for more details. Here're a few quick examples: +Please check [Kysely documentation](https://kysely.dev/docs/intro) for more details. Here are a few quick examples:
198-198: Strengthen adjective and fix hyphenation.Use a stronger adjective and hyphenate “long-standing.”
-It provides a good solution to the long standing `whereRaw` [Prisma feature request](https://github.com/prisma/prisma/issues/5560). +It provides an effective solution to the long-standing `whereRaw` [Prisma feature request](https://github.com/prisma/prisma/issues/5560).
233-233: Add comma for compound sentence.A comma before “so” clarifies the relationship between clauses.
-The field is fully evaluated at the database side so performance will be optimal. +The field is fully evaluated at the database side, so performance will be optimal.
272-272: Add comma after introductory adverb.Introductory “Usually” should be followed by a comma.
-Usually a plugin would call the `proceed` callback to trigger the execution of the original query, but you can choose to completely override the query behavior with custom logic. +Usually, a plugin would call the `proceed` callback to trigger the execution of the original query, but you can choose to completely override the query behavior with custom logic.
280-280: Add comma before conjunction.A comma before “but” improves readability.
-It’s harder to implement but can guarantee intercepting all CRUD operations. +It’s harder to implement, but can guarantee intercepting all CRUD operations.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
README.md(1 hunks)TODO.md(1 hunks)package.json(1 hunks)packages/cli/package.json(1 hunks)packages/cli/src/actions/generate.ts(1 hunks)packages/cli/src/actions/init.ts(1 hunks)packages/create-zenstack/package.json(1 hunks)packages/create-zenstack/src/index.ts(1 hunks)packages/language/package.json(1 hunks)packages/runtime/package.json(1 hunks)packages/runtime/test/plugin/query-lifecycle.test.ts(2 hunks)packages/sdk/package.json(1 hunks)packages/sdk/src/prisma/prisma-schema-generator.ts(0 hunks)packages/tanstack-query/package.json(1 hunks)packages/testtools/package.json(1 hunks)packages/zod/package.json(1 hunks)samples/blog/package.json(1 hunks)
💤 Files with no reviewable changes (1)
- packages/sdk/src/prisma/prisma-schema-generator.ts
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
TODO.md
72-72: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
73-73: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
74-74: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
77-77: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
78-78: Unordered list indentation
Expected: 2; Actual: 4
(MD007, ul-indent)
79-79: Unordered list indentation
Expected: 4; Actual: 8
(MD007, ul-indent)
🪛 LanguageTool
README.md
[style] ~37-~37: The word ‘biggest’ tends to be overused. Consider an alternative.
Context: ...://github.com/zenstackhq/zenstack). The biggest change is V3 doesn't have a runtime dependency...
(BIG_DIFFERENCE)
[uncategorized] ~45-~45: The hyphen in Fully-typed is redundant.
Context: ...ype inference, less code generation. 3. Fully-typed query-builder API as a better escape ha...
(ADVERB_LY_HYPHEN_FIX)
[style] ~123-~123: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...on. ## Compiling ZModel schema ZModel needs to be compiled to TypeScript before being ...
(REP_NEED_TO_VB)
[style] ~129-~129: Consider shortening or rephrasing this to strengthen your wording.
Context: ...run the "generate" command whenever you make changes to the ZModel schema. ## Creating ZenStac...
(MAKE_CHANGES)
[style] ~176-~176: The contraction ‘Here’re’ is uncommon in written English.
Context: ...ysely.dev/docs/intro) for more details. Here're a few quick examples: ```ts await clie...
(THERE_RE_CONTRACTION_UNCOMMON)
[style] ~198-~198: Consider using a different adjective in this context to strengthen your wording.
Context: ...ck.dev'), }, }); ``` It provides a good solution to the long standing `whereRaw...
(GOOD_ALTERNATIVE)
[misspelling] ~198-~198: This word is normally spelled with a hyphen.
Context: ...``` It provides a good solution to the long standing whereRaw [Prisma feature request](htt...
(EN_COMPOUNDS_LONG_STANDING)
[uncategorized] ~232-~232: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ... is fully evaluated at the database side so performance will be optimal. ### Polym...
(COMMA_COMPOUND_SENTENCE_2)
[typographical] ~273-~273: Consider adding a comma after ‘Usually’ for more clarity.
Context: ... return result; }, }); ``` Usually a plugin would call the proceed callb...
(RB_LY_COMMA)
[style] ~274-~274: Try moving the adverb to make the sentence clearer.
Context: ...tion of the original query, but you can choose to completely override the query behavior with custom logic. #### 2. Kysely quer...
(SPLIT_INFINITIVE)
[uncategorized] ~280-~280: Possible missing comma found.
Context: ...de` structures. It's harder to implement but can guarantee intercepting all CRUD ope...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (2)
- GitHub Check: build-test (20.x)
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (13)
samples/blog/package.json (1)
3-3: Bump sample-todo version to v3.0.0-alpha.2
Aligns this sample project with the coordinated alpha.2 release across the monorepo.packages/zod/package.json (1)
3-3: Update @zenstackhq/zod to v3.0.0-alpha.2
Consistent version bump with other ZenStack packages for the alpha.2 rollout.packages/runtime/package.json (1)
3-3: Upgrade @zenstackhq/runtime to v3.0.0-alpha.2
Keeps the runtime in sync with the latest alpha release across the ecosystem.packages/tanstack-query/package.json (1)
3-3: Set @zenstackhq/tanstack-query version to v3.0.0-alpha.2
Matches the synchronized version bump for the alpha.2 release.packages/language/package.json (1)
4-4: Align @zenstackhq/language with v3.0.0-alpha.2
Ensures the language package is updated in step with the coordinated alpha.2 update.packages/sdk/package.json (1)
3-3: Consistent version bump to 3.0.0-alpha.2
This aligns with the synchronized release across ZenStack packages.package.json (1)
3-3: Updated root version to 3.0.0-alpha.2
Matches the sub-packages and samples.packages/testtools/package.json (1)
3-3: Bumped testtools package version to 3.0.0-alpha.2
Synchronized with other core packages; no metadata changes.packages/cli/src/actions/generate.ts (1)
39-45: Improve code block formatting in console output
Switching to a TypeScript-specific block (```ts) enhances readability without altering functionality.TODO.md (1)
79-79: RevertedMulti-schemato incomplete as intended
The change from[x]to[ ]for the PostgreSQL multi-schema task correctly reflects its in-progress status.packages/cli/package.json (1)
6-6: Version bump looks fineThe update to
3.0.0-alpha.2aligns with the coordinated release across the mono-repo. No further action required.packages/create-zenstack/package.json (1)
3-3: Package version synchronised
create-zenstackis now on3.0.0-alpha.2, keeping it in lock-step with sibling packages. 👍README.md (1)
252-252: Verify the plugin interface link.The relative path
[RuntimePlugin](./packages/runtime/src/client/plugin.ts#L121)may not resolve correctly in the rendered README. Please confirm the URL or switch to an absolute GitHub link.
| - [ ] Polymorphism | ||
| - [ ] Validation |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Incorrect placement and indentation of ORM items
The Polymorphism and Validation entries are currently top-level but should be nested under the ORM section with the same indent as other ORM sub-items.
Apply this diff to move and indent them appropriately:
@@ -9,6 +9,10 @@
- [ ] ORM
- [x] Create
...
- [ ] Strict undefined check
+ - [ ] Polymorphism
+ - [ ] Validation
- [ ] Extensions
...Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In TODO.md around lines 69 to 70, the items "Polymorphism" and "Validation" are
incorrectly placed as top-level entries. Move these two items under the "ORM"
section and indent them to match the other ORM sub-items for consistent
formatting and correct hierarchy.
| { name: '@zenstackhq/cli@next', dev: true }, | ||
| { name: '@zenstackhq/runtime@next', dev: false }, |
There was a problem hiding this comment.
🛠️ Refactor suggestion
yarn install path is still incorrect – switch to yarn add
Great to see the @next tags added. However, for Yarn users the command produced by installPackage is still yarn install <pkg>, which installs from package.json instead of adding a new dep. This breaks project boot-strapping for Yarn.
Suggested fix:
- runCommand(
- `${agent} install ${pkg.name} ${pkg.dev ? saveDev : ''}`,
- `Installing "${pkg.name}"`
- );
+ const cmd =
+ agent === 'yarn'
+ ? `yarn add ${pkg.name} ${pkg.dev ? '-D' : ''}`
+ : `${agent} install ${pkg.name} ${pkg.dev ? saveDev : ''}`;
+
+ runCommand(cmd, `Installing "${pkg.name}"`);The same helper is used for all managers, so this single change keeps behaviour consistent.
Also applies to: 78-82
🤖 Prompt for AI Agents
In packages/create-zenstack/src/index.ts around lines 54 to 55 and also 78 to
82, the code uses `yarn install <pkg>` to add packages, which is incorrect
because it installs from package.json instead of adding a new dependency. Update
the command generation logic in the `installPackage` helper to use `yarn add
<pkg>` for Yarn package manager instead of `yarn install <pkg>`. This change
should be applied consistently for all package managers to ensure proper project
boot-strapping.
| { name: '@zenstackhq/cli@next', dev: true }, | ||
| { name: '@zenstackhq/runtime@next', dev: false }, | ||
| ]; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Mirror the Yarn fix here to avoid install failure
Just like in create-zenstack, resolveCommand may map Yarn to yarn install, yielding the same issue. Consider post-processing the resolved command for Yarn to turn install ➜ add, or adjust package-manager-detector mapping if possible. This prevents silent init failures for Yarn projects.
Also applies to: 25-31
🤖 Prompt for AI Agents
In packages/cli/src/actions/init.ts around lines 15 to 17 and 25 to 31, the
resolved Yarn command may incorrectly use 'yarn install', causing silent
failures during initialization. To fix this, post-process the resolved command
for Yarn to replace 'install' with 'add', or update the package-manager-detector
mapping to ensure Yarn commands use 'yarn add' instead of 'yarn install'. This
change will align with the fix applied in create-zenstack and prevent install
failures.
| <a href="https://zenstack.dev"> | ||
| <picture> | ||
| <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo-dark.png"> | ||
| <img src="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo.png" height="128"> |
There was a problem hiding this comment.
Add alt text for logo image.
The <img> tag inside the <picture> element doesn’t include an alt attribute, which is required for accessibility.
- <img src="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo.png" height="128">
+ <img src="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo.png" alt="ZenStack logo" height="128">📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| <img src="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo.png" height="128"> | |
| <img src="https://raw.githubusercontent.com/zenstackhq/zenstack-docs/main/static/img/logo.png" alt="ZenStack logo" height="128"> |
🤖 Prompt for AI Agents
In README.md at line 5, the <img> tag for the logo image is missing an alt
attribute, which is necessary for accessibility. Add a descriptive alt attribute
to the <img> tag, such as alt="ZenStack logo", to provide alternative text for
screen readers.
Summary by CodeRabbit
Documentation
Chores