@thi.ng/ksuid - npm Package Compare versions

Comparing version 3.1.17 to 3.2.0

aksuid.d.ts

@@ -14,2 +14,3 @@ import type { BaseN } from "@thi.ng/base-n";
     readonly epoch: number;
+    protected tmp: Uint8Array;
     protected rnd?: IRandom;
@@ -19,7 +20,7 @@ protected pad: (x: any) => string;
     next(): string;
-    nextBinary(): Uint8Array;
+    nextBinary(buf?: Uint8Array): Uint8Array;
     timeOnly(epoch?: number): string;
-    abstract timeOnlyBinary(epoch?: number): Uint8Array;
+    abstract timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     fromEpoch(epoch?: number): string;
-    fromEpochBinary(epoch?: number): Uint8Array;
+    fromEpochBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     format(buf: Uint8Array): string;
@@ -26,0 +27,0 @@ abstract parse(id: string): {

aksuid.js

@@ -18,8 +18,9 @@ import { BASE62 } from "@thi.ng/base-n/62";
         this.pad = padLeft(this.encodedSize, this.base.base[0]);
+        this.tmp = new Uint8Array(this.size);
     }
     next() {
-        return this.format(this.nextBinary());
+        return this.format(this.nextBinary(this.tmp));
     }
-    nextBinary() {
-        const buf = this.timeOnlyBinary();
+    nextBinary(buf) {
+        buf = this.timeOnlyBinary(undefined, buf);
         return this.rnd
@@ -30,9 +31,9 @@ ? randomBytesFrom(this.rnd, buf, this.epochSize)
     timeOnly(epoch) {
-        return this.format(this.timeOnlyBinary(epoch));
+        return this.format(this.timeOnlyBinary(epoch, this.tmp.fill(0, this.epochSize)));
     }
     fromEpoch(epoch) {
-        return this.format(this.fromEpochBinary(epoch));
+        return this.format(this.fromEpochBinary(epoch, this.tmp));
     }
-    fromEpochBinary(epoch) {
-        const buf = this.timeOnlyBinary(epoch);
+    fromEpochBinary(epoch, buf) {
+        buf = this.timeOnlyBinary(epoch, buf);
         return this.rnd
@@ -39,0 +40,0 @@ ? randomBytesFrom(this.rnd, buf, this.epochSize)

api.d.ts

@@ -18,5 +18,8 @@ import type { BaseN } from "@thi.ng/base-n";
     /**
-     * Returns a new ID as byte array.
+     * Returns a new ID as byte array. If `buf` is given, writes result in
+     * there, else creates new byte array.
+     *
+     * @param buf
      */
-    nextBinary(): Uint8Array;
+    nextBinary(buf?: Uint8Array): Uint8Array;
     /**
@@ -31,7 +34,9 @@ * Returns a new baseN encoded ID string for given `epoch` (default: current
      * Binary version of {@link KSUI.timeOnly}, but returns byte array. The
-     * first `epochSize` bytes will contain the timestamp.
+     * first `epochSize` bytes will contain the timestamp. If `buf` is given,
+     * writes result in there, else creates new byte array.
      *
      * @param epoch -
+     * @param buf -
      */
-    timeOnlyBinary(epoch?: number): Uint8Array;
+    timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     /**
@@ -46,7 +51,9 @@ * Returns a new formatted ID, composed from user supplied timestamp
      * Returns a new ID as byte array, composed from user supplied timestamp
-     * (default: current time) and a random payload.
+     * (default: current time) and a random payload. If `buf` is given, writes
+     * result in there, else creates new byte array.
      *
      * @param epoch
+     * @param buf
      */
-    fromEpochBinary(epoch?: number): Uint8Array;
+    fromEpochBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     /**
@@ -53,0 +60,0 @@ * Returns baseN encoded version of given binary ID (generated via

CHANGELOG.md

 # Change Log
 
-- **Last updated**: 2023-08-10T12:25:09Z
+- **Last updated**: 2023-08-12T13:14:08Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
@@ -12,2 +12,18 @@
 
+## [3.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ksuid@3.2.0) (2023-08-12)
+
+#### 🚀 Features
+
+- add optional buffer args for various methods ([def0db4](https://github.com/thi-ng/umbrella/commit/def0db4))
+  - update IKSUID interface
+  - update AKSUID to re-use internal byte buffer for string IDs,
+    avoiding allocating new temp arrays
+  - refactor .timeOnlyBinary() to avoid internal temp array
+  - update tests (re-ordered random bytes, due to [770dbe5d8](https://github.com/thi-ng/umbrella/commit/770dbe5d8))
+
+#### ⏱ Performance improvements
+
+- update .parse() ([da6765d](https://github.com/thi-ng/umbrella/commit/da6765d))
+  - avoid allocation
+
 ### [3.1.15](https://github.com/thi-ng/umbrella/tree/@thi.ng/ksuid@3.1.15) (2023-08-06)
@@ -14,0 +30,0 @@

ksuid32.d.ts

@@ -5,3 +5,3 @@ import { AKSUID } from "./aksuid.js";
     constructor(opts?: Partial<KSUIDOpts>);
-    timeOnlyBinary(epoch?: number): Uint8Array;
+    timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     parse(id: string): {
@@ -8,0 +8,0 @@ epoch: number;

ksuid32.js

@@ -11,10 +11,13 @@ import { AKSUID } from "./aksuid.js";
     }
-    timeOnlyBinary(epoch = Date.now()) {
-        const buf = new Uint8Array(this.size);
+    timeOnlyBinary(epoch = Date.now(), buf) {
+        buf = buf || new Uint8Array(this.size);
         const t = this.ensureTime((epoch - this.epoch) / 1000, MAX_EPOCH) >>> 0;
-        buf.set([t >>> 24, (t >> 16) & 0xff, (t >> 8) & 0xff, t & 0xff]);
+        buf[0] = t >>> 24;
+        buf[1] = (t >> 16) & 0xff;
+        buf[2] = (t >> 8) & 0xff;
+        buf[3] = t & 0xff;
         return buf;
     }
     parse(id) {
-        const buf = new Uint8Array(this.size);
+        const buf = this.tmp;
         this.base.decodeBytes(id, buf);
@@ -21,0 +24,0 @@ return {

ksuid64.d.ts

@@ -5,3 +5,3 @@ import { AKSUID } from "./aksuid.js";
     constructor(opts?: Partial<KSUIDOpts>);
-    timeOnlyBinary(epoch?: number): Uint8Array;
+    timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     parse(id: string): {
@@ -8,0 +8,0 @@ epoch: number;

ksuid64.js

@@ -10,21 +10,19 @@ import { AKSUID } from "./aksuid.js";
     }
-    timeOnlyBinary(epoch = Date.now()) {
-        const buf = new Uint8Array(this.size);
+    timeOnlyBinary(epoch = Date.now(), buf) {
+        buf = buf || new Uint8Array(this.size);
         const t = this.ensureTime(epoch - this.epoch);
         const h = (t / 4294967296) >>> 0;
         const l = (t & 4294967295) >>> 0;
-        buf.set([
-            h >>> 24,
-            (h >> 16) & 0xff,
-            (h >> 8) & 0xff,
-            h & 0xff,
-            l >>> 24,
-            (l >> 16) & 0xff,
-            (l >> 8) & 0xff,
-            l & 0xff,
-        ]);
+        buf[0] = h >>> 24;
+        buf[1] = (h >> 16) & 0xff;
+        buf[2] = (h >> 8) & 0xff;
+        buf[3] = h & 0xff;
+        buf[4] = l >>> 24;
+        buf[5] = (l >> 16) & 0xff;
+        buf[6] = (l >> 8) & 0xff;
+        buf[7] = l & 0xff;
         return buf;
     }
     parse(id) {
-        const buf = new Uint8Array(this.size);
+        const buf = this.tmp;
         this.base.decodeBytes(id, buf);
@@ -31,0 +29,0 @@ return {

package.json

 {
   "name": "@thi.ng/ksuid",
-  "version": "3.1.17",
+  "version": "3.2.0",
   "description": "Configurable K-sortable unique IDs, ULIDs, binary & base-N encoded, 32/48/64bit time resolutions",
@@ -39,10 +39,10 @@ "type": "module",
   "dependencies": {
-    "@thi.ng/base-n": "^2.5.9",
-    "@thi.ng/errors": "^2.3.2",
-    "@thi.ng/random": "^3.5.3",
-    "@thi.ng/strings": "^3.4.10"
+    "@thi.ng/base-n": "^2.5.10",
+    "@thi.ng/errors": "^2.3.3",
+    "@thi.ng/random": "^3.6.0",
+    "@thi.ng/strings": "^3.4.11"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.36.3",
-    "@thi.ng/testament": "^0.3.20",
+    "@microsoft/api-extractor": "^7.36.4",
+    "@thi.ng/testament": "^0.3.21",
     "rimraf": "^5.0.1",
@@ -118,3 +118,3 @@ "tools": "^0.0.1",
   },
-  "gitHead": "ad9ac3232c6fc5fc8a0df75ac82fc1e0e9fb0258\n"
+  "gitHead": "399f8c53d66b9b763d16c21bb59f145df5f59514\n"
 }

README.md

@@ -115,3 +115,3 @@ <!-- This file is generated - DO NOT EDIT! -->
 
-Package sizes (brotli'd, pre-treeshake): ESM: 809 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 888 bytes
 
@@ -173,6 +173,6 @@ ## Dependencies
 
-// no time shift, 64bit random
+// using base36, no time shift, 64bit random part
 const id36 = defKSUID32({ base: BASE36, epoch: 0, bytes: 8 });
 
-id32.next();
+id36.next();
 // '2VOUKH4K59AG0RXR4XH'
@@ -183,27 +183,10 @@ ```
 
-```text
-yarn bench
+Benchmarks can be run via `yarn bench`. All timings in milliseconds (test
+config: Node v20.4.0, MBA M1 2021, 16GB). The benchmark collects N KSUIDs w/
+different configs in an array, with each case being run 100 times.
 
-benchmarking: b62, 128bit, n=10000
-        warmup... 659.22ms (10 runs)
-        executing...
-        total: 6402.18ms, runs: 100
-        mean: 64.02ms, median: 63.50ms, range: [59.98..96.15]
-        q1: 62.64ms, q3: 64.41ms
-        sd: 6.93%
-benchmarking: b62, 64bit, n=10000
-        warmup... 363.35ms (10 runs)
-        executing...
-        total: 3469.28ms, runs: 100
-        mean: 34.69ms, median: 34.41ms, range: [32.61..56.58]
-        q1: 33.35ms, q3: 35.41ms
-        sd: 7.47%
-benchmarking: b62, 32bit, n=10000
-        warmup... 218.78ms (10 runs)
-        executing...
-        total: 2118.93ms, runs: 100
-        mean: 21.19ms, median: 20.95ms, range: [20.20..25.74]
-        q1: 20.71ms, q3: 21.30ms
-        sd: 4.14%
-```
+|                   Title|    Iter|    Size|       Total|    Mean|  Median|     Min|     Max|      Q1|      Q3|     SD%|
+|------------------------|-------:|-------:|-----------:|-------:|-------:|-------:|-------:|-------:|-------:|-------:|
+|    b62, 128bit, n=10000|     100|       1|     2158.68|   21.59|   21.57|   19.91|   25.91|   20.42|   21.87|    6.26|
+|     b62, 64bit, n=10000|     100|       1|     1200.40|   12.00|   11.95|   11.27|   14.66|   11.82|   12.10|    3.99|
 
@@ -210,0 +193,0 @@ ## Authors

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

Improved metrics

Total package byte prevSize

41109

increased by3.16%

Lines of code

395

increased by2.6%

Worsened metrics

Number of lines in readme file

208

decreased by-7.56%

Dependency changes

• [e-mail]/base-n@^2.5.10

• [e-mail]/errors@^2.3.3

• [e-mail]/random@^3.6.0

• [e-mail]/strings@^3.4.11