@apollion-dsi/relay 0.25.10 → 0.26.0

package/lib/commitMutation/commitMutation.d.ts

@@ -0,0 +1,42 @@
+import { MutationConfig, MutationParameters } from 'relay-runtime';
+import { Environment } from 'relay-runtime/lib/store/RelayStoreTypes';
+/**
+ * Wrapper Promise-based em torno do `commitMutation` do `relay-runtime`.
+ *
+ * O `commitMutation` original do Relay expõe a conclusão da mutação via os
+ * callbacks `onCompleted` e `onError`. Esta função encapsula esses callbacks
+ * em uma `Promise`, permitindo o uso natural de `async/await` no consumidor —
+ * o que tipicamente cobre 95% dos casos. Para fluxos que precisam de
+ * `optimisticResponse`, `updater`, `cacheConfig` etc., todas as demais opções
+ * de `MutationConfig` continuam sendo aceitas via `config`.
+ *
+ * Os campos `onCompleted` e `onError` são omitidos do `config` de propósito:
+ * eles são gerenciados internamente para alimentar o resolve/reject da Promise.
+ *
+ * @typeParam T - Tipo gerado pelo Relay Compiler para a mutação (`graphql`
+ * tagged) — fornece o shape de `variables` e `response`.
+ *
+ * @param environment - Ambiente Relay (geralmente o exposto por
+ * `CreateRelayEnvironment`).
+ * @param config - Configuração da mutação, sem `onCompleted` e `onError`.
+ *
+ * @returns Promise que resolve com `T['response']` ou rejeita com o erro
+ * retornado pelo Relay.
+ *
+ * @example
+ * ```tsx
+ * import { commitMutation } from '@apollion-dsi/relay/commitMutation';
+ * import { Environment } from './environment';
+ * import { MyMutation } from './__generated__/MyMutation.graphql';
+ *
+ * const response = await commitMutation<MyMutation>(Environment, {
+ *   mutation: graphql`
+ *     mutation MyMutation($input: MyInput!) {
+ *       myMutation(input: $input) { ok }
+ *     }
+ *   `,
+ *   variables: { input: { ... } },
+ * });
+ * ```
+ */
+export declare const commitMutation: <T extends MutationParameters = MutationParameters>(environment: Environment, config: Omit<MutationConfig<T>, "onCompleted" | "onError">) => Promise<T["response"]>;

package/lib/commitMutation/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel público do módulo `commitMutation`.
+ *
+ * Reexporta a função `commitMutation` para que consumidores possam importar
+ * via `@apollion-dsi/relay/commitMutation` (importação granular, evitando
+ * carregar o resto do pacote) ou via `@apollion-dsi/relay` (barrel raiz).
+ */
+export * from './commitMutation';

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Barrel público do package `@apollion-dsi/relay`.
+ *
+ * Reexporta a superfície pública do package: a fábrica de Environment
+ * (`CreateRelayEnvironment`), o Context/hook (`EnvironmentProvider` /
+ * `useEnvironment`), os tipos de configuração (`RelayArgsInterface`,
+ * `Sink`), os utilitários de updater de mutations e o wrapper
+ * Promise-based `commitMutation`.
+ *
+ * Cada módulo também pode ser importado de forma granular via
+ * `@apollion-dsi/relay/<nome>` quando o consumidor quiser carregar
+ * menos código.
+ */
+export { default as CreateRelayEnvironment } from './setupRelayEnvironment/setupRelayEnvironment';
+export * from './useEnvironment';
+export * from './relayArgsInterface';
+export * from './mutationUtils';
+export * from './commitMutation';

package/lib/mutationUtils/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Barrel público do módulo `mutationUtils`.
+ *
+ * Reexporta os helpers para escrever `updater`s de mutations Relay
+ * (listas, connections, optimistic responses). Importável via
+ * `@apollion-dsi/relay/mutationUtils` (granular) ou via
+ * `@apollion-dsi/relay` (barrel raiz).
+ */
+export * from './mutationUtils';

