next-js-backend 1.0.0

package/dist/src/services/logger.service.d.ts

@@ -0,0 +1,39 @@
+export interface LoggerService {
+    log(message: unknown, context?: string): any;
+    error(message: unknown, trace?: string, context?: string): any;
+    warn(message: unknown, context?: string): any;
+    debug?(message: unknown, context?: string): any;
+    verbose?(message: unknown, context?: string): any;
+}
+export type LogLevel = 'log' | 'error' | 'warn' | 'debug' | 'verbose';
+export declare class ConsoleLogger implements LoggerService {
+    private static lastTimestamp;
+    protected context?: string;
+    constructor(context?: string);
+    setContext(context: string): void;
+    log(message: unknown, context?: string): void;
+    error(message: unknown, trace?: string, context?: string): void;
+    warn(message: unknown, context?: string): void;
+    debug(message: unknown, context?: string): void;
+    verbose(message: unknown, context?: string): void;
+    protected printMessage(message: unknown, color: string, context: string | undefined, level: string): void;
+}
+/**
+ * A static wrapper around the default logger for use outside of DI context.
+ */
+export declare class Logger {
+    private static staticInstance;
+    private instanceLogger;
+    constructor(context?: string);
+    static overrideLogger(logger: LoggerService): void;
+    log(message: unknown, context?: string): void;
+    error(message: unknown, trace?: string, context?: string): void;
+    warn(message: unknown, context?: string): void;
+    debug(message: unknown, context?: string): void;
+    verbose(message: unknown, context?: string): void;
+    static log(message: unknown, context?: string): void;
+    static error(message: unknown, trace?: string, context?: string): void;
+    static warn(message: unknown, context?: string): void;
+    static debug(message: unknown, context?: string): void;
+    static verbose(message: unknown, context?: string): void;
+}

package/dist/src/session/__tests__/session.module.test.d.ts

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

package/dist/src/session/session.module.d.ts

@@ -0,0 +1,7 @@
+import type { DynamicModule } from '../interfaces';
+import type { SessionModuleOptions } from './session.options';
+export declare const SESSION_OPTIONS = "SESSION_OPTIONS";
+export declare const SESSION_STORE = "SESSION_STORE";
+export declare class SessionModule {
+    static register(options?: SessionModuleOptions): DynamicModule;
+}

package/dist/src/session/session.options.d.ts

@@ -0,0 +1,35 @@
+import type { Type } from '../di/provider';
+import type { SessionStore } from './session.store';
+export interface SessionModuleOptions {
+    /**
+     * Secret string used to sign the cookie.`
+     * If provided, the cookie becomes tamper-proof (HttpOnly and Signed).
+     */
+    secret?: string;
+    /**
+     * Custom storage engine for tracking sessions instead of placing payload directly
+     * into the cookie (which has 4KB size limits).
+     *
+     * If omitted, defaults to an `InMemorySessionStore`.
+     */
+    store?: SessionStore | Type<SessionStore>;
+    /**
+     * The name of the session cookie.
+     * @default 'sid'
+     */
+    cookieName?: string;
+    /**
+     * Default session expiration time in seconds.
+     * @default 86400 (1 day)
+     */
+    ttl?: number;
+    /**
+     * Additional Elysia Cookie configuration
+     */
+    cookieOptions?: {
+        path?: string;
+        domain?: string;
+        secure?: boolean;
+        sameSite?: 'lax' | 'strict' | 'none';
+    };
+}

package/dist/src/session/session.service.d.ts

