Skip to content

Commit

Permalink
Clean up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ai
ai committed Jun 7, 2022
1 parent b8a5e61 commit 96f5d56
Show file tree
Hide file tree
Showing 4 changed files with 16 additions and 259 deletions.
60 changes: 14 additions & 46 deletions README.id-ID.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Mendukung penjelajah (browser) modern, IE [dengan Babel](https://developer.epage
alt="Disponsori oleh Evil Martians" width="236" height="54">
</a>


## Table of Contents

- [Perbandingan dengan UUID](#perbandingan-dengan-uuid)
Expand All @@ -42,17 +43,15 @@ Mendukung penjelajah (browser) modern, IE [dengan Babel](https://developer.epage
- [Alfabet dan Ukuran (Custom)](#alfabet-dan-ukuran-penyesuaian)
- [Generasi Random Bytes (Custom)](#generasi-random-bytes-custom)
- [Penggunaan](#penggunaan)
- [IE](#ie)
- [React](#react)
- [React Native](#react-native)
- [Rollup](#rollup)
- [PouchDB dan CouchDB](#pouchdb-dan-couchdb)
- [Mongoose](#mongoose)
- [Web Workers](#web-workers)
- [CLI](#cli)
- [Bahasa Pemrograman Lainnya](#bahasa-pemrograman-lainnya)
- [Alat](#alat)


## Perbandingan dengan UUID

Nano ID dapat dibandingkan dengan UUID v4 (yang berbasis acak / _randomly generated_). Nano ID dan UUID v4 memiliki jumlah bita yang mirip pada ID yang dihasilkan (126 bita pada NanoID dan 122 bita pada UUID), karenanya ia memiliki probabilitas _collision_ (konflik / tabrakan) yang hampir serupa:
Expand All @@ -65,6 +64,7 @@ Ada tiga buah perbedaan antara Nano ID dan UUID v4:
2. Kode sumber Nano ID **empat kali lebih kecil** ketimbang `uuid/v4`: 130 bytes dibanding 483 bytes.
3. Karena menggunakan trik alokasi memori, Nano ID **dua kali lebih cepat** ketimbang UUID.


## Benchmark

```rust
Expand Down Expand Up @@ -95,6 +95,7 @@ rndm 2,674,806 ops/sec

Konfigurasi pengujian: ThinkPad X1 Carbon Gen 9, Fedora 34, Node.js 16.10.


## Keamanan

_Lihat artikel yang informatif tentang teori angka acak: [Nilai acak yang aman dalam Node.js (English)](https://gist.github.com/joepie91/7105003c3b26e65efcea63f3db82dfba)_.
Expand All @@ -110,6 +111,7 @@ _Lihat artikel yang informatif tentang teori angka acak: [Nilai acak yang aman d

- **Kerentanan.** Untuk melaporkan sebuah _security vulnerability_ atau kerentanan, mohon menggunakan [Tidelift Security Contact](https://tidelift.com/security). Tidelift akan mengkoordinasikan pembetulan dan penyingkapan dari kerentanan tersebut.


## Instalasi

```bash
Expand All @@ -128,18 +130,14 @@ Nano ID tersedia dalam bentuk ES modules. Tidak perlu melakukan konfigurasi apap
import { nanoid } from 'nanoid'
```

Dalam Node.js, dapat digunakan gaya _import_ ala CommonJS:

```js
const { nanoid } = require('nanoid')
```

## API

Nano ID memiliki tiga buah API: normal (_blocking_), asinkronus (_asynchronous_), dan _non-secure_.

Bawaannya, Nano ID menggunakan simbol yang _URL-friendly_ (`A-Za-z0-9_-`) dan mengembalikan ID dengan 21 karakter (untuk memiliki probabilitas collision / tabrakan yang mirip dengan UUID v4).


### Blocking

Penggunaan Nano ID yang aman dan yang paling mudah.
Expand All @@ -161,6 +159,7 @@ Jangan lupa memeriksa tingkat keamanan dari ukuran ID dalam situs [ID collision

Dapat digunakan pula [custom alphabet](#custom-alphabet-or-size) atau [random generator](#custom-random-bytes-generator) yang lain.


### Async

Untuk menghasilkan bytes yang acak dan aman secara kriptografis, CPU mengumpulkan noise elektromagnetik. Umumnya, entropi sudah dikumpulkan terlebih dahulu.
Expand All @@ -181,6 +180,7 @@ Referensi lebih lanjut tentang entropi dapat dilihat pada dokumentasi fungsi [`c

Sayangnya, keuntungan Web Crypto API akan hilang di browser apabila menggunakan API asinkronus ini. Untuk sekarang, browser dibatasi hanya menggunakan API sinkronus (untuk keamanan) atau API asinkronus (lebih cepat, tetapi karena keuntungan Web Crypto hilang, keamanannya sedikit lebih rendah ketimbang penggunaan API sinkronus).


### Non-Secure

Konfigurasi bawaan Nano ID menggunakan random bytes generator yang berasal dari perangkat keras untuk keamanan dan probabilitas collision yang rendah. Apabila tidak terlalu memikirkan soal keamanan, dapat pula menggunakan non-secure generator yang lebih cepat.
Expand All @@ -190,6 +190,7 @@ import { nanoid } from 'nanoid/non-secure'
const id = nanoid() //=> "Uakgb_J5m9g-0JDMbcJqLJ"
```


### Alfabet dan Ukuran (Custom)

`customAlphabet` digunakan untuk membuat Nano ID dengan alfabet dan ukuran ID yang sesuai dengan kebutuhan (dapat dikustomisasi).
Expand Down Expand Up @@ -220,6 +221,7 @@ const nanoid = customAlphabet('1234567890abcdef', 10)
user.id = nanoid()
```


### Generasi Random Bytes (Custom)

`customRandom` digunakan untuk membuat Nano ID yang mengganti alfabet dan algoritma _random bytes generator_ yang telah diimplementasikan pada versi bawaan (dalam artian menggunakan algoritma sendiri untuk mendapatkan random bytes).
Expand Down Expand Up @@ -248,23 +250,8 @@ const nanoid = customRandom(urlAlphabet, 10, random)

API asinkronus dan non-secure tidak tersedia untuk fungsi `customRandom`.

## Penggunaan

### IE

Apabila mengimplementasikan di Internet Explorer, dibutuhkan untuk melakukan [transpile pada `node_modules`](https://developer.epages.com/blog/coding/how-to-transpile-node-modules-with-babel-and-webpack-in-a-monorepo/) dengan Babel dan menambahkan alias untuk `crypto` seperti berikut:

```js
// polyfills.js
if (!window.crypto) {
window.crypto = window.msCrypto
}
```

```js
import './polyfills.js'
import { nanoid } from 'nanoid'
```
## Penggunaan

### React

Expand Down Expand Up @@ -311,18 +298,6 @@ import 'react-native-get-random-values'
import { nanoid } from 'nanoid'
```

### Rollup

Untuk Rollup, dibutuhkan [`@rollup/plugin-node-resolve`](https://github.com/rollup/plugins/tree/master/packages/node-resolve) untuk versi browser.

```js
plugins: [
nodeResolve({
browser: true
})
]
```

### PouchDB dan CouchDB

Dalam PouchDB dan CouchDB, ID tidak bisa dimulai dengan underscore `_`. Sebuah _prefix_ dibutuhkan untuk mencegah hal ini terjadi, karena Nano ID mungkin menggunakan `_` sebagai karakter pertama dari ID yang dihasilkan.
Expand All @@ -336,16 +311,6 @@ db.put({
})
```

### Mongoose

```js
const mySchema = new Schema({
_id: {
type: String,
default: () => nanoid()
}
})
```

### Web Workers

Expand All @@ -360,6 +325,7 @@ nanoid() //=> "Uakgb_J5m9g-0JDMbcJqLJ"

Perhatian: ID yang dihasilkan dari non-secure dapat lebih mudah tabrakan / memiliki probabilitas collision yang lebih besar.


### CLI

Nano ID dapat didapatkan dengan cara menggunakan `npx nanoid` pada Terminal. Hanya diperlukan Node.js untuk ini, dan tidak perlu mengunduh dan menginstall Nano ID dalam sistem.
Expand All @@ -372,6 +338,7 @@ LZfXLFzPPR4NNrgjlWDxn

Bila ingin mengganti alfabet atau ukuran ID, dapat menggunakan [`nanoid-cli`](https://github.com/twhitbeck/nanoid-cli).


### Bahasa Pemrograman Lainnya

Nano ID telah bermigrasi ke berbagai macam bahasa. Seluruh versi dapat digunakan untuk mendapatkan ID generator yang sama pada sisi klien dan sisi penyedia layanan (_client-side_ dan _server-side_).
Expand Down Expand Up @@ -404,6 +371,7 @@ Nano ID telah bermigrasi ke berbagai macam bahasa. Seluruh versi dapat digunakan

Untuk environment lainnya, [CLI](#cli) tersedia untuk melakukan generasi ID dari command line / Terminal.


## Alat

- [ID Size Calculator](https://zelark.github.io/nano-id-cc/) menunjukkan probabilitas collision ketika melakukan konfigurasi alfabet dan ukuran.
Expand Down
72 changes: 0 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,9 @@ Supports modern browsers, IE [with Babel], Node.js and React Native.
* [Custom Alphabet or Size](#custom-alphabet-or-size)
* [Custom Random Bytes Generator](#custom-random-bytes-generator)
* [Usage](#usage)
* [IE](#ie)
* [React](#react)
* [React Native](#react-native)
* [Rollup](#rollup)
* [PouchDB and CouchDB](#pouchdb-and-couchdb)
* [Mongoose](#mongoose)
* [Web Workers](#web-workers)
* [CLI](#cli)
* [Other Programming Languages](#other-programming-languages)
Expand Down Expand Up @@ -156,12 +153,6 @@ as ESM in webpack, Rollup, Parcel, or Node.js.
import { nanoid } from 'nanoid'
```

In Node.js you can use CommonJS import:

```js
const { nanoid } = require('nanoid')
```


## API

Expand Down Expand Up @@ -324,41 +315,6 @@ the same result.

## Usage

### IE

If you support IE, you need to [transpile `node_modules`] by Babel
and add `crypto` alias. Moreover, `UInt8Array` in IE actually
is not an array and to cope with it, you have to convert it to an array
manually:

```js
// polyfills.js
if (!window.crypto && window.msCrypto) {
window.crypto = window.msCrypto

const getRandomValuesDef = window.crypto.getRandomValues

window.crypto.getRandomValues = function (array) {
const values = getRandomValuesDef.call(window.crypto, array)
const result = []

for (let i = 0; i < array.length; i++) {
result[i] = values[i];
}

return result
};
}
```

```js
import './polyfills.js'
import { nanoid } from 'nanoid'
```

[transpile `node_modules`]: https://developer.epages.com/blog/coding/how-to-transpile-node-modules-with-babel-and-webpack-in-a-monorepo/


### React

There’s no correct way to use Nano ID for React `key` prop
Expand Down Expand Up @@ -417,22 +373,6 @@ import { nanoid } from 'nanoid'
[`react-native-get-random-values`]: https://github.com/LinusU/react-native-get-random-values


### Rollup

For Rollup you will need [`@rollup/plugin-node-resolve`] to bundle browser version
of this library.:

```js
plugins: [
nodeResolve({
browser: true
})
]
```

[`@rollup/plugin-node-resolve`]: https://github.com/rollup/plugins/tree/master/packages/node-resolve


### PouchDB and CouchDB

In PouchDB and CouchDB, IDs can’t start with an underscore `_`.
Expand All @@ -449,18 +389,6 @@ db.put({
```


### Mongoose

```js
const mySchema = new Schema({
_id: {
type: String,
default: () => nanoid()
}
})
```


### Web Workers

Web Workers do not have access to a secure random generator.
Expand Down
Loading

0 comments on commit 96f5d56

Please sign in to comment.