Página Inicial>Relacionado com a programação>Outro código-fonte
Baixar

subir de nível

? Este módulo será descontinuado em breve, porque foi substituído por abstract-level .

Índice

Clique para expandir
  • Introdução
  • Plataformas suportadas
  • Uso
  • API
    • levelup(db[, options[, callback]])
    • db.supports
    • db.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]) (formato de array)
    • db.batch() (formato encadeado)
    • db.status
    • db.isOperational()
    • db.createReadStream([options])
    • db.createKeyStream([options])
    • db.createValueStream([options])
    • db.iterator([options])
    • db.clear([options][, callback])
  • O que aconteceu com db.createWriteStream ?
  • Promessa de suporte
  • Eventos
  • Acesso multiprocesso
  • Contribuindo
  • Muito obrigado
  • Doar
  • Licença

Introdução

Armazenamento rápido e simples. Um wrapper Node.js para armazenamentos compatíveis abstract-leveldown , que seguem as características do LevelDB.

LevelDB é um armazenamento simples de valores-chave criado pelo Google. É usado no Google Chrome e em muitos outros produtos. LevelDB suporta matrizes de bytes arbitrárias como chaves e valores, operações get , put e delete singulares, put e delete em lote , iteradores bidirecionais e compactação simples usando o algoritmo Snappy muito rápido.

LevelDB armazena entradas classificadas lexicograficamente por chaves. Isso torna a interface de streaming do levelup - que expõe os iteradores LevelDB como Readable Streams - um mecanismo de consulta muito poderoso.

O armazenamento mais comum é leveldown , que fornece uma ligação C++ pura ao LevelDB. Muitas lojas alternativas estão disponíveis, como level.js no navegador ou memdown para uma loja na memória. Eles normalmente suportam strings e buffers para chaves e valores. Para um conjunto mais rico de tipos de dados, você pode agrupar o armazenamento com encoding-down .

O pacote level é a maneira recomendada de começar. Ele agrupa convenientemente levelup , leveldown e encoding-down . Sua principal exportação é levelup - ou seja, você pode fazer var db = require('level') .

Plataformas suportadas

Nosso objetivo é oferecer suporte às versões Active LTS e Current Node.js, bem como aos navegadores. Para suporte da loja subjacente, consulte a respectiva documentação.

Uso

Se você estiver atualizando: consulte UPGRADING.md .

Primeiro você precisa instalar levelup ! Nenhuma loja está incluída, então você também deve instalar leveldown (por exemplo). 

$ npm install levelup leveldown

Todas as operações são assíncronas. Se você não fornecer um retorno de chamada, uma promessa será retornada. 

 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 )
  } )
} )

API

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

O principal ponto de entrada para criar uma nova instância levelup .

  • db deve ser um armazenamento compatível abstract-leveldown .
  • options são repassadas para a loja subjacente quando abertas e são específicas para o tipo de loja que está sendo usada

Chamar levelup(db) também abrirá o armazenamento subjacente. Esta é uma operação assíncrona que acionará seu retorno de chamada se você fornecer um. O retorno de chamada deve assumir o formato function (err, db) {} onde db é a instância levelup . Se você não fornecer um retorno de chamada, quaisquer operações de leitura e gravação serão simplesmente enfileiradas internamente até que o armazenamento seja totalmente aberto, a menos que haja falha na abertura, caso em que um evento error será emitido.

Isso leva a duas formas alternativas de gerenciar uma instância 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 )
  } )
} )

Contra o equivalente: 

 // 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

Um manifesto somente leitura. Pode ser usado assim: 

 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])

Abre o armazenamento subjacente. Em geral, você não precisa chamar esse método diretamente, pois ele é chamado automaticamente por levelup() . Porém, é possível reabrir a loja após ela ter sido fechada com close() .

Se nenhum retorno de chamada for passado, uma promessa será retornada.

db.close([callback])

close() fecha o armazenamento subjacente. O retorno de chamada receberá qualquer erro encontrado durante o fechamento como primeiro argumento.

Você deve sempre limpar sua instância levelup chamando close() quando não precisar mais dela para liberar recursos. Uma loja não pode ser aberta por múltiplas instâncias de levelup simultaneamente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

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

put() é o método principal para inserir dados no armazenamento. Tanto key quanto value podem ser de qualquer tipo no que diz respeito levelup .

options são repassadas para a loja subjacente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

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

Obtenha um valor da loja por key . A key pode ser de qualquer tipo. Se não existir na loja, o retorno de chamada ou promessa receberá um erro. Um objeto err não encontrado será do tipo 'NotFoundError' então você pode err.type == 'NotFoundError' ou pode realizar um teste verdadeiro na propriedade 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
} )

O objeto options opcionais é passado para o armazenamento subjacente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

db.getMany(keys[, options][, callback])

Obtenha vários valores do armazenamento por meio de um array de keys . O objeto options opcionais é passado para o armazenamento subjacente.

A função callback será chamada com um Error se a operação falhar por algum motivo. Se for bem-sucedido, o primeiro argumento será null e o segundo argumento será uma matriz de valores com a mesma ordem das keys . Se uma chave não for encontrada, o valor relevante será undefined .