@@ -0,0 +1,20 @@
+import { SessionStore } from './session.store';
+import type { SessionModuleOptions } from './session.options';
+import type { SessionData } from '../globals';
+export declare class SessionService {
+    private readonly store;
+    private readonly options;
+    constructor(store: SessionStore, options: SessionModuleOptions);
+    /**
+     * Creates or writes data to a session and manages the corresponding Cookie payload.
+     */
+    createSession(data: SessionData): Promise<string>;
+    /**
+     * Loads session from storage.
+     */
+    getSession(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Destroy the active backend session instance completely.
+     */
+    destroySession(sessionId: string): Promise<void>;
+}

package/dist/src/session/session.store.d.ts

@@ -0,0 +1,39 @@
+import type { SessionData } from '../globals';
+/**
+ * Abstract class that robust session stores must extend.
+ * Users can create custom classes (Redis, Prisma, BunORM) implementing this
+ * to provide centralized state distribution.
+ */
+export declare abstract class SessionStore {
+    /**
+     * Retrieves a session from the store given a session ID.
+     */
+    abstract get(sessionId: string): Promise<SessionData | null>;
+    /**
+     * Upserts a session into the store given a session ID and session data.
+     *
+     * @param sessionId Explicit session ID attached to the Cookie.
+     * @param data The payload attached to the user.
+     * @param ttl Expected Time To Live in seconds. 0 indicates non-expiring.
+     */
+    abstract set(sessionId: string, data: SessionData, ttl: number): Promise<void>;
+    /**
+     * Specifically destroys a running session by ID.
+     */
+    abstract destroy(sessionId: string): Promise<void>;
+    /**
+     * Refresh a session's Time To Live if accessed.
+     */
+    abstract touch?(sessionId: string, ttl: number): Promise<void>;
+}
+/**
+ * A built-in, non-persistent In-Memory Session Storage mechanism.
+ * Ideal for local development or basic deployment without a DB dependency.
+ */
+export declare class InMemorySessionStore implements SessionStore {
+    private store;
+    get(sessionId: string): Promise<SessionData | null>;
+    set(sessionId: string, data: SessionData, ttl: number): Promise<void>;
+    destroy(sessionId: string): Promise<void>;
+    touch(sessionId: string, ttl: number): Promise<void>;
+}

package/dist/test.d.ts

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

package/dist/testing/e2e/auth.test.d.ts

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

package/dist/testing/e2e/config.test.d.ts

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

package/dist/testing/e2e/di.test.d.ts

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

package/dist/testing/e2e/guards-interceptors.test.d.ts

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

package/dist/testing/e2e/routing.test.d.ts

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

package/dist/testing/e2e/validation.test.d.ts

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

package/index.ts

@@ -0,0 +1,24 @@
+export * from './src/constants';
+export * from './src/interfaces';
+export * from './src/decorators/controller.decorator';
+export { Get, Post, Put, Delete, Patch, Options, Head, All, RequestMethod } from './src/decorators/method.decorator';
+export * from './src/decorators/module.decorator';
+export * from './src/decorators/param.decorator';
+export * from './src/decorators/schema.decorator';
+export * from './src/decorators/guard.decorator';
+export * from './src/decorators/interceptor.decorator';
+export * from './src/decorators/pipe.decorator';
+export * from './src/decorators/catch.decorator';
+export * from './src/decorators/filter.decorator';
+export * from './src/di/injectable.decorator';
+export * from './src/di/container';
+export * from './src/exceptions';
+export * from './src/exceptions/validation.pipe';
+export * from './src/factory/elysia-factory';export * from './src/services/logger.service';
+export * from './src/config/config.service';
+export * from './src/config/config.module';
+export * from './src/auth';
+export * from './src/session/session.module';
+export * from './src/session/session.service';
+export * from './src/session/session.store';
+export * from './src/session/session.options';

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "next-js-backend",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./index.ts --outdir ./dist --target node && bun x tsc --emitDeclarationOnly",
+    "prepublishOnly": "bun run build"
+  },
+  "description": "A high-performance NestJS-like backend library for Bun and Next.js Edge, powered by Elysia.",
+  "author": "Tuan Nguyen",
+  "license": "MIT",
+  "keywords": [
+    "elysia",
+    "nestjs",
+    "bun",
+    "nextjs",
+    "library",
+    "edge",
+    "decorators",
+    "dependency-injection"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tuannc/next-js-backend.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tuannc/next-js-backend/issues"
+  },
+  "files": [
+    "dist",
+    "src",
+    "index.ts",
+    "globals.d.ts",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@elysiajs/swagger": "^1.3.1",
+    "@sinclair/typebox": "^0.34.48",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "elysia": "^1.4.27",
+    "jose": "^6.2.1",
+    "reflect-metadata": "^0.2.2"
+  }
+}

package/src/auth/__tests__/password.service.test.ts

