another-express-crud

Let you avoid all the boilerplates to create a crud route

Installation

npm i --save another-express-crud

Example usage

import express from 'express';
import { crud } from 'another-express-crud';

const app = express();

type CrudData = {
  id?: string,
  data: any,
  user?: any,
  files?: any,
  fancyParam?: string
}

const getRequestData = (req) => ({
  id: req.params.id || (req.body && req.body._id),
  data: req.body || {},
  user: req.user,
  files: req.files,
  fancyParam: req.fancyParam
})

const operations = {
  create: (params: CrudData) => ...,
  read: (params: CrudData) => ...,
  update: (params: CrudData) => ...,
  delete: (params: CrudData) => ...,
}

const crudRoutes = crud({
  path: '/user',
  operations,
  getRequestData,
  policy: {
    update: 'owner',
    delete: 'owner'
  },
  hooks: {
    before: {
      create: (params: CrudData) => { success: true },
    },
    after: {
      update: (result, req) => { message: 'update done' },
    }
  }
});
app.use('/api', crudRoutes);

This resulting app is :

| operation | route | | ---------- | ---------------------- | | create | POST /api/user | | read | GET /api/user | | read by id | GET /api/user/:id | | update | PUT /api/user/:id | | update | PATCH /api/user/:id | | delete | DELETE /api/user/:id |

Path

A string to provide a path prefix to the route. Default is '/'.

Request data

The parameter getRequestData is a function to get data provided by the express request that will be passed to most hooks and policy checks. It should be of the form :

type CrudOptions = {
  id: string,
  data: any,
  user: any,
  files: any
}

const getRequestData: (req: Request) => CrudOptions

Notes: No middleware is integrated to parse the body of the requests. You could use for example

• body-parser to get data from json objects and
• express-form-data to get data from FormData objects

import formData from 'express-form-data';
import bodyParser from 'body-parser';
import express from 'express';

const app = express();

// multi-part form data
app.use(formData.parse({ autoFiles: true }));
app.use(formData.format());
app.use(formData.stream());
app.use(formData.union());

// json body
app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

Operations

You should provide an object with at least theese 4 functions:

• create
• read
• update
• delete

All 4 functions should implement the interface : (CrudOptions) => Promise<any>

Note: If you want a good REST implementation you should differentiate the case when:

• read receives id parameters (/test/id) to return only 1 result (if the result is undefined, the route will pass an error to the next middleware with message 'NotFound')
• read receives query parameter (/test?name=john) to return an array of result

Note2: The result of the operation should be returned in the promise (an object or a list of object). If undefined is returned, an error with a message 'NotFound' will be passed to the next middleware.

Hooks

Before

All before hooks take an object CrudOptions in parameter and should return an object indicating if everything is fine and if it's not, the error associated to pass to the next middleware: { success: boolean, error?: Error }

After

All after middlewares take the result of the operation and the request object. They should return a new result or undefined to pass to the afterAll middleware or the response formatter. If the result is undefined the previous result will be used.

Policies

The optional policy object should contain :

| property | type | description | | --------------- | -------------------------- | ----------------------------------------------------------------------------------------------- | | create | string | policy used for create operations | | read | string | policy used for read operations | | update | string | policy used for update operations | | delete | string | policy used for delete operations | | isAuthenticated | (CrudOptions) => boolean | function to determine if the request is made by an authenticated user | | isOwner | (CrudOptions) => boolean | function to determine if a user is the owner of the ressource | | isAdmin | (CrudOptions) => boolean | function to determine if a user has access to all contents | | isDisabled | boolean | disable all policies (if you need to disable policies with an environment variable for example) |

All arguments are optional. Just specify what you need.

You can specify 4 types of policies :

• guest: no permission needed to use the operation
• user: only an authenticated user can access the operation
• owner: only the owner of the ressource can access it
• admin: the ressource is restricted to admin privilege

You can provide isAuthenticated, isOwner and isAdmin functions to customize when the access should be granted.

You can also

By default, all policies are guest if no policy is provided.

Note: By default, if the user object is not undefined, the permission of the request will be at least user (see Request data to know how to get user from request)

Todo

• [ ] More Policy tests
• [ ] Response formatter tests
• [ ] Clearer README with more examples