feat(algo): added bulkGenerate method for Snowflake algorithms

Author: fenying

CHANGES.md

@@ -1,5 +1,9 @@
 # Changes Logs
 
+## v2.1.0
+
+- feat(algo): added `bulkGenerate` for both Snowflake and Snowflake-SI algorithms.
+
 ## v2.0.3
 
 - fix(algo): reverted the update of `v2.0.2` that removed the reset of sequence number to 0.

docs/en-US/api/Snowflake/classes/SnowflakeGenerator.md

@@ -2,7 +2,7 @@
 
 # Class: SnowflakeGenerator
 
-Defined in: [Snowflake.ts:134](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L134)
+Defined in: [Snowflake.ts:162](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L162)
 
 The class for generating Snowflake IDs.
 
@@ -12,7 +12,7 @@ The class for generating Snowflake IDs.
 
 > **new SnowflakeGenerator**(`opts`): `SnowflakeGenerator`
 
-Defined in: [Snowflake.ts:186](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L186)
+Defined in: [Snowflake.ts:214](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L214)
 
 #### Parameters
 
@@ -30,7 +30,7 @@ Defined in: [Snowflake.ts:186](https://github.com/litert/uuid.js/blob/master/src
 
 > `readonly` **epoch**: `number`
 
-Defined in: [Snowflake.ts:176](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L176)
+Defined in: [Snowflake.ts:204](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L204)
 
 The epoch of the generator.
 
@@ -48,7 +48,7 @@ The value is recommended to be the time when the service/application goes online
 
 > `readonly` **machineId**: `number`
 
-Defined in: [Snowflake.ts:167](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L167)
+Defined in: [Snowflake.ts:195](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L195)
 
 The identifier of the machine that generates the UUID.
 
@@ -65,7 +65,7 @@ so that the generated IDs will not conflict with each other.
 
 > `readonly` `static` **MAX\_MACHINE\_ID**: `1023` = `1023`
 
-Defined in: [Snowflake.ts:157](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L157)
+Defined in: [Snowflake.ts:185](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L185)
 
 The maximum machine ID that can be used by the generator.
 
@@ -75,17 +75,50 @@ The maximum machine ID that can be used by the generator.
 
 > `readonly` `static` **MIN\_MACHINE\_ID**: `0` = `0`
 
-Defined in: [Snowflake.ts:151](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L151)
+Defined in: [Snowflake.ts:179](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L179)
 
 The minimum machine ID that can be used by the generator.
 
 ## Methods
 
+### bulkGenerate()
+
+> **bulkGenerate**(`qty`, `opts`): `Promise`\<`bigint`[]\>
+
+Defined in: [Snowflake.ts:286](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L286)
+
+Generate a bulk of Snowflake IDs.
+
+This method helps generate batch of Snowflake IDs, handling the time
+reversed and sequence overflow scenarios automatically.
+
+#### Parameters
+
+##### qty
+
+`number`
+
+The quantity of IDs to generate.
+
+##### opts
+
+[`IBulkGenerationOptions`](../interfaces/IBulkGenerationOptions.md) = `DEFAULT_BULK_OPTIONS`
+
+The options for bulk generation.
+
+#### Returns
+
+`Promise`\<`bigint`[]\>
+
+A promise that resolves to an array of Snowflake IDs.
+
+***
+
 ### generate()
 
 > **generate**(): `bigint`
 
-Defined in: [Snowflake.ts:256](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L256)
+Defined in: [Snowflake.ts:334](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L334)
 
 Generate the next Snowflake ID, based on the current time and the next sequence number.
 
@@ -113,7 +146,7 @@ If the current time is before the epoch.
 
 > **generateBy**(`timestamp`, `sequence`): `bigint`
 
-Defined in: [Snowflake.ts:323](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L323)
+Defined in: [Snowflake.ts:401](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L401)
 
 Generate a Snowflake ID by specifying the timestamp and sequence number.
 

docs/en-US/api/Snowflake/enumerations/ESnowflakeSequenceStrategy.md

@@ -2,7 +2,7 @@
 
 # Enumeration: ESnowflakeSequenceStrategy
 
-Defined in: [Snowflake.ts:55](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L55)
+Defined in: [Snowflake.ts:83](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L83)
 
 How should the generator handle the sequence number when the time changes.
 
@@ -12,7 +12,7 @@ How should the generator handle the sequence number when the time changes.
 
 > **KEEP\_CURRENT**: `1`
 
-Defined in: [Snowflake.ts:72](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L72)
+Defined in: [Snowflake.ts:100](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L100)
 
 Keep the sequence number unchanged when the time changes.
 
@@ -26,7 +26,7 @@ Keep the sequence number unchanged when the time changes.
 
 > **RESET**: `0`
 
-Defined in: [Snowflake.ts:63](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L63)
+Defined in: [Snowflake.ts:91](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L91)
 
 Reset the sequence number to 0 when the time changes.
 

docs/en-US/api/Snowflake/enumerations/ESnowflakeTimeReversedStrategy.md

@@ -2,7 +2,7 @@
 
 # Enumeration: ESnowflakeTimeReversedStrategy
 
-Defined in: [Snowflake.ts:21](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L21)
+Defined in: [Snowflake.ts:49](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L49)
 
 The strategy for handling time reversal events in Snowflake ID generation.
 
@@ -12,7 +12,7 @@ The strategy for handling time reversal events in Snowflake ID generation.
 
 > **THROW\_ERROR**: `0`
 
-Defined in: [Snowflake.ts:30](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L30)
+Defined in: [Snowflake.ts:58](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L58)
 
 Throw an error to stop the generator from generating IDs.
 
@@ -26,7 +26,7 @@ Throw an error to stop the generator from generating IDs.
 
 > **USE\_PREVIOUS\_TIME**: `2`
 
-Defined in: [Snowflake.ts:49](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L49)
+Defined in: [Snowflake.ts:77](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L77)
 
 Use the previous time as the current time to generate IDs.
 
@@ -41,7 +41,7 @@ Use the previous time as the current time to generate IDs.
 
 > **USE\_REVERSED\_TIME**: `1`
 
-Defined in: [Snowflake.ts:39](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L39)
+Defined in: [Snowflake.ts:67](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L67)
 
 Use the reversed time as the current time to generate IDs.
 

docs/en-US/api/Snowflake/index.md

@@ -13,6 +13,7 @@
 
 ## Interfaces
 
+- [IBulkGenerationOptions](interfaces/IBulkGenerationOptions.md)
 - [ISnowflakeOptions](interfaces/ISnowflakeOptions.md)
 
 ## Type Aliases

docs/en-US/api/Snowflake/interfaces/IBulkGenerationOptions.md

@@ -0,0 +1,41 @@
+[Documents for @litert/uuid](../../index.md) / [Snowflake](../index.md) / IBulkGenerationOptions
+
+# Interface: IBulkGenerationOptions
+
+Defined in: [Snowflake.ts:22](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L22)
+
+The options for bulk generation of snowflake IDs.
+
+## Properties
+
+### maxRetries?
+
+> `optional` **maxRetries**: `number`
+
+Defined in: [Snowflake.ts:31](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L31)
+
+The maximum number of sequential retries for generating IDs in bulk.
+
+If the failures exceeded this limit, the original error will be thrown.
+
+#### Default
+
+```ts
+3
+```
+
+***
+
+### retryDelayMs?
+
+> `optional` **retryDelayMs**: `number`
+
+Defined in: [Snowflake.ts:38](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L38)
+
+The delay between each retry attempt in milliseconds.
+
+#### Default
+
+```ts
+1
+```

docs/en-US/api/Snowflake/interfaces/ISnowflakeOptions.md

@@ -2,7 +2,7 @@
 
 # Interface: ISnowflakeOptions
 
-Defined in: [Snowflake.ts:83](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L83)
+Defined in: [Snowflake.ts:111](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L111)
 
 The options for the standard Snowflake ID generator.
 
@@ -16,7 +16,7 @@ The options for the standard Snowflake ID generator.
 
 > `readonly` `optional` **epoch**: `number`
 
-Defined in: [Snowflake.ts:176](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L176)
+Defined in: [Snowflake.ts:204](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L204)
 
 The epoch of the generator.
 
@@ -38,7 +38,7 @@ The value is recommended to be the time when the service/application goes online
 
 > `readonly` **machineId**: `number`
 
-Defined in: [Snowflake.ts:167](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L167)
+Defined in: [Snowflake.ts:195](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L195)
 
 The identifier of the machine that generates the UUID.
 
@@ -59,7 +59,7 @@ so that the generated IDs will not conflict with each other.
 
 > `optional` **onTimeChanged**: [`ESnowflakeSequenceStrategy`](../enumerations/ESnowflakeSequenceStrategy.md) \| [`ISnowflakeUpdateSequenceOnTimeChanged`](../type-aliases/ISnowflakeUpdateSequenceOnTimeChanged.md)\<`bigint`\>
 
-Defined in: [Snowflake.ts:101](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L101)
+Defined in: [Snowflake.ts:129](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L129)
 
 The strategy for handling the sequence number when the time changes.
 
@@ -78,7 +78,7 @@ ESnowflakeSequenceStrategy.RESET
 
 > `optional` **onTimeReversed**: [`ESnowflakeTimeReversedStrategy`](../enumerations/ESnowflakeTimeReversedStrategy.md)
 
-Defined in: [Snowflake.ts:91](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L91)
+Defined in: [Snowflake.ts:119](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L119)
 
 The strategy for handling time reversal events.
 
@@ -94,7 +94,7 @@ ESnowflakeTimeReversedStrategy.THROW_ERROR
 
 > `optional` **sequenceResetThreshold**: `number`
 
-Defined in: [Snowflake.ts:111](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L111)
+Defined in: [Snowflake.ts:139](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L139)
 
 When the sequence strategy is set to `ESnowflakeSequenceStrategy.RESET`,
 this option specifies the threshold for resetting the sequence number.

docs/en-US/api/Snowflake/type-aliases/ISnowflakeUpdateSequenceOnTimeChanged.md

@@ -4,7 +4,7 @@
 
 > **ISnowflakeUpdateSequenceOnTimeChanged**\<`T`\> = (`current`) => `T`
 
-Defined in: [Snowflake.ts:78](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L78)
+Defined in: [Snowflake.ts:106](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L106)
 
 The strategy for handling time changes in Snowflake ID generation.
 

docs/en-US/api/Snowflake/variables/SNOWFLAKE_DEFAULT_TIME_CHANGED_STRATEGY.md

@@ -4,7 +4,7 @@
 
 > `const` **SNOWFLAKE\_DEFAULT\_TIME\_CHANGED\_STRATEGY**: [`RESET`](../enumerations/ESnowflakeSequenceStrategy.md#reset) = `ESnowflakeSequenceStrategy.RESET`
 
-Defined in: [Snowflake.ts:124](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L124)
+Defined in: [Snowflake.ts:152](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L152)
 
 The default strategy for the time changed event,
 which reset the sequence number to 0.

docs/en-US/api/Snowflake/variables/SNOWFLAKE_DEFAULT_TIME_REVERSAL_STRATEGY.md

@@ -4,7 +4,7 @@
 
 > `const` **SNOWFLAKE\_DEFAULT\_TIME\_REVERSAL\_STRATEGY**: [`THROW_ERROR`](../enumerations/ESnowflakeTimeReversedStrategy.md#throw_error) = `ESnowflakeTimeReversedStrategy.THROW_ERROR`
 
-Defined in: [Snowflake.ts:118](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L118)
+Defined in: [Snowflake.ts:146](https://github.com/litert/uuid.js/blob/master/src/lib/Snowflake.ts#L146)
 
 The default strategy for the time reversal event,
 which throws an `E_TIME_REVERSED` error.