yinzerflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Redact Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,340 @@
+# YinzerJS Documentation
+
+## Overview
+
+YinzJS is a lightweight HTTP server framework built for Node.js, designed with TypeScript in mind. It leverages TypeScript's powerful type system to provide enhanced type safety and autocompletion, making it easier for developers to build robust web applications. With YinzJS, you can enjoy a flexible routing system, middleware support, and a straightforward interface to handle incoming requests and responses—all while benefiting from TypeScript's clear typing and error-checking capabilities. This combination allows for a smoother development experience, reducing runtime errors and improving code maintainability.
+
+```typescript
+import { YinzJS } from '@yinzjs/yinzjs';
+
+export const app = new YinzJS({
+  port: 5000,
+});
+
+app.post('/example-route', (ctx) => {
+  const { body } = ctx.request;
+  return { message: 'Hello, world!' };
+});
+
+app.listen();
+```
+
+Sure! Here’s an expanded version of the installation section for YinzJS, providing more context and options for users:
+
+---
+
+## Installation
+
+To get started with YinzJS, simply install it using your preferred package manager. YinzJS is available via npm, as well as other popular package managers such as Bun, Yarn, and pnpm. Follow the instructions below based on the package manager you are using:
+
+### Using npm
+
+If you are using npm, run the following command in your terminal:
+
+```bash
+npm install @yinzjs/yinzjs
+```
+
+This command will download and install YinzJS along with its dependencies into your project's `node_modules` folder.
+
+### Using Bun
+
+For those who prefer Bun, you can add YinzJS to your project with the following command:
+
+```bash
+bun add @yinzjs/yinzjs
+```
+
+Bun is known for its speed and efficiency, making it a great choice for modern JavaScript development.
+
+### Using Yarn
+
+If you're a Yarn user, you can easily install YinzJS by running:
+
+```bash
+yarn add @yinzjs/yinzjs
+```
+
+Yarn provides a fast and reliable way to manage your project's dependencies.
+
+### Using pnpm
+
+For developers who utilize pnpm, you can install YinzJS with:
+
+```bash
+pnpm add @yinzjs/yinzjs
+```
+
+pnpm is an efficient package manager that saves disk space and speeds up installation times.
+
+## Getting Started
+
+### Importing YinzJS
+
+```typescript
+import { YinzJS } from '@yinzjs/yinzjs';
+```
+
+### Creating an Application Instance
+
+You can create an instance of YinzJS by specifying the desired port:
+
+```typescript
+const app = new YinzJS({ port: 5000 });
+```
+
+### Defining Routes
+
+You can define routes using the `route` method. Each route can have a path, a handler, and optional before and after handlers.
+
+```typescript
+app.get(
+  '/example',
+  ({ request, response }) => {
+    return { message: 'Hello, world!' };
+  },
+  {
+    beforeHandler: ({ request, response }) => {
+      // Logic before the main handler
+    },
+    afterHandler: ({ request, response }) => {
+      // Logic after the main handler
+    },
+  },
+);
+```
+
+**Before handler uses:**
+The before handler is a good place to perform operations such as authentication, validation, or any pre-processing logic before the main handler is executed.
+
+**After handler uses:**
+The after handler can be used for post-processing tasks like logging, modifying the response, or cleaning up resources after the main handler has completed.
+
+### Additional Route Methods and Parameters
+
+YinzJS supports various HTTP methods such as `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`. You can use these methods to define routes for specific HTTP requests.
+
+```typescript
+app.get('/example-route', ({ request, response }) => {
+  // Route handler logic
+});
+app.patch('/example-route', ({ request, response }) => {
+  // Route handler logic
+});
+app.post('/example-route', ({ request, response }) => {
+  // Route handler logic
+});
+app.delete('/example-route', ({ request, response }) => {
+  // Route handler logic
+});
+```
+
+You can also specify route parameters using the `:param` syntax:
+
+```typescript
+app.get('/users/:id', ({ request }) => {
+  const { params } = request;
+  const { id } = params;
+  // Route handler logic
+});
+```
+
+You can also access query parameters from the request:
+
+```typescript
+app.get('/search?location=pittsburgh', ({ request, response }) => {
+  const { query } = request;
+  const { location } = query;
+  // Route handler logic
+});
+```
+
+### Route Groups
+
+You can group routes using the `group` method. This is useful for applying middleware to multiple routes at once or for organizing related routes.
+
+```typescript
+app.group('/api', () => {
+  app.get('/users', ({ request, response }) => {
+    // Route handler logic
+  });
+  app.post('/users', ({ request, response }) => {
+    // Route handler logic
+  });
+});
+```
+
+If needed, you can also apply before handlers to the entire group. This logic will run after the global middleware but before the individual route before handlers
+
+```typescript
+app.group(
+  '/api',
+  {
+    beforeHandler: ({ request, response }) => {
+      // Logic before the group
+    },
+  },
+  () => {
+    app.get('/users', ({ request, response }) => {
+      // Route handler logic
+    });
+  },
+);
+```
+
+### Response Handling
+
+The route handlers, before handlers, and middleware functions can return a response in the form of an object or a string. The headers and status code can be set using the `response` object as well. The return headers and status code will be assumed if they are not specified.
+
+```typescript
+app.get('/example-route', () => {
+  return {
+    success: true,
+    message: 'Hello, world!',
+  };
+});
+```
+
+In this example, the response status is set to `200`, and the response body is an object meaning the response headers will be set to `application/json` by default.
+
+```typescript
+app.post('/example-route', ({ response }) => {
+  response.setStatus(201);
+  return 'Hello, world!';
+});
+```
+
+There for more strict control over the response, you can use the `TResponseBody` type parameter to specify the response body type:
+
+```typescript
+app.get('/example-route', (): TResponseBody<{ success: boolean; message: string }> => {
+  return {
+    success: true,
+    message: 'Hello, world!',
+  };
+});
+```
+
+In this example, the response status is set to `201`, and the response body is a string. The response headers are set to `text/plain` by default in this case.
+
+### Changing or Adding Headers
+
+You can also add or remove headers using the `response` object:
+
+```typescript
+app.get('/example-route', ({ response }) => {
+  response.addHeaders(['Content-Type: application/json']);
+  response.removeHeaders(['X-Auth-Token']);
+  return { success: true, message: 'Hello, world!' };
+});
+```
+
+### Route Validation (Coming Soon)
+
+You can validate routes using the `validate` method. This method takes a schema object and validates the request body, query parameters, or route parameters against it.
+
+```typescript
+app.post(
+  '/example-route',
+  ({ request }) => {
+    const { body } = request;
+    const { name, age } = body;
+    // Route handler logic
+  },
+  {
+    validate: {
+      body: {
+        email: { type: 'email', required: true },
+        name: { type: 'string', required: true },
+        dateOfBirth: { type: 'date' },
+        age: { type: 'number', min: 18 },
+      },
+    },
+  },
+);
+```
+
+### Middleware
+
+YinzJS supports middleware that can be applied globally or to specific routes. Middleware can manipulate the request and also return a response. This is useful for tasks such as authentication and throttling.
+
+#### Global Middleware
+
+To apply middleware before all routes:
+
+```typescript
+app.beforeAll(({ request, response }) => {
+  // middleware logic
+});
+```
+
+To apply middleware to specific routes:
+
+```typescript
+app.beforeAll(
+  ({ request, response }) => {
+    // middleware logic
+  },
+  {
+    paths: ['/user/:id'],
+    excluded: [],
+  },
+);
+```
+
+To apply middleware to all routes except specific ones:
+
+```typescript
+app.beforeAll(
+  ({ request, response }) => {
+    // middleware logic
+  },
+  {
+    paths: 'allButExcluded',
+    excluded: ['/login', '/register'],
+  },
+);
+```
+
+#### Include Middleware
+
+To apply middleware to specific routes:
+
+```typescript
+app.use({ paths: ['/route1', '/route2'] }, (ctx) => {
+  // Middleware logic
+});
+```
+
+### Starting the Server
+
+To start the server, call the `listen` method:
+
+```typescript
+app.listen();
+```
+
+## Request Handling Flow
+
+The request handling process follows this sequence:
+
+1. Incoming request
+2. Route validation
+3. Global middleware
+4. Before group middleware
+5. Before route middleware
+6. Route handler
+7. After route middleware
+8. Response sent
+
+## Examples
+
+Refer to the examples folder in the YinzJS repository for more detailed usage examples.
+
+## Conclusion
+
+YinzJS provides a straightforward way to build HTTP servers in Node.js, with support for routing and middleware. For more advanced features, consider extending the framework or integrating with other libraries.
+
+---
+
+Feel free to modify or expand upon this documentation as needed! If you have specific sections or features you'd like to elaborate on, let me know!

