Micri Microservices Framework

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax within an ES module context (e.g., in a file with `.mjs` extension or when `"type": "module"` is set in `package.json`).
  fix Replace all `const { symbol } = require('micri');` statements with `import { symbol } from 'micri';` for Micri imports in your ES module files.

• TypeError: res.send is not a function

  cause Attempting to use convenience methods like `res.send()` or `res.json()` that are common in frameworks like Express, but are not part of Micri's native `http.ServerResponse` object.
  fix Micri handlers operate directly with native Node.js `http.ServerResponse`. To send data, either return a string, Buffer, or Stream from your handler, or use `res.end()` for direct manipulation. For example, `return 'Hello World';` or `res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ message: 'Hello' })); return;`.

• Error: Request body already consumed

  cause Invoking `buffer(req)`, `text(req)`, or `json(req)` more than once for the same incoming HTTP request stream.
  fix Call body parsing functions only once per request. Store the result in a variable and reuse it throughout your handler to access the parsed body data. For example, `const requestBody = await json(req);`

Warnings

• breaking Micri v4.0.0 dropped support for Node.js 10.x. All projects using Micri v4 and above must run on Node.js 12.0.0 or a newer compatible version.
  Fix: Upgrade your Node.js environment to version 12.0.0 or later. Using an active LTS version (e.g., Node.js 18 or 20) is recommended.
• gotcha Micri is intentionally designed without a middleware system, contrasting with frameworks like Express. All request-specific logic (e.g., authentication, logging, explicit body parsing) must be handled within your core handler functions or by wrapping them.
  Fix: Implement shared logic as utility functions or compose your handlers by wrapping them with higher-order functions to apply common behaviors.
• gotcha Request body parsing (for JSON, URL-encoded forms, text, or binary buffers) is not automatic. Developers must explicitly call `buffer(req)`, `text(req)`, or `json(req)` to consume the incoming request body.
  Fix: Always use the provided `buffer`, `text`, or `json` utility functions and await their results to parse the request body. Ensure you call these functions only once per request to avoid errors.
• gotcha When using Micri's built-in router, the order of routes provided as arguments to the `router()` function determines their priority. The first matching route in the list will handle the request.
  Fix: Arrange your routes from the most specific to the least specific. Consider using `on.otherwise()` as the final route to gracefully handle any requests that do not match preceding rules.

Install

• npm install micri npm
• yarn add micri yarn
• pnpm add micri pnpm

Imports

• serve
  wrong:

  const server = micri(...);

  correct:

  import { serve } from 'micri';

  `serve` is the primary function for creating and starting a programmatic HTTP server with a Micri handler.
• { buffer, text, json }
  wrong:

  import * as bodyParser from 'micri/body';

  correct:

  import { buffer, text, json } from 'micri';

  These utilities are for explicitly parsing incoming request bodies (binary, plain text, or JSON). Micri does not perform automatic body parsing, requiring manual calls to these functions.
• Router
  wrong:

  import router from 'micri/router';

  correct:

  import { Router } from 'micri';

  The `Router` object provides the `router` function and methods for defining routes. It is a named export.
• Router.router
  wrong:

  import { router } from 'micri';

  correct:

  import { Router } from 'micri'; const myRouter = Router.router(...);

  The `router` function is a static method of the `Router` object used to create a router instance. For CommonJS, `const { Router: { router } } = require('micri');` is the common nested destructuring pattern.
• on

  import { on } from 'micri';

  `on` is an object containing methods (e.g., `on.get`, `on.post`) used to define specific HTTP method routes when constructing a `router`.

Quickstart

This quickstart demonstrates creating a basic Micri HTTP server using the `serve` function, handling an asynchronous request, and listening on a specified port. It highlights Micri's `async`/`await` focus for simple handlers.

import { serve } from 'micri';
import { ServerResponse, IncomingMessage, Server } from 'http';

const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));

interface CustomRequest extends IncomingMessage {
  // Micri handlers receive native Node.js http.IncomingMessage
  // You can extend it for custom properties if needed.
}

const handler = async (req: CustomRequest, res: ServerResponse): Promise<string> => {
  // Simulate an asynchronous operation, e.g., database call or external API fetch
  await sleep(500);
  
  // Micri handlers can return a string, Buffer, or Stream directly to send as the response body.
  return `Hello from Micri! You accessed: ${req.url}`;
};

const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3000;
const server: Server = serve(handler);

server.listen(PORT, () => {
  console.log(`Micri server listening on http://localhost:${PORT}`);
  console.log('Try opening http://localhost:3000/hello or http://localhost:3000/world in your browser.');
});