Runtime API Reference

This document provides references for runtime APIs exported from the @zenstackhq/runtime package.

Prisma Enhancement API

Enhancement APIs create wrappers around a Prisma client to add additional behavior. These wrappers can be freely combined to fine-tune what behavior to include.

enhance

Description

Calling enhance is the simplest way to include all essential enhancements offered by ZenStack, including access policies, field validation, field omission, and password hashing. It's equivalent to calling:

withOmit(withPassword(withPolicy(prisma, options)));

Signature

function enhance<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    options?: EnhancementOptions
): DbClient;

Parameter prisma

The PrismaClient instance to enhance.

Parameter context

The context to for evaluating access policies with the following typing.

type WithPolicyContext = {
    user?: Record<string, unknown>
};

Field	Description
user	The user object that provides value for the auth() function call in access policies. If provided. Its shape should be consistent with the User model in your ZModel, with all fields optional except for id field(s). Pass undefined to represent an anonymous user, and the auth() function call will evaluate to null in that case.

Parameter options

Options with the following typing.

type TransactionIsolationLevel =
    | 'ReadUncommitted'
    | 'ReadCommitted'
    | 'RepeatableRead'
    | 'Snapshot'
    | 'Serializable';

type EnhancementOptions = {
    loadPath?: string;
    policy?: PolicyDef;
    modelMeta?: ModelMeta;
    logPrismaQuery?: boolean;
    prismaModule?: any;
    transactionMaxWait?: number;
    transactionTimeout?: number;
    transactionIsolationLevel?: TransactionIsolationLevel;
};

Field	Description	Default
loadPath	Path for loading CLI-generated code, including model metadata, access policies, and zod schemas.	node_modules/.zenstack
policy	The access policy data, generated by @core/access-policy plugin.	Loaded from the default location or the path specified by the "loadPath" option
modelMeta	The model metadata, generated by @core/model-meta plugin.	Loaded from the default location or the path specified by the "loadPath" option
zodSchemas	The zod schemas, generated by @core/zod plugin.	Loaded from the default location or the path specified by the "loadPath" option
logPrismaQuery	Whether to log queries sent to Prisma client. Log will be emitted with "info" level, so please make sure you turn that level on when creating Prisma client	false
prismaModule	The Prisma module generated together with PrismaClient. You only need to pass it when you specified a custom PrismaClient output path. The module can be loaded like: import { Prisma } from '<your PrismaClient output path>';.
transactionMaxWait	The maxWait option (in ms) passed to prisma.$transaction() call for transactions initiated by ZenStack.	100000
transactionTimeout	The timeout option (in ms) passed to prisma.$transaction() call for transactions initiated by ZenStack.	100000
transactionIsolationLevel	The isolationLevel option passed to prisma.$transaction() call for transactions initiated by ZenStack.	Database default

Example

const session = getSession();
const enhancedClient = enhance(prisma, { user: session.user });

withPresets

Description

warning

This API is equivalent to enhance and will be deprecated soon.

withPolicy

Use withPolicy to include enhancements of access policy (@@allow and @@deny) and field validation (@length, @email, etc.).

Access policies and validation rules are processed by the @core/access-policy plugin, which transforms the attributes into objects that can be loaded at runtime by default into node_modules/.zenstack folder. withPolicy function also loads from there by default.

If your access policy rules use the auth() function, evaluating it requires access to the current user's identity. You need to pass in a context user object that at least contains the user id.

Signature

function withPolicy<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    options?: WithPolicyOptions
): DbClient;

Parameter prisma

The PrismaClient instance to enhance.

Parameter context

The context to for evaluating access policies with the following typing.

type WithPolicyContext = {
    user?: Record<string, unknown>
};

Field	Description	Default
user	The user object that provides value for the auth() function call in access policies. If provided. Its shape should be consistent with the User model in your ZModel, with all fields optional except for id field(s). Pass undefined to represent an anonymous user, and the auth() function call will evaluate to null in that case.	undefined

Parameter options

Options with the following typing.

type TransactionIsolationLevel =
    | 'ReadUncommitted'
    | 'ReadCommitted'
    | 'RepeatableRead'
    | 'Snapshot'
    | 'Serializable';

type WithPolicyOptions = {
    loadPath?: string;
    policy?: PolicyDef;
    modelMeta?: ModelMeta;
    logPrismaQuery?: boolean;
    transactionMaxWait?: number;
    transactionTimeout?: number;
    transactionIsolationLevel?: TransactionIsolationLevel;
};

Field	Description	Default
loadPath	Path for loading CLI-generated code, including model metadata, access policies, and zod schemas.	node_modules/.zenstack
policy	The access policy data, generated by @core/access-policy plugin.	Loaded from the default location or the path specified by the "loadPath" option
modelMeta	The model metadata, generated by @core/model-meta plugin.	Loaded from the default location or the path specified by the "loadPath" option
zodSchemas	The zod schemas, generated by @core/zod plugin.	Loaded from the default location or the path specified by the "loadPath" option
logPrismaQuery	Whether to log queries sent to Prisma client. Log will be emitted with "info" level, so please make sure you turn that level on when creating Prisma client	false
transactionMaxWait	The maxWait option (in ms) passed to prisma.$transaction() call for transactions initiated by ZenStack.	100000
transactionTimeout	The timeout option (in ms) passed to prisma.$transaction() call for transactions initiated by ZenStack.	100000
transactionIsolationLevel	The isolationLevel option passed to prisma.$transaction() call for transactions initiated by ZenStack.	Database default

Example

// ZModel
model Post {
    id String @id
    title String
    author User @relation(fields: [authorId], references: [id])
    authorId String

    @@allow('read', auth() == author)
}

const session = getSession();
const enhanced = withPolicy(prisma, { user: session.user });
// only posts belonging to the current user are returned
const posts = enhanced.post.findMany();

withOmit

Use withOmit function to include support for the @omit attribute. Fields marked with the attribute will be removed from the entities when they're returned.

Signature

function withOmit<DbClient extends object>(
    prisma: DbClient,
    options?: WithOmitOptions
): DbClient;

Parameter prisma

The PrismaClient instance to enhance.

Parameter options

Options with the following typing.

type WithOmitOptions = {
    loadPath?: string;
    modelMeta?: ModelMeta;
};

Field	Description	Default
loadPath	Path for loading CLI-generated code, including model metadata, access policies, and zod schemas.	node_modules/.zenstack
modelMeta	The model metadata, generated by @core/model-meta plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location

Example

// ZModel
model User {
    id String @id
    email String
    password String @omit
}

const enhanced = withOmit(prisma);
// password field is removed from user entities
const user = enhanced.user.findMany();

withPassword

Use withPassword function to include support for the @password attribute. Fields marked with the attribute will be automatically hashed (using bcryptjs) before being stored.

Signature

function withPassword<DbClient extends object = any>(
    prisma: DbClient,
    options?: WithPasswordOptions
): DbClient;

Parameter prisma

The PrismaClient instance to enhance.

Parameter options

Options with the following typing.

type WithPasswordOptions = {
    loadPath?: string;
    modelMeta?: ModelMeta;
};

Field	Description	Default
loadPath	Path for loading CLI-generated code, including model metadata, access policies, and zod schemas.	node_modules/.zenstack
modelMeta	The model metadata, generated by @core/model-meta plugin.	Loaded from the default location or the path specified by the "loadPath" option

Example

// ZModel
model User {
    id String @id
    email String
    password String @password
}

const enhanced = withPassword(prisma);
// password field is hashed before stored into the database
const user = enhanced.user.create({
    data: { email: 'foo@bar.com', password: 'mysecurepassword' },
});