@thexjs/core 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -103,6 +103,103 @@ interface ReadinessResult {
103
103
  */
104
104
  declare function createHealthCheckHandler(options?: HealthCheckOptions): (req: Request) => Promise<Response | null>;
105
105
 
106
+ /**
107
+ * Production-grade metrics: counters and histograms recorded per request and
108
+ * exported either as Prometheus text at a `/metrics` endpoint or pushed to an
109
+ * OpenTelemetry meter. `@thexjs/core` has no hard dependency on Prometheus or
110
+ * OpenTelemetry — apps opt in by constructing a reporter; everything here
111
+ * degrades to a no-op if nothing is configured. Mirrors the `ErrorReporter`
112
+ * pattern in `./monitoring`.
113
+ */
114
+ interface MetricLabels {
115
+ [key: string]: string;
116
+ }
117
+ interface MetricsReporter {
118
+ /** Increment a counter by `delta` (default 1). */
119
+ incr(name: string, delta?: number, labels?: MetricLabels): void;
120
+ /** Record an observation (e.g. latency in milliseconds) into a histogram. */
121
+ observe(name: string, value: number, labels?: MetricLabels): void;
122
+ /** Optional: flush buffered metrics, e.g. on graceful shutdown. */
123
+ flush?(): Promise<void>;
124
+ /**
125
+ * Optional: answer a `/metrics` request (Prometheus text format). Return
126
+ * `null` for any other path so it can be composed ahead of normal routing,
127
+ * like `createHealthCheckHandler`.
128
+ */
129
+ handleMetrics?(req: Request): Promise<Response | null> | Response | null;
130
+ }
131
+ /** No-op reporter used when no metrics integration is configured. */
132
+ declare const noopMetrics: MetricsReporter;
133
+ interface CounterSeries {
134
+ name: string;
135
+ labels: MetricLabels;
136
+ value: number;
137
+ }
138
+ interface HistogramSeries {
139
+ name: string;
140
+ labels: MetricLabels;
141
+ /** Cumulative count per bucket, parallel to the reporter's bucket bounds. */
142
+ bucketCounts: number[];
143
+ sum: number;
144
+ count: number;
145
+ }
146
+ interface MetricsSnapshot {
147
+ counters: CounterSeries[];
148
+ histograms: HistogramSeries[];
149
+ }
150
+ /** Default latency bucket bounds (ms), used when a histogram has no explicit bounds. */
151
+ declare const DEFAULT_HISTOGRAM_BUCKETS_MS: number[];
152
+ interface InMemoryMetricsOptions {
153
+ /** Bucket bounds for histograms. Defaults to `DEFAULT_HISTOGRAM_BUCKETS_MS`. */
154
+ histogramBuckets?: number[];
155
+ }
156
+ /**
157
+ * In-process metrics registry with a `snapshot()` you can render or test
158
+ * against, plus an optional `/metrics` handler in Prometheus text format.
159
+ * The single object this returns is both a `MetricsReporter` and a handler
160
+ * factory, so it can be passed straight to `createApp`'s `observability.metrics`
161
+ * to get request metrics recorded and served.
162
+ */
163
+ declare function createInMemoryMetrics(options?: InMemoryMetricsOptions): {
164
+ incr: (name: string, delta?: number, labels?: MetricLabels) => void;
165
+ observe: (name: string, value: number, labels?: MetricLabels) => void;
166
+ snapshot: () => MetricsSnapshot;
167
+ renderMetrics: () => string;
168
+ handleMetrics: (req: Request) => Response | null;
169
+ flush(): Promise<void>;
170
+ };
171
+ type InMemoryMetricsReporter = ReturnType<typeof createInMemoryMetrics>;
172
+ /**
173
+ * The subset of an OpenTelemetry meter this integration needs. Pass a meter
174
+ * from your own OTel SDK setup (`metrics.getMeter(...)`) — `@thexjs/core`
175
+ * never initializes OTel itself. Mirrors `createOtelReporter`.
176
+ */
177
+ interface OtelMeterLike {
178
+ createCounter(name: string, options?: {
179
+ description?: string;
180
+ }): {
181
+ add(value: number, attributes?: MetricLabels): void;
182
+ };
183
+ createHistogram(name: string, options?: {
184
+ description?: string;
185
+ }): {
186
+ record(value: number, attributes?: MetricLabels): void;
187
+ };
188
+ }
189
+ /**
190
+ * Forwards recorded metrics to an OpenTelemetry meter. Instruments are
191
+ * created lazily on first use. No `/metrics` endpoint is served — export
192
+ * happens through your OTel setup instead.
193
+ */
194
+ declare function createOtlpMetricsReporter(meter: OtelMeterLike): MetricsReporter;
195
+ /**
196
+ * Wraps a fetch handler so every request is measured: `x_http_requests_total`
197
+ * (counter, labels `method`, `status`), `x_http_request_duration_ms`
198
+ * (histogram, label `method`), and `x_http_errors_total` (counter) for requests
199
+ * that throw. Composable ahead of routing, like `withRequestLogging`.
200
+ */
201
+ declare function withRequestMetrics<Server = unknown>(reporter: MetricsReporter, handler: (req: Request, server?: Server) => Response | Promise<Response>): (req: Request, server?: Server) => Promise<Response>;
202
+
106
203
  /**
107
204
  * Plugin hook for capturing unhandled exceptions during SSR and server
108
205
  * action execution, and exporting them to an APM provider. `@thexjs/core`
@@ -337,6 +434,14 @@ interface CreateAppOptions {
337
434
  errorReporter?: ErrorReporter;
338
435
  /** /healthz and /readyz endpoints, served ahead of all other routing. */
339
436
  health?: HealthCheckOptions;
437
+ /**
438
+ * Metrics reporter for request counters/histograms. Pass
439
+ * `createInMemoryMetrics()` (serves `/metrics` in Prometheus text format)
440
+ * or `createOtlpMetricsReporter(meter)`. When set, request metrics are
441
+ * recorded and, if the reporter exposes `handleMetrics`, a `/metrics`
442
+ * endpoint is served ahead of all other routing.
443
+ */
444
+ metrics?: MetricsReporter;
340
445
  };
