Nano ID

مُولِّد مُعرِّفات فريدة صغير الحجم وآمن ومتوافق مع الروابط (URL) لجافاسكربت.

"مستوى مذهل من الكمالية التي لا معنى لها، والتي يستحيل ألّا تحظى بالاحترام."

صغير الحجم. 118 بايت فقط (بعد التصغير والضغط ببروتلي). بدون أيّ اعتماديات خارجية. يتم التحكّم بالحجم عبر Size Limit.
آمن. يستخدم مُولِّد أرقام عشوائية على مستوى العتاد. يمكن استخدامه في بيئات الكلستر.
مُعرِّفات قصيرة. يستخدم أبجدية أكبر من UUID وهي (A-Za-z0-9_-). لذا تم تقليص حجم المُعرِّف من 36 إلى 21 رمزًا.
قابل للنقل. تم نقل Nano ID إلى أكثر من 20 لغة برمجة.

</div>

import { nanoid } from 'nanoid'
model.id = nanoid() //=> "V1StGXR8_Z5jdHi6B-myT"

Made at <b><a href="https://evilmartians.com/devtools?utm_source=nanoid&utm_campaign=devtools-button&utm_medium=github">Evil Martians</a></b>, product consulting for <b>developer tools</b>.

المقارنة مع UUID

Nano ID قابل للمقارنة مع UUID v4 (المبني على العشوائية). يحتوي على عدد مماثل من البتّات العشوائية في المُعرِّف (126 في Nano ID و122 في UUID)، لذا فإنّ احتمالية التكرار متقاربة:

لكي تكون هناك فرصة واحدة من مليار لحدوث تكرار، يجب توليد 103 تريليون مُعرِّف من النوع v4.

يوجد اختلافان رئيسيان بين Nano ID و UUID v4:

يستخدم Nano ID أبجدية أكبر، لذا يتم ضغط عدد مماثل من البتّات العشوائية في 21 رمزًا فقط بدلاً من 36.
كود Nano ID أصغر بـ 4 مرات من حزمة uuid/v4: 118 بايت مقابل 423.

اختبار الأداء

</div>

rust

$ node ./test/benchmark.js
crypto.randomUUID       21,741,317 ops/sec
uuid v4                 21,204,378 ops/sec
@napi-rs/uuid           10,236,615 ops/sec
uid/secure              10,567,676 ops/sec
@lukeed/uuid             8,647,481 ops/sec
nanoid                   7,800,308 ops/sec
customAlphabet           9,697,350 ops/sec
nanoid for browser         576,759 ops/sec
secure-random-string       529,253 ops/sec
uid-safe.sync              526,459 ops/sec

Non-secure:
uid                     31,379,525 ops/sec
nanoid/non-secure        3,678,505 ops/sec
rndm                     3,767,185 ops/sec

بيئة الاختبار: Framework 13 7840U، فيدورا 39، Node.js 21.6.

الأمان

اقرأ مقالاً جيداً عن نظرية مُولِّدات الأرقام العشوائية: Secure random values (in Node.js)

عدم القابلية للتنبؤ. بدلاً من استخدام Math.random() غير الآمن، يستخدم Nano ID وحدة crypto في Node.js و Web Crypto API في المتصفحات. هذه الوحدات تستخدم مُولِّد أرقام عشوائية على مستوى العتاد لا يمكن التنبؤ به.
التوزيع المنتظم. random % alphabet هو خطأ شائع عند برمجة مُولِّد مُعرِّفات. التوزيع لن يكون متساويًا؛ بعض الرموز ستظهر بتواتر أقل من غيرها. وهذا يقلّل عدد المحاولات اللازمة للكسر بالقوة الغاشمة. يستخدم Nano ID خوارزمية أفضل وقد تم اختباره للتحقّق من انتظام التوزيع.
موثّق جيداً: جميع الحيل البرمجية في Nano ID موثّقة. اطّلع على التعليقات في الكود المصدري.
الثغرات الأمنية: للإبلاغ عن ثغرة أمنية، يُرجى استخدام جهة اتصال Tidelift الأمنية. سيقوم Tidelift بتنسيق الإصلاح والإفصاح.

التثبيت

ESM

يعمل Nano ID 5 مع مشاريع ESM (باستخدام import) في الاختبارات أو سكربتات Node.js.

</div>

bash

npm install nanoid

CommonJS

يمكن استخدام Nano ID مع CommonJS بإحدى الطرق التالية:

يمكنك استخدام require() لاستيراد Nano ID. تحتاج إلى استخدام أحدث إصدار من Node.js 22.12 (يعمل مباشرة) أو Node.js 20 (مع علامة --experimental-require-module).
لـ Node.js 18 يمكنك استيراد Nano ID ديناميكيًا كالتالي:

</div>

let nanoid
module.exports.createID = async () => {
  if (!nanoid) ({ nanoid } = await import('nanoid'))
  return nanoid() // => "V1StGXR8_Z5jdHi6B-myT"
}

