2026-04-06 02:32:47 +03:00

2.5 KiB

Raw Blame History

name	description
api-enums-reference	Use the central API enums file as the source of truth for enum values in this project. Use when: adding enum fields, updating enum options, creating form selects, typing status/discount/rate fields, syncing backend enum changes, or avoiding duplicated hardcoded enum literals.

API Enums Reference

Use this skill whenever work touches enum-like fields in API clients, schemas, forms, table filters, or page logic.

Source of Truth

All shared enum values and enum union types must come from:

packages/api/src/contracts/enums.ts

Do not recreate enum arrays inline when an equivalent enum already exists in this file.

Rules

Reuse before creating. Search and import from @garage/api exports (or local contracts path inside packages/api) before adding new literals.
Keep runtime and type together. For every enum, keep this pattern in enums.ts:

export const ExampleStatus = ['a', 'b'] as const;
export type ExampleStatus = (typeof ExampleStatus)[number];

Preserve backend values exactly. Enum string values are case- and space-sensitive; keep exact spelling from backend migrations/spec.
Avoid duplicate synonyms. If two domains share the same canonical values, prefer reusing an existing enum unless domain separation is intentional.
Update centrally first. When backend enum options change, update packages/api/src/contracts/enums.ts first, then update consuming UI/API code.
Prefer imports in forms and schemas. Use central enums for select options and for typed payload/status fields instead of hardcoded string unions.

Workflow

Identify the enum field and backend values.
Check packages/api/src/contracts/enums.ts for an existing enum.
If found, import and use it.
If missing, add a new const+type pair in enums.ts.
Update consumers to reference the central enum.
Verify there are no duplicated literal arrays for the same field.

Examples

import { InvoiceStatus, type InvoiceStatus as InvoiceStatusType } from '@garage/api'

const statusOptions = InvoiceStatus

type Payload = {
  status: InvoiceStatusType
}

import { DiscountType } from '@garage/api'

const discountOptions = DiscountType.map((value) => ({
  label: value,
  value,
}))

Notes

If a module needs a presentation-specific label, map from the central enum value instead of changing raw enum literals.
If backend adds/removes values, keep API and dashboard aligned in the same change set.

2.5 KiB Raw Blame History