V4

.github/workflows/main.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        node: ["18.x", "20.x", "22.x"]
+        node: ['18.x', '20.x', '22.x', '24.x']
         os: [ubuntu-latest, macOS-latest]
 
     steps:

.gitignore

@@ -110,5 +110,6 @@ package/
 
 dist/*.ts
 dist/**/*.ts
+dist/**/*.mts
 !dist/*.map
 !dist/**/*.map

docs/examples/example-basic.ts

@@ -0,0 +1,27 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://example.com/api',
+  endpoints: {
+    getUser: {
+      url: '/user-details/:id',
+      method: 'GET',
+    },
+    getBooks: {
+      url: '/books/all',
+      method: 'GET',
+    },
+  },
+});
+
+async function main() {
+  // Basic GET request with path param
+  const { data: user } = await api.getUser({ urlPathParams: { id: 2 } });
+  console.log('User:', user);
+
+  // Basic GET request to fetch all books
+  const { data: books } = await api.getBooks();
+  console.log('Books:', books);
+}
+
+main();

docs/examples/example-custom-headers.ts

@@ -0,0 +1,24 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://api.example.com/',
+  headers: {
+    'Content-Type': 'application/json',
+    Authorization: 'Bearer YOUR_TOKEN',
+  },
+  endpoints: {
+    getProfile: {
+      url: '/profile/:id',
+    },
+  },
+});
+
+async function main() {
+  // GET request with custom headers and path param
+  const { data: profile } = await api.getProfile({
+    urlPathParams: { id: 123 },
+  });
+  console.log('Profile:', profile);
+}
+
+main();

docs/examples/example-error-strategy-defaultResponse.ts

@@ -0,0 +1,34 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://example.com/api',
+  // strategy: 'defaultResponse',
+  endpoints: {
+    sendMessage: {
+      method: 'post',
+      url: '/send-message/:postId',
+      // strategy: 'defaultResponse',
+    },
+  },
+});
+
+async function sendMessage() {
+  const { data, error } = await api.sendMessage({
+    body: { message: 'Text' },
+    urlPathParams: { postId: 1 },
+    strategy: 'defaultResponse',
+    defaultResponse: { status: 'failed', message: 'Default response' },
+    onError(error) {
+      console.error('API error:', error.message);
+    },
+  });
+
+  if (error) {
+    console.warn('Message failed to send, using default response:', data);
+    return;
+  }
+
+  console.log('Message sent successfully:', data);
+}
+
+sendMessage();

docs/examples/example-error-strategy-reject.ts

@@ -0,0 +1,27 @@
+import { createApiFetcher } from 'fetchff';
+import type { ResponseError } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://example.com/api',
+  endpoints: {
+    sendMessage: {
+      method: 'post',
+      url: '/send-message/:postId',
+      strategy: 'reject',
+    },
+  },
+});
+
+async function sendMessage() {
+  try {
+    await api.sendMessage({
+      body: { message: 'Text' },
+      urlPathParams: { postId: 1 },
+    });
+    console.log('Message sent successfully');
+  } catch (error) {
+    console.error('Message failed to send:', (error as ResponseError).message);
+  }
+}
+
+sendMessage();

docs/examples/example-error-strategy-silent.ts

@@ -0,0 +1,28 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  baseURL: 'https://example.com/api',
+  endpoints: {
+    sendMessage: {
+      method: 'post',
+      url: '/send-message/:postId',
+      // strategy: 'silent',
+    },
+  },
+});
+
+async function sendMessage() {
+  await api.sendMessage({
+    body: { message: 'Text' },
+    urlPathParams: { postId: 1 },
+    strategy: 'silent',
+    onError(error) {
+      console.error('Silent error logged:', error.message);
+    },
+  });
+
+  // Because of the strategy, if API call fails, it will never reach this point. Otherwise try/catch would need to be required.
+  console.log('Message sent successfully');
+}
+
+sendMessage();

