levelup
v5.1.1
? Ce module sera bientôt obsolète, car il est remplacé par
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]) (sous forme de tableau)db.batch() (forme chaînée)db.statusdb.isOperational()db.createReadStream([options])db.createKeyStream([options])db.createValueStream([options])db.iterator([options])db.clear([options][, callback])db.createWriteStream ? Stockage simple et rapide. Un wrapper Node.js pour les magasins conformes abstract-leveldown , qui suivent les caractéristiques de LevelDB.
LevelDB est un simple magasin clé-valeur créé par Google. Il est utilisé dans Google Chrome et dans de nombreux autres produits. LevelDB prend en charge les tableaux d'octets arbitraires comme clés et valeurs, les opérations get , put et delete singulières, les put et delete par lots , les itérateurs bidirectionnels et la compression simple utilisant l'algorithme Snappy très rapide.
LevelDB stocke les entrées triées lexicographiquement par clés. Cela fait de l'interface de streaming de levelup - qui expose les itérateurs LevelDB en tant que flux lisibles - un mécanisme de requête très puissant.
Le magasin le plus courant est leveldown , qui fournit une liaison C++ pure à LevelDB. De nombreux magasins alternatifs sont disponibles tels que level.js dans le navigateur ou memdown pour un magasin en mémoire. Ils prennent généralement en charge les chaînes et les tampons pour les clés et les valeurs. Pour un ensemble plus riche de types de données, vous pouvez envelopper le magasin avec encoding-down .
Le package level est la méthode recommandée pour commencer. Il regroupe facilement levelup , leveldown et encoding-down . Sa principale exportation est levelup - c'est-à-dire que vous pouvez faire var db = require('level') .
Notre objectif est de prendre en charge les versions Active LTS et Current Node.js ainsi que les navigateurs. Pour la prise en charge du magasin sous-jacent, veuillez consulter la documentation correspondante.
Si vous effectuez une mise à niveau : veuillez consulter UPGRADING.md .
Vous devez d’abord installer levelup ! Aucun magasin n'est inclus, vous devez donc également installer leveldown (par exemple).
$ npm install levelup leveldownToutes les opérations sont asynchrones. Si vous ne fournissez pas de rappel, une promesse est renvoyée.
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]]) Le point d'entrée principal pour créer une nouvelle instance levelup .
db doit être un magasin conforme abstract-leveldown .options sont transmises au magasin sous-jacent lors de l'ouverture et sont spécifiques au type de magasin utilisé L’appel levelup(db) ouvrira également le magasin sous-jacent. Il s'agit d'une opération asynchrone qui déclenchera votre rappel si vous en fournissez un. Le rappel doit prendre la forme function (err, db) {} où db est l'instance levelup . Si vous ne fournissez pas de rappel, toutes les opérations de lecture et d'écriture sont simplement mises en file d'attente en interne jusqu'à ce que le magasin soit complètement ouvert, à moins que son ouverture ne échoue, auquel cas un événement error sera émis.
Cela conduit à deux manières alternatives de gérer une 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 )
} )
} )Contre l'équivalent :
// 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.supportsUn manifeste en lecture seule. Peut être utilisé comme ceci :
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]) Ouvre le magasin sous-jacent. En général, vous ne devriez pas avoir besoin d'appeler cette méthode directement car elle est automatiquement appelée par levelup() . Cependant, il est possible de rouvrir le magasin après sa fermeture avec close() .
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.close([callback]) close() ferme le magasin sous-jacent. Le rappel recevra toute erreur rencontrée lors de la fermeture comme premier argument.
Vous devez toujours nettoyer votre instance levelup en appelant close() lorsque vous n'en avez plus besoin pour libérer des ressources. Un magasin ne peut pas être ouvert simultanément par plusieurs instances de levelup .
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.put(key, value[, options][, callback]) put() est la méthode principale pour insérer des données dans le magasin. key et value peuvent être de n’importe quel type en ce qui concerne levelup .
options sont transmises au magasin sous-jacent.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.get(key[, options][, callback]) Obtenez une valeur du magasin par key . La key peut être de n'importe quel type. S'il n'existe pas dans le magasin, le rappel ou la promesse recevra une erreur. Un objet d'erreur introuvable sera de type 'NotFoundError' , vous pouvez donc err.type == 'NotFoundError' ou vous pouvez effectuer un test de vérité sur la propriété 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
} ) L'objet options facultatif est transmis au magasin sous-jacent.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.getMany(keys[, options][, callback]) Obtenez plusieurs valeurs du magasin par un tableau de keys . L'objet options facultatif est transmis au magasin sous-jacent.
La fonction callback sera appelée avec une Error si l'opération a échoué pour une raison quelconque. En cas de succès, le premier argument sera null et le deuxième argument sera un tableau de valeurs avec le même ordre que keys . Si une clé n'a pas été trouvée, la valeur correspondante sera undefined .
Si aucun rappel n’est fourni, une promesse est renvoyée.
db.del(key[, options][, callback]) del() est la méthode principale pour supprimer des données du magasin.
db . del ( 'foo' , function ( err ) {
if ( err )
// handle I/O or other error
} ) ; options sont transmises au magasin sous-jacent.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.batch(array[, options][, callback]) (sous forme de tableau) batch() peut être utilisé pour des opérations d'écriture en masse très rapides (à la fois put et delete ). L'argument array doit contenir une liste d'opérations à exécuter séquentiellement, bien que dans leur ensemble, elles soient effectuées comme une opération atomique à l'intérieur du magasin sous-jacent.
Chaque opération est contenue dans un objet ayant les propriétés suivantes : type , key , value , où le type est soit 'put' , soit 'del' . Dans le cas de 'del' la propriété value est ignorée. Toute entrée avec une key null ou undefined entraînera le retour d'une erreur lors du callback et toute entrée type: 'put' avec une value null ou undefined renverra une erreur.
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 sont transmises au magasin sous-jacent.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.batch() (forme chaînée) batch() , lorsqu'il est appelé sans argument, renverra un objet Batch qui peut être utilisé pour créer, et éventuellement valider, une opération par lots atomique. Selon la manière dont il est utilisé, il est possible d'obtenir de meilleures performances en utilisant la forme chaînée de batch() plutôt que la forme tableau.
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])
Mettre en file d'attente une opération put sur le lot actuel, non validée jusqu'à ce qu'un write() soit appelé sur le lot. L'argument options , s'il est fourni, doit être un objet et est transmis au magasin sous-jacent.
Cette méthode peut throw une WriteError s'il y a un problème avec votre put (comme si la value est null ou undefined ).
batch.del(key[, options])
Mettre en file d'attente une opération del sur le lot actuel, non validée jusqu'à ce qu'un write() soit appelé sur le lot. L'argument options , s'il est fourni, doit être un objet et est transmis au magasin sous-jacent.
Cette méthode peut throw une WriteError s'il y a un problème avec votre suppression.
batch.clear()
Effacez toutes les opérations en file d'attente sur le lot actuel, toutes les opérations précédentes seront ignorées.
batch.length
Nombre d'opérations en file d'attente sur le lot actuel.
batch.write([options][, callback])
Validez les opérations en file d’attente pour ce lot. Toutes les opérations non effacées seront écrites dans le magasin sous-jacent de manière atomique, c'est-à-dire qu'elles réussiront ou échoueront toutes sans validation partielle.
L'objet options facultatif est transmis à l'opération .write() de l'objet batch sous-jacent.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.statusUne chaîne en lecture seule qui est l'une des suivantes :
new - nouvellement créé, ni ouvert ni ferméopening - en attente de l'ouverture du magasin sous-jacentopen - ouverture réussie du magasin, disponible pour utilisationclosing - attendre la fermeture du magasinclosed - le magasin a été fermé avec succès.db.isOperational() Renvoie true si le magasin accepte les opérations, ce qui dans le cas d' levelup signifie que status est soit opening soit open , car il s'ouvre lui-même et met les opérations en file d'attente jusqu'à son ouverture.
db.createReadStream([options]) Renvoie un flux lisible de paires clé-valeur. Une paire est un objet avec des propriétés key et value . Par défaut, il diffusera toutes les entrées du magasin sous-jacent du début à la fin. Utilisez les options décrites ci-dessous pour contrôler la plage, la direction et les résultats.
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' )
} ) Vous pouvez fournir un objet options comme premier paramètre de createReadStream() avec les propriétés suivantes :
gt (supérieur à), gte (supérieur ou égal) définissent la limite inférieure de la plage à diffuser. Seules les entrées dont la clé est supérieure (ou égale) à cette option seront incluses dans la plage. Lorsque reverse=true l'ordre sera inversé, mais les entrées diffusées seront les mêmes.
lt (inférieur à), lte (inférieur ou égal) définissent la limite supérieure de la plage à diffuser. Seules les entrées dont la clé est inférieure (ou égale) à cette option seront incluses dans la plage. Lorsque reverse=true l'ordre sera inversé, mais les entrées diffusées seront les mêmes.
reverse (booléen, par défaut : false ) : diffuse les entrées dans l'ordre inverse. Attention, en raison de la façon dont fonctionnent les magasins comme LevelDB, une recherche inversée peut être plus lente qu'une recherche directe.
limit (nombre, par défaut : -1 ) : limite le nombre d'entrées collectées par ce flux. Ce nombre représente un nombre maximum d'entrées et peut ne pas être atteint si vous arrivez en premier à la fin de la plage. Une valeur de -1 signifie qu'il n'y a pas de limite. Lorsque reverse=true les entrées avec les clés les plus élevées seront renvoyées au lieu des clés les plus basses.
keys (booléen, par défaut : true ) : si les résultats doivent contenir des clés. S'il est défini sur true et values sont définies sur false , les résultats seront simplement des clés, plutôt que des objets avec une propriété key . Utilisé en interne par la méthode createKeyStream() .
values (booléen, par défaut : true ) : indique si les résultats doivent contenir des valeurs. Si la valeur est true et keys sont définies sur false , les résultats seront simplement des valeurs, plutôt que des objets avec une propriété value . Utilisé en interne par la méthode createValueStream() .
db.createKeyStream([options]) Renvoie un flux lisible de clés plutôt que des paires clé-valeur. Utilisez les mêmes options que celles décrites pour createReadStream() pour contrôler la plage et la direction.
Vous pouvez également obtenir ce flux en passant un objet options à createReadStream() avec keys définies sur true et values définies sur false . Le résultat est équivalent ; les deux flux fonctionnent en mode objet.
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]) Renvoie un flux de valeurs lisible plutôt que des paires clé-valeur. Utilisez les mêmes options que celles décrites pour createReadStream() pour contrôler la plage et la direction.
Vous pouvez également obtenir ce flux en passant un objet options à createReadStream() avec values définies sur true et keys définies sur false . Le résultat est équivalent ; les deux flux fonctionnent en mode objet.
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]) Renvoie un itérateur abstract-leveldown , qui alimente les flux lisibles ci-dessus. Les options sont les mêmes que les options de plage de createReadStream() et sont transmises au magasin sous-jacent.
Ces itérateurs prennent en for await...of :
for await ( const [ key , value ] of db . iterator ( ) ) {
console . log ( value )
}db.clear([options][, callback])Supprimez toutes les entrées ou une plage. Il n'est pas garanti qu'il soit atomique. Accepte les options de plage suivantes (avec les mêmes règles que sur les itérateurs) :
gt (supérieur à), gte (supérieur ou égal) définissent la limite inférieure de la plage à supprimer. Seules les entrées dont la clé est supérieure (ou égale) à cette option seront incluses dans la plage. Lorsque reverse=true l'ordre sera inversé, mais les entrées supprimées seront les mêmes.lt (inférieur à), lte (inférieur ou égal) définissent la limite supérieure de la plage à supprimer. Seules les entrées dont la clé est inférieure (ou égale) à cette option seront incluses dans la plage. Lorsque reverse=true l'ordre sera inversé, mais les entrées supprimées seront les mêmes.reverse (booléen, par défaut : false ) : supprime les entrées dans l'ordre inverse. Efficace uniquement en combinaison avec limit , pour supprimer les N derniers enregistrements.limit (nombre, par défaut : -1 ) : limite le nombre d'entrées à supprimer. Ce nombre représente un nombre maximum d'entrées et peut ne pas être atteint si vous arrivez en premier à la fin de la plage. Une valeur de -1 signifie qu'il n'y a pas de limite. Lorsque reverse=true les entrées avec les clés les plus élevées seront supprimées au lieu des clés les plus basses. Si aucune option n'est fournie, toutes les entrées seront supprimées. La fonction callback sera appelée sans argument si l'opération a réussi ou avec une WriteError si elle a échoué pour une raison quelconque.
Si aucun rappel n’est transmis, une promesse est renvoyée.
db.createWriteStream ? db.createWriteStream() a été supprimé afin de fournir un noyau plus petit et plus maintenable. Il existait principalement pour créer une symétrie avec db.createReadStream() mais après de nombreuses discussions, la supprimer était la meilleure solution.
Le principal moteur de cette évolution était la performance. Alors que db.createReadStream() fonctionne bien dans la plupart des cas d'utilisation, db.createWriteStream() dépendait fortement des clés et des valeurs de l'application. Nous ne pouvons donc pas fournir une implémentation standard et encourager la création d’un plus grand nombre d’implémentations write-stream pour résoudre le large éventail de cas d’utilisation.
Découvrez les implémentations que la communauté a produites ici.
Chaque fonction acceptant un rappel renvoie une promesse si le rappel est omis. La seule exception est le constructeur levelup lui-même, qui, si aucun rappel n'est transmis, ouvrira paresseusement le magasin sous-jacent en arrière-plan.
Exemple:
const db = levelup ( leveldown ( './my-db' ) )
await db . put ( 'foo' , 'bar' )
console . log ( await db . get ( 'foo' ) ) levelup est un EventEmitter et émet les événements suivants.
| Événement | Description | Arguments |
|---|---|---|
put | La clé a été mise à jour | key, value (n'importe laquelle) |
del | La clé a été supprimée | key (n'importe laquelle) |
batch | Le lot a été exécuté | operations (tableau) |
clear | Les entrées ont été supprimées | options (objet) |
opening | Le magasin sous-jacent ouvre ses portes | - |
open | Le magasin a ouvert | - |
ready | Alias d' open | - |
closing | Le magasin ferme | - |
closed | Le magasin est fermé. | - |
error | Une erreur s'est produite | error (Erreur) |
Par exemple vous pouvez faire :
db . on ( 'put' , function ( key , value ) {
console . log ( 'inserted' , { key , value } )
} ) Les magasins comme LevelDB sont thread-safe mais ils ne conviennent pas à l'accès avec plusieurs processus. Vous ne devriez ouvrir un magasin qu’à partir d’un seul processus Node.js. Les clusters Node.js sont constitués de plusieurs processus, une instance levelup ne peut donc pas non plus être partagée entre eux.
Voir Level/awesome pour des modules comme multileveldown qui peuvent vous aider si vous avez besoin qu'un seul magasin soit partagé entre les processus.
Level/levelup est un projet OPEN Open Source . Cela signifie que :
Les personnes apportant des contributions significatives et précieuses bénéficient d'un accès engagé au projet pour contribuer comme bon leur semble. Ce projet ressemble plus à un wiki ouvert qu'à un projet open source gardé standard.
Consultez le Guide des contributions pour plus de détails.
Plateforme de tests multi-navigateurs et Open Source ♥ Fourni par Sauce Labs.
Soutenez-nous avec un don mensuel sur Open Collective et aidez-nous à poursuivre notre travail.
MIT
