FormulaConfigurationService

FormulaConfigurationService

Type: Service Domain: Frontend — Configuration API Client File: src/services/formulaConfiguration.service.ts Last updated: 2026-09-10 Status: Current

Overview

The FormulaConfigurationService class is the backend API client for formula configuration endpoints. It targets /api/configuration/formulas with a date-effective lifecycle model supporting complete-set PUT updates and date-effective reads. The service extends HttpClient and uses CancelablePromise for request cancellation.

Public Interface

Constructor

constructor(readonly config: APIConfig)

Parameter	Type	Description
config	APIConfig	API client configuration (base URL, headers, interceptors)

Methods

getFormulaSets(pageable, meta?)

Retrieves a paginated list of formula sets.

getFormulaSets(
  pageable: PageableRequest<FormulaSetResponse>,
  meta?: Record<string, unknown>
): CancelablePromise<FormulaSetListResponse>

Parameter	Type	Description
pageable	PageableRequest<FormulaSetResponse>	Pagination and sorting options (page, size, sort)
meta	Record<string, unknown>	Optional request metadata

Request: GET /api/configuration/formulas?page={page}&size={size}&sort={sort}

Response: FormulaSetListResponse

{
  content: FormulaSetResponse[],
  page: { number: number, size: number, totalElements: number, totalPages: number }
}

Errors: Standard HTTP errors via interceptor (401, 403, 500)

---

getEffectiveFormulaSet(params, meta?)

Retrieves the formula set effective for a given date and area. This is the date-effective lookup endpoint used by downstream calculation services.

getEffectiveFormulaSet(
  params: FormulaSetEffectiveParams,
  meta?: Record<string, unknown>
): CancelablePromise<FormulaSetResponse>

Parameter	Type	Description
params	FormulaSetEffectiveParams	{ date: 'YYYY-MM-DD', area: 'INTERIOR' | 'COASTAL' }
meta	Record<string, unknown>	Optional request metadata

Request: GET /api/configuration/formulas/{date}/{area}

Response: FormulaSetResponse — the single effective set

Errors:

• 400 — Invalid date format or area (not INTERIOR/COASTAL)
• 404 — No formula set effective for that date/area

---

createFormulaSet(dto, meta?)

Creates a new formula set. The backend assigns the ID and timestamps.

createFormulaSet(
  dto: FormulaSetRequest,
  meta?: Record<string, unknown>
): CancelablePromise<FormulaSetResponse>

Parameter	Type	Description
dto	FormulaSetRequest	{ area, startDate, endDate, formulas }
meta	Record<string, unknown>	Optional request metadata

Request: POST /api/configuration/formulas with body FormulaSetRequest

Response: FormulaSetResponse — created set with assigned id, createdAt, updatedAt

Errors:

• 422 — Validation failed (one or more formulas invalid)

---

updateFormulaSet(id, dto, meta?)

Updates a formula set with a complete replacement (idempotent PUT). The entire formula set is replaced — this is not a partial update.

updateFormulaSet(
  id: number,
  dto: FormulaSetRequest,
  meta?: Record<string, unknown>
): CancelablePromise<FormulaSetResponse>

Parameter	Type	Description
id	number	Formula set ID
dto	FormulaSetRequest	Complete formula set payload
meta	Record<string, unknown>	Optional request metadata

Request: PUT /api/configuration/formulas/{id} with body FormulaSetRequest

Response: FormulaSetResponse — updated set with new updatedAt

Errors:

• 404 — Formula set not found
• 422 — Validation failed or lifecycle rule violation
• 409 — Conflict: future open-ended set already exists for the area

---

deleteFormulaSet(id, meta?)

Soft-deletes a future open-ended formula set. Only sets with startDate > today and endDate === null can be deleted. Deleting reopens the predecessor by clearing its end date.

deleteFormulaSet(
  id: number,
  meta?: Record<string, unknown>
): CancelablePromise<void>

Parameter	Type	Description
id	number	Formula set ID
meta	Record<string, unknown>	Optional request metadata

Request: DELETE /api/configuration/formulas/{id}

Response: 204 No Content

Errors:

• 404 — Formula set not found
• 422 — Not a future open-ended set (cannot delete closed/historical/deleted sets)

---

Types

All types defined in src/services/formulaConfiguration.types.ts:

FormulaValidationError

Field	Type	Description
code	string	Error code (e.g., UNKNOWN_VARIABLE, SYNTAX_ERROR)
message	string	Human-readable message
startOffset	number?	Start character offset in expression
endOffset	number?	End character offset in expression

FormulaItemDto

Field	Type	Description
formulaKey	string	Canonical key (e.g., da.mature.avoidableGradeY)
expression	string	Math expression (e.g., da.mature.merchantableVolume * 0.15)
declaredVariables	string[]	Variables referenced in expression
validationErrors	FormulaValidationError[]	Backend validation errors
sortOrder	number	Display/order priority (1-based)