package/index.d.ts

@@ -0,0 +1,244 @@
+export declare const HttpMethod: {
+	readonly DELETE: "DELETE";
+	readonly GET: "GET";
+	readonly POST: "POST";
+	readonly PUT: "PUT";
+	readonly PATCH: "PATCH";
+	readonly HEAD: "HEAD";
+	readonly OPTIONS: "OPTIONS";
+};
+export type THttpMethod = Enum<typeof HttpMethod>;
+export interface IRequest {
+	protocol: string;
+	method: THttpMethod;
+	path: string;
+	headers: Array<Record<string, string>>;
+	body?: string;
+}
+export declare class HttpRequest {
+	readonly protocol: IRequest["protocol"];
+	readonly method: IRequest["method"];
+	readonly path: IRequest["path"];
+	readonly headers: IRequest["headers"];
+	readonly body: IRequest["body"];
+	constructor(request: string);
+	private _parseRequest;
+	private _divideStringOn;
+}
+declare const HttpStatus: {
+	readonly OK: "OK";
+	readonly CREATED: "Created";
+	readonly NO_CONTENT: "No Content";
+	readonly BAD_REQUEST: "Bad Request";
+	readonly UNAUTHORIZED: "Unauthorized";
+	readonly FORBIDDEN: "Forbidden";
+	readonly NOT_FOUND: "Not Found";
+	readonly METHOD_NOT_ALLOWED: "Method Not Allowed";
+	readonly TOO_MANY_REQUESTS: "Too Many Requests";
+	readonly INTERNAL_SERVER_ERROR: "Internal Server Error";
+};
+export type THttpStatus = Enum<typeof HttpStatus>;
+export declare const HttpStatusCode: {
+	readonly OK: 200;
+	readonly CREATED: 201;
+	readonly NO_CONTENT: 204;
+	readonly BAD_REQUEST: 400;
+	readonly UNAUTHORIZED: 401;
+	readonly FORBIDDEN: 403;
+	readonly NOT_FOUND: 404;
+	readonly METHOD_NOT_ALLOWED: 405;
+	readonly TOO_MANY_REQUESTS: 429;
+	readonly INTERNAL_SERVER_ERROR: 500;
+};
+export type THttpStatusCode = Enum<typeof HttpStatusCode>;
+export interface IHeaders {
+	Authorization?: string;
+	Proxy_Authorization?: string;
+	"WWW-Authenticate"?: string;
+	Age?: string;
+	"Cache-Control"?: string;
+	"Clear-Site-Data"?: string;
+	Expires?: string;
+	"No-Vary-Search"?: string;
+	"Last-Modified"?: string;
+	ETag?: string;
+	"If-Match"?: string;
+	"If-None-Match"?: string;
+	"If-Modified-Since"?: string;
+	"If-Unmodified-Since"?: string;
+	Vary?: string;
+	Connection?: string;
+	"Keep-Alive"?: string;
+	Accept?: string;
+	"Accept-Encoding"?: string;
+	"Accept-Language"?: string;
+	Expect?: string;
+	"Max-Forwards"?: string;
+	Cookie?: string;
+	"Set-Cookie"?: string;
+	"Access-Control-Allow-Credentials"?: string;
+	"Access-Control-Allow-Methods"?: string;
+	"Access-Control-Allow-Headers"?: string;
+	"Access-Control-Allow-Origin"?: string;
+	"Access-Control-Expose-Headers"?: string;
+	"Access-Control-Max-Age"?: string;
+	"Access-Control-Request-Headers"?: string;
+	"Access-Control-Request-Method"?: string;
+	Origin?: string;
+	"Timing-Allow-Origin"?: string;
+	"Content-Disposition"?: string;
+	"Content-Length"?: string;
+	"Content-Type"?: string | "application/json" | "text/html" | "text/plain";
+	"Content-Encoding"?: string;
+	"Content-Language"?: string;
+	"Content-Location"?: string;
+	Forwarded?: string;
+	Via?: string;
+	Location?: string;
+	Refresh?: string;
+	From?: string;
+	Host?: string;
+	Referer?: string;
+	"Referrer-Policy"?: string;
+	"User-Agent"?: string;
+	Allow?: string;
+	Server?: string;
+	Range?: string;
+	"Accept-Ranges"?: string;
+	"Content-Range"?: string;
+	"If-Range"?: string;
+	"Cross-Origin-Embedder-Policy"?: string;
+	"Cross-Origin-Opener-Policy"?: string;
+	"Cross-Origin-Resource-Policy"?: string;
+	"Content-Security-Policy"?: string;
+	"Content-Security-Policy-Report-Only"?: string;
+	"Permissions-Policy"?: string;
+	"Strict-Transport-Security"?: string;
+	"Upgrade-Insecure-Requests"?: string;
+	"X-Content-Type-Options"?: string;
+	"X-Frames-Options"?: string;
+	"X-Permitted-Cross-Domain-Policies"?: string;
+	"X-Powered-By"?: string;
+	"X-XSS-Protection"?: string;
+	"Report-To"?: string;
+	TE?: string;
+	Trailer?: string;
+	"Transfer-Encoding"?: string;
+	"Alt-Svc"?: string;
+	"Alt-Used"?: string;
+	Date?: string;
+	Link?: string;
+	"Retry-After"?: string;
+	"Server-Timing"?: string;
+	"Service-Worker-Allowed"?: string;
+	SourceMap?: string;
+	Upgrade?: string;
+	Priority?: string;
+	"Sec-GPC"?: string;
+}
+export type TResponseBody<T> = T;
+export interface IResponse {
+	status: THttpStatus;
+	statusCode: THttpStatusCode;
+	protocol: string;
+	method: THttpMethod;
+	path: string;
+	headers: IHeaders;
+	body: TResponseBody<unknown>;
+}
+export declare class HttpResponse {
+	protected readonly protocol: IResponse["protocol"];
+	protected readonly method: IResponse["method"];
+	protected readonly path: IResponse["path"];
+	protected status: IResponse["status"];
+	protected statusCode: IResponse["statusCode"];
+	protected headers: IResponse["headers"];
+	protected body: IResponse["body"];
+	constructor(request: HttpRequest);
+	addHeaders(headers: Array<IResponse["headers"]>): void;
+	removeHeaders(headers: Array<keyof IHeaders>): void;
+	setStatus(status: THttpStatusCode): void;
+	setBody(body: TResponseBody<unknown>): void;
+	formatHttpResponse(): string;
+}
+export declare class Context {
+	request: HttpRequest;
+	response: HttpResponse;
+	constructor(request: HttpRequest, response: HttpResponse);
+}
+export type Enum<T> = T[keyof T];
+export type TResponseFunction = (ctx: Context) => TResponseBody<unknown>;
+export type TUndefinableResponseFunction = TResponseFunction | undefined;
+export interface IRoute {
+	path: string;
+	method: THttpMethod;
+	handler: TResponseFunction;
+	beforeHandler?: TResponseFunction | TUndefinableResponseFunction | undefined;
+	afterHandler?: TUndefinableResponseFunction | undefined;
+	beforeGroup?: TResponseFunction | TUndefinableResponseFunction | undefined;
+}
+export interface IMiddleware {
+	fn: TResponseFunction | ((ctx: Context) => void);
+}
+export interface IExcludeMiddleware extends IMiddleware {
+	paths: "allButExcluded";
+	excluded: Array<string>;
+}
+export interface IIncludeMiddleware extends IMiddleware {
+	paths: Array<string>;
+	excluded: [
+	];
+}
+export type TMiddleware = IExcludeMiddleware | IIncludeMiddleware;
+export export declare class YinzJS {
+	private readonly backlog;
+	private readonly ip;
+	private readonly port;
+	private readonly _routes;
+	private readonly middleware;
+	constructor(options?: {
+		port: number;
+	});
+	protected _handleMiddleware(route: IRoute, ctx: Context): TResponseBody<unknown> | void;
+	protected _handleRoute(route: IRoute, ctx: Context): TResponseBody<unknown>;
+	protected _handleRequest(request: HttpRequest): HttpResponse;
+	protected _route(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		method: IRoute["method"];
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	get(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	post(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	put(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	delete(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	patch(path: IRoute["path"], handler: IRoute["handler"], options?: {
+		beforeHandler?: IRoute["beforeHandler"];
+		afterHandler?: IRoute["afterHandler"];
+	}): IRoute;
+	group(prefix: IRoute["path"], routes: Array<IRoute>, options?: {
+		beforeGroup: IRoute["beforeGroup"];
+	}): void;
+	routes(routes: Array<IRoute>): void;
+	beforeAll(fn: TMiddleware["fn"], options?: {
+		paths: IExcludeMiddleware["paths"];
+		excluded: IExcludeMiddleware["excluded"];
+	} | {
+		paths: IIncludeMiddleware["paths"];
+		excluded: IIncludeMiddleware["excluded"];
+	}): void;
+	listen(): void;
+}
+
+export {};