Repository navigation
v0.8.0
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/rsis 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
texschema 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
textypes 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
helmetconfig is now applied. In 0.7.x,helmet: { enabled: false }did not disable helmet, andxFrameOptions/contentSecurityPolicywere ignored.X-XSS-Protectionis now0(current OWASP guidance), replacing1; 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.parsewith prototype-pollution stripping. The full stripping pass runs only when the raw text could contain__proto__orconstructor. - Validators: route validators compile once per route instead of once per request.
TexEngine.parseprecomputes a per-field plan, so it no longer rescans rule strings on each call. - Fewer per-request allocations: no object pool, one
closelistener instead of two, noend()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
304check reads request headers first, so ordinary responses skip twohasHeader()calls. - Compression uses Node's async
zlibon 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
activeRequestsnever 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-ResetandRetry-Afternow report when the current window actually ends, not a full window from now. - Compression
Varyheader: compression now appendsAccept-EncodingtoVaryinstead of overwriting it (which droppedVary: Origin). It also skips responses that already haveContent-EncodingorCache-Control: no-transform, and ignores a secondend()call while compressing. - Stale build output in published packages:
exisjsnow emptiesdist/before every build, so removed modules can no longer ship to npm. - Union pre-coercion:
TexEngineno 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 onceon shutdown.DatabaseManagerinstalled its ownSIGINT/SIGTERMhandlers, 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 concurrentdisconnectAll()calls share the first attempt.res.download()threwcontentDisposition is not a functionon every call, because of an API change in thecontent-dispositiondependency. Fixed and covered by tests.- Route params named differently at the same position (
/stock/:idand/stock/:stockId/items) both received the first route's name, leavingparams.stockIdundefined. 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
queryorparams, fields declaredz.number(),z.boolean()orz.date()are converted from strings before validation. Noz.coerceor.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 (404if missing), and the newrootoption confines request-supplied names to one directory. Content goes through aBuffer, a stream, or thedownload()helper, which never touches the filesystem.download()response helper.return download(bufferOrStream, 'report.csv')fromexisjs/responsesends an attachment from a handler. A returnedBufferis now sent as bytes; before, it was JSON-encoded.- Shutdown signal.
app.onShutdown((signal) => ...)andonApplicationShutdown(signal)now receive the signal name. The docs described anonStophook that never existed; they now documentonCloseand the real shutdown order. InferRouteInput<typeof route>/InferRouteOutput<typeof route>exported fromexisjs/routerto 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 anyboundary.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 andtex.envstartup 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 a400describing 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: trueis ignored and a warning explains how to list origins. /docswas unavailable in production even withdocs.enabled: true. The config now decides in every environment; setenabled: process.env.NODE_ENV !== 'production'to hide it.
Testing
createTestContext(exis({...}))never ranonStart(it checked the wrong marker), so providers, interceptors and routes registered there were missing in tests. It also booted the app twice, runningonStartand database connects twice and leaving one instance open.- Tests could run stale code. A leftover
.exis/routes-manifest.jsfrom 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=1allows an empty run).
Developer experience
- One error shape. Every error response now has
{ success: false, statusCode, error: { code, message, details? } }. Validation errors previously haderror: "Bad Request"(a string); it is now{ code: "VALIDATION_ERROR", ... }. The top-levelmessage,validationErrors,errorsanddetailsfields remain for existing clients.HttpErrorresponses and 404s gainedstatusCode; 500s always includeerror.message. - Constructor injection fails loudly. The
tsx/esbuild toolchain does not emit TypeScript type metadata, soconstructor(private users: UsersService)on a controller or@Injectable()class receivedundefined. It now throws an error naming the class and parameter and pointing to@Inject(UsersService). Docs and the scaffold use@Inject. pluginsinexis.config.tswere dropped whenexis({ 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.CronExpressionis exported fromexisjs/decoratorsas well asexisjs/cron.
create-exisjs
- The class-based project did not compile (
CronExpressionimport) 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, sonpm testran nothing. It is nowtests/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) and02-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-bookstorepreviously 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 acrossnode: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 -- --writeregeneratesdocs/BENCHMARKS.md. - Profiling:
npm run bench:profilecaptures 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) andbench:validation(vs Ajv), usingdo_not_optimize()so V8 cannot skip unused results. - Type-checking covers tests and benchmarks:
npm run typecheckchecks package sources, test files andbench/. 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.
texcode 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 skipTexEngine's extra passes. On thebench:validationmicro-benchmark: flat schema 259 → 44 ns (Ajv: 77 ns), nested schema with an array 820 → 91 ns (Ajv: 68 ns;texalso builds the cleaned output object). Wherenew Functionis 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/rspackage, its Rust sources, and the cross-platform N-API build/publish pipeline (CI no longer installs a Rust toolchain).NativeRadixTreeand 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.jsonexport, and aLICENSEfile in each package. prepublishOnlybuilds each package before publishing.- Unused dev dependencies were removed from
exisjs. create-exisjsstarter projects now depend onexisjs@^0.8.0.
Upgrade Guide
npm install exisjs@^0.8.0
npm uninstall @exisjs/rs # if it was listed explicitly- Make sure your servers run Node.js 20 or newer.
- If you set
trustProxyto a number, confirm it equals the number of proxies in front of your app. - Run your API tests. Any new
400responses point at data that 0.7.x accepted but your schema never allowed (see Breaking Change 3). - If you accept uploads with more than 10 files, more than 100 fields, or a total above
bodyLimit, setlimitson those routes. - Replace any direct
@exisjs/rsimports.
Full Changelog: v0.7.14...v0.8.0