package/lib/mutationUtils/mutationUtils.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @fileoverview Utilitários para escrever `updater`s de mutations Relay
+ * de forma declarativa, sem precisar manipular `RecordProxy` /
+ * `ConnectionHandler` à mão em cada caso comum.
+ *
+ * Cobre os cenários mais frequentes:
+ * - inserir/remover itens em listas (`linked records`);
+ * - inserir/remover edges em connections (paginação Relay);
+ * - copiar campos escalares de um objeto JS para um `RecordProxy`
+ *   (útil em respostas otimistas).
+ */
+import { RecordProxy, RecordSourceSelectorProxy } from 'relay-runtime';
+/**
+ * Verifica se um valor é um objeto não-nulo (para detectar campos
+ * escalares vs. linked records em `copyObjScalarsToProxy`).
+ */
+export declare function isObject(obj: any): boolean;
+/** Argumentos de `listRecordRemoveUpdater`. */
+type ListRecordRemoveUpdaterOptions = {
+    parentId: string;
+    itemId: string;
+    parentFieldName: string;
+    store: RecordSourceSelectorProxy;
+};
+/** Argumentos de `listRecordAddUpdater`. */
+type ListRecordAddUpdaterOptions = {
+    parentId: string;
+    item: Record<string, any>;
+    type: string;
+    parentFieldName: string;
+    store: RecordSourceSelectorProxy;
+};
+/** Argumentos de `optimisticConnectionUpdater`. */
+type OptimisticConnectionUpdaterOptions = {
+    parentId: string;
+    store: RecordSourceSelectorProxy;
+    connectionName: string;
+    item: Record<string, any>;
+    customNode: RecordProxy;
+    itemType: string;
+};
+/** Argumentos de `connectionDeleteEdgeUpdater`. */
+type ConnectionDeleteEdgeUpdaterOptions = {
+    parentId: string;
+    connectionName: string;
+    nodeId: string;
+    store: RecordSourceSelectorProxy;
+};
+/** Argumentos de `copyObjScalarsToProxy`. */
+type CopyObjScalarsToProxyOptions = {
+    object: Record<string, any>;
+    proxy: RecordProxy;
+};
+/**
+ * Identificador único gerado uma vez por carregamento do módulo,
+ * destinado ao campo `clientMutationId` esperado pelo padrão Relay
+ * Modern.
+ */
+export declare const ClientMutationID: string;
+/**
+ * Remove um item de uma lista de `linked records` num parent.
+ *
+ * Usa `getLinkedRecords` + `setLinkedRecords` com filtro por `dataID`.
+ * Para connections paginadas, prefira `connectionDeleteEdgeUpdater`.
+ *
+ * @param options.parentId - DataID do parent que possui o linked field.
+ * @param options.itemId - DataID do item a remover.
+ * @param options.parentFieldName - Nome do field linked no parent.
+ * @param options.store - `RecordSourceSelectorProxy` recebido no updater.
+ */
+export declare function listRecordRemoveUpdater({ parentId, itemId, parentFieldName, store, }: ListRecordRemoveUpdaterOptions): void;
+/**
+ * Adiciona um item ao final de uma lista de `linked records`.
+ *
+ * Cria um novo `RecordProxy` usando `item.id` como dataID e copia todos
+ * os campos de `item` para o novo record (sem validar tipos — escalares
+ * e linked refs viram `setValue`).
+ *
+ * @param options.parentId - DataID do parent.
+ * @param options.item - Objeto com os campos do novo record (precisa ter `id`).
+ * @param options.type - Tipo GraphQL do record (ex: `'Todo'`).
+ * @param options.parentFieldName - Nome do field linked no parent.
+ * @param options.store - `RecordSourceSelectorProxy` do updater.
+ */
+export declare function listRecordAddUpdater({ parentId, item, type, parentFieldName, store, }: ListRecordAddUpdaterOptions): void;
+/**
+ * Insere um edge em uma connection paginada (Relay Connections spec).
+ *
+ * @param store - `RecordSourceSelectorProxy` do updater.
+ * @param parentId - DataID do parent que possui a connection.
+ * @param connectionName - Nome da connection no schema (`@connection(key: ...)`).
+ * @param edge - O `RecordProxy` do edge já criado pelo chamador.
+ * @param before - Se `true`, insere antes do primeiro edge (default `false`).
+ */
+export declare function connectionUpdater(store: RecordSourceSelectorProxy, parentId: string, connectionName: string, edge: RecordProxy, before?: boolean): void;
+/**
+ * Variante de `connectionUpdater` usada em respostas otimistas: cria o
+ * node e o edge "do zero" a partir de um objeto JS, simulando o que o
+ * servidor retornaria.
+ *
+ * @param options.parentId - DataID do parent.
+ * @param options.store - `RecordSourceSelectorProxy`.
+ * @param options.connectionName - Nome da connection.
+ * @param options.item - Objeto com os campos do novo node (precisa ter `id`).
+ * @param options.customNode - `RecordProxy` pré-criado (opcional, evita criar via `item`).
+ * @param options.itemType - Tipo GraphQL do node (ex: `'Todo'`); o edge
+ *   será criado como `<itemType>Edge`.
+ */
+export declare function optimisticConnectionUpdater({ parentId, store, connectionName, item, customNode, itemType, }: OptimisticConnectionUpdaterOptions): void;
+/**
+ * Remove um node de uma connection paginada pelo seu `dataID`.
+ *
+ * Loga `console.warn` se a connection não for encontrada (geralmente
+ * significa que o `connectionName` está errado).
+ *
+ * @param options.parentId - DataID do parent.
+ * @param options.connectionName - Nome da connection.
+ * @param options.nodeId - DataID do node a remover.
+ * @param options.store - `RecordSourceSelectorProxy`.
+ */
+export declare function connectionDeleteEdgeUpdater({ parentId, connectionName, nodeId, store, }: ConnectionDeleteEdgeUpdaterOptions): void;
+/**
+ * Copia os campos escalares de um objeto JS para um `RecordProxy`.
+ *
+ * Ignora campos que são objetos ou arrays (linked records / linked
+ * record lists) — esses precisam ser manipulados com
+ * `setLinkedRecord`/`setLinkedRecords`.
+ *
+ * @param options.object - Objeto JS de origem.
+ * @param options.proxy - `RecordProxy` de destino.
+ */
+export declare function copyObjScalarsToProxy({ object, proxy }: CopyObjScalarsToProxyOptions): void;
+export {};

