kayto_ts 0.1.0

package/src/types.ts

@@ -0,0 +1,95 @@
+export type EndpointsMap = {
+  get: Record<PropertyKey, unknown>;
+  post: Record<PropertyKey, unknown>;
+  put: Record<PropertyKey, unknown>;
+  patch: Record<PropertyKey, unknown>;
+  delete: Record<PropertyKey, unknown>;
+};
+
+export type EndpointOf<
+  Endpoints extends EndpointsMap,
+  Method extends keyof EndpointsMap,
+  Path extends keyof EndpointsMap[Method],
+> = Endpoints[Method][Path];
+
+export type EndpointParams<E> = E extends { params: infer P } ? P : never;
+export type EndpointBody<E> = E extends { body: infer B } ? B : never;
+
+export type ErrorKind =
+  | "network"
+  | "timeout"
+  | "aborted"
+  | "http"
+  | "parse"
+  | "hook";
+
+export type ClientError = {
+  kind: ErrorKind;
+  message: string;
+  cause?: unknown;
+  status?: number;
+};
+
+export type FetchResult<R, E = ClientError> =
+  | { ok: true; result: R; response: Response }
+  | { ok: false; error: E; response?: Response };
+
+export type Result<R, E = string> =
+  | { ok: true; result: R }
+  | { ok: false; error: E };
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type RequestOptions = {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  headers?: RequestInit["headers"];
+};
+
+export type RequestInput<E> = RequestOptions
+  & ([EndpointParams<E>] extends [never] ? {} : { params?: EndpointParams<E> })
+  & ([EndpointBody<E>] extends [never] ? {} : { body: EndpointBody<E> });
+
+export type RequestArgs<E> = [EndpointBody<E>] extends [never]
+  ? [input?: RequestInput<E>]
+  : [input: RequestInput<E>];
+
+export type Api<Endpoints extends EndpointsMap> = {
+  [Method in keyof EndpointsMap]: <
+    Path extends Extract<keyof Endpoints[Method], string>,
+  >(
+    path: Path,
+    ...args: RequestArgs<EndpointOf<Endpoints, Method, Path>>
+  ) => Promise<FetchResult<EndpointOf<Endpoints, Method, Path>>>;
+};
+
+export type RequestHookContext = {
+  method: keyof EndpointsMap;
+  path: string;
+  init: RequestInit;
+};
+
+export type ResponseHookContext = {
+  method: keyof EndpointsMap;
+  path: string;
+  response: Response;
+  durationMs: number;
+};
+
+export type ResponseInterceptorContext = {
+  method: keyof EndpointsMap;
+  path: string;
+  response: Response;
+};
+
+export type ClientHooks = {
+  onRequest?: (context: RequestHookContext) => MaybePromise<void>;
+  onResponse?: (context: ResponseHookContext) => MaybePromise<void>;
+  responseInterceptor?: (
+    context: ResponseInterceptorContext,
+  ) => MaybePromise<Response>;
+};
+
+export type ClientConfig = ClientHooks & {
+  baseUrl?: string;
+};

package/src/utils.ts

