@navios/react-query 0.4.0 → 0.5.0

package/src/common/index.mts

@@ -0,0 +1 @@
+export * from './types.mjs'

package/src/common/types.mts

@@ -0,0 +1,31 @@
+import type { BuilderInstance } from '@navios/builder'
+
+/**
+ * Splits a string by a delimiter into a tuple type.
+ * Used for parsing URL paths into segments for query keys.
+ */
+export type Split<S extends string, D extends string> = string extends S
+  ? string[]
+  : S extends ''
+    ? []
+    : S extends `${infer T}${D}${infer U}`
+      ? [T, ...Split<U, D>]
+      : [S]
+
+/**
+ * Function type for processing API responses before returning to the caller.
+ */
+export type ProcessResponseFunction<TData = unknown, TVariables = unknown> = (
+  variables: TVariables,
+) => Promise<TData> | TData
+
+/**
+ * Options for creating a client instance.
+ */
+export type ClientOptions = {
+  api: BuilderInstance
+  defaults?: {
+    keyPrefix?: string[]
+    keySuffix?: string[]
+  }
+}

package/src/index.mts

@@ -1,8 +1,28 @@
-export * from './types/index.mjs'
-export * from './utils/mutation-key.creator.mjs'
-export * from './utils/query-key-creator.mjs'
-export * from './declare-client.mjs'
-export * from './make-mutation.mjs'
-export * from './make-infinite-query-options.mjs'
-export * from './make-query-options.mjs'
-export * from './types.mjs'
+// Main module exports - organized by domain
+export * from './common/index.mjs'
+export * from './query/index.mjs'
+export * from './mutation/index.mjs'
+export * from './client/index.mjs'
+
+// ============================================================================
+// BACKWARDS COMPATIBILITY ALIASES
+// ============================================================================
+// These exports maintain compatibility with the previous flat structure.
+// They are deprecated and will be removed in a future major version.
+
+// Re-export old function names
+export { makeQueryOptions } from './query/make-options.mjs'
+export { makeInfiniteQueryOptions } from './query/make-infinite-options.mjs'
+export { makeMutation } from './mutation/make-hook.mjs'
+
+// Re-export legacy key creator names
+export {
+  createQueryKey,
+  /** @deprecated Use createQueryKey instead */
+  queryKeyCreator,
+} from './query/key-creator.mjs'
+export {
+  createMutationKey,
+  /** @deprecated Use createMutationKey instead */
+  mutationKeyCreator,
+} from './mutation/key-creator.mjs'

package/src/mutation/index.mts

@@ -0,0 +1,3 @@
+export * from './types.mjs'
+export * from './key-creator.mjs'
+export * from './make-hook.mjs'

package/src/mutation/key-creator.mts

@@ -0,0 +1,64 @@
+import type {
+  AnyEndpointConfig,
+  UrlHasParams,
+  UrlParams,
+} from '@navios/builder'
+import type { DataTag } from '@tanstack/react-query'
+
+import type { QueryParams } from '../query/types.mjs'
+
+import { createQueryKey } from '../query/key-creator.mjs'
+
+/**
+ * Creates a mutation key generator for a given endpoint configuration.
+ *
+ * @param config - The endpoint configuration
+ * @param options - Optional query parameters with a default `processResponse` function
+ * @returns A function that generates mutation keys
+ *
+ * @example Basic usage:
+ * ```typescript
+ * const createMutationKey = createMutationKey(endpoint.config);
+ * const mutationKey = createMutationKey({ urlParams: { id: 123 } });
+ * ```
+ *
+ * @example Advanced usage with processResponse:
+ * ```ts
+ * const createMutationKey = createMutationKey(endpoint.config, {
+ *   processResponse: (data) => {
+ *     if (!data.success) {
+ *       throw new Error(data.message);
+ *     }
+ *     return data.data;
+ *   },
+ * });
+ * // We create a mutation that will be shared across the project for all passed userId
+ * const mutationKey = createMutationKey({ urlParams: { projectId: 123, userId: 'wildcard' } });
+ * ```
+ */
+export function createMutationKey<
+  Config extends AnyEndpointConfig,
+  Options extends QueryParams<Config>,
+  Url extends Config['url'] = Config['url'],
+  HasParams extends UrlHasParams<Url> = UrlHasParams<Url>,
+>(
+  config: Config,
+  options: Options = {
+    processResponse: (data) => data,
+  } as Options,
+): (
+  params: HasParams extends true ? { urlParams: UrlParams<Url> } : {},
+) => Options['processResponse'] extends (...args: unknown[]) => infer Result
+  ? DataTag<[Config['url']], Result, Error>
+  : never {
+  const queryKey = createQueryKey(config, options, false)
+
+  // @ts-expect-error We have correct types in return type
+  return (params) => {
+    return queryKey.filterKey(params)
+  }
+}
+
+// Legacy export for backwards compatibility
+/** @deprecated Use createMutationKey instead */
+export const mutationKeyCreator = createMutationKey

