Documentation

Namespace

db

kiss.db

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

View Source client/core/db/api.js, line 16

Namespaces

faker
memory
mongo
offline
online

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

View Source client/core/db/api.js, line 30

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

View Source client/core/db/api.js, line 420

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

View Source client/core/db/api.js, line 131

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

View Source client/core/db/api.js, line 408

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

View Source client/core/db/api.js, line 395

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

View Source client/core/db/api.js, line 364

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

View Source client/core/db/api.js, line 266

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

View Source client/core/db/api.js, line 247

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

View Source client/core/db/api.js, line 116

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

View Source client/core/db/api.js, line 92

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

View Source client/core/db/api.js, line 73

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

View Source client/core/db/api.js, line 41

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

View Source client/core/db/api.js, line 231

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"
		}
	}]
)

Update the 2 records connected by a link

Parameters:
Name Type Description
link object

View Source client/core/db/api.js, line 176

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

View Source client/core/db/api.js, line 190

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

View Source client/core/db/api.js, line 150

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

View Source client/core/db/api.js, line 166

The request's result

Example
await kiss.db.updateOneDeep("company", "f07xF008d", {name: "pickaform"})