@dsanchos/api 1.0.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dsanchos/api",
+  "version": "1.0.0",
+  "description": "",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "prepublish": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "eslint": "^10.0.0",
+    "prettier": "^3.8.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  }
+}

package/readme.md

@@ -0,0 +1,211 @@
+# api
+
+A lightweight TypeScript fetch wrapper with caching, polling, interceptors, and logging.
+
+Лёгкая TypeScript обёртка над fetch с кэшированием, поллингом, интерсепторами и логированием.
+
+---
+
+## Installation / Установка
+
+```bash
+npm install node-fetch
+```
+
+---
+
+## Quick Start / Быстрый старт
+
+```typescript
+import { ApiCore, defineApi } from "./core.js";
+import { api } from "./api.js";
+
+// Configure once / Настройте один раз
+ApiCore({
+  baseUrl: "https://jsonplaceholder.typicode.com",
+  baseKeepUnusedDataFor: 60,
+  baseHeader: { "Content-Type": "application/json" },
+});
+
+// Make a request / Сделайте запрос
+const { data, isLoading, isError, error } = await api({
+  method: "GET",
+  url: "/posts",
+});
+```
+
+---
+
+## ApiCore
+
+Global configuration for all requests.
+
+Глобальная конфигурация для всех запросов.
+
+```typescript
+ApiCore({
+  baseUrl: "https://api.example.com", // Base URL for all requests
+  baseKeepUnusedDataFor: 60, // Cache TTL in seconds (default: 60)
+  baseHeader: {
+    // Default headers for all requests
+    "Content-Type": "application/json",
+  },
+  logging: true, // Enable request logging
+  interceptors: {
+    request: (props) => ({
+      // Modify request before sending
+      ...props,
+      headers: { Authorization: `Bearer ${getToken()}` },
+    }),
+  },
+});
+```
+
+---
+
+## api()
+
+```typescript
+const { data, isLoading, isFetching, isError, error } = await api({
+  method: "GET", // GET | POST | PUT | PATCH | DELETE
+  url: "/posts", // Path (baseUrl is prepended automatically)
+  headers: {}, // Override default headers
+  body: {}, // Request body (auto JSON.stringify)
+
+  // Cache
+  provideCache: "posts", // Save response under this key
+  keepUnusedDataFor: 30, // Override TTL for this request (seconds)
+  invalidateCache: "posts", // Delete this cache key after request
+});
+```
+
+### Response / Ответ
+
+| Field        | Type             | Description            |
+| ------------ | ---------------- | ---------------------- |
+| `data`       | `any`            | Response data          |
+| `isLoading`  | `boolean`        | True on first load     |
+| `isFetching` | `boolean`        | True on any request    |
+| `isError`    | `boolean`        | True if request failed |
+| `error`      | `string \| null` | Error message          |
+
+---
+
+## Caching / Кэширование
+
+```typescript
+// Save to cache / Сохранить в кэш
+await api({
+  method: "GET",
+  url: "/posts",
+  provideCache: "posts", // Cache key
+  keepUnusedDataFor: 120, // 2 minutes
+});
+
+// Invalidate cache after mutation / Инвалидировать после мутации
+await api({
+  method: "POST",
+  url: "/posts",
+  body: { title: "New post" },
+  invalidateCache: "posts", // Delete "posts" cache
+});
+```
+
+---
+
+## Polling
+
+```typescript
+import { polling } from "./polling.js";
+
+const stop = polling(
+  {
+    method: "GET",
+    url: "/notifications",
+    pollingInterval: 3000, // Every 3 seconds / Каждые 3 секунды
+    stopAfter: 30000, // Stop after 30 seconds / Остановить через 30 секунд
+  },
+  (res, stop) => {
+    console.log(res.data);
+    if (res.isError) stop(); // Stop on error / Остановить при ошибке
+  },
+);
+
+// Stop manually / Остановить вручную
+stop();
+```
+
+---
+
+## defineApi
+
+Group related endpoints without writing types manually.
+
+Группируйте связанные запросы без ручного написания типов.
+
+```typescript
+const usersApi = defineApi({
+  getUsers: { method: "GET", url: "/users" },
+  createUser: { method: "POST", url: "/users" },
+  updateUser: { method: "PUT", url: "/users/1" },
+  deleteUser: { method: "DELETE", url: "/users/1" },
+});
+
+const { data } = await api(usersApi.getUsers);
+```
+
+---
+
+## Logging / Логирование
+
+When `logging: true` is set in `ApiCore`, every request is logged:
+
+При `logging: true` в `ApiCore` каждый запрос логируется:
+
+```
+✅ [GET]    /posts    → 200 (123ms)
+✅ [POST]   /posts    → 201 (89ms)
+❌ [GET]    /posts/99 → 404 (45ms)
+```
+
+---
+
+## Interceptors
+
+Modify every request automatically (e.g. add auth token).
+
+Изменяйте каждый запрос автоматически (например, добавить токен).
+
+```typescript
+ApiCore({
+  baseUrl: "https://api.example.com",
+  interceptors: {
+    request: (props) => ({
+      ...props,
+      headers: {
+        ...props.headers,
+        Authorization: `Bearer ${localStorage.getItem("token")}`,
+      },
+    }),
+  },
+});
+```
+
+---
+
+## Project Structure / Структура проекта
+
+```
+source/
+├── api.ts          # Main fetch wrapper
+├── core.ts         # ApiCore config + defineApi
+├── polling.ts      # Polling utility
+├── logger.ts       # Request logger
+└── api.types.ts    # TypeScript types
+```
+
+---
+
+## License / Лицензия
+
+MIT