341
446
  /** Remote-image proxy at /_x/image?url=... — see ImageProxyOptions. Unset/empty remoteHosts means the route 404s. */
342
447
  images?: ImageProxyOptions;
@@ -521,4 +626,4 @@ declare const logger: Logger;
521
626
  */
522
627
  declare function withRequestLogging<Server = unknown>(handler: (req: Request, server?: Server) => Response | Promise<Response>): (req: Request, server?: Server) => Promise<Response>;
523
628
 
524
- export { type BuildOptions, CLIENT_NAV_SCRIPT, type ContentEntry, type CreateAppOptions, type CsrfOptions, type CsrfResult, DefaultNotFound, EnvLeakageError, type ErrorContext, type ErrorReporter, type Frontmatter, type HealthCheck, type HealthCheckOptions, type ImageProxyOptions, Island, type IslandEntry, type IslandMode, IslandProvider, type LayoutEntry, Link, type LinkProps, type LoaderArgs, type LoaderReturn, type LogFields, type Logger, type MiddlewareContext, type MiddlewareEntry, type MiddlewareFn, type MiddlewareNext, type NotFoundEntry, type OtelTracerLike, PUBLIC_ENV_PREFIX, type RateLimitOptions, type RateLimitResult, type RateLimitStore, type ReadinessResult, type RevalidateOptions, type RouteEntry, type RouteMode, type RouteProps, type SecurityHeadersOptions, type SentryLike, applySecurityHeaders, assertNoEnvLeakage, build, buildSecurityHeaders, checkCsrf, combineReporters, composeMiddleware, createApp, createHealthCheckHandler, createImageProxyHandler, createOtelReporter, createRateLimiter, createRedisRateLimitStore, createSentryReporter, defineConfig, escapeHtml, findLayoutChain, findLeakedEnvKeys, findMiddlewareChain, generateCsrfToken, generateManifestSource, generateServerFunctionClient, getErrorReporter, getServerFunctionHandler, logger, noopReporter, rateLimitMiddleware, registerServerFunctions, renderErrorOverlay, renderMarkdown, renderPage, renderStaticPage, renderStreamingPage, reportException, resetServerFunctions, scanApiDir, scanContent, scanLayouts, scanLayoutsDir, scanMiddleware, scanNotFound, scanPages, scanRoutes, setErrorReporter, verifyCsrfToken, verifyOrigin, withCsrfCookie, withRequestLogging, writeManifest };
629
+ export { type BuildOptions, CLIENT_NAV_SCRIPT, type ContentEntry, type CounterSeries, type CreateAppOptions, type CsrfOptions, type CsrfResult, DEFAULT_HISTOGRAM_BUCKETS_MS, DefaultNotFound, EnvLeakageError, type ErrorContext, type ErrorReporter, type Frontmatter, type HealthCheck, type HealthCheckOptions, type HistogramSeries, type ImageProxyOptions, type InMemoryMetricsOptions, type InMemoryMetricsReporter, Island, type IslandEntry, type IslandMode, IslandProvider, type LayoutEntry, Link, type LinkProps, type LoaderArgs, type LoaderReturn, type LogFields, type Logger, type MetricLabels, type MetricsReporter, type MetricsSnapshot, type MiddlewareContext, type MiddlewareEntry, type MiddlewareFn, type MiddlewareNext, type NotFoundEntry, type OtelMeterLike, type OtelTracerLike, PUBLIC_ENV_PREFIX, type RateLimitOptions, type RateLimitResult, type RateLimitStore, type ReadinessResult, type RevalidateOptions, type RouteEntry, type RouteMode, type RouteProps, type SecurityHeadersOptions, type SentryLike, applySecurityHeaders, assertNoEnvLeakage, build, buildSecurityHeaders, checkCsrf, combineReporters, composeMiddleware, createApp, createHealthCheckHandler, createImageProxyHandler, createInMemoryMetrics, createOtelReporter, createOtlpMetricsReporter, createRateLimiter, createRedisRateLimitStore, createSentryReporter, defineConfig, escapeHtml, findLayoutChain, findLeakedEnvKeys, findMiddlewareChain, generateCsrfToken, generateManifestSource, generateServerFunctionClient, getErrorReporter, getServerFunctionHandler, logger, noopMetrics, noopReporter, rateLimitMiddleware, registerServerFunctions, renderErrorOverlay, renderMarkdown, renderPage, renderStaticPage, renderStreamingPage, reportException, resetServerFunctions, scanApiDir, scanContent, scanLayouts, scanLayoutsDir, scanMiddleware, scanNotFound, scanPages, scanRoutes, setErrorReporter, verifyCsrfToken, verifyOrigin, withCsrfCookie, withRequestLogging, withRequestMetrics, writeManifest };