accessio 1.0.0

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "accessio",
+  "version": "1.0.0",
+  "description": "Fast, flexible HTTP client for Node.js and browsers — simple, modular, and dependency-free",
+  "type": "module",
+  "main": "./cjs/index.cjs",
+  "module": "./src/index.ts",
+  "types": "./index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.ts",
+      "require": "./cjs/index.cjs"
+    },
+    "./helpers/rateLimiter": {
+      "types": "./index.d.ts",
+      "import": "./src/helpers/rateLimiter.ts",
+      "require": "./cjs/helpers/rateLimiter.cjs"
+    },
+    "./helpers/debug": {
+      "types": "./index.d.ts",
+      "import": "./src/helpers/debug.ts",
+      "require": "./cjs/helpers/debug.cjs"
+    },
+    "./core/buildURL": {
+      "types": "./index.d.ts",
+      "import": "./src/core/buildURL.ts",
+      "require": "./cjs/helpers/buildURL.cjs"
+    },
+    "./core/mergeConfig": {
+      "types": "./index.d.ts",
+      "import": "./src/core/mergeConfig.ts",
+      "require": "./cjs/core/mergeConfig.cjs"
+    },
+    "./core/request": {
+      "types": "./index.d.ts",
+      "import": "./src/core/request.ts",
+      "require": "./cjs/core/request.cjs"
+    },
+    "./core/retry": {
+      "types": "./index.d.ts",
+      "import": "./src/core/retry.ts",
+      "require": "./cjs/core/retry.cjs"
+    },
+    "./helpers/parseHeaders": {
+      "types": "./index.d.ts",
+      "import": "./src/helpers/parseHeaders.ts",
+      "require": "./cjs/helpers/parseHeaders.cjs"
+    },
+    "./helpers/settle": {
+      "types": "./index.d.ts",
+      "import": "./src/helpers/settle.ts",
+      "require": "./cjs/helpers/settle.cjs"
+    },
+    "./helpers/transformData": {
+      "types": "./index.d.ts",
+      "import": "./src/helpers/transformData.ts",
+      "require": "./cjs/helpers/transformData.cjs"
+    }
+  },
+  "files": [
+    "src/",
+    "cjs/",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:cjs": "tsup",
+    "build": "npm run build:cjs",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:browser": "vitest run --config vitest.browser.config.js",
+    "release:npm": "gh workflow run publish-npm.yml -f publish_tag=$(git describe --tags --abbrev=0)",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "http",
+    "client",
+    "ajax",
+    "fetch",
+    "promise",
+    "request",
+    "accessio"
+  ],
+  "author": "salvatorecorvaglia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/salvatorecorvaglia/accessio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/salvatorecorvaglia/accessio/issues"
+  },
+  "homepage": "https://github.com/salvatorecorvaglia/accessio#readme",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.1.0",
+    "eslint": "^9.0.0",
+    "jsdom": "^29.0.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.1.0"
+  }
+}

package/src/accessio.ts