@@ -0,0 +1,38 @@
+import { expect, test, describe } from 'bun:test';
+import { PasswordService } from '../password.service';
+
+describe('PasswordService', () => {
+  const passwordService = new PasswordService();
+
+  test('should hash and verify passwords correctly using default (bcrypt)', async () => {
+    const rawPassword = 'super-secret-password';
+    
+    // Hash
+    const hash = await passwordService.hash(rawPassword);
+    
+    expect(hash).toBeString();
+    expect(hash).not.toEqual(rawPassword);
+    
+    // Verify success
+    const isMatch = await passwordService.verify(rawPassword, hash);
+    expect(isMatch).toBe(true);
+    
+    // Verify fail
+    const isNotMatch = await passwordService.verify('wrong-password', hash);
+    expect(isNotMatch).toBe(false);
+  });
+
+  test('should hash and verify passwords using argon2', async () => {
+    const rawPassword = 'another-password-123';
+    
+    // Hash
+    const hash = await passwordService.hash(rawPassword, { algorithm: 'argon2id' });
+    
+    expect(hash).toBeString();
+    expect(hash.startsWith('$argon2')).toBe(true);
+    
+    // Verify success
+    const isMatch = await passwordService.verify(rawPassword, hash);
+    expect(isMatch).toBe(true);
+  });
+});

package/src/auth/auth.guard.ts

