🛁 go-sanitize

Lightweight Go library providing robust string sanitization and normalization utilities

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

• Installation
• Usage
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

📦 Installation

go-sanitize requires a supported release of Go. shell script go get -u github.com/mrz1836/go-sanitize

💡 Usage

Here is a basic example of how to use go-sanitize in your Go project:

```go package main

import ( "fmt" "github.com/mrz1836/go-sanitize" )

func main() { // Sanitize a string to remove unwanted characters input := "Hello, World! @2025" sanitized := sanitize.AlphaNumeric(input, false) // true to keep spaces

// Output: "Sanitized String: HelloWorld2025"
fmt.Println("Sanitized String:", sanitized) 

} ```

• Explore additional usage examples for practical integration patterns
• Review benchmark results to assess performance characteristics
• Examine the comprehensive test suite for validation and coverage
• Fuzz tests are available to ensure robustness against unexpected inputs

📚 Documentation

View the generated documentation

Heads up! go-sanitize is intentionally light on dependencies. The only external package it uses is the excellent testify suite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.

Features

• Alpha and alphanumeric sanitization with optional spaces
• Bitcoin and Bitcoin Cash address sanitizers
• Custom regular expression helper for arbitrary patterns
• Precompiled regex sanitizer for repeated patterns
• Decimal, domain, email and IP address normalization
• HTML and XML stripping with script removal
• URI, URL and XSS sanitization

Functions

• Alpha: Remove non-alphabetic characters, optionally keep spaces
• AlphaNumeric: Remove non-alphanumeric characters, optionally keep spaces
• BitcoinAddress: Filter input to valid Bitcoin address characters
• BitcoinCashAddress: Filter input to valid Bitcoin Cash address characters
• Custom: Use a custom regex to filter input (legacy)
• CustomCompiled: Use a precompiled custom regex to filter input (suggested)
• Decimal: Keep only decimal or float characters
• Domain: Sanitize domain, optionally preserving case and removing www
• Email: Normalize an email address
• FirstToUpper: Capitalize the first letter of a string
• FormalName: Keep only formal name characters
• HTML: Strip HTML tags
• IPAddress: Return sanitized and valid IPv4 or IPv6 address
• Numeric: Remove all but numeric digits
• PhoneNumber: Keep digits and plus signs for phone numbers
• PathName: Sanitize to a path-friendly name
• Punctuation: Allow letters, numbers and basic punctuation
• ScientificNotation: Keep characters valid in scientific notation
• Scripts: Remove scripts, iframe and object tags
• SingleLine: Replace line breaks and tabs with spaces
• Time: Keep only valid time characters
• URI: Keep characters allowed in a URI
• URL: Keep characters allowed in a URL
• XML: Strip XML tags
• XSS: Remove common XSS attack strings

Additional Documentation & Repository Management

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

bash script make test

Run all tests with race detector (slower): bash script make test-race

⚡ Benchmarks

Run the Go benchmarks:

bash script make bench

Benchmark Results

| Benchmark | Iterations | ns/op | B/op | allocs/op | |-------------------------------------------------------|------------|--------:|-----:|----------:| | Alpha | 14,018,806 | 84.89 | 24 | 1 | | Alpha_WithSpaces | 12,664,946 | 94.25 | 24 | 1 | | AlphaNumeric | 9,161,546 | 130.6 | 32 | 1 | | AlphaNumeric_WithSpaces | 7,978,879 | 150.8 | 32 | 1 | | BitcoinAddress | 8,843,929 | 137.1 | 48 | 1 | | BitcoinCashAddress | 5,892,612 | 196.2 | 48 | 1 | | Custom (Legacy) | 938,733 | 1,249.0 | 913 | 16 | | CustomCompiled | 1,576,502 | 762.3 | 96 | 5 | | Decimal | 16,285,825 | 73.91 | 24 | 1 | | Domain | 4,784,115 | 251.6 | 176 | 3 | | Domain_PreserveCase | 5,594,325 | 213.9 | 160 | 2 | | Domain_RemoveWww | 4,771,556 | 251.0 | 176 | 3 | | Email | 8,380,172 | 144.2 | 48 | 2 | | Email_PreserveCase | 13,468,302 | 90.06 | 24 | 1 | | FirstToUpper | 57,342,418 | 20.60 | 16 | 1 | | FormalName | 14,557,754 | 83.12 | 24 | 1 | | HTML | 2,558,787 | 468.5 | 48 | 3 | | IPAddress | 11,388,638 | 102.7 | 32 | 2 | | IPAddress_IPV6 | 3,434,715 | 350.9 | 96 | 2 | | Numeric | 22,661,516 | 52.92 | 16 | 1 | | PhoneNumber | 17,502,224 | 68.84 | 24 | 1 | | PathName | 13,881,150 | 86.58 | 24 | 1 | | Punctuation | 7,377,070 | 162.3 | 48 | 1 | | ScientificNotation | 19,399,621 | 61.62 | 24 | 1 | | Scripts | 2,060,790 | 580.6 | 16 | 1 | | SingleLine | 9,777,549 | 123.5 | 32 | 1 | | Time | 21,270,655 | 55.92 | 16 | 1 | | URI | 9,005,937 | 133.4 | 32 | 1 | | URL | 8,989,400 | 135.2 | 32 | 1 | | XML | 4,351,617 | 275.7 | 48 | 3 | | XSS | 3,302,917 | 362.9 | 40 | 2 |

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments. Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64).

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers

| | |:------------------------------------------------------------------------------------------------:| | MrZ |

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome :raisedhands:! The most basic way to show your support is to star :star2: the project, or to raise issues :speechballoon:. You can also support this project by becoming a sponsor on GitHub :clap: or by making a bitcoin donation to ensure this journey continues indefinitely! :rocket:

📝 License