Skip to content

Commit 1bf8bb4

Browse files
didavid61202didavid61202
authored
feat: experimental type-level RegExp match (#288)
1 parent 0ff5bcf commit 1bf8bb4

File tree

13 files changed

+507
-30
lines changed

13 files changed

+507
-30
lines changed

‎build.config.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@ import { defineBuildConfig } from 'unbuild'
22
export default defineBuildConfig({
33
declaration: true,
44
rollup: { emitCJS: true },
5-
entries: ['./src/index', './src/transform'],
6-
externals: ['magic-regexp'],
5+
entries: ['./src/index', './src/transform', './src/further-magic'],
6+
externals: ['magic-regexp', 'type-level-regexp'],
77
})

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

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ There are a range of helpers that can be used to activate pattern matching, and
5656
| `exactly` | This takes a variable number of inputs and concatenate their patterns, and escapes string inputs to match it exactly. |
5757

5858
::alert
59-
All helpers that takes `string` and `Input` are variadic functions, so you can pass in one or multiple arguments of `string` or `Input` to them and they will be concatenated to one pattern. for example,s `exactly('foo', maybe('bar'))` is equivalent to `exactly('foo').and(maybe('bar'))`.
59+
All helpers that takes `string` and `Input` are variadic functions, so you can pass in one or multiple arguments of `string` or `Input` to them and they will be concatenated to one pattern. for example, `exactly('foo', maybe('bar'))` is equivalent to `exactly('foo').and(maybe('bar'))`.
6060
::
6161

6262
## Chaining inputs
@@ -100,3 +100,28 @@ exactly('test.mjs').or('something.else')
100100
Each function, if you hover over it, shows what's going in, and what's coming out by way of regular expression
101101

102102
You can also call `.toString()` on any input to see the same information at runtime.
103+
104+
## Type-Level match result (experimental)
105+
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 a subpath export `magic-regexp/further-magic` instead of `magic-regexp`.
106+
107+
```ts
108+
import { createRegExp, exactly, digit } from 'magic-regexp/further-magic'
109+
```
110+
111+
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.
112+
113+
This feature works best for matching literal strings such as
114+
```ts
115+
'foo'.match(createRegExp(exactly('foo').groupedAs('g1')))
116+
```
117+
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`.
118+
119+
If matching with dynamic string, such as
120+
```ts
121+
myString.match(createRegExp(exactly('foo').or('bar').groupedAs('g1')))
122+
```
123+
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" }`.
124+
125+
::alert
126+
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/further-magic.test.ts). For type-related issues, please report them to [type-level-regexp](https://github.com/didavid61202/type-level-regexp).
127+
::

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

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,81 @@ const TENET_RE = createRegExp(
3434

3535
assert.equal(TENET_RE.test('TEN<==O==>NET'), true)
3636
```
37+
38+
### Type-level RegExp match and replace result (experimental)
39+
40+
::alert
41+
This feature is still experimental, to try it please import `createRegExp ` and all `Input` helpers from `magic-regexp/further-magic` instead of `magic-regexp`.
42+
::
43+
44+
When matching or replacing with literal string such as `magic-regexp v3.2.5.beta.1 just release!`
45+
46+
```ts
47+
import {
48+
createRegExp,
49+
oneOrMore,
50+
exactly,
51+
nyOf,
52+
digit,
53+
wordChar
54+
} from 'magic-regexp/further-magic'
55+
56+
const literalString = 'magic-regexp 3.2.5.beta.1 just release!'
57+
58+
const semverRegExp = createRegExp(
59+
oneOrMore(digit)
60+
.as('major')
61+
.and('.')
62+
.and(oneOrMore(digit).as('minor'))
63+
.and(
64+
exactly('.')
65+
.and(oneOrMore(anyOf(wordChar, '.')).groupedAs('patch'))
66+
.optionally()
67+
)
68+
)
69+
70+
// `String.match()` example
71+
const matchResult = literalString.match(semverRegExp)
72+
matchResult[0] // "3.2.5.beta.1"
73+
matchResult[3] // "5.beta.1"
74+
matchResult.length // 4
75+
matchResult.index // 14
76+
matchResult.groups
77+
// groups: {
78+
// major: "3";
79+
// minor: "2";
80+
// patch: "5.beta.1";
81+
// }
82+
83+
// `String.replace()` example
84+
const replaceResult = literalString.replace(
85+
semverRegExp,
86+
`minor version "$2" brings many great DX improvements, while patch "$<patch>" fix some bugs and it's`
87+
)
88+
89+
replaceResult // "magic-regexp minor version \"2\" brings many great DX improvements, while patch \"5.beta.1\" fix some bugs and it's just release!"
90+
```
91+
92+
When matching dynamic string, the result will be union of possible matches
93+
94+
```ts
95+
let myString = 'dynamic'
96+
97+
const RegExp = createRegExp(exactly('foo').or('bar').groupedAs('g1'))
98+
const matchAllResult = myString.match(RegExp)
99+
100+
matchAllResult
101+
// null | RegExpMatchResult<{
102+
// matched: ["bar", "bar"] | ["foo", "foo"];
103+
// namedCaptures: ["g1", "bar"] | ["g1", "foo"];
104+
// input: string;
105+
// restInput: undefined;
106+
// }>
107+
matchAllResult?.[0] // ['foo', 'foo'] | ['bar', 'bar']
108+
matchAllResult?.length // 2 | undefined
109+
matchAllResult?.groups
110+
// groups: {
111+
// g1: "foo" | "bar";
112+
// } | undefined
113+
```
114+

‎further-magic.d.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
// Legacy stub for previous TS versions
2+
3+
export * from './dist/further-magic'

‎package.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@
1616
"require": "./dist/transform.cjs",
1717
"types": "./dist/transform.d.ts"
1818
},
19+
"./further-magic": {
20+
"import": "./dist/further-magic.mjs",
21+
"require": "./dist/further-magic.cjs",
22+
"types": "./dist/further-magic.d.ts"
23+
},
1924
"./nuxt": "./nuxt.mjs"
2025
},
2126
"main": "./dist/index.cjs",
@@ -24,7 +29,8 @@
2429
"files": [
2530
"dist",
2631
"nuxt.mjs",
27-
"transform.d.ts"
32+
"transform.d.ts",
33+
"further-magic.d.ts"
2834
],
2935
"scripts": {
3036
"build": "unbuild",
@@ -45,6 +51,7 @@
4551
"estree-walker": "^3.0.1",
4652
"magic-string": "^0.30.0",
4753
"mlly": "^1.0.0",
54+
"type-level-regexp": "~0.1.16",
4855
"ufo": "^1.0.0",
4956
"unplugin": "^1.0.0"
5057
},

‎playground/index.mjs‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
import assert from 'node:assert'
2-
import { createRegExp, exactly, digit, oneOrMore, char, wordChar } from 'magic-regexp'
2+
import { createRegExp, exactly, maybe, digit, oneOrMore, char, wordChar } from 'magic-regexp'
3+
/**
4+
* change to
5+
* import {...} from 'magic-regexp/further-magic'
6+
* to try type level RegExp match results (experimental)
7+
*/
38

49
// Typed capture groups
510
const ID_RE = createRegExp(exactly('id-').and(digit.times(5).groupedAs('id')))
@@ -8,22 +13,18 @@ console.log(ID_RE, groups?.id)
813

914
// Quick-and-dirty semver
1015
const SEMVER_RE = createRegExp(
11-
oneOrMore(digit)
12-
.groupedAs('major')
13-
.and('.')
14-
.and(oneOrMore(digit).groupedAs('minor'))
15-
.and(exactly('.').and(oneOrMore(char).groupedAs('patch')).optionally())
16+
oneOrMore(digit).groupedAs('major'),
17+
'.',
18+
oneOrMore(digit).groupedAs('minor'),
19+
maybe('.', oneOrMore(char).groupedAs('patch'))
1620
)
1721
console.log(SEMVER_RE)
1822

1923
assert.equal(createRegExp(exactly('foo/test.js').after('bar/')).test('bar/foo/test.js'), true)
2024

2125
// References to previously captured groups using the group name
2226
const TENET_RE = createRegExp(
23-
wordChar
24-
.groupedAs('firstChar')
25-
.and(wordChar.groupedAs('secondChar'))
26-
.and(oneOrMore(char))
27+
exactly(wordChar.groupedAs('firstChar'), wordChar.groupedAs('secondChar'), oneOrMore(char))
2728
.and.referenceTo('secondChar')
2829
.and.referenceTo('firstChar')
2930
)

‎pnpm-lock.yaml‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/further-magic.ts‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
import type { Flag } from './core/flags'
2+
import type { Join, UnionToTuple } from './core/types/join'
3+
import type { InputSource, MapToGroups, MapToValues } from './core/types/sources'
4+
import type {
5+
MatchRegExp,
6+
MatchAllRegExp,
7+
ParseRegExp,
8+
RegExpMatchResult,
9+
ReplaceWithRegExp,
10+
} from 'type-level-regexp/regexp'
11+
12+
import { exactly } from './core/inputs'
13+
14+
const NamedGroupsS = Symbol('NamedGroupsType')
15+
const ValueS = Symbol('Value')
16+
const FlagsS = Symbol('Flags')
17+
18+
export type MagicRegExp<
19+
Value extends string,
20+
NamedGroups extends string | never = never,
21+
Flags extends Flag[] | never = never
22+
> = RegExp & {
23+
[NamedGroupsS]: NamedGroups
24+
[ValueS]: Value
25+
[FlagsS]: Flags
26+
}
27+
28+
export const createRegExp: {
29+
/** Create Magic RegExp from Input helpers and string (string will be sanitized) */
30+
<Inputs extends InputSource[]>(...inputs: Inputs): MagicRegExp<
31+
`/${Join<MapToValues<Inputs>, '', ''>}/`,
32+
MapToGroups<Inputs>,
33+
[]
34+
>
35+
<
36+
Inputs extends InputSource[],
37+
FlagUnion extends Flag | undefined = undefined,
38+
CloneFlagUnion extends Flag | undefined = FlagUnion,
39+
Flags extends Flag[] = CloneFlagUnion extends undefined
40+
? []
41+
: UnionToTuple<FlagUnion> extends infer F extends Flag[]
42+
? F
43+
: never
44+
>(
45+
...inputs: [...Inputs, [...Flags] | string | Set<FlagUnion>]
46+
): MagicRegExp<
47+
`/${Join<MapToValues<Inputs>, '', ''>}/${Join<Flags, '', ''>}`,
48+
MapToGroups<Inputs>,
49+
Flags
50+
>
51+
} = (...inputs: any[]) => {
52+
const flags =
53+
inputs.length > 1 &&
54+
(Array.isArray(inputs[inputs.length - 1]) || inputs[inputs.length - 1] instanceof Set)
55+
? inputs.pop()
56+
: undefined
57+
return new RegExp(exactly(...inputs).toString(), [...(flags || '')].join('')) as any
58+
}
59+
60+
export * from './core/flags'
61+
export * from './core/inputs'
62+
export * from './core/types/magic-regexp'
63+
export { spreadRegExpIterator, spreadRegExpMatchArray } from 'type-level-regexp/regexp'
64+
65+
// Add additional overload to global String object types to allow for typed capturing groups
66+
declare global {
67+
interface String {
68+
match<InputString extends string, RegExpPattern extends string, Flags extends Flag[]>(
69+
this: InputString,
70+
regexp: MagicRegExp<`/${RegExpPattern}/${Join<Flags, '', ''>}`, string, Flags>
71+
): MatchRegExp<
72+
InputString,
73+
ParseRegExp<RegExpPattern>,
74+
Flag[] extends Flags ? never : Flags[number]
75+
>
76+
77+
/** @deprecated String.matchAll requires global flag to be set. */
78+
matchAll<R extends MagicRegExp<string, string, Exclude<Flag, 'g'>[]>>(regexp: R): never
79+
80+
matchAll<InputString extends string, RegExpPattern extends string, Flags extends Flag[]>(
81+
this: InputString,
82+
regexp: MagicRegExp<`/${RegExpPattern}/${Join<Flags, '', ''>}`, string, Flags>
83+
): MatchAllRegExp<
84+
InputString,
85+
ParseRegExp<RegExpPattern>,
86+
Flag[] extends Flags ? never : Flags[number]
87+
>
88+
89+
/** @deprecated String.matchAll requires global flag to be set. */
90+
matchAll<R extends MagicRegExp<string, string, never>>(regexp: R): never
91+
92+
replace<
93+
InputString extends string,
94+
RegExpPattern extends string,
95+
Flags extends Flag[],
96+
ReplaceValue extends string,
97+
RegExpParsedAST extends any[] = string extends RegExpPattern
98+
? never
99+
: ParseRegExp<RegExpPattern>,
100+
MatchResult = MatchRegExp<InputString, RegExpParsedAST, Flags[number]>,
101+
Match extends any[] = MatchResult extends RegExpMatchResult<
102+
{
103+
matched: infer MatchArray extends any[]
104+
namedCaptures: [string, any]
105+
input: infer Input extends string
106+
restInput: string | undefined
107+
},
108+
{
109+
index: infer Index extends number
110+
groups: infer Groups
111+
input: string
112+
keys: (...arg: any) => any
113+
}
114+
>
115+
? [...MatchArray, Index, Input, Groups]
116+
: never
117+
>(
118+
this: InputString,
119+
regexp: MagicRegExp<`/${RegExpPattern}/${Join<Flags, '', ''>}`, string, Flags>,
120+
replaceValue: ReplaceValue | ((...match: Match) => ReplaceValue)
121+
): any[] extends RegExpParsedAST
122+
? never
123+
: ReplaceWithRegExp<InputString, RegExpParsedAST, ReplaceValue, Flags[number]>
124+
125+
/** @deprecated String.replaceAll requires global flag to be set. */
126+
replaceAll<R extends MagicRegExp<string, string, never>>(
127+
searchValue: R,
128+
replaceValue: string | ((substring: string, ...args: any[]) => string)
129+
): never
130+
/** @deprecated String.replaceAll requires global flag to be set. */
131+
replaceAll<R extends MagicRegExp<string, string, Exclude<Flag, 'g'>[]>>(
132+
searchValue: R,
133+
replaceValue: string | ((substring: string, ...args: any[]) => string)
134+
): never
135+
}
136+
}

‎src/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import type { MagicRegExp, MagicRegExpMatchArray } from './core/types/magic-rege
66
import { InputSource, MapToCapturedGroupsArr, MapToGroups, MapToValues } from './core/types/sources'
77

88
export const createRegExp: {
9-
/** Create Magic RegExp from Input helpers and strin (string will be sanitized) */
9+
/** Create Magic RegExp from Input helpers and string (string will be sanitized) */
1010
<Inputs extends InputSource[]>(...inputs: Inputs): MagicRegExp<
1111
`/${Join<MapToValues<Inputs>, '', ''>}/`,
1212
MapToGroups<Inputs>,

‎src/transform.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,9 @@ export const MagicRegExpTransformPlugin = createUnplugin(() => {
3434
transform(code, id) {
3535
if (!code.includes('magic-regexp')) return
3636

37-
const statements = findStaticImports(code).filter(i => i.specifier === 'magic-regexp')
37+
const statements = findStaticImports(code).filter(
38+
i => i.specifier === 'magic-regexp' || i.specifier === 'magic-regexp/further-magic'
39+
)
3840
if (!statements.length) return
3941

4042
const contextMap: Context = { ...magicRegExp }

0 commit comments

Comments
 (0)