levelup

subir de nivel

? Este módulo pronto quedará obsoleto porque ha sido reemplazado por abstract-level .

Tabla de contenido

Haga clic para ampliar

• Introducción
• Plataformas compatibles
• 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 matriz)
  • db.batch() (forma encadenada)
  • db.status
  • db.isOperational()
  • db.createReadStream([options])
  • db.createKeyStream([options])
  • db.createValueStream([options])
  • db.iterator([options])
  • db.clear([options][, callback])
• ¿Qué pasó con db.createWriteStream ?
• Soporte de promesa
• Eventos
• Acceso multiproceso
• Contribuyendo
• Muchas gracias
• Donar
• Licencia

Introducción

Almacenamiento rápido y sencillo. Un contenedor de Node.js para tiendas compatibles abstract-leveldown , que siguen las características de LevelDB.

LevelDB es un almacén clave-valor simple creado por Google. Se utiliza en Google Chrome y muchos otros productos. LevelDB admite matrices de bytes arbitrarias como claves y valores, operaciones de obtención , colocación y eliminación singulares, colocación y eliminación por lotes , iteradores bidireccionales y compresión simple utilizando el algoritmo Snappy muy rápido.

LevelDB almacena entradas ordenadas lexicográficamente por claves. Esto hace que la interfaz de streaming de levelup , que expone los iteradores de LevelDB como flujos legibles, sea un mecanismo de consulta muy potente.

El almacén más común es leveldown , que proporciona un enlace de C++ puro a LevelDB. Hay muchas tiendas alternativas disponibles, como level.js en el navegador o memdown para una tienda en memoria. Por lo general, admiten cadenas y búferes tanto para claves como para valores. Para obtener un conjunto más rico de tipos de datos, puede encapsular la tienda con encoding-down .

El paquete level es la forma recomendada de comenzar. Incluye convenientemente levelup , leveldown y encoding-down . Su exportación principal es levelup , es decir, puedes hacerlo var db = require('level') .

Plataformas compatibles

Nuestro objetivo es admitir las versiones Active LTS y Current Node.js, así como los navegadores. Para obtener soporte de la tienda subyacente, consulte la documentación respectiva.

Uso

Si está actualizando: consulte UPGRADING.md .

¡Primero necesitas instalar levelup ! No se incluyen tiendas por lo que también debes instalar leveldown (por ejemplo).

$ npm install levelup leveldown

Todas las operaciones son asincrónicas. Si no proporciona una devolución de llamada, se devuelve una Promesa.

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

El principal punto de entrada para crear una nueva instancia levelup .

• db debe ser un almacén compatible abstract-leveldown .
• options se pasan a la tienda subyacente cuando se abren y son específicas del tipo de tienda que se utiliza.

Llamar levelup(db) también abrirá la tienda subyacente. Esta es una operación asincrónica que activará su devolución de llamada si proporciona una. La devolución de llamada debe tomar el formato function (err, db) {} donde db es la instancia levelup . Si no proporciona una devolución de llamada, cualquier operación de lectura y escritura simplemente se pone en cola internamente hasta que la tienda se abra por completo, a menos que no se abra, en cuyo caso se emitirá un evento error .

Esto lleva a dos formas alternativas de gestionar una instancia 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 )
  } )
} )

Frente al 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

Un manifiesto de solo lectura. Podría usarse así:

 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 la tienda subyacente. En general, no debería necesitar llamar a este método directamente, ya que levelup() lo llama automáticamente. Sin embargo, es posible reabrir la tienda después de haberla cerrado con close() .

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

db.close([callback])

close() cierra la tienda subyacente. La devolución de llamada recibirá cualquier error encontrado durante el cierre como primer argumento.

Siempre debes limpiar tu instancia levelup llamando close() cuando ya no la necesites para liberar recursos. Una tienda no se puede abrir con varias instancias de levelup simultáneamente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

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

put() es el método principal para insertar datos en la tienda. Tanto key como value pueden ser de cualquier tipo en lo que respecta a levelup .

options se pasan a la tienda subyacente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

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

Obtenga un valor de la tienda por key . La key puede ser de cualquier tipo. Si no existe en la tienda, la devolución de llamada o la promesa recibirán un error. Un objeto de error no encontrado será del tipo 'NotFoundError' por lo que puede err.type == 'NotFoundError' o puede realizar una prueba de veracidad en la propiedad 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
} )

El objeto options opcionales se pasa al almacén subyacente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

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

Obtenga múltiples valores de la tienda mediante una matriz de keys . El objeto options opcionales se pasa al almacén subyacente.

La función callback se llamará con un Error si la operación falló por algún motivo. Si tiene éxito, el primer argumento será null y el segundo argumento será una matriz de valores con el mismo orden que keys . Si no se encontró una clave, el valor relevante será undefined .

Si no se proporciona ninguna devolución de llamada, se devuelve una promesa.

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

