From 0021e0e0be574ec22c41dc2eeb81a2a646efef91 Mon Sep 17 00:00:00 2001
From: ymc9 <104139426+ymc9@users.noreply.github.com>
Date: Tue, 18 Nov 2025 20:31:00 -0800
Subject: [PATCH] doc: misc improvements
Fixes #513
---
.../version-3.x/_components/PackageDlx.tsx | 32 ++++++
.../version-3.x/orm/query-builder.md | 2 +-
versioned_docs/version-3.x/orm/quick-start.md | 7 +-
versioned_docs/version-3.x/reference/api.md | 105 +++++++++++++++++-
versioned_docs/version-3.x/reference/cli.md | 1 +
5 files changed, 141 insertions(+), 6 deletions(-)
create mode 100644 versioned_docs/version-3.x/_components/PackageDlx.tsx
diff --git a/versioned_docs/version-3.x/_components/PackageDlx.tsx b/versioned_docs/version-3.x/_components/PackageDlx.tsx
new file mode 100644
index 00000000..9474fce1
--- /dev/null
+++ b/versioned_docs/version-3.x/_components/PackageDlx.tsx
@@ -0,0 +1,32 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+ package: string;
+ script: string;
+ args: string;
+}
+
+const pkgManagers = [
+ { name: 'npm', command: 'npx' },
+ { name: 'pnpm', command: 'pnpm --package=%package dlx', addScript: true },
+ { name: 'bun', command: 'bunx' },
+ { name: 'yarn', command: 'npx' },
+];
+
+const PackageDlx = ({ package: pkg, script, args }: Props) => {
+ return (
+
+ {pkgManagers.map((pm) => (
+
+ {`${pm.command.replace('%package', pkg)}${
+ pm.command.includes('%package') ? '' : ` ${pkg}`
+ }${pm.addScript ? ` ${script}` : ''}${args ? ` ${args}` : ''}`}
+
+ ))}
+
+ );
+};
+
+export default PackageDlx;
diff --git a/versioned_docs/version-3.x/orm/query-builder.md b/versioned_docs/version-3.x/orm/query-builder.md
index 0d909d8a..3221a552 100644
--- a/versioned_docs/version-3.x/orm/query-builder.md
+++ b/versioned_docs/version-3.x/orm/query-builder.md
@@ -1,6 +1,6 @@
---
sidebar_position: 5
-description: Query builder API
+description: Query Builder API
---
import ZenStackVsPrisma from '../_components/ZenStackVsPrisma';
diff --git a/versioned_docs/version-3.x/orm/quick-start.md b/versioned_docs/version-3.x/orm/quick-start.md
index b399fa1a..9b853ad2 100644
--- a/versioned_docs/version-3.x/orm/quick-start.md
+++ b/versioned_docs/version-3.x/orm/quick-start.md
@@ -5,8 +5,9 @@ description: Quick start guide
import StackBlitzGithub from '@site/src/components/StackBlitzGithub';
import ZModelStarter from '../_components/_zmodel-starter.md';
-import PackageInstall from '../_components/PackageInstall.tsx';
-import PackageExec from '../_components/PackageExec.tsx';
+import PackageInstall from '../_components/PackageInstall';
+import PackageExec from '../_components/PackageExec';
+import PackageDlx from '../_components/PackageDlx';
# Quick Start
@@ -30,7 +31,7 @@ Or simply use the [interactive playground](https://stackblitz.com/~/github.com/z
To add ZenStack to an existing project, run the CLI `init` command to install dependencies and create a sample schema:
-
+
Then create a `zenstack/schema.zmodel` file in the root of your project. You can use the following sample schema to get started:
diff --git a/versioned_docs/version-3.x/reference/api.md b/versioned_docs/version-3.x/reference/api.md
index ef5b993a..94d5949c 100644
--- a/versioned_docs/version-3.x/reference/api.md
+++ b/versioned_docs/version-3.x/reference/api.md
@@ -8,7 +8,13 @@ sidebar_label: API
## `@zenstackhq/orm`
-### `class ZenStackClient`
+### `ClientContract`
+
+The interface for the ZenStack ORM client, implemented by [ZenStackClient](#zenstackclient).
+
+### `ZenStackClient`
+
+The class that implements the ORM client.
```ts
/**
@@ -45,4 +51,99 @@ export type ClientOptions = {
*/
computedFields: ComputedFieldsOptions;
};
-```
\ No newline at end of file
+```
+
+#### Query APIs
+
+Please refer to the [ORM Query API documentation](../orm/api/) for more details about query APIs like `findMany`, `create`, `update`, etc.
+
+#### `$connect()`
+
+```ts
+/**
+ * Eagerly connects to the database.
+ */
+$connect(): Promise;
+```
+
+#### `$disconnect()`
+
+```ts
+/**
+ * Explicitly disconnects from the database.
+ */
+$disconnect(): Promise;
+```
+
+#### `$setAuth()`
+
+```ts
+/**
+ * Sets the current user identity.
+ */
+$setAuth(auth: AuthType | undefined): ClientContract;
+```
+
+#### `$auth`
+
+```ts
+/**
+ * The current user identity.
+ */
+get $auth(): AuthType | undefined;
+```
+
+#### `$use()`
+
+Read more in the [Plugins documentation](../orm/plugins/).
+
+```ts
+/**
+ * Returns a new client with the specified plugin installed.
+ */
+$use(plugin: RuntimePlugin): ClientContract;
+```
+
+#### `$unuse()`
+
+Read more in the [Plugins documentation](../orm/plugins/).
+
+```ts
+/**
+ * Returns a new client with the specified plugin removed.
+ */
+$unuse(pluginId: string): ClientContract;
+```
+
+#### `$unuseAll()`
+
+Read more in the [Plugins documentation](../orm/plugins/).
+
+```ts
+/**
+ * Returns a new client with all plugins removed.
+ */
+$unuseAll(): ClientContract;
+```
+
+#### `$qb`
+
+Read more in the [Query Builder API documentation](../orm/query-builder).
+
+```ts
+/**
+ * The underlying Kysely query builder instance.
+ */
+readonly $qb: ToKysely;
+```
+
+#### `$qbRaw`
+
+Read more in the [Query Builder API documentation](../orm/query-builder).
+
+```ts
+/**
+ * The underlying raw Kysely query builder without any ZenStack enhancements.
+ */
+readonly $qbRaw: AnyKysely;
+```
diff --git a/versioned_docs/version-3.x/reference/cli.md b/versioned_docs/version-3.x/reference/cli.md
index 6c68a5e0..7f337483 100644
--- a/versioned_docs/version-3.x/reference/cli.md
+++ b/versioned_docs/version-3.x/reference/cli.md
@@ -26,6 +26,7 @@ Commands:
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.
+ format [options] Format a ZModel schema file.
help [command] display help for command
```