@thexjs/core 1.0.0 → 1.2.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/adapter.d.ts +153 -0
- package/dist/adapter.js +320 -0
- package/dist/chunk-Y3MLOFAG.js +214 -0
- package/dist/data.d.ts +12 -1
- package/dist/data.js +12 -5
- package/dist/index.d.ts +109 -4
- package/dist/index.js +298 -265
- package/package.json +6 -2
package/dist/data.d.ts
CHANGED
|
@@ -7,9 +7,20 @@ interface SQLiteOptions {
|
|
|
7
7
|
}
|
|
8
8
|
declare function connectSQLite(options?: SQLiteOptions): Database;
|
|
9
9
|
|
|
10
|
+
/** A Postgres client scoped to a single transaction (auto-commit/rollback). */
|
|
11
|
+
interface PostgresTransactionClient {
|
|
12
|
+
unsafe(query: string, params?: unknown[]): Promise<unknown>;
|
|
13
|
+
(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown>;
|
|
14
|
+
}
|
|
10
15
|
interface PostgresClient {
|
|
11
|
-
unsafe(query: string): Promise<unknown>;
|
|
16
|
+
unsafe(query: string, params?: unknown[]): Promise<unknown>;
|
|
12
17
|
(strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown>;
|
|
18
|
+
/**
|
|
19
|
+
* Runs `fn` inside a transaction. The callback receives a transaction-scoped
|
|
20
|
+
* client; when it resolves the transaction commits, when it throws it rolls
|
|
21
|
+
* back — so a group of statements either all apply or none do.
|
|
22
|
+
*/
|
|
23
|
+
begin<T>(fn: (tx: PostgresTransactionClient) => Promise<T>): Promise<T>;
|
|
13
24
|
}
|
|
14
25
|
type PostgresSslMode = "disable" | "prefer" | "require" | "verify-ca" | "verify-full";
|
|
15
26
|
interface PostgresOptions {
|
package/dist/data.js
CHANGED
|
@@ -84,7 +84,10 @@ function connectPostgres(options = {}) {
|
|
|
84
84
|
return new Proxy(sql, {
|
|
85
85
|
get(target, prop, receiver) {
|
|
86
86
|
if (prop === "unsafe") {
|
|
87
|
-
return (query) => run(() => client.unsafe(query));
|
|
87
|
+
return (query, params) => run(() => client.unsafe(query, params));
|
|
88
|
+
}
|
|
89
|
+
if (prop === "begin") {
|
|
90
|
+
return (fn) => run(() => client.begin(async (tx) => fn(tx)));
|
|
88
91
|
}
|
|
89
92
|
const value = Reflect.get(target, prop, receiver);
|
|
90
93
|
return typeof value === "function" ? value.bind(target) : value;
|
|
@@ -119,8 +122,10 @@ function runSQLiteMigrations(db, migrationsDir) {
|
|
|
119
122
|
continue;
|
|
120
123
|
}
|
|
121
124
|
const sql = readFileSync(join(migrationsDir, file), "utf-8");
|
|
122
|
-
db.
|
|
123
|
-
|
|
125
|
+
db.transaction(() => {
|
|
126
|
+
db.run(sql);
|
|
127
|
+
db.run("INSERT INTO _x_migrations (name) VALUES (?1)", [file]);
|
|
128
|
+
})();
|
|
124
129
|
console.log(`[x] migration applied: ${file}`);
|
|
125
130
|
result.applied.push(file);
|
|
126
131
|
}
|
|
@@ -146,8 +151,10 @@ async function runPostgresMigrations(client, migrationsDir) {
|
|
|
146
151
|
continue;
|
|
147
152
|
}
|
|
148
153
|
const raw = readFileSync(join(migrationsDir, file), "utf-8");
|
|
149
|
-
await client.
|
|
150
|
-
|
|
154
|
+
await client.begin(async (tx) => {
|
|
155
|
+
await tx.unsafe(raw);
|
|
156
|
+
await tx.unsafe("INSERT INTO _x_migrations (name) VALUES ($1)", [file]);
|
|
157
|
+
});
|
|
151
158
|
console.log(`[x] migration applied: ${file}`);
|
|
152
159
|
result.applied.push(file);
|
|
153
160
|
}
|
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`
|
|
@@ -289,9 +386,9 @@ declare function createRateLimiter(options?: RateLimitOptions): {
|
|
|
289
386
|
declare function rateLimitMiddleware(limiter: ReturnType<typeof createRateLimiter>, req: Request, server?: RateLimitServer): Promise<Response | null>;
|
|
290
387
|
/**
|
|
291
388
|
* Shared rate-limit store backed by Redis, so limits are enforced across
|
|
292
|
-
* multiple server instances.
|
|
293
|
-
*
|
|
294
|
-
* `
|
|
389
|
+
* multiple server instances. Connects lazily on first use and keeps retrying
|
|
390
|
+
* after a failed connection attempt. Pass the result as `store` in
|
|
391
|
+
* `createRateLimiter`/`security.rateLimit`.
|
|
295
392
|
*/
|
|
296
393
|
declare function createRedisRateLimitStore(options?: {
|
|
297
394
|
url?: string;
|
|
@@ -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 };
|