Skip to content

Latest commit

 

History

History
312 lines (226 loc) · 11.1 KB

README.md

File metadata and controls

312 lines (226 loc) · 11.1 KB
Raw

level-supports

Create a manifest describing the abilities of an abstract-level database. No longer compatible with levelup or abstract-leveldown since version 3.0.0.

level badge npm Node version Test Coverage Standard Common Changelog Donate

Usage

const { supports } = require('level-supports')

db.supports = supports({
  permanence: false,
  encodings: {
    utf8: true
  }
})

Receivers of the db can then use it like so:

if (!db.supports.permanence) {
  throw new Error('Persistent storage is required')
}

API

manifest = supports([manifest, ..])

Given zero or more manifest objects, returns a merged and enriched manifest object that has truthy properties for each of the features listed below.

For future extensibility, the properties are truthy rather than strictly typed booleans. Falsy or absent properties are converted to false, other values are allowed:

supports().snapshots // false
supports({ snapshots: true }).snapshots // true
supports({ snapshots: {} }).snapshots // {}
supports({ snapshots: 1 }, { snapshots: 2 }).snapshots // 2

For consumers of the manifest this means they should check support like so:

if (db.supports.snapshots)

Rather than:

if (db.supports.snapshots === true)

Note: the manifest describes high-level features that typically encompass multiple methods of a db. It is currently not a goal to describe a full API, or versions of it.

Features

snapshots (boolean)

Does the database have snapshot guarantees? Meaning that reads are unaffected by simultaneous writes. For example, an iterator should read from a snapshot of the database, created at the time db.iterator() was called. This means the iterator will not see the data of simultaneous write operations.

Must be false if any of the following is true:

  • Reads don't operate on a snapshot
  • Snapshots are created asynchronously.
Support matrix
Module Snapshot guarantee
classic-level ✅
memory-level ✅
browser-level ❌
rocks-level ✅
leveldown ✅
rocksdb ✅
memdown ✅
level-js ✅ (by buffering)
encoding-down ✅
deferred-leveldown ✅
levelup ✅
level-packager ✅
level ✅
level-mem ✅
level-rocksdb ✅
subleveldown ✅
multileveldown ✅ (unless retry is true)
level-party ❌ (unless retry is false)

permanence (boolean)

Does data survive after process (or environment) exit? Typically true. False for memory-level and memdown.

seek (boolean)

Do iterators support seek(..)?

Support matrix
Module Support
abstract-level ✅ 1.0.0
classic-level ✅ 1.0.0
memory-level ✅ 1.0.0
browser-level ✅ 1.0.0
rocks-level ✅ 1.0.0
abstract-leveldown ✅ 6.0.0
leveldown ✅ 1.2.0
rocksdb ✅ 1.0.0
memdown ✅ 4.1.0
level-js ❌
encoding-down ✅ 6.1.0
deferred-leveldown ✅ 5.1.0
levelup ✅ n/a
level-packager ✅ n/a
level ✅ 8.0.0
level-mem ✅ 4.0.0
level-rocksdb ✅ 1.0.0
subleveldown ✅ 4.1.0
multileveldown ❌
level-party ❌

deferredOpen (boolean)

Can operations like db.put() be called without explicitly opening the db? Like so:

const db = new Level()
await db.put('key', 'value')

Always true since abstract-level@1.

createIfMissing, errorIfExists (boolean)

Does db.open() support these options?

Support matrix
Module Support
classic-level ✅
rocks-level ✅
memory-level ❌
browser-level ❌
leveldown ✅
rocksdb ✅
memdown ❌
level-js ❌

events (object)

Which events does the database emit, as indicated by nested properties? For example:

if (db.supports.events.put) {
  db.on('put', listener)
}

streams (boolean)

Does database have the methods createReadStream, createKeyStream and createValueStream, following the API documented in levelup? For abstract-level databases, a standalone module called level-read-stream is available.

Support matrix
Module Support
abstract-level and dependents ❌
abstract-leveldown and dependents ❌
levelup ✅
level-packager ✅
level ✅
level-mem ✅
level-rocksdb ✅
subleveldown ✅
multileveldown ✅
level-party ✅

encodings (object)

Which encodings (by name) does the database support, as indicated by nested properties? For example:

{ utf8: true, json: true }

As the encodings property cannot be false (anymore, since level-supports v3.0.0) it implies that the database supports keyEncoding and valueEncoding options on all relevant methods, uses a default encoding of utf8 and that hence all of its read operations return strings rather than buffers by default.

Support matrix (general support)

This matrix just indicates general support of encodings as a feature, not that the listed modules support the encodings property exactly as described above, which only works on abstract-level databases.

Module Support
abstract-level (and dependents) ✅
abstract-leveldown (and dependents) ❌
encoding-down ✅
levelup ✅
level-packager ✅
level ✅
level-mem ✅
level-rocksdb ✅
subleveldown ✅
multileveldown ✅
level-party ✅
Support matrix (specific encodings)

This matrix lists which encodings are supported as indicated by e.g. db.supports.encodings.utf8. Encodings that encode to another (like how 'json' encodes to 'utf8') are excluded here, though they are present in db.supports.encodings.

Module 'utf8' 'buffer' 'view'
classic-level ✅ ✅ ✅ 1
memory-level ✅ 2 ✅ 2 ✅ 2
browser-level ✅ 1 ✅ 1 ✅
rocks-level ✅ ✅ ✅ 1
level@8 ✅ 3 ✅ 3 ✅ 3
  1. Transcoded (which may have a performance impact).
  2. Can be controlled via storeEncoding option.
  3. Whether it's transcoded depends on environment (Node.js or browser).

additionalMethods (object)

Declares support of additional methods, that are not part of the abstract-level interface. In the form of:

{
  foo: true,
  bar: true
}

Which says the db has two methods, foo and bar. It might be used like so:

if (db.supports.additionalMethods.foo) {
  db.foo()
}

For future extensibility, the properties of additionalMethods should be taken as truthy rather than strictly typed booleans. We may add additional metadata (see #1).

signals (object)

Which methods or method groups take a signal option? At the time of writing there is only one method group: iterators. This includes db.iterator(), db.keys() and db.values(). For example:

if (db.supports.signals.iterators) {
  const ac = new AbortController()
  const iterator = db.keys({ signal: ac.signal })

  ac.abort()
}

Install

With npm do:

npm install level-supports

Contributing

Level/supports is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the Contribution Guide for more details.

Donate

Support us with a monthly donation on Open Collective and help us continue our work.

License

MIT