@adaptivestone/framework 5.0.1 → 5.1.1

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 (81) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/dist/commands/OpenApi.d.ts +26 -0
  3. package/dist/commands/OpenApi.js +101 -0
  4. package/dist/commands/OpenApi.js.map +1 -0
  5. package/dist/commands/Routes.d.ts +17 -0
  6. package/dist/commands/Routes.js +35 -0
  7. package/dist/commands/Routes.js.map +1 -0
  8. package/dist/config/cache.d.ts +14 -0
  9. package/dist/config/cache.js +14 -0
  10. package/dist/config/cache.js.map +1 -0
  11. package/dist/controllers/index.js +34 -4
  12. package/dist/controllers/index.js.map +1 -1
  13. package/dist/helpers/appInstance.d.ts +6 -0
  14. package/dist/helpers/appInstance.js +13 -0
  15. package/dist/helpers/appInstance.js.map +1 -1
  16. package/dist/modules/BaseModel.d.ts +10 -0
  17. package/dist/modules/BaseModel.js +25 -0
  18. package/dist/modules/BaseModel.js.map +1 -1
  19. package/dist/server.d.ts +20 -1
  20. package/dist/server.js +24 -1
  21. package/dist/server.js.map +1 -1
  22. package/dist/services/cache/Cache.d.ts +3 -4
  23. package/dist/services/cache/Cache.js +43 -34
  24. package/dist/services/cache/Cache.js.map +1 -1
  25. package/dist/services/cache/CacheDriver.d.ts +19 -0
  26. package/dist/services/cache/CacheDriver.js +2 -0
  27. package/dist/services/cache/CacheDriver.js.map +1 -0
  28. package/dist/services/cache/drivers/MemoryDriver.d.ts +14 -0
  29. package/dist/services/cache/drivers/MemoryDriver.js +40 -0
  30. package/dist/services/cache/drivers/MemoryDriver.js.map +1 -0
  31. package/dist/services/cache/drivers/RedisDriver.d.ts +22 -0
  32. package/dist/services/cache/drivers/RedisDriver.js +44 -0
  33. package/dist/services/cache/drivers/RedisDriver.js.map +1 -0
  34. package/dist/services/documentation/OpenApiGenerator.d.ts +39 -0
  35. package/dist/services/documentation/OpenApiGenerator.js +296 -0
  36. package/dist/services/documentation/OpenApiGenerator.js.map +1 -0
  37. package/dist/services/http/HttpServer.d.ts +23 -0
  38. package/dist/services/http/HttpServer.js +57 -0
  39. package/dist/services/http/HttpServer.js.map +1 -1
  40. package/dist/services/http/builtinErrorHandlers.d.ts +53 -0
  41. package/dist/services/http/builtinErrorHandlers.js +188 -0
  42. package/dist/services/http/builtinErrorHandlers.js.map +1 -0
  43. package/dist/services/http/httpErrors.d.ts +30 -0
  44. package/dist/services/http/httpErrors.js +46 -0
  45. package/dist/services/http/httpErrors.js.map +1 -0
  46. package/dist/services/http/middleware/AbstractMiddleware.d.ts +25 -7
  47. package/dist/services/http/middleware/AbstractMiddleware.js +14 -0
  48. package/dist/services/http/middleware/AbstractMiddleware.js.map +1 -1
  49. package/dist/services/http/middleware/GetUserByToken.d.ts +13 -0
  50. package/dist/services/http/middleware/GetUserByToken.js +5 -1
  51. package/dist/services/http/middleware/GetUserByToken.js.map +1 -1
  52. package/dist/services/http/middleware/RateLimiter.d.ts +8 -2
  53. package/dist/services/http/middleware/RateLimiter.js +38 -13
  54. package/dist/services/http/middleware/RateLimiter.js.map +1 -1
  55. package/dist/services/http/routing/RouteNode.d.ts +2 -0
  56. package/dist/services/validate/drivers/StandardSchemaDriver.d.ts +5 -2
  57. package/dist/services/validate/drivers/StandardSchemaDriver.js +24 -3
  58. package/dist/services/validate/drivers/StandardSchemaDriver.js.map +1 -1
  59. package/dist/services/validate/drivers/YupDriver.js +91 -2
  60. package/dist/services/validate/drivers/YupDriver.js.map +1 -1
  61. package/dist/services/validate/types.d.ts +7 -4
  62. package/dist/tests/globalSetupNodeTest.d.ts +2 -0
  63. package/dist/tests/globalSetupNodeTest.js +23 -0
  64. package/dist/tests/globalSetupNodeTest.js.map +1 -0
  65. package/dist/tests/globalSetupVitest.js +6 -13
  66. package/dist/tests/globalSetupVitest.js.map +1 -1
  67. package/dist/tests/nodeRunner.node-test.d.ts +14 -0
  68. package/dist/tests/nodeRunner.node-test.js +41 -0
  69. package/dist/tests/nodeRunner.node-test.js.map +1 -0
  70. package/dist/tests/nodeRunnerShared.node-test.d.ts +14 -0
  71. package/dist/tests/nodeRunnerShared.node-test.js +39 -0
  72. package/dist/tests/nodeRunnerShared.node-test.js.map +1 -0
  73. package/dist/tests/setupFramework.d.ts +33 -0
  74. package/dist/tests/setupFramework.js +134 -0
  75. package/dist/tests/setupFramework.js.map +1 -0
  76. package/dist/tests/setupNodeTest.d.ts +1 -0
  77. package/dist/tests/setupNodeTest.js +16 -0
  78. package/dist/tests/setupNodeTest.js.map +1 -0
  79. package/dist/tests/setupVitest.js +8 -99
  80. package/dist/tests/setupVitest.js.map +1 -1
  81. package/package.json +10 -3
