Version: 1.x

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' },
});

Runtime API Reference

Prisma Enhancement API​

enhance​

Description​

Signature​

Parameter prisma​

Parameter context​

Parameter options​

Example​

withPresets​

Description​

withPolicy​

Signature​

Parameter prisma​

Parameter context​

Parameter options​

Example​

withOmit​

Signature​

Parameter prisma​

Parameter options​

Example​

withPassword​

Signature​

Parameter prisma​

Parameter options​

Example​

Comments

Prisma Enhancement API

enhance

Description

Signature

Parameter `prisma`

Parameter `context`

Parameter `options`

Example

withPresets

Description

withPolicy

Signature

Parameter `prisma`

Parameter `context`

Parameter `options`

Example

withOmit

Signature

Parameter `prisma`

Parameter `options`

Example

withPassword

Signature

Parameter `prisma`

Parameter `options`

Example