accessio 1.0.0

package/src/core/request.ts

@@ -0,0 +1,284 @@
+import buildURL from './buildURL';
+import AccessioError from './accessioError';
+import parseHeaders from '../helpers/parseHeaders';
+import transformData from '../helpers/transformData';
+import settle from '../helpers/settle';
+import type { AccessioRequestConfig, AccessioResponse, TransformFunction } from '../types';
+
+const METHOD_KEYS = new Set<string>([
+  'common',
+  'delete',
+  'get',
+  'head',
+  'options',
+  'post',
+  'put',
+  'patch',
+]);
+
+type HeadersConfig = Record<string, Record<string, string>>;
+
+function flattenHeaders(
+  headers: HeadersConfig | undefined,
+  method?: string,
+): Record<string, string> {
+  if (!headers) return {};
+
+  const merged: Record<string, string> = {};
+  const methodLower = (method || 'get').toLowerCase();
+
+  if (headers['common']) {
+    Object.assign(merged, headers['common']);
+  }
+
+  if (headers[methodLower]) {
+    Object.assign(merged, headers[methodLower]);
+  }
+
+  for (const key in headers) {
+    if (
+      Object.prototype.hasOwnProperty.call(headers, key) &&
+      !METHOD_KEYS.has(key)
+    ) {
+      merged[key] = headers[key] as unknown as string;
+    }
+  }
+
+  return merged;
+}
+
+function removeContentType(headers: Record<string, string>): void {
+  const key = Object.keys(headers).find(
+    (k) => k.toLowerCase() === 'content-type',
+  );
+  if (key) {
+    delete headers[key];
+  }
+}
+
+function buildTransformArray(
+  transform: TransformFunction | TransformFunction[] | undefined,
+): TransformFunction[] {
+  if (!transform) return [];
+  if (Array.isArray(transform)) return transform;
+  return [transform];
+}
+
+export default function dispatchRequest(
+  config: AccessioRequestConfig,
+): Promise<AccessioResponse> {
+  const fullURL =
+    config._builtUrl ||
+    buildURL(
+      config.url ?? '',
+      config.baseURL,
+      config.params as Record<string, unknown> | undefined,
+      config.paramsSerializer,
+    );
+
+  const flatHeaders = flattenHeaders(
+    config.headers as HeadersConfig | undefined,
+    config.method,
+  );
+
+  const requestTransforms = buildTransformArray(config.transformRequest);
+
+  const requestData = transformData(
+    requestTransforms,
+    config.data,
+    flatHeaders,
+    config,
+  );
+
+  if (
+    requestData === null ||
+    requestData === undefined ||
+    (typeof FormData !== 'undefined' && requestData instanceof FormData)
+  ) {
+    removeContentType(flatHeaders);
+  }
+
+  if (config.auth) {
+    const username = config.auth.username || '';
+    const password = config.auth.password || '';
+    const credentials = `${username}:${password}`;
+
+    let encoded: string;
+    if (typeof Buffer !== 'undefined') {
+      encoded = Buffer.from(credentials).toString('base64');
+    } else {
+      const bytes = new TextEncoder().encode(credentials);
+      const binString = Array.from(bytes, (x) =>
+        String.fromCodePoint(x),
+      ).join('');
+      encoded = btoa(binString);
+    }
+
+    flatHeaders['Authorization'] = `Basic ${encoded}`;
+  }
+
+  const fetchOptions: RequestInit = {
+    method: (config.method || 'GET').toUpperCase(),
+    headers: flatHeaders,
+  };
+
+  const methodsWithBody = ['POST', 'PUT', 'PATCH', 'DELETE'];
+  if (
+    methodsWithBody.includes(fetchOptions.method!) &&
+    requestData !== undefined &&
+    requestData !== null
+  ) {
+    fetchOptions.body = requestData as BodyInit;
+  }
+
+  if (config.withCredentials) {
+    fetchOptions.credentials = 'include';
+  }
+
+  let abortController: AbortController | null = null;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let isTimedOut = false;
+  let onUserAbort: (() => void) | null = null;
+
+  if (config.timeout && config.timeout > 0) {
+    abortController = new AbortController();
+
+    timeoutId = setTimeout(() => {
+      isTimedOut = true;
+      abortController!.abort(
+        new AccessioError(
+          `timeout of ${config.timeout}ms exceeded`,
+          AccessioError.ETIMEDOUT,
+          config,
+          null,
+          null,
+        ),
+      );
+    }, config.timeout);
+
+    if (config.signal) {
+      if (typeof AbortSignal.any === 'function') {
+        fetchOptions.signal = AbortSignal.any([
+          config.signal,
+          abortController.signal,
+        ]);
+      } else {
+        if (config.signal.aborted) {
+          abortController.abort(config.signal.reason);
+        } else {
+          onUserAbort = () => {
+            abortController!.abort(config.signal!.reason);
+          };
+          config.signal.addEventListener('abort', onUserAbort, {
+            once: true,
+          });
+        }
+        fetchOptions.signal = abortController.signal;
+      }
+    } else {
+      fetchOptions.signal = abortController.signal;
+    }
+  } else if (config.signal) {
+    fetchOptions.signal = config.signal;
+  }
+
+  const requestStartTime = Date.now();
+
+  return fetch(fullURL, fetchOptions)
+    .then(async (fetchResponse) => {
+      let responseData: unknown;
+      const responseType = config.responseType || 'json';
+
+      try {
+        switch (responseType) {
+          case 'arraybuffer':
+            responseData = await fetchResponse.arrayBuffer();
+            break;
+          case 'blob':
+            responseData = await fetchResponse.blob();
+            break;
+          case 'text':
+            responseData = await fetchResponse.text();
+            break;
+          case 'stream':
+            responseData = fetchResponse.body;
+            break;
+          case 'json':
+          default:
+            responseData = await fetchResponse.text();
+            break;
+        }
+      } catch (readError) {
+        throw AccessioError.from(
+          readError as Error,
+          AccessioError.ERR_BAD_RESPONSE,
+          config,
+          fetchResponse,
+          null,
+        );
+      }
+
+      const responseHeaders = parseHeaders(fetchResponse.headers);
+
+      const responseTransforms = buildTransformArray(config.transformResponse);
+
+      responseData = transformData(
+        responseTransforms,
+        responseData,
+        responseHeaders,
+        config,
+      );
+
+      const response: AccessioResponse = {
+        data: responseData,
+        status: fetchResponse.status,
+        statusText: fetchResponse.statusText,
+        headers: responseHeaders,
+        config: config,
+        request: fetchResponse,
+        duration: Date.now() - requestStartTime,
+      };
+
+      return new Promise<AccessioResponse>((resolve, reject) => {
+        settle(resolve as (value: AccessioResponse) => void, reject as (reason: AccessioError) => void, response, config);
+      });
+    })
+    .catch((error) => {
+      if (error instanceof AccessioError) {
+        throw error;
+      }
+
+      if (error instanceof Error && error.name === 'AbortError') {
+        if (isTimedOut) {
+          throw new AccessioError(
+            `timeout of ${config.timeout}ms exceeded`,
+            AccessioError.ETIMEDOUT,
+            config,
+            null,
+            null,
+          );
+        }
+        throw new AccessioError(
+          'Request aborted',
+          AccessioError.ERR_CANCELED,
+          config,
+          null,
+          null,
+        );
+      }
+
+      throw AccessioError.from(
+        error instanceof Error ? error : new Error(String(error)),
+        AccessioError.ERR_NETWORK,
+        config,
+        null,
+        null,
+      );
+    })
+    .finally(() => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (config.signal && onUserAbort) {
+        config.signal.removeEventListener('abort', onUserAbort);
+      }
+    });
+}

