@navios/react-query 0.7.1 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,176 @@
 # Changelog
 
-## [0.7.1] - 2025-12-20
+## [1.0.0] - 2026-01-08
+
+### Highlights
+
+This is the first stable release of `@navios/react-query`. It includes major improvements to type safety, new helpers for common patterns like optimistic updates and SSR prefetching, and full support for discriminated union error handling.
+
+### Changed
+
+- **Optimistic Update Helpers Marked Experimental**: `createOptimisticUpdate` and `createMultiOptimisticUpdate` are now marked as `@experimental`. These APIs may change in future versions - use manual optimistic update patterns for production code until these helpers stabilize.
+
+## [1.0.0-alpha.1] - 2026-01-07
+
+### Highlights
+
+This was a pre-release version of `@navios/react-query`.
+
+### Breaking Changes
+
+- **Type file reorganization** - Client types have been split into modular files for better maintainability:
+  - `client/types.mts` → Split into `client/types/query.mts`, `client/types/mutation.mts`, `client/types/infinite-query.mts`, `client/types/multipart-mutation.mts`, `client/types/from-endpoint.mts`, and `client/types/helpers.mts`
+  - If you were importing internal types directly, update your imports to use the new paths or the re-exported types from the main entry point.
+
+### Added
+
+#### Error Schema Support (Discriminated Union Mode)
+
+Full support for `errorSchema` in queries and mutations when using `useDiscriminatorResponse: true` mode. API error responses are now returned as data (not thrown) and can be discriminated by status code:
+
+```typescript
+const api = builder({ useDiscriminatorResponse: true })
+
+const getUser = client.query({
+  method: 'GET',
+  url: '/users/$userId',
+  responseSchema: userSchema,
+  errorSchema: {
+    400: z.object({ error: z.string(), code: z.number() }),
+    404: z.object({ notFound: z.literal(true) }),
+  },
+  processResponse: (data) => {
+    // data is typed as: User | { error: string, code: number } | { notFound: true }
+    if ('error' in data) {
+      return { ok: false, error: data.error }
+    }
+    if ('notFound' in data) {
+      return { ok: false, error: 'User not found' }
+    }
+    return { ok: true, user: data }
+  },
+})
+```
+
+#### SSR/RSC Prefetch Helpers
+
+New `createPrefetchHelper` and `createPrefetchHelpers` utilities for server-side rendering and React Server Components:
+
+```typescript
+import { createPrefetchHelper, prefetchAll } from '@navios/react-query'
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+
+// Create prefetch helper from query
+const userPrefetch = createPrefetchHelper(getUser)
+
+// Server Component
+async function UserPage({ userId }: { userId: string }) {
+  const queryClient = new QueryClient()
+
+  await userPrefetch.prefetch(queryClient, { urlParams: { userId } })
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <UserProfile userId={userId} />
+    </HydrationBoundary>
+  )
+}
+```
+
+**Prefetch helper methods:**
+
+- `prefetch(queryClient, params)` - Prefetch data on the server
+- `ensureData(queryClient, params)` - Ensure data exists, returns the data
+- `getQueryOptions(params)` - Get raw query options for customization
+- `prefetchMany(queryClient, paramsList)` - Prefetch multiple queries in parallel
+
+**Batch prefetching:**
+
+```typescript
+// Create multiple prefetch helpers at once
+const prefetchers = createPrefetchHelpers({
+  user: getUser,
+  posts: getUserPosts,
+})
+
+// Or use prefetchAll for different queries
+await prefetchAll(queryClient, [
+  { helper: userPrefetch, params: { urlParams: { userId } } },
+  {
+    helper: postsPrefetch,
+    params: { urlParams: { userId }, params: { limit: 10 } },
+  },
+])
+```
+
+#### Optimistic Update Helpers
+
+New `createOptimisticUpdate` and `createMultiOptimisticUpdate` utilities for type-safe optimistic updates:
+
+```typescript
+import {
+  createMultiOptimisticUpdate,
+  createOptimisticUpdate,
+} from '@navios/react-query'
+
+const updateUser = client.mutation({
+  method: 'PATCH',
+  url: '/users/$userId',
+  requestSchema: updateUserSchema,
+  responseSchema: userSchema,
+  processResponse: (data) => data,
+  useContext: () => ({ queryClient: useQueryClient() }),
+  ...createOptimisticUpdate({
+    queryKey: ['users', userId],
+    updateFn: (oldData, variables) => ({
+      ...oldData,
+      ...variables.data,
+    }),
+    rollbackOnError: true, // default
+    invalidateOnSettled: true, // default
+  }),
+})
+```
+
+**Multi-query optimistic updates:**
+
+```typescript
+const updateUser = client.mutation({
+  // ...
+  ...createMultiOptimisticUpdate([
+    {
+      queryKey: ['users', userId],
+      updateFn: (oldData, variables) => ({ ...oldData, ...variables.data }),
+    },
+    {
+      queryKey: ['users'],
+      updateFn: (oldList, variables) =>
+        (oldList ?? []).map((u) =>
+          u.id === userId ? { ...u, ...variables.data } : u,
+        ),
+    },
+  ]),
+})
+```
+
+#### New Type Exports
+
+- `ComputeBaseResult<UseDiscriminator, Response, ErrorSchema>` - Compute result type based on discriminator mode
+- `PrefetchHelper<TParams, TData, TError>` - Type for prefetch helper instances
+- `QueryOptionsCreator<TParams, TData, TError>` - Type for query options creator functions
+- `OptimisticUpdateConfig<TData, TVariables, TQueryData>` - Configuration for optimistic updates
+- `OptimisticUpdateCallbacks<TData, TVariables, TQueryData>` - Return type from `createOptimisticUpdate`
+
+### Changed
+
+- **Improved type inference** - Better type inference for `processResponse` callbacks, especially when using `errorSchema`
+- **Modular type definitions** - Client types are now organized into separate files by concern:
+  - `types/query.mts` - Query-related types
+  - `types/mutation.mts` - Mutation-related types
+  - `types/infinite-query.mts` - Infinite query types
+  - `types/multipart-mutation.mts` - Multipart mutation types
+  - `types/from-endpoint.mts` - Types for `*FromEndpoint` methods
+  - `types/helpers.mts` - Helper types like `EndpointHelper`, `StreamHelper`, `ComputeBaseResult`
 
 ### Fixed
 

