> For the complete documentation index, see [llms.txt](https://dosaic.gitbook.io/dosaic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dosaic.gitbook.io/dosaic/extensions/sqids.md).

# Sqids

Dosaic.Extensions.Sqids is an extension library that provides string methods to encode and decode values using the [Sqids](https://sqids.org/) algorithm — producing short, YouTube-like identifiers that are URL-safe and reversible.

## Installation

```shell
dotnet add package Dosaic.Extensions.Sqids
```

or add as a package reference to your `.csproj`:

```xml
<PackageReference Include="Dosaic.Extensions.Sqids" Version="" />
```

## Features

* **`ToSqid()`** — encode any string (including Unicode) into a Sqid
* **`FromSqid()`** — decode a Sqid back to the original string (guaranteed round-trip)
* **Default encoder** — pre-configured with a shuffled alphabet and minimum length of 10
* **Custom encoder** — pass a `SqidsEncoder<char>` instance to override encoding options per-call
* **Global encoder override** — replace the default encoder application-wide via `SqidExtensions.Encoder`
* **Null safety** — both methods throw `ArgumentNullException` immediately for `null` inputs
* **Unicode support** — encodes and decodes non-ASCII strings (e.g. Chinese, emoji) correctly

## Usage

### Basic Encoding and Decoding

```csharp
using Dosaic.Extensions.Sqids;

// Encode a string to a Sqid
string sqid = "HelloWorld".ToSqid();
// e.g. "kKs7PVdXUYnH" (length >= 10, URL-safe)

// Decode back to the original string
string original = sqid.FromSqid();
// "HelloWorld"
```

Round-tripping is guaranteed with the same encoder:

```csharp
string value = "ComplexString123";
string result = value.ToSqid().FromSqid();
// result == "ComplexString123"
```

### Unicode and Special Characters

```csharp
string unicode = "你好世界".ToSqid();
string decoded = unicode.FromSqid();
// decoded == "你好世界"

string special = "!@#$%^&*()".ToSqid();
```

### Custom Encoder

Supply a `SqidsEncoder<char>` directly to override options on a per-call basis without affecting the global encoder:

```csharp
using Dosaic.Extensions.Sqids;
using Sqids;

var encoder = new SqidsEncoder<char>(new SqidsOptions
{
    Alphabet = "abcdefghijklmnopqrstuvwxyz0123456789",
    MinLength = 5
});

string sqid     = "Hello".ToSqid(encoder);
string original = sqid.FromSqid(encoder);
// original == "Hello"
```

## Configuration

The default encoder is a static property and can be replaced application-wide:

```csharp
using Dosaic.Extensions.Sqids;
using Sqids;

SqidExtensions.Encoder = new SqidsEncoder<char>(new SqidsOptions
{
    Alphabet  = "yourCustomAlphabetHere",
    MinLength = 12
});
```

**Default settings:**

| Option      | Value                                                            |
| ----------- | ---------------------------------------------------------------- |
| `Alphabet`  | `kKsW7PVdXUYnHgQ6rujl0GepfNzB2qZ9bC83IyDmOAtJ4hcSvM1Roaw5LxEiTF` |
| `MinLength` | `10`                                                             |

## Use Cases

* Creating short, URL-friendly identifiers from arbitrary strings
* Obfuscating sequential or predictable IDs in public-facing URLs
* Generating consistent, reversible short codes for sharing links


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://dosaic.gitbook.io/dosaic/extensions/sqids.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.