@@ -0,0 +1,251 @@
+import InterceptorManager from './interceptors/interceptorManager';
+import AccessioError from './core/accessioError';
+import mergeConfig from './core/mergeConfig';
+import dispatchRequest from './core/request';
+import buildURL from './core/buildURL';
+import retryRequest from './core/retry';
+import { logRequest, logResponse, logError } from './helpers/debug';
+import { rateLimitedRequest } from './helpers/rateLimiter';
+import type {
+  AccessioRequestConfig,
+  AccessioResponse,
+  Interceptors,
+  InterceptorHandler,
+} from './types';
+
+export class Accessio {
+  defaults: AccessioRequestConfig;
+  interceptors: Interceptors;
+
+  constructor(instanceConfig: AccessioRequestConfig = {}) {
+    this.defaults = instanceConfig;
+    this.interceptors = {
+      request: new InterceptorManager(),
+      response: new InterceptorManager(),
+    };
+  }
+
+  request<T = any>(
+    configOrUrl: string | AccessioRequestConfig,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    if (typeof configOrUrl === 'string') {
+      config = { ...config, url: configOrUrl };
+    } else {
+      config = configOrUrl ? { ...configOrUrl } : {};
+    }
+
+    const mergedConfig = mergeConfig(this.defaults, config);
+
+    mergedConfig.method = (mergedConfig.method || 'get').toLowerCase();
+
+    if (!mergedConfig.url && !mergedConfig.baseURL) {
+      throw new AccessioError(
+        'Request URL is required. Provide a `url` or `baseURL` in the config.',
+        AccessioError.ERR_BAD_OPTION,
+        mergedConfig,
+        null,
+        null,
+      );
+    }
+
+    const requestInterceptors: any[] = [];
+    const responseInterceptors: any[] = [];
+
+    this.interceptors.request.forEach((interceptor: InterceptorHandler) => {
+      if (interceptor.runWhen && !interceptor.runWhen(mergedConfig)) {
+        return;
+      }
+      requestInterceptors.unshift(interceptor);
+    });
+
+    this.interceptors.response.forEach((interceptor: InterceptorHandler) => {
+      responseInterceptors.push(interceptor);
+    });
+
+    let promise: Promise<any> = Promise.resolve(mergedConfig);
+
+    for (const interceptor of requestInterceptors) {
+      promise = promise.then(
+        (value: any) => {
+          if (interceptor.fulfilled) {
+            return interceptor.fulfilled(value);
+          }
+          return value;
+        },
+        interceptor.rejected,
+      );
+    }
+
+    promise = promise.then((cfg: any) => {
+      const fullUrl = buildURL(
+        cfg.url ?? '',
+        cfg.baseURL,
+        cfg.params,
+        cfg.paramsSerializer,
+      );
+
+      logRequest(cfg, fullUrl);
+
+      const enrichedCfg =
+        fullUrl !== (cfg.url || '')
+          ? { ...cfg, _builtUrl: fullUrl }
+          : cfg;
+
+      const dispatchFn = cfg.rateLimiter
+        ? (config: AccessioRequestConfig) =>
+            rateLimitedRequest(dispatchRequest, config.rateLimiter!, config)
+        : dispatchRequest;
+
+      return retryRequest(dispatchFn, enrichedCfg);
+    });
+
+    promise = promise.then(
+      (value: any) => {
+        logResponse(value);
+        return value;
+      },
+      (error: any) => {
+        logError(error, mergedConfig);
+        throw error;
+      },
+    );
+
+    for (const interceptor of responseInterceptors) {
+      promise = promise.then(
+        (value: any) => {
+          if (interceptor.fulfilled) {
+            return interceptor.fulfilled(value);
+          }
+          return value;
+        },
+        interceptor.rejected,
+      );
+    }
+
+    return promise;
+  }
+
+  getUri(config?: AccessioRequestConfig): string {
+    const merged = mergeConfig(this.defaults, config);
+    return buildURL(
+      merged.url ?? '',
+      merged.baseURL,
+      merged.params,
+      merged.paramsSerializer,
+    );
+  }
+
+  get<T = any>(
+    url: string,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'get', url }),
+    );
+  }
+
+  delete<T = any>(
+    url: string,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'delete', url }),
+    );
+  }
+
+  head<T = any>(
+    url: string,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'head', url }),
+    );
+  }
+
+  options<T = any>(
+    url: string,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'options', url }),
+    );
+  }
+
+  post<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'post', url, data }),
+    );
+  }
+
+  put<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'put', url, data }),
+    );
+  }
+
+  patch<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, { method: 'patch', url, data }),
+    );
+  }
+
+  postForm<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, {
+        method: 'post',
+        url,
+        data,
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    );
+  }
+
+  putForm<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, {
+        method: 'put',
+        url,
+        data,
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    );
+  }
+
+  patchForm<T = any>(
+    url: string,
+    data?: any,
+    config?: AccessioRequestConfig,
+  ): Promise<AccessioResponse<T>> {
+    return this.request<T>(
+      mergeConfig(config || {}, {
+        method: 'patch',
+        url,
+        data,
+        headers: { 'Content-Type': 'multipart/form-data' },
+      }),
+    );
+  }
+}
+
+export default Accessio;

package/src/constants/errorCodes.ts

