Achieve — High Level Logic Project. Creating a new meta design pattern.

Friendly in development. Fast in production. Just build your apps. Let Achieve do the rest.

← Back to technical specifications

Achieve JavaScript Servlet Lifecycle

Created November 6, 2026 · Updated November 6, 2026 · Achieve 3.1.0 · Qualified runtime: Node.js 24.22.2

Achieve invokes an exported servlet(session) function when routing selects a JavaScript Servlet. The lifecycle connects module loading, request state, returned values, asynchronous settlement, response completion, diagnostics, and development reloading without requiring an additional HTTP framework.

Discovery and loading

CommonJS servlets use .jss or .jss.cjs; ECMAScript modules use .jss.mjs. These markers identify executable backend resources that are invoked rather than served as source. The module must export a function named servlet.

export async function servlet(session) {
  const result = await findResult(session.params);
  return JSON.stringify(result);
}

In development mode, Achieve checks servlet and session.load() module changes and reloads changed code. In production mode, modules and resolution results are cached for repeated use until the process restarts.

The session boundary

The session supplies parsed params, the original Node request and response, appPath, the current servlet dirPath, and load() for backend modules. GET query parameters and supported POST form or JSON data are made available through params; other input remains on the request stream.

session.load() resolves a backend module relative to the current servlet directory. CommonJS loading returns the module synchronously; ESM loading returns a Promise and is awaited.

Managed completion

With the default session.autoEnd = true, Achieve inspects the returned value. A direct value becomes response content. A Promise or thenable is awaited and its resolved value follows the same rules. If the result is null or undefined while the status remains 200, Achieve selects 204; an empty string remains a valid response body.

For HEAD, Achieve runs the same servlet but suppresses content. Status-specific rules such as 204 and 205 are enforced at the managed response boundary. If the application has already completed or destroyed the response, Achieve does not attempt a second completion.

Application-owned completion

Set session.autoEnd = false only when application code will complete the response itself:

exports.servlet = function(session) {
  session.autoEnd = false;
  session.response.write("Hello ");
  session.response.end("World!");
};

Achieve then does not inspect the returned value or Promise for normal completion. Ordinary async/await does not require this setting; returning the Promise is the simpler managed form.

Errors and diagnostics

Achieve catches synchronous load or invocation errors and rejection of the returned Promise. Before headers are sent, it can generate its managed 500 response and record the server-side diagnostic. After headers are sent, it reports the error and terminates an incomplete response rather than attempting to replace it with a new 500. Detached asynchronous errors that occur after the servlet contract has ended are the application's responsibility.

Verification and limits

Servlet, module, startup-error, Promise, response-completion, request-input, and logging suites cover CommonJS and ESM loading, exports, reload and caching behavior, direct and asynchronous results, empty results, application-owned responses, HEAD, status-specific suppression, errors before and after headers, and subsequent request health across all four transports.

Achieve manages servlet errors; it is not a process sandbox. Servlet code and npm modules execute with the Node.js process's permissions. When autoEnd is false, eventual successful completion and detached asynchronous work remain application responsibilities.

See JavaScript Servlets and the Servlet Session Object.