package/lib/relayArgsInterface/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Barrel público do módulo `relayArgsInterface`.
+ *
+ * Reexporta os tipos `RelayArgsInterface` (config aceita por
+ * `CreateRelayEnvironment`) e `Sink` (interface do Observable Relay).
+ */
+export * from './relayArgsInterface';

package/lib/relayArgsInterface/relayArgsInterface.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview Tipos públicos consumidos pelo `setupRelayEnvironment`
+ * (`RelayArgsInterface`) e pelos seus internals (`Sink`).
+ *
+ * `RelayArgsInterface` é o contrato de configuração de
+ * `CreateRelayEnvironment` — qualquer mudança aqui é parte da API
+ * pública do package.
+ */
+/**
+ * Sink do `Observable` Relay. Implementado pelo runtime do Relay e
+ * passado para o callback de `Observable.create`. Os internals de
+ * fetch/subscription usam essa interface para propagar dados, erros
+ * e completação para a stream.
+ */
+export interface Sink {
+    /** Empurra o próximo valor para a stream. */
+    next(value: any): void;
+    /** Reporta um erro e fecha a stream. */
+    error(error: Error, isUncaughtThrownError?: boolean): void;
+    /** Sinaliza completação normal da stream. */
+    complete(): void;
+    /** `true` quando a stream já foi fechada (sink complete/error). */
+    readonly closed: boolean;
+}
+/**
+ * Configuração aceita pelo construtor de `CreateRelayEnvironment`.
+ *
+ * Apenas `url` é obrigatório. Todos os demais campos têm defaults
+ * sensatos definidos no construtor.
+ *
+ * @see {@link "../setupRelayEnvironment/setupRelayEnvironment"} para os defaults.
+ */
+export interface RelayArgsInterface {
+    /**
+     * Endpoint HTTP do servidor GraphQL. Obrigatório.
+     */
+    url: string;
+    /**
+     * Endpoint do servidor de autenticação. Usado pelo fluxo de
+     * verificação de sessão (`${authUrl}user/me`). Obrigatório quando
+     * `useAuthorization` é `true`.
+     */
+    authUrl?: string;
+    /**
+     * Endpoint WebSocket para subscriptions GraphQL. Obrigatório quando
+     * `useSubscription` é `true`.
+     */
+    socket?: string;
+    /**
+     * Lista de delays (ms) entre tentativas de retry, com backoff.
+     *
+     * @defaultValue `[1s, 2s, 3s, 5s, 8s, 13s, 21s, 34s]` (fibonacci-like)
+     */
+    retries?: number[];
+    /**
+     * Timeout por requisição em ms.
+     *
+     * @defaultValue 15 minutos
+     */
+    timeout?: number;
+    /**
+     * Habilita o handler de subscriptions GraphQL via WebSocket.
+     *
+     * @defaultValue false
+     */
+    useSubscription?: boolean;
+    /**
+     * Habilita autenticação via JWT — injeta `Authorization: Bearer <token>`
+     * em cada request usando o `sessionToken` armazenado.
+     *
+     * @defaultValue false
+     */
+    useAuthorization?: boolean;
+    /**
+     * Habilita cache de respostas via `QueryResponseCache` do Relay.
+     * Por recomendação do time do Relay, vem desligado por padrão.
+     *
+     * @defaultValue false
+     */
+    useCache?: boolean;
+    /**
+     * TTL (ms) das entradas do cache de queries.
+     *
+     * @defaultValue 8 minutos
+     */
+    cacheTime?: number;
+    /**
+     * Tamanho máximo do cache (número de queries distintas mantidas).
+     *
+     * @defaultValue 250
+     */
+    cacheSize?: number;
+    /**
+     * Nome da chave usada em storage para o token de sessão (JWT).
+     *
+     * @defaultValue `'USER_SESSION_TOKEN'`
+     */
+    sessionStorageProp?: string;
+    /**
+     * Nome da chave usada em storage para o refresh token.
+     *
+     * @defaultValue `'USER_REFRESH_TOKEN'`
+     */
+    refreshStorageProp?: string;
+    /**
+     * Rota interna para a qual o usuário será redirecionado quando a
+     * sessão expirar (ou em erros de auth, se `redirectOnError` estiver
+     * ligado).
+     *
+     * @defaultValue `'/'`
+     */
+    loginRoute?: string;
+    /**
+     * Liga logs verbosos (útil em desenvolvimento). Não habilite em
+     * produção.
+     *
+     * @defaultValue false
+     */
+    useDebug?: boolean;
+    /**
+     * Habilita retries em caso de erro/timeout, usando os delays de
+     * `retries`.
+     *
+     * @defaultValue false
+     */
+    useRetries?: boolean;
+    /**
+     * Redireciona o usuário para `loginRoute` quando um erro com status
+     * em `authenticationErrors` é detectado e a sessão é considerada
+     * inválida.
+     *
+     * @defaultValue false
+     */
+    redirectOnError?: boolean;
+    /**
+     * Lista de status HTTP que disparam retry (quando `useRetries` é
+     * `true`). Defaults cobrem erros típicos de Cloudflare.
+     *
+     * @defaultValue `[503, 504, 521, 522, 524]`
+     * @see https://support.cloudflare.com/hc/pt-br/articles/115003011431-Solu%C3%A7%C3%A3o-de-problemas-de-erros-5XX-da-Cloudflare
+     */
+    retryWhen?: number[];
+    /**
+     * Status considerados como erro de autenticação para o fluxo de
+     * `redirectOnError`.
+     *
+     * @defaultValue `[401, 403]`
+     */
+    authenticationErrors?: number[];
+    /**
+     * Estratégia de storage no browser para tokens.
+     *
+     * @defaultValue `'localStorage'`
+     */
+    storageType?: 'cookie' | 'localStorage';
+    /**
+     * Identificador de parceiro enviado em todas as requests via
+     * header `X-Partner`. Útil para tenants/whitelabels.
+     *
+     * @defaultValue undefined
+     */
+    partner?: string;
+}

