nolo-cli 0.143.0-alpha.1 → 0.145.0-alpha.1

package/node_modules/browser-level/UPGRADING.md

@@ -0,0 +1,143 @@
+# Upgrade Guide
+
+This document describes breaking changes and how to upgrade. For a complete list of changes including minor and patch releases, please refer to the [changelog](CHANGELOG.md).
+
+## 3.0.0
+
+This release upgrades to `abstract-level` 3. Please see its [upgrade guide](https://github.com/Level/abstract-level/blob/v3.0.0/UPGRADING.md).
+
+## 2.0.0
+
+This release upgrades to `abstract-level` 2 which adds [hooks](https://github.com/Level/abstract-level#hooks) and drops callbacks and not-found errors. Please refer to the [upgrade guide of `abstract-level`](https://github.com/Level/abstract-level/blob/v2.0.0/UPGRADING.md) for details.
+
+## 1.0.0
+
+**Introducing `browser-level`: a fork of [`level-js`](https://github.com/Level/level-js) that removes the need for [`levelup`](https://github.com/Level/levelup) and more. It implements the [`abstract-level`](https://github.com/Level/abstract-level) interface instead of [`abstract-leveldown`](https://github.com/Level/abstract-leveldown) and thus has the same API as `level` and `levelup` including encodings, promises and events. In addition, you can now choose to use Uint8Array instead of Buffer. Sublevels are builtin.**
+
+We've put together several upgrade guides for different modules. See the [FAQ](https://github.com/Level/community#faq) to find the best upgrade guide for you. This one describes how to replace `level-js` with `browser-level`. There will be a separate guide for `level`.
+
+### What is not covered here
+
+If you are using any of the following, please also read the upgrade guide of [`abstract-level@1`](https://github.com/Level/abstract-level/blob/main/UPGRADING.md#100) which goes into more detail about these:
+
+- Specific error messages (replaced with error codes)
+- The `db.iterator().end()` method (renamed to `close()`, with `end()` as an alias)
+- Zero-length keys and range options (now valid)
+- The `db.supports.bufferKeys` property.
+
+### Changes to initialization
+
+We started using classes, which means using `new` is now required. If you previously did:
+
+```js
+const levelJs = require('level-js')
+const db = levelJs('example')
+```
+
+You must now do:
+
+```js
+const { BrowserLevel } = require('browser-level')
+const db = new BrowserLevel('example')
+```
+
+Arguments and options are the same except that `browser-level` has additional options to control encodings. For backwards compatibility, the `prefix` option has the same default value. Namely `'level-js-'`.
+
+### There is only encodings
+
+The `asBuffer`, `valueAsBuffer` and `keyAsBuffer` options have been replaced with encoding options. The default encoding is `'utf8'` which means operations return strings rather than Buffers by default. If you previously did:
+
+```js
+db.get('example', { asBuffer: false }, callback)
+db.get('example', callback)
+```
+
+You must now do:
+
+```js
+db.get('example', callback)
+db.get('example', { valueEncoding: 'buffer' }, callback)
+```
+
+Or using promises (new):
+
+```js
+const str = await db.get('example')
+const buf = await db.get('example', { valueEncoding: 'buffer' })
+```
+
+Or using Uint8Array (new):
+
+```js
+const arr = await db.get('example', { valueEncoding: 'view' })
+```
+
+### Uint8Array support
+
+A `browser-level` database uses Uint8Array internally, instead of Buffer like `level-js` did. This doesn't change the ability to read existing databases: `browser-level` can read and write databases that were created with `level-js` and vice versa. Externally both Uint8Array and Buffer can be used (see README for details) to maintain backwards- and ecosystem compatibility. You can choose to use Uint8Array exclusively and omit the `buffer` shim from a JavaScript bundle (through configuration of Webpack, Browserify or other bundlers).
+
+### Unwrapping the onion
+
+If you were wrapping `level-js` with `levelup`, `encoding-down` and / or `subleveldown`, remove those modules. If you previously did:
+
+```js
+const levelJs = require('level-js')
+const levelup = require('levelup')
+const enc = require('encoding-down')
+const subleveldown = require('subleveldown')
+
+const db = levelup(enc(levelJs('example')))
+const sublevel = subleveldown(db, 'foo')
+```
+
+You must now do:
+
+```js
+const { BrowserLevel } = require('browser-level')
+const db = new BrowserLevel('example')
+const sublevel = db.sublevel('foo')
+```
+
+### Prefers backpressure over snapshot guarantees
+
+Previously (in `level-js`) an iterator would keep reading in the background, so as to keep the underlying IndexedDB transaction alive and thus not see the data of simultaneous writes. I.e. it was reading from a snapshot in time. This had two major downsides. It was not possible to lazily iterate a large database, as all of the data would be read into memory. Secondly, IndexedDB doesn't actually use a snapshot (the Chrome implementation used to, others never did) but rather a blocking transaction. Meaning you couldn't write to a database while an iterator was active; the write would wait for the iterator to end.
+
+To solve those issues, an iterator now reads a few entries ahead and then opens a new transaction on the next read. A "few" means all entries for `iterator.all()`, `size` amount of entries for `iterator.nextv(size)` and a hardcoded 100 entries for `iterator.next()`. Individual calls to those methods still have snapshot guarantees, but repeated calls do not.
+
+The resulting breaking change is that an iterator will include the data of simultaneous writes, if `db.put()`, `db.del()` or `db.batch()` are called in between creating the iterator and consuming the iterator, or in between calls to `iterator.next()` or `iterator.nextv()`. For example:
+
+```js
+const iterator = db.iterator()
+await db.put('abc', '123')
+
+for await (const [key, value] of iterator) {
+  // This might be 'abc'
+  console.log(key)
+}
+```
+
+To reflect the new behavior, `db.supports.snapshots` is now false. If snapshot guarantees are a must for your application then use `iterator.all()` (which is a new method compared to `level-js`) and call it immediately after creating the iterator:
+
+```js
+const entries = await db.iterator({ limit: 50 }).all()
+
+// Synchronously iterate the result
+for (const [key, value] of entries) {
+  console.log(key)
+}
+```
+
+Unrelated, iterating should now be faster because `browser-level` iterators use the `getAll()` and `getAllKeys()` methods of IndexedDB, instead of a cursor like `level-js` did. This means multiple entries are transferred from IndexedDB to JS in a single turn of the JS event loop, rather than one turn per entry. Reverse iterators do still use a cursor and are therefor slower.
+
+Lastly, the new logic enabled us to implement and fully support `iterator.seek()`.
+
+### Changes to lesser-used properties and methods
+
+- The `db.prefix` property of `level-js`, conflicting with the `db.prefix` property of sublevels, has been renamed to `db.namePrefix`. The relevant constructor option (`prefix`) remains the same.
+- The `db.location`, `db.version` and `db.db` properties are now read-only getters
+- The internal `db.store()` and `db.await()` methods are no longer accessible
+- The `db.upgrade()` utility for upgrading from v4.x to v5.x has been removed.
+
+---
+
+_For earlier releases, before `browser-level` was forked from `level-js` (v6.1.0), please see [the upgrade guide of `level-js`](https://github.com/Level/level-js/blob/HEAD/UPGRADING.md)._

package/node_modules/browser-level/index.d.ts

@@ -0,0 +1,108 @@
+import {
+  AbstractLevel,
+  AbstractDatabaseOptions,
+  AbstractOpenOptions,
+  AbstractGetOptions,
+  AbstractGetManyOptions,
+  AbstractPutOptions,
+  AbstractDelOptions,
+  AbstractBatchOptions,
+  AbstractChainedBatch,
+  AbstractIterator,
+  AbstractKeyIterator,
+  AbstractValueIterator,
+  AbstractIteratorOptions,
+  AbstractKeyIteratorOptions,
+  AbstractValueIteratorOptions,
+  AbstractBatchOperation
+} from 'abstract-level'
+
+/**
+ * An {@link AbstractLevel} database for browsers, backed by [IndexedDB][1].
+ *
+ * @template KDefault The default type of keys if not overridden on operations.
+ * @template VDefault The default type of values if not overridden on operations.
+ *
+ * [1]: https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API
+ */
+export class BrowserLevel<KDefault = string, VDefault = string>
+  extends AbstractLevel<Uint8Array, KDefault, VDefault> {
+  /**
+   * Database constructor.
+   *
+   * @param location The name of the [`IDBDatabase`](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase)
+   * to be opened, as well as the name of the object store within that database. The name
+   * of the `IDBDatabase` will be prefixed with {@link DatabaseOptions.prefix}.
+   * @param options Options, of which some will be forwarded to {@link open}.
+   */
+  constructor (location: string, options?: DatabaseOptions<KDefault, VDefault> | undefined)
+
+  /**
+   * Location that was passed to the constructor.
+   */
+  get location (): string
+
+  /**
+   * Database name prefix that was passed to the constructor (as `prefix`).
+   */
+  get namePrefix (): string
+
+  /**
+   * Version that was passed to the constructor.
+   */
+  get version (): number
+
+  /**
+   * Delete the IndexedDB database at the given {@link location}.
+   */
+  static destroy (location: string): Promise<void>
+  static destroy (location: string, prefix: string): Promise<void>
+}
+
+/**
+ * Options for the {@link BrowserLevel} constructor.
+ */
+export interface DatabaseOptions<K, V> extends AbstractDatabaseOptions<K, V> {
+  /**
+   * Prefix for the `IDBDatabase` name. Can be set to an empty string.
+   *
+   * @defaultValue `'level-js-'`
+   */
+  prefix?: string
+
+  /**
+   * The version to open the `IDBDatabase` with.
+   *
+   * @defaultValue `1`
+   */
+  version?: number | string
+
+  /**
+   * An {@link AbstractLevel} option that has no effect on {@link BrowserLevel}.
+   */
+  createIfMissing?: boolean
+
+  /**
+   * An {@link AbstractLevel} option that has no effect on {@link BrowserLevel}.
+   */
+  errorIfExists?: boolean
+}
+
+// Export types so that consumers don't have to guess whether they're extended
+export type OpenOptions = AbstractOpenOptions
+export type GetOptions<K, V> = AbstractGetOptions<K, V>
+export type GetManyOptions<K, V> = AbstractGetManyOptions<K, V>
+export type PutOptions<K, V> = AbstractPutOptions<K, V>
+export type DelOptions<K> = AbstractDelOptions<K>
+
+export type BatchOptions<K, V> = AbstractBatchOptions<K, V>
+export type BatchOperation<TDatabase, K, V> = AbstractBatchOperation<TDatabase, K, V>
+export type ChainedBatch<TDatabase, K, V> = AbstractChainedBatch<TDatabase, K, V>
+
+export type Iterator<TDatabase, K, V> = AbstractIterator<TDatabase, K, V>
+export type KeyIterator<TDatabase, K> = AbstractKeyIterator<TDatabase, K>
+export type ValueIterator<TDatabase, K, V> = AbstractValueIterator<TDatabase, K, V>
+
+export type IteratorOptions<K, V> = AbstractIteratorOptions<K, V>
+export type KeyIteratorOptions<K> = AbstractKeyIteratorOptions<K>
+export type ValueIteratorOptions<K, V> = AbstractValueIteratorOptions<K, V>

package/node_modules/browser-level/index.js

@@ -0,0 +1,323 @@
+/* global indexedDB */
+
+'use strict'
+
+const { AbstractLevel } = require('abstract-level')
+const { Iterator } = require('./iterator')
+const deserialize = require('./util/deserialize')
+const clear = require('./util/clear')
+const createKeyRange = require('./util/key-range')
+
+// Keep as-is for compatibility with existing level-js databases
+const DEFAULT_PREFIX = 'level-js-'
+
+const kIDB = Symbol('idb')
+const kNamePrefix = Symbol('namePrefix')
+const kLocation = Symbol('location')
+const kVersion = Symbol('version')
+const kStore = Symbol('store')
+const kOnComplete = Symbol('onComplete')
+
+class BrowserLevel extends AbstractLevel {
+  constructor (location, options) {
+    const { prefix, version, ...forward } = options || {}
+
+    super({
+      encodings: { view: true },
+      snapshots: false,
+      createIfMissing: false,
+      errorIfExists: false,
+      seek: true,
+      has: true,
+      getSync: false
+    }, forward)
+
+    if (typeof location !== 'string' || location === '') {
+      throw new TypeError("The first argument 'location' must be a non-empty string")
+    }
+
+    // TODO (next major): remove default prefix
+    this[kLocation] = location
+    this[kNamePrefix] = prefix == null ? DEFAULT_PREFIX : prefix
+    this[kVersion] = parseInt(version || 1, 10)
+    this[kIDB] = null
+  }
+
+  get location () {
+    return this[kLocation]
+  }
+
+  get namePrefix () {
+    return this[kNamePrefix]
+  }
+
+  get version () {
+    return this[kVersion]
+  }
+
+  // Exposed for backwards compat and unit tests
+  get db () {
+    return this[kIDB]
+  }
+
+  get type () {
+    return 'browser-level'
+  }
+
+  async _open (options) {
+    const request = indexedDB.open(this[kNamePrefix] + this[kLocation], this[kVersion])
+
+    request.onupgradeneeded = (ev) => {
+      const db = ev.target.result
+
+      if (!db.objectStoreNames.contains(this[kLocation])) {
+        db.createObjectStore(this[kLocation])
+      }
+    }
+
+    return new Promise((resolve, reject) => {
+      request.onerror = function () {
+        reject(request.error || new Error('unknown error'))
+      }
+
+      request.onsuccess = () => {
+        this[kIDB] = request.result
+        resolve()
+      }
+    })
+  }
+
+  [kStore] (mode) {
+    const transaction = this[kIDB].transaction([this[kLocation]], mode)
+    return transaction.objectStore(this[kLocation])
+  }
+
+  [kOnComplete] (request) {
+    const transaction = request.transaction
+
+    return new Promise(function (resolve, reject) {
+      // Take advantage of the fact that a non-canceled request error aborts
+      // the transaction. I.e. no need to listen for "request.onerror".
+      transaction.onabort = function () {
+        reject(transaction.error || new Error('aborted by user'))
+      }
+
+      transaction.oncomplete = function () {
+        resolve(request.result)
+      }
+    })
+  }
+
+  async _get (key, options) {
+    const store = this[kStore]('readonly')
+    const request = store.get(key)
+    const value = await this[kOnComplete](request)
+
+    return deserialize(value)
+  }
+
+  async _getMany (keys, options) {
+    const store = this[kStore]('readonly')
+    const iterator = keys.values()
+
+    // Consume the iterator with N parallel worker bees
+    const n = Math.min(16, keys.length)
+    const bees = new Array(n)
+    const values = new Array(keys.length)
+
+    let keyIndex = 0
+    let abort = false
+
+    const bee = async function () {
+      try {
+        for (const key of iterator) {
+          if (abort) break
+
+          const valueIndex = keyIndex++
+          const request = store.get(key)
+
+          await new Promise(function (resolve, reject) {
+            request.onsuccess = () => {
+              values[valueIndex] = deserialize(request.result)
+              resolve()
+            }
+
+            request.onerror = (ev) => {
+              ev.stopPropagation()
+              reject(request.error)
+            }
+          })
+        }
+      } catch (err) {
+        abort = true
+        throw err
+      }
+    }
+
+    for (let i = 0; i < n; i++) {
+      bees[i] = bee()
+    }
+
+    await Promise.allSettled(bees)
+    return values
+  }
+
+  async _has (key, options) {
+    const store = this[kStore]('readonly')
+    const request = store.count(key)
+    const count = await this[kOnComplete](request)
+
+    return count === 1
+  }
+
+  async _hasMany (keys, options) {
+    const store = this[kStore]('readonly')
+    const iterator = keys.values()
+
+    // Consume the iterator with N parallel worker bees
+    const n = Math.min(16, keys.length)
+    const bees = new Array(n)
+    const results = new Array(keys.length)
+
+    let keyIndex = 0
+    let abort = false
+
+    const bee = async function () {
+      try {
+        for (const key of iterator) {
+          if (abort) break
+
+          const resultIndex = keyIndex++
+          const request = store.count(key)
+
+          await new Promise(function (resolve, reject) {
+            request.onsuccess = () => {
+              results[resultIndex] = request.result === 1
+              resolve()
+            }
+
+            request.onerror = (ev) => {
+              ev.stopPropagation()
+              reject(request.error)
+            }
+          })
+        }
+      } catch (err) {
+        abort = true
+        throw err
+      }
+    }
+
+    for (let i = 0; i < n; i++) {
+      bees[i] = bee()
+    }
+
+    await Promise.allSettled(bees)
+    return results
+  }
+
+  async _del (key, options) {
+    const store = this[kStore]('readwrite')
+    const request = store.delete(key)
+
+    return this[kOnComplete](request)
+  }
+
+  async _put (key, value, options) {
+    const store = this[kStore]('readwrite')
+
+    // Will throw a DataError or DataCloneError if the environment
+    // does not support serializing the key or value respectively.
+    const request = store.put(value, key)
+
+    return this[kOnComplete](request)
+  }
+
+  // TODO: implement key and value iterators
+  _iterator (options) {
+    return new Iterator(this, this[kLocation], options)
+  }
+
+  async _batch (operations, options) {
+    const store = this[kStore]('readwrite')
+    const transaction = store.transaction
+    let index = 0
+    let error
+
+    const promise = new Promise(function (resolve, reject) {
+      transaction.onabort = function () {
+        reject(error || transaction.error || new Error('aborted by user'))
+      }
+
+      transaction.oncomplete = resolve
+    })
+
+    // Wait for a request to complete before making the next, saving CPU.
+    function loop () {
+      const op = operations[index++]
+      const key = op.key
+
+      let req
+
+      try {
+        req = op.type === 'del' ? store.delete(key) : store.put(op.value, key)
+      } catch (err) {
+        error = err
+        transaction.abort()
+        return
+      }
+
+      if (index < operations.length) {
+        req.onsuccess = loop
+      } else if (typeof transaction.commit === 'function') {
+        // Commit now instead of waiting for auto-commit
+        transaction.commit()
+      }
+    }
+
+    loop()
+    return promise
+  }
+
+  async _clear (options) {
+    let keyRange
+
+    try {
+      keyRange = createKeyRange(options)
+    } catch (e) {
+      // The lower key is greater than the upper key.
+      // IndexedDB throws an error, but we'll just do nothing.
+      return
+    }
+
+    if (options.limit >= 0) {
+      // IDBObjectStore#delete(range) doesn't have such an option.
+      // Fall back to cursor-based implementation.
+      return clear(this, this[kLocation], keyRange, options)
+    }
+
+    const store = this[kStore]('readwrite')
+    const request = keyRange ? store.delete(keyRange) : store.clear()
+
+    return this[kOnComplete](request)
+  }
+
+  async _close () {
+    this[kIDB].close()
+  }
+}
+
+BrowserLevel.destroy = async function (location, prefix) {
+  if (prefix == null) {
+    prefix = DEFAULT_PREFIX
+  }
+
+  const request = indexedDB.deleteDatabase(prefix + location)
+
+  return new Promise(function (resolve, reject) {
+    request.onsuccess = resolve
+    request.onerror = reject
+  })
+}
+
+exports.BrowserLevel = BrowserLevel