package/source/api.ts

@@ -0,0 +1,101 @@
+import fetch from "node-fetch";
+import type { API, APIResponse, CacheEntry } from "./api.types.js";
+import { getConfig } from "./core.js";
+import { Logger } from "./logger.js";
+
+const cache = new Map<string, CacheEntry>();
+
+export async function api(props: API): Promise<APIResponse> {
+  const {
+    baseUrl,
+    baseKeepUnusedDataFor = 60,
+    baseHeader,
+    interceptors,
+    logger,
+  } = getConfig();
+
+  const finalProps = interceptors?.request
+    ? await Promise.resolve(interceptors.request(props))
+    : props;
+
+  const {
+    method,
+    url,
+    headers,
+    body,
+    keepUnusedDataFor = baseKeepUnusedDataFor,
+    provideCache = "",
+    invalidateCache = "",
+  } = finalProps;
+
+  let data = null;
+  let isLoading = true;
+  let isFetching = true;
+  let isError = false;
+  let error = null;
+
+  const TTL = keepUnusedDataFor * 1000;
+  const now = Date.now();
+
+  if (provideCache) {
+    const cached = cache.get(provideCache);
+
+    if (cached && now - cached.timestamp < TTL) {
+      return {
+        data: cached.data,
+        isLoading: false,
+        isFetching: false,
+        isError: false,
+        error: null,
+      };
+    }
+  }
+
+  try {
+    isFetching = true;
+    if (!data) isLoading = true;
+
+    const start = performance.now();
+    const response = await fetch(`${baseUrl}${url}`, {
+      method,
+      headers: headers ?? baseHeader,
+      body: body ? JSON.stringify(body) : null,
+    });
+    const ms = Math.round(performance.now() - start);
+
+    if (logger) {
+      Logger(method, url, response.status, ms);
+    }
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    data = await response.json();
+
+    isLoading = false;
+
+    if (invalidateCache) {
+      for (const key of invalidateCache) {
+        cache.delete(key);
+      }
+    } else {
+      if (provideCache) {
+        cache.set(provideCache, { data, timestamp: now });
+      }
+    }
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+    isError = true;
+  } finally {
+    isFetching = false;
+  }
+
+  return {
+    data,
+    isLoading,
+    isFetching,
+    isError,
+    error,
+  };
+}

package/source/api.types.ts