@@ -0,0 +1,201 @@
+import { type ClientError, type ErrorKind, type RequestInput, type RequestOptions, type Result } from "./types";
+
+export const HTTP_METHOD = {
+  get: "GET",
+  post: "POST",
+  put: "PUT",
+  patch: "PATCH",
+  delete: "DELETE",
+} as const;
+
+export function makeClientError(
+  kind: ErrorKind,
+  message: string,
+  cause?: unknown,
+  status?: number,
+): ClientError {
+  return { kind, message, cause, status };
+}
+
+export function createFetchSignal(options: RequestOptions): {
+  signal?: AbortSignal;
+  cleanup: () => void;
+  didTimeout: () => boolean;
+} {
+  const { signal, timeoutMs } = options;
+
+  if (timeoutMs == null) {
+    return { signal, cleanup: () => {}, didTimeout: () => false };
+  }
+
+  let timedOut = false;
+  const controller = new AbortController();
+  const onAbort = () => {
+    controller.abort(
+      signal?.reason ?? new DOMException("The operation was aborted", "AbortError"),
+    );
+  };
+
+  if (signal?.aborted) {
+    onAbort();
+  } else if (signal) {
+    signal.addEventListener("abort", onAbort, { once: true });
+  }
+
+  const timeoutId = setTimeout(() => {
+    timedOut = true;
+    controller.abort(
+      new DOMException(`Timed out after ${timeoutMs}ms`, "TimeoutError"),
+    );
+  }, timeoutMs);
+
+  const cleanup = () => {
+    clearTimeout(timeoutId);
+
+    if (signal) {
+      signal.removeEventListener("abort", onAbort);
+    }
+  };
+
+  return { signal: controller.signal, cleanup, didTimeout: () => timedOut };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isAbsoluteUrl(path: string): boolean {
+  return /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(path) || path.startsWith("//");
+}
+
+function appendQueryToUrl(path: string, query: Record<string, unknown>): string {
+  const absolute = isAbsoluteUrl(path);
+  const url = absolute ? new URL(path) : new URL(path, "http://localhost");
+
+  for (const [key, value] of Object.entries(query)) {
+    if (value == null) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item != null) {
+          url.searchParams.append(key, String(item));
+        }
+      }
+
+      continue;
+    }
+
+    url.searchParams.set(key, String(value));
+  }
+
+  if (absolute) {
+    return url.toString();
+  }
+
+  return `${url.pathname}${url.search}`;
+}
+
+export function buildPath(path: string, params: unknown): string {
+  if (!isRecord(params)) {
+    return path;
+  }
+
+  let nextPath = path;
+
+  if (isRecord(params.path)) {
+    for (const [key, value] of Object.entries(params.path)) {
+      if (value != null) {
+        nextPath = nextPath.replaceAll(
+          "{" + key + "}",
+          encodeURIComponent(String(value)),
+        );
+      }
+    }
+  }
+
+  if (isRecord(params.query)) {
+    return appendQueryToUrl(nextPath, params.query);
+  }
+
+  return nextPath;
+}
+
+export function resolveRequestUrl(path: string, baseUrl?: string): string {
+  if (!baseUrl || isAbsoluteUrl(path)) {
+    return path;
+  }
+
+  return new URL(path, baseUrl).toString();
+}
+
+function isRawBody(body: unknown): body is NonNullable<RequestInit["body"]> {
+  return (
+    typeof body === "string"
+    || body instanceof Blob
+    || body instanceof FormData
+    || body instanceof URLSearchParams
+    || body instanceof ArrayBuffer
+    || ArrayBuffer.isView(body)
+    || body instanceof ReadableStream
+  );
+}
+
+export function createBodyAndHeaders(input: RequestInput<unknown>): {
+  body?: NonNullable<RequestInit["body"]>;
+  headers: Headers;
+} {
+  const headers = new Headers(input.headers);
+  const body = "body" in input ? (input as { body?: unknown }).body : undefined;
+
+  if (body == null) {
+    return { body: undefined, headers };
+  }
+
+  if (isRawBody(body)) {
+    return { body, headers };
+  }
+
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+
+  return { body: JSON.stringify(body), headers };
+}
+
+function isJsonContentType(contentType: string): boolean {
+  return (
+    contentType.includes("application/json")
+    || contentType.includes("application/problem+json")
+    || contentType.includes("+json")
+  );
+}
+
+function isTextContentType(contentType: string): boolean {
+  return contentType.startsWith("text/");
+}
+
+export async function safeResponseBody(
+  response: Response,
+): Promise<Result<unknown, unknown>> {
+  const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+
+  if (response.status === 204 || response.status === 205 || response.status === 304) {
+    return { ok: true, result: null };
+  }
+
+  try {
+    if (isJsonContentType(contentType)) {
+      return { ok: true, result: await response.json() };
+    }
+
+    if (isTextContentType(contentType)) {
+      return { ok: true, result: await response.text() };
+    }
+
+    return { ok: true, result: await response.blob() };
+  } catch (err) {
+    return { ok: false, error: err };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}