shorol

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

Presets Scope

Presets are scoped, best-effort helpers for common formats. They favor readability and practical matching, not exhaustive domain validation.

• Use shorol/presets for common pattern starters.
• Keep strict business validation in app/domain logic.
• See docs/presets.md for scope and examples.

Quick Start (AI-Ready)

• Goal: human-readable regex for a phone number.
• Input: digits and separators.
• 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

Explain a chain in plain English

Every builder chain can explain itself, useful in code review or for an agent to double-check its own output against intent.

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

phone.explain();
// => 'Start of string, then a named group "area" containing (a digit, repeated 3 times),
//     then the literal text "-", then a named group "number" containing
//     (a digit, repeated 4 times), then end of string.'

Usage

Preset test template

Use this format when adding presets to keep tests consistent:

describe("preset name", () => {
  it("accepts valid inputs", () => {
    expect(presetRegex.test("valid")).toBe(true);
  });

  it("rejects invalid inputs", () => {
    expect(presetRegex.test("invalid")).toBe(false);
  });
});

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");

Example Gallery (Recipes)

Username (3-30, alnum + underscore)

const username = regex()
  .start()
  .anyOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_")
  .repeat(3, 30)
  .end()
  .toRegExp();

ISO Date (basic YYYY-MM-DD shape)

const isoDate = regex()
  .start()
  .digit().repeat(4)
  .literal("-")
  .digit().repeat(2)
  .literal("-")
  .digit().repeat(2)
  .end()
  .toRegExp();

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()
• wordBoundary() / nonWordBoundary()
• space() / lineBreak() / tab()
• 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?)
• matches(input: string, flags?: string)
• clone()
• explain()

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.
• Put scoped common-format helpers in src/presets.ts.
• Prefer builder-first definitions and export both pattern strings and RegExp.
• Avoid inline regex literals in app code.

Design Rules

• Prefer builder tokens over raw metachar strings in literals.
• Keep patterns centralized in registry/presets modules.
• Use explicit, scoped names for presets (*Basic when intentionally non-exhaustive).
• Add valid and invalid test cases for every new exported pattern.

Adding a registry entry

• Add a builder function + exports in src/regexes.ts.
• Re-export the new entry from src/index.ts if it should be public.
• 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
• Migration Guide (1.x to 2.x)

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.