# Reference Data Layer

## Table of Contents

- [Purpose](#purpose)
- [Responsibilities](#responsibilities)
- [Recommended Structure](#recommended-structure)
- [Rules](#rules)
- [Examples](#examples)

## Purpose

The `refdata/` layer contains app-wide reference datasets that are reused across modules.

Reference data is data that usually comes from the backend, but is not owned by one feature module.

Examples:

- countries
- languages
- currencies
- time zones
- common option dictionaries
- shared lookup datasets

## Responsibilities

The `refdata/` layer is responsible for:

- fetching common reference datasets
- exposing reusable query hooks for those datasets
- defining cache keys for reference data
- keeping app-wide lookup data out of feature modules

## Recommended Structure

For small datasets, a single file per dataset is enough:

```plaintext
refdata/
├── countries.ts
├── languages.ts
└── currencies.ts
```

For larger datasets, use a folder:

```plaintext
refdata/
└── countries/
    ├── api.ts
    ├── dto.ts
    ├── mapper.ts
    ├── queries.ts
    └── keys.ts
```

## Rules

1. Use `refdata/` only for app-wide datasets.

   If a dataset belongs to one feature module, keep it in that module's `data/` layer.

2. `refdata/` may use infrastructure.

   Reference data hooks can use `#infrastructure/axios` and `#infrastructure/reactQuery`.

3. `refdata/` should not import from `view/`, `pages/`, or feature modules.

   It should remain reusable across the app.

4. Expose hooks or small service functions.

   Consumers should not need to know backend endpoints or cache key details.

5. Add mappers when backend DTOs differ from app-facing reference data.

   If a reference dataset performs DTO transformation, test the mapper the same way module data mappers are tested.

## Examples

```ts
import { keepPreviousData, useQuery } from "@tanstack/react-query";
import { axiosClient } from "#infrastructure/axios";
import { createKeyBuilder } from "#infrastructure/reactQuery";

export const countriesCacheKey = createKeyBuilder(
  "REF_DATA",
  "COUNTRIES",
  "LIST",
);

interface CountryData {
  code: string;
  name: string;
}

export const useCountries = () => {
  return useQuery({
    queryKey: countriesCacheKey.store(),
    placeholderData: keepPreviousData,
    queryFn: async () => {
      return axiosClient
        .get<Array<CountryData>>("/datasets/countries")
        .then((data) => data.data);
    },
  });
};
```