hanzio 1.0.2 → 1.0.6

package/README.md

@@ -2,7 +2,7 @@
 
 A small TypeScript-first utility library for common application code: arrays,
 strings, promises, caching, state machines, dates, URLs, Zod helpers, API clients,
-JWTs, gzip, sitemap crawling, queues, and colorful terminal logging.
+JWTs, gzip, sitemap crawling, queues, secrets, and colorful terminal logging.
 
 ## Install
 
@@ -211,6 +211,26 @@ import { promiseTimeout } from 'hanzio'
 await promiseTimeout(250)
 ```
 
+### Secrets
+
+`defineSecretSet` loads a typed set of required secrets from `process.env` or
+Infisical before the rest of the program starts.
+
+```ts
+import { defineSecretSet } from 'hanzio'
+
+export const backendSecrets = await defineSecretSet(
+	['DATABASE_URL', 'APP_SECRET'] as const,
+	{ projectId: 'infisical-project-id' }
+)
+
+const databaseUrl = backendSecrets.secret('DATABASE_URL')
+```
+
+For Vite config, `viteSecretSetPlugin(secretSet)` exposes the loaded values as
+`import.meta.env.*` replacements. Use `getViteDefine(secretSet)` if you need the
+raw `define` object.
+
 ### Cache
 
 `cacheFunction` wraps sync or async functions with TTL caching and request

package/dist/index.d.ts

@@ -11,3 +11,7 @@ export * from './zod';
 export * from './api-wrapper';
 export * from './p-queue';
 export * from './cool-console-log';
+export * from './jwt';
+export * from './gzip';
+export * from './sitemap';
+export * from './secrets';

package/dist/index.js

@@ -879,6 +879,150 @@ class PQueue {
   }
 }
 
+// src/jwt/index.ts
+import * as jose from "jose";
+async function jwtSign(payload, secret) {
+  const secretKey = new TextEncoder().encode(secret);
+  return await new jose.SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuedAt().sign(secretKey);
+}
+async function jwtVerify2(token, secret) {
+  try {
+    const secretKey = new TextEncoder().encode(secret);
+    const { payload } = await jose.jwtVerify(token, secretKey);
+    return payload;
+  } catch (_error) {
+    return null;
+  }
+}
+
+// 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);
+}
+
+// src/sitemap/index.ts
+var createTimeoutController = (timeout) => {
+  const controller = new AbortController;
+  setTimeout(() => controller.abort(), timeout);
+  return controller;
+};
+var discoverSitemaps = async (domain) => {
+  const normalizedDomain = domain.replace(/\/$/, "");
+  const commonLocations = [
+    "/sitemap.xml",
+    "/sitemap_index.xml",
+    "/sitemap/",
+    "/sitemaps.xml",
+    "/sitemap/sitemap.xml"
+  ];
+  const sitemaps = new Set;
+  const requestOptions = {
+    headers: {
+      "User-Agent": "SitemapCrawler/1.0"
+    },
+    signal: createTimeoutController(5000).signal
+  };
+  try {
+    const robotsTxt = await fetch(`${normalizedDomain}/robots.txt`, {
+      ...requestOptions
+    });
+    if (robotsTxt.ok) {
+      const text = await robotsTxt.text();
+      const sitemapMatches = text.match(/Sitemap: (.*)/gi);
+      if (sitemapMatches) {
+        sitemapMatches.forEach((match) => {
+          const url = match.replace("Sitemap:", "").trim();
+          sitemaps.add(url);
+        });
+      }
+      if (sitemaps.size > 0) {
+        return [...sitemaps];
+      }
+    }
+  } catch (error) {
+    console.warn("Could not fetch robots.txt:", error instanceof Error ? error.message : "Unknown error");
+  }
+  for (const location of commonLocations) {
+    try {
+      const response = await fetch(`${normalizedDomain}${location}`, {
+        ...requestOptions,
+        method: "HEAD"
+      });
+      if (response.ok) {
+        return [`${normalizedDomain}${location}`];
+      }
+    } catch (_error) {}
+  }
+  return [];
+};
+var getDomainSitemap = async (domain, options = {}) => {
+  const {
+    filterIndexes,
+    concurrency = 10,
+    maxDepth = 5,
+    timeout = 1e4
+  } = options;
+  let normalizedDomain = domain.replace(/\/$/, "");
+  if (!normalizedDomain.startsWith("http")) {
+    normalizedDomain = `https://${normalizedDomain}`;
+  }
+  const sitemapUrls = await discoverSitemaps(normalizedDomain);
+  if (sitemapUrls.length === 0) {
+    throw new Error("No sitemaps found for the domain");
+  }
+  const queue = new PQueue({ concurrency });
+  const result = {
+    links: new Set,
+    visited: new Set
+  };
+  const locRegex = /<loc>([^<]+)<\/loc>/g;
+  const isXmlSitemap = (url) => url.endsWith(".xml") || url.toLowerCase().includes("sitemap");
+  const processSitemap = async (sitemapUrl, depth = 0) => {
+    if (depth > maxDepth || result.visited.has(sitemapUrl)) {
+      return;
+    }
+    result.visited.add(sitemapUrl);
+    try {
+      const controller = createTimeoutController(timeout);
+      const response = await fetch(sitemapUrl, {
+        headers: {
+          "User-Agent": "SitemapCrawler/1.0"
+        },
+        signal: controller.signal
+      });
+      if (!response.ok)
+        throw new Error(`HTTP error! status: ${response.status}`);
+      const data = await response.text();
+      const matches = [...data.matchAll(locRegex)].map((match) => match[1].trim()).filter((link) => {
+        if (filterIndexes && isXmlSitemap(link)) {
+          return link.includes(filterIndexes);
+        }
+        return true;
+      });
+      for (const link of matches) {
+        if (isXmlSitemap(link)) {
+          queue.add(() => processSitemap(link, depth + 1));
+        } else {
+          result.links.add(link);
+        }
+      }
+    } catch (error) {
+      console.warn(`Failed to process sitemap ${sitemapUrl}:`, error instanceof Error ? error.message : "Unknown error");
+    }
+  };
+  await Promise.all(sitemapUrls.map((sitemapUrl) => queue.add(() => processSitemap(sitemapUrl))));
+  await queue.onIdle();
+  return [...result.links];
+};
+
 // src/typedswitch/index.ts
 function runSwitch(value, keyOrCases, casesOrDefault, defaultCase) {
   let key;
@@ -1640,6 +1784,8 @@ export {
   logBanner,
   linearRegressionTrend,
   keyBy,
+  jwtVerify2 as jwtVerify,
+  jwtSign,
   jsonToZodSchemaMapper,
   isSuccess,
   isFailure,
@@ -1649,16 +1795,19 @@ export {
   getUniqueValues,
   getPreviousReportPeriod,
   getHeatmapCellStyle,
+  getDomainSitemap,
   getDomainFaviconUrl,
   generateId,
   formatPeriodLabel,
   findArrayDifferenceByKey,
   extractNumber,
+  decompressString,
   createZId,
   createResolveColorsByKeys,
   createCoolLogger,
   createApiWrapper,
   createApiClient,
+  compressString,
   compact,
   colorize,
   chunkArray,

package/dist/secrets/index.d.ts

@@ -0,0 +1,27 @@
+export type SecretEnvironment = 'dev' | 'staging' | 'prod';
+export type DefineSecretSetOptions<SecretKey extends string> = {
+    readonly projectId: string;
+    readonly siteUrl?: string;
+    readonly environment?: SecretEnvironment | (() => SecretEnvironment);
+    readonly clientIdEnvKey?: string;
+    readonly clientSecretEnvKey?: string;
+    readonly loader?: SecretSetLoader<SecretKey>;
+    readonly getLocalIp?: () => string;
+};
+export type SecretSetLoaderContext<SecretKey extends string> = {
+    readonly keys: readonly SecretKey[];
+    readonly projectId: string;
+    readonly environment: SecretEnvironment;
+    readonly siteUrl: string;
+    readonly clientIdEnvKey: string;
+    readonly clientSecretEnvKey: string;
+};
+export type SecretSetLoader<SecretKey extends string> = (context: SecretSetLoaderContext<SecretKey>) => Promise<Partial<Record<SecretKey, string>>>;
+export type SecretSet<SecretKey extends string> = {
+    secret: (key: SecretKey) => string;
+    secrets: () => Record<SecretKey, string>;
+    reload: () => Promise<SecretSet<SecretKey>>;
+};
+export * from './vite';
+export declare function getSecretEnvironment(): SecretEnvironment;
+export declare function defineSecretSet<const SecretKeys extends readonly string[]>(keys: SecretKeys, options: DefineSecretSetOptions<SecretKeys[number]>): Promise<SecretSet<SecretKeys[number]>>;

package/dist/secrets/vite.d.ts

@@ -0,0 +1,9 @@
+import type { SecretSet } from '.';
+export type ViteSecretSetPlugin = {
+    name: string;
+    config: () => {
+        define: Record<string, string>;
+    };
+};
+export declare function getViteDefine<SecretKey extends string>(secretSet: SecretSet<SecretKey>): Record<string, string>;
+export declare function viteSecretSetPlugin<SecretKey extends string>(secretSet: SecretSet<SecretKey>): ViteSecretSetPlugin;

package/dist/src/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/src/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
+};