package/src/{make-mutation.mts → mutation/make-hook.mts}

@@ -1,6 +1,7 @@
 import type {
   AbstractEndpoint,
   AnyEndpointConfig,
+  NaviosZodRequest,
   UrlHasParams,
   UrlParams,
 } from '@navios/builder'
@@ -13,20 +14,30 @@ import {
   useQueryClient,
 } from '@tanstack/react-query'
 
-import type { BaseMutationArgs, BaseMutationParams } from './types.mjs'
+import type { MutationParams } from './types.mjs'
 
-import { mutationKeyCreator } from './index.mjs'
+import { createMutationKey } from './key-creator.mjs'
 
+/**
+ * Creates a mutation hook for a given endpoint.
+ *
+ * Returns a function that when called returns a TanStack Query mutation result.
+ * The returned function also has helper methods attached (mutationKey, useIsMutating).
+ *
+ * @param endpoint - The navios endpoint to create a mutation hook for
+ * @param options - Mutation configuration including processResponse and callbacks
+ * @returns A hook function that returns mutation result with attached helpers
+ */
 export function makeMutation<
   Config extends AnyEndpointConfig,
   TData = unknown,
-  TVariables extends BaseMutationArgs<Config> = BaseMutationArgs<Config>,
+  TVariables extends NaviosZodRequest<Config> = NaviosZodRequest<Config>,
   TResponse = z.output<Config['responseSchema']>,
   TContext = unknown,
   UseKey extends boolean = false,
 >(
   endpoint: AbstractEndpoint<Config>,
-  options: BaseMutationParams<
+  options: MutationParams<
     Config,
     TData,
     TVariables,
@@ -37,22 +48,22 @@ export function makeMutation<
 ) {
   const config = endpoint.config
 
-  const mutationKey = mutationKeyCreator(config, options)
+  const mutationKey = createMutationKey(config, options)
   const result = (
     keyParams: UseKey extends true
       ? UrlHasParams<Config['url']> extends true
         ? UrlParams<Config['url']>
         : never
       : never,
-  ): UseMutationResult<TData, Error, BaseMutationArgs<Config>> => {
+  ): UseMutationResult<TData, Error, NaviosZodRequest<Config>> => {
     const queryClient = useQueryClient()
     const {
       useKey,
       useContext,
       onError,
       onSuccess,
-      keyPrefix,
-      keySuffix,
+      keyPrefix: _keyPrefix,
+      keySuffix: _keySuffix,
       processResponse,
       ...rest
     } = options

package/src/mutation/types.mts

@@ -0,0 +1,106 @@
+import type {
+  AnyEndpointConfig,
+  NaviosZodRequest,
+  UrlHasParams,
+  UrlParams,
+} from '@navios/builder'
+import type { DataTag, QueryClient, UseMutationOptions } from '@tanstack/react-query'
+import type { z, ZodObject } from 'zod/v4'
+
+import type { ProcessResponseFunction } from '../common/types.mjs'
+
+/**
+ * Arguments for mutation functions based on URL params, request schema, and query schema.
+ */
+export type MutationArgs<
+  Url extends string = string,
+  RequestSchema = unknown,
+  QuerySchema = unknown,
+> = (UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {}) &
+  (RequestSchema extends ZodObject ? { data: z.input<RequestSchema> } : {}) &
+  (QuerySchema extends ZodObject ? { params: z.input<QuerySchema> } : {})
+
+/**
+ * Helper methods attached to mutation hooks.
+ */
+export type MutationHelpers<Url extends string, Result = unknown> =
+  UrlHasParams<Url> extends true
+    ? {
+        mutationKey: (params: UrlParams<Url>) => DataTag<[Url], Result, Error>
+        useIsMutating: (keyParams: UrlParams<Url>) => boolean
+      }
+    : {
+        mutationKey: () => DataTag<[Url], Result, Error>
+        useIsMutating: () => boolean
+      }
+
+/**
+ * Base parameters for mutation configuration.
+ */
+export interface MutationParams<
+  Config extends AnyEndpointConfig,
+  TData = unknown,
+  TVariables = NaviosZodRequest<Config>,
+  TResponse = z.output<Config['responseSchema']>,
+  TContext = unknown,
+  UseKey extends boolean = false,
+> extends Omit<
+    UseMutationOptions<TData, Error, TVariables>,
+    'mutationKey' | 'mutationFn' | 'onSuccess' | 'onError' | 'scope'
+  > {
+  processResponse: ProcessResponseFunction<TData, TResponse>
+  /**
+   * React hooks that will prepare the context for the mutation onSuccess and onError
+   * callbacks. This is useful for when you want to use the context in the callbacks
+   */
+  useContext?: () => TContext
+  onSuccess?: (
+    queryClient: QueryClient,
+    data: TData,
+    variables: TVariables,
+    context: TContext,
+  ) => void | Promise<void>
+  onError?: (
+    queryClient: QueryClient,
+    err: unknown,
+    variables: TVariables,
+    context: TContext,
+  ) => void | Promise<void>
+
+  /**
+   * If true, we will create a mutation key that can be shared across the project.
+   */
+  useKey?: UseKey
+  keyPrefix?: UseKey extends true
+    ? UrlHasParams<Config['url']> extends true
+      ? string[]
+      : never
+    : never
+  keySuffix?: UseKey extends true
+    ? UrlHasParams<Config['url']> extends true
+      ? string[]
+      : never
+    : never
+}
+
+// Legacy type aliases for backwards compatibility
+/** @deprecated Use MutationArgs instead */
+export type ClientMutationArgs<
+  Url extends string = string,
+  RequestSchema = unknown,
+  QuerySchema = unknown,
+> = MutationArgs<Url, RequestSchema, QuerySchema>
+
+/** @deprecated Use MutationParams instead */
+export type BaseMutationParams<
+  Config extends AnyEndpointConfig,
+  TData = unknown,
+  TVariables = NaviosZodRequest<Config>,
+  TResponse = z.output<Config['responseSchema']>,
+  TContext = unknown,
+  UseKey extends boolean = false,
+> = MutationParams<Config, TData, TVariables, TResponse, TContext, UseKey>
+
+/** @deprecated Use NaviosZodRequest from @navios/builder instead */
+export type BaseMutationArgs<Config extends AnyEndpointConfig> =
+  NaviosZodRequest<Config>

package/src/query/index.mts

@@ -0,0 +1,4 @@
+export * from './types.mjs'
+export * from './key-creator.mjs'
+export * from './make-options.mjs'
+export * from './make-infinite-options.mjs'

package/src/{utils/query-key-creator.mts → query/key-creator.mts}

@@ -1,62 +1,32 @@
-import type {
-  AnyEndpointConfig,
-  UrlHasParams,
-  UrlParams,
-} from '@navios/builder'
+import type { AnyEndpointConfig, UrlHasParams } from '@navios/builder'
 import type { DataTag, InfiniteData } from '@tanstack/react-query'
-import type { z, ZodObject } from 'zod/v4'
 
 import { bindUrlParams } from '@navios/builder'
 
-import type { BaseQueryParams } from '../types.mjs'
+import type { Split } from '../common/types.mjs'
+import type { QueryKeyCreatorResult, QueryParams } from './types.mjs'
 
-type Split<S extends string, D extends string> = string extends S
-  ? string[]
-  : S extends ''
-    ? []
-    : S extends `${infer T}${D}${infer U}`
-      ? [T, ...Split<U, D>]
-      : [S]
-
-export type QueryKeyCreatorResult<
-  QuerySchema = undefined,
-  Url extends string = string,
-  Result = unknown,
-  IsInfinite extends boolean = false,
-  HasParams extends UrlHasParams<Url> = UrlHasParams<Url>,
-> = {
-  template: Split<Url, '/'>
-  dataTag: (
-    params: (HasParams extends true ? { urlParams: UrlParams<Url> } : {}) &
-      (QuerySchema extends ZodObject ? { params: z.input<QuerySchema> } : {}),
-  ) => DataTag<
-    Split<Url, '/'>,
-    IsInfinite extends true ? InfiniteData<Result> : Result,
-    Error
-  >
-  filterKey: (
-    params: HasParams extends true ? { urlParams: UrlParams<Url> } : {},
-  ) => DataTag<
-    Split<Url, '/'>,
-    IsInfinite extends true ? InfiniteData<Result> : Result,
-    Error
-  >
-  bindToUrl: (
-    params: (HasParams extends true ? { urlParams: UrlParams<Url> } : {}) &
-      (QuerySchema extends ZodObject ? { params: z.infer<QuerySchema> } : {}),
-  ) => string
-}
-
-export function queryKeyCreator<
+/**
+ * Creates a query key generator for a given endpoint configuration.
+ *
+ * The returned object provides methods to generate query keys that can be used
+ * with TanStack Query for caching, invalidation, and data tagging.
+ *
+ * @param config - The endpoint configuration
+ * @param options - Query parameters including processResponse and key prefix/suffix
+ * @param isInfinite - Whether this is for an infinite query
+ * @returns An object with methods to generate query keys
+ */
+export function createQueryKey<
   Config extends AnyEndpointConfig,
-  Options extends BaseQueryParams<Config>,
+  Options extends QueryParams<Config>,
   IsInfinite extends boolean,
   Url extends Config['url'] = Config['url'],
   HasParams extends UrlHasParams<Url> = UrlHasParams<Url>,
 >(
   config: Config,
   options: Options,
-  isInfinite: IsInfinite,
+  _isInfinite: IsInfinite,
 ): QueryKeyCreatorResult<
   Config['querySchema'],
   Url,
@@ -119,7 +89,11 @@ export function queryKeyCreator<
     },
 
     bindToUrl: (params) => {
-      return bindUrlParams<Url>(url, params ?? ({} as any))
+      return bindUrlParams<Url>(url, params ?? ({} as never))
     },
   }
 }