del() es el método principal para eliminar datos de la tienda.

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

options se pasan a la tienda subyacente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

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

batch() se puede utilizar para operaciones de escritura masiva muy rápidas (tanto poner como eliminar ). El argumento array debe contener una lista de operaciones que se ejecutarán secuencialmente, aunque en su conjunto se realizan como una operación atómica dentro del almacén subyacente.

Cada operación está contenida en un objeto que tiene las siguientes propiedades: type , key , value , donde el tipo es 'put' o 'del' . En el caso de 'del' se ignora la propiedad value . Cualquier entrada con una key null o undefined provocará que se devuelva un error en la callback y cualquier type: 'put' con un value null o undefined devolverá un error.

 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 se pasan a la tienda subyacente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

db.batch() (forma encadenada)

batch() , cuando se llama sin argumentos, devolverá un objeto Batch que se puede usar para construir y, eventualmente, confirmar, una operación por lotes atómica. Dependiendo de cómo se use, es posible obtener un mayor rendimiento al usar la forma encadenada de batch() en lugar de la forma de matriz.

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

Ponga en cola una operación de colocación en el lote actual, no confirmada hasta que se llame a write() en el lote. El argumento options , si se proporciona, debe ser un objeto y se pasa al almacén subyacente.

Este método puede throw un WriteError si hay un problema con su transferencia (como que el value sea null o undefined ).

batch.del(key[, options])

Ponga en cola una operación del en el lote actual, no confirmada hasta que se llame a write() en el lote. El argumento options , si se proporciona, debe ser un objeto y se pasa al almacén subyacente.

Este método puede throw un WriteError si hay un problema con la eliminación.

batch.clear()

Borre todas las operaciones en cola en el lote actual; cualquier operación anterior se descartará.

batch.length

El número de operaciones en cola en el lote actual.

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

Confirme las operaciones en cola para este lote. Todas las operaciones que no se borren se escribirán atómicamente en el almacén subyacente, es decir, todas tendrán éxito o fallarán sin confirmaciones parciales.

El objeto options opcionales se pasa a la operación .write() del objeto por lotes subyacente.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

db.status

Una cadena de solo lectura que es una de:

• new : recién creado, no abierto ni cerrado
• opening : esperando a que se abra la tienda subyacente
• open : abrió con éxito la tienda, disponible para su uso
• closing - esperando a que cierren la tienda
• closed : la tienda se ha cerrado correctamente.

db.isOperational()

Devuelve true si la tienda acepta operaciones, lo que en el caso de levelup significa que status es opening o open , porque se abre solo y pone en cola las operaciones hasta que se abre.

db.createReadStream([options])

Devuelve un flujo legible de pares clave-valor. Un par es un objeto con propiedades key y value . De forma predeterminada, transmitirá todas las entradas en la tienda subyacente de principio a fin. Utilice las opciones que se describen a continuación para controlar el rango, la dirección y los 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' )
  } )

Puede proporcionar un objeto de opciones como primer parámetro para createReadStream() con las siguientes propiedades:

• gt (mayor que), gte (mayor o igual) definen el límite inferior del rango que se transmitirá. Solo se incluirán en el rango las entradas cuya clave sea mayor (o igual) que esta opción. Cuando reverse=true el orden se invertirá, pero las entradas transmitidas serán las mismas.

• lt (menor que), lte (menor que o igual) definen el límite superior del rango que se transmitirá. Solo se incluirán en el rango las entradas cuya clave sea menor (o igual) que esta opción. Cuando reverse=true el orden se invertirá, pero las entradas transmitidas serán las mismas.

• reverse (booleana, predeterminada: false ) : transmite entradas en orden inverso. Tenga en cuenta que, debido a la forma en que funcionan las tiendas como LevelDB, una búsqueda inversa puede ser más lenta que una búsqueda directa.

• limit (número, predeterminado: -1 ) : limita el número de entradas recopiladas por esta secuencia. Este número representa un número máximo de entradas y es posible que no se alcance si llega primero al final del rango. Un valor de -1 significa que no hay límite. Cuando reverse=true se devolverán las entradas con las claves más altas en lugar de las claves más bajas.

• keys (booleano, predeterminado: true ) : si los resultados deben contener claves. Si se establece en true y values en false , los resultados serán simplemente claves, en lugar de objetos con una propiedad key . Usado internamente por el método createKeyStream() .

• values (booleano, predeterminado: true ) : si los resultados deben contener valores. Si se establece en true y keys en false , los resultados serán simplemente valores, en lugar de objetos con una propiedad value . Utilizado internamente por el método createValueStream() .

db.createKeyStream([options])

Devuelve un flujo legible de claves en lugar de pares clave-valor. Utilice las mismas opciones descritas para createReadStream() para controlar el rango y la dirección.

