@geekmidas/client 0.0.1 → 0.1.0

package/src/endpoint-hooks.ts

@@ -0,0 +1,203 @@
+import type {
+  QueryClient,
+  UseMutationOptions,
+  UseQueryOptions,
+} from '@tanstack/react-query';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import type {
+  ExtractEndpointResponse,
+  FilteredRequestConfig,
+  IsConfigRequired,
+  MutationEndpoint,
+  QueryEndpoint,
+  TypedApiFunction,
+} from './types';
+
+/**
+ * Build query key from endpoint and config
+ */
+function buildQueryKey<Paths, T extends QueryEndpoint<Paths>>(
+  endpoint: T,
+  config?: FilteredRequestConfig<Paths, T>,
+): unknown[] {
+  const key: unknown[] = [endpoint];
+
+  if (config && 'params' in config && config.params) {
+    key.push({ params: config.params });
+  }
+
+  if (config && 'query' in config && config.query) {
+    key.push({ query: config.query });
+  }
+
+  return key;
+}
+
+/**
+ * Options for creating endpoint-based hooks
+ */
+export interface CreateEndpointHooksOptions {
+  queryClient?: QueryClient;
+}
+
+/**
+ * Hook options type that conditionally requires config
+ */
+type UseQueryArgs<Paths, T extends QueryEndpoint<Paths>> = IsConfigRequired<
+  Paths,
+  T
+> extends true
+  ? [
+      config: FilteredRequestConfig<Paths, T>,
+      options?: Omit<
+        UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
+        'queryKey' | 'queryFn'
+      >,
+    ]
+  : [
+      config?: FilteredRequestConfig<Paths, T>,
+      options?: Omit<
+        UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
+        'queryKey' | 'queryFn'
+      >,
+    ];
+
+/**
+ * Endpoint-based React Query hooks
+ */
+export interface EndpointHooks<Paths> {
+  /**
+   * Use query hook for GET endpoints.
+   * Config is required when endpoint has path params.
+   */
+  useQuery: <T extends QueryEndpoint<Paths>>(
+    endpoint: T,
+    ...args: UseQueryArgs<Paths, T>
+  ) => ReturnType<typeof useQuery<ExtractEndpointResponse<Paths, T>, Error>>;
+
+  /**
+   * Use mutation hook for POST, PUT, PATCH, DELETE endpoints.
+   * Config with params/body is passed to mutate().
+   */
+  useMutation: <T extends MutationEndpoint<Paths>>(
+    endpoint: T,
+    options?: Omit<
+      UseMutationOptions<
+        ExtractEndpointResponse<Paths, T>,
+        Error,
+        FilteredRequestConfig<Paths, T>
+      >,
+      'mutationFn'
+    >,
+  ) => ReturnType<
+    typeof useMutation<
+      ExtractEndpointResponse<Paths, T>,
+      Error,
+      FilteredRequestConfig<Paths, T>
+    >
+  >;
+
+  /**
+   * Build a query key for manual cache operations
+   */
+  buildQueryKey: <T extends QueryEndpoint<Paths>>(
+    endpoint: T,
+    config?: FilteredRequestConfig<Paths, T>,
+  ) => unknown[];
+}
+
+/**
+ * Create endpoint-based React Query hooks from a typed fetcher.
+ *
+ * @example
+ * ```typescript
+ * const fetcher = createAuthAwareFetcher<paths>({ ... });
+ * const hooks = createEndpointHooks<paths>(fetcher);
+ *
+ * // In a component
+ * const { data } = hooks.useQuery('GET /users/{id}', { params: { id: '123' } });
+ *
+ * const mutation = hooks.useMutation('POST /users');
+ * await mutation.mutateAsync({ body: { name: 'John' } });
+ * ```
+ */
+export function createEndpointHooks<Paths>(
+  fetcher: TypedApiFunction<Paths>,
+  options: CreateEndpointHooksOptions = {},
+): EndpointHooks<Paths> {
+  return {
+    useQuery: <T extends QueryEndpoint<Paths>>(
+      endpoint: T,
+      ...args: UseQueryArgs<Paths, T>
+    ) => {
+      // Parse args - config is first, options is second
+      const [config, queryOptions] = args as [
+        FilteredRequestConfig<Paths, T> | undefined,
+        (
+          | Omit<
+              UseQueryOptions<ExtractEndpointResponse<Paths, T>, Error>,
+              'queryKey' | 'queryFn'
+            >
+          | undefined
+        ),
+      ];
+
+      const queryKey = buildQueryKey(endpoint, config);
+
+      const memoizedOptions = useMemo(
+        () => ({
+          queryKey,
+          queryFn: () =>
+            fetcher(
+              endpoint as Parameters<typeof fetcher>[0],
+              config as Parameters<typeof fetcher>[1],
+            ),
+          ...queryOptions,
+        }),
+        [
+          queryKey.join(','),
+          endpoint,
+          JSON.stringify(config),
+          JSON.stringify(queryOptions),
+        ],
+      );
+
+      return useQuery<ExtractEndpointResponse<Paths, T>, Error>(
+        memoizedOptions,
+      );
+    },
+
+    useMutation: <T extends MutationEndpoint<Paths>>(
+      endpoint: T,
+      mutationOptions?: Omit<
+        UseMutationOptions<
+          ExtractEndpointResponse<Paths, T>,
+          Error,
+          FilteredRequestConfig<Paths, T>
+        >,
+        'mutationFn'
+      >,
+    ) => {
+      const memoizedOptions = useMemo(
+        () => ({
+          mutationFn: (config: FilteredRequestConfig<Paths, T>) =>
+            fetcher(
+              endpoint as Parameters<typeof fetcher>[0],
+              config as Parameters<typeof fetcher>[1],
+            ),
+          ...mutationOptions,
+        }),
+        [endpoint, JSON.stringify(mutationOptions)],
+      );
+
+      return useMutation<
+        ExtractEndpointResponse<Paths, T>,
+        Error,
+        FilteredRequestConfig<Paths, T>
+      >(memoizedOptions);
+    },
+
+    buildQueryKey,
+  };
+}

