@apso/cli 0.1.7 → 0.1.9

package/README.md

@@ -4,27 +4,58 @@
 - [Prerequisites](#prerequisites)
 - [Usage](#usage)
 - [Local Development](#local-development)
+- [Populating an .apsorc File](#populating-an-apsorc-file)
 - [Debugging](##debugging)
 - [Commands](#commands)
 
-# Prerequisites
-
-You need to have setup access to Mavric's private NPM packages.
-Find out how [here](https://github.com/mavric/.github-private/blob/main/how-to/private-npm.md)
 
 # Usage
 
-```sh-session
-$ npm install -g @mavric/apso-cli
-$ apso COMMAND
-running command...
-$ apso (--version)
-@mavric/apso-cli/0.0.26 linux-x64 node-v18.20.2
-$ apso --help [COMMAND]
-USAGE
-  $ apso COMMAND
-...
-```
+Follow these steps to create and run a new APSO server project:
+
+1. **Install the CLI globally:**
+   ```sh
+   npm install -g @apso/apso-cli
+   ```
+
+2. **Initialize a new server project:**
+   ```sh
+   apso server new --name <PROJECT_NAME>
+   ```
+   This creates a new project folder with the necessary boilerplate.
+
+3. **Define your database schema:**
+   Edit the `.apsorc` file in your new project folder to describe your entities and relationships. See the [Populating an .apsorc File](#populating-an-apsorc-file) section for details and examples.
+
+4. **Generate code and database entities:**
+   ```sh
+   apso server scaffold
+   ```
+   This command generates all relevant modules and entity code based on your `.apsorc` file.
+
+5. **Configure your database connection:**
+   Update your project's `.env` file with the database credentials you want to use.
+
+6. **Start the local Postgres instance (Docker):**
+   ```sh
+   npm run compose
+   ```
+   This command uses Docker Compose to start a local Postgres database instance.
+
+7. **Provision your schema/database:**
+   ```sh
+   npm run provision
+   ```
+   This sets up your new schema instance in the database.
+
+8. **(Optional) Enable automatic model sync for local development:**
+   If you want to skip manual migrations and always sync your models with the database (useful for rapid prototyping or starting from scratch), set the following in your `.env` file:
+   ```env
+   DATABASE_SYNC=true
+   ```
+   With this setting, your models will be automatically synced to the database on startup.
+
+> For more details on configuring your schema, see the [Populating an .apsorc File](#populating-an-apsorc-file) section below.
 
 # Local Development
 
@@ -59,6 +90,103 @@ Now we will run the scaffold command which will generate the all the relevant mo
 apso server scaffold
 ```
 
+# Populating an .apsorc File
+
+The `.apsorc` file defines your domain model, including entities and their relationships, for APSO code generation. It is required for scaffolding your backend service.
+
+## How to Create and Populate `.apsorc`
+
+1. **Location**: Place the `.apsorc` file in the root of your service directory.
+2. **Version**: Set the `version` property to `2` for the latest schema.
+3. **Entities**: Define each domain entity, its fields, and any unique constraints.
+4. **Relationships**: Specify how entities relate (e.g., OneToMany, ManyToOne, etc.).
+5. **rootFolder**: Set the folder where generated code will be placed (e.g., `src`).
+
+> **Tip:** You can find sample `.apsorc` files in `apso-cli/test/apsorc-json/` for both v1 and v2 formats.
+
+### Example `.apsorc` v2 File
+
+```json
+{
+  "version": 2,
+  "rootFolder": "src",
+  "relationships": [
+    { "from": "User", "to": "WorkspaceUser", "type": "OneToMany", "nullable": true },
+    { "from": "Workspace", "to": "WorkspaceUser", "type": "OneToMany" },
+    { "from": "Workspace", "to": "Application", "type": "OneToMany", "index": true },
+    { "from": "Application", "to": "ApplicationService", "type": "OneToMany" },
+    { "from": "Application", "to": "User", "type": "ManyToOne", "to_name": "owner" },
+    { "from": "ApplicationService", "to": "ApplicationServiceApiKey", "type": "OneToMany" },
+    { "from": "ApplicationService", "to": "ApplicationServiceMetric", "type": "OneToMany" },
+    { "from": "ApplicationService", "to": "InfrastructureStack", "type": "ManyToOne", "to_name": "networkStack", "nullable": true },
+    { "from": "ApplicationService", "to": "InfrastructureStack", "type": "ManyToOne", "to_name": "databaseStack", "nullable": true },
+    { "from": "InfrastructureStack", "to": "InfrastructureStack", "type": "ManyToOne", "to_name": "networkStack", "nullable": true }
+  ],
+  "entities": [
+    {
+      "name": "User",
+      "created_at": true,
+      "updated_at": true,
+      "fields": [
+        { "name": "cognito_id", "type": "text", "unique": true },
+        { "name": "email", "type": "text", "length": 255, "is_email": true },
+        { "name": "fullName", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "name": "Workspace",
+      "created_at": true,
+      "updated_at": true,
+      "fields": [
+        { "name": "name", "type": "text" }
+      ]
+    },
+    {
+      "name": "WorkspaceUser",
+      "created_at": true,
+      "updated_at": true,
+      "fields": [
+        { "name": "email", "type": "text", "length": 255, "is_email": true },
+        { "name": "invite_code", "type": "text", "length": 64 },
+        { "name": "role", "type": "enum", "values": ["User", "Admin"], "default": "Admin" },
+        { "name": "status", "type": "enum", "values": ["Active", "Invited", "Inactive", "Deleted"] },
+        { "name": "activeAt", "type": "date", "nullable": true }
+      ]
+    },
+    {
+      "name": "Application",
+      "created_at": true,
+      "updated_at": true,
+      "fields": [
+        { "name": "name", "type": "text" },
+        { "name": "status", "type": "enum", "values": ["Active", "Deleted"] }
+      ]
+    }
+    // ... more entities as needed ...
+  ]
+}
+```
+
+For a full example, see [`apso-cli/test/apsorc-json/apsorc.v2.json`](./test/apsorc-json/apsorc.v2.json).
+
+## Schema Reference
+
+The `.apsorc` file must conform to the [APSO Configuration Schema](./apsorc.schema.json). This schema defines all valid properties, types, and constraints for your configuration file.
+
+### Inline Schema (apsorc.schema.json)
+
+```json
+// ... see full contents in apso-cli/apsorc.schema.json ...
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "APSO Configuration Schema",
+  "description": "Schema for the .apsorc file used by APSO to define entities and relationships.",
+  // ... (truncated for brevity) ...
+}
+```
+
+See the [full schema file](./apsorc.schema.json) for all details and validation rules.
+
 ## Debugging
 
 For debugging we would use the debug package so you need to import the package in file where you want to debug any code.

package/dist/commands/server/scaffold.js

@@ -6,8 +6,15 @@ const path = tslib_1.__importStar(require("path"));
 const lib_1 = require("../../lib");
 const base_command_1 = tslib_1.__importDefault(require("../../lib/base-command"));
 const apsorc_parser_1 = require("../../lib/apsorc-parser");
+const perf_hooks_1 = require("perf_hooks");
+const Eta = tslib_1.__importStar(require("eta"));
+Eta.configure({
+    views: path.join(__dirname, "../../lib/templates"),
+    cache: false
+});
 class Scaffold extends base_command_1.default {
     async scaffoldServer(dir, entity, relationshipMap, apiType) {
+        const entityBuildStart = perf_hooks_1.performance.now();
         this.log(`Building... ${entity.name}`);
         const entityName = entity.name;
         const filePath = path.join(dir, entityName);
@@ -24,13 +31,31 @@ class Scaffold extends base_command_1.default {
                 break;
         }
         await (0, lib_1.createModule)(filePath, entity, { apiType });
+        const entityBuildTime = perf_hooks_1.performance.now() - entityBuildStart;
+        console.log(`[apso] Finished building entity '${entity.name}' in ${entityBuildTime.toFixed(2)} ms`);
     }
     async setupRestFiles(dir, entity, relationshipMap, apiType) {
         const filePath = path.join(dir, entity.name);
         const entityRelationships = relationshipMap[entity.name] || [];
+        const tDto = perf_hooks_1.performance.now();
         await (0, lib_1.createDto)(filePath, entity, entityRelationships, { apiType });
+        if (process.env.DEBUG) {
+            console.log(`[timing] createDto for ${entity.name}: ${(perf_hooks_1.performance.now() - tDto).toFixed(2)}ms`);
+            const used = process.memoryUsage();
+            console.log(`[mem] heapUsed after createDto for ${entity.name}: ${(used.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+        }
+        const tService = perf_hooks_1.performance.now();
         await (0, lib_1.createService)(filePath, entity);
+        if (process.env.DEBUG) {
+            console.log(`[timing] createService for ${entity.name}: ${(perf_hooks_1.performance.now() - tService).toFixed(2)}ms`);
+            const used = process.memoryUsage();
+            console.log(`[mem] heapUsed after createService for ${entity.name}: ${(used.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+        }
+        const tController = perf_hooks_1.performance.now();
         await (0, lib_1.createController)(filePath, entity, relationshipMap);
+        if (process.env.DEBUG) {
+            console.log(`[timing] createController for ${entity.name}: ${(perf_hooks_1.performance.now() - tController).toFixed(2)}ms`);
+        }
     }
     async setupGraphqlFiles(dir, entity, relationshipMap) {
         const filePath = path.join(dir, entity.name);
@@ -38,17 +63,28 @@ class Scaffold extends base_command_1.default {
         await (0, lib_1.createGqlDTO)(filePath, entity, entityRelationships);
     }
     async run() {
+        const totalBuildStart = perf_hooks_1.performance.now();
         const { rootFolder, entities, relationshipMap, apiType } = (0, lib_1.parseApsorc)();
         const rootPath = path.join(process.cwd(), rootFolder);
         const autogenPath = path.join(rootPath, "autogen");
         const lowerCaseApiType = apiType.toLowerCase();
         await (0, lib_1.createEnums)(autogenPath, entities, lowerCaseApiType);
-        entities.forEach((entity) => {
+        await Promise.all(entities.map(async (entity) => {
             const scaffoldModel = this.scaffoldServer.bind(this);
-            scaffoldModel(autogenPath, entity, relationshipMap, lowerCaseApiType);
-        });
+            await scaffoldModel(autogenPath, entity, relationshipMap, lowerCaseApiType);
+            if (process.env.DEBUG) {
+                const used = process.memoryUsage();
+                console.log(`[mem] heapUsed after ${entity.name}: ${(used.heapUsed / 1024 / 1024).toFixed(2)} MB`);
+            }
+        }));
         await (0, lib_1.createIndexAppModule)(autogenPath, entities, lowerCaseApiType);
-        await this.runNpmCommand(["run", "format"]);
+        const totalBuildTime = perf_hooks_1.performance.now() - totalBuildStart;
+        console.log(`[apso] Finished building all entities in ${totalBuildTime.toFixed(2)} ms`);
+        const formatStart = perf_hooks_1.performance.now();
+        console.log("[apso] Formatting files...");
+        await this.runNpmCommand(["run", "format", "src/autogen/**/*.ts"], true);
+        const formatTime = perf_hooks_1.performance.now() - formatStart;
+        console.log(`[apso] Finished formatting in ${formatTime.toFixed(2)} ms`);
     }
 }
 Scaffold.description = "Setup new entities and interfaces for an Apso Server";

package/dist/lib/apsorc-parser.js

@@ -6,6 +6,7 @@ const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const rc_1 = tslib_1.__importDefault(require("rc"));
 const relationships_1 = require("./utils/relationships");
+const perf_hooks_1 = require("perf_hooks");
 var ApiType;
 (function (ApiType) {
     ApiType["Graphql"] = "graphql";
@@ -42,6 +43,8 @@ const parseRc = () => {
     };
 };
 const parseApsorc = () => {
+    const debug = process.env.DEBUG;
+    const start = perf_hooks_1.performance.now();
     const apsoConfig = parseRc();
     if (apsoConfig.version === 1 &&
         (apsoConfig === null || apsoConfig === void 0 ? void 0 : apsoConfig.apiType.toLowerCase()) !== ApiType.Rest.toLowerCase()) {
@@ -49,18 +52,39 @@ const parseApsorc = () => {
     }
     else {
         switch (apsoConfig.version) {
-            case 1:
-                return {
+            case 1: {
+                const v1Start = perf_hooks_1.performance.now();
+                const result = {
                     rootFolder: apsoConfig.rootFolder,
                     apiType: apsoConfig.apiType,
                     ...(0, exports.parseApsorcV1)(apsoConfig),
                 };
-            case 2:
-                return {
+                if (debug) {
+                    console.log(`[timing] parseApsorcV1: ${(perf_hooks_1.performance.now() - v1Start).toFixed(2)}ms`);
+                }
+                if (debug) {
+                    console.log(`[timing] parseApsorc total: ${(perf_hooks_1.performance.now() - start).toFixed(2)}ms`);
+                }
+                return result;
+            }
+            case 2: {
+                const result = {
                     rootFolder: apsoConfig.rootFolder,
                     apiType: apsoConfig.apiType,
-                    ...(0, exports.parseApsorcV2)(apsoConfig),
+                    ...(() => {
+                        const relStart = perf_hooks_1.performance.now();
+                        const parsed = (0, exports.parseApsorcV2)(apsoConfig);
+                        if (debug) {
+                            console.log(`[timing] parseApsorcV2: ${(perf_hooks_1.performance.now() - relStart).toFixed(2)}ms`);
+                        }
+                        return parsed;
+                    })(),
                 };
+                if (debug) {
+                    console.log(`[timing] parseApsorc total: ${(perf_hooks_1.performance.now() - start).toFixed(2)}ms`);
+                }
+                return result;
+            }
         }
         throw new Error(`Invalid apsorc config version: ${apsoConfig.version}`);
     }

package/dist/lib/base-command.d.ts

@@ -1,4 +1,4 @@
 import { Command } from "@oclif/core";
 export default abstract class BaseCommand extends Command {
-    runNpmCommand(args: string[]): Promise<void>;
+    runNpmCommand(args: string[], silent?: boolean): Promise<void>;
 }

package/dist/lib/base-command.js

@@ -3,12 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const child_process_1 = require("child_process");
 class BaseCommand extends core_1.Command {
-    async runNpmCommand(args) {
+    async runNpmCommand(args, silent = false) {
         return new Promise((resolve, reject) => {
             const command = "npm";
             const cmdStr = `${command} ${args.join(" ")}`;
             this.log(cmdStr);
-            const child = (0, child_process_1.spawn)(command, args, { stdio: "inherit" });
+            const child = (0, child_process_1.spawn)(command, args, { stdio: silent ? "ignore" : "inherit" });
             child.on("close", (code) => {
                 if (code !== 0) {
                     reject({

package/dist/lib/controller.js

@@ -6,7 +6,13 @@ const Eta = tslib_1.__importStar(require("eta"));
 const path = tslib_1.__importStar(require("path"));
 const file_system_1 = require("./utils/file-system");
 const relationships_1 = require("./utils/relationships");
+const parse_1 = require("./utils/relationships/parse");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
+const perf_hooks_1 = require("perf_hooks");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const os_1 = tslib_1.__importDefault(require("os"));
+const util_1 = require("util");
+const unlinkAsync = (0, util_1.promisify)(fs_1.default.unlink);
 /**
  * Generates NestJS controller and spec files for a given entity.
  *
@@ -19,33 +25,71 @@ const createController = async (apiBaseDir, entity, relationshipMap) => {
     const { name: entityName } = entity;
     const controllerFileName = path.join(apiBaseDir, `${entityName}.controller.ts`);
     const specFileName = path.join(apiBaseDir, `${entityName}.controller.spec.ts`);
-    // Dependencies and names needed by the template
+    const startTotal = perf_hooks_1.performance.now();
+    const startRel = perf_hooks_1.performance.now();
+    const relationships = (0, relationships_1.getRelationshipForTemplate)(entityName, relationshipMap[entityName]);
+    const relTime = perf_hooks_1.performance.now() - startRel;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] getRelationshipForTemplate: ${relTime.toFixed(2)} ms`);
+    }
+    const startNested = perf_hooks_1.performance.now();
+    const tmpDir = os_1.default.tmpdir();
+    const nestedJoinsFile = path.join(tmpDir, `apso-nested-joins-${entityName}-${Date.now()}.eta`);
+    const nestedJoinsStream = fs_1.default.createWriteStream(nestedJoinsFile, { encoding: "utf8" });
+    let nestedCount = 0;
+    nestedCount = await (0, parse_1.streamNestedRelationships)(entityName, relationshipMap, nestedJoinsStream);
+    nestedJoinsStream.end();
+    await new Promise((resolve) => {
+        nestedJoinsStream.on("finish", resolve);
+    });
+    const nestedTime = perf_hooks_1.performance.now() - startNested;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] getNestedRelationships (streamed ${nestedCount} paths): ${nestedTime.toFixed(2)} ms`);
+    }
     const svcName = `${entityName}Service`;
     const ctrlName = `${entityName}Controller`;
     const pluralEntityName = (0, pluralize_1.default)(entityName);
-    // Get processed relationships specific to this entity
-    const relationships = (0, relationships_1.getRelationshipForTemplate)(entityName, relationshipMap[entityName]);
-    // Get nested relationship paths for the @Crud join configuration
-    const nestedRelationships = (0, relationships_1.getNestedRelationships)(entityName, relationshipMap);
-    // Data object for the Eta template
     const data = {
         svcName,
         ctrlName,
         entityName,
         pluralEntityName,
-        // Ensure uniqueness in associations (though getRelationshipForTemplate might handle this)
         associations: [...new Set(relationships)],
-        nestedAssociations: [...new Set(nestedRelationships)],
+        nestedJoinsFile,
     };
-    // Configure Eta
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
-    // Render controller template
+    const startRenderController = perf_hooks_1.performance.now();
     const controllerContent = await Eta.renderFileAsync("./rest/controller-rest", data);
-    (0, file_system_1.createFile)(controllerFileName, controllerContent);
-    // Render spec template
+    const renderControllerTime = perf_hooks_1.performance.now() - startRenderController;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] renderController: ${renderControllerTime.toFixed(2)} ms`);
+    }
+    const startWriteController = perf_hooks_1.performance.now();
+    await (0, file_system_1.createFile)(controllerFileName, controllerContent);
+    const writeControllerTime = perf_hooks_1.performance.now() - startWriteController;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] writeController: ${writeControllerTime.toFixed(2)} ms`);
+    }
+    const startRenderSpec = perf_hooks_1.performance.now();
     const specContent = await Eta.renderFileAsync("./rest/controller-rest-spec", data);
-    (0, file_system_1.createFile)(specFileName, specContent);
+    const renderSpecTime = perf_hooks_1.performance.now() - startRenderSpec;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] renderSpec: ${renderSpecTime.toFixed(2)} ms`);
+    }
+    const startWriteSpec = perf_hooks_1.performance.now();
+    await (0, file_system_1.createFile)(specFileName, specContent);
+    const writeSpecTime = perf_hooks_1.performance.now() - startWriteSpec;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] writeSpec: ${writeSpecTime.toFixed(2)} ms`);
+    }
+    try {
+        await unlinkAsync(nestedJoinsFile);
+    }
+    catch (error) {
+        console.warn(`[createController][${entityName}] Warning: Failed to delete temp file ${nestedJoinsFile}:`, error);
+    }
+    const totalTime = perf_hooks_1.performance.now() - startTotal;
+    if (process.env.DEBUG) {
+        console.log(`[createController][${entityName}] TOTAL: ${totalTime.toFixed(2)} ms`);
+    }
 };
 exports.createController = createController;

package/dist/lib/dto.js

@@ -26,23 +26,23 @@ options) => {
     const dtoFile = path.join(dtoDir, `${entityName}.dto.ts`);
     const columns = (0, field_1.getFieldForTemplate)(fields, entityName);
     const relationshipsTemplate = (0, relationships_1.getRelationshipForTemplate)(entityName, relationships);
-    if (process.env.DEBUG) {
-        console.log('[DTO DEBUG] Generating DTO for:', entityName);
-        console.log('[DTO DEBUG] relationshipsTemplate:', relationshipsTemplate);
-    }
+    // if (process.env.DEBUG) {
+    //   console.log('[DTO DEBUG] Generating DTO for:', entityName);
+    //   console.log('[DTO DEBUG] relationshipsTemplate:', relationshipsTemplate);
+    // }
     // Add foreign key columns for ManyToOne relationships if not present
     relationshipsTemplate.forEach(rel => {
         if (rel.type === 'ManyToOne') {
             const fkName = (0, casing_1.camelCase)(rel.referenceName || rel.name) + 'Id';
-            if (process.env.DEBUG) {
-                console.log('[DTO DEBUG]', {
-                    relType: rel.type,
-                    relName: rel.name,
-                    referenceName: rel.referenceName,
-                    fkName,
-                    columns: columns.map(c => c.name)
-                });
-            }
+            // if (process.env.DEBUG) {
+            //   console.log('[DTO DEBUG]', {
+            //     relType: rel.type,
+            //     relName: rel.name,
+            //     referenceName: rel.referenceName,
+            //     fkName,
+            //     columns: columns.map(c => c.name)
+            //   });
+            // }
             if (!columns.some(col => col.name === fkName)) {
                 columns.push({
                     name: fkName,
@@ -73,13 +73,9 @@ options) => {
         apiType: (_a = options === null || options === void 0 ? void 0 : options.apiType) !== null && _a !== void 0 ? _a : "rest",
         importEnums: (0, field_1.typeExistsInEntity)(entity, "enum") !== -1,
     };
-    // Configure Eta
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
     // Render the unified template only once
     const dtoContent = await Eta.renderFileAsync("./rest/dto-rest", data);
     // Create only one DTO file
-    (0, file_system_1.createFile)(dtoFile, dtoContent);
+    await (0, file_system_1.createFile)(dtoFile, dtoContent);
 };
 exports.createDto = createDto;

package/dist/lib/entity.js

@@ -2,13 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEntity = void 0;
 const tslib_1 = require("tslib");
-const Eta = tslib_1.__importStar(require("eta"));
 const path = tslib_1.__importStar(require("path"));
 const file_system_1 = require("./utils/file-system");
 const field_1 = require("./utils/field");
 const relationships_1 = require("./utils/relationships");
 const casing_1 = require("./utils/casing");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
+const Eta = tslib_1.__importStar(require("eta"));
 /**
  * Generates a TypeORM entity file based on the entity definition and relationships.
  *
@@ -43,11 +43,8 @@ const createEntity = async (apiBaseDir, entity, relationshipsNew, apiType) => {
         importEnums: (0, field_1.typeExistsInEntity)(entity, "enum") !== -1,
         apiType,
     };
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
     const templatePath = apiType === "graphql" ? "./graphql/gql-entity-graphql" : "./entities/entity";
     const content = await Eta.renderFileAsync(templatePath, data);
-    (0, file_system_1.createFile)(File, content);
+    await (0, file_system_1.createFile)(File, content);
 };
 exports.createEntity = createEntity;

package/dist/lib/enums.js

@@ -2,10 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEnums = void 0;
 const tslib_1 = require("tslib");
-const Eta = tslib_1.__importStar(require("eta"));
 const path = tslib_1.__importStar(require("path"));
 const file_system_1 = require("./utils/file-system");
 const field_1 = require("./utils/field");
+const Eta = tslib_1.__importStar(require("eta"));
 const createEnums = async (apiBaseDir, entities, apiType) => {
     if (entities.length > 0) {
         const outputFile = path.join(apiBaseDir, "enums.ts");
@@ -18,13 +18,10 @@ const createEnums = async (apiBaseDir, entities, apiType) => {
         }))
             .filter(Boolean);
         if (allEnumsFields.length > 0) {
-            Eta.configure({
-                views: path.join(__dirname, "templates"),
-            });
             const content = await Eta.renderFileAsync(`./${apiType}/enums-${apiType}`, {
                 allEnumsFields,
             });
-            (0, file_system_1.createFile)(outputFile, content);
+            await (0, file_system_1.createFile)(outputFile, content);
         }
     }
 };

package/dist/lib/gql-dto.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGqlDTO = void 0;
 const tslib_1 = require("tslib");
-const Eta = tslib_1.__importStar(require("eta"));
 const path = tslib_1.__importStar(require("path"));
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
+const Eta = tslib_1.__importStar(require("eta"));
 const field_1 = require("./utils/field");
 const relationships_1 = require("./utils/relationships");
 const casing_1 = require("./utils/casing");
@@ -33,11 +33,7 @@ const createGqlDTO = async (apiBaseDir, entity, relationshipsNew) => {
         entitiesToImport,
         importEnums: (0, field_1.typeExistsInEntity)(entity, "enum") !== -1,
     };
-    Eta.configure({
-        // This tells Eta to look for templates in the /templates directory
-        views: path.join(__dirname, "templates"),
-    });
     const contentEntity = await Eta.renderFileAsync("./graphql/gql-dto-graphql", data);
-    (0, file_system_1.createFile)(File, contentEntity);
+    await (0, file_system_1.createFile)(File, contentEntity);
 };
 exports.createGqlDTO = createGqlDTO;

package/dist/lib/index-module.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createIndexAppModule = void 0;
 const tslib_1 = require("tslib");
-const file_system_1 = require("./utils/file-system");
 const Eta = tslib_1.__importStar(require("eta"));
+const file_system_1 = require("./utils/file-system");
 const path = tslib_1.__importStar(require("path"));
 /**
  * Generates an index file (e.g., index.ts) that exports all generated entity modules.
@@ -18,12 +18,9 @@ const path = tslib_1.__importStar(require("path"));
  */
 const createIndexAppModule = async (apiBaseDir, entities, apiType) => {
     const File = path.join(apiBaseDir, `index.ts`);
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
     const content = await Eta.renderFileAsync(`./${apiType}/index-module-${apiType}`, {
         entities,
     });
-    (0, file_system_1.createFile)(File, content);
+    await (0, file_system_1.createFile)(File, content);
 };
 exports.createIndexAppModule = createIndexAppModule;

package/dist/lib/module.js

@@ -30,15 +30,11 @@ const createModule = async (apiBaseDir, entity, options) => {
         resolverName,
         entityName,
     };
-    // Configure Eta
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
     // Determine template based on API type
     const templatePath = (options === null || options === void 0 ? void 0 : options.apiType) === "graphql" ? "./graphql/gql-module-graphql" : "./rest/module-rest";
     // Render the template
     const content = await Eta.renderFileAsync(templatePath, data);
     // Create the module file
-    (0, file_system_1.createFile)(moduleFileName, content);
+    await (0, file_system_1.createFile)(moduleFileName, content);
 };
 exports.createModule = createModule;

package/dist/lib/service.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createService = void 0;
 const tslib_1 = require("tslib");
-const file_system_1 = require("./utils/file-system");
 const Eta = tslib_1.__importStar(require("eta"));
+const file_system_1 = require("./utils/file-system");
 const path = tslib_1.__importStar(require("path"));
 /**
  * Generates NestJS service and spec files for a given entity.
@@ -25,15 +25,13 @@ const createService = async (apiBaseDir, entity) => {
         repoName,
         entityName,
     };
-    // Configure Eta
-    Eta.configure({
-        views: path.join(__dirname, "templates"),
-    });
     // Render service template
     const serviceContent = await Eta.renderFileAsync("./rest/service-rest", data);
-    (0, file_system_1.createFile)(serviceFileName, serviceContent);
+    await (0, file_system_1.createFile)(serviceFileName, serviceContent);
+    Eta.templates.remove("./rest/service-rest");
     // Render spec template
     const specContent = await Eta.renderFileAsync("./rest/service-rest-spec", data);
-    (0, file_system_1.createFile)(specFileName, specContent);
+    await (0, file_system_1.createFile)(specFileName, specContent);
+    Eta.templates.remove("./rest/service-rest-spec");
 };
 exports.createService = createService;

package/dist/lib/templates/rest/controller-rest.eta

@@ -36,10 +36,8 @@ import {<%= it.svcName %>} from './<%= it.entityName %>.service';
                     <%= assoc.relationshipName %>: { eager: false },
                     <% } %>
                 <% }) %>
-                <% if (it.nestedAssociations.length) {%>
-                    <% it.nestedAssociations.forEach((assoc) => { %>
-                    "<%= assoc %>": { eager: false },
-                    <% }) %>
+                <% if (it.nestedJoinsFile) {%>
+                    <%~ includeFile(it.nestedJoinsFile) %>
                 <% }%>
             },
         <% } %>

package/dist/lib/utils/file-system.d.ts

@@ -1,2 +1,2 @@
-export declare const createFile: (file: string, content: string) => void;
+export declare const createFile: (file: string, content: string) => Promise<void>;
 export declare const createDirectoryContents: (templatePath: string, newProjectPath: string, apiType: string) => void;

package/dist/lib/utils/file-system.js

@@ -4,15 +4,15 @@ exports.createDirectoryContents = exports.createFile = void 0;
 const tslib_1 = require("tslib");
 const path = tslib_1.__importStar(require("path"));
 const fs = tslib_1.__importStar(require("fs"));
-const createDir = (dirname) => {
+const createDir = async (dirname) => {
     if (!fs.existsSync(dirname)) {
-        fs.mkdirSync(dirname, { recursive: true });
+        await fs.promises.mkdir(dirname, { recursive: true });
     }
 };
-const createFile = (file, content) => {
+const createFile = async (file, content) => {
     const dirname = path.dirname(file);
-    createDir(dirname);
-    fs.writeFileSync(file, content);
+    await createDir(dirname);
+    await fs.promises.writeFile(file, content);
 };
 exports.createFile = createFile;
 const createDirectoryContents = (templatePath, newProjectPath, apiType) => {

package/dist/lib/utils/relationships/parse.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { ApsorcRelationship, Relationship, RelationshipMap, RelationshipForTemplate } from "../../types";
 /**
  * Parses a OneToMany relationship definition.
@@ -51,5 +52,24 @@ export declare const getRelationshipIdField: (relationship: Relationship) => str
  * @returns An array of RelationshipForTemplate objects with extra properties for the template.
  */
 export declare const getRelationshipForTemplate: (entityName: string, relationships: Relationship[]) => RelationshipForTemplate[];
-export declare const getNestedRelationships: (entityName: string, relationshipMap: RelationshipMap, prefix?: string, visited?: Set<string>) => string[];
+/**
+ * Generates all valid nested join paths for an entity, avoiding cycles and redundant paths.
+ *
+ * Requirements enforced:
+ * 1. No cycles by tracking visited (entity, reference) pairs in the current path
+ * 2. Allow the same entity with different references (proper name vs alias)
+ * 3. Allow different aliases to the same entity in different branches
+ * 4. Respect max depth limit
+ *
+ * @param entityName - Current entity to generate relationships from
+ * @param relationshipMap - Map of all entity relationships
+ * @param maxDepth - Maximum depth of nested joins (default: 6)
+ * @param path - Current join path being built (internal use)
+ * @param visitedPairs - Set of (entity, reference) pairs visited in current path (internal use)
+ * @param baseEntity - The root entity we started from (internal use)
+ * @returns Generator yielding valid join path strings
+ */
+export declare function generateNestedRelationships(entityName: string, relationshipMap: RelationshipMap, maxDepth?: number, path?: string[], visitedPairs?: Set<string>, baseEntity?: string): Generator<string>;
+export declare function getNestedRelationships(entityName: string, relationshipMap: RelationshipMap, maxDepth?: number): string[];
+export declare function streamNestedRelationships(entityName: string, relationshipMap: RelationshipMap, writable: NodeJS.WritableStream, maxDepth?: number): Promise<number>;
 export declare const getRelationshipsForImport: (entityName: string, relationships?: Relationship[]) => string[];

package/dist/lib/utils/relationships/parse.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRelationshipsForImport = exports.getNestedRelationships = exports.getRelationshipForTemplate = exports.getRelationshipIdField = exports.parseRelationships = exports.parseRelationship = exports.parseManyToMany = exports.parseManytoOne = exports.parseOneToMany = void 0;
+exports.getRelationshipsForImport = exports.streamNestedRelationships = exports.getNestedRelationships = exports.generateNestedRelationships = exports.getRelationshipForTemplate = exports.getRelationshipIdField = exports.parseRelationships = exports.parseRelationship = exports.parseManyToMany = exports.parseManytoOne = exports.parseOneToMany = void 0;
 const tslib_1 = require("tslib");
 const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
 const casing_1 = require("../../utils/casing");
@@ -355,9 +355,15 @@ const getRelationshipForTemplate = (entityName, relationships) => {
         const relationshipName = (0, casing_1.camelCase)(thisReferenceName || relationship.name);
         const needsPluralInverse = relationship.type === 'ManyToOne' || relationship.type === 'ManyToMany';
         // DEBUG LOGGING
-        if (process.env.DEBUG) {
-            console.log('[DEBUG] relationship.name:', relationship.name, '| relationship.referenceName:', relationship.referenceName, '| thisReferenceName:', thisReferenceName, '| pluralizedRelationshipName:', (0, casing_1.camelCase)((0, pluralize_1.default)(thisReferenceName || relationship.name)), '| pluralizedName:', (0, casing_1.camelCase)((0, pluralize_1.default)(relationship.name)));
-        }
+        // if (process.env.DEBUG) {
+        //   console.log(
+        //     '[DEBUG] relationship.name:', relationship.name,
+        //     '| relationship.referenceName:', relationship.referenceName,
+        //     '| thisReferenceName:', thisReferenceName,
+        //     '| pluralizedRelationshipName:', camelCase(pluralize(thisReferenceName || relationship.name)),
+        //     '| pluralizedName:', camelCase(pluralize(relationship.name))
+        //   );
+        // }
         const inverseSidePropertyName = calculateInversePropertyName(relationship, entityName, relationshipName, needsPluralInverse);
         if (relationship.biDirectional && !relationship.inverseReferenceName &&
             (relationship.type === 'ManyToMany' || relationship.type === 'OneToMany' || relationship.type === 'OneToOne')) {
@@ -379,47 +385,99 @@ const getRelationshipForTemplate = (entityName, relationships) => {
     });
 };
 exports.getRelationshipForTemplate = getRelationshipForTemplate;
-const getNestedRelationships = (entityName, relationshipMap, prefix = "", visited = new Set()) => {
-    const relationships = [];
-    if (visited.has(entityName)) {
-        return relationships;
-    }
-    const currentRelationships = relationshipMap[entityName];
-    if (!currentRelationships)
-        return relationships;
-    visited.add(entityName);
-    for (const relationship of currentRelationships) {
-        const { name: relationshipName, type } = relationship;
+/**
+ * Generates all valid nested join paths for an entity, avoiding cycles and redundant paths.
+ *
+ * Requirements enforced:
+ * 1. No cycles by tracking visited (entity, reference) pairs in the current path
+ * 2. Allow the same entity with different references (proper name vs alias)
+ * 3. Allow different aliases to the same entity in different branches
+ * 4. Respect max depth limit
+ *
+ * @param entityName - Current entity to generate relationships from
+ * @param relationshipMap - Map of all entity relationships
+ * @param maxDepth - Maximum depth of nested joins (default: 6)
+ * @param path - Current join path being built (internal use)
+ * @param visitedPairs - Set of (entity, reference) pairs visited in current path (internal use)
+ * @param baseEntity - The root entity we started from (internal use)
+ * @returns Generator yielding valid join path strings
+ */
+function* generateNestedRelationships(entityName, relationshipMap, maxDepth = 4, path = [], visitedPairs = new Set(), baseEntity = entityName) {
+    // Stop if we've reached maximum depth
+    if (path.length >= maxDepth)
+        return;
+    // Get relationships for the current entity
+    const relationships = relationshipMap[entityName];
+    if (!relationships)
+        return;
+    for (const relationship of relationships) {
         const referenceName = getRelationshipName(relationship);
+        const type = relationship.type;
+        // Format the property name based on relationship type
+        // OneToMany and ManyToMany relationships use plural forms
         const formattedName = type === "ManyToOne" || type === "OneToOne"
-            ? (0, casing_1.camelCase)(referenceName)
-            : (0, casing_1.camelCase)((0, pluralize_1.default)(referenceName));
-        // Create the relationship path while preserving camelCase
-        let relationshipPath;
-        if (prefix) {
-            // Split the path by dots and preserve each segment's casing
-            const segments = prefix.split('.');
-            relationshipPath = `${segments.join('.')}.${formattedName}`;
-        }
-        else {
-            relationshipPath = formattedName;
+            ? referenceName
+            : (0, pluralize_1.default)(referenceName);
+        // Create a unique key for this (entity, reference) pair
+        const entityReferencePair = `${relationship.name}:${referenceName}`;
+        // Check if this exact (entity, reference) pair would create a cycle
+        const wouldCreateCycle = visitedPairs.has(entityReferencePair);
+        // Special case: prevent immediate self-reference loops (same property name)
+        // But allow different properties on the same entity type
+        const isImmediateSelfLoop = relationship.name === entityName &&
+            path.length > 0 &&
+            path[path.length - 1] === formattedName;
+        // Skip immediate self-loops (like networkStack.networkStack)
+        if (isImmediateSelfLoop)
+            continue;
+        // Skip cycles of the same (entity, reference) pair
+        if (wouldCreateCycle)
+            continue;
+        // Handle base entity returns: allow functional aliases but block generic relationships
+        if (relationship.name === baseEntity) {
+            // Check if this is a specific functional alias (different from default entity name)
+            const defaultSingularName = (0, casing_1.camelCase)(relationship.name);
+            const defaultPluralName = (0, casing_1.camelCase)((0, pluralize_1.default)(relationship.name));
+            const originalEntityName = relationship.name;
+            const isSpecificFunctionalAlias = relationship.referenceName &&
+                relationship.referenceName !== defaultSingularName &&
+                relationship.referenceName !== defaultPluralName &&
+                relationship.referenceName !== originalEntityName &&
+                relationship.referenceName !== relationship.name.toLowerCase();
+            // Block generic returns to base entity, allow functional aliases
+            if (!isSpecificFunctionalAlias) {
+                continue;
+            }
         }
-        const hasChild = relationshipPath.includes(".");
-        const exists = prefix
-            .split(".")
-            .some((a) => a === (0, casing_1.camelCase)(referenceName) ||
-            a === (0, casing_1.camelCase)((0, pluralize_1.default)(referenceName)));
-        const deepEnough = prefix.split(".").length >= 4;
-        const canAdd = hasChild && !exists && !deepEnough;
-        if (canAdd) {
-            relationships.push(relationshipPath);
+        // Build the new path
+        const newPath = [...path, formattedName];
+        // Always yield the join path if it's longer than 1 level
+        if (newPath.length > 1) {
+            yield newPath.join(".");
         }
-        const nestedRelationships = (0, exports.getNestedRelationships)(relationshipName, relationshipMap, relationshipPath, new Set(visited));
-        relationships.push(...nestedRelationships);
+        // Create new visited pairs set with the current relationship pair added
+        const newVisitedPairs = new Set(visitedPairs);
+        newVisitedPairs.add(entityReferencePair); // Add the relationship we're about to follow
+        // Recursively generate deeper nested relationships
+        yield* generateNestedRelationships(relationship.name, relationshipMap, maxDepth, newPath, newVisitedPairs, baseEntity);
     }
-    return relationships;
-};
+}
+exports.generateNestedRelationships = generateNestedRelationships;
+// In-memory collector
+function getNestedRelationships(entityName, relationshipMap, maxDepth) {
+    return [...generateNestedRelationships(entityName, relationshipMap, maxDepth)];
+}
 exports.getNestedRelationships = getNestedRelationships;
+// Streaming function
+async function streamNestedRelationships(entityName, relationshipMap, writable, maxDepth) {
+    let count = 0;
+    for (const joinPath of generateNestedRelationships(entityName, relationshipMap, maxDepth)) {
+        writable.write(`"${joinPath}": { eager: false },\n`);
+        count++;
+    }
+    return count;
+}
+exports.streamNestedRelationships = streamNestedRelationships;
 const getRelationshipsForImport = (entityName, relationships) => {
     if (relationships === undefined) {
         return [];

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.7",
+  "version": "0.1.9",
   "commands": {
     "server:new": {
       "id": "server:new",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",
   "bin": {