ZenStack V3

https://zenstack.dev/docs/
Admin
ZenStack is a data layer for modern TypeScript applications. Use this if the user's package.json has...
Tokens:192,968
Snippets:1,629
Trust Score:7.8
Update:14 hours ago
Show doc for...
Tokens:
Raw
### Initialize ZenStack in an existing project (pnpm)

Source: https://zenstack.dev/docs/quick-start

Run the CLI init command to install dependencies and create a sample schema.

```bash
pnpm --package=@zenstackhq/cli dlx zen init
```

--------------------------------

### Install ZenStack dependencies (bun)

Source: https://zenstack.dev/docs/quick-start

Install runtime dependencies and the CLI as a dev dependency.

```bash
bun add @zenstackhq/schema @zenstackhq/orm
bun add --dev @zenstackhq/cli
```

--------------------------------

### Install kysely-bun-sqlite with bun

Source: https://zenstack.dev/docs/recipe/databases/sqlite

Install the kysely-bun-sqlite community dialect for Bun's builtin sqlite module using bun.

```bash
bun add kysely-bun-sqlite
```

--------------------------------

### Initialize ZenStack in an existing project (npm)

Source: https://zenstack.dev/docs/quick-start

Run the CLI init command to install dependencies and create a sample schema.

```bash
npx @zenstackhq/cli init
```

--------------------------------

### Initialize ZenStack in an existing project (bun)

Source: https://zenstack.dev/docs/quick-start

Run the CLI init command to install dependencies and create a sample schema.

```bash
bunx @zenstackhq/cli init
```

--------------------------------

### Install kysely-bun-sqlite with npm

Source: https://zenstack.dev/docs/recipe/databases/sqlite

Install the kysely-bun-sqlite community dialect for Bun's builtin sqlite module using npm.

```bash
npm install kysely-bun-sqlite
```

--------------------------------

### Install @zenstackhq/fetch-client with bun

Source: https://zenstack.dev/docs/service/client-sdk/fetch-client

Install the fetch client package using bun.

```bash
bun add @zenstackhq/fetch-client
```

--------------------------------

### Install ZenStack dependencies (pnpm)

Source: https://zenstack.dev/docs/quick-start

Install runtime dependencies and the CLI as a dev dependency.

```bash
pnpm add @zenstackhq/schema @zenstackhq/orm
pnpm add --save-dev @zenstackhq/cli
```

--------------------------------

### Install kysely-bun-sqlite with pnpm

Source: https://zenstack.dev/docs/recipe/databases/sqlite

Install the kysely-bun-sqlite community dialect for Bun's builtin sqlite module using pnpm.

```bash
pnpm add kysely-bun-sqlite
```

--------------------------------

### Install ZenStack dependencies (yarn)

Source: https://zenstack.dev/docs/quick-start

Install runtime dependencies and the CLI as a dev dependency.

```bash
yarn add @zenstackhq/schema @zenstackhq/orm
yarn add --dev @zenstackhq/cli
```

--------------------------------

### Install kysely-bun-sqlite with yarn

Source: https://zenstack.dev/docs/recipe/databases/sqlite

Install the kysely-bun-sqlite community dialect for Bun's builtin sqlite module using yarn.

```bash
yarn add kysely-bun-sqlite
```

--------------------------------

### Install ZenStack dependencies (npm)

Source: https://zenstack.dev/docs/quick-start

Install runtime dependencies and the CLI as a dev dependency.

```bash
npm install @zenstackhq/schema @zenstackhq/orm
npm install --save-dev @zenstackhq/cli
```

--------------------------------

### Install @zenstackhq/tanstack-query with bun

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Install the package using bun.

```bash
bun add @zenstackhq/tanstack-query
```

--------------------------------

### Install @zenstackhq/tanstack-query with yarn

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Install the package using yarn.

```bash
yarn add @zenstackhq/tanstack-query
```

--------------------------------

### Install @zenstackhq/fetch-client with yarn

Source: https://zenstack.dev/docs/service/client-sdk/fetch-client

Install the fetch client package using yarn.

```bash
yarn add @zenstackhq/fetch-client
```

--------------------------------

### List posts example (GET /post)

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request to list posts. The response includes meta.total, data array, and pagination links.

```ts
GET /post
```

```json
{
    "meta": {
        "total": 1
    },
    "data": [
        {
            "attributes": {
                "authorId": 1,
                "published": true,
                "title": "My Awesome Post",
                "viewCount": 0
            },
            "id": 1,
            "links": {
                "self": "http://myhost/api/post/1"
            },
            "relationships": {
                "author": {
                    "data": { "id": 1, "type": "user" },
                    "links": {
                        "related": "http://myhost/api/post/1/author/1",
                        "self": "http://myhost/api/post/1/relationships/author/1"
                    }
                }
            },
            "type": "post"
        }
    ],
    "jsonapi": {
        "version": "1.1"
    },
    "links": {
        "first": "http://myhost/api/post?page%5Blimit%5D=100",
        "last": "http://myhost/api/post?page%5Boffset%5D=0",
        "next": null,
        "prev": null,
        "self": "http://myhost/api/post"
    }
}
```

--------------------------------

### Install @zenstackhq/fetch-client with npm

Source: https://zenstack.dev/docs/service/client-sdk/fetch-client

Install the fetch client package using npm.

```bash
npm install @zenstackhq/fetch-client
```

--------------------------------

### GET custom procedure example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example of calling a query procedure with URL-encoded arguments.