+
+// Legacy export for backwards compatibility
+/** @deprecated Use createQueryKey instead */
+export const queryKeyCreator = createQueryKey

package/src/{make-infinite-query-options.mts → query/make-infinite-options.mts}

@@ -17,11 +17,21 @@ import {
   useSuspenseInfiniteQuery,
 } from '@tanstack/react-query'
 
-import type { InfiniteQueryOptions } from './types.mjs'
-import type { ClientQueryArgs } from './types/index.mjs'
+import type { InfiniteQueryOptions, QueryArgs } from './types.mjs'
 
-import { queryKeyCreator } from './utils/query-key-creator.mjs'
+import { createQueryKey } from './key-creator.mjs'
 
+/**
+ * Creates infinite query options for a given endpoint.
+ *
+ * Returns a function that generates TanStack Query infinite options when called with params.
+ * The returned function also has helper methods attached (use, useSuspense, invalidate, etc.)
+ *
+ * @param endpoint - The navios endpoint to create infinite query options for
+ * @param options - Infinite query configuration including processResponse and pagination params
+ * @param baseQuery - Optional base query options to merge
+ * @returns A function that generates infinite query options with attached helpers
+ */
 export function makeInfiniteQueryOptions<
   Config extends AnyEndpointConfig,
   Options extends InfiniteQueryOptions<Config>,
