scru64 - npm Package Compare versions

Comparing version 0.3.3 to 0.3.4

dist/index.d.ts

@@ -100,3 +100,3 @@ /**
  *
- * The generator offers six different methods to generate a SCRU64 ID:
+ * The generator comes with several different methods that generate a SCRU64 ID:
  *
@@ -112,10 +112,18 @@ * | Flavor                      | Timestamp | On big clock rewind |
  *
- * All of these methods return monotonically increasing IDs unless a timestamp
- * provided is significantly (by default, approx. 10 seconds) smaller than the
- * one embedded in the immediately preceding ID. If such a significant clock
- * rollback is detected, (1) the `generate` (OrAbort) method aborts and returns
- * `undefined`; (2) the `OrReset` variants reset the generator and return a new
- * ID based on the given timestamp; and, (3) the `OrSleep` and `OrAwait` methods
- * sleep and wait for the next timestamp tick. The `Core` functions offer
- * low-level primitives.
+ * All of these methods return a monotonically increasing ID by reusing the
+ * previous `timestamp` even if the one provided is smaller than the immediately
+ * preceding ID's, unless such a clock rollback is considered significant (by
+ * default, approx. 10 seconds). A clock rollback may also be detected when a
+ * generator has generated too many IDs within a certain unit of time, because
+ * this implementation increments the previous `timestamp` when `counter`
+ * reaches the limit to continue instant monotonic generation. When a
+ * significant clock rollback is detected:
+ *
+ * 1. `generate` (OrAbort) methods abort and return `undefined` immediately.
+ * 2. `OrReset` variants reset the generator and return a new ID based on the
+ *    given `timestamp`, breaking the increasing order of IDs.
+ * 3. `OrSleep` and `OrAwait` methods sleep and wait for the next timestamp
+ *    tick.
+ *
+ * The `Core` functions offer low-level primitives to customize the behavior.
  */
@@ -213,8 +221,9 @@ export declare class Scru64Generator {
  * A `NodeSpec` is usually expressed as a node spec string, which starts with a
- * decimal `nodeId`, a hexadecimal `nodeId` prefixed with `"0x"`, or a 12-digit
+ * decimal `nodeId`, a hexadecimal `nodeId` prefixed by "0x", or a 12-digit
  * `nodePrev` SCRU64 ID value, followed by a slash and a decimal `nodeIdSize`
- * value ranging from 1 to 23 (e.g., `"42/8"`, `"0xb00/12"`, `"0u2r85hm2pt3/16"`).
- * The first and second forms create a fresh new generator with the given
- * `nodeId`, while the third form constructs one that generates subsequent
- * SCRU64 IDs to the `nodePrev`.
+ * value ranging from 1 to 23 (e.g., "42/8", "0xb00/12", "0u2r85hm2pt3/16"). The
+ * first and second forms create a fresh new generator with the given `nodeId`,
+ * while the third form constructs one that generates subsequent SCRU64 IDs to
+ * the `nodePrev`. See also {@link https://github.com/scru64/spec#informative-usage-notes | the usage notes}
+ * in the SCRU64 spec for tips and techniques to design node configurations.
  */
@@ -272,7 +281,10 @@ export type NodeSpec = string | {
  *
- * The global generator reads the node configuration from the `SCRU64_NODE_SPEC`
- * global variable by default, and it throws an error if it fails to read a
- * well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  */
@@ -314,7 +326,10 @@ export declare class GlobalGenerator {
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -332,7 +347,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -349,7 +367,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -366,7 +387,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -373,0 +397,0 @@ * This function usually returns a value immediately, but if not possible, it

dist/index.js

@@ -254,3 +254,3 @@ /**
  *
- * The generator offers six different methods to generate a SCRU64 ID:
+ * The generator comes with several different methods that generate a SCRU64 ID:
  *
@@ -266,10 +266,18 @@ * | Flavor                      | Timestamp | On big clock rewind |
  *
- * All of these methods return monotonically increasing IDs unless a timestamp
- * provided is significantly (by default, approx. 10 seconds) smaller than the
- * one embedded in the immediately preceding ID. If such a significant clock
- * rollback is detected, (1) the `generate` (OrAbort) method aborts and returns
- * `undefined`; (2) the `OrReset` variants reset the generator and return a new
- * ID based on the given timestamp; and, (3) the `OrSleep` and `OrAwait` methods
- * sleep and wait for the next timestamp tick. The `Core` functions offer
- * low-level primitives.
+ * All of these methods return a monotonically increasing ID by reusing the
+ * previous `timestamp` even if the one provided is smaller than the immediately
+ * preceding ID's, unless such a clock rollback is considered significant (by
+ * default, approx. 10 seconds). A clock rollback may also be detected when a
+ * generator has generated too many IDs within a certain unit of time, because
+ * this implementation increments the previous `timestamp` when `counter`
+ * reaches the limit to continue instant monotonic generation. When a
+ * significant clock rollback is detected:
+ *
+ * 1. `generate` (OrAbort) methods abort and return `undefined` immediately.
+ * 2. `OrReset` variants reset the generator and return a new ID based on the
+ *    given `timestamp`, breaking the increasing order of IDs.
+ * 3. `OrSleep` and `OrAwait` methods sleep and wait for the next timestamp
+ *    tick.
+ *
+ * The `Core` functions offer low-level primitives to customize the behavior.
  */
@@ -540,7 +548,10 @@ export class Scru64Generator {
  *
- * The global generator reads the node configuration from the `SCRU64_NODE_SPEC`
- * global variable by default, and it throws an error if it fails to read a
- * well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  */
@@ -604,7 +615,10 @@ export class GlobalGenerator {
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -622,7 +636,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -639,7 +656,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -656,7 +676,10 @@ * This function usually returns a value immediately, but if not possible, it
  *
- * The {@link GlobalGenerator} reads the node configuration from the
- * `SCRU64_NODE_SPEC` global variable by default, and it throws an error if it
- * fails to read a well-formed node spec string (e.g., `"42/8"`, `"0xb00/12"`,
- * `"0u2r85hm2pt3/16"`) when a generator method is first called. See also
- * {@link NodeSpec} for the node spec string format.
+ * By default, the global generator reads the node configuration from the
+ * `SCRU64_NODE_SPEC` global variable when a generator method is first called,
+ * and it throws an error if it fails to do so. The node configuration is
+ * encoded in a node spec string consisting of `nodeId` and `nodeIdSize`
+ * integers separated by a slash (e.g., "42/8", "0xb00/12"; see {@link NodeSpec}
+ * for details). You can configure the global generator differently by calling
+ * {@link GlobalGenerator.initialize} before the default initializer is
+ * triggered.
  *
@@ -663,0 +686,0 @@ * This function usually returns a value immediately, but if not possible, it

package.json

 {
   "name": "scru64",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "SCRU64: Sortable, Clock-based, Realm-specifically Unique identifier",
@@ -9,3 +9,5 @@ "type": "module",
   "exports": "./dist/index.js",
-  "bin": "./cli.js",
+  "bin": {
+    "scru64": "cli.js"
+  },
   "files": [
@@ -35,5 +37,5 @@ "dist"
     "mocha": "^10.2.0",
-    "typedoc": "^0.25.0",
+    "typedoc": "^0.25.1",
     "typescript": "^5.2.2"
   }
 }

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

60677

increased by5.05%

Lines of code

1137

increased by4.31%

No dependency changes