@mpen/rerouter 0.1.9 → 0.3.0

package/src/bin.ts

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { parseArgs, type ParseArgsConfig } from 'node:util'
+import { parse } from 'path-to-regexp'
+import { normalizeLegacyPathToRegexpSyntax, normalizeRoutes, type Route } from './lib/routes'
+
+const PARSE_CONFIG = {
+    options: {
+        output: { type: 'string', short: 'o' },
+        write: { type: 'boolean', short: 'w' },
+        'wildcard-delimiter': { type: 'string' },
+        'encode-function': { type: 'string' },
+    },
+    allowPositionals: true,
+    strict: true,
+} satisfies ParseArgsConfig
+
+type CompileOptions = {
+    delimiter?: string
+    encode?: string
+    functionName?: string
+}
+
+type RunOptions = {
+    cwd?: string
+    commandName?: string
+    commandArgs?: readonly string[]
+}
+
+type RunResult = {
+    exitCode?: number
+    stdout: string
+    stderr: string
+}
+
+function escapeString(value: string): string {
+    return JSON.stringify(value)
+}
+
+function shellEscape(arg: string): string {
+    if (/^[a-z0-9/_.-]+$/i.test(arg)) return arg
+    return `'${arg.replace(/'/g, "'\\''")}'`
+}
+
+function compilePathGenerator(
+    pattern: string,
+    {
+        delimiter = '/',
+        encode = 'encodeURIComponent',
+        functionName = 'generate',
+    }: CompileOptions = {},
+): string {
+    const { tokens } = parse(normalizeLegacyPathToRegexpSyntax(pattern))
+
+    type Prop = { name: string; type: string }
+
+    const baseProps: Prop[] = []
+    const groupTypes: string[] = []
+
+    const typeOfParam = (t: any) => (t.type === 'wildcard' ? 'WildcardType' : 'ParamType')
+    const makeProp = (name: string, t: any): Prop => ({ name, type: typeOfParam(t) })
+
+    function collectGroupProps(ts2: any[]): Prop[] {
+        const props: Prop[] = []
+        for (const t of ts2) {
+            if (t.type === 'param' || t.type === 'wildcard') props.push(makeProp(t.name, t))
+            else if (t.type === 'group') props.push(...collectGroupProps(t.tokens))
+        }
+        return props
+    }
+
+    function collectTypes(ts2: any[], intoBase = true) {
+        for (const t of ts2) {
+            if ((t.type === 'param' || t.type === 'wildcard') && intoBase) {
+                baseProps.push(makeProp(t.name, t))
+            } else if (t.type === 'group') {
+                const groupProps = collectGroupProps(t.tokens)
+                if (groupProps.length) {
+                    const some = [
+                        '{',
+                        ...groupProps.map((p) => `    ${escapeString(p.name)}: ${p.type}`),
+                        '}',
+                    ].join('\n')
+                    groupTypes.push(`AllOrNone<${some}>`)
+                }
+                collectTypes(t.tokens, false)
+            }
+        }
+    }
+
+    collectTypes(tokens)
+
+    const baseParamsType = [
+        '{',
+        ...baseProps.map((p) => `    ${escapeString(p.name)}: ${p.type}`),
+        '}',
+    ].join('\n')
+    const paramsType = groupTypes.length
+        ? `${baseParamsType} & ${groupTypes.join(' & ')}`
+        : baseParamsType
+
+    const lines: string[] = []
+    const indentUnit = '    '
+    const line = (indentLevel: number, text = ''): void => {
+        if (text === '') lines.push('')
+        else lines.push(indentUnit.repeat(indentLevel) + text)
+    }
+    const hasAnyParams = baseProps.length > 0 || groupTypes.length > 0
+
+    if (hasAnyParams) {
+        lines.push(`export function ${functionName}(`)
+        lines.push(`    params: ${paramsType}`)
+        lines.push(`): string {`)
+    } else {
+        lines.push(`export function ${functionName}(): string {`)
+    }
+    line(1, `let sb = ""`)
+    line(0)
+
+    const delim = escapeString(delimiter)
+
+    function collectNames(ts2: any[]): string[] {
+        const names: string[] = []
+        for (const t of ts2) {
+            if (t.type === 'param' || t.type === 'wildcard') names.push(t.name)
+            else if (t.type === 'group') names.push(...collectNames(t.tokens))
+        }
+        return names
+    }
+
+    function emitTokens(ts2: any[], indentLevel: number, optional = false): void {
+        if (!optional && hasAnyParams) {
+            for (const t of ts2) {
+                if (t.type === 'param' || t.type === 'wildcard') {
+                    line(
+                        indentLevel,
+                        `if (params[${escapeString(t.name)}] == null) throw new Error(${escapeString(`Missing param: ${t.name}`)})`,
+                    )
+                }
+            }
+        }
+
+        for (const t of ts2) {
+            if (t.type === 'text') {
+                line(indentLevel, `sb += ${escapeString(t.value)}`)
+            } else if (t.type === 'param') {
+                line(indentLevel, `sb += (${encode})(String(params[${escapeString(t.name)}]))`)
+            } else if (t.type === 'wildcard') {
+                line(
+                    indentLevel,
+                    `sb += Array.from(params[${escapeString(t.name)}], v => (${encode})(String(v))).join(${delim})`,
+                )
+            } else if (t.type === 'group') {
+                const names = collectNames(t.tokens).map((name) => escapeString(name))
+                if (!names.length) continue
+                const all = names.map((n) => `params[${n}] != null`).join(' && ')
+                const none = names.map((n) => `params[${n}] == null`).join(' && ')
+                const list = names.join(', ')
+
+                line(indentLevel, `if (${all}) {`)
+                emitTokens(t.tokens, indentLevel + 1, true)
+                line(indentLevel, `} else if (!(${none})) {`)
+                line(
+                    indentLevel + 1,
+                    `throw new Error(${escapeString(`Group requires all-or-none: ${list}`)})`,
+                )
+                line(indentLevel, `}`)
+            }
+        }
+    }
+
+    emitTokens(tokens, 1)
+    line(0)
+    line(1, `return sb`)
+    lines.push(`}`)
+    return lines.join('\n')
+}
+
+function toRouteFunctionName(routeName: string): string {
+    const ident = routeName
+        .trim()
+        .replace(/[^a-zA-Z0-9_]/g, '_')
+        .replace(/^[^a-zA-Z_]+/, '')
+    return ident || 'route'
+}
+
+type ExtractedRoute = { name: string; pattern: string }
+
+async function importRoutes(routesPath: string): Promise<readonly Route[]> {
+    const mod = (await import(pathToFileURL(routesPath).href)) as { default?: unknown }
+    if (!Array.isArray(mod.default)) {
+        throw new Error('Routes file must default export an array of routes.')
+    }
+    return mod.default as readonly Route[]
+}
+
+function extractRoutes(routes: readonly Route[]): ExtractedRoute[] {
+    return normalizeRoutes(routes).flatMap((route) => {
+        if (!route.name || typeof route.pattern !== 'string') return []
+        return [{ name: route.name, pattern: route.pattern }]
+    })
+}
+
+async function main(
+    options: Options,
+    positionals: Positionals,
+    {
+        cwd = process.cwd(),
+        commandName = 'rerouter',
+        commandArgs = process.argv.slice(2),
+    }: RunOptions = {},
+): Promise<RunResult> {
+    const [routesPathArg] = positionals
+    if (!routesPathArg) {
+        return {
+            exitCode: 1,
+            stdout: '',
+            stderr: 'Usage: rerouter <routes-file> [-o <output-file>] [-w] [--wildcard-delimiter <string>] [--encode-function <identifier>]\n',
+        }
+    }
+
+    const routesPath = path.resolve(cwd, routesPathArg)
+    let outputPath: string | undefined
+    if (options.output) {
+        outputPath = path.resolve(cwd, options.output as string)
+    } else if (options.write) {
+        outputPath = path.join(
+            path.dirname(routesPath),
+            path.basename(routesPath, path.extname(routesPath)) + '.gen.ts',
+        )
+    }
+
+    const routes = extractRoutes(await importRoutes(routesPath))
+        .map((r) => ({ ...r, pattern: r.pattern.trim() }))
+        .filter((r) => r.pattern.startsWith('/') && r.pattern !== '*')
+
+    const wildcardDelimiter = (options['wildcard-delimiter'] as string | undefined) ?? '/'
+    const encodeFunction =
+        (options['encode-function'] as string | undefined) ?? 'encodeURIComponent'
+
+    const commandText = [commandName, ...commandArgs.map(shellEscape)].join(' ')
+
+    const out: string[] = []
+    out.push(`// Do not modify this file. It was auto-generated with the following command:`)
+    out.push(`// $ ${commandText}`)
+    out.push(``)
+    out.push(`type AllOrNone<T> =`)
+    out.push(`    | Required<T>`)
+    out.push(`    | { [K in keyof T]?: never }`)
+    out.push(``)
+    out.push(`type ParamType = string | number | boolean`)
+    out.push(`type WildcardType = Iterable<ParamType>`)
+    out.push(``)
+
+    if (!routes.length) {
+        out.push(`// No string route patterns found in the default export.`)
+        out.push(``)
+    } else {
+        const usedNames = new Set<string>()
+        for (const route of routes) {
+            const base = toRouteFunctionName(route.name)
+            let name = base
+            let i = 2
+            while (usedNames.has(name)) {
+                name = `${base}_${i++}`
+            }
+            usedNames.add(name)
+
+            out.push(
+                compilePathGenerator(route.pattern, {
+                    functionName: name,
+                    delimiter: wildcardDelimiter,
+                    encode: encodeFunction,
+                }),
+            )
+            out.push(``)
+        }
+    }
+
+    const finalOutput = out.join('\n')
+    if (outputPath) {
+        await fs.writeFile(outputPath, finalOutput, 'utf8')
+        return { stdout: '', stderr: `Wrote ${outputPath}\n` }
+    } else {
+        return { stdout: finalOutput, stderr: '' }
+    }
+}
+
+/**
+ * Runs the rerouter CLI implementation without spawning a separate process.
+ *
+ * @param args - Command line arguments, excluding the binary name.
+ * @param options - Runtime options used to resolve paths and render the command comment.
+ * @returns Captured stdout, stderr, and an optional process exit code.
+ *
+ * @example
+ * ```ts
+ * const result = await runRerouterBin(['./routes.ts'])
+ * process.stdout.write(result.stdout)
+ * ```
+ *
+ * @internal
+ */
+export async function runRerouterBin(
+    args: readonly string[],
+    options: RunOptions = {},
+): Promise<RunResult> {
+    const { values, positionals } = parseArgs({ ...PARSE_CONFIG, args: [...args] })
+    return main(values, positionals, { ...options, commandArgs: args })
+}
+
+//#region Invoke main
+type ParsedConfig = ReturnType<typeof parseArgs<typeof PARSE_CONFIG>>
+type Options = ParsedConfig['values']
+type Positionals = ParsedConfig['positionals']
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    runRerouterBin(process.argv.slice(2)).then(
+        (result) => {
+            if (result.stdout) process.stdout.write(result.stdout)
+            if (result.stderr) process.stderr.write(result.stderr)
+            if (typeof result.exitCode === 'number') process.exitCode = result.exitCode
+        },
+        (err) => {
+            console.error(err ?? 'An unknown error occurred')
+            process.exitCode = 1
+        },
+    )
+}
+//#endregion

