0
# Micro
1

2
Micro is a minimalist framework for building asynchronous HTTP microservices in Node.js. It features an ultra-lightweight architecture (~260 lines of code) with built-in support for async/await patterns, JSON parsing utilities, automatic error handling with customizable status codes, and flexible deployment options including TCP, UNIX domain sockets, and Windows named pipes.
3

4
## Package Information
5

6
- **Package Name**: micro
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install micro`
10

11
## Core Imports
12

13
```typescript
14
import { serve, send, sendError, run, buffer, text, json, createError, HttpError } from "micro";
15
import type { IncomingMessage, ServerResponse } from "http";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { serve, send, sendError, run, buffer, text, json, createError, HttpError } = require("micro");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { serve, send, sendError, json } from "micro";
28
import type { IncomingMessage, ServerResponse } from "http";
29
import http from "http";
30

31
// Simple microservice
32
const handler = async (req: IncomingMessage, res: ServerResponse) => {
33
  return "Hello World";
34
};
35

36
// Programmatic usage
37
const server = new http.Server(serve(handler));
38
server.listen(3000);
39

40
// With JSON body parsing
41
const jsonHandler = async (req: IncomingMessage, res: ServerResponse) => {
42
  if (req.method === "POST") {
43
    const data = await json(req);
44
    return { received: data, timestamp: Date.now() };
45
  }
46
  return { message: "Send a POST request with JSON" };
47
};
48
```
49

50
## Architecture
51

52
Micro is built around several key components:
53

54
- **Request Handler System**: Core `serve` function converts async handlers to standard HTTP listeners
55
- **Body Parsing Utilities**: Async functions (`buffer`, `text`, `json`) for parsing request bodies with size limits
56
- **Response Management**: `send` function with automatic content-type detection for different data types
57
- **Error Handling**: Structured error system with HTTP status codes and development/production modes
58
- **CLI Interface**: Binary for running microservices with flexible endpoint configuration
59

60
## Capabilities
61

62
### Core Server Functionality
63

64
Primary server creation and request handling functionality. The heart of Micro's microservice architecture.
65

66
```typescript { .api }
67
function serve(fn: RequestHandler): RequestListener;
68
function run(req: IncomingMessage, res: ServerResponse, fn: RequestHandler): Promise<void>;
69

70
type RequestHandler = (req: IncomingMessage, res: ServerResponse) => unknown;
71
```
72

73
[Server Functionality](./server.md)
74

75
### Body Parsing
76

77
Request body parsing utilities for handling JSON, text, and binary data with size limits and encoding support.
78

79
```typescript { .api }
80
function buffer(req: IncomingMessage, options?: BufferInfo): Promise<Buffer>;
81
function text(req: IncomingMessage, options?: BufferInfo): Promise<string>;
82
function json(req: IncomingMessage, options?: BufferInfo): Promise<unknown>;
83

84
interface BufferInfo {
85
  limit?: string | number | undefined;
86
  encoding?: BufferEncoding;
87
}
88
```
89

90
[Body Parsing](./body-parsing.md)
91

92
### Response Handling
93

94
Response sending utilities with automatic content-type detection and error response management.
95

96
```typescript { .api }
97
function send(res: ServerResponse, code: number, obj?: unknown): void;
98
function sendError(req: IncomingMessage, res: ServerResponse, errorObj: Error | HttpError): void;
99
```
100

101
[Response Handling](./response-handling.md)
102

103
### Error Management
104

105
HTTP error creation and handling with status codes and structured error responses.
106

107
```typescript { .api }
108
class HttpError extends Error {
109
  constructor(message: string);
110
  statusCode?: number;
111
  originalError?: Error;
112
}
113

114
function createError(code: number, message: string, original: Error): HttpError;
115
```
116

117
[Error Management](./error-management.md)
118

119
### Command Line Interface
120

121
CLI binary for running microservices with support for multiple endpoint types and configuration options.
122

123
```bash { .api }
124
micro [options] [entry_point.js]
125

126
Options:
127
  --help                    Show help message
128
  -v, --version            Show version number
129
  -l, --listen <uri>       Specify listen URI (tcp://, unix:, pipe:)
130
```
131

132
[Command Line Interface](./cli.md)