@rudderjs/router 1.0.0 → 1.1.0

package/dist/index.js

@@ -89,12 +89,55 @@ export const Put = createMethodDecorator('PUT');
 export const Patch = createMethodDecorator('PATCH');
 export const Delete = createMethodDecorator('DELETE');
 export const Options = createMethodDecorator('OPTIONS');
+// ─── Path utilities ────────────────────────────────────────
+/**
+ * Remove every balanced `{...}` block from a path. Used to peel off
+ * `where*()` regex constraint segments before scanning the path for `:param`
+ * names. Brace nesting is honoured so quantifier braces (`{8}`, `{4}`) inside
+ * a constraint don't terminate the block early.
+ */
+function stripRegexSegments(path) {
+    let out = '';
+    let i = 0;
+    while (i < path.length) {
+        if (path[i] !== '{') {
+            out += path[i];
+            i++;
+            continue;
+        }
+        let depth = 1;
+        i++;
+        while (i < path.length && depth > 0) {
+            if (path[i] === '{')
+                depth++;
+            else if (path[i] === '}')
+                depth--;
+            i++;
+        }
+    }
+    return out;
+}
+// ─── Route param constraint patterns ──────────────────────
+//
+// Reusable regex shards consumed by `RouteBuilder.where*()` and exported so
+// app code can compose its own Hono `:param{pattern}` strings if needed.
+/** Matches one or more digits — `[0-9]+`. */
+export const ROUTE_PATTERN_NUMBER = '[0-9]+';
+/** Matches one or more ASCII letters — `[A-Za-z]+`. */
+export const ROUTE_PATTERN_ALPHA = '[A-Za-z]+';
+/** Matches one or more ASCII letters or digits — `[A-Za-z0-9]+`. */
+export const ROUTE_PATTERN_ALPHANUM = '[A-Za-z0-9]+';
+/** Matches a UUID of any version (case-insensitive). */
+export const ROUTE_PATTERN_UUID = '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
+/** Matches a Crockford base32 ULID (26 chars). */
+export const ROUTE_PATTERN_ULID = '[0-7][0-9A-HJKMNP-TV-Z]{25}';
 // ─── RouteBuilder ──────────────────────────────────────────
 /**
- * Returned by `router.get/post/etc` — allows naming the registered route.
+ * Returned by `router.get/post/etc` — allows naming the registered route and
+ * constraining `:param` segments via Laravel-style `where*` shortcuts.
  *
  * @example
- * router.get('/users/:id', handler).name('users.show')
+ * router.get('/users/:id', handler).name('users.show').whereNumber('id')
  * route('users.show', { id: 1 })  // → '/users/1'
  */
 export class RouteBuilder {
@@ -106,22 +149,164 @@ export class RouteBuilder {
     }
     /** Assign a name to this route for use with `route()` and `Url.signedRoute()`. */
     name(n) {
-        this._router._registerName(n, this.definition.path);
+        // Pass the definition itself so later `where*()` calls (which mutate
+        // `definition.path`) are reflected when the named route is looked up.
+        this._router._registerName(n, this.definition);
+        return this;
+    }
+    /**
+     * Constrain a `:param` segment with a custom regex. Accepts either a string
+     * (used verbatim) or a `RegExp` (its `.source` is taken — `/^/`, `/$/`, and
+     * flags are ignored, since Hono anchors per-segment).
+     *
+     * Mutates the route's path in place to `:param{pattern}` (Hono regex syntax).
+     * Calling `where*` again on the same param overwrites the previous pattern.
+     *
+     * Throws if the route path has no `:param` segment.
+     */
+    where(param, regex) {
+        const pattern = regex instanceof RegExp ? regex.source : regex;
+        const path = this.definition.path;
+        let out = '';
+        let matched = false;
+        let i = 0;
+        while (i < path.length) {
+            if (path[i] !== ':') {
+                out += path[i];
+                i++;
+                continue;
+            }
+            // Scan a `:paramName(?)?{balanced regex}?` segment.
+            let j = i + 1;
+            while (j < path.length && /[A-Za-z0-9_]/.test(path[j] ?? ''))
+                j++;
+            const name = path.slice(i + 1, j);
+            let opt = '';
+            if (path[j] === '?') {
+                opt = '?';
+                j++;
+            }
+            // Consume a balanced `{ ... }` block (handles `[0-9]{8}`-style nesting).
+            let bodyEnd = j;
+            if (path[j] === '{') {
+                let depth = 1;
+                bodyEnd = j + 1;
+                while (bodyEnd < path.length && depth > 0) {
+                    if (path[bodyEnd] === '{')
+                        depth++;
+                    else if (path[bodyEnd] === '}')
+                        depth--;
+                    bodyEnd++;
+                }
+            }
+            if (name === param) {
+                out += `:${name}${opt}{${pattern}}`;
+                matched = true;
+            }
+            else {
+                out += path.slice(i, bodyEnd);
+            }
+            i = bodyEnd;
+        }
+        if (!matched) {
+            throw new Error(`[RudderJS Router] where("${param}", ...) — route path "${path}" has no :${param} segment.`);
+        }
+        this.definition.path = out;
         return this;
     }
+    /** Constrain `:param` to one or more digits. */
+    whereNumber(param) { return this.where(param, ROUTE_PATTERN_NUMBER); }
+    /** Constrain `:param` to one or more ASCII letters. */
+    whereAlpha(param) { return this.where(param, ROUTE_PATTERN_ALPHA); }
+    /** Constrain `:param` to one or more ASCII letters or digits. */
+    whereAlphaNumeric(param) { return this.where(param, ROUTE_PATTERN_ALPHANUM); }
+    /** Constrain `:param` to a UUID of any version. */
+    whereUuid(param) { return this.where(param, ROUTE_PATTERN_UUID); }
+    /** Constrain `:param` to a Crockford base32 ULID. */
+    whereUlid(param) { return this.where(param, ROUTE_PATTERN_ULID); }
+    /**
+     * Constrain `:param` to one of the supplied literal values. Each value is
+     * regex-escaped, so `'a.b'` matches the literal string `a.b`, not "a then any
+     * char then b". Throws when `values` is empty.
+     *
+     * @example
+     * router.get('/posts/:status', handler).whereIn('status', ['draft', 'published'])
+     */
+    whereIn(param, values) {
+        if (values.length === 0) {
+            throw new Error(`[RudderJS Router] whereIn("${param}", []) — values must be non-empty.`);
+        }
+        const escaped = values.map(v => String(v).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+        return this.where(param, `(?:${escaped.join('|')})`);
+    }
+    /**
+     * Restrict this route to a specific subdomain. The template is matched against
+     * the request's `Host` header (port stripped, case-insensitive); `:param`
+     * segments capture into `req.params` alongside path params.
+     *
+     * @example
+     * router.get('/users', listUsers).domain('api.example.com')
+     * router.get('/admin', dash).domain(':tenant.example.com')  // captures req.params.tenant
+     */
+    domain(template) {
+        this.definition.host = template;
+        return this;
+    }
+    /**
+     * Custom response when an explicit route binding (`router.bind('user', User)`)
+     * resolves to `null`. Receives the request and the not-found error; return any
+     * value a handler may return (`Response`, plain object → JSON, string → body,
+     * or `undefined` after writing to `res` directly). Does not fire for optional
+     * bindings — those quietly resolve to `null` instead.
+     *
+     * @example
+     * router.get('/users/:user', show)
+     *   .missing((_req, err) => Response.json({ error: err.message }, { status: 404 }))
+     */
+    missing(fn) {
+        this.definition.missing = fn;
+        return this;
+    }
+}
+/**
+ * Thrown by route binding middleware when a required `{param}` cannot be
+ * resolved into a model instance. `@rudderjs/core` picks up the duck-typed
+ * `httpStatus` and renders this as an HTTP 404; apps can catch it explicitly
+ * to render a custom not-found page.
+ */
+export class RouteModelNotFoundError extends Error {
+    model;
+    param;
+    value;
+    /** Duck-typed signal to `@rudderjs/core`'s exception handler. */
+    httpStatus = 404;
+    constructor(model, param, value) {
+        super(`[RudderJS] No ${model} matched route parameter "${param}" with value "${value}".`);
+        this.name = 'RouteModelNotFoundError';
+        this.model = model;
+        this.param = param;
+        this.value = value;
+    }
 }
 // ─── Router ────────────────────────────────────────────────
 export class Router {
     routes = [];
     globalMiddleware = [];
     namedRoutes = new Map();
+    bindings = new Map();
+    /**
+     * Active `group()` scopes, outermost first. Synchronous module-level state
+     * is fine — route loaders execute synchronously at module evaluation, and
+     * `group()` only mutates the stack inside its own callback's lifetime.
+     */
+    _groupStack = [];
     /** @internal — called by RouteBuilder */
-    _registerName(name, path) {
-        this.namedRoutes.set(name, path);
+    _registerName(name, def) {
+        this.namedRoutes.set(name, def);
     }
-    /** Look up a named route's path. */
+    /** Look up a named route's path. Reflects any `where*()` mutations. */
     getNamedRoute(name) {
-        return this.namedRoutes.get(name);
+        return this.namedRoutes.get(name)?.path;
     }
     /**
      * Check whether a named route is registered.
@@ -138,23 +323,209 @@ export class Router {
     }
     /** All registered named routes. */
     listNamed() {
-        return Object.fromEntries(this.namedRoutes);
+        const out = {};
+        for (const [name, def] of this.namedRoutes)
+            out[name] = def.path;
+        return out;
     }
-    /** Clear registered routes, middleware, and named routes. */
+    /** Clear registered routes, middleware, named routes, and route bindings. */
     reset() {
         this.routes = [];
         this.globalMiddleware = [];
         this.namedRoutes.clear();
+        this.bindings.clear();
+        this._groupStack = [];
+        return this;
+    }
+    /**
+     * Run `fn` with a group scope active. Every route registered (via fluent
+     * `.get()`/`.post()`/etc. or `registerController()`) inside `fn` inherits
+     * the group's `prefix`, `domain`, and `middleware`. Nested calls compose:
+     * prefixes concatenate, middleware stacks accumulate, the innermost defined
+     * `domain` wins.
+     *
+     * Distinct from `runWithGroup('web' | 'api', …)` — that tags routes with
+     * their middleware-group label (web vs api) and is called once by the
+     * framework's route loader. `router.group()` is the user-facing scoping
+     * primitive; both can be active at the same time.
+     *
+     * @example
+     * router.group({ prefix: '/admin', middleware: [adminAuth] }, () => {
+     *   router.get('/users', listUsers)        // GET /admin/users (with adminAuth)
+     *   router.get('/posts', listPosts)        // GET /admin/posts (with adminAuth)
+     * })
+     *
+     * router.group({ domain: ':tenant.example.com', prefix: '/api' }, () => {
+     *   router.get('/me', me)                  // GET :tenant.example.com/api/me
+     * })
+     */
+    group(opts, fn) {
+        this._groupStack = [...this._groupStack, opts];
+        try {
+            fn();
+        }
+        finally {
+            this._groupStack = this._groupStack.slice(0, -1);
+        }
         return this;
     }
+    /**
+     * Compose the active group stack into the values used to register a route.
+     * Path prefixes concatenate (and collapse `/+` to `/`), middleware stacks
+     * concatenate, the innermost defined `host` wins.
+     */
+    _applyGroupStack(path, middleware) {
+        if (this._groupStack.length === 0) {
+            return { path, middleware, host: undefined };
+        }
+        let prefix = '';
+        let host;
+        const groupMw = [];
+        for (const g of this._groupStack) {
+            if (g.prefix)
+                prefix += g.prefix;
+            if (g.domain)
+                host = g.domain;
+            if (g.middleware)
+                groupMw.push(...g.middleware);
+        }
+        const composedPath = `${prefix}${path}`.replace(/\/+/g, '/');
+        return {
+            path: composedPath,
+            middleware: [...groupMw, ...middleware],
+            host,
+        };
+    }
     /** Register a global middleware (runs on every route). */
     use(middleware) {
         this.globalMiddleware.push(middleware);
         return this;
     }
+    /**
+     * Bind a route parameter name to a resolver. When a route's path contains
+     * `:<name>`, the matching string param is resolved before the handler runs;
+     * the result is exposed as `req.bound[name]`. The raw string remains in
+     * `req.params[name]` so existing code keeps working.
+     *
+     * Resolvers are duck-typed — pass any class with a static `findForRoute(val)`
+     * method (`@rudderjs/orm` Model classes match by default). Bindings are
+     * opt-in: routes whose path does not include the bound `:name` are unaffected.
+     *
+     * @example
+     * import { router } from '@rudderjs/router'
+     * import { User } from '../app/Models/User.js'
+     *
+     * router.bind('user', User)
+     * router.get('/users/:user', (req) => req.bound!['user'])
+     *
+     * // Custom column → declare on the model:
+     * class Post extends Model {
+     *   static override routeKey = 'slug'
+     * }
+     * router.bind('post', Post)  // resolves /posts/:post by slug
+     *
+     * // Optional binding — null when missing instead of 404:
+     * router.bind('viewer', User, { optional: true })
+     */
+    bind(name, resolver, options = {}) {
+        this.bindings.set(name, { resolver, optional: options.optional ?? false });
+        return this;
+    }
+    /** All registered route bindings, keyed by param name. */
+    listBindings() {
+        const out = {};
+        for (const [name, binding] of this.bindings)
+            out[name] = binding.resolver;
+        return out;
+    }
+    /**
+     * Build the per-route binding middleware. Walks the route's `:param` segments,
+     * looks them up in the binding map, and resolves each before calling `next()`.
+     * No-op for routes whose path contains no bound params.
+     *
+     * Takes the full `RouteDefinition` (not just path) so the closure can capture
+     * `def.missing` — the per-route 404 customisation set via `RouteBuilder.missing()`.
+     */
+    _buildBindingMiddleware(def) {
+        // Strip `{regex}` constraint segments from `where*()` before scanning for
+        // param names — otherwise a `:` inside a custom pattern could be misread
+        // as a route param. Uses balanced-brace stripping to support nested `{n}`
+        // quantifiers (e.g. UUID's `[0-9a-f]{8}-...`).
+        const stripped = stripRegexSegments(def.path);
+        const paramNames = [...stripped.matchAll(/:([a-zA-Z_][a-zA-Z0-9_]*)\??/g)].map(m => m[1]);
+        const matches = [];
+        for (const name of paramNames) {
+            const binding = this.bindings.get(name);
+            if (binding)
+                matches.push([name, binding]);
+        }
+        if (matches.length === 0)
+            return null;
+        return async (req, res, next) => {
+            // Lazy-init bound bag so handlers always see an object.
+            const bound = req.bound ?? {};
+            req.bound = bound;
+            for (const [name, binding] of matches) {
+                const raw = req.params[name];
+                let err = null;
+                if (raw === undefined || raw === '') {
+                    if (binding.optional) {
+                        bound[name] = null;
+                        continue;
+                    }
+                    err = new RouteModelNotFoundError(binding.resolver.name, name, '');
+                }
+                else {
+                    const resolved = await binding.resolver.findForRoute(raw);
+                    if (resolved === null || resolved === undefined) {
+                        if (binding.optional) {
+                            bound[name] = null;
+                            continue;
+                        }
+                        err = new RouteModelNotFoundError(binding.resolver.name, name, raw);
+                    }
+                    else {
+                        bound[name] = resolved;
+                    }
+                }
+                if (err) {
+                    if (def.missing) {
+                        // Route opted into a custom 404 — dispatch the result the same
+                        // way registerRoute() handles a route handler's return value.
+                        const result = await def.missing(req, err);
+                        if (result instanceof Response) {
+                            ;
+                            res.raw.res = result;
+                            return;
+                        }
+                        if (typeof result === 'string') {
+                            res.send(result);
+                            return;
+                        }
+                        if (result !== undefined && result !== null) {
+                            res.json(result);
+                            return;
+                        }
+                        // undefined → callback wrote to res directly; trust that.
+                        return;
+                    }
+                    throw err;
+                }
+            }
+            await next();
+        };
+    }
     /** Manually register a route. Returns `this` for bulk registration. */
     add(method, path, handler, middleware = []) {
-        const def = { method, path, handler, middleware };
+        const composed = this._applyGroupStack(path, middleware);
+        const def = {
+            method,
+            path: composed.path,
+            handler,
+            middleware: composed.middleware,
+        };
+        if (composed.host)
+            def.host = composed.host;
         const group = currentGroup();
         if (group)
             def.group = group;
@@ -169,7 +540,15 @@ export class Router {
     delete(path, handler, middleware) { return this._rb('DELETE', path, handler, middleware); }
     all(path, handler, middleware) { return this._rb('ALL', path, handler, middleware); }
     _rb(method, path, handler, middleware = []) {
-        const def = { method, path, handler, middleware };
+        const composed = this._applyGroupStack(path, middleware);
+        const def = {
+            method,
+            path: composed.path,
+            handler,
+            middleware: composed.middleware,
+        };
+        if (composed.host)
+            def.host = composed.host;
         const group = currentGroup();
         if (group)
             def.group = group;
@@ -192,12 +571,15 @@ export class Router {
                 value: `${ControllerClass.name}@${String(route.handlerKey)}`,
                 configurable: true,
             });
+            const composed = this._applyGroupStack(fullPath, [...ctrlMw, ...route.middleware]);
             const def = {
                 method: route.method,
-                path: fullPath,
+                path: composed.path,
                 handler,
-                middleware: [...ctrlMw, ...route.middleware],
+                middleware: composed.middleware,
             };
+            if (composed.host)
+                def.host = composed.host;
             if (group)
                 def.group = group;
             this.routes.push(def);
@@ -208,13 +590,204 @@ export class Router {
     mount(server) {
         for (const mw of this.globalMiddleware)
             server.applyMiddleware(mw);
-        for (const route of this.routes)
-            server.registerRoute(route);
+        for (const route of this.routes) {
+            const bindingMw = this._buildBindingMiddleware(route);
+            if (bindingMw) {
+                server.registerRoute({
+                    ...route,
+                    middleware: [bindingMw, ...route.middleware],
+                });
+            }
+            else {
+                server.registerRoute(route);
+            }
+        }
     }
     /** All registered routes — useful for `routes:list`. */
     list() {
         return [...this.routes];
     }
+    // ── Resource controllers ───────────────────────────────────
+    /**
+     * Register the canonical seven CRUD routes for a plain controller class:
+     * `index`, `create`, `store`, `show`, `edit`, `update`, `destroy`. Methods
+     * the controller doesn't implement are silently skipped, so a partial
+     * controller works without `only`/`except` boilerplate.
+     *
+     * The `update` route is registered for both `PUT` and `PATCH`. Route names
+     * default to `<name>.<verb>` (`posts.show`, `posts.update`). The path param
+     * defaults to a naive singular (`posts` → `:post`); pass
+     * `{ parameters: { posts: 'article' } }` to override.
+     *
+     * Use plain method names — no decorators. Call `router.registerController()`
+     * for decorator-driven controllers instead.
+     *
+     * @example
+     * router.resource('posts', PostController)
+     * router.resource('posts', PostController, { only: ['index', 'show'] })
+     * router.resource('posts', PostController, { middleware: [authMw] })
+     */
+    resource(name, Ctrl, opts = {}) {
+        return this._registerResource(name, Ctrl, RESOURCE_VERBS, opts);
+    }
+    /**
+     * Register an API-only resource — the same routes as `resource()` minus
+     * `create` and `edit`, since those render HTML forms and have no JSON
+     * equivalent.
+     *
+     * @example
+     * router.apiResource('posts', PostController)
+     */
+    apiResource(name, Ctrl, opts = {}) {
+        return this._registerResource(name, Ctrl, RESOURCE_VERBS, {
+            ...opts,
+            except: [...(opts.except ?? []), 'create', 'edit'],
+        });
+    }
+    /**
+     * Register a singleton resource — `show`, `edit`, `update` only. Use for
+     * "the current user's profile" / "the application's settings" style
+     * resources where there's only ever one of the thing.
+     *
+     * Add a creation flow with `.creatable()` (registers `create` + `store`) or
+     * a deletion flow with `.destroyable()` (registers `destroy`).
+     *
+     * @example
+     * router.singleton('profile', ProfileController)            // /profile + /profile/edit
+     * router.singleton('profile', ProfileController).creatable() // also /profile/create + POST /profile
+     */
+    singleton(name, Ctrl, opts = {}) {
+        const reg = this._registerResource(name, Ctrl, SINGLETON_VERBS, opts);
+        return new SingletonRegistration(reg.builders, this, name, Ctrl, opts);
+    }
+    /** @internal — shared registration loop for resource/apiResource/singleton. */
+    _registerResource(name, Ctrl, table, opts) {
+        const instance = new Ctrl();
+        const verbs = filterVerbs(table, opts);
+        const paramName = opts.parameters?.[name] ?? singularize(name);
+        const builders = [];
+        for (const spec of verbs) {
+            const fn = instance[spec.verb];
+            if (typeof fn !== 'function')
+                continue; // partial controller — skip
+            const path = spec.path(name, paramName);
+            const handler = fn.bind(instance);
+            Object.defineProperty(handler, 'name', {
+                value: `${Ctrl.name}@${spec.verb}`,
+                configurable: true,
+            });
+            const builder = this._rb(spec.method, path, handler, opts.middleware ?? []);
+            builder.name(opts.names?.[spec.verb] ?? `${name}.${spec.nameSuffix}`);
+            builders.push(builder);
+            if (spec.verb === 'update') {
+                // `update` registers PUT + PATCH at the same path. The PATCH route
+                // doesn't get a name to avoid a collision with the PUT route's name —
+                // both verbs resolve the same path, so `route('posts.update')` works
+                // for either.
+                const patch = this._rb('PATCH', path, handler, opts.middleware ?? []);
+                builders.push(patch);
+            }
+        }
+        return new ResourceRegistration(builders);
+    }
+}
+const RESOURCE_VERBS = [
+    { verb: 'index', method: 'GET', path: (n) => `/${n}`, nameSuffix: 'index' },
+    { verb: 'create', method: 'GET', path: (n) => `/${n}/create`, nameSuffix: 'create' },
+    { verb: 'store', method: 'POST', path: (n) => `/${n}`, nameSuffix: 'store' },
+    { verb: 'show', method: 'GET', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'show' },
+    { verb: 'edit', method: 'GET', path: (n, p) => `/${n}/:${p}/edit`, nameSuffix: 'edit' },
+    { verb: 'update', method: 'PUT', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'update' },
+    { verb: 'destroy', method: 'DELETE', path: (n, p) => `/${n}/:${p}`, nameSuffix: 'destroy' },
+];
+const SINGLETON_VERBS = [
+    { verb: 'show', method: 'GET', path: (n) => `/${n}`, nameSuffix: 'show' },
+    { verb: 'edit', method: 'GET', path: (n) => `/${n}/edit`, nameSuffix: 'edit' },
+    { verb: 'update', method: 'PUT', path: (n) => `/${n}`, nameSuffix: 'update' },
+];
+const SINGLETON_CREATE_VERBS = [
+    { verb: 'create', method: 'GET', path: (n) => `/${n}/create`, nameSuffix: 'create' },
+    { verb: 'store', method: 'POST', path: (n) => `/${n}`, nameSuffix: 'store' },
+];
+const SINGLETON_DESTROY_VERBS = [
+    { verb: 'destroy', method: 'DELETE', path: (n) => `/${n}`, nameSuffix: 'destroy' },
+];
+function filterVerbs(table, opts) {
+    let verbs = table;
+    if (opts.only) {
+        const allow = new Set(opts.only);
+        verbs = verbs.filter(v => allow.has(v.verb));
+    }
+    if (opts.except) {
+        const deny = new Set(opts.except);
+        verbs = verbs.filter(v => !deny.has(v.verb));
+    }
+    return verbs;
+}
+/**
+ * Naive English singularizer for the default resource param name. Handles the
+ * three patterns Laravel users hit constantly (`posts → post`,
+ * `categories → category`, `boxes → box`). Anything irregular — `people`,
+ * `data`, etc. — should be overridden via the `parameters` option, exactly
+ * as in Laravel.
+ */
+function singularize(name) {
+    if (/[^aeiou]ies$/i.test(name))
+        return name.slice(0, -3) + 'y'; // categories → category
+    if (/(s|x|z|ch|sh)es$/i.test(name))
+        return name.slice(0, -2); // boxes → box
+    if (/s$/i.test(name) && !/ss$/i.test(name))
+        return name.slice(0, -1); // posts → post
+    return name;
+}
+/**
+ * Returned by `router.resource()`/`apiResource()`. The `builders` array holds
+ * one `RouteBuilder` per registered route in declaration order — apply
+ * `where*()`, additional middleware, or rename individual routes by indexing
+ * directly. The `update` PATCH alias is included as a separate builder
+ * immediately after its PUT counterpart.
+ */
+export class ResourceRegistration {
+    builders;
+    constructor(builders) {
+        this.builders = builders;
+    }
+}
+/**
+ * Returned by `router.singleton()`. Adds two opt-in helpers on top of
+ * `ResourceRegistration` for resources that also expose a creation flow
+ * (`.creatable()`) or deletion flow (`.destroyable()`).
+ */
+export class SingletonRegistration extends ResourceRegistration {
+    _router;
+    _name;
+    _Ctrl;
+    _opts;
+    constructor(builders, _router, _name, _Ctrl, _opts) {
+        super(builders);
+        this._router = _router;
+        this._name = _name;
+        this._Ctrl = _Ctrl;
+        this._opts = _opts;
+    }
+    /**
+     * Add `GET /<name>/create` and `POST /<name>` — the create/store half of a
+     * full resource. Skipped for any verb the controller doesn't implement.
+     */
+    creatable() {
+        const reg = this._router._registerResource(this._name, this._Ctrl, SINGLETON_CREATE_VERBS, this._opts);
+        this.builders.push(...reg.builders);
+        return this;
+    }
+    /**
+     * Add `DELETE /<name>` — the destroy half of a full resource. Skipped if
+     * the controller doesn't implement `destroy()`.
+     */
+    destroyable() {
+        const reg = this._router._registerResource(this._name, this._Ctrl, SINGLETON_DESTROY_VERBS, this._opts);
+        this.builders.push(...reg.builders);
+        return this;
+    }
 }
 // ─── Global router instance ────────────────────────────────
 export const router = new Router();
@@ -237,7 +810,10 @@ export function route(name, params = {}) {
     if (path === undefined)
         throw new Error(`[RudderJS] Named route "${name}" is not defined.`);
     const used = new Set();
-    let result = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\?)?/g, (_match, key, optional) => {
+    // Strip `:param{regex}` constraint segments before substitution so the
+    // simple param-name regex doesn't get confused by nested braces (UUID's
+    // `[0-9a-f]{8}-...{12}` etc.).
+    let result = stripRegexSegments(path).replace(/:([a-zA-Z_][a-zA-Z0-9_]*)(\?)?/g, (_match, key, optional) => {
         if (key in params) {
             used.add(key);
             return String(params[key]);