@thexjs/core 1.3.5 → 1.4.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/README.md CHANGED
@@ -53,6 +53,23 @@ Given a `pagesDir`, `scanPages` walks the directory and maps files to routes:
53
53
 
54
54
  Files and directories prefixed with `_` or `.` are never treated as routes.
55
55
 
56
+ ### Route resolution order
57
+
58
+ When several routes could match one URL, the most specific one wins:
59
+
60
+ 1. **Static (literal) routes beat dynamic ones** — `/users/new` is served by
61
+ `pages/users/new.tsx`, never by `pages/users/[id].tsx`.
62
+ 2. **Single-segment params beat catch-alls** — `[slug].tsx` matches
63
+ `/blog/hello` over `[...rest].tsx`.
64
+ 3. **Same-category ties are broken segment-by-segment, positionally**: at the
65
+ first segment where two routes differ, a literal segment (`users`) beats a
66
+ param (`:id`) which beats a catch-all (`*`). For example `pages/users/[id].tsx`
67
+ (`/users/:id`) beats `pages/[slug]/profile.tsx` (`/:slug/profile`) for the
68
+ URL `/users/profile`, because their first segments are literal vs. param.
69
+ Fully tied routes (identical segment specificity) fall back to a lexical
70
+ sort by route path. The outcome is deterministic, independent of the OS's
71
+ directory-scan order — you never need to rename files to force a winner.
72
+
56
73
  Underlying scanners (`scanRoutes`, `scanPages`, `scanApiDir`, `scanLayouts`, `scanLayoutsDir`, `scanMiddleware`, `scanNotFound`) and chain resolvers (`findLayoutChain`, `findMiddlewareChain`) are exported if you need to build custom tooling on top of the same conventions.
57
74
 
58
75
  ## Route modes: static vs. server
package/dist/adapter.js CHANGED
@@ -9,7 +9,8 @@ import {
9
9
  scanNotFound,
10
10
  scanPages,
11
11
  scanRoutes
12
- } from "./chunk-PQ7ZVWEJ.js";
12
+ } from "./chunk-VC5XI6HX.js";
13
+ import "./chunk-VIXLBKMC.js";
13
14
 
14
15
  // src/adapter/bundle.ts
15
16
  import { mkdirSync, rmSync, writeFileSync } from "fs";
@@ -1,3 +1,8 @@
1
+ import {
2
+ OTEL_ERROR_STATUS_CODE,
3
+ tracePhase
4
+ } from "./chunk-VIXLBKMC.js";
5
+
1
6
  // src/security/env-isolation.ts
2
7
  var PUBLIC_ENV_PREFIX = "THEXJS_PUBLIC_";
3
8
  var ENV_ACCESS_PATTERNS = [
@@ -86,7 +91,6 @@ function createSentryReporter(sentry) {
86
91
  }
87
92
  };
88
93
  }
