Pete Miller
5cc0360a83
components/ai_chat/resources/page/api/ai_chat_api.ts had trouble with typescript intellisense due to the process file mutation functions now having an array as their first param. Apparently due to contravariance checks
970 lines
33 KiB
TypeScript
970 lines
33 KiB
TypeScript
// Copyright (c) 2025 The Brave Authors. All rights reserved.
|
||
// This Source Code Form is subject to the terms of the Mozilla Public
|
||
// License, v. 2.0. If a copy of the MPL was not distributed with this file,
|
||
// You can obtain one at https://mozilla.org/MPL/2.0/.
|
||
|
||
import * as React from 'react'
|
||
import {
|
||
QueryClient,
|
||
QueryObserver,
|
||
useQuery,
|
||
UseQueryResult as ReactQueryUseQueryResult,
|
||
useMutation,
|
||
UseMutationResult as ReactQueryUseMutationResult,
|
||
UseMutationOptions,
|
||
QueryObserverOptions,
|
||
MutationOptions,
|
||
MutationObserver,
|
||
MutateOptions,
|
||
} from '@tanstack/react-query'
|
||
|
||
/**
|
||
* Shared QueryClient singleton used by all APIs created with createInterfaceApi.
|
||
* Each API differentiates its data via unique key prefixes.
|
||
* Callers can still pass their own QueryClient if needed.
|
||
*/
|
||
let sharedQueryClient = new QueryClient()
|
||
|
||
/**
|
||
* Removes all data from the shared QueryClient used by all calls to
|
||
* createInterfaceApi which do not provide their own QueryClient.
|
||
*/
|
||
export function clearAllDataForTesting() {
|
||
// sharedQueryClient.clear() or .cancelQueries() can throw a CancelledError,
|
||
// and it's probably best to move to a new instance in-between tests anyway.
|
||
sharedQueryClient = new QueryClient()
|
||
}
|
||
|
||
type ChangeReturnType<T extends (...args: any[]) => any, R> = T extends (
|
||
...args: infer P
|
||
) => any
|
||
? (...args: P) => R
|
||
: never
|
||
|
||
export type NoPlaceholderQueryEndpointDefinition<
|
||
P extends readonly any[],
|
||
R,
|
||
> = {
|
||
query: (...args: P) => Promise<R>
|
||
prefetchWithArgs?: NoInfer<P>
|
||
} & Omit<
|
||
QueryObserverOptions<NoInfer<R>>,
|
||
'queryKey' | 'queryFn' | 'placeholderData'
|
||
>
|
||
|
||
export type PlaceholderQueryEndpointDefinition<
|
||
P extends readonly any[],
|
||
R,
|
||
> = NoPlaceholderQueryEndpointDefinition<P, R> & {
|
||
placeholderData: NoInfer<R>
|
||
}
|
||
|
||
export type QueryEndpointDefinition<P extends readonly any[], R> =
|
||
| NoPlaceholderQueryEndpointDefinition<P, R>
|
||
| PlaceholderQueryEndpointDefinition<P, R>
|
||
|
||
export type MutationEndpointDefinition<P extends readonly any[], R> = {
|
||
mutation: (...args: P) => Promise<R>
|
||
} & Omit<MutationOptions<NoInfer<R>, unknown, P>, 'mutationKey' | 'mutationFn'>
|
||
|
||
/**
|
||
* Each endpoint must be one of:
|
||
* { query: (...args: A) => Promise<T>, prefetch?: boolean }
|
||
* or
|
||
* { mutation: (...args: A) => Promise<T> }
|
||
*
|
||
* For query endpoints, you get `.fetch(...)`, `.useQuery(...)`, `.invalidate(...)`, and `.update(...)`.
|
||
* For mutation endpoints, you get `.mutate(...)` and `.useMutation()`.
|
||
*/
|
||
export type EndpointDef<P extends readonly any[], R> =
|
||
| QueryEndpointDefinition<P, R>
|
||
| MutationEndpointDefinition<P, R>
|
||
|
||
/**
|
||
* EventDef<Args, Payload> is just a phantom object whose sole job is to carry
|
||
* the tuple‐type `Args` (an array of key‐argument types) and the `Payload` type.
|
||
*
|
||
* At runtime `event()` returns a dummy object; we only use its type for inference.
|
||
*/
|
||
export type EventDef<Args extends any[], Payload extends any[]> = {
|
||
registerEmitter: (emitter: (...args: Payload) => void) => void
|
||
/**
|
||
* phantom field so we can extract `Args` at the type level
|
||
*/
|
||
__args: Args
|
||
}
|
||
|
||
// This function only exists to actually prevent inferring of
|
||
// query args from prefetchWithArgs so that typescript avoids
|
||
// confusion if the query() parameters don't match the prefetchWithArgs type
|
||
// and informs the consumer that there's a mismatch that needs to be fixed.
|
||
// Ideally consumers would not need to wrap their endpoints in query()
|
||
// and they don't if they don't define prefetchWithArgs.
|
||
export function query<const P extends readonly any[], R>(
|
||
endpoint: QueryEndpointDefinition<P, R>,
|
||
): QueryEndpointDefinition<P, R> {
|
||
return endpoint
|
||
}
|
||
|
||
/**
|
||
* Wrapper for an endpoint which creates data that is not fetched but is
|
||
* updated by events and provided with initial data.
|
||
* @param data optional initial data
|
||
* @returns query endpoint definition
|
||
*/
|
||
// Overload: when data is provided, return type includes placeholderData
|
||
export function state<R>(data: R): PlaceholderQueryEndpointDefinition<[], R>
|
||
// Overload: when no data, return type without placeholderData
|
||
export function state<R>(): NoPlaceholderQueryEndpointDefinition<[], R>
|
||
// Implementation
|
||
export function state<R>(data?: R): QueryEndpointDefinition<[], R> {
|
||
const base = {
|
||
query: () =>
|
||
Promise.reject(new Error('State endpoint should not be called')),
|
||
enabled: false,
|
||
prefetchWithArgs: [] as [],
|
||
staleTime: 'static' as const,
|
||
}
|
||
if (data !== undefined) {
|
||
return { ...base, placeholderData: data }
|
||
}
|
||
return base
|
||
}
|
||
|
||
/**
|
||
* Call this for each event in your config. For example:
|
||
* events: {
|
||
* onConversationDeleted: event<[string], boolean>(),
|
||
* onUserRenamed: event<[number], { id: number; newName: string }>(),
|
||
* }
|
||
*
|
||
* That tells the factory "`onConversationDeleted` takes one key‐arg (string),
|
||
* and its payload is a boolean."
|
||
*/
|
||
export function event<Args extends any[], Payload extends any[]>(
|
||
registerEmitter: (emitter: (...args: Payload) => void) => void,
|
||
): EventDef<Args, Payload> {
|
||
return {
|
||
registerEmitter,
|
||
__args: [] as any as Args,
|
||
}
|
||
}
|
||
|
||
// Basis for a unique key for each call to createInterfaceApi for the current scope
|
||
let globalRootInstanceCount = 0
|
||
|
||
/**
|
||
* Factory function to create a subscribable API with a shared cache based off
|
||
* (usually a mojom) interface which exposes features of Tanstack Query in a
|
||
* similar fashion to RTK Query's createApi.
|
||
*
|
||
* Whilst this sets up a store that could be (ab)used to store, update and
|
||
* subscribe to any data, it encourages its use only for remote-fetched data,
|
||
* and not reactive state needed for the UI. The intention is for that kind of
|
||
* state to be handled by the more featureful UI framework.
|
||
*
|
||
* See readme.md for detailed usage instructions and examples.
|
||
*/
|
||
export function createInterfaceApi<
|
||
/**
|
||
* ExposedActions is a record of simple actions that can be called directly from the UI.
|
||
* These actions do not require any status helpers or long-term data caching.
|
||
* For example:
|
||
* {
|
||
* sendMessage: (message: string) => void,
|
||
* deleteConversation: (id: string) => void,
|
||
* …
|
||
* }
|
||
*/
|
||
const ExposedActions extends Record<
|
||
string,
|
||
Function | Record<string, Function>
|
||
>,
|
||
// Use `EndpointDef<any, any>` (not `any[]`) so that specific endpoint
|
||
// definitions remain assignable under `strictFunctionTypes`. With `any[]`,
|
||
// mutation callbacks like `onMutate: (variables: [a, b]) => …` fail
|
||
// contravariance checks against `(variables: any[]) => …` because tuples
|
||
// are narrower than `any[]`. Switching to `any` makes the parameter slot
|
||
// bivariant and side-steps the variance issue without losing inference on
|
||
// the concrete `RawEndpoints` type below.
|
||
const RawEndpoints extends Record<string, EndpointDef<any, any>>,
|
||
EventDefinitions extends Record<string, EventDef<any[], any>> = {},
|
||
>(config: {
|
||
/**
|
||
* Simple actions that can be called directly from the UI. These
|
||
* don't need any status helpers or data caching. If helper data for status,
|
||
* e.g. "in progress", would be useful then consider using a mutation endpoint instead.
|
||
*/
|
||
actions?: ExposedActions
|
||
|
||
/**
|
||
* Actions to expose to the UI, each have a result that will be cached or mutated
|
||
*/
|
||
endpoints: RawEndpoints
|
||
|
||
/** An array of event names to broadcast */
|
||
events?: EventDefinitions
|
||
}) {
|
||
// Use shared QueryClient by default for proper React context integration.
|
||
// All APIs share the same client; keys differentiate the data.
|
||
const queryClient = sharedQueryClient
|
||
|
||
const rootKey = globalRootInstanceCount++
|
||
|
||
type ValidKey = keyof RawEndpoints & string
|
||
|
||
// For each endpoint K:
|
||
// ArgsOf<K> = the parameter‐tuple of raw[K].[query|mutation]
|
||
// DataOf<K> = the (Promise-d) returned type of raw[K].[query|mutation]
|
||
type ArgsOf<K extends ValidKey> =
|
||
RawEndpoints[K] extends QueryEndpointDefinition<infer QueryArgs, any>
|
||
? QueryArgs
|
||
: RawEndpoints[K] extends MutationEndpointDefinition<
|
||
infer MutationArgs,
|
||
any
|
||
>
|
||
? MutationArgs
|
||
: never
|
||
type DataOf<K extends keyof RawEndpoints> =
|
||
RawEndpoints[K] extends QueryEndpointDefinition<any, infer QueryResult>
|
||
? QueryResult
|
||
: RawEndpoints[K] extends MutationEndpointDefinition<
|
||
any,
|
||
infer MutationResult
|
||
>
|
||
? MutationResult
|
||
: never
|
||
|
||
// If placeholder data is provided, we can assume that data is never undefined
|
||
type EndpointDataForKey<K extends ValidKey> = RawEndpoints[K] extends {
|
||
placeholderData: DataOf<K>
|
||
}
|
||
? DataOf<K>
|
||
: DataOf<K> | undefined
|
||
|
||
// Custom results
|
||
type BaseUseQueryResult<K extends ValidKey> = ReactQueryUseQueryResult<
|
||
DataOf<K>
|
||
>
|
||
type UseQueryResult<K extends ValidKey> = BaseUseQueryResult<K> & {
|
||
// Convenience - a nicer name for data
|
||
// *and* never undefined if placeholder data is provided, e.g.
|
||
// `const { getThingsData } = useGetThings()`
|
||
// instead of
|
||
// ```
|
||
// const { data: getThingsData } = useSaveSomething()
|
||
// if (!getThingsData) {
|
||
// throw new Error('getThingsData should never be undefined as it has placeholder data')
|
||
// }
|
||
// ```
|
||
[P in K as `${P}Data`]: EndpointDataForKey<K>
|
||
// Note: We could add more convenience properties here,
|
||
// e.g. `isMyQueryLoading`.
|
||
} & {
|
||
// Never undefined if placeholderData is provided
|
||
data: EndpointDataForKey<K>
|
||
}
|
||
|
||
type BaseUseMutationResult<K extends ValidKey> = ReactQueryUseMutationResult<
|
||
DataOf<K>,
|
||
unknown,
|
||
ArgsOf<K>
|
||
> & {
|
||
// Nicer version of mutate where args are optional if no parameters
|
||
mutate: ArgsOf<K> extends []
|
||
? () => ReturnType<
|
||
ReactQueryUseMutationResult<DataOf<K>, unknown, ArgsOf<K>>['mutate']
|
||
>
|
||
: ReactQueryUseMutationResult<DataOf<K>, unknown, ArgsOf<K>>['mutate']
|
||
}
|
||
type UseMutationResult<K extends ValidKey> = BaseUseMutationResult<K> & {
|
||
// Convenience - a nicer name for mutate, e.g.
|
||
// `const { saveSomething } = useSaveSomething()`
|
||
// instead of
|
||
// `const { mutate: saveSomething } = useSaveSomething()`
|
||
[P in K]: BaseUseMutationResult<K>['mutate']
|
||
}
|
||
|
||
type APIActions = {
|
||
[K in keyof ExposedActions]: ExposedActions[K] extends (
|
||
...args: infer P
|
||
) => any
|
||
? ExposedActions[K]
|
||
: {
|
||
[P in keyof ExposedActions[K]]: ExposedActions[K][P]
|
||
}
|
||
}
|
||
|
||
// Don't allow individual hook uses to specify events since those are specified either at the endpoint
|
||
// definition or by the mutation function call.
|
||
type APIUseMutationOptions<K extends ValidKey> = Omit<
|
||
UseMutationOptions<DataOf<K>, unknown, ArgsOf<K>>,
|
||
'onMutate' | 'onError' | 'onSuccess' | 'onSettled'
|
||
>
|
||
|
||
// Build out methods for every K in RawEndpoints, depending on whether it's a query or mutation
|
||
type APIEndpoints = {
|
||
[K in ValidKey]: RawEndpoints[K] extends QueryEndpointDefinition<any, any>
|
||
? {
|
||
/**
|
||
* Call the underlying query and return the data. This will
|
||
* also cause anyone subscribed to this endpoint to receive the
|
||
* updated data.
|
||
*/
|
||
fetch: (...args: ArgsOf<K>) => Promise<DataOf<K>>
|
||
|
||
/**
|
||
* Imperative (non-reactive) way to retrieve data for this endpoint.
|
||
* Should only be used in callbacks or functions where reading the
|
||
* latest data is necessary, e.g. for optimistic updates.
|
||
*
|
||
* Hint: Do not use this function inside a component, because it won't
|
||
* receive updates. Use useQuery to create a QueryObserver that
|
||
* subscribes to changes.
|
||
*/
|
||
current: (...args: ArgsOf<K>) => EndpointDataForKey<K>
|
||
|
||
/**
|
||
* Reset the cache for this endpoint
|
||
* (specifying optional arguments as the key)
|
||
* which will remove the data from the cache
|
||
* and reset the state to undefined or placeholderData.
|
||
*/
|
||
reset: (...args: ArgsOf<K>) => void
|
||
|
||
/**
|
||
* Invalidate the cache for this endpoint
|
||
* (specifying optional arguments as the key to invalidate)
|
||
* which will force a re-fetch of the data if currently
|
||
* subscribed to, or on the next call to `fetch()`.
|
||
*/
|
||
invalidate: (...args: ArgsOf<K>) => void
|
||
|
||
/**
|
||
* React hook for accessing state of a query endpoint including progress, cached data and re-fetching
|
||
* See https://tanstack.com/query/latest/docs/framework/react/reference/useQuery
|
||
*/
|
||
useQuery: (...args: ArgsOf<K>) => UseQueryResult<K>
|
||
|
||
/**
|
||
* Manually update the cache for this endpoint
|
||
* (specifying optional arguments as the key to update).
|
||
* Usage: api.myEndpoint.update(arg1, arg2, ..., updaterFnOrUpdate)
|
||
* where updaterFnOrUpdate has signature (old: Data | undefined) => Data
|
||
* OR is a Partial<Data> to update the object directly.
|
||
*
|
||
* This is useful in event handlers from the remote interface, or
|
||
* optimistic updates.
|
||
*/
|
||
update: (
|
||
...argsAndUpdater: [
|
||
...Params: ArgsOf<K>,
|
||
updater:
|
||
| ((old: DataOf<K>) => Partial<DataOf<K>>)
|
||
| Partial<DataOf<K>>,
|
||
]
|
||
) => void
|
||
} & (RawEndpoints[K] extends { placeholderData: DataOf<K> }
|
||
? {
|
||
// If placeholder data is provided, we know
|
||
// the data will never be undefined, so we can
|
||
// provide a potentially even more convenient hook.
|
||
useData: (...args: ArgsOf<K>) => DataOf<K>
|
||
}
|
||
: {})
|
||
: RawEndpoints[K] extends MutationEndpointDefinition<any, any>
|
||
? {
|
||
/**
|
||
* Call the underlying `raw[K].mutation(...args)` and return the data.
|
||
*/
|
||
mutate: ChangeReturnType<
|
||
BaseUseMutationResult<K>['mutate'],
|
||
Promise<DataOf<K>>
|
||
>
|
||
|
||
/**
|
||
* Hook: runs `useMutation` for this mutation endpoint.
|
||
* You can call `mutate(variables)` or `mutateAsync(variables)` on the result.
|
||
*/
|
||
useMutation: (
|
||
options?: APIUseMutationOptions<K>,
|
||
) => UseMutationResult<K>
|
||
}
|
||
: never
|
||
}
|
||
|
||
const endpoints = {} as APIEndpoints
|
||
|
||
// Build endpoints - Queries and Mutations
|
||
//
|
||
// Expose React Query's hooks and methods for each endpoint,
|
||
// deciding if it's a query or mutation endpoint.
|
||
//
|
||
//
|
||
;(Object.keys(config.endpoints) as Array<ValidKey>).forEach((name) => {
|
||
const endpointDef = config.endpoints[name]
|
||
const baseKey = [rootKey, name]
|
||
|
||
if ('query' in endpointDef) {
|
||
const { query, prefetchWithArgs, ...queryOptions } =
|
||
endpointDef as QueryEndpointDefinition<any, any>
|
||
type QArgs = ArgsOf<typeof name>
|
||
type QData = DataOf<typeof name>
|
||
|
||
if (!queryOptions.staleTime) {
|
||
// The default for staleTime is 0, meaning a result is stale as soon
|
||
// as it is received. That results in every useQuery call causing a
|
||
// re-fetch after returning the stale data.
|
||
// Infinity will make data always considered fresh and re-fetch will
|
||
// only occur when invalidated, manually refetched, or if refetchOnX is
|
||
// set.
|
||
queryOptions.staleTime = Infinity
|
||
}
|
||
|
||
// fetch(...args):
|
||
// - calls `query(...args)`
|
||
// - sets the result into cache under [...baseKey, ...args]
|
||
// - returns the data
|
||
const fetcher = async (...args: QArgs) => {
|
||
const data = await queryClient.fetchQuery<QData, never, QArgs>({
|
||
queryKey: [...baseKey, ...args],
|
||
queryFn: () => {
|
||
const queryResult = query(...args)
|
||
return queryResult
|
||
},
|
||
...queryOptions,
|
||
})
|
||
return data
|
||
}
|
||
|
||
const getCachedData = (...args: QArgs) => {
|
||
const queryKey = [...baseKey, ...args] as readonly any[]
|
||
let cachedData = queryClient.getQueryData<QData>(queryKey)
|
||
if (cachedData === undefined && 'placeholderData' in queryOptions) {
|
||
cachedData = queryOptions.placeholderData
|
||
}
|
||
return cachedData
|
||
}
|
||
|
||
// invalidates the cache so that it will be refetched
|
||
// if the data is needed.
|
||
const invalidate = (...args: QArgs) => {
|
||
const queryKey = [...baseKey, ...args]
|
||
queryClient.invalidateQueries({
|
||
queryKey,
|
||
exact: true,
|
||
})
|
||
}
|
||
|
||
// Removes state and resets to undefined or placeholderData
|
||
const reset = (...args: QArgs) => {
|
||
const queryKey = [...baseKey, ...args]
|
||
// We can use removeQueries if we don't want
|
||
// to reset to placeholderData.
|
||
queryClient.resetQueries({
|
||
queryKey,
|
||
exact: true,
|
||
})
|
||
}
|
||
|
||
// useQuery(...args): wrapper around React-Query's useQuery
|
||
const useQ = (...args: QArgs) => {
|
||
const useQueryResult = useQuery<QData>(
|
||
{
|
||
queryKey: [...baseKey, ...args],
|
||
queryFn: () => {
|
||
const queryResult = query(...args)
|
||
return queryResult
|
||
},
|
||
...queryOptions,
|
||
},
|
||
queryClient,
|
||
)
|
||
return {
|
||
...useQueryResult,
|
||
// Typescript will handle whether this property
|
||
// is accessible as definitely QData or undefined | QData.
|
||
// We don't need to check if placeholderData is provided.
|
||
[`${name}Data`]: useQueryResult.data,
|
||
} as UseQueryResult<typeof name>
|
||
}
|
||
|
||
// update(...args, updaterFn): manually setQueryData for that key
|
||
// We can accept a partial update only if the data is an object
|
||
type AllowedUpdateParam = QData extends {} ? Partial<QData> : QData
|
||
function updateFromOld(
|
||
old: QData | undefined,
|
||
update: AllowedUpdateParam,
|
||
): QData {
|
||
if (
|
||
old === undefined
|
||
|| Array.isArray(old)
|
||
|| typeof old !== 'object'
|
||
) {
|
||
// Technically we shouldn't allow this as it might just be partial
|
||
return update as QData
|
||
}
|
||
// Objects can be combined
|
||
return { ...old, ...(update as Partial<QData>) } as QData
|
||
}
|
||
|
||
const updater = (
|
||
...argsAndUpdater: [
|
||
...Params: QArgs,
|
||
updaterFn: ((old: QData) => AllowedUpdateParam) | AllowedUpdateParam,
|
||
]
|
||
) => {
|
||
const up = argsAndUpdater[argsAndUpdater.length - 1] as
|
||
| ((old: QData) => AllowedUpdateParam)
|
||
| Partial<QData>
|
||
// args is everything except the updater function (or updated state) which is
|
||
// always the last argument.
|
||
const args = argsAndUpdater.slice(
|
||
0,
|
||
argsAndUpdater.length - 1,
|
||
) as unknown as QArgs
|
||
|
||
const queryKey = [...baseKey, ...args]
|
||
|
||
queryClient.setQueryData<QData>(queryKey, (old) => {
|
||
const updateData: AllowedUpdateParam =
|
||
typeof up === 'function'
|
||
? up(old as QData)
|
||
: (up as AllowedUpdateParam)
|
||
const oldOrPlaceholder = getCachedData(...args)
|
||
if (!old && oldOrPlaceholder) {
|
||
// Warn only if this is a regular query. "state" queries will always
|
||
// use the update mechanism - the initial data is always considered
|
||
// placeholder.
|
||
if (endpointDef.enabled) {
|
||
console.warn(
|
||
'Updating data for query when base data has not yet'
|
||
+ ' been received. Placeholder data will convert to "real" data.'
|
||
+ ' `isPlaceholder` can no longer be relied upon for this query.',
|
||
{ queryKey, old, oldOrPlaceholder, updateData },
|
||
)
|
||
}
|
||
old = oldOrPlaceholder
|
||
}
|
||
const newData = updateFromOld(old, updateData)
|
||
return newData
|
||
})
|
||
|
||
// Cancel and re-queue because our set could be replaced if there is a
|
||
// query in-progress.
|
||
if (queryClient.isFetching({ queryKey, exact: true })) {
|
||
queryClient.cancelQueries({
|
||
queryKey,
|
||
exact: true,
|
||
})
|
||
// re-queue, but must first invalidate so that fetcher performs a new
|
||
// fetch instead of return the cached result
|
||
queryClient.invalidateQueries({
|
||
queryKey,
|
||
exact: true,
|
||
})
|
||
fetcher(...args)
|
||
}
|
||
}
|
||
|
||
if (prefetchWithArgs && queryOptions.enabled !== false) {
|
||
// If this endpoint is marked as prefetch, we prefetch it immediately
|
||
// even if the UI doesn't call it yet - we don't
|
||
// want to wait for React to initialize.
|
||
fetcher(...(prefetchWithArgs as QArgs))
|
||
}
|
||
|
||
;(endpoints as any)[name] = {
|
||
fetch: fetcher,
|
||
current: getCachedData,
|
||
invalidate,
|
||
reset,
|
||
useQuery: useQ,
|
||
update: updater,
|
||
}
|
||
} else if ('mutation' in endpointDef) {
|
||
const { mutation, ...mutationOptions } = endpointDef
|
||
type MArgs = ArgsOf<typeof name> | never
|
||
type MData = DataOf<typeof name>
|
||
|
||
// Allow the caller to e.g. handle mutation results
|
||
queryClient.setMutationDefaults(baseKey, mutationOptions)
|
||
|
||
type EndpointUseMutationOptions = UseMutationOptions<
|
||
MData,
|
||
unknown,
|
||
MArgs
|
||
>
|
||
|
||
// useMutation(): wrap React-Query's useMutation
|
||
const useMut = (
|
||
options?: APIUseMutationOptions<typeof name>,
|
||
...args: MArgs
|
||
): UseMutationResult<typeof name> => {
|
||
const mutationOptions: EndpointUseMutationOptions = { ...options }
|
||
// Do not allow overriding the events - they can be specified in the
|
||
// endpoint definition or at the mutation call. The typescript type prohibits
|
||
// this but we should enforce it at runtime for JS or ignored TS errors in order
|
||
// to avoid unexpected behavior.
|
||
for (const key of [
|
||
'onSuccess',
|
||
'onSettled',
|
||
'onError',
|
||
'onMutate',
|
||
] as Partial<keyof EndpointUseMutationOptions>[]) {
|
||
if (Object.hasOwn(mutationOptions, key)) {
|
||
delete mutationOptions[key]
|
||
}
|
||
}
|
||
const useMutationResult = useMutation<MData, unknown, MArgs>(
|
||
{
|
||
mutationKey: [...baseKey, ...args],
|
||
mutationFn: (variables) => mutation(...variables),
|
||
...mutationOptions,
|
||
},
|
||
queryClient,
|
||
)
|
||
|
||
return {
|
||
...useMutationResult,
|
||
[name]: useMutationResult.mutate,
|
||
} as UseMutationResult<typeof name>
|
||
}
|
||
|
||
const directMutateFn = (
|
||
args: MArgs,
|
||
options?: MutateOptions<MData, unknown, MArgs, unknown>,
|
||
) => {
|
||
const observer = new MutationObserver<MData, unknown, MArgs, unknown>(
|
||
queryClient,
|
||
{
|
||
...options,
|
||
mutationKey: [...baseKey, ...(args ?? [])],
|
||
mutationFn: (variables) => mutation(...variables),
|
||
},
|
||
)
|
||
|
||
return observer.mutate(args ?? [])
|
||
}
|
||
|
||
;(endpoints as any)[name] = {
|
||
mutate: directMutateFn,
|
||
useMutation: useMut,
|
||
}
|
||
}
|
||
})
|
||
|
||
// Events
|
||
// We expect `config.events` to be something like:
|
||
// {
|
||
// onSomethingHappened: event<[], { some: 'data' }>(),
|
||
// onConversationDeleted: event<[conversationId: string], boolean>(),
|
||
// onUserRenamed: event<[userId: number], { id:number; newName: string }>(),
|
||
// }
|
||
//
|
||
// Where the user can subscribe to an argument-less event,
|
||
// e.g. `onSomethingHappened`, or an event with key arguments,
|
||
// e.g. `onConversationDeleted` which takes a `conversationId` as the key argument.
|
||
//
|
||
// That is different from the payload, which is the data that is sent
|
||
// when the event is emitted.
|
||
// e.g.
|
||
// useOnConversationDeleted(conversationId, (result) => {
|
||
// console.log(`Conversation ${conversationId} was deleted: ${result}`)
|
||
// })
|
||
//
|
||
// -or-
|
||
//
|
||
// useOnSomethingHappened((data) => {})
|
||
//
|
||
//
|
||
type EvAll = keyof NonNullable<typeof config.events>
|
||
type EvDefs = NonNullable<typeof config.events>
|
||
|
||
type KeyArgsOf<K extends EvAll> =
|
||
EvDefs[K] extends EventDef<infer A, any> ? A : never
|
||
type PayloadOf<K extends EvAll> =
|
||
EvDefs[K] extends EventDef<any, infer P extends any[]> ? P : never
|
||
|
||
type EventInternalData<T> = { payload: T; eventCount: number }
|
||
|
||
function emitEvent<K extends EvAll>(
|
||
eventName: K,
|
||
...argsAndPayload: [...KeyArgsOf<K>, PayloadOf<K>]
|
||
) {
|
||
const payload = argsAndPayload[argsAndPayload.length - 1] as PayloadOf<K>
|
||
const keyArgs = argsAndPayload.slice(
|
||
0,
|
||
argsAndPayload.length - 1,
|
||
) as KeyArgsOf<K>
|
||
queryClient.setQueryData<EventInternalData<PayloadOf<K>>>(
|
||
[rootKey, eventName, ...keyArgs],
|
||
(old) => ({ payload, eventCount: (old?.eventCount ?? 0) + 1 }),
|
||
)
|
||
}
|
||
|
||
type EventHooks = {
|
||
/**
|
||
* React hook to wrap useEffect with a subscription and unsubscription
|
||
* to the event, firing the provided handler, and resubscribing
|
||
* whenever the provided dependencies change.
|
||
*/
|
||
[K in EvAll as `use${Capitalize<string & K>}`]: (
|
||
handler?: (...result: PayloadOf<K>) => void,
|
||
deps?: React.DependencyList,
|
||
...keyArgs: KeyArgsOf<K>
|
||
) => void
|
||
} & {
|
||
/**
|
||
* React hook to get the latest payload for the event. Useful for one-off
|
||
* events without needing to add extra state to your UI component
|
||
*/
|
||
[K in EvAll as `useCurrent${Capitalize<string & K>}`]: (
|
||
...keyArgs: KeyArgsOf<K>
|
||
) => {
|
||
hasEmitted: boolean
|
||
/**
|
||
* The latest data for the event, or undefined if no data has been set
|
||
*/
|
||
data: PayloadOf<K> | undefined
|
||
}
|
||
} & {
|
||
/**
|
||
* Subscribe and unsubscribe to the event
|
||
*/
|
||
[K in EvAll as `subscribeTo${Capitalize<string & K>}`]: (
|
||
handler: (...result: PayloadOf<K>) => void,
|
||
...keyArgs: KeyArgsOf<K>
|
||
) => () => void
|
||
} & {
|
||
/**
|
||
* Clear event data so that useCurrentMyEvent will return undefined until
|
||
* the next time the event is emitted.
|
||
*/
|
||
[K in EvAll as `reset${Capitalize<string & K>}`]: (
|
||
...keyArgs: KeyArgsOf<K>
|
||
) => void
|
||
}
|
||
|
||
// Events implementation
|
||
|
||
const eventHooks = {} as EventHooks
|
||
|
||
;(Object.keys(config.events || {}) as Array<EvAll>).forEach((eventName) => {
|
||
const cap = `${(eventName as string)[0].toUpperCase()}${(eventName as string).slice(1)}`
|
||
const hookName = `use${cap}`
|
||
const hookNameUseCurrent = `useCurrent${cap}`
|
||
const subscribeName = `subscribeTo${cap}`
|
||
const handledName = `reset${cap}`
|
||
|
||
const keyBase = [rootKey, eventName]
|
||
|
||
// register the emitter for the event
|
||
// @ts-expect-error we need to fix the type of argsAndPayload
|
||
;(config.events as any)[eventName].registerEmitter((...args) =>
|
||
// @ts-expect-error
|
||
emitEvent(eventName, args),
|
||
)
|
||
|
||
// useCurrentMyEvent
|
||
;(eventHooks as any)[hookNameUseCurrent] = (...keyArgs: any[]) => {
|
||
const hookData = useQuery<EventInternalData<PayloadOf<typeof eventName>>>(
|
||
{
|
||
queryKey: [...keyBase, ...keyArgs],
|
||
enabled: false,
|
||
queryFn: () =>
|
||
Promise.reject(
|
||
new Error(
|
||
`${eventName as string} is an event, not a query and should not try to fetch data`,
|
||
),
|
||
),
|
||
},
|
||
queryClient,
|
||
)
|
||
|
||
return {
|
||
hasEmitted: hookData.isFetched,
|
||
data: hookData.data?.payload,
|
||
}
|
||
}
|
||
|
||
// subscribeToMyEvent
|
||
;(eventHooks as any)[subscribeName] = (
|
||
handler: (...result: PayloadOf<typeof eventName>) => {},
|
||
...keyArgs: any[]
|
||
) => {
|
||
const observer = new QueryObserver<
|
||
EventInternalData<PayloadOf<typeof eventName>>
|
||
>(queryClient, {
|
||
queryKey: [...keyBase, ...keyArgs],
|
||
enabled: false,
|
||
queryFn: () =>
|
||
Promise.reject(
|
||
new Error(
|
||
`${eventName as string} is an event, not a query and should not try to fetch data`,
|
||
),
|
||
),
|
||
})
|
||
|
||
const unsubscribe = observer.subscribe((result) => {
|
||
if (result.data !== undefined) {
|
||
handler(...result.data.payload)
|
||
} else {
|
||
// We would only get here if there is never any payload type for
|
||
// this event.
|
||
// @ts-expect-error no args
|
||
handler()
|
||
}
|
||
})
|
||
|
||
return unsubscribe
|
||
}
|
||
|
||
// useMyEvent
|
||
;(eventHooks as any)[hookName] = (
|
||
handler: (...result: PayloadOf<typeof eventName>) => {},
|
||
deps: React.DependencyList,
|
||
...keyArgs: any[]
|
||
) => {
|
||
// Every time this function is called, we're probably going to get a new instance
|
||
// of the handler, but we don't want to depend on it so that we re-subscribe
|
||
// every time the handler changes. We also don't want to call an old version
|
||
// of the handler when the event fires. Storing in a ref solves both requirements.
|
||
const handlerRef = React.useRef(handler)
|
||
handlerRef.current = handler
|
||
React.useEffect(() => {
|
||
const unsubscribe = (eventHooks as any)[subscribeName](
|
||
handlerRef.current,
|
||
...keyArgs,
|
||
)
|
||
return () => {
|
||
unsubscribe()
|
||
}
|
||
}, deps)
|
||
}
|
||
|
||
// Remove any emitted data for this event
|
||
;(eventHooks as any)[handledName] = (...keyArgs: any[]) => {
|
||
queryClient.resetQueries({
|
||
queryKey: [...keyBase, ...keyArgs],
|
||
exact: true,
|
||
})
|
||
}
|
||
})
|
||
|
||
type MutationKeys = {
|
||
[K in keyof RawEndpoints]: RawEndpoints[K] extends MutationEndpointDefinition<
|
||
any,
|
||
any
|
||
>
|
||
? K
|
||
: never
|
||
}[keyof RawEndpoints]
|
||
& string
|
||
|
||
type QueryKeys = {
|
||
[K in keyof RawEndpoints]: RawEndpoints[K] extends QueryEndpointDefinition<
|
||
any,
|
||
any
|
||
>
|
||
? K
|
||
: never
|
||
}[keyof RawEndpoints]
|
||
& string
|
||
|
||
// Build convenience root access to endpoints
|
||
type RootEndpointMethods =
|
||
// Queries
|
||
{
|
||
// Named query React hook
|
||
[K in QueryKeys as `use${Capitalize<string & K>}`]: (
|
||
...args: ArgsOf<K>
|
||
) => UseQueryResult<K>
|
||
} & {
|
||
// Direct access to endpoint to get non-hook current data, invalidate the query, etc.
|
||
[K in QueryKeys]: APIEndpoints[K]
|
||
} & {
|
||
// Queries with placeholder data always have data, so we can have a
|
||
// named data convenience hook if components don't need progress state.
|
||
[K in ValidKey as RawEndpoints[K] extends PlaceholderQueryEndpointDefinition<
|
||
any,
|
||
any
|
||
>
|
||
? `use${Capitalize<string & K>}Data`
|
||
: never]: (...args: ArgsOf<K>) => DataOf<K>
|
||
} & {
|
||
// Mutations
|
||
// useDoSomething: endpoints.doSomething.useMutation
|
||
[K in MutationKeys as `use${Capitalize<string & K>}`]: (
|
||
options?: APIUseMutationOptions<K>,
|
||
) => UseMutationResult<K>
|
||
} & {
|
||
// doSomething: endpoints.doSomething.mutate
|
||
[K in MutationKeys]: Extract<APIEndpoints[K], { mutate: any }>['mutate']
|
||
}
|
||
|
||
const rootEndpointProperties = {} as RootEndpointMethods
|
||
|
||
;(Object.keys(config.endpoints) as Array<keyof RawEndpoints>).forEach(
|
||
(name) => {
|
||
const capitalized = `${(name as string)[0].toUpperCase()}${(name as string).slice(1)}`
|
||
const hookName =
|
||
`use${capitalized}` as `use${Capitalize<string & typeof name>}`
|
||
|
||
if ('query' in config.endpoints[name]) {
|
||
// @ts-expect-error: generated hook name
|
||
rootEndpointProperties[hookName] = (endpoints as any)[name].useQuery
|
||
|
||
// @ts-expect-error
|
||
rootEndpointProperties[name] = (endpoints as any)[name]
|
||
|
||
if ('placeholderData' in config.endpoints[name]) {
|
||
// @ts-expect-error: generated hook name
|
||
rootEndpointProperties[`use${capitalized}Data`] = (
|
||
...args: any[]
|
||
) => {
|
||
return (endpoints as any)[name].useQuery(...args).data
|
||
}
|
||
}
|
||
}
|
||
|
||
if ('mutation' in config.endpoints[name]) {
|
||
// @ts-expect-error: we know that `endpoints[name].useMutation` matches the signature
|
||
rootEndpointProperties[hookName] = (endpoints as any)[name].useMutation
|
||
// @ts-expect-error
|
||
rootEndpointProperties[name] = (endpoints as any)[name].mutate
|
||
}
|
||
},
|
||
)
|
||
|
||
const actions = config.actions as any as APIActions
|
||
|
||
// Convenient access to query endpoint child functions
|
||
|
||
const api = {
|
||
emitEvent,
|
||
...actions,
|
||
...rootEndpointProperties,
|
||
...eventHooks,
|
||
/**
|
||
* Invalidates all queries for this API instance, causing them to refetch
|
||
* if currently subscribed. Useful for Storybook/tests when any control
|
||
* changes and you want all data to refresh from mock functions.
|
||
*/
|
||
invalidateAll: () => {
|
||
queryClient.invalidateQueries({
|
||
queryKey: [rootKey],
|
||
exact: false,
|
||
})
|
||
},
|
||
close: () => {
|
||
// Cancel all pending queries for this API key
|
||
queryClient.cancelQueries({ queryKey: [rootKey], exact: false })
|
||
// Queries will be gc with no subscribers but we can remove them immediately
|
||
queryClient.removeQueries({ queryKey: [rootKey], exact: false })
|
||
},
|
||
}
|
||
|
||
return api
|
||
}
|