hanzio 1.0.0

package/dist/api-wrapper/index.js

@@ -0,0 +1,250 @@
+// src/api-wrapper/index.ts
+import { ZodError } from "zod";
+
+class ResponseValidationError extends Error {
+  zodError;
+  rawResponse;
+  validationIssues;
+  constructor(zodError, rawResponse) {
+    const issues = zodError.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    super(`Response validation failed: ${issues}`);
+    this.name = "ResponseValidationError";
+    this.zodError = zodError;
+    this.rawResponse = rawResponse;
+    this.validationIssues = issues;
+  }
+}
+
+class HttpResponseError extends Error {
+  status;
+  body;
+  constructor(status, body) {
+    super(`HTTP error: ${status} - ${body}`);
+    this.name = "HttpResponseError";
+    this.status = status;
+    this.body = body;
+  }
+}
+function createApiClient(apiConfig) {
+  const request = async (endpointKey, input = {}) => {
+    const endpoint = apiConfig.endpoints[endpointKey];
+    if (!endpoint) {
+      throw new Error(`Unknown API endpoint: ${String(endpointKey)}`);
+    }
+    const { finalUrl, fullUrl } = buildUrl(endpoint, input.reqParams, input.reqQuery, apiConfig.baseApiUrls, apiConfig.defaultBaseApiUrl, input.url);
+    const endpointName = apiConfig.name ? `${apiConfig.name}.${String(endpointKey)}` : String(endpointKey);
+    const startedAt = Date.now();
+    let retryCount = 0;
+    let httpStatus = 0;
+    apiConfig.onRequestStart?.({ endpoint: endpointName, url: fullUrl });
+    try {
+      const config = {
+        method: endpoint.method,
+        url: finalUrl,
+        queryParams: buildQueryParams(endpoint, input.reqQuery),
+        body: buildRequestBody(endpoint, input.reqBody),
+        headers: buildHeaders(endpoint, input.reqHeaders, apiConfig.defaultHeaders ?? {}),
+        doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
+        timeoutMs: apiConfig.timeoutMs,
+        fetchFn: apiConfig.fetch ?? fetch
+      };
+      const result = await makeRequestWithRetry(config, apiConfig.retries ?? 3, apiConfig.retryDelayMs ?? 300, (response) => validateAndTransformResponse(endpoint, response), apiConfig.shouldRetry ?? defaultShouldRetry, apiConfig.logger);
+      retryCount = result.retryCount;
+      httpStatus = result.httpStatus;
+      const responseTimeMs = Date.now() - startedAt;
+      const responseSizeMb = calculateSizeInMb(result.validatedData);
+      const requestSizeMb = calculateSizeInMb({
+        method: config.method,
+        url: fullUrl,
+        body: config.body,
+        headers: config.headers
+      });
+      apiConfig.onRequestEnd?.({
+        endpoint: endpointName,
+        url: fullUrl,
+        status: httpStatus,
+        retryCount,
+        responseTimeMs
+      });
+      return {
+        data: result.validatedData,
+        requestSizeMb,
+        responseSizeMb,
+        requestSizeTotalMb: requestSizeMb + responseSizeMb,
+        responseTimeMs,
+        httpStatus,
+        retryCount
+      };
+    } catch (error) {
+      apiConfig.logger?.error?.(error);
+      throw error;
+    }
+  };
+  return { request };
+}
+var createApiWrapper = createApiClient;
+async function validateResponse(schema, data) {
+  try {
+    return await schema.parseAsync(data);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new ResponseValidationError(error, data);
+    }
+    throw error;
+  }
+}
+async function httpRequest(config) {
+  const queryString = config.doNotEncodeQueryParams ? Object.entries(config.queryParams).map(([key, value]) => `${key}=${value}`).join("&") : new URLSearchParams(config.queryParams).toString();
+  const fullUrl = queryString ? `${config.url}?${queryString}` : config.url;
+  const abortController = new AbortController;
+  const timeout = config.timeoutMs === undefined ? undefined : setTimeout(() => abortController.abort(), config.timeoutMs);
+  try {
+    return await config.fetchFn(fullUrl, {
+      method: config.method,
+      headers: config.headers,
+      body: buildFetchBody(config.body, config.headers),
+      signal: abortController.signal
+    });
+  } finally {
+    if (timeout)
+      clearTimeout(timeout);
+  }
+}
+async function makeRequestWithRetry(config, maxRetries, retryDelayMs, validateFn, shouldRetry, logger) {
+  let retryCount = 0;
+  while (true) {
+    try {
+      logger?.debug?.("API request", config);
+      const response = await httpRequest(config);
+      if (response.status >= 400) {
+        if (retryCount < maxRetries && shouldRetry({ response, retryCount, maxRetries })) {
+          retryCount++;
+          await delay(retryDelayMs);
+          continue;
+        }
+        throw new HttpResponseError(response.status, await response.text());
+      }
+      return {
+        validatedData: await validateFn(response),
+        retryCount,
+        httpStatus: response.status
+      };
+    } catch (error) {
+      if (error instanceof HttpResponseError)
+        throw error;
+      if (retryCount >= maxRetries || !shouldRetry({ error, retryCount, maxRetries })) {
+        throw error;
+      }
+      retryCount++;
+      await delay(retryDelayMs);
+    }
+  }
+}
+async function validateAndTransformResponse(endpoint, response) {
+  const responseHeaders = getHeadersAsObject(response.headers);
+  const contentType = responseHeaders["content-type"] ?? "";
+  const responseData = contentType.includes("application/json") ? await response.json() : await response.text();
+  const transformedData = endpoint.resFormatter ? endpoint.resFormatter(responseData, responseHeaders) : responseData;
+  return validateResponse(endpoint.resSchema, transformedData);
+}
+function buildUrl(endpoint, params, reqQuery, baseApiUrls, defaultBaseApiUrl, url) {
+  if (url) {
+    const finalUrl2 = replacePathParams(url, params);
+    const queryString2 = new URLSearchParams(buildQueryParams(endpoint, reqQuery)).toString();
+    return {
+      finalUrl: finalUrl2,
+      fullUrl: queryString2 ? `${finalUrl2}?${queryString2}` : finalUrl2
+    };
+  }
+  const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0];
+  if (!defaultBaseUrl) {
+    throw new Error("At least one base API URL is required");
+  }
+  const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl;
+  const configBaseUrl = baseApiUrls[baseUrlKey];
+  if (!configBaseUrl) {
+    throw new Error(`Unknown base API URL: ${baseUrlKey}`);
+  }
+  const baseUrl = typeof configBaseUrl === "function" ? configBaseUrl() : configBaseUrl;
+  const path = typeof endpoint.path === "function" ? endpoint.path(baseUrl) : endpoint.path;
+  const finalUrl = replacePathParams(`${baseUrl}${path}`, params);
+  const queryString = new URLSearchParams(buildQueryParams(endpoint, reqQuery)).toString();
+  return {
+    finalUrl,
+    fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+  };
+}
+function buildQueryParams(endpoint, query) {
+  const defaultParams = endpoint.reqDefaultQueryParams ?? {};
+  const parsedQuery = endpoint.reqQuerySchema ? endpoint.reqQuerySchema.parse(query) : query ?? {};
+  const merged = { ...defaultParams, ...parsedQuery };
+  return Object.fromEntries(Object.entries(merged).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+}
+function buildRequestBody(endpoint, body) {
+  if (!endpoint.reqBodySchema)
+    return body;
+  const parsedBody = endpoint.reqBodySchema.parse(body);
+  if (endpoint.reqBodyFormat !== "form-data") {
+    return parsedBody;
+  }
+  const formData = new FormData;
+  for (const [key, value] of Object.entries(parsedBody)) {
+    if (value == null)
+      continue;
+    formData.set(key, value instanceof Blob ? value : String(value));
+  }
+  return formData;
+}
+function buildHeaders(endpoint, headers, defaultHeaders) {
+  const contentType = endpoint.reqBodyFormat === "json" ? "application/json" : undefined;
+  const parsedHeaders = endpoint.reqHeadersSchema ? endpoint.reqHeadersSchema.parse(headers) : headers ?? {};
+  return {
+    ...defaultHeaders,
+    ...contentType && { "Content-Type": contentType },
+    ...endpoint.defaultHeaders,
+    ...parsedHeaders
+  };
+}
+function buildFetchBody(body, headers) {
+  if (body === undefined || body === null)
+    return;
+  if (body instanceof FormData || body instanceof Blob)
+    return body;
+  if (headers["Content-Type"] === "application/json")
+    return JSON.stringify(body);
+  return body;
+}
+function replacePathParams(path, params) {
+  return path.replace(/:(\w+)/g, (_, key) => {
+    const value = params?.[key];
+    if (value === undefined) {
+      throw new Error(`Missing required path parameter: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+function getHeadersAsObject(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+function calculateSizeInMb(data) {
+  const sizeInBytes = new TextEncoder().encode(JSON.stringify(data)).length;
+  return sizeInBytes / (1024 * 1024);
+}
+function defaultShouldRetry({ error, response }) {
+  if (error)
+    return true;
+  return response ? response.status >= 500 : false;
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  createApiWrapper,
+  createApiClient,
+  ResponseValidationError,
+  HttpResponseError
+};

package/dist/array/index.d.ts

@@ -0,0 +1,22 @@
+export interface ArrayDifference<TCurrent, TNext> {
+    new: TNext[];
+    upsert: TNext[];
+    delete: TCurrent[];
+}
+type PropertyKeyValue = string | number | symbol;
+type NonNullableValue<T> = T extends null | undefined ? never : T;
+type ItemsMatchingKeyValue<T, TKey extends keyof T, TValue> = [
+    Extract<T, Record<TKey, TValue>>
+] extends [never] ? T : Extract<T, Record<TKey, TValue>>;
+export declare function chunkArray<T>(array: readonly T[], chunkSize: number): T[][];
+export declare function findArrayDifferenceByKey<TCurrent, TNext, TKey extends keyof TCurrent & keyof TNext>(current: readonly TCurrent[], next: readonly TNext[], key: TKey): ArrayDifference<TCurrent, TNext>;
+export declare function getUniqueValues<T>(array: readonly T[]): T[];
+export declare function compact<T>(array: readonly T[]): NonNullableValue<T>[];
+export declare function getUniqueValuesByKey<T, TKey extends keyof T>(array: readonly T[], key: TKey): T[];
+export declare function groupBy<T, TKey extends keyof T, TGroupKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Record<TGroupKey, T[]>;
+export declare function groupBy<T, TGroupKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TGroupKey): Record<TGroupKey, T[]>;
+export declare function keyBy<T, TKey extends keyof T, TRecordKey extends Extract<T[TKey], PropertyKeyValue>>(array: readonly T[], key: TKey): Record<TRecordKey, T>;
+export declare function keyBy<T, TRecordKey extends PropertyKeyValue>(array: readonly T[], keyFn: (item: T) => TRecordKey): Record<TRecordKey, T>;
+export declare function partition<T>(array: readonly T[], predicate: (item: T, index: number) => boolean): [matched: T[], unmatched: T[]];
+export declare function pickItemsInArray<T, TKey extends keyof T, const TValue extends readonly T[TKey][]>(array: readonly T[], key: TKey, values: TValue): ItemsMatchingKeyValue<T, TKey, TValue[number]>[];
+export {};

package/dist/cache/index.d.ts

@@ -0,0 +1,19 @@
+type AnyFunction = (...args: never[]) => unknown;
+type CachedFunction<T extends AnyFunction> = {
+    (...args: Parameters<T>): ReturnType<T>;
+    clearCache: () => void;
+};
+export type CacheFunctionOptions<T extends AnyFunction> = {
+    name: string;
+    fn: T;
+    cacheTimeMs?: number;
+    refreshInBackground?: boolean;
+    cacheKeyArgs?: number[];
+    cacheKeyFn?: (...args: Parameters<T>) => unknown[];
+    /** Called when a background refresh fails (default: silent). */
+    onBackgroundRefreshError?: (error: unknown, context: {
+        name: string;
+    }) => void;
+};
+export declare function cacheFunction<T extends AnyFunction>(options: CacheFunctionOptions<T>): CachedFunction<T>;
+export {};

package/dist/date/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calculate the previous period date range for a given period type.
+ */
+export declare function getPreviousReportPeriod(periodType: 'MONTHLY' | 'QUARTERLY' | 'YEARLY', referenceDate?: Date): {
+    start: Date;
+    end: Date;
+};
+/**
+ * Format a date range as a human-readable period label.
+ */
+export declare function formatPeriodLabel(start: Date | string, end: Date | string, includeDay?: boolean): string;

package/dist/gzip/index.d.ts

@@ -0,0 +1,2 @@
+export declare function compressString(input: string): string;
+export declare function decompressString(compressedString: string): string;

package/dist/gzip/index.js

@@ -0,0 +1,16 @@
+// src/gzip/index.ts
+import pako from "pako";
+function compressString(input) {
+  const uint8Array = new TextEncoder().encode(input);
+  const compressed = pako.deflate(uint8Array);
+  return btoa(String.fromCharCode.apply(null, compressed));
+}
+function decompressString(compressedString) {
+  const compressedData = new Uint8Array(atob(compressedString).split("").map((char) => char.charCodeAt(0)));
+  const decompressed = pako.inflate(compressedData);
+  return new TextDecoder().decode(decompressed);
+}
+export {
+  decompressString,
+  compressString
+};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './typedswitch';
+export * from './array';
+export * from './string';
+export * from './promise';
+export * from './cache';
+export * from './state';
+export * from './math';
+export * from './date';
+export * from './url';
+export * from './zod';
+export * from './api-wrapper';
+export * from './p-queue';