@@ -40,11 +50,11 @@ export function makeInfiniteQueryOptions<
   baseQuery: BaseQuery = {} as BaseQuery,
 ) {
   const config = endpoint.config
-  const queryKey = queryKeyCreator(config, options, true)
+  const queryKey = createQueryKey(config, options, true)
 
   const processResponse = options.processResponse
   const res = (
-    params: ClientQueryArgs,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
   ): Options['processResponse'] extends (...args: any[]) => infer Result
     ? UseSuspenseInfiniteQueryOptions<
         Result,
@@ -56,9 +66,8 @@ export function makeInfiniteQueryOptions<
     : never => {
     // @ts-expect-error TS2322 We know that the processResponse is defined
     return infiniteQueryOptions({
-      // @ts-expect-error TS2322 We know the type
       queryKey: queryKey.dataTag(params),
-      queryFn: async ({ signal, pageParam }) => {
+      queryFn: async ({ signal, pageParam }): Promise<ReturnType<Options['processResponse']>> => {
         let result
         try {
           result = await endpoint({
@@ -77,9 +86,10 @@ export function makeInfiniteQueryOptions<
           throw err
         }
 
-        return processResponse(result)
+        return processResponse(result) as ReturnType<Options['processResponse']>
       },
       getNextPageParam: options.getNextPageParam,
+      getPreviousPageParam: options.getPreviousPageParam,
       initialPageParam:
         options.initialPageParam ??
         config.querySchema.parse('params' in params ? params.params : {}),
@@ -88,24 +98,28 @@ export function makeInfiniteQueryOptions<
   }
   res.queryKey = queryKey
 
-  res.use = (params: ClientQueryArgs) => {
+  res.use = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
     return useInfiniteQuery(res(params))
   }
 
-  res.useSuspense = (params: ClientQueryArgs) => {
+  res.useSuspense = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
     return useSuspenseInfiniteQuery(res(params))
   }
 
-  res.invalidate = (queryClient: QueryClient, params: ClientQueryArgs) => {
+  res.invalidate = (
+    queryClient: QueryClient,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
+  ) => {
     return queryClient.invalidateQueries({
-      // @ts-expect-error We add additional function to the result
       queryKey: res.queryKey.dataTag(params),
     })
   }
 
-  res.invalidateAll = (queryClient: QueryClient, params: ClientQueryArgs) => {
+  res.invalidateAll = (
+    queryClient: QueryClient,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
+  ) => {
     return queryClient.invalidateQueries({
-      // @ts-expect-error We add additional function to the result
       queryKey: res.queryKey.filterKey(params),
       exact: false,
     })

package/src/{make-query-options.mts → query/make-options.mts}

@@ -8,22 +8,25 @@ import type {
 
 import { queryOptions, useQuery, useSuspenseQuery } from '@tanstack/react-query'
 
-import type { BaseQueryArgs, BaseQueryParams } from './types.mjs'
-import type { ClientQueryArgs } from './types/index.mjs'
+import type { Split } from '../common/types.mjs'
+import type { QueryArgs, QueryParams } from './types.mjs'
 
-import { queryKeyCreator } from './utils/query-key-creator.mjs'
-
-type Split<S extends string, D extends string> = string extends S
-  ? string[]
-  : S extends ''
-    ? []
-    : S extends `${infer T}${D}${infer U}`
-      ? [T, ...Split<U, D>]
-      : [S]
+import { createQueryKey } from './key-creator.mjs'
 
+/**
+ * Creates query options for a given endpoint.
+ *
+ * Returns a function that generates TanStack Query options when called with params.
+ * The returned function also has helper methods attached (use, useSuspense, invalidate, etc.)
+ *
+ * @param endpoint - The navios endpoint to create query options for
+ * @param options - Query configuration including processResponse
+ * @param baseQuery - Optional base query options to merge
+ * @returns A function that generates query options with attached helpers
+ */
 export function makeQueryOptions<
   Config extends AnyEndpointConfig,
-  Options extends BaseQueryParams<Config>,
+  Options extends QueryParams<Config>,
   BaseQuery extends Omit<
     UseQueryOptions<ReturnType<Options['processResponse']>, Error, any>,
     | 'queryKey'
@@ -40,12 +43,11 @@ export function makeQueryOptions<
   baseQuery: BaseQuery = {} as BaseQuery,
 ) {
   const config = endpoint.config
-  // Let's hack the url to be a string for now
-  const queryKey = queryKeyCreator(config, options, false)
+  const queryKey = createQueryKey(config, options, false)
   const processResponse = options.processResponse
 
   const result = (
-    params: BaseQueryArgs<Config>,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
   ): Options['processResponse'] extends (...args: any[]) => infer Result
     ? UseSuspenseQueryOptions<
         Result,
@@ -57,7 +59,7 @@ export function makeQueryOptions<
     // @ts-expect-error TS2322 We know that the processResponse is defined
     return queryOptions({
       queryKey: queryKey.dataTag(params),
-      queryFn: async ({ signal }) => {
+      queryFn: async ({ signal }): Promise<ReturnType<Options['processResponse']>> => {
         let result
         try {
           result = await endpoint({
@@ -71,35 +73,34 @@ export function makeQueryOptions<
           throw err
         }
 
-        return processResponse(result)
+        return processResponse(result) as ReturnType<Options['processResponse']>
       },
       ...baseQuery,
     })
   }
   result.queryKey = queryKey
-  result.use = (params: ClientQueryArgs) => {
-    // @ts-expect-error We add additional function to the result
+  result.use = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
     return useQuery(result(params))
   }
 
-  result.useSuspense = (params: ClientQueryArgs) => {
-    // @ts-expect-error We add additional function to the result
+  result.useSuspense = (params: QueryArgs<Config['url'], Config['querySchema']>) => {
     return useSuspenseQuery(result(params))
   }
 
-  result.invalidate = (queryClient: QueryClient, params: ClientQueryArgs) => {
+  result.invalidate = (
+    queryClient: QueryClient,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
+  ) => {
     return queryClient.invalidateQueries({
-      // @ts-expect-error We add additional function to the result
       queryKey: result.queryKey.dataTag(params),
     })
   }
 
   result.invalidateAll = (
     queryClient: QueryClient,
-    params: ClientQueryArgs,
+    params: QueryArgs<Config['url'], Config['querySchema']>,
   ) => {
     return queryClient.invalidateQueries({
-      // @ts-expect-error We add additional function to the result
       queryKey: result.queryKey.filterKey(params),
       exact: false,
     })