fragment-ts 1.0.16 → 1.0.18

package/src/core/decorators/injection.decorators.ts

@@ -1,26 +1,150 @@
-import { METADATA_KEYS } from '../metadata/metadata-keys';
+import { METADATA_KEYS } from "../metadata/metadata-keys";
 
+/**
+ * @Autowired - Automatically inject dependencies by type
+ * Usage: @Autowired() private myService: MyService;
+ */
 export function Autowired(): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
-    const type = Reflect.getMetadata('design:type', target, propertyKey);
+    // Get the design type from TypeScript metadata
+    const type = Reflect.getMetadata("design:type", target, propertyKey);
+
+    if (!type || type === Object) {
+      throw new Error(
+        `Cannot use @Autowired on property "${String(propertyKey)}" in ${target.constructor.name}. ` +
+          `Make sure TypeScript emitDecoratorMetadata is enabled and the type is explicitly declared.`,
+      );
+    }
+
+    // Store the type in metadata so DI container can resolve it
     Reflect.defineMetadata(METADATA_KEYS.AUTOWIRED, type, target, propertyKey);
   };
 }
 
-export function Inject(token: string): PropertyDecorator {
+/**
+ * @Inject - Inject dependency by token (string or class)
+ * Usage: @Inject('MyService') private service: MyService;
+ * or: @Inject(MyService) private service: MyService;
+ */
+export function Inject(token: string | Function): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
     Reflect.defineMetadata(METADATA_KEYS.INJECT, token, target, propertyKey);
   };
 }
 
+/**
+ * @InjectRepository - Inject TypeORM repository for an entity
+ * Usage: @InjectRepository(User) private userRepo: Repository<User>;
+ */
+export function InjectRepository(entity: Function): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    Reflect.defineMetadata(
+      METADATA_KEYS.INJECT_REPOSITORY,
+      entity,
+      target,
+      propertyKey,
+    );
+  };
+}
+
+/**
+ * @Qualifier - Specify which bean to inject when multiple exist
+ * Usage: @Qualifier('primary') @Autowired() private service: MyService;
+ */
 export function Qualifier(name: string): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
     Reflect.defineMetadata(METADATA_KEYS.QUALIFIER, name, target, propertyKey);
   };
 }
 
+/**
+ * @Value - Inject configuration value from environment or config
+ * Usage: @Value('${PORT}') private port: number;
+ * or: @Value('${DB_HOST:localhost}') private host: string;
+ */
 export function Value(expression: string): PropertyDecorator {
   return (target: any, propertyKey: string | symbol) => {
-    Reflect.defineMetadata(METADATA_KEYS.VALUE, expression, target, propertyKey);
+    Reflect.defineMetadata(
+      METADATA_KEYS.VALUE,
+      expression,
+      target,
+      propertyKey,
+    );
+  };
+}
+
+/**
+ * @Optional - Mark dependency as optional (won't throw if not found)
+ * Usage: @Optional() @Autowired() private service?: MyService;
+ */
+export function Optional(): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    Reflect.defineMetadata(METADATA_KEYS.OPTIONAL, true, target, propertyKey);
+  };
+}
+
+/**
+ * @Lazy - Lazy load dependency (create on first access)
+ * Usage: @Lazy() @Autowired() private service: MyService;
+ */
+export function Lazy(): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    Reflect.defineMetadata(METADATA_KEYS.LAZY, true, target, propertyKey);
+
+    const type = Reflect.getMetadata("design:type", target, propertyKey);
+
+    // Create a getter that resolves on first access
+    let cached: any = null;
+    let resolved = false;
+
+    Object.defineProperty(target, propertyKey, {
+      get() {
+        if (!resolved) {
+          const { DIContainer } = require("../container/di-container");
+          const container = DIContainer.getInstance();
+          cached = container.resolve(type);
+          resolved = true;
+        }
+        return cached;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  };
+}
+
+/**
+ * @PostConstruct - Method called after dependency injection is complete
+ * Usage: @PostConstruct() init() { ... }
+ */
+export function PostConstruct(): MethodDecorator {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    Reflect.defineMetadata(
+      METADATA_KEYS.POST_CONSTRUCT,
+      propertyKey,
+      target.constructor,
+    );
+  };
+}
+
+/**
+ * @PreDestroy - Method called before bean is destroyed
+ * Usage: @PreDestroy() cleanup() { ... }
+ */
+export function PreDestroy(): MethodDecorator {
+  return (
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ) => {
+    Reflect.defineMetadata(
+      METADATA_KEYS.PRE_DESTROY,
+      propertyKey,
+      target.constructor,
+    );
   };
-}
+}