package/src/components/Link.test.tsx

@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Window } from 'happy-dom'
+
+const testWindow = new Window({ url: 'http://localhost/start' })
+
+testWindow.SyntaxError = SyntaxError
+
+Object.assign(globalThis, {
+    window: testWindow,
+    document: testWindow.document,
+    navigator: testWindow.navigator,
+    location: testWindow.location,
+    history: testWindow.history,
+    Event: testWindow.Event,
+    HTMLElement: testWindow.HTMLElement,
+    MouseEvent: testWindow.MouseEvent,
+    Node: testWindow.Node,
+    PopStateEvent: testWindow.PopStateEvent,
+    SyntaxError,
+    getComputedStyle: testWindow.getComputedStyle.bind(testWindow),
+})
+
+const { cleanup, fireEvent, render, screen } = await import('@testing-library/react')
+const { Link } = await import('./Link')
+
+describe(Link.name, () => {
+    beforeEach(() => {
+        window.history.replaceState(null, '', '/start')
+    })
+
+    afterEach(() => {
+        cleanup()
+        window.history.replaceState(null, '', '/start')
+    })
+
+    test('renders a link with merged search params', () => {
+        render(
+            <Link
+                aria-label="Match details"
+                className={['match-link', { selected: true, pending: false }]}
+                to="/matches?sort=asc"
+                search={{ page: 2, sort: 'desc' }}
+            >
+                View match
+            </Link>,
+        )
+
+        const link = screen.getByRole('link', { name: 'Match details' })
+
+        expect(link.textContent).toBe('View match')
+        expect(link.getAttribute('class')).toBe('match-link selected')
+        expect(link.getAttribute('href')).toBe('/matches?sort=desc&page=2')
+    })
+
+    test('pushes the target URL and emits popstate on ordinary clicks', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42?tab=details">View match</Link>)
+
+        fireEvent.click(screen.getByRole('link', { name: 'View match' }))
+
+        expect(window.location.pathname).toBe('/matches/42')
+        expect(window.location.search).toBe('?tab=details')
+        expect(popstateCount).toBe(1)
+    })
+
+    test('replaces the current URL when replace is set', () => {
+        const replaceState = window.history.replaceState.bind(window.history)
+        let replacedUrl = ''
+        window.history.replaceState = ((data, title, url) => {
+            replacedUrl = String(url)
+            return replaceState(data, title, url)
+        }) as History['replaceState']
+
+        render(
+            <Link replace to="/matches/42">
+                Replace match
+            </Link>,
+        )
+
+        try {
+            fireEvent.click(screen.getByRole('link', { name: 'Replace match' }))
+
+            expect(replacedUrl).toBe('/matches/42')
+            expect(window.location.pathname).toBe('/matches/42')
+        } finally {
+            window.history.replaceState = replaceState
+        }
+    })
+
+    test('leaves modified clicks to the browser', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42">Open elsewhere</Link>)
+
+        const defaultWasNotPrevented = fireEvent.click(
+            screen.getByRole('link', { name: 'Open elsewhere' }),
+            { ctrlKey: true },
+        )
+
+        expect(defaultWasNotPrevented).toBe(true)
+        expect(popstateCount).toBe(0)
+    })
+
+    test('leaves non-primary button clicks to the browser', () => {
+        let popstateCount = 0
+        window.addEventListener(
+            'popstate',
+            () => {
+                popstateCount += 1
+            },
+            { once: true },
+        )
+
+        render(<Link to="/matches/42">Open with auxiliary button</Link>)
+
+        const defaultWasNotPrevented = fireEvent.click(
+            screen.getByRole('link', { name: 'Open with auxiliary button' }),
+            { button: 1 },
+        )
+
+        expect(defaultWasNotPrevented).toBe(true)
+        expect(popstateCount).toBe(0)
+    })
+})