يمكنك استخدام Nano ID 3.x (ما زلنا ندعمه):

</div>

bash

npm install nanoid@3

JSR

JSR هو بديل لـ npm بحوكمة مفتوحة وتطوير نشط (على عكس npm).

</div>

bash

npx jsr add @sitnik/nanoid

يمكنك استخدامه في Node.js و Deno و Bun وغيرها.

</div>

// استبدل `nanoid` بـ `@sitnik/nanoid` في جميع الاستيرادات
import { nanoid } from '@sitnik/nanoid'

لـ Deno ثبّته عبر deno add jsr:@sitnik/nanoid أو استورده من jsr:@sitnik/nanoid.

CDN

للتجارب السريعة، يمكنك تحميل Nano ID من CDN. لكن لا يُنصح باستخدامه في الإنتاج بسبب انخفاض أداء التحميل.

</div>

import { nanoid } from 'https://cdn.jsdelivr.net/npm/nanoid/nanoid.js'

واجهة البرمجة (API)

يمتلك Nano ID واجهتي برمجة: عادية وغير آمنة.

بشكل افتراضي، يستخدم Nano ID رموزًا متوافقة مع الروابط (A-Za-z0-9_-) ويُنتج مُعرِّفًا مكوّنًا من 21 حرفًا (ليكون احتمال التكرار مماثلاً لـ UUID v4).

متزامن (Blocking)

الطريقة الأسهل والأكثر أمانًا لاستخدام Nano ID.

في حالات نادرة قد يحجب المعالج عن العمليات الأخرى أثناء جمع الضوضاء لمُولِّد الأرقام العشوائية على مستوى العتاد.

</div>

import { nanoid } from 'nanoid'
model.id = nanoid() //=> "V1StGXR8_Z5jdHi6B-myT"

إذا أردت تقليل حجم المُعرِّف (وزيادة احتمالية التكرار)، يمكنك تمرير الحجم كمعامل.

</div>

nanoid(10) //=> "IRFa-VaY2b"

لا تنسَ التحقّق من أمان حجم المُعرِّف الخاص بك عبر حاسبة احتمالية تكرار المُعرِّف.

يمكنك أيضًا استخدام أبجدية مخصّصة أو مُولِّد أرقام عشوائية مخصّص.

غير آمن (Non-Secure)

بشكل افتراضي، يستخدم Nano ID توليد بايتات عشوائية على مستوى العتاد من أجل الأمان وتقليل احتمالية التكرار. إذا لم يكن الأمان مهمًا بالنسبة لك، يمكنك استخدامه في بيئات لا تتوفر فيها مُولِّدات أرقام عشوائية على مستوى العتاد.

</div>

import { nanoid } from 'nanoid/non-secure'
const id = nanoid() //=> "Uakgb_J5m9g-0JDMbcJqLJ"

أبجدية أو حجم مخصّص

تُرجع customAlphabet دالة تتيح لك إنشاء nanoid بأبجديتك وحجمك الخاصّين.

</div>

import { customAlphabet } from 'nanoid'
const nanoid = customAlphabet('1234567890abcdef', 10)
model.id = nanoid() //=> "4f90d13a42"

import { customAlphabet } from 'nanoid/non-secure'
const nanoid = customAlphabet('1234567890abcdef', 10)
user.id = nanoid()

تحقّق من أمان أبجديتك المخصّصة وحجم المُعرِّف عبر حاسبة احتمالية تكرار المُعرِّف. لمزيد من خيارات الأبجديات، اطّلع على nanoid-dictionary.

يجب أن تحتوي الأبجدية على 256 رمزًا أو أقل. وإلا فإن أمان خوارزمية المُولِّد الداخلية غير مضمون.

بالإضافة إلى تحديد حجم افتراضي، يمكنك تغيير حجم المُعرِّف عند استدعاء الدالة:

</div>

import { customAlphabet } from 'nanoid'
const nanoid = customAlphabet('1234567890abcdef', 10)
model.id = nanoid(5) //=> "f01a2"

مُولِّد بايتات عشوائية مخصّص

تتيح لك customRandom إنشاء nanoid واستبدال الأبجدية ومُولِّد البايتات العشوائية الافتراضي.

في هذا المثال، يتم استخدام مُولِّد مبني على بذرة (seed):

</div>

import { customRandom } from 'nanoid'

const rng = seedrandom(seed)
const nanoid = customRandom('abcdef', 10, size => {
  return new Uint8Array(size).map(() => 256 * rng())
})

nanoid() //=> "fbaefaadeb"

يجب أن تقبل دالة random حجم المصفوفة وتُرجع مصفوفة من الأرقام العشوائية.

إذا أردت استخدام نفس الرموز المتوافقة مع الروابط مع customRandom، يمكنك الحصول على الأبجدية الافتراضية عبر urlAlphabet.

</div>

