@navios/react-query 0.4.0 → 0.5.0

package/src/query/types.mts

@@ -0,0 +1,163 @@
+import type {
+  AnyEndpointConfig,
+  BaseEndpointConfig,
+  HttpMethod,
+  UrlHasParams,
+  UrlParams,
+  Util_FlatObject,
+} from '@navios/builder'
+import type {
+  DataTag,
+  InfiniteData,
+  QueryClient,
+  UseQueryResult,
+  UseSuspenseQueryResult,
+} from '@tanstack/react-query'
+import type { z, ZodObject, ZodType } from 'zod/v4'
+
+import type { Split } from '../common/types.mjs'
+
+/**
+ * Arguments for query functions based on URL params and query schema.
+ */
+export type QueryArgs<
+  Url extends string = string,
+  QuerySchema = ZodObject,
+  RequestSchema = undefined,
+> = (UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {}) &
+  (QuerySchema extends ZodObject ? { params: z.input<QuerySchema> } : {}) &
+  (RequestSchema extends ZodType ? { data: z.input<RequestSchema> } : {})
+
+/**
+ * Arguments containing only URL params (for invalidateAll operations).
+ */
+export type QueryUrlParamsArgs<Url extends string = string> =
+  UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {} | undefined
+
+/**
+ * Base parameters for query configuration.
+ */
+export type QueryParams<Config extends AnyEndpointConfig, Res = any> = {
+  keyPrefix?: string[]
+  keySuffix?: string[]
+  onFail?: (err: unknown) => void
+  processResponse: (data: z.output<Config['responseSchema']>) => Res
+}
+
+/**
+ * Result type from the query key creator function.
+ */
+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
+}
+
+/**
+ * Helper methods attached to query options.
+ */
+export type QueryHelpers<
+  Url extends string,
+  QuerySchema extends ZodObject | undefined = undefined,
+  Result = undefined,
+  IsInfinite extends boolean = false,
+  RequestSchema extends ZodType | undefined = undefined,
+> = {
+  queryKey: QueryKeyCreatorResult<QuerySchema, Url, Result, IsInfinite>
+  use: (
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema, RequestSchema>>,
+  ) => UseQueryResult<Result, Error>
+  useSuspense: (
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema, RequestSchema>>,
+  ) => UseSuspenseQueryResult<Result, Error>
+  invalidate: (
+    queryClient: QueryClient,
+    params: Util_FlatObject<QueryArgs<Url, QuerySchema, RequestSchema>>,
+  ) => () => Promise<void>
+  invalidateAll: (
+    queryClient: QueryClient,
+    params: Util_FlatObject<QueryUrlParamsArgs<Url>>,
+  ) => () => Promise<void>
+}
+
+/**
+ * Options for infinite query configuration.
+ */
+export type InfiniteQueryOptions<
+  Config extends BaseEndpointConfig<HttpMethod, string, ZodObject>,
+  Res = any,
+> = {
+  keyPrefix?: string[]
+  keySuffix?: string[]
+  processResponse: (data: z.infer<Config['responseSchema']>) => Res
+  onFail?: (err: unknown) => void
+  getNextPageParam: (
+    lastPage: Res,
+    allPages: Res[],
+    lastPageParam: z.infer<Config['querySchema']> | undefined,
+    allPageParams: z.infer<Config['querySchema']>[] | undefined,
+  ) =>
+    | z.input<Config['querySchema']>
+    | z.infer<Config['querySchema']>
+    | undefined
+  getPreviousPageParam?: (
+    firstPage: Res,
+    allPages: Res[],
+    lastPageParam: z.infer<Config['querySchema']> | undefined,
+    allPageParams: z.infer<Config['querySchema']>[] | undefined,
+  ) => z.input<Config['querySchema']>
+  initialPageParam?:
+    | z.input<Config['querySchema']>
+    | z.infer<Config['querySchema']>
+}
+
+// Legacy type aliases for backwards compatibility
+/** @deprecated Use QueryArgs instead */
+export type ClientQueryArgs<
+  Url extends string = string,
+  QuerySchema = ZodObject,
+  RequestSchema = undefined,
+> = QueryArgs<Url, QuerySchema, RequestSchema>
+
+/** @deprecated Use QueryUrlParamsArgs instead */
+export type ClientQueryUrlParamsArgs<Url extends string = string> =
+  QueryUrlParamsArgs<Url>
+
+/** @deprecated Use QueryParams instead */
+export type BaseQueryParams<
+  Config extends AnyEndpointConfig,
+  Res = unknown,
+> = QueryParams<Config, Res>
+
+/** @deprecated Use QueryArgs instead */
+export type BaseQueryArgs<Config extends AnyEndpointConfig> = (UrlHasParams<
+  Config['url']
+> extends true
+  ? { urlParams: UrlParams<Config['url']> }
+  : {}) &
+  (Config['querySchema'] extends ZodObject
+    ? { params: z.input<Config['querySchema']> }
+    : {})

package/dist/tsdown.config.d.mts

