Merge pull request #24 from Stravaig-Projects/#22-static-shortcode

#22 Add a static class to gen short codes quickly

Author: colinangusmackay

README.md

@@ -34,6 +34,36 @@ You can also install using the package manager.
 
 If you are going to be using extensions for the Microsoft Dependency Injection then you only need to install the `Straviag.ShortCode.DependencyInjection` package in your application entry assembly (the assembly in which you setup the dependency injection for your application) as it has a dependency on `Stravaig.ShortCode` already. In any other assembly in your application that needs to generate short codes, you will typically only need to install the `Stravaig.ShortCode` package.
 
+## Fastest way to get started
+
+There is a `static ShortCode` class that is preconfigures with some _reasonable_ defaults, although they can be overridden if desired.
+
+To get a short code:
+
+```csharp
+// To generate a 7 character random short code
+ShortCode.GenerateRandomShortCode();
+
+// To generate short code of the given length
+ShortCode.GenerateRandomShortCode(int length);
+
+// To generate a 7 character sequential short code
+ShortCode.GenerateSequentialShortCode();
+
+// To generate sequential short code of the given length
+ShortCode.GenerateSequentialShortCode(int length);
+```
+
+There are some configuration methods you can call during your app's startup:
+
+* `ShortCode.SetLength(int)` sets the default length of the short codes that you want, defaults to 7.
+* `ShortCode.SetSequentialSeed(ulong)` sets the starting point for the sequential codes, otherwise it will reset to zero every time your app starts.
+* `ShortCode.SetCharacterSpace(string)` sets the characters that can be used in a short code, defaults to `NamedCharacterSpaces.LettersAndDigits` which is a list of unaccented Latin letters in lower and upper case and the digits zero to nine.
+* `ShortCode.Use<TGenerator>()` sets the random generator to use. `TGenerator` can be:
+  - `GuidCodeGenerator`: The code is a hashed form of a GUID
+  - `RandomCodeGenerator`: The code is generated from the `Random` class.
+  - `CrytographicallyRandomCodeGenerator`: The code is generated using a cryptographic strength random number generator.
+
 ## Setting up Short Codes with Microsoft's Dependency Injection
 
 If web apps this will be in your `Startup` class, somewhere in the `ConfigureServices` method. Otherwise it will go wherever you are adding your dependency to the service collection.

release-notes/wip-release-notes.md

@@ -8,10 +8,13 @@ Date: ???
 
 ### Features
 
+* #22: Static methods for accessing Short codes more easily
+
 ### Miscellaneous
 
 * Remove "IsDraft" flag from release task in the build.
 
 ### Dependabot
 
+* Bump Moq from 4.15.2 to 4.16.0
 

src/Stravaig.ShortCode.Tests/ShortCodeTests.cs

@@ -0,0 +1,114 @@
+using System;
+using System.Collections.Generic;
+using NUnit.Framework;
+using Shouldly;
+using Stravaig.ShortCode.Tests.__helpers;
+
+namespace Stravaig.ShortCode.Tests
+{
+    [TestFixture]
+    public class ShortCodeTests
+    {
+        [SetUp]
+        public void Reset()
+        {
+            var staticType = typeof(ShortCode);
+            var constructor = staticType.TypeInitializer ?? throw new InvalidOperationException($"{nameof(ShortCode)} is expected to have a static constructor.");
+            constructor.Invoke(null, Array.Empty<object>());
+        }
+
+        [Test]
+        public void DefaultSettings_HappyPath()
+        {
+            var sequentialCode1 = ShortCode.GenerateSequentialShortCode();
+            sequentialCode1.Length.ShouldBe(7);
+            sequentialCode1.ShouldBe("aaaaaab");
+            
+            var sequentialCode2 = ShortCode.GenerateSequentialShortCode();
+            sequentialCode2.Length.ShouldBe(7);
+            sequentialCode2.ShouldBe("aaaaaac");
+
+            var randomCode1 = ShortCode.GenerateRandomShortCode();
+            randomCode1.Length.ShouldBe(7);
+
+            var randomCode2 = ShortCode.GenerateRandomShortCode();
+            randomCode2.Length.ShouldBe(7);
+            randomCode1.ShouldNotBe(randomCode2);
+        }
+        
+        [Test]
+        [TestCaseSource(sourceName: nameof(Lengths))]
+        public void SetLength_HappyPath(int length)
+        {
+            ShortCode.SetDefaultLength(length);
+            
+            var sequentialCode = ShortCode.GenerateSequentialShortCode();
+            sequentialCode.Length.ShouldBe(length);
+            
+            var randomCode = ShortCode.GenerateRandomShortCode();
+            randomCode.Length.ShouldBe(length);
+        }
+        
+        [Test]
+        [TestCase(10UL, "aaaaaal")]
+        [TestCase(100UL, "aaaaabN")]
+        public void SetSequentialSeed_HappyPath(ulong seed, string value)
+        {
+            ShortCode.SetSequentialSeed(seed);
+            var sequentialCode = ShortCode.GenerateSequentialShortCode();
+            sequentialCode.ShouldBe(value);
+        }
+
+        [Test]
+        [TestCase("0001111", "01")]
+        [TestCase("AAABBBB", "AB")]
+        [TestCase("AAAAADD", "ABCD")]
+        [TestCase("0000030", "01234")]
+        public void SetCharacterSpace_HappyPath(string value, string characterSpace)
+        {
+            ShortCode.SetSequentialSeed(14UL);
+            ShortCode.SetCharacterSpace(characterSpace);
+            var sequentialCode = ShortCode.GenerateSequentialShortCode();
+            sequentialCode.ShouldBe(value);
+        }
+
+        [Test]
+        public void Use_SetsTheInternalGeneratorToRandom()
+        {
+            ShortCode.Use<RandomCodeGenerator>();
+            dynamic shortCode = new StaticJailbreak(typeof(ShortCode));
+            IShortCodeGenerator generator = (IShortCodeGenerator)shortCode._randomGenerator;
+
+            generator.ShouldNotBeNull();
+            generator.ShouldBeOfType(typeof(RandomCodeGenerator));
+        }
+        
+        [Test]
+        public void Use_SetsTheInternalGeneratorToGuid()
+        {
+            ShortCode.Use<GuidCodeGenerator>();
+            dynamic shortCode = new StaticJailbreak(typeof(ShortCode));
+            IShortCodeGenerator generator = (IShortCodeGenerator)shortCode._randomGenerator;
+
+            generator.ShouldNotBeNull();
+            generator.ShouldBeOfType(typeof(GuidCodeGenerator));
+        }
+
+        [Test]
+        public void Use_SetsTheInternalGeneratorToCryptographicallyRandom()
+        {
+            ShortCode.Use<CryptographicallyRandomCodeGenerator>();
+            dynamic shortCode = new StaticJailbreak(typeof(ShortCode));
+            IShortCodeGenerator generator = (IShortCodeGenerator)shortCode._randomGenerator;
+
+            generator.ShouldNotBeNull();
+            generator.ShouldBeOfType(typeof(CryptographicallyRandomCodeGenerator));
+        }
+
+        private static IEnumerable<int> Lengths()
+        {
+            for (int i = 1; i <= 9; i++)
+                yield return i;
+        }
+    }
+}