package/README.md

@@ -9,7 +9,9 @@ Type-safe React Query integration for Navios API client with Zod schema validati
 - **React Query Integration** - Seamless integration with TanStack Query v5
 - **Declarative API** - Define endpoints once, use everywhere
 - **URL Parameters** - Built-in support for parameterized URLs (`/users/$userId`)
-- **Optimistic Updates** - First-class support via `onMutate` callback
+- **Optimistic Updates** - First-class helpers via `createOptimisticUpdate`
+- **SSR/RSC Support** - Built-in prefetch helpers for server-side rendering
+- **Error Schema Support** - Type-safe error handling with discriminated unions
 - **Stream Support** - Handle file downloads and blob responses
 
 ## Installation
@@ -514,6 +516,148 @@ function AvatarUpload({ userId }: { userId: string }) {
 }
 ```
 
+## SSR/RSC Prefetch Helpers
+
+For server-side rendering and React Server Components, use the prefetch helpers:
+
+```typescript
+import { createPrefetchHelper, prefetchAll } from '@navios/react-query'
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+
+// Create prefetch helper from your query
+const userPrefetch = createPrefetchHelper(getUser)
+
+// Server Component
+async function UserPage({ userId }: { userId: string }) {
+  const queryClient = new QueryClient()
+
+  await userPrefetch.prefetch(queryClient, { urlParams: { userId } })
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <UserProfile userId={userId} />
+    </HydrationBoundary>
+  )
+}
+```
+
+### Batch Prefetching
+
+```typescript
+// Create multiple helpers at once
+const prefetchers = createPrefetchHelpers({
+  user: getUser,
+  posts: getUserPosts,
+})
+
+// Or prefetch different queries in parallel
+await prefetchAll(queryClient, [
+  { helper: userPrefetch, params: { urlParams: { userId } } },
+  { helper: postsPrefetch, params: { urlParams: { userId }, params: { limit: 10 } } },
+])
+```
+
+### Helper Methods
+
+- `prefetch(queryClient, params)` - Prefetch data on the server
+- `ensureData(queryClient, params)` - Ensure data exists, returns the data
+- `getQueryOptions(params)` - Get raw query options for customization
+- `prefetchMany(queryClient, paramsList)` - Prefetch multiple queries in parallel
+
+## Optimistic Update Helpers
+
+Simplify optimistic updates with the `createOptimisticUpdate` helper:
+
+```typescript
+import { createOptimisticUpdate } from '@navios/react-query'
+
+const updateUser = client.mutation({
+  method: 'PATCH',
+  url: '/users/$userId',
+  requestSchema: updateUserSchema,
+  responseSchema: userSchema,
+  processResponse: (data) => data,
+  useContext: () => ({ queryClient: useQueryClient() }),
+  ...createOptimisticUpdate({
+    queryKey: ['users', userId],
+    updateFn: (oldData, variables) => ({
+      ...oldData,
+      ...variables.data,
+    }),
+    rollbackOnError: true,    // default
+    invalidateOnSettled: true, // default
+  }),
+})
+```
+
+### Multi-Query Optimistic Updates
+
+When a mutation affects multiple cached queries:
+
+```typescript
+import { createMultiOptimisticUpdate } from '@navios/react-query'
+
+const updateUser = client.mutation({
+  // ...config
+  ...createMultiOptimisticUpdate([
+    {
+      queryKey: ['users', userId],
+      updateFn: (oldData, variables) => ({ ...oldData, ...variables.data }),
+    },
+    {
+      queryKey: ['users'],
+      updateFn: (oldList, variables) =>
+        (oldList ?? []).map((u) =>
+          u.id === userId ? { ...u, ...variables.data } : u
+        ),
+    },
+  ]),
+})
+```
+
+## Error Schema Support
+
+When using `useDiscriminatorResponse: true` mode, API errors are returned as data instead of being thrown. This enables type-safe error discrimination:
+
+```typescript
+const api = builder({ useDiscriminatorResponse: true })
+
+const getUser = client.query({
+  method: 'GET',
+  url: '/users/$userId',
+  responseSchema: userSchema,
+  errorSchema: {
+    400: z.object({ error: z.string(), code: z.number() }),
+    404: z.object({ notFound: z.literal(true) }),
+    500: z.object({ serverError: z.string() }),
+  },
+  processResponse: (data) => {
+    // data is typed as: User | { error: string, code: number } | { notFound: true } | { serverError: string }
+    if ('error' in data) {
+      return { ok: false as const, error: data.error }
+    }
+    if ('notFound' in data) {
+      return { ok: false as const, error: 'User not found' }
+    }
+    if ('serverError' in data) {
+      return { ok: false as const, error: data.serverError }
+    }
+    return { ok: true as const, user: data }
+  },
+})
+
+// In your component
+function UserProfile({ userId }: { userId: string }) {
+  const result = getUser.useSuspense({ urlParams: { userId } })
+
+  if (!result.ok) {
+    return <ErrorMessage error={result.error} />
+  }
+
+  return <div>{result.user.name}</div>
+}
+```
+
 ## API Reference
 
 ### `declareClient(options)`
@@ -594,11 +738,15 @@ The context passed to mutation callbacks includes:
 - `meta` - Mutation metadata
 - `onMutateResult` - Return value from `onMutate` (in `onSuccess`, `onError`, `onSettled`)
 
-## Migration from 0.5.x
+## Migration to 1.0.0
+
+See [CHANGELOG.md](./CHANGELOG.md) for full migration guide.
+
+### From 0.7.x
 
-See [CHANGELOG.md](./CHANGELOG.md) for migration guide from 0.5.x to 0.6.0.
+- **Type file reorganization** - If importing internal types, update paths to use `client/types/*.mts`
 
-Key changes:
+### From 0.5.x to 0.6.x
 
 - Mutation callbacks now receive `(data, variables, context)` instead of `(queryClient, data, variables)`
 - Use `useContext` hook to provide `queryClient` and other dependencies

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}

package/coverage/block-navigation.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+var jumpToCode = (function init() {
+    // Classes of code we would like to highlight in the file view
+    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
+
+    // Elements to highlight in the file listing view
+    var fileListingElements = ['td.pct.low'];
+
+    // We don't want to select elements that are direct descendants of another match
+    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
+
+    // Selector that finds elements on the page to which we can jump
+    var selector =
+        fileListingElements.join(', ') +
+        ', ' +
+        notSelector +
+        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
+
+    // The NodeList of matching elements
+    var missingCoverageElements = document.querySelectorAll(selector);
+
+    var currentIndex;
+
+    function toggleClass(index) {
+        missingCoverageElements
+            .item(currentIndex)
+            .classList.remove('highlighted');
+        missingCoverageElements.item(index).classList.add('highlighted');
+    }
+
+    function makeCurrent(index) {
+        toggleClass(index);
+        currentIndex = index;
+        missingCoverageElements.item(index).scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center'
+        });
+    }
+
+    function goToPrevious() {
+        var nextIndex = 0;
+        if (typeof currentIndex !== 'number' || currentIndex === 0) {
+            nextIndex = missingCoverageElements.length - 1;
+        } else if (missingCoverageElements.length > 1) {
+            nextIndex = currentIndex - 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    function goToNext() {
+        var nextIndex = 0;
+
+        if (
+            typeof currentIndex === 'number' &&
+            currentIndex < missingCoverageElements.length - 1
+        ) {
+            nextIndex = currentIndex + 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    return function jump(event) {
+        if (
+            document.getElementById('fileSearch') === document.activeElement &&
+            document.activeElement != null
+        ) {
+            // if we're currently focused on the search input, we don't want to navigate
+            return;
+        }
+
+        switch (event.which) {
+            case 78: // n
+            case 74: // j
+                goToNext();
+                break;
+            case 66: // b
+            case 75: // k
+            case 80: // p
+                goToPrevious();
+                break;
+        }
+    };
+})();
+window.addEventListener('keydown', jumpToCode);