@@ -1,3 +0,0 @@
-declare const _default: import("tsdown").UserConfig | import("tsdown").UserConfigFn;
-export default _default;
-//# sourceMappingURL=tsdown.config.d.mts.map

package/dist/tsdown.config.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tsdown.config.d.mts","sourceRoot":"","sources":["../tsdown.config.mts"],"names":[],"mappings":";AAEA,wBAQE"}

package/dist/tsup.config.d.mts

@@ -1,3 +0,0 @@
-declare const _default: import("tsup").Options | import("tsup").Options[] | ((overrideOptions: import("tsup").Options) => import("tsup").Options | import("tsup").Options[] | Promise<import("tsup").Options | import("tsup").Options[]>);
-export default _default;
-//# sourceMappingURL=tsup.config.d.mts.map

package/dist/tsup.config.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tsup.config.d.mts","sourceRoot":"","sources":["../tsup.config.mts"],"names":[],"mappings":";AAEA,wBAQE"}

package/dist/vitest.config.d.mts

@@ -1,3 +0,0 @@
-declare const _default: import("vitest/config").UserWorkspaceConfig;
-export default _default;
-//# sourceMappingURL=vitest.config.d.mts.map

package/dist/vitest.config.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"vitest.config.d.mts","sourceRoot":"","sources":["../vitest.config.mts"],"names":[],"mappings":";AAEA,wBAME"}

package/src/types/client-endpoint-helper.mts

@@ -1,29 +0,0 @@
-import type {
-  BaseEndpointConfig,
-  EndpointFunctionArgs,
-  HttpMethod,
-  Util_FlatObject,
-} from '@navios/builder'
-import type { z } from 'zod/v4'
-
-export type ClientEndpointHelper<
-  Method extends HttpMethod = HttpMethod,
-  Url extends string = string,
-  RequestSchema = unknown,
-  ResponseSchema extends z.ZodType = z.ZodType,
-  QuerySchema = unknown,
-> = {
-  endpoint: ((
-    params: Util_FlatObject<
-      EndpointFunctionArgs<Url, QuerySchema, RequestSchema>
-    >,
-  ) => Promise<z.output<ResponseSchema>>) & {
-    config: BaseEndpointConfig<
-      Method,
-      Url,
-      QuerySchema,
-      ResponseSchema,
-      RequestSchema
-    >
-  }
-}

package/src/types/index.mts

@@ -1,7 +0,0 @@
-export * from './client-endpoint-helper.mjs'
-export * from './client-instance.mjs'
-export * from './mutation-args.mjs'
-export * from './mutation-helpers.mjs'
-export * from './query-args.mjs'
-export * from './query-helpers.mjs'
-export * from './query-url-params-args.mjs'

package/src/types/mutation-args.mts

@@ -1,10 +0,0 @@
-import type { UrlHasParams, UrlParams } from '@navios/builder'
-import type { z, ZodObject } from 'zod/v4'
-
-export type ClientMutationArgs<
-  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> } : {})

package/src/types/mutation-helpers.mts

@@ -1,13 +0,0 @@
-import type { UrlHasParams, UrlParams } from '@navios/builder'
-import type { DataTag } from '@tanstack/react-query'
-
-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
-      }

package/src/types/query-args.mts

@@ -1,8 +0,0 @@
-import type { UrlHasParams, UrlParams } from '@navios/builder'
-import type { z, ZodObject } from 'zod/v4'
-
-export type ClientQueryArgs<
-  Url extends string = string,
-  QuerySchema = ZodObject,
-> = (UrlHasParams<Url> extends true ? { urlParams: UrlParams<Url> } : {}) &
-  (QuerySchema extends ZodObject ? { params: z.input<QuerySchema> } : {})

package/src/types/query-helpers.mts

@@ -1,34 +0,0 @@
-import type { Util_FlatObject } from '@navios/builder'
-import type {
-  QueryClient,
-  UseQueryResult,
-  UseSuspenseQueryResult,
-} from '@tanstack/react-query'
-import type { ZodObject } from 'zod/v4'
-
-import type { QueryKeyCreatorResult } from '../utils/query-key-creator.mjs'
-import type { ClientQueryArgs } from './query-args.mjs'
-import type { ClientQueryUrlParamsArgs } from './query-url-params-args.mjs'
-
-export type QueryHelpers<
-  Url extends string,
-  QuerySchema extends ZodObject | undefined = undefined,
-  Result = undefined,
-  IsInfinite extends boolean = false,
-> = {
-  queryKey: QueryKeyCreatorResult<QuerySchema, Url, Result, IsInfinite>
-  use: (
-    params: Util_FlatObject<ClientQueryArgs<Url, QuerySchema>>,
-  ) => UseQueryResult<Result, Error>
-  useSuspense: (
-    params: Util_FlatObject<ClientQueryArgs<Url, QuerySchema>>,
-  ) => UseSuspenseQueryResult<Result, Error>
-  invalidate: (
-    queryClient: QueryClient,
-    params: Util_FlatObject<ClientQueryArgs<Url, QuerySchema>>,
-  ) => () => Promise<void>
-  invalidateAll: (
-    queryClient: QueryClient,
-    params: Util_FlatObject<ClientQueryUrlParamsArgs<Url>>,
-  ) => () => Promise<void>
-}

