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發生了什麼事？快速而簡單的儲存。用於abstract-leveldown相容儲存的 Node.js 包裝器，遵循 LevelDB 的特性。
LevelDB 是 Google 建構的一個簡單的鍵值儲存。它用於 Google Chrome 和許多其他產品。 LevelDB 支援任意位元組數組作為鍵和值、單一get 、 put和delete操作、批次 put 和 delete 、雙向迭代器以及使用非常快速的 Snappy 演算法的簡單壓縮。
LevelDB 儲存按鍵字典順序排序的項目。這使得levelup的流介面（將 LevelDB 迭代器公開為可讀流）成為非常強大的查詢機制。
最常見的儲存是leveldown ，它提供了與 LevelDB 的純 C++ 綁定。有許多替代儲存可用，例如瀏覽器中的level.js或用於記憶體儲存的memdown 。它們通常支援鍵和值的字串和緩衝區。對於更豐富的資料類型，您可以使用encoding-down包裝儲存。
level包是推薦的入門方式。它方便地捆綁了levelup 、 leveldown和encoding-down 。它的主要導出是levelup - 即你可以執行var db = require('level') 。
我們的目標是支援 Active LTS 和目前 Node.js 版本以及瀏覽器。有關底層商店的支持，請參閱相應的文件。
如果您要升級：請參閱UPGRADING.md 。
首先你需要安裝levelup ！不包括任何商店，因此您也必須安裝leveldown （例如）。
$ npm install levelup leveldown所有操作都是異步的。如果您不提供回調，則會返回 Promise。
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()關閉底層儲存。回調將接收關閉期間遇到的任何錯誤作為第一個參數。
當您不再需要它來釋放資源時，您應該始終透過呼叫close()來清理您的levelup實例。一個商店不能由多個levelup實例同時開啟。
如果沒有傳遞回調，則傳回一個承諾。
db.put(key, value[, options][, callback]) put()是將資料插入儲存的主要方法。就levelup而言， key和value都可以是任何類型。
options被傳遞到底層儲存。
如果沒有傳遞回調，則傳回一個承諾。
db.get(key[, options][, callback])透過key從 store 取得一個值。 key可以是任何類型。如果商店中不存在，則回調或 Promise 將收到錯誤。找不到的 err 物件的類型為'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回錯誤，並且任何類型： value null或undefined的type: 'put'條目都會傳回錯誤。
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參數（如果提供）必須是物件並傳遞到底層儲存。
如果您的 put 有問題（例如value null或undefined ），則此方法可能會throw WriteError 。
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 （大於或等於）定義要串流傳輸的範圍的下限。只有鍵大於（或等於）此選項的條目才會包含在範圍中。當reverse=true時，順序將顛倒，但串流的條目將相同。
lt （小於）、 lte （小於或等於）定義要串流傳輸的範圍的上限。只有鍵小於（或等於）此選項的條目才會包含在範圍中。當reverse=true時，順序將顛倒，但串流的條目將相同。
reverse (boolean, default: false ) : 以相反的順序流條目。請注意，由於 LevelDB 等儲存的工作方式，反向查找可能比正向查找慢。
limit (number, default: -1 ) : 限制該流收集的條目數量。該數字代表最大條目數，如果您先到達範圍末尾，則可能無法達到。值為-1表示沒有限制。當reverse=true時，將傳回具有最高鍵的條目而不是最低鍵的條目。
keys （布林值，預設值： true ） ：結果是否應包含鍵。如果設定為true且values設為false ，則結果將只是鍵，而不是具有key屬性的物件。由createKeyStream()方法在內部使用。
values (boolean, default: 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 （大於或等於）定義要刪除的範圍的下限。只有鍵大於（或等於）此選項的條目才會包含在範圍中。當reverse=true時，順序將相反，但刪除的條目將是相同的。lt （小於）、 lte （小於或等於）定義要刪除的範圍的上限。只有鍵小於（或等於）此選項的條目才會包含在範圍中。當reverse=true時，順序將相反，但刪除的條目將是相同的。reverse (boolean, default: false ) : 以相反的順序刪除條目。僅與limit結合使用有效，刪除最後 N 筆記錄。limit (number, default: -1 ) : 限制要刪除的條目數。該數字代表最大條目數，如果您先到達範圍末尾，則可能無法達到。值為-1表示沒有限制。當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是一個OPEN 開源專案。這意味著：
做出重大和有價值貢獻的個人將獲得對該專案的承諾訪問權限，以做出他們認為合適的貢獻。這個專案更像是一個開放的維基百科，而不是一個標準的受保護的開源專案。
有關更多詳細信息，請參閱貢獻指南。
跨瀏覽器測試平台和開源 ♥ 由 Sauce Labs 提供。
每月在 Open Collective 上捐款支持我們，並幫助我們繼續我們的工作。
麻省理工學院
