Skip to content

v0.8.0

Choose a tag to compare

@github-actions github-actions released this 10 Oct 06:52
· 25 commits to main since this release

ExisJS Release v0.8.0

Release Date: 2026-10-09
Type: Major Release: Pure TypeScript Core, Performance & Security Hardening
Affected Packages: exisjs, create-exisjs, @exisjs/fetch (all aligned to 0.8.0)
Removed Package: @exisjs/rs


Highlights

  • No more native engine. The Rust N-API package @exisjs/rs is gone. Every subsystem it backed now runs in plain TypeScript. Measured per call, the native bindings were slower than JavaScript for every hot-path job, because copying values across the N-API boundary cost more than the work itself. ExisJS now installs the same way on every OS and CPU architecture, with no platform binaries to download or compile.
  • Faster request pipeline on the Node engine. Framework overhead per request is roughly halved, and CPU time per request is 9–18% lower end to end.
  • A compiled validator. Each tex schema compiles once into a generated JavaScript function, the way Ajv does. A full 3-field parse dropped from an estimated 4.2 µs to about 0.04 µs.
  • Security fixes for cross-request data exposure, upload path traversal, upload memory exhaustion, client IP spoofing with trustProxy: N, and ignored helmet settings.
  • Validator correctness. Several tex types and modifiers were parsed but never enforced before. They are enforced now.

⚠️ Breaking Changes

Read this section before upgrading from 0.7.x. Most apps need no code changes; check each item that applies to you.

1. @exisjs/rs removed

exisjs no longer depends on @exisjs/rs. If your app imported it directly (for example signJwt, verifyJwt or NativeMemoryCache), those imports break. ExisJS does not ship a built-in JWT implementation; use a dedicated library such as jose.

- import { signJwt, verifyJwt } from '@exisjs/rs'
+ import { SignJWT, jwtVerify } from 'jose'

Remove @exisjs/rs from your package.json after upgrading. The exisjs/sanitize API is unchanged.

2. trustProxy: <number> now counts hops like Express

Before, trustProxy: 1 returned the second-to-last X-Forwarded-For entry, which a client can set. That let anyone spoof their IP and get around rate limits and IP filters. trustProxy: N now trusts the N closest hops, counting the socket peer.

X-Forwarded-For (socket = proxy) trustProxy 0.7.x req.ip 0.8.0 req.ip
client, proxy1, proxy2 1 proxy1 proxy2
client, proxy1, proxy2 2 client proxy1
6.6.6.6, 203.0.113.7 (one proxy) 1 6.6.6.6 (spoofed) 203.0.113.7

CDN headers (CF-Connecting-IP, True-Client-IP, X-Real-IP, X-Client-IP) are now honored only with trustProxy: true, since any client can send them. If you run behind N proxies, set trustProxy to N.

3. tex now enforces rules it used to ignore

The native validator parsed these rules but let any value through. Requests that passed in 0.7.x with invalid values in these fields now get 400:

Rule 0.7.x 0.8.0
tex.uuid() / tex.uuid({ version }) Any value accepted RFC 4122 format; version checked when given
tex.cuid() Any value accepted CUID format
tex.creditCard() Any value accepted 12–19 digits and a Luhn checksum
tex.literal(v) Any value accepted Must equal v
tex.union([...]) Parsed as its first member only First matching alternative wins
tex.record(schema) Values not checked Every value validated
tex.email() Must only contain @ local@domain, no whitespace
tex.password({ max }) max ignored max enforced
{ dedupe: true } Ignored Duplicates removed
{ slugify: true } / { collapseWhitespace: true } Ignored Applied

String length limits (min/max) now count characters, not UTF-8 bytes.

4. Multipart uploads have default limits

Unless a route sets its own limits: 10 files, 100 fields, 200 parts, 1 MB per text field, and all files together may not exceed bodyLimit (default 10 MB). Exceeding a limit returns 413. Before, a file over the limit was silently truncated and the combined size was unbounded.

Files saved to disk are now named <field>-<uuid><ext>, not <field>-<timestamp>-<random><ext>. Both parts are sanitized, so a field name like ../../x can no longer escape the upload directory.

5. Security header changes

  • helmet config is now applied. In 0.7.x, helmet: { enabled: false } did not disable helmet, and xFrameOptions / contentSecurityPolicy were ignored.
  • X-XSS-Protection is now 0 (current OWASP guidance), replacing 1; mode=block.
  • CORS with an allow-list, RegExp or function origin now sends Vary: Origin.

6. Client-supplied request IDs are validated

