typedapi-client-helpers 0.1.1

package/bin/typedapi-generate.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../scripts/generate-api-minimal.mjs";

package/dist/index.cjs

@@ -0,0 +1,339 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TypedApiToastProvider: () => TypedApiToastProvider,
+  buildQuery: () => buildQuery,
+  extractArgsToastsAndParams: () => extractArgsToastsAndParams,
+  getSortDirectionFromSortType: () => getSortDirectionFromSortType,
+  getSortTypeFromSortDirection: () => getSortTypeFromSortDirection,
+  handleApiResponse: () => handleApiResponse,
+  resetUnauthorizedHandling: () => resetUnauthorizedHandling,
+  sortTypes: () => sortTypes,
+  toFormData: () => toFormData,
+  toast: () => toast
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/toast/toast.tsx
+var import_react_toastify = require("react-toastify");
+var import_jsx_runtime = require("react/jsx-runtime");
+function ToastContent({ title, message }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { children: title }),
+    message && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { children: message })
+  ] });
+}
+var toast = {
+  success(message, title = "Success!") {
+    import_react_toastify.toast.success(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContent, { title, message }));
+  },
+  error(message, title = "Error!") {
+    import_react_toastify.toast.error(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContent, { title, message }));
+  },
+  warning(message, title = "Warning!") {
+    import_react_toastify.toast.warning(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContent, { title, message }));
+  },
+  info(message, title = "Info") {
+    import_react_toastify.toast.info(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContent, { title, message }));
+  },
+  async errorResponse(error) {
+    let message = "Something went wrong.";
+    try {
+      if (error instanceof Response) {
+        const text = await error.text();
+        message = text || message;
+      } else if (error instanceof Error) {
+        message = error.message;
+      } else if (typeof error === "string") {
+        message = error;
+      } else if (error && typeof error === "object") {
+        message = JSON.stringify(error);
+      }
+    } catch {
+    }
+    import_react_toastify.toast.error(/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ToastContent, { title: "Error!", message }));
+  }
+};
+
+// src/toast/ToastProvider.tsx
+var import_react_toastify2 = require("react-toastify");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function TypedApiToastProvider() {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react_toastify2.ToastContainer, { position: "bottom-right" });
+}
+
+// src/utils/buildQuery.ts
+function buildQuery(filters, page = 1, pageSize = 100, sortBy = null, sortDirection) {
+  let isPageSizeSet = pageSize > 0;
+  const query = filters.reduce((queryResult, filter) => {
+    const { filterName, filterNameMax, type, value, maxValue, isAList } = filter;
+    if ((value === null || value === void 0 || value === "") && (maxValue === null || maxValue === void 0 || maxValue === "")) {
+      return queryResult;
+    }
+    if (isAList && Array.isArray(value)) {
+      if (isOptionValueArray(value)) {
+        queryResult[filterName] = value.map(
+          (item) => convertType(type, item.value)
+        );
+        return queryResult;
+      }
+      queryResult[filterName] = value.map(
+        (item) => convertType(type, item)
+      );
+      return queryResult;
+    }
+    if (value !== "null" && value !== "undefined" && value !== null && value !== void 0 && value !== "") {
+      const convertedValue = convertType(type, value);
+      if (convertedValue !== null) {
+        queryResult[filterName] = convertedValue;
+      }
+    }
+    if (filterNameMax && maxValue !== null && maxValue !== void 0 && maxValue !== "") {
+      const convertedMaxValue = convertType(type, maxValue);
+      if (convertedMaxValue !== null) {
+        queryResult[filterNameMax] = convertedMaxValue;
+      }
+    }
+    if (String(filterName) === "pageSize" && !isPageSizeSet) {
+      isPageSizeSet = true;
+    }
+    return queryResult;
+  }, {});
+  query.pageNumber = page;
+  if (isPageSizeSet) {
+    query.pageSize = pageSize;
+  }
+  if (sortBy) {
+    query.sortBy = sortBy;
+  }
+  if (sortDirection !== void 0 && sortDirection !== "Default") {
+    query.sortDirection = sortDirection;
+  }
+  return query;
+}
+function isOptionValue(value) {
+  return typeof value === "object" && value !== null && "value" in value;
+}
+function isOptionValueArray(value) {
+  return value.every(isOptionValue);
+}
+function convertType(type, value) {
+  switch (type) {
+    case "date":
+      return value instanceof Date ? value.toISOString() : value;
+    case "number":
+      return Number(value);
+    case "boolean":
+      return Boolean(value);
+    default:
+      return value;
+  }
+}
+
+// src/utils/extractArgsToastsAndParams.ts
+function isToastOptions(value) {
+  return typeof value === "object" && value !== null && ("toastSuccess" in value || "toastError" in value);
+}
+function isRequestParams(value) {
+  return typeof value === "object" && value !== null && !isToastOptions(value);
+}
+function extractArgsToastsAndParams(argsWithToast) {
+  const args = [...argsWithToast];
+  let toastOptions;
+  let params;
+  const lastArg = args[args.length - 1];
+  if (isRequestParams(lastArg)) {
+    params = lastArg;
+    args.pop();
+  }
+  const newLastArg = args[args.length - 1];
+  if (isToastOptions(newLastArg)) {
+    toastOptions = newLastArg;
+    args.pop();
+  }
+  return {
+    args,
+    toastOptions,
+    params
+  };
+}
+
+// src/utils/handleApiResponse.ts
+var isHandlingUnauthorized = false;
+function handleUnauthorized() {
+  if (isHandlingUnauthorized) {
+    return {
+      ok: false,
+      status: 401,
+      response: void 0,
+      error: new Error("Unauthorized")
+    };
+  }
+  isHandlingUnauthorized = true;
+  localStorage.removeItem("loggedInUser");
+  sessionStorage.clear();
+  toast.error("Your session has expired. Please log in again.", "Session Expired");
+  if (window.location.pathname !== "/login") {
+    window.dispatchEvent(new Event("unauthorized"));
+  }
+  return {
+    ok: false,
+    status: 401,
+    response: void 0,
+    error: new Error("Unauthorized")
+  };
+}
+function resetUnauthorizedHandling() {
+  isHandlingUnauthorized = false;
+}
+async function handleApiResponse(call, toastOptions) {
+  let response;
+  try {
+    response = await call();
+    if (response.status === 401) {
+      return handleUnauthorized();
+    }
+    let data;
+    try {
+      const textData = await response.text();
+      data = textData ? JSON.parse(textData) : void 0;
+    } catch {
+      data = void 0;
+    }
+    if (response.ok) {
+      if (toastOptions?.toastSuccess) {
+        toast.success(
+          toastOptions.toastSuccess.message,
+          toastOptions.toastSuccess.title
+        );
+      }
+      return {
+        ok: true,
+        status: response.status,
+        response: data
+      };
+    }
+    if (toastOptions?.toastError) {
+      toast.error(
+        toastOptions.toastError.message,
+        toastOptions.toastError.title
+      );
+    } else {
+      await toast.errorResponse(response);
+    }
+    return {
+      ok: false,
+      status: response.status,
+      response: data,
+      error: null
+    };
+  } catch (error) {
+    const status = error instanceof Response ? error.status : response?.status ?? 0;
+    if (status === 401) {
+      return handleUnauthorized();
+    }
+    await toast.errorResponse(error);
+    return {
+      ok: false,
+      status,
+      response: void 0,
+      error
+    };
+  }
+}
+
+// src/utils/SortTypeFromSortDirection.ts
+var sortTypes = [
+  "Default",
+  "Neutral",
+  "Ascending",
+  "Descending"
+];
+function getSortTypeFromSortDirection(sortDirection) {
+  switch (sortDirection) {
+    case "Ascending":
+      return "Ascending";
+    case "Descending":
+      return "Descending";
+    case "Default":
+    default:
+      return "Default";
+  }
+}
+function getSortDirectionFromSortType(sortType) {
+  switch (sortType) {
+    case "Ascending":
+      return "Ascending";
+    case "Descending":
+      return "Descending";
+    case "Neutral":
+    case "Default":
+    default:
+      return "Default";
+  }
+}
+
+// src/utils/toFormData.ts
+function toFormData(payload) {
+  const formData = new FormData();
+  for (const [key, value] of Object.entries(payload)) {
+    appendFormDataValue(formData, key, value);
+  }
+  return formData;
+}
+function appendFormDataValue(formData, key, value) {
+  if (value === null || value === void 0) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      appendFormDataValue(formData, key, item);
+    }
+    return;
+  }
+  if (value instanceof File) {
+    formData.append(key, value, value.name);
+    return;
+  }
+  if (value instanceof Blob) {
+    formData.append(key, value);
+    return;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    formData.append(key, String(value));
+    return;
+  }
+  formData.append(key, JSON.stringify(value));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TypedApiToastProvider,
+  buildQuery,
+  extractArgsToastsAndParams,
+  getSortDirectionFromSortType,
+  getSortTypeFromSortDirection,
+  handleApiResponse,
+  resetUnauthorizedHandling,
+  sortTypes,
+  toFormData,
+  toast
+});

