@avleon/core 0.0.39 → 0.0.42-rc0.1

package/README.md

@@ -1,20 +1,9 @@
-# AvleonJs
+# Avleon 
 
-## ⚠️ WARNING: NOT FOR PRODUCTION USE
+![npm version](https://img.shields.io/npm/v/@avleon/core.svg) ![Build](https://github.com/avleonjs/avleon-core/actions/workflows/release.yml/badge.svg)
+## ⚠️ WARNING
 
 > **🚧 This project is in active development.**
->
-> It is **not stable** and **not ready** for live environments.  
-> Use **only for testing, experimentation, or internal evaluation**.
->
-> ####❗ Risks of using this in production:
->
-> - 🔄 Breaking changes may be introduced at any time
-> - 🧪 Features are experimental and may be unstable
-> - 🔐 Security has not been audited
-> - 💥 Potential for data loss or critical errors
->
-> **Please do not deploy this in production environments.**
 
 ## Overview
 
@@ -69,11 +58,11 @@ Avleon is a powerful, TypeScript-based web framework built on top of Fastify, de
 ## Installation
 
 ```bash
-npm install @avleon/core
+npx @avleon/cli new myapp
 # or
-yarn add @avleon/core
+yarn dlx @avleon/cli new myapp
 # or
-pnpm add @avleon/core
+pnpm dlx @avleon/cli new myapp
 ```
 
 ## Quick Start
@@ -81,7 +70,7 @@ pnpm add @avleon/core
 ### Minimal
 
 ```typescript
-import { Avleon, ApiController, Get, Results } from "@avleon/core";
+import { Avleon } from "@avleon/core";
 
 const app = Avleon.createApplication();
 app.mapGet("/", () => "Hello, Avleon");
@@ -123,7 +112,9 @@ const app = Avleon.createApplication();
 // Configure and run the application
 app.useCors();
 app.useControllers([UserController]);
-app.run(3000);
+// For auto register controller `app.useControllers({auto:true});`
+
+app.run(); // or app.run(port)
 ```
 
 ### Controllers
@@ -253,7 +244,9 @@ class UserController {
 Secure your API with authentication and authorization:
 
 ```typescript
-@Authorize
+import { CanAuthorize } from "@avleon/core";
+
+@CanAuthorize
 class JwtAuthorization extends AuthorizeMiddleware {
   authorize(roles: string[]) {
     return async (req: IRequest) => {
@@ -382,6 +375,66 @@ app.useOpenApi(OpenApiConfig, (config) => {
 
 ### Database Integration
 
+## 1. Knex
+
+```typescript
+const app = Avleon.createApplication();
+app.useKnex({
+  client: 'mysql',
+  connection: {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'your_database_user',
+    password: 'your_database_password',
+    database: 'myapp_test',
+  },
+})
+```
+or using config class 
+
+```typescript
+@AppConfig
+export class KnexConfig implements IConfig {
+  // config method is mendatory
+  // config method has access to environment variables by default
+  config(env: Environment) {
+    return {
+      client: 'mysql',
+      connection: {
+        host: env.get("DB_HOST") || '127.0.0.1',
+        port: env.get("DB_PORT") || 3306,
+        user: env.get("DB_USER")|| 'your_database_user',
+        password: env.get("DB_PASS") || 'your_database_password',
+        database: env.get("DB_NAME") || 'myapp_test',
+      },
+    };
+  }
+}
+
+// now we can register it with our app
+
+app.useKenx(KnexConfig)
+```
+
+### Exmaple uses
+
+```typescript
+import { DB, AppService } from "@avleon/core";
+
+@AppService
+export class UsersService{
+  constructor(
+    private readonly db: DB
+  ){}
+
+  async findAll(){
+    const result = await this.db.client.select("*").from("users");
+    return result;
+  }
+}
+```
+
+## 2. Typeorm
 Connect to databases using TypeORM:
 
 ```typescript
@@ -402,9 +455,9 @@ Or use the config class:
 
 ```typescript
 // datasource.config.ts
-import { Config, IConfig } from "@avleon/core";
+import { AppConfig, IConfig } from "@avleon/core";
 
-@Config
+@AppConfig
 export class DataSourceConfig implements IConfig {
   // config method is mendatory
   // config method has access to environment variables by default
@@ -451,24 +504,53 @@ export class UserService {
 }
 ```
 
-### File Uploads
+### File Uploads & File Storage
 
 Handle file uploads with multipart support:
 
 ```typescript
 // Configure multipart file uploads
 app.useMultipart({
-  destination: path.join(process.cwd(), 'uploads'),
+  destination: path.join(process.cwd(), 'public/uploads'),
   limits: {
     fileSize: 5 * 1024 * 1024 // 5MB
   }
 });
-
+```
+```typescript
 // In your controller
+import {FileStorage} from '@avleon/core';
+
+//inject FileStorage into constructor
+constructor(
+  private readonly fileStorage: FileStorage
+){}
+
+@OpenApi({
+  description: "Uploading single file"
+  body:{
+    type:"object",
+    properties:{
+      file:{
+        type:"string",
+        format:"binary"
+      }
+    },
+    required:["file"]
+  }
+})
 @Post('/upload')
-async uploadFile(@MultipartFile() file: any) {
+async uploadSingleFile(@UploadFile('file') file: MultipartFile) {
   // Process uploaded file
-  return HttpResponse.Ok({ filename: file.filename });
+  const result = await this.fileStorage.save(file);
+  // or with new name 
+  //  const result = await this.fileStorage.save(file, {as:newname.ext});
+  // result
+  // {
+  //  uploadPath:"/uplaod",
+  //  staticPath: "/static/"
+  //}
+  return result;
 }
 ```
 
@@ -477,6 +559,9 @@ async uploadFile(@MultipartFile() file: any) {
 Serve static files:
 
 ```typescript
+import path from 'path';
+
+
 app.useStaticFiles({
   path: path.join(process.cwd(), "public"),
   prefix: "/static/",
@@ -552,7 +637,7 @@ app
     // Handler function
   })
   .useMiddleware([AuthMiddleware])
-  .useSwagger({
+  .useOpenApi({
     summary: "Get all users",
     description: "Retrieves a list of all users",
     tags: ["users"],

package/dist/cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache.test.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cache_1 = require("./cache");
+describe("CacheManager (in-memory)", () => {
+    let cache;
+    beforeEach(() => {
+        cache = new cache_1.CacheManager();
+    });
+    it("should set and get a value", async () => {
+        await cache.set("foo", "bar");
+        const result = await cache.get("foo");
+        expect(result).toBe("bar");
+    });
+    it("should return null for missing key", async () => {
+        const result = await cache.get("missing");
+        expect(result).toBeNull();
+    });
+    it("should delete a key", async () => {
+        await cache.set("foo", "bar");
+        await cache.delete("foo");
+        const result = await cache.get("foo");
+        expect(result).toBeNull();
+    });
+    it("should associate keys with tags and invalidate by tag", async () => {
+        await cache.set("a", 1, ["tag1"]);
+        await cache.set("b", 2, ["tag1", "tag2"]);
+        await cache.set("c", 3, ["tag2"]);
+        await cache.invalidateTag("tag1");
+        expect(await cache.get("a")).toBeNull();
+        expect(await cache.get("b")).toBeNull();
+        expect(await cache.get("c")).toBe(3);
+    });
+    it("should not fail when invalidating a non-existent tag", async () => {
+        await expect(cache.invalidateTag("nope")).resolves.not.toThrow();
+    });
+});

package/dist/controller.d.ts

@@ -4,6 +4,8 @@
  * @email xtrinsic96@gmail.com
  * @url https://github.com/xtareq
  */
+export declare const REQUEST_METADATA_KEY: unique symbol;
+export declare function AvleonRequest(): ParameterDecorator;
 /**
  * Options for configuring a controller.
  * @remarks

package/dist/controller.js

@@ -6,10 +6,23 @@
  * @url https://github.com/xtareq
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_METADATA_KEY = void 0;
+exports.AvleonRequest = AvleonRequest;
 exports.createControllerDecorator = createControllerDecorator;
 exports.ApiController = ApiController;
 const typedi_1 = require("typedi");
 const container_1 = require("./container");
+exports.REQUEST_METADATA_KEY = Symbol('avleon:request');
+function AvleonRequest() {
+    return (target, propertyKey, parameterIndex) => {
+        const existingParams = Reflect.getMetadata(exports.REQUEST_METADATA_KEY, target, propertyKey) || [];
+        existingParams.push({
+            index: parameterIndex,
+            type: 'request',
+        });
+        Reflect.defineMetadata(exports.REQUEST_METADATA_KEY, existingParams, target, propertyKey);
+    };
+}
 function createControllerDecorator(type = "web") {
     return function (pathOrOptions, maybeOptions) {
         return function (target) {

package/dist/controller.test.d.ts

@@ -0,0 +1 @@
+import "reflect-metadata";

package/dist/controller.test.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const controller_1 = require("./controller");
+const containerModule = __importStar(require("./container"));
+const typedi_1 = require("typedi");
+describe("Controller Decorators", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    describe("ApiController", () => {
+        it("should apply metadata and Service decorator when used as a class decorator", () => {
+            const registerControllerSpy = jest.spyOn(containerModule, "registerController");
+            let TestController = class TestController {
+            };
+            TestController = __decorate([
+                controller_1.ApiController
+            ], TestController);
+            expect(Reflect.getMetadata(containerModule.API_CONTROLLER_METADATA_KEY, TestController)).toBe(true);
+            expect(registerControllerSpy).toHaveBeenCalledWith(TestController);
+            expect(Reflect.getMetadata(containerModule.CONTROLLER_META_KEY, TestController)).toEqual({
+                type: "api",
+                path: "/",
+                options: {},
+            });
+        });
+        it("should apply metadata and Service decorator when used with a path", () => {
+            const registerControllerSpy = jest.spyOn(containerModule, "registerController");
+            let TestController = class TestController {
+            };
+            TestController = __decorate([
+                (0, controller_1.ApiController)("/test")
+            ], TestController);
+            expect(Reflect.getMetadata(containerModule.API_CONTROLLER_METADATA_KEY, TestController)).toBe(true);
+            expect(registerControllerSpy).toHaveBeenCalledWith(TestController);
+            expect(Reflect.getMetadata(containerModule.CONTROLLER_META_KEY, TestController)).toEqual({
+                type: "api",
+                path: "/test",
+                options: {},
+            });
+        });
+        it("should apply metadata and Service decorator when used with options", () => {
+            const registerControllerSpy = jest.spyOn(containerModule, "registerController");
+            const options = { name: "Custom", path: "/custom", version: "1.0.0" };
+            let TestController = class TestController {
+            };
+            TestController = __decorate([
+                (0, controller_1.ApiController)(options)
+            ], TestController);
+            expect(Reflect.getMetadata(containerModule.API_CONTROLLER_METADATA_KEY, TestController)).toBe(true);
+            expect(registerControllerSpy).toHaveBeenCalledWith(TestController);
+            expect(Reflect.getMetadata(containerModule.CONTROLLER_META_KEY, TestController)).toEqual({
+                type: "api",
+                path: "/custom",
+                options,
+            });
+        });
+        const originalService = typedi_1.Service;
+        // @ts-ignore
+        containerModule.Service = undefined;
+        expect(() => {
+            let TestController = class TestController {
+            };
+            TestController = __decorate([
+                controller_1.ApiController
+            ], TestController);
+        }).toThrow("Service decorator is not a function");
+        // Restore
+        // @ts-ignore
+        containerModule.Service = originalService;
+    });
+});

package/dist/environment-variables.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/environment-variables.test.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const environment_variables_1 = require("./environment-variables");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+jest.mock("fs");
+const mockedFs = fs_1.default;
+describe("Environment", () => {
+    const envFilePath = path_1.default.join(process.cwd(), ".env");
+    const envContent = "TEST_KEY=123\nANOTHER_KEY=abc";
+    const parsedEnv = { TEST_KEY: "123", ANOTHER_KEY: "abc" };
+    beforeEach(() => {
+        jest.resetModules();
+        mockedFs.existsSync.mockClear();
+        mockedFs.readFileSync.mockClear();
+        process.env.TEST_KEY = "override";
+        process.env.ONLY_PROCESS = "proc";
+    });
+    afterEach(() => {
+        delete process.env.TEST_KEY;
+        delete process.env.ONLY_PROCESS;
+    });
+    it("should get value from process.env if present", () => {
+        mockedFs.existsSync.mockReturnValue(true);
+        mockedFs.readFileSync.mockReturnValue(envContent);
+        const env = new environment_variables_1.Environment();
+        expect(env.get("TEST_KEY")).toBe("override");
+    });
+    it("should get value from .env file if not in process.env", () => {
+        mockedFs.existsSync.mockReturnValue(true);
+        mockedFs.readFileSync.mockReturnValue(envContent);
+        const env = new environment_variables_1.Environment();
+        expect(env.get("ANOTHER_KEY")).toBe("abc");
+    });
+    it("should return undefined for missing key", () => {
+        mockedFs.existsSync.mockReturnValue(true);
+        mockedFs.readFileSync.mockReturnValue(envContent);
+        const env = new environment_variables_1.Environment();
+        expect(env.get("MISSING_KEY")).toBeUndefined();
+    });
+    it("should throw EnvironmentVariableNotFound for getOrThrow if missing", () => {
+        mockedFs.existsSync.mockReturnValue(true);
+        mockedFs.readFileSync.mockReturnValue(envContent);
+        const env = new environment_variables_1.Environment();
+        expect(() => env.getOrThrow("MISSING_KEY")).toThrow();
+    });
+    it("should get all variables with process.env taking precedence", () => {
+        mockedFs.existsSync.mockReturnValue(true);
+        mockedFs.readFileSync.mockReturnValue(envContent);
+        const env = new environment_variables_1.Environment();
+        const all = env.getAll();
+        expect(all.TEST_KEY).toBe("override");
+        expect(all.ANOTHER_KEY).toBe("abc");
+        expect(all.ONLY_PROCESS).toBe("proc");
+    });
+    it("should handle missing .env file gracefully", () => {
+        mockedFs.existsSync.mockReturnValue(false);
+        const env = new environment_variables_1.Environment();
+        expect(env.get("ONLY_PROCESS")).toBe("proc");
+        expect(env.get("TEST_KEY")).toBe("override");
+    });
+    it("should return empty object if error occurs during parsing", () => {
+        mockedFs.existsSync.mockImplementation(() => { throw new Error("fs error"); });
+        const env = new environment_variables_1.Environment();
+        expect(env.getAll()).toEqual({});
+    });
+});

package/dist/exceptions/http-exceptions.d.ts

@@ -7,6 +7,7 @@
 export declare abstract class BaseHttpException extends Error {
     code: number;
     name: string;
+    payload: any;
     constructor(message: any);
     isCustomException(): boolean;
 }

package/dist/exceptions/http-exceptions.js

@@ -9,9 +9,11 @@ exports.HttpExceptions = exports.ForbiddenException = exports.UnauthorizedExcept
  */
 class BaseHttpException extends Error {
     constructor(message) {
-        super(JSON.stringify(message));
+        const stringMessage = typeof message === "string" ? message : JSON.stringify(message);
+        super(stringMessage);
         this.code = 500;
         this.name = "HttpException";
+        this.payload = typeof message === "string" ? { message } : message;
     }
     isCustomException() {
         return true;

package/dist/file-storage.d.ts

@@ -1,4 +1,4 @@
-import { PathLike } from "fs";
+import fs, { PathLike } from "fs";
 import { MultipartFile } from "./multipart";
 interface TransformOptions {
     resize?: {
@@ -10,9 +10,9 @@ interface TransformOptions {
 }
 export interface FileStorageInterface {
     transform(options: TransformOptions): FileStorage;
-    save(file: MultipartFile, options?: SaveOptionsSingle): Promise<MultipartFile | undefined>;
-    saveAll(files: MultipartFile[], options?: SaveOptions): Promise<MultipartFile[] | undefined>;
-    remove(filepath: PathLike): Promise<void>;
+    save(file: MultipartFile, options?: SaveOptionsSingle): Promise<MultipartFile>;
+    saveAll(files: MultipartFile[], options?: SaveOptions): Promise<MultipartFile[]>;
+    remove(filepath: string): Promise<void>;
 }
 export interface SaveOptions {
     overwrite?: boolean;
@@ -23,12 +23,47 @@ export interface SaveOptionsSingle extends SaveOptions {
 }
 export declare class FileStorage implements FileStorageInterface {
     private transformOptions;
-    transform(options: TransformOptions): this;
-    private isFileExists;
-    save(f: MultipartFile, options?: SaveOptionsSingle): Promise<import("@fastify/multipart").MultipartFile | undefined>;
-    remove(filepath: PathLike): Promise<void>;
-    saveAll(files: MultipartFile[], options?: SaveOptions): Promise<MultipartFile[]>;
+    private readonly baseDir;
+    private readonly maxFileSize;
+    constructor();
+    /**
+     * Set transformation options for the next save operation
+     */
+    transform(options: TransformOptions): FileStorage;
+    getUploadFile(fliePath: string): Promise<Buffer<ArrayBufferLike>>;
+    download(filepath: PathLike): Promise<{
+        download: boolean;
+        stream: fs.ReadStream;
+        filename: string;
+    }>;
+    downloadAs(filepath: PathLike, filename: string): Promise<{
+        download: boolean;
+        stream: fs.ReadStream;
+        filename: string;
+    }>;
+    /**
+     * Save a single file with optional transformations
+     */
+    save(f: MultipartFile, options?: SaveOptionsSingle): Promise<any>;
+    /**
+     * Save multiple files
+     */
+    saveAll(files: MultipartFile[], options?: SaveOptions): Promise<any[]>;
+    /**
+     * Remove a file from storage
+     */
+    remove(filepath: string): Promise<void>;
+    /**
+     * Process image with transformations using sharp
+     */
     private processImage;
+    /**
+     * Helper methods
+     */
+    private isFileExists;
     private ensureDirectoryExists;
+    private removeFileSync;
+    private isImageFile;
+    private validateFilename;
 }
 export {};