@chcaa/sqlite-json-table
v3.0.0-beta.8
Published
A wrapper for sqlite tables making it easy to manage json-objects with the flexibility of a nosql database and still use the power of SQL for querying data.
Downloads
232
Readme
sqlite-json-table
sqlite-json-table
is an implementation of a JSON-based SQLite database. It provides an interface for creating, maintaining, and querying one or
more SQLite tables containing JSON data. It further allows for indexing selected fields and creating relations between objects
as well as creating and synchronizing cross-table references.
Entries are based on JSON-compliant JavaScript objects. Queries to the database return parsed, regular JavaScript objects and arrays. Inserting and updating entries is similarly done using regular objects and arrays which are automatically serialized into their proper forms in the database.
Main Features
- Create either a single table or a full database with a combination of objects and relations
- Easy indexing of fields for performant querying and sorting (including support for nested objects and arrays)
- Query fields using regular SQL syntax
- Mix complex object strutures and relations between objects from different tables
- Automatic handling of database index creation and migrations
- Automatic population and depopulation of relational data
- Easy and performant modification of existing objects in the table
- Export to newline-delimited json file (.ndjson)
About SQLite JSON Tables
As a general rule-of-thumb, an SQLite table corresponds to a set of JSON objects. Each object corresponds to a single row. If no indexing or relation is made (for more about indexing and relations, see below) an entry contains exactly two columns:
- An
id
for the entry (uniquely generated or provided by the user): Stored as an INTEGER - The
json
object serialized wihJSON.stringify()
: Stored as TEXT
(For more about SQLite data types, see here).
To take advantage of the optimizations of SQLite, it is possible to create field indexes for certain fields. Every indexed field is placed in its own column in the SQLite table (or a separate index table for arrays), allowing for fast access when filtering and sorting using the SQLite engine. Relations can be made within or across tables, making it possible to combine complex object structures with traditional relations by referring the ids of other objects in the database. By both supporting complex objects and traditional relations, the best of the NoSQL- and SQL-database worlds are combined making it easy to store complex objects and by the same time prevent redundancy by normalizing data where it makes sense.
Getting Started
sqlite-json-table
provides two complementary ways of working with tables. If only a single table is required, it is possible to import and use only
the JsonTable
class, thus avoiding unnecessary overhead. To handle multiple tables, a JsonTableDb
class is provided to manage the creation and
maintenance of tables, including managing relations and bidirectional synchronization in and across tables with relational data.
Installation
npm install @chcaa/sqlite-json-table
Dependencies
An instance of better-sqlite3
is expected to be passed in as the database interface to use.
DB Configuration
The following pragma settings are recommended when configuring SQLite.
import { Database } from 'better-sqlite3';
db = new Database("PATH-TO-FILE");
db.pragma('journal_mode = WAL'); // https://www.sqlite.org/wal.html
db.pragma('synchronous = normal'); // https://www.sqlite.org/pragma.html#pragma_synchronous
db.pragma('foreign_keys = true'); // https://www.sqlite.org/pragma.html#pragma_foreign_keys
General Usage
In the following section, general usage is presented along with examples and notes for best practices.
- Creating Tables
- Creating Entries
- Querying Entries
- Updating Entries
- Deleting Entries
- Exporting Data
- Database Migration
For a detailed description of each method see Class: JsonTable and Class: JsonTableDb and their respective JsDocs.
Creating Tables
There are two fundamental ways of creating tables. Either a single table can be created, using the JsonTable
class, or multiple tables
can be created and managed using the JsonTableDb
class which takes care of table management and supports cross-table events and actions.
NOTE: In the examples below, the data is stored in-memory. Pass in a file path to create a persistent SQLite database.
A few words on terminology: When making tables, create
refers to the creation of a JavaScript representation and configuration of the table,
while init
creates the actual table in the SQLite database, and creates any necessary index columns and index tables in the database as well.
A Single JsonTable
A single table is self-contained and works without the database manager (but does not allow for relations).
The constructor takes the following arguments: A better-sqlite3
instance, a name for the table, and an optional options
object
for indexing. For more about the JsonTableOptions
object, see JsonTableOptions.
import Database from 'better-sqlite3';
import { JsonTable } from '@chcaa/sqlite-json-table';
let db = new Database(':memory:'); // NB pass in a file path to make the db persistent
let myJsonTable = new JsonTable(db, 'persons'); // creates the table
Using the JsonTableDb Database Manager
Multiple JsonTable
instances in a project should be created and managed using a JsonTableDb
instance which then handles the lifecycle of
the JsonTable
s and makes cross-table events and relations between JsonTable
entries possible.
Creating a new JsonTableDb
instance:
import Database from 'better-sqlite3';
import { JsonTableDb, JsonTable } from '@chcaa/sqlite-json-table';
let db = new Database(':memory:'); // NB pass in a file path to make the db persistent
let jsonTableDb = new JsonTableDb(db);
Creating a New JsonTable
To create and initialize a new JsonTable
instance, use the createAndInitJsonTable
method:
import Database from 'better-sqlite3';
import { JsonTableDb, JsonTable } from '@chcaa/sqlite-json-table';
let db = new Database(':memory:'); // NB pass in a file path to make the db persistent
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons');
The database manager provides other methods for creating and initializing JsonTable
instances. See Class: JsonTableDb for more.
Field Indexes and Relations
To be able to query and/or sort on a field and relational field, in e.g. JsonTable#find()
, the field must first be registered as a field index.
Field indexes are provided as an array of objects, where each object corresponds to a single field index.
Each field index must have the field
property. The field
property refers to a field on the objects to be saved in the table. E.g. { field: 'name' }
declares that an index should be created for the top-level field name
. It is possible to create nested fields too: In the example here, name
and age
are top-level fields, while street
is a field of the nested object address
, signified with the dot separator.
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'name' },
{ field: 'age' },
{ field: 'address.street' }
]
});
If the path is an array or is included in an array, the field index must declare this by setting the array
property to true
.
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'hobbies', array: true }, // an array of strings
{ field: 'addresses.street', array: true }, // an array of address objects, where each address objects street field should be indexed
]
});
Relations
Relations are similar to relations between tables in a relational database. Relations can both be self-referential and reference other tables.
Relations are created by setting the relation
property of a field index. Defining relations makes it possible to query and populate the relations when
fetching objects using, e.g., JsonTable#find()
.
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'cars', array: true, relation: { target: 'cars' } } // an array of car ids
]
});
let carJsonTable = jsonTableDb.createAndInitJsonTable('cars', {
fieldIndexes: [], // no field indexes
});
When using relations, the field holding the relation must have one of the following values:
- 1–1 and M-1 relations:
null
, an integer >= 0 or an object with anid
field >= 0 - 1-M and M-M relations: an array of integers >= 0 or an array of objects with an
id
field >= 0
When saving or updating objects which have relations, automatic depopulation of relations will be performed before storing the object in the database. This makes it possible to save and update objects with populated relations without having to replace the populated relations with their corresponding id.
personJsonTable.create({ cars: [{ id: 1, make: "Ford", model: "Fiesta" }] }); // will store { cars: [1] } in the persons JsonTable
NOTE
JsonTable#on()
,JsonTableDb#onRelationChange()
andjsonTableDb#registerBidirectionalSync()
can be used to be notified about and handle changes to relations.
Optimizing for Querying and Sorting
As field indexes make a copy of the value from the entry object and store it in a separate column/table, the field index value can be transformed to improve querying and sorting without affecting the original value. This can be used to improve the querying capabilities by e.g., normalizing special characters to their ASCII equivalent, converting to lowercase, trimming whitespaces, etc.
Field index transformations also make it possible to solve a limitation of Sqlite in relation to UTF-8 where Sqlite does only support
case-insensitive comparisons on ASCII characters. By adding a lowercase
transformation
to a field index this limitation can be circumvented.
Transformations are applied to any value corresponding to the field index before the value is stored in the column/table of the field index in the database.
Values used for querying a field index passed in using queryOptions.filter.bindValues
will have the same transformations applied before the database is
queried.
IMPORTANT
If transformations for a field index are changed (added, removed, transform order changed) after the field index has been created in the database. TheJsonTable#reindex()
method must be called with the field paths for any field index with changes to its transformations. As transformations are just expressed as one or more functions, this cannot be automatically detected onJsonTable#init()
and is therefore up to the user code to handle.If data exists for a given field index and transformations are changed without a
redindex()
the index could be in an unpredictable state leading to wrong search results.Run the
reindex()
in a database migration and create a new migration file for every time areindex()
is required to make sure they only run once per change.
Transformations to a field index are applied by setting the transform
property of the field index configuration object to a single transform function or an
array of transform functions. A transform function is a function that takes a single value parameter and returns the transformed version of the value or
throws and error if the value could not be transformed. sqlite-json-table
already comes with a set of often-used transformations which can be imported
from @chcaa/sqlite-json-table/transform
.
See here for details.
import { lowercase, trim, foldToAscii } from '@chcaa/sqlite-json-table/transform';
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'name', transform: [lowercase, trim, foldToAscii] }
]
});
A Note on Transactions
Every JsonTable
method altering or querying the database runs by default in its own transaction. If the transaction fails, all changes performed within
the transaction will be rolled back. The methods create()
, createWithId()
, update()
,
delete()
, deleteById()
all supports both taking a single value and an array of values making it possible to group changes into the same transaction.
NOTE
If multiple method calls need to be grouped together into a single transaction useJsonTableDb#runInTransaction()
.
Creating Entries
Any valid JSON object can be stored in the table. The create
method adds an id
field
to the object with the id of the row from the table in the database.
let person = { name: 'John', address: 'Some Street', age: 23, created: Date.now() };
personJsonTable.create(person);
console.log(person.id); // an id is added on succesful create
Multiple entries can be created at once (within the same transaction) by passing an array of the entries to the create method.
let person = { name: 'John', address: 'Some Street', age: 23, created: Date.now() };
let person2 = { name: 'Jane', address: 'Some Other Street', age: 43, created: Date.now() };
personJsonTable.create([person, person2]);
If the id is required as part of the creation process, a function can be passed in as the second argument which will then be called with the id before the object is stored in the database.
let person = { name: 'John', address: 'Some Street', age: 23, created: Date.now() };
personJsonTable.create(person, (person, id) => person._idInternal = id);
If the id is generated externally (id must be an integer), use:
let person = { name: 'John', address: 'Some Street', age: 23, created: Date.now(), id: 1 };
personJsonTable.createWithId(person);
To create entries with relations, the JsonTable
instance must be configured with the relations it the field indexes and all involved
JsonTable
instances must be registered in the same JsonTableDb
.
let cityJsonTable = jsonTableDb.createAndInitJsonTable('cities');
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'boss', relation: { target: 'persons' } }, // relation to entry in the same table
{ field: 'address.city', relation: { target: 'cities' } } // nested relation to a different table
]
});
let theWindyCity = { name: 'Chicago', country: 'USA' };
cityJsonTable.create(theWindyCity);
let harry = { name: 'Harry', boss: null, address: { street: 'CEO Street', city: theWindyCity } };
let sally = { name: 'Sally', boss: harry, address: { street: 'Employee Avenue', city: theWindyCity } }
personJsonTable.create([harry, sally]);
A single relation must be expressed by: null
, an integer (referring an id), or an object with an id
field. An array of relations must be
expressed by: an empty array, an array of integers (referring an id), or an array of objects with an id
field.
Relations expressed by an object with an id
are automatically depopulated before saving to the database.
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'cars', array: true, relation: { target: 'cars' } } // an array of car ids
]
});
let carJsonTable = jsonTableDb.createAndInitJsonTable('cars', {
fieldIndexes: [], // no field indexes
});
// This way
let myCars = [{ model: "Audi" }, { model: "Fiat" }];
carJsonTable.create(myCars); // the cars are given the necessary id field and saved in carJsonTable
personJsonTable.create({ name: "Peter", cars: myCars }); // the cars are depopulated and replaced with their ids
// ... or this way
personJsonTable.create({ name: "Peter", cars: [myCars[0].id, myCars[1].id] }); // no depopulation will take place, as ids are already there
// BUT NOT THIS WAY
personJsonTable.create({ name: "Peter", cars: [{ model: "Audi" }, { model: "Fiat" }] }); // will throw an error as no ids exist in the car objects
NOTE: Entries can be repopulated when queried. See more in the section Querying Entries or Class: JsonTable.
Updating Entries
To update an entry, it must have the id
field set.
let person = personJsonTable.getById(1);
person.age++;
personJsonTable.update(person);
Updating All Entries
If all entries need to be updated e.g., when a new field is added to the model or a field is no longer required
a special updateAll()
method is provided which can handle this in a safe and performant way in a single transaction.
the updateAll()
takes a function which is passed each entry. The function can by its return value
control what should happen to the entry in one of the following ways:
- Update the passed in entry and return nothing → the entry will be updated in the database with all changes.
- Return an object → the returned object will replace the current object in the database.
- Return false → no operation will be performed.
- return null → the entry will be deleted from the database.
personJsonTable.updateAll((entry) => {
if (entry.name === 'John') {
entry.name = 'Johnny';
} else {
return false;
}
});
Deleting Entries
Delete an entry by its id:
personJsonTable.deleteById(1);
or by the entry with the id to delete:
let person = personJsonTable.getById(1);
personJsonTable.delete(person);
Querying Entries
Fetch an entry by its id using getById()
:
let person = personJsonTable.getById(1);
Multiple entries can be retrieved simultaneously using getByIds()
. null
is inserted for ids with no matching entries:
let person1 = { name: 'John', address: 'Some Street', age: 23, created: Date.now() };
let person2 = { name: 'Gerry', address: 'Baker Street', age: 45, created: Date.now() };
personJsonTable.create([person1, person2]); // the entries are given ids 1 and 2
let oneResult = personJsonTable.getByIds([1, 2]); // returns both entries
let theSameResult = personJsonTable.getByIds([1, 2, 1]); // returns three entries where index 0 and index 2 are the same
let anotherResult = personJsonTable.getByIds([2, 3, 1]); // returns [{ name: 'Gerry', ... }, null, { name: 'John' ... }]
To get all entries, use getAll()
which optionally can be sorted using any of the configured fieldIndexes
not having array: true
. (If the table contains
many entries
iteratorAll()
should be used instead to avoid memory issues):
let persons = personJsonTable.getAll(); // No sorting
let sortedPersons = personJsonTable.getAll({ field: 'age', order: 'desc' }); // Sorted by age in descending order
If the entries retrieved are configured with a relational field index, it is possible to populate these relations (replacing their ids with the full entries):
let carJsonTable = jsonTableDb.createAndInitJsonTable('cars');
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: 'cars', array: true, relation: { target: 'cars' } } // an array of car ids
]
});
// ...
let person = personJsonTable.getById(1); // -> { name: 'Peter', cars: [1, 2] }
personJsonTable.populate(person, 'cars'); // -> { name: 'Peter', cars: [{ id: 1, model: 'Audi' }, { id: 2, model: 'Fiat' }] }
The configured fieldIndexes
can be queried directly using SQL syntax using the find()
and findOne()
methods. Field names must be quoted:
let result = personJsonTable.find({
filter: { where: '"name" LIKE ? AND "created" > ? AND "addresses.street" = ?', bindValues: ['J%', 1200202022, "Some Street"] },
sorting: { field: 'created', order: 'desc' },
pagination: { offset: 0, limit: 2 }
});
See further documentation of find()
and findOne()
in the JsDocs and the JsonTable Details.
If filtering is required on a field which is not configured in fieldIndexes
, use filterAll()
.
filterAll()
will load all entries from the database (in chunks) and apply the passed in predicate filter.
let result = personJsonTable.filterAll((person) => person.address = 'Some Street');
NOTE
This is less performant than querying field indexes, as all entries need to be parsed, so use field indexes if possible.
Exporting Data
All entries in a table can be exported directly to ndjson
using exportToJsonFile()
:
await personJsonTable.exportToJsonFile('/data/persons.ndsjon');
Alternatively a ReadableStream
can be obtained e.g., to stream the content using a http-response or any
other compatible consumer of a ReadableStream
instance.
let readableStream = jsonTable.createExportReadableStream();
response = new Response(readableStream, {
headers: {
'Content-Type': 'application/octet-stream',
'Content-Disposition': `attachment; filename="${filename}"`
}
});
Database Migration
Sometimes changes to the existing data model can require the production database to be upgraded to
match the changes. This could e.g., be adding new fields that require a default value (e.g. null
),
restructuring of fields, or deletion of fields.
IMPORTANT
JsonTable.init()
handles all additions and modifications tofieldIndexes
so these changes do not require a patch.
Changes in the development code should just be applied, and the test data updated, but to get the production database in sync when publishing a new version with a changed "schema," a patch-file is required, which can perform the changes to the live database.
Patches are described in patch-files (see template below) which name should follow the pattern YYYY-DD-MM_v{SEMANTIC_VERSION}.patch.js
.
So if the next version of the app is1.2.0
and the live database needs to be patched create a new patch file with the current date and the
target version number e.g. 2023-10-10_v1.2.0.patch.js
. The date is required, but is only used for sorting correctly in the filesystem.
A patch file template should look like the following:
import { JsonTable } from "@chcaa/sqlite-json-table";
let state = 0;
export async function beforePatch(db) {
// any setup for the patch can be done here
state = 1;
}
/**
* OBS this function must be a synchronous function as it will be executed inside a transaction which cannot span multi ticks on the event loop
* @param {import('better-sqlite3')} db
*/
export function patch(db) {
// use state from beforePatch if required, if async operations is not required, just do everything here...
let testTable = new JsonTable(db, 'test-table', {
fieldIndexes: [] // the same field indexes as the table has in production to avoid unnecessary reindexing
});
testTable.init(false); // throws an error if not exists, which is good as a precaution
testTable.updateAll(entry => {
// do updates here (add/alter/delete fields), see docs on "updateAll" for different returns values meaning
});
// To alter or delete a table use JsonTableDb#deleteTable() or JsonTableDb#copyJsonTableTo() for e.g. renaming a table
// There should be no need for using the "db" directly.
// (creation of tables will be handled automatically when the app starts up and creates a new JsonTable which is not present, so this should not be handled here).
}
When initializing the application before any data is loaded, do the following to apply the patches required to get the database patched with the missing patches:
import { DatabaseMigrator } from '@chcaa/sqlite-json-table';
let patchDir = '../DIR-WITH_PATCH_FILES';
let backupDir = '.../DIR-FOR-BACKUP'
let db; // the better-sqlite3 instance to patch
let currentDbVersion = '1.0.0'; // this should come from a file or a table in the db
let maxPatchVersion = '1.2.0'; // this should be the current version of the app, e.g. taken from package.json
let dbMigrator = new DatabaseMigrator(db, patchDir, currentDbVersion, maxPatchVersion, {
printStatus: true, // defaults to false
disableForeignKeyConstraints: true, // disable key constratins while migrating, defaults to true
backupDirPath: backupDir // optional, but recommended is no other backup of the db exists
});
let patches = await dbMigrator.getPatches();
await dbMigrator.applyPatches(patches, info => {
currentDbVersion = info.version; // this should be written to where the db version number is stored
});
Class: JsonTable
The JsonTable
class is responsible for a single table in the database and is the main interface for creating, updating, deleting, and
querying entries in the table.
The public methods of the class are presented below. For a more detailed view, please see the respective JsDocs and source code.
Properties
Property: jsonTable#name
(readonly)
string
- The table name.
Setup
These methods are mainly used to create a stand-alone JsonTable
instance. If you work with multiple tables, you should use the JsonTableDb
class which
provides methods for creating and managing table instances.
Constructor: new JsonTable(db, name, [options], [jsonTableDb])
Creates a new JsonTable
instance.
Parameters:
db: Database
- Thebetter-sqlite3
database instance.name: string
- The name of the table to create.options?: JsonTableOptions
- AJsonTableOptions
object. Defaults to{}
. See below for more about theJsonTableOptions
object.jsonTableDb?: JsonTableDb
- AJsonTableDb
instance to connect the newly createdJsonTable
instance to. Used by the methods of theJsonTableDb
class.
Returns:
JsonTable
- The newly createdJsonTable
instance.
Example:
import Database from 'better-sqlite3';
import { JsonTable } from '@chcaa/sqlite-json-table';
let db = new Database(':memory:'); // NB pass in a file path to make the db persistent
let personJsonTable = new JsonTable(db, 'persons', {
fieldIndexes: [
{ field: 'name' },
{ field: 'age' },
{ field: 'address.street' }
]
});
The constructor method only creates the JsonTable
instance; it does not automatically register it in the SQLite database. To do so, it is necessary to also
call the init()
method.
Method: init([createTableIfNotExists])
Initializes an already created JsonTable
instance in the database. By default, the method takes care of creating the table in the database,
including setup of field index columns. If a table with the name already exists in the database, it will be reconfigured with the new field indexes.
If createTableIfNotExists
is false
and no table exists in the database with the same name, an error will be thrown.
Parameters:
createTableIfNotExists?: boolean
: Whether to create the table if it does not already exist. Defaults totrue
.
Example:
// Imports and database object creation
let personJsonTable = new JsonTable(db, 'persons', {
fieldIndexes: [
{ field: 'name' },
{ field: 'age' },
{ field: 'address.street' }
]
});
personJsonTable.init();
Method: createAndInit(db, name, [options], [jsonTableDb])
(static)
Creates and inits the table. The table will be created if it does not exist. This is a shorthand for creating the
JsonTable
using the constructor and then initializing it immediately after.
Parameters:
- The parameters are the same as for the
constructor
and are passed on.
Returns:
JsonTable
- The newly created and initializedJsonTable
instance.
Example:
let personJsonTable = JsonTable.createAndInit(db, 'persons');
Creating Entries
Method: create(entries, [preprocess])
Inserts one or more entries into the table. Any populated relations are automatically depopulated and replaced with their IDs
(the passed in entries will not be altered). If objects to be created already have an id
field, an error will be thrown.
If a preprocess callback function is provided, the function is executed for each entry before saving it to the database.
Parameters:
entries: object|object[]
- An object or an array of objects to insert into the table.preprocess?: function
- A callback that is called for each entry. Takes two parameters:entry: object
- The entry object.id: number
- The newly assigned ID returned from the SQLite table.
Returns:
object|object[]
- The passed in entry/entries with an addedid
field.
Example:
// One entry
let person = { name: "Jody", age: 55, address: { street: "New Street" } };
personJsonTable.create(person);
// Multiple entries
let people = [
{ name: "Jody", age: 55, address: { street: "New Street" } },
{ name: "Sara", age: 20, address: { street: "Old Street" } }
];
personJsonTable.create(people);
// Preprocessing
personJsonTable.create(people, (entry, id) => entry.archivedId = id)
// This will throw an error:
personJsonTable.create({ id: 5, name: "Hansi", age: 44, address: { street: "Bad Street" } });
Method: createWithId(entries)
Inserts one or more entries into the table. Any populated relations are automatically depopulated and replaced with their IDs (the passed in entries will not be altered).
Each entry must have an id
field with value >= 1 and must be an integer. If no id
field is provided, or if the ids provided
already exist in the SQLite table, an error will be thrown.
Parameters:
entries: object|object[]
- An object or array of objects to insert into the table.
Returns:
object|object[]
- The passed in entry/entries.
Example:
// One entry
let person = { id: 3, name: "Jody", age: 55, address: { street: "New Street" } };
personJsonTable.createWithId(person);
// Multiple entries
let people = [
{ id: 45, name: "Jody", age: 55, address: { street: "New Street" } },
{ id: 26, name: "Sara", age: 20, address: { street: "Old Street" } }
];
personJsonTable.createWithId(people);
// These will throw errors
personJsonTable.createWithId({ name: "Jimmy", age: 32, address: { street: "A Street" } }); // No id provided
personJsonTable.createWithId({ id: 3, name: "Hansi", age: 44, address: { street: "Bad Street" } }); // Already exists in the table
Updating Entries
Method: update(entries)
Updates one or more entries in the table.
The entries passed in must all have an id
which is used to determine which row to update in the table. Any populated relations are automatically
depopulated and replaced with their IDs before being saved (the passed in entries will not be altered).
Parameters:
entries: object|object[]
- The entry or entries to update in the table. All entries must have anid
field.
Returns:
object|object[]
- The passed in entry/entries.
Example:
personJsonTable.createWithId({ id: 3, name: "Jody", age: 55, address: { street: "New Street" } });
let person = personJsonTable.getById(3);
person.age++;
personJsonTable.update(person);
//OR - the entry does not need to come from the db, as long as the id is known
personJsonTable.update({ id: 3, name: "Jody", age: 56, address: { street: "New Street" } });
Method: updateAll(updateCb)
Iterates over all entries in the table and calls the passed in callback function for each entry. The method call will be wrapped in a transaction, so any error thrown from the callback function will roll back any operations performed before the error occurred.
NOTE: Update events will not be fired using this method.
Parameters:
updateCb: function
- The callback function to call with each entry as parameter. The function must return one of the following, depending on the desired outcome.- Return
undefined
(or nothing): The entry will be updated in the database with the changes made to it. - Return
object
: The returned object will replace the existing object in the database. - Return
false
: No operation will be performed. - Return
null
: The entry will be deleted from the database.
- Return
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons');
personJsonTable.create([
{ name: "Jamie Saint Merat", hobbies: ['Swimming', 'Running'] },
{ name: "Michael Hoggard", hobbies: ['Biking'] },
{ name: "Paul Kelland", hobbies: [] },
{ name: "Lis Sørensen", hobbies: ['Biking'] }
]);
const bikingPredicate = hobby => hobby.trim().toLowerCase() === 'biking';
const bikingToCyclingMapping = hobby => bikingPredicate(hobby) ? 'Cycling' : hobby;
// conditionally update or delete...
personJsonTable.updateAll(person => {
let update = false;
if (person.hobbies.length === 0) {
return null; // Remove persons with no hobbies from the database
}
if (person.name.startsWith('Jamie')) {
person.name = 'James';
update = true;
}
if (person.hobbies.includes(bikingPredicate)) {
persons.hobbies = person.hobbies.map(bikingToCyclingMapping);
update = true;
}
return update;
});
// add a new field to all
personJsonTable.updateAll(person => {
person.friends = []; // as we do not return anything all entries will be updated with the new field
});
Deleting Entries
Method: delete(entries)
Deletes one or more entries in the table.
Parameters:
entries: object|object[]
- The entry or array of entries to delete from the database.
Example:
let jsonTableDb = new JsonTableDb(db);
let paintersJsonTable = jsonTableDb.createAndInitJsonTable('artists');
paintersJsonTable.create({ name: "Vincent van Gogh" }); // get the id 1 in the database
let aPainter = paintersJsonTable.getById(1); // retrieve the entry by its id
paintersJsonTable.delete(aPainter);
Method: deleteById(ids)
Deletes one or more entries in the table by their id.
Parameters:
ids: number|number[]
- The id or arrays of ids to delete.
Example:
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons');
personJsonTable.create([
{ name: "Jamie Saint Merat", hobbies: ['Swimming', 'Running'] },
{ name: "Michael Hoggard", hobbies: ['Biking'] },
{ name: "Paul Kelland", hobbies: [] },
{ name: "Lis Sørensen", hobbies: ['Biking'] }
]);
personJsonTable.deleteById([2, 3]);
Querying Entries
NOTE
Any relations in the returned entries are represented by their id. To replace the ids with the referenced objects, see Populating and Depopulating Entries.
Method: getById(id, [options])
Returns an entry by its id or null
if no entry was found.
Parameters:
id: number
- The id of the entry to retrieve.options?: object
- Projection options. See project() for details.includeFields?: string[]
- The fields to include.excludeFields?: string[]
- The fields to exclude.
Returns:
object|null
- Anobject
if an entry with the id was found ornull
if no matching entry was found.
Example:
let person = personJsonTable.getById(4);
let personWithNameOnly = personJsonTable.getById(4, { includeFields: ['name'] });
Method: getByIds(ids, [options])
Returns an array of entries corresponding to the passed in ids.
If one or more ids was not found, null
is inserted at the given indices. If multiple ids are identical, the same entry will be used for each identical id.
Parameters:
ids: number[]|Set<number>
- An array or set of ids to query for.options?: object
- Projection options. See project() for details.includeFields?: string[]
- The fields to include.excludeFields?: string[]
- The fields to exclude.
Returns:
object[]
- An array of objects representing entries in the same order as their ids was passed to this method.
Example:
let people = [
{ id: 45, name: "Jody", age: 55, address: { street: "New Street" } },
{ id: 26, name: "Sara", age: 20, address: { street: "Old Street" } }
];
personJsonTable.createWithId(people);
let persons = personJsonTable.getByIds([45, 26]); // -> [ { id: 45, ... }, { id: 26, ... } ]
let persons2 = personJsonTable.getByIds([33, 26]); // -> [ null, { id: 26, ... } ]
let persons3 = personJsonTable.getByIds([45, 26, 45]); // -> [ { id: 45, ... }, { id: 26, ... },{ id: 45, ... } ]
Method: getAll([queryOptions])
Returns all entries in the table.
Parameters:
queryOptions?: object
- The query options to apply to the query.sorting?: object
- The sorting to apply.field?: string
- The path to sort by. Must be defined as a field index or be"id"
. Defaults to"id"
.order?: "asc"|"desc"
- The order to sort by. Defaults to"asc"
.
includeFields?: string[]
- The fields to include. See project() for details.excludeFields?: string[]
- The fields to exclude. See project() for details.
Returns:
object[]
- An array of all entries sorted by path and order.
Example:
let personJsonTable = new JsonTable(db, 'persons', {
fieldIndexes: [
{ field: 'name' },
{ field: 'age' },
{ field: 'address.street' }
]
});
// ...
let allPersons = personJsonTable.getAll({ sorting: { field: 'name', order: 'desc' } })
Method: find([queryOptions])
Finds all entries matching the query options. The filter.where
property declares an SQLite flavored SQL condition which allows the database to
perform the filtering for high performance. Fields paths must be double-quoted.
The queryOptions
object included in the result object will have added defaults for missing optional values, totalCount
added to the pagination
object
(if total count is calculated) and bindValues
transformed using any transform functions configured on the target field index of given bind value.
Parameters:
queryOptions?: object
- The query options to apply to the query.filter?: object
- The filter to apply to the SQL query.where?: string
- A conditional statement using SQL syntax. Must refer to defined field indexes or"id"
. Be aware that fields must be double-quoted.bindValues?: any[]
- An array of values to replace placeholders (?) in thefilter.where
statement.
populateFields?: boolean|string[]
-true
returns the full entries that match the query. To only return their ids, set this property tofalse
. Provide an array of relation fields to return the full entries and further populate the provided relations with their full entries. Defaults totrue
.sorting?: object
- The sorting to apply to the query.field?: string
- The field to sort by. Must be defined as a field index or be"id"
. Defaults to"id"
.order?: "asc"|"desc"
- The order to sort by. Defaults to"asc"
.pagination?: object
- Apply pagination to results.offset: number
- The offset to start from. Must be an integer >= 0.limit: number
- The maximum number of results to return. Must be an integer >= 1.countTotal?: boolean
- Include the total count in the results. Defaults tofalse
.
includeFields?: string[]
- The fields to include. See project() for details.excludeFields?: string[]
- The fields to exclude. See project() for details.
Returns:
{results: object[], queryOptions: object, totalCount: number}
- An object containing an array of results, updatedqueryOptions
and a total count (if requested).
Example:
let personJsonTable = jsonTableDb.createAndInitJsonTable("persons", {
fieldIndexes: [
{ field: "age" },
{ field: "name" },
{ field: "address.city" },
{ field: "spouse", relation: { target: "persons" } }
]
});
// ...
let persons = personJsonTable.find({
filter: {
where: '"age" > ? AND "address.city" = ?',
bindValues: [30, "Århus"]
},
populateFields: ["spouse"],
sorting: {
field: "name",
order: "desc"
},
pagination: {
offset: 10,
limit: 30,
countTotal: true
}
});
// {
// results: [
// { id: 45, name: "Benny", age: 31, address: { city: "Århus" }, spouse: { id: 3, name: "Suzy", ... } },
// { id: 33, name: "Jytte", ... }
// ],
// queryOptions: { ... },
// totalCount: 231
// }
Method: findOne([queryOptions])
Similar to JsonTable#find()
but only returns the first matching entry. Ignores any provided pagination
object.
Parameters:
queryOptions?: object
- See details underfind()
.
Returns:
object|null
- The entry matching the query ornull
if no match was found.
Example:
let jsonTableDb = new JsonTableDb(db);
let gameJsonTable = jsonTableDb.createAndInitJsonTable('games', {
fieldIndexes: [
{ field: 'title' }
]
});
gameJsonTable.create([
{ title: 'World of Warcraft' },
{ title: 'Warcraft 3' },
{ title: 'The Sims' },
{ title: 'Kerbal Space Program' }
])
let theFirstMatch = gameJsonTable.findOne({
filter: {
where: '"title" LIKE ?',
bindValues: ['%Warcraft%']
}
});
console.log(theFirstMatch.title); // -> "World of Warcraft"
Method: filterAll(predicate)
Streams all entries from the table and applies the predicate filter on each entry.
This method is less performant than querying field indexes using find()
,
as all entries need to be parsed, so use field indexes and find()
if possible.
Parameters:
predicate: function
- A callback function to apply for each entry. The function takes one parameter, the entry, and must return a truthy or falsy value (similar toArray.filter()
).
Returns:
object[]
- An array containing all entries passing the predicate test.
Example:
let personJsonTable = new JsonTable(db, 'persons', {
fieldIndexes: [] // no field indexes for "age", so we need to use filterAll()
});
let personsRetired = personJsonTable.filterAll(person => person.age > 67);
Method: countAll()
Counts all entries in the table.
Returns:
number
- The total count of entries in the table.
Example:
let totalCount = personJsonTable.countAll();
Method: count([queryOptions])
Counts the number of entries in the table matching the query.
Paramters:
queryOptions: object
- The query options to apply to the query.filter?: object
- The filter to apply to the SQL query.where?: string
- A conditional statement using SQL syntax. Must refer to defined field indexes or"id"
. Be aware that fields must be double-quoted.bindValues?: any[]
- An array of values to replace placeholders (?) in thefilter.where
statement.
Returns:
number
- The count of entries matching the query.
Example:
let personJsonTable = new JsonTable(db, 'persons', {
fieldIndexes: [
{ field: 'age' }
]
});
let retiredCount = personJsonTable.count({
filter: {
where: '"age" > ?',
bindValues: [67]
}
});
Method: iteratorAll([chunkSize])
Creates a new iterator for iterating over all entries in the table. The iteration is done in a streaming manner so
only chunkSize
(default 1000) is read into memory at the same time.
Parameters:
chunkSize?: number
- The number of entries to read into memory for each chunk. Defaults to1000
.
Returns:
Generator
- AGenerator
instance that iterates over all entries in the table.
Example:
let uniqueNames = new Set();
for (let person of personJsonTable.iteratorAll()) {
uniqueNames.add(person.name);
}
Populating Entries
Method: populate(entries, fields)
Populates relation fields with their referenced entries. Nested relations are allowed as long as they are reachable from a registered relation field index of
the JsonTable
the passed in entries belongs to.
NOTE: The passed in entries will be updated in place.
Parameters:
entries: object|object[]
- An entry or array of entries matching the entry types stored in thisJsonTable
instance. All entries must have the field:id
.fields: string[]
- An array of registered relation field indexes to populate with their referenced entries.
Returns:
object|object[]
- The passed in entries with populated relations.
Example:
let jsonTableDb = new JsonTableDb(db);
let bandJsonTable = jsonTableDb.createAndInitJsonTable('bands');
let artistJsonTable = jsonTableDb.createAndInitJsonTable('artists', {
fieldIndexes: [
{ field: 'name' },
{ field: 'band', relation: { target: 'bands' } }
]
});
bandJsonTable.create({ name: 'Tool' });
let band1 = bandJsonTable.findOne({ filter: { where: '"name" = ?', bindValues: ['Tool'] } });
artistJsonTable.create([
{ name: 'Maynard James Keenan', instrument: 'vocals', band: band1 },
{ name: 'Danny Carey', instrument: 'drums', band: band1 }
]); // Band relations are saved in the database in the form of ids
let bandMembers = artistJsonTable.getAll(); // Still only have the ids. We must populate them
// → [{ name: 'Maynard James Keenan', instrument: 'vocals', band: 1 }, ...]
let populatedBandMembers = artistJsonTable.populate(bandMembers, ['band']);
// The full band object is now attached as the 'band' field
// → [{ id: 1, name: 'Maynard James Keenan', instrument: 'vocals', band: { id: 1, name: 'Tool' } }, ...]
Method: depopulate(entries)
Depopulates all relation fields, replacing any populated entry with its id.
NOTE: The passed in entries will be updated in place.
Parameters:
entries: object|object[]
- An entry or array of entries matching the entry types stored in thisJsonTable
instance. All entries must have the field:id
.
Returns:
object|object[]
- The passed-in entries with depopulated relations.
Example:
// ... continued from the example above
let depopulatedBandMembers = artistJsonTable.depopulate(populatedBandMembers);
// Now the band objects are replaced with their ids again
// → [{ id: 1, name: 'Maynard James Keenan', instrument: 'vocals', band: 1 }, ...]
Method project(entries, options)
Projects the entry or entries to only include the fields defined in includeFields
and/or exclude the fields defined in excludeFields
.
A nested object included by a projection will only have its properties altered if at least one field of the object is present in includeFields
or
excludeFields
. Otherwise, the object will be untouched.
The id
of the root object and any populated relations will be included as default unless explicitly excluded.
Projections support the wildcard operator *
which can be used to include all fields of an object or fields starting with a prefix.
When targeting nestede fields, e.g., ["address.zipCode"]
, and all parent fields should be included as well, include the wildcard operator path
to include the parent fields ["*", "address.zipCode"]
.
To exclude all fields of an object, e.g., private fields starting with a _
exclude the fields using ["_*"]
.
To exclude all fields no matter what their parent/ancestor is use *.
, e.g., exclude all field recursively matching a pattern using ["*._private"]
or even ["*._*"]
.
A field which is included by a wildcard in excludeFields
can be preserved by putting the field explicitly in includeFields
, e.g.,
will the following include all fields of the root object, except the fields starting with "_"
unless it is the exact field "_public"
.
{
includeFields: [
"*",
"_public"
],
excludeFields: [
"_*"
]
}
(To not only include the "_public"
field we need to include "*"
as well in includeFields
).
NOTE: The passed in entries will be updated in place.
Parameters:
entries: object|object[]
- An entry or array of entries matching the entry types stored in thisJsonTable
instance. All entries must have the field:id
.options: object
- Include and exclude options.includeFields?: string[]
- The field paths to include.excludeFields?: string[]
- The field path to exclude.
Returns:
object|object[]
- The passed-in entries with projects applied.
Example:
let jsonTableDb = new JsonTableDb(db);
let bandJsonTable = jsonTableDb.createAndInitJsonTable('bands');
let artistJsonTable = jsonTableDb.createAndInitJsonTable('artists', {
fieldIndexes: [
{ field: 'name' },
{ field: 'band', relation: { target: 'bands' } }
]
});
let band1 = bandJsonTable.create({ name: 'Tool', dicography: [{ title: "Ænima" }] });
artistJsonTable.create([
{ name: 'Maynard James Keenan', instrument: 'vocals', band: band1 },
{ name: 'Danny Carey', instrument: 'drums', band: band1 }
]); // Band relations are saved in the database in the form of ids
let bandMembers = artistJsonTable.getAll(); // Still only have the ids. We must populate them
// → [{ name: 'Maynard James Keenan', instrument: 'vocals', band: 1 }, ...]
let populatedBandMembers = artistJsonTable.populate(bandMembers, ['band']);
// The full band object is now attached as the 'band' field
// → [{ id: 1, name: 'Maynard James Keenan', instrument: 'vocals', band: { id: 1, name: 'Tool' } }, ...]
let bandMembersWithNameAndBandName = artistJsonTable.project(populatedBandMembers, { includeFields: ['name', 'band.name'] });
// We now only have the id, name, band.id and band.name fields.
// -> [{ id: 1, name: 'Maynard James Keenan', band: { id: 1, name: 'Tool' } }, ...]
let bandMembersAndBandName = artistJsonTable.project(populatedBandMembers, { includeFields: ['*', 'band.name'] });
// All band member fields and the band.id and band.name fields.
// -> [{ id: 1, name: 'Maynard James Keenan', band: { id: 1, name: 'Tool' } }, ...]
Events
The JsonTable
emits events before and after altering changes to the database occur. This makes it possible to, e.g., centralize
adding meta-data such as created/updated timestamps before an entry is persisted, run an action after a change occurs or see what has changed
by comparing the before and after state of an entry.
An event can be one of the six states:
beforeCreate
afterCreate
beforeUpdate
afterUpdate
beforeDelete
afterDelete
Before events
Before events will be emitted before the given action is applied to the database and makes it possible to modify the entries before the change is persisted.
The
event will be a part of the current transaction, so any additional change done inside the before event listener will be a part of the transaction
and will be rolled back if the transaction fails. The before event object has the following properties (see on()
for
details):
{
eventName,
jsonTable,
ids,
entries,
entriesBeforeChange
}
The entriesBeforeChange
property will be undefined
for the beforeCreate
event.
After events
After events will be emitted after the given action is applied to the database and the transaction is committed but before the caller which caused the event regains control.
The after event object has the following properties (see on()
for details):
{
eventName,
jsonTable,
ids,
entries
}
The entries
property will be undefined
for the afterDelete
event.
As after events are emitted before the caller initiating the event regains control event listeners depending on state updated by the initiating
caller, and where the initiating caller first updates the state after a successful change to the db,
must postpone their handling of the event by e.g., using process.nextTick()
.
Example:
let updateCount = 0;
function update() {
jsonTable.update({ id: 1, name: "John" });
updateCount++; // runs after jsonTable.update() succeeds
}
jsonTable.on('afterUpdate', () => {
console.log(updateCount); // will be 0 as the update() function has not had a chance to change updateCount yet
process.nextTick(() => console.log(updateCount)); // will be 1 as the update() function now has completed
});
update();
Passing State from Before- to After Events
State can be passed from a before event to an after event using the state object passed to the listener function. The object passed to a before listener will also be passed to the after listener, making it possible to store information which must be collected in the before listener but first needed in the after listener.
The state object is shared between all listeners, so it is recommended to use a Symbol
or similar as the property key to avoid other listeners from
accidentally overriding the set property.
Method: on(eventName, listener)
Registers a listener for the given event.
The same listener function for the same event can only be registered once, even if passed to this method multiple times.
Parameters:
eventName: "beforeCreate"|"afterCreate"|"beforeUpdate"|"afterUpdate"|"beforeDelete"|"afterDelete"
- The event to listen for.listener: function(event: object, state: object)
- The event-listener to call when the event occurs. Takes two parameters:event: object
- Contains information about the event.eventName: string
- The name of the event.jsonTable: JsonTable
- TheJsonTable
instance that triggered the event.ids: number[]
- The ids of the entries involved in the event.entries: object[]
- The entries involved in the event.entriesBeforeChange: object[]
- The entries involved in the event before the change is applied. (Will only be included in before events).
state: object
- An object passed from before to after listeners which can be used to share state. Shared between all listeners.
NOTE: The
ids
,entries
andentriesBeforeChange
of theevent
object are guaranteed to be in the same order.
Example:
// import statements and jsonTableDb instantiation comes here
let documentJsonTable = jsonTableDb.createAndInitJsonTable('documents');
let changelogJsonTable = jsonTableDb.createAndInitJsonTable('changelogs');
const stateKey = Symbol();
// Listening for 'before updates'
documentJsonTable.on('beforeUpdate', beforeUpdateLogger);
function beforeUpdateLogger(event, state) {
// let's make an array-based changelog of updates
let changes = [];
for (let i = 0; i < event.entries; i++) {
// entries, entriesBeforeChange & ids are always in same order
let oldEntry = event.entriesBeforeChange[i];
let newEntry = event.entries[i];
let diff = calcDiff(oldEntry, newEntry);
changes.push(diffStr);
}
// passing data to the 'afterUpdate' event using 'state'
state[stateKey] = changes;
}
// Listening for 'after updates'; a "follow-up" on the 'before'
documentJsonTable.on('afterUpdate', afterUpdateLogger);
function afterUpdateLogger(event, state) {
let logEntry = {
timeStamp: Date.now(),
changedEntries: event.ids,
changes: state[stateKey] // access our passed-on data
}
changelogJsonTable.create(logEntry);
}
// a function that calculates a diff between two objects
function calcDiff(obj1, obj2) {
let diff;
// We assume that it works and returns a representation of the diff
return diff;
}
Method: off(eventName, listener)
Unregisters a registered listener for the given event.
Parameters:
eventName: "beforeCreate"|"afterCreate"|"beforeUpdate"|"afterUpdate"|"beforeDelete"|"afterDelete"
- The event to stop listening for.listener: function
- The event-listener to unregister for further notifications about the event.
Example:
// continuation of the previous example
// we are now done with logging and want to disable the listener
// in this example, we only wish to log the first ~10000 updates
// do this from inside from one of the listeners, so we only unregister once and only when actually listening
let changelogCount = changelogJsonTable.countAll();
if (changelogCount > 10000) {
// it's important that we in some way kept a reference to the listener function
// to be able to remove it again using the reference
documentJsonTable.off('beforeUpdate', beforeUpdateLogger);
documentJsonTable.off('afterUpdate', afterUpdateLogger);
}
Exporting Data
Method: createExportReadableStream()
Creates a readable stream for exporting data as JSON strings where each entry is separated by '\n' (ndjson).
Returns:
ExportReadableStream
(extendsnode:stream.Readable
).
Example:
// use for creating a HTTP reponse object
let stream = personJsonTable.createExportReadableStream();
let reponse = new Response(stream, {
headers: {
'Content-Type': 'application/octet-stream',
'Content-Disposition': `attachment; filename="persons.ndjson"`
}
});
// return the response to the web-client
Method: exportToJsonFile(destFilePath)
(async)
Exports all objects in the table to a ndjson file.
Parameters:
destFilePath: string
- The full path of the file to save to. If the path does not exist, it is created.
Returns:
{Promise<void>}
.
Example:
await personJsonTable.exportToJsonFile('/path/and/filename.ndjson');
Reindexing Field Indexes
Method: reindex(fields)
Reindexes the passed in field index paths. If at least one of the fields is a singular field index (array=false
) all singular field indexes will be reindexed.
As JsonTable#init()
automatically reindexes new field indexes the use of this method is only necessary if an existing
field index's transform
function has been changed, so it produces a different output than before, which will not be detected by the init()
method, or if the
entries have been altered from outside the JsonTable
.
Parameters:
fields: string[]
- The field index paths to reindex.
Example:
personJsonTable.reindex(['age', 'children.name']);
Method: reindexAll()
Reindexes all field indexes.
As JsonTable#init()
automatically reindexes new field indexes the use of this method is only necessary if an existing
index
field's transform
function has been changed, so it produces a different output than before, which will not be detected by the init()
method, or if the
entries have been altered from outside the JsonTable
.
In most cases it will be more optimized to use reindex()
and only reindex the field indexes which requires to be updated.
Example:
personJsonTable.reindexAll();
Class: JsonTableDb
The JsonTableDb
class is responsible for managing multiple tables and makes cross-table references possible.
The public methods of the class are presented below. For a more detailed view, please see the respective JsDocs and source code.
Setup
Constructor: new JsonTableDb(db)
Creates a new JsonTableDb
instance for the database specified.
Parameters:
db: Database
- Abetter-sqlite3
instance.
Returns:
JsonTableDb
- A newJsonTableDb
instance.
Example:
import Database from 'better-sqlite3';
import { JsonTableDb, JsonTable } from '@chcaa/sqlite-json-table';
let db = new Database(':memory:'); // NB pass in a file path to make the db persistent
let jsonTableDb = new JsonTableDb(db);
Creating and Initializing New JsonTable Instances
The following methods can be used to create and initialize JsonTable
instances. The
creation also registers the JsonTable
instance in the JsonTableDb
instance. For more on the difference between creating and
initializing, see the JsonTable
class overview.
Method: createJsonTable(name, [options])
Creates and registers a JsonTable
without initializing it.
Parameters:
name: string
- The name of the table to create.options?: JsonTableOptions
- See more under The JsonTableOptions object.
Returns:
JsonTable
- A newJsonTable
instance.
Example:
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createJsonTable('persons', {
fieldIndexes: [
{ field: "name" }
]
});
Method: createAndInitJsonTable(name, [options], [createTableIfNotExists])
Creates, registers, and initializes a JsonTable
.
Parameters:
name: string
- The name of the table to create and initialize.options?: JsonTableOptions
- See more under The JsonTableOptions object.createTableIfNotExists?: boolean
- Whether to create the table in the database if no table with that name exists. Defaults totrue
.
Returns:
JsonTable
- The newly created and instantiatedJsonTable
instance.
Example:
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createAndInitJsonTable('persons', {
fieldIndexes: [
{ field: "name" },
{ field: children, array: true }
]
});
Method: initJsonTable(jsonTable, [createTableIfNotExists])
Initializes the passed in JsonTable
. If the instance is already initialized, no action will be taken.
Parameters:
jsonTable: JsonTable
- The JsonTable instance to initialize.createTableIfNotExists?: boolean
- Whether to create the table in the database if no table with that name exists. Defaults totrue
.
Example:
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createJsonTable('persons', {
fieldIndexes: [
{ field: "name" }
]
});
jsonTableDb.initJsonTable(personJsonTable);
Method: initAllJsonTables([createTableIfNotExists])
Initializes all registered JsonTable
instances which have not been initialized yet.
Parameters:
createTableIfNotExists?: boolean
- Whether to create the tables in the database if no table with the given name exists. Defaults totrue
.
Example:
let jsonTableDb = new JsonTableDb(db);
let personJsonTable = jsonTableDb.createJsonTable('persons', {
fieldIndexes: [
{ field: 'name' },
{ field: 'pet', relation: { target: 'pets' } }
]
});
let petJsonTable = jsonTableDb.createJsonTable('pets');
jsonTableDb.initAllJsonTables();
Registering Existing JsonTable Instances
The following methods are mainly used internally. If the JsonTableDb
methods are used to create and delete JsonTable
instances, they are automatically
registered and unregistered. The same happens when using the JsonTable
constructor and passing a JsonTableDb
instance as argument.
Only if a JsonTable
instance is created without providing a JsonTableDb
argument, should it be registered manually.
Method: registerJsonTable(jsonTable)
Registers a JsonTable
instance in the JsonTableDb instance.
Parameters:
jsonTable: JsonTable
- TheJsonTable
instance to register.
Example:
let personJsonTable = new JsonTable('persons');
jsonTableDb.registerJsonTable(personJsonTable);
Method: unregisterJsonTable(jsonTable)
Unregisters the given JsonTable
instance.
Parameters:
jsonTable: JsonTable
- TheJsonTable
instance to unregister.
Returns:
boolean
-true
if the instance exists and was successfully unregistered, otherwisefalse
.
Example:
let personJsonTable = new JsonTable('persons');
jsonTableDb.registerJsonTable(personJsonTable);
jsonTableDb.unregisterJsonTable(personJsonTable);