Skip to main content

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>
};
FieldDescription
userThe 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 EnhancementOptions = {
loadPath?: string;
policy?: PolicyDef;
modelMeta?: ModelMeta;
logPrismaQuery?: boolean;
};
FieldDescriptionDefault
loadPathPath for loading CLI-generated code, including model metadata, access policies, and zod schemas.node_modules/.zenstack
policyThe access policy data, generated by @core/access-policy plugin.Loaded from the default location or the path specified by the "loadPath" option
modelMetaThe model metadata, generated by @core/model-meta plugin.Loaded from the default location or the path specified by the "loadPath" option
zodSchemasThe zod schemas, generated by @core/zod plugin.Loaded from the default location or the path specified by the "loadPath" option
logPrismaQueryWhether 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 clientfalse

Example

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

withPresets

Description

danger

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>
};
FieldDescriptionDefault
userThe 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 WithPolicyOptions = {
loadPath?: string;
policy?: PolicyDef;
modelMeta?: ModelMeta;
logPrismaQuery?: boolean;
};
FieldDescriptionDefault
loadPathPath for loading CLI-generated code, including model metadata, access policies, and zod schemas.node_modules/.zenstack
policyThe access policy data, generated by @core/access-policy plugin.Loaded from the default location or the path specified by the "loadPath" option
modelMetaThe model metadata, generated by @core/model-meta plugin.Loaded from the default location or the path specified by the "loadPath" option
zodSchemasThe zod schemas, generated by @core/zod plugin.Loaded from the default location or the path specified by the "loadPath" option
logPrismaQueryWhether 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 clientfalse

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;
};
FieldDescriptionDefault
loadPathPath for loading CLI-generated code, including model metadata, access policies, and zod schemas.node_modules/.zenstack
modelMetaThe 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;
};
FieldDescriptionDefault
loadPathPath for loading CLI-generated code, including model metadata, access policies, and zod schemas.node_modules/.zenstack
modelMetaThe 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' },
});