kuuid - npm Package Compare versions

Comparing version 0.6.2 to 1.0.1

index.d.ts

@@ -9,2 +9,22 @@
 declare namespace kuuid {
+
+  interface IDOpts {
+    /** The timestamp used to generate the id. Either an ISO string or number of milliseconds
+     * since 1970. Default: undefined, which 
+     */
+    timestamp?: string | number | undefined;
+    /** The amount of random data to append to the time portion of the id. A number
+     * between 1 and 4. Default: 4.
+     */
+    random?: number;
+    /** Whether to generate the id in oldest-first order (false) or newest-first order (true).
+     * Default: false
+     */
+    reverse?: boolean;
+    /** Whether to generate the id to second precision (false) or millisecond precision (true).
+     * Default: false
+     */
+    millsecond?: false;
+  }
+
   /**
@@ -15,3 +35,3 @@ * Generate the 8-character prefix
    */
-  function prefix(t? : string | number): string;
+  function prefix(opts?: IDOpts | string | number): string;
 
@@ -23,10 +43,10 @@ /**
    */
-  function prefixr(t? : string | number): string;
+  function prefixr(t?: string | number): string;
 
-    /**
-   * Generate the 8-character prefix - ms mode
-   * @param t ISO-8601 date string or number of milliseconds since 1970
-   * @return 8-character prefix string
-   */
-  function prefixms(t? : string | number): string;
+  /**
+ * Generate the 8-character prefix - ms mode
+ * @param t ISO-8601 date string or number of milliseconds since 1970
+ * @return 8-character prefix string
+ */
+  function prefixms(t?: string | number): string;
 
@@ -41,6 +61,6 @@ /**
    * Generate a date/time sortable 32 character unique identifier
-   * @param t ISO-8601 date string or number of milliseconds since 1970
+   * @param t ISO-8601 date string or number of milliseconds since 1970 or options
    * @return 32-character id
    */
-  function id(t? : string | number): string;
+  function id(opts?: IDOpts | string | number): string;
 
@@ -52,10 +72,10 @@ /**
    */
-  function idr(t? : string | number): string;
+  function idr(t?: string | number): string;
 
-    /**
-   * Generate short a date/time sortable 32 character unique identifier
-   * @param t ISO-8601 date string or number of milliseconds since 1970
-   * @return 32-character id
-   */
-  function ids(t? : string | number): string;
+  /**
+ * Generate short a date/time sortable 32 character unique identifier
+ * @param t ISO-8601 date string or number of milliseconds since 1970
+ * @return 32-character id
+ */
+  function ids(t?: string | number): string;
 
@@ -67,10 +87,10 @@ /**
    */
-  function idsr(t? : string | number): string;
+  function idsr(t?: string | number): string;
 
-    /**
-   * Generate a millisecond, time sortable 32 character unique identifier
-   * @param t ISO-8601 date string or number of milliseconds since 1970
-   * @return 32-character id
-   */
-  function idms(t? : string | number): string;
+  /**
+ * Generate a millisecond, time sortable 32 character unique identifier
+ * @param t ISO-8601 date string or number of milliseconds since 1970
+ * @return 32-character id
+ */
+  function idms(t?: string | number): string;
 }
@@ -77,0 +97,0 @@

index.js

@@ -21,16 +21,19 @@ // standard Node.js crypto library
 // that is base62 encoded and sorts in time order
