docs: proof-read docs (#50)

Author: mdjastrzebski

README.md

@@ -6,9 +6,9 @@ A user-friendly regular expression builder for TypeScript and JavaScript.
 
 ## Goal
 
-Regular expressions are a powerful tool for matching simple and complex text patterns, yet they are notorious for their hard-to-parse syntax.
+Regular expressions are a powerful tool for matching text patterns, yet they are notorious for their hard-to-parse syntax, especially in the case of more complex patterns.
 
-This library allows users to create regular expressions in a structured way, making them ease to understand.
+This library allows users to create regular expressions in a structured way, making them easy to write and review. It provides a domain-specific langauge for defining regular expressions, which are finally turned into JavaScript-native `RegExp` objects for fast execution.
 
 ```ts
 // Before
@@ -61,8 +61,8 @@ TS Regex Builder allows you to build complex regular expressions using domain-sp
 
 Terminology:
 - regex construct (`RegexConstruct`) - common name for all regex constructs like character classes, quantifiers, and anchors.
-- regex element (`RegexElement`) - fundamental building block of a regular expression, defined as either a regex construct or a string.
-- regex sequence (`RegexSequence`) - a sequence of regex elements forming a regular expression. For developer convenience it also accepts a single element instead of array.
+- regex element (`RegexElement`) - a fundamental building block of a regular expression, defined as either a regex construct or a string.
+- regex sequence (`RegexSequence`) - a sequence of regex elements forming a regular expression. For developer convenience, it also accepts a single element instead of an array.
 
 Most of the regex constructs accept a regex sequence as their argument.
 
@@ -87,7 +87,7 @@ const currencyAmount = buildRegExp([
 ]);
 ```
 
-Comprehensive API document is available [here](./API.md).
+See [API document](./docs/API.md).
 
 ### Regex Builders
 
@@ -129,15 +129,19 @@ Comprehensive API document is available [here](./API.md).
 
 ### Anchors
 
-| Anchor          | Regex Syntax  | Description                                                      |
-| --------------- | ------------- | ---------------------------------------------------------------- |
-| `startOfString` | `^`           | Match start of the string (or start of a line in multiline mode) |
-| `endOfString`   | `$`           | Match end of the string (or end of a line in multiline mode)     |
+| Anchor          | Regex Syntax  | Description                                                              |
+| --------------- | ------------- | ------------------------------------------------------------------------ |
+| `startOfString` | `^`           | Match the start of the string (or the start of a line in multiline mode) |
+| `endOfString`   | `$`           | Match the end of the string (or the end of a line in multiline mode)     |
 
 ## Examples
 
 See [Examples document](./docs/Examples.md).
 
+## Performance
+
+Regular expressions created with this library are executed at runtime, so you should avoid creating them in a context where they would need to be executed multiple times, e.g., inside loops or functions. We recommend that you create a top-level object for each required regex.
+
 ## Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.

docs/API.md

@@ -4,7 +4,7 @@
 
 ### `RegexSequence`
 
-The sequence of regex elements forming a regular expression. For developer convenience it also accepts a single element instead of array.
+The sequence of regex elements forming a regular expression. For developer convenience, it also accepts a single element instead of an array.
 
 ### `RegexElement`
 
@@ -14,7 +14,7 @@ Fundamental building blocks of a regular expression, defined as either a regex c
 
 The common type for all regex constructs like character classes, quantifiers, and anchors. You should not need to use this type directly, it is returned by all regex construct functions.
 
-Note: the shape of the `RegexConstruct` is considered private, and may change in a breaking way without a major release. We will focus on maintaining the compatibility of regexes built with 
+Note: the shape of the `RegexConstruct` is considered private and may change in a breaking way without a major release. We will focus on maintaining the compatibility of regexes built with 
 
 
 ## Builder
@@ -33,14 +33,14 @@ function buildRegExp(
 ): RegExp;
 ```
 
-The `buildRegExp` is a top-level function responsible for build JavaScript-native `RegExp` object from passed regex sequence.
+The `buildRegExp` is a top-level function responsible for building a JavaScript-native `RegExp` object from passed regex sequence.
 
 It optionally accepts a list of regex flags:
 
-- `global` - find all matches in a string, instead of just the first one.
+- `global` - find all matches in a string instead of just the first one.
 - `ignoreCase` - perform case-insensitive matching.
 - `multiline` - treat the start and end of each line in a string as the beginning and end of the string.
-- `hasIndices` - provide the start and end indices of each captured group in a match.
+- `hasIndices` - provide each captured group's start and end indices in a match.
 
 ## Constructs
 
@@ -56,7 +56,7 @@ function capture(
 
 Regex syntax: `(...)`.
 
-Captures, also known as capturing groups, are used to extract and store parts of the matched string for later use.
+Captures, also known as capturing groups, extract and store parts of the matched string for later use.
 
 ### `choiceOf()`
 
@@ -68,7 +68,7 @@ function choiceOf(
 
 Regex syntax: `a|b|c`.
 
-The `choiceOf` (disjunction) construct is used to match one out of several possible sequences. It functions similarly to a logical OR operator in programming. It can match simple string options as well as complex patterns.
+The `choiceOf` (disjunction) construct matches one out of several possible sequences. It functions similarly to a logical OR operator in programming. It can match simple string options as well as complex patterns.
 
 Example: `choiceOf("color", "colour")` matches either `color` or `colour` pattern.
 
@@ -86,7 +86,7 @@ function zeroOrMore(
 
 Regex syntax: `x*`;
 
-The `zeroOrMore` quantifier matches zero or more occurrences of given pattern, allowing a flexible number of repetitions of that element.
+The `zeroOrMore` quantifier matches zero or more occurrences of a given pattern, allowing a flexible number of repetitions of that element.
 
 ### `oneOrMore()`
 
@@ -98,7 +98,7 @@ function oneOrMore(
 
 Regex syntax: `x+`;
 
-The `oneOrMore` quantifier matches one or more occurrences of given pattern, allowing a flexible number of repetitions of that element.
+The `oneOrMore` quantifier matches one or more occurrences of a given pattern, allowing a flexible number of repetitions of that element.
 
 ### `optional()`
 
@@ -110,7 +110,7 @@ function optional(
 
 Regex syntax: `x?`;
 
-The `optional` quantifier matches zero or one occurrence of given pattern, making it optional.
+The `optional` quantifier matches zero or one occurrence of a given pattern, making it optional.
 
 ### `repeat()`
 
@@ -123,13 +123,13 @@ function repeat(
 
 Regex syntax: `x{n}`, `x{min,}`, `x{min, max}`.
 
-The `repeat` quantifier in regex matches either exactly `count` times or between `min` and `max` times. If only `min` is provided it matches at least `min` times.
+The `repeat` quantifier in regex matches either exactly `count` times or between `min` and `max` times. If only `min` is provided, it matches at least `min` times.
 
 ## Character classes
 
 Character classes are a set of characters that match any one of the characters in the set.
 
-### Common character classess
+### Common character classes
 
 ```ts
 const any: CharacterClass;
@@ -153,7 +153,7 @@ function anyOf(
 
 Regex syntax: `[abc]`.
 
-The `anyOf` class matches any character present in the `character` string.
+The `anyOf` class matches any character in the `character` string.
 
 Example: `anyOf('aeiou')` will match either `a`, `e`, `i` `o` or `u` characters.
 
@@ -168,7 +168,7 @@ function charRange(
 
 Regex syntax: `[a-z]`.
 
-The `charRange` class matches any character present in the range from `start` to `end` (inclusive).
+The `charRange` class matches any characters in the range from `start` to `end` (inclusive).
 
 Examples:
 
@@ -191,7 +191,7 @@ The `charClass` construct creates a new character class that includes all passed
 Examples:
 
 - `charClass(charRange('a', 'f'), digit)` will match all lowercase hex digits (`0` to `9` and `a` to `f`).
-- `charClass(charRange('a', 'z'), digit, anyOf("._-"))` will match any digit, lowercase latin lettet from `a` to `z`, and either of `.`, `_`, and `-` characters.
+- `charClass(charRange('a', 'z'), digit, anyOf("._-"))` will match any digit, lowercase Latin letter from `a` to `z`, and either of `.`, `_`, and `-` characters.
 
 ### `inverted()`
 
@@ -203,7 +203,7 @@ function inverted(
 
 Regex syntax: `[^...]`.
 
-The `inverted` construct creates a new character class that matches any character that is not present in the passed character class.
+The `inverted` construct creates a new character class that matches any character not present in the passed character class.
 
 Examples:
 
@@ -212,7 +212,7 @@ Examples:
 
 ## Anchors
 
-Anchors are special characters or sequences that specify positions in the input string, rather than matching specific characters.
+Anchors are special characters or sequences that specify positions in the input string rather than matching specific characters.
 
 ### Start and end of string
 

docs/Examples.md

@@ -22,7 +22,7 @@ See tests: [example-hashtags.ts](../src/__tests__/example-hashtags.ts).
 
 ## Hex color validation
 
-This regex validate whether given string is a valid hex color, with 6 or 3 hex digits.
+This regex validates whether a given string is a valid hex color, with 6 or 3 hex digits.
 
 ```ts
 const hexDigit = charClass(digit, charRange('a', 'f'));
@@ -47,7 +47,7 @@ See tests: [example-hex-color.ts](../src/__tests__/example-hex-color.ts).
 
 ## Simple URL validation
 
-This regex validates (in simplified way) whether given string is a URL.
+This regex validates (in a simplified way) whether a given string is a URL.
 
 ```ts
 const protocol = [choiceOf('http', 'https'), '://'];
@@ -75,7 +75,7 @@ See tests: [example-url.ts](../src/__tests__/example-url.ts).
 
 ## Email address validation
 
-This regex validates whether given string is a properly formatted email address.
+This regex validates whether a given string is a properly formatted email address.
 
 ```ts
 const hostnameChars = charClass(charRange('a', 'z'), digit, anyOf('-.'));
@@ -103,7 +103,7 @@ See tests: [example-email.ts](../src/__tests__/example-email.ts).
 
 ## JavaScript number validation
 
-This regex validates if given string is a valid JavaScript number.
+This regex validates if a given string is a valid JavaScript number.
 
 
 ```ts