package/src/components/Link.tsx

@@ -0,0 +1,87 @@
+import { cc, type ClassValue } from '@mpen/classcat'
+import type { OverrideProps } from '@mpen/ts-types/react'
+import type { MouseEvent } from 'react'
+import { pushUrl, replaceUrl } from '../lib/url'
+import { mergeSearch } from '../lib/mergeSearch'
+
+/**
+ * Values accepted by [`Link`]{@link Link} for building query strings.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches" search={{ page: 2, sort: 'desc' }}>
+ *     Matches
+ * </Link>
+ * ```
+ */
+export type SearchParamsInit =
+    | string
+    | string[][]
+    | Record<string, string | number | boolean | undefined | null>
+    | URLSearchParams
+
+/**
+ * Props for [`Link`]{@link Link}.
+ */
+export type LinkProps = OverrideProps<
+    'a',
+    {
+        /**
+         * Classes to apply to the rendered anchor.
+         */
+        className?: ClassValue
+
+        /**
+         * Destination URL passed to the rendered anchor's `href` attribute.
+         */
+        to: string
+
+        /**
+         * Query parameters to merge into [`LinkProps.to`]{@link LinkProps#to}.
+         */
+        search?: SearchParamsInit
+
+        /**
+         * Whether navigation should replace the current history entry instead of pushing a new one.
+         */
+        replace?: boolean
+
+        href: never
+        onClick: never
+    }
+>
+
+/**
+ * Renders an anchor that navigates with rerouter history updates on ordinary clicks.
+ *
+ * @example
+ * ```tsx
+ * <Link to="/matches/42" search={{ tab: 'details' }}>
+ *     View match
+ * </Link>
+ * ```
+ *
+ * @param props - Anchor props plus rerouter navigation options.
+ * @returns An anchor element that pushes or replaces the browser URL.
+ */
+export function Link({ to, search, children, className, replace, ...rest }: LinkProps) {
+    const href = search ? mergeSearch(to, search) : to
+    const linkClassName = cc(className)
+
+    const onClick = (ev: MouseEvent<HTMLAnchorElement>) => {
+        if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return
+        if (ev.button !== 0) return
+        ev.preventDefault()
+        if (replace) {
+            replaceUrl(href)
+        } else {
+            pushUrl(href)
+        }
+    }
+
+    return (
+        <a {...rest} className={linkClassName || undefined} href={href} onClick={onClick}>
+            {children}
+        </a>
+    )
+}