package/lib/setupRelayEnvironment/executeEnvironment.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Detecção de ambiente de execução (browser/DOM,
+ * Worker, viewport) usada por `setupRelayEnvironment` para alternar
+ * comportamento entre browser e SSR.
+ *
+ * Não exposto pelo barrel raiz — implementação interna de
+ * `CreateRelayEnvironment`.
+ */
+/**
+ * Conjunto de flags booleanas indicando capacidades do ambiente atual.
+ * Inspirado no antigo `fbjs/ExecutionEnvironment`. Usado para evitar
+ * dependências circulares e permitir que o código reaja a SSR sem
+ * importar React diretamente.
+ */
+declare const _default: {
+    /** `true` em browsers. */
+    canUseDOM: boolean;
+    /** `true` se `Worker` está disponível globalmente. */
+    canUseWorkers: boolean;
+    /** `true` em browsers que suportam `addEventListener` ou IE `attachEvent`. */
+    canUseEventListeners: boolean;
+    /** `true` em browsers com `window.screen` (viewport mensurável). */
+    canUseViewport: boolean;
+    /** `true` quando rodando em um Worker (sem DOM). */
+    isInWorker: boolean;
+};
+export default _default;

package/lib/setupRelayEnvironment/fetchQuery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Fábrica da `fetchFn` do Relay usada por
+ * `setupRelayEnvironment`. Encapsula cache de respostas, retries via
+ * `fetchWithRetries`, tratamento de erros (incluindo redirect em caso
+ * de sessão expirada) e adaptação para o modelo `Observable` que o
+ * `Network.create` do Relay espera.
+ *
+ * Não exposto pelo barrel raiz — implementação interna de
+ * `CreateRelayEnvironment`.
+ */
+import { CacheConfig, Observable, RequestParameters, UploadableMap, Variables } from 'relay-runtime';
+/**
+ * Cria a fetch function que será passada para `Network.create` do Relay.
+ *
+ * Comportamento:
+ * - Para queries com `useCache` ligado, tenta servir do cache
+ *   (`QueryResponseCache`) antes de fazer a requisição.
+ * - Para mutations com `useCache` ligado, limpa o cache (invalidação
+ *   total — Relay vai re-buscar queries afetadas).
+ * - Em caso de erro de autenticação detectado, chama o endpoint
+ *   `${authUrl}user/me` e, se inválido, limpa storage e redireciona
+ *   para `loginRoute`.
+ * - Erros são propagados via `sink.error()`.
+ *
+ * @param config - Instância de `CreateRelayEnvironment` configurada.
+ * @returns Função compatível com `Network.create(fetchFn, ...)`.
+ */
+export declare const createFetchFunction: (config: any) => (request: RequestParameters, variables: Variables, cacheConfig: CacheConfig, uploadables: UploadableMap) => Observable<unknown>;

package/lib/setupRelayEnvironment/fetchWithRetries.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Implementação de `fetch` com retries e timeout, usada
+ * internamente por `fetchQuery` no `setupRelayEnvironment`.
+ *
+ * Adiciona em cima do `fetch` nativo:
+ * - timeout por requisição (`AbortController`);
+ * - retry com delays configuráveis (`retries` no config) quando o
+ *   status HTTP está em `retryWhen` ou houve timeout;
+ * - debug logs opcionais via `useDebug`.
+ *
+ * Não exposto pelo barrel raiz — implementação interna de
+ * `CreateRelayEnvironment`.
+ */
+/**
+ * Subconjunto de `RequestInit` aceito por `fetchWithRetries`. Mantemos
+ * apenas os campos efetivamente repassados ao `fetch` nativo.
+ */
+export type InitWithRetries = {
+    body?: BodyInit | null;
+    cache?: RequestCache;
+    credentials?: RequestCredentials;
+    headers?: HeadersInit;
+    method?: string;
+    mode?: RequestMode;
+};
+/**
+ * Cria uma função `fetch` configurada com timeout e retries.
+ *
+ * Comportamento:
+ * - Cada tentativa tem timeout de `config.timeout` ms (via `AbortController`).
+ * - Se houver timeout ou o status estiver em `config.retryWhen`, agenda
+ *   a próxima tentativa com o delay correspondente em `config.retries`.
+ * - Retries só ocorrem quando há DOM disponível e `config.useRetries`
+ *   é `true` — no SSR a primeira tentativa é a única.
+ * - Erros não relacionados a `AbortError` são rejeitados imediatamente.
+ *
+ * @param config - Configuração do environment (timeout, retries,
+ *   retryWhen, useRetries, useDebug, url).
+ * @returns Função que recebe `RequestInit` e retorna `Promise<Response>`.
+ */
+export declare function fetchWithRetries(config: any): (init?: InitWithRetries | null) => Promise<any>;

