levelup
v5.1.1
? Этот модуль скоро станет устаревшим, поскольку его заменяет модуль
abstract-level.
levelup(db[, options[, callback]])db.supportsdb.open([options][, callback])db.close([callback])db.put(key, value[, options][, callback])db.get(key[, options][, callback])db.getMany(keys[, options][, callback])db.del(key[, options][, callback])db.batch(array[, options][, callback]) (форма массива)db.batch() (связанная форма)db.statusdb.isOperational()db.createReadStream([options])db.createKeyStream([options])db.createValueStream([options])db.iterator([options])db.clear([options][, callback])db.createWriteStream ? Быстрое и простое хранение. Оболочка Node.js для хранилищ, совместимых с abstract-leveldown , которые соответствуют характеристикам LevelDB.
LevelDB — это простое хранилище ключей и значений, созданное Google. Он используется в Google Chrome и многих других продуктах. LevelDB поддерживает произвольные массивы байтов как ключи, так и значения, единичные операции get , put и delete , пакетную операцию put и delete , двунаправленные итераторы и простое сжатие с использованием очень быстрого алгоритма Snappy.
LevelDB хранит записи, отсортированные лексикографически по ключам. Это делает потоковый интерфейс levelup , который предоставляет итераторы LevelDB как читаемые потоки, очень мощным механизмом запросов.
Наиболее распространенным хранилищем является leveldown , который обеспечивает привязку чистого C++ к LevelDB. Доступно множество альтернативных хранилищ, например level.js в браузере или memdown для хранилища в памяти. Обычно они поддерживают строки и буферы как для ключей, так и для значений. Для более богатого набора типов данных вы можете обернуть хранилище encoding-down .
Пакет level — рекомендуемый способ начать работу. Он удобно объединяет levelup , leveldown encoding-down . Его основной экспорт — levelup , т.е. вы можете сделать var db = require('level') .
Мы стремимся поддерживать выпуски Active LTS и Current Node.js, а также браузеры. Информацию о поддержке базового хранилища см. в соответствующей документации.
Если вы обновляетесь: пожалуйста, посетите UPGRADING.md .
Сначала вам нужно установить levelup ! Магазины не включены, поэтому вам также необходимо установить leveldown (например).
$ npm install levelup leveldownВсе операции асинхронны. Если вы не предоставляете обратный вызов, возвращается обещание.
var levelup = require ( 'levelup' )
var leveldown = require ( 'leveldown' )
// 1) Create our store
var db = levelup ( leveldown ( './mydb' ) )
// 2) Put a key & value
db . put ( 'name' , 'levelup' , function ( err ) {
if ( err ) return console . log ( 'Ooops!' , err ) // some kind of I/O error
// 3) Fetch by key
db . get ( 'name' , function ( err , value ) {
if ( err ) return console . log ( 'Ooops!' , err ) // likely the key was not found
// Ta da!
console . log ( 'name=' + value )
} )
} ) levelup(db[, options[, callback]]) Основная точка входа для создания нового экземпляра levelup .
db должен быть хранилищем, совместимым abstract-leveldown .options передаются в базовое хранилище при открытии и зависят от типа используемого хранилища. Вызов levelup(db) также откроет базовое хранилище. Это асинхронная операция, которая вызовет обратный вызов, если вы его предоставите. Обратный вызов должен иметь форму function (err, db) {} , где db — это экземпляр levelup . Если вы не предоставляете обратный вызов, любые операции чтения и записи просто ставятся в очередь до тех пор, пока хранилище не будет полностью открыто, если только оно не откроется, и в этом случае будет выдано событие error .
Это приводит к двум альтернативным способам управления экземпляром 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 )
} )
} )По сравнению с эквивалентом:
// 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.supportsМанифест, доступный только для чтения. Можно использовать так:
if ( ! db . supports . permanence ) {
throw new Error ( 'Persistent storage is required' )
}
if ( db . supports . bufferKeys && db . supports . promises ) {
await db . put ( Buffer . from ( 'key' ) , 'value' )
}db.open([options][, callback]) Открывает базовое хранилище. В общем, вам не нужно вызывать этот метод напрямую, поскольку он автоматически вызывается levelup() . Однако можно снова открыть хранилище после его закрытия с помощью close() .
Если обратный вызов не передан, возвращается обещание.
db.close([callback]) close() закрывает базовое хранилище. Обратный вызов будет получать любую ошибку, возникшую при закрытии, в качестве первого аргумента.
Вы всегда должны очищать свой экземпляр levelup , вызывая close() когда он вам больше не нужен, чтобы освободить ресурсы. Магазин не может быть открыт несколькими экземплярами levelup одновременно.
Если обратный вызов не передан, возвращается обещание.
db.put(key, value[, options][, callback]) put() — основной метод вставки данных в хранилище. И key , и value могут быть любого типа в зависимости от levelup .
options передаются в базовое хранилище.
Если обратный вызов не передан, возвращается обещание.
db.get(key[, options][, callback]) Получить значение из хранилища по key . key может быть любого типа. Если его не существует в хранилище, обратный вызов или обещание получат ошибку. Ненайденный объект ошибки будет иметь тип '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 передается в базовое хранилище.
Если обратный вызов не передан, возвращается обещание.
db.getMany(keys[, options][, callback]) Получите несколько значений из хранилища по массиву keys . Объект необязательных options передается в базовое хранилище.
Функция callback будет вызвана с Error , если операция по какой-либо причине не удалась. В случае успеха первый аргумент будет null , а второй аргумент будет массивом значений в том же порядке, что и keys . Если ключ не найден, соответствующее значение будет undefined .
Если обратный вызов не указан, возвращается обещание.
db.del(key[, options][, callback]) del() — основной метод удаления данных из хранилища.
db . del ( 'foo' , function ( err ) {
if ( err )
// handle I/O or other error
} ) ; options передаются в базовое хранилище.
Если обратный вызов не передан, возвращается обещание.
db.batch(array[, options][, callback]) (форма массива) batch() можно использовать для очень быстрых операций массовой записи (как put , так и delete ). Аргумент array должен содержать список операций, которые должны выполняться последовательно, хотя в целом они выполняются как атомарная операция внутри базового хранилища.
Каждая операция содержится в объекте, имеющем следующие свойства: type , key , value , где тип — 'put' или 'del' . В случае 'del' свойство value игнорируется. Любые записи с key , равным null или undefined приведут к возврату ошибки в callback , а запись любого type: 'put' со value , равным null или undefined вернет ошибку.
const 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 передаются в базовое хранилище.
Если обратный вызов не передан, возвращается обещание.
db.batch() (связанная форма) 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[, options])
Поставить в очередь операцию put для текущего пакета, не фиксируя ее до тех пор, пока для пакета не будет вызвана функция write() . Аргумент options , если он предоставлен, должен быть объектом и передаваться в базовое хранилище.
Этот метод может throw WriteError если с вашим put возникла проблема (например, value null или undefined ).
batch.del(key[, options])
Поставить в очередь операцию del для текущего пакета, не фиксируемую до тех пор, пока для пакета не будет вызвана функция write() . Аргумент options , если он предоставлен, должен быть объектом и передаваться в базовое хранилище.
Этот метод может throw WriteError , если при удалении возникла проблема.
batch.clear()
Очистите все операции в очереди в текущем пакете; все предыдущие операции будут отменены.
batch.length
Количество операций в очереди в текущем пакете.
batch.write([options][, callback])
Зафиксируйте операции в очереди для этого пакета. Все не очищенные операции будут записываться в базовое хранилище атомарно, то есть либо все они завершатся успешно, либо потерпят неудачу без частичных фиксаций.
Объект необязательных options передается в операцию .write() базового пакетного объекта.
Если обратный вызов не передан, возвращается обещание.
db.statusСтрока только для чтения, которая является одной из:
new - вновь созданный, не открытый и не закрытыйopening - ожидание открытия базового хранилищаopen - магазин успешно открыт, доступен для использованияclosing - ожидание закрытия магазинаclosed — магазин успешно закрыт.db.isOperational() Возвращает true , если хранилище принимает операции, что в случае levelup означает, что status — opening или open , поскольку оно открывается само и ставит операции в очередь до открытия.
db.createReadStream([options]) Возвращает читаемый поток пар ключ-значение. Пара — это объект со свойствами key и value . По умолчанию он будет передавать все записи в базовом хранилище от начала до конца. Используйте параметры, описанные ниже, для управления диапазоном, направлением и результатами.
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' )
} ) Вы можете предоставить объект параметров в качестве первого параметра для createReadStream() со следующими свойствами:
gt (больше), gte (больше или равно) определяют нижнюю границу диапазона для потоковой передачи. В диапазон будут включены только записи, ключ которых больше (или равен) этой опции. Еслиverse reverse=true порядок будет обратным, но потоковые записи останутся прежними.
lt (меньше), lte (меньше или равно) определяют верхнюю границу диапазона для потоковой передачи. В диапазон будут включены только записи, ключ которых меньше (или равен) этой опции. Еслиverse reverse=true порядок будет обратным, но потоковые записи останутся прежними.
reverse (логический, по умолчанию: false ) : записи потока в обратном порядке. Помните, что из-за особенностей работы таких хранилищ, как LevelDB, обратный поиск может быть медленнее, чем прямой.
limit (число, по умолчанию: -1 ) : ограничить количество записей, собираемых этим потоком. Это число представляет собой максимальное количество записей и может быть не достигнуто, если вы сначала дойдете до конца диапазона. Значение -1 означает отсутствие ограничений. Когдаverse reverse=true вместо самых низких ключей будут возвращены записи с самыми высокими ключами.
keys (логическое значение, по умолчанию: true ) : должны ли результаты содержать ключи. Если установлено значение true , а values — false , то результатами будут просто ключи, а не объекты со свойством key . Используется внутри метода createKeyStream() .
values (логическое значение, по умолчанию: true ) : должны ли результаты содержать значения. Если установлено значение true , а keys установлено значение false то результатами будут просто значения, а не объекты со свойством value . Используется внутри метода createValueStream() .
db.createKeyStream([options]) Возвращает читаемый поток ключей, а не пары ключ-значение. Используйте те же параметры, что описаны для createReadStream() чтобы управлять диапазоном и направлением.
Вы также можете получить этот поток, передав объект параметров в createReadStream() с keys установленными в true и values установленными в false . Результат эквивалентен; оба потока работают в объектном режиме.
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]) Возвращает читаемый поток значений, а не пары ключ-значение. Используйте те же параметры, что описаны для createReadStream() чтобы управлять диапазоном и направлением.
Вы также можете получить этот поток, передав объект параметров в createReadStream() со values установленными в true , и keys установленными в false . Результат эквивалентен; оба потока работают в объектном режиме.
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]) Возвращает итератор abstract-leveldown , который обеспечивает работу читаемых потоков выше. Параметры аналогичны параметрам диапазона метода createReadStream() и передаются в базовое хранилище.
Эти итераторы поддерживают for await...of :
for await ( const [ key , value ] of db . iterator ( ) ) {
console . log ( value )
}db.clear([options][, callback])Удалить все записи или диапазон. Не гарантируется атомарность. Принимает следующие параметры диапазона (с теми же правилами, что и для итераторов):
gt (больше), gte (больше или равно) определяют нижнюю границу удаляемого диапазона. В диапазон будут включены только записи, ключ которых больше (или равен) этой опции. Еслиverse reverse=true порядок будет изменен, но удаленные записи останутся прежними.lt (меньше), lte (меньше или равно) определяют верхнюю границу удаляемого диапазона. В диапазон будут включены только записи, ключ которых меньше (или равен) этой опции. Еслиverse reverse=true порядок будет обратным, но удаленные записи останутся прежними.reverse (логический, по умолчанию: false ) : удалять записи в обратном порядке. Эффективен только в сочетании с limit для удаления последних N записей.limit (число, по умолчанию: -1 ) : ограничение количества удаляемых записей. Это число представляет собой максимальное количество записей и может быть не достигнуто, если вы сначала дойдете до конца диапазона. Значение -1 означает отсутствие ограничений. Когдаverse reverse=true записи с самыми высокими ключами будут удалены вместо самых низких ключей. Если параметры не указаны, все записи будут удалены. Функция callback будет вызвана без аргументов, если операция прошла успешно, или с ошибкой WriteError если по какой-либо причине она не удалась.
Если обратный вызов не передан, возвращается обещание.
db.createWriteStream ? db.createWriteStream() был удален, чтобы обеспечить меньшее и более удобное в обслуживании ядро. В первую очередь он существовал для создания симметрии с помощью db.createReadStream() но после долгих обсуждений лучшим решением было его удаление.
Главной движущей силой этого была производительность. Хотя db.createReadStream() работает хорошо в большинстве случаев использования, db.createWriteStream() сильно зависел от ключей и значений приложения. Таким образом, мы не можем предоставить стандартную реализацию и поощрять создание большего количества реализаций write-stream для решения широкого спектра вариантов использования.
Ознакомьтесь с реализациями, созданными сообществом, здесь.
Каждая функция, принимающая обратный вызов, возвращает обещание, если обратный вызов опущен. Единственным исключением является сам конструктор levelup , который, если не передать обратный вызов, будет лениво открывать базовое хранилище в фоновом режиме.
Пример:
const db = levelup ( leveldown ( './my-db' ) )
await db . put ( 'foo' , 'bar' )
console . log ( await db . get ( 'foo' ) ) levelup является EventEmitter и генерирует следующие события.
| Событие | Описание | Аргументы |
|---|---|---|
put | Ключ обновлен | key, value (любое) |
del | Ключ был удален | key (любой) |
batch | Пакет выполнил | operations (массив) |
clear | Записи были удалены | options (объект) |
opening | Базовый магазин открывается | - |
open | Магазин открылся | - |
ready | Псевдоним open | - |
closing | Магазин закрывается | - |
closed | Магазин закрылся. | - |
error | Произошла ошибка | error (Ошибка) |
Например, вы можете сделать:
db . on ( 'put' , function ( key , value ) {
console . log ( 'inserted' , { key , value } )
} ) Такие хранилища, как LevelDB, являются поточно-ориентированными, но не подходят для доступа к ним со стороны нескольких процессов. Магазин должен быть открыт только из одного процесса Node.js. Кластеры Node.js состоят из нескольких процессов, поэтому экземпляр levelup также не может использоваться ими совместно.
См. Level/awesome для таких модулей, как multileveldown , которые могут помочь, если вам требуется, чтобы одно хранилище было общим для нескольких процессов.
Level/levelup — это ОТКРЫТЫЙ проект с открытым исходным кодом . Это означает, что:
Лицам, внесшим значительный и ценный вклад, предоставляется доступ к проекту, чтобы они могли вносить свой вклад по своему усмотрению. Этот проект больше похож на открытую вики, чем на стандартный защищенный проект с открытым исходным кодом.
Дополнительную информацию см. в Руководстве по участию.
Платформа кросс-браузерного тестирования и открытый исходный код ♥ предоставлены Sauce Labs.
Поддержите нас ежемесячным пожертвованием на Open Collective и помогите нам продолжить нашу работу.
Массачусетский технологический институт
