Regulas

Regulas is a lightweight, zero-dependency regex builder for JavaScript/TypeScript.

✅ Readable & Composable Syntax ✅ Zero Dependencies – works out of the box ✅ Powerful Features – named groups, lookarounds, ranges, reusable patterns

Instead of writing complex regex strings manually, you compose patterns using simple, readable functions. This makes your regex:

• Clear – easy to read
• Safe – fewer mistakes
• Maintainable – simple to update and reuse

📦 Installation

npm install regulas

or

yarn add regulas

📝 Usage

// ESM
import { Regulas, range, oneOf, allOf, next, prev } from "regulas";

// CJS
const { Regulas, range, oneOf, allOf, next, prev } = require("regulas");

🧠 Mental Model

Think of Regulas like LEGO blocks for regex:

• Pieces – building blocks like range, allOf, oneOf, next, prev
• Quantifiers – .oneOrMore, .zeroOrMore, .optional, .repeat(n,m), .lazy
• Combinators – allOf (sequence), oneOf (alternatives)
• Final step – call .toRegex() to get a real JavaScript RegExp

Note: next and prev are lookarounds and cannot have quantifiers

🚀 Quick Start

import { Regulas, range } from "regulas";

// Match an IPv4 address
const re = Regulas(
  range("0-255").group("first"),
  ".",
  range("0-255").group("second"),
  ".",
  range("0-255").group("third"),
  ".",
  range("0-255").group("fourth")
).toRegex();

console.log(re.test("157.237.84.2")); // true
console.log(re.exec("157.237.84.2").groups);
// { first: "157", second: "237", third: "84", fourth: "2" }

⚡ Core Features

1. Building Blocks

Regulas(...)

Main entry point. Wraps everything into a regex builder. Call .toRegex() directly.

const re = Regulas(
  oneOf("cat")
).toRegex();
console.log(re.test("cat")); // true

range(...pattern)

Create numeric or character ranges.

const re = Regulas(
  range("a-c", "x-z")
).toRegex();
console.log(re.test("b")); // true
console.log(re.test("g")); // false

allOf(...pattern) & oneOf(...pattern)

Combine multiple pieces sequentially (allOf) or as alternatives (oneOf).

// oneOf
const re = Regulas(
  oneOf("cat", "dog")
).toRegex();
console.log(re.test("dog")); // true

// allOf
const re2 = Regulas(
  allOf("cat", "dog")
).toRegex();
console.log(re2.test("catdog")); // true
console.log(re2.test("dogcat")); // false

2. Quantifiers

Attach to any piece (except next and prev):

• .oneOrMore → 1+ matches
• .optional → 0 or 1 match
• .zeroOrMore → 0+ matches
• .repeat(n, m) → between n and m matches
• .lazy → makes quantifier non-greedy

// oneOrMore
const re = Regulas(
  range("a-z").oneOrMore
).toRegex();
console.log(re.test("aaaa")); // true

// optional
const re2 = Regulas(
  range("b").optional
).toRegex();
console.log(re2.test("")); // true

// repeat
const re3 = Regulas(
  range("a-z").repeat(3,5)
).toRegex();
console.log(re3.test("aaa")); // true

// lazy
const re4 = Regulas(
  range("a-z").oneOrMore.lazy
).toRegex();
console.log(re4.test("aaa")); // false

3. Lookarounds

next(...pattern)

Positive or negative lookahead.

// positive
const re = Regulas(
  next(
    allOf("foo")
  )
).toRegex();
console.log(re.test("foobar")); // true

// negative
const re2 = Regulas(
  next(
    allOf("foo")
  ).not
).toRegex();
console.log(re2.test("bar")); // true

prev(...pattern)

Positive or negative lookbehind.

// positive
const re = Regulas(
  prev(
    allOf("bar")
  )
).toRegex();
console.log(re.test("foobar")); // true

// negative
const re2 = Regulas(
  prev(
    allOf("bar")
  ).not
).toRegex();
console.log(re2.test("foo")); // true

4. Named Groups

const re = Regulas(
  allOf("abc").group("myGroup")
).toRegex();
console.log(re.test("abc")); // true
console.log(re.exec("abc").groups); // { myGroup: "abc" }

5. Saving & Reusing Patterns

const username = range("a-zA-Z0-9_+").oneOrMore;
const re = Regulas(username).toRegex();
console.log(re.test("user_123")); // true

// Using saved variable
const re2 = Regulas(
  range("a-zA-Z0-9_+").oneOrMore.save("username"),
  "<username>",
  "<username>"
).toRegex();

6. Start/End Anchors

const re = Regulas(
  allOf("abc")
).fullMatch.toRegex();
console.log(re.test("abc")); // true

📖 Why Use Regulas?

• Readable – self-explanatory regex
• Composable – build complex patterns from reusable pieces
• Powerful – supports lookarounds, named groups, numeric & character ranges

💡 Tips for Beginners

1. Start with range and allOf/oneOf
2. Attach quantifiers to pieces, not raw strings
3. Use next() & prev() for lookarounds/lookbehinds
4. Save reusable patterns with .save('name') and use <name>

⚖ License

MIT License © 2025 SamYeem