https://github.com/khalidabuhakmeh/codez
A library designed to help generating codes / confirmation strings
https://github.com/khalidabuhakmeh/codez
Last synced: 8 months ago
JSON representation
A library designed to help generating codes / confirmation strings
- Host: GitHub
- URL: https://github.com/khalidabuhakmeh/codez
- Owner: khalidabuhakmeh
- License: mit
- Created: 2018-12-14T18:25:31.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2019-03-04T15:04:23.000Z (almost 7 years ago)
- Last Synced: 2025-04-10T16:40:19.326Z (8 months ago)
- Language: C#
- Size: 73.2 KB
- Stars: 44
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-csharp - Codez - A library designed to help ease the process of generating codes for your end users that can be helpful for confirmation numbers, reservation systems, error codes, and more. (🗒️ Cheatsheets / 📦 Libraries)
README
# 
## Codez
Codez is a library designed to help ease the process of generating codes for your end users that can be helpful for confirmation numbers, reservation systems, error codes, and more.
## Getting Started
> dotnet add package Codez
## Code Generators (ICodeGenerator)
The core of the library is the `ICodeGenerator` interface, which has two methods: `GenerateAsync` and `TryGenerateAsync`. You can also implement your own code generator by inheriting from `CodeGeneratorBase`. The `CodeGeneratorBase` class is made up of several dependencies that can change the behavior of the generate methods:
- Alphabet (`IAlphabet`)
- Randomizer (`IRandomizer`)
- Uniqueness (`IUniqueness`)
- Stop Words (`IStopWords`)
- Options (`CodeGeneratorOptions`)
- Transformers (`ITransformer`)
- Listeners (`IListener`)
Each dependency is explained in detail below. If you don't want to customize anything, Codez also comes with some generators and dependencies out of the box. Some generators in the Codez package are `CodeGenerator` and `NonRepeatingCodeGenerator`.
### GenerateAsync
The `GenerateAsync` method returns a code based on the alphabet and the length specified.
```c#
var generator = new CodeGenerator();
// returns "]hG/g"
string result = await generator.GenerateAsync(length: 5);
```
If the generator fails to generate a code, it will throw a `CodeGeneratorException`.
### TryGenerateAsync
The `TryGenerateAsync` method returns a `CodeGeneratorResult` that gives you the generated value, and some other metadata from the generation process. This method will **not** throw a `CodeGeneratorException`.
```c#
var generator = new CodeGenerator();
// returns CodeGeneratorResult
var result = await generator.TryGenerateAsync(length: 5);
if (result.Success) {
Console.WriteLine(result.Value);
}
```
### Alphabet
The alphabet is an important part of the generation process. You can constrain what kinds of codes get generated by specifying the alphabet appropriately. Codez comes with an `AsciiAlphabet` by default with characters between `! (33)` and `~ (126)` included.
You can also use the `StringAlphabet` class to pass in a string, and each character will be treated as an option during the generation.
```c#
var alphabet = new StringAlphabet("ABCDE");
var characters = alphabet.Characters;
```
You may also implement your own class using the `IAlphabet` interface.
### Randomizer
The `IRandomizer` interface picks a random index based on your alphabet size. The `RandomRandomizer` is used by default.
### Uniqueness
The `IUniqueness` interface allows you to enforce global uniquness on the codes that are being generated. This can be against a database, web api, or whatever you would like. By default, Codez provides a `NoUniqueness` implementation.
### Stop Words
StopWords (`IStopWords`) provides a mechanism to filter out codes that may be deemed inappropriate or incorrect. You can live on the edge by using the default `NoStopWords`. If you like it boring, you can also use the `InMemoryStopWords` implementation and provide inappropriate words there, which uses an `IndexOf` implementation to find matches.
### Transformers
The transformer (`ITransfomer`) interface allows you to take a uniquely generated code and transform it into something else. The transfomer will only run when the result is a `Success`. **Note, The uniqueness of the code coming from a transfomer is not guaranteed.**
There is a sample in which this libary is used to [generate unique container names](https://github.com/khalidabuhakmeh/codez/blob/master/test/Tests/TransformerTests.cs).
### IListener
The `IListener` interface can be implemented on any of the dependencies of a code generator. In `CodeGeneratorBase` all dependencies that implement the interface will will be called twice: `OnBeforeAttempt` and `OnAfterAttempt`. This gives you an oppurtunity to hook into the attempt process.
### Options
Options allow you to alter the behavior of the code generation:
- Retry Limit (default of 5): Number of iterations to attempt generation
## Contributors
- [Tim VanFosson](https://github.com/tvanfosson)