Requirements for manifests
vweevers opened this issue · 5 comments
I felt the need to defragment various threads:
- Detect presence of
approximateSize
: Level/deferred-leveldown#35 and Level/abstract-leveldown#8 - Get an underlying
db
with a certaintype
: Level/subleveldown#34 - Exposing sublevels to clients: Level/subleveldown#35
- Various: Level/levelup#279
Prior art:
level-manifest
(used bymultilevel
but notmultileveldown
)
Requirements:
- Manifests must be objects (established in Level/levelup#279)
- Declare high-level features as booleans:
- snapshot guarantees (use case: tests, consumers that require consistency)
- exclusive access (use case: live streams, prehooks) (see Level/levelup#279)
- binary keys (use case: tests, deciding on a network transport)
- permanence (use case: packager tests)
- seeking (use case: tests, multiget, skip scans)
- Declare additional methods and properties (that are not part of the abstract API)
- Examples:
approximateSize()
(use case: defer/proxy/expose)- sublevels (use case: exposing them to clients)
- Declare name, return type, sync/callback/promise
- Examples:
- Nice to have: use manifests the other way around, to declare features that a plugin wants
Open questions:
- Should manifests extend manifests from underlying downs? Note that underlying downs can be swapped at runtime.
- In some cases, feature support depends on the runtime environment too. E.g. not all browsers support binary keys in
level-js
. Is that something we want to expose?
Should manifests extend manifests from underlying downs? Note that underlying downs can be swapped at runtime.
Let's take db.clear()
as an example, and a few different db's.
level-party
db
It may or may not have db.clear()
depending on:
- Whether
db
is the leader (backed byleveldown
) or follower (backed by amultileveldown
client) - Whether
db
is open (it's underlying db may be wrapped indeferred-leveldown
) - Whether
db
is wrapped insubleveldown
(in which case, see below)
In this case, it must be level-party
that defines the (hardcoded) manifest, and can include clear
in the manifest if all its dependencies support it.
subleveldown
db
It may or may not have db.clear()
depending on:
- Whether its input db has
clear()
(if we refactorsubleveldown
to unwrap the db early on, in its constructor, then we have the necessary info) - Whether it depends on
"abstract-leveldown": "^6.0.2"
but doesn't implementclear
itself and therefor incorrectly deletes all entries of the input db (this is currently the case, and something that would be solved by a manifest)
Here as well, it must be subleveldown
that defines the manifest, with the added limitation that the manifest cannot be "static" - as in require('subleveldown').manifest
.
We can start off simple, with a manifest object that has boolean properties, where each property describes a known feature. We can later handle custom features.
That's a smaller scope than e.g. level-manifest
which describes methods of a db and their "type" (readable, writable, sync or async).
In other words, when our manifest lists a feature like { clear: true }
) it is assumed to mean that the db has a clear()
method with the "standard" function signature.
We can later extend the format into { clear: { whatever } }
.
So to be future-proof, I'll rephrase: we can start off with a manifest object has truthy properties.
In some cases, feature support depends on the runtime environment too. E.g. not all browsers support binary keys in
level-js
. Is that something we want to expose?
Yes, and we can. We already feature-detect binary keys so we can just put the result of that in the manifest.
Ooh. We can also add levelup
features like deferredOpen
to the manifest. That could make merging levelup
and abstract-leveldown
smoother. E.g. we can implement deferred open in abstract-leveldown
, have it declare supports.deferredOpen = true
, then in levelup
we'll do:
if (db.supports.deferredOpen) {
// Use directly
} else {
// Wrap with deferred-leveldown
}
Additional requirements can be discussed in https://github.com/Level/supports.
For overall progress, see #83.