docs/examples/example-error-strategy-softFail.ts

@@ -0,0 +1,30 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  apiUrl: 'https://example.com/api',
+  // You can set default strategy for all endpoints
+  strategy: 'softFail',
+  endpoints: {
+    sendMessage: {
+      method: 'post',
+      url: '/send-message/:postId',
+      // You can override strategy for particular endpoint (we set the same here for demonstration)
+      strategy: 'softFail',
+    },
+  },
+});
+
+async function sendMessage() {
+  const { data, error } = await api.sendMessage({
+    body: { message: 'Text' },
+    urlPathParams: { postId: 1 },
+  });
+
+  if (error) {
+    console.error('Request Error', error.message);
+  } else {
+    console.log('Message sent successfully:', data);
+  }
+}
+
+sendMessage();

docs/examples/example-request-chaining.ts

@@ -0,0 +1,32 @@
+import { createApiFetcher } from 'fetchff';
+
+const api = createApiFetcher({
+  baseURL: 'https://example.com/api',
+  endpoints: {
+    getUser: { url: '/user' },
+    createPost: { url: '/post', method: 'POST' },
+  },
+});
+
+interface PostData {
+  title: string;
+  content: string;
+}
+
+async function fetchUserAndCreatePost(userId: number, postData: PostData) {
+  // Fetch user data
+  const { data: userData } = await api.getUser({ params: { userId } });
+
+  // Create a new post with the fetched user data
+  return await api.createPost({
+    body: {
+      ...postData,
+      userId: userData.id,
+    },
+  });
+}
+
+// Example usage
+fetchUserAndCreatePost(1, { title: 'New Post', content: 'This is a new post.' })
+  .then((response) => console.log('Post created:', response))
+  .catch((error) => console.error('Error:', error));

docs/examples/example-typescript.ts

@@ -0,0 +1,51 @@
+import { createApiFetcher } from 'fetchff';
+import type { Endpoint } from 'fetchff';
+
+// Example endpoint interfaces
+type Book = { id: number; title: string; rating: number };
+type Books = { books: Book[]; totalResults: number };
+type BookQueryParams = { newBook?: boolean; category?: string };
+type BookPathParams = { bookId: number };
+
+const endpoints = {
+  fetchBooks: {
+    url: '/books',
+    method: 'GET' as const,
+  },
+  fetchBook: {
+    url: '/books/:bookId',
+    method: 'GET' as const,
+  },
+} as const;
+
+interface EndpointsList {
+  fetchBook: Endpoint<{
+    response: Book;
+    params: BookQueryParams;
+    urlPathParams: BookPathParams;
+  }>;
+  fetchBooks: Endpoint<{ response: Books; params: BookQueryParams }>;
+}
+
+const api = createApiFetcher<EndpointsList>({
+  baseURL: 'https://example.com/api',
+  endpoints,
+  strategy: 'softFail',
+});
+
+async function main() {
+  // Properly typed request with URL params
+  const { data: book } = await api.fetchBook({
+    params: { newBook: true },
+    urlPathParams: { bookId: 1 },
+  });
+  console.log('Book:', book);
+
+  // Generic type can be passed directly for additional type safety
+  const { data: books } = await api.fetchBooks<{ response: Books }>({
+    params: { category: 'fiction' },
+  });
+  console.log('Books:', books);
+}
+
+main();

jest.config.js

@@ -4,4 +4,14 @@ module.exports = {
   testEnvironment: 'node',
   workerThreads: true,
   coverageReporters: ['lcov', 'text', 'html'],
+  coveragePathIgnorePatterns: [
+    '/node_modules/',
+    '/test/utils/',
+    '/test/mocks/',
+    '/dist/',
+  ],
+  moduleNameMapper: {
+    '^fetchff$': '<rootDir>/src/index.ts',
+    '^fetchff/(.*)$': '<rootDir>/src/$1.ts',
+  },
 };