@thi.ng/ksuid 2.1.30 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2023-01-17T10:57:27Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,29 @@ 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.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ksuid@3.0.0) (2023-01-17)
+
+#### 🛑 Breaking changes
+
+- update readme w/ v3.0.0 info ([f8d83c8](https://github.com/thi-ng/umbrella/commit/f8d83c8))
+- BREAKING CHANGE: `epoch` config unified to use milliseconds
+  - add new section to readme
+  - see [3d73b1766](https://github.com/thi-ng/umbrella/commit/3d73b1766) for code details
+
+#### 🚀 Features
+
+- fix [#372](https://github.com/thi-ng/umbrella/issues/372), add fromEpoch() methods ([e416e91](https://github.com/thi-ng/umbrella/commit/e416e91))
+  - add fromEpoch/fromEpochBinary() to IKSUID interface
+  - add impls in AKSUID
+  - add tests for all 3 classes
+
+#### ♻️ Refactoring
+
+- use milliseconds as unified epoch offsets ([3d73b17](https://github.com/thi-ng/umbrella/commit/3d73b17))
+  - clarify KSUIDOpts.epoch docs
+  - refactor KSUID32 to use milliseconds as `epoch` offset
+  - update tests
+
 ## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/ksuid@2.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -11,6 +11,7 @@ This project is part of the
 
 - [About](#about)
 - [Status](#status)
+  - [Breaking changes](#breaking-changes)
 - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -58,6 +59,16 @@ support
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bksuid%5D+in%3Atitle)
 
+### Breaking changes
+
+Since v3.0.0 all
+[`epoch`](https://docs.thi.ng/umbrella/ksuid/interfaces/KSUIDOpts.html#epoch)
+time-shift config values are to be given in milliseconds. This change is
+unifying this behavior and is only a breaking change if using `KSUID32` and
+specifying custom `epoch` offsets (using defaults is **not** impacted).
+Previously, `KSUID32` used an offset given in seconds, whereas the other
+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
@@ -84,7 +95,7 @@ For Node.js REPL:
 const ksuid = await import("@thi.ng/ksuid");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 754 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 769 bytes
 
 ## Dependencies
 
@@ -143,6 +154,8 @@ import { BASE36 } from "@thi.ng/base-n";
 
 // no time shift, 64bit random
 const id36 = defKSUID32({ base: BASE36, epoch: 0, bytes: 8 });
+
+id32.next();
 // '2VOUKH4K59AG0RXR4XH'
 ```
 
@@ -191,4 +204,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2020 - 2022 Karsten Schmidt // Apache License 2.0
+© 2020 - 2023 Karsten Schmidt // Apache License 2.0

package/aksuid.d.ts

@@ -18,6 +18,8 @@ export declare abstract class AKSUID implements IKSUID {
     nextBinary(): Uint8Array;
     timeOnly(epoch?: number): string;
     abstract timeOnlyBinary(epoch?: number): Uint8Array;
+    fromEpoch(epoch?: number): string;
+    fromEpochBinary(epoch?: number): Uint8Array;
     format(buf: Uint8Array): string;
     abstract parse(id: string): {
         epoch: number;

package/aksuid.js

@@ -28,6 +28,15 @@ export class AKSUID {
     timeOnly(epoch) {
         return this.format(this.timeOnlyBinary(epoch));
     }
+    fromEpoch(epoch) {
+        return this.format(this.fromEpochBinary(epoch));
+    }
+    fromEpochBinary(epoch) {
+        const buf = this.timeOnlyBinary(epoch);
+        return this.rnd
+            ? randomBytesFrom(this.rnd, buf, this.epochSize)
+            : randomBytes(buf, this.epochSize);
+    }
     format(buf) {
         this.ensureSize(buf);
         return this.pad(this.base.encodeBytes(buf));

package/api.d.ts

@@ -32,6 +32,20 @@ export interface IKSUID {
      * @param epoch -
      */
     timeOnlyBinary(epoch?: number): Uint8Array;
+    /**
+     * Returns a new formatted ID, composed from user supplied timestamp
+     * (default: current time) and a random payload.
+     *
+     * @param epoch
+     */
+    fromEpoch(epoch?: number): string;
+    /**
+     * Returns a new ID as byte array, composed from user supplied timestamp
+     * (default: current time) and a random payload.
+     *
+     * @param epoch
+     */
+    fromEpochBinary(epoch?: number): Uint8Array;
     /**
      * Returns baseN encoded version of given binary ID (generated via
      * `.nextBinary()`).
@@ -76,15 +90,15 @@ export interface KSUIDOpts {
      */
     bytes: number;
     /**
-     * Time offset in seconds, relative to standard Unix epoch. This is used to
-     * extend the time headroom of IDs into the future.
+     * Time offset in milliseconds, relative to standard Unix epoch. This is
+     * used to extend the time headroom of IDs into the future.
      *
      * @remarks
      * The default value (for both 32 & 64bit impls) is approx. 2020-09-13,
-     * meaning this is the T0 epoch for all IDs (providing an additional ~50
-     * year lifespan compared to the standard 1970-01-01 epoch)
+     * meaning this is the `t0` base epoch for all generated IDs (providing an
+     * additional ~50 year lifespan compared to the standard 1970-01-01 epoch)
      *
-     * @defaultValue 1_600_000_000 or 1_600_000_000_000
+     * @defaultValue 1_600_000_000_000
      */
     epoch: number;
 }

package/ksuid32.js

@@ -2,14 +2,14 @@ import { AKSUID } from "./aksuid.js";
 export class KSUID32 extends AKSUID {
     constructor(opts) {
         super(4, {
-            epoch: 1600000000,
+            epoch: 1600000000000,
             bytes: 16,
             ...opts,
         });
     }
     timeOnlyBinary(epoch = Date.now()) {
         const buf = new Uint8Array(this.size);
-        const t = this.ensureTime((epoch / 1000 - this.epoch) | 0);
+        const t = this.ensureTime(((epoch - this.epoch) / 1000) | 0);
         buf.set([t >>> 24, (t >> 16) & 0xff, (t >> 8) & 0xff, t & 0xff]);
         return buf;
     }
@@ -17,7 +17,7 @@ export class KSUID32 extends AKSUID {
         const buf = new Uint8Array(this.size);
         this.base.decodeBytes(id, buf);
         return {
-            epoch: (this.u32(buf) + this.epoch) * 1000,
+            epoch: this.u32(buf) * 1000 + this.epoch,
             id: buf.slice(4),
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/ksuid",
-  "version": "2.1.30",
+  "version": "3.0.0",
   "description": "Configurable K-sortable unique IDs, ULIDs, binary & base-N encoded, 32/48/64bit time resolutions",
   "type": "module",
   "module": "./index.js",
@@ -35,14 +35,14 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/base-n": "^2.3.11",
-    "@thi.ng/errors": "^2.2.7",
-    "@thi.ng/random": "^3.3.20",
-    "@thi.ng/strings": "^3.3.22"
+    "@thi.ng/base-n": "^2.3.12",
+    "@thi.ng/errors": "^2.2.8",
+    "@thi.ng/random": "^3.3.21",
+    "@thi.ng/strings": "^3.3.23"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.8",
+    "@thi.ng/testament": "^0.3.9",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.22",
@@ -109,5 +109,5 @@
     "status": "stable",
     "year": 2020
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "02425e5d92d381af664430d56609ee82948b4f59\n"
 }