An incoming X-Request-Id / traceparent / X-B3-TraceId is reused only if it is at most 128 characters of A–Z a–z 0–9 . _ : -. Otherwise a fresh req-N ID is generated.

7. Error responses: error is always an object

Validation errors used to return "error": "Bad Request". Every error now returns "error": { "code", "message", "details?" } plus statusCode. Clients that read body.error as a string for validation failures must read body.error.message (or the unchanged top-level message). The validationErrors, errors and details fields are unchanged.

8. Route middleware runs before validation

Middleware listed on a route (and @Use(...)) now runs before body, query and param validation. Middleware that relied on already-validated or coerced values (for example reading req.params.id as a number) should move that logic into the handler or a guard.

9. Undecorated constructor parameters throw

On controllers and @Injectable() classes, a required constructor parameter without @Inject(Token) (or @Optional()) now throws instead of receiving undefined.

10. Test runs with no tests fail

exisjs test exits with an error when no test file matches, and when a test file crashes while loading.

11. Node.js 20 or newer

All packages now declare "engines": { "node": ">=20.0.0" }, and exisjs doctor checks the same minimum.


Performance

All numbers come from the compiled dist on the Node engine (Windows, i5-11400H, Node 26.3), comparing 0.7.14 with 0.8.0.

CPU time per request (lower is better)

Route 0.7.14 default 0.8.0 default 0.7.14 lean¹ 0.8.0 lean¹
GET / (JSON) 32.8 µs 31.8 µs 29.7 µs 27.1 µs
GET /user/:id?x=1 35.2 µs 30.7 µs 31.0 µs 27.4 µs
GET with 2 params 35.1 µs 30.2 µs 31.2 µs 27.1 µs
POST JSON echo 48.5 µs 41.9 µs 45.6 µs 37.2 µs

¹ helmet: false, cors: false

Framework overhead only (in-process, no sockets)

Route 0.7.14 0.8.0
GET / (lean) 1,198 ns 665 ns
GET /user/:id?x (lean) 2,881 ns 1,440 ns
GET / (default) 2,244 ns 1,593 ns
GET /user/:id?x (default) 3,995 ns 2,506 ns

Building blocks

Operation 0.7.14 (native) 0.8.0 (JS)
Route lookup (param route) 2,612 ns 342 ns
JSON body parse 2,617 ns 385 ns
tex 3-field object parse ~4,200 ns² 37 ns
tex nested 6-field object parse — 219 ns

² Estimated: 3,100 ns measured for the native check plus about 1,100 ns of TexEngine pre/post processing.

What changed

  • Router: the JS radix tree is the default. Static routes resolve through an exact-match table built at startup. The shared per-path result cache was removed (see Security).
  • JSON bodies: JSON.parse with prototype-pollution stripping. The full stripping pass runs only when the raw text could contain __proto__ or constructor.
  • Validators: route validators compile once per route instead of once per request. TexEngine.parse precomputes a per-field plan, so it no longer rescans rule strings on each call.
  • Fewer per-request allocations: no object pool, one close listener instead of two, no end() completion callback unless finish hooks exist, lazily created DI cache and abort handler, and no CORS closure per request.
  • Request ID is assigned inline, so an app without middleware runs a single-stage pipeline.
  • Conditional GET: the 304 check reads request headers first, so ordinary responses skip two hasHeader() calls.
  • Compression uses Node's async zlib on the libuv threadpool, so large responses no longer block other requests. Brotli uses quality 4.

Security

Issue Impact in 0.7.x Fix
Pooled request/response objects A handler still awaiting after the client disconnected could read the next user's request Pooling removed; fresh objects per request
Shared route params cache All requests for the same URL shared one mutable params object Cache removed; each match gets a fresh, null-prototype params object
Multipart field name in file path name="../../x" wrote outside the upload directory Names sanitized; resolved path verified inside the destination
Unbounded multipart parsing Memory/disk exhaustion via many or huge files (streamUpload had no limits at all) Default limits; combined size capped by bodyLimit; partial files removed on failure
trustProxy: N off by one Client could spoof req.ip Express hop semantics (see Breaking Changes)
helmet options ignored Security headers could not be configured or disabled Config wired through
Unbounded cache stores @Cacheable and idempotency caches grew without limit Bounded to 50,000 / 10,000 entries
Malformed % escape in a path param Unhandled URIError returned 500 Returns 400 Bad Request
Client request IDs Arbitrary 16 KB values echoed into logs and headers Length and charset validated

