How kuberwastaken/fuzzy-redirect works
Project Type and Purpose
• This is an open-source, TypeScript-based npm library called fuzzy-redirect.
• Purpose: provide a fuzzy‐matching engine and framework integrations (React Router & Next.js) to automatically redirect mistyped URLs to the closest valid route.
• Key features: Levenshtein-based matching core, React hooks/components, Next.js hooks for both Pages and App routers, a CLI to auto-generate route lists, and full TypeScript support.
File Structure Analysis
• Top-level files:
• package.json, tsconfig*.json, jest.config.js – build, test, and publishing configuration
• README.md, CONTRIBUTING.md, LICENSE, CHANGELOG.md – documentation
• src/
• cli/generate.ts – CLI entry for route scanning & file generation
• core/fuzzy.ts – core matching logic (findClosestRoute, Levenshtein, thresholds)
• index.ts – main export façade
• next/index.ts & next/app.ts – Next.js Pages Router and App Router hooks
• react/index.ts & react/utils.ts – React Router hooks/components and helper to extract routes
• tests/ & test_failure.txt – Jest test cases validating core, React, and Next integrations.
• Build targets: CJS (tsconfig.cjs.json), ESM (tsconfig.esm.json), and type declarations (tsconfig.types.json).
README Insights
• Describes usage patterns in React & Next.js, the core API, configuration options, and the CLI generator workflow.
• Highlights dependencies (TypeScript, minimal external libs) and extension points (useFuzzyRedirect, useAppFuzzyRedirect, FuzzyRedirect component, findClosestRoute).
Main Components
a. Core Fuzzy Engine
– Module: src/core/fuzzy.ts
– Responsibility: calculate edit distances and pick the closest route.
b. Integration Layers
– React Integration: src/react
• Exposes useFuzzyRedirect hook, FuzzyRedirect component, extractRoutes utility.
– Next.js Integration: src/next
• Exposes useFuzzyRedirect for Pages Router (index.ts) and useAppFuzzyRedirect for App Router (app.ts).
c. CLI Generator
– Module: src/cli/generate.ts
– Responsibility: scan a codebase’s pages/ or app/ directory, build and emit a route‐list file (fuzzy-routes.ts).
d. Consumer Application
– React or Next.js app that imports fuzzy-redirect modules or the generated routes file
– Runs in browser, calls integration hooks/components to perform runtime redirection.
e. Build & Publish Pipeline
– TypeScript compiler produces CJS, ESM, and type files
– npm publish step, versioning driven by CHANGELOG.md and PUBLISHING.md
Relationships & Data Flow
• CLI Generator reads filesystem (pages/ or app/) → outputs route-list artifact
• Consumer App imports fuzzy-redirect API or generated routes → passes validRoutes to hooks/components
• Integration hook calls Core Fuzzy Engine → computes closest match for current URL
• If match found, integration triggers Router redirect (React Router or Next Router)
• Tests import each layer to validate behavior end-to-end
Architectural Patterns & Design Principles
• Single Responsibility: core fuzzy logic is decoupled from framework code
• Facade Pattern: index.ts re-exports public API for simplicity
• Plugin/Adapter: separate adapters for React and Next.js using the same core engine
• CLI as a build‐time tool, distinct from runtime libraries
Technologies & Frameworks
• TypeScript (strictly typed codebase, multi-target outputs)
• Jest for unit tests
• Node.js for CLI (npx entrypoint)
• React Router & Next.js routers at runtime
• Clear component names (e.g., CoreFuzzyEngine, ReactHookAdapter, NextPagesAdapter, CLI_Generator)
• Annotations for file paths (e.g., src/core/fuzzy.ts) if desired for precision