const { customRandom, urlAlphabet } = require('nanoid')
const nanoid = customRandom(urlAlphabet, 10, random)

ملاحظة: بين إصدارات Nano ID قد يتغيّر تسلسل استدعاء مُولِّد الأرقام العشوائية. إذا كنت تستخدم مُولِّدات مبنية على بذرة، فإننا لا نضمن نفس النتيجة.

الاستخدام

React

لا توجد طريقة صحيحة لاستخدام Nano ID كخاصية key في React لأنها يجب أن تكون ثابتة بين عمليات التصيير (renders).

</div>

jsx

function Todos({ todos }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={nanoid()}>
          {' '}
          /* لا تفعل هذا */
          {todo.text}
        </li>
      ))}
    </ul>
  )
}

يجب عليك بدلاً من ذلك استخدام مُعرِّف ثابت من داخل عنصر القائمة.

</div>

jsx

const todoItems = todos.map(todo => <li key={todo.id}>{todo.text}</li>)

في حال لم تمتلك مُعرِّفات ثابتة، يُفضّل استخدام الفهرس (index) كـ key بدلاً من nanoid():

</div>

jsx

const todoItems = todos.map((text, index) => (
  <li key={index}>
    {' '}
    /* غير مُوصى به لكنه أفضل من nanoid(). استخدمه فقط إذا لم تكن لديك مُعرِّفات
    ثابتة. */
    {text}
  </li>
))

إذا كنت تحتاج فقط إلى مُعرِّفات عشوائية لربط العناصر ببعضها مثل labels وحقول الإدخال، يُنصح باستخدام useId. تمت إضافة هذا الـ hook في React 18.

React Native

لا يحتوي React Native على مُولِّد أرقام عشوائية مدمج. يعمل البوليفِل التالي مع React Native العادي و Expo بدءًا من الإصدار 39.x.

اطّلع على توثيق react-native-get-random-values وثبّتها.
استوردها قبل Nano ID.

</div>

import 'react-native-get-random-values'
import { nanoid } from 'nanoid'

PouchDB و CouchDB

في PouchDB و CouchDB، لا يمكن أن تبدأ المُعرِّفات بشرطة سفلية _. يلزم إضافة بادئة لتجنّب هذه المشكلة، لأن Nano ID قد يستخدم _ في بداية المُعرِّف بشكل افتراضي.

أَعِد تعريف المُعرِّف الافتراضي بالخيار التالي:

</div>

db.put({
  _id: 'id' + nanoid(),
  …
})

سطر الأوامر (CLI)

يمكنك الحصول على مُعرِّف فريد في الطرفية عبر تشغيل npx nanoid. تحتاج فقط إلى Node.js مثبّتًا على النظام. لا يلزم تثبيت Nano ID مسبقًا.

</div>

$ npx nanoid
npx: installed 1 in 0.63s
LZfXLFzPPR4NNrgjlWDxn

يمكن تحديد حجم المُعرِّف المُولَّد عبر خيار --size (أو -s):

</div>

$ npx nanoid --size 10
L3til0JS4z

يمكن تحديد أبجدية مخصّصة عبر خيار --alphabet (أو -a) (لاحظ أن --size مطلوب في هذه الحالة):

</div>

$ npx nanoid --alphabet abc --size 15
bccbcabaabaccab

TypeScript

يتيح Nano ID تحويل النصوص المُولَّدة إلى أنواع مبهمة (opaque types) في TypeScript. مثال:

</div>

declare const userIdBrand: unique symbol
type UserId = string & { [userIdBrand]: true }

// استخدم معامل النوع الصريح:
mockUser(nanoid<UserId>())

interface User {
  id: UserId
  name: string
}

const user: User = {
  // يتم التحويل تلقائيًا إلى UserId:
  id: nanoid(),
  name: 'Alice'
}

لغات البرمجة الأخرى

تم نقل Nano ID إلى العديد من اللغات. يمكنك استخدام هذه الإصدارات للحصول على نفس مُولِّد المُعرِّفات على جانبَي العميل والخادم.

</div>

C
C#
C++
Clojure and ClojureScript
ColdFusion/CFML
Crystal
Dart & Flutter
Elixir
Gleam
Go
Haskell
Haxe
Janet
Java
Kotlin
MySQL/MariaDB
Nim
OCaml
Perl
PHP
Python native implementation with dictionaries and fast implementation (written in Rust)
Postgres Extension and Native Function
R (with dictionaries)
Ruby
Rust
Swift
Unison
V
Zig

للبيئات الأخرى، يتوفر سطر الأوامر لتوليد المُعرِّفات من الطرفية.

الأدوات

حاسبة حجم المُعرِّف تعرض احتمالية التكرار عند تعديل أبجدية المُعرِّف أو حجمه.
nanoid-dictionary تحتوي على أبجديات شائعة لاستخدامها مع customAlphabet.
nanoid-good للتأكد من أن المُعرِّف لا يحتوي على كلمات غير لائقة.

</div>