A seneca.js entity CRUD plugin.
Last update: 06/14/2018
The seneca-entity plugin already provides simple persistent functions:
data$. The seneca-entity-crud plugin encapsulate these functions in an efficient way.
Why this plugin?
When we develop real applications, we often have to manage a lot of entities. For example: customer, product, catalog, address, order, sell, relations between them and so one. Working with the seneca-entity plugin, the same kind of code can be duplicated a lot of time. For example, here is a code used to simply read an entity:
// Database entity creationvar entityFactory = seneca// Reads the entity in the databaseentityFactory
The seneca-entity-crud plugin do the same work in a simplest manner. It defines a
read command and can use the promises power. Let's see it.
Once for all, the application promisify the
const promise =const seneca =var act = promise
And here is our new code used to read an entity:
// Reads the entity in the database;
Less code. CRUD names. And the code is easier to understand.
One very nice thing: in addition to CRUD, this plugin offers additional commands.
checkcommand verify that the store works. It performs a create-then-delete operation. This is useful when the microservice using this plugin has a health process.
countcommand encapsulate the
list$function, but return only the count for network optimization.
deleterelationshipscommand extends the deletion of an entity to that of all its relations. See this readme file.
querycommand encapsulate the
list$function with new features.
truncatecommand works as traditional SQL
TRUNCATE TABLE my_table.
And we even lie on the floor:
- This plugin includes an optional input data validation functionality to be used before the create or update action.
last_updatedate value can be automatically added to each entity when created or updated.
- The appends feature provides additional actions during read or query.
- The joins feature provides deep readings from IDs contained in entities.
- The then feature provides additional processes on entities being read or queried.
- The uniqueness feature checks the uniqueness of the fields in the database before creating or updating an entity.
- For security, using the optional
nonamespace: trueargument, the namespace of the resulting entities is automatically removed.
- Defaults can be added to the resulting entities.
How it works
Your application must declare the seneca-entity plugin:
const seneca =seneca// For Seneca >= 3.xseneca
See the seneca-entity project for installation and more information.
Your application must declare this plugin:
The options are:
- zone: the name of your zone (optional).
- base: the name of your base (optional).
- name: the primary name of your entities. Default:
entity. The primary name must not contain hyphen (-).
- last_update: an optional boolean value. If true, the current date value is automatically added to each entity (the field name is
last_update) when created or updated. Default:
- role: the name of your role, so this plugin commands are part of your patterns. Default:
- config.msg_no_entity: the default error message when an entity is not found.
- config.msg_no_id: the default error message when an entity ID is not found.
- config.msg_not_unique: the default error message when an entity field is not unique.
Proceed each seneca-entity-crud command as any seneca command. Here is a full example for the
create command, using the seneca-mem-store persistence plugin:
'use strict'/* Prerequisites */const promise =const seneca =/* Plugin declaration */seneca// For Seneca >= 3.x/* Promisify seneca actions */var act = promise/* Starts seneca */seneca
Try it! The console shows:
My great post ID is: <an id like 5a4732ef4049cfcb07d992007e003932>
For the list of the commands and their arguments, see the chapter below: API commands specifications.
Note: the ID generated for the entity is provided by the store plugin used in your application.
Input data validation
In most cases, it's a best practice to validate input data before insert it in the database. The seneca-entity-crud plugin cannot validate input data by itself: it highly depends on your application data types. However, if you need to proceed input data validation, this plugin can use your favorite function.
For more information and examples, please see the input data validation documentation.
The returned namespace
By default, the entity$ field of the resulting entities contains the entity namespace
zone-base-name. For security reasons, sensitive applications may not need this data. To automatically remove the resulting entity namespace, use the
nonamespace: true argument in the command.
Note: for convenience, the
nonamespaceargument value can be the
trueboolean or the
var myId = '5a4732ef4049cfcb07d992007e003932'// Read
For more information on zone, base and name, see the entity namespace tutorial.
Note: this feature is optional.
The defaults argument is an object. Each object key/value pair is a default field name/value pair:
'a field name': <a default value> 'another field name': <another default value> ...
If the resulting entity does not contain the field
a field name, it is added with the default value.
If the resulting entity already contains the field
a field name, nothing is changed.
How it works
role: 'my-role' cmd: 'read' id: anId defaults: ...role: 'my-role' cmd: 'query' defaults: ...
var myId = '5a4732ef4049cfcb07d992007e003932'// Read
The console output looks like:
id: '5a4732ef4049cfcb07d992007e003932' ... country: 'Belgium' currency: 'Euro'
API commands specifications
- check: verify that the store can create-then-delete an entity.
- count: retrieve the count of the entities from your database.
- create: insert a new entity into your database.
- delete: remove an entity from your database.
- deleterelationships: remove all relationships of an entity from your database.
- first: retrieve from your database the first entity matching filters.
- query: retrieve a list of entities from your database.
- read: retrieve an entity from your database.
- truncate: remove all the entities from your database.
- update: update an entity previously created into your database.
- validate: validate your data.
To install, simply use npm:
npm install seneca-entity-crud
To run tests, simply use npm:
The Senecajs org encourages open participation. If you feel you can help in any way, be it with documentation, examples, extra testing, or new features please get in touch.
Copyright (c) 2016-2018, Richard Rodger and other contributors. Licensed under MIT.