الصفحة الرئيسية>المتعلقة بالبرمجة>شفرة المصدر الأخرى
تنزيل

مستوى أعلى

؟ سيتم إهمال هذه الوحدة قريبًا، لأنه تم استبدالها بالمستوى abstract-level .

جدول المحتويات

انقر للتوسيع
  • مقدمة
  • المنصات المدعومة
  • الاستخدام
  • واجهة برمجة التطبيقات
    • 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]) (نموذج الصفيف)
    • db.batch() (نموذج متسلسل)
    • db.status
    • db.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 مصفوفات البايت العشوائية كمفاتيح وقيم، وعمليات الحصول على المفرد، ووضعها وحذفها ، ووضعها وحذفها على دفعات ، ومكررات ثنائية الاتجاه، والضغط البسيط باستخدام خوارزمية Snappy السريعة جدًا.

يقوم LevelDB بتخزين الإدخالات مرتبة معجميًا حسب المفاتيح. وهذا يجعل واجهة التدفق الخاصة بـ levelup - والتي تعرض مكررات LevelDB كتدفقات قابلة للقراءة - آلية استعلام قوية جدًا.

المتجر الأكثر شيوعًا هو leveldown الذي يوفر ربط C++ خالصًا بـ LevelDB. تتوفر العديد من المتاجر البديلة مثل 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

جميع العمليات غير متزامنة. إذا لم تقم بتوفير رد اتصال، فسيتم إرجاع الوعد. 

 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() لعمليات الكتابة المجمعة السريعة جدًا (سواء الوضع أو الحذف ). يجب أن تحتوي وسيطة 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])

وضع عملية وضع في قائمة الانتظار على الدفعة الحالية، ولا يتم الالتزام بها حتى يتم استدعاء write() على الدفعة. يجب أن تكون وسيطة options ، إذا تم توفيرها، كائنًا ويتم تمريرها إلى المتجر الأساسي.

قد تؤدي هذه الطريقة throw WriteError إذا كانت هناك مشكلة في وضعك (مثل أن تكون 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 (أكبر من أو يساوي) يحددان الحد الأدنى للنطاق المراد بثه. سيتم تضمين الإدخالات التي يكون فيها المفتاح أكبر من (أو يساوي) هذا الخيار فقط في النطاق. عندما reverse=true سيتم عكس الترتيب، لكن الإدخالات المتدفقة ستكون هي نفسها.

  • lt (أقل من)، lte (أقل من أو يساوي) يحددان الحد الأعلى للنطاق الذي سيتم بثه. سيتم تضمين الإدخالات التي يكون فيها المفتاح أقل من (أو يساوي) هذا الخيار فقط في النطاق. عندما reverse=true سيتم عكس الترتيب، لكن الإدخالات المتدفقة ستكون هي نفسها.

  • reverse (منطقي، افتراضي: false ) : دفق الإدخالات بترتيب عكسي. كن حذرًا، نظرًا للطريقة التي تعمل بها المتاجر مثل LevelDB، فقد يكون البحث العكسي أبطأ من البحث الأمامي.

  • limit (الرقم، الافتراضي: -1 ) : تحديد عدد الإدخالات التي تم جمعها بواسطة هذا الدفق. يمثل هذا الرقم الحد الأقصى لعدد الإدخالات وقد لا يتم الوصول إليه إذا وصلت إلى نهاية النطاق أولاً. القيمة -1 تعني عدم وجود حد. عندما 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 (أكبر من أو يساوي) تحدد الحد الأدنى للنطاق المراد حذفه. سيتم تضمين الإدخالات التي يكون فيها المفتاح أكبر من (أو يساوي) هذا الخيار فقط في النطاق. عندما reverse=true سيتم عكس الترتيب، لكن الإدخالات المحذوفة ستكون هي نفسها.
  • lt (أقل من)، lte (أقل من أو يساوي) تحدد الحد الأعلى للنطاق المراد حذفه. سيتم تضمين الإدخالات التي يكون فيها المفتاح أقل من (أو يساوي) هذا الخيار فقط في النطاق. عندما reverse=true سيتم عكس الترتيب، لكن الإدخالات المحذوفة ستكون هي نفسها.
  • reverse (منطقي، افتراضي: false ) : حذف الإدخالات بترتيب عكسي. فعال فقط مع limit لإزالة آخر N من السجلات.
  • limit (الرقم، الافتراضي: -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 هو مشروع مفتوح المصدر . وهذا يعني أن:

يتم منح الأفراد الذين يقدمون مساهمات كبيرة وقيمة إمكانية الوصول إلى المشروع للمساهمة على النحو الذي يرونه مناسبًا. هذا المشروع يشبه الويكي المفتوح أكثر من كونه مشروعًا قياسيًا مفتوح المصدر ومحميًا.

راجع دليل المساهمة لمزيد من التفاصيل.

شكرا جزيلا

منصة اختبار عبر المتصفحات ومصدر مفتوح ♥ مقدمة من Sauce Labs.

يتبرع

ادعمنا بالتبرع الشهري على Open Collective وساعدنا على مواصلة عملنا.

رخصة

معهد ماساتشوستس للتكنولوجيا

يوسع
معلومات إضافية
تطبيقات ذات صلة
نوصي لك
أخبار ذات صلة الكل