webspresso 0.0.103 → 0.0.105

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 (165) hide show
  1. package/.agents/AGENTS.md +6 -0
  2. package/.agents/ARCHITECTURE.md +23 -0
  3. package/.agents/CACHE.md +147 -0
  4. package/.agents/CLI.md +1 -1
  5. package/.agents/EARLY_HINTS.md +120 -0
  6. package/.agents/HEALTH.md +118 -0
  7. package/.agents/LIMITS.md +109 -0
  8. package/.agents/ORM.md +155 -1
  9. package/.agents/PLUGINS.md +28 -0
  10. package/.agents/RESILIENCE.md +235 -0
  11. package/AGENTS.md +6 -0
  12. package/README.md +2 -2
  13. package/bin/commands/add-docker.js +6 -6
  14. package/bin/commands/dev.js +4 -3
  15. package/bin/commands/new.js +5 -5
  16. package/bin/commands/openapi.js +1 -1
  17. package/bin/commands/start.js +1 -1
  18. package/bin/utils/orm-map-html.js +2 -8
  19. package/bin/utils/project.js +2 -2
  20. package/core/auth/hash.js +5 -4
  21. package/core/auth/jwt.js +6 -57
  22. package/core/auth/magic-link.js +4 -5
  23. package/core/auth/manager.js +3 -5
  24. package/core/auth/oauth.js +45 -30
  25. package/core/auth/totp.js +5 -16
  26. package/core/auth/user-agent.js +1 -21
  27. package/core/cache/byte-size.js +123 -0
  28. package/core/cache/index.js +21 -0
  29. package/core/cache/lru.js +477 -0
  30. package/core/cache/tagged-lru.js +346 -0
  31. package/core/commands/registry.js +6 -20
  32. package/core/content/renderer.js +1 -13
  33. package/core/early-hints/index.js +267 -0
  34. package/core/errors/domain.js +48 -0
  35. package/core/errors/http.js +31 -0
  36. package/core/errors/index.js +10 -0
  37. package/core/errors/middleware.js +2 -8
  38. package/core/errors/normalize.js +88 -2
  39. package/core/events/discovery.js +6 -24
  40. package/core/events/dispatcher.js +2 -7
  41. package/core/forms/form-builder.js +1 -9
  42. package/core/health/index.js +41 -0
  43. package/core/health/middleware.js +213 -0
  44. package/core/health/normalize.js +140 -0
  45. package/core/health/probes.js +203 -0
  46. package/core/limits/index.js +34 -0
  47. package/core/limits/middleware.js +317 -0
  48. package/core/limits/normalize.js +222 -0
  49. package/core/orm/batch.js +70 -0
  50. package/core/orm/cache/fingerprint.js +2 -2
  51. package/core/orm/cache/memory-provider.js +27 -110
  52. package/core/orm/index.js +76 -8
  53. package/core/orm/json-fields.js +22 -8
  54. package/core/orm/model.js +10 -0
  55. package/core/orm/query-builder.js +63 -9
  56. package/core/orm/query-filters.js +393 -0
  57. package/core/orm/repository.js +318 -19
  58. package/core/orm/schema-helpers.js +8 -10
  59. package/core/orm/scopes.js +321 -1
  60. package/core/orm/transaction.js +10 -2
  61. package/core/orm/utils.js +4 -86
  62. package/core/queue/adapters/database.js +4 -8
  63. package/core/queue/manager.js +55 -41
  64. package/core/resilience/circuit-breaker.js +391 -0
  65. package/core/resilience/errors.js +63 -0
  66. package/core/resilience/index.js +53 -0
  67. package/core/resilience/registry.js +97 -0
  68. package/core/resilience/retry.js +203 -0
  69. package/core/schema-cache.js +9 -2
  70. package/core/shutdown/http-adapter.js +4 -1
  71. package/core/shutdown/shutdown-manager.js +132 -31
  72. package/core/utils/array.js +12 -0
  73. package/core/utils/base64url.js +8 -0
  74. package/core/utils/crypto.js +191 -0
  75. package/core/utils/ensure-leading-slash.js +6 -0
  76. package/core/utils/escape-html.js +7 -0
  77. package/core/utils/escape-regexp.js +7 -0
  78. package/core/utils/fetch.js +121 -0
  79. package/core/utils/fs.js +144 -0
  80. package/core/utils/get-client-ip.js +6 -0
  81. package/core/utils/hmac.js +6 -0
  82. package/core/utils/html.js +72 -0
  83. package/core/utils/ip.js +86 -0
  84. package/core/utils/json.js +98 -0
  85. package/core/utils/object.js +106 -0
  86. package/core/utils/random.js +9 -0
  87. package/core/utils/regex.js +77 -0
  88. package/core/utils/safe-compare.js +3 -0
  89. package/core/utils/sha256.js +6 -0
  90. package/core/utils/string.js +87 -0
  91. package/core/utils/strip-trailing-slash.js +6 -0
  92. package/core/utils/time.js +96 -0
  93. package/core/utils/timeout.js +348 -0
  94. package/core/utils/url.js +106 -0
  95. package/core/utils/walk.js +7 -0
  96. package/index.d.ts +627 -2
  97. package/index.js +158 -0
  98. package/package.json +1 -2
  99. package/plugins/admin-panel/auth.js +15 -7
  100. package/plugins/admin-panel/client/parts/01-state-api-breadcrumb.js +82 -10
  101. package/plugins/admin-panel/client/parts/05-rich-text-file-helpers.js +4 -2
  102. package/plugins/admin-panel/client/parts/08-record-list.js +3 -2
  103. package/plugins/admin-panel/client/parts/10-export-registry.js +6 -0
  104. package/plugins/admin-panel/core/api-extensions.js +3 -80
  105. package/plugins/admin-panel/index.js +1 -1
  106. package/plugins/admin-panel/lib/login-rate-limiter.js +15 -13
  107. package/plugins/admin-panel/modules/menu.js +1 -1
  108. package/plugins/api-key/crypto.js +3 -26
  109. package/plugins/api-key/scopes.js +5 -7
  110. package/plugins/audit-log/api-handlers.js +8 -7
  111. package/plugins/audit-log/middleware.js +11 -2
  112. package/plugins/audit-log/parse.js +3 -3
  113. package/plugins/basic-auth/index.js +2 -26
  114. package/plugins/cors.js +2 -2
  115. package/plugins/csrf/index.js +7 -23
  116. package/plugins/dashboard/app.js +2 -2
  117. package/plugins/dashboard/index.js +5 -5
  118. package/plugins/data-exchange/record-selection.js +2 -5
  119. package/plugins/email/api-handlers.js +5 -18
  120. package/plugins/email/auth-bridge.js +3 -2
  121. package/plugins/file-manager/admin-component.js +3 -1
  122. package/plugins/file-manager/core.js +34 -4
  123. package/plugins/health-check.js +2 -1
  124. package/plugins/index.js +2 -0
  125. package/plugins/lazy.js +5 -6
  126. package/plugins/mcp/auth.js +1 -13
  127. package/plugins/mcp/discovery.js +18 -17
  128. package/plugins/mcp/index.js +23 -1
  129. package/plugins/mcp/transports/sse.js +10 -1
  130. package/plugins/orm-cache-admin/admin-component.js +3 -2
  131. package/plugins/polar/src/api.js +11 -3
  132. package/plugins/polar/src/webhooks.js +7 -13
  133. package/plugins/rate-limit/index.js +3 -1
  134. package/plugins/recaptcha/helpers.js +1 -7
  135. package/plugins/recaptcha/verify.js +37 -23
  136. package/plugins/redirect/index.js +57 -7
  137. package/plugins/rest-resources/index.js +1 -207
  138. package/plugins/rls/index.js +170 -0
  139. package/plugins/schema-explorer/admin-component.js +4 -2
  140. package/plugins/schema-explorer.js +40 -29
  141. package/plugins/seo-checker/index.js +5 -2
  142. package/plugins/site-analytics/tracking.js +21 -18
  143. package/plugins/sitemap.js +21 -17
  144. package/plugins/swagger.js +13 -17
  145. package/plugins/upload/index.js +4 -3
  146. package/plugins/upload/orphan-pruner.js +4 -3
  147. package/plugins/webhooks/crypto.js +6 -28
  148. package/plugins/webhooks/dispatcher.js +14 -9
  149. package/plugins/webhooks/index.js +6 -0
  150. package/plugins/webhooks/matcher.js +28 -17
  151. package/plugins/webhooks/sender.js +40 -13
  152. package/src/app-context.js +41 -5
  153. package/src/dev/banner.js +6 -2
  154. package/src/dev-reload/index.js +47 -6
  155. package/src/file-router.js +1 -3
  156. package/src/helpers.js +180 -33
  157. package/src/modules/module-discovery.js +1 -9
  158. package/src/pages/page-loader.js +53 -1
  159. package/src/plugin-manager.js +90 -17
  160. package/src/server.js +137 -26
  161. package/src/services/discovery.js +19 -40
  162. package/src/services/executor.js +86 -25
  163. package/src/services/memoize.js +3 -25
  164. package/src/services/registry.js +6 -0
  165. package/src/template/precompile.js +8 -19
