lokijs-collections
v0.32.0
Published
TypeScript in-memory data collections based off LokiJS with data models, constraints (like primary keys and non-null fields), and collection change tracking
Downloads
13
Readme
LokiJS Collections
TypeScript port of lokiJS.
As of version 0.22.0
of this project, lokiJS is no longer a dependency and a [email protected]
is integrates directly into this project.
Usage
This project is designed to be imported using commonJs require(...)
calls.
To use this in a web app, it's currently setup to be required and then included in a bundle at build time.
Setup
Creating a database instance is the most involved task, once the database instance is created the rest is fairly straightfoward. You'll need a few things to create a lokijs-collection database:
- A database name
- Data models - one for each collection with schema information about the type of data being stored in each
- (optional) A database persister. You can use the DummyDataPersister in the 'test/' directory if you don't need to persist your data yet or aren't sure how a data persister works. You can use defaults for the rest of the settings, most of them work fine
1. Example - Creating an in-memory database instance:
var InMemDbImpl = require("lokijs-collections/db-collections/InMemDbImpl");
var ModelDefinitionsSet = require("lokijs-collections/data-models/ModelDefinitionsSet");
var DtoPropertyConverter = require("@twg2/ts-twg2-ast-codegen/code-types/DtoPropertyConverter");
var databaseName = "...";
// two collection schemas or models, enables a lot of cool TypeScript type checking, fewer bugs, and easy constraint setup (i.e. not-null, unique, auto-generated)
var dataModels = {
collection_1_name: {
properties: DtoPropertyConverter.parseAndConvertTemplateMap({
"id": { primaryKey: true, autoGenerate: true, type: "number" },
"name": { type: "string" },
"props": { type: "string[]" },
})
},
collection_2_name: {
properties: DtoPropertyConverter.parseAndConvertTemplateMap({
"userId": { type: "string" },
"note": { type: "string" },
"timestamp": { autoGenerate: true, type: "Date" },
})
}
};
// create the DB instance, there are a lot of configurable settings, this one is using a dummy data persister, everything is in-memory
var dbInst = new InMemDbImpl(databaseName,
{ readAllow: true, writeAllow: true, compressLocalStores: false },
"for-in-if",
"collection_meta_data", false,
ModelDefinitionsSet.fromCollectionModels(dataModels, null/*defaultDataTypes*/),
(collectionName) => { return { ... }; },
(obj, collection, dataModel) => {
return Object.keys(obj);
// or
return dataModel.fieldNames;
}
);
2. Example - Creating a WebSQL database persister:
Note: the WebSqlPersister
constructor has several parameters which are highly customizable, please read the class and constructor documentation for details.
var DbUtil = require("lokijs-collections/persisters/DbUtil");
var WebSqlSpi = require("lokijs-collections/persisters/WebSqlSpi");
var WebSqlPersister = require("lokijs-collections/persisters/WebSqlPersister");
// log to console or other error logger
var trace: WebSqlSpi.Trace = {
log: (...args: any[]) => ...,
error: (...args: any[]) => ...,
text: (...args: any[]) => ...,
};
var sqlInst = WebSqlSpi.newWebSqlDb("persistent-websql-database", null, null, null,
{ trace: trace, logVerbosity: DbUtil.logLevels.ERROR });
var persister = new WebSqlPersister(sqlInst,
trace,
() => dbInst.listCollections(),
(collName, data) => {
var coll = dbInst.getCollection(collName, true);
coll.insert(data);
return coll;
},
(itm) => InMemDbImpl.cloneCloneDelete(itm, true),
null,
null,
(err) => trace.error("storage error", err),
[],
[]
);
You now have a working in-memory database using TypeScript. You can skip Example #2 if you do not wish to persist the in-memory database between page/application reloads. Checkout the 'test/' directory for usage examples.
Project Structure
db-collections/
Contains 'DataCollection', a wrapper for a loki.js collection, add/remove/update functions modify the underlying loki.js collection. Also contains 'InMemDbImpl' which bridges the gap between an untyped loki.js instance and 'DataCollection'.
data-models/
ModelDefinitionsSet for creating and managing a group of DataCollectionModels using DtoModels or DataCollectionModels as a starting point.
change-trackers/
Collections and handlers for tracking lokijs collection changes (i.e. updates, additions, deletions).
key-constraints/
Collection meta-data and unique/primary key constraint handlers for 'DataCollection'. Includes:
PrimaryKeyMaintainer
for checking uniqueness of primary keys and/or generating numerical keys (i.e. 1, 2, 3, ...),NonNullKeyMaintainer
for checking that fields have values
persisters/
'DataPersister' implementations and helper classes for persisting and restoring in-memory databases. Currently provides a WebSQL persister with an alpha level IndexedDB persister.