package/src/components/NavLink.test.tsx

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { Window } from 'happy-dom'
+
+const testWindow = new Window({ url: 'http://localhost/start' })
+
+testWindow.SyntaxError = SyntaxError
+
+Object.assign(globalThis, {
+    window: testWindow,
+    document: testWindow.document,
+    navigator: testWindow.navigator,
+    location: testWindow.location,
+    history: testWindow.history,
+    Event: testWindow.Event,
+    HTMLElement: testWindow.HTMLElement,
+    MouseEvent: testWindow.MouseEvent,
+    Node: testWindow.Node,
+    PopStateEvent: testWindow.PopStateEvent,
+    SyntaxError,
+    getComputedStyle: testWindow.getComputedStyle.bind(testWindow),
+})
+
+const { cleanup, render } = await import('@testing-library/react')
+const { NavLink } = await import('./NavLink')
+
+describe(NavLink.name, () => {
+    beforeEach(() => {
+        window.history.replaceState(null, '', '/start')
+    })
+
+    afterEach(() => {
+        cleanup()
+        window.history.replaceState(null, '', '/start')
+    })
+
+    test('renders active classes when the target path matches the current path', () => {
+        const { getByRole } = render(
+            <NavLink
+                activeClass={{ active: true, pending: false }}
+                className="pill"
+                inactiveClass="muted"
+                to="/start?tab=details"
+            >
+                Start
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Start' }).getAttribute('class')).toBe('pill active')
+    })
+
+    test('renders inactive classes when the target path does not match the current path', () => {
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass={{ muted: true }}
+                to="/matches"
+            >
+                Matches
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Matches' }).getAttribute('class')).toBe('pill muted')
+    })
+
+    test('normalizes relative targets using the current URL', () => {
+        window.history.replaceState(null, '', '/matches/42')
+
+        const { getByRole } = render(
+            <NavLink activeClass="active" className="pill" inactiveClass="muted" to="?tab=details">
+                Current match
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Current match' }).getAttribute('class')).toBe(
+            'pill active',
+        )
+    })
+
+    test('renders active classes for prefix matches', () => {
+        window.history.replaceState(null, '', '/fetch-loading/abc-123')
+
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass="muted"
+                match="prefix"
+                to="/fetch-loading"
+            >
+                Fetch Loading
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Fetch Loading' }).getAttribute('class')).toBe(
+            'pill active',
+        )
+    })
+
+    test('does not render active classes for partial segment prefix matches', () => {
+        window.history.replaceState(null, '', '/fetch-loading-old')
+
+        const { getByRole } = render(
+            <NavLink
+                activeClass="active"
+                className="pill"
+                inactiveClass="muted"
+                match="prefix"
+                to="/fetch-loading"
+            >
+                Fetch Loading
+            </NavLink>,
+        )
+
+        expect(getByRole('link', { name: 'Fetch Loading' }).getAttribute('class')).toBe(
+            'pill muted',
+        )
+    })
+})