Level/levelup-2-API

https://github.com/Level/levelup

Special Notes

• What happened to db.createWriteStream()

levelup(db[, options[, callback]])

The main entry point for creating a new levelup instance.

创建新的levelup实例的主要入口

• db must be an abstract-leveldown compliant store. db必须是抽象leveldown兼容存储器
  
• options is passed on to the underlying store when opened and is specific to the type of store being used 在开启时options值被传递给其下面的存储器，并且指定被使用的存储器的类型
  

Calling levelup(db) will also open the underlying store. This is an asynchronous operation which will trigger your callback if you provide one. The callback should take the form function (err, db) {} where db is the levelup instance. If you don't provide a callback, any read & write operations are simply queued internally until the store is fully opened.

调用levelup(db)也将会开启底层存储器。这是个异步操作，如果你提供了回调函数将会被触发。这个回调将使用function (err, db) {}格式，db即levelup实例。如果你没有提供回调函数，任何读写操作将仅进行简单内部排序，直至存储器完全打开

This leads to two alternative ways of managing a levelup instance:

这将导致两种可选的处理levelup实例的方法：

levelup(leveldown(location), options, function (err, db) {
  if (err) throw err

  db.get('foo', function (err, value) {
    if (err) return console.log('foo does not exist')
    console.log('got foo =', value)
  })
})

Versus the equivalent:

与之相等的是：

// Will throw if an error occurs
var db = levelup(leveldown(location), options)

db.get('foo', function (err, value) {
  if (err) return console.log('foo does not exist')
  console.log('got foo =', value)
})

db.open([callback])

Opens the underlying store. In general you should never need to call this method directly as it's automatically called by levelup().

打开底层的存储器。通常来说，你应该不需要直接调用这个方法，因为它会自动被levelup()函数调用

However, it is possible to reopen the store after it has been closed with close(), although this is not generally advised.

可是，在被close()函数关闭后还是可以使用这个重启存储器的，虽然通常是不推荐使用的

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.close([callback])

close() closes the underlying store. The callback will receive any error encountered during closing as the first argument.

close()函数将关闭底层存储器。这个回调函数将收到在关闭时任何遇见的错误，并将其作为第一个参数

You should always clean up your levelup instance by calling close() when you no longer need it to free up resources. A store cannot be opened by multiple instances of levelup simultaneously.

在你不在需要levelup实例去释放资源时，你应该总是要通过调用 close()函数来清理它

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.put(key, value[, options][, callback])

put() is the primary method for inserting data into the store. Both key and value can be of any type as far as levelup is concerned.

put()函数是主要的插入数据到存储器的方法。key和value可为任意levelup包含的类型

options is passed on to the underlying store.

options值将会传递给底层的存储器

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.get(key[, options][, callback])

get() is the primary method for fetching data from the store. The key can be of any type. If it doesn't exist in the store then the callback or promise will receive an error. A not-found err object will be of type 'NotFoundError' so you can err.type == 'NotFoundError' or you can perform a truthy test on the property err.notFound.

get()函数是主要的从存储器中获取数据的方法。key值可以是任意类型。如果它不存在于存储器中，那么回调函数或promise将收到error。一个没有找到的错误将被定义为'NotFoundError'方法，所以你可以err.type == 'NotFoundError'或在属性err.notFound中执行一个可信的测试，如下

db.get('foo', function (err, value) {
  if (err) {
    if (err.notFound) {
      // handle a 'NotFoundError' here
      return
    }
    // I/O or other error, pass it up the callback chain
    return callback(err)
  }

  // .. handle `value` here
})

options is passed on to the underlying store.

options值将会传递给底层的存储器

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.del(key[, options][, callback])

del() is the primary method for removing data from the store.

del()是主要的从存储器中移除数据的方法

db.del('foo', function (err) {
  if (err)
    // handle I/O or other error
});

options is passed on to the underlying store.

options值将会传递给底层的存储器

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.batch(array[, options][, callback]) (array form)

batch() can be used for very fast bulk-write operations (both put and delete). The array argument should contain a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside the underlying store.

为了快速进行块写操作（如 put和delete操作），可以使用batch()函数。array参数应该包含顺序执行的操作序列，虽然在底层的存储器中他们被当作一个整体，即一个原子操作来执行

Each operation is contained in an object having the following properties: type, key, value, where the type is either 'put' or 'del'. In the case of 'del' the value property is ignored. Any entries with a key of null or undefined will cause an error to be returned on the callback and any type: 'put' entry with a value of null or undefined will return an error.

每一个被包含在对象中的操作都有这如下属性：type, key, value，type要么是put，要么是del。在del的情况下，value将会被忽略。任何带着key为null或undefined的条目将导致在callback函数中返回一个错误。而任何带着value为null或undefined的条目的type为put的操作将返回一个错误

