Db API¶

Drosse leverages LokiJS power to allow stateful interactive mocking. But don't worry, no need for database configuration or any complicated stuffs. Basically, LokiJS is a nosql document database (a bit like mongo, but way simpler).

When you start your mock server for the first time, Drosse will create a database and store it in a mocks.json file in your [mocks root] directory. Yes! You've read it, it's a simple JSON file. You can open it in your IDE and see the content of your database. But don't modify it manually, it will probably break the database. To be precise, LokiJS is a in-memory database and it will simply dump its content every 4 seconds in the mocks.json file.

How do I update it, then ?

LokiJS is collections-based. You can consider each collection as an array of objects, each object being a document.

To provide some contents to your database, you need to create a collections directory in your [mocks root] directory. In this directory you will define your collections. A collection can be either:

A directory that contains JSON files. These files must contain a JSON object (not an array).
A JSON files that must contain an array of objects.

In the end it's the same. Drosse will process either the directory or the big JSON file and insert it as a new collection full of documents in your database.

Note

You can redefine the mocks.json database file and the collections directory name in your .drosserc.js file (see Configuration).

By default, on each startup Drosse will check the collections directory and see if the collection already exists in the database. If not, it will import it. If the collection already exists, Drosse won't import it again; even if you added new files in the collection directory.

If you want a fresh database, simply delete the mocks.json file and restart Drosse.

Tip

You can also type directly db drop in the Drosse CLI to achieve the same goal.

That's a bit hard! Is there a smoother way?

You ask it, we provide.

You can define a shallowCollections key in your .drosserc.js file. It must contain an array with collection names. All the collections listed in this array will be recreated from the JSON files in the collections directory on each Drosse startup.

Identify your documents¶

One more thing. To make Drosse aware of how you identify each of your document, you should provide in each document a DROSSE property which contains an ids property, which itself contains a list of what you consider the document identifiers.

It can be very useful to have different identifiers for your documents. As the identifiers don't have to be unique, it's not an issue. Don't forget that Drosse is a mock server. You aim to mock a real system that lives somewhere out there. And in the real world, it happens often that the same entity is retrieved through different ways. Imagine a Project entity. It could be retrieved by its unique ID, but maybe also by a customer unique code or whatever else.

The real backend has probably different methods to fetch the project accordingly. But here we want to be fast and we don't care about all that. So we can store all the potential identifiers of a document in our DROSSE.ids array. It will look like this:

{
  "id": 1980,
  "name": "Construction of a skyscraper",
  "customer": {
    "id": 888,
    "name": "ACME corp",
    "projectCode": "SKYSCRAPER-999"
  },
  "budget": 98000000,
  "DROSSE": {
    "ids": [1980, "SKYSCRAPER-999"]
  }
}

Like this, it will be easier to find our document and we won't have to ask ourselves which identifier was sent to our service.

Reference documents¶

In the above example we have a customer inside a project. But what if we want to list all the customers in our app ? We could duplicate the customer informations into a customers collection, but that would mean that the customer's informations displayed in the project document are duplicated. Not good to maintain our mocks...

Here come reference documents to the rescue!

Assuming you have a customers collection with this customer document in it.

{
  "id": 888,
  "name": "ACME corp",
  "address": {
    "street": "Undefined or null 1",
    "zip": "00001",
    "town": "North Pole City"
  },
  "activity": "Secretely conquer the world by not being evil... at first.",
  "DROSSE": {
    "ids": [888]
  }
}

You can redefine your project like this:

{
  "id": 1980,
  "name": "Construction of a skyscraper",
  "customer": {
    "collection": "customers",
    "id": 888,
    "projectCode": "SKYSCRAPER-999"
  },
  "budget": 98000000,
  "DROSSE": {
    "ids": [1980, "SKYSCRAPER-999"]
  }
}

The company name is not duplicated anymore.

When you've fetched the project document, you can easily query the linked customer by calling the db.get.byRef() method and pass it the project.customer object. Drosse will automatically understand the pattern "collection - id" and return the corresponding customer document. You can then overwrite project.customer with this result.

API¶

Once your documents are stored in the database, here is how you can query them or even insert new documents programmatically. As you've maybe already read above in the Dynamic mocks section, when you define a service function, it takes an object as argument and this object contains a db property. This db property exposes the whole Drosse DB API. Let's have a look to it in detail.

list¶