# darkgraycat/split-route architecture

> Architecture diagram of the GitHub repository darkgraycat/split-route, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/darkgraycat/split-route
- Repository: https://github.com/darkgraycat/split-route

## Overview

#### Purpose and Entry Points
`split-route` is a small Node.js package for building conditional Express middleware chains within one route. Consumers import the package root (`index.js`), which exposes the implementation from `lib/index.js`.

Paths: `index.js`, `lib/index.js`, `package.json`

#### Public Builder API
The core export accepts a selector callback, typically `(req, res) => value`, and returns a fluent builder. Callers register branches with `.case(value, ...middleware)`, optionally add `.default(...middleware)`, then call `.end()` to obtain Express-compatible middleware.

Path: `lib/index.js`

#### Route Dispatch Stage
At request time, the built middleware invokes the selector callback and compares its result with registered case values. The selected branch becomes the active middleware sequence; if no case matches, the default branch is used when present.

Path: `lib/index.js`

#### Middleware Composition Boundary
Each branch accepts one or more Express middleware functions. The package’s primary boundary is between branch selection and normal Express execution: after selection, middleware must preserve Express’s `(req, res, next)` contract and call `next()` to continue the route pipeline.

Paths: `lib/index.js`, `README.md`

#### Nested Routing Composition
A branch can itself contain another completed `splitRoute(...).case(...).end()` middleware. This makes nested decision trees possible without creating separate Express route declarations; nesting remains standard middleware composition rather than a separate runtime or router abstraction.

Paths: `lib/index.js`, `README.md`

#### Runtime and Dependencies
The package runs in Node.js and targets Express middleware interoperability, but Express is consumed by applications rather than represented as repository infrastructure. There are no services, databases, web servers, or deployment resources in this repository.

Paths: `package.json`, `package-lock.json`

#### Verification Surface
Behavior is exercised through the package’s test entry point, covering the exported builder and its dispatch behavior.

Paths: `tests/index.test.js`, `tests`

Main entry points: [`lib/index.js`](https://github.com/darkgraycat/split-route/blob/main/lib/index.js) (Split-route builder), [`index.js`](https://github.com/darkgraycat/split-route/blob/main/index.js) (Package root export), [`package.json`](https://github.com/darkgraycat/split-route/blob/main/package.json) (Package manifest), [`README.md`](https://github.com/darkgraycat/split-route/blob/main/README.md) (Usage documentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_package["split-route package"]
  node_package_root["Package root export<br/>Node.js entry<br/>[index.js]"]
  node_core_export["Split-route builder<br/>fluent API<br/>[index.js]"]
  node_branch_registry["Branch registry<br/>dispatch state<br/>[index.js]"]
  node_completed_middleware["Completed middleware<br/>Express middleware<br/>[index.js]"]
  node_dispatch{{"Request dispatch<br/>runtime stage<br/>[index.js]"}}
  node_branch_chain["Selected middleware chain<br/>Express chain<br/>[index.js]"]
  node_nested_route["Nested completed split-route<br/>composed middleware<br/>[index.js]"]
  node_package_manifest["Package manifest<br/>npm metadata<br/>[package.json]"]
end

node_consumer["Express application<br/>consumer"]
node_selector["Selector callback<br/>application callback"]
node_express_pipeline["Express route pipeline<br/>external runtime"]
node_documentation["Usage documentation<br/>[README.md]"]
node_tests["Dispatch tests<br/>verification<br/>[index.test.js]"]

node_consumer -->|"imports"| node_package_root
node_package_root -->|"exposes"| node_core_export
node_core_export -->|"accepts"| node_selector
node_core_export -->|"registers cases and default"| node_branch_registry
node_core_export -->|"end&#40;&#41; returns"| node_completed_middleware
node_consumer -->|"mounts in route"| node_completed_middleware
node_completed_middleware -->|"invokes on request"| node_dispatch
node_selector -->|"provides selection value"| node_dispatch
node_branch_registry -->|"supplies branches"| node_dispatch
node_dispatch -->|"selects matching or default"| node_branch_chain
node_branch_chain -->|"calls next&#40;&#41;"| node_express_pipeline
node_nested_route -->|"can be included in"| node_branch_chain
node_core_export -.->|"can produce"| node_nested_route
node_documentation -.->|"documents"| node_core_export
node_tests -.->|"verifies"| node_core_export
node_package_manifest -.->|"declares entry package"| node_package_root

click node_package_root "https://github.com/darkgraycat/split-route/blob/main/index.js"
click node_core_export "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_branch_registry "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_completed_middleware "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_dispatch "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_branch_chain "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_nested_route "https://github.com/darkgraycat/split-route/blob/main/lib/index.js"
click node_documentation "https://github.com/darkgraycat/split-route/blob/main/README.md"
click node_tests "https://github.com/darkgraycat/split-route/blob/main/tests/index.test.js"
click node_package_manifest "https://github.com/darkgraycat/split-route/blob/main/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package_root,node_core_export,node_branch_registry,node_completed_middleware,node_dispatch,node_branch_chain,node_nested_route,node_package_manifest toneBlue
class node_consumer,node_selector,node_express_pipeline,node_documentation,node_tests toneNeutral
```

## Components

### split-route package

Conditional Express middleware composition.

- [Package root export](https://github.com/darkgraycat/split-route/blob/main/index.js): Node.js entry · Public package entry point. · `index.js`
- [Split-route builder](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): fluent API · Accepts a selector and exposes case, default, and end. · `lib/index.js`
- [Branch registry](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): dispatch state · Stores case values, middleware sequences, and an optional default. · `lib/index.js`
- [Completed middleware](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): Express middleware · Produced by end() for use in a route pipeline. · `lib/index.js`
- [Request dispatch](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): runtime stage · Matches the selector result to a case or default branch. · `lib/index.js`
- [Selected middleware chain](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): Express chain · Runs the selected branch under the req, res, next contract. · `lib/index.js`
- [Nested completed split-route](https://github.com/darkgraycat/split-route/blob/main/lib/index.js): composed middleware · A completed builder can be used as branch middleware. · `lib/index.js`
- [Package manifest](https://github.com/darkgraycat/split-route/blob/main/package.json): npm metadata · Defines the Node.js package runtime and dependencies. · `package.json`

### Other components

- **Express application**: consumer · Imports the package and mounts completed middleware in a route.
- **Selector callback**: application callback · Derives the value used for branch selection.
- **Express route pipeline**: external runtime · Continues when branch middleware calls next().
- [Usage documentation](https://github.com/darkgraycat/split-route/blob/main/README.md): documentation · Documents middleware and nested composition. · `README.md`
- [Dispatch tests](https://github.com/darkgraycat/split-route/blob/main/tests/index.test.js): verification · Exercises the exported builder and dispatch behavior. · `tests/index.test.js`

## Connections

- Express application → Package root export: imports
- Package root export → Split-route builder: exposes
- Split-route builder → Selector callback: accepts
- Split-route builder → Branch registry: registers cases and default
- Split-route builder → Completed middleware: end() returns
- Express application → Completed middleware: mounts in route
- Completed middleware → Request dispatch: invokes on request
- Selector callback → Request dispatch: provides selection value
- Branch registry → Request dispatch: supplies branches
- Request dispatch → Selected middleware chain: selects matching or default
- Selected middleware chain → Express route pipeline: calls next()
- Nested completed split-route → Selected middleware chain: can be included in
- Split-route builder → Nested completed split-route: can produce
- Usage documentation → Split-route builder: documents
- Dispatch tests → Split-route builder: verifies
- Package manifest → Package root export: declares entry package