ZenStack V3

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 for chat and support.

What's ZenStack

ZenStack is a TypeScript database toolkit for developing full-stack or backend Node.js/Bun applications. It provides a unified data modeling and access solution with the following features:

• A modern schema-first ORM that's compatible with Prisma's schema and API
• Versatile data access APIs: high-level (Prisma-style) ORM queries + low-level (Kysely) query builder
• Built-in access control and data validation
• Advanced data modeling patterns like polymorphism
• Designed for extensibility and flexibility: plugins, life-cycle hooks, etc.
• Automatic CRUD web APIs with adapters for popular frameworks
• Automatic TanStack Query hooks for easy CRUD from the frontend

What's new with V3

ZenStack V3 is a major rewrite of V2. The biggest change is V3 doesn't have a runtime dependency to Prisma anymore. Instead of working as a big wrapper of Prisma as in V2, V3 made a bold move and implemented the entire ORM engine using Kysely, while keeping the query API fully compatible with Prisma.

Please check this blog post for why we made this big architectural change decision.

Even without using advanced features, ZenStack offers the following benefits as a drop-in replacement to Prisma:

1. Pure TypeScript implementation without any Rust/WASM components.
2. More TypeScript type inference, less code generation.
3. Fully-typed query-builder API as a better escape hatch compared to Prisma's raw queries or typed SQL.

Although ZenStack v3's runtime doesn't depend on Prisma anymore (specifically, @prisma/client), it still relies on Prisma to handle database migration. See database migration for more details.

Get started

You can also check the blog sample for a complete example.

Installation

1. Creating a new project

Use the following command to scaffold a simple TypeScript command line application with ZenStack configured:

npm create zenstack@next my-project

2. Setting up an existing project

Or, if you have an existing project, use the CLI to initialize it:

npx @zenstackhq/cli@next init

3. Manual setup

Alternatively, you can set it up manually:

npm install -D @zenstackhq/cli@next
npm install @zenstackhq/runtime@next

Then create a zenstack folder and a schema.zmodel file in it.

Writing ZModel schema

ZenStack uses a DSL named ZModel to model different aspects of database:

• Tables and fields
• Validation rules (coming soon)
• Access control policies (coming soon)
• ...

ZModel is a super set of Prisma Schema Language, i.e., every valid Prisma schema is a valid ZModel.

Installing a database driver

ZenStack doesn't bundle any database drivers. You need to install by yourself based on the database provider you use.

The project scaffolded by npm create zenstack is pre-configured to use SQLite. You only need to follow instructions here if you want to change it.

For SQLite:

npm install better-sqlite3

For Postgres:

npm install pg

Pushing schema to the database

Run the following command to sync schema to the database for local development:

npx zenstack db push

Under the hood, the command uses prisma db push to do the job.

See database migration for how to use migration to manage schema changes for production.

Compiling ZModel schema

ZModel needs to be compiled to TypeScript before being used to create a database client. Simply run the following command:

npx zenstack generate

A schema.ts file will be created inside the zenstack folder. The file should be included as part of your source tree for compilation/bundling. You may choose to include or ignore it in source control (and generate on the fly during build). Just remember to rerun the "generate" command whenever you make changes to the ZModel schema.

Creating ZenStack client

Now you can use the compiled TypeScript schema to instantiate a database client:

import { ZenStackClient } from '@zenstackhq/runtime';
import { schema } from './zenstack/schema';

const client = new ZenStackClient(schema, {
    dialectConfig: { ... }
});

Using ZenStackClient

ORM API

ZenStackClient offers the full set of CRUD APIs that PrismaClient has - findMany, create, aggregate, etc. See prisma documentation for detailed guide.

A few quick examples:

const user = await client.user.create({
    data: {
        name: 'Alex',
        email: 'alex@zenstack.dev',
        posts: { create: { title: 'Hello world' } },
    },
});

const userWithPosts = await client.user.findUnique({
    where: { id: user.id },
    include: { posts: true },
});

const groupedPosts = await client.post.groupBy({
    by: 'published',
    _count: true,
});

Under the hood, all ORM queries are transformed into Kysely queries for execution.

Query builder API

ZenStack uses Kysely to handle database operations, and it also directly exposes Kysely's query builder. You can use it when your use case outgrows the ORM API's capabilities. The query builder API is fully typed, and its types are directly inferred from schema.ts so no extra set up is needed.

Please check Kysely documentation for more details. Here're a few quick examples:

await client.$qb
    .selectFrom('User')
    .leftJoin('Post', 'Post.authorId', 'User.id')
    .select(['User.id', 'User.email', 'Post.title'])
    .execute();

