uuid 0.5.3

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 87

0.5.0 WARNING: MathRNG is now the default RNG method when using v4 of v5. If you wish to use CryptoRNG, import uuid_util.dart and use UuidUtil.cryptoRNG() with the RNG option

Build Status

dart-uuid

Join the chat at https://gitter.im/Daegalus/dart-uuid

Simple, fast generation of RFC4122 UUIDs.

Heavily based on node-uuid by Robert Kieffer (I even copied this readme over and modified it.) Primarily becaue it works, well written, and so on.

Features:

  • Generate RFC4122 version 1, version 4, or version 5 UUIDs
  • Runs in dartvm and browsers.
  • Cryptographically strong random number generation on all platforms
  • Annotated source code

Getting Started

Instructions

  1. Open a command line and cd to your projects root folder
  2. In your pubspec, add an entry for dart-uuid to your dependencies (example below)
  3. pub install
  4. If you wish to run tests, go into packages/dart-uuid/ and run 'dart test/uuid_test.dart'

Pubspec

There are 2 options. Directly from git, or from pub.dartlang.org

pub.dartlang.org: (you can use 'any' instead of a version if you just want the latest always)

dependencies:
  uuid: 0.5.0
import 'package:uuid/uuid.dart';

var uuid = new Uuid();

Then create some ids ...

// Generate a v1 (time-based) id
uuid.v1(); // -> '6c84fb90-12c4-11e1-840d-7b25c5ee775a'

// Generate a v4 (random) id
uuid.v4(); // -> '110ec58a-a0f2-4ac4-8393-c866d813b8d1'

// Generate a v5 (namespace-name-sha1-based) id
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com'); // -> 'c74a196f-f19d-5ea9-bffd-a2742432fc9c'

API

uuid.v1({Map options: null, List buffer: null, int offset: 0})

Generate and return a RFC4122 v1 (timestamp-based) UUID.

  • options - (Map) Optional uuid state to apply. Properties may include:

    • node - (List) Node id as List of 6 bytes (per 4.1.6). Default: Randomnly generated ID.
    • clockseq - (Number between 0 - 0x3fff) RFC clock sequence. Default: An internally maintained clockseq is used.
    • msecs - (Number) Time in milliseconds since unix Epoch. Default: The current time is used.
    • nsecs - (Number between 0-9999) additional time, in 100-nanosecond units. Ignored if msecs is unspecified. Default: internal uuid counter is used, as per 4.2.1.2.
  • buffer - (List) Array or buffer where UUID bytes are to be written.

  • offset - (Int) Starting index in buffer at which to begin writing.

Returns buffer, if specified, otherwise the string form of the UUID

Example: Generate string UUID with fully-specified options

uuid.v1(options: {
    'node': [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
    'clockSeq': 0x1234,
    'mSecs': new Date(2011,11,01).millisecondsSinceEpoch,
    'nSecs': 5678
})   // -> "1d6a6e2e-0457-11e1-9234-0123456789ab"

Example: In-place generation of two binary IDs

// Generate two ids in an array
var myBuffer = new List(32); // -> []
uuid.v1(buffer: myBuffer);   
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null, null]
uuid.v1(buffer: myBuffer, offset: 16);  
// -> [115, 189, 5, 128, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128, 115, 189, 5, 129, 201, 91, 17, 225, 146, 52, 109, 0, 9, 0, 52, 128]

// Optionally use uuid.unparse() to get stringify the ids
uuid.unparse(buffer: myBuffer);    // -> '73bd0580-c95b-11e1-9234-6d0009003480'
uuid.unparse(buffer: myBuffer, offset: 16) // -> '73bd0581-c95b-11e1-9234-6d0009003480'

uuid.v4({Map options: null, List buffer: null, int offset: 0})

Generate and return a RFC4122 v4 UUID.

  • options - (Map) Optional uuid state to apply. Properties may include:

    • random - (Number[16]) List of 16 numbers (0-255) to use in place of randomly generated values
    • rng - (Function) Random # generator to use. A Custom function that returns an list[16] of byte values or 1 of 2 provided.
    • namedArgs - (Map<Symbol, dynamic>) The arguments and values you want to pass to your function.
    • positionalArgs - (List) The positional arguments for your functions. if any.
  • buffer - (List) Array or buffer where UUID bytes are to be written.

  • offset - (Number) Starting index in buffer at which to begin writing.

