@geekmidas/client 0.0.1

package/dist/types.d.cts

@@ -0,0 +1,2 @@
+import { EndpointString, ExtractEndpointConfig, ExtractEndpointResponse, ExtractMethod, ExtractPathParams, ExtractQueryParams, ExtractRequestBody, ExtractResponse, FetcherOptions, FilterEndpointByMethod, FilteredRequestConfig, MutationEndpoint, OpenAPIRoutes, ParseEndpoint, QueryEndpoint, RequestConfig, TypedEndpoint, ValidEndpoint } from "./types-csACmD6U.cjs";
+export { EndpointString, ExtractEndpointConfig, ExtractEndpointResponse, ExtractMethod, ExtractPathParams, ExtractQueryParams, ExtractRequestBody, ExtractResponse, FetcherOptions, FilterEndpointByMethod, FilteredRequestConfig, MutationEndpoint, OpenAPIRoutes, ParseEndpoint, QueryEndpoint, RequestConfig, TypedEndpoint, ValidEndpoint };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { EndpointString, ExtractEndpointConfig, ExtractEndpointResponse, ExtractMethod, ExtractPathParams, ExtractQueryParams, ExtractRequestBody, ExtractResponse, FetcherOptions, FilterEndpointByMethod, FilteredRequestConfig, MutationEndpoint, OpenAPIRoutes, ParseEndpoint, QueryEndpoint, RequestConfig, TypedEndpoint, ValidEndpoint } from "./types-tMp85Lt_.mjs";
+export { EndpointString, ExtractEndpointConfig, ExtractEndpointResponse, ExtractMethod, ExtractPathParams, ExtractQueryParams, ExtractRequestBody, ExtractResponse, FetcherOptions, FilterEndpointByMethod, FilteredRequestConfig, MutationEndpoint, OpenAPIRoutes, ParseEndpoint, QueryEndpoint, RequestConfig, TypedEndpoint, ValidEndpoint };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@geekmidas/client",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./fetcher": {
+      "types": "./dist/fetcher.d.ts",
+      "import": "./dist/fetcher.mjs",
+      "require": "./dist/fetcher.cjs"
+    },
+    "./react-query": {
+      "types": "./dist/react-query.d.ts",
+      "import": "./dist/react-query.mjs",
+      "require": "./dist/react-query.cjs"
+    },
+    "./openapi": {
+      "types": "./dist/openapi-hooks.d.ts",
+      "import": "./dist/openapi-hooks.mjs",
+      "require": "./dist/openapi-hooks.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.mjs",
+      "require": "./dist/types.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geekmidas/toolbox.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "~6.6.3",
+    "@testing-library/dom": "~10.4.0",
+    "@testing-library/react": "~16.3.0",
+    "@testing-library/react-hooks": "~8.0.1",
+    "@types/react": "~19.1.8",
+    "@types/react-dom": "~19.1.6",
+    "jsdom": "~26.1.0",
+    "msw": "~2.10.3"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "scripts": {
+    "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"
+  }
+}

package/src/__tests__/fetcher.spec.ts