package/src/core/retry.ts

@@ -0,0 +1,117 @@
+import {
+  ERR_CANCELED,
+  ERR_NETWORK,
+  ETIMEDOUT,
+} from '../constants/errorCodes';
+import type {
+  AccessioRequestConfig,
+  AccessioResponse,
+  AccessioError,
+  RetryConditionFunction,
+  OnRetryFunction,
+} from '../types';
+
+function defaultRetryCondition(error: any): boolean {
+  if (error.code === ERR_CANCELED) {
+    return false;
+  }
+
+  if (error.code === ERR_NETWORK) {
+    return true;
+  }
+
+  if (error.code === ETIMEDOUT) {
+    return true;
+  }
+
+  if (error.response && error.response.status >= 500) {
+    return true;
+  }
+
+  return false;
+}
+
+function calculateDelay(attempt: number, baseDelay: number): number {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+  return Math.round(exponentialDelay + jitter);
+}
+
+function sleep(ms: number, options?: { signal?: AbortSignal }): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let onAbort: (() => void) | undefined;
+
+    const timeoutId = setTimeout(() => {
+      if (options?.signal && onAbort) {
+        options.signal.removeEventListener('abort', onAbort);
+      }
+      resolve();
+    }, ms);
+
+    if (options?.signal) {
+      if (options.signal.aborted) {
+        clearTimeout(timeoutId);
+        return reject(
+          options.signal.reason || new Error('Sleep aborted'),
+        );
+      }
+
+      onAbort = () => {
+        clearTimeout(timeoutId);
+        reject(options.signal!.reason || new Error('Sleep aborted'));
+      };
+
+      options.signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}
+
+async function retryRequest(
+  dispatchFn: (config: AccessioRequestConfig) => Promise<any>,
+  config: AccessioRequestConfig,
+): Promise<any> {
+  const maxRetries = config.retry ?? 0;
+
+  if (maxRetries <= 0) {
+    return dispatchFn(config);
+  }
+
+  const retryDelay = config.retryDelay ?? 1000;
+  const retryCondition: RetryConditionFunction =
+    config.retryCondition ?? defaultRetryCondition;
+
+  let lastError: any;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await dispatchFn(config);
+      return response;
+    } catch (error) {
+      lastError = error;
+
+      const isLastAttempt = attempt >= maxRetries;
+      const shouldRetry = !isLastAttempt && retryCondition(error as AccessioError);
+
+      if (!shouldRetry) {
+        throw error;
+      }
+
+      const delay = calculateDelay(attempt, retryDelay);
+
+      if (typeof config.onRetry === 'function') {
+        (config.onRetry as OnRetryFunction)(
+          attempt + 1,
+          error as AccessioError,
+          config,
+        );
+      }
+
+      await sleep(delay, { signal: config.signal });
+    }
+  }
+
+  throw lastError;
+}
+
+export { defaultRetryCondition, calculateDelay };
+export default retryRequest;