```ts
// for arguments `{"userId":1,"limit":10}`
GET /$procs/getUserFeeds?args=%7B%22userId%22%3A1%2C%22limit%22%3A10%7D
```

--------------------------------

### Install @zenstackhq/tanstack-query with npm

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Install the package using npm.

```bash
npm install @zenstackhq/tanstack-query
```

--------------------------------

### Install @zenstackhq/tanstack-query with pnpm

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Install the package using pnpm.

```bash
pnpm add @zenstackhq/tanstack-query
```

--------------------------------

### Install @zenstackhq/server with bun

Source: https://zenstack.dev/docs/reference/server-adapters/express

Install the ZenStack server package using bun.

```bash
bun add @zenstackhq/server
```

--------------------------------

### Fetch post example (GET /post/1)

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request to fetch a single post. The response includes the resource data and self link.

```ts
GET /post/1
```

```json
{
    "data": {
        "attributes": {
            "authorId": 1,
            "published": true,
            "title": "My Awesome Post",
            "viewCount": 0
        },
        "id": 1,
        "links": {
            "self": "http://myhost/api/post/1"
        },
        "relationships": {
            "author": {
                "data": { "id": 1, "type": "user" },
                "links": {
                    "related": "http://myhost/api/post/1/author/1",
                    "self": "http://myhost/api/post/1/relationships/author/1"
                }
            }
        },
        "type": "post"
    },
    "jsonapi": {
        "version": "1.1"
    },
    "links": {
        "self": "http://myhost/api/post/1"
    }
}
```

--------------------------------

### Install @zenstackhq/server with yarn

Source: https://zenstack.dev/docs/reference/server-adapters/express

Install the ZenStack server package using yarn.

```bash
yarn add @zenstackhq/server
```

--------------------------------

### Install @zenstackhq/fetch-client with pnpm

Source: https://zenstack.dev/docs/service/client-sdk/fetch-client

Install the fetch client package using pnpm.

```bash
pnpm add @zenstackhq/fetch-client
```

--------------------------------

### Install @zenstackhq/server with npm

Source: https://zenstack.dev/docs/reference/server-adapters/express

Install the ZenStack server package using npm.

```bash
npm install @zenstackhq/server
```

--------------------------------

### Install @zenstackhq/server with pnpm

Source: https://zenstack.dev/docs/reference/server-adapters/express

Install the ZenStack server package using pnpm.

```bash
pnpm add @zenstackhq/server
```

--------------------------------

### TypeScript example using PolicyPlugin and auth

Source: https://zenstack.dev/docs/orm/access-control/query

Demonstrates using the PolicyPlugin to enforce access control. Creates users and posts, installs the plugin, sets auth context, and queries posts as different users to show filtered results.

```typescript
import { PolicyPlugin } from '@zenstackhq/plugin-policy';
import { createClient } from '../db';
import { schema } from './zenstack/schema';

async function main() {
  const db = await createClient(schema);

  // create users and posts with raw client
  const alice = await db.user.create({
    data: {
      email: 'alice@example.com',
      posts: {
        create: [
          { title: 'Alice Draft Post', published: false },
          { title: 'Alice Published Post', published: true }
        ]
      }
    }
  });

  const bob = await db.user.create({
    data: {
      email: 'bob@example.com',
      posts: {
        create: [{ title: 'Bob Draft Post', published: false }]
      }
    }
  });

  // install policy plugin
  const authDb = db.$use(new PolicyPlugin());

  // create user-bound clients
  const aliceDb = authDb.$setAuth(alice);
  const bobDb = authDb.$setAuth(bob);

  // query posts as Alice
  console.log('Alice sees posts:');
  console.table(
    await aliceDb.post.findMany({
      select: { title: true, published: true }
    })
  );

  // query posts as Bob
  console.log('Bob sees posts:');
  console.table(
    await bobDb.post.findMany({
      select: { title: true, published: true }
    })
  );
}

main();
```

--------------------------------

### Preview ZenStack skills before installing

Source: https://zenstack.dev/docs/recipe/ai-agents

Run this command to preview what's included in the skills collection before installing.

```bash
npx skills add zenstackhq/skills --list
```

--------------------------------

### zen info command help

Source: https://zenstack.dev/docs/reference/cli

Shows the usage and options for 'zen info', which gets information of installed ZenStack packages. Accepts an optional project path argument.

```bash
Usage: zen info [options] [path]

Get information of installed ZenStack.

Arguments:
  path        project path (default: ".")

Options:
  -h, --help  display help for command
```

--------------------------------

### Install @neondatabase/serverless with bun

Source: https://zenstack.dev/docs/recipe/databases/neon

Install the Neon serverless driver using bun.

```bash
bun add @neondatabase/serverless
```

--------------------------------

### Install @zenstackhq/better-auth with bun

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the ZenStack better-auth database adapter using bun.

```bash
bun add @zenstackhq/better-auth
```

--------------------------------

### Create ZenStackClient with MySQL dialect

Source: https://zenstack.dev/docs/recipe/databases/mysql

Instantiate ZenStackClient with a MySQL connection pool. Requires a DATABASE_URL environment variable and the mysql2 driver installed.

```ts
import { schema } from './zenstack/schema';
import { createPool } from 'mysql2';
import { ZenStackClient } from '@zenstackhq/orm';
import { MysqlDialect } from '@zenstackhq/orm/dialects/mysql';

const db = new ZenStackClient(schema, {
  dialect: new MysqlDialect({
    pool: createPool(process.env.DATABASE_URL),
  }),
});
```