var ops = [
  { type: 'del', key: 'father' },
  { type: 'put', key: 'name', value: 'Yuri Irsenovich Kim' },
  { type: 'put', key: 'dob', value: '16 February 1941' },
  { type: 'put', key: 'spouse', value: 'Kim Young-sook' },
  { type: 'put', key: 'occupation', value: 'Clown' }
]

db.batch(ops, function (err) {//即进行批处理
  if (err) return console.log('Ooops!', err)
  console.log('Great success dear leader!')
})

options is passed on to the underlying store.

options值将会传递给底层的存储器

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.batch() (chained form)

batch(), when called with no arguments will return a Batch object which can be used to build, and eventually commit, an atomic batch operation. Depending on how it's used, it is possible to obtain greater performance when using the chained form of batch() over the array form.

batch()函数当不带着参数调用时将返回一个用于构建的Batch对象，并且最后将提交一个原子批处理操作。当使用batch()的链接形式来覆盖其数组格式时，获取更高的性能是有可能的，这将取决于它是怎么使用的

db.batch()
  .del('father')
  .put('name', 'Yuri Irsenovich Kim')
  .put('dob', '16 February 1941')
  .put('spouse', 'Kim Young-sook')
  .put('occupation', 'Clown')
  .write(function () { console.log('Done!') })

batch.put(key, value)

Queue a put operation on the current batch, not committed until a write() is called on the batch.

在当前的batch对象下排序一个put操作，不提交，直至write()函数被调用

This method may throw a WriteError if there is a problem with your put (such as the value being null or undefined).

如果这里带着put函数的问题（如value值为null或undefined），这个方法将抛出一个WriteError

batch.del(key)

Queue a del operation on the current batch, not committed until a write() is called on the batch.

在当前的batch对象下排序一个del操作，不提交，直至write()函数被调用

This method may throw a WriteError if there is a problem with your delete.

如果这里带着delete操作的问题，这个方法将抛出一个WriteError

batch.clear()

Clear all queued operations on the current batch, any previous operations will be discarded.

在当前的batch对象下清理所有排序操作，任何以前的操作将被抛弃

batch.length

The number of queued operations on the current batch.

在当前的batch对象下排序的操作数目

batch.write([options][, callback])

Commit the queued operations for this batch. All operations not cleared will be written to the underlying store atomically, that is, they will either all succeed or fail with no partial commits.

提交batch对象中排序的操作。所有没有没清除的操作将会被自动写到底层的存储器中，这个操作要么全部成功要么是没有部分提交的失败

The optional options object is passed to the .write() operation of the underlying batch object.

可选的options对象被传递给底层的batch对象的.write()操作

If no callback is passed, a promise is returned.

如果没有传递回调函数，将返回promise

db.isOpen()

A levelup instance can be in one of the following states:

levelup实例可能是如下的几种状态之一：

• "new" - newly created, not opened or closed 新创建的，没被打开或关闭过
  
• "opening" - waiting for the underlying store to be opened 等待底层的存储器被打开
  
• "open" - successfully opened the store, available for use 成功打开存储器，可以使用
  
• "closing" - waiting for the store to be closed 等待存储器被关闭
  
• "closed" - store has been successfully closed, should not be used 存储器被成功关闭，不应该被使用
  

isOpen() will return true only when the state is "open".

isOpen()函数将只在状态为"open"时返回true

db.isClosed()

See isOpen() 有关状态的说法看isOpen()

isClosed() will return true only when the state is "closing" or "closed", it can be useful for determining if read and write operations are permissible.

isClosed()函数将只在状态为 "closing"或"closed"时返回true，它可以被用于决定是否读写操作被允许

db.createReadStream([options])

Returns a Readable Stream of key-value pairs. A pair is an object with key and value properties. By default it will stream all entries in the underlying store from start to end. Use the options described below to control the range, direction and results.

返回一个键值对的可读流。一对是一个带着key和value属性的对象。默认情况下，它将从头到尾流遍底层存储中的所有条目。使用下面描述的options去控制范围、方向和结果。

db.createReadStream()
  .on('data', function (data) {
    console.log(data.key, '=', data.value)
  })
  .on('error', function (err) {
    console.log('Oh my!', err)
  })
  .on('close', function () {
    console.log('Stream closed')
  })
  .on('end', function () {
    console.log('Stream ended')
  })

You can supply an options object as the first parameter to createReadStream() with the following properties:

你可以使用任何带着下面的属性的options对象作为createReadStream()函数的第一个参数

• gt (greater than), gte (greater than or equal) define the lower bound of the range to be streamed. Only entries where the key is greater than (or equal to) this option will be included in the range. When reverse=true the order will be reversed, but the entries streamed will be the same.   gt（大于），gte（大于或等于)定义了流范围的下界。只有key大于（或等于）这个option的条目会被包含进这个范围。当reverse=true，这个顺序将会被反转，但是条目流是相同的
  

