hanzio 1.0.3 → 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

@@ -14,3 +14,4 @@ export * from './cool-console-log';
 export * from './jwt';
 export * from './gzip';
 export * from './sitemap';
+export * from './secrets';

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
+};