Overview #

Features #

• This package gives you Uuid for generating unique UUIDs and converting them into strings and bytes.
• Supports UUID versions 1 (timestamped), 4 (random), 6, and 7. The last two are IETF drafts as of 2022.
• Works in all platforms, including browsers.
• Excellent performance.

Links #

• API documentation
• Github project
  • We appreciate feedback, issue reports, and pull requests.

Getting started #

1.Add dependency #

In pubspec.yaml:

dependencies:
  kind_uuid: ^1.0.0

2.Use package #

import 'package:kind_uuid/kind_uuid.dart';

void main() {
  // We recommend you to use the default constructor so you can make
  // application-wide changes with Uuid.setDefaultFactory(...).
  final uuid = Uuid();
  print('UUID: $uuid');
  print('UUID bytes: ${uuid.toBytes()}');

  // Construct an UUID with version 1.
  final timestamped = Uuid.timestampedV1();
  print('Timestamped UUID timestamp: ${timestamped.dateTime()}');

  // Parse a string
  final parsedUuid = Uuid.parse('f81d4fae-7dec-11d0-a765-00a0c91e6bf6');
  print('UUID from string: $parsedUuid');

  // Read bytes
  final uuidFromBytes = Uuid.fromBytes(
    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
  );
  print('UUID from bytes: $uuidFromBytes');
}

Manual #

Generating UUIDs #

We recommend that you use the Uuid():

final uuid = Uuid();

It can be configured with Uuid.setDefaultFactory(...):

void main() {
  // Set default UUID factory.
  Uuid.setDefaultFactory(Uuid.timestampedV1);
  
  // Construct UUIDs.
  final uuid = Uuid();
  print(uuid);
}

All the supported versions are:

• Uuid.random generates UUIDs with version 4 (RFC 4122).
• Uuid.timestampedV1 generates UUIDs with version 1 (RFC 4122).
• Uuid.timestampedV6 generates UUIDs with version 6 (RFC draft).
• Uuid.timestampedV7 generates UUIDs with version 7 (RFC draft).

Timestamping behavior #

If you don't specify DateTime yourself, it is taken from the zone-local clock (in package:clock). In Dart, DateTime has millisecond precision in browsers and microsecond precision in other platforms. If the system clock moves backward (because of network time synchronization), a small (under 1 second) change is ignored and the previous clock value will be returned until the system clock is greater than it. Thus timestamps tend to retain the real chronological order.

The (usually 14 bit) "clock sequence" field has a random value. If timestamp is equal to the previous timestamp, the previous clock sequence value is incremented by a random amount. Integer overflow is carried to the timestamp integer.

You can write a custom TimestampingState if you want to customize the behavior.

Random number generator #

By default, UUID generation uses UuidRandom, which enables much better performance than Random.secure(). Our benchmarks show that UuidRandom can be approximately 500 times faster.

UuidRandom retains good enough security for UUID generation (but NOT other use cases). Random.secure() is used as entropy source in the beginning and roughly every 100k UUIDs. New blocks are generated with a modified ChaCha20 that does only 8 rounds. The formula for computing the next block of random numbers is chacha20_with_8_rounds(previous_block XOR secret_block).

If you are unhappy with the optimization, you can change the random number generator by calling Uuid.useSystemRandomByDefault(). You can also specify a random number generator when you generate UUIDs:

final uuid = Uuid.timestampedV1(random: yourRandom);