También puede obtener esta secuencia pasando un objeto de opciones a createReadStream() con keys configuradas en true y values establecidos en false . El resultado es equivalente; Ambas corrientes operan en modo 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])

Devuelve un flujo legible de valores en lugar de pares clave-valor. Utilice las mismas opciones descritas para createReadStream() para controlar el rango y la dirección.

También puede obtener esta secuencia pasando un objeto de opciones a createReadStream() con values establecidos en true y keys establecidas en false . El resultado es equivalente; Ambas corrientes operan en modo 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])

Devuelve un iterador abstract-leveldown , que es lo que impulsa los flujos legibles anteriores. Las opciones son las mismas que las opciones de rango de createReadStream() y se pasan al almacén subyacente.

Estos iteradores admiten for await...of :

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

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

Eliminar todas las entradas o un rango. No se garantiza que sea atómico. Acepta las siguientes opciones de rango (con las mismas reglas que en los iteradores):

• gt (mayor que), gte (mayor o igual) definen el límite inferior del rango que se eliminará. Solo se incluirán en el rango las entradas cuya clave sea mayor (o igual) que esta opción. Cuando reverse=true el orden se invertirá, pero las entradas eliminadas serán las mismas.
• lt (menor que), lte (menor que o igual) definen el límite superior del rango que se eliminará. Solo se incluirán en el rango las entradas cuya clave sea menor (o igual) que esta opción. Cuando reverse=true el orden se invertirá, pero las entradas eliminadas serán las mismas.
• reverse (booleana, predeterminada: false ) : elimina entradas en orden inverso. Solo es efectivo en combinación con limit para eliminar los últimos N registros.
• limit (número, predeterminado: -1 ) : limita el número de entradas que se eliminarán. Este número representa un número máximo de entradas y es posible que no se alcance si llega primero al final del rango. Un valor de -1 significa que no hay límite. Cuando reverse=true se eliminarán las entradas con las claves más altas en lugar de las claves más bajas.

Si no se proporcionan opciones, se eliminarán todas las entradas. La función callback se llamará sin argumentos si la operación fue exitosa o con un WriteError si falló por algún motivo.

Si no se pasa ninguna devolución de llamada, se devuelve una promesa.

¿Qué pasó con db.createWriteStream ?

db.createWriteStream() se ha eliminado para proporcionar un núcleo más pequeño y más fácil de mantener. Existía principalmente para crear simetría con db.createReadStream() pero, tras mucha discusión, eliminarlo fue el mejor curso de acción.

El principal impulsor de esto fue el rendimiento. Si bien db.createReadStream() funciona bien en la mayoría de los casos de uso, db.createWriteStream() dependía en gran medida de las claves y valores de la aplicación. Por lo tanto, no podemos proporcionar una implementación estándar y alentar la creación de más implementaciones write-stream para resolver el amplio espectro de casos de uso.

Consulte las implementaciones que la comunidad ha producido aquí.

Soporte de promesa

Cada función que acepta una devolución de llamada devuelve una promesa si se omite la devolución de llamada. La única excepción es el constructor levelup en sí, que si no se pasa ninguna devolución de llamada, abrirá perezosamente la tienda subyacente en segundo plano.

Ejemplo:

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

Eventos

levelup es un EventEmitter y emite los siguientes eventos.

Evento	Descripción	Argumentos
put	La clave ha sido actualizada.	key, value (cualquiera)
del	La clave ha sido eliminada	key (cualquiera)
batch	El lote se ha ejecutado	operations (matriz)
clear	Se eliminaron las entradas	options (objeto)
opening	Se está abriendo la tienda subyacente	-
open	La tienda ha abierto	-
ready	Alias ​​de open	-
closing	La tienda está cerrando	-
closed	La tienda ha cerrado.	-
error	Se produjo un error	error (Error)

Por ejemplo puedes hacer:

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

Acceso multiproceso

Las tiendas como LevelDB son seguras para subprocesos, pero no son adecuadas para acceder con múltiples procesos. Sólo deberías tener una tienda abierta desde un único proceso de Node.js. Los clústeres de Node.js se componen de múltiples procesos, por lo que tampoco se puede compartir una instancia levelup entre ellos.

Consulte Level/awesome para módulos como multileveldown que pueden ayudar si necesita compartir una única tienda entre procesos.

Contribuyendo

Level/levelup es un proyecto OPEN de código abierto . Esto significa que:

Las personas que realizan contribuciones significativas y valiosas reciben acceso comprometido al proyecto para contribuir como mejor les parezca. Este proyecto se parece más a una wiki abierta que a un proyecto estándar de código abierto protegido.

Consulte la Guía de contribuciones para obtener más detalles.

Muchas gracias

Plataforma de pruebas para varios navegadores y código abierto ♥ Proporcionada por Sauce Labs.

Donar

Apóyanos con una donación mensual en Open Collective y ayúdanos a continuar nuestro trabajo.

Licencia

MIT