nest-hex 0.2.2 → 0.3.2

package/README.md

@@ -1,172 +1,28 @@
 # nest-hex
 
-> A tiny, **class-based**, **NestJS-native** helper library for building **pluggable adapters** following the Ports & Adapters (Hexagonal Architecture) pattern with minimal boilerplate and great developer experience.
+> A tiny, **class-based**, **NestJS-native** library for building **pluggable adapters** following the Ports & Adapters (Hexagonal Architecture) pattern with minimal boilerplate.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Why Hexagonal Architecture?
+## What is nest-hex?
 
-**Hexagonal Architecture (Ports & Adapters)** is a powerful pattern for building maintainable, testable, and adaptable applications. Here's why it matters:
+**nest-hex** eliminates boilerplate when building NestJS applications with the Ports & Adapters (Hexagonal Architecture) pattern. It provides decorators and base classes that handle all the repetitive wiring, letting you focus on business logic.
 
-### 🎯 Keep Domain Logic Pure
-Your business logic should never depend on infrastructure details like databases, APIs, or file systems. By defining **ports** (interfaces), your domain layer stays clean and focused on what matters: solving business problems.
+### Why Hexagonal Architecture?
 
-### 🔌 Pluggable Infrastructure
-Need to switch from AWS S3 to Google Cloud Storage? Replace MongoDB with PostgreSQL? Change from REST to GraphQL? With hexagonal architecture, you just swap the **adapter** – your domain logic never changes.
-
-### 🧪 Effortless Testing
-Mock external services by creating test adapters. No complex setup, no database connections, no API calls. Just simple, fast unit tests that focus on business logic.
-
-### 🌍 Environment Flexibility
-- **Development**: Use filesystem storage
-- **Testing**: Use in-memory mocks
-- **Production**: Use AWS S3
-
-Same domain code, different adapters. Configure once, swap anywhere.
-
-### 📦 Independent Deployment
-Infrastructure changes don't require redeploying your entire application. Update an adapter independently without touching core business logic.
-
-## Why This Library?
-
-Building NestJS applications with the Ports & Adapters pattern involves repetitive boilerplate:
-
-- Registering concrete implementation classes
-- Aliasing port tokens to implementations (`useExisting`)
-- Exporting only the port token (not provider objects)
-- Supporting both `register()` and `registerAsync()` patterns
-- Keeping the app responsible for configuration (no `process.env` in libraries)
-
-**nest-hex eliminates this boilerplate** while maintaining compile-time type safety and providing a delightful developer experience through both decorators and a powerful CLI.
+- 🧪 **Testable** - Mock infrastructure easily, test business logic in isolation
+- 🔌 **Swappable** - Switch from S3 to Azure Blob Storage without touching domain code
+- 🎯 **Clean** - Keep business logic free of infrastructure concerns
+- 🌍 **Flexible** - Use different adapters for dev, test, and production
 
 ## Features
 
-- 🎯 **Declarative**: Declare port tokens and implementations once using `@Port({ token, implementation })`
-- 🏗️ **Class-based**: Use standard NestJS dynamic modules, no function factories required
-- 🔒 **Type-safe**: `AdapterModule<TToken>` carries compile-time proof of which token it provides
-- ⚡ **Zero runtime overhead**: Uses TypeScript decorators and metadata, minimal abstraction
-- 📦 **Tiny**: Core library is under 1KB minified
-- 🧪 **Testable**: Easily mock adapters for testing
-- 🛠️ **Powerful CLI**: Generate ports, adapters, and services with a single command
-
-## CLI
-
-**nest-hex** includes a powerful CLI to scaffold ports, adapters, and services instantly. No more manual file creation!
-
-### Quick Start
-
-```bash
-# Initialize configuration
-npx nest-hex init
-
-# Generate a port (domain interface)
-npx nest-hex generate port ObjectStorage
-
-# Generate an adapter for the port
-npx nest-hex generate adapter S3 --port ObjectStorage
-
-# Generate both port and adapter together
-npx nest-hex generate full ObjectStorage S3
-
-# Generate a service that uses a port
-npx nest-hex generate service FileUpload
-```
-
-### Available Commands
-
-#### `init`
-Create a `nest-hex.config.ts` configuration file in your project.
-
-```bash
-npx nest-hex init
-```
-
-#### `generate` (or `g`)
-Generate ports, adapters, services, or complete modules.
-
-```bash
-# Generate a port
-npx nest-hex generate port <name>
-npx nest-hex g port PaymentGateway
-
-# Generate an adapter
-npx nest-hex generate adapter <name> --port <portName>
-npx nest-hex g adapter Stripe --port PaymentGateway
-
-# Generate both port and adapter
-npx nest-hex generate full <portName> <adapterName>
-npx nest-hex g full EmailService SendGrid
-
-# Generate a service
-npx nest-hex generate service <name>
-npx nest-hex g service UserRegistration
-```
-
-### Interactive Mode
-
-Run commands without arguments for interactive prompts:
-
-```bash
-npx nest-hex generate
-# → Select type: port, adapter, service, or full
-# → Enter name(s)
-# → Files generated!
-```
-
-### Configuration
-
-The CLI uses `nest-hex.config.ts` to customize output paths and naming conventions:
-
-```typescript
-// nest-hex.config.ts
-import { defineConfig } from 'nest-hex/cli';
-
-export default defineConfig({
-  output: {
-    portsDir: 'src/domain/ports',      // Where to generate ports
-    adaptersDir: 'src/infrastructure', // Where to generate adapters
-    servicesDir: 'src/application',    // Where to generate services
-  },
-  naming: {
-    portSuffix: 'Port',     // ObjectStoragePort
-    tokenSuffix: '_PORT',   // OBJECT_STORAGE_PORT
-    adapterSuffix: 'Adapter', // S3Adapter
-    serviceSuffix: 'Service', // FileUploadService
-  },
-});
-```
-
-### What Gets Generated
-
-#### Port Generation
-Creates a complete port with:
-- Token definition (`OBJECT_STORAGE_PORT`)
-- TypeScript interface with example methods
-- Service implementation with `@InjectPort`
-- Module that accepts adapters
-- Barrel exports (`index.ts`)
-
-#### Adapter Generation
-Creates a production-ready adapter with:
-- Implementation service class
-- Options interface
-- Adapter class with `@Port` decorator
-- Complete TypeScript types
-- Barrel exports
-
-#### Service Generation
-Creates a domain service with:
-- Service class with `@InjectPort` usage
-- Type-safe port injection
-- Example business logic methods
-
-### CLI Benefits
-
-✅ **Instant scaffolding** - Generate complete, type-safe modules in seconds
-✅ **Consistent structure** - All team members follow the same patterns
-✅ **Best practices built-in** - Generated code follows hexagonal architecture principles
-✅ **Customizable** - Configure paths and naming to match your project
-✅ **Interactive** - Friendly prompts guide you through generation
+- 🎯 **Declarative** - Declare port tokens and implementations once using `@Adapter({ portToken, implementation })`
+- 🏗️ **Class-based** - Standard NestJS dynamic modules, no function factories
+- 🔒 **Type-safe** - Compile-time proof that adapters provide the correct port tokens
+- ⚡ **Zero runtime overhead** - Uses TypeScript decorators and metadata
+- 📦 **Tiny** - Core library under 1KB minified
+- 🛠️ **Powerful CLI** - Generate ports, adapters, and services instantly
 
 ## Installation
 
