API Docs for:
Show:

JsonDB Class

Module: API

Provides access to JSON-DB databases. A JSON-DB database is a file-based object database where objects are stored in JSON files. JSON files may be arranged in an arbitrary directory hierarchy under a single "root" directory. Though this class allows files to be written using the 'write' method, any other means of writing files from within CompleteFTP or externally may also be used. Objects in a JSON-DB database are accessed via an 'object-path'.

The object-path in JSON-DB is analogous to a primary key in relational databases in the sense that it uniquely defines a single entity. It's more powerful than a primary key though since it facilitates grouping of data like a traditional file-system. An object path consists of a file-path and an option object-path. For example, if a JSON file called "b.json" is placed in a directory "a" under the root directory, and if that file defines an object with a property, "c", then that property may be read using the object-path, "a/b.c".

An existing JSON object may be updated using the 'update' method. Individual objects may be read from a JSON-DB via the 'read' method. More generic querying is supported via the 'query' method.

Since JSON-DB uses a file-system for storage, non-JSON files may be stored in the datbase alongside (JSON) objects. The 'writeText' and 'writeBase64' allows such files to be written using the same file-paths as JSON objects.

References between objects in a JSON-DB database are done via string properties with the suffix, "ref". The value is the object-reference of the referenced object. The read method returns these properties as strings. The 'dereference' method may be used to resolve reference properties to the objects that they reference. The deferenced properties will have the name of the reference property with the "ref" suffix removed.

Constructor

JsonDB

()

Methods

dereference

(
  • object
)
Object

Resolves reference properties to the objects that they reference. The deferenced properties will have the name of the reference property with the "_ref" suffix removed.

Parameters:

  • object Object

    Object to be dereferenced. This object is not modified.

Returns:

Object: Object with all reference properties dereferenced.

query

(
  • pattern
  • type
  • comparer
  • value
  • callback
)
Array

A JSON-DB may be queried using an object-path containing wild-cards and a comparison. For example, a JSON-DB has a directory called 'products' that contains a set of product objects stored in JSON files whose names are the product IDs, and those objects have a property called 'colour'. To query for a certain colour, the pattern would be "products/.colour". If we want to find all the green objects then we'd call the query method as follows: myDb.query('products/.colour', 'string', '=', 'green').

The result may be obtained via the callback or the return value.

Parameters:

  • pattern String

    Wildcard object-path.

  • type String

    Type being queried for: "number", "string" or "date".

  • comparer String

    Comparison operator to use: "=", ">", "<", ">=", "<=", "<>" or "LIKE".

  • value Object

    Value to compare with.

  • callback Function

    (Optional) callback function to call for each match found.

Returns:

Array: Array containing all matches.

read

(
  • objectPath
  • fullResult
)
Object

Reads the object at the given path from the database. The path may specify a directory of JSON files, a specific JSON file, or an property within the object defined in a JSON file. For example, the path "a/b.c" will reference the property called "c" within the file with the path "a/b.json".

Parameters:

  • objectPath String

    Path of the object.

  • fullResult Boolean

    (Optional) should a full result object be returned, or just the object that was read. Defaults to false.

Returns:

Object: The object returned depends on the 'fullResult' argument. If fullresult is false then the object at the path will be returned or an exception will be thrown if no object is found. If fullResult is true then an object with the following properties will be returned: 'target' the object at the path or null if not found; 'containers' an array of objects above the target object in the object-path; 'path' the object path; 'error' the error that occurred (if any).

readBase64

(
  • filePath
)
String

Reads the binary file at the given location and returns the content as a base-64 encoded string.

Parameters:

  • filePath String

    Path of the file to read.

Returns:

String: Content of file as base-64

readText

(
  • filePath
)
String

Reads the text file at the given location and returns the content as a string.

Parameters:

  • filePath String

    Path of the file to read.

Returns:

String: Content of file

update

(
  • objectPath
  • callback
)

Updates an object that already exists in the database using a callback method. The callback function takes a single argument, which is the object that was read from the database. This object may be modified within the callback. The file containing the object will be written back to the database after the callback function returns.

Parameters:

  • objectPath String

    Path of object to be updated. This may specify a JSON file or an object within a file.

  • callback Function

    Callback function that is called for the object.

write

(
  • filePath
  • object
)

Writes the object to a JSON file at the given file-path.

Parameters:

  • filePath String

    Path of the file to be written. Note that this path must only specify the file and not any object within a file.

  • object Object

    Object to be written.

writeBase64

(
  • filePath
  • base64
)

Writes a binary file at the given location (relative to the JSON-DB root).

Parameters:

  • filePath String

    Path of the file to write the binary data to.

  • base64 String

    Base-64 encoded binary data to write.

writeText

(
  • filePath
  • text
)

Writes a text file at the given location (relative to the JSON-DB root).

Parameters:

  • filePath String

    Path of the file to write the text to.

  • text String

    Text to write.