src/Stravaig.ShortCode.Tests/__helpers/Jailbreak.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Dynamic;
+using System.Reflection;
+
+namespace Stravaig.ShortCode.Tests.__helpers
+{
+    public class StaticJailbreak : DynamicObject
+    {
+        private const MemberTypes IsPropertyOrField = MemberTypes.Property | MemberTypes.Field;
+        private const BindingFlags AllAccessModifiers = BindingFlags.Public | BindingFlags.NonPublic;
+        
+        private readonly Type _type;
+
+        public StaticJailbreak(Type staticType)
+        {
+            _type = staticType;
+        }
+
+        public override bool TryGetMember(GetMemberBinder binder, out object result)
+        {
+            MemberInfo[] members = _type.GetMember(
+                binder.Name,
+                IsPropertyOrField, 
+                AllAccessModifiers | BindingFlags.Static | BindingFlags.GetField | BindingFlags.GetProperty);
+            if (members.Length == 0)
+            {
+                result = null;                
+                return false;
+            }
+
+            if (members.Length > 1)
+            {
+                throw new AmbiguousMatchException($"Found {members.Length} matches for {binder.Name}.");
+            }
+
+            var member = members[0];
+            if (member is FieldInfo field)
+            {
+                result = field.GetValue(null);
+                return true;
+            }
+            
+            if (member is PropertyInfo property)
+            {
+                var method = property.GetMethod;
+                if (method == null)
+                {
+                    result = null;
+                    return false;
+                }
+
+                result = method.Invoke(null, Array.Empty<object>());
+                return true;
+            }
+            
+            throw new InvalidOperationException($"{member} is not a property or field.");
+        }
+    }
+}

src/Stravaig.ShortCode/ShortCode.cs

@@ -0,0 +1,55 @@
+using System;
+
+namespace Stravaig.ShortCode
+{
+    public static class ShortCode
+    {
+        private static int _defaultLength;
+        private static Encoder _encoder;
+        private static SequentialCodeGenerator _sequentialCodeGenerator;
+        private static IShortCodeGenerator _randomGenerator;
+
+        static ShortCode()
+        {
+            _defaultLength = 7;
+            _encoder = new Encoder(NamedCharacterSpaces.LettersAndDigits);
+            _sequentialCodeGenerator = new SequentialCodeGenerator();
+            _randomGenerator = new CryptographicallyRandomCodeGenerator();
+        }
+        
+        public static string GenerateSequentialShortCode(int? length = null)
+        {
+            ulong code = _sequentialCodeGenerator.GetNextCode();
+            return _encoder.Convert(code, length ?? _defaultLength);
+        }
+
+        public static string GenerateRandomShortCode(int? length = null)
+        {
+            ulong code = _randomGenerator.GetNextCode();
+            return _encoder.Convert(code, length ?? _defaultLength);
+        }
+
+        public static void SetSequentialSeed(ulong seed)
+        {
+            _sequentialCodeGenerator = new SequentialCodeGenerator(seed);
+        }
+
+        public static void SetCharacterSpace(string characterSpace)
+        {
+            _encoder = new Encoder(characterSpace);
+        }
+
+        public static void SetDefaultLength(int length)
+        {
+            int maxLength = _encoder.MaxLength();
+            if (length <= 0) throw new ArgumentOutOfRangeException(nameof(length), $"Must be between 1 and {maxLength}");
+            if (length > maxLength) throw new ArgumentOutOfRangeException(nameof(length), $"Must be between 1 and {maxLength}");
+            _defaultLength = length;
+        }
+
+        public static void Use<TGenerator>() where TGenerator : IShortCodeGenerator, new()
+        {
+            _randomGenerator = new TGenerator();
+        }
+    }
+}

version.txt

@@ -1 +1 @@
-0.2.3
+0.3.0