@@ -0,0 +1,296 @@
1
+ /**
2
+ * OpenAPI 3.1 generator.
3
+ *
4
+ * Pure function: takes the flattened route list (`RouteRegistry.flatten()`) and
5
+ * emits an OpenAPI document. No CLI, no fs, no app boot — the `openapi` command
6
+ * (`src/commands/OpenApi.ts`) populates the registry and hands the routes here.
7
+ *
8
+ * Schema → JSON Schema goes through the validator driver seam
9
+ * (`ValidateService.resolve(schema).toJsonSchema`), so any vendor with
10
+ * introspection (zod native, yup `describe()`, arktype, or a user-registered
11
+ * driver) is documented; vendors without it degrade to a placeholder + warning.
12
+ * The same seam powers the future MCP surface — nothing here is OpenAPI-only
13
+ * throwaway.
14
+ */
15
+ import { isContentTypeRequestMap } from "../validate/contentType.js";
16
+ import ValidateService from "../validate/ValidateService.js";
17
+ /**
18
+ * Build an OpenAPI 3.1 document from flattened routes.
19
+ */
20
+ export async function generateOpenApi(routes, opts) {
21
+ const warn = opts.onWarning ?? (() => { });
22
+ const paths = {};
23
+ const securitySchemes = {};
24
+ const tagNames = new Set();
25
+ for (const route of routes) {
26
+ const { path, params: pathParams, hadSplat } = convertPath(route.path);
27
+ if (hadSplat) {
28
+ warn(`${route.method} ${route.path}: catch-all (*) approximated as a path parameter — OpenAPI has no catch-all.`);
29
+ }
30
+ const meta = route.entry.meta ?? {};
31
+ const tag = (meta.controllerClass ?? 'default').split('/')[0];
32
+ tagNames.add(tag);
33
+ const parameters = pathParams.map((name) => ({
34
+ name,
35
+ in: 'path',
36
+ required: true,
37
+ schema: { type: 'string' },
38
+ }));
39
+ const ctx = `${route.method} ${path}`;
40
+ parameters.push(...(await buildQueryParameters(route, warn, ctx)));
41
+ const operation = {
42
+ operationId: operationId(route, path),
43
+ tags: [tag],
44
+ responses: defaultResponses(),
45
+ };
46
+ if (meta.description) {
47
+ operation.summary = meta.description;
48
+ }
49
+ if (parameters.length > 0) {
50
+ operation.parameters = parameters;
51
+ }
52
+ const requestBody = await buildRequestBody(route, warn, ctx);
53
+ if (requestBody) {
54
+ operation.requestBody = requestBody;
55
+ }
56
+ const security = collectSecurity(route.middlewares, securitySchemes);
57
+ if (security.length > 0) {
58
+ operation.security = security;
59
+ }
60
+ let pathItem = paths[path];
61
+ if (!pathItem) {
62
+ pathItem = {};
63
+ paths[path] = pathItem;
64
+ }
65
+ pathItem[route.method.toLowerCase()] = operation;
66
+ }
67
+ const doc = {
68
+ openapi: '3.1.0',
69
+ info: opts.info,
70
+ paths,
71
+ tags: [...tagNames].sort().map((name) => ({ name })),
72
+ components: { securitySchemes },
73
+ };
74
+ if (opts.servers && opts.servers.length > 0) {
75
+ doc.servers = opts.servers;
76
+ }
77
+ return doc;
78
+ }
79
+ // ── path ──────────────────────────────────────────────────────────────────────
80
+ /** `:id` → `{id}`, trailing `*rest` → `{rest}` (splat approximated). */
81
+ function convertPath(internalPath) {
82
+ const params = [];
83
+ let hadSplat = false;
84
+ const out = internalPath
85
+ .split('/')
86
+ .map((seg) => {
87
+ if (seg.startsWith(':')) {
88
+ const name = seg.slice(1);
89
+ params.push(name);
90
+ return `{${name}}`;
91
+ }
92
+ if (seg.startsWith('*')) {
93
+ hadSplat = true;
94
+ const name = seg.slice(1) || 'splat';
95
+ params.push(name);
96
+ return `{${name}}`;
97
+ }
98
+ return seg;
99
+ })
100
+ .join('/');
101
+ return { path: out || '/', params, hadSplat };
102
+ }
103
+ function operationId(route, path) {
104
+ const name = route.entry.meta?.methodName;
105
+ if (name) {
106
+ return name;
107
+ }
108
+ const slug = path.replace(/[^a-zA-Z0-9]+/g, '_').replace(/^_|_$/g, '');
109
+ return `${route.method.toLowerCase()}_${slug || 'root'}`;
110
+ }
111
+ // ── schema conversion ──────────────────────────────────────────────────────────
112
+ /** Resolve a schema's driver and emit JSON Schema; null when not introspectable. */
113
+ async function schemaToJson(schema) {
114
+ const driver = ValidateService.resolve(schema);
115
+ if (!driver?.toJsonSchema) {
116
+ return null;
117
+ }
118
+ const result = await driver.toJsonSchema(schema);
119
+ if (!result) {
120
+ return null;
121
+ }
122
+ // `$schema` is a standalone-document marker; invalid when embedded in OpenAPI.
123
+ const { $schema, ...rest } = result;
124
+ return rest;
125
+ }
126
+ function placeholderSchema() {
127
+ return {
128
+ type: 'object',
129
+ description: 'Schema introspection unavailable for this validator (no toJsonSchema). Body shape not documented.',
130
+ };
131
+ }
132
+ /**
133
+ * Combine body schemas. A single schema passes through untouched (keeps its
134
+ * top-level keys — `description`, `additionalProperties`, non-object types).
135
+ * Multiple are shallow-merged into one object schema (route body + middleware
136
+ * params), mirroring the runtime's `Object.assign` of validated parts.
137
+ */
138
+ function combineSchemas(schemas) {
139
+ return schemas.length === 1 ? schemas[0] : mergeObjectSchemas(schemas);
140
+ }
141
+ /** Shallow-merge object JSON Schemas: union `properties` + `required`. */
142
+ function mergeObjectSchemas(schemas) {
143
+ const properties = {};
144
+ const required = new Set();
145
+ for (const schema of schemas) {
146
+ const props = schema.properties;
147
+ if (props && typeof props === 'object') {
148
+ Object.assign(properties, props);
149
+ }
150
+ if (Array.isArray(schema.required)) {
151
+ for (const key of schema.required) {
152
+ required.add(key);
153
+ }
154
+ }
155
+ }
156
+ const out = { type: 'object', properties };
157
+ if (required.size > 0) {
158
+ out.required = [...required];
159
+ }
160
+ return out;
161
+ }
162
+ function hasBinaryField(schema) {
163
+ const props = schema.properties;
164
+ if (!props || typeof props !== 'object') {
165
+ return false;
166
+ }
167
+ return Object.values(props).some((p) => p != null && typeof p === 'object' && p.format === 'binary');
168
+ }
169
+ // ── middleware-contributed schemas ──────────────────────────────────────────────
170
+ /** Read static `relatedRequestParameters` / `relatedQueryParameters` off classes. */
171
+ function collectMiddlewareSchemas(middlewares, kind) {
172
+ const prop = kind === 'request' ? 'relatedRequestParameters' : 'relatedQueryParameters';
173
+ const out = [];
174
+ for (const mw of middlewares) {
175
+ const schema = mw.Class[prop];
176
+ if (schema) {
177
+ out.push(schema);
178
+ }
179
+ }
180
+ return out;
181
+ }
182
+ // ── query / body / security ─────────────────────────────────────────────────────
183
+ async function buildQueryParameters(route, warn, ctx) {
184
+ const schemas = [
185
+ ...(route.entry.query ? [route.entry.query] : []),
186
+ ...collectMiddlewareSchemas(route.middlewares, 'query'),
187
+ ];
188
+ const params = [];
189
+ for (const schema of schemas) {
190
+ const json = await schemaToJson(schema);
191
+ if (!json) {
192
+ warn(`${ctx} query: schema introspection unavailable — params omitted.`);
193
+ continue;
194
+ }
195
+ const props = json.properties ?? {};
196
+ const required = new Set(Array.isArray(json.required) ? json.required : []);
197
+ for (const [name, propSchema] of Object.entries(props)) {
198
+ params.push({
199
+ name,
200
+ in: 'query',
201
+ required: required.has(name),
202
+ schema: propSchema,
203
+ });
204
+ }
205
+ }
206
+ return params;
207
+ }
208
+ async function buildRequestBody(route, warn, ctx) {
209
+ const req = route.entry.request;
210
+ const mwSchemas = collectMiddlewareSchemas(route.middlewares, 'request');
211
+ const mwParts = (await Promise.all(mwSchemas.map((s) => schemaToJson(s)))).filter((s) => s != null);
212
+ // Content-type map → one media type per declared key (native multipart support).
213
+ if (req && isContentTypeRequestMap(req)) {
214
+ const content = {};
215
+ for (const [mediaType, schema] of Object.entries(req)) {
216
+ const converted = await schemaToJson(schema);
217
+ if (!converted) {
218
+ warn(`${ctx} body (${mediaType}): schema introspection unavailable.`);
219
+ }
220
+ const merged = combineSchemas([
221
+ converted ?? placeholderSchema(),
222
+ ...mwParts,
223
+ ]);
224
+ content[mediaType] = { schema: merged };
225
+ }
226
+ return { content };
227
+ }
228
+ // Single schema (or none).
229
+ let routeObj = null;
230
+ if (req) {
231
+ routeObj = await schemaToJson(req);
232
+ if (!routeObj) {
233
+ warn(`${ctx} body: schema introspection unavailable — placeholder emitted.`);
234
+ }
235
+ }
236
+ const parts = [
237
+ ...(routeObj ? [routeObj] : req ? [placeholderSchema()] : []),
238
+ ...mwParts,
239
+ ];
240
+ if (parts.length === 0) {
241
+ return undefined; // no declared body
242
+ }
243
+ const schema = combineSchemas(parts);
244
+ const mediaType = hasBinaryField(schema)
245
+ ? 'multipart/form-data'
246
+ : 'application/json';
247
+ return { content: { [mediaType]: { schema } } };
248
+ }
249
+ function collectSecurity(middlewares, securitySchemes) {
250
+ const requirements = [];
251
+ const seen = new Set();
252
+ for (const mw of middlewares) {
253
+ const params = mw.Class
254
+ .usedAuthParameters;
255
+ if (!Array.isArray(params)) {
256
+ continue;
257
+ }
258
+ for (const param of params) {
259
+ if (!securitySchemes[param.name]) {
260
+ securitySchemes[param.name] = toSecurityScheme(param);
261
+ }
262
+ if (!seen.has(param.name)) {
263
+ seen.add(param.name);
264
+ requirements.push({ [param.name]: [] });
265
+ }
266
+ }
267
+ }
268
+ return requirements;
269
+ }
270
+ function toSecurityScheme(param) {
271
+ if (param.type === 'apiKey') {
272
+ return {
273
+ type: 'apiKey',
274
+ name: param.name,
275
+ in: param.in ?? 'header',
276
+ description: param.description,
277
+ };
278
+ }
279
+ if (param.type === 'http') {
280
+ return {
281
+ type: 'http',
282
+ scheme: param.scheme ?? 'bearer',
283
+ description: param.description,
284
+ };
285
+ }
286
+ return { type: param.type, description: param.description };
287
+ }
288
+ function defaultResponses() {
289
+ return {
290
+ '200': { description: 'Successful response' },
291
+ '400': { description: 'Validation error' },
292
+ '401': { description: 'Unauthorized' },
293
+ '404': { description: 'Not found' },
294
+ };
295
+ }
296
+ //# sourceMappingURL=OpenApiGenerator.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"OpenApiGenerator.js","sourceRoot":"","sources":["../../../src/services/documentation/OpenApiGenerator.ts"],"names":[],"mappings":"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"}
@@ -3,6 +3,7 @@ import type { Express, Request } from 'express';
3
3
  import type { TFunction } from 'i18next';
