mikroserve 0.0.1 → 0.0.4

package/README.md

@@ -1,3 +1,180 @@
 # MikroServe
 
-TODO
+**Minimalistic, ready-to-use API, built on Node.js primitives**.
+
+![Build Status](https://github.com/mikaelvesavuori/mikroserve/workflows/main/badge.svg)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+- Native Node.js [http](https://nodejs.org/api/http.html)/[https](https://nodejs.org/api/https.html) implementation, meaning maximum performance
+- [Hono](https://hono.dev)-style API semantics for GET, POST, PATCH, PUT, DELETE operations
+- Supports being exposed over both HTTP and HTTPS
+- Supports custom middlewares
+- Out-of-the-box CORS support
+- Built-in customizable rate limiter
+- Tiny (~3.2kb gzipped)
+- Only a single dependency: [MikroConf](https://github.com/mikaelvesavuori/mikroconf)
+
+## Installation
+
+```bash
+npm install mikroserve -S
+```
+
+## Usage
+
+### Quick Start
+
+A minimum example of a tiny MikroServe API could look like the below.
+
+```typescript
+import { MikroServe, type Context } from 'mikroserve';
+
+// Create an instance of MikroServe using only default values
+const api = new MikroServe();
+
+// Add any routes that should be exposed
+// This will expose a GET route on the root of the API, responding with plain text
+api.get('/', (c: Context) => c.text('Hello world!'));
+
+// Start the server
+api.start();
+
+// The API is ready – go ahead and curl it in your command line of choice
+// curl 0.0.0.0:3000
+// The response should be "Hello world!"
+```
+
+## Bigger example
+
+```typescript
+import { MikroServe } from 'mikroserve';
+
+// Create a new api instance
+const api = new MikroServe({
+  port: 3000,
+  host: '0.0.0.0',
+  useHttps: false,
+  sslCert: '',
+  sslKey: '',
+  sslCa: '',
+  debug: true,
+  rateLimit: {
+    requestsPerMinute: 60,
+    enabled: true
+  },
+  allowedDomains: ['*']
+});
+
+// Define a global middleware for logging
+api.use(async (ctx, next) => {
+  console.log(`Request received: ${ctx.req.method} ${ctx.path}`);
+  const start = Date.now();
+  const response = await next();
+  const duration = Date.now() - start;
+  console.log(`Request completed in ${duration}ms with status ${response.statusCode}`);
+  return response;
+});
+
+// Define a auth middleware
+const requireAuth = async (ctx, next) => {
+  const token = ctx.headers.authorization?.replace('Bearer ', '');
+
+  if (!token) {
+    return ctx.status(401).json({
+      error: 'Unauthorized',
+      message: 'Authentication required'
+    });
+  }
+
+  // Validate token logic would go here
+  // For this example, we'll just check if it's "valid-token"
+  if (token !== 'valid-token') {
+    return ctx.status(401).json({
+      error: 'Unauthorized',
+      message: 'Invalid authentication token'
+    });
+  }
+
+  // Set user on context for downstream handlers
+  ctx.user = { id: '123', name: 'Example User' };
+
+  return next();
+};
+
+// Basic routes
+api.get('/', (c) => c.text('Hello, World!'));
+
+api.get('/json', (c) => c.json({ message: 'This is JSON' }));
+
+// Route with URL parameters
+api.get('/users/:id', (c) => {
+  return c.json({
+    userId: c.params.id,
+    message: `User details for ${c.params.id}`
+  });
+});
+
+// Route with query parameters
+api.get('/search', (c) => {
+  const query = c.query.q || '';
+  const page = Number.parseInt(c.query.page || '1');
+
+  return c.json({
+    query,
+    page,
+    results: [`Result 1 for "${query}"`, `Result 2 for "${query}"`]
+  });
+});
+
+// POST route with body parsing
+api.post('/echo', (c) =>
+  c.json({
+    message: 'Echo response',
+    body: c.body,
+    contentType: c.req.headers['content-type']
+  })
+);
+
+// Route with middleware
+api.get('/protected', requireAuth, (c) => {
+  return c.json({
+    message: 'This is protected content',
+    user: c.user
+  });
+});
+
+// Route with custom status code
+api.get('/not-found', (c) =>
+  c.status(404).json({
+    error: 'Not Found',
+    message: 'This resource was not found'
+  })
+);
+
+// Route with redirection
+api.get('/redirect', (c) => c.redirect('/redirected-to'));
+api.get('/redirected-to', (c) => c.text('You have been redirected'));
+
+// Error handling example
+api.get('/error', () => {
+  throw new Error('This is a test error');
+});
+
+api.start();
+```
+
+## Create self-signed HTTPS certificates
+
+On Mac and Linux, run:
+
+```sh
+openssl req -x509 -newkey rsa:2048 -keyout local-key.pem -out local-cert.pem -days 365 -nodes -subj "/CN=localhost"
+```
+
+Feel free to change the key and cert names as you wish.
+
+## License
+
+MIT. See the `LICENSE` file.

package/lib/MikroServe.d.mts

@@ -1,104 +1,84 @@
 import http from 'node:http';
 import https from 'node:https';
-import { MikroServeConfiguration, Middleware, RouteHandler } from './interfaces/index.mjs';
+import { MikroServeOptions, Middleware, RouteHandler } from './interfaces/index.mjs';
 
 /**
- * MikroServe manages HTTP server operations with routing.
+ * @description MikroServe manages HTTP server operations with routing.
  */
 declare class MikroServe {
-    private config;
     private rateLimiter;
     private router;
-    private useHttps;
-    private sslCert?;
-    private sslKey?;
-    private sslCa?;
-    private debug;
+    private config;
     /**
      * @description Creates a new MikroServe instance.
-     * @param config - Server configuration options
      */
-    constructor(config: MikroServeConfiguration);
+    constructor(options?: MikroServeOptions);
     /**
-     * Register a global middleware
+     * @description Register a global middleware.
      */
     use(middleware: Middleware): this;
     /**
-     * Register a GET route
+     * @description Register a GET route.
      */
     get(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a POST route
+     * @description Register a POST route.
      */
     post(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a PUT route
+     * @description Register a PUT route.
      */
     put(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a DELETE route
+     * @description Register a DELETE route.
      */
     delete(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a PATCH route
+     * @description Register a PATCH route.
      */
     patch(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register an OPTIONS route
+     * @description Register an OPTIONS route.
      */
     options(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Creates an HTTP/HTTPS server, sets up graceful shutdown, and starts listening.
-     * @returns Running HTTP/HTTPS server
+     * @description Creates an HTTP/HTTPS server, sets up graceful shutdown, and starts listening.
      */
     start(): http.Server | https.Server;
     /**
-     * Creates and configures a server instance without starting it.
-     * @returns Configured HTTP or HTTPS server instance
+     * @description Creates and configures a server instance without starting it.
      */
     createServer(): http.Server | https.Server;
     /**
-     * Rate limiting middleware
+     * @description Rate limiting middleware.
      */
     private rateLimitMiddleware;
     /**
-     * Request handler for HTTP and HTTPS servers.
+     * @description Request handler for HTTP and HTTPS servers.
      */
     private requestHandler;
     /**
-     * Writes out a clean log to represent the duration of the request.
+     * @description Writes out a clean log to represent the duration of the request.
      */
     private logDuration;
     /**
-     * Parses the request body based on content type.
-     * @param req - HTTP request object
-     * @returns Promise resolving to the parsed body
-     * @throws Will throw if body cannot be parsed
-     */
-    /**
-     * Parses the request body based on content type.
-     * @param req - HTTP request object
-     * @returns Promise resolving to the parsed body
-     * @throws Will throw if body cannot be parsed
+     * @description Parses the request body based on content type.
      */
     private parseBody;
     /**
-     * CORS middleware
+     * @description CORS middleware.
      */
     private setCorsHeaders;
     /**
-     * Set security headers
+     * @description Set security headers.
      */
     private setSecurityHeaders;
     /**
-     * Sends a response with appropriate headers.
-     * @param res - HTTP response object
-     * @param response - Response data and status code
+     * @description Sends a response with appropriate headers.
      */
     private respond;
     /**
-     * Sets up graceful shutdown handlers for a server.
-     * @param server - The HTTP/HTTPS server to add shutdown handlers to
+     * @description Sets up graceful shutdown handlers for a server.
      */
     setupGracefulShutdown(server: http.Server | https.Server): void;
 }

package/lib/MikroServe.d.ts

@@ -1,104 +1,84 @@
 import http from 'node:http';
 import https from 'node:https';
-import { MikroServeConfiguration, Middleware, RouteHandler } from './interfaces/index.js';
+import { MikroServeOptions, Middleware, RouteHandler } from './interfaces/index.js';
 
 /**
- * MikroServe manages HTTP server operations with routing.
+ * @description MikroServe manages HTTP server operations with routing.
  */
 declare class MikroServe {
-    private config;
     private rateLimiter;
     private router;
-    private useHttps;
-    private sslCert?;
-    private sslKey?;
-    private sslCa?;
-    private debug;
+    private config;
     /**
      * @description Creates a new MikroServe instance.
-     * @param config - Server configuration options
      */
-    constructor(config: MikroServeConfiguration);
+    constructor(options?: MikroServeOptions);
     /**
-     * Register a global middleware
+     * @description Register a global middleware.
      */
     use(middleware: Middleware): this;
     /**
-     * Register a GET route
+     * @description Register a GET route.
      */
     get(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a POST route
+     * @description Register a POST route.
      */
     post(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a PUT route
+     * @description Register a PUT route.
      */
     put(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a DELETE route
+     * @description Register a DELETE route.
      */
     delete(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register a PATCH route
+     * @description Register a PATCH route.
      */
     patch(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Register an OPTIONS route
+     * @description Register an OPTIONS route.
      */
     options(path: string, ...handlers: (RouteHandler | Middleware)[]): this;
     /**
-     * Creates an HTTP/HTTPS server, sets up graceful shutdown, and starts listening.
-     * @returns Running HTTP/HTTPS server
+     * @description Creates an HTTP/HTTPS server, sets up graceful shutdown, and starts listening.
      */
     start(): http.Server | https.Server;
     /**
-     * Creates and configures a server instance without starting it.
-     * @returns Configured HTTP or HTTPS server instance
+     * @description Creates and configures a server instance without starting it.
      */
     createServer(): http.Server | https.Server;
     /**
-     * Rate limiting middleware
+     * @description Rate limiting middleware.
      */
     private rateLimitMiddleware;
     /**
-     * Request handler for HTTP and HTTPS servers.
+     * @description Request handler for HTTP and HTTPS servers.
      */
     private requestHandler;
     /**
-     * Writes out a clean log to represent the duration of the request.
+     * @description Writes out a clean log to represent the duration of the request.
      */
     private logDuration;
     /**
-     * Parses the request body based on content type.
-     * @param req - HTTP request object
-     * @returns Promise resolving to the parsed body
-     * @throws Will throw if body cannot be parsed
-     */
-    /**
-     * Parses the request body based on content type.
-     * @param req - HTTP request object
-     * @returns Promise resolving to the parsed body
-     * @throws Will throw if body cannot be parsed
+     * @description Parses the request body based on content type.
      */
     private parseBody;
     /**
-     * CORS middleware
+     * @description CORS middleware.
      */
     private setCorsHeaders;
     /**
-     * Set security headers
+     * @description Set security headers.
      */
     private setSecurityHeaders;
     /**
-     * Sends a response with appropriate headers.
-     * @param res - HTTP response object
-     * @param response - Response data and status code
+     * @description Sends a response with appropriate headers.
      */
     private respond;
     /**
-     * Sets up graceful shutdown handlers for a server.
-     * @param server - The HTTP/HTTPS server to add shutdown handlers to
+     * @description Sets up graceful shutdown handlers for a server.
      */
     setupGracefulShutdown(server: http.Server | https.Server): void;
 }