shorol

Shorol is a fluent, human-readable regex builder for JavaScript and TypeScript. It helps teams generate regex that stays readable in code review, centralizes patterns in one place, and exports both pattern strings and RegExp objects for practical use. It is especially useful for keeping complex patterns understandable during code review. It is optimized for easy collaboration.

Install

npm install shorol

🤖 AI Context

If you are an AI assistant, please refer to:

• llms.txt for a condensed API reference.
• SKILL.md for agentic usage instructions.

AI-Trigger Keywords

• humanize regex
• readable regex builder
• fluent regex DSL
• safe regex composition
• regex patterns registry

Registry Helpers (Current)

• slugBuilder, slugPattern, slugRegex
• identifierBuilder, identifierPattern, identifierRegex

Quick Start (AI-Ready)

1. Goal: human-readable regex for a phone number.
2. Input: digits and separators.
3. Output: native RegExp with named groups.

import { regex } from "shorol";

const phone = regex()
  .start()
  .namedGroup("area", (b) => b.digit().repeat(3))
  .literal("-")
  .namedGroup("number", (b) => b.digit().repeat(4))
  .end()
  .toRegExp();

phone.test("415-5555"); // true

Usage

Simple literal

import { regex } from "shorol";

const pattern = regex().start().literal("cat").end();
const re = pattern.toRegExp();

Groups and quantifiers

const re = regex()
  .group((b) => b.literal("cat").orLiteral("dog"))
  .whitespace()
  .word()
  .oneOrMore()
  .toRegExp("i");

Alternation

const pattern = regex().literal("yes").orLiteral("no").toString();

Character classes

const slug = regex()
  .anyOf("abcdefghijklmnopqrstuvwxyz0123456789")
  .oneOrMore()
  .toRegExp("i");

const noSpaces = regex()
  .start()
  .noneOf(" \t\n\r")
  .oneOrMore()
  .end()
  .toRegExp();

const lowerAZ = regex().range("a", "z").oneOrMore().toRegExp();

Lookarounds and named groups

const password = regex()
  .lookahead((b) => b.any().oneOrMore().digit())
  .lookahead((b) => b.any().oneOrMore().anyOf("!@#$"))
  .any()
  .oneOrMore()
  .toRegExp();

const quoted = regex()
  .namedGroup("value", (b) => b.noneOf("\"").oneOrMore())
  .toRegExp();

UUID v4 (builder example)

const uuidV4 = regex()
  .start()
  .anyOf("0123456789abcdef").repeat(8)
  .literal("-")
  .anyOf("0123456789abcdef").repeat(4)
  .literal("-")
  .literal("4")
  .anyOf("0123456789abcdef").repeat(3)
  .literal("-")
  .anyOf("89ab")
  .anyOf("0123456789abcdef").repeat(3)
  .literal("-")
  .anyOf("0123456789abcdef").repeat(12)
  .end()
  .toRegExp("i");

Named capture groups

const re = regex()
  .namedGroup("area", (b) => b.digit().repeat(3))
  .literal("-")
  .namedGroup("number", (b) => b.digit().repeat(4))
  .toRegExp();

Central regex registry

import { slugRegex, identifierPattern } from "shorol";

slugRegex.test("my-post-slug"); // true
const identifier = new RegExp(identifierPattern);

API

Entry

• regex(): Builder

Builder

• start() / end()
• literal(text: string)
• anyOf(chars: string | string[]) / noneOf(chars: string | string[]) / range(from: string, to: string)
• any() / digit() / word() / whitespace()
• group(fn) / namedGroup(name, fn) / nonCapture(fn)
• lookahead(fn) / negativeLookahead(fn) / lookbehind(fn) / negativeLookbehind(fn)
• or(fn) / orLiteral(text)
• optional() / zeroOrMore() / oneOrMore() / repeat(min, max?)
• global() / ignoreCase() / multiline() / dotAll() / unicode()
• flags(flags: string) / toString() / toRegExp(flags?)

AI & Contributor Guidance

Shorol is designed to keep regex readable for humans. To make AI- and human-generated regex easy to review:

• Put all regex definitions in src/regexes.ts.
• Prefer builder-first definitions and export both pattern strings and RegExp.
• Avoid inline regex literals in app code.

Adding a registry entry

1. Add a builder function + exports in src/regexes.ts.
2. Re-export the new entry from src/index.ts if it should be public.
3. Add a small test in src/regexes.test.ts.

Example registry entry:

export const slugBuilder = () =>
  regex()
    .start()
    .word()
    .oneOrMore()
    .nonCapture((b) => b.literal("-").word().oneOrMore())
    .zeroOrMore()
    .end();

export const slugPattern = slugBuilder().toString();
export const slugRegex = slugBuilder().toRegExp();

Project Links

• License
• Code of Conduct
• Feature Plan

Release Process

Releases are automated via GitHub Actions and semantic-release on merges to main. This project follows Conventional Commits to automate releases. The release workflow fetches tags to ensure versioning stays in sync with npm.

License

MIT. See LICENSE.