Requirements for manifests

[vweevers]

I felt the need to defragment various threads:

• Detect presence of approximateSize: implement manifest functionality deferred-leveldown#35 and detecting approximateSize presence abstract-leveldown#8
• Get an underlying db with a certain type: Current functionality and the future (hoping on support for all use cases) subleveldown#34
• Exposing sublevels to clients: multilevel(down) and level-manifest compatibility subleveldown#35
• Various: isEmbedded() expose what sort of contract the leveldown can provide. levelup#279

Prior art:

• level-manifest (used by multilevel but not multileveldown)

Requirements:

• Manifests must be objects (established in isEmbedded() expose what sort of contract the leveldown can provide. 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 isEmbedded() expose what sort of contract the leveldown can provide. 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
• 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?

[vweevers]

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 by leveldown) or follower (backed by a multileveldown client)
• Whether db is open (it's underlying db may be wrapped in deferred-leveldown)
• Whether db is wrapped in subleveldown (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 refactor subleveldown 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 implement clear 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.

[vweevers]

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.

[vweevers]

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.

[vweevers]

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
}

[vweevers]

Additional requirements can be discussed in https://github.com/Level/supports.

For overall progress, see #83.