@adonisjs/http-server 8.0.0-next.9 → 8.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/build/chunk-B2GA45YG.js +35 -0
  2. package/build/define_config-t7GL92UR.js +5470 -0
  3. package/build/factories/http_context.d.ts +10 -4
  4. package/build/factories/main.d.ts +2 -2
  5. package/build/factories/main.js +328 -345
  6. package/build/factories/request.d.ts +4 -4
  7. package/build/factories/response.d.ts +4 -4
  8. package/build/factories/router.d.ts +1 -1
  9. package/build/factories/server_factory.d.ts +1 -1
  10. package/build/factories/url_builder_factory.d.ts +3 -3
  11. package/build/helpers-XD4_pfkD.js +108 -0
  12. package/build/helpers-aa47NQc6.js +1426 -0
  13. package/build/index.d.ts +2 -2
  14. package/build/index.js +330 -373
  15. package/build/src/client/helpers.d.ts +37 -0
  16. package/build/src/client/types.d.ts +194 -0
  17. package/build/src/client/url_builder.d.ts +15 -0
  18. package/build/src/client/url_builder.js +131 -0
  19. package/build/src/cookies/client.d.ts +28 -5
  20. package/build/src/cookies/drivers/encrypted.d.ts +1 -1
  21. package/build/src/cookies/drivers/signed.d.ts +1 -1
  22. package/build/src/cookies/parser.d.ts +1 -1
  23. package/build/src/cookies/serializer.d.ts +2 -2
  24. package/build/src/debug.d.ts +14 -1
  25. package/build/src/define_config.d.ts +19 -1
  26. package/build/src/define_middleware.d.ts +19 -3
  27. package/build/src/errors.d.ts +60 -5
  28. package/build/src/exception_handler.d.ts +28 -8
  29. package/build/src/helpers.d.ts +5 -17
  30. package/build/src/helpers.js +4 -24
  31. package/build/src/http_context/main.d.ts +67 -17
  32. package/build/src/qs.d.ts +17 -3
  33. package/build/src/redirect.d.ts +22 -3
  34. package/build/src/request.d.ts +12 -5
  35. package/build/src/response.d.ts +5 -5
  36. package/build/src/response_status.d.ts +14 -0
  37. package/build/src/router/main.d.ts +6 -2
  38. package/build/src/router/route.d.ts +130 -32
  39. package/build/src/router/signed_url_builder.d.ts +1 -1
  40. package/build/src/server/main.d.ts +6 -6
  41. package/build/src/types/main.js +2 -0
  42. package/build/src/types/request.d.ts +2 -1
  43. package/build/src/types/response.d.ts +6 -1
  44. package/build/src/types/route.d.ts +3 -27
  45. package/build/src/types/url_builder.d.ts +2 -140
  46. package/build/src/utils.d.ts +71 -6
  47. package/package.json +57 -48
  48. package/build/chunk-CVZAIRWJ.js +0 -1222
  49. package/build/chunk-JD6QW4NQ.js +0 -4428
  50. package/build/src/router/url_builder.d.ts +0 -9
@@ -3,16 +3,29 @@ import type { Level } from '@adonisjs/logger/types';
3
3
  import type { HttpContext } from './http_context/main.ts';
4
4
  import type { HttpError, StatusPageRange, StatusPageRenderer } from './types/server.ts';
5
5
  /**
6
- * The base HTTP exception handler one can inherit from to handle
7
- * HTTP exceptions.
6
+ * The base HTTP exception handler that provides comprehensive error handling capabilities.
8
7
  *
9
- * The HTTP exception handler has support for
8
+ * This class can be inherited to create custom exception handlers for your application.
9
+ * It provides built-in support for:
10
10
  *
11
- * - Ability to render exceptions by calling the render method on the exception.
12
- * - Rendering status pages
13
- * - Pretty printing errors during development
14
- * - Transforming errors to JSON or HTML using content negotiation
15
- * - Reporting errors
11
+ * - Self-handling exceptions via their own render/handle methods
12
+ * - Custom status page rendering for different HTTP error codes
13
+ * - Debug-friendly error display during development
14
+ * - Content negotiation for JSON, JSON API, and HTML error responses
15
+ * - Configurable error reporting and logging
16
+ * - Validation error handling with field-specific messages
17
+ *
18
+ * @example
19
+ * ```ts
20
+ * export default class HttpExceptionHandler extends ExceptionHandler {
21
+ * protected debug = app.inDev
22
+ * protected renderStatusPages = app.inProduction
23
+ *
24
+ * protected statusPages = {
25
+ * '404': (error, ctx) => ctx.view.render('errors/404')
26
+ * }
27
+ * }
28
+ * ```
16
29
  */
