router-creator is a lightweight TypeScript utility for building full route trees with support for pathnames, nested segments, parameters, attributes, and origins.
It simplifies dynamic URL construction and routing logic in frontend or backend projects, offering utilities to set parameters, resolve full paths or URLs, and even validate if a pathname exists in your route tree.
- 🌳 Build nested and typed route trees
- 🌐 Handle full paths and origins
- ⚙️ Support for dynamic parameters (e.g.
:id) - 🔍 Match pathnames and validate against route tree
- 🏷️ Add attributes to paths (e.g.
loggable,authRequired, etc.) - 🧪 Fully tested and TypeScript-ready
npm install router-creator
# or
yarn add router-creatorimport RouterCreator, { createRouter } from "router-creator";
// This is the best ".ts way" to get the instance router.
const routes = createRouter("http://localhost:3000", {
private: {
users: {
_att: ["loggable"],
idUser: ":id_user",
},
auth: {
signout: "sign-out",
session: {},
},
},
public: {
auth: {
signin: "sign-in",
signup: {
_path: "sign-up",
init: {},
complete: {},
},
},
},
});
// This is a deprecated ".ts way" to get the instance router.
const router = new RouterCreator("http://localhost:3000").createPathnames({
private: {
users: {
_att: ["loggable"],
idUser: ":id_user",
},
auth: {
signout: "sign-out",
session: {},
},
},
public: {
auth: {
signin: "sign-in",
signup: {
_path: "sign-up",
init: {},
complete: {},
},
},
},
});
// Accessing full path
router.private.users.root.get(); // "/private/users"
router.private.users.idUser.get(); // "/private/users/:id_user"
router.private.users.idUser.set("123").get(); // "/private/users/123"
//Accessing full URL
router.private.auth.signout.getUrl(); // "http://localhost:3000/private/auth/sign-out"
// Matching pathnames
router.hasPathname("/private/users"); // true
router.hasPathname("/private/users/123"); // true
router.hasPathname("/private/invalid"); // false
// Match path with specific attribute (e.g. "loggable")
router.hasPathname("/private/users/123", { attribute: "loggable" }); // true
router.hasPathname("/private/auth/sign-out", { attribute: "loggable" }); // falseCreate paths that starts with $ or with the reserved names get, set, getParams, getOrigin, etc... May cause unexpected behavior.
The createRouter() function accepts an origin and plain object that represents your entire route structure. Each key becomes a named path, and you can define dynamic segments, nested paths, and attach custom attributes to each route.
Each key inside the object represents a route segment. You can define:
- A static path:
"segment"that will be converted into"/segment". - A dynamic parameter:
":paramName"that will be converted into"/:paramName". - Nested objects for nested paths. The key of the object will be used as the path segment if isn't a
_pathkey inside the object. - Metadata using special keys:
_path: defines the current segment (when isn't defined, the key of the object will be used)._att: an array of custom attributes (optional)
const router = createRouter("https://example.com", {
private: {
// /private
users: {
// /private/users
idUser: ":idUser", // /private/users/:idUser
},
reports: {
// /reports
id_report: {
// /reports/:id_report
_path: ":id_report",
_att: ["loggable"],
download: {
// /reports/:id_report/download
file: {}, // /reports/:id_report/download/file
},
},
},
},
});The createPathnames() method accepts a plain object that represents your entire route structure. Each key becomes a named path, and you can define dynamic segments, nested paths, and attach custom attributes to each route.
Each key inside the object represents a route segment. You can define:
- A static path:
""or"segment"that will be converted into"/"or"/segment"respectively. - A dynamic parameter:
":paramName"that will be converted into"/:paramName". - Nested objects for nested paths. The key of the object will be used as the path segment if isn't a
_pathkey inside the object. - Metadata using special keys:
_path: defines the current segment (when isn't defined, the key of the object will be used)._att: an array of custom attributes (optional)
const routes = new RouterCreator("https://example.com").createPathnames({
private: {
users: {
idUser: ":idUser",
},
reports: {
id_report: {
_path: ":id_report",
_att: ["loggable"],
download: {
file: {},
},
},
},
},
});Creates a new router with a defined base origin (e.g. "https://myapp.com").
Returns the full pathname from the root to this path.
routes.private.users.idUser.get(); // "/private/users/:id_user"Returns the pathname of the current path.
routes.private.users.idUser.getPath(); // "/:id_user"Returns the full URL including origin.
routes.private.users.idUser.getUrl();
// "http://localhost:3000/private/users/:id_user"Injects a parameter into a route that uses a :param placeholder.
routes.private.users.id_user.set("abc123").get(); // "/private/users/abc123"
routes.private.users.id_user.get(); // "/private/users/id-user"Starts the pathname in the next child path.
routes.private.start().users.id_user.get(); // "/users/:id-user"
routes.private.users.start().id_user.get(); // "/:id-user"Checks if the given pathname exists in the route tree. Optionally filters by attribute.
routes.hasPathname("/private/users/abc123"); // boolean
routes.hasPathname("/private/captures/123/upload/files", { attribute: "loggable" }); // boolean