@rudderjs/router 1.0.0 → 1.1.0

package/README.md

@@ -39,6 +39,33 @@ router.get('/invoices/:id/download', handler, [ValidateSignature()]).name('invoi
 
 ---
 
+## Parameter constraints (`where*()`)
+
+Constrain `:param` segments to a regex with Laravel-style `where*()` shortcuts. Internally, the path is rewritten to Hono's `:param{regex}` syntax so non-matching requests 404 before they reach the handler.
+
+```ts
+router.get('/users/:id', handler).whereNumber('id').name('users.show')
+router.get('/u/:id', handler).whereUuid('id')
+router.get('/posts/:status', handler).whereIn('status', ['draft', 'published'])
+router.get('/n/:n', handler).where('n', /\d{3,5}/)
+```
+
+| Method | Pattern |
+|--------|---------|
+| `where(param, regex)` | Custom — string or `RegExp` (uses `.source`) |
+| `whereNumber(param)` | `[0-9]+` |
+| `whereAlpha(param)` | `[A-Za-z]+` |
+| `whereAlphaNumeric(param)` | `[A-Za-z0-9]+` |
+| `whereUuid(param)` | UUID, any version |
+| `whereUlid(param)` | Crockford base32 ULID (26 chars) |
+| `whereIn(param, values)` | Alternation over regex-escaped literals |
+
+Chains in any order with `.name()`; calling another `where*()` for the same param overwrites. Throws if the route path has no `:param` segment. The patterns are also exported as constants — `ROUTE_PATTERN_NUMBER`, `ROUTE_PATTERN_ALPHA`, `ROUTE_PATTERN_ALPHANUM`, `ROUTE_PATTERN_UUID`, `ROUTE_PATTERN_ULID`.
+
+> Decorator routes (`@Get('/users/:id')`) don't return a `RouteBuilder`, so `where*()` is fluent-only in v1.
+
+---
+
 ## `route()` — URL generation
 
 Generate a URL from a named route. Route parameters are substituted; unused params are appended as a query string.
@@ -146,6 +173,176 @@ router.post('/admin', handler, [authMiddleware, adminMiddleware])
 
 ---
 
+## Route model binding
+
+Bind a `:param` segment to any class with a static `findForRoute(value)` method (a `@rudderjs/orm` Model is the canonical fit). Resolution runs as a prepended per-route middleware before your handler, exposing the result as `req.bound!.<name>`.
+
+```ts
+import { router } from '@rudderjs/router'
+import { User } from '../app/Models/User.js'
+
+router.bind('user', User)
+
+router.get('/users/:user', (req) => {
+  const user = req.bound!['user']  // a User instance, or 404 was thrown
+  return user
+})
+
+// Optional binding — null instead of 404 when missing
+router.bind('viewer', User, { optional: true })
+```
+
+Returning `null` from `findForRoute` triggers `RouteModelNotFoundError` (HTTP 404). The raw string remains in `req.params[name]` regardless. Routes whose path doesn't include a bound param are unaffected.
+
+The `RouteResolver` contract is duck-typed — `name: string` + `findForRoute(value): unknown | Promise<unknown | null>` — so the router doesn't depend on `@rudderjs/orm`.
+
+### Custom 404 with `.missing()`
+
+Override the default 404 response per route. Receives the request and the binding error; return a value the route handler may return — `Response`, plain object → JSON, string → body, or `undefined` (you wrote to `res` directly).
+
+```ts
+router.get('/users/:user', show)
+  .missing((_req, err) => Response.json({ error: err.message }, { status: 404 }))
+
+router.get('/posts/:post', show)
+  .missing((_req, err) => ({ message: `Post ${err.value} not found` }))    // → 200 JSON
+```
+
+Optional bindings do NOT trigger `.missing()` — they quietly resolve to `null` instead.
+
+---
+
+## Route groups (`router.group()`)
+
+Apply a `prefix`, `domain`, or shared `middleware` stack to every route registered inside the callback. Nested groups concatenate prefixes and middleware; the innermost defined `domain` wins (hosts can't compose).
+
+```ts
+import { router } from '@rudderjs/router'
+
+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
+})
+
+// Nested
+router.group({ prefix: '/api' }, () => {
+  router.group({ prefix: '/v1', middleware: [throttle] }, () => {
+    router.get('/users', listUsers)          // GET /api/v1/users (with throttle)
+  })
+})
+```
+
+`router.group()` is the user-facing scoping primitive. Distinct from `runWithGroup('web' | 'api', …)` — that tags routes with their middleware-group label and is called once by the framework's route loader. Both can be active at the same time.
+
+---
+
+## Subdomain routing (`.domain()`)
+
+Restrict a route to a specific host. The template is matched against the request's `Host` header (port stripped, case-insensitive); `:param` segments capture into `req.params` alongside path params.
+
+```ts
+router.get('/users', listUsers).domain('api.example.com')
+router.get('/me', me).domain(':tenant.example.com')
+// req.params.tenant === 'acme' for Host: acme.example.com
+
+router.group({ domain: 'admin.example.com', middleware: [adminAuth] }, () => {
+  router.get('/dashboard', dash)             // GET admin.example.com/dashboard
+})
+```
+
+Mismatched hosts return 404. Subdomain `:param` and path `:param` of the same name collide — path wins.
+
+---
+
+## Resource controllers (`router.resource()`)
+
+Wire the seven canonical CRUD routes from a plain controller class — Laravel's `Route::resource` for RudderJS. No decorators; methods are matched by name.
+
+```ts
+import { router } from '@rudderjs/router'
+
+class PostController {
+  async index   (_ctx) { /* GET    /posts            → list   */ }
+  async create  (_ctx) { /* GET    /posts/create     → form   */ }
+  async store   (_ctx) { /* POST   /posts            → persist */ }
+  async show    (_ctx) { /* GET    /posts/:post      → one    */ }
+  async edit    (_ctx) { /* GET    /posts/:post/edit → form   */ }
+  async update  (_ctx) { /* PUT|PATCH /posts/:post   → update */ }
+  async destroy (_ctx) { /* DELETE /posts/:post      → delete */ }
+}
+
+router.resource('posts', PostController)
+```
+
+| Verb | Method | Path | Route name |
+|--------|--------|------|------------|
+| index   | `GET`    | `/posts`            | `posts.index`   |
+| create  | `GET`    | `/posts/create`     | `posts.create`  |
+| store   | `POST`   | `/posts`            | `posts.store`   |
+| show    | `GET`    | `/posts/:post`      | `posts.show`    |
+| edit    | `GET`    | `/posts/:post/edit` | `posts.edit`    |
+| update  | `PUT`+`PATCH` | `/posts/:post` | `posts.update` |
+| destroy | `DELETE` | `/posts/:post`      | `posts.destroy` |
+
+Methods the controller doesn't implement are silently skipped, so partial controllers work with no `only`/`except` boilerplate.
+
+### `apiResource()` — drops the HTML form pages
+
+```ts
+router.apiResource('posts', PostController)
+// no posts.create, no posts.edit
+```
+
+### `singleton()` — for "the one of these"
+
+```ts
+router.singleton('profile', ProfileController)
+// GET    /profile          posts.show (named profile.show)
+// GET    /profile/edit     profile.edit
+// PUT    /profile          profile.update
+// PATCH  /profile          (alias)
+
+router.singleton('profile', ProfileController).creatable()    // adds GET /profile/create + POST /profile
+router.singleton('profile', ProfileController).destroyable()  // adds DELETE /profile
+```
+
+### Options
+
+```ts
+router.resource('posts', PostController, {
+  only:       ['index', 'show'],
+  except:     ['destroy'],
+  parameters: { posts: 'article' },        // /posts/:article instead of /posts/:post
+  names:      { show: 'posts.detail' },
+  middleware: [authMw],
+})
+```
+
+### Per-route customisation via `.builders[]`
+
+The registration object exposes the underlying `RouteBuilder[]` — apply `where*()`, additional `.middleware()`, or rename one route in isolation:
+
+```ts
+const reg = router.resource('posts', PostController)
+reg.builders[3].whereNumber('post')       // constrain show route only
+```
+
+Builders are in declaration order: `index`, `create`, `store`, `show`, `edit`, `update` (PUT), `update` (PATCH alias), `destroy` — minus any verb the controller skipped.
+
+### Scaffolder
+
+```bash
+pnpm rudder make:controller PostController --resource    # full 7-verb stub
+pnpm rudder make:controller PostController --api         # API-only (no create/edit)
+pnpm rudder make:controller ProfileController --singleton
+```
+
+---
+
 ## Mounting onto a server adapter
 
 ```ts
@@ -169,20 +366,35 @@ router.mount(serverAdapter)
 | `all(path, handler, mw?)` | `RouteBuilder` | Register route matching any method |
 | `add(method, path, handler, mw?)` | `this` | Register route with explicit method |
 | `use(middleware)` | `this` | Register global middleware |
+| `bind(name, resolver, opts?)` | `this` | Bind a `:param` to a `RouteResolver` (e.g. an ORM Model) for auto-resolution |
+| `listBindings()` | `Record<string, RouteResolver>` | All registered route bindings |
+| `group(opts, fn)` | `this` | Apply prefix/domain/middleware to every route registered inside `fn` |
+| `resource(name, Ctrl, opts?)` | `ResourceRegistration` | Register the seven canonical RESTful routes |
+| `apiResource(name, Ctrl, opts?)` | `ResourceRegistration` | Resource minus `create`/`edit` |
+| `singleton(name, Ctrl, opts?)` | `SingletonRegistration` | `show`/`edit`/`update` for a single-instance resource |
 | `registerController(Class)` | `this` | Register decorator-based controller |
 | `mount(serverAdapter)` | `void` | Apply middleware + routes to adapter |
 | `list()` | `RouteDefinition[]` | All registered routes |
 | `listNamed()` | `Record<string, string>` | All named routes |
 | `getNamedRoute(name)` | `string \| undefined` | Path for a named route |
-| `reset()` | `this` | Clear routes, middleware, and named routes |
+| `reset()` | `this` | Clear routes, middleware, named routes, and bindings |
 
 ### `RouteBuilder`
 
-Returned by the shorthand route methods. Allows naming the registered route.
+Returned by the shorthand route methods. Allows naming the registered route and constraining `:param` segments.
 
 | Method | Description |
 |--------|-------------|
 | `.name(n)` | Assign a name to the route |
+| `.where(param, regex)` | Constrain `:param` to a custom regex (string or `RegExp`) |
+| `.whereNumber(param)` | Shortcut for `[0-9]+` |
+| `.whereAlpha(param)` | Shortcut for `[A-Za-z]+` |
+| `.whereAlphaNumeric(param)` | Shortcut for `[A-Za-z0-9]+` |
+| `.whereUuid(param)` | Shortcut for any-version UUID |
+| `.whereUlid(param)` | Shortcut for Crockford base32 ULID |
+| `.whereIn(param, values)` | Constrain `:param` to one of the supplied literals |
+| `.domain(template)` | Restrict to a host; `:param` segments capture into `req.params` |
+| `.missing(fn)` | Custom 404 callback when an explicit binding fails to resolve |
 
 ### `Url`
 

package/boost/guidelines.md

@@ -34,6 +34,59 @@ route('posts.show', { slug: 'hello' })    // optional ':id?' segment omitted
 
 Throws if a required parameter is missing or the name is not registered.
 
+### Parameter constraints
+
+```ts
+import { Route } from '@rudderjs/router'
+
+Route.get('/users/:id', handler).whereNumber('id').name('users.show')
+Route.get('/u/:id', handler).whereUuid('id')
+Route.get('/posts/:status', handler).whereIn('status', ['draft', 'published'])
+Route.get('/n/:n', handler).where('n', /\d{3,5}/)
+```
+
+Available shortcuts: `whereNumber` / `whereAlpha` / `whereAlphaNumeric` / `whereUuid` / `whereUlid` / `whereIn(param, values)`. Base method `.where(param, regex)` accepts a string or `RegExp`. Throws when the path has no `:param` segment, or when `whereIn` gets an empty values array. Order-independent against `.name()`.
+
+> Fluent-only — decorator routes (`@Get('/users/:id')`) don't return a `RouteBuilder`.
+
+### Route groups
+
+```ts
+import { router } from '@rudderjs/router'
+
+router.group({ prefix: '/admin', middleware: [adminAuth] }, () => {
+  router.get('/users', listUsers)            // GET /admin/users (with adminAuth)
+})
+
+router.group({ domain: ':tenant.example.com', prefix: '/api' }, () => {
+  router.get('/me', me)                      // GET :tenant.example.com/api/me
+})
+```
+
+Nested groups concatenate prefixes and middleware; innermost defined `domain` wins. `router.group()` is the user-facing scoping primitive — distinct from `runWithGroup('web' | 'api', …)` (the framework's web/api middleware-group tag).
+
+### Subdomain routing
+
+```ts
+router.get('/users', listUsers).domain('api.example.com')
+router.get('/me', me).domain(':tenant.example.com')
+// req.params.tenant === 'acme' for Host: acme.example.com
+```
+
+Mismatched hosts return 404. Subdomain `:param` and path `:param` of the same name collide — path wins.
+
+### Route binding 404 customisation
+
+```ts
+router.get('/users/:user', show)
+  .missing((_req, err) => Response.json({ error: err.message }, { status: 404 }))
+
+router.get('/posts/:post', show)
+  .missing((_req, err) => ({ message: `Post ${err.value} not found` }))
+```
+
+Returns: `Response`, plain object → JSON, string → body, or `undefined` (callback wrote to `res` directly). Optional bindings do NOT trigger `.missing()`.
+
 ### Route-level middleware
 
 ```ts

package/dist/index.d.ts

@@ -12,11 +12,22 @@ export declare const Put: (path?: string) => MethodDecorator;
 export declare const Patch: (path?: string) => MethodDecorator;
 export declare const Delete: (path?: string) => MethodDecorator;
 export declare const Options: (path?: string) => MethodDecorator;
+/** Matches one or more digits — `[0-9]+`. */
+export declare const ROUTE_PATTERN_NUMBER = "[0-9]+";
+/** Matches one or more ASCII letters — `[A-Za-z]+`. */
+export declare const ROUTE_PATTERN_ALPHA = "[A-Za-z]+";
+/** Matches one or more ASCII letters or digits — `[A-Za-z0-9]+`. */
+export declare const ROUTE_PATTERN_ALPHANUM = "[A-Za-z0-9]+";
+/** Matches a UUID of any version (case-insensitive). */
+export declare 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 declare const ROUTE_PATTERN_ULID = "[0-7][0-9A-HJKMNP-TV-Z]{25}";
 /**
- * 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 declare class RouteBuilder {
@@ -25,14 +36,124 @@ export declare class RouteBuilder {
     constructor(definition: RouteDefinition, _router: Router);
     /** Assign a name to this route for use with `route()` and `Url.signedRoute()`. */
     name(n: string): 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: string, regex: string | RegExp): this;
+    /** Constrain `:param` to one or more digits. */
+    whereNumber(param: string): this;
+    /** Constrain `:param` to one or more ASCII letters. */
+    whereAlpha(param: string): this;
+    /** Constrain `:param` to one or more ASCII letters or digits. */
+    whereAlphaNumeric(param: string): this;
+    /** Constrain `:param` to a UUID of any version. */
+    whereUuid(param: string): this;
+    /** Constrain `:param` to a Crockford base32 ULID. */
+    whereUlid(param: string): this;
+    /**
+     * 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: string, values: readonly (string | number)[]): this;
+    /**
+     * 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: string): 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: NonNullable<RouteDefinition['missing']>): this;
+}
+/**
+ * Options accepted by `router.group(opts, fn)`. Each route registered inside
+ * `fn` inherits the prefix, domain, and middleware. Nested groups concatenate
+ * prefixes and middleware; the innermost defined `domain` wins (hosts can't
+ * compose). Distinct from `runWithGroup('web' | 'api', …)`, which only tags
+ * routes with their middleware-group label.
+ */
+export interface RouteGroupOptions {
+    /** Path prefix applied to every route registered in the group. */
+    prefix?: string;
+    /** Subdomain template applied to every route registered in the group. */
+    domain?: string;
+    /** Middleware prepended to every route's chain (before per-route middleware). */
+    middleware?: MiddlewareHandler[];
+}
+/**
+ * Duck-typed contract for any object that resolves a string route parameter
+ * into a value (typically a Model instance, but the router doesn't depend on
+ * `@rudderjs/orm` — anything with a static `findForRoute` method works).
+ *
+ * Returning `null` signals "not found" — the router maps that to a thrown
+ * `RouteModelNotFoundError`, which the framework's HTTP layer renders as a 404.
+ */
+export interface RouteResolver {
+    /** Owning class name — used for error messages only. */
+    name: string;
+    /** Resolve the raw param value. Return `null` for not-found. */
+    findForRoute(value: string): Promise<unknown | null> | unknown | null;
+}
+export interface RouteBindingOptions {
+    /**
+     * When `true`, an absent or unresolvable param value silently sets
+     * `req.bound[name] = null` instead of throwing. Useful for shared routes
+     * that may or may not have a logged-in subject.
+     */
+    optional?: boolean;
+}
+/**
+ * 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 declare class RouteModelNotFoundError extends Error {
+    readonly model: string;
+    readonly param: string;
+    readonly value: string;
+    /** Duck-typed signal to `@rudderjs/core`'s exception handler. */
+    readonly httpStatus = 404;
+    constructor(model: string, param: string, value: string);
 }
 export declare class Router {
     private routes;
     private globalMiddleware;
     private namedRoutes;
+    private bindings;
+    /**
+     * 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.
+     */
+    private _groupStack;
     /** @internal — called by RouteBuilder */
-    _registerName(name: string, path: string): void;
-    /** Look up a named route's path. */
+    _registerName(name: string, def: RouteDefinition): void;
+    /** Look up a named route's path. Reflects any `where*()` mutations. */
     getNamedRoute(name: string): string | undefined;
     /**
      * Check whether a named route is registered.
@@ -47,10 +168,77 @@ export declare class Router {
     has(name: string): boolean;
     /** All registered named routes. */
     listNamed(): Record<string, string>;
-    /** Clear registered routes, middleware, and named routes. */
+    /** Clear registered routes, middleware, named routes, and route bindings. */
     reset(): 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: RouteGroupOptions, fn: () => void): 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.
