README updates

Author: dingosky

.vscode/settings.json

@@ -17,6 +17,7 @@
     "dingoskyme",
     "FFTFTTFFTFTTFFTT",
     "GACGGTCG",
+    "Hmmmm",
     "insgkskn",
     "JMGP",
     "kiyooodd",

README.md

@@ -25,6 +25,7 @@ Simple, flexible and efficient generation of probably unique identifiers (`puid`
     - [ID randomness](#IDRandomness)
     - [Efficiency](#Efficiency)
     - [Overkill and Under Specify](#Overkill)
+- [Efficiencies](#Efficiencies)
 - [tl;dr](#tl;dr)
 
 ## <a name="Overview"></a>Overview
@@ -255,7 +256,7 @@ Rather, a random string represents _captured_ entropy, entropy that was produced
   // => '18f6303a'
 ```
 
-In this case, the entropy of the string **`'18f6303a'`** is 1 bit. That's it; 1 bit. The same entropy as when the outcome **`'1'`** is observed. In either case, there are only two possible, equally likely outcomes and the resulting entropy is therefore 1 bit. It's important to have this clear understanding: 
+In this case, the entropy of the string **`'18f6303a'`** is 1 bit. That's it; 1 bit. The same entropy as when the outcome **`'1'`** is observed. In either case, there are only two equally possible outcomes and the resulting entropy is therefore 1 bit. It's important to have this clear understanding: 
 
  > _**Entropy is a measure in the uncertainty of an event, independent of the representation of that uncertainty**_
 
@@ -339,7 +340,7 @@ First, consider the amount of source entropy used in the code above. The JavaScr
 
 Second, consider how much entropy was captured by the ID. Given there are 26 characters, each character represents log<sub>2</sub>(26) = 4.7 bits of entropy. So each generated ID represents 8 * 4.7 = 37.6 bits of entropy.
 
-Hmmmm. That means the ratio of ID entropy to source entropy is 37.6 / 464 = 0.09, or a whopping **9%**. That's not an efficiency most developers would be comfortable with. Granted, this is a particularly egregious example, but most random ID generation suffers such inefficient use of source entropy.
+Hmmmm. That means the ratio of ID entropy to source entropy is 37.6 / 424 = 0.09, or a whopping **9%**. That's not an efficiency most developers would be comfortable with. Granted, this is a particularly egregious example, but most random ID generation suffers such inefficient use of source entropy.
 
 Without delving into the specifics (see the code?), `puid-js` employs various means to maximize the use of source entropy. In comparison, `puid-js` uses **87.5%** of source entropy in generating random IDs using lower case alpha characters. For character sets with counts equal a power of 2, `puid-js` uses 100% of source entropy.
 
@@ -349,7 +350,7 @@ As previous noted, the entropy of a random string is equal to the entropy per ch
 
 <a name="UUIDCharacters"></a>
 
-However, the total entropy of a string is the product of the entropy per character times the string length *only* if each character in the final string is equally probable. This is always the case for `puid-js`, and is usually the case for other random string generators. There is, however, a notable exception: the version 4 string representation of a `uuid`. As defined in [RFC 4122, Section 4.4](https://tools.ietf.org/html/rfc4122#section-4.4), a v4 `uuid` uses a total of 32 hex and 4 hyphen characters. Although the hex characters can represent 4 bits of entropy each, 6 bits of the hex representation in a `uuid` are actually fixed, so there is only `32*4 - 6 = 122`-bits of entropy (not 128). The 4 fixed-position hyphen characters contribute zero entropy. So a 36 character `uuid` has an `ere` of `122 / (36*8) = 0.40`, or **40%**. Compare that to, say, the default `puid-js` generator, which has slightly higher entropy (128 bits) and yet yields an `ere` of 0.75, or **75%**. Who doesn't love efficiency?
+The total entropy of a string is the product of the entropy per character times the string length *only* if each character in the final string is equally probable. This is always the case for `puid-js`, and is usually the case for other random string generators. There is, however, a notable exception: the version 4 string representation of a `uuid`. As defined in [RFC 4122, Section 4.4](https://tools.ietf.org/html/rfc4122#section-4.4), a v4 `uuid` uses a total of 32 hex and 4 hyphen characters. Although the hex characters can represent 4 bits of entropy each, 6 bits of the hex representation in a `uuid` are actually fixed, so there is only `32*4 - 6 = 122`-bits of entropy (not 128). The 4 fixed-position hyphen characters contribute zero entropy. So a 36 character `uuid` has an `ere` of `122 / (36*8) = 0.40`, or **40%**. Compare that to, say, the default `puid-js` generator, which has slightly higher entropy (128 bits) and yet yields an `ere` of 0.75, or **75%**. Who doesn't love efficiency?
 
 [TOC](#TOC)
 
@@ -391,28 +392,58 @@ Hmmm. Looks like there are 500,000 IDs expected and the repeat risk is 1 in a tr
 
 [TOC](#TOC)
 
+### <a name="Efficiencies"></a>Efficiencies
+
+`Puid` employs a number of efficiencies for random ID generation:
+
+- Only the number of bytes necessary to generate the next `puid` are fetched from the entropy source
+- Each `puid` character is generated by slicing the minimum number of bits possible
+- Any left-over bits are carried forward and used in generating the next `puid`
+- All characters are equally probable to maximize captured entropy
+- Only characters that represent entropy are present in the final ID 
+- Easily specified `total/risk` ensures ID are only as long as actually necessary
+
+[TOC](#TOC)
+
 ### <a name="tl;dr"></a>tl;dr
 
-`puid-js` is a simple, flexible and efficient random ID generator:
+`Puid` is a simple, fast, flexible and efficient random ID generator:
 
-- **Easy to use**
+- **Ease**
 
-    Random ID generator is one line of code
+    Random ID generator specified in one line of code
 
 - **Flexible**
 
     Full control over entropy source, ID characters and amount of ID randomness
 
+- **Explicit**
+
+    Clear specification of chosen level of randomness
+
 - **Efficient**
 
-    Efficient use of system entropy
+    Maximum use of system entropy
 
 - **Secure**
 
-    Easily specify a secure source of entropy
-    
-- **Clear intent**
+    Defaults to a secure source of entropy
+
+- **Compact**
+
+    ID strings represent maximum entropy for characters used
 
-    Explicit declaration of chosen level of randomness
+- **Secure**
+
+    Defaults to a secure source of entropy and at least 128 bits of ID entropy
+
+
+```js
+  const { Chars, puid } = require('puid-js')
+
+  const { generator: randId } = puid(chars:Chars.SAFE32, total:10e6, risk: 1e15)
+  randId()
+  // => 'tp9TJPNM2rmMLN22prFf'
+```
 
 [TOC](#TOC)

package.json

@@ -1,7 +1,7 @@
 {
   "name": "puid-js",
   "version": "1.0.2",
-  "description": "Simple, fast, flexible and efficient generation of probably unique identifiers (`puid`, aka random strings) of intuitively specified entropy using pre-defined or custom characters.",
+  "description": "Simple, fast, flexible and efficient generation of probably unique identifiers (`puid`, aka random strings) of intuitively specified entropy using pre-defined or custom characters, including unicode",
   "main": "build/main/index.js",
   "typings": "build/main/index.d.ts",
   "module": "build/module/index.js",

src/lib/puid.ts

@@ -46,7 +46,7 @@ const selectEntropyFunction = (puidConfig: PuidConfig): EntropyFunction => {
  *
  * ### Example (es module)
  * ```js
- * import puid from 'puid-js'
+ * import Chars, puid from 'puid-js'
  *
  * const { generator: safe32Id } = puid({ total: 100000, risk: 1e12, chars: Chars.Safe32 })
  * safe32Id()
@@ -55,7 +55,7 @@ const selectEntropyFunction = (puidConfig: PuidConfig): EntropyFunction => {
  *
  * ### Example (commonjs)
  * ```js
- * const puid = require('puid-js')
+ * const { Chars, puid } = require('puid-js')
  *
  * const { generator: alphaNumId } = puid({ total: 100000, risk: 1e12, chars: Chars.AlphaNum })
  * alphaNumId()