--------------------------------

### Install PostgreSQL driver with bun

Source: https://zenstack.dev/docs/migrate-prisma

Install the PostgreSQL database driver and its type definitions using bun. ZenStack does not bundle database drivers.

```bash
bun add pg
bun add --dev @types/pg
```

--------------------------------

### Install MySQL driver with bun

Source: https://zenstack.dev/docs/migrate-prisma

Install the MySQL database driver using bun. ZenStack does not bundle database drivers.

```bash
bun add mysql2
```

--------------------------------

### Install @neondatabase/serverless with pnpm

Source: https://zenstack.dev/docs/recipe/databases/neon

Install the Neon serverless driver using pnpm.

```bash
pnpm add @neondatabase/serverless
```

--------------------------------

### Install SQLite driver with bun

Source: https://zenstack.dev/docs/migrate-prisma

Install the SQLite database driver and its type definitions using bun. ZenStack does not bundle database drivers.

```bash
bun add better-sqlite3
bun add --dev @types/better-sqlite3
```

--------------------------------

### Install @neondatabase/serverless with npm

Source: https://zenstack.dev/docs/recipe/databases/neon

Install the Neon serverless driver using npm.

```bash
npm install @neondatabase/serverless
```

--------------------------------

### Install @neondatabase/serverless with yarn

Source: https://zenstack.dev/docs/recipe/databases/neon

Install the Neon serverless driver using yarn.

```bash
yarn add @neondatabase/serverless
```

--------------------------------

### Install @zenstackhq/better-auth with yarn

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the ZenStack better-auth database adapter using yarn.

```bash
yarn add @zenstackhq/better-auth
```

--------------------------------

### Install @better-auth/cli with bun

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the better-auth CLI as a dev dependency using bun.

```bash
bun add --dev @better-auth/cli
```

--------------------------------

### Install SQLite driver with pnpm

Source: https://zenstack.dev/docs/migrate-prisma

Install the SQLite database driver and its type definitions using pnpm. ZenStack does not bundle database drivers.

```bash
pnpm add better-sqlite3
pnpm add --save-dev @types/better-sqlite3
```

--------------------------------

### Install MySQL driver with pnpm

Source: https://zenstack.dev/docs/migrate-prisma

Install the MySQL database driver using pnpm. ZenStack does not bundle database drivers.

```bash
pnpm add mysql2
```

--------------------------------

### Creating a resource example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request body for creating a resource. The `data` object must include `type` and `attributes`.

```json
POST /user
{
    "data": {
        "type": "user",
        "attributes": {
            "name": "Emily",
            "email": "emily@zenstack.dev"
        }
    }
}
```

--------------------------------

### Install PostgreSQL driver with npm

Source: https://zenstack.dev/docs/migrate-prisma

Install the PostgreSQL database driver and its type definitions using npm. ZenStack does not bundle database drivers.

```bash
npm install pg
npm install --save-dev @types/pg
```

--------------------------------

### Install @zenstackhq/better-auth with pnpm

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the ZenStack better-auth database adapter using pnpm.

```bash
pnpm add @zenstackhq/better-auth
```

--------------------------------

### Install SQLite driver with npm

Source: https://zenstack.dev/docs/migrate-prisma

Install the SQLite database driver and its type definitions using npm. ZenStack does not bundle database drivers.

```bash
npm install better-sqlite3
npm install --save-dev @types/better-sqlite3
```

--------------------------------

### Install MySQL driver with npm

Source: https://zenstack.dev/docs/migrate-prisma

Install the MySQL database driver using npm. ZenStack does not bundle database drivers.

```bash
npm install mysql2
```

--------------------------------

### Install @zenstackhq/better-auth with npm

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the ZenStack better-auth database adapter using npm.

```bash
npm install @zenstackhq/better-auth
```

--------------------------------

### Install @zenstackhq/plugin-soft-delete

Source: https://zenstack.dev/docs/reference/plugins/soft-delete

Install the soft-delete plugin package via npm.

```bash
npm install @zenstackhq/plugin-soft-delete
```

--------------------------------

### Install @better-auth/cli with pnpm

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the better-auth CLI as a dev dependency using pnpm.

```bash
pnpm add --save-dev @better-auth/cli
```

--------------------------------

### Install PostgreSQL driver with pnpm

Source: https://zenstack.dev/docs/migrate-prisma

Install the PostgreSQL database driver and its type definitions using pnpm. ZenStack does not bundle database drivers.

```bash
pnpm add pg
pnpm add --save-dev @types/pg
```

--------------------------------

### Install MySQL driver with yarn

Source: https://zenstack.dev/docs/migrate-prisma

Install the MySQL database driver using yarn. ZenStack does not bundle database drivers.

```bash
yarn add mysql2
```

--------------------------------

### Install @better-auth/cli with npm

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the better-auth CLI as a dev dependency using npm.

```bash
npm install --save-dev @better-auth/cli
```

--------------------------------

### Install PostgreSQL driver with yarn

Source: https://zenstack.dev/docs/migrate-prisma

Install the PostgreSQL database driver and its type definitions using yarn. ZenStack does not bundle database drivers.

```bash
yarn add pg
yarn add --dev @types/pg
```

--------------------------------

### Install @better-auth/cli with yarn

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Install the better-auth CLI as a dev dependency using yarn.

```bash
yarn add --dev @better-auth/cli
```

--------------------------------

### zen init command help

