hono 4.6.0: Hono

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify hono.Hono in pkg:npm/hono@4.6.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/hono@4.6.0
Demonstrate these symbols/APIs:
  - hono.Hono
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:05edf12f16567a6074cbf05f2a010e9141278b277f31353716f693bc3da59dc9","constraints":{"executionContext":"node"},"contract":["Hono instance handles GET requests and returns JSON response with status code and headers","Hono router extracts path parameters and query parameters from request context","Hono router dispatches POST requests and parses incoming JSON body","Hono middleware executes in onion model modifying context variables and response headers","Hono mounts sub-applications using route method preserving nested path prefixes","Hono handles unhandled exceptions via onError and unmatched routes via notFound"],"goal":"verify hono.Hono in pkg:npm/hono@4.6.0","kind":"HOW","packages":["pkg:npm/hono@4.6.0"],"schemaVersion":1,"symbols":["hono.Hono"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/hono@4.6.0"],"schemaVersion":1,"subject":"pkg:npm/hono@4.6.0","symbols":["hono.Hono"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hono-hono",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hono-hono",
      "version": "1.0.0",
      "dependencies": {
        "hono": "4.6.0"
      }
    },
    "node_modules/hono": {
      "version": "4.6.0",
      "resolved": "https://registry.npmjs.org/hono/-/hono-4.6.0.tgz",
      "integrity": "sha512-2jN7gHRCbfFXpHitg87ZDsComUB+PEm+rf2aDjy6e9SCwgnxkpQBCTKYumWQ4q4D3a+KuSW8VJAHzl4EnqYfeg==",
      "license": "MIT",
      "engines": {
        "node": ">=16.0.0"
      }
    }
  }
}

{
  "name": "sample-hono-hono",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for hono.Hono in pkg:npm/hono@4.6.0",
  "dependencies": {
    "hono": "4.6.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify hono.Hono in pkg:npm/hono@4.6.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/hono@4.6.0"
  ],
  "symbols": [
    "hono.Hono"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

import { Hono } from 'hono';

/**
 * Creates and configures a Hono web application demonstrating core features:
 * route definitions, URL parameters, query strings, JSON payloads, middleware,
 * sub-app mounting, and custom error/notFound handling.
 *
 * @returns {Hono} The configured Hono application.
 */
export function createApp() {
  const app = new Hono();

  // Middleware modifying context and downstream headers
  app.use('*', async (c, next) => {
    c.set('customContextKey', 'context-value-123');
    await next();
    c.header('X-Custom-Middleware', 'hono-processed');
  });

  // GET route with JSON response and custom status/headers
  app.get('/api/hello', (c) => {
    return c.json(
      { message: 'Hello Hono', ctx: c.get('customContextKey') },
      200,
      { 'X-Hello-Response': 'true' }
    );
  });

  // Route parameters and query parameters
  app.get('/api/users/:id', (c) => {
    const id = c.req.param('id');
    const role = c.req.query('role');
    return c.json({ id, role });
  });

  // POST route parsing JSON body
  app.post('/api/items', async (c) => {
    const body = await c.req.json();
    return c.json({ success: true, item: body }, 201);
  });

  // Sub-app mounted via app.route
  const subApp = new Hono();
  subApp.get('/status', (c) => c.json({ subStatus: 'operational' }));
  app.route('/api/sub', subApp);

  // Route that throws an error to test onError
  app.get('/api/error', () => {
    throw new Error('Test server exception');
  });

  // Custom error handler
  app.onError((err, c) => {
    return c.json(
      { error: err.message, handled: true },
      500
    );
  });

  // Custom not found handler
  app.notFound((c) => {
    return c.json(
      { error: 'Resource Not Found', pathname: c.req.path },
      404
    );
  });

  return app;
}

export { Hono };

import assert from 'node:assert/strict';
import { createApp, Hono } from '../src/index.mjs';

// Contract 1: Hono instance handles GET requests and returns JSON response with status code and headers
{
  assert.equal(typeof Hono, 'function', 'Hono must be a constructor');
  const app = createApp();
  assert.ok(app instanceof Hono, 'createApp must return a Hono instance');

  const res = await app.request('http://localhost/api/hello');
  assert.equal(res.status, 200, 'GET /api/hello must return 200');
  assert.equal(res.headers.get('x-hello-response'), 'true');
  assert.equal(res.headers.get('x-custom-middleware'), 'hono-processed');

  const body = await res.json();
  assert.equal(body.message, 'Hello Hono');
  assert.equal(body.ctx, 'context-value-123');
}

// Contract 2: Hono router extracts path parameters and query parameters from request context
{
  const app = createApp();

  const res = await app.request('http://localhost/api/users/user-456?role=editor');
  assert.equal(res.status, 200);

  const body = await res.json();
  assert.equal(body.id, 'user-456');
  assert.equal(body.role, 'editor');
}

// Contract 3: Hono router dispatches POST requests and parses incoming JSON body
{
  const app = createApp();

  const payload = { title: 'Sample Item', count: 10 };
  const res = await app.request('http://localhost/api/items', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });

  assert.equal(res.status, 201, 'POST /api/items must return 201');
  const body = await res.json();
  assert.equal(body.success, true);
  assert.deepEqual(body.item, payload);
}

// Contract 4: Hono middleware executes in onion model modifying context variables and response headers
{
  const app = createApp();

  const res = await app.request('http://localhost/api/hello');
  assert.equal(res.headers.get('x-custom-middleware'), 'hono-processed');
  const body = await res.json();
  assert.equal(body.ctx, 'context-value-123');
}

// Contract 5: Hono mounts sub-applications using route method preserving nested path prefixes
{
  const app = createApp();

  const res = await app.request('http://localhost/api/sub/status');
  assert.equal(res.status, 200);

  const body = await res.json();
  assert.equal(body.subStatus, 'operational');
}

// Contract 6: Hono handles unhandled exceptions via onError and unmatched routes via notFound
{
  const app = createApp();

  // Test custom error handler
  const errorRes = await app.request('http://localhost/api/error');
  assert.equal(errorRes.status, 500);
  const errorBody = await errorRes.json();
  assert.equal(errorBody.error, 'Test server exception');
  assert.equal(errorBody.handled, true);

  // Test custom not found handler
  const notFoundRes = await app.request('http://localhost/api/non-existent-route');
  assert.equal(notFoundRes.status, 404);
  const notFoundBody = await notFoundRes.json();
  assert.equal(notFoundBody.error, 'Resource Not Found');
}

console.log('All contracts for hono.Hono in pkg:npm/hono@4.6.0 passed.');