@uniai-fe/uds-templates 0.5.29 → 0.6.1

package/src/weather/apis/client.ts

@@ -0,0 +1,459 @@
+"use client";
+
+import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { getQueryString } from "@uniai-fe/util-api";
+import { isValidNumber } from "@uniai-fe/util-functions";
+import type {
+  API_Req_Weather,
+  API_Req_WeatherAlert,
+  API_Res_WeatherAlert,
+  API_Res_WeatherForecast,
+  API_Res_WeatherNow,
+  API_Res_WeatherSummary,
+  WeatherClientQueryOptions,
+  WeatherClientRouteOptions,
+} from "../types";
+
+const WEATHER_CLIENT_ROUTE_PATH = {
+  now: "/api/weather/now",
+  forecast: "/api/weather/forecast",
+  summary: "/api/weather/summary",
+  alert: "/api/weather/alert",
+} as const;
+
+/**
+ * Weather Client; query string에 포함 가능한 값인지 확인.
+ * @param {unknown} value 확인할 query 값
+ * @return {boolean} query 포함 가능 여부
+ */
+const hasQueryValue = (value: unknown): boolean =>
+  value !== null && typeof value !== "undefined" && value !== "";
+
+/**
+ * Weather Client; backend weather route query로 전달할 값만 정리.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [params.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @return {API_Req_Weather} local route query 파라미터
+ */
+export const getWeatherClientParams = ({
+  farm_idx,
+  lat,
+  lng,
+  nx,
+  ny,
+  base_date,
+  base_time,
+  now_base_date,
+  now_base_time,
+  forecast_base_date,
+  forecast_base_time,
+  locale,
+  include_raw,
+}: API_Req_Weather): API_Req_Weather => ({
+  ...(hasQueryValue(farm_idx) ? { farm_idx } : {}),
+  ...(hasQueryValue(lat) ? { lat } : {}),
+  ...(hasQueryValue(lng) ? { lng } : {}),
+  ...(hasQueryValue(nx) ? { nx } : {}),
+  ...(hasQueryValue(ny) ? { ny } : {}),
+  ...(hasQueryValue(base_date) ? { base_date } : {}),
+  ...(hasQueryValue(base_time) ? { base_time } : {}),
+  ...(hasQueryValue(now_base_date) ? { now_base_date } : {}),
+  ...(hasQueryValue(now_base_time) ? { now_base_time } : {}),
+  ...(hasQueryValue(forecast_base_date) ? { forecast_base_date } : {}),
+  ...(hasQueryValue(forecast_base_time) ? { forecast_base_time } : {}),
+  ...(locale ? { locale } : {}),
+  ...(typeof include_raw === "boolean" ? { include_raw } : {}),
+});
+
+/**
+ * Weather Client; route override 또는 기본 local route 경로 선택.
+ * @param {string} [routePath] service app의 local weather route 경로
+ * @param {string} fallbackRoutePath 기본 local weather route 경로
+ * @return {string} fetch에 사용할 local route 경로
+ */
+const getWeatherRoutePath = (
+  routePath: string | undefined,
+  fallbackRoutePath: string,
+): string => routePath || fallbackRoutePath;
+
+/**
+ * Weather Client; 현재/예보 조회가 가능한 위치 입력인지 확인.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @return {boolean} 위치 기반 weather query 실행 가능 여부
+ */
+const isWeatherLocationAvailable = ({ lat, lng }: API_Req_Weather): boolean =>
+  lat !== null &&
+  lng !== null &&
+  typeof lat !== "undefined" &&
+  typeof lng !== "undefined" &&
+  isValidNumber(lat) &&
+  isValidNumber(lng);
+
+/**
+ * Weather Client; backend 격자 입력이 사용 가능한지 확인.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @return {boolean} 격자 기반 weather query 실행 가능 여부
+ */
+const isWeatherGridAvailable = ({ nx, ny }: API_Req_Weather): boolean =>
+  nx !== null &&
+  ny !== null &&
+  typeof nx !== "undefined" &&
+  typeof ny !== "undefined" &&
+  isValidNumber(nx) &&
+  isValidNumber(ny) &&
+  Number(nx) > 0 &&
+  Number(ny) > 0;
+
+/**
+ * Weather Client; 특보 조회가 가능한 농장 식별자인지 확인.
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @return {boolean} 특보 query 실행 가능 여부
+ */
+const isWeatherFarmAvailable = ({ farm_idx }: API_Req_WeatherAlert): boolean =>
+  hasQueryValue(farm_idx) && Number(farm_idx) > 0;
+
+/**
+ * Weather Client; summary 조회에 필요한 입력인지 확인.
+ * @param {API_Req_Weather} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @return {boolean} summary query 실행 가능 여부
+ */
+const isWeatherSummaryAvailable = (params: API_Req_Weather): boolean =>
+  isWeatherFarmAvailable({ farm_idx: params.farm_idx ?? null }) &&
+  (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params));
+
+/**
+ * Weather Client; React Query key에 사용할 weather 요청 값을 정렬.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [params.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @return {readonly unknown[]} React Query key 값
+ */
+const getWeatherQueryKeyValues = (params: API_Req_Weather) => {
+  const {
+    farm_idx,
+    lat,
+    lng,
+    nx,
+    ny,
+    base_date,
+    base_time,
+    now_base_date,
+    now_base_time,
+    forecast_base_date,
+    forecast_base_time,
+    locale,
+    include_raw,
+  } = getWeatherClientParams(params);
+
+  return [
+    farm_idx,
+    lat,
+    lng,
+    nx,
+    ny,
+    base_date,
+    base_time,
+    now_base_date,
+    now_base_time,
+    forecast_base_date,
+    forecast_base_time,
+    locale,
+    include_raw,
+  ] as const;
+};
+
+/**
+ * Weather Client; 현재 날씨 fetch.
+ * @method GET
+ * @param {API_Req_WeatherNow} params 현재 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재 날씨 재현용 날짜
+ * @param {string} [params.base_time] 현재 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 현재 날씨 응답
+ */
+export const getWeatherNow = async <Data = API_Res_WeatherNow>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.now,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 예보 날씨 fetch.
+ * @method GET
+ * @param {API_Req_WeatherForecast} params 예보 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 예보 날씨 재현용 날짜
+ * @param {string} [params.base_time] 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 예보 날씨 응답
+ */
+export const getWeatherForecast = async <Data = API_Res_WeatherForecast>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.forecast,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; summary fetch.
+ * @method GET
+ * @param {API_Req_WeatherSummary} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} summary 응답
+ */
+export const getWeatherSummary = async <Data = API_Res_WeatherSummary>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.summary,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 특보 fetch.
+ * @method GET
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 특보 응답
+ */
+export const getWeatherAlert = async <Data = API_Res_WeatherAlert>(
+  params: API_Req_WeatherAlert,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.alert,
+      )}${getQueryString(params)}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 현재 날씨 react query.
+ * @method GET
+ * @param {API_Req_WeatherNow} params 현재 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 현재 날씨 재현용 날짜
+ * @param {string} [params.base_time] 현재 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 현재 날씨 query 결과
+ */
+export const useQueryWeatherNow = <Data = API_Res_WeatherNow>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.now,
+  );
+
+  return useQuery({
+    queryKey: ["weather_now", routePath, ...getWeatherQueryKeyValues(params)],
+    queryFn: () => getWeatherNow<Data>(params, { routePath }),
+    enabled:
+      (options.enabled ?? true) &&
+      (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params)),
+    staleTime: 10 * 60 * 1000,
+    refetchInterval: 5 * 60 * 1000,
+    refetchOnWindowFocus: true,
+  });
+};
+
+/**
+ * Weather Client; 예보 날씨 react query.
+ * @method GET
+ * @param {API_Req_WeatherForecast} params 예보 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.base_date] 예보 날씨 재현용 날짜
+ * @param {string} [params.base_time] 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 예보 날씨 query 결과
+ */
+export const useQueryWeatherForecast = <Data = API_Res_WeatherForecast>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.forecast,
+  );
+
+  return useQuery({
+    queryKey: [
+      "weather_forecast",
+      routePath,
+      ...getWeatherQueryKeyValues(params),
+    ],
+    queryFn: () => getWeatherForecast<Data>(params, { routePath }),
+    enabled:
+      (options.enabled ?? true) &&
+      (isWeatherLocationAvailable(params) || isWeatherGridAvailable(params)),
+    staleTime: 30 * 60 * 1000,
+  });
+};
+
+/**
+ * Weather Client; summary react query.
+ * @method GET
+ * @param {API_Req_WeatherSummary} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {number|null} [params.nx] backend 격자 X
+ * @param {number|null} [params.ny] backend 격자 Y
+ * @param {string} [params.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [params.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [params.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [params.forecast_base_time] summary 예보 날씨 재현용 시각
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} summary query 결과
+ */
+export const useQueryWeatherSummary = <Data = API_Res_WeatherSummary>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.summary,
+  );
+
+  return useQuery({
+    queryKey: [
+      "weather_summary",
+      routePath,
+      ...getWeatherQueryKeyValues(params),
+    ],
+    queryFn: () => getWeatherSummary<Data>(params, { routePath }),
+    enabled: (options.enabled ?? true) && isWeatherSummaryAvailable(params),
+    staleTime: 10 * 60 * 1000,
+  });
+};
+
+/**
+ * Weather Client; 특보 react query.
+ * @method GET
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 특보 query 결과
+ */
+export const useQueryWeatherAlert = <Data = API_Res_WeatherAlert>(
+  params: API_Req_WeatherAlert,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const farmIdx = params.farm_idx;
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.alert,
+  );
+
+  return useQuery({
+    queryKey: ["weather_alert", routePath, farmIdx],
+    queryFn: () => getWeatherAlert<Data>({ farm_idx: farmIdx }, { routePath }),
+    enabled:
+      (options.enabled ?? true) &&
+      isWeatherFarmAvailable({ farm_idx: farmIdx }),
+    staleTime: 60 * 60 * 1000,
+  });
+};

package/src/weather/apis/index.ts

@@ -1,4 +1,2 @@
-export * from "./korea/client";
-export * from "./korea/server";
-export * from "./open-weather-map/client";
-export * from "./open-weather-map/server";
+export * from "./client";
+export * from "./server";