@vestify/core NPM

Vestify Core

Vest users with the permissions they need. 📝🔐🚀

What is it?

@vestify/core is a flexible framework to build middleware for authorizing CRUD (Create, Retrieve, Update, Destroy) actions in an Express server. It does not enforce any data structure or database type. It is for authorization only, it does not care how you authenticate your users.

The primary aim of the Vestify suite of libraries is to provide an easy-to-use middleware for authorizing requests with fine grained control over fields/columns when performing CRUD actions.

Usage

@vestify/core is not intended to be used directly, but rather underneath the hood of a corresponding companion library that simplifies your workflow. Ideally, you will initialize your instance of Vestify via the companion library. Once initialized, you can use your instance of Vestify's addRoutesTo() function in an Express app. A brief example:

const app = express()
const router = Router()
const vestify = initVestify(...)
app.use(json())
vestify.addRoutesTo(router)
app.use('/resources', router)

This function will iterate over your registered Resource objects and build the applicable routes for your application. The routes will use Vestify's middleware to authorize and process transaction requests, running lifecycle hooks along the way. By default the middleware will return JSON representing the output of your transaction, or you can use the Resource options to tell it to use a next function, in which case it will assign the result of the transaction to the _vestify key of the request to allow your app to make the final call on what gets done with the data.

Routing and Request Bodies

Learn more about how how @vestify/core maps URLs and request bodies to corresponding CRUD actions here

Request Handling

Request Lifecycle

@vestify/core's middlewareForRoute function processes a request using the lifecycle hooks assigned to the registered Resource for which a request applies.

Learn more about @vestify/core's request lifecycle in the Request Lifecycle Documentation.

Logging

You can provide a custom logger for your instance of Vestify, or by default any logging statements from @vestify/core will use console. If you would like to suppress logging, set any of the following applicable environmental variables to true:

VESTIFY_SUPPRESS_LOG_LOGGING
VESTIFY_SUPPRESS_INFO_LOGGING
VESTIFY_SUPPRESS_WARN_LOGGING
VESTIFY_SUPPRESS_ERROR_LOGGING
VESTIFY_SUPPRESS_ALL_LOGGING

You can also get more verbose logging with VESTIFY_VERBOSE_LOGGING set to true

Companion Libraries

Currently, @vestify/core is used by the following companion library:

@vestify/type-orm Provides initiator functions that are compatible with Type ORM

We are open to adding new companion libraries to streamline usage of @vestify/core. Please see the @vestify/dev-kit project for tips on how to set up a project that adheres to the Vestify team project standards, and send us a message letting us know if you would like to contribute.

Building a Companion Library

There are a few basic functions you will use to build out a companion library on the back of @vestify/core:

defineResource
definePermission
initVestify

Build Your CRUD Functions

To create your companion library, you can implement some generic CRUD functions that can be used to initiate Resource objects through the defineResource factory, and it's recommended to provide your own public facing factory function to define Resource objects as opposed to directly exposing the class.

Implement a Compatible `UserPermissionsRetriever`

The way you retrieve permissions will vary based on how you are dealing with CRUD actions and how you are assigning permissions. You may be using a database, writing to files, etc., and you may be setting permissions based on API keys or user access tokens, etc.

@vestify/core just needs to know how to retrieve permissions as Permission objects for a given request.

You can use the definePermission factory function to build out your UserPermissionsRetriever

Provide a Factory Function from Your Module

Finally, you can provide end users with a custom factory method that returns the output of initVestify after defining Resource objects using your custom Resource factory.

Disclaimer

It is not recommended to extend the classes used under the hood by @vestify/core since you don't want to find yourself and others in a subclassing nightmare. If you are importing from anywhere other than the main file specified in package.json this will not be supported by the Vestify team and you're on your own.