Source: https://zenstack.dev/docs/reference/cli

Shows the usage and options for 'zen init', which initializes an existing project for ZenStack. Accepts an optional project path argument.

```bash
Usage: zen init [options] [path]

Initialize an existing project for ZenStack.

Arguments:
  path        project path (default: ".")

Options:
  -h, --help  display help for command
```

--------------------------------

### Install SQLite driver with yarn

Source: https://zenstack.dev/docs/migrate-prisma

Install the SQLite database driver and its type definitions using yarn. ZenStack does not bundle database drivers.

```bash
yarn add better-sqlite3
yarn add --dev @types/better-sqlite3
```

--------------------------------

### Install @zenstackhq/sdk with bun

Source: https://zenstack.dev/docs/recipe/plugin-dev

Install the SDK package as a dev dependency using bun.

```bash
bun add --dev @zenstackhq/sdk
```

--------------------------------

### POST custom procedure example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example of calling a mutation procedure with arguments in the request body.

```ts
POST /$procs/signUp
{
    "args": {
        "email": "alice@zenstack.dev"
    }
}
```

--------------------------------

### Scaffold a new project with npm create zenstack

Source: https://zenstack.dev/docs/quick-start

Run this command to scaffold a new project with a pre-configured minimal starter.

```bash
npm create zenstack my-project
```

--------------------------------

### Install @zenstackhq/plugin-policy with bun

Source: https://zenstack.dev/docs/migrate-v2

Install the access control plugin package using bun.

```bash
bun add @zenstackhq/plugin-policy
```

--------------------------------

### Install @zenstackhq/zod with bun

Source: https://zenstack.dev/docs/utilities/zod

Install the package and Zod 4.0 or above using bun.

```bash
bun add @zenstackhq/zod zod
```

--------------------------------

### Start ZenStack Studio with npx

Source: https://zenstack.dev/docs/studio

Run this command in your project to turn your database into a studio and MCP server. Requires an existing PostgreSQL, MySQL, or SQLite database.

```bash
npx @zenstackhq/cli studio
```

--------------------------------

### Install @zenstackhq/sdk with pnpm

Source: https://zenstack.dev/docs/recipe/plugin-dev

Install the SDK package as a dev dependency using pnpm.

```bash
pnpm add --save-dev @zenstackhq/sdk
```

--------------------------------

### Install ZenStack skills globally

Source: https://zenstack.dev/docs/recipe/ai-agents

Use the -g flag to install the skills globally so they are available across all your projects.

```bash
npx skills add zenstackhq/skills --all -g
```

--------------------------------

### Install @zenstackhq/sdk with npm

Source: https://zenstack.dev/docs/recipe/plugin-dev

Install the SDK package as a dev dependency using npm.

```bash
npm install --save-dev @zenstackhq/sdk
```

--------------------------------

### Install @zenstackhq/sdk with yarn

Source: https://zenstack.dev/docs/recipe/plugin-dev

Install the SDK package as a dev dependency using yarn.

```bash
yarn add --dev @zenstackhq/sdk
```

--------------------------------

### Install all ZenStack skills with skills.sh

Source: https://zenstack.dev/docs/recipe/ai-agents

Run this command in your project's root directory to install every ZenStack skill at once. The CLI auto-detects installed coding agents (Claude Code, Cursor, Copilot, etc.) and sets up the skills for each.

```bash
npx skills add zenstackhq/skills --all
```

--------------------------------

### Install @zenstackhq/zod with pnpm

Source: https://zenstack.dev/docs/utilities/zod

Install the package and Zod 4.0 or above using pnpm.

```bash
pnpm add @zenstackhq/zod zod
```

--------------------------------

### $setOptions method with example

Source: https://zenstack.dev/docs/reference/api

Returns a new client with new options applied. The example shows disabling input validation.

```typescript
/**
 * Returns a new client with new options applied.
 * @example
 * ```
 * const dbNoValidation = db.$setOptions({ ...db.$options, validateInput: false });
 * ```
 */
$setOptions<Options extends ClientOptions<Schema>>(options: Options): ClientContract<Schema, Options>;
```

--------------------------------

### Install @zenstackhq/plugin-policy with yarn

Source: https://zenstack.dev/docs/migrate-v2

Install the access control plugin package using yarn.

```bash
yarn add @zenstackhq/plugin-policy
```

--------------------------------

### Install @zenstackhq/plugin-policy with pnpm

Source: https://zenstack.dev/docs/migrate-v2

Install the access control plugin package using pnpm.

```bash
pnpm add @zenstackhq/plugin-policy
```

--------------------------------

### Install new packages (bun)

Source: https://zenstack.dev/docs/migrate-v2

Installs the v3 schema and ORM packages, plus the CLI as a dev dependency.

```bash
bun add @zenstackhq/schema @zenstackhq/orm
bun add --save-dev @zenstackhq/cli
```

--------------------------------

### GET /api/openapi.json (Express example)

Source: https://zenstack.dev/docs/service/openapi/restful

Example of serving the generated OpenAPI spec as a JSON endpoint using Express. This endpoint allows tools like Swagger UI to access the spec at a known URL.

```APIDOC
## GET /api/openapi.json

### Description
Serves the generated OpenAPI specification as a JSON endpoint. This is a common pattern to expose the spec alongside the API for tools like Swagger UI.

### Method
GET

### Endpoint
`/api/openapi.json`

### Response
Returns the OpenAPI specification as a JSON object.

### Request Example
```ts
import express from 'express';
import { schema } from '~/zenstack/schema';
import { RestApiHandler } from '@zenstackhq/server/api';