package/src/defaults/index.ts

@@ -0,0 +1,36 @@
+import { defaultTransformRequest, defaultTransformResponse } from './transforms';
+import type { AccessioRequestConfig } from '../types';
+
+const defaults: AccessioRequestConfig = {
+  method: 'get',
+  timeout: 0,
+  headers: {
+    common: {
+      Accept: 'application/json, text/plain, */*',
+    },
+    delete: {},
+    get: {},
+    head: {},
+    options: {},
+    post: {
+      'Content-Type': 'application/json',
+    },
+    put: {
+      'Content-Type': 'application/json',
+    },
+    patch: {
+      'Content-Type': 'application/json',
+    },
+  },
+  transformRequest: [defaultTransformRequest],
+  transformResponse: [defaultTransformResponse],
+  validateStatus: function defaultValidateStatus(
+    status: number,
+  ): boolean {
+    return status >= 200 && status < 300;
+  },
+  responseType: 'json',
+  withCredentials: false,
+};
+
+export default defaults;

package/src/defaults/transforms.ts

@@ -0,0 +1,44 @@
+export function defaultTransformRequest(
+  data: unknown,
+  headers: Record<string, string>,
+): unknown {
+  if (data === null || data === undefined) {
+    return data;
+  }
+
+  if (
+    typeof data === 'string' ||
+    data instanceof ArrayBuffer ||
+    (typeof Blob !== 'undefined' && data instanceof Blob) ||
+    (typeof FormData !== 'undefined' && data instanceof FormData) ||
+    (typeof URLSearchParams !== 'undefined' && data instanceof URLSearchParams) ||
+    (typeof ReadableStream !== 'undefined' && data instanceof ReadableStream)
+  ) {
+    return data;
+  }
+
+  if (typeof data === 'object') {
+    if (headers && typeof headers === 'object') {
+      const hasContentType = Object.keys(headers).some(
+        (key) => key.toLowerCase() === 'content-type',
+      );
+      if (!hasContentType) {
+        headers['Content-Type'] = 'application/json';
+      }
+    }
+    return JSON.stringify(data);
+  }
+
+  return data;
+}
+
+export function defaultTransformResponse(data: unknown): unknown {
+  if (typeof data === 'string') {
+    try {
+      return JSON.parse(data);
+    } catch {
+      // Not JSON — return as-is
+    }
+  }
+  return data;
+}