package/lib/setupRelayEnvironment/setupRelayEnvironment.d.ts

@@ -0,0 +1,128 @@
+import { Environment } from 'relay-runtime';
+import { RelayArgsInterface } from '../relayArgsInterface';
+declare const kMountEnvironment: unique symbol;
+declare const kFeetchHandler: unique symbol;
+declare const kSubscriptionHandler: unique symbol;
+/**
+ * Fábrica de `Environment` Relay com bateria inclusa: autenticação JWT,
+ * retries com backoff, suporte a subscriptions via WebSocket, cache de
+ * respostas e estratégia plugável de storage (localStorage ou cookie).
+ *
+ * Esta classe encapsula a configuração que normalmente precisaria ser
+ * escrita à mão para cada projeto que usa Relay: criar `Network`,
+ * `RecordSource`, `Store`, configurar `fetch` com retries/timeout,
+ * adicionar headers de autenticação, lidar com redirecionamento em caso
+ * de sessão expirada e opcionalmente registrar um handler de
+ * subscriptions GraphQL.
+ *
+ * A instância exposta possui a propriedade pública `Environment`, que é
+ * o objeto que deve ser passado para `react-relay` (via `RelayEnvironmentProvider`
+ * ou `QueryRenderer`).
+ *
+ * @example Setup mínimo
+ * ```ts
+ * import { CreateRelayEnvironment } from '@apollion-dsi/relay';
+ *
+ * const { Environment } = new CreateRelayEnvironment({
+ *   url: 'https://api.example.com/graphql/',
+ * });
+ * ```
+ *
+ * @example Com auth JWT e retries
+ * ```ts
+ * const { Environment } = new CreateRelayEnvironment({
+ *   url: 'https://api.example.com/graphql/',
+ *   authUrl: 'https://api.example.com/auth/',
+ *   useAuthorization: true,
+ *   useRetries: true,
+ *   retries: [1000, 2000, 5000],
+ * });
+ * ```
+ *
+ * @example Com subscriptions
+ * ```ts
+ * const { Environment } = new CreateRelayEnvironment({
+ *   url: 'https://api.example.com/graphql/',
+ *   socket: 'wss://api.example.com/graphql/',
+ *   useSubscription: true,
+ * });
+ * ```
+ *
+ * @see {@link RelayArgsInterface} para a lista completa de opções de configuração.
+ */
+export default class RelayEnvironment implements RelayArgsInterface {
+    /** Endpoint HTTP do servidor GraphQL. Obrigatório. */
+    url: string;
+    /** Endpoint do servidor de autenticação. Obrigatório quando `useAuthorization` é `true`. */
+    authUrl?: string;
+    /** Endpoint WebSocket para subscriptions. Obrigatório quando `useSubscription` é `true`. */
+    socket?: string;
+    /** Lista de delays (ms) entre tentativas, quando `useRetries` é `true`. */
+    retries?: number[];
+    /** Timeout (ms) por requisição. */
+    timeout?: number;
+    /** Habilita subscriptions GraphQL via WebSocket. */
+    useSubscription?: boolean;
+    /** Habilita injeção do header `Authorization: Bearer <token>` em cada request. */
+    useAuthorization?: boolean;
+    /** Habilita cache de respostas (via `QueryResponseCache` do Relay). */
+    useCache?: boolean;
+    /** TTL (ms) das entradas do cache. */
+    cacheTime?: number;
+    /** Tamanho máximo do cache (número de queries). */
+    cacheSize?: number;
+    /** Nome da chave em storage usada para guardar o token de sessão. */
+    sessionStorageProp?: string;
+    /** Nome da chave em storage usada para guardar o refresh token. */
+    refreshStorageProp?: string;
+    /** Rota usada para redirecionar o usuário em caso de sessão expirada. */
+    loginRoute?: string;
+    /** Liga logs de debug (útil em desenvolvimento). */
+    useDebug?: boolean;
+    /** Habilita o mecanismo de retries em caso de erro/timeout. */
+    useRetries?: boolean;
+    /** Redireciona automaticamente para `loginRoute` em caso de erro de auth. */
+    redirectOnError?: boolean;
+    /** Lista de status HTTP que disparam retry (quando `useRetries` é `true`). */
+    retryWhen?: number[];
+    /** Status HTTP considerados como erros de autenticação (default: 401, 403). */
+    authenticationErrors?: number[];
+    /** Estratégia de storage no browser. */
+    storageType: 'cookie' | 'localStorage';
+    /** Identificador opcional do parceiro, enviado no header `X-Partner`. */
+    partner?: string;
+    /**
+     * Função de fetch montada para uso pelo `Network` do Relay. Interno.
+     */
+    private [kFeetchHandler]?;
+    /**
+     * Função de subscription montada para uso pelo `Network` do Relay. Interno.
+     */
+    private [kSubscriptionHandler]?;
+    /**
+     * Handler de storage. Expõe métodos `getTokens`, `setTokens`, `clear`,
+     * `hasChangedSession`. Use diretamente quando precisar manipular tokens
+     * fora do fluxo padrão (ex: tela de login).
+     */
+    StorageHandler: any;
+    /**
+     * Instância de `Environment` do `relay-runtime` pronta para uso com
+     * `RelayEnvironmentProvider` (`react-relay`).
+     */
+    Environment: Environment;
+    /**
+     * @param config - Configuração da instância. Veja {@link RelayArgsInterface}.
+     * Apenas `url` é obrigatório; demais opções têm defaults sensatos.
+     *
+     * @throws {Error} Se `url` não for informado.
+     * @throws {Error} Se `useAuthorization` for `true` e `authUrl` não for informado.
+     * @throws {Error} Se `useSubscription` for `true` e `socket` não for informado.
+     */
+    constructor(config: RelayArgsInterface);
+    /**
+     * Monta o `Environment` Relay a partir da fetch function e subscription
+     * handler configurados. Chamado uma única vez pelo construtor.
+     */
+    private [kMountEnvironment];
+}
+export {};

