Service

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

TypeScript

// Example service abstract class (or interface)
export interface WeatherService {
  static Token = "WeatherService";
  public getWeatherByCity(city: string): Promise<Result<Weather>>;
}

// Example service implementation
class WeatherServiceImpl implements WeatherService {
  constructor(
    private apiKey: string,
    private baseUrl: string) {}

  async getWeatherByCity(city: string): Promise<Result<Weather>> {
    try {
      const response =
        await axios.get(`${this.baseUrl}?q=${city}&appid=${this.apiKey}`);
      return Result.withContent(Weather.from(response.data));
    } catch (error) {
      return Result.withFailure(error);
    }
  }
}

In SoapJS projects, services operates similarly to a repository, utilizing IoC (Inversion of Control) principles. In the business logic, we refer to the WeatherService interface rather than a specific implementation, ensuring decoupling and flexibility. The actual service bound to this interface, such as WeatherServiceImpl, is determined within the Dependencies configuration, allowing for easy substitution and testing.

TypeScript

export class Dependencies {
  public async configure() {
    // rest of the components ...
    container
      .bind<WeatherService>(WeatherService.Token)
      .toContantValue(
        new WeatherServiceImpl(
          process.env['WEATHER_API_KEY'],
          process.env['WEATHER_API_URL']
        )
      );
  }
}

Creating new service

Using CLI Command with options

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

soap new service -n "Weather" -e "weather" -m "getWeatherByCity(city:string):Weather" -w -f

Options explained:

• -n: Name of the service (e.g., "Weather").

• -e: Endpoint associated with the service (e.g., "weather").

• -m: Method name(s)/ declaration(s), separated by commas.

• -w: Generate with dependencies included.

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

• --help: display help for command

Using Interactive Form

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

soap new service -w -f

Follow the prompts to enter your service's details.

Using JSON Configuration

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

{
  "services": [
    {
      "name": "Weather",
      "endpoint": "weather",
      "methods": [
        {
          "name": "getWeatherByCity",
          "params": ["city:string"],
          "return_type": "Weather"
        }
      ]
    }
  ]
}

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.

• --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.

File Structure

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

src/
  - shop/
    - data/
      - services/
        - weather.service-impl.ts
        - index.ts
    - domain/
      - services/
        - weather.service.ts
        - index.ts
      - entities/
        - weather.ts
        - index.ts
...