package/src/helpers/debug.ts

@@ -0,0 +1,103 @@
+import type { AccessioRequestConfig, AccessioResponse } from '../types';
+import AccessioError from '../core/accessioError';
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${sizes[i]}`;
+}
+
+function sanitizeConfigForLog(
+  config: AccessioRequestConfig,
+): { params: Record<string, unknown> | undefined; timeout: number | undefined; retry: number | undefined } {
+  return {
+    params: config.params,
+    timeout: config.timeout,
+    retry: config.retry,
+  };
+}
+
+export function logRequest(
+  config: AccessioRequestConfig,
+  fullUrl: string,
+): void {
+  if (!config.debug) return;
+
+  const safe = sanitizeConfigForLog(config);
+
+  const method = (config.method || 'GET').toUpperCase();
+  const url = fullUrl || config.url || '';
+
+  const parts: string[] = [`🐦‍⬛ [Accessio] → ${method} ${url}`];
+
+  if (safe.params && Object.keys(safe.params).length > 0) {
+    parts.push(`   Params: ${JSON.stringify(safe.params)}`);
+  }
+
+  if (config.data && typeof config.data === 'object') {
+    const preview = JSON.stringify(config.data);
+    const truncated =
+      preview.length > 200 ? `${preview.substring(0, 200)}...` : preview;
+    parts.push(`   Body: ${truncated}`);
+  }
+
+  if (safe.timeout) {
+    parts.push(`   Timeout: ${safe.timeout}ms`);
+  }
+
+  if (safe.retry) {
+    parts.push(`   Retry: ${safe.retry}x`);
+  }
+
+  console.log(parts.join('\n'));
+}
+
+export function logResponse(response: AccessioResponse): void {
+  if (!response.config || !response.config.debug) return;
+  const status = response.status;
+  const statusText = response.statusText || '';
+  const duration =
+    response.duration != null ? `${response.duration}ms` : '??';
+
+  const statusIcon =
+    status >= 200 && status < 300
+      ? '✅'
+      : status >= 400
+        ? '❌'
+        : '⚠️';
+
+  const parts: string[] = [
+    `🐦‍⬛ [Accessio] ← ${statusIcon} ${status} ${statusText} (${duration})`,
+  ];
+
+  if (response.data) {
+    try {
+      const size =
+        typeof response.data === 'string'
+          ? response.data.length
+          : JSON.stringify(response.data).length;
+      parts.push(`   Size: ~${formatBytes(size)}`);
+    } catch {
+      // ignore
+    }
+  }
+
+  console.log(parts.join('\n'));
+}
+
+export function logError(error: AccessioError, config?: AccessioRequestConfig): void {
+  if (!config || !config.debug) return;
+
+  const parts: string[] = [`🐦‍⬛ [Accessio] ← ❌ ERROR: ${error.message}`];
+
+  if (error.code) {
+    parts.push(`   Code: ${error.code}`);
+  }
+
+  if (error.response) {
+    parts.push(`   Status: ${error.response.status}`);
+  }
+
+  console.log(parts.join('\n'));
+}

package/src/helpers/parseHeaders.ts

@@ -0,0 +1,35 @@
+export default function parseHeaders(
+  headers: any,
+): Record<string, string> {
+  const parsed: Record<string, string> = {};
+
+  if (!headers) return parsed;
+
+  if (typeof headers.forEach === 'function') {
+    headers.forEach((value: string, key: string) => {
+      parsed[key.toLowerCase()] = value;
+    });
+    return parsed;
+  }
+
+  if (typeof headers === 'string') {
+    headers.split('\n').forEach((line: string) => {
+      const index = line.indexOf(':');
+      if (index > 0) {
+        const key = line.substring(0, index).trim().toLowerCase();
+        const value = line.substring(index + 1).trim();
+        parsed[key] = value;
+      }
+    });
+    return parsed;
+  }
+
+  if (typeof headers === 'object') {
+    Object.keys(headers).forEach((key) => {
+      parsed[key.toLowerCase()] = headers[key];
+    });
+    return parsed;
+  }
+
+  return parsed;
+}

package/src/helpers/rateLimiter.ts

@@ -0,0 +1,96 @@
+import type {
+  RateLimiter,
+  AccessioRequestConfig,
+  AccessioResponse,
+} from '../types';
+
+interface QueueItem {
+  resolve: () => void;
+  reject: (reason: Error) => void;
+}
+
+export function createRateLimiter(maxConcurrent: number = Infinity): RateLimiter {
+  if (
+    maxConcurrent !== Infinity &&
+    (!Number.isInteger(maxConcurrent) || maxConcurrent < 1)
+  ) {
+    throw new RangeError(
+      `[Accessio] maxConcurrent must be a positive integer or Infinity, got: ${maxConcurrent}`,
+    );
+  }
+  let active = 0;
+  let destroyed = false;
+  const queue: QueueItem[] = [];
+
+  function acquire(): Promise<void> {
+    if (destroyed) {
+      return Promise.reject(
+        new Error('[Accessio] Rate limiter has been destroyed'),
+      );
+    }
+
+    if (active < maxConcurrent) {
+      active++;
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve, reject) => {
+      queue.push({ resolve, reject });
+    });
+  }
+
+  function release(): void {
+    if (destroyed) return;
+
+    if (active <= 0) return;
+
+    active--;
+
+    if (queue.length > 0 && active < maxConcurrent) {
+      active++;
+      const next = queue.shift();
+      next?.resolve();
+    }
+  }
+
+  function destroy(): void {
+    destroyed = true;
+    const reason = new Error(
+      '[Accessio] Rate limiter destroyed — pending request cancelled',
+    );
+    while (queue.length > 0) {
+      const next = queue.shift();
+      next?.reject(reason);
+    }
+  }
+
+  return {
+    acquire,
+    release,
+    destroy,
+    get pending() {
+      return queue.length;
+    },
+    get active() {
+      return active;
+    },
+    get destroyed() {
+      return destroyed;
+    },
+  };
+}
+
+export async function rateLimitedRequest<T = unknown>(
+  dispatchFn: (config: AccessioRequestConfig) => Promise<AccessioResponse<T>>,
+  limiter: RateLimiter,
+  config: AccessioRequestConfig,
+): Promise<AccessioResponse<T>> {
+  await limiter.acquire();
+  try {
+    return await dispatchFn(config);
+  } finally {
+    limiter.release();
+  }
+}
+
+export default createRateLimiter;