89
- var OTEL_ERROR_STATUS_CODE = 2;
90
94
  function createOtelReporter(tracer) {
91
95
  return {
92
96
  captureException(error, context) {
@@ -267,8 +271,8 @@ function findMiddlewareChain(routeFilePath, middleware, routesDir) {
267
271
  return chain;
268
272
  }
269
273
  function routePatternToRegex(routePath) {
270
- const regexStr = routePath.replace(/\//g, "\\/").replace(/:(\w+)/g, "([^/]+)").replace(/\*/g, "(.+)");
271
- return new RegExp(`^${regexStr}$`);
274
+ const escaped = routePath.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\//g, "\\/").replace(/:(\w+)/g, "([^/]+)").replace(/\*/g, "(.+)");
275
+ return new RegExp(`^${escaped}$`);
272
276
  }
273
277
  function extractParams(routePath, paramNames, url) {
274
278
  const regex = routePatternToRegex(routePath);
@@ -311,6 +315,21 @@ export function href<T extends keyof RouteMap & string>(
311
315
  for (const [key, value] of Object.entries(params)) {
312
316
  result = result.replace(new RegExp(\`:\${key}(?=/|$)\`), encodeURIComponent(String(value)));
313
317
  }
318
+ // Catch-all params have no \`:name\` token in the path \u2014 they render as an
319
+ // anonymous \`*\` segment. Substitute them in segment order, keeping \`/\`
320
+ // between encoded fragments so multi-segment values stay readable. An exact
321
+ // segment-token check (prefixed by \`/\`) is required: a prefix scan of
322
+ // \`:key\` would also match a longer \`:id2\` param and skip the wildcard.
323
+ const isNamedToken = (key: string) => new RegExp(\`(^|/):\${key}(?=/|$)\`).test(path);
324
+ for (const [key, value] of Object.entries(params)) {
325
+ if (!isNamedToken(key)) {
326
+ const encoded = String(value)
327
+ .split("/")
328
+ .map(encodeURIComponent)
329
+ .join("/");
330
+ result = result.replace(/\\*/, encoded);
331
+ }
332
+ }
314
333
  result = result.replace(/\\*+$/, "");
315
334
  return result;
316
335
  }
@@ -323,6 +342,65 @@ function writeManifest(routes, routesDir) {
323
342
  return manifestPath;
324
343
  }
325
344
 
345
+ // src/security/body-size.ts
346
+ var DEFAULT_MAX_BODY_SIZE = 1048576;
347
+ var RequestBodyTooLargeError = class extends Error {
348
+ maxBytes;
349
+ constructor(maxBytes) {
350
+ super(`Request body exceeds the ${maxBytes} byte limit`);
351
+ this.name = "RequestBodyTooLargeError";
352
+ this.maxBytes = maxBytes;
353
+ }
354
+ };
355
+ function isBodylessMethod(method) {
356
+ return method === "GET" || method === "HEAD" || method === "OPTIONS";
357
+ }
358
+ function enforceRequestBodySize(req, maxBytes) {
359
+ if (isBodylessMethod(req.method)) return req;
360
+ const contentLength = req.headers.get("content-length");
361
+ if (contentLength !== null) {
362
+ const declared = Number(contentLength);
363
+ if (Number.isFinite(declared) && declared > maxBytes) {
364
+ return new Response("Payload too large", {
365
+ status: 413,
366
+ headers: { "Content-Type": "text/plain; charset=utf-8" }
367
+ });
368
+ }
369
+ return req;
370
+ }
371
+ const source = req.body;
372
+ if (source === null) return req;
373
+ const { readable, writable } = new TransformStream();
374
+ const writer = writable.getWriter();
375
+ let total = 0;
376
+ const pump = async () => {
377
+ const reader = source.getReader();
378
+ try {
379
+ while (true) {
380
+ const { done, value } = await reader.read();
381
+ if (done) break;
382
+ total += value.byteLength;
383
+ if (total > maxBytes) {
384
+ await reader.cancel().catch(() => {
385
+ });
386
+ await writer.abort(new RequestBodyTooLargeError(maxBytes));
387
+ return;
388
+ }
389
+ await writer.write(value);
390
+ }
391
+ await writer.close();
392
+ } catch (err) {
393
+ await writer.abort(err);
394
+ }
395
+ };
396
+ void pump();
397
+ return new Request(req.url, {
398
+ method: req.method,
399
+ headers: req.headers,
400
+ body: readable
401
+ });
402
+ }
403
+
326
404
  // src/security/csrf.ts
327
405
  var CSRF_COOKIE_NAME = "x_csrf_token";
328
406
  var CSRF_HEADER_NAME = "x-csrf-token";
@@ -366,6 +444,15 @@ function readCookie(req, name) {
366
444
  }
367
445
  return null;
368
446
  }
447
+ function tokensEqual(a, b) {
448
+ const encoder = new TextEncoder();
449
+ const aBytes = encoder.encode(a);
450
+ const bBytes = encoder.encode(b);
451
+ if (aBytes.length !== bBytes.length) return false;
452
+ let diff = 0;
453
+ for (let i = 0; i < aBytes.length; i++) diff |= (aBytes[i] ?? 0) ^ (bBytes[i] ?? 0);
454
+ return diff === 0;
455
+ }
369
456
  function verifyCsrfToken(req) {
370
457
  if (SAFE_METHODS.has(req.method)) return { ok: true };
371
458
  const cookieToken = readCookie(req, CSRF_COOKIE_NAME);
@@ -373,7 +460,7 @@ function verifyCsrfToken(req) {
373
460
  if (!cookieToken || !headerToken) {
374
461
  return { ok: false, reason: `missing CSRF cookie or "${CSRF_HEADER_NAME}" header` };
375
462
  }
376
- if (cookieToken !== headerToken) {
463
+ if (!tokensEqual(cookieToken, headerToken)) {
377
464
  return { ok: false, reason: "CSRF token mismatch" };
378
465
  }
379
466
  return { ok: true };
@@ -466,14 +553,28 @@ function getServerFunctionHandler(csrfOptions) {
466
553
  try {
467
554
  const body = await req.json();
468
555
  args = Array.isArray(body) ? body : [body];
469
- } catch {
556
+ } catch (err) {
557
+ if (err instanceof RequestBodyTooLargeError) {
558
+ return new Response("Payload too large", { status: 413 });
559
+ }
470
560
  return new Response("Invalid request body", { status: 400 });
471
561
  }
472
562
  try {
473
- const result = await fn(...args);
563
+ const result = await tracePhase(
564
+ "x.action",
565
+ { route: concretePath, action: actionName },
566
+ () => fn(...args)
567
+ );
474
568
  return Response.json(result);
475
569
  } catch (err) {
476
- reportException(err, { route: concretePath, phase: "action" });
570
+ const errorId = crypto.randomUUID().replace(/-/g, "");
571
+ reportException(err, { route: concretePath, phase: "action", errorId });
572
+ if (process.env.NODE_ENV === "production") {
573
+ return new Response(`Internal error (id: ${errorId})`, {
574
+ status: 500,
575
+ headers: { "x-x-error-id": errorId }
576
+ });
577
+ }
477
578
  const message = err instanceof Error ? err.message : "Internal error";
478
579
  return new Response(message, { status: 500 });
479
580
  }
@@ -694,6 +795,11 @@ export {
694
795
  extractParams,
695
796
  generateManifestSource,
696
797
  writeManifest,
798
+ DEFAULT_MAX_BODY_SIZE,
799
+ RequestBodyTooLargeError,
800
+ enforceRequestBodySize,
801
+ originFromHeader,
802
+ requestOrigin,
697
803
  verifyOrigin,
698
804
  generateCsrfToken,
699
805
  verifyCsrfToken,
@@ -0,0 +1,170 @@
1
+ // src/observability/redact.ts
2
+ var REDACTED = "[REDACTED]";
3
+ var SENSITIVE_KEY_RE = /(password|passwd|token|secret|authorization|cookie|session|credential|api[_ -]?key|private[_ -]?key|access[_ -]?key|refresh[_ -]?token|bearer)/i;
4
+ function isSensitiveKey(key) {
5
+ return SENSITIVE_KEY_RE.test(key);
6
+ }
7
+ function redactString(input) {
8
+ return input.replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=:-]+/gi, "$1 " + REDACTED).replace(/\b(authorization|auth)\s*[:=]\s*[^\s,;]+/gi, "$1 " + REDACTED).replace(/(\b[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/\s@:]*:)([^/\s]*)(@)/g, `$1${REDACTED}$3`);
9
+ }
10
+ function redactValue(value, depth = 0) {
11
+ if (typeof value === "string") return redactString(value);
12
+ if (depth > 10) return value;
13
+ if (Array.isArray(value)) return value.map((v) => redactValue(v, depth + 1));
14
+ if (value !== null && typeof value === "object") {
15
+ const out = {};
16
+ for (const [key, val] of Object.entries(value)) {
17
+ out[key] = isSensitiveKey(key) ? REDACTED : redactValue(val, depth + 1);
18
+ }
19
+ return out;
20
+ }
21
+ return value;
22
+ }
23
+
24
+ // src/observability/tracing.ts
25
+ var noopSpan = {
26
+ setAttribute: () => {
27
+ },
28
+ recordException: () => {
29
+ },
30
+ setStatus: () => {
31
+ },
32
+ end: () => {
33
+ }
34
+ };
35
+ var noopTracer = {
36
+ startSpan: () => noopSpan
37
+ };
38
+ var activeTracer = noopTracer;
39
+ function setTracer(tracer) {
40
+ activeTracer = tracer;
41
+ }
42
+ function getTracer() {
43
+ return activeTracer;
44
+ }
45
+ var OTEL_ERROR_STATUS_CODE = 2;
46
+ var requestStorage = null;
47
+ function asyncLocalStorage() {
48
+ if (requestStorage) return requestStorage;
49
+ try {
50
+ const { AsyncLocalStorage } = import.meta.require("node:async_hooks");
51
+ requestStorage = new AsyncLocalStorage();
52
+ } catch {
53
+ requestStorage = {
54
+ getStore: () => void 0,
55
+ run: (_ctx, fn) => fn()
56
+ };
57
+ }
58
+ return requestStorage;
59
+ }
60
+ async function runWithRequestSpan(requestId, initAttributes, work) {
61
+ const root = activeTracer.startSpan("x.http", {
62
+ attributes: { "x.requestId": requestId, ...initAttributes }
63
+ });
64
+ const storage = asyncLocalStorage();
65
+ return storage.run({ requestId }, async () => {
66
+ try {
67
+ const value = await work(
68
+ (attributes) => {
69
+ if (attributes) {
70
+ for (const [key, item] of Object.entries(attributes)) {
71
+ root.setAttribute(key, item);
72
+ }
73
+ }
74
+ },
75
+ (error) => recordError(root, error)
76
+ );
77
+ root.end();
78
+ return value;
79
+ } catch (error) {
80
+ recordError(root, error);
81
+ root.end();
82
+ throw error;
83
+ }
84
+ });
85
+ }
86
+ function recordError(span, error) {
87
+ span.recordException(error);
88
+ span.setStatus({
89
+ code: OTEL_ERROR_STATUS_CODE,
90
+ message: error instanceof Error ? error.message : String(error)
91
+ });
92
+ }
93
+ async function tracePhase(name, attributes, work) {
94
+ const context = asyncLocalStorage().getStore();
95
+ if (!context) return work();
96
+ const span = activeTracer.startSpan(name, {
97
+ attributes: { "x.requestId": context.requestId, ...attributes }
98
+ });
99
+ try {
100
+ return await work();
101
+ } catch (error) {
102
+ recordError(span, error);
103
+ throw error;
104
+ } finally {
105
+ span.end();
106
+ }
107
+ }
108
+ function tracePhaseSync(name, attributes, work) {
109
+ const context = asyncLocalStorage().getStore();
110
+ if (!context) return work();
111
+ const span = activeTracer.startSpan(name, {
112
+ attributes: { "x.requestId": context.requestId, ...attributes }
113
+ });
114
+ try {
115
+ return work();
116
+ } catch (error) {
117
+ recordError(span, error);
118
+ throw error;
119
+ } finally {
120
+ span.end();
121
+ }
122
+ }
123
+ function maskSqlLiterals(statement) {
124
+ return statement.replace(/'(?:[^']|'')*'/g, "'?'").replace(/"(?:[^"]|"")*"/g, '"?"');
125
+ }
126
+ function dbTraceAttributes(system, statement) {
127
+ const keyword = /^\s*(\w+)/.exec(statement)?.[1]?.toLowerCase();
128
+ return {
129
+ "db.system": system,
130
+ "db.operation": keyword ?? "other",
131
+ "db.statement": maskSqlLiterals(redactString(statement)).trim().slice(0, 512)
132
+ };
133
+ }
134
+ var requestIds = /* @__PURE__ */ new WeakMap();
135
+ function traceRequestId(req) {
136
+ return requestIds.get(req) ?? req.headers.get("x-request-id") ?? crypto.randomUUID();
137
+ }
138
+ function withRequestTracing(handler) {
139
+ return async (req, server) => {
140
+ const existing = req.headers.get("x-request-id");
141
+ const requestId = existing ?? crypto.randomUUID();
142
+ if (!existing) requestIds.set(req, requestId);
143
+ const url = new URL(req.url);
144
+ return runWithRequestSpan(
145
+ requestId,
146
+ { route: url.pathname, method: req.method },
147
+ async (finish) => {
148
+ const res = await handler(req, server);
149
+ finish({ "http.response.status_code": res.status });
150
+ return res;
151
+ }
152
+ );
153
+ };
154
+ }
155
+
156
+ export {
157
+ REDACTED,
158
+ isSensitiveKey,
159
+ redactString,
160
+ redactValue,
161
+ setTracer,
162
+ getTracer,
163
+ OTEL_ERROR_STATUS_CODE,
164
+ runWithRequestSpan,
165
+ tracePhase,
166
+ tracePhaseSync,
167
+ dbTraceAttributes,
168
+ traceRequestId,
169
+ withRequestTracing
170
+ };
package/dist/data.d.ts CHANGED
@@ -1,6 +1,5 @@
1
1
  import { Database } from 'bun:sqlite';
2
2
 
3
- /** A Postgres client scoped to a single transaction (auto-commit/rollback). */
4
3
  interface PostgresTransactionClient {
5
4
  unsafe(query: string, params?: unknown[]): Promise<unknown>;
6
5
  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown>;
package/dist/data.js CHANGED
@@ -1,3 +1,9 @@
1
+ import {
2
+ dbTraceAttributes,
3
+ tracePhase,
4
+ tracePhaseSync
5
+ } from "./chunk-VIXLBKMC.js";
6
+
1
7
  // src/data/migrate.ts
2
8
  import { readdirSync, readFileSync } from "fs";
3
9
  import { join } from "path";
@@ -39,13 +45,8 @@ function runSQLiteMigrations(db, migrationsDir) {
39
45
  }
40
46
  return result;
41
47
  }
48
+ var MIGRATION_LOCK_KEY = 791975531451977;
42
49
  async function runPostgresMigrations(client, migrationsDir) {
43
- await client.unsafe(`CREATE TABLE IF NOT EXISTS _x_migrations (
44
- name TEXT PRIMARY KEY,
45
- applied_at TIMESTAMP DEFAULT NOW()
46
- )`);
47
- const rows = await client.unsafe("SELECT name FROM _x_migrations");
48
- const applied = new Set(rows.map((r) => r.name));
49
50
  let files;
50
51
  try {
51
52
  files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql")).sort(compareMigrationNames);
@@ -53,19 +54,41 @@ async function runPostgresMigrations(client, migrationsDir) {
53
54
  return { applied: [], skipped: [] };
54
55
  }
55
56
  const result = { applied: [], skipped: [] };
56
- for (const file of files) {
57
- if (applied.has(file)) {
58
- result.skipped.push(file);
59
- continue;
57
+ let failed = null;
58
+ await client.begin(async (tx) => {
59
+ await tx.unsafe("SELECT pg_advisory_xact_lock($1)", [MIGRATION_LOCK_KEY]);
60
+ await tx.unsafe(`CREATE TABLE IF NOT EXISTS _x_migrations (
61
+ name TEXT PRIMARY KEY,
62
+ applied_at TIMESTAMP DEFAULT NOW()
63
+ )`);
64
+ const rows = await tx.unsafe("SELECT name FROM _x_migrations");
65
+ const applied = new Set(rows.map((r) => r.name));
66
+ let seq = 0;
67
+ for (const file of files) {
68
+ if (applied.has(file)) {
69
+ result.skipped.push(file);
70
+ continue;
71
+ }
72
+ if (failed !== null) break;
73
+ const raw = readFileSync(join(migrationsDir, file), "utf-8");
74
+ const savepoint = `x_migration_${seq++}`;
75
+ await tx.unsafe(`SAVEPOINT ${savepoint}`);
76
+ try {
77
+ await tx.unsafe(raw);
78
+ await tx.unsafe("INSERT INTO _x_migrations (name) VALUES ($1)", [file]);
79
+ await tx.unsafe(`RELEASE SAVEPOINT ${savepoint}`);
80
+ console.log(`[x] migration applied: ${file}`);
81
+ result.applied.push(file);
82
+ } catch (err) {
83
+ await tx.unsafe(`ROLLBACK TO SAVEPOINT ${savepoint}`).catch(() => {
84
+ });
85
+ await tx.unsafe(`RELEASE SAVEPOINT ${savepoint}`).catch(() => {
86
+ });
87
+ failed = err;
88
+ }
60
89
  }
61
- const raw = readFileSync(join(migrationsDir, file), "utf-8");
62
- await client.begin(async (tx) => {
63
- await tx.unsafe(raw);
64
- await tx.unsafe("INSERT INTO _x_migrations (name) VALUES ($1)", [file]);
65
- });
66
- console.log(`[x] migration applied: ${file}`);
67
- result.applied.push(file);
68
- }
90
+ });
91
+ if (failed !== null) throw failed;
69
92
  return result;
70
93
  }
71
94
 
@@ -137,7 +160,13 @@ function connectPostgres(options = {}) {
137
160
  return new Proxy(sql, {
138
161
  get(target, prop, receiver) {
139
162
  if (prop === "unsafe") {
140
- return (query, params) => run(() => client.unsafe(query, params));
163
+ return (query, params) => run(
164
+ () => tracePhase(
165
+ "x.db",
166
+ dbTraceAttributes("postgres", query),
167
+ () => client.unsafe(query, params)
168
+ )
169
+ );
141
170
  }
142
171
  if (prop === "begin") {
143
172
  return (fn) => run(() => client.begin(async (tx) => fn(tx)));
@@ -147,7 +176,14 @@ function connectPostgres(options = {}) {
147
176
  },
148
177
  apply(_target, _thisArg, args) {
149
178
  const [strings, ...values] = args;
150
- return run(() => client(strings, ...values));
179
+ const statement = strings.join("?");
180
+ return run(
181
+ () => tracePhase(
182
+ "x.db",
183
+ dbTraceAttributes("postgres", statement),
184
+ () => client(strings, ...values)
185
+ )
186
+ );
151
187
  }
152
188
  });
153
189
  }
@@ -163,6 +199,38 @@ function loadBunSQLite() {
163
199
  );
164
200
  }
165
201
  }
202
+ function traceSQLite(db) {
203
+ return new Proxy(db, {
204
+ get(target, prop, receiver) {
205
+ const value = Reflect.get(target, prop, receiver);
206
+ if (typeof value !== "function") return value;
207
+ if (prop === "query") {
208
+ return (sql) => traceStatement(value.call(target, sql), sql);
209
+ }
210
+ if (prop === "run" || prop === "execute") {
211
+ return (...args) => tracePhaseSync(
212
+ "x.db",
213
+ dbTraceAttributes("sqlite", String(args[0] ?? "")),
214
+ () => value.apply(target, args)
215
+ );
216
+ }
217
+ return value.bind(target);
218
+ }
219
+ });
220
+ }
221
+ function traceStatement(statement, sql) {
222
+ if (statement === null || typeof statement !== "object") return statement;
223
+ return new Proxy(statement, {
224
+ get(target, prop, receiver) {
225
+ const value = Reflect.get(target, prop, receiver);
226
+ if (typeof value !== "function") return value;
227
+ if (prop === "all" || prop === "get" || prop === "run" || prop === "values") {
228
+ return (...args) => tracePhaseSync("x.db", dbTraceAttributes("sqlite", sql), () => value.apply(target, args));
229
+ }
230
+ return value.bind(target);
231
+ }
232
+ });
233
+ }
166
234
  function connectSQLite(options) {
167
235
  const { Database: DB } = loadBunSQLite();
168
236
  const db = new DB(options?.path ?? "data/dev.db");
@@ -172,7 +240,7 @@ function connectSQLite(options) {
172
240
  if (options?.foreignKeys !== false) {
173
241
  db.run("PRAGMA foreign_keys = ON");
174
242
  }
175
- return db;
243
+ return traceSQLite(db);
176
244
  }
177
245
  export {
178
246
  connectPostgres,