Mbrcode

Mbrcode is a lightweight, deterministic, and clean membership code generator for Ruby applications.

It produces stable, structured IDs using the format:

PREFIX + SHARD + "-" + DIGITS

Where:

PREFIX → normalized to exactly 4 characters
SHARD → numeric grouping/version number
DIGITS → auto-incrementing sequence
Raw length before dashes = EXACTLY 16 characters

Example output:

MBR1-0000-0000-000

Mbrcode is ideal for membership systems, gyms, schools, apps, organizations, ERPs, identity platforms, and anything requiring clean, compact, and consistent codes.

✨ Features

🔒 Thread-safe incremental counter
🧩 Smart prefix normalization rules
📏 Always 16 raw characters before dash grouping
🔣 Groups digits into 4-4-4 format when possible
⚙️ Configurable prefix and shard
💎 Zero external dependencies
🚀 Fast, simple, production-ready

📦 Installation

Add to your Gemfile:

gem "mbrcode"

Install:

bundle install

Or install manually:

gem install mbrcode

🚀 Usage

Default generation

Mbrcode.generate
# => "MBR1-0000-0000-000"

Custom prefix

Mbrcode.generate(prefix: "user")
# => "USER1-0000-0000-000"

Multi-word prefix → initials

Mbrcode.generate(prefix: "karate membership")
# => "KM00-0000-0000-000"

Prefix shorter than 4 chars → padded

Mbrcode.generate(prefix: "ab")
# => "AB00-0000-0000-000"

Long prefix → first 4 characters

Mbrcode.generate(prefix: "customer")
# => "CUST1-0000-0000-000"

Custom shard

Mbrcode.generate(prefix: "mbr", shard: 2)
# => "MBR2-0000-0000-000"

🧠 Prefix Normalization Rules

Input Prefix	Output Prefix	Rule Applied
"m"	"M000"	padded to 4 characters
"ab"	"AB00"	padded to 4 characters
"karate membership"	"KM00"	initials + padded
"ruby on rails"	"ROR0"	initials + padded
"customer"	"CUST"	first 4 characters
"USER"	"USER"	unchanged (4 chars)

🔢 16-Character Enforcement

Before grouping and adding dashes, the ID ALWAYS equals:

PREFIX(4) + SHARD(N) + DIGITS(M) = 16 characters

If the shard leaves no space for digits:

Mbrcode.generate(prefix: "abcd", shard: 999999999)
# => raises "Shard too long"

This ensures consistent, predictable, compact membership IDs.

🧪 Testing

Run RSpec tests:

bundle exec rspec

All tests should pass.

🛠 Development

Clone the repository:

git clone https://github.com/delacruzjames/mbrcode.git
cd mbrcode

Install dependencies:

bundle install

Run tests:

bundle exec rspec

🤝 Contributing

Pull requests are welcome!
Please include tests for new features or bug fixes.

📜 License

Released under the MIT License.

👤 Author

Sensei James Dela Cruz
Ruby Developer • API Architect • Karate Instructor

📧 Email: delacruzjamesmartin@gmail.com
🐙 GitHub: @delacruzjames