@guren/server 1.4.0 → 2.0.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.
- package/dist/{AuthManager-C84xF5ks.d.ts → AuthManager-DBP4KYsx.d.ts} +1 -1
- package/dist/ConsoleKernel-DlK9j2Lu.d.ts +101 -0
- package/dist/DocsViewerServiceProvider-D7RGJPGM.js +75 -0
- package/dist/{I18nManager-CmUqj6bU.d.ts → I18nManager-BiSoczfV.d.ts} +1 -1
- package/dist/McpServiceProvider-7BB5FPF3.js +8 -0
- package/dist/auth/index.d.ts +39 -29
- package/dist/auth/index.js +2 -2
- package/dist/broadcasting/index.js +2 -2
- package/dist/cache/index.js +2 -2
- package/dist/chunk-2V3YID4H.js +20 -0
- package/dist/{chunk-JIT7QVMJ.js → chunk-4DW4GRWF.js} +3 -3
- package/dist/{chunk-R2TCP7D7.js → chunk-6J6B5KOB.js} +18 -2
- package/dist/chunk-AZOYI43J.js +18 -0
- package/dist/{chunk-DCYKSYAT.js → chunk-B5E5VBDI.js} +54 -2
- package/dist/{chunk-NYQGAWDN.js → chunk-BZMZEFRG.js} +7 -11
- package/dist/{chunk-4SBGSJNT.js → chunk-CWI4AJ47.js} +2 -1
- package/dist/{chunk-NQCZQAJL.js → chunk-DSDX3ASM.js} +21 -2
- package/dist/{chunk-MC752CQT.js → chunk-EI5GYMAT.js} +2 -1
- package/dist/{chunk-AUXQISW5.js → chunk-HONCNQXZ.js} +38 -5
- package/dist/{chunk-CSRQTEQA.js → chunk-HWEWL6TE.js} +6 -1
- package/dist/chunk-JBG4AR24.js +18 -0
- package/dist/{chunk-EDRGAM6G.js → chunk-K6CUBJX6.js} +11 -16
- package/dist/{chunk-WJJ5CTNI.js → chunk-KTNJG7R7.js} +6 -2
- package/dist/{chunk-74HTZG3V.js → chunk-LAJQCSSF.js} +24 -0
- package/dist/{chunk-H32L2NE3.js → chunk-LVJCZCAV.js} +20 -13
- package/dist/{chunk-CSDKWLFD.js → chunk-N7PLD7MB.js} +120 -43
- package/dist/{chunk-ONSDE37A.js → chunk-SFQP6O52.js} +1 -0
- package/dist/{chunk-XMQZENBP.js → chunk-TVY72CLV.js} +3 -1
- package/dist/chunk-WIXGT4TN.js +18 -0
- package/dist/{email-verification-H_WlpsVH.d.ts → email-verification-D8N7P6Pu.d.ts} +1 -1
- package/dist/encryption/index.js +2 -2
- package/dist/events/index.js +1 -1
- package/dist/i18n/index.d.ts +2 -2
- package/dist/index.d.ts +348 -330
- package/dist/index.js +332 -110
- package/dist/lambda/index.d.ts +5 -5
- package/dist/lambda/index.js +1 -1
- package/dist/mail/index.js +4 -3
- package/dist/mcp/index.d.ts +14 -4
- package/dist/mcp/index.js +3 -2
- package/dist/notifications/index.d.ts +55 -6
- package/dist/notifications/index.js +12 -3
- package/dist/queue/index.d.ts +5 -5
- package/dist/queue/index.js +4 -2
- package/dist/redis/index.d.ts +4 -4
- package/dist/redis/index.js +7 -0
- package/dist/runtime/index.d.ts +5 -5
- package/dist/runtime/index.js +24 -9
- package/dist/scheduling/index.js +2 -2
- package/dist/storage/index.js +2 -1
- package/dist/{Application-BvBqgc2k.d.ts → validation-CDR7lRE8.d.ts} +873 -654
- package/package.json +3 -3
- package/dist/ConsoleKernel-Dw9X9qZY.d.ts +0 -207
- package/dist/McpServiceProvider-TZWQWXCT.js +0 -7
- package/dist/{api-token-COQHXyM_.d.ts → api-token-D24VPr_E.d.ts} +101 -101
- package/dist/{client-BQwF2b9Y.d.ts → rate-limit-D9J2b4S1.d.ts} +36 -36
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
import * as hono from 'hono';
|
|
2
2
|
import { Context, MiddlewareHandler, Hono, Next, ExecutionContext } from 'hono';
|
|
3
|
-
import { l as OAuthManager, g as AuthContext, j as ApiToken, C as CreateSessionMiddlewareOptions } from './api-token-
|
|
4
|
-
import { A as AuthManager } from './AuthManager-
|
|
3
|
+
import { l as OAuthManager, g as AuthContext, j as ApiToken, C as CreateSessionMiddlewareOptions } from './api-token-D24VPr_E.js';
|
|
4
|
+
import { A as AuthManager } from './AuthManager-DBP4KYsx.js';
|
|
5
5
|
import { InlineConfig, ViteDevServer } from 'vite';
|
|
6
6
|
import { E as EventManager } from './EventManager-CmIoLt7r.js';
|
|
7
7
|
import { C as CacheManager } from './CacheManager-BmDzUKrF.js';
|
|
8
8
|
import { M as MailManager } from './MailManager-DpMvYiP9.js';
|
|
9
9
|
import { L as LogManager } from './LogManager-7mxnkaPM.js';
|
|
10
|
-
import { I as I18nManager } from './I18nManager-
|
|
10
|
+
import { I as I18nManager } from './I18nManager-BiSoczfV.js';
|
|
11
11
|
import { B as BroadcastManager } from './BroadcastManager-D8KoJxiV.js';
|
|
12
12
|
import { E as Encrypter, A as AppKeyring } from './app-key-CsBfRC_Q.js';
|
|
13
13
|
import { S as StorageManager } from './StorageManager-oZTHqaza.js';
|
|
@@ -184,6 +184,13 @@ interface InertiaDocumentOptions {
|
|
|
184
184
|
* `matchMedia` before React hydrates.
|
|
185
185
|
*/
|
|
186
186
|
readonly prepaintScript?: InertiaDocumentValue;
|
|
187
|
+
/**
|
|
188
|
+
* Raw markup inlined into `<head>`, ahead of the critical CSS and stylesheet
|
|
189
|
+
* links. Unescaped — the app author owns this string. Use it for static,
|
|
190
|
+
* site-wide tags the framework has no way to infer on its own, such as
|
|
191
|
+
* `<link rel="icon">` favicons.
|
|
192
|
+
*/
|
|
193
|
+
readonly head?: InertiaDocumentValue;
|
|
187
194
|
}
|
|
188
195
|
/**
|
|
189
196
|
* Register app-wide document defaults for server-rendered Inertia responses.
|
|
@@ -198,8 +205,9 @@ interface InertiaDocumentOptions {
|
|
|
198
205
|
* requests are in flight leaks the new policy into them. Use the matching
|
|
199
206
|
* {@link InertiaOptions} fields for a single response instead.
|
|
200
207
|
*
|
|
201
|
-
* The values are emitted verbatim inside `<style>` / `<script>` elements
|
|
202
|
-
* they are developer-authored assets, never
|
|
208
|
+
* The values are emitted verbatim — inside `<style>` / `<script>` elements,
|
|
209
|
+
* or as raw markup for `head` — they are developer-authored assets, never
|
|
210
|
+
* user input.
|
|
203
211
|
*
|
|
204
212
|
* ```typescript
|
|
205
213
|
* setInertiaDocument({
|
|
@@ -242,187 +250,69 @@ declare function getInertiaSharedPropsResolver(): SharedInertiaPropsResolver<Res
|
|
|
242
250
|
declare function shareInertiaProps<Props extends Record<string, unknown>>(resolverFn: SharedInertiaPropsResolver<Props>): void;
|
|
243
251
|
|
|
244
252
|
/**
|
|
245
|
-
*
|
|
246
|
-
* Falls back to an empty object if the payload cannot be parsed.
|
|
253
|
+
* Service factory function.
|
|
247
254
|
*/
|
|
248
|
-
|
|
249
|
-
interface ValidationIssueLike {
|
|
250
|
-
path: PropertyKey[];
|
|
251
|
-
message: string;
|
|
252
|
-
}
|
|
253
|
-
interface ValidationErrorLike {
|
|
254
|
-
issues: ValidationIssueLike[];
|
|
255
|
-
}
|
|
255
|
+
type ServiceFactory<T> = (container: Container) => T;
|
|
256
256
|
/**
|
|
257
|
-
*
|
|
257
|
+
* Service class constructor.
|
|
258
258
|
*/
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
declare const VALIDATED_DATA_KEY = "guren:validated";
|
|
262
|
-
interface ValidationSchema<T = unknown> {
|
|
263
|
-
parse(data: unknown): T;
|
|
264
|
-
safeParse(data: unknown): {
|
|
265
|
-
success: true;
|
|
266
|
-
data: T;
|
|
267
|
-
} | {
|
|
268
|
-
success: false;
|
|
269
|
-
error: ValidationErrorLike;
|
|
270
|
-
};
|
|
271
|
-
}
|
|
272
|
-
interface ValidateRequestOptions {
|
|
273
|
-
/**
|
|
274
|
-
* Custom error handler when validation fails.
|
|
275
|
-
* Defaults to returning a 422 JSON response with formatted errors.
|
|
276
|
-
*/
|
|
277
|
-
onError?: (ctx: Context, errors: Record<string, string>) => Response | Promise<Response>;
|
|
278
|
-
/**
|
|
279
|
-
* HTTP status code for validation errors.
|
|
280
|
-
* Defaults to 422 (Unprocessable Entity).
|
|
281
|
-
*/
|
|
282
|
-
status?: number;
|
|
283
|
-
/**
|
|
284
|
-
* Fallback message when no field-specific errors are available.
|
|
285
|
-
*/
|
|
286
|
-
fallbackMessage?: string;
|
|
287
|
-
}
|
|
259
|
+
type ServiceClass<T> = new (...args: unknown[]) => T;
|
|
288
260
|
/**
|
|
289
|
-
*
|
|
290
|
-
* Returns undefined if validation middleware hasn't run or validation failed.
|
|
261
|
+
* Service binding configuration.
|
|
291
262
|
*/
|
|
292
|
-
|
|
263
|
+
interface ServiceBinding {
|
|
264
|
+
factory: ServiceFactory<unknown>;
|
|
265
|
+
singleton: boolean;
|
|
266
|
+
instance?: unknown;
|
|
267
|
+
}
|
|
293
268
|
/**
|
|
294
|
-
*
|
|
295
|
-
*
|
|
296
|
-
* @example
|
|
297
|
-
* ```ts
|
|
298
|
-
* import { z } from 'zod'
|
|
299
|
-
* import { validateRequest, getValidatedData } from '@guren/server'
|
|
300
|
-
*
|
|
301
|
-
* const CreateUserSchema = z.object({
|
|
302
|
-
* name: z.string().min(1),
|
|
303
|
-
* email: z.email(),
|
|
304
|
-
* })
|
|
305
|
-
*
|
|
306
|
-
* app.post('/users', validateRequest(CreateUserSchema), (c) => {
|
|
307
|
-
* const data = getValidatedData<z.infer<typeof CreateUserSchema>>(c)
|
|
308
|
-
* // data is typed and validated
|
|
309
|
-
* return c.json({ user: data })
|
|
310
|
-
* })
|
|
311
|
-
* ```
|
|
269
|
+
* Contextual binding builder interface.
|
|
312
270
|
*/
|
|
313
|
-
|
|
271
|
+
interface ContextualBindingBuilder {
|
|
272
|
+
needs(abstract: string): ContextualNeedsBuilder;
|
|
273
|
+
}
|
|
314
274
|
/**
|
|
315
|
-
*
|
|
316
|
-
* Useful when the schema depends on request context.
|
|
317
|
-
*
|
|
318
|
-
* @example
|
|
319
|
-
* ```ts
|
|
320
|
-
* app.post('/users/:role', validateRequestWith((ctx) => {
|
|
321
|
-
* const role = ctx.req.param('role')
|
|
322
|
-
* return role === 'admin' ? AdminSchema : UserSchema
|
|
323
|
-
* }), handler)
|
|
324
|
-
* ```
|
|
275
|
+
* Contextual needs builder interface.
|
|
325
276
|
*/
|
|
326
|
-
|
|
277
|
+
interface ContextualNeedsBuilder {
|
|
278
|
+
give<T>(factory: ServiceFactory<T> | T): void;
|
|
279
|
+
}
|
|
327
280
|
/**
|
|
328
|
-
*
|
|
329
|
-
* Useful for manual validation in handlers.
|
|
330
|
-
*
|
|
331
|
-
* @example
|
|
332
|
-
* ```ts
|
|
333
|
-
* app.post('/data', async (c) => {
|
|
334
|
-
* const payload = await parseRequestPayload(c)
|
|
335
|
-
* const data = validate(MySchema, payload)
|
|
336
|
-
* // throws ValidationError if invalid
|
|
337
|
-
* return c.json(data)
|
|
338
|
-
* })
|
|
339
|
-
* ```
|
|
281
|
+
* Contextual binding configuration.
|
|
340
282
|
*/
|
|
341
|
-
|
|
283
|
+
interface ContextualBinding {
|
|
284
|
+
concrete: string;
|
|
285
|
+
needs: string;
|
|
286
|
+
factory: ServiceFactory<unknown>;
|
|
287
|
+
}
|
|
342
288
|
/**
|
|
343
|
-
*
|
|
344
|
-
* Does not throw on validation failure.
|
|
289
|
+
* Service provider options.
|
|
345
290
|
*/
|
|
346
|
-
|
|
347
|
-
success: true;
|
|
348
|
-
data: T;
|
|
349
|
-
} | {
|
|
350
|
-
success: false;
|
|
351
|
-
errors: Record<string, string>;
|
|
352
|
-
};
|
|
353
|
-
|
|
354
|
-
interface HstsOptions {
|
|
355
|
-
/** Max age in seconds. */
|
|
356
|
-
maxAge: number;
|
|
357
|
-
/** Include subdomains. Default: false */
|
|
358
|
-
includeSubDomains?: boolean;
|
|
359
|
-
/** Enable HSTS preload. Default: false */
|
|
360
|
-
preload?: boolean;
|
|
361
|
-
}
|
|
362
|
-
interface SecurityHeadersOptions {
|
|
363
|
-
/** X-Frame-Options header. Set to false to disable. Default: 'SAMEORIGIN' */
|
|
364
|
-
frameOptions?: string | false;
|
|
365
|
-
/** X-Content-Type-Options header. Set to false to disable. Default: 'nosniff' */
|
|
366
|
-
contentTypeOptions?: string | false;
|
|
367
|
-
/** X-XSS-Protection header. Set to false to disable. Default: '0' */
|
|
368
|
-
xssProtection?: string | false;
|
|
369
|
-
/** Referrer-Policy header. Set to false to disable. Default: 'strict-origin-when-cross-origin' */
|
|
370
|
-
referrerPolicy?: string | false;
|
|
371
|
-
/** X-Permitted-Cross-Domain-Policies header. Set to false to disable. Default: 'none' */
|
|
372
|
-
crossDomainPolicies?: string | false;
|
|
291
|
+
interface ServiceProviderOptions {
|
|
373
292
|
/**
|
|
374
|
-
*
|
|
375
|
-
* Default: `{ maxAge: 31536000 }` (1 year) when NODE_ENV is 'production', false otherwise.
|
|
376
|
-
* Browsers ignore HSTS on plain-HTTP responses, so the production default is safe behind TLS terminators.
|
|
293
|
+
* Whether this provider should be deferred.
|
|
377
294
|
*/
|
|
378
|
-
|
|
295
|
+
deferred?: boolean;
|
|
296
|
+
/**
|
|
297
|
+
* Services this provider provides (for deferred loading).
|
|
298
|
+
*/
|
|
299
|
+
provides?: string[];
|
|
379
300
|
}
|
|
380
301
|
/**
|
|
381
|
-
*
|
|
382
|
-
*
|
|
383
|
-
* @example
|
|
384
|
-
* ```ts
|
|
385
|
-
* import { createSecurityHeaders } from '@guren/core'
|
|
386
|
-
*
|
|
387
|
-
* app.use('*', createSecurityHeaders())
|
|
388
|
-
*
|
|
389
|
-
* // With HSTS enabled
|
|
390
|
-
* app.use('*', createSecurityHeaders({
|
|
391
|
-
* hsts: { maxAge: 31536000, includeSubDomains: true },
|
|
392
|
-
* }))
|
|
393
|
-
*
|
|
394
|
-
* // Disable specific headers
|
|
395
|
-
* app.use('*', createSecurityHeaders({
|
|
396
|
-
* frameOptions: false,
|
|
397
|
-
* xssProtection: false,
|
|
398
|
-
* }))
|
|
399
|
-
* ```
|
|
302
|
+
* Provider interface for container-based service providers.
|
|
400
303
|
*/
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
/** Allowed hosts. Supports exact matches and wildcard subdomains (e.g., '*.example.com'). */
|
|
405
|
-
allowedHosts: string[];
|
|
406
|
-
/** Paths to exclude from host checking (e.g., ['/healthcheck', '/up']). */
|
|
407
|
-
exclude?: string[];
|
|
408
|
-
/** Custom response when host is not authorized. Default: 403 Forbidden. */
|
|
409
|
-
onError?: (ctx: Context) => Response | Promise<Response>;
|
|
304
|
+
interface Provider {
|
|
305
|
+
register?(context: unknown): void | Promise<void>;
|
|
306
|
+
boot?(context: unknown): void | Promise<void>;
|
|
410
307
|
}
|
|
411
308
|
/**
|
|
412
|
-
*
|
|
413
|
-
* Protects against DNS rebinding and host header attacks.
|
|
414
|
-
*
|
|
415
|
-
* @example
|
|
416
|
-
* ```ts
|
|
417
|
-
* import { createHostAuthorizationMiddleware } from '@guren/core'
|
|
418
|
-
*
|
|
419
|
-
* app.use('*', createHostAuthorizationMiddleware({
|
|
420
|
-
* allowedHosts: ['example.com', '*.example.com', 'localhost:3000'],
|
|
421
|
-
* exclude: ['/healthcheck'],
|
|
422
|
-
* }))
|
|
423
|
-
* ```
|
|
309
|
+
* Service provider class type.
|
|
424
310
|
*/
|
|
425
|
-
|
|
311
|
+
interface ServiceProviderClass {
|
|
312
|
+
new (container: Container): Provider;
|
|
313
|
+
deferred?: boolean;
|
|
314
|
+
provides?: string[];
|
|
315
|
+
}
|
|
426
316
|
|
|
427
317
|
/**
|
|
428
318
|
* Serialized job data stored in the queue.
|
|
@@ -631,6 +521,17 @@ declare function getQueueDriver(): QueueDriver | null;
|
|
|
631
521
|
* ```
|
|
632
522
|
*/
|
|
633
523
|
declare abstract class Job<T = unknown> {
|
|
524
|
+
/**
|
|
525
|
+
* Stable wire name for this job.
|
|
526
|
+
*
|
|
527
|
+
* Queued messages record this name, and the worker resolves the class back
|
|
528
|
+
* from it. When omitted the class name is used, which breaks if a bundler
|
|
529
|
+
* mangles identifiers or if the class is later renamed while messages are
|
|
530
|
+
* still in flight. Set it to pin the name across both.
|
|
531
|
+
*
|
|
532
|
+
* @default the class name
|
|
533
|
+
*/
|
|
534
|
+
static jobName?: string;
|
|
634
535
|
/**
|
|
635
536
|
* The queue this job should be dispatched to.
|
|
636
537
|
* @default 'default'
|
|
@@ -687,6 +588,7 @@ declare abstract class Job<T = unknown> {
|
|
|
687
588
|
interface JobClass<T = unknown> {
|
|
688
589
|
new (): Job<T>;
|
|
689
590
|
name: string;
|
|
591
|
+
jobName?: string;
|
|
690
592
|
queue: string;
|
|
691
593
|
maxAttempts: number;
|
|
692
594
|
backoff: 'exponential' | 'linear' | number;
|
|
@@ -694,6 +596,18 @@ interface JobClass<T = unknown> {
|
|
|
694
596
|
dispatchAfter(delayMs: number, payload: T, options?: Omit<JobOptions, 'delay'>): Promise<string>;
|
|
695
597
|
calculateRetryDelay(attempts: number): number;
|
|
696
598
|
}
|
|
599
|
+
/**
|
|
600
|
+
* Resolve the wire name a job is queued and looked up under.
|
|
601
|
+
*
|
|
602
|
+
* Prefers an explicit `jobName` over the class name so that renaming the class
|
|
603
|
+
* or bundling with identifier mangling does not orphan queued messages.
|
|
604
|
+
*
|
|
605
|
+
* Only an *own* `jobName` counts. Static members are inherited, so reading it
|
|
606
|
+
* off the prototype chain would make every subclass of a pinned job claim its
|
|
607
|
+
* parent's identity and overwrite it in the registry. A subclass that wants a
|
|
608
|
+
* pinned name declares its own.
|
|
609
|
+
*/
|
|
610
|
+
declare function resolveJobName(jobClass: Pick<JobClass, 'name' | 'jobName'>): string;
|
|
697
611
|
/**
|
|
698
612
|
* Register a job class for the worker to use.
|
|
699
613
|
*/
|
|
@@ -904,6 +818,14 @@ interface Notifiable {
|
|
|
904
818
|
* Get the notification routing information for a given channel.
|
|
905
819
|
*/
|
|
906
820
|
routeNotificationFor(channel: string): string | null;
|
|
821
|
+
/**
|
|
822
|
+
* Stable type name for this notifiable (optional).
|
|
823
|
+
*
|
|
824
|
+
* Defaults to the constructor name. Set this when the notifiable is rebuilt
|
|
825
|
+
* from a queue payload, or when the class name is not durable (bundlers that
|
|
826
|
+
* mangle identifiers).
|
|
827
|
+
*/
|
|
828
|
+
notifiableType?: string;
|
|
907
829
|
/**
|
|
908
830
|
* Database notifications (optional).
|
|
909
831
|
*/
|
|
@@ -1113,16 +1035,28 @@ declare class NotificationManager {
|
|
|
1113
1035
|
sendNowToMany(notifiables: Notifiable[], notification: Notification): Promise<void>;
|
|
1114
1036
|
/**
|
|
1115
1037
|
* Serialize notifiable for queue storage.
|
|
1038
|
+
*
|
|
1039
|
+
* Routing is resolved here rather than in the worker: `routeNotificationFor`
|
|
1040
|
+
* is arbitrary user code — often a closure on an object literal — and cannot
|
|
1041
|
+
* be reconstructed from a payload.
|
|
1042
|
+
*
|
|
1043
|
+
* @param channels - Channels to resolve routes for
|
|
1116
1044
|
*/
|
|
1117
|
-
protected serializeNotifiable(notifiable: Notifiable): SerializedNotifiable;
|
|
1045
|
+
protected serializeNotifiable(notifiable: Notifiable, channels?: string[]): SerializedNotifiable;
|
|
1118
1046
|
/**
|
|
1119
1047
|
* Serialize notification for queue storage.
|
|
1048
|
+
*
|
|
1049
|
+
* Only own enumerable properties are captured. Behaviour is restored by
|
|
1050
|
+
* rebuilding the registered class in the job handler, not by serializing it.
|
|
1120
1051
|
*/
|
|
1121
1052
|
protected serializeNotification(notification: Notification): SerializedNotification;
|
|
1122
1053
|
/**
|
|
1123
|
-
*
|
|
1054
|
+
* Bind this manager to the queued-notification job and register it.
|
|
1055
|
+
*
|
|
1056
|
+
* Call this during boot in a process that runs a worker but may never send
|
|
1057
|
+
* a notification itself: without it, the worker cannot resolve the job.
|
|
1124
1058
|
*/
|
|
1125
|
-
|
|
1059
|
+
registerQueueJob(): typeof SendNotificationJob;
|
|
1126
1060
|
}
|
|
1127
1061
|
/**
|
|
1128
1062
|
* Payload for queued notifications.
|
|
@@ -1134,11 +1068,13 @@ interface SendNotificationPayload {
|
|
|
1134
1068
|
}
|
|
1135
1069
|
interface SerializedNotifiable {
|
|
1136
1070
|
type: string;
|
|
1071
|
+
/** Channel routes resolved at dispatch time. Absent on legacy payloads. */
|
|
1072
|
+
routes?: Record<string, string | null>;
|
|
1137
1073
|
data: Record<string, unknown>;
|
|
1138
1074
|
}
|
|
1139
1075
|
interface SerializedNotification {
|
|
1140
|
-
type: string;
|
|
1141
1076
|
id: string;
|
|
1077
|
+
createdAt: string;
|
|
1142
1078
|
data: Record<string, unknown>;
|
|
1143
1079
|
}
|
|
1144
1080
|
/**
|
|
@@ -1150,6 +1086,18 @@ declare class SendNotificationJob extends Job<SendNotificationPayload> {
|
|
|
1150
1086
|
static maxAttempts: number;
|
|
1151
1087
|
static notificationManager: NotificationManager | null;
|
|
1152
1088
|
handle(payload: SendNotificationPayload): Promise<void>;
|
|
1089
|
+
/**
|
|
1090
|
+
* Rebuild the notifiable from its serialized data.
|
|
1091
|
+
*/
|
|
1092
|
+
protected rebuildNotifiable(serialized: SerializedNotifiable): Notifiable;
|
|
1093
|
+
/**
|
|
1094
|
+
* Rebuild a real notification instance from its serialized data.
|
|
1095
|
+
*
|
|
1096
|
+
* The class is looked up in the notification registry and instantiated via
|
|
1097
|
+
* its prototype, so prototype methods (`via`, `toMail`, `toDatabase`,
|
|
1098
|
+
* `toSlack`, `shouldSend`) are restored without running the constructor.
|
|
1099
|
+
*/
|
|
1100
|
+
protected rebuildNotification(type: string, serialized: SerializedNotification): Notification;
|
|
1153
1101
|
}
|
|
1154
1102
|
/**
|
|
1155
1103
|
* Set the global notification manager.
|
|
@@ -1357,23 +1305,464 @@ interface ServiceBindings {
|
|
|
1357
1305
|
'exception.handler': ExceptionHandler;
|
|
1358
1306
|
}
|
|
1359
1307
|
|
|
1360
|
-
/** Structural type for DI containers, avoiding a hard dependency on Container. */
|
|
1361
|
-
interface ContainerLike {
|
|
1362
|
-
make(key: string): unknown;
|
|
1363
|
-
has?(key: string): boolean;
|
|
1364
|
-
}
|
|
1365
1308
|
/**
|
|
1366
|
-
*
|
|
1367
|
-
*
|
|
1309
|
+
* Dependency injection container with type-safe service resolution.
|
|
1310
|
+
*
|
|
1311
|
+
* @example
|
|
1312
|
+
* ```typescript
|
|
1313
|
+
* const container = new Container()
|
|
1314
|
+
*
|
|
1315
|
+
* // Register services
|
|
1316
|
+
* container.singleton('events', (c) => new EventManager())
|
|
1317
|
+
* container.instance('config', loadConfig())
|
|
1318
|
+
*
|
|
1319
|
+
* // Type-safe resolution (known bindings)
|
|
1320
|
+
* const events = container.make('events') // EventManager
|
|
1321
|
+
*
|
|
1322
|
+
* // Generic resolution (custom bindings)
|
|
1323
|
+
* const db = container.make<Database>('db')
|
|
1324
|
+
* ```
|
|
1368
1325
|
*/
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1326
|
+
declare class Container {
|
|
1327
|
+
protected bindings: Map<string, ServiceBinding>;
|
|
1328
|
+
protected aliases: Map<string, string>;
|
|
1329
|
+
protected tags: Map<string, Set<string>>;
|
|
1330
|
+
protected contextualBindings: ContextualBinding[];
|
|
1331
|
+
protected resolvingStack: string[];
|
|
1332
|
+
protected scopedInstances: Map<string, unknown>[];
|
|
1333
|
+
protected fakes: Map<string, unknown>;
|
|
1334
|
+
/** @internal Used by ProviderManager to resolve deferred providers on demand */
|
|
1335
|
+
deferredProviderLoader: ((service: string) => Promise<void>) | null;
|
|
1336
|
+
/**
|
|
1337
|
+
* Bind a service to the container.
|
|
1338
|
+
* Each resolution creates a new instance.
|
|
1339
|
+
*/
|
|
1340
|
+
bind<T>(key: string, factory: ServiceFactory<T>): this;
|
|
1341
|
+
/**
|
|
1342
|
+
* Bind a singleton service to the container.
|
|
1343
|
+
* Only one instance is created and reused.
|
|
1344
|
+
*/
|
|
1345
|
+
singleton<T>(key: string, factory: ServiceFactory<T>): this;
|
|
1346
|
+
/**
|
|
1347
|
+
* Bind an existing instance to the container.
|
|
1348
|
+
*/
|
|
1349
|
+
instance<T>(key: string, value: T): this;
|
|
1350
|
+
/**
|
|
1351
|
+
* Resolve a service from the container.
|
|
1352
|
+
*
|
|
1353
|
+
* Known service keys (from ServiceBindings) are automatically typed:
|
|
1354
|
+
* ```typescript
|
|
1355
|
+
* container.make('events') // EventManager
|
|
1356
|
+
* container.make('cache') // CacheManager
|
|
1357
|
+
* ```
|
|
1358
|
+
*
|
|
1359
|
+
* Custom keys require an explicit type parameter:
|
|
1360
|
+
* ```typescript
|
|
1361
|
+
* container.make<MyService>('myService')
|
|
1362
|
+
* ```
|
|
1363
|
+
*/
|
|
1364
|
+
make<K extends keyof ServiceBindings>(key: K): ServiceBindings[K];
|
|
1365
|
+
make<T>(key: string): T;
|
|
1366
|
+
/**
|
|
1367
|
+
* Resolve a service with additional parameters.
|
|
1368
|
+
*/
|
|
1369
|
+
makeWith<T>(key: string, params: Record<string, unknown>): T;
|
|
1370
|
+
/**
|
|
1371
|
+
* Check if a service is bound in the container.
|
|
1372
|
+
*/
|
|
1373
|
+
has(key: string): boolean;
|
|
1374
|
+
/**
|
|
1375
|
+
* Create an alias for a service.
|
|
1376
|
+
*/
|
|
1377
|
+
alias(alias: string, key: string): this;
|
|
1378
|
+
/**
|
|
1379
|
+
* Tag multiple services with a tag name.
|
|
1380
|
+
*/
|
|
1381
|
+
tag(keys: string[], tagName: string): this;
|
|
1382
|
+
/**
|
|
1383
|
+
* Resolve all services with a given tag.
|
|
1384
|
+
*/
|
|
1385
|
+
tagged<T = unknown>(tagName: string): T[];
|
|
1386
|
+
/**
|
|
1387
|
+
* Define a contextual binding.
|
|
1388
|
+
*/
|
|
1389
|
+
when(concrete: string): ContextualBindingBuilder;
|
|
1390
|
+
/**
|
|
1391
|
+
* Run a callback within a scoped context.
|
|
1392
|
+
* Services resolved within the scope are cached and released when the scope ends.
|
|
1393
|
+
*/
|
|
1394
|
+
scoped<T>(callback: () => T): T;
|
|
1395
|
+
/**
|
|
1396
|
+
* Run an async callback within a scoped context.
|
|
1397
|
+
*/
|
|
1398
|
+
scopedAsync<T>(callback: () => Promise<T>): Promise<T>;
|
|
1399
|
+
/**
|
|
1400
|
+
* Replace a service binding with a fake instance for testing.
|
|
1401
|
+
* Returns a disposable that restores the original binding when disposed.
|
|
1402
|
+
*
|
|
1403
|
+
* @example
|
|
1404
|
+
* ```typescript
|
|
1405
|
+
* // Using 'using' declaration (auto-cleanup)
|
|
1406
|
+
* using _ = container.fake('events', fakeEventManager)
|
|
1407
|
+
*
|
|
1408
|
+
* // Manual cleanup
|
|
1409
|
+
* const restore = container.fake('mail', fakeMailManager)
|
|
1410
|
+
* // ... run tests ...
|
|
1411
|
+
* restore[Symbol.dispose]()
|
|
1412
|
+
* ```
|
|
1413
|
+
*/
|
|
1414
|
+
fake<K extends keyof ServiceBindings>(key: K, instance: ServiceBindings[K]): Disposable;
|
|
1415
|
+
fake(key: string, instance: unknown): Disposable;
|
|
1416
|
+
/**
|
|
1417
|
+
* Check if a service is currently faked.
|
|
1418
|
+
*/
|
|
1419
|
+
isFaked(key: string): boolean;
|
|
1420
|
+
/**
|
|
1421
|
+
* Remove all fakes.
|
|
1422
|
+
*/
|
|
1423
|
+
clearFakes(): void;
|
|
1424
|
+
/**
|
|
1425
|
+
* Flush all resolved singleton instances.
|
|
1426
|
+
*/
|
|
1427
|
+
flush(): void;
|
|
1428
|
+
/**
|
|
1429
|
+
* Remove a binding from the container.
|
|
1430
|
+
*/
|
|
1431
|
+
forget(key: string): this;
|
|
1432
|
+
/**
|
|
1433
|
+
* Get all bound service keys.
|
|
1434
|
+
*/
|
|
1435
|
+
getBindings(): string[];
|
|
1436
|
+
/**
|
|
1437
|
+
* Get all aliases.
|
|
1438
|
+
*/
|
|
1439
|
+
getAliases(): Record<string, string>;
|
|
1440
|
+
/**
|
|
1441
|
+
* Get all tags.
|
|
1442
|
+
*/
|
|
1443
|
+
getTags(): Record<string, string[]>;
|
|
1444
|
+
protected resolveAlias(key: string): string;
|
|
1445
|
+
protected findContextualBinding(needs: string): ServiceFactory<unknown> | null;
|
|
1446
|
+
}
|
|
1447
|
+
/**
|
|
1448
|
+
* Create a new container instance.
|
|
1449
|
+
*/
|
|
1450
|
+
declare function createContainer(): Container;
|
|
1451
|
+
declare function setContainer(container: Container): void;
|
|
1452
|
+
declare function getContainer(): Container;
|
|
1453
|
+
declare function resolve<T = unknown>(key: string): T;
|
|
1454
|
+
|
|
1455
|
+
/**
|
|
1456
|
+
* Constructor shape accepted wherever a provider class can be registered.
|
|
1457
|
+
*/
|
|
1458
|
+
type ServiceProviderConstructor = new (container: Container) => ServiceProvider;
|
|
1459
|
+
/**
|
|
1460
|
+
* Base service provider class.
|
|
1461
|
+
*
|
|
1462
|
+
* Service providers are the central place of all application bootstrapping.
|
|
1463
|
+
* Your own application, as well as all core services, are bootstrapped via providers.
|
|
1464
|
+
*
|
|
1465
|
+
* @example
|
|
1466
|
+
* ```typescript
|
|
1467
|
+
* export class AppServiceProvider extends ServiceProvider {
|
|
1468
|
+
* register(): void {
|
|
1469
|
+
* // Register bindings
|
|
1470
|
+
* this.container.singleton('db', (c) => new Database(c.make('config')))
|
|
1471
|
+
* }
|
|
1472
|
+
*
|
|
1473
|
+
* boot(): void {
|
|
1474
|
+
* // Bootstrap after all providers registered
|
|
1475
|
+
* const db = this.container.make<Database>('db')
|
|
1476
|
+
* db.connect()
|
|
1477
|
+
* }
|
|
1478
|
+
* }
|
|
1479
|
+
* ```
|
|
1480
|
+
*/
|
|
1481
|
+
declare abstract class ServiceProvider implements Provider {
|
|
1482
|
+
protected container: Container;
|
|
1483
|
+
/**
|
|
1484
|
+
* Whether this provider should be deferred.
|
|
1485
|
+
* Deferred providers are only loaded when one of their provided services is requested.
|
|
1486
|
+
*/
|
|
1487
|
+
static deferred: boolean;
|
|
1488
|
+
/**
|
|
1489
|
+
* The services provided by this provider (for deferred loading).
|
|
1490
|
+
*/
|
|
1491
|
+
static provides: string[];
|
|
1492
|
+
constructor(container: Container);
|
|
1493
|
+
/**
|
|
1494
|
+
* Register any application services.
|
|
1495
|
+
* This is called before any other providers have booted.
|
|
1496
|
+
*/
|
|
1497
|
+
abstract register(): void | Promise<void>;
|
|
1498
|
+
/**
|
|
1499
|
+
* Bootstrap any application services.
|
|
1500
|
+
* This is called after all providers have registered.
|
|
1501
|
+
*/
|
|
1502
|
+
boot?(): void | Promise<void>;
|
|
1503
|
+
/**
|
|
1504
|
+
* Get the services provided by the provider.
|
|
1505
|
+
*/
|
|
1506
|
+
provides(): string[];
|
|
1507
|
+
/**
|
|
1508
|
+
* Check if this provider is deferred.
|
|
1509
|
+
*/
|
|
1510
|
+
isDeferred(): boolean;
|
|
1511
|
+
}
|
|
1512
|
+
/**
|
|
1513
|
+
* Provider manager for registering and booting providers.
|
|
1514
|
+
*/
|
|
1515
|
+
declare class ProviderManager {
|
|
1516
|
+
protected container: Container;
|
|
1517
|
+
protected providers: ServiceProvider[];
|
|
1518
|
+
protected registered: Set<ServiceProvider>;
|
|
1519
|
+
protected booted: Set<ServiceProvider>;
|
|
1520
|
+
protected deferredProviders: Map<string, ServiceProvider>;
|
|
1521
|
+
private allBooted;
|
|
1522
|
+
constructor(container: Container);
|
|
1523
|
+
/**
|
|
1524
|
+
* Register a provider.
|
|
1525
|
+
*/
|
|
1526
|
+
register(providerOrClass: ServiceProvider | ServiceProviderConstructor): this;
|
|
1527
|
+
/**
|
|
1528
|
+
* Register multiple providers.
|
|
1529
|
+
*/
|
|
1530
|
+
registerMany(providers: Array<ServiceProvider | ServiceProviderConstructor>): this;
|
|
1531
|
+
/**
|
|
1532
|
+
* Register all non-deferred providers.
|
|
1533
|
+
*/
|
|
1534
|
+
registerAll(): Promise<void>;
|
|
1535
|
+
/**
|
|
1536
|
+
* Boot all registered providers.
|
|
1537
|
+
*/
|
|
1538
|
+
bootAll(): Promise<void>;
|
|
1539
|
+
/**
|
|
1540
|
+
* Load a deferred provider for a service.
|
|
1541
|
+
*/
|
|
1542
|
+
loadDeferredProvider(service: string): Promise<void>;
|
|
1543
|
+
/**
|
|
1544
|
+
* Check if a service is provided by a deferred provider.
|
|
1545
|
+
*/
|
|
1546
|
+
isDeferredService(service: string): boolean;
|
|
1547
|
+
/**
|
|
1548
|
+
* Get all registered providers.
|
|
1549
|
+
*/
|
|
1550
|
+
getProviders(): ServiceProvider[];
|
|
1551
|
+
/**
|
|
1552
|
+
* Get all deferred services.
|
|
1553
|
+
*/
|
|
1554
|
+
getDeferredServices(): string[];
|
|
1555
|
+
}
|
|
1556
|
+
|
|
1557
|
+
/**
|
|
1558
|
+
* Parsed argument definition.
|
|
1559
|
+
*/
|
|
1560
|
+
interface ArgumentDefinition {
|
|
1561
|
+
name: string;
|
|
1562
|
+
description?: string;
|
|
1563
|
+
required: boolean;
|
|
1564
|
+
array: boolean;
|
|
1565
|
+
defaultValue?: string;
|
|
1566
|
+
}
|
|
1567
|
+
/**
|
|
1568
|
+
* Parsed option definition.
|
|
1569
|
+
*/
|
|
1570
|
+
interface OptionDefinition {
|
|
1571
|
+
name: string;
|
|
1572
|
+
shortcut?: string;
|
|
1573
|
+
description?: string;
|
|
1574
|
+
requiresValue: boolean;
|
|
1575
|
+
defaultValue?: string | boolean;
|
|
1576
|
+
array: boolean;
|
|
1577
|
+
}
|
|
1578
|
+
/**
|
|
1579
|
+
* Parsed signature.
|
|
1580
|
+
*/
|
|
1581
|
+
interface ParsedSignature {
|
|
1582
|
+
name: string;
|
|
1583
|
+
arguments: ArgumentDefinition[];
|
|
1584
|
+
options: OptionDefinition[];
|
|
1585
|
+
}
|
|
1586
|
+
/**
|
|
1587
|
+
* Command class type.
|
|
1588
|
+
*/
|
|
1589
|
+
interface CommandClass {
|
|
1590
|
+
signature: string;
|
|
1591
|
+
description: string;
|
|
1592
|
+
new (container?: Container): CommandInstance;
|
|
1593
|
+
}
|
|
1594
|
+
/**
|
|
1595
|
+
* Command instance type.
|
|
1596
|
+
*/
|
|
1597
|
+
interface CommandInstance {
|
|
1598
|
+
setInput(argv: string[]): void;
|
|
1599
|
+
setOutput(output: OutputInterface): void;
|
|
1600
|
+
setKernel(kernel: {
|
|
1601
|
+
handle(argv: string[]): Promise<number>;
|
|
1602
|
+
}): void;
|
|
1603
|
+
run(): Promise<number>;
|
|
1604
|
+
}
|
|
1605
|
+
/**
|
|
1606
|
+
* Output interface.
|
|
1607
|
+
*/
|
|
1608
|
+
interface OutputInterface {
|
|
1609
|
+
info(message: string): void;
|
|
1610
|
+
error(message: string): void;
|
|
1611
|
+
warn(message: string): void;
|
|
1612
|
+
success(message: string): void;
|
|
1613
|
+
line(message: string): void;
|
|
1614
|
+
newLine(count?: number): void;
|
|
1615
|
+
table(headers: string[], rows: string[][]): void;
|
|
1616
|
+
write(message: string): void;
|
|
1617
|
+
}
|
|
1618
|
+
/**
|
|
1619
|
+
* Input interface.
|
|
1620
|
+
*/
|
|
1621
|
+
interface InputInterface {
|
|
1622
|
+
argument<T = string>(name: string): T;
|
|
1623
|
+
arguments(): Record<string, string | string[]>;
|
|
1624
|
+
option<T = string | boolean>(name: string): T | undefined;
|
|
1625
|
+
options(): Record<string, string | boolean | string[]>;
|
|
1626
|
+
hasOption(name: string): boolean;
|
|
1627
|
+
}
|
|
1628
|
+
/**
|
|
1629
|
+
* Console kernel options.
|
|
1630
|
+
*/
|
|
1631
|
+
interface ConsoleKernelOptions {
|
|
1632
|
+
container?: Container;
|
|
1633
|
+
}
|
|
1634
|
+
/**
|
|
1635
|
+
* Schedule definition for a command.
|
|
1636
|
+
*/
|
|
1637
|
+
interface ScheduledCommand {
|
|
1638
|
+
command: string;
|
|
1639
|
+
args?: string[];
|
|
1640
|
+
expression: string;
|
|
1641
|
+
timezone?: string;
|
|
1642
|
+
description?: string;
|
|
1643
|
+
}
|
|
1644
|
+
/**
|
|
1645
|
+
* Interactive prompt types.
|
|
1646
|
+
*/
|
|
1647
|
+
interface PromptInterface {
|
|
1648
|
+
ask(question: string, defaultValue?: string): Promise<string>;
|
|
1649
|
+
confirm(question: string, defaultValue?: boolean): Promise<boolean>;
|
|
1650
|
+
choice<T extends string>(question: string, choices: T[], defaultValue?: T): Promise<T>;
|
|
1651
|
+
secret(question: string): Promise<string>;
|
|
1652
|
+
}
|
|
1653
|
+
/**
|
|
1654
|
+
* Progress bar interface.
|
|
1655
|
+
*/
|
|
1656
|
+
interface ProgressInterface {
|
|
1657
|
+
start(total: number): void;
|
|
1658
|
+
advance(step?: number): void;
|
|
1659
|
+
finish(): void;
|
|
1660
|
+
setProgress(current: number): void;
|
|
1661
|
+
}
|
|
1662
|
+
|
|
1663
|
+
/**
|
|
1664
|
+
* Declarative definition of an application module — a self-contained
|
|
1665
|
+
* `modules/<name>/` directory that can register routes and providers, per
|
|
1666
|
+
* RFC 0002. Unlike `definePlugin()`, a module has no config stage and no
|
|
1667
|
+
* register/boot lifecycle of its own: it's a plain descriptor bundling
|
|
1668
|
+
* providers and a route registrar that `Application` folds into its own
|
|
1669
|
+
* provider list and route mounting.
|
|
1670
|
+
*/
|
|
1671
|
+
interface ModuleDefinition {
|
|
1672
|
+
/** Diagnostic name; also the expected directory name under `modules/`. */
|
|
1673
|
+
name: string;
|
|
1674
|
+
/**
|
|
1675
|
+
* URL prefix applied to all module routes via `router.group(prefix, ...)`.
|
|
1676
|
+
* Declarative on purpose — tooling can read a module's URL surface
|
|
1677
|
+
* statically without executing the registrar.
|
|
1678
|
+
*/
|
|
1679
|
+
prefix?: string;
|
|
1680
|
+
/** Route registrar, invoked after `options.routes` during boot. */
|
|
1681
|
+
routes?: (router: Router) => void | Promise<void>;
|
|
1682
|
+
/** Providers appended to the application's provider list. */
|
|
1683
|
+
providers?: ServiceProviderConstructor[];
|
|
1684
|
+
/**
|
|
1685
|
+
* Console commands the module owns, exposed so the project's console
|
|
1686
|
+
* entrypoint can register them without importing module internals:
|
|
1687
|
+
* `kernel.registerMany(billingModule.commands)`. Nothing registers them
|
|
1688
|
+
* automatically — `Application` never builds a `ConsoleKernel`, and
|
|
1689
|
+
* command registration stays explicit so a bundled deployment resolves
|
|
1690
|
+
* the same commands as a local checkout.
|
|
1691
|
+
*/
|
|
1692
|
+
commands?: CommandClass[];
|
|
1693
|
+
}
|
|
1694
|
+
/**
|
|
1695
|
+
* A module as `Application` consumes it — `providers` and `commands`
|
|
1696
|
+
* normalized to always be arrays so callers don't repeat the `?? []`
|
|
1697
|
+
* fallback. `commands` in particular is read by hand-written console
|
|
1698
|
+
* entrypoints (`kernel.registerMany(billingModule.commands)`), where an
|
|
1699
|
+
* `undefined` would be a runtime error rather than a no-op.
|
|
1700
|
+
*/
|
|
1701
|
+
interface GurenModule {
|
|
1702
|
+
name: string;
|
|
1703
|
+
prefix?: string;
|
|
1704
|
+
routes?: (router: Router) => void | Promise<void>;
|
|
1705
|
+
providers: ServiceProviderConstructor[];
|
|
1706
|
+
commands: CommandClass[];
|
|
1707
|
+
}
|
|
1708
|
+
/**
|
|
1709
|
+
* Define a Guren application module without boilerplate.
|
|
1710
|
+
*
|
|
1711
|
+
* @example
|
|
1712
|
+
* ```typescript
|
|
1713
|
+
* // modules/billing/index.ts
|
|
1714
|
+
* export const billingModule = defineModule({
|
|
1715
|
+
* name: 'billing',
|
|
1716
|
+
* prefix: '/billing',
|
|
1717
|
+
* routes: registerBillingRoutes,
|
|
1718
|
+
* providers: [BillingServiceProvider],
|
|
1719
|
+
* commands: [InvoiceCommand],
|
|
1720
|
+
* })
|
|
1721
|
+
*
|
|
1722
|
+
* // src/app.ts
|
|
1723
|
+
* createApp({ routes, providers, modules: [billingModule] })
|
|
1724
|
+
*
|
|
1725
|
+
* // src/console.ts
|
|
1726
|
+
* kernel.registerMany(billingModule.commands)
|
|
1727
|
+
* ```
|
|
1728
|
+
*/
|
|
1729
|
+
declare function defineModule(definition: ModuleDefinition): GurenModule;
|
|
1730
|
+
/**
|
|
1731
|
+
* Runs a module's route registrar against `router`, applying its `prefix`
|
|
1732
|
+
* via `router.group()` when set. Shared by `Application.mountRoutes()` (at
|
|
1733
|
+
* boot) and the CLI's route loader (for `guren codegen`/`audit`/`routes`/
|
|
1734
|
+
* `openapi:generate`, which need the same route set without booting a real
|
|
1735
|
+
* app) so both stay in sync — a bugfix to one path fixes the other.
|
|
1736
|
+
*
|
|
1737
|
+
* `router.group(prefix, callback)`'s callback is synchronous — it pushes
|
|
1738
|
+
* the prefix, invokes the callback, then pops it, with no support for
|
|
1739
|
+
* awaiting inside. Capturing the registrar's return value and awaiting it
|
|
1740
|
+
* after `group()` returns preserves prefixing for the common case (a
|
|
1741
|
+
* synchronous registrar, or an async one that calls `router.get`/`post`/
|
|
1742
|
+
* etc. before its first `await`); route calls after an `await` inside an
|
|
1743
|
+
* async, prefixed module registrar would run with the prefix already
|
|
1744
|
+
* popped. Registrars with no prefix don't go through group() and have no
|
|
1745
|
+
* such limitation.
|
|
1746
|
+
*/
|
|
1747
|
+
declare function mountModuleRoutes(router: Router, gurenModule: GurenModule): Promise<void>;
|
|
1748
|
+
|
|
1749
|
+
/** Structural type for DI containers, avoiding a hard dependency on Container. */
|
|
1750
|
+
interface ContainerLike {
|
|
1751
|
+
make(key: string): unknown;
|
|
1752
|
+
has?(key: string): boolean;
|
|
1753
|
+
}
|
|
1754
|
+
/**
|
|
1755
|
+
* Duck-type interface for Zod-like schemas.
|
|
1756
|
+
* Allows validation without a direct Zod dependency.
|
|
1757
|
+
*/
|
|
1758
|
+
interface ZodLikeSchema<T> {
|
|
1759
|
+
safeParse(data: unknown): {
|
|
1760
|
+
success: true;
|
|
1761
|
+
data: T;
|
|
1762
|
+
} | {
|
|
1763
|
+
success: false;
|
|
1764
|
+
error: {
|
|
1765
|
+
issues: Array<{
|
|
1377
1766
|
path: PropertyKey[];
|
|
1378
1767
|
message: string;
|
|
1379
1768
|
}>;
|
|
@@ -1544,320 +1933,114 @@ declare class Controller {
|
|
|
1544
1933
|
* ```typescript
|
|
1545
1934
|
* if (await this.can('update', [Post, post])) { ... }
|
|
1546
1935
|
* ```
|
|
1547
|
-
*/
|
|
1548
|
-
protected can(ability: string, ...args: unknown[]): Promise<boolean>;
|
|
1549
|
-
private gateUser;
|
|
1550
|
-
protected inertia<TPage extends InertiaPageContractLike>(page: TPage, props: InertiaPageProps<TPage>, options?: InertiaResponseOptions): Promise<InertiaResponse<InertiaPageComponent<TPage>, InertiaPageProps<TPage> & ResolvedSharedInertiaProps>>;
|
|
1551
|
-
protected inertia<Component extends string, Props extends DefaultInertiaProps>(component: Component, props: Props, options?: InertiaResponseOptions): Promise<InertiaResponse<Component, Props & ResolvedSharedInertiaProps>>;
|
|
1552
|
-
protected json<T>(data: T, init?: ResponseInit): Response;
|
|
1553
|
-
protected text(body: string, init?: ResponseInit): Response;
|
|
1554
|
-
protected redirect(url: string, options?: RedirectOptions): Response;
|
|
1555
|
-
/**
|
|
1556
|
-
* Return a 204 No Content response.
|
|
1557
|
-
*/
|
|
1558
|
-
protected noContent(): Response;
|
|
1559
|
-
/**
|
|
1560
|
-
* Return a 201 Created response with JSON data.
|
|
1561
|
-
*/
|
|
1562
|
-
protected created<T>(data?: T, init?: ResponseInit): Response;
|
|
1563
|
-
/**
|
|
1564
|
-
* Return a 202 Accepted response with optional JSON data.
|
|
1565
|
-
*/
|
|
1566
|
-
protected accepted<T>(data?: T, init?: ResponseInit): Response;
|
|
1567
|
-
private jsonStatus;
|
|
1568
|
-
/**
|
|
1569
|
-
* Get a specific input value from the request body or query parameters.
|
|
1570
|
-
* Body values take precedence over query parameters.
|
|
1571
|
-
*/
|
|
1572
|
-
protected input<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
|
|
1573
|
-
/**
|
|
1574
|
-
* Get a query parameter value.
|
|
1575
|
-
*/
|
|
1576
|
-
protected query(key: string, defaultValue?: string): string | undefined;
|
|
1577
|
-
/**
|
|
1578
|
-
* Get only the specified keys from the request body.
|
|
1579
|
-
*/
|
|
1580
|
-
protected only(...keys: string[]): Promise<Record<string, unknown>>;
|
|
1581
|
-
/**
|
|
1582
|
-
* Get all request body values except the specified keys.
|
|
1583
|
-
*/
|
|
1584
|
-
protected except(...keys: string[]): Promise<Record<string, unknown>>;
|
|
1585
|
-
/**
|
|
1586
|
-
* Check if a key exists in the request body.
|
|
1587
|
-
*/
|
|
1588
|
-
protected has(key: string): Promise<boolean>;
|
|
1589
|
-
/** Flatten query string arrays to scalar values for cleaner schema usage. */
|
|
1590
|
-
private flattenQueries;
|
|
1591
|
-
/**
|
|
1592
|
-
* Validate the request body against a Zod-like schema.
|
|
1593
|
-
* Throws ValidationException on failure.
|
|
1594
|
-
*
|
|
1595
|
-
* @example
|
|
1596
|
-
* ```typescript
|
|
1597
|
-
* const data = await this.validateBody(CreatePostSchema)
|
|
1598
|
-
* ```
|
|
1599
|
-
*/
|
|
1600
|
-
protected validateBody<T>(schema: ZodLikeSchema<T>): Promise<T>;
|
|
1601
|
-
/**
|
|
1602
|
-
* Validate query parameters against a Zod-like schema.
|
|
1603
|
-
* Throws ValidationException on failure.
|
|
1604
|
-
*
|
|
1605
|
-
* @example
|
|
1606
|
-
* ```typescript
|
|
1607
|
-
* const { page } = this.validateQuery(PageQuerySchema)
|
|
1608
|
-
* ```
|
|
1609
|
-
*/
|
|
1610
|
-
protected validateQuery<T>(schema: ZodLikeSchema<T>): T;
|
|
1611
|
-
/**
|
|
1612
|
-
* Validate route parameters against a Zod-like schema.
|
|
1613
|
-
* Throws ValidationException on failure.
|
|
1614
|
-
*
|
|
1615
|
-
* @example
|
|
1616
|
-
* ```typescript
|
|
1617
|
-
* const { id } = this.validateParams(PostIdParamSchema)
|
|
1618
|
-
* ```
|
|
1619
|
-
*/
|
|
1620
|
-
protected validateParams<T>(schema: ZodLikeSchema<T>): T;
|
|
1621
|
-
/**
|
|
1622
|
-
* Validate the request body against a Zod-like schema without throwing.
|
|
1623
|
-
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
1624
|
-
*
|
|
1625
|
-
* @example
|
|
1626
|
-
* ```typescript
|
|
1627
|
-
* const result = await this.validateBodySafe(CreatePostSchema)
|
|
1628
|
-
* if (!result.success) {
|
|
1629
|
-
* return this.inertia(pages.posts.New, { errors: result.errors }, { status: 422 })
|
|
1630
|
-
* }
|
|
1631
|
-
* const { title, body } = result.data
|
|
1632
|
-
* ```
|
|
1633
|
-
*/
|
|
1634
|
-
protected validateBodySafe<T>(schema: ZodLikeSchema<T>): Promise<SafeValidationResult<T>>;
|
|
1635
|
-
/**
|
|
1636
|
-
* Validate query parameters against a Zod-like schema without throwing.
|
|
1637
|
-
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
1638
|
-
*/
|
|
1639
|
-
protected validateQuerySafe<T>(schema: ZodLikeSchema<T>): SafeValidationResult<T>;
|
|
1640
|
-
/**
|
|
1641
|
-
* Validate route parameters against a Zod-like schema without throwing.
|
|
1642
|
-
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
1643
|
-
*/
|
|
1644
|
-
protected validateParamsSafe<T>(schema: ZodLikeSchema<T>): SafeValidationResult<T>;
|
|
1645
|
-
private runValidation;
|
|
1646
|
-
private runValidationSafe;
|
|
1647
|
-
private getBody;
|
|
1648
|
-
}
|
|
1649
|
-
|
|
1650
|
-
/**
|
|
1651
|
-
* Service factory function.
|
|
1652
|
-
*/
|
|
1653
|
-
type ServiceFactory<T> = (container: Container) => T;
|
|
1654
|
-
/**
|
|
1655
|
-
* Service class constructor.
|
|
1656
|
-
*/
|
|
1657
|
-
type ServiceClass<T> = new (...args: unknown[]) => T;
|
|
1658
|
-
/**
|
|
1659
|
-
* Service binding configuration.
|
|
1660
|
-
*/
|
|
1661
|
-
interface ServiceBinding {
|
|
1662
|
-
factory: ServiceFactory<unknown>;
|
|
1663
|
-
singleton: boolean;
|
|
1664
|
-
instance?: unknown;
|
|
1665
|
-
}
|
|
1666
|
-
/**
|
|
1667
|
-
* Contextual binding builder interface.
|
|
1668
|
-
*/
|
|
1669
|
-
interface ContextualBindingBuilder {
|
|
1670
|
-
needs(abstract: string): ContextualNeedsBuilder;
|
|
1671
|
-
}
|
|
1672
|
-
/**
|
|
1673
|
-
* Contextual needs builder interface.
|
|
1674
|
-
*/
|
|
1675
|
-
interface ContextualNeedsBuilder {
|
|
1676
|
-
give<T>(factory: ServiceFactory<T> | T): void;
|
|
1677
|
-
}
|
|
1678
|
-
/**
|
|
1679
|
-
* Contextual binding configuration.
|
|
1680
|
-
*/
|
|
1681
|
-
interface ContextualBinding {
|
|
1682
|
-
concrete: string;
|
|
1683
|
-
needs: string;
|
|
1684
|
-
factory: ServiceFactory<unknown>;
|
|
1685
|
-
}
|
|
1686
|
-
/**
|
|
1687
|
-
* Service provider options.
|
|
1688
|
-
*/
|
|
1689
|
-
interface ServiceProviderOptions {
|
|
1690
|
-
/**
|
|
1691
|
-
* Whether this provider should be deferred.
|
|
1692
|
-
*/
|
|
1693
|
-
deferred?: boolean;
|
|
1694
|
-
/**
|
|
1695
|
-
* Services this provider provides (for deferred loading).
|
|
1696
|
-
*/
|
|
1697
|
-
provides?: string[];
|
|
1698
|
-
}
|
|
1699
|
-
/**
|
|
1700
|
-
* Provider interface for container-based service providers.
|
|
1701
|
-
*/
|
|
1702
|
-
interface Provider {
|
|
1703
|
-
register?(context: unknown): void | Promise<void>;
|
|
1704
|
-
boot?(context: unknown): void | Promise<void>;
|
|
1705
|
-
}
|
|
1706
|
-
/**
|
|
1707
|
-
* Service provider class type.
|
|
1708
|
-
*/
|
|
1709
|
-
interface ServiceProviderClass {
|
|
1710
|
-
new (container: Container): Provider;
|
|
1711
|
-
deferred?: boolean;
|
|
1712
|
-
provides?: string[];
|
|
1713
|
-
}
|
|
1714
|
-
|
|
1715
|
-
/**
|
|
1716
|
-
* Dependency injection container with type-safe service resolution.
|
|
1717
|
-
*
|
|
1718
|
-
* @example
|
|
1719
|
-
* ```typescript
|
|
1720
|
-
* const container = new Container()
|
|
1721
|
-
*
|
|
1722
|
-
* // Register services
|
|
1723
|
-
* container.singleton('events', (c) => new EventManager())
|
|
1724
|
-
* container.instance('config', loadConfig())
|
|
1725
|
-
*
|
|
1726
|
-
* // Type-safe resolution (known bindings)
|
|
1727
|
-
* const events = container.make('events') // EventManager
|
|
1728
|
-
*
|
|
1729
|
-
* // Generic resolution (custom bindings)
|
|
1730
|
-
* const db = container.make<Database>('db')
|
|
1731
|
-
* ```
|
|
1732
|
-
*/
|
|
1733
|
-
declare class Container {
|
|
1734
|
-
protected bindings: Map<string, ServiceBinding>;
|
|
1735
|
-
protected aliases: Map<string, string>;
|
|
1736
|
-
protected tags: Map<string, Set<string>>;
|
|
1737
|
-
protected contextualBindings: ContextualBinding[];
|
|
1738
|
-
protected resolvingStack: string[];
|
|
1739
|
-
protected scopedInstances: Map<string, unknown>[];
|
|
1740
|
-
protected fakes: Map<string, unknown>;
|
|
1741
|
-
/** @internal Used by ProviderManager to resolve deferred providers on demand */
|
|
1742
|
-
deferredProviderLoader: ((service: string) => Promise<void>) | null;
|
|
1743
|
-
/**
|
|
1744
|
-
* Bind a service to the container.
|
|
1745
|
-
* Each resolution creates a new instance.
|
|
1746
|
-
*/
|
|
1747
|
-
bind<T>(key: string, factory: ServiceFactory<T>): this;
|
|
1748
|
-
/**
|
|
1749
|
-
* Bind a singleton service to the container.
|
|
1750
|
-
* Only one instance is created and reused.
|
|
1751
|
-
*/
|
|
1752
|
-
singleton<T>(key: string, factory: ServiceFactory<T>): this;
|
|
1753
|
-
/**
|
|
1754
|
-
* Bind an existing instance to the container.
|
|
1755
|
-
*/
|
|
1756
|
-
instance<T>(key: string, value: T): this;
|
|
1757
|
-
/**
|
|
1758
|
-
* Resolve a service from the container.
|
|
1759
|
-
*
|
|
1760
|
-
* Known service keys (from ServiceBindings) are automatically typed:
|
|
1761
|
-
* ```typescript
|
|
1762
|
-
* container.make('events') // EventManager
|
|
1763
|
-
* container.make('cache') // CacheManager
|
|
1764
|
-
* ```
|
|
1765
|
-
*
|
|
1766
|
-
* Custom keys require an explicit type parameter:
|
|
1767
|
-
* ```typescript
|
|
1768
|
-
* container.make<MyService>('myService')
|
|
1769
|
-
* ```
|
|
1770
|
-
*/
|
|
1771
|
-
make<K extends keyof ServiceBindings>(key: K): ServiceBindings[K];
|
|
1772
|
-
make<T>(key: string): T;
|
|
1936
|
+
*/
|
|
1937
|
+
protected can(ability: string, ...args: unknown[]): Promise<boolean>;
|
|
1938
|
+
private gateUser;
|
|
1939
|
+
protected inertia<TPage extends InertiaPageContractLike>(page: TPage, props: InertiaPageProps<TPage>, options?: InertiaResponseOptions): Promise<InertiaResponse<InertiaPageComponent<TPage>, InertiaPageProps<TPage> & ResolvedSharedInertiaProps>>;
|
|
1940
|
+
protected inertia<Component extends string, Props extends DefaultInertiaProps>(component: Component, props: Props, options?: InertiaResponseOptions): Promise<InertiaResponse<Component, Props & ResolvedSharedInertiaProps>>;
|
|
1941
|
+
protected json<T>(data: T, init?: ResponseInit): Response;
|
|
1942
|
+
protected text(body: string, init?: ResponseInit): Response;
|
|
1943
|
+
protected redirect(url: string, options?: RedirectOptions): Response;
|
|
1773
1944
|
/**
|
|
1774
|
-
*
|
|
1945
|
+
* Return a 204 No Content response.
|
|
1775
1946
|
*/
|
|
1776
|
-
|
|
1947
|
+
protected noContent(): Response;
|
|
1777
1948
|
/**
|
|
1778
|
-
*
|
|
1949
|
+
* Return a 201 Created response with JSON data.
|
|
1779
1950
|
*/
|
|
1780
|
-
|
|
1951
|
+
protected created<T>(data?: T, init?: ResponseInit): Response;
|
|
1781
1952
|
/**
|
|
1782
|
-
*
|
|
1953
|
+
* Return a 202 Accepted response with optional JSON data.
|
|
1783
1954
|
*/
|
|
1784
|
-
|
|
1955
|
+
protected accepted<T>(data?: T, init?: ResponseInit): Response;
|
|
1956
|
+
private jsonStatus;
|
|
1785
1957
|
/**
|
|
1786
|
-
*
|
|
1958
|
+
* Get a specific input value from the request body or query parameters.
|
|
1959
|
+
* Body values take precedence over query parameters.
|
|
1787
1960
|
*/
|
|
1788
|
-
|
|
1961
|
+
protected input<T = unknown>(key: string, defaultValue?: T): Promise<T | undefined>;
|
|
1789
1962
|
/**
|
|
1790
|
-
*
|
|
1963
|
+
* Get a query parameter value.
|
|
1791
1964
|
*/
|
|
1792
|
-
|
|
1965
|
+
protected query(key: string, defaultValue?: string): string | undefined;
|
|
1793
1966
|
/**
|
|
1794
|
-
*
|
|
1967
|
+
* Get only the specified keys from the request body.
|
|
1795
1968
|
*/
|
|
1796
|
-
|
|
1969
|
+
protected only(...keys: string[]): Promise<Record<string, unknown>>;
|
|
1797
1970
|
/**
|
|
1798
|
-
*
|
|
1799
|
-
* Services resolved within the scope are cached and released when the scope ends.
|
|
1971
|
+
* Get all request body values except the specified keys.
|
|
1800
1972
|
*/
|
|
1801
|
-
|
|
1973
|
+
protected except(...keys: string[]): Promise<Record<string, unknown>>;
|
|
1802
1974
|
/**
|
|
1803
|
-
*
|
|
1975
|
+
* Check if a key exists in the request body.
|
|
1804
1976
|
*/
|
|
1805
|
-
|
|
1977
|
+
protected has(key: string): Promise<boolean>;
|
|
1978
|
+
/** Flatten query string arrays to scalar values for cleaner schema usage. */
|
|
1979
|
+
private flattenQueries;
|
|
1806
1980
|
/**
|
|
1807
|
-
*
|
|
1808
|
-
*
|
|
1981
|
+
* Validate the request body against a Zod-like schema.
|
|
1982
|
+
* Throws ValidationException on failure.
|
|
1809
1983
|
*
|
|
1810
1984
|
* @example
|
|
1811
1985
|
* ```typescript
|
|
1812
|
-
*
|
|
1813
|
-
* using _ = container.fake('events', fakeEventManager)
|
|
1814
|
-
*
|
|
1815
|
-
* // Manual cleanup
|
|
1816
|
-
* const restore = container.fake('mail', fakeMailManager)
|
|
1817
|
-
* // ... run tests ...
|
|
1818
|
-
* restore[Symbol.dispose]()
|
|
1986
|
+
* const data = await this.validateBody(CreatePostSchema)
|
|
1819
1987
|
* ```
|
|
1820
1988
|
*/
|
|
1821
|
-
|
|
1822
|
-
fake(key: string, instance: unknown): Disposable;
|
|
1823
|
-
/**
|
|
1824
|
-
* Check if a service is currently faked.
|
|
1825
|
-
*/
|
|
1826
|
-
isFaked(key: string): boolean;
|
|
1827
|
-
/**
|
|
1828
|
-
* Remove all fakes.
|
|
1829
|
-
*/
|
|
1830
|
-
clearFakes(): void;
|
|
1989
|
+
protected validateBody<T>(schema: ZodLikeSchema<T>): Promise<T>;
|
|
1831
1990
|
/**
|
|
1832
|
-
*
|
|
1991
|
+
* Validate query parameters against a Zod-like schema.
|
|
1992
|
+
* Throws ValidationException on failure.
|
|
1993
|
+
*
|
|
1994
|
+
* @example
|
|
1995
|
+
* ```typescript
|
|
1996
|
+
* const { page } = this.validateQuery(PageQuerySchema)
|
|
1997
|
+
* ```
|
|
1833
1998
|
*/
|
|
1834
|
-
|
|
1999
|
+
protected validateQuery<T>(schema: ZodLikeSchema<T>): T;
|
|
1835
2000
|
/**
|
|
1836
|
-
*
|
|
2001
|
+
* Validate route parameters against a Zod-like schema.
|
|
2002
|
+
* Throws ValidationException on failure.
|
|
2003
|
+
*
|
|
2004
|
+
* @example
|
|
2005
|
+
* ```typescript
|
|
2006
|
+
* const { id } = this.validateParams(PostIdParamSchema)
|
|
2007
|
+
* ```
|
|
1837
2008
|
*/
|
|
1838
|
-
|
|
2009
|
+
protected validateParams<T>(schema: ZodLikeSchema<T>): T;
|
|
1839
2010
|
/**
|
|
1840
|
-
*
|
|
2011
|
+
* Validate the request body against a Zod-like schema without throwing.
|
|
2012
|
+
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
2013
|
+
*
|
|
2014
|
+
* @example
|
|
2015
|
+
* ```typescript
|
|
2016
|
+
* const result = await this.validateBodySafe(CreatePostSchema)
|
|
2017
|
+
* if (!result.success) {
|
|
2018
|
+
* return this.inertia(pages.posts.New, { errors: result.errors }, { status: 422 })
|
|
2019
|
+
* }
|
|
2020
|
+
* const { title, body } = result.data
|
|
2021
|
+
* ```
|
|
1841
2022
|
*/
|
|
1842
|
-
|
|
2023
|
+
protected validateBodySafe<T>(schema: ZodLikeSchema<T>): Promise<SafeValidationResult<T>>;
|
|
1843
2024
|
/**
|
|
1844
|
-
*
|
|
2025
|
+
* Validate query parameters against a Zod-like schema without throwing.
|
|
2026
|
+
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
1845
2027
|
*/
|
|
1846
|
-
|
|
2028
|
+
protected validateQuerySafe<T>(schema: ZodLikeSchema<T>): SafeValidationResult<T>;
|
|
1847
2029
|
/**
|
|
1848
|
-
*
|
|
2030
|
+
* Validate route parameters against a Zod-like schema without throwing.
|
|
2031
|
+
* Returns a discriminated union: `{ success: true, data }` or `{ success: false, errors }`.
|
|
1849
2032
|
*/
|
|
1850
|
-
|
|
1851
|
-
|
|
1852
|
-
|
|
2033
|
+
protected validateParamsSafe<T>(schema: ZodLikeSchema<T>): SafeValidationResult<T>;
|
|
2034
|
+
private runValidation;
|
|
2035
|
+
private runValidationSafe;
|
|
2036
|
+
private getBody;
|
|
2037
|
+
}
|
|
2038
|
+
|
|
2039
|
+
interface MiddlewareCapabilities {
|
|
2040
|
+
authentication?: {
|
|
2041
|
+
mode: 'required' | 'guest-only';
|
|
2042
|
+
};
|
|
1853
2043
|
}
|
|
1854
|
-
/**
|
|
1855
|
-
* Create a new container instance.
|
|
1856
|
-
*/
|
|
1857
|
-
declare function createContainer(): Container;
|
|
1858
|
-
declare function setContainer(container: Container): void;
|
|
1859
|
-
declare function getContainer(): Container;
|
|
1860
|
-
declare function resolve<T = unknown>(key: string): T;
|
|
1861
2044
|
|
|
1862
2045
|
/**
|
|
1863
2046
|
* Constructor type for Controller classes.
|
|
@@ -1945,6 +2128,15 @@ interface RouteDefinition {
|
|
|
1945
2128
|
middlewareNames?: string[];
|
|
1946
2129
|
/** Whether inline (unnamed) middleware handlers are attached */
|
|
1947
2130
|
hasInlineMiddleware?: boolean;
|
|
2131
|
+
/**
|
|
2132
|
+
* Security capabilities aggregated from the route's middleware chain
|
|
2133
|
+
* (named aliases, groups, and inline handlers). Always present on routers
|
|
2134
|
+
* from this release — an empty object means "no recognized capability" —
|
|
2135
|
+
* so consumers can distinguish that from definitions produced by older
|
|
2136
|
+
* servers, where the field is absent. The value shape is internal and may
|
|
2137
|
+
* change (RFC 0007).
|
|
2138
|
+
*/
|
|
2139
|
+
capabilities?: MiddlewareCapabilities;
|
|
1948
2140
|
/** Controller binding when the handler is a [Controller, 'method'] tuple */
|
|
1949
2141
|
controller?: {
|
|
1950
2142
|
name: string;
|
|
@@ -2019,207 +2211,118 @@ declare class Router<M extends string = never> {
|
|
|
2019
2211
|
patch<C extends ControllerConstructor, TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: ControllerAction<C>): RouteBuilder<M>;
|
|
2020
2212
|
delete<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2021
2213
|
delete<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2022
|
-
delete<C extends ControllerConstructor, TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: ControllerAction<C>): RouteBuilder<M>;
|
|
2023
|
-
group(prefix: string, callback: (router: Router<M>) => void): this;
|
|
2024
|
-
route(name: string, params?: Record<string, string | number>): string;
|
|
2025
|
-
hasRoute(name: string): boolean;
|
|
2026
|
-
resource<C extends ControllerConstructor>(path: string, controller: C, options?: ResourceRouteOptions): this;
|
|
2027
|
-
mount(app: Hono, options?: RouterMountOptions): void;
|
|
2028
|
-
clear(): void;
|
|
2029
|
-
resetMiddleware(): void;
|
|
2030
|
-
definitions(): RouteDefinition[];
|
|
2031
|
-
applyMiddlewareScope<T>(names: string[], callback: () => T): T;
|
|
2032
|
-
private register;
|
|
2033
|
-
private add;
|
|
2034
|
-
private resolveMiddlewareNames;
|
|
2035
|
-
}
|
|
2036
|
-
declare class RouterMiddlewareGroupBuilder<M extends string = never> {
|
|
2037
|
-
private readonly router;
|
|
2038
|
-
private readonly names;
|
|
2039
|
-
constructor(router: Router<M>, names: string[]);
|
|
2040
|
-
group(callback: (router: Router<M>) => void): Router<M>;
|
|
2041
|
-
get<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2042
|
-
get<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2043
|
-
post<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2044
|
-
post<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2045
|
-
put<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2046
|
-
put<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2047
|
-
patch<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2048
|
-
patch<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2049
|
-
delete<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2050
|
-
delete<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2051
|
-
}
|
|
2052
|
-
|
|
2053
|
-
/**
|
|
2054
|
-
* Constructor shape accepted wherever a provider class can be registered.
|
|
2055
|
-
*/
|
|
2056
|
-
type ServiceProviderConstructor = new (container: Container) => ServiceProvider;
|
|
2057
|
-
/**
|
|
2058
|
-
* Base service provider class.
|
|
2059
|
-
*
|
|
2060
|
-
* Service providers are the central place of all application bootstrapping.
|
|
2061
|
-
* Your own application, as well as all core services, are bootstrapped via providers.
|
|
2062
|
-
*
|
|
2063
|
-
* @example
|
|
2064
|
-
* ```typescript
|
|
2065
|
-
* export class AppServiceProvider extends ServiceProvider {
|
|
2066
|
-
* register(): void {
|
|
2067
|
-
* // Register bindings
|
|
2068
|
-
* this.container.singleton('db', (c) => new Database(c.make('config')))
|
|
2069
|
-
* }
|
|
2070
|
-
*
|
|
2071
|
-
* boot(): void {
|
|
2072
|
-
* // Bootstrap after all providers registered
|
|
2073
|
-
* const db = this.container.make<Database>('db')
|
|
2074
|
-
* db.connect()
|
|
2075
|
-
* }
|
|
2076
|
-
* }
|
|
2077
|
-
* ```
|
|
2078
|
-
*/
|
|
2079
|
-
declare abstract class ServiceProvider implements Provider {
|
|
2080
|
-
protected container: Container;
|
|
2081
|
-
/**
|
|
2082
|
-
* Whether this provider should be deferred.
|
|
2083
|
-
* Deferred providers are only loaded when one of their provided services is requested.
|
|
2084
|
-
*/
|
|
2085
|
-
static deferred: boolean;
|
|
2086
|
-
/**
|
|
2087
|
-
* The services provided by this provider (for deferred loading).
|
|
2088
|
-
*/
|
|
2089
|
-
static provides: string[];
|
|
2090
|
-
constructor(container: Container);
|
|
2091
|
-
/**
|
|
2092
|
-
* Register any application services.
|
|
2093
|
-
* This is called before any other providers have booted.
|
|
2094
|
-
*/
|
|
2095
|
-
abstract register(): void | Promise<void>;
|
|
2096
|
-
/**
|
|
2097
|
-
* Bootstrap any application services.
|
|
2098
|
-
* This is called after all providers have registered.
|
|
2099
|
-
*/
|
|
2100
|
-
boot?(): void | Promise<void>;
|
|
2101
|
-
/**
|
|
2102
|
-
* Get the services provided by the provider.
|
|
2103
|
-
*/
|
|
2104
|
-
provides(): string[];
|
|
2105
|
-
/**
|
|
2106
|
-
* Check if this provider is deferred.
|
|
2107
|
-
*/
|
|
2108
|
-
isDeferred(): boolean;
|
|
2109
|
-
}
|
|
2110
|
-
/**
|
|
2111
|
-
* Provider manager for registering and booting providers.
|
|
2112
|
-
*/
|
|
2113
|
-
declare class ProviderManager {
|
|
2114
|
-
protected container: Container;
|
|
2115
|
-
protected providers: ServiceProvider[];
|
|
2116
|
-
protected registered: Set<ServiceProvider>;
|
|
2117
|
-
protected booted: Set<ServiceProvider>;
|
|
2118
|
-
protected deferredProviders: Map<string, ServiceProvider>;
|
|
2119
|
-
private allBooted;
|
|
2120
|
-
constructor(container: Container);
|
|
2121
|
-
/**
|
|
2122
|
-
* Register a provider.
|
|
2123
|
-
*/
|
|
2124
|
-
register(providerOrClass: ServiceProvider | ServiceProviderConstructor): this;
|
|
2125
|
-
/**
|
|
2126
|
-
* Register multiple providers.
|
|
2127
|
-
*/
|
|
2128
|
-
registerMany(providers: Array<ServiceProvider | ServiceProviderConstructor>): this;
|
|
2129
|
-
/**
|
|
2130
|
-
* Register all non-deferred providers.
|
|
2131
|
-
*/
|
|
2132
|
-
registerAll(): Promise<void>;
|
|
2133
|
-
/**
|
|
2134
|
-
* Boot all registered providers.
|
|
2135
|
-
*/
|
|
2136
|
-
bootAll(): Promise<void>;
|
|
2137
|
-
/**
|
|
2138
|
-
* Load a deferred provider for a service.
|
|
2139
|
-
*/
|
|
2140
|
-
loadDeferredProvider(service: string): Promise<void>;
|
|
2141
|
-
/**
|
|
2142
|
-
* Check if a service is provided by a deferred provider.
|
|
2143
|
-
*/
|
|
2144
|
-
isDeferredService(service: string): boolean;
|
|
2145
|
-
/**
|
|
2146
|
-
* Get all registered providers.
|
|
2147
|
-
*/
|
|
2148
|
-
getProviders(): ServiceProvider[];
|
|
2214
|
+
delete<C extends ControllerConstructor, TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: ControllerAction<C>): RouteBuilder<M>;
|
|
2215
|
+
group(prefix: string, callback: (router: Router<M>) => void): this;
|
|
2216
|
+
route(name: string, params?: Record<string, string | number>): string;
|
|
2217
|
+
hasRoute(name: string): boolean;
|
|
2218
|
+
resource<C extends ControllerConstructor>(path: string, controller: C, options?: ResourceRouteOptions): this;
|
|
2219
|
+
mount(app: Hono, options?: RouterMountOptions): void;
|
|
2220
|
+
clear(): void;
|
|
2221
|
+
resetMiddleware(): void;
|
|
2222
|
+
definitions(): RouteDefinition[];
|
|
2223
|
+
applyMiddlewareScope<T>(names: string[], callback: () => T): T;
|
|
2224
|
+
private register;
|
|
2225
|
+
private add;
|
|
2149
2226
|
/**
|
|
2150
|
-
*
|
|
2227
|
+
* Security capabilities present on a route's middleware chain, aggregated
|
|
2228
|
+
* across named aliases (group-expanded) and inline handlers. Unlike
|
|
2229
|
+
* `resolveMiddlewareNames`, unregistered names are skipped rather than
|
|
2230
|
+
* thrown: `definitions()` must stay side-effect-free for introspection of
|
|
2231
|
+
* routers that never mount (audit, codegen), and an unresolvable alias
|
|
2232
|
+
* simply contributes no capabilities.
|
|
2151
2233
|
*/
|
|
2152
|
-
|
|
2234
|
+
private aggregateCapabilities;
|
|
2235
|
+
private resolveMiddlewareNames;
|
|
2236
|
+
}
|
|
2237
|
+
declare class RouterMiddlewareGroupBuilder<M extends string = never> {
|
|
2238
|
+
private readonly router;
|
|
2239
|
+
private readonly names;
|
|
2240
|
+
constructor(router: Router<M>, names: string[]);
|
|
2241
|
+
group(callback: (router: Router<M>) => void): Router<M>;
|
|
2242
|
+
get<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2243
|
+
get<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2244
|
+
post<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2245
|
+
post<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2246
|
+
put<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2247
|
+
put<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2248
|
+
patch<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2249
|
+
patch<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2250
|
+
delete<C extends ControllerConstructor>(path: string, handler: RouteHandler<C>, ...middlewares: MiddlewareHandler[]): RouteBuilder<M>;
|
|
2251
|
+
delete<TParamsSchema extends SchemaLike<unknown>, TQuerySchema extends SchemaLike<unknown>, TBodySchema extends SchemaLike<unknown>, TOutputSchema extends SchemaLike<unknown>>(path: string, options: RouteContractOptions<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>, handler: TypedRouteHandler<TParamsSchema, TQuerySchema, TBodySchema, TOutputSchema>): RouteBuilder<M>;
|
|
2153
2252
|
}
|
|
2154
2253
|
|
|
2155
|
-
|
|
2156
|
-
|
|
2157
|
-
|
|
2158
|
-
|
|
2159
|
-
|
|
2160
|
-
|
|
2161
|
-
|
|
2162
|
-
|
|
2163
|
-
interface
|
|
2164
|
-
/**
|
|
2165
|
-
|
|
2254
|
+
interface HstsOptions {
|
|
2255
|
+
/** Max age in seconds. */
|
|
2256
|
+
maxAge: number;
|
|
2257
|
+
/** Include subdomains. Default: false */
|
|
2258
|
+
includeSubDomains?: boolean;
|
|
2259
|
+
/** Enable HSTS preload. Default: false */
|
|
2260
|
+
preload?: boolean;
|
|
2261
|
+
}
|
|
2262
|
+
interface SecurityHeadersOptions {
|
|
2263
|
+
/** X-Frame-Options header. Set to false to disable. Default: 'SAMEORIGIN' */
|
|
2264
|
+
frameOptions?: string | false;
|
|
2265
|
+
/** X-Content-Type-Options header. Set to false to disable. Default: 'nosniff' */
|
|
2266
|
+
contentTypeOptions?: string | false;
|
|
2267
|
+
/** X-XSS-Protection header. Set to false to disable. Default: '0' */
|
|
2268
|
+
xssProtection?: string | false;
|
|
2269
|
+
/** Referrer-Policy header. Set to false to disable. Default: 'strict-origin-when-cross-origin' */
|
|
2270
|
+
referrerPolicy?: string | false;
|
|
2271
|
+
/** X-Permitted-Cross-Domain-Policies header. Set to false to disable. Default: 'none' */
|
|
2272
|
+
crossDomainPolicies?: string | false;
|
|
2166
2273
|
/**
|
|
2167
|
-
*
|
|
2168
|
-
*
|
|
2169
|
-
*
|
|
2274
|
+
* Strict-Transport-Security header.
|
|
2275
|
+
* Default: `{ maxAge: 31536000 }` (1 year) when NODE_ENV is 'production', false otherwise.
|
|
2276
|
+
* Browsers ignore HSTS on plain-HTTP responses, so the production default is safe behind TLS terminators.
|
|
2170
2277
|
*/
|
|
2171
|
-
|
|
2172
|
-
/** Route registrar, invoked after `options.routes` during boot. */
|
|
2173
|
-
routes?: (router: Router) => void | Promise<void>;
|
|
2174
|
-
/** Providers appended to the application's provider list. */
|
|
2175
|
-
providers?: ServiceProviderConstructor[];
|
|
2176
|
-
}
|
|
2177
|
-
/**
|
|
2178
|
-
* A module as `Application` consumes it — `providers` normalized to always
|
|
2179
|
-
* be an array so callers don't repeat the `?? []` fallback.
|
|
2180
|
-
*/
|
|
2181
|
-
interface GurenModule {
|
|
2182
|
-
name: string;
|
|
2183
|
-
prefix?: string;
|
|
2184
|
-
routes?: (router: Router) => void | Promise<void>;
|
|
2185
|
-
providers: ServiceProviderConstructor[];
|
|
2278
|
+
hsts?: HstsOptions | false;
|
|
2186
2279
|
}
|
|
2187
2280
|
/**
|
|
2188
|
-
*
|
|
2281
|
+
* Middleware that sets common HTTP security headers on every response.
|
|
2189
2282
|
*
|
|
2190
2283
|
* @example
|
|
2191
|
-
* ```
|
|
2192
|
-
*
|
|
2193
|
-
* export const billingModule = defineModule({
|
|
2194
|
-
* name: 'billing',
|
|
2195
|
-
* prefix: '/billing',
|
|
2196
|
-
* routes: registerBillingRoutes,
|
|
2197
|
-
* providers: [BillingServiceProvider],
|
|
2198
|
-
* })
|
|
2284
|
+
* ```ts
|
|
2285
|
+
* import { createSecurityHeaders } from '@guren/core'
|
|
2199
2286
|
*
|
|
2200
|
-
*
|
|
2201
|
-
*
|
|
2287
|
+
* app.use('*', createSecurityHeaders())
|
|
2288
|
+
*
|
|
2289
|
+
* // With HSTS enabled
|
|
2290
|
+
* app.use('*', createSecurityHeaders({
|
|
2291
|
+
* hsts: { maxAge: 31536000, includeSubDomains: true },
|
|
2292
|
+
* }))
|
|
2293
|
+
*
|
|
2294
|
+
* // Disable specific headers
|
|
2295
|
+
* app.use('*', createSecurityHeaders({
|
|
2296
|
+
* frameOptions: false,
|
|
2297
|
+
* xssProtection: false,
|
|
2298
|
+
* }))
|
|
2202
2299
|
* ```
|
|
2203
2300
|
*/
|
|
2204
|
-
declare function
|
|
2301
|
+
declare function createSecurityHeaders(options?: SecurityHeadersOptions): MiddlewareHandler;
|
|
2302
|
+
|
|
2303
|
+
interface HostAuthorizationOptions {
|
|
2304
|
+
/** Allowed hosts. Supports exact matches and wildcard subdomains (e.g., '*.example.com'). */
|
|
2305
|
+
allowedHosts: string[];
|
|
2306
|
+
/** Paths to exclude from host checking (e.g., ['/healthcheck', '/up']). */
|
|
2307
|
+
exclude?: string[];
|
|
2308
|
+
/** Custom response when host is not authorized. Default: 403 Forbidden. */
|
|
2309
|
+
onError?: (ctx: Context) => Response | Promise<Response>;
|
|
2310
|
+
}
|
|
2205
2311
|
/**
|
|
2206
|
-
*
|
|
2207
|
-
*
|
|
2208
|
-
* boot) and the CLI's route loader (for `guren codegen`/`audit`/`routes`/
|
|
2209
|
-
* `openapi:generate`, which need the same route set without booting a real
|
|
2210
|
-
* app) so both stay in sync — a bugfix to one path fixes the other.
|
|
2312
|
+
* Middleware that validates the Host header against an allowed list.
|
|
2313
|
+
* Protects against DNS rebinding and host header attacks.
|
|
2211
2314
|
*
|
|
2212
|
-
*
|
|
2213
|
-
*
|
|
2214
|
-
*
|
|
2215
|
-
*
|
|
2216
|
-
*
|
|
2217
|
-
*
|
|
2218
|
-
*
|
|
2219
|
-
*
|
|
2220
|
-
*
|
|
2315
|
+
* @example
|
|
2316
|
+
* ```ts
|
|
2317
|
+
* import { createHostAuthorizationMiddleware } from '@guren/core'
|
|
2318
|
+
*
|
|
2319
|
+
* app.use('*', createHostAuthorizationMiddleware({
|
|
2320
|
+
* allowedHosts: ['example.com', '*.example.com', 'localhost:3000'],
|
|
2321
|
+
* exclude: ['/healthcheck'],
|
|
2322
|
+
* }))
|
|
2323
|
+
* ```
|
|
2221
2324
|
*/
|
|
2222
|
-
declare function
|
|
2325
|
+
declare function createHostAuthorizationMiddleware(options: HostAuthorizationOptions): MiddlewareHandler;
|
|
2223
2326
|
|
|
2224
2327
|
declare const GUREN_ASCII_ART: string;
|
|
2225
2328
|
interface DevBannerOptions {
|
|
@@ -2333,10 +2436,16 @@ declare class Application {
|
|
|
2333
2436
|
private mountSecurityDefaults;
|
|
2334
2437
|
private mountHostAuthorization;
|
|
2335
2438
|
/**
|
|
2336
|
-
* Mounts
|
|
2337
|
-
*
|
|
2439
|
+
* Mounts an opt-in, dev-only framework endpoint: the MCP endpoint
|
|
2440
|
+
* (/_guren/mcp) and the docs viewer (/_guren/docs) both work this way.
|
|
2441
|
+
*
|
|
2442
|
+
* Only the dynamic import is allowed to fail silently — these
|
|
2443
|
+
* providers reach optional dependencies (the MCP SDK, @guren/cli) that
|
|
2444
|
+
* an app need not have installed, and `missing` names that case. A
|
|
2445
|
+
* failure inside the provider's own boot is a real problem and is
|
|
2446
|
+
* rethrown, rather than leaving the developer with a silent 404.
|
|
2338
2447
|
*/
|
|
2339
|
-
private
|
|
2448
|
+
private mountDevEndpoint;
|
|
2340
2449
|
/**
|
|
2341
2450
|
* Fetch handler to integrate with Bun.serve or any standard Fetch runtime.
|
|
2342
2451
|
*/
|
|
@@ -2363,4 +2472,114 @@ declare class Application {
|
|
|
2363
2472
|
}
|
|
2364
2473
|
declare function createApp(options?: ApplicationOptions): Application;
|
|
2365
2474
|
|
|
2366
|
-
|
|
2475
|
+
/**
|
|
2476
|
+
* Parses the incoming request payload supporting both JSON bodies and form submissions.
|
|
2477
|
+
* Falls back to an empty object if the payload cannot be parsed.
|
|
2478
|
+
*/
|
|
2479
|
+
declare function parseRequestPayload(ctx: Context): Promise<Record<string, unknown>>;
|
|
2480
|
+
interface ValidationIssueLike {
|
|
2481
|
+
path: PropertyKey[];
|
|
2482
|
+
message: string;
|
|
2483
|
+
}
|
|
2484
|
+
interface ValidationErrorLike {
|
|
2485
|
+
issues: ValidationIssueLike[];
|
|
2486
|
+
}
|
|
2487
|
+
/**
|
|
2488
|
+
* Converts a Zod-style validation error into a flat record usable by forms.
|
|
2489
|
+
*/
|
|
2490
|
+
declare function formatValidationErrors(error: ValidationErrorLike, fallbackMessage?: string): Record<string, string>;
|
|
2491
|
+
|
|
2492
|
+
declare const VALIDATED_DATA_KEY = "guren:validated";
|
|
2493
|
+
interface ValidationSchema<T = unknown> {
|
|
2494
|
+
parse(data: unknown): T;
|
|
2495
|
+
safeParse(data: unknown): {
|
|
2496
|
+
success: true;
|
|
2497
|
+
data: T;
|
|
2498
|
+
} | {
|
|
2499
|
+
success: false;
|
|
2500
|
+
error: ValidationErrorLike;
|
|
2501
|
+
};
|
|
2502
|
+
}
|
|
2503
|
+
interface ValidateRequestOptions {
|
|
2504
|
+
/**
|
|
2505
|
+
* Custom error handler when validation fails.
|
|
2506
|
+
* Defaults to returning a 422 JSON response with formatted errors.
|
|
2507
|
+
*/
|
|
2508
|
+
onError?: (ctx: Context, errors: Record<string, string>) => Response | Promise<Response>;
|
|
2509
|
+
/**
|
|
2510
|
+
* HTTP status code for validation errors.
|
|
2511
|
+
* Defaults to 422 (Unprocessable Entity).
|
|
2512
|
+
*/
|
|
2513
|
+
status?: number;
|
|
2514
|
+
/**
|
|
2515
|
+
* Fallback message when no field-specific errors are available.
|
|
2516
|
+
*/
|
|
2517
|
+
fallbackMessage?: string;
|
|
2518
|
+
}
|
|
2519
|
+
/**
|
|
2520
|
+
* Get validated data from the request context.
|
|
2521
|
+
* Returns undefined if validation middleware hasn't run or validation failed.
|
|
2522
|
+
*/
|
|
2523
|
+
declare function getValidatedData<T = Record<string, unknown>>(ctx: Context): T | undefined;
|
|
2524
|
+
/**
|
|
2525
|
+
* Creates a validation middleware that validates the request body against a Zod schema.
|
|
2526
|
+
*
|
|
2527
|
+
* @example
|
|
2528
|
+
* ```ts
|
|
2529
|
+
* import { z } from 'zod'
|
|
2530
|
+
* import { validateRequest, getValidatedData } from '@guren/server'
|
|
2531
|
+
*
|
|
2532
|
+
* const CreateUserSchema = z.object({
|
|
2533
|
+
* name: z.string().min(1),
|
|
2534
|
+
* email: z.email(),
|
|
2535
|
+
* })
|
|
2536
|
+
*
|
|
2537
|
+
* app.post('/users', validateRequest(CreateUserSchema), (c) => {
|
|
2538
|
+
* const data = getValidatedData<z.infer<typeof CreateUserSchema>>(c)
|
|
2539
|
+
* // data is typed and validated
|
|
2540
|
+
* return c.json({ user: data })
|
|
2541
|
+
* })
|
|
2542
|
+
* ```
|
|
2543
|
+
*/
|
|
2544
|
+
declare function validateRequest<T>(schema: ValidationSchema<T>, options?: ValidateRequestOptions): MiddlewareHandler;
|
|
2545
|
+
/**
|
|
2546
|
+
* Creates a validation middleware from a schema factory function.
|
|
2547
|
+
* Useful when the schema depends on request context.
|
|
2548
|
+
*
|
|
2549
|
+
* @example
|
|
2550
|
+
* ```ts
|
|
2551
|
+
* app.post('/users/:role', validateRequestWith((ctx) => {
|
|
2552
|
+
* const role = ctx.req.param('role')
|
|
2553
|
+
* return role === 'admin' ? AdminSchema : UserSchema
|
|
2554
|
+
* }), handler)
|
|
2555
|
+
* ```
|
|
2556
|
+
*/
|
|
2557
|
+
declare function validateRequestWith<T>(schemaFactory: (ctx: Context) => ValidationSchema<T>, options?: ValidateRequestOptions): MiddlewareHandler;
|
|
2558
|
+
/**
|
|
2559
|
+
* Validates data against a schema and throws if invalid.
|
|
2560
|
+
* Useful for manual validation in handlers.
|
|
2561
|
+
*
|
|
2562
|
+
* @example
|
|
2563
|
+
* ```ts
|
|
2564
|
+
* app.post('/data', async (c) => {
|
|
2565
|
+
* const payload = await parseRequestPayload(c)
|
|
2566
|
+
* const data = validate(MySchema, payload)
|
|
2567
|
+
* // throws ValidationError if invalid
|
|
2568
|
+
* return c.json(data)
|
|
2569
|
+
* })
|
|
2570
|
+
* ```
|
|
2571
|
+
*/
|
|
2572
|
+
declare function validate<T>(schema: ValidationSchema<T>, data: unknown): T;
|
|
2573
|
+
/**
|
|
2574
|
+
* Validates data against a schema and returns a result object.
|
|
2575
|
+
* Does not throw on validation failure.
|
|
2576
|
+
*/
|
|
2577
|
+
declare function validateSafe<T>(schema: ValidationSchema<T>, data: unknown): {
|
|
2578
|
+
success: true;
|
|
2579
|
+
data: T;
|
|
2580
|
+
} | {
|
|
2581
|
+
success: false;
|
|
2582
|
+
errors: Record<string, string>;
|
|
2583
|
+
};
|
|
2584
|
+
|
|
2585
|
+
export { type InertiaSsrContext as $, Application as A, type DatabaseNotification as B, type CommandClass as C, type DevBannerOptions as D, type ErrorResponse as E, type ExceptionClass as F, GUREN_ASCII_ART as G, ExceptionHandler as H, type InputInterface as I, type ExceptionHandlerOptions as J, type ExceptionRenderer as K, type ExceptionReporter as L, type FailedJob as M, NotificationManager as N, type OutputInterface as O, type ParsedSignature as P, QueueManager as Q, type GurenModule as R, ServiceProvider as S, type HostAuthorizationOptions as T, type HstsOptions as U, type InertiaDocumentContext as V, type InertiaDocumentOptions as W, type InertiaOptions as X, type InertiaPagePayload as Y, type InertiaResponse as Z, type InertiaSharedProps as _, Container as a, defineModule as a$, type InertiaSsrOptions as a0, type InertiaSsrRenderer as a1, type InertiaSsrResult as a2, type InferInertiaProps as a3, Job as a4, type JobClass as a5, type JobFailureHandler as a6, type JobHandler as a7, type JobOptions as a8, type ModuleDefinition as a9, type SentNotification as aA, type ServiceBinding as aB, type ServiceClass as aC, type ServiceFactory as aD, type ServiceProviderClass as aE, type ServiceProviderOptions as aF, type SharedInertiaPropsResolver as aG, type SlackAttachment as aH, type SlackBlock as aI, type SlackMessage as aJ, VALIDATED_DATA_KEY as aK, type ValidateRequestOptions as aL, type ValidationSchema as aM, type WorkerOptions as aN, abort as aO, abortIf as aP, abortUnless as aQ, clearJobRegistry as aR, createApp as aS, createContainer as aT, createCsrfMiddleware as aU, createExceptionHandler as aV, createHostAuthorizationMiddleware as aW, createNotificationManager as aX, createQueueManager as aY, createSecurityHeaders as aZ, csrfField as a_, type Notifiable as aa, Notification as ab, type NotificationAttachment as ac, type NotificationChannel as ad, type NotificationChannelFactory as ae, type NotificationClass as af, type NotificationMailMessage as ag, type NotificationManagerOptions as ah, type ProgressInterface as ai, type PromptInterface as aj, ProviderManager as ak, type QueueConfig as al, type QueueDriver as am, type QueueDriverFactory as an, type QueuedJob as ao, type RendererRegistration as ap, type ResolvedSharedInertiaProps as aq, type ResourceRouteOptions as ar, type RouteBuilder as as, type RouteContractOptions as at, type RouteDefinition as au, type RouteOpenApiMetadata as av, type ResourceAction as aw, Router as ax, type ScheduledCommand as ay, type SecurityHeadersOptions as az, type ConsoleKernelOptions as b, formatValidationErrors as b0, getContainer as b1, getCsrfToken as b2, getExceptionHandler as b3, getInertiaSharedPropsResolver as b4, getJob as b5, getNotificationManager as b6, getQueueDriver as b7, getRegisteredJobs as b8, getValidatedData as b9, inertia as ba, mountModuleRoutes as bb, parseRequestPayload as bc, registerJob as bd, resolve as be, resolveJobName as bf, setContainer as bg, setExceptionHandler as bh, setInertiaDocument as bi, setInertiaSharedProps as bj, setInertiaSsrRenderer as bk, setNotificationManager as bl, setQueueDriver as bm, shareInertiaProps as bn, validate as bo, validateRequest as bp, validateRequestWith as bq, validateSafe as br, verifyCsrfToken as bs, type StartViteDevServerOptions as c, type StartedViteDevServer as d, type ServiceProviderConstructor as e, type OptionDefinition as f, type CommandInstance as g, type ServiceBindings as h, type ApplicationListenOptions as i, type ApplicationOptions as j, type ArgumentDefinition as k, logDevServerBanner as l, type AuthPayload as m, type AuthPluginOptions as n, CSRF_FORM_FIELD as o, CSRF_HEADER_NAME as p, CSRF_TOKEN_KEY as q, type Provider as r, startViteDevServer as s, type ContextualBinding as t, type ContextualBindingBuilder as u, type ContextualNeedsBuilder as v, Controller as w, type ControllerInertiaProps as x, type CsrfOptions as y, type DatabaseChannelOptions as z };
|