Se nenhum retorno de chamada for fornecido, uma promessa será retornada.

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

del() é o método principal para remover dados do armazenamento. 

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

options são repassadas para a loja subjacente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

db.batch(array[, options][, callback]) (formato de array)

batch() pode ser usado para operações de gravação em massa muito rápidas ( put e delete ). O argumento array deve conter uma lista de operações a serem executadas sequencialmente, embora como um todo elas sejam executadas como uma operação atômica dentro do armazenamento subjacente.

Cada operação está contida em um objeto com as seguintes propriedades: type , key , value , onde o tipo é 'put' ou 'del' . No caso de 'del' a propriedade value é ignorada. Quaisquer entradas com uma key null ou undefined farão com que um erro seja retornado no callback e qualquer entrada type: 'put' com um value null ou undefined retornará um erro. 

 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 são repassadas para a loja subjacente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

db.batch() (formato encadeado)

batch() , quando chamado sem argumentos retornará um objeto Batch que pode ser usado para construir e, eventualmente, confirmar uma operação em lote atômico. Dependendo de como é utilizado, é possível obter maior desempenho ao utilizar a forma encadeada de batch() em vez da forma array. 

 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])

Enfileira uma operação put no lote atual, não confirmada até que um write() seja chamado no lote. O argumento options , se fornecido, deve ser um objeto e é passado para o armazenamento subjacente.

Este método pode throw um WriteError se houver um problema com sua colocação (como o value ser null ou undefined ).

batch.del(key[, options])

Enfileira uma operação del no lote atual, não confirmada até que um write() seja chamado no lote. O argumento options , se fornecido, deve ser um objeto e é passado para o armazenamento subjacente.

Este método pode throw um WriteError se houver um problema com sua exclusão.

batch.clear()

Limpe todas as operações enfileiradas no lote atual; todas as operações anteriores serão descartadas.

batch.length

O número de operações enfileiradas no lote atual.

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

Confirme as operações na fila para este lote. Todas as operações não limpas serão gravadas no armazenamento subjacente atomicamente, ou seja, todas serão bem-sucedidas ou falharão sem confirmações parciais.

O objeto options opcionais é passado para a operação .write() do objeto de lote subjacente.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

db.status

Uma string somente leitura que é um dos seguintes:

  • new - recém-criado, não aberto ou fechado
  • opening - aguardando a abertura da loja subjacente
  • open - abriu a loja com sucesso, disponível para uso
  • closing - aguardando o fechamento da loja
  • closed - a loja foi fechada com sucesso.

db.isOperational()

Retorna true se a loja aceitar operações, o que no caso de levelup significa que status é opening ou open , pois ela se abre e coloca as operações na fila até serem abertas.

db.createReadStream([options])

Retorna um fluxo legível de pares de valores-chave. Um par é um objeto com propriedades key e value . Por padrão, ele transmitirá todas as entradas no armazenamento subjacente do início ao fim. Use as opções descritas abaixo para controlar o alcance, a direção e os resultados. 

 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' )
  } )

Você pode fornecer um objeto de opções como o primeiro parâmetro para createReadStream() com as seguintes propriedades:

  • gt (maior que), gte (maior que ou igual) definem o limite inferior do intervalo a ser transmitido. Somente entradas onde a chave for maior (ou igual) a esta opção serão incluídas no intervalo. Quando reverse=true a ordem será invertida, mas as entradas transmitidas serão as mesmas.

  • lt (menor que), lte (menor que ou igual) definem o limite superior do intervalo a ser transmitido. Somente entradas onde a chave for menor (ou igual) a esta opção serão incluídas no intervalo. Quando reverse=true a ordem será invertida, mas as entradas transmitidas serão as mesmas.

  • reverse (boolean, default: false ) : entradas de fluxo na ordem inversa. Esteja ciente de que, devido à maneira como os armazenamentos como o LevelDB funcionam, uma busca reversa pode ser mais lenta do que uma busca direta.

  • limit (number, default: -1 ) : limita o número de entradas coletadas por este fluxo. Este número representa um número máximo de entradas e pode não ser alcançado se você chegar primeiro ao final do intervalo. Um valor de -1 significa que não há limite. Quando reverse=true as entradas com as chaves mais altas serão retornadas em vez das chaves mais baixas.

  • keys (boolean, default: true ) : se os resultados devem conter chaves. Se definido como true e values definidos como false , os resultados serão simplesmente chaves, em vez de objetos com uma propriedade key . Usado internamente pelo método createKeyStream() .

  • values (booleano, padrão: true ) : se os resultados devem conter valores. Se definido como true e keys definidas como false , os resultados serão simplesmente valores, em vez de objetos com uma propriedade value . Usado internamente pelo método createValueStream() .

db.createKeyStream([options])

Retorna um fluxo legível de chaves em vez de pares de valores-chave. Use as mesmas opções descritas para createReadStream() para controlar o intervalo e a direção.

Você também pode obter esse fluxo passando um objeto de opções para createReadStream() com keys definidas como true e values definidos como false . O resultado é equivalente; ambos os fluxos operam no modo de objeto. 

 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])