@@ -0,0 +1,29 @@
+const ErrorCodes = {
+  ERR_BAD_OPTION_VALUE: 'ERR_BAD_OPTION_VALUE',
+  ERR_BAD_OPTION: 'ERR_BAD_OPTION',
+  ECONNABORTED: 'ECONNABORTED',
+  ETIMEDOUT: 'ETIMEDOUT',
+  ERR_NETWORK: 'ERR_NETWORK',
+  ERR_FR_TOO_MANY_REDIRECTS: 'ERR_FR_TOO_MANY_REDIRECTS',
+  ERR_BAD_RESPONSE: 'ERR_BAD_RESPONSE',
+  ERR_BAD_REQUEST: 'ERR_BAD_REQUEST',
+  ERR_CANCELED: 'ERR_CANCELED',
+  ERR_NOT_SUPPORT: 'ERR_NOT_SUPPORT',
+  ERR_INVALID_URL: 'ERR_INVALID_URL',
+} as const;
+
+export default ErrorCodes;
+
+export const {
+  ERR_BAD_OPTION_VALUE,
+  ERR_BAD_OPTION,
+  ECONNABORTED,
+  ETIMEDOUT,
+  ERR_NETWORK,
+  ERR_FR_TOO_MANY_REDIRECTS,
+  ERR_BAD_RESPONSE,
+  ERR_BAD_REQUEST,
+  ERR_CANCELED,
+  ERR_NOT_SUPPORT,
+  ERR_INVALID_URL,
+} = ErrorCodes;

package/src/core/accessioError.ts

@@ -0,0 +1,74 @@
+import ErrorCodes from '../constants/errorCodes';
+import type { AccessioRequestConfig, AccessioResponse } from '../types';
+
+export class AccessioError extends Error {
+  static ERR_BAD_OPTION_VALUE: string = ErrorCodes.ERR_BAD_OPTION_VALUE;
+  static ERR_BAD_OPTION: string = ErrorCodes.ERR_BAD_OPTION;
+  static ECONNABORTED: string = ErrorCodes.ECONNABORTED;
+  static ETIMEDOUT: string = ErrorCodes.ETIMEDOUT;
+  static ERR_NETWORK: string = ErrorCodes.ERR_NETWORK;
+  static ERR_FR_TOO_MANY_REDIRECTS: string = ErrorCodes.ERR_FR_TOO_MANY_REDIRECTS;
+  static ERR_BAD_RESPONSE: string = ErrorCodes.ERR_BAD_RESPONSE;
+  static ERR_BAD_REQUEST: string = ErrorCodes.ERR_BAD_REQUEST;
+  static ERR_CANCELED: string = ErrorCodes.ERR_CANCELED;
+  static ERR_NOT_SUPPORT: string = ErrorCodes.ERR_NOT_SUPPORT;
+  static ERR_INVALID_URL: string = ErrorCodes.ERR_INVALID_URL;
+
+  readonly code: string | null;
+  readonly config: AccessioRequestConfig | null;
+  readonly request: unknown;
+  readonly response: AccessioResponse | null;
+  readonly isAccessioError: true;
+  cause?: Error;
+
+  constructor(
+    message: string,
+    code: string | null,
+    config: AccessioRequestConfig | null,
+    request: unknown,
+    response: AccessioResponse | null,
+  ) {
+    super(message);
+    this.name = 'AccessioError';
+    this.code = code ?? null;
+    this.config = config ?? null;
+    this.request = request ?? null;
+    this.response = response ?? null;
+    this.isAccessioError = true;
+
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, AccessioError);
+    }
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      status: this.response ? this.response.status : null,
+      config: this.config,
+    };
+  }
+
+  static from(
+    error: Error,
+    code: string,
+    config: AccessioRequestConfig | null,
+    request: unknown,
+    response: AccessioResponse | null,
+  ): AccessioError {
+    const accessioError = new AccessioError(
+      error.message,
+      code,
+      config,
+      request,
+      response,
+    );
+    accessioError.cause = error;
+    accessioError.stack = error.stack;
+    return accessioError;
+  }
+}
+
+export default AccessioError;

package/src/core/buildURL.ts