package/index.d.ts CHANGED
@@ -62,10 +62,28 @@ export interface CreateAppOptions {
62
62
  timeout?: string | ((req: Request, res: Response, ctx: ErrorPageContext) => unknown);
63
63
  };
64
64
  timeout?: string | false;
65
+ /** Global timeouts configuration across server, services, background jobs, outgoing fetch, webhooks, and shutdown */
66
+ timeouts?: {
67
+ request?: number | string | false;
68
+ service?: number | string | false;
69
+ queue?: number | string | false;
70
+ fetch?: number | string | false;
71
+ webhook?: number | string | false;
72
+ shutdown?: number | string | false;
73
+ loader?: number | string | false;
74
+ };
65
75
  auth?: unknown;
66
76
  db?: DatabaseInstance | null;
67
77
  /** HTTP response compression options */
68
78
  compression?: boolean | CompressionOptions;
79
+ /** HTTP 103 Early Hints options (preloads CSS/JS before SSR finish) */
80
+ earlyHints?: boolean | (string | EarlyHintLink)[] | EarlyHintsOptions;
81
+ /** Payload size limits and DoS protection for JSON, URL-encoded, raw, and text bodies */
82
+ limits?: string | number | PayloadLimitsConfig;
83
+ /** Cloud & Kubernetes Health check probes (/healthz & /readyz) */
84
+ healthCheck?: boolean | string | HealthCheckConfig;
85
+ /** High-Performance In-Memory LRU & Tagged Cache options */
86
+ cache?: boolean | LruCacheConfig;
69
87
  /** Shutdown and lifecycle configuration */
70
88
  shutdown?: ShutdownOptions;
