NoSQL database wrapper API
- built to work seamlessly in memory, offline, or online
- if connected to KissJS server:
- online mode pushes updates dynamically over all connected clients through WebSocket
- field updates handle relationships with foreign records, and compute the required updates to keep data coherent
Namespaces
Members
# static mode
Database mode:
- online: persist data on the server - requires a connection
- offline: persist data on the client - no connection required
- memory: no persistence at all - a browser refresh flushes the data
Methods
# async static count(modelId, query) → {number}
Count the number of records that match a query
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
query |
object
|
Use same query format as for find() method |
The number of records
number
# async static deleteFakeRecords(modelId)
Delete all the fake records inserted using the method insertFakeRecords. Other records remain untouched.
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
The target collection |
Example
await kiss.db.deleteFakeRecords()
# async static deleteMany(modelId, query, sendToTrashopt)
Delete many records from a collection
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
modelId |
string
|
||
query |
object
|
||
sendToTrash |
boolean
|
<optional> |
If true, keeps the original record in a "trash" collection |
The request's result
# async static deleteOne(modelId, recordId, sendToTrashopt)
Delete a record from a collection
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
modelId |
string
|
||
recordId |
string
|
||
sendToTrash |
boolean
|
<optional> |
If true, keeps the original record in a "trash" collection. Default = false |
The request's result
Example
await kiss.db.deleteOne("user", "007f9d6a-2cbc-42f1-80c4-dad7951414af")
# async static find(modelId, queryopt) → {Array.<object>}
Find records applying:
- filter
- sort
- group
- project
- skip
- limit
The query can be a normalized object, easier to serialize / deserialize.
Without a filter parameter, it returns all the records of the collection. The filter can be a group of filters, where each filter can be:
- a field condition (example: country = "France")
- another group of filters. Check the example below.
Important: KissJS doesn't use server-side grouping and paging (using skip/limit) at the moment because:
- KissJS must work offline
- it's faster in memory for small / medium datasets We'll see how it evolves in the future with the project requirements.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
modelId |
string
|
||
query |
object
|
<optional> |
Query object |
filter |
*
|
<optional> |
The query |
filterSyntax |
string
|
<optional> |
The query syntax. By default, passed as a normalized object |
sort |
*
|
<optional> |
Sort fields |
sortSyntax |
string
|
<optional> |
The sort syntax. By default, passed as a normalized array |
group |
Array.<string>
|
<optional> |
Array of fields to group by: ["country", "city"] |
groupUnwind |
boolean
|
<optional> |
true to unwind the fields for records that belongs to multiple groups |
projection |
object
|
<optional> |
{firstName: 1, lastName: 1, password: 0} |
skip |
object
|
<optional> |
Number of records to skip |
limit |
object
|
<optional> |
Number of records to return |
An array containing the records data
Array.<object>
Example
// Sample filter: "Get all people born in France within years 2000 and 2020, which last name is Dupont or Dupond"
const filter = {
type: "group",
operator: "and",
filters: [
{
type: "group",
operator: "and",
filters: [
{
type: "filter",
fieldId: "country",
operator: "=",
value: "France"
},
{
type: "filter",
fieldId: "birthDate",
operator: ">=",
value: "2000-01-01"
},
{
type: "filter",
fieldId: "birthDate",
operator: "<",
value: "2020-01-01"
}
]
},
{
type: "group",
operator: "or",
filters: [
{
type: "filter",
fieldId: "lastName",
operator: "=",
value: "dupond"
},
{
type: "filter",
fieldId: "lastName",
operator: "=",
value: "dupont"
}
]
}
]
}
let users = await kiss.db.find("user", {
filter: filter,
sort: [{lastName: "asc"}, {birthDate: "desc"}],
projection: {password: 0},
skip: 100,
limit: 50
})
# async static findById(modelId, ids, sortopt, sortSyntaxopt) → {Array.<object>}
Find multiple records by id
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
modelId |
string
|
||
ids |
Array.<string>
|
ids of the records to retrieve |
|
sort |
Array.<object>
|
object
|
<optional> |
Sort options, as a normalized array or a Mongo object. Normalized example: [{fieldA: "asc"}, {fieldB: "desc"}]. Mongo example: {fieldA: 1, fieldB: -1} |
sortSyntax |
string
|
<optional> |
Sort syntax: "nomalized" | "mongo". Default is normalized |
The found records
Array.<object>
Example
let users = await kiss.db.findById("user", ["fa7f9d6a-2cbc-42f1-80c4-dad795141eee", "0e7f9d6a-2cbc-42f1-80c4-dad795141547"])
let sortedUsers = await kiss.db.findById("user", ["fa7f9d6a-2cbc-42f1-80c4-dad795141eee", "0e7f9d6a-2cbc-42f1-80c4-dad795141547"], [{lastName: "asc"}, {age: "desc"}])
let mongoSortedUsers = await kiss.db.findById("user", ["fa7f9d6a-2cbc-42f1-80c4-dad795141eee", "0e7f9d6a-2cbc-42f1-80c4-dad795141547"], {lastName: 1, age: -1}, "mongo")
# async static findOne(modelId, recordId) → {object}
Find a single record by id
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
recordId |
string
|
The found record
object
Example
let Bob = await kiss.db.findOne("user", "fa7f9d6a-2cbc-42f1-80c4-dad795141eee")
# async static insertFakeRecords(modelId, fields, numberOfRecords) → {Array.<object>}
Insert some fake records in a collection, for testing purpose.
See db.faker documentation for more details.
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
The target collection |
fields |
Array.<object>
|
Array of fields that defines the model |
numberOfRecords |
integer
|
Number of fake records to insert |
The array of inserted records data
Array.<object>
Example
// Insert 100 products into the collection
await kiss.db.insertFakeRecords("product", [
{primary: true, label: "Title", type: "text"},
{label: "Release date", type: "date"}
{label: "Category", type: "select", multiple: true, options: [{value: "Adventure", color: "#00aaee"}, {value: "Action", color: "#00eeaa"}]}
{label: "Life time", type: "integer", min: 0, max: 5}
], 100)
# async static insertMany(modelId, records) → {Array.<object>}
Insert many records in a collection
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
records |
Array.<object>
|
An array of records [{...}, {...}] for bulk insert |
The array of inserted records data
Array.<object>
Example
let newUsers = await kiss.db.insertMany("user", [
{firstName: "Will", lastName: "Smith"},
{firstName: "Joe", lastName: "Dalton"},
{firstName: "Albert", lastName: "Einstein"}
])
# async static insertOne(modelId, record) → {object}
Insert one record in a collection
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
record |
object
|
A single record |
The inserted record data
object
Example
let newUser = await kiss.db.insertOne("user", {firstName: "Bob", lastName: "Wilson"})
console.log(newUser) // returns {firstName: "Bob", lastName: "Wilson"}
# static setMode(mode)
Set the datatabase mode
Parameters:
Name | Type | Description |
---|---|---|
mode |
string
|
memory | offline | online |
Example
// Setting offline mode
kiss.db.setMode("offline")
# async static updateBulk(operations)
Update multiple records in multiple collections
Parameters:
Name | Type | Description |
---|---|---|
operations |
Array.<object>
|
The list of updates to perform |
The request's result
Example
kiss.db.updateBulk(
[{
modelId: "project",
recordId: "6ab2f4fd-e6f3-4fc3-998f-96629e7ef109",
updates: {
projectName: "Yet another Javascript project"
}
}, {
modelId: "task",
recordId: "5eb85fe3-2634-466c-839f-08423fc1cac1",
updates: {
taskName: "Task 1"
}
}, {
modelId: "task",
recordId: "5ae68056-f099-473b-8f5f-af9eeec9ddff",
updates: {
taskName: "Task 2",
status: "done"
}
}, {
modelId: "task",
recordId: "1f7f9d6a-2cbc-42f1-80c4-8ad795141493",
updates: {
status: "pending"
}
}]
)
# static updateLink(link)
Update the 2 records connected by a link
Parameters:
Name | Type | Description |
---|---|---|
link |
object
|
The transaction result
# async static updateMany(modelId, query, update)
Update many records in a single collection
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
query |
object
|
|
update |
object
|
The request's result
# async static updateOne(modelId, recordId, update) → {object}
Update a single record in a collection
Parameters:
Name | Type | Description |
---|---|---|
modelId |
string
|
|
recordId |
string
|
|
update |
object
|
The request's result
object
Example
let updatedUser = await kiss.db.updateOne("user", "f07xF008d", {lastName: "Smith"})
console.log(updatedUser) // returns {firstName: "Bob", lastName: "Smith"}
# async static updateOneDeep(modelId, recordId, updateopt)
Update a record then propagate the mutation to foreign records
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
modelId |
string
|
||
recordId |
string
|
||
update |
string
|
<optional> |
If not specified, re-compute all the computed fields |
The request's result
Example
await kiss.db.updateOneDeep("company", "f07xF008d", {name: "pickaform"})