diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..d716568 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,24 @@ +# BSD 2-Clause License + +Copyright (c) 2024, Sean Hickey (Wisellama) + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4cfa1b2 --- /dev/null +++ b/README.md @@ -0,0 +1,30 @@ +# ULID + +```sh +go get git.wisellama.rocks/Wisellama/ulid@v0.0.1 +``` + +ULIDs are universally unique lexico-graphically sortable +identifiers. They fit in the same 128-bits as a UUID, except that +instead of being pure random or using some hardware information, they +tag on a timestamp on the front. This makes them random but sortable +which is useful when using them for database IDs. Databases can +pre-load chunks of IDs that it assumes will be used. Fully random IDs +would break this caching functionality, but sortable random IDs will +keep the performance benefits. + +This is Wisellama's implementation of a ULID library following the spec: +https://git.wisellama.rocks/Mirrors/ulid-spec + +I was inspired by oklog's ULID library, and I used it to verify my +implementation was working correctly. I use this library in production +at work, so I highly recommend it. +https://github.com/oklog/ulid + +I did not implement the full spec, and I'm sure I'm missing features +that are available in the oklog repo. However, I wanted to implement +ULIDs myself to support the features I use regularly. I don't like +adding unnecessary dependencies, so if there's something easy enough +that I can implement myself, I will most likely attempt to do so. + +See the examples directory for usage.