update docs

docs/content/2.getting-started/2.usage.md

@@ -86,3 +86,28 @@ exactly('test.mjs').or('something.else')
 Each function, if you hover over it, shows what's going in, and what's coming out by way of regular expression
 
 You can also call `.toString()` on any input to see the same information at runtime.
+
+## Type-Level match result (experimental)
+We also provide an experimental feature that allows you to obtain the type-level results of a RegExp match or replace in string literals. To try this feature, please import all helpers from `magic-regexp/type-level-regexp` instead of `magic-regexp`.
+
+```ts
+import { createRegExp, exactly, digit } from 'magic-regexp/type-level-regexp'
+```
+
+This feature is especially useful when you want to obtain the type of the matched groups or test if your RegExp matches and captures from a given string as expected.
+
+This feature works best for matching literal strings such as
+```ts
+'foo'.match(createRegExp(exactly('foo').groupedAs('g1')))
+```
+which will return a matched result of type `['foo', 'foo']`. `result.groups` of type `{ g1: 'foo' }`, `result.index` of type `0` and `result.length` of type `2`.
+
+If matching with dynamic string, such as 
+```ts
+myString.match(createRegExp(exactly('foo').or('bar').groupedAs('g1')))
+```
+the type of the matched result will be `null`, or array of union of possible matches `["bar", "bar"] | ["foo", "foo"]` and `result.groups` will be type `{ g1: "bar" } | { g1: "foo" }`.
+
+::alert
+For more usage details please see the [usage examples](3.examples.md#type-level-regexp-match-and-replace-result-experimental) or [test](https://github.com/danielroe/magic-regexp/blob/main/test/type-level-regexp.test.ts). For type-related issues, please report them to [type-level-regexp](https://github.com/didavid61202/type-level-regexp).
+::

docs/content/2.getting-started/3.examples.md

@@ -35,3 +35,81 @@ const TENET_RE = createRegExp(
 
 assert.equal(TENET_RE.test('TEN<==O==>NET'), true)
 ```
+
+### Type-level RegExp match and replace result (experimental)
+
+::alert
+This feature is still experimental, to try it please import `createRegExp ` and all `Input` helpers from `magic-regexp/type-level-regexp` instead of `magic-regexp`.
+::
+
+When matching or replacing with literal string such as `magic-regexp v3.2.5.beta.1 just release!`
+
+```ts
+import { 
+  createRegExp, 
+  oneOrMore, 
+  exactly, 
+  nyOf, 
+  digit, 
+  wordChar 
+} from 'magic-regexp/type-level-regexp'
+
+const literalString = 'magic-regexp 3.2.5.beta.1 just release!'
+
+const semverRegExp = createRegExp(
+  oneOrMore(digit)
+    .as('major')
+    .and('.')
+    .and(oneOrMore(digit).as('minor'))
+    .and(
+      exactly('.')
+        .and(oneOrMore(anyOf(wordChar, '.')).groupedAs('patch'))
+        .optionally()
+    )
+)
+
+// `String.match()` example
+const matchResult = literalString.match(semverRegExp)
+matchResult[0] // "3.2.5.beta.1"
+matchResult[3] // "5.beta.1"
+matchResult.length // 4
+matchResult.index // 14
+matchResult.groups
+//   groups: {
+//     major: "3";
+//     minor: "2";
+//     patch: "5.beta.1";
+//  }
+
+// `String.replace()` example
+const replaceResult = literalString.replace(
+    semverRegExp,
+    `minor version "$2" brings many great DX improvements, while patch "$<patch>" fix some bugs and it's`
+  )
+
+replaceResult // "magic-regexp minor version \"2\" brings many great DX improvements, while patch \"5.beta.1\" fix some bugs and it's just release!"
+```
+
+When matching dynamic string, the result will be union of possible matches
+
+```ts
+let myString = 'dynamic'
+
+const RegExp = createRegExp(exactly('foo').or('bar').groupedAs('g1'))
+const matchAllResult = myString.match(RegExp)
+
+matchAllResult
+// null | RegExpMatchResult<{
+//     matched: ["bar", "bar"] | ["foo", "foo"];
+//     namedCaptures: ["g1", "bar"] | ["g1", "foo"];
+//     input: string;
+//     restInput: undefined;
+// }> 
+matchAllResult?.[0] // ['foo', 'foo'] | ['bar', 'bar']
+matchAllResult?.length // 2 | undefined
+matchAllResult?.groups
+// groups: {
+//     g1: "foo" | "bar";
+// } | undefined
+```
+