const app = express();
const handler = new RestApiHandler({ schema, endpoint: 'http://localhost:3000/api' });

// Serve the OpenAPI spec
app.get('/api/openapi.json', async (_req, res) => {
    const spec = await handler.generateSpec({
        title: 'My API',
        respectAccessPolicies: true,
    });
    res.json(spec);
});
```
```

--------------------------------

### Creating a related resource example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request body for creating a resource under a parent resource. The `data` object must include `type` and `attributes`.

```json
POST /user/1/posts
{
    "data": {
        "type": "post",
        "attributes": {
            "title": "My Awesome Post",
            "published": true
        }
    }
}
```

--------------------------------

### Install PGlite and Kysely with bun

Source: https://zenstack.dev/docs/recipe/databases/postgres

Install the PGlite and Kysely packages using bun. Note: PGlite is not officially supported by ZenStack.

```bash
bun add @electric-sql/pglite kysely
```

--------------------------------

### Install @zenstackhq/plugin-policy with npm

Source: https://zenstack.dev/docs/migrate-v2

Install the access control plugin package using npm.

```bash
npm install @zenstackhq/plugin-policy
```

--------------------------------

### Example Query Key for useFindUniqueUser

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Shows the query key generated for a useFindUniqueUser call with a where filter.

```ts
useFindUniqueUser({ where: { id: '1' } })
```

```ts
['zenstack', 'User', 'findUnique', { where: { id: '1' } }, { infinite: false }]
```

--------------------------------

### Create user-bound ORM client with $setAuth

Source: https://zenstack.dev/docs/recipe/auth-integration/better-auth

Pass the userId to ZenStackClient's $setAuth() method to get a user-bound ORM client with access policy plugin installed.

```tsx
// ZenStack ORM client with access policy plugin installed
import { authDb } from './db'; 

const userDb = authDb.$setAuth({ userId });
```

--------------------------------

### Fetch related resource example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request and response for fetching a related resource. The response includes the related resource's attributes, relationships, and links.

```ts
GET /post/1/author
```

```json
{
   "data" : {
      "attributes" : {
         "email" : "emily@zenstack.dev",
         "name" : "Emily"
      },
      "id" : 1,
      "links" : {
         "self" : "http://myhost/api/user/1"
      },
      "relationships" : {
         "posts" : {
            "links" : {
               "related" : "http://myhost/api/user/1/posts",
               "self" : "http://myhost/api/user/1/relationships/posts"
            }
         }
      },
      "type" : "user"
   },
   "jsonapi" : {
      "version" : "1.1"
   },
   "links" : {
      "self" : "http://myhost/api/post/1/author"
   }
}
```

--------------------------------

### Install PGlite and Kysely with npm

Source: https://zenstack.dev/docs/recipe/databases/postgres

Install the PGlite and Kysely packages using npm. Note: PGlite is not officially supported by ZenStack.

```bash
npm install @electric-sql/pglite kysely
```

--------------------------------

### Install new packages (yarn)

Source: https://zenstack.dev/docs/migrate-v2

Installs the v3 schema and ORM packages, plus the CLI as a dev dependency.

```bash
yarn add @zenstackhq/schema @zenstackhq/orm
yarn add --save-dev @zenstackhq/cli
```

--------------------------------

### Response wrapped in data field

Source: https://zenstack.dev/docs/service/api-handler/rpc

The output shape conforms to the data structure returned by the corresponding ZenStackClient API, wrapped into a `data` field. The example shows a GET response with a list of posts.

```json
GET /api/post/findMany

{
    "data": [ { "id": 1, "title": "Hello World" } ]
}
```

--------------------------------

### $use() method

Source: https://zenstack.dev/docs/reference/api

Returns a new client with the specified plugin installed.

```typescript
/**
 * Returns a new client with the specified plugin installed.
 */
$use(plugin: RuntimePlugin<Schema>): ClientContract<Schema>;
```

--------------------------------

### POST to-many relationship example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request body for adding posts to a user's posts relationship.

```json
POST /user/1/relationships/posts
{
    "data": [
        { "type": "post", "id": "1" },
        { "type": "post", "id": "2" }
    ]
}
```

--------------------------------

### GET/DELETE query parameter serialization

Source: https://zenstack.dev/docs/service/api-handler/rpc

For GET and DELETE endpoints, the query body is serialized and passed as the `q` query parameter. The example shows a URL-encoded JSON query for filtering posts by `public: true`.

```http
GET /api/post/findMany?q=%7B%22where%22%3A%7B%22public%22%3Atrue%7D%7D
```

--------------------------------

### Fetch to-one relationship example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request and response for fetching a to-one relationship. The response includes the related resource data, JSON:API version, and links.

```ts
GET /post/1/relationships/author
```

```json
{
    "data" : { "id" : 1, "type" : "user" },
    "jsonapi" : {
        "version" : "1.1"
    },
    "links" : {
        "self" : "http://myhost/api/post/1/relationships/author"
    }
}
```

--------------------------------

### Fetch to-many relationship example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request and response for fetching a to-many relationship. The response includes an array of related resources, JSON:API version, and pagination links.

```ts
GET /user/1/relationships/posts
```

