@naturalcycles/db-lib
Advanced tools
Lowest Common Denominator API to supported Databases
Defines 3 things:
CommonDB interfaceCommonDao classDBQuery classCommonDB serves as a Lowest Commond Denominator between different DB implementations (see further).
So you can use same syntax, e.g getById<DBM>(id: string): Promise<DBM | undefined> across
different DBs.
DBQuery allows to use the same query syntax across different DBs! E.g:
const q = DBQuery.create('table1')
.filterEq('type', 'cat')
.filter('updated', '>', '2019-01-17')
.order('name', true)
await db.runQuery(q)
So, you can run it against Datastore, Firestore, Redis, MongoDB, Airtable, etc. Different DBs, same syntax!
You can swap DB implementations without changing your application code. Migrate Datastore to Firestore? Easy.
You can test your code against InMemoryDB (that implements full CommonDB interface, even with
querying, streaming, etc). So, your unit tests can use exactly same querying syntax, or even exactly
same services, DAOs. Just swap real DB with InMemoryDB in your setupJest.ts (for example).
idscreated, updated (unix timestamps)2019-06-21CommonDB is a low-level API (no high-level sugar-syntax). CommonDao is the opposite - a high-level API (with convenience methods), built on top of CommonDB.
Concerns of CommonDB:
Concerns of CommonDao:
id, created, updated fieldsping(): Promise<void>
Call this to check that DB connection, credentials, configuration is working. Should throw an error if any of above is invalid.
getByIds<DBM>(table: string, ids: string[]): Promise<DBM[]>
await db.getByIds('table1', ['id1, 'id2'])
// [ { id: 'id1', ... }, { id: 'id2', ... } ]
Should return items in the same order as ids in the input.
Only returns items that are found, does not return undefined (absent) items.
runQuery<DBM>(q: DBQuery<DBM>): Promise<RunQueryResult<DBM>>
const q = DBQuery.create('table1').filterEq('type', 'cat').order('name', true) // desc
await db.runQuery(q)
// { records: [ { ... }, { ... }, ... ] }
runQueryCount(q: DBQuery): Promise<number>
await db.runQuery(DBQuery.create('table1'))
// 5
streamQuery<DBM>(q: DBQuery<DBM>): ReadableTyped<DBM>
Returns ReadableTyped (typed wrapper of Node.js
Readable).
Streams in Node.js support back-pressure by default (if piped properly by the consumer).
const q = DBQuery.create('table1') // "return all items" query
await _pipeline([
db.streamQuery(q),
writableForEach(item => {
console.log(item)
}),
])
// { item1 }
// { item2 }
// ...
saveBatch<DBM>(table: string, dbms: DBM[]): Promise<void>
Since CommonDB is a "minimal API", there's no save method for a single item, only for multiple. Pass an array with single item to save just one item.
const items = [
{ item1 },
{ item2 },
]
await db.saveBatch('table1', items) // returns void
await db.runQuery(DBQuery.create('table1') // "get all" query
// [ { item1 }, { item2 } ]
deleteByIds(table: string, ids: string[]): Promise<number>
Returns number of deleted items (not all CommonDB implementations support that).
await db.deleteByIds('table1', ['id1', 'id2'])
// 2
deleteByQuery(q: DBQuery): Promise<number>
Returns number of deleted items.
await db.deleteByQuery(DBQuery.create('table1'))
// 2
getTables(): Promise<string[]>
await db.getTables()
// [ 'table1', 'table2' ]
getTableSchema(table: string): Promise<JsonSchemaObject>
await db.getTableSchema('table1')
Returns a JsonSchema, generated from the table.
createTable(table: string, schema: JsonSchemaObject): Promise<void>
Applicable to Relational DBs, like MySQL. Will invoke smth like create table Table1 ... ;. Takes a
JsonSchema as an argument.
Object that defines "DB Query".
// Simplest query - "get all" query
DBQuery.create('table1')
// where type = "cat"
DBQuery.create('table1').filter('type', '==', 'cat')
// OR
DBQuery.create('table1').filterEq('type', 'cat')
// Where updated > 2019-01-17
DBQuery.create('table1').filter('updated', '>', '2019-01-17')
// order by 'name'
DBQuery.create('table1').filter('updated', '>', '2019-01-17').order('name')
// order by 'name' in descending order
DBQuery.create('table1').filter('updated', '>', '2019-01-17').order('name', true)
Features:
.filter('updatedDate', '>', '2019-01-17')
.filterEq('updated', true)
.order('updated') // asc
.order('updated', true) // desc
.limit(1000)
.limit(0) // no limit
Allows "projection queries" - queries that return subset of fields. Like select a,b,c from Table
in SQL, as opposed to select * from Table.
Passing empty array will actually return an array of empty objects (documented edge case).
.select([]) // returns [ {}, {}, {} ]
.select(['id']) //=> [ { id: 'id1' }, { id: 'id2' }, ... ]
/ root/adapter/file/adapter/cachedb/testing
/validation
engines.node >= LTSmain: dist/index.js: commonjs, es2020types: dist/index.d.ts: typescript types/src folder with source *.ts files includedFAQs
Lowest Common Denominator API to supported Databases
We found that @naturalcycles/db-lib demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.