package/lib/setupRelayEnvironment/setupRelayEnvironment.helpers.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Helpers internos usados por `setupRelayEnvironment` para
+ * montar a Network do Relay: detecção do tipo de operação, construção do
+ * body/headers da requisição, parse de respostas (incluindo
+ * `multipart/mixed` para `@defer`/`@stream`), redirecionamento em erro
+ * de auth e constantes de tempo.
+ *
+ * Não exposto pelo barrel raiz — faz parte da implementação interna de
+ * `CreateRelayEnvironment`.
+ */
+import { CacheConfig, RequestParameters, UploadableMap, Variables } from 'relay-runtime';
+import { RelayArgsInterface, Sink } from '../relayArgsInterface';
+/** Verdadeiro se a operação Relay é uma mutation. */
+export declare const isMutation: (request: RequestParameters) => boolean;
+/** Verdadeiro se a operação Relay é uma query. */
+export declare const isQuery: (request: RequestParameters) => boolean;
+/** Verdadeiro quando o consumidor pediu `force: true` no `CacheConfig` (bypass do cache). */
+export declare const forceFetch: (cacheConfig: CacheConfig) => boolean;
+/**
+ * Retorna o delimitador (`?` ou `&`) apropriado para anexar query params
+ * à URL atual do browser. Retorna string vazia em ambientes sem DOM (SSR).
+ */
+export declare const getParamsDelimiter: () => string;
+/**
+ * Retorna o `pathname` atual do browser, ou string vazia em ambientes
+ * sem DOM (SSR).
+ */
+export declare const getBrowserLocation: () => string;
+/**
+ * Redireciona o usuário para `redirectTo`, preservando a URL atual em
+ * `?redirect=` (para o fluxo de login redirecionar de volta).
+ *
+ * Não adiciona o parâmetro `redirect` quando a URL atual já é igual ao
+ * destino ou quando o destino é a própria `loginRoute`.
+ *
+ * @param url - URL atual (origem do redirect).
+ * @param redirectTo - Destino do redirect.
+ * @param config - Configuração do environment (usada para checar `loginRoute`).
+ */
+export declare const redirectUser: (url: string, redirectTo: string, config?: RelayArgsInterface) => void;
+/**
+ * Constrói o body da requisição GraphQL — multipart se há uploadables,
+ * JSON caso contrário.
+ *
+ * @param request - Parâmetros da requisição Relay.
+ * @param variables - Variáveis da operação.
+ * @param uploadables - Arquivos para upload (opcional).
+ */
+export declare function getRequestBody(request: RequestParameters, variables: Variables, uploadables?: UploadableMap): string | FormData;
+/**
+ * Monta os headers HTTP da requisição. Para uploads, usa `Accept: *\/*`
+ * e deixa o browser definir o `Content-Type` com boundary. Para JSON,
+ * usa `application/json` em ambos.
+ *
+ * Quando `useAuthorization` está ligado e existe um `sessionToken` em
+ * storage, anexa `Authorization: Bearer <token>` — exceto quando o
+ * usuário está na própria rota de login (para evitar loops).
+ *
+ * Se um `partner` está configurado, adiciona o header `X-Partner`.
+ */
+export declare const getHeaders: (args: any, uploadables?: UploadableMap) => HeadersInit;
+/**
+ * Lê o `Response` do fetch e empurra os dados para o `Sink` do Relay.
+ *
+ * Suporta três modos:
+ * - `multipart/mixed` (usado por `@defer` e `@stream`): lê o stream
+ *   chunk a chunk e usa `PatchResolver` para repassar cada patch.
+ * - `application/json`: parseia o JSON inteiro e chama `callback`.
+ * - Outros: lê como texto e empurra como array de strings.
+ *
+ * Copiado da biblioteca `fetch-multipart-graphql` com adaptações para o
+ * `Sink` Relay.
+ */
+export declare const handleData: (response: Response, sink: Sink, callback: (data: any) => void) => void;
+/** Constante de tempo: 1 segundo em milissegundos. */
+export declare const ONE_SECOND = 1000;
+/** Constante de tempo: 1 minuto em milissegundos. */
+export declare const ONE_MINUTE: number;