```json
{
    "data" : [
        { "id" : 1, "type" : "post" },
        { "id" : 2, "type" : "post" }
    ],
    "jsonapi" : {
        "version" : "1.1"
    },
    "links" : {
        "first" : "http://myhost/api/user/1/relationships/posts?page%5Blimit%5D=100",
        "last" : "http://myhost/api/user/1/relationships/posts?page%5Boffset%5D=0",
        "next" : null,
        "prev" : null,
        "self" : "http://myhost/api/user/1/relationships/posts"
    }
}
```

--------------------------------

### Response body with meta field

Source: https://zenstack.dev/docs/service/api-handler/rpc

The `meta` object from superjson-serialization of the response body is included as an additional field `meta` in the response body. The example shows a GET response with a `Bytes` field and the corresponding `meta`. Use the `meta.serialization` field value to superjson-deserialize the response body.

```json
GET /api/post/findFirst

{ 
    "data": { "id": 1, "bytes": "AQID" },
    "meta": { "serialization": {"values": { "bytes": [[ "custom","Bytes"]] } } } 
}
```

--------------------------------

### Sample main.ts using custom procedures

Source: https://zenstack.dev/docs/orm/custom-proc

Imports createClient from './db', creates a client, and calls the 'signUp' and 'getUserFeeds' procedures, logging the results.

```typescript
import { createClient } from './db';

async function main() {
  const db = await createClient();

  const user = await db.$procs.signUp({ args: { email: 'alice@zenstack.dev' } });
  console.log('Created user with "signUp" proc:', user);

  const feed = await db.$procs.getUserFeeds({ args: { userId: user.id } });
  console.log('Feeds from "getUserFeeds" proc:', feed);
}

main();
```

--------------------------------

### Field-level policy usage example (main.ts)

Source: https://zenstack.dev/docs/orm/access-control/field-level

Demonstrates using the PolicyPlugin to enforce field-level policies. Creates users and posts, installs the policy plugin, and creates user-bound clients. Shows that Bob cannot update a post title he doesn't own (throws error), while Alice can update her own post title.

```typescript
import { PolicyPlugin } from '@zenstackhq/plugin-policy';
import { createClient } from '../db';
import { schema } from './zenstack/schema';

async function main() {
  const db = await createClient(schema);

  // create users and posts with raw client
  const alice = await db.user.create({
    data: {
      email: 'alice@example.com',
      posts: {
        create: [
          { id: 1, title: 'Alice Published Post', published: true },
          { id: 2, title: 'Alice Draft Post', published: false }
        ]
      }
    }
  });

  const bob = await db.user.create({
    data: {
      email: 'bob@example.com'
    }
  });

  // install policy plugin
  const authDb = db.$use(new PolicyPlugin());

  // create user-bound clients
  const aliceDb = authDb.$setAuth(alice);
  const bobDb = authDb.$setAuth(bob);

  // query posts as Alice, only published posts' titles are visible
  console.log('Alice sees posts:');
  console.table(await aliceDb.post.findMany());

  // updating title with Bob should fail
  try {
    await bobDb.post.update({
      where: { id: 1 },
      data: { title: 'Hacked Title' }
    });
  } catch (err) {
    console.log(`Bob failed to update post title as expected, ${err}`);
  }

  // updating title with Alice should succeed
  const updated = await aliceDb.post.update({
    where: { id: 1 },
    data: { title: 'Alice Updated Post' }
  });
  console.log('Alice successfully updated her post title.');
  console.table(updated);
}

main();

```

--------------------------------

### View example: UserInfo

Source: https://zenstack.dev/docs/reference/zmodel/view

Example of a view named UserInfo with three fields: id (Int), email (String), and name (String).

```zmodel
view UserInfo {
    id    Int
    email String
    name  String
}
```

--------------------------------

### Fetch specific related resource example

Source: https://zenstack.dev/docs/service/api-handler/rest

Example request for fetching a specific related resource from a to-many relation.

```ts
GET /user/1/posts/1
```

--------------------------------

### Entity Mutation Hooks Plugin Example (plugins/entity-mutation-hooks.ts)

Source: https://zenstack.dev/docs/orm/plugins/entity-mutation-hooks

Demonstrates using definePlugin from @zenstackhq/orm to intercept all mutations and Post update mutations. The first plugin logs before/after mutations for all models without loading entities. The second plugin loads before/after entities for Post updates, with typed entities when passing the schema. Requires a database client and schema setup.

```typescript
import { definePlugin } from '@zenstackhq/orm';
import { createClient } from '../db';
import { schema } from '../zenstack/schema';
import { createUsersAndPosts } from '../utils';

async function main() {
  const db = await createClient();

  // intercept all mutations, without loading entities
  const db1 = db.$use(
    definePlugin({
      id: 'plugin1',
      onEntityMutation: {
        $all: {
          beforeEntityMutation: ({ model, action }) => {
            console.log('[plugin1] Before mutation:', model, action);
          },

          afterEntityMutation: ({ model, action }) => {
            console.log('[plugin1] After mutation:', model, action);
          }
        }
      }
    })
  );

  await createUsersAndPosts(db1);

  // only intercept Post's update mutation, loading before and after entities
  // (passing the schema to `definePlugin` makes the loaded entities typed)
  const plugin2 = definePlugin(schema, {
    id: 'plugin2',
    onEntityMutation: {
      Post: {
        async beforeEntityMutation({ action, loadBeforeMutationEntities }) {
          if (action === 'update') {
            // entities are typed as `Post` rows
            const entities = await loadBeforeMutationEntities();
            console.log('[plugin2] Before mutation:', action, entities);
          }
        },

        async afterEntityMutation({ action, loadAfterMutationEntities }) {
          if (action === 'update') {
            const entities = await loadAfterMutationEntities();
            console.log('[plugin2] After mutation:', action, entities);
          }
        }
      }
    }
  });
  const db2 = db.$use(plugin2);

  const post = await db2.post.create({ data: { title: 'New Post' } });
  await db2.post.update({ where: { id: post.id }, data: { viewCount: 1 } });
}

main();
```

