@varasto/express-crud
Utility for generating Express.js router that handles CRUD operations for a single namespace in Varasto storage, with optional validation performed by Yup.
It is similar to Varasto server (which can also be used as Express.js router) expect that it only handles single namespace in the storage, generates automatically keys for new items stored in the namespace and provides optional validation.
Installation
$ npm install --save @varasto/express-crudUsage
The package provides an function called createRouter, which creates an
Express.js router that provides basic CRUD operations to an namespace
in Varasto storage, with optional validation provided by Yup.
import { createRouter } from '@varasto/express-crud';
import { createFileSystemStorage } from '@varasto/fs-storage';
import express from 'express';
import * as yup from 'yup';
const storage = createFileSystemStorage({ dir: './data' });
const personSchema = yup.object().shape({
name: yup.string().required(),
age: yup.number().required().positive().integer(),
email: yup.string().email(),
});
const app = express();
express.use(
'/api/people',
createRouter(storage, 'people', { schema: personSchema })
);The Express.js application will now respond to GET, POST, PATCH and
DELETE requests made into URI /api/people. Data passed with POST and
PATCH requests must pass schema validation, if one is provided. All data
will be stored under namespace people.
Options
The function takes an optional configuration object, which supports these settings:
schema
Optional Yup schema to which all data is validated against. If omitted, no validation is performed at all.
keyGenerator
Optional function that will be used to generate keys for new entries that are
created with POST requests. If omitted, UUID keys will be generated for all
new entries intead.
Listing items
To list all items stored under the namespace, you make an GET request without
any key included in the request path.
GET / HTTP/1.0To which the router will respond with an JSON object which contains each item stored under the namespace mapped with the key that is used to identify each individual item.
{
"b24ed42e-6ffd-11ec-a909-97c71e1c1df5": {
"name": "John Doe",
"age": 25,
"email": "john.doe@example.com"
},
"bc846d00-6ffd-11ec-972a-a7b216391618": {
"name": "Jane Doe",
"age": 30,
"email": "jane.doe@example.com"
}
}Creating new items
To create new item under the namespace, you make an POST request without any
key included in the request path, with value of the new item included in the
request body as JSON.
POST / HTTP/1.0
Content-Type: application/json
Content-Length: 72
{
"name": "John Doe",
"age": 25,
"email": "john.doe@example.com"
}The router will assign an key to the newly created item which will be used to identify the item with. Key of the item will be returned as the response.
This key can be later used to identify the created item.
{
"key": "403ecc3e-6fff-11ec-87d5-bf4f846a6b19"
}Replacing existing items
To replace an already existing item, you make an POST request with key of the
item you wish to replace as part of the request path, with new value of the
item included in the request body as JSON.
POST /403ecc3e-6fff-11ec-87d5-bf4f846a6b19 HTTP/1.0
Content-Type: application/json
Content-Length: 72
{
"name": "John Doe",
"age": 26,
"email": "john.doe@example.com"
}If the item does not exist in the namespace, 404 will be returned as response instead.
If optional schema was given to the router, an validation will be performed against it. If the given data does not pass the validation 404 error will be returned as response, with the response body containing details on why the validation failed.
Updating existing items
To partially update an already existing item, you make an PATCH request with
key of the item you wish to update as part of the request path. The JSON
included in response body will be shallowly merged with the already existing
data and the result will be sent as response.
PATCH /403ecc3e-6fff-11ec-87d5-bf4f846a6b19 HTTP/1.0
Content-Type: application/json
Content-Length: 15
{
"age": 26
}And the server will respond with:
{
"name": "John Doe",
"age": 26,
"email": "john.doe@example.com"
}If the item does not exist in the namespace, 404 will be returned as response instead.
If optional schema was given to the router, an validation will be performed against it. If the updated data does not pass the validation 404 error will be returned as response, with the response body containing details on why the validation failed.
Removing items
To remove an item, you make a DELETE request with key of the item you wish to
delete as part of the request path.
DELETE /403ecc3e-6fff-11ec-87d5-bf4f846a6b19 HTTP/1.0If the item exists in the namespace, it will be removed and it's value is returned as response. If the item does not exist, 404 error will be returned as response instead.