package/src/core/metadata/metadata-keys.ts

@@ -1,19 +1,45 @@
 export const METADATA_KEYS = {
-  INJECTABLE: 'fragment:injectable',
-  SCOPE: 'fragment:scope',
-  SERVICE: 'fragment:service',
-  CONTROLLER: 'fragment:controller',
-  REPOSITORY: 'fragment:repository',
-  AUTO_CONFIGURATION: 'fragment:auto-configuration',
-  CONDITIONAL_ON_CLASS: 'fragment:conditional-class',
-  CONDITIONAL_ON_MISSING_BEAN: 'fragment:conditional-missing-bean',
-  CONDITIONAL_ON_PROPERTY: 'fragment:conditional-property',
-  AUTOWIRED: 'fragment:autowired',
-  INJECT: 'fragment:inject',
-  QUALIFIER: 'fragment:qualifier',
-  VALUE: 'fragment:value',
-  HTTP_METHOD: 'fragment:http-method',
-  ROUTE_PATH: 'fragment:route-path',
-  PARAM_METADATA: 'fragment:param-metadata',
-  APPLICATION: 'fragment:application'
-};
+  // Class decorators
+  APPLICATION: "fragment:application",
+  INJECTABLE: "fragment:injectable",
+  CONTROLLER: "fragment:controller",
+  SERVICE: "fragment:service",
+  REPOSITORY: "fragment:repository",
+  AUTO_CONFIGURATION: "fragment:auto-configuration",
+  SCOPE: "fragment:scope",
+
+  // Property decorators
+  AUTOWIRED: "fragment:autowired",
+  INJECT: "fragment:inject",
+  INJECT_REPOSITORY: "fragment:inject-repository",
+  QUALIFIER: "fragment:qualifier",
+  VALUE: "fragment:value",
+  OPTIONAL: "fragment:optional",
+  LAZY: "fragment:lazy",
+
+  // Method decorators
+  HTTP_METHOD: "fragment:http-method",
+  ROUTE_PATH: "fragment:route-path",
+  POST_CONSTRUCT: "fragment:post-construct",
+  PRE_DESTROY: "fragment:pre-destroy",
+
+  // Parameter decorators
+  PARAM_METADATA: "fragment:param-metadata",
+
+  // Conditional decorators
+  CONDITIONAL_ON_CLASS: "fragment:conditional-on-class",
+  CONDITIONAL_ON_MISSING_BEAN: "fragment:conditional-on-missing-bean",
+  CONDITIONAL_ON_PROPERTY: "fragment:conditional-on-property",
+  CONDITIONAL_ON_BEAN: "fragment:conditional-on-bean",
+
+  // Middleware & Guards
+  USE_GUARDS: "fragment:use-guards",
+  USE_INTERCEPTORS: "fragment:use-interceptors",
+  USE_FILTERS: "fragment:use-filters",
+
+  // Validation
+  VALIDATE: "fragment:validate",
+  TRANSFORM: "fragment:transform",
+} as const;
+
+export type MetadataKey = (typeof METADATA_KEYS)[keyof typeof METADATA_KEYS];

package/src/index.ts

@@ -19,6 +19,7 @@ export * from "./ai/ai.module";
 export * from "./plugins/plugin-manager";
 export * from "./shared/errors";
 export * from './core/scanner/component-scanner';