package/dist/index.d.cts

@@ -0,0 +1,225 @@
+import * as react from 'react';
+
+type QueryParamsType = Record<string | number, any>;
+type ResponseFormat = keyof Omit<Body, "body" | "bodyUsed">;
+interface FullRequestParams extends Omit<RequestInit, "body"> {
+    /** set parameter to `true` for call `securityWorker` for this request */
+    secure?: boolean;
+    /** request path */
+    path: string;
+    /** content type of request body */
+    type?: ContentType;
+    /** query params */
+    query?: QueryParamsType;
+    /** format of response (i.e. response.json() -> format: "json") */
+    format?: ResponseFormat;
+    /** request body */
+    body?: unknown;
+    /** base url */
+    baseUrl?: string;
+    /** request cancellation token */
+    cancelToken?: CancelToken;
+}
+type RequestParams = Omit<FullRequestParams, "body" | "method" | "query" | "path">;
+interface HttpResponse$1<D extends unknown, E extends unknown = unknown> extends Response {
+    data: D;
+    error: E;
+}
+type CancelToken = Symbol | string | number;
+declare enum ContentType {
+    Json = "application/json",
+    JsonApi = "application/vnd.api+json",
+    FormData = "multipart/form-data",
+    UrlEncoded = "application/x-www-form-urlencoded",
+    Text = "text/plain"
+}
+
+type ExtractResponse<T> = T extends Promise<HttpResponse$1<infer R, any>> ? R : never;
+type UnwrapArray<T> = T extends (infer U)[] ? U : T;
+type ExtractDataIfPaginated<T> = T extends {
+    data?: (infer U)[] | null;
+} ? U : T;
+type SortableKeys<T> = keyof UnwrapArray<ExtractDataIfPaginated<T>>;
+type WithoutRequestParams<T extends any[]> = T extends [
+    infer First,
+    ...infer Rest
+] ? First extends RequestParams ? Rest : [First, ...WithoutRequestParams<Rest>] : [];
+
+/**
+ * Standard result wrapper for API calls.
+ *
+ * When `ok` is true, the request succeeded and `response` contains the expected data.
+ * When `ok` is false, the request failed and `error` contains the thrown or returned error value.
+ */
+type ApiResult<T> = {
+    ok: true;
+    status: number;
+    response: T;
+} | {
+    ok: false;
+    status: number;
+    response?: T;
+    error: unknown;
+};
+
+/**
+ * Supported filter input types used by typed filter forms.
+ *
+ * These values decide which UI input should be rendered for a filter.
+ */
+type FilterType = "number" | "date" | "string" | "timespan" | "boolean" | "boolean-button" | "OptionValue";
+/**
+ * Selectable option value used by option-based filters.
+ *
+ * `name` is shown in the UI and `value` is sent as the actual filter value.
+ */
+interface OptionValue {
+    name: string;
+    value: number | string | Date;
+}
+/**
+ * Configuration for one filter field in a typed filter form.
+ *
+ * `filterName` maps the form value to a query property.
+ * `filterNameMax` can be used for range filters such as dates or numbers.
+ */
+interface FilterFormValues<TQuery> {
+    name: string;
+    filterName: keyof TQuery;
+    filterNameMax?: keyof TQuery;
+    type: FilterType;
+    value: number | string | Date | boolean | null | OptionValue[] | string[];
+    maxValue?: number | string | Date | null;
+    isAList: boolean;
+}
+
+/**
+ * Sort state used by UI components.
+ *
+ * `Neutral` represents a UI-only state and is sent to the API as `Default`.
+ */
+type SortType = "Default" | "Neutral" | "Ascending" | "Descending";
+
+/**
+ * Toast helper for showing consistent success, error, warning, and info messages.
+ *
+ * Wraps `react-toastify` with a shared title/message layout.
+ */
+declare const toast: {
+    success(message: string, title?: string): void;
+    error(message: string, title?: string): void;
+    warning(message: string, title?: string): void;
+    info(message: string, title?: string): void;
+    errorResponse(error: Response | unknown): Promise<void>;
+};
+
+/**
+ * Shared toast container for TypedApi UI notifications.
+ *
+ * Add this once near the root of the app to enable toast messages.
+ */
+declare function TypedApiToastProvider(): react.JSX.Element;
+
+/**
+ * Extended fetch response returned by the generated HTTP client.
+ *
+ * `data` contains the successful response body and `error` contains the error body when available.
+ */
+interface HttpResponse<D extends unknown, E extends unknown = unknown> extends Response {
+    data: D;
+    error: E;
+}
+/**
+ * Runtime request options that can be passed to generated API methods.
+ *
+ * Used for extra request configuration such as headers, query values, or fetch options.
+ */
+type RuntimeRequestParams = Record<string, unknown>;
+
+/**
+ * Toast message shown after an API action.
+ *
+ * `title` is optional and `message` contains the main notification text.
+ */
+type ToastMessage = {
+    title?: string;
+    message: string;
+};
+/**
+ * Optional toast messages for API success and error states.
+ *
+ * Use this to show consistent notifications after typed API requests.
+ */
+type ToastOptions = {
+    toastSuccess?: ToastMessage;
+    toastError?: ToastMessage;
+};
+
+type SortDirection = number | string;
+/**
+ * Builds a typed query object from filter form values, pagination, and sorting.
+ *
+ * Empty filter values are ignored.
+ * List filters are converted item by item.
+ * `OptionValue` lists send their `value` fields instead of the display names.
+ */
+declare function buildQuery<TQuery, TSortModel = keyof TQuery>(filters: FilterFormValues<TQuery>[], page?: number, pageSize?: number, sortBy?: keyof TSortModel | null, sortDirection?: SortDirection): Partial<TQuery>;
+
+/**
+ * Splits API wrapper arguments into actual API arguments, optional toast options,
+ * and optional runtime request params.
+ *
+ * This allows generated wrapper methods to accept toast and request options
+ * without changing the original API method arguments.
+ */
+declare function extractArgsToastsAndParams<TArgs extends unknown[]>(argsWithToast: [...TArgs, ToastOptions?, RuntimeRequestParams?]): {
+    args: TArgs;
+    toastOptions?: ToastOptions;
+    params?: RuntimeRequestParams;
+};
+
+/**
+ * Resets the unauthorized handling lock.
+ *
+ * This allows future `401 Unauthorized` responses to trigger the shared handling again.
+ */
+declare function resetUnauthorizedHandling(): void;
+/**
+ * Executes an API call and converts the response into an `ApiResult`.
+ *
+ * Successful responses return `{ ok: true }`.
+ * Failed responses return `{ ok: false }` and show either a custom error toast
+ * or the response error message.
+ */
+declare function handleApiResponse<T>(call: () => Promise<HttpResponse<T, unknown>>, toastOptions?: ToastOptions): Promise<ApiResult<T>>;
+
+/** Values supported by the generated API SortDirection enum. */
+type ApiSortDirection = "Default" | "Ascending" | "Descending";
+/**
+ * Sort states supported by TypedApi UI components.
+ *
+ * Includes `Neutral`, which is a UI-only state and is sent to the API as `Default`.
+ */
+declare const sortTypes: readonly ["Default", "Neutral", "Ascending", "Descending"];
+/**
+ * Converts an API sort direction to the sort state used by UI components.
+ *
+ * Unknown or missing values safely fall back to `Default`.
+ */
+declare function getSortTypeFromSortDirection(sortDirection: ApiSortDirection | null | undefined): SortType;
+/**
+ * Converts a UI sort state to a value accepted by the generated API.
+ *
+ * `Neutral` means no explicit sorting is active, so it maps to `Default`.
+ */
+declare function getSortDirectionFromSortType(sortType: SortType | null | undefined): ApiSortDirection;
+
+/**
+ * Converts an object payload into `FormData`.
+ *
+ * Supports single files, file arrays, primitive values, and nested objects.
+ * Arrays are appended as repeated fields with the same key.
+ */
+declare function toFormData<T extends object>(payload: T): FormData;
+
+export { type ApiResult, type ApiSortDirection, type ExtractDataIfPaginated, type ExtractResponse, type FilterFormValues, type FilterType, type HttpResponse, type OptionValue, type RuntimeRequestParams, type SortDirection, type SortType, type SortableKeys, type ToastMessage, type ToastOptions, TypedApiToastProvider, type UnwrapArray, type WithoutRequestParams, buildQuery, extractArgsToastsAndParams, getSortDirectionFromSortType, getSortTypeFromSortDirection, handleApiResponse, resetUnauthorizedHandling, sortTypes, toFormData, toast };