You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To generate monotonically increasing ULIDs, create a monotonic counter.
76
+
To generate monotonically increasing ULIDs, create a monotonic counter with `monotonicFactory`.
93
77
94
-
*Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond*
78
+
> Note that the same seed time is being passed in for this example to demonstrate its behaviour when generating multiple ULIDs within the same millisecond
95
79
96
-
```javascript
97
-
import { monotonicFactory } from'ulid'
80
+
```typescript
81
+
import { monotonicFactory } from"ulid";
98
82
99
-
constulid=monotonicFactory()
83
+
const ulid =monotonicFactory();
100
84
101
85
// Strict ordering for the same timestamp, by incrementing the least-significant random bit by 1
102
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR8
103
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVR9
104
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRA
105
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRB
106
-
ulid(150000) // 000XAL6S41ACTAV9WEVGEMMVRC
86
+
ulid(150000);//"000XAL6S41ACTAV9WEVGEMMVR8"
87
+
ulid(150000);//"000XAL6S41ACTAV9WEVGEMMVR9"
88
+
ulid(150000);//"000XAL6S41ACTAV9WEVGEMMVRA"
89
+
ulid(150000);//"000XAL6S41ACTAV9WEVGEMMVRB"
90
+
ulid(150000);//"000XAL6S41ACTAV9WEVGEMMVRC"
107
91
108
92
// Even if a lower timestamp is passed (or generated), it will preserve sort order
109
-
ulid(100000) // 000XAL6S41ACTAV9WEVGEMMVRD
93
+
ulid(100000);//"000XAL6S41ACTAV9WEVGEMMVRD"
110
94
```
111
95
112
96
### Pseudo-Random Number Generators
113
97
114
-
`ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on node it will use `crypto.randomBytes`.
98
+
`ulid` automatically detects a suitable (cryptographically-secure) PRNG. In the browser it will use `crypto.getRandomValues` and on NodeJS it will use `crypto.randomBytes`.
115
99
116
-
#### Allowing the insecure `Math.random`
100
+
#### Using `Math.random` (insecure)
117
101
118
-
By default, `ulid` will not use `Math.random`, because that is insecure. To allow the use of `Math.random`, you'll have to use `factory` and `detectPrng`.
102
+
By default, `ulid` will not use `Math.random` to generate random values. You can bypass this limitation by overriding the PRNG:
119
103
120
-
```javascript
121
-
import { factory, detectPrng } from'ulid'
104
+
```typescript
105
+
const ulid =monotonicFactory(() =>Math.random());
122
106
123
-
constprng=detectPrng(true) // pass `true` to allow insecure
124
-
constulid=factory(prng)
125
-
126
-
ulid() // 01BXAVRG61YJ5YSBRM51702F6M
107
+
ulid(); // "01BXAVRG61YJ5YSBRM51702F6M"
127
108
```
128
109
129
-
#### Use your own PRNG
130
-
131
-
To use your own pseudo-random number generator, import the factory, and pass it your generator function.
110
+
### Validity
132
111
133
-
```javascript
134
-
import { factory } from'ulid'
135
-
importprngfrom'somewhere'
112
+
You can verify if a value is a valid ULID by using `isValid`:
136
113
137
-
constulid=factory(prng)
114
+
```typescript
115
+
import { isValid } from"ulid";
138
116
139
-
ulid() // 01BXAVRG61YJ5YSBRM51702F6M
117
+
isValid("01ARYZ6S41TSV4RRFFQ69G5FAV"); // true
118
+
isValid("01ARYZ6S41TSV4RRFFQ69G5FA"); // false
140
119
```
141
120
142
-
You can also pass in a `prng` to the `monotonicFactory` function.
121
+
### ULID Time
143
122
144
-
```javascript
145
-
import { monotonicFactory } from'ulid'
146
-
importprngfrom'somewhere'
123
+
You can encode and decode ULID timestamps by using `encodeTime` and `decodeTime` respectively:
Note that while `decodeTime` works on full ULIDs, `encodeTime` encodes only the _time portion_ of ULIDs:
154
132
155
-
Refer to [ulid/spec](https://github.com/ulid/spec)
133
+
```typescript
134
+
import { encodeTime } from"ulid";
156
135
157
-
## Specification
136
+
encodeTime(1469918176385); // "01ARYZ6S41"
137
+
```
158
138
159
-
Refer to [ulid/spec](https://github.com/ulid/spec)
139
+
### Tests
160
140
161
-
## Test Suite
141
+
Install dependencies using `npm install` first, and then simply run `npm test` to run the test suite.
162
142
163
-
```
164
-
npm test
165
-
```
143
+
## Specification
144
+
145
+
You can find the full specification, as well as information regarding implementations in other languages, over at [ulid/spec](https://github.com/ulid/spec).
166
146
167
147
## Performance
168
148
169
-
```
170
-
npm run perf
171
-
```
149
+
You can test `ulid`'s performance by running `npm run bench`:
172
150
173
151
```
174
-
ulid
175
-
336,331,131 op/s » encodeTime
176
-
102,041,736 op/s » encodeRandom
177
-
17,408 op/s » generate
178
-
179
-
180
-
Suites: 1
181
-
Benches: 3
182
-
Elapsed: 7,285.75 ms
152
+
Simple ulid x 56,782 ops/sec ±2.50% (86 runs sampled)
153
+
ulid with timestamp x 58,574 ops/sec ±1.80% (87 runs sampled)
0 commit comments