package/src/infer.ts

@@ -0,0 +1,161 @@
+import type {
+  Endpoint,
+  EndpointSchemas,
+} from '@geekmidas/constructs/endpoints';
+import type { HttpMethod } from '@geekmidas/constructs/types';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * Infers path parameters from a route string as an object
+ * @example '/users/{id}/posts/{postId}' -> { id: string, postId: string }
+ */
+type InferPathParams<TRoute extends string> =
+  TRoute extends `${string}{${infer Param}}${infer Rest}`
+    ? { [K in Param]: string } & InferPathParams<Rest>
+    : {};
+
+/**
+ * Converts an HTTP method to lowercase for TypedFetcher compatibility
+ */
+type LowercaseMethod<T extends HttpMethod> = Lowercase<T>;
+
+/**
+ * Infers route-level parameters (path params)
+ */
+type InferRouteParameters<TRoute extends string> =
+  InferPathParams<TRoute> extends Record<string, never>
+    ? {}
+    : {
+        parameters: {
+          path: InferPathParams<TRoute>;
+        };
+      };
+
+/**
+ * Infers operation-level parameters (query params)
+ */
+type InferOperationParameters<TInput extends EndpointSchemas> = TInput extends {
+  query: infer Q;
+}
+  ? {
+      parameters: {
+        query: InferStandardSchema<Q>;
+      };
+    }
+  : {};
+
+/**
+ * Infers the operation object compatible with TypedFetcher
+ */
+type InferOperation<
+  TInput extends EndpointSchemas,
+  TOutput extends StandardSchemaV1 | undefined,
+> = InferOperationParameters<TInput> & {
+  requestBody?: TInput extends { body: infer B }
+    ? {
+        content: {
+          'application/json': InferStandardSchema<B>;
+        };
+      }
+    : never;
+  responses: {
+    200: {
+      content: TOutput extends StandardSchemaV1
+        ? {
+            'application/json': InferStandardSchema<TOutput>;
+          }
+        : never;
+    };
+  };
+};
+
+/**
+ * Infers the TypedFetcher-compatible paths structure from a single endpoint
+ *
+ * This generates a structure compatible with @geekmidas/client TypedFetcher,
+ * allowing you to create a typed client directly from endpoint definitions
+ * without needing OpenAPI JSON + codegen.
+ *
+ * @example
+ * ```typescript
+ * import { e } from '@geekmidas/constructs';
+ * import { createTypedFetcher, type InferOpenApiFromEndpoint } from '@geekmidas/client';
+ * import { z } from 'zod';
+ *
+ * const endpoint = e
+ *   .get('/users/{id}')
+ *   .params(z.object({ id: z.string() }))
+ *   .output(z.object({ id: z.string(), name: z.string() }))
+ *   .handle(async ({ params }) => ({ id: params.id, name: 'John' }));
+ *
+ * type Paths = InferOpenApiFromEndpoint<typeof endpoint>['paths'];
+ * const client = createTypedFetcher<Paths>({ baseURL: 'http://localhost:3000' });
+ * const user = await client('GET /users/{id}', { params: { id: '123' } });
+ * ```
+ */
+export type InferOpenApiFromEndpoint<T> = T extends Endpoint<
+  infer TRoute,
+  infer TMethod,
+  infer TInput,
+  infer TOutput,
+  any,
+  any,
+  any
+>
+  ? {
+      paths: {
+        [K in TRoute]: InferRouteParameters<TRoute> & {
+          [M in LowercaseMethod<TMethod>]: InferOperation<TInput, TOutput>;
+        };
+      };
+    }
+  : never;
+
+/**
+ * Infers TypedFetcher-compatible paths structure from multiple endpoints
+ *
+ * Merges multiple endpoint definitions into a single paths object that can be
+ * used with @geekmidas/client TypedFetcher for fully type-safe API calls.
+ *
+ * @example
+ * ```typescript
+ * import { e } from '@geekmidas/constructs';
+ * import { createTypedFetcher, type InferOpenApi } from '@geekmidas/client';
+ * import { z } from 'zod';
+ *
+ * // Define endpoints
+ * const getUserEndpoint = e
+ *   .get('/users/{id}')
+ *   .params(z.object({ id: z.string() }))
+ *   .output(z.object({ id: z.string(), name: z.string() }))
+ *   .handle(async ({ params }) => ({ id: params.id, name: 'John' }));
+ *
+ * const createUserEndpoint = e
+ *   .post('/users')
+ *   .body(z.object({ name: z.string() }))
+ *   .output(z.object({ id: z.string(), name: z.string() }))
+ *   .handle(async ({ body }) => ({ id: '123', name: body.name }));
+ *
+ * // Export for client
+ * export const endpoints = [getUserEndpoint, createUserEndpoint] as const;
+ * export type Paths = InferOpenApi<typeof endpoints>['paths'];
+ *
+ * // Client usage
+ * import type { Paths } from './endpoints';
+ * const client = createTypedFetcher<Paths>({ baseURL: 'http://localhost:3000' });
+ *
+ * const user = await client('GET /users/{id}', { params: { id: '123' } });
+ * const newUser = await client('POST /users', { body: { name: 'Jane' } });
+ * ```
+ */
+export type InferOpenApi<TEndpoints extends readonly any[]> =
+  TEndpoints extends readonly [infer First, ...infer Rest]
+    ? InferOpenApiFromEndpoint<First> extends { paths: infer P1 }
+      ? Rest extends []
+        ? { paths: P1 }
+        : InferOpenApi<Rest> extends { paths: infer P2 }
+          ? { paths: P1 & P2 }
+          : { paths: P1 }
+      : InferOpenApi<Rest>
+    : { paths: {} };