FormulaSetResponse

Field	Type	Description
id	number	Unique identifier
area	'INTERIOR' | 'COASTAL'	Geographic area
startDate	string	ISO date string (YYYY-MM-DD)
endDate	string | null	ISO date string or null for open-ended
deleted	boolean	Soft-delete flag
formulas	FormulaItemDto[]	Ordered formula list
createdAt	string	ISO timestamp
updatedAt	string	ISO timestamp

FormulaSetListResponse

Field	Type	Description
content	FormulaSetResponse[]	Page of formula sets
page	object	{ number, size, totalElements, totalPages }

FormulaSetRequest

Field	Type	Description
area	'INTERIOR' | 'COASTAL'	Geographic area
startDate	string	ISO date string (YYYY-MM-DD)
endDate	string | null	ISO date string or null for open-ended
formulas	FormulaItemDto[]	Formula items

FormulaSetEffectiveParams

Field	Type	Description
date	string	YYYY-MM-DD
area	'INTERIOR' | 'COASTAL'	Geographic area

PageableRequest<T>

From @/services/types:

interface PageableRequest<T> {
  page: number;
  size: number;
  sort?: string[];
}

Registration

Registered in src/services/APIs.ts:

export const API = {
  // ...
  formulaConfiguration: new FormulaConfigurationService(apiConfig),
};

Dependencies

Inward (Imports)

Module	Purpose
@/services/utils	removeEmpty — strips undefined/null query params
@/services/formulaConfiguration.types	All DTO types
@/services/types	PageableRequest
@/config/api/CancelablePromise	Cancellable promise wrapper
@/config/api/types	HttpClient, APIConfig

Outward (Consumed By)

Consumer	Context
@/hooks/useFormulaConfiguration	All query/mutation hooks
FormulaConfigurationList	Via useFormulaSetList
FormulaConfigurationDetail	Via all hooks
Wiremock stubs	frontend/stub/mappings/formula-configuration.json

Known Constraints

• Complete-replace PUT — updateFormulaSet sends entire FormulaSetRequest; no PATCH support
• No client-side caching — relies on TanStack Query in hooks layer
• CancelablePromise — callers can cancel in-flight requests via .cancel()
• Error handling delegated — HTTP interceptors handle 401/403/500; 422/409/404 surfaced to callers
• Date format — startDate/endDate use ISO date strings (YYYY-MM-DD); createdAt/updatedAt use full ISO timestamps

Usage Example

// Direct service usage (rare — prefer hooks)
const service = API.formulaConfiguration;

// List with pagination
const list = await service.getFormulaSets({
  page: 0,
  size: 20,
  sort: ["startDate,DESC"],
});

// Date-effective lookup (used by calculation engine)
const effective = await service.getEffectiveFormulaSet({
  date: "2026-09-10",
  area: "INTERIOR",
});

// Create new set
const created = await service.createFormulaSet({
  area: "INTERIOR",
  startDate: "2026-09-10",
  endDate: null,
  formulas: [
    {
      formulaKey: "da.test",
      expression: "1 + 1",
      declaredVariables: [],
      validationErrors: [],
      sortOrder: 1,
    },
  ],
});

// Update (complete replace)
const updated = await service.updateFormulaSet(5, {
  ...dto,
  formulas: [...newFormulas],
});

// Soft-delete future open-ended
await service.deleteFormulaSet(5);

Wiremock Stubs

Defined in frontend/stub/mappings/formula-configuration.json:

Mapping	Method	Path	Response
List formula sets	GET	/api/configuration/formulas	configuration/formulas/list.json
Get effective	GET	/api/configuration/formulas/{date}/{area}	configuration/formulas/effective.json
Create	POST	/api/configuration/formulas	201 with created body
Update	PUT	/api/configuration/formulas/{id}	200 with updated body
Delete	DELETE	/api/configuration/formulas/{id}	204
Error: invalid params	GET	/api/configuration/formulas/.*	400 problem+json
Error: not found (effective)	GET	/api/configuration/formulas/2020-01-01/INTERIOR	404 problem+json
Error: invalid delete	DELETE	/api/configuration/formulas/1	422 problem+json
Error: validation failed	POST	/api/configuration/formulas (body contains INVALID_FORMULA)	422 with validationErrors
Error: conflict on update	PUT	/api/configuration/formulas/{id} (body contains CONFLICT)	409 problem+json

Related Pages

• FormulaConfigurationList — List page using useFormulaSetList
• FormulaConfigurationDetail — Detail page using all hooks
• useFormulaConfiguration — TanStack Query hooks
• FormulaConfigurationAPI — API page for endpoints
• FormulaEditorPattern — Pattern for FormulaInput integration