--------------------------------

### V3 type and with example

Source: https://zenstack.dev/docs/migrate-v2

V3 replaces abstract model with type and extends with with.

```zmodel
type Timestamped {
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post with Timestamped {
  id Int @id @default(autoincrement())
  title String
}
```

--------------------------------

### Svelte: useInfiniteFindMany for infinite pagination

Source: https://zenstack.dev/docs/service/client-sdk/tanstack-query

Use the infinite variant of useFindMany to build paginated or infinitely scrolling UIs. This example loads posts with author included, ordered by creation date, and fetches the next page when the button is clicked. Requires a schema and the @zenstackhq/tanstack-query/svelte package.

```svelte
<script lang="ts">
  // post list component with infinite loading

  import { useClientQueries } from '@zenstackhq/tanstack-query/svelte';

  const client = useClientQueries(schema);

  const PAGE_SIZE = 10;

  const fetchArgs = {
    include: { author: true },
    orderBy: { createdAt: 'desc' as const },
    take: PAGE_SIZE,
  };

  const query = client.post.useInfiniteFindMany(
    () => fetchArgs,
    () => ({
      getNextPageParam: (lastPage, pages) => {
        if (lastPage.length < PAGE_SIZE) {
          return undefined;
        }
        const fetched = pages.flatMap((item) => item).length;
        return {
          ...fetchArgs,
          skip: fetched,
        };
      }})
    );    
</script>

<div>
  <ul>
    <div>
      {#if query.data}
        {#each query.data.pages as posts, i (i)}
          {#each posts as post (post.id)}
            <li>{post.title} by {post.author.email}</li>
          {/each}
        {/each}
      {/if}
    </div>
  </ul>
  {#if query.hasNextPage}
    <button on:click={() => query.fetchNextPage()}>
      Load more
    </button>
  {/if}
</div>
```

--------------------------------

### Install the plugin at runtime

Source: https://zenstack.dev/docs/migrate-v2

Create an ORM client with and without access control. Use the PolicyPlugin to enable access control.

```ts
import { PolicyPlugin } from '@zenstackhq/plugin-policy';

// ORM client without access control
export const db = new ZenStackClient({ ... });

// ORM client with access control
export const authDb = db.$use(new PolicyPlugin());
```

--------------------------------

### Sample ZenStack schema (zenstack/schema.zmodel)

Source: https://zenstack.dev/docs/quick-start

A minimal schema with User and Post models, using SQLite. Create this file in the root of your project.

```zmodel
datasource db {
    provider = 'sqlite'
    url = 'file:./dev.db'
}

model User {
    id       String @id @default(cuid())
    email    String @unique
    posts    Post[]
}

model Post {
    id        String   @id @default(cuid())
    createdAt DateTime @default(now())
    updatedAt DateTime @updatedAt
    title     String
    content   String
    published Boolean  @default(false)
    author    User     @relation(fields: [authorId], references: [id])
    authorId  String
}
```

--------------------------------

### Create ZenStackClient with SQLite for Bun

Source: https://zenstack.dev/docs/recipe/databases/sqlite

Create a ZenStackClient instance using Bun's builtin sqlite module and the BunSqliteDialect from kysely-bun-sqlite. The database file is './dev.db'.

```ts
import { schema } from './zenstack/schema';
import { Database } from 'bun:sqlite';
import { ZenStackClient } from '@zenstackhq/orm';
import { BunSqliteDialect } from 'kysely-bun-sqlite';

const db = new ZenStackClient(schema, {
    dialect: new BunSqliteDialect({ database: new Database('./dev.db') }),
});
```

--------------------------------

### Install @zenstackhq/zod with yarn

Source: https://zenstack.dev/docs/utilities/zod

Install the package and Zod 4.0 or above using yarn.

```bash
yarn add @zenstackhq/zod zod
```

--------------------------------

### Initialize ZenStack project with bun

Source: https://zenstack.dev/docs/orm/introspection

Initializes a new ZenStack project using bun. Run this first when starting from an existing database.

```bash
bunx zen init
```

--------------------------------

### ZenStack CLI usage and commands

Source: https://zenstack.dev/docs/reference/cli

Shows the top-level CLI help output listing global options and available commands: generate, migrate, db, info, init, check, format.

```text
zen [options] [command]

ζ ZenStack is the modern data layer for TypeScript apps.

Documentation: https://zenstack.dev/docs

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.
  format [options]    Format a ZModel schema file.
  help [command]      display help for command
```

--------------------------------

### Create API sample (create.ts)

Source: https://zenstack.dev/docs/orm/api/create

Demonstrates the `create`, `createMany`, and `createManyAndReturn` methods. Shows nested creates with `include`, `select`, `connect`, and `skipDuplicates`. Requires a `db` client from `./db`.

