Skip to main content

ApinniDomain Decorator

The @ApinniDomain decorator groups API endpoints into logical domains, organizing their generated type definitions into separate files (e.g., auth-types.d.ts, api-types.d.ts). It works with @ApinniController and @ApinniEndpoint to provide a structured approach to API type generation, improving modularity and maintainability in large projects.

Key Features
  • Groups endpoints into domains for organized type generation.
  • Generates separate type definition files per domain.
  • Supports single or multiple domains for flexible organization.
  • Enhances API modularity and type discoverability.

Syntax​

Use the @ApinniDomain decorator to annotate a controller class, specifying one or more domains to group its endpoints.

Basic Syntax
@ApinniDomain({ domains: ['auth'] })
@ApinniController({ path: '/auth' })
class AuthController {}

Options​

The decorator accepts an options object with the following property:

PropertyTypeDescription
domainsstring[]An array of strings defining the domain(s) for generated types (e.g., ["auth"] or ["auth", "api"]).
tip

Use descriptive domain names (e.g., auth, user, billing) to clearly organize generated type files and improve project scalability.

Domain-Based Type Generation​

The @ApinniDomain decorator instructs the Apinni pipeline to generate type definitions for a controller’s endpoints in separate files based on the specified domains. Each domain corresponds to a type definition file (e.g., auth-types.d.ts), containing the request and response types for all endpoints in that domain. Endpoints in a controller are included in the type files for each specified domain, allowing flexible organization across multiple type files.

Usage with ApinniController and ApinniEndpoint​

The @ApinniDomain decorator is applied at the controller level and works with @ApinniController to set the base path and @ApinniEndpoint to define individual endpoints. The generated types for these endpoints are organized into the specified domain files.

Example 1: Single Domain​

Group endpoints into a single domain for type generation.

Single Domain
import { ApinniController, ApinniEndpoint, ApinniDomain } from '@apinni/client-ts';

@ApinniDomain({ domains: 'auth' })
@ApinniController({ path: '/auth' })
class AuthController {
  @ApinniEndpoint({ path: '/login', method: 'POST' })
  login() {
    return { token: 'abc123' };
  }
}
example
  • Domain: auth
  • Generated File: auth-types.d.ts
  • Endpoint: /auth/login (POST)
  • Generated Types: Includes request/response types for login endpoint

Example 2: Multiple Domains​

Group endpoints into multiple domains for flexible type organization.

Multiple Domains
import { ApinniController, ApinniEndpoint, ApinniDomain } from '@apinni/client-ts';

@ApinniDomain({ domains: ['auth', 'api'] })
@ApinniController({ path: '/auth' })
class AuthController {
  @ApinniEndpoint({ path: '/login', method: 'POST' })
  login() {
    return { token: 'abc123' };
  }
}
example
  • Domains: auth, api
  • Generated Files: auth-types.d.ts, api-types.d.ts
  • Endpoint: /auth/login (POST)
  • Generated Types: Included in both auth-types.d.ts and api-types.d.ts

Example 3: Multiple Controllers with Domains​

Define multiple controllers grouped into domains.

Multiple Endpoints with Domains
import { ApinniController, ApinniEndpoint, ApinniDomain } from '@apinni/client-ts';
import type { User } from './types';

type LoginRequest = { username: string; password: string };
type LoginResponse = { token: string };
type UsersResponse = Array<User>;

@ApinniDomain({ domains: ['auth', 'api'] })
@ApinniController({ path: '/auth' })
class AuthController {
  @ApinniEndpoint({
    path: '/login',
    method: 'POST',
    request: { model: 'LoginRequest' },
    responses: { 200: { model: 'LoginResponse' } }
  })
  login() {
    return { token: 'abc123' };
  }
}

@ApinniDomain({ domains: ['api'] })
@ApinniController({ path: '/users' })
class UserController {
  @ApinniEndpoint<{ responses: { type: UsersResponse }}>({
    path: '/find',
    method: 'GET',
  })
  getUsers() {
    return [/* users */];
  }
}
example
  • Generated Files: auth-types.d.ts, api-types.d.ts
  • Endpoints:
    • /auth/login presented in both auth-types.d.ts and api-types.d.ts files
    • /users/find presented in api-types.d.ts file

Usage Notes​

  • Domain Naming: Use clear, meaningful domain names to reflect the purpose of the endpoints (e.g., auth for authentication-related endpoints).
  • Type Generation: Each domain generates a separate .d.ts file containing all endpoint types for the controller.
  • Multiple Domains: Endpoints are included in all specified domains’ type files, allowing flexible organization.
warning

Avoid empty or invalid domain names to prevent errors in type generation. Ensure domain names are unique within your project to avoid file conflicts.

Try It Out

Explore these examples in a live TypeScript environment: CodeSandbox Link.

info

For advanced use cases, check the Apinni API Reference or contact the Apinni community.