+     */
+    private _applyGroupStack;
     /** Register a global middleware (runs on every route). */
     use(middleware: MiddlewareHandler): 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: string, resolver: RouteResolver, options?: RouteBindingOptions): this;
+    /** All registered route bindings, keyed by param name. */
+    listBindings(): Record<string, RouteResolver>;
+    /**
+     * 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()`.
+     */
+    private _buildBindingMiddleware;
     /** Manually register a route. Returns `this` for bulk registration. */
     add(method: HttpMethod, path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): this;
     get(path: string, handler: RouteHandler, middleware?: MiddlewareHandler[]): RouteBuilder;
@@ -66,6 +254,107 @@ export declare class Router {
     mount(server: ServerAdapter): void;
     /** All registered routes — useful for `routes:list`. */
     list(): RouteDefinition[];
+    /**
+     * 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: string, Ctrl: new () => object, opts?: ResourceOptions): ResourceRegistration;
+    /**
+     * 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: string, Ctrl: new () => object, opts?: ResourceOptions): ResourceRegistration;
+    /**
+     * 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: string, Ctrl: new () => object, opts?: ResourceOptions): SingletonRegistration;
+    /** @internal — shared registration loop for resource/apiResource/singleton. */
+    _registerResource(name: string, Ctrl: new () => object, table: readonly ResourceVerbSpec[], opts: ResourceOptions): ResourceRegistration;
+}
+/** The seven canonical RESTful verbs Laravel's `Route::resource` exposes. */
+export type ResourceVerb = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+interface ResourceVerbSpec {
+    verb: ResourceVerb;
+    method: HttpMethod;
+    path: (name: string, param: string) => string;
+    nameSuffix: string;
+}
+/**
+ * Options accepted by `router.resource`/`apiResource`/`singleton`.
+ *
+ * - `only`/`except` — restrict the verbs registered.
+ * - `parameters` — override the `:param` segment name for a given resource
+ *   (e.g. `{ posts: 'article' }` → `/posts/:article`).
+ * - `names` — override the generated route names per verb.
+ * - `middleware` — applied to every route registered by the resource.
+ */
+export interface ResourceOptions {
+    only?: readonly ResourceVerb[];
+    except?: readonly ResourceVerb[];
+    parameters?: Record<string, string>;
+    names?: Partial<Record<ResourceVerb, string>>;
+    middleware?: MiddlewareHandler[];
+}
+/**
+ * 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 declare class ResourceRegistration {
+    readonly builders: RouteBuilder[];
+    constructor(builders: RouteBuilder[]);
+}
+/**
+ * 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 declare class SingletonRegistration extends ResourceRegistration {
+    private readonly _router;
+    private readonly _name;
+    private readonly _Ctrl;
+    private readonly _opts;
+    constructor(builders: RouteBuilder[], _router: Router, _name: string, _Ctrl: new () => object, _opts: ResourceOptions);
+    /**
+     * 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(): this;
+    /**
+     * Add `DELETE /<name>` — the destroy half of a full resource. Skipped if
+     * the controller doesn't implement `destroy()`.
+     */
+    destroyable(): this;
 }
 export declare const router: Router;
 /** Alias for router — Laravel-style capitalised name */
@@ -126,4 +415,5 @@ export declare class Url {
  * router.get('/invoice/:id/download', handler, [ValidateSignature()])
  */
 export declare function ValidateSignature(): MiddlewareHandler;
+export {};
 //# sourceMappingURL=index.d.ts.map