tshex-cli 1.0.13 → 1.0.15

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 virtualitems
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 virtualitems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/build/main.js

@@ -1,22 +1,15 @@
 #!/usr/bin/env node
 import { program } from 'commander';
-import fs from 'fs';
-import path from 'path';
-var packageJson = JSON.parse(fs.readFileSync(path.join(import.meta.dirname, '..', 'package.json'), 'utf-8'));
-program
-    .name('tshex')
-    .version(packageJson.version)
-    .option('--lib <name>', 'creates a new library with it\'s shared directory')
-    .option('--ctx <name>', 'creates a new context')
-    .option('--cls <name>', 'creates a new class')
-    .option('--rfc <name>', 'creates a new react functional component')
-    .option('--dir <path>', 'sets the directory to create the new item')
-    .parse(process.argv);
+import fs from 'node:fs';
+import path from 'node:path';
+function readPackageJson() {
+    return JSON.parse(fs.readFileSync(path.join(import.meta.dirname, '..', 'package.json'), 'utf-8'));
+}
 function executeCreateLib(templatesDir, libraryDir) {
     try {
         fs.cpSync(path.join(templatesDir, 'lib'), libraryDir, {
             recursive: true,
-            filter: function (src) { return (!src.endsWith('.gitkeep')); }
+            filter: (src) => !src.endsWith('.gitkeep')
         });
         console.log('Library created successfully');
     }
@@ -28,7 +21,7 @@ function executeCreateContext(templatesDir, contextDir) {
     try {
         fs.cpSync(path.join(templatesDir, 'ctx'), contextDir, {
             recursive: true,
-            filter: function (src) { return (!src.endsWith('.gitkeep')); }
+            filter: (src) => !src.endsWith('.gitkeep')
         });
         console.log('Context created successfully');
     }
@@ -36,29 +29,10 @@ function executeCreateContext(templatesDir, contextDir) {
         console.error(err);
     }
 }
-function executeCreateClass(templatesDir, classDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'cls.example'), classDir, {});
-        console.log('Class created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-function executeCreateReactFunctionalComponent(templatesDir, classDir) {
-    try {
-        fs.cpSync(path.join(templatesDir, 'rfc.example'), classDir, {});
-        console.log('React component created successfully');
-    }
-    catch (err) {
-        console.error(err);
-    }
-}
-(function () {
-    var _a;
-    var templatesDir = path.join(import.meta.dirname, '..', 'templates');
-    var options = program.opts();
-    var targetDir = path.resolve((_a = options.dir) !== null && _a !== void 0 ? _a : process.cwd());
+function main(program) {
+    const templatesDir = path.join(import.meta.dirname, '..', 'templates');
+    const options = program.opts();
+    let targetDir = path.resolve(options.dir ?? process.cwd());
     if (Object.keys(options).length === 0) {
         program.help();
         return;
@@ -74,12 +48,13 @@ function executeCreateReactFunctionalComponent(templatesDir, classDir) {
         targetDir = path.join(targetDir, options.ctx);
         executeCreateContext(templatesDir, targetDir);
     }
-    if (options.cls !== undefined) {
-        var target = path.join(targetDir, options.cls + '.ts');
-        executeCreateClass(templatesDir, target);
-    }
-    if (options.rfc !== undefined) {
-        var target = path.join(targetDir, options.rfc + '.tsx');
-        executeCreateReactFunctionalComponent(templatesDir, target);
-    }
-})();
+}
+const packageJson = readPackageJson();
+program
+    .name('tshex')
+    .version(packageJson.version)
+    .option('--lib <name>', "creates a new library with it's shared directory")
+    .option('--ctx <name>', 'creates a new context')
+    .option('--dir <path>', 'sets the directory to create the new item')
+    .parse(process.argv);
+main(program);

package/package.json

@@ -1,52 +1,50 @@
-{
-  "name": "tshex-cli",
-  "version": "1.0.13",
-  "author": "https://github.com/virtualitems/",
-  "description": "Typescript Hexagonal Architecture CLI",
-  "type": "module",
-  "main": "./build/main.js",
-  "keywords": [
-    "architecture",
-    "clean-architecture",
-    "clean",
-    "cli",
-    "ddd",
-    "design-patterns",
-    "design",
-    "domain-driven-design",
-    "hexagonal",
-    "pattern",
-    "software-architecture",
-    "tshex",
-    "tshex-cli",
-    "typescript",
-    "virtualitems"
-  ],
-  "homepage": "https://github.com/virtualitems/tshex-cli",
-  "bugs": {
-    "url": "https://github.com/virtualitems/tshex-cli/issues"
-  },
-  "files": [
-    "./build",
-    "./source",
-    "./templates"
-  ],
-  "types": "./source/index.d.ts",
-  "scripts": {
-    "examples": "tsc -p examples",
-    "build": "tsc && tsc-alias",
-    "dev": "tsc -w"
-  },
-  "devDependencies": {
-    "@types/commander": "^2.12.0",
-    "@types/node": "^22.5.4",
-    "tsc-alias": "^1.8.10",
-    "typescript": "^5.4.5"
-  },
-  "dependencies": {
-    "commander": "^12.1.0"
-  },
-  "bin": {
-    "tshex": "./build/main.js"
-  }
-}
+{
+  "name": "tshex-cli",
+  "version": "1.0.15",
+  "author": "https://github.com/virtualitems/",
+  "description": "Typescript Hexagonal Architecture CLI",
+  "type": "module",
+  "main": "./build/main.js",
+  "keywords": [
+    "architecture",
+    "clean-architecture",
+    "clean",
+    "cli",
+    "ddd",
+    "design-patterns",
+    "design",
+    "domain-driven-design",
+    "hexagonal",
+    "pattern",
+    "software-architecture",
+    "tshex",
+    "tshex-cli",
+    "typescript",
+    "virtualitems"
+  ],
+  "homepage": "https://github.com/virtualitems/tshex-cli",
+  "bugs": {
+    "url": "https://github.com/virtualitems/tshex-cli/issues"
+  },
+  "files": [
+    "./build",
+    "./source",
+    "./templates"
+  ],
+  "types": "./source/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^22.5.4",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "bin": {
+    "tshex": "./build/main.js"
+  },
+  "scripts": {
+    "examples": "tsc -p examples",
+    "build": "tsc",
+    "dev": "tsc -w"
+  }
+}

package/readme.md

@@ -1,76 +1,205 @@
-# Hexagonal Architecture CLI
-
-This CLI will help you to generate a hexagonal architecture structure.
-
-# Why?
-
-Hexagonal architecture is a software design pattern that separates the internal domain of the application from the external dependencies.. This separation is achieved by dividing the application into layers. Each layer has a specific responsibility and interacts with the other layers in a specific way.
-
-Because what we are trying to achieve is a separation between the domain code and the installed dependencies, a Hexagonal Architecture Framework is a step in the opposite direction, as it couples the domain code with the framework. This is why we need a tool to help us to create the structure with our own codebase.
-
-# Usage example
-
-https://github.com/virtualitems/tshex-cli
-
-# Note!!!
-
-This tool and its templates are in constant development, so be aware that some changes may occur and be careful when updating the tool.
-
-If you have any suggestions or improvements, please let me know.
-
-https://github.com/virtualitems/tshex-cli/issues
-
-# Installation
-
-```bash
-npm install -g tshex-cli
-```
-
-# Usage
-
-> Remember to replace placeholders `<...>` with the actual data.
->
-
-## Getting started
-
-```bash
-tshex --lib <library-name> --ctx <context-name>
-```
-
-## Help
-
-```bash
-tshex -h
-
-tshex --help
-```
-
-## Create a new library
-
-```bash
-tshex --lib <name>
-```
-
-## Create a new context
-
-```bash
-tshex --ctx <name>
-```
-
-## Create a new class
-
-```bash
-tshex --cls <name>
-```
-
-## Create a new react functional component
-
-```bash
-tshex --rfc <name>
-```
-
-## Set the directory to create the new items
-
-```bash
-tshex --lib <lib-name> --ctx <ctx-name> --dir <path>
-```
+# Hexagonal Architecture CLI
+
+This CLI will help you to generate a hexagonal architecture structure.
+
+# Why?
+
+Hexagonal architecture is a software design pattern that separates the internal domain of the application from the external dependencies. This separation is achieved by dividing the application into layers. Each layer has a specific responsibility and interacts with the other layers in a specific way.
+
+The goal is to separate the domain code from installed dependencies. A Hexagonal Architecture _framework_ would work against that goal, since it couples the domain code to the framework itself. That is why this CLI exists: it scaffolds the structure for you, using your own codebase instead of a framework.
+
+# Note
+
+This tool and its templates are in constant development, so be aware that some changes may occur and be careful when updating the tool.
+
+If you have any suggestions or improvements, please let me know.
+
+https://github.com/virtualitems/tshex-cli/issues
+
+# Getting started
+
+`tshex` scaffolds folders and files for a hexagonal architecture project. It does not write business logic for you; it only generates the structure, so you can fill it in with your own code.
+
+There are two things you can generate:
+
+- A **library** (`--lib`): the shared foundation of a project. It contains the domain and application contracts (entities, value objects, services, etc.) that the rest of the code depends on.
+- A **context** (`--ctx`): a specific business area (e.g. `users`, `billing`, `orders`). It contains the `domain/`, `application/`, and `adapters/` folders where you implement that area's logic.
+
+A typical project has one library and one or more contexts inside it.
+
+## Install
+
+Install the CLI globally:
+
+```bash
+npm install -g tshex-cli
+```
+
+Check the installation:
+
+```bash
+tshex --version
+```
+
+Show the command options:
+
+```bash
+tshex --help
+```
+
+## Usage
+
+```bash
+tshex [--lib <name>] [--ctx <name>] [--dir <path>]
+```
+
+| Option         | Purpose                                                            |
+| -------------- | ------------------------------------------------------------------- |
+| `--lib <name>` | Generate a library called `<name>`, based on `templates/lib`.       |
+| `--ctx <name>` | Generate a context called `<name>`, based on `templates/ctx`.       |
+| `--dir <path>` | Parent directory where the library/context will be created. Defaults to the current directory. |
+| `--help`       | Show the command options.                                           |
+| `--version`    | Show the installed version.                                         |
+
+`--lib` and `--ctx` can be used together in a single command (see [Create a library and a context together](#create-a-library-and-a-context-together)). Running `tshex` without any options just prints the help text — it does not generate anything.
+
+## Create a library
+
+Use this when you are starting a new project and need the shared contracts that the rest of your code will build on:
+
+```bash
+tshex --lib core
+```
+
+This generates a `core/` folder in the current directory:
+
+```text
+core/
+├── index.d.ts
+├── main.ts
+└── shared/
+    ├── application/
+    │   ├── databases.ts
+    │   ├── events.ts
+    │   ├── http.ts
+    │   ├── loggers.ts
+    │   └── services.ts
+    └── domain/
+        ├── aggregates.ts
+        ├── entities.ts
+        ├── errors.ts
+        └── value-objects.ts
+```
+
+What each file is for:
+
+| File               | Purpose                                       |
+| ------------------ | --------------------------------------------- |
+| `index.d.ts`       | Declare library types.                        |
+| `main.ts`          | Export the library API.                       |
+| `entities.ts`      | Define entity contracts.                      |
+| `value-objects.ts` | Define value objects and validation.          |
+| `aggregates.ts`    | Define aggregate contracts.                   |
+| `errors.ts`        | Define domain errors.                         |
+| `services.ts`      | Define application service contracts.         |
+| `databases.ts`     | Define data manager and repository contracts. |
+| `events.ts`        | Define event contracts.                       |
+| `http.ts`          | Define HTTP response contracts.               |
+| `loggers.ts`       | Define logger contracts.                      |
+
+`main.ts` is generated with a placeholder `throw new Error('Not implemented yet')`, so the library fails loudly if you try to use it before filling it in. To start using it, open `main.ts`, remove that line, and export your own code, built on top of the shared contracts. For example:
+
+```ts
+export { Entity } from './shared/domain/entities.js'
+export { ValueObject, Email } from './shared/domain/value-objects.js'
+
+class User extends Entity {
+    constructor(public readonly email: Email) {
+        super()
+    }
+}
+```
+
+## Create a context
+
+Use this to scaffold a specific business area, such as `users`, inside an existing library (or on its own):
+
+```bash
+tshex --ctx users
+```
+
+This generates a `users/` folder in the current directory:
+
+```text
+users/
+├── adapters/
+├── application/
+├── domain/
+└── index.ts
+```
+
+What each part is for:
+
+| Path           | Purpose                                                         |
+| -------------- | ---------------------------------------------------------------- |
+| `domain/`      | Entities, value objects, aggregates, and domain errors.          |
+| `application/` | Use cases, services, DTOs, and contracts.                        |
+| `adapters/`    | Database, HTTP, event, file, and service implementations.        |
+| `index.ts`     | Export or compose the context's public API.                      |
+
+## Choose the destination folder
+
+By default, `tshex` creates files in your current directory. Use `--dir` to choose a different parent directory instead.
+
+Create a library inside `./src`:
+
+```bash
+tshex --lib core --dir ./src
+```
+
+This generates the library at:
+
+```text
+./src/core
+```
+
+Create a context inside that library:
+
+```bash
+tshex --ctx users --dir ./src/core
+```
+
+This generates the context at:
+
+```text
+./src/core/users
+```
+
+You can also use an absolute path:
+
+```bash
+tshex --ctx users --dir /workspace/project/src
+```
+
+## Create a library and a context together
+
+You can generate both in a single command. `tshex` creates the library first, then creates the context inside it:
+
+```bash
+tshex --dir ./src --lib core --ctx users
+```
+
+Result:
+
+```text
+src/
+└── core/
+    ├── index.d.ts
+    ├── main.ts
+    ├── shared/
+    └── users/
+        ├── adapters/
+        ├── application/
+        ├── domain/
+        └── index.ts
+```