wagesj45/CapyKit
wagesj45/CapyKit
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity

Improve developer documentation

Browse source
This commit is contained in:
Jordan Wages 2026-07-07 01:31:52 -05:00
commit ab7b83abbb
48 changed files with 679 additions and 576 deletions
Download patch file Download diff file Expand all files Collapse all files

88
Docs/_site/getting-started.html
View file

@ -73,6 +73,94 @@
<article data-uid="">
<h1 id="getting-started">Getting Started</h1>
<p>This guide shows the common setup and first-use patterns for consuming CapyKit from a .NET 8 project.</p>
<h2 id="install">Install</h2>
<p>Add CapyKit to your project from NuGet:</p>
<pre><code class="lang-bash">dotnet add package CapyKit
</code></pre>
<p>If you are working from a local checkout instead, reference the project directly:</p>
<pre><code class="lang-bash">dotnet add reference ../CapyKit/CapyKit.csproj
</code></pre>
<h2 id="add-namespaces">Add Namespaces</h2>
<p>Most APIs live in one of three namespaces:</p>
<pre><code class="lang-csharp">using CapyKit;
using CapyKit.Extensions;
using CapyKit.Helpers;
</code></pre>
<p>Use <code>CapyKit</code> for core types such as <code>Password</code>, <code>Pool&lt;T&gt;</code>, and <code>CapyEventReporter</code>. Use <code>CapyKit.Extensions</code> for extension methods. Use <code>CapyKit.Helpers</code> for serialization, compression, security, keys, language, and calculation helpers.</p>
<h2 id="work-with-strings">Work With Strings</h2>
<pre><code class="lang-csharp">using CapyKit.Extensions;
string? suppliedName = &quot;&quot;;
string name = suppliedName.IfNullOrWhiteSpace(&quot;Guest&quot;);
</code></pre>
<p><code>IfNullOrEmpty</code> and <code>IfNullOrWhiteSpace</code> return the original value when it is usable and return your replacement value when it is not.</p>
<h2 id="page-and-filter-collections">Page And Filter Collections</h2>
<pre><code class="lang-csharp">using CapyKit.Extensions;
var activeUsers = users.Filter(user =&gt; user.Disabled);
var secondPage = activeUsers.Page(pageNumber: 2, pageSize: 25);
int pageCount = activeUsers.PageCount(pageSize: 25);
</code></pre>
<p><code>Filter</code> removes items that match the predicate. <code>Page</code> uses natural page numbering, so the first page is <code>1</code>.</p>
<h2 id="serialize-and-compress-data">Serialize And Compress Data</h2>
<pre><code class="lang-csharp">using CapyKit.Helpers;
var json = SerializationHelper.SerializeToString(order);
var copy = SerializationHelper.Deserialize&lt;Order&gt;(json);
var compressed = CompressionHelper.CompressToString(order);
var restored = CompressionHelper.Decompress&lt;Order&gt;(compressed);
</code></pre>
<p>Serialization uses <code>System.Text.Json</code>. Compression stores the serialized JSON payload using gzip; <code>CompressToString</code> returns a Base64 representation for easier storage or transport.</p>
<h2 id="hash-and-verify-passwords">Hash And Verify Passwords</h2>
<pre><code class="lang-csharp">using CapyKit;
using CapyKit.Helpers;
Password storedPassword = SecurityHelper.Pbkdf2(&quot;correct horse battery staple&quot;);
bool passwordMatches = SecurityHelper.CompareHashedPassword(
storedPassword,
&quot;correct horse battery staple&quot;,
storedPassword.Salt,
Password.Pbkdf2Algorithm);
</code></pre>
<p><code>SecurityHelper.Pbkdf2</code> creates a <code>Password</code> with a random salt. Store the hash, salt, and algorithm information required by your application, then compare future password attempts using the same salt and algorithm.</p>
<h2 id="generate-random-values">Generate Random Values</h2>
<pre><code class="lang-csharp">using CapyKit.Helpers;
string token = SecurityHelper.GetRandomString(32);
string password = SecurityHelper.GetRandomPassword(
20,
ValidCharacterCollection.Lowercase,
ValidCharacterCollection.Uppercase,
ValidCharacterCollection.Numbers,
ValidCharacterCollection.Special);
</code></pre>
<p>Random string and password generation use .NET cryptographic random number generation.</p>
<h2 id="create-and-validate-keys">Create And Validate Keys</h2>
<pre><code class="lang-csharp">using System.Text;
using CapyKit.Helpers;
var keyHelper = new KeyHelper();
keyHelper.SetMasterKeyAccessor(() =&gt; Encoding.UTF8.GetBytes(&quot;replace-with-your-master-key&quot;));
keyHelper.SetSaltSizeAccessor(() =&gt; 8);
keyHelper.SetNumPartsAccessor(() =&gt; 4);
string key = keyHelper.GenerateKey();
bool valid = keyHelper.ValidateKey(key);
</code></pre>
<p><code>KeyHelper</code> uses an application-provided master key to sign generated key material. Keep the master key secret and stable for keys that must remain valid over time.</p>
<h2 id="subscribe-to-capykit-events">Subscribe To CapyKit Events</h2>
<pre><code class="lang-csharp">using CapyKit;
CapyEventReporter.Subscribe(
e =&gt; Console.WriteLine($&quot;[{e.Level}] {e.MethodName}: {e.Message}&quot;),
EventLevel.Warning);
</code></pre>
<p>CapyKit does not require a logging framework. Subscribe to events and forward them to whatever logging or telemetry system your application already uses.</p>
<h2 id="browse-the-api">Browse The API</h2>
<p>For the full list of namespaces, types, overloads, and member signatures, open the generated <a href="api/toc.html">API Reference</a>.</p>
</article>