```typescript
import { createClient } from './db';

async function main() {
  const db = await createClient();

  // create a user with some posts
  const user1 = await db.user.create({
    data: {
      email: 'u1@test.com',
      posts: {
        create: [
          {
            title: 'Post1',
            content: 'My first post',
            published: false
          },
          {
            title: 'Post2',
            content: 'Just another post',
            published: true
          }
        ]
      }
    },
    // the `include` clause includes the relation in the
    // create result
    include: { posts: true }
  });

  // the created user together with the posts relation are returned
  console.log('User', user1.email, 'is created with posts', user1.posts);

  // you can also use the "select" clause to pick specific fields to return
  const user2 = await db.user.create({
    data: { email: 'u2@test.com' },
    select: { id: true }
  });
  // only "id" field is available
  console.log('New user created with id:', user2.id);

  // instead of creating nested relations, you can also use
  // the `connect` clause to connect to existing entities
  const newPost = await db.post.create({ data: { title: 'Post3', content: '' } });
  const user3 = await db.user.create({
    data: {
      email: 'u3@test.com',
      posts: { connect: { id: newPost.id } }
    },
    include: { posts: true }
  });
  console.log(
    `User#${user3.id} is connected to posts:`,
    user3.posts.map((p) => p.id)
  );

  // `createMany` allows you to batch create entities
  const result = await db.user.createMany({
    data: [{ email: 'u4@test.com' }, { email: 'u5@test.com' }]
  });
  // only the number of entites created will be returned
  console.log('Number of users created:', result.count);

  // `createManyAndReturn` is similar except that it returns
  // the created entities
  const newUsers = await db.user.createManyAndReturn({
    data: [{ email: 'u6@test.com' }, { email: 'u7@test.com' }]
  });
  console.log('Some more users created:', newUsers);

  // use the `skipDuplicates` flag to ignore items that violate
  // unique constraints
  const moreUsers = await db.user.createManyAndReturn({
    data: [{ email: 'u7@test.com' }, { email: 'u8@test.com' }],
    skipDuplicates: true
  });
  console.log('More users created:', moreUsers);
}

main();
```

--------------------------------

### Install @zenstackhq/zod with npm

Source: https://zenstack.dev/docs/utilities/zod

Install the package and Zod 4.0 or above using npm.

```bash
npm install @zenstackhq/zod zod
```

--------------------------------

### zen proxy command usage and options

Source: https://zenstack.dev/docs/reference/cli

Shows the usage and options for the `zen proxy` command, which starts the ZenStack proxy server. The command is also aliased as `studio`. Options include `--schema`, `-p, --port` (default 2311), `-o, --output`, `-d, --databaseUrl`, `-l, --logLevel`, `--introspect`, `--no-version-check`, and `-h, --help`.

```bash
Usage: zen proxy [options]

Options:
  --schema <file>            schema file (with extension .zmodel). Defaults to "zenstack/schema.zmodel" unless specified in package.json.
  -p, --port <port>          port to run the proxy server on (default: 2311)
  -o, --output <path>        output directory for `zen generate` command
  -d, --databaseUrl <url>    database connection URL
  -l, --logLevel <level...>  Query log levels (e.g., query, error)
  --introspect               introspect the database to generate a schema when no schema file is found
  --no-version-check         do not check for new version
  -h, --help                 Show this help message
```

--------------------------------

### Generate TypeScript from schema (bun)

Source: https://zenstack.dev/docs/quick-start

Run zen generate to compile the schema into TypeScript. Optionally run zen db push to push the schema to the database.

```bash
bunx zen generate
```

--------------------------------

### Initialize ZenStack project with npm

Source: https://zenstack.dev/docs/orm/introspection

Initializes a new ZenStack project using npm. Run this first when starting from an existing database.

```bash
npx zen init
```

--------------------------------

### Function application example

Source: https://zenstack.dev/docs/reference/zmodel/function

Example of applying the uuid function with an argument in a default value.

```zmodel
id String @default(uuid(4))
```

--------------------------------

### Model attribute application example

Source: https://zenstack.dev/docs/reference/zmodel/attribute

Example of applying the @@unique attribute to a model.

```zmodel
model User {
    org      String
    userName String
    @@unique([org, userName])
}
```

--------------------------------

### Model attribute definition example

Source: https://zenstack.dev/docs/reference/zmodel/attribute

Example of defining a model attribute with parameters.

```zmodel
attribute @@unique(_ fields: FieldReference[], name: String?, map: String?)
```

--------------------------------

### Field attribute application example

Source: https://zenstack.dev/docs/reference/zmodel/attribute

Example of applying the @id attribute to a field.

```zmodel
model User {
    id Int @id(map: "_id")
}
```

--------------------------------

### Field attribute definition example

Source: https://zenstack.dev/docs/reference/zmodel/attribute

Example of defining a field attribute with parameters.

```zmodel
attribute @id(map: String?, length: Int?)
```

--------------------------------

### Generate TypeScript from schema (npm)

Source: https://zenstack.dev/docs/quick-start

Run zen generate to compile the schema into TypeScript. Optionally run zen db push to push the schema to the database.

```bash
npx zen generate
```

--------------------------------

### Function definition example

Source: https://zenstack.dev/docs/reference/zmodel/function

Example of a function definition with an optional parameter, as shown in the syntax section.

```zmodel
function uuid(version: Int?): String {}
```

--------------------------------

### Update related resource - example request

Source: https://zenstack.dev/docs/service/api-handler/rest

Example of updating a related resource under a parent resource.

```json
PUT /user/1/posts/1
{
    "data": {
        "type": "post",
        "attributes": {
            "title": "My Even More Awesome Post"
        }
    }
}
```
Tokens:
Raw