Skip to main content
The @ooneex/service component is the service layer foundation for Ooneex applications. A service is an injectable unit of business logic — order processing, payment handling, email dispatch — that you register with a decorator and resolve from the container. Each service implements the IService interface, exposing a single execute(data?) entry point, and is wired into @ooneex/container so dependencies resolve automatically.

​
Why this component

  • Business logic in one place. Keep domain operations out of controllers and routes; controllers stay thin and delegate to services.
  • Container-managed. Register a service with @decorator.service() and resolve it anywhere with container.get() — no manual wiring.
  • One contract. Every service implements IService, so they all share the same execute(data?) shape and compose predictably.
  • Scope control. Choose singleton, transient, or request scope per service to match its lifecycle.
  • Composable. Services resolve and call other services, building larger operations from smaller units.

​
How it works

A service is a plain class decorated with @decorator.service(). The decorator calls container.add(target, scope), registering the class with @ooneex/container. From then on, container.get(MyService) returns an instance with its scope honored — the container constructs it, caches it (for singletons), and resolves any container-backed dependencies it pulls in. The IService contract is intentionally minimal:
MemberPurpose
execute(data?)The service’s single entry point. Accepts optional input data and runs the business logic.
export interface IService {
  execute: (data?: any) => Promise<any> | any;
}
The decorator defaults to the singleton scope, but accepts any EContainerScope:
ScopeLifecycle
EContainerScope.SingletonOne instance shared across the whole application (default).
EContainerScope.TransientA new instance on every container.get() resolution.
EContainerScope.RequestA new instance per request context.

​
Decorator and usage

​
@decorator.service(scope?)

Registers a service class with the container. It takes an optional scope (defaults to EContainerScope.Singleton) and returns a class decorator that adds the target to the container. 
import { decorator, type IService } from "@ooneex/service";

interface InvoiceData {
  items: Array<{ price: number; quantity: number }>;
  taxRate: number;
}

@decorator.service()
export class InvoiceService implements IService {
  public async execute(data?: InvoiceData): Promise<number> {
    if (!data) return 0;

    const subtotal = data.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0,
    );

    return subtotal * (1 + data.taxRate);
  }
}
Resolve it from the container wherever you need it — the decorator already registered it: 
import { container } from "@ooneex/container";
import { InvoiceService } from "./services/InvoiceService";

const invoiceService = container.get(InvoiceService);

const total = await invoiceService.execute({
  items: [{ price: 19.99, quantity: 2 }],
  taxRate: 0.2,
});
Pass a scope to change the lifecycle — for example, a fresh instance per resolution: 
import { decorator, type IService } from "@ooneex/service";
import { EContainerScope } from "@ooneex/container";

@decorator.service(EContainerScope.Transient)
export class RequestContextService implements IService {
  private readonly requestId = crypto.randomUUID();

  public async execute(): Promise<string> {
    return this.requestId;
  }
}
Services compose by resolving one another from the container, letting a higher-level operation orchestrate smaller services: 
import { container } from "@ooneex/container";
import { decorator, type IService } from "@ooneex/service";
import { InvoiceService } from "./InvoiceService";

interface CheckoutData {
  items: Array<{ price: number; quantity: number }>;
  taxRate: number;
}

@decorator.service()
export class CheckoutService implements IService {
  private readonly invoiceService = container.get(InvoiceService);

  public async execute(data?: CheckoutData): Promise<void> {
    if (!data) return;

    const total = await this.invoiceService.execute(data);
    // ...charge the customer, persist the order, etc.
  }
}

​
Best practices

  • One responsibility per service. A service handles a single business operation; compose services rather than growing one into a god class.
  • Keep execute() the public entry point. Put orchestration in execute() and break the steps into private methods.
  • Type the input. Replace the default Record<string, unknown> data shape with a precise interface for the service’s input.
  • Handle the empty case. data is optional — guard for undefined before using it.
  • Resolve, don’t construct. Get services from the container with container.get() so scopes and dependencies are honored; avoid new.
  • Pick the right scope. Default to singleton for stateless logic; use transient or request scope only when per-call or per-request state matters.
  • Let controllers stay thin. Keep routing and HTTP concerns in controllers and delegate the work to services.

​
CLI command

Scaffold a service class and its test file with the generator. It writes the class under modules/<module>/src/services/<Name>Service.ts, adds a matching test, and installs @ooneex/service if it is missing. 
# Interactive: prompts for the name
ooneex service:create

# Provide the name
ooneex service:create --name=Invoice

# Target a module and overwrite
ooneex service:create --name=Invoice --module=billing --override
OptionDescriptionDefault
--nameService class name. The Service suffix is appended automatically.Prompted if omitted
--moduleTarget module the class is generated into.shared
--overrideOverwrite an existing class without prompting.false
The generated class is a ready-to-fill IService stub: 
import { decorator } from "@ooneex/service";
import type { IService } from "@ooneex/service";

type ServiceDataType = Record<string, unknown>;

@decorator.service()
export class InvoiceService implements IService {
  // biome-ignore lint/suspicious/noExplicitAny: trust me
  public async execute(data?: ServiceDataType): Promise<any> {
    // TODO: Implement service logic
  }
}
See service:create for the full command reference.

​
Use with Claude and Codex

The generator ships a matching service:create skill. It runs the scaffold and then guides your AI agent through completing the service — defining a real ServiceDataType, implementing execute() with the business logic, and injecting dependencies. Initialize the skills once for your agent: 
ooneex claude:init
Then ask Claude in natural language — it maps the request to the generator, runs it, and fills in the implementation:
Prompt
Create a service that calculates invoice totals.
For example, the prompt above maps to service:create --name=Invoice, then implements execute() to compute the totals.