Returns buffer, if specified, otherwise the string form of the UUID

Example: Generate string UUID with different RNG method

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.cryptoRNG
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"

Example: Generate string UUID with different RNG method and named parameters

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.mathRNG,
  'namedArgs': new Map.fromIterables([const Symbol('seed')],[1])
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"

Example: Generate string UUID with different RNG method and positional parameters

import 'package:uuid/uuid_util.dart';
uuid.v4(options: {
  'rng': UuidUtil.mathRNG,
  'positionalArgs': [1]
});
// -> "09a91894-e93f-4141-a3ec-82eb32f2a3ef"

Example: Generate string UUID with fully-specified options

uuid.v4(options: {
  'random': [
    0x10, 0x91, 0x56, 0xbe, 0xc4, 0xfb, 0xc1, 0xea,
    0x71, 0xb4, 0xef, 0xe1, 0x67, 0x1c, 0x58, 0x36
  ]
});
// -> "109156be-c4fb-41ea-b1b4-efe1671c5836"

Example: Generate two IDs in a single buffer

var myBuffer = new List(32);
uuid.v4(buffer: myBuffer);
uuid.v4(buffer: myBuffer, offset: 16);

uuid.v5(String namespace, String name, {Map options: null, List buffer: null, int offset: 0})

Generate and return a RFC4122 v5 UUID.

  • options - (Map) Optional uuid state to apply. Properties may include:

    • randomNamespace - (Boolean) Default True. Returns if you want a v4 generated namespace (true) or NAMESPACE_NIL (false)
  • buffer - (List) Array or buffer where UUID bytes are to be written.

  • offset - (Number) Starting index in buffer at which to begin writing.

Returns buffer, if specified, otherwise the string form of the UUID

Example: Generate string UUID with fully-specified options

uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com');
// -> "c74a196f-f19d-5ea9-bffd-a2742432fc9c"

Example: Generate two IDs in a single buffer

var myBuffer = new List(32);
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com', buffer: myBuffer);
uuid.v5(Uuid.NAMESPACE_URL, 'www.google.com', buffer: myBuffer, offset: 16);

uuid.parse(String uuid, {List buffer: null, int offset: 0})

uuid.unparse(List buffer, {int offset: 0})

Parse and unparse UUIDs

  • id - (String) UUID(-like) string
  • buffer - (List) Array or buffer where UUID bytes are to be written. Default: A new Array or Buffer is used
  • offset - (Int | Number) Starting index in buffer at which to begin writing. Default: 0

Example parsing and unparsing a UUID string

var bytes = uuid.parse('797ff043-11eb-11e1-80d6-510998755d10'); // -> [121, 127, 240, 67, 17, 235, 17, 225, 128, 214, 81, 9, 152, 117, 93, 16]
var string = uuid.unparse(bytes); // -> '797ff043-11eb-11e1-80d6-510998755d10'

For more examples or usage, check my test implementations.

Testing

In dartvm

dart test\uuid_test.dart

In Browser

N/A as I have not used or tested this in the browser. But there are users of this library that do, and reported that it does infact work.

Benchmarking

Its pretty quick, but no official benchmarking.

Release notes

See CHANGELOG

v0.5.3

  • Merged pull request to support crypto 2.0.0
  • Support convert 2.0.0

v0.5.2

  • Merged pull request to upgrade crypto library to 1.0.0.

v0.5.1

  • Merged pull request for various updates and cleanup.

v0.5.0

  • Reverted back to custom AES implementation. Moved RNG methods to UuidUtil (import 'package:uuid/uuid_util.dart')
  • Fixed a potential bug with custom RNG method passing and added more ways to pass in custom RNG functions.
  • Cleaned up and refactored some stuff. Using only v1 is only 67kb of js, Using only v4 is 97kb. Using crypt v4 is 118kb. Using both v1 and non-crypto v4 is 126kb.
  • Default RNG for v4 is now the mathRNG function. If you wish to use cryptoRNG, import UuidUtil and pass in cryptoRNG.
  • Updated README.md with more examples and usages.
  • Updated Tests.

v0.4.1

  • Changed initCipher location so that if you ever only use v1 UUIDs, you will get a very small Dart2JS output compared to v4 or v5 that do load it.

v0.4.0

  • Use Cipher base.dart, as I don't need entropy generators, and this allows me to merge client/server together again and fix many issues this caused.

v0.3.2

  • Fix import/library bug.