-const prefix = function (t) {
-  // get time stamp for now
-  const timestamp = ts(t)
+const prefix = function (opts) {
+  if (typeof opts === 'string' || typeof opts === 'number') {
+    opts = {
+      timestamp: opts,
+      reverse: false,
+      random: 4,
+      millisecond: false
+    }
+  } else {
+    opts = opts || {}
+  }
 
-  // turn timestamp into 8-digit, base-62 encoded string
-  return base62Encode(timestamp).padStart(8, '0')
-}
-
-// calculate an 8-digit prefix for the timestamp 't'
-// that is base62 encoded and sorts in time order
-// but with milliseconds
-const prefixms = function (t) {
   // get time stamp for now
-  const timestamp = tsms(t)
+  let timestamp = opts.millisecond ? tsms(opts.timestamp) : ts(opts.timestamp)
+  if (opts.reverse) {
+    timestamp = maxTS - timestamp
+  }
 
@@ -41,25 +44,4 @@ // turn timestamp into 8-digit, base-62 encoded string
 
-// calculate an 8-digit prefix for the timestamp 't'
-// that is base62 encoded and sorts in reverse time order
-const prefixReverse = function (t) {
-  // get time stamp for now
-  const timestamp = maxTS - ts(t)
-
-  // turn timestamp into 8-digit, base-62 encoded string
-  return base62Encode(timestamp).padStart(8, '0')
-}
-
-// calculate an 8-digit prefix for the timestamp 't'
-// that is base62 encoded and sorts in reverse time order
-// but with milliseconds
-const prefixReverseMs = function (t) {
-  // get time stamp for now
-  const timestamp = maxTS - tsms(t)
-
-  // turn timestamp into 8-digit, base-62 encoded string
-  return base62Encode(timestamp).padStart(8, '0')
-}
-
 const rand = function (n) {
-  if (!n) {
+  if (!n || n < 1 || n > 4) {
     n = 4
@@ -78,4 +60,16 @@ }
 // generate a kuuid
-const id = function (t) {
-  return prefix(t) + rand()
+const id = function (opts) {
+  opts = opts || {}
+  const ty = typeof opts
+  if (['string', 'number'].includes(ty)) {
+    return prefix(opts) + rand()
+  }
+  if (ty === 'object') {
+    opts.timestamp = opts.timestamp ? opts.timestamp : undefined
+    opts.random = opts.random ? opts.random : 4
+    opts.reverse = !!opts.reverse
+    opts.millisecond = !!opts.millisecond
+    return prefix(opts) + rand(opts.random)
+  }
+  throw new Error('invalid parameters')
 }
@@ -85,3 +79,3 @@
 const idms = function (t) {
-  return prefixms(t) + rand()
+  return id({ timestamp: t, millisecond: true })
 }
@@ -91,3 +85,3 @@
 const idr = function (t) {
-  return prefixReverse(t) + rand()
+  return id({ timestamp: t, reverse: true })
 }
@@ -97,3 +91,3 @@
 const idmsr = function (t) {
-  return prefixReverseMs(t) + rand()
+  return id({ timestamp: t, reverse: true, millisecond: true })
 }
@@ -103,10 +97,25 @@
 const ids = function (t) {
-  return prefixms(t) + rand(2)
+  return id({ timestamp: t, random: 2 })
 }
 
-// generate short id
+// generate short id (reverse)
 const idsr = function (t) {
-  return prefixReverse(t) + rand(2)
+  return id({ timestamp: t, reverse: true, random: 2 })
 }
 
+// prefix milliseconds
+const prefixms = function (t) {
+  return prefix({ timestamp: t, millisecond: true })
+}
+
+// prefix reverse
+const prefixReverse = function (t) {
+  return prefix({ timestamp: t, reverse: true })
+}
+
+// prefix milliseconds reverse
+const prefixReverseMs = function (t) {
+  return prefix({ timestamp: t, reverse: true, millisecond: true })
+}
+
 module.exports = {
@@ -113,0 +122,0 @@ id,

package.json

 {
   "name": "kuuid",
-  "version": "0.6.2",
+  "version": "1.0.1",
   "description": "K-sortable UUID - roughly time-sortable unique id generator",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -9,3 +9,3 @@ # kuuid
 - unique - no two ids will be the same, or at least the likelihood of a clash is vanishingly small.
-- time-sortable - the ids sort into time order, with one second precision.
+- time-sortable - the ids sort into time order (or reverse time order), with one second (or millisecond) precision.
 
@@ -50,92 +50,45 @@ If a `kuuid`-generated id were used as a database's unique identifier, it would sort roughly in time order (`kuuid.id()`), or reverse time order (`kuuid.idr()`)
 
-Supplying no parameter to `kuuid.id()` uses the current time to generate the timestamp part of the id. You may also supply your own date/time:
+## Parameters
 
-```js
-// 'now'
-kuuid.id()
+By default, the `id()` function returns an id made up of a timestamp derived from "now" to second precision, 128 bits of data and it will sort in oldest-first order. This can be configured by overriding these defaults:
 
-// ISO String 
-kuuid.id('2018-07-20T10:10:34.234Z')
-
-// millseconds since 1970
-kuuid.id(1514764800000)
-```
-
-## Reverse mode
-
-If you want your data to sort into "newest first" order, then `kuuid.idr()` returns an id that sorts in the opposite order:
-
 ```js
-// 'now'
-kuuid.idr()
-// zzyIy6DZ2SKTqh2WpV6D0DTbkK0kbn5u
-
-// Epoch
-kuuid.idr('1970-01-01T00:00:00Z')
-// zzzzzzzz2v3VKT4Sl9yV2f6v673SDt5v
+const id = kuuid.id({
+  timestamp: '2000-01-01T10:24:22.000Z', // use a known timestamp
+  random: 1, // use less random data
+  reverse: true, // sort in newest first order
+  millisecond: true // the timestamp should be to millisecond precision
+})
 ```
 
-## Millisecond mode
+- `timestamp` - an ISO string representing the date/time required or an integer representing the number of milliseconds since 1970. Default "now"
+- `random` - the quantity of random data. Between 1 and 4. Default `4`.
+- `reverse` - if true, the id will sort in newest-first order. Default `false`.
+- `millisecond` - if true, the id's time component will be stored with milliecond precision. Default `false`.
 
-If you want your ids to have millsecond prevision then use `idms()`:
+For backwards compatibility, the `id()` function will also accept a string or number parameter representing the timestamp.
 
 ```js
 // 'now'
-kuuid.idms()
-// 0T6vppV82RX4Nx1ZzGqB0Exjjs4fkuhh
-```
+kuuid.id()
 
-```js
-// 'now' reverse
-kuuid.idmsr()
-// zWt4A9Wz3TxK0h4MRkec06xADk3kIemn
-```
-
-## Short ids
-
-If you want your ids shorter (timestamp + 64 bits of random data ), then use `ids()` & `idsr()` for forward and reverse, respectively:
-
-```js
-// forward
-kuuid.ids()
-// 0S9QEzP23Wyk3p4IfNi6
-
-// reverse
-kuuid.idsr()
-// zzyFmalU06RfUZ3zMoay
-```
-
-## Generating a prefix
-
-If you only need the time-based prefix, you can call `kuuid.prefix()`:
-
-```js
-// 'now'
-kuuid.prefix()
-
 // ISO String 
-kuuid.prefix('2018-07-20T10:10:34.234Z')
+kuuid.id('2018-07-20T10:10:34.234Z')
 
 // millseconds since 1970
-kuuid.prefix(1514764800000)
+kuuid.id(1514764800000)
 ```
 
-or for a reverse-mode prefix:
+## Shortcut functions
 
-```js
-kuuid.prefixReverse()
-```
+- `idr()` - returns an id that sorts in newest-first order.
+- `idms()` - returns an id with millisecond precision.
+- `ids()` - returns a shorter id (64-bits of random data).
+- `idsr()` - returns a short it in newest-first order.
+- `prefix()` - returns only the time prefix.
+- `prefixReverse()` - returns only the time prefix (reverse order).
+- `prefixms()` - returns only the time prefix with ms precision.
+- `prefixReverseMs()` - returns only the time prefix with ms precision. (reverse order).
+- `rand()` - returns the random portion of the id.
 
-or for a millisecond-precision version:
-
-```js
-kuuid.prefixms()
-```
-
-or for a millisecond-precision reversed version:
-
-```js
-kuuid.prefixReverseMs()
-```
-
 ## How does it work?
@@ -146,3 +99,3 @@
 - 8 characters representing the number of seconds since 1st January 1970.
-- 24 characters containing random data.
+- 24 characters containing random data (for the default 128-bits)
 
@@ -149,0 +102,0 @@ The front eight characters allow the string to be sorted by time. Two ids created in the same second will have the same front eight characters. The remaining 24 characters contain 128 bits of random data.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

24348

increased by4.9%

Lines of code

232

increased by14.29%

Number of low quality alerts

0

decreased by-100%

Worsened metrics

Number of lines in readme file

112

decreased by-29.56%

No dependency changes