@@ -180,8 +36,7 @@ pnpm add nest-hex
 bun add nest-hex
 ```
 
-### Peer Dependencies
-
+**Peer dependencies:**
 ```bash
 npm install @nestjs/common @nestjs/core reflect-metadata
 ```
@@ -192,11 +47,11 @@ npm install @nestjs/common @nestjs/core reflect-metadata
 
 ```typescript
 // storage.port.ts
-export const STORAGE_PORT = Symbol('STORAGE_PORT');
+export const STORAGE_PORT = Symbol('STORAGE_PORT')
 
 export interface StoragePort {
-  upload(file: Buffer, key: string): Promise<{ url: string }>;
-  download(key: string): Promise<Buffer>;
+  upload(key: string, data: Buffer): Promise<string>
+  download(key: string): Promise<Buffer>
 }
 ```
 
@@ -204,103 +59,116 @@ export interface StoragePort {
 
 ```typescript
 // s3.adapter.ts
-import { Injectable } from '@nestjs/common';
-import { Adapter, Port } from 'nest-hex';
-import { STORAGE_PORT, type StoragePort } from './storage.port';
+import { Injectable } from '@nestjs/common'
+import { Adapter } from 'nest-hex'
+import { STORAGE_PORT, type StoragePort } from './storage.port'
 
 // Implementation service
 @Injectable()
