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.

withPresets

Description

Calling withPresets 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:

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

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

Signature

ts
function withPresets<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    policy?: PolicyDef,
    modelMeta?: ModelMeta
): DbClient;

ts
function withPresets<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    policy?: PolicyDef,
    modelMeta?: ModelMeta
): DbClient;

Parameter	Description	Default
prisma	The Prisma client to enhance
context	The context to for evaluating access policies
policy	The access policy data, generated by @zenstack/access-policy plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location
modelMeta	The model metadata, generated by @zenstack/model-meta plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location

Example

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

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

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 @zenstackhq/access-policy, 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 object containing the user id.

Signature

ts
function withPolicy<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    policy?: PolicyDef,
    modelMeta?: ModelMeta
): DbClient;

ts
function withPolicy<DbClient extends object>(
    prisma: DbClient,
    context?: WithPolicyContext,
    policy?: PolicyDef,
    modelMeta?: ModelMeta
): DbClient;

Parameter	Description	Default
prisma	The Prisma client to enhance
context	The context to for evaluating access policies
policy	The access policy data, generated by @zenstack/access-policy plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location
modelMeta	The model metadata, generated by @zenstack/model-meta plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location

Example

prisma
// ZModel
model Post {
    id String @id
    title String
    author User @relation(fields: [authorId], references: [id])
    authorId String
    @@allow('read', auth() == author)
}

prisma
// ZModel
model Post {
    id String @id
    title String
    author User @relation(fields: [authorId], references: [id])
    authorId String
    @@allow('read', auth() == author)
}

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

ts
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

ts
function withOmit<DbClient extends object>(
    prisma: DbClient,
    modelMeta?: ModelMeta
): DbClient;

ts
function withOmit<DbClient extends object>(
    prisma: DbClient,
    modelMeta?: ModelMeta
): DbClient;

Parameter	Description	Default
prisma	The Prisma client to enhance
modelMeta	The model metadata, generated by @zenstack/model-meta plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location

Example

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

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

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

ts
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

ts
function withPassword<DbClient extends object = any>(
    prisma: DbClient,
    modelMeta?: ModelMeta
): DbClient;

ts
function withPassword<DbClient extends object = any>(
    prisma: DbClient,
    modelMeta?: ModelMeta
): DbClient;

Parameter	Description	Default
prisma	The Prisma client to enhance
modelMeta	The model metadata, generated by @zenstack/model-meta plugin. Only need to pass it if you configured the plugin to generate into custom location.	Loaded from default location

Example

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

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

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

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