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
// ZModelmodel Post {id String @idtitle Stringauthor User @relation(fields: [authorId], references: [id])authorId String@@allow('read', auth() == author)}
prisma
// ZModelmodel Post {id String @idtitle Stringauthor 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 returnedconst posts = enhanced.post.findMany();
ts
const session = getSession();const enhanced = withPolicy(prisma, { user: session.user });// only posts belonging to the current user are returnedconst 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
// ZModelmodel User {id String @idemail Stringpassword String @omit}
prisma
// ZModelmodel User {id String @idemail Stringpassword String @omit}
ts
const enhanced = withOmit(prisma);// password field is removed from user entitiesconst user = enhanced.user.findMany();
ts
const enhanced = withOmit(prisma);// password field is removed from user entitiesconst 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
// ZModelmodel User {id String @idemail Stringpassword String @password}
prisma
// ZModelmodel User {id String @idemail Stringpassword String @password}
ts
const enhanced = withPassword(prisma);// password field is hashed before stored into the databaseconst user = enhanced.user.create({data: { email: 'foo@bar.com', password: 'mysecurepassword' },});
ts
const enhanced = withPassword(prisma);// password field is hashed before stored into the databaseconst user = enhanced.user.create({data: { email: 'foo@bar.com', password: 'mysecurepassword' },});