+export * from './testing/runner';
 
 export {
   FragmentApplication,

package/src/testing/TEST.md

@@ -0,0 +1,321 @@
+// ============================================
+// user.service.spec.ts
+// Example test file for UserService
+// ============================================
+
+import 'reflect-metadata';
+import { UserService } from './user.service';
+import { UserRepository } from './user.repository';
+import { EmailService } from './email.service';
+import { DIContainer } from 'fragment-ts';
+
+describe('UserService', () => {
+  let userService: UserService;
+  let userRepository: UserRepository;
+  let emailService: EmailService;
+  let container: DIContainer;
+
+  // Setup before each test
+  beforeEach(() => {
+    // Create a fresh DI container for each test
+    container = DIContainer.getInstance();
+    container.reset();
+
+    // Mock dependencies
+    userRepository = {
+      findAll: async () => [],
+      findById: async (id: number) => null,
+      findByEmail: async (email: string) => null,
+      create: async (data: any) => ({ id: 1, ...data }),
+      update: async (id: number, data: any) => null,
+      delete: async (id: number) => true,
+    } as any;
+
+    emailService = {
+      sendWelcomeEmail: async (email: string, name: string) => {},
+      sendPasswordReset: async (email: string, token: string) => {},
+    } as any;
+
+    // Register mocks in container
+    container.register(UserRepository, userRepository);
+    container.register(EmailService, emailService);
+
+    // Create service instance (will auto-inject mocks)
+    userService = container.resolve(UserService);
+  });
+
+  it('should get all users', async () => {
+    const mockUsers = [
+      { id: 1, name: 'John', email: 'john@example.com', isActive: true },
+      { id: 2, name: 'Jane', email: 'jane@example.com', isActive: true },
+    ];
+
+    userRepository.findAll = async () => mockUsers;
+
+    const users = await userService.getAllUsers();
+
+    expect(users).toEqual(mockUsers);
+    expect(users).toHaveLength(2);
+  });
+
+  it('should get user by id', async () => {
+    const mockUser = {
+      id: 1,
+      name: 'John',
+      email: 'john@example.com',
+      isActive: true,
+    };
+
+    userRepository.findById = async (id: number) =>
+      id === 1 ? mockUser : null;
+
+    const user = await userService.getUserById(1);
+
+    expect(user).toEqual(mockUser);
+    expect(user?.name).toBe('John');
+  });
+
+  it('should create user and send welcome email', async () => {
+    const newUser = {
+      name: 'John',
+      email: 'john@example.com',
+    };
+
+    let emailSent = false;
+    emailService.sendWelcomeEmail = async () => {
+      emailSent = true;
+    };
+
+    const user = await userService.createUser(newUser);
+
+    expect(user.name).toBe('John');
+    expect(user.email).toBe('john@example.com');
+    expect(emailSent).toBeTruthy();
+  });
+
+  it('should throw error when creating duplicate email', async () => {
+    const existingUser = {
+      id: 1,
+      name: 'Existing',
+      email: 'test@example.com',
+      isActive: true,
+    };
+
+    userRepository.findByEmail = async (email: string) =>
+      email === 'test@example.com' ? existingUser : null;
+
+    try {
+      await userService.createUser({
+        name: 'New User',
+        email: 'test@example.com',
+      });
+      throw new Error('Should have thrown error');
+    } catch (error: any) {
+      expect(error.message).toContain('already exists');
+    }
+  });
+
+  it('should update user', async () => {
+    const existingUser = {
+      id: 1,
+      name: 'John',
+      email: 'john@example.com',
+      isActive: true,
+    };
+
+    userRepository.findById = async (id: number) =>
+      id === 1 ? existingUser : null;
+    userRepository.update = async (id: number, data: any) => ({
+      ...existingUser,
+      ...data,
+    });
+
+    const updated = await userService.updateUser(1, { name: 'John Updated' });
+
+    expect(updated?.name).toBe('John Updated');
+  });
+
+  it('should delete user', async () => {
+    const existingUser = {
+      id: 1,
+      name: 'John',
+      email: 'john@example.com',
+      isActive: true,
+    };
+
+    userRepository.findById = async (id: number) =>
+      id === 1 ? existingUser : null;
+
+    const deleted = await userService.deleteUser(1);
+
+    expect(deleted).toBeTruthy();
+  });
+
+  it('should throw error when deleting non-existent user', async () => {
+    userRepository.findById = async () => null;
+
+    try {
+      await userService.deleteUser(999);
+      throw new Error('Should have thrown error');
+    } catch (error: any) {
+      expect(error.message).toContain('not found');
+    }
+  });
+
+  it('should request password reset', async () => {
+    const existingUser = {
+      id: 1,
+      name: 'John',
+      email: 'john@example.com',
+      isActive: true,
+    };
+
+    userRepository.findByEmail = async (email: string) =>
+      email === 'john@example.com' ? existingUser : null;
+
+    let resetEmailSent = false;
+    let resetToken = '';
+
+    emailService.sendPasswordReset = async (email: string, token: string) => {
+      resetEmailSent = true;
+      resetToken = token;
+    };
+
+    await userService.requestPasswordReset('john@example.com');
+
+    expect(resetEmailSent).toBeTruthy();
+    expect(resetToken).toBeTruthy();
+  });
+});
+
+// ============================================
+// di-container.spec.ts
+// Example test file for DI Container
+// ============================================
+
+describe('DIContainer', () => {
+  let container: DIContainer;
+
+  beforeEach(() => {
+    container = DIContainer.getInstance();
+    container.reset();
+  });
+
+  it('should resolve singleton instances', () => {
+    class TestService {
+      counter = 0;
+    }
+
+    container.register(TestService);
+
+    const instance1 = container.resolve(TestService);
+    const instance2 = container.resolve(TestService);
+
+    instance1.counter = 5;
+
+    expect(instance2.counter).toBe(5);
+    expect(instance1).toBe(instance2);
+  });
+
+  it('should inject constructor dependencies', () => {
+    @Injectable()
+    class DependencyService {
+      getValue() {
+        return 'dependency';
+      }
+    }
+
+    @Injectable()
+    class TestService {
+      constructor(private dep: DependencyService) {}
+
+      getDepValue() {
+        return this.dep.getValue();
+      }
+    }
+
+    container.register(DependencyService);
+    container.register(TestService);
+
+    const service = container.resolve(TestService);
+
+    expect(service.getDepValue()).toBe('dependency');
+  });
+
+  it('should inject properties with @Autowired', () => {
+    @Injectable()
+    class DependencyService {
+      getValue() {
+        return 'autowired';
+      }
+    }
+
+    @Injectable()
+    class TestService {
+      @Autowired()
+      private dep!: DependencyService;
+
+      getDepValue() {
+        return this.dep.getValue();
+      }
+    }
+
+    container.register(DependencyService);
+    container.register(TestService);
+
+    const service = container.resolve(TestService);
+
+    expect(service.getDepValue()).toBe('autowired');
+  });
+
+  it('should inject values with @Value', () => {
+    process.env.TEST_VALUE = '42';
+
+    @Injectable()
+    class TestService {
+      @Value('${TEST_VALUE}')
+      private value!: number;
+
+      getValue() {
+        return this.value;
+      }
+    }
+
+    container.register(TestService);
+    const service = container.resolve(TestService);
+
+    expect(service.getValue()).toBe(42);
+
+    delete process.env.TEST_VALUE;
+  });
+
+  it('should detect circular dependencies', () => {
+    @Injectable()
+    class ServiceA {
+      constructor(private b: ServiceB) {}
+    }
+
+    @Injectable()
+    class ServiceB {
+      constructor(private a: ServiceA) {}
+    }
+
+    container.register(ServiceA);
+    container.register(ServiceB);
+
+    expect(() => container.resolve(ServiceA)).toThrow('Circular dependency');
+  });
+});
+
+// ============================================
+// Helper functions for testing
+// ============================================
+
+// Mock functions for testing
+global.beforeEach = (fn: () => void) => {
+  // Implement beforeEach hook
+};
+
+global.afterEach = (fn: () => void) => {
+  // Implement afterEach hook
+};