bleuutils

Shared utilities for the BleuPigs ecosystem, built on BleuMoon.

Installation

Add to your bleumoon.toml:

[dependencies]
bleuutils = "*"

Then install:

bleumoon pkg install

Usage

local bleuutils = require("@pkg/bleuutils/src")

Version / Manifest Reader

Read your package version directly from bleumoon.toml at runtime — no more hardcoded version strings.

local version = bleuutils.version

-- Read just the version string
local ver = version.readVersion()

-- Read the full manifest
local manifest = version.readManifest()
print(manifest.package.name)    -- e.g. "bleuauth"
print(manifest.package.version) -- e.g. "0.2.1"

readVersion() and readManifest() automatically walk up the directory tree from the calling script's location to find the nearest bleumoon.toml. No configuration required — it works from any depth within your project.

URL Utilities

Unified URL encoding, query string, and path building helpers.

local url = bleuutils.url

-- Form data encoding/decoding (RFC 6749 §4.3.2)
local encoded = url.encodeFormData({ grant_type = "authorization_code", code = "abc" })
local decoded = url.decodeFormData("grant_type=authorization_code&code=abc")

-- Query string helpers
local qs = url.buildQueryString({ page = "1", limit = "10" })  -- "?limit=10&page=1" (sorted)
local parsed = url.parseQueryString("?page=1&limit=10")

-- URL building with sorted query parameters
local fullUrl = url.build("https://api.example.com", "/v2/resources", {
    maxPageSize = "10",
    pageToken = "abc",
})

-- Path segment encoding
local segment = url.encodePathSegment("hello world")

-- Path joining
local path = url.join("cloud", "v2", "universes", "123")  -- "/cloud/v2/universes/123"

Base64url Encoding

RFC 4648 §5 base64url encoding/decoding, required by JWT (RFC 7515 §2).

local base64url = bleuutils.base64url

local encoded = base64url.encode("Hello, World!")  -- "SGVsbG8sIFdvcmxkIQ"
local decoded = base64url.decode("SGVsbG8sIFdvcmxkIQ")  -- "Hello, World!"

Byte Utilities

local bytes = bleuutils.bytes

local raw = bytes.hexToBytes("48656c6c6f")  -- "Hello"
local hex = bytes.bytesToHex("Hello")       -- "48656c6c6f"

Prerequisites

• BleuMoon v1.0.0 or later
• StyLua (for code formatting)

Tip: If you have Nix with flakes enabled, both tools are provided automatically via nix develop.

Getting Started

With Nix (recommended)

git clone https://git.ds.reinitialized.net/bleupigs.club/bleuutils.git
cd bleuutils
nix develop

This drops you into a shell with BleuMoon and StyLua available.

Without Nix

1. Install BleuMoon and StyLua manually.

2. Clone the repository:

   git clone https://git.ds.reinitialized.net/bleupigs.club/bleuutils.git
   cd bleuutils
   

3. Install dependencies:

   bleumoon pkg install
   

4. Run the application:

   bleumoon run src/main
   

Running Tests

bleumoon run tests/init

Formatting

Check formatting:

stylua --check .

Apply formatting:

stylua .

Project Structure

├── .editorconfig          # Editor configuration
├── .forgejo/workflows/    # CI/CD pipelines (Forgejo Actions)
├── .github/               # GitHub/Copilot configuration
├── .luaurc                # Luau language settings & aliases
├── .vscode/               # VS Code workspace settings
├── bleumoon.toml          # Project manifest & dependencies
├── flake.nix              # Nix flake for reproducible dev environment
├── stylua.toml            # StyLua formatter configuration
├── CHANGELOG.md           # Version history
├── LICENSE                # MIT License
├── README.md              # This file
├── docs/
│   ├── architecture/      # Architecture Decision Records
│   └── investigations/    # Bug investigation write-ups
├── src/
│   ├── init.luau          # Library entry point (re-exports all modules)
│   ├── main.luau          # CLI entry point
│   ├── base64url.luau     # Base64url encoding/decoding (RFC 4648 §5)
│   ├── bytes.luau         # Byte conversion utilities
│   ├── url.luau           # URL encoding, query strings, path building
│   └── version.luau       # Version/manifest reader from bleumoon.toml
├── tests/
│   ├── init.luau              # Test runner
│   ├── base64url.test.luau    # Base64url tests
│   ├── bytes.test.luau        # Byte utilities tests
│   ├── url.test.luau          # URL utilities tests
│   └── version.test.luau      # Version/manifest reader tests
├── packages/              # Installed dependencies (auto-managed, gitignored)
└── types/                 # Auto-generated type definitions (gitignored)

License

This project is licensed under the MIT License.