nest-hex 0.2.0 → 0.3.2

package/dist/src/cli/utils/port-scanner.js

@@ -0,0 +1,104 @@
+var import_node_module = require("node:module");
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __legacyDecorateClassTS = 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;
+};
+
+// src/cli/utils/port-scanner.ts
+var exports_port_scanner = {};
+__export(exports_port_scanner, {
+  scanAvailablePorts: () => scanAvailablePorts,
+  findPortByName: () => findPortByName
+});
+module.exports = __toCommonJS(exports_port_scanner);
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+function scanAvailablePorts(config, projectRoot = process.cwd()) {
+  const portsDir = config.output?.portsDir || "src/ports";
+  const portsDirPath = import_node_path.join(projectRoot, portsDir);
+  if (!import_node_fs.existsSync(portsDirPath)) {
+    return [];
+  }
+  const ports = [];
+  const entries = import_node_fs.readdirSync(portsDirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const portName = entry.name;
+    const portPath = import_node_path.join(portsDirPath, portName);
+    const tokenFileName = `${portName}.token.ts`;
+    const tokenFilePath = import_node_path.join(portPath, tokenFileName);
+    if (!import_node_fs.existsSync(tokenFilePath)) {
+      continue;
+    }
+    const tokenFileContent = import_node_fs.readFileSync(tokenFilePath, "utf-8");
+    const tokenMatch = tokenFileContent.match(/export\s+const\s+([A-Z_]+)\s*=\s*Symbol/);
+    if (!tokenMatch || !tokenMatch[1]) {
+      continue;
+    }
+    const tokenName = tokenMatch[1];
+    const pascalName = portName.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+    const portsDirName = portsDir.split("/").pop() || "ports";
+    const tokenImportPath = `../../${portsDirName}/${portName}`;
+    ports.push({
+      name: portName,
+      pascalName,
+      tokenName,
+      tokenImportPath,
+      portPath
+    });
+  }
+  return ports;
+}
+function findPortByName(portName, config, projectRoot = process.cwd()) {
+  const ports = scanAvailablePorts(config, projectRoot);
+  return ports.find((p) => p.name === portName) || null;
+}

package/dist/src/cli/utils/template-renderer.d.ts

@@ -0,0 +1,30 @@
+interface GeneratorContext extends Record<string, unknown> {
+	original: string;
+	kebab: string;
+	camel: string;
+	pascal: string;
+	snake: string;
+	screamingSnake: string;
+	nameKebab: string;
+	nameCamel: string;
+	namePascal: string;
+	nameSnake: string;
+	nameScreamingSnake: string;
+	portSuffix: string;
+	adapterSuffix: string;
+	fileCase: "kebab" | "camel" | "pascal";
+	indent: "tab" | number;
+	quotes: "single" | "double";
+	semicolons: boolean;
+	includeModule: boolean;
+	includeService: boolean;
+	registrationType: "sync" | "async";
+	generateExample: boolean;
+	coreImportPath: string;
+}
+interface TemplateContext extends GeneratorContext {
+	[key: string]: unknown;
+}
+declare function renderTemplate(templatePath: string, context: TemplateContext): Promise<string>;
+declare function renderTemplateString(templateString: string, context: TemplateContext): Promise<string>;
+export { renderTemplateString, renderTemplate };

package/dist/src/cli/utils/template-renderer.js

@@ -0,0 +1,95 @@
+var import_node_module = require("node:module");
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __legacyDecorateClassTS = 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;
+};
+
+// src/cli/utils/template-renderer.ts
+var exports_template_renderer = {};
+__export(exports_template_renderer, {
+  renderTemplateString: () => renderTemplateString,
+  renderTemplate: () => renderTemplate
+});
+module.exports = __toCommonJS(exports_template_renderer);
+var import_handlebars = __toESM(require("handlebars"));
+async function renderTemplate(templatePath, context) {
+  try {
+    const file = Bun.file(templatePath);
+    if (!await file.exists()) {
+      throw new Error(`Template file not found: ${templatePath}
+` + "Please ensure the template exists or report this as a bug.");
+    }
+    const templateSource = await file.text();
+    try {
+      const template = import_handlebars.default.compile(templateSource);
+      return template(context);
+    } catch (compileError) {
+      throw new Error(`Failed to compile template ${templatePath}: ` + `${compileError instanceof Error ? compileError.message : String(compileError)}
+` + "This may indicate invalid Handlebars syntax in the template.");
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Template file not found")) {
+      throw error;
+    }
+    if (error instanceof Error && error.message.includes("Failed to compile template")) {
+      throw error;
+    }
+    throw new Error(`Failed to read template ${templatePath}: ` + `${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function renderTemplateString(templateString, context) {
+  try {
+    const template = import_handlebars.default.compile(templateString);
+    return template(context);
+  } catch (error) {
+    throw new Error("Failed to compile template string: " + `${error instanceof Error ? error.message : String(error)}
+` + "This may indicate invalid Handlebars syntax.");
+  }
+}

package/dist/{index.d.ts → 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/{index.js → src/index.js}

@@ -1,8 +1,21 @@
 var import_node_module = require("node:module");
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __moduleCache = /* @__PURE__ */ new WeakMap;
 var __toCommonJS = (from) => {
   var entry = __moduleCache.get(from), desc;
@@ -17,6 +30,7 @@ var __toCommonJS = (from) => {
   __moduleCache.set(from, entry);
   return entry;
 };
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -41,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);
@@ -53,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
@@ -88,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
@@ -110,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.0",
+	"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": {
@@ -14,7 +14,7 @@
 		"dist"
 	],
 	"bin": {
-		"nest-hex": "./dist/cli/bin.js"
+		"nest-hex": "./dist/src/cli/bin.js"
 	},
 	"repository": {
 		"type": "git",
@@ -64,18 +64,18 @@
 			"optional": true
 		}
 	},
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
+	"main": "./dist/src/index.js",
+	"types": "./dist/src/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./dist/index.d.ts",
-			"require": "./dist/index.js",
-			"import": "./dist/index.js"
+			"types": "./dist/src/index.d.ts",
+			"require": "./dist/src/index.js",
+			"import": "./dist/src/index.js"
 		},
 		"./cli": {
-			"types": "./dist/cli/index.d.ts",
-			"require": "./dist/cli/index.js",
-			"import": "./dist/cli/index.js"
+			"types": "./dist/src/cli/index.d.ts",
+			"require": "./dist/src/cli/index.js",
+			"import": "./dist/src/cli/index.js"
 		},
 		"./package.json": "./package.json"
 	},