• lt (less than), lte (less than or equal) define the higher bound of the range to be streamed. Only entries where the key is less than (or equal to) this option will be included in the range. When reverse=true the order will be reversed, but the entries streamed will be the same.   lt(小于),lte(小于或等于)定义了流范围的上界。只有key小于（或等于）这个option的条目会被包含进这个范围。当reverse=true，这个顺序将会被反转，但是条目流是相同的
  

• reverse (boolean, default: false): stream entries in reverse order. Beware that due to the way that stores like LevelDB work, a reverse seek can be slower than a forward seek. 以相反顺序输入流条目。注意，因为像LevelDB这样的存储器的工作方式，反向查找将慢于正向查找
  

• limit (number, default: -1): limit the number of entries collected by this stream. This number represents a maximum number of entries and may not be reached if you get to the end of the range first. A value of -1 means there is no limit. When reverse=true the entries with the highest keys will be returned instead of the lowest keys.  限制被流选择的条目的数量。这个数量代表了条目的最大数量，如果先到了范围的结尾处，它可能不会被触发。-1值意味着这里没有限制。当设置reverse=true，条目将会从最高值的keys的方向被返回，而不是最低的keys方向。
  

• keys (boolean, default: true): whether the results should contain keys. If set to true and values set to false then results will simply be keys, rather than objects with a key property. Used internally by the createKeyStream()method.  是否结果应该包含keys。如果设置为true，且values设置为false，结果将只有keys，而不是带有key属性的对象。通过createKeyStream()方法内部使用
  

• values (boolean, default: true): whether the results should contain values. If set to true and keys set to falsethen results will simply be values, rather than objects with a value property. Used internally by the createValueStream() method. 是否结果应该包含values。如果设置为true，且keys设置为false，结果将只有values，而不是带有value属性的对象。通过createKeyStream()方法内部使用

Legacy options:遗留options

• start: instead use gte 可用于替换gte


• end: instead use lte 可用于替换lte


db.createKeyStream([options])

Returns a Readable Stream of keys rather than key-value pairs. Use the same options as described for createReadStream to control the range and direction.

返回一个keys的可读流，而不是键值对。使用和在createReadStream中描述的相同的options去控制范围了方向

You can also obtain this stream by passing an options object to createReadStream() with keys set to true and values set to false. The result is equivalent; both streams operate in object mode.

你也可以通过传递一个keys设置为true，values设置为false的options对象给createReadStream()来获得该流。这两个的结果是相等的；他们的流都在对象模块中被操作

db.createKeyStream()
  .on('data', function (data) {
    console.log('key=', data)
  })

// same as:
db.createReadStream({ keys: true, values: false })
  .on('data', function (data) {
    console.log('key=', data)
  })

db.createValueStream([options])

Returns a Readable Stream of values rather than key-value pairs. Use the same options as described for createReadStream to control the range and direction.

返回一个values的可读流，而不是键值对。使用和在createReadStream中描述的相同的options去控制范围了方向

You can also obtain this stream by passing an options object to createReadStream() with values set to true and keys set to false. The result is equivalent; both streams operate in object mode.

你也可以通过传递一个keys设置为false，values设置为true的options对象给createReadStream()来获得该流。这两个的结果是相等的；他们的流都在对象模块中被操作

db.createValueStream()
  .on('data', function (data) {
    console.log('value=', data)
  })

// same as:
db.createReadStream({ keys: false, values: true })
  .on('data', function (data) {
    console.log('value=', data)
  })

db.iterator([options])

Returns an abstract-leveldown iterator, which is what powers the readable streams above. Options are the same as the range options of createReadStream() and are passed to the underlying store.

返回一个抽象leveldown迭代器，用于加强上面的可读流。其options与createReadStream()的范围options是相同的，并且被传递给底层的存储器

What happened to db.createWriteStream?

db.createWriteStream() has been removed in order to provide a smaller and more maintainable core. It primarily existed to create symmetry with db.createReadStream() but through much discussion, removing it was the best course of action.

为了提供一个更小且可保存的代码，db.createWriteStream() 就被移除了。它主要存在是为了与db.createReadStream()方法对称，但是通过更多的讨论后，移除它会更好。

The main driver for this was performance. While db.createReadStream() performs well under most use cases, db.createWriteStream() was highly dependent on the application keys and values. Thus we can't provide a standard implementation and encourage more write-stream implementations to be created to solve the broad spectrum of use cases.

移除它的主要驱动是其性能。在大多数情况下，db.createReadStream()执行得很好，db.createWriteStream()则更多依赖于应用的keys和values。因此，我们不能提供一个标准的实现，并鼓励创建更多的写流实现来解决广泛的用例范围

Check out the implementations that the community has already produced here.

请查看社区已经在here生成的实现。