@@ -0,0 +1,60 @@
+export type METHODS = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export type CacheEntry = {
+  data: any;
+  timestamp: number;
+};
+
+export type headersMap = {
+  "Content-Type":
+    | "application/json"
+    | "application/x-www-form-urlencoded"
+    | "multipart/form-data"
+    | "text/html"
+    | "text/plain";
+
+  Accept: "application/json" | "text/html" | "*/*";
+
+  Authorization: `Bearer ${string}` | `Basic ${string}` | `ApiKey ${string}`;
+
+  "Cache-Control": "no-cache" | "no-store" | "max-age=3600";
+
+  "Accept-Encoding": "gzip" | "deflate" | "gzip, deflate";
+};
+
+export type Headers = {
+  [K in keyof headersMap]?: headersMap[K];
+};
+
+export interface API {
+  method: METHODS;
+  url: string;
+  headers?: Headers;
+  body?: any;
+  keepUnusedDataFor?: number;
+  pollingInterval?: number;
+  stopAfter?: number;
+  provideCache?: string;
+  invalidateCache?: string[];
+}
+
+export interface APIResponse {
+  data: any;
+  isLoading: boolean;
+  isFetching: boolean;
+  isError: boolean;
+  error: string | null;
+}
+
+export type OnData = (res: any, stop: () => void) => void;
+
+export interface CORE {
+  baseUrl: string;
+  baseKeepUnusedDataFor: number;
+  baseHeader: Headers;
+  interceptors?: {
+    request?: (props: API) => API | Promise<API>;
+    response?: (res: APIResponse) => APIResponse | Promise<APIResponse>;
+  };
+  logger?: boolean;
+}

package/source/core.ts

@@ -0,0 +1,37 @@
+import type { API, CORE } from "./api.types.js";
+
+const config: CORE = {
+  baseUrl: "",
+  baseKeepUnusedDataFor: 60,
+  baseHeader: {},
+  interceptors: {},
+  logger: true,
+};
+
+export function ApiCore(props: CORE) {
+  config.baseUrl = props.baseUrl;
+  config.baseKeepUnusedDataFor = props.baseKeepUnusedDataFor;
+
+  config.baseHeader = props.baseHeader;
+
+  if (props.logger) {
+    config.logger = props.logger;
+  }
+
+  if (props.interceptors) {
+    config.interceptors = props.interceptors;
+  }
+}
+
+export function getConfig() {
+  return config;
+}
+
+export function defineApi<T extends Record<string, API>>(props: T) {
+  return props;
+}
+
+// Планы на будущее!
+// retry.ts        — повтор запроса при ошибке (retryCount, retryDelay)
+// queue.ts        — очередь запросов (не слать 100 запросов одновременно)
+// abort.ts        — отмена запроса через AbortController

package/source/index.ts

@@ -0,0 +1,3 @@
+export { api } from "./api.js";
+export { ApiCore, defineApi } from "./core.js";
+export { polling } from "./polling.js";

package/source/logger.ts

@@ -0,0 +1,9 @@
+export function Logger(
+  method: string,
+  url: string,
+  status: number,
+  ms: number,
+) {
+  const isSuccess = status >= 400 ? "❌" : "✅";
+  console.log(`${isSuccess} [${method}] ${url} -> ${status} (${ms}ms)`);
+}

package/source/polling.ts

@@ -0,0 +1,22 @@
+import { api } from "./api.js";
+import type { API, OnData } from "./api.types.js";
+
+export function polling(props: API, onData: OnData): void {
+  const { pollingInterval = 3000, stopAfter } = props;
+  let isActive = true;
+
+  const stop = () => {
+    isActive = false;
+  };
+
+  async function poll() {
+    if (!isActive) return;
+    const res = await api(props);
+    onData(res, stop);
+    if (isActive) setTimeout(poll, pollingInterval);
+  }
+
+  poll();
+
+  if (stopAfter) setTimeout(stop, stopAfter);
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "rootDir": "./source",
+    "outDir": "./dist",
+
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "esnext",
+    "types": ["node"],
+
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+    // "noEmit": true,
+    // "allowImportingTsExtensions":
+
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true
+  }
+}