Kawara data module

This module is used client-side as a middleman between apps and database. It provides get, insert, update and remove methods.

I. Installation & usage

/* cd ~/your/app/path */
> npm i kawara-data-module

/* ~/your/app/path/index.js */
import DM from 'kawara-data-module'

/* Default value of rootUrl is 'http://localhost:3000',
 * set it to the adress where your kawara-core server runs */
DM.rootUrl = someUrl

/* All DM methods return promises. opt value is described further below */
await DM.get(...opt)
await DM.insert(...opt)
await DM.update(...opt)
await DM.remove(...opt)
await DM.getFilesInfo(...ids)
DM.getFile(id)

II. Documentation

General purpose

The idea behind this module is to give a simple way of retrieving data from the Kawara server (kawara-core). See kawara-core/routes/utils/schemas/index.js to understand data types below. <RAW_NEW_DOCUMENT>, <RAW_UPD_DOCUMENT> and <UPDATION_QUERY> types are not valid types in the eyes of kawara-core, and are described at the end of this table.

DM.get

Params | Purpose -|- ...(<DOCUMENT_CLASS> \|\| <DOCUMENT_TYPE> \|\| <DOCUMENT_ID>) | Query all documents of a class, a type or a document with a specific _id. Adding a parameter to this.get is like performing a or condition, rather than a and. Meaning that this.get(a, b, c) will return every document matching a or b or c. If only one parameter is given and the parameter is of type <DOCUMENT_ID>, kawara-core server will return a single <DOCUMENT> object. If not, an array of <DOCUMENT>s will be returned instead.

DM.insert

Params | Purpose -|- ...<RAW_NEW_DOCUMENT> *(see documentation below) | Create documents by giving them as parameters, where files to upload are inside the doc.content.some_field prop. Upload fields then look like this: some_field: {type: 'upload', value: fileInput.value}. The DM.insert function then replaces the field value with a temp id and stores the file in a files variable. Then it sends to the server a request with a docs prop and a files prop, which can be understood by the kawara-core server. kawara-core server returns a single <DOCUMENT> object if a single document is given as paremeter, returns an array of <DOCUMENT>s objects if an array is given instead.

DM.update

Params | Purpose -|- <RAW_UPD_DOCUMENT> \|\| [...<RAW_UPD_DOCUMENT>] *(see documentation below) | Works the same than DM.insert, splits parameters into docs and files props for the query sent to the server. Server returns a single updated document if a single document is given, and an array of documents instead. (<DOCUMENT_ID> \|\| [...<DOCUMENT_ID>]), (<UPDATION_QUERY> \|\| [...<UPDATION_QUERY>]) *(see documentation below) | Applies queries to given documents. If a single query is given, it will be applied to all documents. Otherwise, the number of documents must be equal to the number of queries. Queries can contain files the same way <RAW_UPD_DOCUMENT>s can.

DM.remove

Params | Purpose -|- <DOCUMENT_ID> \|\| [...<DOCUMENT_ID>] | Sets the status prop to 'removed' for each document with an _id prop matching one of those given in the params. Returns one or many updated documents, depending on the number of params given.

DM.getFilesInfo

Documentation to be written

Specific data types

Some precisions about the data types that can be given to DM methods, but are not recognized on the kawara-core server side. See full types documentation at kawara-core/routes/utils/schemas/index.js. Type | Description -|- <RAW_NEW_DOCUMENT> | This type is like a <INPUT_NEW_DOCUMENT>, but it's <UPLOAD_FIELD>'s value take a file input value. <RAW_UPD_DOCUMENT> | This type is like a <DOCUMENT>, but it can have fields in it's content prop where it's type is 'upload', and it's value is a file input value. <UPDATION_QUERY> | This type describes an object litteral containing 0, 1 or 2 properties, which can be set and remove.

III. Next steps

• [ ] Finish writing the documentation about <UPDATION_QUERY>
• [ ] Fix the bug when updating with a single id and a single query (no arrays)
• [ ] Write documentation about DM.getFilesInfo and DM.getFile
• [ ] Write the above specific data types inside kawara-core's validation module
• [ ] Use the kawara-core's validation module inside kawara-data-module
• [ ] Better comments inside code
• [ ] Enhance DM.get possibilities

Thanks for reading