@@ -0,0 +1,34 @@
+import { Injectable } from '../di/injectable.decorator';
+import { type CanActivate } from '../interfaces';
+import { type Context } from 'elysia';
+import { JwtService } from './jwt.service';
+import { UnauthorizedException } from '../exceptions';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(private readonly jwtService: JwtService) {}
+
+  async canActivate(context: Context): Promise<boolean> {
+    const request = context.request;
+    const authHeader = request.headers.get('authorization');
+    
+    if (!authHeader) {
+      throw new UnauthorizedException('Missing Authorization header');
+    }
+
+    const [type, token] = authHeader.split(' ');
+
+    if (type !== 'Bearer' || !token) {
+      throw new UnauthorizedException('Invalid token format (expected Bearer <token>)');
+    }
+
+    try {
+      const payload = await this.jwtService.verifyAsync(token);
+      // Append user payload directly into the context stream so controllers can access it
+      (context as any).user = payload;
+      return true;
+    } catch (error) {
+      throw new UnauthorizedException('Token is invalid or expired');
+    }
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,4 @@
+export * from './jwt.service';
+export * from './jwt.module';
+export * from './auth.guard';
+export * from './password.service';

package/src/auth/jwt.module.ts

@@ -0,0 +1,24 @@
+import { Module } from '../decorators/module.decorator';
+import { type DynamicModule } from '../interfaces';
+import { JwtService, type JwtModuleOptions } from './jwt.service';
+
+@Module({})
+export class JwtModule {
+  /**
+   * Bootstraps the JwtModule.
+   * 
+   * @param options Configuration options including signing secret and defaults
+   */
+  static register(options: JwtModuleOptions): DynamicModule {
+    return {
+      module: JwtModule,
+      providers: [
+        {
+          provide: JwtService,
+          useFactory: () => new JwtService(options),
+        }
+      ],
+      exports: [JwtService]
+    };
+  }
+}

package/src/auth/jwt.service.ts

@@ -0,0 +1,65 @@
+import { Injectable } from '../di/injectable.decorator';
+import { SignJWT, jwtVerify, type JWTPayload } from 'jose';
+
+export interface JwtModuleOptions {
+  secret: string;
+  signOptions?: {
+    expiresIn?: string | number; // e.g. '1h', '2 days', 3600
+    issuer?: string;
+    audience?: string | string[];
+    algorithm?: string;
+  };
+}
+
+@Injectable()
+export class JwtService {
+  private readonly secretKey: Uint8Array;
+
+  constructor(private readonly options: JwtModuleOptions) {
+    if (!options.secret) {
+      throw new Error('JwtModule requires a secret key for signing tokens.');
+    }
+    this.secretKey = new TextEncoder().encode(options.secret);
+  }
+
+  /**
+   * Synchronously signs a token payload.
+   * Note: While jose generally operates async, we provide a signature abstraction 
+   * that awaits natively inside modern Promise contexts.
+   */
+  async signAsync(payload: JWTPayload, options?: JwtModuleOptions['signOptions']): Promise<string> {
+    const combinedOptions = { ...this.options.signOptions, ...options };
+    const alg = combinedOptions.algorithm || 'HS256';
+
+    let signer = new SignJWT(payload)
+      .setProtectedHeader({ alg })
+      .setIssuedAt();
+
+    if (combinedOptions.expiresIn) {
+      signer = signer.setExpirationTime(combinedOptions.expiresIn as any);
+    }
+    if (combinedOptions.issuer) {
+      signer = signer.setIssuer(combinedOptions.issuer);
+    }
+    if (combinedOptions.audience) {
+      signer = signer.setAudience(combinedOptions.audience);
+    }
+
+    return await signer.sign(this.secretKey);
+  }
+
+  /**
+   * Verifies a JWT token asynchronously and returns the decoded payload.
+   */
+  async verifyAsync<T extends JWTPayload = JWTPayload>(token: string): Promise<T> {
+    try {
+      const { payload } = await jwtVerify(token, this.secretKey, {
+        issuer: this.options.signOptions?.issuer,
+        audience: this.options.signOptions?.audience,
+      });
+      return payload as T;
+    } catch (e: any) {
+      throw new Error(`Invalid or expired token: ${e.message}`);
+    }
+  }
+}

package/src/auth/password.service.ts

@@ -0,0 +1,48 @@
+import { Injectable } from '../di/injectable.decorator';
+
+export interface HashOptions {
+  /**
+   * The hashing algorithm to use.
+   * Bun natively supports 'bcrypt', 'argon2id', 'argon2d', 'argon2i'.
+   * @default 'bcrypt'
+   */
+  algorithm?: 'bcrypt' | 'argon2id' | 'argon2d' | 'argon2i';
+  
+  /**
+   * For bcrypt: the cost factor (4-31). Default is 10.
+   * For argon2: memory cost, time cost, etc. are handled securely by Bun.
+   */
+  cost?: number;
+}
+
+@Injectable()
+export class PasswordService {
+  /**
+   * Hashes a plaintext password securely.
+   * Uses Bun's native, highly optimized `Bun.password.hash` engine.
+   * 
+   * @param password The raw, plaintext password.
+   * @param options Hashing algorithm options (default: bcrypt, cost: 10).
+   * @returns A Promise that resolves to the hashed password string.
+   */
+  async hash(password: string, options?: HashOptions): Promise<string> {
+    const alg = options?.algorithm || 'bcrypt';
+    const cost = options?.cost || 10;
+    
+    return Bun.password.hash(password, {
+      algorithm: alg,
+      cost,
+    } as any);
+  }
+
+  /**
+   * Verifies a plaintext password against a previously hashed password string.
+   * 
+   * @param password The raw, plaintext password to check.
+   * @param hash The stored hash string (argon2 or bcrypt).
+   * @returns A Promise that resolves to true if the password matches the hash.
+   */
+  async verify(password: string, hash: string): Promise<boolean> {
+    return Bun.password.verify(password, hash);
+  }
+}

package/src/config/config.module.ts

@@ -0,0 +1,24 @@
+import { Module } from '../decorators/module.decorator';
+import { type DynamicModule } from '../interfaces';
+import { ConfigService, type ConfigModuleOptions } from './config.service';
+
+@Module({})
+export class ConfigModule {
+  /**
+   * Bootstraps the ConfigModule.
+   * 
+   * @param options Configuration options including TypeBox schema
+   */
+  static forRoot(options: ConfigModuleOptions = {}): DynamicModule {
+    return {
+      module: ConfigModule,
+      providers: [
+        {
+          provide: ConfigService,
+          useFactory: () => new ConfigService(options),
+        }
+      ],
+      exports: [ConfigService]
+    };
+  }
+}

package/src/config/config.service.ts

@@ -0,0 +1,78 @@
+import { Injectable } from '../di/injectable.decorator';
+import { Type as T, type TSchema } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+import { Logger } from '../services/logger.service';
+
+export interface ConfigModuleOptions {
+  /**
+   * TypeBox schema to validate process.env
+   */
+  schema?: TSchema;
+  /**
+   * Optional custom config object. If not provided, process.env is used.
+   */
+  load?: Record<string, string>;
+}
+
+@Injectable()
+export class ConfigService<Config = Record<string, string>> {
+  private config: Config;
+  private readonly logger = new Logger('ConfigService');
+
+  constructor(options?: ConfigModuleOptions) {
+    const rawConfig = options?.load || process.env;
+
+    if (options?.schema) {
+      try {
+        const copy = { ...rawConfig };
+        
+        // Convert strings to correct primitives (e.g "3000" -> 3000, "true" -> true)
+        Value.Convert(options.schema, copy);
+        
+        // Apply default values defined in the schema
+        const defaulted = Value.Default(options.schema, copy) as any;
+        
+        // Validate and decode
+        const decoded = Value.Decode(options.schema, defaulted);
+        
+        this.config = (decoded || defaulted) as Config;
+      } catch (error: any) {
+        this.logger.error('Environment validation failed!');
+        
+        // Print detailed TypeBox errors
+        const errors = [...Value.Errors(options.schema, rawConfig)];
+        errors.forEach(err => {
+            this.logger.error(`- Property '${err.path}' ${err.message}`);
+        });
+        
+        throw new Error('Config validation error');
+      }
+    } else {
+      this.config = rawConfig as unknown as Config;
+    }
+  }
+
+  /**
+   * Get a configuration value by key
+   */
+  get<T = string>(key: keyof Config): T | undefined;
+  get<T = string>(key: keyof Config, defaultValue: T): T;
+  get<T = string>(key: keyof Config, defaultValue?: T): T | undefined {
+    const value = this.config[key];
+    if (value !== undefined) {
+      return value as unknown as T;
+    }
+    return defaultValue;
+  }
+
+  /**
+   * Get a configuration value asserting it exists
+   */
+  getOrThrow<T = string>(key: keyof Config): T {
+    const value = this.config[key];
+    if (value === undefined) {
+      throw new Error(`Configuration key "${String(key)}" does not exist`);
+    }
+    return value as unknown as T;
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export * from './config.service';
+export * from './config.module';

package/src/constants.ts

@@ -0,0 +1,16 @@
+export const CONTROLLER_WATERMARK = '__controller__';
+export const INJECTABLE_WATERMARK = '__injectable__';
+export const METHOD_METADATA = 'method';
+export const PATH_METADATA = 'path';
+export const ROUTE_ARGS_METADATA = '__routeArguments__';
+export const GUARDS_METADATA = '__guards__';
+export const INTERCEPTORS_METADATA = '__interceptors__';
+export const PIPES_METADATA = '__pipes__';
+export const FILTERS_METADATA = 'filters';
+export const SCHEMA_METADATA = '__schema__';
+export const MODULE_METADATA = {
+  IMPORTS: 'imports',
+  PROVIDERS: 'providers',
+  CONTROLLERS: 'controllers',
+  EXPORTS: 'exports',
+};

package/src/decorators/catch.decorator.ts

@@ -0,0 +1,16 @@
+import 'reflect-metadata';
+import { Type } from '../di/provider';
+
+export const FILTER_CATCH_EXCEPTIONS = 'FILTER_CATCH_EXCEPTIONS';
+
+/**
+ * Decorator that marks a class as a Nest exception filter.
+ * An exception filter handles thrown exceptions caught during execution.
+ * 
+ * @param exceptions One or more exception types that this filter should catch.
+ */
+export function Catch(...exceptions: Type<any>[]): ClassDecorator {
+  return (target: Function) => {
+    Reflect.defineMetadata(FILTER_CATCH_EXCEPTIONS, exceptions, target);
+  };
+}

package/src/decorators/controller.decorator.ts

@@ -0,0 +1,14 @@
+import 'reflect-metadata';
+import { Injectable } from '../di/injectable.decorator';
+
+import { CONTROLLER_WATERMARK, PATH_METADATA } from '../constants';
+
+export function Controller(prefix: string = ''): ClassDecorator {
+  return (target: Function) => {
+    Injectable()(target);
+    Reflect.defineMetadata(CONTROLLER_WATERMARK, true, target);
+    // Ensure prefixes start with / and don't end with / unless it's just /
+    const normalizedPrefix = prefix.startsWith('/') ? prefix : `/${prefix}`;
+    Reflect.defineMetadata(PATH_METADATA, normalizedPrefix, target);
+  };
+}

package/src/decorators/filter.decorator.ts

@@ -0,0 +1,22 @@
+import 'reflect-metadata';
+import { FILTERS_METADATA } from '../constants';
+
+/**
+ * Decorator that binds exception filters to the scope of the controller or method.
+ * 
+ * @param filters One or more filter instances or classes to use.
+ */
+export function UseFilters(...filters: (Function | Record<string, any>)[]): MethodDecorator & ClassDecorator {
+  return (
+    target: any,
+    propertyKey?: string | symbol,
+    descriptor?: TypedPropertyDescriptor<any>,
+  ) => {
+    if (descriptor) {
+      Reflect.defineMetadata(FILTERS_METADATA, filters, descriptor.value!);
+      return descriptor;
+    }
+    Reflect.defineMetadata(FILTERS_METADATA, filters, target);
+    return target;
+  };
+}