@@ -0,0 +1,99 @@
+import type { ParamsSerializer } from '../types';
+
+function serializeParams(
+  params: Record<string, unknown>,
+  paramsSerializer?: ParamsSerializer,
+): string {
+  if (!params) return '';
+
+  if (typeof paramsSerializer === 'function') {
+    return paramsSerializer(params);
+  }
+
+  if (
+    typeof URLSearchParams !== 'undefined' &&
+    params instanceof URLSearchParams
+  ) {
+    return params.toString();
+  }
+
+  const parts: string[] = [];
+
+  function encode(prefix: string, value: unknown): void {
+    if (value === null || value === undefined) {
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        if (typeof item === 'object' && item !== null) {
+          encode(`${prefix}[${index}]`, item);
+        } else {
+          encode(`${prefix}[]`, item);
+        }
+      });
+    } else if (typeof value === 'object' && !(value instanceof Date)) {
+      Object.keys(value as Record<string, unknown>).forEach((key) => {
+        encode(`${prefix}[${key}]`, (value as Record<string, unknown>)[key]);
+      });
+    } else {
+      const encodedValue = value instanceof Date ? value.toISOString() : value;
+      parts.push(
+        `${encodeURIComponent(prefix)}=${encodeURIComponent(
+          encodedValue as string,
+        )}`,
+      );
+    }
+  }
+
+  Object.keys(params).forEach((key) => {
+    encode(key, params[key]);
+  });
+
+  return parts.join('&');
+}
+
+function combineURLs(baseURL: string, relativeURL: string): string {
+  if (!baseURL) return relativeURL || '';
+  if (!relativeURL) return baseURL;
+
+  let base = baseURL;
+  while (base.endsWith('/')) {
+    base = base.slice(0, -1);
+  }
+
+  let relative = relativeURL;
+  while (relative.startsWith('/')) {
+    relative = relative.slice(1);
+  }
+
+  return `${base}/${relative}`;
+}
+
+function isAbsoluteURL(url: string): boolean {
+  return /^([a-z][a-z\d+\-.]*:)?\/\//i.test(url);
+}
+
+export default function buildURL(
+  url: string,
+  baseURL?: string,
+  params?: Record<string, unknown>,
+  paramsSerializer?: ParamsSerializer,
+): string {
+  let fullURL =
+    baseURL && !isAbsoluteURL(url) ? combineURLs(baseURL, url) : url || '';
+
+  const serialized = serializeParams(params as Record<string, unknown>, paramsSerializer);
+  if (serialized) {
+    const hashIndex = fullURL.indexOf('#');
+    if (hashIndex !== -1) {
+      fullURL = fullURL.slice(0, hashIndex);
+    }
+    fullURL +=
+      (fullURL.indexOf('?') === -1 ? '?' : '&') + serialized;
+  }
+
+  return fullURL;
+}
+
+export { serializeParams, combineURLs, isAbsoluteURL };

package/src/core/mergeConfig.ts

@@ -0,0 +1,78 @@
+import type { AccessioRequestConfig } from '../types';
+
+function deepMerge(...sources: any[]): Record<string, any> {
+  const result: Record<string, any> = {};
+
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+
+    for (const key of Object.keys(source)) {
+      const value = source[key];
+
+      if (
+        value &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+      ) {
+        if (
+          value instanceof Date ||
+          value instanceof RegExp ||
+          value instanceof Map ||
+          value instanceof Set ||
+          value instanceof Error ||
+          (typeof ArrayBuffer !== 'undefined' &&
+            value instanceof ArrayBuffer) ||
+          (typeof Blob !== 'undefined' && value instanceof Blob)
+        ) {
+          result[key] = value;
+        } else if (
+          result[key] &&
+          typeof result[key] === 'object' &&
+          !Array.isArray(result[key])
+        ) {
+          result[key] = deepMerge(result[key], value);
+        } else {
+          result[key] = deepMerge(value);
+        }
+      } else if (value !== undefined) {
+        result[key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+const requestOnlyKeys = new Set<string>(['url', 'data', 'signal']);
+const deepMergeKeys = new Set<string>(['headers']);
+
+export default function mergeConfig(
+  config1: AccessioRequestConfig = {},
+  config2: AccessioRequestConfig = {},
+): AccessioRequestConfig {
+  const merged: any = {};
+
+  const allKeys = new Set<string>([
+    ...Object.keys(config1),
+    ...Object.keys(config2),
+  ]);
+
+  for (const key of allKeys) {
+    const val1 = config1[key as keyof AccessioRequestConfig];
+    const val2 = config2[key as keyof AccessioRequestConfig];
+
+    if (requestOnlyKeys.has(key)) {
+      if (val2 !== undefined) {
+        merged[key] = val2;
+      }
+    } else if (deepMergeKeys.has(key)) {
+      merged[key] = deepMerge(val1 || {}, val2 || {});
+    } else {
+      merged[key] = val2 !== undefined ? val2 : val1;
+    }
+  }
+
+  return merged;
+}
+
+export { deepMerge };