v0.3.1

  • Update pubspec to allow installation of the latest Cipher 0.7.

v0.3.0

  • Updated to latest Cipher at 0.6.0. This created a breaking change in the imports. Please make sure you update your code.
  • Fixed problem when creating v4 UUIDs too fast, it would create duplicate UUIDs.

v0.2.2

  • Pegging cipher to 0.4.0 temporarily for browser support

v0.2.1

  • Using new version of cipher.

v0.2.0

  • Dart 1.0 Readiness
  • Switched from custom AES to cipher package AES.

v0.1.6

  • Adjusting usage of constants.
  • Fixing tests.

v0.1.5

  • Stupid typo on import.

v0.1.4

  • Fixing Crypto package move.

v0.1.3

  • Fixing language changes.

v0.1.2

  • Fix change of charCodes to codeUnits

v0.1.1

  • Fixing syntax for upcoming breaking changes.

v0.1.0

  • Cleanup, changes, and prep for M3.

v0.0.9

  • Minor fix with a const RegExp
  • Made sure everything builds on latest dart.
  • Fixed pubspec to now import unittest from pub instead of sdk.

v0.0.8

  • Changed to the new optional paramater syntaxes and usages.
  • Adjusted tests for the new function call style due to parameter change.
  • Fixed Import/Source/Library statements to the new format.

v0.0.7

  • Made changes requested by the Google team to get my package up on pub.dartlang.org

v0.0.6

  • Fixed up some code to make it possibly faster and using better Dart practices.
  • Cleaned up some documentation.

v0.0.5

  • Added Initial AES for Dart (untested if it actually works/matches other AES encryptors)
  • Use AES cipher to create crypto strong bytes.

v0.0.4

  • Issue wasn't Math.Random() but a bad reseed by me.
  • Cleaned up for new Pub layout.

v0.0.3

  • Added UUIDv5
  • Fixed UUIDv4 bugs
  • Added more unit tests
  • Found bug in dart's Math.Random(), reported, waiting for fix to fix my code.

v0.0.2

  • Initial tests
  • Fixed some parser bugs.

v0.0.1

  • Initial Release
  • No tests

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  uuid: "^0.5.3"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:uuid/uuid.dart';
        
Version Uploaded Documentation Archive
0.5.3 Jun 4, 2016 Go to the documentation of uuid 0.5.3 Download uuid 0.5.3 archive
0.5.2 Apr 11, 2016 Go to the documentation of uuid 0.5.2 Download uuid 0.5.2 archive
0.5.1 Mar 31, 2016 Go to the documentation of uuid 0.5.1 Download uuid 0.5.1 archive
0.5.0 Dec 31, 2014 Go to the documentation of uuid 0.5.0 Download uuid 0.5.0 archive
0.4.1 Sep 29, 2014 Go to the documentation of uuid 0.4.1 Download uuid 0.4.1 archive
0.4.0 Aug 14, 2014 Go to the documentation of uuid 0.4.0 Download uuid 0.4.0 archive
0.3.2 Apr 20, 2014 Go to the documentation of uuid 0.3.2 Download uuid 0.3.2 archive
0.3.1 Apr 11, 2014 Go to the documentation of uuid 0.3.1 Download uuid 0.3.1 archive
0.3.0 Feb 27, 2014 Go to the documentation of uuid 0.3.0 Download uuid 0.3.0 archive
0.2.2 Jan 19, 2014 Go to the documentation of uuid 0.2.2 Download uuid 0.2.2 archive

All 23 versions...

Analysis

This feature is new.
We welcome feedback.

We analyzed this package, and provided a score, details, and suggestions below.

  • completed on Dec 6, 2017
  • Dart: 2.0.0-dev.8.0
  • pana: 0.7.3+1

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
98
Health:
Code health derived from static analysis. [more]
94
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
49
Overall score:
Weighted score of the above. [more]
87

Platforms

Detected platforms: Flutter, server, web

All libraries agree

Suggestions

  • Use analysis_options.yaml.

    Rename old .analysis_options file to analysis_options.yaml.

Dependencies

Package Constraint Resolved Available
Direct dependencies
convert >=1.0.0 <3.0.0 2.0.1
crypto >=1.0.0 <3.0.0 2.0.2+1
Transitive dependencies
charcode 1.1.1
collection 1.14.3
typed_data 1.1.5
Dev dependencies
test any