package/src/types/query-url-params-args.mts

@@ -1,6 +0,0 @@
-import type { UrlHasParams, UrlParams } from '@navios/builder'
-
-export type ClientQueryUrlParamsArgs<Url extends string = string> =
-  UrlHasParams<Url> extends true
-    ? { urlParams: UrlParams<Url> }
-    : {} | undefined

package/src/types.mts

@@ -1,118 +0,0 @@
-import type {
-  AnyEndpointConfig,
-  BaseEndpointConfig,
-  BuilderInstance,
-  HttpMethod,
-  NaviosZodRequest,
-  UrlHasParams,
-  UrlParams,
-} from '@navios/builder'
-import type { QueryClient, UseMutationOptions } from '@tanstack/react-query'
-import type { z, ZodObject } from 'zod/v4'
-
-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]
-
-export type ProcessResponseFunction<TData = unknown, TVariables = unknown> = (
-  variables: TVariables,
-) => Promise<TData> | TData
-
-export type ClientOptions<ProcessResponse = unknown> = {
-  api: BuilderInstance
-  defaults?: {
-    keyPrefix?: string[]
-    keySuffix?: string[]
-  }
-}
-
-export type BaseQueryParams<Config extends AnyEndpointConfig, Res = any> = {
-  keyPrefix?: string[]
-  keySuffix?: string[]
-  onFail?: (err: unknown) => void
-  processResponse: (data: z.output<Config['responseSchema']>) => Res
-}
-
-export interface BaseMutationParams<
-  Config extends AnyEndpointConfig,
-  TData = unknown,
-  TVariables = BaseMutationArgs<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
-}
-
-export type BaseQueryArgs<Config extends AnyEndpointConfig> = (UrlHasParams<
-  Config['url']
-> extends true
-  ? { urlParams: UrlParams<Config['url']> }
-  : {}) &
-  (Config['querySchema'] extends ZodObject
-    ? { params: z.input<Config['querySchema']> }
-    : {})
-
-export type BaseMutationArgs<Config extends AnyEndpointConfig> =
-  NaviosZodRequest<Config>
-
-export type InfiniteQueryOptions<
-  Config extends BaseEndpointConfig<HttpMethod, string, ZodObject>,
-  Res = any,
-> = {
-  keyPrefix?: string[]
-  keySuffix?: string[]
-  processResponse: (data: z.infer<Config['responseSchema']>) => Res
-  onFail?: (err: unknown) => void
-  getNextPageParam: (
-    lastPage: Res,
-    allPages: Res[],
-    lastPageParam: z.infer<Config['querySchema']> | undefined,
-    allPageParams: z.infer<Config['querySchema']>[] | undefined,
-  ) =>
-    | z.input<Config['querySchema']>
-    | z.infer<Config['querySchema']>
-    | undefined
-  initialPageParam?:
-    | z.input<Config['querySchema']>
-    | z.infer<Config['querySchema']>
-}

package/src/utils/mutation-key.creator.mts

@@ -1,65 +0,0 @@
-import type {
-  AnyEndpointConfig,
-  UrlHasParams,
-  UrlParams,
-} from '@navios/builder'
-import type { DataTag } from '@tanstack/react-query'
-
-import type { BaseQueryParams } from '../types.mjs'
-
-import { queryKeyCreator } from './query-key-creator.mjs'
-
-/**
- * Creates a mutation key for a given endpoint configuration and options.
- *
- * @param {config: Config } config - The endpoint object containing the configuration.
- * @param {Options} [options] - Optional query parameters with a default `processResponse` function that processes the response data.
- *
- * @returns {Object} An object containing the `mutationKey` function.
- *
- * The `mutationKey` function generates a mutation key based on the provided parameters:
- * - If the URL has parameters (`HasParams` is `true`), it expects an object with `urlParams`.
- * - The return type of the `mutationKey` function depends on the `processResponse` function in `options`.
- *   If `processResponse` is defined, the return type is a `DataTag` containing the processed result and an error type.
- *
- * @example Example usage:
- * ```typescript
- * const createMutationKey = mutationKeyCreator(endpoint.config);
- * const mutationKey = createMutationKey({ urlParams: { id: 123 } });
- * ```
- *
- * @example Advanced usage:
- * ```ts
- * const createMutationKey = mutationKeyCreator(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 mutationKeyCreator<
-  Config extends AnyEndpointConfig,
-  Options extends BaseQueryParams<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: any[]) => infer Result
-  ? DataTag<[Config['url']], Result, Error>
-  : never {
-  const queryKey = queryKeyCreator(config, options, false)
-
-  // @ts-expect-error We have correct types in return type
-  return (params) => {
-    return queryKey.filterKey(params)
-  }
-}