@asenajs/asena 0.1.17 → 0.1.19

package/README.md

@@ -3,6 +3,10 @@
 Asena is a NestJS-like IoC web framework built on top of Hono and Bun. It combines the power of dependency injection
 with the performance of Bun runtime and the flexibility of Hono web framework.
 
+## Documentation
+
+For detailed documentation, please visit [not ready yet](https://asena.sh). Documentation is still in progress, but updates are being made regularly.
+
 ## Key Features
 
 - **Dependency Injection**: Built-in IoC container for managing dependencies
@@ -14,97 +18,227 @@ with the performance of Bun runtime and the flexibility of Hono web framework.
 
 ## Quick Start
 
-First, install the required packages:
+First, create a new project using Bun:
 
 ```bash
+bun init
+```
 
-bun add @asenajs/asena @asenajs/asena-cli hono winston
+For decorators working properly, you need to add some settings to your tsconfig. Here is an recommended file:
+
+```json
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": false,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true
+  }
+}
 ```
 
-Then, create a new project using the CLI:
+Then, install the required packages:
 
 ```bash
 
-## Creates a .asenarc.json file with default values (requires manual updates). Source folder is 'src'.
-asena-cli init
+bun add @asenajs/asena hono winston
 ```
 
+Add @asenajs/asena-cli to your package. This package provides a CLI for creating and managing Asena projects.
+
+```bash
+bun add -D @asenajs/asena-cli
+```
+
+Then, create a new asena-config.ts file using the CLI:
+
+```bash
+
+## Creates a asena-config.ts file with default values (requires manual updates). Source folder is 'src'.
+asena init
+```
+
+`Note`: Built options directly copy of bun options, you can check bun documentation for more
+options. [Bun Documentation](https://bun.sh/docs/bundler#reference)
+
 Create index.ts file under your src folder:
 
 ```typescript
-import {AsenaServer} from '@asenajs/asena';
-import {DefaultLogger} from '@asenajs/asena/lib/services';
+// src/index.ts
+const [adapter, serverLogger] = createHonoAdapter(new DefaultLogger());
+await new AsenaServer(adapter, serverLogger).port(3000).start(true);
+```
 
-const server = new AsenaServer().logger(new DefaultLogger()).port(3000);
+To run asena you need at least one controller. Create a new controller:
 
-await server.start();
+```typescript
+// src/controllers/TestController.ts
+import type { Context } from '@asenajs/asena/adapter/hono';
+import { Controller } from '@asenajs/asena/server';
+import { Get } from '@asenajs/asena/web';
+
+@Controller('/hello')
+export class TestController {
+
+    @Get('/world')
+    public async getHello(context: Context) {
+        return context.send('Hello World');
+    }
+
+}
 ```
 
 Finally, run the project:
 
 ```bash
 
-asena-cli dev start
+## only for fast developing purposes
+asena dev start
+```
 
+```bash
 ## or you can simply build then run your bundled project
+asena build
+## then go to dist folder and run the project this way it will consume less memory
+bun index.asena.js
+```
+
+## Example
 
-asena-cli build
+Here is a simple example of a controller with service and middleware:
 
-## theb go to dist folder and run the project
+### Middleware
 
-bun index.asena.js
+This middleware sets a value to the context object.
+
+```typescript
+// src/middleware/TestMiddleware.ts
+import type { AsenaNextHandler } from '@asenajs/asena/adapter';
+import type { Context, MiddlewareService } from '@asenajs/asena/adapter/hono';
+import { Middleware } from '@asenajs/asena/server';
+
+@Middleware()
+export class TestMiddleware implements MiddlewareService {
+  public handle(context: Context, next: AsenaNextHandler) {
+    context.setValue('testValue', 'test');
+
+    next();
+  }
+}
 ```
 
-`Note`: Built options directly copy of bun options, you can check bun documentation for more
-options. [Bun Documentation](https://bun.sh/docs/bundler#reference)
+### Service
 
-## Example
+Basic service with a getter and setter.
+
+```typescript
+import { Service } from '@asenajs/asena/server';
+
+@Service()
+export class HelloService {
+  private _foo = 'bar';
+
+  public get foo(): string {
+    return this._foo;
+  }
+
+  public set foo(value: string) {
+    this._foo = value;
+  }
+}
+```
 
-Here is a simple example of a controller:
+### Controller
+
+Controller with a GET route that uses the middleware and service.
 
 ```typescript
-// src/controllers/TestController.ts
-import {type Context, Controller, Get} from '@asenajs/asena';
+// src/controller/TestController.ts
+import { type Context, Controller, Get, Inject } from '@asenajs/asena';
+import { HelloService } from '../service/HelloService.ts';
+import { TestMiddleware } from '../middleware/TestMiddleware.ts';
 
-@Controller()
+@Controller('/v1')
 export class TestController {
-    @Get('/')
-    public async testerTest(context: Context) {
-        return context.send('Hello world!');
-    }
+  @Inject(HelloService)
+  private helloService: HelloService;
+
+  @Get('foo')
+  public async getFoo(context: Context) {
+    return context.send(this.helloService.foo);
+  }
+
+  @Get({ path: 'world', middlewares: [TestMiddleware] })
+  public async getHello(context: Context) {
+    const testValue: string = context.getValue('testValue');
+
+    return context.send(testValue);
+  }
 }
 ```
 
+### Index
+
+The main file that starts the server.
+
 ```typescript
 // src/index.ts
-import {AsenaServer, DefaultLogger} from '@asenajs/asena';
+import { AsenaServer, createHonoAdapter } from '@asenajs/asena';
+import { DefaultLogger } from '@asenajs/asena/logger';
 
-new AsenaServer().logger(new DefaultLogger()).port(3000).start();
+const [adapter, serverLogger] = createHonoAdapter(new DefaultLogger());
+await new AsenaServer(adapter, serverLogger).port(3000).start(true);
 ```
 
 then run
 
 ```bash
+asena dev start
+```
+
+You should see the following output:
 
-asena-cli dev start
+```text
 
-## logs
-2024-11-16 15:29:44 [info]:
+Build completed successfully.
+2024-11-19 17:58:35 [info]:
     ___    _____  ______ _   __ ___
    /   |  / ___/ / ____// | / //   |
   / /| |  \__ \ / __/  /  |/ // /| |
  / ___ | ___/ // /___ / /|  // ___ |
 /_/  |_|/____//_____//_/ |_//_/  |_|
 
-2024-11-16 15:29:44 [info]:     IoC initialized
-2024-11-16 15:29:44 [info]:     No server services found
-2024-11-16 15:29:44 [info]:     Controller: TestController found
-2024-11-16 15:29:44 [info]:     METHOD: GET, PATH: /, READY
-2024-11-16 15:29:44 [info]:     No websockets found
-2024-11-16 15:29:44 [info]:     Server started on port 3000
+2024-11-19 17:58:35 [info]:     IoC initialized
+2024-11-19 17:58:35 [info]:     No server services found
+2024-11-19 17:58:35 [info]:     Controller: V1 found
+2024-11-19 17:58:35 [info]:     Successfully registered GET route for PATH: /v1/foo
+2024-11-19 17:58:35 [info]:     Successfully registered GET route for PATH: /v1/world
+2024-11-19 17:58:35 [info]:     No websockets found
+2024-11-19 17:58:35 [info]:     Server started on port 3000
 ```
 
-and you see the result on your browser [http://localhost:3000](http://localhost:3000) with "Hello world!" message.
+and you see the result on your browser [http://localhost:3000/v1/foo](http://localhost:3000/v1/foo) with "bar" message.
 
 `Note`: For more example, you can check this project [Example](https://github.com/LibirSoft/AsenaExample).
 
@@ -144,7 +278,7 @@ the project:
 ### Performance Comparison (Fastest to Slowest)
 
 | Framework                            | Requests/sec | Latency (avg) | Transfer/sec |
-|--------------------------------------|--------------|---------------|--------------|
+| ------------------------------------ | ------------ | ------------- | ------------ |
 | Hono                                 | 147,031.08   | 2.69ms        | 18.09MB      |
 | Asena                                | 137,148.80   | 2.89ms        | 16.74MB      |
 | NestJS (Bun + Fastify)               | 81,652.05    | 6.01ms        | 13.78MB      |
@@ -161,7 +295,3 @@ the project:
 > - Running on same hardware
 
 _Note: Lower latency and higher requests/sec indicate better performance_
-
-## Documentation
-
-For detailed documentation, please visit [not ready yet](https://asena.sh).

package/dist/index.d.ts

@@ -1,10 +1 @@
-export { AsenaServer } from './lib/server';
-export * from './lib/server/web/middleware';
-export * from './lib/services';
-export * from './lib/adapter';
-export * from './lib/adapter/defaultAdapter';
-export { Implements } from './lib/ioc/component/decorators/Implements';
-export { Inject } from './lib/ioc/component/decorators/Inject';
-export * from './lib/server/web/api';
-export * from './lib/server/web/websocket';
-export * from './lib/server/decorators';
+export { AsenaServer, createHonoAdapter } from './lib/server';

package/dist/index.js

@@ -1,11 +1,2 @@
-export { AsenaServer } from './lib/server';
-export * from './lib/server/web/middleware';
-export * from './lib/services';
-export * from './lib/adapter';
-export * from './lib/adapter/defaultAdapter';
-export { Implements } from './lib/ioc/component/decorators/Implements';
-export { Inject } from './lib/ioc/component/decorators/Inject';
-export * from './lib/server/web/api';
-export * from './lib/server/web/websocket';
-export * from './lib/server/decorators';
+export { AsenaServer, createHonoAdapter } from './lib/server';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,uCAAuC,CAAC;AAC/D,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/lib/adapter/AsenaAdapter.d.ts

@@ -1,88 +1,81 @@
-import type { RouteParams } from './types';
+import type { AsenaServeOptions, ErrorHandler, RouteParams } from './types';
 import type { BaseMiddleware } from '../server/web/types';
-import type { ValidatorClass } from '../server/types';
 import type { Server } from 'bun';
 import type { AsenaWebsocketAdapter } from './AsenaWebsocketAdapter';
-import type { ServerLogger } from '../services';
+import type { ServerLogger } from '../logger';
+import type { AsenaContext } from './AsenaContext';
 /**
  * Abstract class representing an adapter for the Asena framework.
+ * This adapter serves as a base interface between the framework and different server implementations.
  *
- * @template A - Type for the application instance.
- * @template H - Type for the handler.
- * @template AM - Type for the middleware.
- * @template AH - Type for the handler.
- * @template R - Type for the request.
- * @template S - Type for the response.
- * @template WSA - Type for the WebSocket adapter.
+ * @template A - Type for the application instance (e.g., Express, Bun, etc.)
+ * @template R - Type for the request object
+ * @template S - Type for the response object
+ * @template VS - Type for the validator schema
+ * @template WSA - Type for the WebSocket adapter implementation
  */
-export declare abstract class AsenaAdapter<A = unknown, H = unknown, AM = unknown, AH = unknown, R = unknown, S = unknown, WSA extends AsenaWebsocketAdapter<A, AM> = AsenaWebsocketAdapter<A, AM>> {
+export declare abstract class AsenaAdapter<A, C extends AsenaContext<any, any>, VS, WSA extends AsenaWebsocketAdapter<A, C>> {
     /**
-     * The application instance.
+     * The name identifier of the adapter
+     */
+    readonly name: string;
+    /**
+     * The main application instance
      */
     app: A;
     /**
-     * The WebSocket adapter instance.
+     * WebSocket adapter instance for handling real-time communications
      */
     websocketAdapter: WSA;
     /**
-     * The port number.
+     * Server port number
      */
     protected port: number;
     /**
-     * The logger instance.
+     * Logger instance for server operations
      */
     protected logger: ServerLogger;
-    protected constructor(websocketAdapter: WSA, logger?: ServerLogger);
-    /**
-     * Sets the port number.
-     *
-     * @param {number} port - The port number to set.
-     */
-    abstract setPort(port: number): void;
     /**
-     * Uses a middleware.
-     *
-     * @param {BaseMiddleware<R, S>} middleware - The middleware to use.
-     * @param path - The path to use the middleware on.
+     * Creates a new adapter instance
+     * @param websocketAdapter - WebSocket adapter implementation
+     * @param logger - Optional custom logger implementation
      */
-    abstract use(middleware: BaseMiddleware<R, S>, path?: string): void;
+    protected constructor(websocketAdapter: WSA, logger?: ServerLogger);
     /**
-     * Registers a route.
-     *
-     * @param {RouteParams<AM, AH>} params - The route parameters.
+     * Configures the server port
+     * @param port - Port number to listen on
      */
-    abstract registerRoute(params: RouteParams<AM, AH>): void;
+    abstract setPort(port: number): void;
     /**
-     * Prepares middlewares.
-     *
-     * @param {BaseMiddleware<R, S> | BaseMiddleware<R, S>[]} middlewares - The middlewares to prepare.
-     * @returns {any[]} The prepared middlewares.
+     * Registers middleware to the application
+     * @param middleware - Middleware implementation
+     * @param path - Optional path to apply the middleware to
      */
-    abstract prepareMiddlewares(middlewares: BaseMiddleware<R, S> | BaseMiddleware<R, S>[]): any[];
+    abstract use(middleware: BaseMiddleware<C>, path?: string): Promise<void> | void;
     /**
-     * Prepares a handler.
-     *
-     * @param {H} handler - The handler to prepare.
-     * @returns {any} The prepared handler.
+     * Registers a new route with the application
+     * @param params - Route configuration parameters
      */
-    abstract prepareHandler(handler: H): any;
+    abstract registerRoute(params: RouteParams<C, VS>): Promise<void> | void;
     /**
-     * Starts the server.
-     *
-     * @returns {Promise<Server>} A promise that resolves to the server instance.
+     * Initializes and starts the server
+     * @returns Server instance
      */
-    abstract start(): Promise<Server>;
+    abstract start(): Promise<Server> | Server;
     /**
-     * Sets an error handler.
-     *
-     * @param {any} errorHandler - The error handler to set.
+     * Sets up global error handling
+     * @param errorHandler - Error handler implementation
      */
-    abstract onError(errorHandler: any): void;
+    abstract onError(errorHandler: ErrorHandler<C>): Promise<void> | void;
     /**
-     * Prepares a validator.
+     * Configures server options.
      *
-     * @param {ValidatorClass<AM>} validator - The validator to prepare.
-     * @returns {any} The prepared validator.
+     * @param options - Configuration options for the server, which can include:
+     *   - `ServeOptions`: Basic server options.
+     *   - `TLSServeOptions`: Options for TLS/SSL configuration.
+     *   - `UnixServeOptions`: Options for Unix domain sockets.
+     *   - `UnixTLSServeOptions`: Options for Unix domain sockets with TLS/SSL.
+     * @returns A promise that resolves when the options are set, or void.
      */
-    abstract prepareValidator(validator: ValidatorClass<AM>): any;
+    abstract serveOptions(options: () => Promise<AsenaServeOptions> | AsenaServeOptions): Promise<void> | void;
 }

package/dist/lib/adapter/AsenaAdapter.js

@@ -1,35 +1,46 @@
 /**
  * Abstract class representing an adapter for the Asena framework.
+ * This adapter serves as a base interface between the framework and different server implementations.
  *
- * @template A - Type for the application instance.
- * @template H - Type for the handler.
- * @template AM - Type for the middleware.
- * @template AH - Type for the handler.
- * @template R - Type for the request.
- * @template S - Type for the response.
- * @template WSA - Type for the WebSocket adapter.
+ * @template A - Type for the application instance (e.g., Express, Bun, etc.)
+ * @template R - Type for the request object
+ * @template S - Type for the response object
+ * @template VS - Type for the validator schema
+ * @template WSA - Type for the WebSocket adapter implementation
  */
 export class AsenaAdapter {
     /**
-     * The application instance.
+     * The name identifier of the adapter
+     */
+    name;
+    /**
+     * The main application instance
      */
     app;
     /**
-     * The WebSocket adapter instance.
+     * WebSocket adapter instance for handling real-time communications
      */
     websocketAdapter;
     /**
-     * The port number.
+     * Server port number
      */
     port;
     /**
-     * The logger instance.
+     * Logger instance for server operations
      */
     logger = console;
+    /**
+     * Creates a new adapter instance
+     * @param websocketAdapter - WebSocket adapter implementation
+     * @param logger - Optional custom logger implementation
+     */
     constructor(websocketAdapter, logger) {
         this.websocketAdapter = websocketAdapter;
         if (logger) {
             this.logger = logger;
+            if (!this.websocketAdapter.logger) {
+                this.websocketAdapter.logger = logger;
+            }
         }
     }
 }

package/dist/lib/adapter/AsenaAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"AsenaAdapter.js","sourceRoot":"","sources":["../../../lib/adapter/AsenaAdapter.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,MAAM,OAAgB,YAAY;IAUhC;;OAEG;IACI,GAAG,CAAI;IAEd;;OAEG;IACI,gBAAgB,CAAM;IAE7B;;OAEG;IACO,IAAI,CAAS;IAEvB;;OAEG;IACO,MAAM,GAAiB,OAAO,CAAC;IAEzC,YAAsB,gBAAqB,EAAE,MAAqB;QAChE,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;CA8DF"}
+{"version":3,"file":"AsenaAdapter.js","sourceRoot":"","sources":["../../../lib/adapter/AsenaAdapter.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,MAAM,OAAgB,YAAY;IAEhC;;OAEG;IACa,IAAI,CAAS;IAE7B;;OAEG;IACI,GAAG,CAAI;IAEd;;OAEG;IACI,gBAAgB,CAAM;IAE7B;;OAEG;IACO,IAAI,CAAS;IAEvB;;OAEG;IACO,MAAM,GAAiB,OAAO,CAAC;IAEzC;;;;OAIG;IACH,YAAsB,gBAAqB,EAAE,MAAqB;QAChE,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YAErB,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC;gBAClC,IAAI,CAAC,gBAAgB,CAAC,MAAM,GAAG,MAAM,CAAC;YACxC,CAAC;QACH,CAAC;IACH,CAAC;CA6CF"}