Fixed

  • Route errors became 404s in apps without middleware: an error thrown by a handler skipped the error handlers and returned 404 Not Found.
  • Bun active-request leak: the Bun response shim never signalled completion, so activeRequests never reached zero and graceful shutdown waited for its full timeout.
  • streamUpload() resolved too early: it resolved before files had finished writing to disk.
  • Rate-limit reset headers: X-RateLimit-Reset, RateLimit-Reset and Retry-After now report when the current window actually ends, not a full window from now.
  • Compression Vary header: compression now appends Accept-Encoding to Vary instead of overwriting it (which dropped Vary: Origin). It also skips responses that already have Content-Encoding or Cache-Control: no-transform, and ignores a second end() call while compressing.
  • Stale build output in published packages: exisjs now empties dist/ before every build, so removed modules can no longer ship to npm.
  • Union pre-coercion: TexEngine no longer applies number or boolean coercion to union fields before the compiled rule picks an alternative.

Fixes from Production Reports

  • Error: Called end on pool more than once on shutdown. DatabaseManager installed its own SIGINT/SIGTERM handlers, so a registered database was disconnected the moment the signal arrived (while requests were still in flight), and again by the graceful shutdown. Each database is now disconnected exactly once, after requests have drained; repeated or concurrent disconnectAll() calls share the first attempt.
  • res.download() threw contentDisposition is not a function on every call, because of an API change in the content-disposition dependency. Fixed and covered by tests.
  • Route params named differently at the same position (/stock/:id and /stock/:stockId/items) both received the first route's name, leaving params.stockId undefined. Each route now gets the names it declared. Static segments were already preferred over params and wildcards regardless of registration order; tests now pin that down.
  • Zod query/param coercion. For Zod 3 and Zod 4 object schemas used as query or params, fields declared z.number(), z.boolean() or z.date() are converted from strings before validation. No z.coerce or .transform(Number) needed.
  • res.download(string) no longer guesses. It used to read the string as a file if it looked like an existing path and otherwise send it as content, so user-influenced text could cause an arbitrary file to be sent. A string is now always a file path (404 if missing), and the new root option confines request-supplied names to one directory. Content goes through a Buffer, a stream, or the download() helper, which never touches the filesystem.
  • download() response helper. return download(bufferOrStream, 'report.csv') from exisjs/response sends an attachment from a handler. A returned Buffer is now sent as bytes; before, it was JSON-encoded.
  • Shutdown signal. app.onShutdown((signal) => ...) and onApplicationShutdown(signal) now receive the signal name. The docs described an onStop hook that never existed; they now document onClose and the real shutdown order.
  • InferRouteInput<typeof route> / InferRouteOutput<typeof route> exported from exisjs/router to type services from route definitions.

Fixes from the Example and Scaffold Audit

Both example apps and the create-exisjs output were run end to end (type-check, tests, production build, real requests). That exposed the following framework problems, all fixed in this release.

Security and correctness

  • Boundaries were ignored in production builds. After exisjs build + exisjs start, routes were mounted from the build manifest without loading any boundary.ts: guards, auth middleware, CORS rules, headers, timeouts and providers defined in boundaries applied in development only. Manifest routes now go through the same mounting path as development.
  • A boundary that failed to load was skipped silently. The routes beneath it were served without its protection. The failure now propagates and those routes are not mounted.
  • Passwords appeared in production logs. Validation diagnostics logged the received value of every failing field, including password. Credential fields (password, token, secret, authorization, apiKey, card and PIN fields) are now [Redacted] in logs, error responses and tex.env startup errors. The ASCII table is no longer written to production logs.
  • Authentication now runs before validation. Route middleware (including @Use(...)) ran after body/query/param validation, so an unauthenticated request with a bad payload received a 400 describing the expected fields. Order is now: route middleware, upload parsing, validation, handler.
  • CORS no longer emits Access-Control-Allow-Origin: * with credentials. Browsers reject that combination. With a wildcard origin, credentials: true is ignored and a warning explains how to list origins.
  • /docs was unavailable in production even with docs.enabled: true. The config now decides in every environment; set enabled: process.env.NODE_ENV !== 'production' to hide it.

Testing

  • createTestContext(exis({...})) never ran onStart (it checked the wrong marker), so providers, interceptors and routes registered there were missing in tests. It also booted the app twice, running onStart and database connects twice and leaving one instance open.
  • Tests could run stale code. A leftover .exis/routes-manifest.js from an earlier build was loaded in development and test mode. The manifest is now used in production only.
  • A test file that crashed on import was reported as PASS, and a run that matched no test files exited successfully. Both now fail (EXIS_PASS_WITH_NO_TESTS=1 allows an empty run).