17
30
  export declare class ExceptionHandler extends Macroable {
18
31
  #private;
@@ -53,6 +66,13 @@ export declare class ExceptionHandler extends Macroable {
53
66
  * Errors with these codes are handled but not logged
54
67
  */
55
68
  protected ignoreCodes: string[];
69
+ /**
70
+ * Normalizes any thrown value into a standardized HttpError object
71
+ * Ensures the error has required properties like message and status
72
+ * @param error - Any thrown value (Error, string, object, etc.)
73
+ * @returns {HttpError} Normalized error object with status and message
74
+ */
75
+ protected toHttpError(error: unknown): HttpError;
56
76
  /**
57
77
  * Provides additional context information for error reporting
58
78
  * Includes request ID when available for correlation across logs
@@ -1,9 +1,11 @@
1
- import { type Encryption } from '@adonisjs/encryption';
1
+ import { type Encryption } from '@boringnode/encryption';
2
+ import { type Qs } from './qs.ts';
3
+ import { createURL } from './client/helpers.ts';
2
4
  import { type CookieOptions } from './types/response.ts';
3
- import { type SignedURLOptions, type URLOptions } from './types/url_builder.ts';
5
+ import { type SignedURLOptions } from './types/url_builder.ts';
4
6
  import type { RouteMatchers, RouteJSON, MatchItRouteToken } from './types/route.ts';
5
7
  import { type MiddlewareFn, type RouteHandlerInfo, type MiddlewareHandlerInfo, type ParsedGlobalMiddleware, type ParsedNamedMiddleware } from './types/middleware.ts';
6
- import { type Qs } from './qs.ts';
8
+ export { createURL };
7
9
  /**
8
10
  * This function is similar to the intrinsic function encodeURI. However, it will not encode:
9
11
  * - The \, ^, or | characters
@@ -43,20 +45,6 @@ export { default as mime } from 'mime-types';
43
45
  * @returns {MatchItRouteToken[]} Array of parsed route tokens
44
46
  */
45
47
  export declare function parseRoute(pattern: string, matchers?: RouteMatchers): MatchItRouteToken[];
46
- /**
47
- * Makes URL for a given route pattern using its parsed tokens. The
48
- * tokens could be generated using the "parseRoute" method.
49
- *
50
- * @param pattern - The route pattern
51
- * @param tokens - Array of parsed route tokens
52
- * @param searchParamsStringifier - Function to stringify query parameters
53
- * @param params - Route parameters as array or object
54
- * @param options - URL options
55
- * @returns {string} The generated URL
56
- */
57
- export declare function createURL(pattern: string, tokens: Pick<MatchItRouteToken, 'val' | 'type' | 'end'>[], searchParamsStringifier: (qs: Record<string, any>) => string, params?: any[] | {
58
- [param: string]: any;
59
- }, options?: URLOptions): string;
60
48
  /**
61
49
  * Makes signed URL for a given route pattern using its parsed tokens. The
62
50
  * tokens could be generated using the "parseRoute" method.
@@ -1,24 +1,4 @@
1
- import {
2
- appendQueryString,
3
- createSignedURL,
4
- createURL,
5
- default as default2,
6
- default2 as default3,
7
- matchRoute,
8
- middlewareInfo,
9
- parseRoute,
10
- routeInfo,
11
- serializeCookie
12
- } from "../chunk-CVZAIRWJ.js";
13
- export {
14
- appendQueryString,
15
- createSignedURL,
16
- createURL,
17
- default2 as encodeUrl,
18
- matchRoute,
19
- middlewareInfo,
20
- default3 as mime,
21
- parseRoute,
22
- routeInfo,
23
- serializeCookie
24
- };
1
+ import "../chunk-B2GA45YG.js";
2
+ import { a as middlewareInfo, c as routeInfo, i as matchRoute, l as serializeCookie, n as createSignedURL, o as mime, r as encodeUrl, s as parseRoute, t as appendQueryString } from "../helpers-aa47NQc6.js";
3
+ import { t as createURL } from "../helpers-XD4_pfkD.js";
4
+ export { appendQueryString, createSignedURL, createURL, encodeUrl, matchRoute, middlewareInfo, mime, parseRoute, routeInfo, serializeCookie };
@@ -1,36 +1,86 @@
1
1
  import Macroable from '@poppinss/macroable';
2
2
  import type { Logger } from '@adonisjs/logger';
3
3
  import { type ContainerResolver } from '@adonisjs/fold';
4
- import type { Request } from '../request.ts';
5
- import type { Response } from '../response.ts';
4
+ import type { HttpRequest } from '../request.ts';
5
+ import type { HttpResponse } from '../response.ts';
6
6
  import type { RouteJSON } from '../types/route.ts';
7
7
  /**
8
- * Http context encapsulates properties for a given HTTP request. The
9
- * context class can be extended using macros and getters.
8
+ * HTTP context encapsulates all properties and services for a given HTTP request.
9
+ *
10
+ * The HttpContext class serves as the central hub for request-specific data and services.
11
+ * It provides access to the request, response, route information, container resolver,
12
+ * and logger instances. The context can be extended using macros and getters for
13
+ * application-specific functionality.
14
+ *
15
+ * @example
16
+ * ```ts
17
+ * export default class UsersController {
18
+ * async show({ request, response, params }: HttpContext) {
19
+ * const user = await User.find(params.id)
20
+ * return response.json(user)
21
+ * }
22
+ * }
23
+ * ```
10
24
  */
11
25
  export declare class HttpContext extends Macroable {
12
- request: Request;
13
- response: Response;
26
+ request: HttpRequest;
27
+ response: HttpResponse;
14
28
  logger: Logger;
15
29
  containerResolver: ContainerResolver<any>;
16
30
  /**
17
- * Find if async localstorage is enabled for HTTP requests
18
- * or not
31
+ * Indicates whether async local storage is enabled for HTTP requests.
32
+ *
33
+ * When enabled, the HTTP context is automatically available within the
34
+ * scope of request processing through static methods like get() and getOrFail().
19
35
  */
20
36
  static get usingAsyncLocalStorage(): boolean;
21
37
  /**
22
- * Get access to the HTTP context. Available only when
23
- * "usingAsyncLocalStorage" is true
38
+ * Get access to the current HTTP context from async local storage.
39
+ *
40
+ * This method is only available when async local storage is enabled.
41
+ * Returns null if called outside of an HTTP request context.
42
+ *
43
+ * @example
44
+ * ```ts
45
+ * const ctx = HttpContext.get()
46
+ * if (ctx) {
47
+ * console.log(ctx.request.url())
48
+ * }
49
+ * ```
24
50
  */
25
51
  static get(): HttpContext | null;
26
52
  /**
27
- * Get the HttpContext instance or raise an exception if not
28
- * available
53
+ * Get the HttpContext instance or raise an exception if not available.
54
+ *
55
+ * This method is useful when you need guaranteed access to the HTTP context
56
+ * and want to fail fast if it's not available.
57
+ *
58
+ * @throws RuntimeException when async local storage is disabled or context is unavailable
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * const ctx = HttpContext.getOrFail()
63
+ * const userId = ctx.request.input('user_id')
64
+ * ```
29
65
  */
30
66
  static getOrFail(): HttpContext;
31
67
  /**
32
- * Run a method that doesn't have access to HTTP context from
33
- * the async local storage.
68
+ * Run a method outside of the HTTP context scope.
69
+ *
70
+ * This method allows you to execute code that should not have access to
71
+ * the current HTTP context from async local storage. Useful for background
72
+ * tasks or operations that should be context-independent.
73
+ *
74
+ * @param callback - Function to execute outside the context
75
+ * @param args - Arguments to pass to the callback
76
+ *
77
+ * @example
78
+ * ```ts
79
+ * HttpContext.runOutsideContext(() => {
80
+ * // This code cannot access HttpContext.get()
81
+ * performBackgroundTask()
82
+ * })
83
+ * ```
34
84
  */
35
85
  static runOutsideContext<T>(callback: (...args: any[]) => T, ...args: any[]): T;
36
86
  /**
@@ -53,12 +103,12 @@ export declare class HttpContext extends Macroable {
53
103
  /**
54
104
  * Creates a new HttpContext instance
55
105
  *
56
- * @param {Request} request - The HTTP request instance
57
- * @param {Response} response - The HTTP response instance
106
+ * @param {HttpRequest} request - The HTTP request instance
107
+ * @param {HttpResponse} response - The HTTP response instance
58
108
  * @param {Logger} logger - The logger instance
59
109
  * @param {ContainerResolver<any>} containerResolver - The IoC container resolver
60
110
  */
61
- constructor(request: Request, response: Response, logger: Logger, containerResolver: ContainerResolver<any>);
111
+ constructor(request: HttpRequest, response: HttpResponse, logger: Logger, containerResolver: ContainerResolver<any>);
62
112
  /**
63
113
  * A helper to see top level properties on the context object
64
114
  */
package/build/src/qs.d.ts CHANGED
@@ -1,7 +1,21 @@
1
1
  import { type QSParserConfig } from './types/qs.ts';
2
2
  /**
3
- * Query string parser used to parse and stringify query
4
- * strings.
3
+ * Query string parser that provides methods to parse and stringify query strings.
4
+ *
5
+ * This class wraps the popular 'qs' package with configurable options for parsing
6
+ * and stringifying query parameters. It allows customization of array handling,
7
+ * depth limits, and encoding behavior.
8
+ *
9
+ * @example
10
+ * ```ts
11
+ * const qs = new Qs({
12
+ * parse: { depth: 5, arrayLimit: 20 },
13
+ * stringify: { encode: false, skipNulls: true }
14
+ * })
15
+ *
16
+ * const parsed = qs.parse('users[0][name]=john&users[0][age]=25')
17
+ * const stringified = qs.stringify({ users: [{ name: 'john', age: 25 }] })
18
+ * ```
5
19
  */
6
20
  export declare class Qs {
7
21
  #private;
@@ -15,7 +29,7 @@ export declare class Qs {
15
29
  * @param value - Query string to parse (e.g., "foo=bar&baz=qux")
16
30
  * @returns Parsed object representation of the query string
17
31
  */
18
- parse: (value: string) => import("qs").ParsedQs;
32
+ parse: (value: string) => import("@poppinss/qs").ParsedQs;
19
33
  /**
20
34
  * Converts a JavaScript object into a query string using the configured options
21
35
  * @param value - Object to convert to query string
@@ -1,10 +1,29 @@
1
1
  import type { IncomingMessage } from 'node:http';
2
2
  import type { Qs } from './qs.ts';
3
- import type { Response } from './response.ts';
4
3
  import type { Router } from './router/main.ts';
4
+ import type { HttpResponse } from './response.ts';
5
5
  import type { RoutesList, LookupList, URLOptions, GetRoutesForMethod, RouteBuilderArguments } from './types/url_builder.ts';
6
6
  /**
7
- * Exposes the API to construct redirect routes
7
+ * Provides a fluent API for constructing HTTP redirect responses.
8
+ *
9
+ * The Redirect class allows you to build redirects with custom status codes,
10
+ * query string forwarding, and route-based URL generation. It supports both
11
+ * direct URL redirects and route-based redirects using registered route names.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * // Basic redirect
16
+ * return response.redirect('https://example.com')
17
+ *
18
+ * // Redirect to a route
19
+ * return response.redirect().toRoute('users.show', { id: 1 })
20
+ *
21
+ * // Redirect with status code and query string
22
+ * return response.redirect()
23
+ * .status(301)
24
+ * .withQs({ utm_source: 'newsletter' })
25
+ * .toPath('/dashboard')
26
+ * ```
8
27
  */
9
28
  export declare class Redirect {
10
29
  #private;
@@ -15,7 +34,7 @@ export declare class Redirect {
15
34
  * @param router - AdonisJS router instance
16
35
  * @param qs - Query string parser instance
17
36
  */
18
- constructor(request: IncomingMessage, response: Response, router: Router, qs: Qs);
37
+ constructor(request: IncomingMessage, response: HttpResponse, router: Router, qs: Qs);
19
38
  /**
20
39
  * Sets a custom HTTP status code for the redirect response
21
40
  * @param statusCode - HTTP status code to use (e.g., 301, 302, 307)
@@ -1,5 +1,5 @@
1
1
  import Macroable from '@poppinss/macroable';
2
- import type { Encryption } from '@adonisjs/encryption';
2
+ import type { Encryption } from '@boringnode/encryption';
3
3
  import { type ServerResponse, type IncomingMessage, type IncomingHttpHeaders } from 'node:http';
4
4
  import type { Qs } from './qs.ts';
5
5
  import { type RequestConfig } from './types/request.ts';
@@ -13,7 +13,7 @@ import type { HttpContext } from './http_context/main.ts';
13
13
  * You can access the original [IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
14
14
  * using `request.request` property.
15
15
  */
16
- export declare class Request extends Macroable {
16
+ export declare class HttpRequest extends Macroable {
17
17
  #private;
18
18
  /** Native Node.js incoming message instance */
19
19
  request: IncomingMessage;
@@ -48,9 +48,16 @@ export declare class Request extends Macroable {
48
48
  /** Native Node.js server response instance */
49
49
  response: ServerResponse, encryption: Encryption, config: RequestConfig, qsParser: Qs);
50
50
  /**
51
- * Returns the request id from the `x-request-id` header. The
52
- * header is untouched, if it already exists.
53
- * @returns The request ID or undefined if not found/generated
51
+ * Returns the request ID from the `x-request-id` header.
52
+ *
53
+ * If the header doesn't exist and request ID generation is enabled,
54
+ * a new UUID will be generated and added to the request headers.
55
+ *
56
+ * @example
57
+ * ```ts
58
+ * const requestId = request.id()
59
+ * console.log(requestId) // '550e8400-e29b-41d4-a716-446655440000'
60
+ * ```
54
61
  */
55
62
  id(): string | undefined;
56
63
  /**
@@ -1,5 +1,5 @@
1
1
  import Macroable from '@poppinss/macroable';
2
- import type { Encryption } from '@adonisjs/encryption';
2
+ import type { Encryption } from '@boringnode/encryption';
3
3
  import { type ServerResponse, type IncomingMessage } from 'node:http';
4
4
  import type { Qs } from './qs.ts';
5
5
  import { Redirect } from './redirect.ts';
@@ -19,7 +19,7 @@ import type { CastableHeader, CookieOptions, ResponseConfig, ResponseStream } fr
19
19
  * response.download('/path/to/file.pdf')
20
20
  * ```
21
21
  */
22
- export declare class Response extends Macroable {
22
+ export declare class HttpResponse extends Macroable {
23
23
  #private;
24
24
  request: IncomingMessage;
25
25
  response: ServerResponse;
@@ -46,7 +46,7 @@ export declare class Response extends Macroable {
46
46
  /**
47
47
  * The readable stream instance configured for the response
48
48
  */
49
- get outgoingStream(): import("stream").Readable | undefined;
49
+ get outgoingStream(): ResponseStream | undefined;
50
50
  /**
51
51
  * Configuration for file streaming including path and etag generation flag
52
52
  */
@@ -159,14 +159,14 @@ export declare class Response extends Macroable {
159
159
  * @param key - Header name
160
160
  * @returns The header value
161
161
  */
162
- getHeader(key: string): import("http").OutgoingHttpHeader | undefined;
162
+ getHeader(key: string): import("node:http").OutgoingHttpHeader | undefined;
163
163
  /**
164
164
  * Gets all response headers as an object
165
165
  *
166
166
  * @returns Object containing all headers
167
167
  */
168
168
  getHeaders(): {
169
- [x: string]: import("http").OutgoingHttpHeader | undefined;
169
+ [x: string]: import("node:http").OutgoingHttpHeader | undefined;
170
170
  accept?: string | string[] | undefined;
171
171
  "accept-charset"?: string | string[] | undefined;
172
172
  "accept-encoding"?: string | string[] | undefined;
@@ -1,3 +1,17 @@
1
+ /**
2
+ * Standard HTTP response status codes organized as a constant object.
3
+ *
4
+ * This object provides named constants for all standard HTTP status codes,
5
+ * making code more readable and less error-prone when setting response statuses.
6
+ * The naming follows PascalCase convention for consistency with TypeScript conventions.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * response.status(ResponseStatus.NotFound)
11
+ * response.status(ResponseStatus.InternalServerError)
12
+ * response.status(ResponseStatus.Created)
13
+ * ```
14
+ */
1
15
  export declare const ResponseStatus: {
2
16
  readonly Continue: 100;
3
17
  readonly SwitchingProtocols: 101;
@@ -1,4 +1,4 @@
1
- import type { Encryption } from '@adonisjs/encryption';
1
+ import type { Encryption } from '@boringnode/encryption';
2
2
  import type { Application } from '@adonisjs/application';
3
3
  import type { Constructor, LazyImport } from '@poppinss/utils/types';
4
4
  import type { Qs } from '../qs.ts';
@@ -249,7 +249,11 @@ export declare class Router {
249
249
  * @param indentation - Indentation level for generated types
250
250
  * @returns Generated TypeScript types as string
251
251
  */
252
- generateTypes(indentation?: number): string;
252
+ generateTypes(indentation?: number): {
253
+ imports: never[];
254
+ types: string[];
255
+ routes: string;
256
+ };
253
257
  /**
254
258
  * Find route for a given URL, method and optionally domain
255
259
  * @param uri - The URI to match
@@ -2,10 +2,27 @@ import Macroable from '@poppinss/macroable';
2
2
  import type { Application } from '@adonisjs/application';
3
3
  import type { Constructor, LazyImport, OneOrMore } from '@poppinss/utils/types';
4
4
  import type { MiddlewareFn, ParsedNamedMiddleware, ParsedGlobalMiddleware } from '../types/middleware.ts';
5
- import type { RouteFn, RouteJSON, RouteMatcher, RouteMatchers, StoreRouteMiddleware, GetControllerHandlers } from '../types/route.ts';
5
+ import type { RouteFn, RouteJSON, RouteMatcher, RouteMatchers, StoreRouteHandler, StoreRouteMiddleware, GetControllerHandlers } from '../types/route.ts';
6
6
  /**
7
- * The route class exposes the APIs for constructing a route using the
8
- * fluent API.
7
+ * The Route class provides a fluent API for constructing and configuring HTTP routes.
8
+ *
9
+ * Routes define how HTTP requests are handled by mapping URL patterns and HTTP methods
10
+ * to controller actions or inline handlers. This class supports middleware application,
11
+ * parameter validation, naming, and various other route-specific configurations.
12
+ *
13
+ * @example
14
+ * ```ts
15
+ * const route = new Route(app, middleware, {
16
+ * pattern: '/users/:id',
17
+ * methods: ['GET'],
18
+ * handler: 'UsersController.show'
19
+ * })
20
+ *
21
+ * route
22
+ * .where('id', /^[0-9]+$/)
23
+ * .middleware(['auth'])
24
+ * .as('users.show')
25
+ * ```
9
26
  */
10
27
  export declare class Route<Controller extends Constructor<any> = any> extends Macroable {
11
28
  #private;
@@ -22,79 +39,160 @@ export declare class Route<Controller extends Constructor<any> = any> extends Ma
22
39
  globalMatchers: RouteMatchers;
23
40
  });
24
41
  /**
25
- * Define matcher for a given param. If a matcher exists, then we do not
26
- * override that, since the routes inside a group will set matchers
27
- * before the group, so they should have priority over the group
28
- * matchers.
42
+ * Returns the route's handler configuration object.
43
+ */
44
+ getHandler(): StoreRouteHandler;
45
+ /**
46
+ * Defines a validation matcher for a route parameter. Route-level matchers
47
+ * take precedence over group-level matchers to ensure routes can override
48
+ * group constraints.
49
+ *
50
+ * @param param - The name of the route parameter to validate
51
+ * @param matcher - The validation pattern as a string, RegExp, or RouteMatcher object
29
52
  *
53
+ * @example
30
54
  * ```ts
55
+ * // Validate that 'id' is numeric
56
+ * route.where('id', /^[0-9]+$/)
57
+ *
58
+ * // Using a string pattern
59
+ * route.where('slug', '[a-z0-9-]+')
60
+ *
61
+ * // Route matcher takes precedence over group matcher
31
62
  * Route.group(() => {
32
63
  * Route.get('/:id', 'handler').where('id', /^[0-9]$/)
33
64
  * }).where('id', /[^a-z$]/)
65
+ * // The route's /^[0-9]$/ wins over the group's matcher
34
66
  * ```
35
- *
36
- * The `/^[0-9]$/` will win over the matcher defined by the group
37
67
  */
38
68
  where(param: string, matcher: RouteMatcher | string | RegExp): this;
39
69
  /**
40
- * Define prefix for the route. Calling this method multiple times
41
- * applies multiple prefixes in the reverse order.
42
- * @param prefix - The prefix to add to the route
43
- * @returns Current Route instance for method chaining
70
+ * Adds a URL prefix to the route pattern. Multiple calls stack prefixes
71
+ * which are applied in reverse order during pattern computation.
72
+ *
73
+ * @param prefix - The URL prefix to prepend to the route pattern
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * route.prefix('/api').prefix('/v1')
78
+ * // Results in pattern: /v1/api/users (for original pattern /users)
79
+ * ```
44
80
  */
45
81
  prefix(prefix: string): this;
46
82
  /**
47
- * Define a custom domain for the route. We do not overwrite the domain
48
- * unless `overwrite` flag is set to true.
83
+ * Assigns a custom domain to the route. By default, routes belong to the
84
+ * 'root' domain. Once set, the domain is not overwritten unless the
85
+ * overwrite flag is true.
86
+ *
87
+ * @param domain - The domain identifier for this route
88
+ * @param overwrite - Whether to overwrite an existing non-root domain
89
+ *
90
+ * @example
91
+ * ```ts
92
+ * route.domain('api.example.com')
93
+ *
94
+ * // Overwrite existing domain
95
+ * route.domain('new.example.com', true)
96
+ * ```
49
97
  */
50
98
  domain(domain: string, overwrite?: boolean): this;
51
99
  /**
52
- * Define one or more middleware to be executed before the route
53
- * handler.
100
+ * Registers one or more middleware to execute before the route handler.
101
+ * Middleware can be inline functions or named middleware references registered
102
+ * with the router's middleware store.
103
+ *
104
+ * @param middleware - Single middleware or array of middleware to apply
105
+ *
106
+ * @example
107
+ * ```ts
108
+ * // Single middleware
109
+ * route.use(async (ctx, next) => {
110
+ * console.log('Before handler')
111
+ * await next()
112
+ * })
54
113
  *
55
- * Named middleware can be referenced using the name registered with
56
- * the router middleware store.
114
+ * // Multiple middleware
115
+ * route.use(['auth', 'admin'])
116
+ * ```
57
117
  */
58
118
  use(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
59
119
  /**
60
- * Alias for {@link Route.use}
120
+ * Alias for the {@link Route.use} method.
121
+ *
122
+ * @param middleware - Single middleware or array of middleware to apply
61
123
  */
62
124
  middleware(middleware: OneOrMore<MiddlewareFn | ParsedNamedMiddleware>): this;
63
125
  /**
64
- * Give a unique name to the route. Assinging a new unique removes the
65
- * existing name of the route.
126
+ * Assigns a unique name to the route for use in URL generation and route
127
+ * referencing. Assigning a new name replaces any existing name unless
128
+ * prepend is true.
66
129
  *
67
- * Setting prepends to true prefixes the name to the existing name.
130
+ * @param name - The route name to assign
131
+ * @param prepend - If true, prepends the name to the existing name with a dot separator
132
+ *
133
+ * @example
134
+ * ```ts
135
+ * // Set route name
136
+ * route.as('users.show')
137
+ *
138
+ * // Prepend to existing name (typically used by route groups)
139
+ * route.as('admin', true) // Results in 'admin.users.show'
140
+ * ```
68
141
  */
69
142
  as(name: string, prepend?: boolean): this;
70
143
  /**
71
- * Check if the route was marked to be deleted
144
+ * Checks whether the route has been marked for deletion. Deleted routes
145
+ * are excluded from the route store during registration.
72
146
  */
73
147
  isDeleted(): boolean;
74
148
  /**
75
- * Mark route as deleted. Deleted routes are not registered
76
- * with the route store
149
+ * Marks the route for deletion. Deleted routes will not be registered
150
+ * with the route store when Router.commit() is called.
151
+ *
152
+ * @example
153
+ * ```ts
154
+ * const route = Route.get('/admin', 'handler')
155
+ * route.markAsDeleted()
156
+ * // This route will not be registered
157
+ * ```
77
158
  */
78
159
  markAsDeleted(): void;
79
160
  /**
80
- * Get the route name
161
+ * Returns the unique name assigned to the route, if any.
81
162
  */
82
163
  getName(): string | undefined;
83
164
  /**
84
- * Get the route pattern
165
+ * Returns the route's URL pattern with dynamic parameters.
85
166
  */
86
167
  getPattern(): string;
87
168
  /**
88
- * Set the route pattern
169
+ * Updates the route's URL pattern.
170
+ *
171
+ * @param pattern - The new URL pattern to assign to the route
172
+ *
173
+ * @example
174
+ * ```ts
175
+ * route.setPattern('/users/:id/posts/:postId')
176
+ * ```
89
177
  */
90
178
  setPattern(pattern: string): this;
91
179
  /**
92
- * Returns the stack of middleware registered on the route.
93
- * The value is shared by reference.
180
+ * Returns the multi-dimensional middleware stack registered on this route.
181
+ * The returned value is shared by reference, not a copy.
94
182
  */
95
183
  getMiddleware(): StoreRouteMiddleware[][];
96
184
  /**
97
- * Returns JSON representation of the route
185
+ * Serializes the route into a JSON representation suitable for storage and
186
+ * execution. This includes the computed pattern with prefixes, merged matchers,
187
+ * parsed route tokens, and frozen middleware stack.
188
+ *
189
+ * @example
190
+ * ```ts
191
+ * const json = route.toJSON()
192
+ * console.log(json.pattern) // '/api/users/:id'
193
+ * console.log(json.methods) // ['GET']
194
+ * console.log(json.name) // 'users.show'
195
+ * ```
98
196
  */
99
197
  toJSON(): RouteJSON;
100
198
  }
@@ -1,4 +1,4 @@
1
- import type { Encryption } from '@adonisjs/encryption';
1
+ import type { Encryption } from '@boringnode/encryption';
2
2
  import { type Router } from './main.ts';
3
3
  import { type UrlFor, type LookupList, type SignedURLOptions } from '../types/url_builder.ts';
4
4
  /**