package/lib/setupRelayEnvironment/storage.d.ts

@@ -0,0 +1,59 @@
+import { RelayArgsInterface } from '../relayArgsInterface';
+/** Par de tokens armazenado. */
+type TokenTypes = {
+    sessionToken?: string;
+    refreshToken?: string;
+};
+declare const kStorageHandler: unique symbol;
+declare const kPropSession: unique symbol;
+declare const kPropRefresh: unique symbol;
+/**
+ * Handler de storage usado por `CreateRelayEnvironment`. Encapsula a
+ * estratégia escolhida (`storageType`) e padroniza a manipulação de
+ * `sessionToken` e `refreshToken` por trás de uma API estável.
+ *
+ * @example
+ * ```ts
+ * const { StorageHandler } = new CreateRelayEnvironment({ ... });
+ * StorageHandler.setTokens({ sessionToken: 't', refreshToken: 'r' });
+ * const { sessionToken } = StorageHandler.getTokens();
+ * StorageHandler.clear();
+ * ```
+ */
+export default class StorageClass {
+    private [kStorageHandler];
+    private [kPropSession];
+    private [kPropRefresh];
+    /**
+     * @param strategy - Instância de `CreateRelayEnvironment` (que
+     *   implementa `RelayArgsInterface`). Os campos lidos são
+     *   `storageType`, `sessionStorageProp`, `refreshStorageProp`.
+     */
+    constructor(strategy: RelayArgsInterface);
+    /**
+     * Lê os tokens atualmente armazenados.
+     *
+     * @returns Objeto com `sessionToken` e `refreshToken` (podem ser
+     *   `undefined` quando ausentes).
+     */
+    getTokens(): TokenTypes;
+    /**
+     * Grava ambos os tokens em storage. Use após receber resposta de
+     * login/refresh.
+     */
+    setTokens(tokens: TokenTypes): void;
+    /**
+     * Remove ambos os tokens do storage. Usado em logout ou ao detectar
+     * sessão expirada.
+     */
+    clear(): void;
+    /**
+     * Compara um novo `sessionToken` com o atualmente armazenado.
+     *
+     * @param tokens - Objeto contendo o novo `sessionToken` (vindo, por
+     *   exemplo, de um header de resposta).
+     * @returns `true` se o token mudou.
+     */
+    hasChangedSession({ sessionToken: newSessionToken }: TokenTypes): boolean;
+}
+export {};

package/lib/setupRelayEnvironment/subscriptionHandler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Fábrica do subscription handler GraphQL via WebSocket,
+ * usada por `setupRelayEnvironment` quando `useSubscription` está
+ * habilitado.
+ *
+ * Baseado em `graphql-ws` (protocolo `graphql-transport-ws`).
+ *
+ * Não exposto pelo barrel raiz — implementação interna de
+ * `CreateRelayEnvironment`.
+ */
+/**
+ * Monta a subscription function para o `Network.create` do Relay.
+ *
+ * Retorna uma função (a ser chamada uma vez, no setup do Environment)
+ * que por sua vez retorna a subscribe function que o Relay vai invocar
+ * para cada subscription operation. A adaptação de callbacks
+ * `next/error/complete` do `graphql-ws` para o `Sink` do Observable
+ * Relay é feita aqui.
+ *
+ * @param settings - Objeto com a URL do endpoint WebSocket (`socket`).
+ *   Quando `useSubscription` é `true` mas `socket` não foi configurado,
+ *   o construtor de `CreateRelayEnvironment` lança erro antes desta
+ *   função ser chamada.
+ * @returns Função que, quando invocada, retorna a subscribe function
+ *   compatível com `Network.create(fetchFn, subscribeFn)`.
+ */
+export declare function setupSubscription(settings: {
+    socket?: string;
+}): () => any;

package/lib/useEnvironment/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Barrel público do módulo `useEnvironment`.
+ *
+ * Reexporta o hook `useEnvironment` e o componente `EnvironmentProvider`,
+ * para que consumidores possam importar via
+ * `@apollion-dsi/relay/useEnvironment` (granular) ou via
+ * `@apollion-dsi/relay` (barrel raiz).
+ */
+export * from './useEnvironment';

package/lib/useEnvironment/useEnvironment.d.ts

