@thi.ng/ksuid 3.1.15 → 3.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-08-06T09:21:31Z
+- **Last updated**: 2023-08-12T13:14:08Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,22 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [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)
 
 #### 🩹 Bug fixes

package/README.md

@@ -1,6 +1,7 @@
 <!-- This file is generated - DO NOT EDIT! -->
+<!-- Please see: https://github.com/thi-ng/umbrella/blob/develop/CONTRIBUTING.md#changes-to-readme-files -->
 
-# ![@thi.ng/ksuid](https://media.thi.ng/umbrella/banners-20220914/thing-ksuid.svg?2a899961)
+# ![@thi.ng/ksuid](https://media.thi.ng/umbrella/banners-20230807/thing-ksuid.svg?2a899961)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/ksuid.svg)](https://www.npmjs.com/package/@thi.ng/ksuid)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/ksuid.svg)
@@ -87,7 +88,7 @@ implementations already used milliseconds.
 
 ## Related packages
 
-- [@thi.ng/base-n](https://github.com/thi-ng/umbrella/tree/develop/packages/base-n) - Arbitrary base-n conversions w/ presets for base16/32/36/58/62/64/85, support for arrays & bigints
+- [@thi.ng/base-n](https://github.com/thi-ng/umbrella/tree/develop/packages/base-n) - Arbitrary base-n conversions w/ presets for base8/16/32/36/58/62/64/85, support for bigints and encoding/decoding of byte arrays
 - [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen) - Generator of opaque numeric identifiers with optional support for ID versioning and efficient re-use
 - [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random) - Pseudo-random number generators w/ unified API, distributions, weighted choices, ID generation
 
@@ -111,7 +112,7 @@ For Node.js REPL:
 const ksuid = await import("@thi.ng/ksuid");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 809 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 888 bytes
 
 ## Dependencies
 
@@ -168,40 +169,23 @@ Creating custom IDs:
 ```ts
 import { BASE36 } from "@thi.ng/base-n";
 
-// 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'
 ```
 
 ## Benchmarks
 
-```text
-yarn bench
-
-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%
-```
+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.
+
+|                   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|
 
 ## Authors
 

package/aksuid.d.ts

@@ -11,15 +11,16 @@ export declare abstract class AKSUID implements IKSUID {
     readonly encodedSize: number;
     readonly base: BaseN;
     readonly epoch: number;
+    protected tmp: Uint8Array;
     protected rnd?: IRandom;
     protected pad: (x: any) => string;
     protected constructor(epochSize: number, opts: Partial<KSUIDOpts>);
     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;
     abstract parse(id: string): {
         epoch: number;

package/aksuid.js

@@ -15,24 +15,25 @@ export class AKSUID {
         this.size = this.epochSize + opts.bytes;
         this.encodedSize = this.base.size(2 ** (this.size * 8) - 1);
         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
             ? randomBytesFrom(this.rnd, buf, this.epochSize)
             : randomBytes(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
             ? randomBytesFrom(this.rnd, buf, this.epochSize)
             : randomBytes(buf, this.epochSize);

package/api.d.ts

@@ -15,9 +15,12 @@ export interface IKSUID {
      */
     next(): string;
     /**
-     * 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;
     /**
      * Returns a new baseN encoded ID string for given `epoch` (default: current
      * time) and with all random payload bytes set to 0.
@@ -27,11 +30,13 @@ export interface IKSUID {
     timeOnly(epoch?: number): string;
     /**
      * 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;
     /**
      * Returns a new formatted ID, composed from user supplied timestamp
      * (default: current time) and a random payload.
@@ -41,11 +46,13 @@ export interface IKSUID {
     fromEpoch(epoch?: number): string;
     /**
      * 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;
     /**
      * Returns baseN encoded version of given binary ID (generated via
      * `.nextBinary()`).

package/ksuid32.d.ts

@@ -2,7 +2,7 @@ import { AKSUID } from "./aksuid.js";
 import type { KSUIDOpts } from "./api.js";
 export declare class KSUID32 extends AKSUID {
     constructor(opts?: Partial<KSUIDOpts>);
-    timeOnlyBinary(epoch?: number): Uint8Array;
+    timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     parse(id: string): {
         epoch: number;
         id: Uint8Array;

package/ksuid32.js

@@ -8,14 +8,17 @@ export class KSUID32 extends AKSUID {
             ...opts,
         });
     }
-    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);
         return {
             epoch: this.u32(buf) * 1000 + this.epoch,

package/ksuid64.d.ts

@@ -2,7 +2,7 @@ import { AKSUID } from "./aksuid.js";
 import type { KSUIDOpts } from "./api.js";
 export declare class KSUID64 extends AKSUID {
     constructor(opts?: Partial<KSUIDOpts>);
-    timeOnlyBinary(epoch?: number): Uint8Array;
+    timeOnlyBinary(epoch?: number, buf?: Uint8Array): Uint8Array;
     parse(id: string): {
         epoch: number;
         id: Uint8Array;

package/ksuid64.js

@@ -7,25 +7,23 @@ export class KSUID64 extends AKSUID {
             ...opts,
         });
     }
-    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);
         return {
             epoch: this.u32(buf) * 4294967296 + this.u32(buf, 4) + this.epoch,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/ksuid",
-  "version": "3.1.15",
+  "version": "3.2.0",
   "description": "Configurable K-sortable unique IDs, ULIDs, binary & base-N encoded, 32/48/64bit time resolutions",
   "type": "module",
   "module": "./index.js",
@@ -36,14 +36,14 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/base-n": "^2.5.7",
-    "@thi.ng/errors": "^2.3.0",
-    "@thi.ng/random": "^3.5.1",
-    "@thi.ng/strings": "^3.4.8"
+    "@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.18",
+    "@microsoft/api-extractor": "^7.36.4",
+    "@thi.ng/testament": "^0.3.21",
     "rimraf": "^5.0.1",
     "tools": "^0.0.1",
     "typedoc": "^0.24.8",
@@ -114,5 +114,5 @@
     "status": "stable",
     "year": 2020
   },
-  "gitHead": "888293c74f2e9a481d500d4ec319f1e2bd765ec6\n"
+  "gitHead": "399f8c53d66b9b763d16c21bb59f145df5f59514\n"
 }