refactor: open element types (#33)

Author: mdjastrzebski

src/builders.ts

@@ -1,6 +1,6 @@
-import type { RegexElement } from './components/types';
+import type { RegexNode } from './types';
 import { encodeSequence } from './encoder/encoder';
-import { asElementArray } from './utils/elements';
+import { asNodeArray } from './utils/nodes';
 import { optionalFirstArg } from './utils/optional-arg';
 
 export interface RegexFlags {
@@ -26,7 +26,7 @@ export interface RegexFlags {
  * @param elements Single regex element or array of elements
  * @returns
  */
-export function buildRegex(elements: RegexElement | RegexElement[]): RegExp;
+export function buildRegex(elements: RegexNode | RegexNode[]): RegExp;
 
 /**
  * Generate RegExp object from elements with passed flags.
@@ -37,7 +37,7 @@ export function buildRegex(elements: RegexElement | RegexElement[]): RegExp;
  */
 export function buildRegex(
   flags: RegexFlags,
-  elements: RegexElement | RegexElement[]
+  elements: RegexNode | RegexNode[]
 ): RegExp;
 
 export function buildRegex(first: any, second?: any): RegExp {
@@ -46,9 +46,9 @@ export function buildRegex(first: any, second?: any): RegExp {
 
 export function _buildRegex(
   flags: RegexFlags,
-  elements: RegexElement | RegexElement[]
+  elements: RegexNode | RegexNode[]
 ): RegExp {
-  const pattern = encodeSequence(asElementArray(elements)).pattern;
+  const pattern = encodeSequence(asNodeArray(elements)).pattern;
   const flagsString = encodeFlags(flags ?? {});
   return new RegExp(pattern, flagsString);
 }
@@ -58,8 +58,8 @@ export function _buildRegex(
  * @param elements Single regex element or array of elements
  * @returns regex pattern string
  */
-export function buildPattern(elements: RegexElement | RegexElement[]): string {
-  return encodeSequence(asElementArray(elements)).pattern;
+export function buildPattern(elements: RegexNode | RegexNode[]): string {
+  return encodeSequence(asNodeArray(elements)).pattern;
 }
 
 function encodeFlags(flags: RegexFlags): string {

src/components/__tests__/character-class.test.ts

@@ -5,11 +5,11 @@ import {
   characterClass,
   characterRange,
   digit,
-  encodeCharacterClass,
   inverted,
   whitespace,
   word,
 } from '../character-class';
+import { buildRegex } from '../../builders';
 
 test('`any` character class', () => {
   expect(any).toHavePattern('.');
@@ -64,7 +64,7 @@ test('`characterRange` base cases', () => {
 
 test('`characterRange` throws on incorrect arguments', () => {
   expect(() => characterRange('z', 'a')).toThrowErrorMatchingInlineSnapshot(
-    `"\`start\` should be less or equal to \`end\`"`
+    `"\`start\` should be before or equal to \`end\`"`
   );
   expect(() => characterRange('aa', 'z')).toThrowErrorMatchingInlineSnapshot(
     `"\`characterRange\` should receive only single character \`start\` string"`
@@ -119,12 +119,15 @@ test('`inverted` character class execution', () => {
 
 test('`encodeCharacterClass` throws on empty text', () => {
   expect(() =>
-    encodeCharacterClass({
-      type: 'characterClass',
-      characters: [],
-      ranges: [],
-      isInverted: false,
-    })
+    buildRegex(
+      // @ts-expect-error
+      inverted({
+        type: 'characterClass',
+        characters: [],
+        ranges: [],
+        isInverted: false,
+      })
+    )
   ).toThrowErrorMatchingInlineSnapshot(
     `"Character class should contain at least one character or character range"`
   );

src/components/__tests__/choice-of.test.ts

@@ -38,6 +38,6 @@ test('`choiceOf` using nested regex', () => {
 
 test('`choiceOf` throws on empty options', () => {
   expect(() => choiceOf()).toThrowErrorMatchingInlineSnapshot(
-    `"\`choiceOf\` should receive at least one option"`
+    `"\`choiceOf\` should receive at least one alternative"`
   );
 });

src/components/anchors.ts

@@ -1,19 +1,26 @@
-import { type EncoderNode, EncoderPrecedence } from '../encoder/types';
-import type { Anchor } from './types';
+import type { EncodeOutput } from '../encoder/types';
+import type { RegexElement } from '../types';
+
+export interface Anchor extends RegexElement {
+  type: 'anchor';
+  symbol: string;
+}
 
 export const startOfString: Anchor = {
   type: 'anchor',
   symbol: '^',
+  encode: encodeAnchor,
 };
 
 export const endOfString: Anchor = {
   type: 'anchor',
   symbol: '$',
+  encode: encodeAnchor,
 };
 
-export function encodeAnchor(anchor: Anchor): EncoderNode {
+function encodeAnchor(this: Anchor): EncodeOutput {
   return {
-    precedence: EncoderPrecedence.Sequence,
-    pattern: anchor.symbol,
+    precedence: 'sequence',
+    pattern: this.symbol,
   };
 }

src/components/capture.ts

@@ -1,17 +1,24 @@
-import { type EncoderNode, EncoderPrecedence } from '../encoder/types';
-import { asElementArray } from '../utils/elements';
-import type { Capture, RegexElement } from './types';
+import { encodeSequence } from '../encoder/encoder';
+import type { EncodeOutput } from '../encoder/types';
+import { asNodeArray } from '../utils/nodes';
+import type { RegexElement, RegexNode } from '../types';
 
-export function capture(children: RegexElement | RegexElement[]): Capture {
+export interface Capture extends RegexElement {
+  type: 'capture';
+  children: RegexNode[];
+}
+
+export function capture(nodes: RegexNode | RegexNode[]): Capture {
   return {
     type: 'capture',
-    children: asElementArray(children),
+    children: asNodeArray(nodes),
+    encode: encodeCapture,
   };
 }
 
-export function encodeCapture(node: EncoderNode): EncoderNode {
+function encodeCapture(this: Capture): EncodeOutput {
   return {
-    precedence: EncoderPrecedence.Atom,
-    pattern: `(${node.pattern})`,
+    precedence: 'atom',
+    pattern: `(${encodeSequence(this.children).pattern})`,
   };
 }

src/components/character-class.ts

@@ -1,33 +1,52 @@
-import { type EncoderNode, EncoderPrecedence } from '../encoder/types';
+import type { EncodeOutput } from '../encoder/types';
 import { escapeText } from '../utils/text';
-import type { CharacterClass } from './types';
+
+export interface CharacterClass {
+  type: 'characterClass';
+  characters: string[];
+  ranges: CharacterRange[];
+  isInverted: boolean;
+  encode: () => EncodeOutput;
+}
+
+/**
+ * Character range from start to end (inclusive).
+ */
+export interface CharacterRange {
+  start: string;
+  end: string;
+}
 
 export const any: CharacterClass = {
   type: 'characterClass',
   characters: ['.'],
   ranges: [],
   isInverted: false,
+  encode: encodeCharacterClass,
 };
 
 export const digit: CharacterClass = {
   type: 'characterClass',
   characters: ['\\d'],
   ranges: [],
   isInverted: false,
+  encode: encodeCharacterClass,
 };
 
 export const word: CharacterClass = {
   type: 'characterClass',
   characters: ['\\w'],
   ranges: [],
   isInverted: false,
+  encode: encodeCharacterClass,
 };
 
 export const whitespace: CharacterClass = {
   type: 'characterClass',
   characters: ['\\s'],
   ranges: [],
   isInverted: false,
+  encode: encodeCharacterClass,
 };
 
 export function characterClass(...elements: CharacterClass[]): CharacterClass {
@@ -44,6 +63,7 @@ export function characterClass(...elements: CharacterClass[]): CharacterClass {
     characters: elements.map((c) => c.characters).flat(),
     ranges: elements.map((c) => c.ranges).flat(),
     isInverted: false,
+    encode: encodeCharacterClass,
   };
 }
 
@@ -61,7 +81,7 @@ export function characterRange(start: string, end: string): CharacterClass {
   }
 
   if (start > end) {
-    throw new Error('`start` should be less or equal to `end`');
+    throw new Error('`start` should be before or equal to `end`');
   }
 
   const range = {
@@ -74,6 +94,7 @@ export function characterRange(start: string, end: string): CharacterClass {
     characters: [],
     ranges: [range],
     isInverted: false,
+    encode: encodeCharacterClass,
   };
 }
 
@@ -88,53 +109,51 @@ export function anyOf(characters: string): CharacterClass {
     characters: charactersArray,
     ranges: [],
     isInverted: false,
+    encode: encodeCharacterClass,
   };
 }
 
-export function inverted({
-  characters,
-  ranges,
-  isInverted,
-}: CharacterClass): CharacterClass {
+export function inverted(element: CharacterClass): CharacterClass {
   return {
     type: 'characterClass',
-    characters: characters,
-    ranges: ranges,
-    isInverted: !isInverted,
+    characters: element.characters,
+    ranges: element.ranges,
+    isInverted: !element.isInverted,
+    encode: encodeCharacterClass,
   };
 }
 
-export function encodeCharacterClass({
-  characters,
-  ranges,
-  isInverted,
-}: CharacterClass): EncoderNode {
-  if (characters.length === 0 && ranges.length === 0) {
+function encodeCharacterClass(this: CharacterClass): EncodeOutput {
+  if (this.characters.length === 0 && this.ranges.length === 0) {
     throw new Error(
       'Character class should contain at least one character or character range'
     );
   }
 
   // Direct rendering for single-character class
-  if (characters.length === 1 && ranges?.length === 0 && !isInverted) {
+  if (
+    this.characters.length === 1 &&
+    this.ranges?.length === 0 &&
+    !this.isInverted
+  ) {
     return {
-      precedence: EncoderPrecedence.Atom,
-      pattern: characters[0]!,
+      precedence: 'atom',
+      pattern: this.characters[0]!,
     };
   }
 
   // If passed characters includes hyphen (`-`) it need to be moved to
   // first (or last) place in order to treat it as hyphen character and not a range.
   // See: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Character_classes#types
-  const hyphenString = characters.includes('-') ? '-' : '';
-  const charactersString = characters.filter((c) => c !== '-').join('');
-  const rangesString = ranges
+  const hyphen = this.characters.includes('-') ? '-' : '';
+  const otherCharacters = this.characters.filter((c) => c !== '-').join('');
+  const ranges = this.ranges
     .map(({ start, end }) => `${start}-${end}`)
     .join('');
-  const invertedString = isInverted ? '^' : '';
+  const isInverted = this.isInverted ? '^' : '';
 
   return {
-    precedence: EncoderPrecedence.Atom,
-    pattern: `[${invertedString}${hyphenString}${rangesString}${charactersString}]`,
+    precedence: 'atom',
+    pattern: `[${isInverted}${hyphen}${ranges}${otherCharacters}]`,
   };
 }

src/components/choice-of.ts

@@ -1,35 +1,35 @@
-import {
-  type EncoderNode,
-  EncoderPrecedence,
-  type EncodeSequence,
-} from '../encoder/types';
-import { asElementArray } from '../utils/elements';
-import type { ChoiceOf, RegexElement } from './types';
+import { encodeSequence } from '../encoder/encoder';
+import type { EncodeOutput } from '../encoder/types';
+import { asNodeArray } from '../utils/nodes';
+import type { RegexElement, RegexNode } from '../types';
+
+export interface ChoiceOf extends RegexElement {
+  type: 'choiceOf';
+  alternatives: RegexNode[][];
+}
 
 export function choiceOf(
-  ...children: Array<RegexElement | RegexElement[]>
+  ...alternatives: Array<RegexNode | RegexNode[]>
 ): ChoiceOf {
-  if (children.length === 0) {
-    throw new Error('`choiceOf` should receive at least one option');
+  if (alternatives.length === 0) {
+    throw new Error('`choiceOf` should receive at least one alternative');
   }
 
   return {
     type: 'choiceOf',
-    children: children.map((c) => asElementArray(c)),
+    alternatives: alternatives.map((c) => asNodeArray(c)),
+    encode: encodeChoiceOf,
   };
 }
 
-export function encodeChoiceOf(
-  element: ChoiceOf,
-  encodeSequence: EncodeSequence
-): EncoderNode {
-  const encodedNodes = element.children.map((c) => encodeSequence(c));
-  if (encodedNodes.length === 1) {
-    return encodedNodes[0]!;
+function encodeChoiceOf(this: ChoiceOf): EncodeOutput {
+  const encodedAlternatives = this.alternatives.map((c) => encodeSequence(c));
+  if (encodedAlternatives.length === 1) {
+    return encodedAlternatives[0]!;
   }
 
   return {
-    precedence: EncoderPrecedence.Alternation,
-    pattern: encodedNodes.map((n) => n.pattern).join('|'),
+    precedence: 'alternation',
+    pattern: encodedAlternatives.map((n) => n.pattern).join('|'),
   };
 }