-class S3StorageService implements StoragePort {
-  async upload(file: Buffer, key: string) {
+class S3Service implements StoragePort {
+  constructor(private options: { bucket: string; region: string }) {}
+
+  async upload(key: string, data: Buffer): Promise<string> {
     // AWS S3 upload logic here
-    return { url: `https://s3.amazonaws.com/bucket/${key}` };
+    return `https://s3.amazonaws.com/${this.options.bucket}/${key}`
   }
 
-  async download(key: string) {
+  async download(key: string): Promise<Buffer> {
     // AWS S3 download logic here
-    return Buffer.from('file contents');
+    return Buffer.from('file contents')
   }
 }
 
-// Adapter configuration
-interface S3Options {
-  bucket: string;
-  region: string;
-  accessKeyId?: string;
-  secretAccessKey?: string;
-}
-
 // Adapter module - single decorator declares everything!
-@Port({
-  token: STORAGE_PORT,
-  implementation: S3StorageService,
+@Adapter({
+  portToken: STORAGE_PORT,
+  implementation: S3Service
 })
-export class S3Adapter extends Adapter<S3Options> {}
+export class S3Adapter extends AdapterBase<{ bucket: string; region: string }> {}
 ```
 
-### 3. Create a Port Module (Domain Service)
+### 3. Create a Domain Service
 
 ```typescript
-// storage.module.ts
-import { Injectable, Module } from '@nestjs/common';
-import { InjectPort, PortModule } from 'nest-hex';
-import { STORAGE_PORT, type StoragePort } from './storage.port';
+// file.service.ts
+import { Injectable } from '@nestjs/common'
+import { InjectPort } from 'nest-hex'
+import { STORAGE_PORT, type StoragePort } from './storage.port'
 
-// Domain service that uses the port
 @Injectable()
-export class StorageService {
+export class FileService {
   constructor(
     @InjectPort(STORAGE_PORT)
-    private readonly storage: StoragePort,
+    private readonly storage: StoragePort
   ) {}
 
-  async uploadUserAvatar(userId: string, image: Buffer) {
-    const key = `avatars/${userId}.jpg`;
-    return this.storage.upload(image, key);
-  }
-
-  async downloadUserAvatar(userId: string) {
-    const key = `avatars/${userId}.jpg`;
-    return this.storage.download(key);
+  async uploadUserAvatar(userId: string, image: Buffer): Promise<string> {
+    const key = `avatars/${userId}.jpg`
+    return this.storage.upload(key, image)
   }
 }
+```
+
+### 4. Create a Port Module
+
+```typescript
+// file.module.ts
+import { Module } from '@nestjs/common'
+import { PortModule } from 'nest-hex'
+import { FileService } from './file.service'
 
-// Port module that accepts any adapter
 @Module({})
-export class StorageModule extends PortModule<typeof StorageService> {}
+export class FileModule extends PortModule<typeof FileService> {}
 ```
 
-### 4. Wire It Up in Your App
+### 5. Wire It Up
 
 ```typescript
 // app.module.ts
-import { Module } from '@nestjs/common';
-import { StorageModule } from './storage/storage.module';
-import S3Adapter from './storage/adapters/s3.adapter';
+import { Module } from '@nestjs/common'
+import { FileModule } from './file.module'
+import { S3Adapter } from './s3.adapter'
 
 @Module({
   imports: [
-    StorageModule.register({
+    FileModule.register({
       adapter: S3Adapter.register({
-        bucket: 'my-app-uploads',
-        region: 'us-east-1',
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-      }),
-    }),
-  ],
+        bucket: process.env.S3_BUCKET || 'my-bucket',
+        region: process.env.AWS_REGION || 'us-east-1'
+      })
+    })
+  ]
 })
 export class AppModule {}
 ```
 
 That's it! You now have a fully type-safe, pluggable storage adapter. 🎉
 
+## CLI
+
+Generate ports, adapters, and services instantly with the built-in CLI:
+
+```bash
+# Initialize configuration
+npx nest-hex init
+
+# Generate a port (domain interface)
+npx nest-hex generate port ObjectStorage
+
+# Generate an adapter for the port
+npx nest-hex generate adapter S3 --port ObjectStorage
+
+# Or generate both at once
+npx nest-hex generate full ObjectStorage S3
+```
+
+**See [CLI Documentation](./docs/cli.md) for complete command reference, configuration options, and template customization.**
+
 ## Key Benefits
 
 ### Before (Manual Boilerplate)
 
 ```typescript
-// Lots of manual wiring...
 @Module({})
 export class S3StorageModule {
   static register(options: S3Options): DynamicModule {
@@ -312,7 +180,7 @@ export class S3StorageModule {
         // More boilerplate...
       ],
       exports: [STORAGE_PORT],
-    };
+    }
   }
 }
 ```
@@ -320,267 +188,109 @@ export class S3StorageModule {
 ### After (With nest-hex)
 
 ```typescript
-// Clean and declarative!
-@Port({
-  token: STORAGE_PORT,
-  implementation: S3StorageService,
+@Adapter({
+  portToken: STORAGE_PORT,
+  implementation: S3StorageService
 })
-export class S3Adapter extends Adapter<S3Options> {}
+export class S3Adapter extends AdapterBase<S3Options> {}
 ```
 
-## Advanced Usage
+## Swappable Infrastructure
 
-### Async Registration with Dependency Injection
+The real power: swap infrastructure without touching business logic.
 
 ```typescript
-import { ConfigModule, ConfigService } from '@nestjs/config';
+// Development: Use local filesystem
+const adapter = process.env.NODE_ENV === 'production'
+  ? S3Adapter.register({ bucket: 'prod-bucket', region: 'us-east-1' })
+  : LocalStorageAdapter.register({ basePath: './uploads' })
 
 @Module({
-  imports: [
-    StorageModule.register({
-      adapter: S3Adapter.registerAsync({
-        imports: [ConfigModule],
-        inject: [ConfigService],
-        useFactory: (config: ConfigService) => ({
-          bucket: config.get('S3_BUCKET'),
-          region: config.get('AWS_REGION'),
-          accessKeyId: config.get('AWS_ACCESS_KEY_ID'),
-          secretAccessKey: config.get('AWS_SECRET_ACCESS_KEY'),
-        }),
-      }),
-    }),
-  ],
+  imports: [FileModule.register({ adapter })]
 })
 export class AppModule {}
 ```
 
-### Custom Imports and Extra Ports
-
-```typescript
-@Port({
-  token: HTTP_CLIENT_PORT,
-  implementation: AxiosHttpClient,
-})
-class AxiosAdapterClass extends Adapter<AxiosOptions> {
-  protected override imports(options: AxiosOptions) {
-    return [
-      HttpModule.register({
-        baseURL: options.baseUrl,
-        timeout: options.timeout,
-      }),
-    ];
-  }
-
-  protected override extraPoviders(options: AxiosOptions) {
-    return [
-      {
-        provide: 'HTTP_CLIENT_CONFIG',
-        useValue: options,
-      },
-    ];
-  }
-}
-```
-
-### Swapping Adapters - The Power of Pluggability
+Your `FileService` business logic **never changes**. Only the adapter changes.
 
-**This is the core benefit of hexagonal architecture**: swap infrastructure without touching business logic.
+## Advanced Features
 
-#### Environment-Based Swapping
+### Async Configuration with Dependency Injection
 
 ```typescript
-// Development: Use filesystem storage
-import FilesystemAdapter from './storage/adapters/filesystem.adapter';
-
-// Production: Use AWS S3
-import S3Adapter from './storage/adapters/s3.adapter';
-
-const adapter = process.env.NODE_ENV === 'production'
-  ? S3Adapter.register({ bucket: 'prod-bucket', region: 'us-east-1' })
-  : FilesystemAdapter.register({ basePath: './uploads' });
-
 @Module({
   imports: [
-    StorageModule.register({ adapter }),
-  ],
+    FileModule.register({
+      adapter: S3Adapter.registerAsync({
+        imports: [ConfigModule],
+        inject: [ConfigService],
+        useFactory: (config: ConfigService) => ({
+          bucket: config.get('S3_BUCKET')!,
+          region: config.get('AWS_REGION')!
+        })
+      })
+    })
+  ]
 })
 export class AppModule {}
 ```
 
-#### Multi-Cloud Strategy
-
-```typescript
-// Easily switch cloud providers without changing domain code
-const storageAdapter = process.env.CLOUD_PROVIDER === 'aws'
-  ? S3Adapter.register({ bucket: 'my-bucket', region: 'us-east-1' })
-  : process.env.CLOUD_PROVIDER === 'gcp'
-  ? GCSAdapter.register({ bucket: 'my-bucket' })
-  : AzureBlobAdapter.register({ containerName: 'my-container' });
-```
-
-#### Feature Flags
-
-```typescript
-// Gradually migrate to new infrastructure
-const emailAdapter = featureFlags.useNewEmailProvider
-  ? SendGridAdapter.register({ apiKey: process.env.SENDGRID_KEY })
-  : SESAdapter.register({ region: 'us-east-1' });
-```
-
-#### Testing with Mocks
+### Adapters with Dependencies
 
 ```typescript
-// Test module: in-memory mock
-const testAdapter = MockStorageAdapter.register();
-
-// Production module: real infrastructure
-const prodAdapter = S3Adapter.register({ bucket: 'prod' });
-
-// Same domain code, different runtime behavior
+@Adapter({
+  portToken: HTTP_CLIENT_PORT,
+  implementation: AxiosHttpClient,
+  imports: [HttpModule],
+  providers: [
+    { provide: 'HTTP_CONFIG', useValue: { timeout: 5000 } }
+  ]
+})
+export class AxiosAdapter extends AdapterBase<AxiosOptions> {}
 ```
 
-**Key Point**: Your `StorageService` business logic **never changes**. Only the infrastructure adapter changes. This is the essence of maintainable architecture.
-
-### Testing with Mock Adapters
+### Mock Adapters for Testing
 
 ```typescript
-import { Adapter, Port } from 'nest-hex';
-
-class MockStorageService {
-  async upload(file: Buffer, key: string) {
-    return { url: `mock://storage/${key}` };
+@Injectable()
+class MockStorageService implements StoragePort {
+  async upload(key: string, data: Buffer): Promise<string> {
+    return `mock://storage/${key}`
   }
-
-  async download(key: string) {
-    return Buffer.from('mock file contents');
+  async download(key: string): Promise<Buffer> {
+    return Buffer.from('mock data')
   }
 }
 
-@Port({
-  token: STORAGE_PORT,
-  implementation: MockStorageService,
+@Adapter({
+  portToken: STORAGE_PORT,
+  implementation: MockStorageService
 })
-export class MockStorageAdapter extends Adapter<void> {}
+export class MockStorageAdapter extends AdapterBase<{}> {}
 
 // Use in tests
 const module = await Test.createTestingModule({
   imports: [
-    StorageModule.register({
-      adapter: MockStorageAdapter.register(undefined),
-    }),
-  ],
-}).compile();
-```
-
-## API Reference
-
-### Core Classes
-
-#### `Adapter<TOptions>`
-
-Abstract base class for building adapter modules.
-
-**Methods:**
-- `static register<TToken, TOptions>(options: TOptions): AdapterModule<TToken>` - Synchronous registration
-- `static registerAsync<TToken, TOptions>(config: AsyncConfig): AdapterModule<TToken>` - Async registration with DI
-
-**Protected Hooks:**
-- `protected imports(options?: TOptions): unknown[]` - Override to import other NestJS modules
-- `protected extraPoviders(options: TOptions): Port[]` - Override to add additional providers
-
-#### `PortModule<TService>`
-
-Abstract base class for building port modules that consume adapters.
-
-**Methods:**
-- `static register<TToken>({ adapter }: { adapter?: AdapterModule<TToken> }): DynamicModule`
-
-### Decorators
-
-#### `@Port({ token, implementation })`
-
-Class decorator that declares which port token an adapter provides and its implementation class.
-
-**Parameters:**
-- `token: TToken` - The port token (usually a Symbol)
-- `implementation: Type<unknown>` - The concrete implementation class
-
-**Example:**
-```typescript
-@Port({
-  token: STORAGE_PORT,
-  implementation: S3StorageService,
-})
-class S3Adapter extends Adapter<S3Options> {}
-```
-
-#### `@InjectPort(token)`
-
-Parameter decorator for injecting a port token into service constructors.
-
-**Example:**
-```typescript
-constructor(
-  @InjectPort(STORAGE_PORT)
-  private readonly storage: StoragePort,
-) {}
+    FileModule.register({
+      adapter: MockStorageAdapter.register({})
+    })
+  ]
+}).compile()
 ```
 
-### Types
-
-#### `AdapterModule<TToken>`
-
-A DynamicModule that carries compile-time proof it provides `TToken`.
-
-```typescript
-type AdapterModule<TToken> = DynamicModule & {
-  __provides: TToken;
-};
-```
-
-## Best Practices
-
-### ✅ Do's
-
-- **Export port tokens, not provider objects**
-  ```typescript
-  exports: [STORAGE_PORT]  // ✅ Correct
-  ```
-
-- **Keep configuration in the app layer**
-  ```typescript
-  // ✅ Good: App provides config
-  S3Adapter.register({
-    bucket: process.env.S3_BUCKET,
-  })
-  ```
-
-- **Use `@InjectPort` for clarity**
-  ```typescript
-  @InjectPort(STORAGE_PORT)  // ✅ Clear intent
-  ```
-
-- **Create small, focused adapters**
-  - One adapter = one infrastructure concern
-
-### ❌ Don'ts
-
-- **Don't export provider objects**
-  ```typescript
-  exports: [{ provide: STORAGE_PORT, useExisting: S3Service }]  // ❌ Wrong
-  ```
+## Documentation
 
-- **Don't use `process.env` in adapters**
-  ```typescript
-  // ❌ Bad: Config hard-coded in adapter
-  class S3Adapter {
-    bucket = process.env.S3_BUCKET;
-  }
-  ```
+📚 **Complete Documentation:**
+- **[Library Documentation](./docs/library.md)** - Full API reference, architecture guide, advanced patterns, and examples
+- **[CLI Documentation](./docs/cli.md)** - Complete CLI reference, configuration, templates, and best practices
 
-- **Don't mix domain logic with adapters**
-  - Adapters = infrastructure only
-  - Domain logic = port modules/services
+📖 **Quick Links:**
+- [Core Concepts](./docs/library.md#core-concepts) - Understand ports, adapters, and services
+- [Why Hexagonal Architecture?](./docs/library.md#why-hexagonal-architecture) - Benefits with code examples
+- [Architecture Overview](./docs/library.md#architecture-overview) - Visual diagrams
+- [API Reference](./docs/library.md#api-reference) - Complete API documentation
+- [Testing Guide](./docs/library.md#testing) - Mock adapters and integration testing
+- [Migration Guide](./docs/library.md#migration-guide) - Upgrading from @Port to @Adapter
 
 ## Examples
 
@@ -588,17 +298,16 @@ See the [`examples/`](./examples) directory for complete working examples:
 
 - **Object Storage** - S3 adapter with file upload/download
 - **Currency Rates** - HTTP API adapter with rate conversion
-- **Basic Examples** - Decorator usage patterns
-
-## Documentation
-
-- 📖 [Full Specification](./spec/spec.md) - Complete implementation guide with AWS S3 and HTTP API examples
-- 🔧 [API Reference](#api-reference) - Detailed API documentation
+- **Mock Patterns** - Testing with mock adapters
 
 ## License
 
-MIT
+MIT © [Your Name]
 
 ## Contributing
 
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our code of conduct and development process.
+
+---
+
+**Built with ❤️ for the NestJS community**

package/dist/src/cli/bin.js

@@ -1156,7 +1156,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path3 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;
@@ -1483,7 +1483,11 @@ function Confirm({
 // src/cli/ui/components/FileProgress.tsx
 var import_ink3 = require("ink");
 var jsx_dev_runtime3 = __toESM(require_jsx_dev_runtime(), 1);
-function FileProgress({ fileName, status, error }) {
+function FileProgress({
+  fileName,
+  status,
+  error
+}) {
   const getStatusIcon = () => {
     switch (status) {
       case "completed":
@@ -1558,7 +1562,11 @@ function FileProgress({ fileName, status, error }) {
 var import_ui3 = require("@inkjs/ui");
 var import_ink4 = require("ink");
 var jsx_dev_runtime4 = __toESM(require_jsx_dev_runtime(), 1);
-function NameInput({ type, step, onSubmit }) {
+function NameInput({
+  type,
+  step,
+  onSubmit
+}) {
   if (type === "full") {
     const currentStep = step || "port";
     const labels = {
@@ -1649,7 +1657,10 @@ function NameInput({ type, step, onSubmit }) {
 var import_ui4 = require("@inkjs/ui");
 var import_ink5 = require("ink");
 var jsx_dev_runtime5 = __toESM(require_jsx_dev_runtime(), 1);
-function PortSelector({ ports, onSubmit }) {
+function PortSelector({
+  ports,
+  onSubmit
+}) {
   if (ports.length === 0) {
     return /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(import_ink5.Box, {
       flexDirection: "column",
@@ -1734,7 +1745,10 @@ function PortSelector({ ports, onSubmit }) {
 var import_ui5 = require("@inkjs/ui");
 var import_ink6 = require("ink");
 var jsx_dev_runtime6 = __toESM(require_jsx_dev_runtime(), 1);
-function ProgressIndicator({ steps, title }) {
+function ProgressIndicator({
+  steps,
+  title
+}) {
   return /* @__PURE__ */ jsx_dev_runtime6.jsxDEV(import_ink6.Box, {
     flexDirection: "column",
     paddingY: 1,

package/dist/src/cli/commands/index.js

@@ -1155,7 +1155,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path3 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;
@@ -1482,7 +1482,11 @@ function Confirm({
 // src/cli/ui/components/FileProgress.tsx
 var import_ink3 = require("ink");
 var jsx_dev_runtime3 = __toESM(require_jsx_dev_runtime(), 1);
-function FileProgress({ fileName, status, error }) {
+function FileProgress({
+  fileName,
+  status,
+  error
+}) {
   const getStatusIcon = () => {
     switch (status) {
       case "completed":
@@ -1557,7 +1561,11 @@ function FileProgress({ fileName, status, error }) {
 var import_ui3 = require("@inkjs/ui");
 var import_ink4 = require("ink");
 var jsx_dev_runtime4 = __toESM(require_jsx_dev_runtime(), 1);
-function NameInput({ type, step, onSubmit }) {
+function NameInput({
+  type,
+  step,
+  onSubmit
+}) {
   if (type === "full") {
     const currentStep = step || "port";
     const labels = {
@@ -1648,7 +1656,10 @@ function NameInput({ type, step, onSubmit }) {
 var import_ui4 = require("@inkjs/ui");
 var import_ink5 = require("ink");
 var jsx_dev_runtime5 = __toESM(require_jsx_dev_runtime(), 1);
-function PortSelector({ ports, onSubmit }) {
+function PortSelector({
+  ports,
+  onSubmit
+}) {
   if (ports.length === 0) {
     return /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(import_ink5.Box, {
       flexDirection: "column",
@@ -1733,7 +1744,10 @@ function PortSelector({ ports, onSubmit }) {
 var import_ui5 = require("@inkjs/ui");
 var import_ink6 = require("ink");
 var jsx_dev_runtime6 = __toESM(require_jsx_dev_runtime(), 1);
-function ProgressIndicator({ steps, title }) {
+function ProgressIndicator({
+  steps,
+  title
+}) {
   return /* @__PURE__ */ jsx_dev_runtime6.jsxDEV(import_ink6.Box, {
     flexDirection: "column",
     paddingY: 1,

package/dist/src/cli/generators/adapter.generator.js

@@ -237,7 +237,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path2 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;

package/dist/src/cli/generators/base.generator.js

@@ -237,7 +237,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path2 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;

package/dist/src/cli/generators/index.d.ts

@@ -193,6 +193,22 @@ declare abstract class BaseGenerator {
 	protected generateFiles(files: FileToGenerate[], dryRun?: boolean): Promise<string[]>;
 }
 /**
+* Generator for creating port files.
+*
+* Generates:
+* - Port interface (domain contract)
+* - Port token (dependency injection token)
+* - Port service (optional - domain service using the port)
+* - Port module (optional - feature module wrapper)
+* - Index file (barrel exports)
+*/
+declare class PortGenerator extends BaseGenerator {
+	/**
+	* Generate all port files.
+	*/
+	generate(options: GeneratorOptions): Promise<GeneratorResult>;
+}
+/**
 * Additional options for adapter generation.
 */
 interface AdapterGeneratorOptions extends GeneratorOptions {
@@ -233,22 +249,6 @@ declare class AdapterGenerator extends BaseGenerator {
 	generate(options: AdapterGeneratorOptions): Promise<GeneratorResult>;
 }
 /**
-* Generator for creating port files.
-*
-* Generates:
-* - Port interface (domain contract)
-* - Port token (dependency injection token)
-* - Port service (optional - domain service using the port)
-* - Port module (optional - feature module wrapper)
-* - Index file (barrel exports)
-*/
-declare class PortGenerator extends BaseGenerator {
-	/**
-	* Generate all port files.
-	*/
-	generate(options: GeneratorOptions): Promise<GeneratorResult>;
-}
-/**
 * Generator for creating standalone services.
 *
 * Generates:

package/dist/src/cli/generators/index.js

@@ -237,7 +237,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path2 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;

package/dist/src/cli/generators/port.generator.js

@@ -237,7 +237,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path2 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;

package/dist/src/cli/generators/service.generator.js

@@ -237,7 +237,7 @@ __export(exports_base_generator, {
 });
 module.exports = __toCommonJS(exports_base_generator);
 var import_node_path2 = require("node:path");
-var __dirname = "C:\\Users\\liorv\\OneDrive\\Desktop\\Projects\\Personal\\nestjs-adapter\\src\\cli\\generators";
+var __dirname = "/home/runner/work/nest-hex/nest-hex/src/cli/generators";
 
 class BaseGenerator {
   config;

package/dist/src/cli/ui/components/index.d.ts

@@ -1,3 +1,15 @@
+interface PortInfo {
+	/** Port name in kebab-case (e.g., 'object-storage') */
+	name: string;
+	/** Port name in PascalCase (e.g., 'ObjectStorage') */
+	pascalName: string;
+	/** Token name (e.g., 'OBJECT_STORAGE_PORT') */
+	tokenName: string;
+	/** Relative import path from adapter to port token file */
+	tokenImportPath: string;
+	/** Absolute path to port directory */
+	portPath: string;
+}
 interface ComponentOption {
 	value: string;
 	label: string;
@@ -39,18 +51,6 @@ interface NameInputProps {
 * Name input for component generation.
 */
 declare function NameInput({ type, step, onSubmit }: NameInputProps): JSX.Element;
-interface PortInfo {
-	/** Port name in kebab-case (e.g., 'object-storage') */
-	name: string;
-	/** Port name in PascalCase (e.g., 'ObjectStorage') */
-	pascalName: string;
-	/** Token name (e.g., 'OBJECT_STORAGE_PORT') */
-	tokenName: string;
-	/** Relative import path from adapter to port token file */
-	tokenImportPath: string;
-	/** Absolute path to port directory */
-	portPath: string;
-}
 interface PortSelectorProps {
 	ports: PortInfo[];
 	onSubmit: (portInfo: PortInfo) => void;

package/dist/src/cli/ui/components/index.js

@@ -1037,7 +1037,11 @@ function Confirm({
 // src/cli/ui/components/FileProgress.tsx
 var import_ink3 = require("ink");
 var jsx_dev_runtime3 = __toESM(require_jsx_dev_runtime(), 1);
-function FileProgress({ fileName, status, error }) {
+function FileProgress({
+  fileName,
+  status,
+  error
+}) {
   const getStatusIcon = () => {
     switch (status) {
       case "completed":
@@ -1112,7 +1116,11 @@ function FileProgress({ fileName, status, error }) {
 var import_ui3 = require("@inkjs/ui");
 var import_ink4 = require("ink");
 var jsx_dev_runtime4 = __toESM(require_jsx_dev_runtime(), 1);
-function NameInput({ type, step, onSubmit }) {
+function NameInput({
+  type,
+  step,
+  onSubmit
+}) {
   if (type === "full") {
     const currentStep = step || "port";
     const labels = {
@@ -1203,7 +1211,10 @@ function NameInput({ type, step, onSubmit }) {
 var import_ui4 = require("@inkjs/ui");
 var import_ink5 = require("ink");
 var jsx_dev_runtime5 = __toESM(require_jsx_dev_runtime(), 1);
-function PortSelector({ ports, onSubmit }) {
+function PortSelector({
+  ports,
+  onSubmit
+}) {
   if (ports.length === 0) {
     return /* @__PURE__ */ jsx_dev_runtime5.jsxDEV(import_ink5.Box, {
       flexDirection: "column",
@@ -1288,7 +1299,10 @@ function PortSelector({ ports, onSubmit }) {
 var import_ui5 = require("@inkjs/ui");
 var import_ink6 = require("ink");
 var jsx_dev_runtime6 = __toESM(require_jsx_dev_runtime(), 1);
-function ProgressIndicator({ steps, title }) {
+function ProgressIndicator({
+  steps,
+  title
+}) {
   return /* @__PURE__ */ jsx_dev_runtime6.jsxDEV(import_ink6.Box, {
     flexDirection: "column",
     paddingY: 1,

package/dist/src/index.d.ts

@@ -30,31 +30,43 @@ type PortConfig<
 *
 * Adapters are dynamic modules that provide a port token and hide infrastructure details.
 * This base class automatically handles provider registration, token aliasing, and exports
-* by reading metadata from the @Port decorator.
+* by reading metadata from the @Adapter decorator.
 *
 * @template TOptions - The options type for configuring this adapter
 *
 * @example
+* Basic adapter with decorator options:
 * ```typescript
-* @Port({
-*   token: STORAGE_PORT,
+* @Adapter({
+*   portToken: STORAGE_PORT,
+*   implementation: S3Service,
+*   imports: [HttpModule],
+*   providers: [{ provide: 'CONFIG', useValue: {...} }]
+* })
+* class S3Adapter extends AdapterBase<S3Options> {}
+* ```
+*
+* Advanced adapter with dynamic configuration:
+* ```typescript
+* @Adapter({
+*   portToken: STORAGE_PORT,
 *   implementation: S3Service
 * })
-* class S3Adapter extends Adapter<S3Options> {
-*   protected override imports(options: S3Options) {
-*     return []; // Optional: import other modules
+* class S3Adapter extends AdapterBase<S3Options> {
+*   protected imports(options: S3Options) {
+*     return [HttpModule.register({ timeout: options.timeout })]
 *   }
 *
-*   protected override extraPoviders(options: S3Options) {
-*     return []; // Optional: additional providers
+*   protected extraProviders(options: S3Options) {
+*     return [{ provide: 'S3_CONFIG', useValue: options }]
 *   }
 * }
 * ```
 */
-declare class Adapter<TOptions> {
+declare class AdapterBase<TOptions> {
 	/**
 	* Optional hook to import other NestJS modules.
-	* Override this method to add module dependencies.
+	* Override this method to add module dependencies based on options.
 	*
 	* @param _options - The adapter configuration options
 	* @returns Array of modules to import
@@ -62,31 +74,31 @@ declare class Adapter<TOptions> {
 	protected imports(_options?: TOptions): unknown[];
 	/**
 	* Optional hook to provide additional providers.
-	* Override this method to add helper services, factories, or initialization logic.
+	* Override this method to add helper services, factories, or initialization logic based on options.
 	*
 	* @param _options - The adapter configuration options
 	* @returns Array of additional providers
 	*/
-	protected extraPoviders(_options: TOptions): Provider[];
+	protected extraProviders(_options: TOptions): Provider[];
 	/**
 	* Synchronous registration method.
 	* Creates a dynamic module with the adapter's port token and implementation.
 	*
 	* @param options - The adapter configuration options
 	* @returns An AdapterModule with compile-time token proof
-	* @throws Error if @Port decorator is missing or incomplete
+	* @throws Error if @Adapter decorator is missing or incomplete
 	*/
 	static register<
 		TToken,
 		TOptions
-	>(this: new () => Adapter<TOptions>, options: TOptions): AdapterModule<TToken>;
+	>(this: new () => AdapterBase<TOptions>, options: TOptions): AdapterModule<TToken>;
 	/**
 	* Asynchronous registration method with dependency injection support.
 	* Creates a dynamic module where options are resolved via DI.
 	*
 	* @param options - Async configuration with factory, imports, and inject
 	* @returns An AdapterModule with compile-time token proof
-	* @throws Error if @Port decorator is missing or incomplete
+	* @throws Error if @Adapter decorator is missing or incomplete
 	*
 	* @example
 	* ```typescript
@@ -100,35 +112,53 @@ declare class Adapter<TOptions> {
 	static registerAsync<
 		TToken,
 		TOptions
-	>(this: new () => Adapter<TOptions>, options: {
+	>(this: new () => AdapterBase<TOptions>, options: {
 		imports?: unknown[];
 		inject?: unknown[];
 		useFactory: (...args: unknown[]) => TOptions | Promise<TOptions>;
 	}): AdapterModule<TToken>;
 }
-import { Type } from "@nestjs/common";
+import { DynamicModule as DynamicModule2, Provider as Provider2, Type } from "@nestjs/common";
 /**
-* Declares the port configuration for an adapter (token and implementation).
+* Declares the adapter configuration (port token, implementation, imports, and extra providers).
 *
-* This decorator stores both the port token and implementation class in metadata,
-* which is read at runtime by the Adapter base class's register() and registerAsync() methods.
+* This decorator stores the port token, implementation class, optional imports, and
+* optional extra providers in metadata, which is read at runtime by the Adapter base
+* class's register() and registerAsync() methods.
 *
-* @param config - Port configuration object
-* @param config.token - The port token this adapter provides
+* @param config - Adapter configuration object
+* @param config.portToken - The port token this adapter provides
 * @param config.implementation - The concrete implementation class that provides the port functionality
+* @param config.imports - Optional array of NestJS modules to import (module classes or DynamicModule objects)
+* @param config.providers - Optional array of additional providers to register
 *
 * @example
+* Basic adapter:
 * ```typescript
-* @Port({
-*   token: OBJECT_STORAGE_PORT,
+* @Adapter({
+*   portToken: OBJECT_STORAGE_PORT,
 *   implementation: S3ObjectStorageService
 * })
-* class S3Adapter extends Adapter<S3Options> {}
+* class S3Adapter extends AdapterBase<S3Options> {}
+* ```
+*
+* @example
+* Adapter with imports and extra providers:
+* ```typescript
+* @Adapter({
+*   portToken: HTTP_CLIENT_PORT,
+*   implementation: AxiosHttpClient,
+*   imports: [HttpModule],
+*   providers: [{ provide: 'HTTP_CONFIG', useValue: { timeout: 5000 } }]
+* })
+* class AxiosAdapter extends AdapterBase<AxiosOptions> {}
 * ```
 */
-declare function Port2<C extends PortConfig<any, any>>(config: {
-	token: C["token"];
+declare function Adapter<C extends PortConfig<any, any>>(config: {
+	portToken: C["token"];
 	implementation: Type<C["port"]>;
+	imports?: Array<Type<any> | DynamicModule2 | Promise<DynamicModule2>>;
+	providers?: Provider2[];
 }): ClassDecorator;
 /**
 * DX decorator for injecting a port token into service constructors.
@@ -148,7 +178,7 @@ declare function Port2<C extends PortConfig<any, any>>(config: {
 * ```
 */
 declare function InjectPort<TToken>(token: TToken): ParameterDecorator;
-import { DynamicModule as DynamicModule2 } from "@nestjs/common";
+import { DynamicModule as DynamicModule3 } from "@nestjs/common";
 declare class PortModule<_TService> {
 	/**
 	* Registers the port module with an adapter.
@@ -159,6 +189,6 @@ declare class PortModule<_TService> {
 	*/
 	static register<TToken>({ adapter }: {
 		adapter?: AdapterModule<TToken>;
-	}): DynamicModule2;
+	}): DynamicModule3;
 }
-export { PortModule, PortConfig, Port2 as Port, InjectPort, AdapterModule, Adapter };
+export { PortModule, PortConfig, InjectPort, AdapterModule, AdapterBase, Adapter };

package/dist/src/index.js

@@ -55,8 +55,8 @@ var __legacyDecorateClassTS = function(decorators, target, key, desc) {
 var exports_src = {};
 __export(exports_src, {
   PortModule: () => PortModule,
-  Port: () => Port,
   InjectPort: () => InjectPort,
+  AdapterBase: () => AdapterBase,
   Adapter: () => Adapter
 });
 module.exports = __toCommonJS(exports_src);
@@ -67,32 +67,37 @@ var import_reflect_metadata = require("reflect-metadata");
 // src/core/constants.ts
 var PORT_TOKEN_METADATA = Symbol("PORT_TOKEN_METADATA");
 var PORT_IMPLEMENTATION_METADATA = Symbol("PORT_IMPLEMENTATION_METADATA");
+var ADAPTER_IMPORTS_METADATA = Symbol("ADAPTER_IMPORTS_METADATA");
+var ADAPTER_PROVIDERS_METADATA = Symbol("ADAPTER_PROVIDERS_METADATA");
 
 // src/core/adapter.base.ts
-class Adapter {
+class AdapterBase {
   imports(_options) {
     return [];
   }
-  extraPoviders(_options) {
+  extraProviders(_options) {
     return [];
   }
   static register(options) {
     const instance = new this;
     const token = Reflect.getMetadata(PORT_TOKEN_METADATA, this);
     const implementation = Reflect.getMetadata(PORT_IMPLEMENTATION_METADATA, this);
+    const decoratorImports = Reflect.getMetadata(ADAPTER_IMPORTS_METADATA, this) ?? [];
+    const decoratorProviders = Reflect.getMetadata(ADAPTER_PROVIDERS_METADATA, this) ?? [];
     if (!token) {
-      throw new Error(`${this.name} must be decorated with @Port() and specify 'token'`);
+      throw new Error(`${this.name} must be decorated with @Adapter() and specify 'portToken'`);
     }
     if (!implementation) {
-      throw new Error(`${this.name} must be decorated with @Port() and specify 'implementation'`);
+      throw new Error(`${this.name} must be decorated with @Adapter() and specify 'implementation'`);
     }
     return {
       module: this,
-      imports: instance.imports(options),
+      imports: [...decoratorImports, ...instance.imports(options)],
       providers: [
         implementation,
         { provide: token, useExisting: implementation },
-        ...instance.extraPoviders(options)
+        ...decoratorProviders,
+        ...instance.extraProviders(options)
       ],
       exports: [token],
       __provides: token
@@ -102,19 +107,26 @@ class Adapter {
     const instance = new this;
     const token = Reflect.getMetadata(PORT_TOKEN_METADATA, this);
     const implementation = Reflect.getMetadata(PORT_IMPLEMENTATION_METADATA, this);
+    const decoratorImports = Reflect.getMetadata(ADAPTER_IMPORTS_METADATA, this) ?? [];
+    const decoratorProviders = Reflect.getMetadata(ADAPTER_PROVIDERS_METADATA, this) ?? [];
     if (!token) {
-      throw new Error(`${this.name} must be decorated with @Port() and specify 'token'`);
+      throw new Error(`${this.name} must be decorated with @Adapter() and specify 'portToken'`);
     }
     if (!implementation) {
-      throw new Error(`${this.name} must be decorated with @Port() and specify 'implementation'`);
+      throw new Error(`${this.name} must be decorated with @Adapter() and specify 'implementation'`);
     }
     return {
       module: this,
-      imports: [...options.imports ?? [], ...instance.imports()],
+      imports: [
+        ...decoratorImports,
+        ...instance.imports(),
+        ...options.imports ?? []
+      ],
       providers: [
         implementation,
         { provide: token, useExisting: implementation },
-        ...instance.extraPoviders({})
+        ...decoratorProviders,
+        ...instance.extraProviders({})
       ],
       exports: [token],
       __provides: token
@@ -124,10 +136,16 @@ class Adapter {
 // src/core/decorators.ts
 var import_reflect_metadata2 = require("reflect-metadata");
 var import_common = require("@nestjs/common");
-function Port(config) {
+function Adapter(config) {
   return (target) => {
-    Reflect.defineMetadata(PORT_TOKEN_METADATA, config.token, target);
+    Reflect.defineMetadata(PORT_TOKEN_METADATA, config.portToken, target);
     Reflect.defineMetadata(PORT_IMPLEMENTATION_METADATA, config.implementation, target);
+    if (config.imports) {
+      Reflect.defineMetadata(ADAPTER_IMPORTS_METADATA, config.imports, target);
+    }
+    if (config.providers) {
+      Reflect.defineMetadata(ADAPTER_PROVIDERS_METADATA, config.providers, target);
+    }
   };
 }
 function InjectPort(token) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nest-hex",
-	"version": "0.2.2",
+	"version": "0.3.2",
 	"description": "A tiny NestJS-native library for building pluggable adapters (Ports & Adapters / Hexagonal) using class-based Dynamic Modules, with great DX and strong type safety.",
 	"homepage": "https://github.com/LiorVainer/nest-hex#readme",
 	"bugs": {