@@ -0,0 +1,73 @@
+import React from 'react';
+import { Environment } from 'relay-runtime';
+import { MockEnvironment } from 'relay-test-utils';
+/**
+ * Estado interno do Context: contém apenas o `Environment` Relay
+ * (real ou mockado em testes).
+ */
+type StateType = {
+    environment: Environment | MockEnvironment;
+};
+/**
+ * Props do `EnvironmentProvider`.
+ */
+type EnvironmentProviderInterface = {
+    children: React.ReactNode;
+} & StateType;
+/**
+ * Provider que injeta o `Environment` Relay na árvore React via Context.
+ *
+ * Em produção, passe a propriedade `Environment` exposta por
+ * `CreateRelayEnvironment`. Em testes, passe um `MockEnvironment` de
+ * `relay-test-utils` para facilitar a substituição do backend.
+ *
+ * @example
+ * ```tsx
+ * import { CreateRelayEnvironment, EnvironmentProvider } from '@apollion-dsi/relay';
+ *
+ * const { Environment } = new CreateRelayEnvironment({ url: '...' });
+ *
+ * function App() {
+ *   return (
+ *     <EnvironmentProvider environment={Environment}>
+ *       <Routes />
+ *     </EnvironmentProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Em testes
+ * ```tsx
+ * import { createMockEnvironment } from 'relay-test-utils';
+ *
+ * const mock = createMockEnvironment();
+ * render(
+ *   <EnvironmentProvider environment={mock}>
+ *     <SubjectUnderTest />
+ *   </EnvironmentProvider>
+ * );
+ * ```
+ */
+declare function EnvironmentProvider({ children, environment }: EnvironmentProviderInterface): React.JSX.Element;
+/**
+ * Hook para acessar o `Environment` Relay corrente.
+ *
+ * Deve ser usado dentro de um `EnvironmentProvider`. Lança erro
+ * descritivo caso seja chamado fora dele ou se nenhum environment
+ * tenha sido fornecido — falhas silenciosas aqui geralmente viram
+ * "loading infinito" no Relay, então preferimos falhar cedo.
+ *
+ * @returns Objeto com a propriedade `environment`.
+ * @throws {Error} Quando usado fora de `EnvironmentProvider` ou quando
+ *   o environment fornecido é `null`/`undefined`.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { environment } = useEnvironment();
+ *   // ...
+ * }
+ * ```
+ */
+declare function useEnvironment(): StateType;
+export { EnvironmentProvider, useEnvironment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apollion-dsi/relay",
-  "version": "0.25.10",
+  "version": "0.26.0",
   "description": "Frontend services regarding Relay Environment",
   "main": "lib/index.js",
   "module": "lib/index.esm.js",
@@ -22,8 +22,7 @@
     "format": "yarn prettier --write",
     "validate": "./scripts/validate.sh",
     "validate:tests": "jest --coverage",
-    "build": "node ./esbuild",
-    "postbuild": "tsc --emitDeclarationOnly",
+    "build": "node -e \"require('fs').rmSync('./lib',{recursive:true,force:true})\" && node ./esbuild && tsc --emitDeclarationOnly",
     "test": "yarn validate",
     "code:check": "yarn lint && yarn coverage"
   },
@@ -32,16 +31,16 @@
   },
   "dependencies": {
     "fetch-multipart-graphql": "2.3.1",
-    "graphql": "15.10.1",
+    "graphql": "16.14.2",
     "graphql-ws": "6.0.8",
     "js-cookie": "3.0.7",
     "nanoid": "5.1.11",
-    "react-relay": "20.1.1",
-    "relay-runtime": "20.1.1",
-    "relay-test-utils": "20.1.1"
+    "react-relay": "21.0.1",
+    "relay-runtime": "21.0.1",
+    "relay-test-utils": "21.0.1"
   },
   "devDependencies": {
-    "@apollion-dsi/eslint-config": "0.7.0",
+    "@apollion-dsi/eslint-config": "0.8.0",
     "@babel/core": "7.29.0",
     "@babel/plugin-transform-class-properties": "7.27.1",
     "@babel/plugin-transform-runtime": "7.29.0",
@@ -59,12 +58,12 @@
     "@types/relay-runtime": "20.1.1",
     "@types/relay-test-utils": "19.0.0",
     "babel-jest": "30.4.1",
-    "babel-plugin-relay": "20.1.1",
+    "babel-plugin-relay": "21.0.1",
     "esbuild": "0.28.0",
     "eslint": "9.29.0",
     "express": "4.22.2",
-    "express-graphql": "0.12.0",
-    "graphql-relay": "0.9.0",
+    "graphql-http": "1.22.4",
+    "graphql-relay": "0.10.2",
     "isomorphic-fetch": "3.0.0",
     "jest": "30.4.2",
     "jest-environment-jsdom": "30.4.1",
@@ -72,7 +71,7 @@
     "prettier": "3.8.3",
     "react": "19.2.6",
     "react-dom": "19.2.6",
-    "relay-compiler": "20.1.1",
+    "relay-compiler": "21.0.1",
     "typescript": "6.0.3"
   }
 }