Retorna um fluxo legível de valores em vez de pares de valores-chave. Use as mesmas opções descritas para createReadStream() para controlar o intervalo e a direção.

Você também pode obter esse fluxo passando um objeto de opções para createReadStream() com values definidos como true e keys definidas como false . O resultado é equivalente; ambos os fluxos operam no modo de objeto. 

 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])

Retorna um iterador abstract-leveldown , que é o que alimenta os fluxos legíveis acima. As opções são iguais às opções de intervalo de createReadStream() e são passadas para o armazenamento subjacente.

Esses iteradores suportam for await...of : 

 for await ( const [ key , value ] of db . iterator ( ) ) {
  console . log ( value )
}

db.clear([options][, callback])

Exclua todas as entradas ou um intervalo. Não é garantido que seja atômico. Aceita as seguintes opções de intervalo (com as mesmas regras dos iteradores):

  • gt (maior que), gte (maior que ou igual) definem o limite inferior do intervalo a ser excluído. Somente entradas onde a chave for maior (ou igual) a esta opção serão incluídas no intervalo. Quando reverse=true a ordem será invertida, mas as entradas excluídas serão as mesmas.
  • lt (menor que), lte (menor que ou igual) definem o limite superior do intervalo a ser excluído. Somente entradas onde a chave for menor (ou igual) a esta opção serão incluídas no intervalo. Quando reverse=true a ordem será invertida, mas as entradas excluídas serão as mesmas.
  • reverse (boolean, default: false ) : exclui entradas na ordem inversa. Eficaz apenas em combinação com limit , para remover os últimos N registros.
  • limit (número, padrão: -1 ) : limita o número de entradas a serem excluídas. Este número representa um número máximo de entradas e pode não ser alcançado se você chegar primeiro ao final do intervalo. Um valor de -1 significa que não há limite. Quando reverse=true as entradas com as chaves mais altas serão excluídas em vez das chaves mais baixas.

Se nenhuma opção for fornecida, todas as entradas serão excluídas. A função callback será chamada sem argumentos se a operação for bem-sucedida ou com WriteError se falhar por qualquer motivo.

Se nenhum retorno de chamada for passado, uma promessa será retornada.

O que aconteceu com db.createWriteStream ?

db.createWriteStream() foi removido para fornecer um núcleo menor e mais fácil de manter. Ele existia principalmente para criar simetria com db.createReadStream() mas, após muita discussão, removê-lo foi o melhor curso de ação.

O principal motivador para isso foi o desempenho. Embora db.createReadStream() tenha um bom desempenho na maioria dos casos de uso, db.createWriteStream() era altamente dependente das chaves e valores do aplicativo. Portanto, não podemos fornecer uma implementação padrão e encorajar a criação de mais implementações write-stream para resolver o amplo espectro de casos de uso.

Confira as implementações que a comunidade produziu aqui.

Promessa de suporte

Cada função que aceita um retorno de chamada retorna uma promessa se o retorno de chamada for omitido. A única exceção é o próprio construtor levelup , que, se nenhum retorno de chamada for passado, abrirá preguiçosamente o armazenamento subjacente em segundo plano.

Exemplo: 

 const db = levelup ( leveldown ( './my-db' ) )
await db . put ( 'foo' , 'bar' )
console . log ( await db . get ( 'foo' ) )

Eventos

levelup é um EventEmitter e emite os seguintes eventos.

Evento Descrição Argumentos
put A chave foi atualizada key, value (qualquer)
del A chave foi excluída key (qualquer)
batch O lote foi executado operations (matriz)
clear As entradas foram excluídas options (objeto)
opening A loja subjacente está abrindo -
open A loja abriu -
ready Alias ​​de open -
closing Loja está fechando -
closed A loja fechou. -
error Ocorreu um erro error (Erro)

Por exemplo você pode fazer: 

 db . on ( 'put' , function ( key , value ) {
  console . log ( 'inserted' , { key , value } )
} )

Acesso multiprocesso

Lojas como LevelDB são thread-safe, mas não são adequadas para acesso com vários processos. Você só deve ter uma loja aberta a partir de um único processo Node.js. Os clusters Node.js são compostos de vários processos, portanto, uma instância levelup também não pode ser compartilhada entre eles.

Consulte Level/awesome para módulos como multileveldown que podem ajudar se você precisar que um único armazenamento seja compartilhado entre processos.

Contribuindo

Level/levelup é um projeto de código aberto e aberto . Isso significa que:

Indivíduos que fazem contribuições significativas e valiosas recebem acesso de comprometimento ao projeto para contribuir como acharem adequado. Este projeto é mais parecido com um wiki aberto do que com um projeto padrão de código aberto protegido.

Consulte o Guia de Contribuição para obter mais detalhes.

Muito obrigado

Plataforma de teste entre navegadores e código aberto ♥ Fornecido pela Sauce Labs.

Doar

Apoie-nos com uma doação mensal no Open Collective e ajude-nos a continuar nosso trabalho.

Licença

MIT

Expandir
Informações adicionais
Aplicativos Relacionados
Recomendado para você
Informações Relacionadas Todos