4
4
  import Base from '../../modules/Base.ts';
5
5
  import type { IApp } from '../../server.ts';
6
+ import { type ErrorHandlerFn, type ErrorHandlerResult, type ErrorLogLevel } from './builtinErrorHandlers.ts';
6
7
  import { RouteRegistry } from './routing/RouteRegistry.ts';
7
8
  export interface FrameworkRequest extends Request {
8
9
  appInfo: {
@@ -20,12 +21,34 @@ export interface FrameworkRequest extends Request {
20
21
  * HTTP server based on Express
21
22
  */
22
23
  declare class HttpServer extends Base {
24
+ #private;
23
25
  express: Express;
24
26
  httpServer: Server;
25
27
  routeRegistry: RouteRegistry;
26
28
  constructor(app: IApp);
27
29
  /** Mount the route adapter — single entry to the registry. */
28
30
  mountAdapter(): void;
31
+ /**
32
+ * Register a handler mapping a thrown error class to an HTTP response.
33
+ * Consumer handlers are checked before the built-ins (`HttpError` mapper,
34
+ * mongoose validation safety net) in registration order — the first
35
+ * `instanceof` match whose handler returns non-null wins; return `null` to
36
+ * pass to the next entry. Typical registration point is the project's
37
+ * `bootHttp` hook. Returns an unregister function.
38
+ */
39
+ registerErrorHandler<E extends Error>(errorClass: abstract new (...args: never[]) => E, handler: ErrorHandlerFn<E>, opts?: {
40
+ logLevel?: ErrorLogLevel;
41
+ }): () => void;
42
+ /**
43
+ * Resolve a handler-thrown error through the registry: consumer tier first,
44
+ * then built-ins; first `instanceof` match returning non-null wins. A
45
+ * handler that itself throws aborts the walk (logged here at `error`; the
46
+ * caller falls through to its 500) — never a crash loop. Returns null when
47
+ * no entry produced a response.
48
+ */
49
+ resolveError(err: unknown, req: FrameworkRequest): Promise<(ErrorHandlerResult & {
50
+ logLevel: ErrorLogLevel;
51
+ }) | null>;
29
52
  /**
30
53
  * Add handle for 404 error
31
54
  */
@@ -1,6 +1,7 @@
1
1
  import http from 'node:http';
2
2
  import express from 'express';
3
3
  import Base from "../../modules/Base.js";
4
+ import { builtInErrorHandlers, } from "./builtinErrorHandlers.js";
4
5
  import Cors from "./middleware/Cors.js";
5
6
  import I18nMiddleware from "./middleware/I18n.js";
6
7
  import IpDetector from "./middleware/IpDetector.js";
@@ -16,6 +17,9 @@ class HttpServer extends Base {
16
17
  express;
17
18
  httpServer;
18
19
  routeRegistry;
20
+ /** Consumer-registered error handlers — checked before the built-ins. */
21
+ #errorHandlers = [];
22
+ #builtInHandlers = builtInErrorHandlers();
19
23
  constructor(app) {
20
24
  super(app);
21
25
  this.express = express();
@@ -68,6 +72,59 @@ class HttpServer extends Base {
68
72
  mountAdapter() {
69
73
  this.express.use(createExpressAdapter(this.routeRegistry, this.app));
70
74
  }
75
+ /**
76
+ * Register a handler mapping a thrown error class to an HTTP response.
77
+ * Consumer handlers are checked before the built-ins (`HttpError` mapper,
78
+ * mongoose validation safety net) in registration order — the first
79
+ * `instanceof` match whose handler returns non-null wins; return `null` to
80
+ * pass to the next entry. Typical registration point is the project's
81
+ * `bootHttp` hook. Returns an unregister function.
82
+ */
83
+ registerErrorHandler(errorClass, handler, opts) {
84
+ const entry = {
85
+ errorClass,
86
+ // Stored type-erased; `resolveError` guarantees `instanceof errorClass`
87
+ // before the call, so the narrower parameter type is safe.
88
+ handler: handler,
89
+ logLevel: opts?.logLevel ?? 'warn',
90
+ };
91
+ this.#errorHandlers.push(entry);
92
+ return () => {
93
+ const i = this.#errorHandlers.indexOf(entry);
94
+ if (i !== -1) {
95
+ this.#errorHandlers.splice(i, 1);
96
+ }
97
+ };
98
+ }
99
+ /**
100
+ * Resolve a handler-thrown error through the registry: consumer tier first,
101
+ * then built-ins; first `instanceof` match returning non-null wins. A
102
+ * handler that itself throws aborts the walk (logged here at `error`; the
103
+ * caller falls through to its 500) — never a crash loop. Returns null when
104
+ * no entry produced a response.
105
+ */
106
+ async resolveError(err, req) {
107
+ for (const entry of [...this.#errorHandlers, ...this.#builtInHandlers]) {
108
+ if (err instanceof entry.errorClass) {
109
+ let result;
110
+ try {
111
+ result = await entry.handler(err, req);
112
+ }
113
+ catch (handlerErr) {
114
+ // Keep the stack — a broken consumer handler is exactly the case
115
+ // where `${err}` (message-only) isn't enough to debug.
116
+ this.logger?.error(`Error handler for ${entry.errorClass.name} threw: ${handlerErr instanceof Error
117
+ ? (handlerErr.stack ?? handlerErr.message)
118
+ : handlerErr}`);
119
+ return null;
120
+ }
121
+ if (result != null) {
122
+ return { ...result, logLevel: entry.logLevel };
123
+ }
124
+ }
125
+ }
126
+ return null;
127
+ }
71
128
  /**
72
129
  * Add handle for 404 error
73
130
  */
@@ -1 +1 @@
1
- {"version":3,"file":"HttpServer.js","sourceRoot":"","sources":["../../../src/services/http/HttpServer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"HttpServer.js","sourceRoot":"","sources":["../../../src/services/http/HttpServer.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,53 @@
1
+ import mongoose from 'mongoose';
2
+ import type { FrameworkRequest } from './HttpServer.ts';
3
+ /** Levels the registry may log a handled error at (winston leveled methods). */
4
+ export type ErrorLogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
5
+ /** What a handler returns to produce a response; `null`/`undefined` = pass. */
6
+ export interface ErrorHandlerResult {
7
+ status: number;
8
+ body: unknown;
9
+ }
10
+ export type ErrorHandlerFn<E extends Error = Error> = (err: E, req: FrameworkRequest) => ErrorHandlerResult | null | undefined | Promise<ErrorHandlerResult | null | undefined>;
11
+ /** A registered (class, handler, level) triple as stored by the registry. */
12
+ export interface RegisteredErrorHandler {
13
+ errorClass: abstract new (...args: never[]) => Error;
14
+ handler: ErrorHandlerFn;
15
+ logLevel: ErrorLogLevel;
16
+ }
17
+ /**
18
+ * Sanitize an error for the RESOLVED-branch log line. A raw Mongoose
19
+ * `ValidationError`'s `.message` (and `.stack` header) interpolates the
20
+ * rejected `{VALUE}`, so `logger.warn(err)` would leak the submission into
21
+ * logs — and whatever ships them (Sentry, retention) — even after the 400
22
+ * body was sanitized. Rebuild a fresh `Error` that reuses the per-path
23
+ * `safeValidationMessage` texts under the safe static prefix
24
+ * (`<ModelName> validation failed`); its stack is minted here, input-free.
25
+ * Anything else passes through untouched. The UNRESOLVED 500 path deliberately
26
+ * keeps logging the original error in full: that branch is a server-side
27
+ * defect, and the developer needs every detail.
28
+ */
29
+ export declare function toLoggableError(err: unknown): unknown;
30
+ /**
31
+ * Safety net for an escaped Mongoose `ValidationError`: returns a per-field
32
+ * `{ <path>: message }` map ONLY when every failing model path is a field the
33
+ * client actually sent — the keys of the validated `request` ∪ `query`, minus
34
+ * the framework-injected `contentType` discriminant (see
35
+ * `ControllerManager.#wrapHandlerEntry`). A nested path (`profile.name`)
36
+ * matches on its first segment and is reported under the full path (the
37
+ * client owns that subtree). Any renamed/internal path → `null`, so the
38
+ * caller keeps the honest 500 and never leaks a non-public field name.
39
+ *
40
+ * Each message is rebuilt by `safeValidationMessage` from the validation
41
+ * `kind` + constraint — the raw `err.errors[path].message` is NEVER used, so
42
+ * the submitted value can't ride into the response or the log.
43
+ */
44
+ export declare function matchedClientValidationErrors(err: mongoose.Error.ValidationError, req: FrameworkRequest): Record<string, string> | null;
45
+ /**
46
+ * Framework built-in registry entries, checked AFTER any consumer-registered
47
+ * handlers ("yours win"):
48
+ * 1. `HttpError` → its own status / `body ?? { message }`; `verbose`
49
+ * (deliberate control flow, not a defect).
50
+ * 2. Escaped Mongoose `ValidationError` → the safety net above; `warn`
51
+ * (signals a route schema missing a constraint the model enforces).
52
+ */
53
+ export declare function builtInErrorHandlers(): RegisteredErrorHandler[];