Developer experience

  • One error shape. Every error response now has { success: false, statusCode, error: { code, message, details? } }. Validation errors previously had error: "Bad Request" (a string); it is now { code: "VALIDATION_ERROR", ... }. The top-level message, validationErrors, errors and details fields remain for existing clients. HttpError responses and 404s gained statusCode; 500s always include error.message.
  • Constructor injection fails loudly. The tsx/esbuild toolchain does not emit TypeScript type metadata, so constructor(private users: UsersService) on a controller or @Injectable() class received undefined. It now throws an error naming the class and parameter and pointing to @Inject(UsersService). Docs and the scaffold use @Inject.
  • plugins in exis.config.ts were dropped when exis({ plugins }) was also used. The two lists are now combined.
  • HttpError.notFound('Book not found') produced "Book not found not found"; a message already ending in "not found" is used as written.
  • CronExpression is exported from exisjs/decorators as well as exisjs/cron.

create-exisjs

  • The class-based project did not compile (CronExpression import) and its controller's constructor injection did not work.
  • The generated test was written as users.e2e-spec.ts, which the configured pattern (tests/**/*.test.ts) never matched, so npm test ran nothing. It is now tests/users.test.ts.
  • Config no longer pairs a wildcard CORS origin with credentials; lifecycle comments and the database stub now show registerDatabase().

Examples

  • 01-my-app (functional) and 02-bookstore (class-based) were rewritten as small, correct reference apps: validated env, register/login, routes protected by a boundary or @Use, typed handlers, and tests that run against the source. 02-bookstore previously hashed passwords twice, so login could never succeed, and connected/disconnected its database twice.
  • New npm run verify:examples (and a CI job with MongoDB) type-checks, tests, builds and boots each example in production mode, then does the same for freshly scaffolded projects.

Tooling

  • Benchmark suite rewritten (bench/README.md). It now covers four scenarios (static JSON, params + query, JSON echo, body validation) with identical routes across node:http, ExisJS (node and uws), Fastify, Hono and Express. Responses are verified before measuring, every run is warmed up, targets are interleaved across rounds and medians reported, and server CPU per request is recorded. npm run bench -- --write regenerates docs/BENCHMARKS.md.
  • Profiling: npm run bench:profile captures a V8 CPU or heap profile under load and prints the hottest functions grouped by origin.
  • Micro-benchmarks: bench:router (vs find-my-way and Hono) and bench:validation (vs Ajv), using do_not_optimize() so V8 cannot skip unused results.
  • Type-checking covers tests and benchmarks: npm run typecheck checks package sources, test files and bench/. CI now runs lint and typecheck before tests.
  • Router lookups: params are written directly into the result object, static segments are compared without allocating, and unambiguous 404s skip the backtracking search. Param lookups now run level with find-my-way, and static lookups about 5x faster.
  • tex code generation: each schema now compiles to one generated JavaScript function (type checks inlined, nested objects and arrays as nested blocks and loops), the approach Ajv uses. Error paths are built only when validation fails, and fields without defaults, coercion, sanitizers or refinements skip TexEngine's extra passes. On the bench:validation micro-benchmark: flat schema 259 → 44 ns (Ajv: 77 ns), nested schema with an array 820 → 91 ns (Ajv: 68 ns; tex also builds the cleaned output object). Where new Function is blocked (strict CSP, some edge runtimes), the closure-based validator is used automatically. The two implementations are compared against each other on 32,000 randomized inputs in the test suite.

Removed

  • @exisjs/rs package, its Rust sources, and the cross-platform N-API build/publish pipeline (CI no longer installs a Rust toolchain).
  • NativeRadixTree and all native code paths in the router, validator, sanitizers, cookies, ETag, compression, cache, idempotency, rate limiter and IP filter.
  • The "Native Engine" check in exisjs doctor.

Packaging

  • All three published packages are versioned 0.8.0.
  • Standard metadata: homepage, bugs, repository.directory, engines, publishConfig, a ./package.json export, and a LICENSE file in each package.
  • prepublishOnly builds each package before publishing.
  • Unused dev dependencies were removed from exisjs.
  • create-exisjs starter projects now depend on exisjs@^0.8.0.

Upgrade Guide

npm install exisjs@^0.8.0
npm uninstall @exisjs/rs   # if it was listed explicitly
  1. Make sure your servers run Node.js 20 or newer.
  2. If you set trustProxy to a number, confirm it equals the number of proxies in front of your app.
  3. Run your API tests. Any new 400 responses point at data that 0.7.x accepted but your schema never allowed (see Breaking Change 3).
  4. If you accept uploads with more than 10 files, more than 100 fields, or a total above bodyLimit, set limits on those routes.
  5. Replace any direct @exisjs/rs imports.

Full Changelog: v0.7.14...v0.8.0