71
89
  /**
@@ -91,6 +109,10 @@ export interface CreateAppOptions {
91
109
  port?: number;
92
110
  shutdown?: ShutdownOptions;
93
111
  compression?: boolean | CompressionOptions;
112
+ earlyHints?: boolean | (string | EarlyHintLink)[] | EarlyHintsOptions;
113
+ limits?: string | number | PayloadLimitsConfig;
114
+ healthCheck?: boolean | string | HealthCheckConfig;
115
+ cache?: boolean | LruCacheConfig;
94
116
  trustProxy?: boolean | number | string;
95
117
  [key: string]: unknown;
96
118
  };
@@ -194,6 +216,8 @@ export interface ServiceContext {
194
216
  invalidate?: (name: string, input?: unknown, ctx?: unknown) => boolean;
195
217
  clearCache?: (name?: string) => boolean;
196
218
  };
219
+ breaker?: (name: string, options?: CircuitBreakerOptions) => CircuitBreaker;
220
+ retry?: typeof retry;
197
221
  [key: string]: unknown;
198
222
  }
199
223
 
@@ -217,6 +241,8 @@ export interface ServiceDefinition<TInput = unknown, TOutput = unknown> {
217
241
  };
218
242
  timeout?: number | string;
219
243
  transaction?: boolean;
244
+ circuitBreaker?: boolean | string | CircuitBreakerOptions | CircuitBreaker;
245
+ retry?: boolean | number | RetryOptions;
220
246
  [key: string]: unknown;
221
247
  }
222
248
 
@@ -362,6 +388,27 @@ export interface ShutdownOptions {
362
388
  exitOnSignal?: boolean;
363
389
  }
364
390
 
391
+ export interface EarlyHintLink {
392
+ url?: string;
393
+ href?: string;
394
+ rel?: 'preload' | 'preconnect' | 'prefetch' | 'modulepreload' | 'dns-prefetch' | string;
395
+ as?: 'style' | 'script' | 'font' | 'image' | 'fetch' | 'video' | 'audio' | string;
396
+ crossOrigin?: boolean | '' | 'anonymous' | 'use-credentials';
397
+ crossorigin?: boolean | '' | 'anonymous' | 'use-credentials';
398
+ type?: string;
399
+ media?: string;
400
+ fetchPriority?: 'high' | 'low' | 'auto';
401
+ fetchpriority?: 'high' | 'low' | 'auto';
402
+ noPush?: boolean;
403
+ nopush?: boolean;
404
+ }
405
+
406
+ export interface EarlyHintsOptions {
407
+ enabled?: boolean;
408
+ auto?: boolean;
409
+ links?: (string | EarlyHintLink)[] | ((req: Request) => (string | EarlyHintLink)[]);
410
+ }
411
+
365
412
  export interface ServerAdapter {
366
413
  close(): Promise<void>;
367
414
  forceClose?(): void;
@@ -404,6 +451,8 @@ export interface WebspressoApplication extends Application {
404
451
  readonly isShuttingDown: boolean;
405
452
  shutdownManager: ShutdownManager;
406
453
  serviceRegistry: ServiceRegistry;
454
+ breakers?: CircuitBreakerRegistry;
455
+ getBreaker?(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
407
456
  onShutdown(fn: () => Promise<void> | void): this;
408
457
  close(reason?: string): Promise<void>;
409
458
  enableShutdownHooks(): this;
@@ -468,7 +517,20 @@ export class ConflictError extends HttpError { constructor(message?: string, opt
468
517
  export class PayloadTooLargeError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
469
518
  export class UnsupportedMediaTypeError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
470
519
  export class UnprocessableEntityError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
520
+ export class RequestTimeoutError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
471
521
  export class TooManyRequestsError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
522
+ export class ServiceUnavailableError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
523
+ export class GatewayTimeoutError extends HttpError { constructor(message?: string, options?: ErrorOptions); }
524
+ export class CircuitBreakerOpenError extends ServiceUnavailableError {
525
+ breakerName: string;
526
+ resetTimeoutMs: number;
527
+ constructor(breakerName?: string, resetTimeoutMs?: number, options?: ErrorOptions);
528
+ }
529
+ export class CircuitBreakerTimeoutError extends GatewayTimeoutError {
530
+ breakerName: string;
531
+ timeoutMs: number;
532
+ constructor(breakerName?: string, timeoutMs?: number, options?: ErrorOptions);
533
+ }
472
534
 
473
535
  export class ValidationError extends HttpError {
474
536
  fields: Record<string, string[] | string>;
@@ -500,6 +562,330 @@ export namespace compression {
500
562
  export function appendVary(res: unknown, field: string): void;
501
563
  }
502
564
 
565
+ export function createEarlyHintsMiddleware(options?: boolean | EarlyHintsOptions): RequestHandler;
566
+ export function sendEarlyHints(
567
+ res: unknown,
568
+ hints: string | EarlyHintLink | (string | EarlyHintLink)[] | Record<string, unknown>,
569
+ callback?: (err?: Error | null) => void
570
+ ): boolean;
571
+ export function formatLink(item: string | EarlyHintLink): string | null;
572
+ export function formatLinkHeader(links: string | EarlyHintLink | (string | EarlyHintLink)[]): string[];
573
+ export function inferAsType(url: string): string | null;
574
+
575
+ export namespace earlyHints {
576
+ export const EXTENSION_AS_MAP: Record<string, string>;
577
+ export function inferAsType(url: string): string | null;
578
+ export function formatLink(item: string | EarlyHintLink): string | null;
579
+ export function formatLinkHeader(links: string | EarlyHintLink | (string | EarlyHintLink)[]): string[];
580
+ export function sendEarlyHints(
581
+ res: unknown,
582
+ hints: string | EarlyHintLink | (string | EarlyHintLink)[] | Record<string, unknown>,
583
+ callback?: (err?: Error | null) => void
584
+ ): boolean;
585
+ export function createEarlyHintsMiddleware(options?: boolean | EarlyHintsOptions): RequestHandler;
586
+ }
587
+
588
+ export interface PayloadLimitParserConfig {
589
+ enabled?: boolean;
590
+ limit?: string | number;
591
+ strict?: boolean;
592
+ extended?: boolean;
593
+ parameterLimit?: number;
594
+ type?: string | ((req: Request) => boolean);
595
+ verify?: (req: Request, res: Response, buf: Buffer, encoding: string) => void;
596
+ [key: string]: unknown;
597
+ }
598
+
599
+ export interface PayloadLimitsConfig {
600
+ /** Size limit for application/json (default: '1mb') or false to disable */
601
+ json?: string | number | boolean | PayloadLimitParserConfig;
602
+ /** Size limit for application/x-www-form-urlencoded (default: '1mb') or false to disable */
603
+ urlencoded?: string | number | boolean | PayloadLimitParserConfig;
604
+ /** Size limit for application/octet-stream (default: false / disabled) */
605
+ raw?: string | number | boolean | PayloadLimitParserConfig;
606
+ /** Size limit for text/plain (default: false / disabled) */
607
+ text?: string | number | boolean | PayloadLimitParserConfig;
608
+ /** Maximum number of URL-encoded parameters (default: 1000) */
609
+ parameterLimit?: number;
610
+ /** Capture raw request body Buffer to req.rawBody (e.g. for webhook signatures) */
611
+ captureRawBody?: boolean | (string | RegExp)[] | ((req: Request) => boolean);
612
+ /** Path prefixes or patterns excluded from global body parsing */
613
+ exclude?: (string | RegExp)[];
614
+ /** Per-route payload limits or false to disable body parsing */
615
+ routes?: Record<string, string | number | boolean | PayloadLimitsConfig>;
616
+ }
617
+
618
+ export function normalizeLimits(options?: unknown): unknown;
619
+ export function setupLimitsMiddleware(app: Application, options?: unknown): unknown;
620
+ export function createLimitsMiddleware(routeOptions?: unknown): RequestHandler;
621
+ export function parseByteSize(value: string | number): number | string;
622
+
623
+ export namespace limits {
624
+ export const DEFAULT_LIMITS: Record<string, unknown>;
625
+ export function parseByteSize(value: string | number): number | string;
626
+ export function normalizeLimits(options?: unknown): unknown;
627
+ export function matchesPath(pattern: string | RegExp | Function, pathname: string): boolean;
628
+ export function shouldSkipBodyParser(req: Request, excludeList?: unknown[]): boolean;
629
+ export function shouldCaptureRawBody(req: Request, captureSetting?: unknown): boolean;
630
+ export function createLimitsMiddleware(routeOptions?: unknown): RequestHandler;
631
+ export function setupLimitsMiddleware(app: Application, options?: unknown): unknown;
632
+ }
633
+
634
+ export interface HealthCheckConfig {
635
+ /** Enable or disable health check endpoints (default: true if healthCheck option is provided) */
636
+ enabled?: boolean;
637
+ /** Liveness endpoint path (default: '/healthz', or false to disable) */
638
+ path?: string | false;
639
+ /** Readiness endpoint path (default: '/readyz', or false to disable) */
640
+ readyPath?: string | false;
641
+ /** Combined status endpoint path (default: '/health', or false to disable) */
642
+ combinedPath?: string | false;
643
+ /** Probe database connectivity in readiness (default: true) */
644
+ db?: boolean;
645
+ /** Probe worker queue readiness (default: true) */
646
+ queue?: boolean;
647
+ /** Monitor event loop delay/lag (default: true) */
648
+ eventLoopLag?: boolean;
649
+ /** Event loop delay threshold in ms before marking degraded (default: 300) */
650
+ eventLoopThresholdMs?: number;
651
+ /** Timeout in ms for DB and custom checks (default: 3000) */
652
+ timeoutMs?: number;
653
+ /** Map of custom async health checks */
654
+ checks?: Record<string, (context: unknown) => Promise<unknown> | unknown>;
655
+ /** Custom headers to attach to health probe responses */
656
+ headers?: Record<string, string>;
657
+ }
658
+
659
+ export function normalizeHealthConfig(options?: unknown): unknown;
660
+ export function setupHealthMiddleware(app: Application, options?: unknown, context?: unknown): unknown;
661
+ export function createHealthManager(config: unknown, context?: unknown): unknown;
662
+
663
+ export namespace health {
664
+ export const DEFAULT_HEALTH_CONFIG: Record<string, unknown>;
665
+ export function normalizeHealthConfig(options?: unknown): unknown;
666
+ export function formatMb(bytes: number): string;
667
+ export function createEventLoopMonitor(): unknown;
668
+ export function getSystemMetrics(monitor?: unknown): unknown;
669
+ export function probeDatabase(db: unknown, timeoutMs?: number): Promise<{ status: string; latencyMs?: number; error?: string }>;
670
+ export function probeQueue(queue: unknown): Promise<{ status: string; stats?: unknown; error?: string }>;
671
+ export function probeCustomChecks(checks?: Record<string, Function>, context?: unknown, timeoutMs?: number): Promise<{ isHealthy: boolean; results: Record<string, unknown> }>;
672
+ export function createHealthManager(config: unknown, context?: unknown): unknown;
673
+ export function setupHealthMiddleware(app: Application, options?: unknown, context?: unknown): unknown;
674
+ }
675
+
676
+ // --- In-Memory & Tagged LRU Cache Engine ---
677
+
678
+ export interface LruCacheConfig {
679
+ /** Maximum number of entries before LRU eviction (default: 1000, 0 = unlimited) */
680
+ maxEntries?: number;
681
+ /** Maximum byte budget (default: 0 = unlimited) */
682
+ maxBytes?: number;
683
+ /** Maximum megabytes budget (converts to bytes) */
684
+ maxMemoryMb?: number;
685
+ /** Default TTL in milliseconds or duration string ('5m', '1h', default: 0 = no expiry) */
686
+ defaultTtl?: string | number;
687
+ /** Whether to deep-clone cached values on read/write to prevent accidental mutation (default: false) */
688
+ clone?: boolean;
689
+ /** Custom byte sizer function (default: approximateByteSize) */
690
+ sizeCalculation?: (value: unknown, key: string) => number;
691
+ /** Callback fired when an entry is evicted, expired, or deleted */
692
+ onEvict?: (key: string, value: unknown, reason: 'evict' | 'expire' | 'delete' | 'clear') => void;
693
+ }
694
+
695
+ export class LruCache<V = unknown> {
696
+ constructor(options?: LruCacheConfig);
697
+ readonly size: number;
698
+ readonly currentBytes: number;
699
+ readonly maxBytes: number;
700
+ readonly maxEntries: number;
701
+ readonly hits: number;
702
+ readonly misses: number;
703
+ readonly hitRate: number;
704
+ readonly evictions: number;
705
+ readonly expirations: number;
706
+ get(key: string): V | undefined;
707
+ peek(key: string): V | undefined;
708
+ has(key: string): boolean;
709
+ set(key: string, value: V, options?: { ttl?: string | number; ttlMs?: number; size?: number }): this;
710
+ delete(key: string): boolean;
711
+ del(key: string): boolean;
712
+ clear(): this;
713
+ pruneExpired(): number;
714
+ getOrSet(key: string, asyncFactory: (key: string) => Promise<V>, options?: { ttl?: string | number; ttlMs?: number; size?: number }): Promise<V>;
715
+ getStats(): Record<string, number>;
716
+ resetStats(): void;
717
+ keys(): IterableIterator<string>;
718
+ values(): IterableIterator<V>;
719
+ entries(): IterableIterator<[string, V]>;
720
+ [Symbol.iterator](): IterableIterator<[string, V]>;
721
+ forEach(callback: (value: V, key: string, cache: this) => void, thisArg?: unknown): void;
722
+ }
723
+
724
+ export class TaggedLruCache<V = unknown> {
725
+ constructor(options?: LruCacheConfig);
726
+ readonly size: number;
727
+ readonly currentBytes: number;
728
+ readonly maxBytes: number;
729
+ readonly maxEntries: number;
730
+ readonly hits: number;
731
+ readonly misses: number;
732
+ readonly hitRate: number;
733
+ readonly evictions: number;
734
+ readonly expirations: number;
735
+ get(key: string): V | undefined;
736
+ peek(key: string): V | undefined;
737
+ has(key: string): boolean;
738
+ set(key: string, value: V, options?: { tags?: string | string[]; ttl?: string | number; ttlMs?: number; size?: number }): this;
739
+ delete(key: string): boolean;
740
+ del(key: string): boolean;
741
+ invalidateTag(tag: string): number;
742
+ invalidateTags(tags: string | string[]): number;
743
+ hasTag(tag: string): boolean;
744
+ getKeysForTag(tag: string): string[];
745
+ clear(): this;
746
+ pruneExpired(): number;
747
+ getOrSet(key: string, asyncFactory: (key: string) => Promise<V>, options?: { tags?: string | string[]; ttl?: string | number; ttlMs?: number; size?: number }): Promise<V>;
748
+ getSizeStats(): Record<string, number>;
749
+ getStats(): Record<string, number>;
750
+ resetStats(): void;
751
+ keys(): IterableIterator<string>;
752
+ values(): IterableIterator<V>;
753
+ entries(): IterableIterator<[string, V]>;
754
+ [Symbol.iterator](): IterableIterator<[string, V]>;
755
+ forEach(callback: (value: V, key: string, cache: this) => void, thisArg?: unknown): void;
756
+ }
757
+
758
+ export function createLruCache<V = unknown>(options?: LruCacheConfig): LruCache<V>;
759
+ export function createTaggedLruCache<V = unknown>(options?: LruCacheConfig): TaggedLruCache<V>;
760
+ export function approximateByteSize(value: unknown): number;
761
+
762
+ export namespace cache {
763
+ export { LruCache, TaggedLruCache, createLruCache, createTaggedLruCache, approximateByteSize };
764
+ }
765
+
766
+ // --- Enterprise Resilience & Fault Tolerance (Circuit Breaker & Retry Engine) ---
767
+
768
+ export interface CircuitBreakerOptions {
769
+ name?: string;
770
+ failureThreshold?: number;
771
+ failureRateThreshold?: number;
772
+ minimumRequests?: number;
773
+ rollingWindow?: number | string;
774
+ rollingWindowMs?: number | string;
775
+ successThreshold?: number;
776
+ resetTimeout?: number | string;
777
+ resetTimeoutMs?: number | string;
778
+ timeout?: number | string;
779
+ timeoutMs?: number | string;
780
+ fallback?: (err: Error, ...args: any[]) => any;
781
+ isFailure?: (err: Error) => boolean;
782
+ onStateChange?: (from: string, to: string, breaker: CircuitBreaker) => void;
783
+ }
784
+
785
+ export interface CircuitBreakerStats {
786
+ name: string;
787
+ state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
788
+ totalCalls: number;
789
+ successfulCalls: number;
790
+ failedCalls: number;
791
+ rejectedCalls: number;
792
+ timedOutCalls: number;
793
+ fallbackCalls: number;
794
+ consecutiveFailures: number;
795
+ consecutiveSuccesses: number;
796
+ failureRate: number;
797
+ lastFailureTime: number | null;
798
+ lastSuccessTime: number | null;
799
+ lastStateChange: number;
800
+ }
801
+
802
+ export class CircuitBreaker extends import('events').EventEmitter {
803
+ readonly name: string;
804
+ readonly failureThreshold: number;
805
+ readonly failureRateThreshold: number | null;
806
+ readonly minimumRequests: number;
807
+ readonly rollingWindowMs: number;
808
+ readonly successThreshold: number;
809
+ readonly resetTimeoutMs: number;
810
+ readonly timeoutMs: number;
811
+ readonly fallback: ((err: Error, ...args: any[]) => any) | null;
812
+ readonly isFailure: (err: Error) => boolean;
813
+
814
+ state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
815
+ consecutiveFailures: number;
816
+ consecutiveSuccesses: number;
817
+ lastStateChange: number;
818
+ lastFailureTime: number | null;
819
+ lastSuccessTime: number | null;
820
+
821
+ static readonly STATE_CLOSED: 'CLOSED';
822
+ static readonly STATE_OPEN: 'OPEN';
823
+ static readonly STATE_HALF_OPEN: 'HALF_OPEN';
824
+
825
+ readonly isClosed: boolean;
826
+ readonly isOpen: boolean;
827
+ readonly isHalfOpen: boolean;
828
+
829
+ constructor(options?: CircuitBreakerOptions);
830
+
831
+ execute<T = any>(fn: (...args: any[]) => Promise<T> | T, ...args: any[]): Promise<T>;
832
+ wrap<T = any>(fn: (...args: any[]) => Promise<T> | T): (...args: any[]) => Promise<T>;
833
+ open(): this;
834
+ close(): this;
835
+ halfOpen(): this;
836
+ reset(): this;
837
+ getFailureRate(): number;
838
+ getStats(): CircuitBreakerStats;
839
+ }
840
+
841
+ export function createCircuitBreaker(options?: CircuitBreakerOptions): CircuitBreaker;
842
+
843
+ export interface RetryOptions {
844
+ retries?: number;
845
+ delay?: number | string;
846
+ minTimeout?: number | string;
847
+ maxTimeout?: number | string;
848
+ factor?: number;
849
+ jitter?: boolean;
850
+ shouldRetry?: (error: Error, attempt: number) => boolean;
851
+ onRetry?: (info: { attempt: number; error: Error; delayMs: number }) => void;
852
+ signal?: AbortSignal;
853
+ }
854
+
855
+ export function retry<T = any>(asyncFn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
856
+ export function withRetry<T = any>(asyncFn: (...args: any[]) => Promise<T>, options?: RetryOptions): (...args: any[]) => Promise<T>;
857
+ export function isTransientError(error: unknown): boolean;
858
+ export function calculateBackoffDelay(attempt: number, minTimeoutMs: number, maxTimeoutMs: number, factor: number, jitter: boolean): number;
859
+
860
+ export class CircuitBreakerRegistry {
861
+ readonly breakers: Map<string, CircuitBreaker>;
862
+ getBreaker(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
863
+ hasBreaker(name: string): boolean;
864
+ getAllBreakers(): CircuitBreaker[];
865
+ getStats(): Record<string, CircuitBreakerStats>;
866
+ resetAll(): void;
867
+ clear(): void;
868
+ }
869
+
870
+ export const circuitBreakerRegistry: CircuitBreakerRegistry;
871
+ export function getBreaker(name: string, options?: CircuitBreakerOptions): CircuitBreaker;
872
+
873
+ export namespace resilience {
874
+ export {
875
+ CircuitBreaker,
876
+ createCircuitBreaker,
877
+ retry,
878
+ withRetry,
879
+ isTransientError,
880
+ calculateBackoffDelay,
881
+ CircuitBreakerRegistry,
882
+ circuitBreakerRegistry,
883
+ getBreaker,
884
+ CircuitBreakerOpenError,
885
+ CircuitBreakerTimeoutError,
886
+ };
887
+ }
888
+
503
889
  export function resolveClientRuntime(options?: {
504
890
  clientRuntime?: {
505
891
  alpine?: boolean | Record<string, unknown>;
@@ -519,8 +905,12 @@ export function getAppContext(): {
519
905
  serviceRegistry: ServiceRegistry | null;
520
906
  events?: any;
521
907
  mailer?: Mailer | null;
908
+ cache?: TaggedLruCache | null;
522
909
  };
523
910
 
911
+ export function getCache(): TaggedLruCache | null;
912
+ export function hasCache(): boolean;
913
+
524
914
  export function getDb(): DatabaseInstance;
525
915
 
526
916
  export function hasDb(): boolean;
@@ -830,6 +1220,140 @@ export function loadListeners(dirPath: string, dispatcher: EventDispatcher, opti
830
1220
 
831
1221
  export function createHelpers(context: Record<string, unknown>): Record<string, unknown>;
832
1222
 
1223
+ export interface FetchWithTimeoutOptions extends RequestInit {
1224
+ timeout?: number;
1225
+ }
1226
+
1227
+ export function fetchWithTimeout(url: string | URL | Request, options?: FetchWithTimeoutOptions): Promise<Response>;
1228
+ export function safeCompare(a: string | Buffer | null | undefined, b: string | Buffer | null | undefined): boolean;
1229
+ export function sha256(data: string | Buffer | unknown, encoding?: import('crypto').BinaryToTextEncoding | 'buffer'): string | Buffer;
1230
+ export function hmacSha256(data: string | Buffer | unknown, secret: string | Buffer, encoding?: import('crypto').BinaryToTextEncoding | 'buffer'): string | Buffer;
1231
+ export function randomToken(byteLength?: number, encoding?: import('crypto').BinaryToTextEncoding | 'buffer'): string | Buffer;
1232
+ export function randomId(prefix?: string, byteLength?: number, encoding?: import('crypto').BinaryToTextEncoding): string;
1233
+ export function randomTimestampedId(prefix?: string, byteLength?: number, encoding?: import('crypto').BinaryToTextEncoding): string;
1234
+ export function base64UrlEncode(input: string | Buffer | unknown): string;
1235
+ export function base64UrlDecode(input: string): string;
1236
+ export function escapeHtml(value: unknown): string;
1237
+ export function unescapeHtml(value: unknown): string;
1238
+ export function getClientIp<T = string>(req?: any, fallback?: T): string | T;
1239
+
1240
+ export interface WalkDirectoryOptions {
1241
+ extensions?: string[] | Set<string> | null;
1242
+ recursive?: boolean;
1243
+ ignoreTests?: boolean;
1244
+ ignorePrefixes?: string[];
1245
+ ignoreNames?: string[];
1246
+ filter?: (fullPath: string, dirent: import('fs').Dirent) => boolean;
1247
+ baseDir?: string;
1248
+ detailed?: boolean;
1249
+ }
1250
+
1251
+ export interface WalkDirectoryItem {
1252
+ absolutePath: string;
1253
+ relativePath: string;
1254
+ name: string;
1255
+ ext: string;
1256
+ }
1257
+
1258
+ export function walkDirectory(dir: string, options?: WalkDirectoryOptions & { detailed?: false }): string[];
1259
+ export function walkDirectory(dir: string, options: WalkDirectoryOptions & { detailed: true }): WalkDirectoryItem[];
1260
+ export function walkDirectory(dir: string, options?: WalkDirectoryOptions): string[] | WalkDirectoryItem[];
1261
+ export function walkDirectoryDetailed(dir: string, options?: WalkDirectoryOptions): WalkDirectoryItem[];
1262
+
1263
+ export interface StripTrailingSlashOptions {
1264
+ preserveRoot?: boolean;
1265
+ }
1266
+
1267
+ export function stripTrailingSlash(input: string | unknown, options?: StripTrailingSlashOptions): string;
1268
+ export function ensureLeadingSlash(input: string | unknown): string;
1269
+ export function ensureTrailingSlash(input: string | unknown): string;
1270
+ export function stripLeadingSlash(input: string | unknown): string;
1271
+ export function joinUrl(base: string, ...paths: string[]): string;
1272
+
1273
+ export interface GlobToRegExpOptions {
1274
+ separator?: '/' | '.' | null;
1275
+ exact?: boolean;
1276
+ flags?: string;
1277
+ }
1278
+
1279
+ export function escapeRegExp(str: string | unknown): string;
1280
+ export function escapeRegex(str: string | unknown): string;
1281
+ export function globToRegExp(pattern: string, options?: GlobToRegExpOptions): RegExp;
1282
+
1283
+ export function parseDurationSec(duration: string | number | unknown, defaultSec?: number): number;
1284
+ export function parseDuration(duration: string | number | unknown, defaultSec?: number): number;
1285
+ export function parseDurationMs(ttl: string | number | boolean | unknown, defaultMs?: number): number;
1286
+ export function sleep(ms: number): Promise<void>;
1287
+
1288
+ export function safeJsonParse<T = unknown>(input: string | unknown, fallback?: T, reviver?: (this: any, key: string, value: any) => any): any | T;
1289
+ export function safeJsonStringify(value: unknown, space?: string | number | null, fallback?: string): string;
1290
+ export function isValidJson(str: string | unknown): boolean;
1291
+
1292
+ export function toSnakeCase(str: string | unknown): string;
1293
+ export function snakeToCamel(str: string | unknown): string;
1294
+ export function camelToSnake(str: string | unknown): string;
1295
+ export function toKebabCase(str: string | unknown): string;
1296
+ export function toPascalCase(str: string | unknown): string;
1297
+
1298
+ export function ensureArray<T>(value: T | T[] | null | undefined): T[];
1299
+ export function pick<T extends object, K extends keyof T>(obj: T | null | undefined, keys: K[] | K): Pick<T, K>;
1300
+ export function omit<T extends object, K extends keyof T>(obj: T | null | undefined, keys: K[] | K): Omit<T, K>;
1301
+ export function deepClone<T>(obj: T): T;
1302
+
1303
+ export const DEFAULT_TIMEOUTS: Readonly<{
1304
+ request: number;
1305
+ service: number;
1306
+ queue: number;
1307
+ fetch: number;
1308
+ webhook: number;
1309
+ shutdown: number;
1310
+ loader: number;
1311
+ }>;
1312
+
1313
+ export interface NormalizedTimeouts {
1314
+ request: number | false;
1315
+ service: number | false;
1316
+ queue: number | false;
1317
+ fetch: number | false;
1318
+ webhook: number | false;
1319
+ shutdown: number | false;
1320
+ loader: number | false;
1321
+ }
1322
+
1323
+ export function normalizeTimeouts(options?: {
1324
+ timeouts?: Partial<Record<keyof NormalizedTimeouts, number | string | false>>;
1325
+ timeout?: number | string | false;
1326
+ [key: string]: unknown;
1327
+ }): Readonly<NormalizedTimeouts>;
1328
+
1329
+ export class TimeoutError extends WebspressoError {
1330
+ status: number;
1331
+ statusCode: number;
1332
+ timeout?: number | null;
1333
+ scope: string;
1334
+ constructor(message?: string, options?: ErrorOptions & { timeout?: number; status?: number; statusCode?: number; scope?: string });
1335
+ }
1336
+
1337
+ export function withTimeout<T>(
1338
+ promiseOrFn: Promise<T> | ((signal?: AbortSignal) => Promise<T> | T),
1339
+ timeout: number | string | boolean,
1340
+ options?: {
1341
+ controller?: AbortController;
1342
+ signal?: AbortSignal;
1343
+ errorMessage?: string;
1344
+ errorCode?: string;
1345
+ statusCode?: number;
1346
+ scope?: string;
1347
+ unref?: boolean;
1348
+ createError?: (timeoutMs: number) => Error;
1349
+ }
1350
+ ): Promise<T>;
1351
+
1352
+ export function createTimeoutMiddleware(
1353
+ timeoutConfig: number | string | boolean,
1354
+ options?: { respond?: boolean }
1355
+ ): (req: Request, res: Response, next: (err?: unknown) => void) => void;
1356
+
833
1357
  export const utils: Record<string, unknown>;
834
1358
 
835
1359
  export class AssetManager {
@@ -917,9 +1441,34 @@ export interface ScopeContext {
917
1441
  tenantId?: unknown;
918
1442
  withTrashed?: boolean;
919
1443
  onlyTrashed?: boolean;
1444
+ user?: Record<string, any> | null;
1445
+ rlsDisabled?: boolean;
920
1446
  [key: string]: unknown;
921
1447
  }
922
1448
 
1449
+ export type ModelRlsAction = 'read' | 'update' | 'delete' | 'create';
1450
+
1451
+ export type ModelRlsRuleCallback<T = any> = (
1452
+ user: Record<string, any> | null,
1453
+ qb: import('knex').Knex.QueryBuilder,
1454
+ action?: ModelRlsAction,
1455
+ context?: ScopeContext
1456
+ ) => boolean | Record<string, any> | ((q: import('knex').Knex.QueryBuilder) => any) | void;
1457
+
1458
+ export interface ModelRlsConfig<T = any> {
1459
+ userColumn?: string;
1460
+ tenantColumn?: string;
1461
+ bypassRoles?: string[] | ((user: Record<string, any> | null, action?: string) => boolean) | false;
1462
+ bypass?: (user: Record<string, any> | null, action: string, context?: ScopeContext) => boolean;
1463
+ read?: ModelRlsRuleCallback<T> | Record<string, any> | boolean;
1464
+ update?: ModelRlsRuleCallback<T> | Record<string, any> | boolean;
1465
+ delete?: ModelRlsRuleCallback<T> | Record<string, any> | boolean;
1466
+ create?: ((user: Record<string, any> | null, data: Partial<T>, context?: ScopeContext) => boolean | Partial<T> | Promise<boolean | Partial<T>>) | boolean;
1467
+ rule?: ModelRlsRuleCallback<T>;
1468
+ filter?: ModelRlsRuleCallback<T>;
1469
+ validateUpdate?: (user: Record<string, any> | null, data: Partial<T>, context?: ScopeContext) => boolean | void;
1470
+ }
1471
+
923
1472
  export type RelationType = 'belongsTo' | 'hasMany' | 'hasOne';
924
1473
 
925
1474
  export type RelationCascadeOption =
@@ -1100,6 +1649,7 @@ export interface ModelOptions<TSchema = ZodObject<Record<string, ZodTypeAny>>> {
1100
1649
  };
1101
1650
  searchable?: string[];
1102
1651
  cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
1652
+ rls?: ModelRlsConfig<any> | ModelRlsRuleCallback<any> | null;
1103
1653
  }
1104
1654
 
1105
1655
  export interface ModelDefinition<TModel = Record<string, any>> {
@@ -1141,6 +1691,7 @@ export interface ModelDefinition<TModel = Record<string, any>> {
1141
1691
  searchable?: string[];
1142
1692
  hooks: Record<string, unknown>;
1143
1693
  cache?: boolean | 'auto' | 'smart' | { strategy: 'auto' | 'smart' };
1694
+ rls?: ModelRlsConfig<any> | ModelRlsRuleCallback<any> | null;
1144
1695
  }
1145
1696
 
1146
1697
  export function defineModel<TSchema = ZodObject<any>>(
@@ -1222,6 +1773,11 @@ export interface QueryBuilder<T = Record<string, any>> {
1222
1773
  include(...relations: string[]): this;
1223
1774
  withTrashed(): this;
1224
1775
  onlyTrashed(): this;
1776
+ forUser(user: Record<string, any> | null): this;
1777
+ withoutRls(): this;
1778
+ forTenant(tenantId: unknown): this;
1779
+ withContext(customContext: Partial<ScopeContext>): this;
1780
+ asAction(action: ModelRlsAction): this;
1225
1781
  first(): Promise<T | null>;
1226
1782
  list(): Promise<T[]>;
1227
1783
  get(): Promise<T[]>;
@@ -1236,13 +1792,41 @@ export interface QueryBuilder<T = Record<string, any>> {
1236
1792
  [key: string]: unknown;
1237
1793
  }
1238
1794
 
1795
+ export interface BatchOptions {
1796
+ chunkSize?: number;
1797
+ transaction?: boolean;
1798
+ validate?: boolean;
1799
+ hooks?: boolean;
1800
+ returning?: boolean;
1801
+ }
1802
+
1803
+ export interface UpsertOptions extends BatchOptions {
1804
+ updateColumns?: string[] | Record<string, unknown>;
1805
+ }
1806
+
1807
+ export interface BatchUpsertOptions extends BatchOptions {
1808
+ updateColumns?: string[] | Record<string, unknown>;
1809
+ }
1810
+
1239
1811
  export interface Repository<T = Record<string, any>> {
1240
1812
  findById(id: string | number, options?: FindOptions): Promise<T | null>;
1241
1813
  findOne(conditions: Partial<T> | Record<string, unknown>, options?: FindOptions): Promise<T | null>;
1242
1814
  findAll(options?: FindOptions): Promise<T[]>;
1243
1815
  find(conditions?: Partial<T> | Record<string, unknown>, options?: FindOptions): Promise<T[]>;
1244
1816
  create(data: Partial<T> | Record<string, unknown>): Promise<T>;
1245
- createMany(data: (Partial<T> | Record<string, unknown>)[]): Promise<T[]>;
1817
+ createMany(data: (Partial<T> | Record<string, unknown>)[], options?: BatchOptions): Promise<T[]>;
1818
+ createBatch(data: (Partial<T> | Record<string, unknown>)[], options?: BatchOptions): Promise<T[]>;
1819
+ upsert(
1820
+ data: Partial<T> | Record<string, unknown>,
1821
+ conflictTarget?: string | string[],
1822
+ updateColumns?: string[] | Record<string, unknown>,
1823
+ options?: UpsertOptions
1824
+ ): Promise<T | null>;
1825
+ upsertBatch(
1826
+ data: (Partial<T> | Record<string, unknown>)[],
1827
+ conflictTarget?: string | string[],
1828
+ options?: BatchUpsertOptions
1829
+ ): Promise<T[]>;
1246
1830
  update(id: string | number, data: Partial<T> | Record<string, unknown>): Promise<T | null>;
1247
1831
  updateWhere(conditions: Partial<T> | Record<string, unknown>, data: Partial<T> | Record<string, unknown>): Promise<number>;
1248
1832
  delete(id: string | number, options?: { cascade?: boolean; deletedAt?: Date }): Promise<boolean>;
@@ -1255,6 +1839,11 @@ export interface Repository<T = Record<string, any>> {
1255
1839
  with(...relations: string[]): QueryBuilder<T>;
1256
1840
  include(...relations: string[]): QueryBuilder<T>;
1257
1841
  search(term: string, columns?: string | string[], options?: SearchOptions): QueryBuilder<T>;
1842
+ forUser(user: Record<string, any> | null): Repository<T>;
1843
+ withoutRls(): Repository<T>;
1844
+ forTenant(tenantId: unknown): Repository<T>;
1845
+ withContext(customContext: Partial<ScopeContext>): Repository<T>;
1846
+ getScopeContext(): ScopeContext;
1258
1847
  model: ModelDefinition<T>;
1259
1848
  }
1260
1849
 
@@ -1361,6 +1950,10 @@ export interface TransactionContext {
1361
1950
  getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
1362
1951
  getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
1363
1952
  createRepository<T = Record<string, any>>(model: ModelDefinition<T>, scopeContext?: ScopeContext): Repository<T>;
1953
+ forTenant(tenantId: unknown): this;
1954
+ forUser(user: Record<string, any> | null): this;
1955
+ withoutRls(): this;
1956
+ getScopeContext(): ScopeContext;
1364
1957
  }
1365
1958
 
1366
1959
  export interface DatabaseInstance {
@@ -1374,6 +1967,21 @@ export interface DatabaseInstance {
1374
1967
  getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
1375
1968
  createRepository<T = Record<string, any>>(model: ModelDefinition<T>, scopeContext?: ScopeContext): Repository<T>;
1376
1969
  query<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): QueryBuilder<T>;
1970
+ forUser(user: Record<string, any> | null): {
1971
+ getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
1972
+ getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
1973
+ query<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): QueryBuilder<T>;
1974
+ };
1975
+ withoutRls(): {
1976
+ getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
1977
+ getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
1978
+ query<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): QueryBuilder<T>;
1979
+ };
1980
+ forTenant(tenantId: unknown): {
1981
+ getRepository<K extends keyof WebspressoModels>(modelName: K, scopeContext?: ScopeContext): Repository<WebspressoModels[K]>;
1982
+ getRepository<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): Repository<T>;
1983
+ query<T = Record<string, any>>(modelName: string, scopeContext?: ScopeContext): QueryBuilder<T>;
1984
+ };
1377
1985
  transaction<T>(callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
1378
1986
  runInTransaction<T>(callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
1379
1987
  getAmbientTransaction(): Knex.Transaction | null;
@@ -1390,6 +1998,8 @@ export function getAmbientTransaction(): Knex.Transaction | null;
1390
1998
  export function hasAmbientTransaction(): boolean;
1391
1999
  export function createTransactionContext(trx: Knex.Transaction, scopeContext?: ScopeContext): TransactionContext;
1392
2000
  export function runTransaction<T>(knex: Knex, callback: (ctx: TransactionContext) => Promise<T>, scopeContext?: ScopeContext): Promise<T>;
2001
+ export function calculateSafeChunkSize(knexInstance: unknown, columnCount?: number, requestedChunkSize?: number | null): number;
2002
+ export function chunkArray<T>(array: T[], size: number): T[][];
1393
2003
 
1394
2004
  export function createMemoryCacheProvider(options?: OrmMemoryCacheOptions): {
1395
2005
  get(key: string): unknown;
@@ -3187,6 +3797,7 @@ export interface PageContext<TParams = Record<string, string>, TQuery = Record<s
3187
3797
  logger: Console;
3188
3798
  redirect: (url: string, status?: number) => { __redirected: boolean };
3189
3799
  error: (status?: number, message?: string) => never;
3800
+ earlyHints?: (links: string | EarlyHintLink | (string | EarlyHintLink)[], callback?: (err?: Error | null) => void) => boolean;
3190
3801
  fsy: Record<string, unknown>;
3191
3802
  locale: string;
3192
3803
  t: (key: string, params?: Record<string, unknown>) => string;
@@ -3195,6 +3806,7 @@ export interface PageContext<TParams = Record<string, string>, TQuery = Record<s
3195
3806
 
3196
3807
  export interface DefinePageOptions<TData = any, TParams = Record<string, string>, TQuery = Record<string, string>> {
3197
3808
  middleware?: (string | import('express').RequestHandler | [string, Record<string, unknown>])[];
3809
+ earlyHints?: boolean | (string | EarlyHintLink)[] | EarlyHintsOptions;
3198
3810
  load?: (ctx: PageContext<TParams, TQuery>) => Promise<TData> | TData;
3199
3811
  head?: (data: TData, ctx: PageContext<TParams, TQuery>) => Record<string, unknown>;
3200
3812
  render?: (data: TData, ctx: PageContext<TParams, TQuery>) => string | Promise<string>;
@@ -3787,7 +4399,7 @@ export class SessionManager {
3787
4399
  }
3788
4400
 
3789
4401
  export function parseUserAgent(userAgent?: string): DeviceInfo;
3790
- export function getClientIp(req?: any): string;
4402
+ export function getClientIp<T = string>(req?: any, fallback?: T): string | T;
3791
4403
  export function createUserSessionsTable(knex: any): Promise<void>;
3792
4404
  export function dropUserSessionsTable(knex: any): Promise<void>;
3793
4405
  export function createKnexSessionTracker(db: any, options?: { tableName?: string }): SessionTracker;
@@ -3859,4 +4471,17 @@ export namespace commands {
3859
4471
  };
3860
4472
  }
3861
4473
 
4474
+ // --- Row Level Security Plugin ---
4475
+ export interface RlsPluginOptions {
4476
+ bypassRoles?: string[] | ((user: Record<string, any> | null, req: any) => boolean) | false;
4477
+ getUser?: (req: any) => Record<string, any> | null;
4478
+ getTenantId?: (req: any, user: Record<string, any> | null) => unknown;
4479
+ global?: boolean;
4480
+ enabled?: boolean;
4481
+ }
4482
+
4483
+ export function rlsPlugin(options?: RlsPluginOptions): import('./src/plugin-manager').Plugin;
4484
+ export function createRlsMiddleware(options?: RlsPluginOptions): (req: any, res: any, next: (err?: any) => void) => void;
4485
+
4486
+
3862
4487