package/src/types.ts

@@ -130,14 +130,75 @@ export type ExtractEndpointConfig<
     : never
   : never;
 
-export type FilteredRequestConfig<Paths, T extends EndpointString> = {
-  [K in keyof ExtractEndpointConfig<Paths, T> as ExtractEndpointConfig<
-    Paths,
-    T
-  >[K] extends never | undefined
-    ? never
-    : K]: ExtractEndpointConfig<Paths, T>[K];
-};
+/**
+ * Build a request config type where:
+ * - `params` is required if the endpoint has path parameters
+ * - `body` is required if the endpoint has a request body
+ * - `query` and `headers` are always optional
+ */
+export type FilteredRequestConfig<
+  Paths,
+  T extends EndpointString,
+> = T extends `${infer Method} ${infer Route}`
+  ? Route extends OpenAPIRoutes<Paths>
+    ? Lowercase<Method> extends ExtractMethod<Paths, Route>
+      ? BuildRequestConfig<
+          ExtractPathParams<Paths, Route>,
+          ExtractQueryParams<Paths, Route, Lowercase<Method>>,
+          ExtractRequestBody<Paths, Route, Lowercase<Method>>
+        >
+      : never
+    : never
+  : never;
+
+/**
+ * Helper to build request config with correct required/optional fields
+ */
+type BuildRequestConfig<TParams, TQuery, TBody> = SimplifyIntersection<
+  // params: required if not never
+  (TParams extends never ? {} : { params: TParams }) &
+    // body: required if not never
+    (TBody extends never ? {} : { body: TBody }) &
+    // query: optional if not never
+    (TQuery extends never ? {} : { query?: TQuery }) & {
+      // headers: always optional
+      headers?: Record<string, string>;
+    }
+>;
+
+/**
+ * Simplify intersection types for better IDE display
+ */
+type SimplifyIntersection<T> = { [K in keyof T]: T[K] };
+
+/**
+ * Check if the config object is required (has any required fields)
+ */
+export type IsConfigRequired<
+  Paths,
+  T extends EndpointString,
+> = T extends `${infer Method} ${infer Route}`
+  ? Route extends OpenAPIRoutes<Paths>
+    ? Lowercase<Method> extends ExtractMethod<Paths, Route>
+      ? ExtractPathParams<Paths, Route> extends never
+        ? ExtractRequestBody<Paths, Route, Lowercase<Method>> extends never
+          ? false
+          : true
+        : true
+      : false
+    : false
+  : false;
+
+/**
+ * Typed function signature for the API client.
+ * Config is required when endpoint has path params or body.
+ */
+export type TypedApiFunction<Paths> = <T extends TypedEndpoint<Paths>>(
+  endpoint: T,
+  ...args: IsConfigRequired<Paths, T> extends true
+    ? [config: FilteredRequestConfig<Paths, T>]
+    : [config?: FilteredRequestConfig<Paths, T>]
+) => Promise<ExtractEndpointResponse<Paths, T>>;
 
 export interface FetcherOptions {
   baseURL?: string;