Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Sin adapter (Svelte, Solid, Angular) ​

No hay adapter de Svelte, Solid ni Angular (para Vue 3 existe @getenginex/sdk-vue, que hace todo lo que esta página describe). Las fábricas de @getenginex/sdk/query (y de los /query de los paquetes de producto) devuelven objetos simples, compatibles con TanStack Query v5 de cualquier framework:

ts
import { createMutations, createQueries, enginexKeys } from '@getenginex/sdk/query'

const q = createQueries(enginex)   // once per client
const m = createMutations(enginex)

q.wallet.getBalance()      // { queryKey, queryFn }  → useQuery / createQuery / prefetchQuery
m.deposits.createPix()     // { mutationKey, mutationFn, invalidates }  → useMutation / createMutation

Las claves, la invalidación y la idempotencia son las de la capa de queries.

Lo que hacen los adapters (React y Vue) y tú haces a mano ​

  1. Volver a llamar a la fábrica cuando la sesión cambia. La clave de las queries de usuario lleva el userId del momento de la llamada (sin sesión, 'anonymous', y el queryFn rechaza con UNAUTHENTICATED sin request). Arma las opciones dentro de algo reactivo a la sesión (un getter, computed, $derived, signal) para que la clave acompañe el inicio y el cierre de sesión.
  2. Eliminar los datos del usuario anterior. Cuando el usuario cambia, elimina (no solo invalides) enginexKeys.user() del QueryClient.
  3. Invalidar después del éxito. En el onSuccess, invalida cada clave de invalidates(input, result) y devuelve la promise, para que la mutation solo termine con los datos actualizados.
  4. No reintentar UNAUTHENTICATED. Ese error no hizo request; reintentarlo solo retrasa el error.

Los pasos 2 y 4 caben en un solo módulo, compartido por los ejemplos de abajo:

ts
// enginex.ts
import { createEnginexClient, isEnginexError, localStorageTokenStore, type Session } from '@getenginex/sdk'
import { createMutations, createQueries, enginexKeys } from '@getenginex/sdk/query'
// The framework package's QueryClient.
import { QueryClient } from '@tanstack/svelte-query' // or '@tanstack/solid-query'

export const enginex = createEnginexClient({ locale: 'pt-BR', tokenStore: localStorageTokenStore() })
export const q = createQueries(enginex)
export const m = createMutations(enginex)

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,
      retry: (failures, error) => !isEnginexError(error, 'UNAUTHENTICATED') && failures < 3,
    },
  },
})

// User switch (logout, login, another `sub`): nothing from the previous player stays in the cache.
const identity = (s: Session) => `${s.status}:${s.userId ?? ''}`
let last = identity(enginex.session.get())
enginex.session.subscribe((session) => {
  const next = identity(session)
  if (next !== last) queryClient.removeQueries({ queryKey: enginexKeys.user() })
  last = next
})

// Step 3: the onSuccess of every SDK mutation.
export function invalidateAfter<I, R>(options: { invalidates: (input: I, result: R) => readonly (readonly unknown[])[] }) {
  return (result: R, input: I) =>
    Promise.all(options.invalidates(input, result).map((queryKey) => queryClient.invalidateQueries({ queryKey })))
}

Svelte 5 (@tanstack/svelte-query 6) ​

svelte
<!-- App.svelte -->
<script lang="ts">
  import { QueryClientProvider } from '@tanstack/svelte-query'
  import { queryClient } from './enginex'
  let { children } = $props()
</script>

<QueryClientProvider client={queryClient}>{@render children()}</QueryClientProvider>
ts
// session.svelte.ts
import { enginex } from './enginex'

class SessionState {
  current = $state.raw(enginex.session.get())
}
export const session = new SessionState()
enginex.session.subscribe((s) => {
  session.current = s
})
svelte
<script lang="ts">
  import { createMutation, createQuery } from '@tanstack/svelte-query'
  import { invalidateAfter, m, q } from './enginex'
  import { session } from './session.svelte'

  // The function is re-evaluated when `session.current` changes: the key follows the login.
  const balance = createQuery(() => ({
    ...q.wallet.getBalance(),
    enabled: session.current.status === 'authenticated',
  }))

  const createPix = m.deposits.createPix()
  const pix = createMutation(() => ({ ...createPix, onSuccess: invalidateAfter(createPix) }))
</script>

{#if balance.data}<p>{balance.data.realBalance}</p>{/if}
<button disabled={pix.isPending} onclick={() => pix.mutate({ amount: 5000 })}>Deposit</button>

Esta página no tiene ejemplo de Svelte 4. Allí, con @tanstack/svelte-query 5, las opciones van en un store (derived del store de la sesión) en lugar de una función; las reglas de arriba son las mismas.

Solid (@tanstack/solid-query) ​

tsx
import { QueryClientProvider, createMutation, createQuery } from '@tanstack/solid-query'
import { createSignal } from 'solid-js'
import { enginex, invalidateAfter, m, q, queryClient } from './enginex'

const [session, setSession] = createSignal(enginex.session.get())
enginex.session.subscribe(setSession)

function Wallet() {
  // The function is re-run when `session()` changes: the key follows the login.
  const balance = createQuery(() => ({
    ...q.wallet.getBalance(),
    enabled: session().status === 'authenticated',
  }))

  const createPix = m.deposits.createPix()
  const pix = createMutation(() => ({ ...createPix, onSuccess: invalidateAfter(createPix) }))

  return (
    <>
      <p>{balance.data?.realBalance}</p>
      <button disabled={pix.isPending} onClick={() => pix.mutate({ amount: 5000 })}>
        Deposit
      </button>
    </>
  )
}

export const App = () => (
  <QueryClientProvider client={queryClient}>
    <Wallet />
  </QueryClientProvider>
)

Sin framework (@tanstack/query-core) ​

Las mismas fábricas sirven para el QueryClient puro, en un script o en un servidor:

ts
const balance = await queryClient.fetchQuery(q.wallet.getBalance())
await queryClient.prefetchQuery(q.config.get())

En el servidor, crea un cliente del SDK y un QueryClient por request (consulta Primeros pasos), nunca en el ámbito del módulo.

Realtime ​

El realtime del core funciona igual en cualquier framework. Para el patrón de useRealtimeSync de React y Vue (invalidar el saldo en cada balance_update en lugar de escribir en el caché), suscríbete al tópico e invalida la clave de la fábrica:

ts
import { coreTopics, createRealtime } from '@getenginex/sdk/realtime'

const realtime = createRealtime(enginex)
const invalidateBalance = () => queryClient.invalidateQueries({ queryKey: q.wallet.getBalance().queryKey })
const off = realtime.subscribe(coreTopics.balance(), invalidateBalance)
const offResync = realtime.onResync(coreTopics.balance(), invalidateBalance)

Suscríbete solo con un usuario en la sesión y vuelve a suscribirte cuando el usuario cambie (la clave del saldo lleva el userId). Consulta Realtime.