Query builder can also be "blended" into ORM API calls as a local escape hatch for building complex filter conditions. It allows for greater flexibility without forcing you to entirely resort to the query builder API.

await client.user.findMany({
    where: {
        age: { gt: 18 },
        // "eb" is a Kysely expression builder
        $expr: (eb) => eb('email', 'like', '%@zenstack.dev'),
    },
});

It provides a good solution to the long standing whereRaw Prisma feature request. We may make similar extensions to the select and orderBy clauses in the future.

Computed fields

ZenStack v3 allows you to define database-evaluated computed fields with the following two steps:

1. Declare it in ZModel

   model User {
       ...
       /// number of posts owned by the user
       postCount Int @computed
   }

2. Provide its implementation using query builder when constructing ZenStackClient

   const client = new ZenStackClient(schema, {
       ...
       computedFields: {
           User: {
               postCount: (eb) =>
                   eb
                       .selectFrom('Post')
                       .whereRef('Post.authorId', '=', 'User.id')
                       .select(({ fn }) =>
                           fn.countAll<number>().as('postCount')
                       ),
           },
       },
   });

You can then use the computed field anywhere a regular field can be used, for field selection, filtering, sorting, etc. The field is fully evaluated at the database side so performance will be optimal.

Polymorphic models

Coming soon...

Access policies

Coming soon...

Validation rules

Coming soon...

Custom procedures

Coming soon...

Runtime plugins

V3 introduces a new runtime plugin mechanism that allows you to tap into the ORM's query execution in various ways. A plugin implements the RuntimePlugin interface, and can be installed with the ZenStackClient.$use API.

You can use a plugin to achieve the following goals:

1. ORM query interception

ORM query interception allows you to intercept the high-level ORM API calls.

client.$use({
    id: 'cost-logger',
    async onQuery({ model, operation, proceed, queryArgs }) {
        const start = Date.now();
        const result = await proceed(queryArgs);
        console.log(
            `[cost] ${model} ${operation} took ${Date.now() - start}ms`
        );
        return result;
    },
});

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.

2. Kysely query interception

Kysely query interception allows you to intercept the low-level query builder API calls. Since ORM queries are transformed into Kysely queries before execution, they are automatically captured as well.

Kysely query interception works against the low-level Kysely OperationNode structures. It's harder to implement but can guarantee intercepting all CRUD operations.

client.$use({
    id: 'insert-interception-plugin',
    onKyselyQuery({query, proceed}) {
        if (query.kind === 'InsertQueryNode') {
            query = sanitizeInsertData(query);
        }
        return proceed(query);
    },
});

function sanitizeInsertData(query: InsertQueryNode) {
    ...
}

3. Entity mutation interception

Another popular interception use case is, instead of intercepting calls, "listening on" entity changes.

client.$use({
    id: 'mutation-hook-plugin',
    beforeEntityMutation({ model, action }) {
        console.log(`Before ${model} ${action}`);
    },
    afterEntityMutation({ model, action }) {
        console.log(`After ${model} ${action}`);
    },
});

You can provide an extra mutationInterceptionFilter to control what to intercept, and opt in for loading the affected entities before and/or after the mutation.

client.$use({
    id: 'mutation-hook-plugin',
    mutationInterceptionFilter: ({ model }) => {
        return {
            intercept: model === 'User',
            // load entities affected before the mutation (defaults to false)
            loadBeforeMutationEntity: true,
            // load entities affected after the mutation (defaults to false)
            loadAfterMutationEntity: true,
        };
    },
    beforeEntityMutation({ model, action, entities }) {
        console.log(`Before ${model} ${action}: ${entities}`);
    },
    afterEntityMutation({ model, action, afterMutationEntities }) {
        console.log(`After ${model} ${action}: ${afterMutationEntities}`);
    },
});

Other guides

Database migration

ZenStack v3 delegates database schema migration to Prisma. The CLI provides Prisma CLI wrappers for managing migrations.

• Sync schema to dev database and create a migration record:

  npx zenstack migrate dev

• Deploy new migrations:

  npx zenstack migrate deploy

• Reset dev database

  npx zenstack migrate reset

See Prisma Migrate documentation for more details.

Migrating Prisma projects

1. Install "@zenstackhq/cli@next" and "@zenstackhq/runtime@next" packages
2. Remove "@prisma/client" dependency
3. Install "better-sqlite3" or "pg" based on database type
4. Move "schema.prisma" to "zenstack" folder and rename it to "schema.zmodel"
5. Run npx zenstack generate
6. Replace new PrismaClient() with new ZenStackClient(schema, { ... })

Limitations

1. Only SQLite (better-sqlite3) and Postgres (pg) database providers are supported.
2. Prisma client extensions are not supported.
3. Prisma custom generators are not supported (may add support in the future).