From 26535ba0972f2fe749ae8dc010168257e6b7c292 Mon Sep 17 00:00:00 2001 From: Stephen Celis Date: Mon, 4 Feb 2013 17:45:09 -0800 Subject: [PATCH] Initial commit Druuid generates 64-bit, time-sortable UUIDs. When converted to base 36, they're quite compact (e.g., '2cnpvvfko1s3d'). Signed-off-by: Stephen Celis --- .gitignore | 2 ++ Gemfile | 2 ++ Gemfile.lock | 26 +++++++++++++++++ Makefile | 5 ++++ README.markdown | 71 +++++++++++++++++++++++++++++++++++++++++++++ Rakefile | 7 +++++ druuid.gemspec | 21 ++++++++++++++ druuid.js | 61 ++++++++++++++++++++++++++++++++++++++ druuid.rb | 43 +++++++++++++++++++++++++++ package.json | 23 +++++++++++++++ spec/druuid_spec.js | 70 ++++++++++++++++++++++++++++++++++++++++++++ spec/druuid_spec.rb | 57 ++++++++++++++++++++++++++++++++++++ 12 files changed, 388 insertions(+) create mode 100644 .gitignore create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 Makefile create mode 100644 README.markdown create mode 100644 Rakefile create mode 100644 druuid.gemspec create mode 100644 druuid.js create mode 100644 druuid.rb create mode 100644 package.json create mode 100644 spec/druuid_spec.js create mode 100644 spec/druuid_spec.rb diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..022b988 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +node_modules +vendor diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..e45e65f --- /dev/null +++ b/Gemfile @@ -0,0 +1,2 @@ +source :rubygems +gemspec diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..413a740 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,26 @@ +PATH + remote: . + specs: + druuid (1.0.0) + +GEM + remote: http://rubygems.org/ + specs: + diff-lcs (1.1.3) + rake (10.0.3) + rspec (2.12.0) + rspec-core (~> 2.12.0) + rspec-expectations (~> 2.12.0) + rspec-mocks (~> 2.12.0) + rspec-core (2.12.2) + rspec-expectations (2.12.1) + diff-lcs (~> 1.1.3) + rspec-mocks (2.12.2) + +PLATFORMS + ruby + +DEPENDENCIES + druuid! + rake + rspec diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..fe180e9 --- /dev/null +++ b/Makefile @@ -0,0 +1,5 @@ + +test: + @node_modules/.bin/mocha --require should spec/druuid_spec + +.PHONY: test diff --git a/README.markdown b/README.markdown new file mode 100644 index 0000000..c04aeb0 --- /dev/null +++ b/README.markdown @@ -0,0 +1,71 @@ +# Druuid + +Date-relative UUID generation. + + +## Overview + +Druuid generates 64-bit, time-sortable UUIDs. + + +## Dependencies/Installation + +### Node + +``` sh +$ brew install gmp # `apt-get install libgmp' on Ubuntu. +$ npm install druuid +``` + +### Ruby + +``` sh +$ gem install druuid +``` + + +## Examples + +### Node + +``` javascript +var druuid = require('druuid'); +var uuid = druuid.gen(); +// => +druuid.time(uuid); +// => Sat Feb 04 2012 00:00:00 GMT-0800 (PST) +``` + +### Ruby + +``` ruby +require 'druuid' +uuid = Druuid.gen +# => 11142943683383068069 +Druuid.time uuid +# => 2012-02-04 00:00:00 -0800 +``` + +## License + +(The MIT License) + +© 2013 Recurly Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..a35f4c5 --- /dev/null +++ b/Rakefile @@ -0,0 +1,7 @@ +begin + require 'rspec/core/rake_task' + RSpec::Core::RakeTask.new + task default: :spec +rescue LoadError + warn "RSpec unavailable; run `bundle'." +end diff --git a/druuid.gemspec b/druuid.gemspec new file mode 100644 index 0000000..a4ef7e7 --- /dev/null +++ b/druuid.gemspec @@ -0,0 +1,21 @@ +Gem::Specification.new do |s| + s.name = 'druuid' + s.version = '1.0.0' + s.summary = 'Date-relative UUID generation' + s.description = 'Druuid generates 64-bit, time-sortable UUIDs.' + + s.require_path = '.' + s.files = 'druuid.rb' + s.test_file = 'spec/druuid_spec.rb' + + s.author = 'Stephen Celis' + s.email = 'stephen@recurly.com' + s.homepage = 'https://github.com/recurly/druuid' + + s.add_development_dependency 'rake' + s.add_development_dependency 'rspec' + + s.required_ruby_version = '>= 1.9' + + s.license = 'MIT' +end diff --git a/druuid.js b/druuid.js new file mode 100644 index 0000000..3dc1d41 --- /dev/null +++ b/druuid.js @@ -0,0 +1,61 @@ + +/*! + * druuid: Date-relative UUID generation. + */ + +/** + * Module dependencies. + */ + +var bigint = require('bigint'); + +/** + * Module exports. + */ + +var druuid = module.exports = {}; + +/** + * The offset from which druuid UUIDs are generated (in milliseconds). + */ + +druuid.epoch = 0; + +/** + * Generates a time-sortable, 64-bit UUID. + * + * Examples: + * + * druuid.gen() + * // => + * + * @param {Date} [date=new Date()] of UUID + * @param {Number} [epoch=druuid.epoch] offset + * @return {BigInt} UUID + */ + +druuid.gen = function gen(date, epoch){ + if (!date) date = new Date(); + if (!epoch) epoch = druuid.epoch; + var id = bigint(date - epoch).shiftLeft(63 - 40); + return id.or(Math.round(Math.random() * 1e16) % Math.pow(2, 63 - 40)); +}; + +/** + * Determines when a given UUID was generated. + * + * Examples: + * + * druuid.time(11142943683383068069); + * // => Sat Feb 04 2012 00:00:00 GMT-0800 (PST) + * + * @param {BigInt|Number|String} uuid + * @param {Number} [epoch=druuid.epoch] offset + * @return {Date} when UUID was generated + */ + +druuid.time = function(uuid, epoch){ + if (!epoch) epoch = druuid.epoch; + var ms = bigint(uuid).shiftRight(63 - 40).toNumber(); + return new Date(ms + epoch); +}; diff --git a/druuid.rb b/druuid.rb new file mode 100644 index 0000000..27fce76 --- /dev/null +++ b/druuid.rb @@ -0,0 +1,43 @@ +require 'securerandom' + +# = Druuid +# +# Date-relative UUID generation. +module Druuid + + class << self + + # The offset from which Druuid UUIDs are generated (in seconds). + attr_accessor :epoch + + # Generates a time-sortable, 64-bit UUID. + # + # @example + # Druuid.gen + # # => 11142943683383068069 + # @param [Time] time of UUID + # @param [Numeric] epoch offset + # @return [Bignum] UUID + def gen time = Time.now, epoch = epoch + ms = ((time.to_f - epoch.to_i) * 1e3).round + rand = (SecureRandom.random_number * 1e16).round + id = ms << (63 - 40) + id | rand % (2 ** (63 - 40)) + end + + # Determines when a given UUID was generated. + # + # @param [Numeric] uuid + # @param [Numeric] epoch offset + # @return [Time] when UUID was generated + # @example + # Druuid.time 11142943683383068069 + # # => 2012-02-04 00:00:00 -0800 + def time uuid, epoch = epoch + ms = uuid >> (63 - 40) + Time.at (ms / 1e3) + epoch.to_i + end + + end + +end diff --git a/package.json b/package.json new file mode 100644 index 0000000..3867de9 --- /dev/null +++ b/package.json @@ -0,0 +1,23 @@ +{ + "name": "druuid" + , "version": "1.0.0" + , "description": "Date-relative UUIDs" + , "contributors": [ + "Stephen Celis " + ] + , "main": "./druuid" + , "repository": { + "type": "git", + "url": "https://github.com/recurly/druuid.git" + } + , "dependencies": { + "bigint": "0.3.9" + } + , "devDependencies": { + "jshint": "*" + , "mocha": "*" + , "should": "*" + } + , "engines": { "node": "0.8.x" } + , "license": "MIT" +} diff --git a/spec/druuid_spec.js b/spec/druuid_spec.js new file mode 100644 index 0000000..5f42b22 --- /dev/null +++ b/spec/druuid_spec.js @@ -0,0 +1,70 @@ + +var druuid = require('../druuid') + , bigint = require('bigint'); + +describe('druuid', function(){ + describe('.gen', function(){ + it('generates a UUID', function(){ + var uuid = druuid.gen(); + uuid.should.be.instanceOf(bigint); + uuid.should.not.equal(druuid.gen()); + }); + + var datetime = new Date(Date.UTC(2012, 1, 4, 8)) + , prefix = '111429436833'; + context('with a given time', function(){ + it('generates the UUID against the time', function(){ + var uuid = druuid.gen(datetime).toString(); + uuid.substr(0, 12).should.equal(prefix); + }); + }); + + var offset = 1000 * 60 * 60 * 24; + context('with a given epoch', function(){ + it('generates the UUID against the offset', function(){ + var dateoffset = new Date(datetime); + dateoffset.setMilliseconds(dateoffset.getMilliseconds() + offset); + var uuid = druuid.gen(dateoffset, offset).toString(); + uuid.substr(0, 12).should.equal(prefix); + }); + }); + + context('with a default epoch', function(){ + var oldEpoch; + before(function(){ oldEpoch = druuid.epoch, druuid.epoch = offset; }); + it('generates the UUID against the offset', function(){ + var dateoffset = new Date(datetime); + dateoffset.setMilliseconds(dateoffset.getMilliseconds() + offset); + var uuid = druuid.gen(dateoffset).toString(); + uuid.substr(0, 12).should.equal(prefix); + }); + after(function(){ druuid.epoch = oldEpoch; }); + }); + }); + + describe('.time', function(){ + var datetime = new Date(Date.UTC(2012, 1, 4, 8)) + , uuid = '11142943683383068069'; + it('determines when a UUID was generated', function(){ + druuid.time(uuid).should.equal(datetime); + }); + + var offset = 1000 * 60 * 60 * 24 + , dateoffset = new Date(datetime); + dateoffset.setMilliseconds(dateoffset.getMilliseconds() + offset); + context('with a given epoch', function(){ + it('determines UUID date against the offset', function(){ + druuid.time(uuid, offset).should.equal(dateoffset); + }); + }); + + context('with a default epoch', function(){ + var oldEpoch; + before(function(){ oldEpoch = druuid.epoch, druuid.epoch = offset; }); + it('generates the UUID against the offset', function(){ + druuid.time(uuid).should.equal(dateoffset); + }); + after(function(){ druuid.epoch = oldEpoch; }); + }); + }); +}); diff --git a/spec/druuid_spec.rb b/spec/druuid_spec.rb new file mode 100644 index 0000000..456f310 --- /dev/null +++ b/spec/druuid_spec.rb @@ -0,0 +1,57 @@ +require_relative '../druuid' + +describe Druuid do + describe '.gen' do + it 'generates a UUID' do + uuid = Druuid.gen + uuid.should be_instance_of Bignum + uuid.should_not eq Druuid.gen + end + + let(:datetime) { Time.utc 2012, 2, 4, 8 } + let(:prefix) { '111429436833' } + context 'with a given time' do + it 'generates the UUID against the time' do + Druuid.gen(datetime).to_s[0, 12].should eq prefix + end + end + + let(:offset) { 60 * 60 * 24 } + context 'with a given epoch' do + it 'generates the UUID against the offset' do + Druuid.gen(datetime + offset, offset).to_s[0, 12].should eq prefix + end + end + + context 'with a default epoch' do + before { @old_epoch, Druuid.epoch = Druuid.epoch, offset } + it 'generates the UUID against the offset' do + Druuid.gen(datetime + offset).to_s[0, 12].should eq prefix + end + after { Druuid.epoch = @old_epoch } + end + end + + describe '.time' do + let(:datetime) { Time.utc 2012, 2, 4, 8 } + let(:uuid) { 11142943683383068069 } + it 'determines when a UUID was generated' do + Druuid.time(uuid).should eq datetime + end + + let(:offset) { 60 * 60 * 24 } + context 'with a given epoch' do + it 'determines UUID date against the offset' do + Druuid.time(uuid, offset).should eq datetime + offset + end + end + + context 'with a default epoch' do + before { @old_epoch, Druuid.epoch = Druuid.epoch, offset } + it 'determines UUID date against the offest' do + Druuid.time(uuid).should eq datetime + offset + end + after { Druuid.epoch = @old_epoch } + end + end +end