Controller

In this guide, we'll go through the steps to create a new controller in your SoapJS project. You can create controllers using CLI commands, interactive forms, or by defining them in a JSON file.

TypeScript

export class CustomerController {
  static Token = 'CustomerController';

  public async getCustomerDetails(input: string): Promise<Result<Customer>> {
    let result: Result;
    // call use case (may include simple logic)
    return result;
  }
  ...
}

Since the Controller is inherently linked to routes, its integration becomes essential when you include a web framework in your project's configuration. If you opt to create a controller through the CLI, either by specifying details in a JSON file or via the interactive mode, and include routing information during this process, the corresponding controller will be seamlessly integrated into the routing system. This integration ensures that, post-creation, the controller is automatically registered within the router, facilitating immediate route handling and response.

Creating new controller

Using CLI Command with options

To create a new controller directly via the CLI, use the following command:

soap new controller -n "Customer" -e "shop" -h "getCustomerDetails(id:string):Entity<Customer>" -w -f

Options explained:

• -n: Name the controller. If not set uses endpoint.

• -e: Endpoint associated with the controller (e.g., "shop").

• -h: List handler names and/or declarations

• --no-tests: Skip test generation.

• --no-rel: Skip generating related files. You can also specify specific groups.

• --force: Force the creation, overwrite files if necessary.

• --patch: Add content to the files if they exists.

• --help: display help for command

Keep in mind that controller is a complex component with many dependencies, especially related to the routes. When creating a controller using a command and options, you will only be limited to creating the controller and entities/models included in input or output.

Using Interactive Form

If you prefer to use an interactive form to specify your controller details, simply run:

soap new controller -w -f

Follow the prompts to enter your controller's details.

Using JSON Configuration

Alternatively, you can define your controller in a JSON file. Here is an example structure:

{
  "controllers": [
    {
      "name": "Customer",
      "endpoint": "shop",
      "handlers": [
        {
          "name": "getCustomerDetails",
          "is_async": true,
          "params": [
            {
              "name": "input",
              "type": "string"
            }
          ],
          "return_type": "Entity<Customer>"
        }
      ]
    }
  ]
}

Save this to a file, for example api.json, and run:

soap new --json "./path/to/api.json" -w -f

Options:

• --json: Path to your JSON configuration file.

• -w: Generate with dependencies included.

• -f: Force the creation, overwrite files if necessary.

File Structure

After creating your controller, your file structure (assuming default configuration settings) should look like this:

src/
  - shop/
    - domain/
      - entities/
        - customer.ts
        - index.ts
      - controllers/
        - customer.controller.ts
        - index.ts
...

# OR (including routing)

src/
  - shop/
    - domain/
      - entities/
        - customer.ts
        - index.ts
      - controllers/
        - customer.controller.ts
        - index.ts
    - routes/
      - get-customer-details.route.ts
      - get-customer-details.route-io.ts
      - index.ts
  - router.ts
  - dependencies.ts
...