@@ -0,0 +1,409 @@
+import { describe, expect, it, vi } from 'vitest';
+import { type FetchFn, createTypedFetcher } from '../fetcher';
+import type { paths } from '../openapi-types';
+import './setup';
+
+describe('TypedFetcher', () => {
+  it('should make GET request to fetch users', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('GET /users');
+
+    expect(result).toEqual({
+      users: [
+        { id: '1', name: 'John Doe', email: 'john@example.com' },
+        { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+      ],
+    });
+  });
+
+  it('should make GET request with path params', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('GET /users/{id}', { params: { id: '123' } });
+
+    expect(result).toEqual({
+      id: '123',
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  });
+
+  it('should make POST request with body', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const requestBody = { name: 'Jane Doe', email: 'jane@example.com' };
+    const result = await client('POST /users', { body: requestBody });
+
+    expect(result).toEqual({
+      id: '123',
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+    });
+  });
+
+  it('should make PUT request with path params and body', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('PUT /users/{id}', {
+      params: { id: '456' },
+      body: { name: 'Updated Name' },
+    });
+
+    expect(result).toEqual({
+      id: '456',
+      name: 'Updated Name',
+      email: 'john@example.com',
+    });
+  });
+
+  it('should handle DELETE requests', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    // DELETE returns no content (204)
+    const result = await client('DELETE /users/{id}', {
+      params: { id: '123' },
+    });
+
+    // For 204 responses, result should be undefined or empty
+    expect(result).toBeUndefined();
+  });
+
+  it('should handle query parameters', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('GET /posts', {
+      query: { page: 2, limit: 5, sort: 'desc' },
+    });
+
+    expect(result.posts).toHaveLength(5);
+  });
+
+  it('should handle array query parameters', async () => {
+    // Mock fetch to capture the request URL
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: async () => ({ items: ['a', 'b', 'c'] }),
+    });
+
+    const client = createTypedFetcher<any>({
+      baseURL: 'https://api.example.com',
+      fetch: mockFetch,
+    });
+
+    await client('GET /search', {
+      query: { tags: ['nodejs', 'typescript', 'javascript'] as any },
+    });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/search?tags=nodejs&tags=typescript&tags=javascript',
+      expect.any(Object),
+    );
+  });
+
+  it('should handle object query parameters with dot notation', async () => {
+    // Mock fetch to capture the request URL
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: async () => ({ results: [] }),
+    });
+
+    const client = createTypedFetcher<any>({
+      baseURL: 'https://api.example.com',
+      fetch: mockFetch,
+    });
+
+    await client('GET /products', {
+      query: {
+        filter: {
+          category: 'electronics',
+          minPrice: 100,
+          maxPrice: 500,
+        },
+        sort: 'price',
+      } as any,
+    });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/products?filter.category=electronics&filter.minPrice=100&filter.maxPrice=500&sort=price',
+      expect.any(Object),
+    );
+  });
+
+  it('should handle arrays within nested objects', async () => {
+    // Mock fetch to capture the request URL
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: new Headers({ 'content-type': 'application/json' }),
+      json: async () => ({ results: [] }),
+    });
+
+    const client = createTypedFetcher<any>({
+      baseURL: 'https://api.example.com',
+      fetch: mockFetch,
+    });
+
+    await client('GET /advanced-search', {
+      query: {
+        user: {
+          roles: ['admin', 'moderator', 'user'],
+          status: 'active',
+        },
+        settings: {
+          notifications: {
+            types: ['email', 'sms', 'push'],
+            enabled: true,
+          },
+        },
+      } as any,
+    });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/advanced-search?user.roles=admin&user.roles=moderator&user.roles=user&user.status=active&settings.notifications.types=email&settings.notifications.types=sms&settings.notifications.types=push&settings.notifications.enabled=true',
+      expect.any(Object),
+    );
+  });
+
+  it('should handle 404 errors', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    try {
+      await client('GET /users/{id}', {
+        params: { id: '404' },
+      });
+      expect.fail('Should have thrown an error');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Response);
+      const response = error as Response;
+      expect(response.status).toBe(404);
+      const data = await response.json();
+      expect(data.message).toBe('User not found');
+    }
+  });
+
+  it('should handle 500 errors', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    try {
+      await client('GET /error');
+      expect.fail('Should have thrown an error');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Response);
+      const response = error as Response;
+      expect(response.status).toBe(500);
+      const data = await response.json();
+      expect(data.message).toBe('Internal server error');
+    }
+  });
+
+  it('should apply request interceptor', async () => {
+    const onRequest = vi.fn((config) => ({
+      ...config,
+      headers: { ...config.headers, 'X-Custom-Header': 'test-value' },
+    }));
+
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      onRequest,
+    });
+
+    await client('GET /users/{id}', { params: { id: '123' } });
+
+    expect(onRequest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'GET',
+        headers: expect.any(Object),
+      }),
+    );
+  });
+
+  it('should apply response interceptor', async () => {
+    const onResponse = vi.fn((response) => response);
+
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      onResponse,
+    });
+
+    await client('GET /users/{id}', { params: { id: '123' } });
+
+    expect(onResponse).toHaveBeenCalledWith(expect.any(Response));
+  });
+
+  it('should apply error handler', async () => {
+    const onError = vi.fn();
+
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      onError,
+    });
+
+    await expect(
+      client('GET /users/{id}', { params: { id: '404' } }),
+    ).rejects.toThrow();
+
+    expect(onError).toHaveBeenCalledWith(expect.any(Response));
+  });
+
+  it('should merge default headers with request headers', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      headers: { Authorization: 'Bearer valid-token' },
+    });
+
+    const result = await client('GET /protected', {
+      headers: { 'X-Custom': 'value' },
+    });
+
+    expect(result).toEqual({ message: 'Protected data' });
+  });
+
+  it('should handle unauthorized requests', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      headers: { Authorization: 'Bearer broken-token' },
+    });
+
+    try {
+      await client('GET /protected');
+      expect.fail('Should have thrown an error');
+    } catch (error) {
+      expect(error).toBeInstanceOf(Response);
+      const response = error as Response;
+      expect(response.status).toBe(401);
+      const data = await response.json();
+      expect(data.message).toBe('Unauthorized');
+    }
+  });
+
+  it('should handle empty query parameters', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('GET /posts', {
+      query: { page: 1, sort: undefined as any },
+    });
+
+    expect(result.pagination.page).toBe(1);
+    expect(result.sort).toBe('asc'); // Default value when sort is undefined
+  });
+
+  it('should properly encode path parameters', async () => {
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+    });
+
+    const result = await client('GET /users/{id}', {
+      params: { id: 'user with spaces' },
+    });
+
+    // MSW decodes the URL parameters, so we get the original value back
+    expect(result).toEqual({
+      id: 'user with spaces',
+      name: 'John Doe',
+      email: 'john@example.com',
+    });
+  });
+
+  it('should correctly substitute multiple path parameters', async () => {
+    // Add a mock handler for this test
+    const mockFetch = vi.fn(async (url: string) => {
+      if (url === 'https://api.example.com/posts/123/comments/456') {
+        return new Response(
+          JSON.stringify({
+            postId: '123',
+            commentId: '456',
+            content: 'Test comment',
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      return new Response('Not found', { status: 404 });
+    }) as FetchFn;
+
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      fetch: mockFetch,
+    });
+
+    const result = await client(
+      'GET /posts/{postId}/comments/{commentId}' as any,
+      {
+        params: { postId: '123', commentId: '456' },
+      },
+    );
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/posts/123/comments/456',
+      expect.any(Object),
+    );
+    expect(result).toEqual({
+      postId: '123',
+      commentId: '456',
+      content: 'Test comment',
+    });
+  });
+
+  it('should URL encode special characters in path parameters', async () => {
+    // Mock fetch to verify the actual URL being called
+    const mockFetch = vi.fn(async (url: string) => {
+      if (
+        url ===
+        'https://api.example.com/users/user%20with%20spaces%2Fand%2Fslashes'
+      ) {
+        return new Response(
+          JSON.stringify({
+            id: 'user with spaces/and/slashes',
+            name: 'Test User',
+            email: 'test@example.com',
+          }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      return new Response('Not found', { status: 404 });
+    }) as typeof fetch;
+
+    const client = createTypedFetcher<paths>({
+      baseURL: 'https://api.example.com',
+      fetch: mockFetch,
+    });
+
+    const result = await client('GET /users/{id}', {
+      params: { id: 'user with spaces/and/slashes' },
+    });
+
+    // Verify the URL was properly encoded
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/users/user%20with%20spaces%2Fand%2Fslashes',
+      expect.any(Object),
+    );
+
+    expect(result).toEqual({
+      id: 'user with spaces/and/slashes',
+      name: 'Test User',
+      email: 'test@example.com',
+    });
+  });
+});

package/src/__tests__/method-restrictions.spec.tsx

@@ -0,0 +1,227 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { renderHook } from '@testing-library/react';
+// biome-ignore lint/style/useImportType: <explanation>
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import type { paths } from '../openapi-types';
+import { createTypedQueryClient } from '../react-query';
+import './setup';
+
+describe('Method Restrictions', () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,
+      },
+    },
+  });
+
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  describe('useQuery', () => {
+    it('should accept GET endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - GET endpoints are allowed
+      const { result } = renderHook(() => typedClient.useQuery('GET /users'), {
+        wrapper,
+      });
+
+      expect(result.current).toBeDefined();
+    });
+
+    it('should accept GET endpoints with parameters', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - GET endpoints with params are allowed
+      const { result } = renderHook(
+        () =>
+          typedClient.useQuery('GET /users/{id}', {
+            params: { id: '123' },
+          }),
+        { wrapper },
+      );
+
+      expect(result.current).toBeDefined();
+    });
+
+    it('should accept GET endpoints with query parameters', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - GET endpoints with query params are allowed
+      const { result } = renderHook(
+        () =>
+          typedClient.useQuery('GET /posts', {
+            query: { page: 1, limit: 10 },
+          }),
+        { wrapper },
+      );
+
+      expect(result.current).toBeDefined();
+    });
+
+    // The following tests would fail TypeScript compilation if uncommented
+    // They are left here as documentation of what should NOT work
+
+    /*
+    it('should NOT accept POST endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // @ts-expect-error - POST endpoints should not be allowed in useQuery
+      const { result } = renderHook(
+        () => typedClient.useQuery('POST /users'),
+        { wrapper },
+      );
+    });
+
+    it('should NOT accept PUT endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // @ts-expect-error - PUT endpoints should not be allowed in useQuery
+      const { result } = renderHook(
+        () => typedClient.useQuery('PUT /users/{id}', { params: { id: '123' } }),
+        { wrapper },
+      );
+    });
+
+    it('should NOT accept DELETE endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // @ts-expect-error - DELETE endpoints should not be allowed in useQuery
+      const { result } = renderHook(
+        () => typedClient.useQuery('DELETE /users/{id}', { params: { id: '123' } }),
+        { wrapper },
+      );
+    });
+    */
+  });
+
+  describe('useMutation', () => {
+    it('should accept POST endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - POST endpoints are allowed
+      const { result } = renderHook(
+        () => typedClient.useMutation('POST /users'),
+        { wrapper },
+      );
+
+      expect(result.current).toBeDefined();
+    });
+
+    it('should accept PUT endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - PUT endpoints are allowed
+      const { result } = renderHook(
+        () => typedClient.useMutation('PUT /users/{id}'),
+        { wrapper },
+      );
+
+      expect(result.current).toBeDefined();
+    });
+
+    it('should accept DELETE endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // This should compile - DELETE endpoints are allowed
+      const { result } = renderHook(
+        () => typedClient.useMutation('DELETE /users/{id}'),
+        { wrapper },
+      );
+
+      expect(result.current).toBeDefined();
+    });
+
+    // The following test would fail TypeScript compilation if uncommented
+    // It is left here as documentation of what should NOT work
+
+    /*
+    it('should NOT accept GET endpoints', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      // @ts-expect-error - GET endpoints should not be allowed in useMutation
+      const { result } = renderHook(
+        () => typedClient.useMutation('GET /users'),
+        { wrapper },
+      );
+    });
+    */
+  });
+
+  describe('Type inference', () => {
+    it('should correctly infer response types for GET requests', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      const { result } = renderHook(() => typedClient.useQuery('GET /users'), {
+        wrapper,
+      });
+
+      // TypeScript should infer this type correctly
+      type ResponseType = typeof result.current.data;
+      type ExpectedType =
+        | { users: Array<{ id: string; name: string; email: string }> }
+        | undefined;
+
+      // This assertion validates that the types match at compile time
+      const _typeCheck: ResponseType extends ExpectedType ? true : false = true;
+      const _typeCheck2: ExpectedType extends ResponseType ? true : false =
+        true;
+
+      expect(_typeCheck).toBe(true);
+      expect(_typeCheck2).toBe(true);
+    });
+
+    it('should correctly infer response types for POST requests', () => {
+      const typedClient = createTypedQueryClient<paths>({
+        baseURL: 'https://api.example.com',
+      });
+
+      const { result } = renderHook(
+        () => typedClient.useMutation('POST /users'),
+        { wrapper },
+      );
+
+      // TypeScript should infer this type correctly
+      type ResponseType = typeof result.current.data;
+      type ExpectedType =
+        | { id: string; name: string; email: string }
+        | undefined;
+
+      // This assertion validates that the types match at compile time
+      const _typeCheck: ResponseType extends ExpectedType ? true : false = true;
+      const _typeCheck2: ExpectedType extends ResponseType ? true : false =
+        true;
+
+      expect(_typeCheck).toBe(true);
+      expect(_typeCheck2).toBe(true);
+    });
+  });
+});