Create Resource Service

Creates a service for CRUD operations on a domain entity. Resource services extend

BaseService

for event emission, inject repositories for data access, and use

AuthorizationService

for permission checks.

Quick Reference

Location:

src/services/{entity-name}.service.ts

Naming: Singular, kebab-case (e.g.,

note.service.ts

,

course.service.ts

)

Prerequisites

Before creating a resource service, ensure you have:

1. Schema created (

   src/schemas/{entity-name}.schema.ts

   )
2. Repository interface created (

   src/repositories/{entity-name}.repository.ts

   )
3. At least one repository implementation (MockDB or MongoDB)

Instructions

Step 1: Create the Service File

Create

src/services/{entity-name}.service.ts

Step 2: Import Dependencies

import type { I{Entity}Repository } from "@/repositories/{entity-name}.repository";
import type { PaginatedResultType } from "@/schemas/shared.schema";
import type {
  Create{Entity}Type,
  {Entity}QueryParamsType,
  {Entity}Type,
  Update{Entity}Type,
} from "@/schemas/{entity-name}.schema";
import type { AuthenticatedUserContextType } from "@/schemas/user.schemas";
import { AuthorizationService } from "@/services/authorization.service";
import { UnauthorizedError } from "@/errors";
import { MockDb{Entity}Repository } from "@/repositories/mockdb/{entity-name}.mockdb.repository";
import { BaseService } from "@/events/base.service";

Step 3: Create the Service Class

export class {Entity}Service extends BaseService {
  private readonly {entity}Repository: I{Entity}Repository;
  private readonly authorizationService: AuthorizationService;

  constructor(
    {entity}Repository?: I{Entity}Repository,
    authorizationService?: AuthorizationService,
  ) {
    super("{entities}"); // Service name for events (plural)

    this.{entity}Repository = {entity}Repository ?? new MockDb{Entity}Repository();
    this.authorizationService = authorizationService ?? new AuthorizationService();
  }

  // CRUD methods...
}

Step 4: Implement CRUD Methods

getAll

async getAll(
  params: {Entity}QueryParamsType,
  user: AuthenticatedUserContextType,
): Promise<PaginatedResultType<{Entity}Type>> {
  // Admins see all, users see only their own
  if (this.authorizationService.isAdmin(user)) {
    return this.{entity}Repository.findAll(params);
  }
  return this.{entity}Repository.findAll({ ...params, createdBy: user.userId });
}

getById

async getById(
  id: string,
  user: AuthenticatedUserContextType,
): Promise<{Entity}Type | null> {
  const {entity} = await this.{entity}Repository.findById(id);
  if (!{entity}) {
    return null;
  }

  const canView = await this.authorizationService.canView{Entity}(user, {entity});
  if (!canView) throw new UnauthorizedError();

  return {entity};
}

create

async create(
  data: Create{Entity}Type,
  user: AuthenticatedUserContextType,
): Promise<{Entity}Type> {
  const canCreate = await this.authorizationService.canCreate{Entity}(user);
  if (!canCreate) throw new UnauthorizedError();

  const {entity} = await this.{entity}Repository.create(data, user.userId);

  this.emitEvent("created", {entity}, {
    id: {entity}.id,
    user,
  });

  return {entity};
}

update

async update(
  id: string,
  data: Update{Entity}Type,
  user: AuthenticatedUserContextType,
): Promise<{Entity}Type | null> {
  const {entity} = await this.{entity}Repository.findById(id);
  if (!{entity}) {
    return null;
  }

  const canUpdate = await this.authorizationService.canUpdate{Entity}(user, {entity});
  if (!canUpdate) throw new UnauthorizedError();

  const updated{Entity} = await this.{entity}Repository.update(id, data);
  if (!updated{Entity}) {
    return null;
  }

  this.emitEvent("updated", updated{Entity}, {
    id: updated{Entity}.id,
    user,
  });

  return updated{Entity};
}

delete

async delete(
  id: string,
  user: AuthenticatedUserContextType,
): Promise<boolean> {
  const {entity} = await this.{entity}Repository.findById(id);
  if (!{entity}) {
    return false;
  }

  const canDelete = await this.authorizationService.canDelete{Entity}(user, {entity});
  if (!canDelete) throw new UnauthorizedError();

  const deleted = await this.{entity}Repository.remove(id);
  if (deleted) {
    this.emitEvent("deleted", {entity}, {
      id: {entity}.id,
      user,
    });
  }

  return deleted;
}

Patterns & Rules

Extending BaseService

export class {Entity}Service extends BaseService {
  constructor(...) {
    super("{entities}"); // Plural name for event namespace
  }
}

The

serviceName

is used for event routing (e.g.,

notes:created

,

notes:updated

).

Dependency Injection

constructor(
  {entity}Repository?: I{Entity}Repository,
  authorizationService?: AuthorizationService,
) {
  // Provide defaults for convenience, but allow injection for testing
  this.{entity}Repository = {entity}Repository ?? new MockDb{Entity}Repository();
  this.authorizationService = authorizationService ?? new AuthorizationService();
}

• Accept interfaces for repositories (not concrete classes)
• Provide defaults for easier instantiation
• Allow injection for testing with mocks

Authorization Pattern

Every operation should check permissions:

const canDoX = await this.authorizationService.canX{Entity}(user, {entity});
if (!canDoX) throw new UnauthorizedError();

You must add corresponding methods to

AuthorizationService

:

• canView{Entity}(user, entity)

• canCreate{Entity}(user)

• canUpdate{Entity}(user, entity)

• canDelete{Entity}(user, entity)

Event Emission Pattern

Emit events after successful operations:

this.emitEvent("created", {entity}, { id: {entity}.id, user });
this.emitEvent("updated", updated{Entity}, { id: updated{Entity}.id, user });
this.emitEvent("deleted", {entity}, { id: {entity}.id, user });

Events are only emitted for

create

,

update

,

delete

- not for reads.

Error Handling

• Not found: Return

  null

  (let controller decide HTTP status)
• Unauthorized: Throw

  UnauthorizedError

  from

  @/errors

• Other errors: Let them propagate (global error handler catches)

Return Types

• getAll

  :

  Promise<PaginatedResultType<{Entity}Type>>

• getById

  :

  Promise<{Entity}Type | null>

• create

  :

  Promise<{Entity}Type>

• update

  :

  Promise<{Entity}Type | null>

• delete

  :

  Promise<boolean>

Complete Example

See REFERENCE.md for a complete

NoteService

implementation.

After Creating the Service

1. Add authorization methods to

   AuthorizationService

   for this entity
2. Add event schema (optional) - see

   add-resource-events

   skill
3. Create controller - see

   create-controller

   skill
4. Write tests - see

   test-service

   skill

What NOT to Do

• Do NOT put HTTP-specific logic in services (that's for controllers)
• Do NOT return HTTP status codes or responses
• Do NOT skip authorization checks
• Do NOT emit events before confirming the operation succeeded
• Do NOT inject concrete repository classes - use interfaces