@apollion-dsi/relay 0.27.2 → 0.28.0

package/lib/relayArgsInterface/index.esm.js

@@ -0,0 +1 @@
+import"../chunks/chunk-FYOI5Q5V.esm.js";

package/lib/relayArgsInterface/relayArgsInterface.d.ts

@@ -1,207 +1,234 @@
 /**
- * @fileoverview Tipos públicos consumidos pelo `setupRelayEnvironment`
- * (`RelayArgsInterface`) e pelos seus internals (`Sink`).
+ * @fileoverview Public types consumed by `setupRelayEnvironment`
+ * (`RelayArgsInterface`) and by its internals (`Sink`).
  *
- * `RelayArgsInterface` é o contrato de configuração de
- * `CreateRelayEnvironment` — qualquer mudança aqui é parte da API
- * pública do package.
+ * `RelayArgsInterface` is the configuration contract of
+ * `CreateRelayEnvironment` — any change here is part of the package's
+ * public API.
  */
 /**
- * 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.
+ * Relay `Observable` sink. Implemented by the Relay runtime and
+ * passed to the `Observable.create` callback. The fetch/subscription
+ * internals use this interface to propagate data, errors
+ * and completion to the stream.
  */
 export interface Sink {
-    /** Empurra o próximo valor para a stream. */
+    /** Pushes the next value into the stream. */
     next(value: any): void;
-    /** Reporta um erro e fecha a stream. */
+    /** Reports an error and closes the stream. */
     error(error: Error, isUncaughtThrownError?: boolean): void;
-    /** Sinaliza completação normal da stream. */
+    /** Signals normal stream completion. */
     complete(): void;
-    /** `true` quando a stream já foi fechada (sink complete/error). */
+    /** `true` when the stream has already been closed (sink complete/error). */
     readonly closed: boolean;
 }
 /**
- * Configuração aceita pelo construtor de `CreateRelayEnvironment`.
+ * Configuration accepted by the `CreateRelayEnvironment` constructor.
  *
- * Apenas `url` é obrigatório. Todos os demais campos têm defaults
- * sensatos definidos no construtor.
+ * Only `url` is required. All the other fields have sensible defaults
+ * defined in the constructor.
  *
- * @see {@link "../setupRelayEnvironment/setupRelayEnvironment"} para os defaults.
+ * @see {@link "../setupRelayEnvironment/setupRelayEnvironment"} for the defaults.
  */
 export interface RelayArgsInterface {
     /**
-     * Endpoint HTTP do servidor GraphQL. Obrigatório.
+     * HTTP endpoint of the GraphQL server. Required.
      */
     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`.
+     * Authentication server endpoint. Used by the session verification
+     * flow (`${authUrl}user/me`). Required when
+     * `useAuthorization` is `true`.
      */
     authUrl?: string;
     /**
-     * Endpoint WebSocket para subscriptions GraphQL. Obrigatório quando
-     * `useSubscription` é `true`.
+     * WebSocket endpoint for GraphQL subscriptions. Required when
+     * `useSubscription` is `true`.
      */
     socket?: string;
     /**
-     * Lista de delays (ms) entre tentativas de retry, com backoff.
+     * List of delays (ms) between retry attempts, with backoff.
      *
      * @defaultValue `[1s, 2s, 3s, 5s, 8s, 13s, 21s, 34s]` (fibonacci-like)
      */
     retries?: number[];
     /**
-     * Timeout por requisição em ms.
+     * Per-request timeout in ms.
      *
-     * @defaultValue 15 minutos
+     * @defaultValue 15 minutes
      */
     timeout?: number;
     /**
-     * Habilita o handler de subscriptions GraphQL via WebSocket.
+     * Enables the GraphQL subscriptions handler over WebSocket.
      *
      * @defaultValue false
      */
     useSubscription?: boolean;
     /**
-     * Habilita autenticação via JWT — injeta `Authorization: Bearer <token>`
-     * em cada request usando o `sessionToken` armazenado.
+     * Enables JWT authentication — injects `Authorization: Bearer <token>`
+     * on every request using the stored `sessionToken`.
      *
      * @defaultValue false
      */
     useAuthorization?: boolean;
     /**
-     * Modelo de autenticação usado pelo Environment.
+     * Authentication model used by the Environment.
      *
-     * - `'bearer'` (default, retrocompat): lê o `sessionToken` do storage
-     *   JS-legível e injeta `Authorization: Bearer <token>` em cada request.
-     *   A verificação de sessão usa o probe `${authUrl}user/me`.
-     * - `'cookie'`: modelo de **sessão por cookie httpOnly**. O Environment
-     *   **não** lê o token em JS nem injeta `Authorization` — o cookie de
-     *   sessão (httpOnly + SameSite) viaja sozinho desde que o fetch use
-     *   `credentials` (default `'include'` neste modo). A renovação de
-     *   sessão é disparada por erro de auth (ex: 401) chamando `authUrl`
-     *   com `credentials:'include'`, sem probe a `user/me`.
+     * - `'bearer'` (default, backwards-compatible): reads the `sessionToken`
+     *   from JS-readable storage and injects `Authorization: Bearer <token>`
+     *   on every request. Session verification uses the `${authUrl}user/me` probe.
+     * - `'cookie'`: **httpOnly cookie session** model. The Environment does
+     *   **not** read the token in JS nor inject `Authorization` — the session
+     *   cookie (httpOnly + SameSite) travels on its own as long as the fetch uses
+     *   `credentials` (default `'include'` in this mode). Session renewal
+     *   is triggered by an auth error (e.g. 401) calling `authUrl`
+     *   with `credentials:'include'`, without probing `user/me`.
      *
      * @defaultValue `'bearer'`
      */
     authMode?: 'bearer' | 'cookie';
     /**
-     * Valor de `credentials` repassado aos fetches GraphQL e de
-     * verificação/refresh de sessão. Use `'include'` para que o browser
-     * anexe automaticamente cookies httpOnly de sessão (inclusive
+     * `credentials` value forwarded to the GraphQL and session
+     * verification/refresh fetches. Use `'include'` so the browser
+     * automatically attaches httpOnly session cookies (including
      * cross-origin).
      *
-     * Quando não definido: `'include'` no modo `authMode:'cookie'`, e
-     * omitido (default do browser) no modo `'bearer'` — preservando a
-     * retrocompat dos consumidores Bearer existentes.
+     * When not set: `'include'` in `authMode:'cookie'` mode, and
+     * omitted (browser default) in `'bearer'` mode — preserving
+     * backwards compatibility for existing Bearer consumers.
      *
-     * @defaultValue `authMode:'cookie'` → `'include'`; senão omitido.
+     * @defaultValue `authMode:'cookie'` → `'include'`; otherwise omitted.
      */
     credentials?: RequestCredentials;
     /**
-     * URL usada para verificar/renovar a sessão quando um erro de auth é
-     * detectado. Torna o probe configurável/opcional:
+     * URL used to verify/renew the session when an auth error is
+     * detected. Makes the probe configurable/optional:
      *
-     * - `string` — sobrescreve a URL padrão do probe.
-     * - `false` — **desliga** o probe; um erro de auth é tratado como
-     *   logout direto (limpa storage + redireciona para `loginRoute`),
-     *   sem nenhuma requisição extra.
-     * - não definido — usa o default do modo: `${authUrl}user/me` (GET,
-     *   modo `bearer`) ou `authUrl` (POST + `credentials:'include'`, modo
-     *   `cookie`).
+     * - `string` — overrides the default probe URL.
+     * - `false` — **disables** the probe; an auth error is treated as
+     *   a direct logout (clears storage + redirects to `loginRoute`),
+     *   without any extra request.
+     * - not set — uses the mode's default: `${authUrl}user/me` (GET,
+     *   `bearer` mode) or `authUrl` (POST + `credentials:'include'`,
+     *   `cookie` mode).
      *
-     * @defaultValue depende de `authMode` (veja acima).
+     * @defaultValue depends on `authMode` (see above).
      */
     sessionCheckUrl?: string | false;
     /**
-     * Habilita cache de respostas via `QueryResponseCache` do Relay.
-     * Por recomendação do time do Relay, vem desligado por padrão.
+     * Enables response caching via Relay's `QueryResponseCache`.
+     * Per the Relay team's recommendation, it is off by default.
      *
      * @defaultValue false
      */
     useCache?: boolean;
     /**
-     * TTL (ms) das entradas do cache de queries.
+     * TTL (ms) of the query cache entries.
      *
-     * @defaultValue 8 minutos
+     * @defaultValue 8 minutes
      */
     cacheTime?: number;
     /**
-     * Tamanho máximo do cache (número de queries distintas mantidas).
+     * Maximum cache size (number of distinct queries kept).
      *
      * @defaultValue 250
      */
     cacheSize?: number;
     /**
-     * Nome da chave usada em storage para o token de sessão (JWT).
+     * Storage key name for the session token (JWT).
      *
      * @defaultValue `'USER_SESSION_TOKEN'`
      */
     sessionStorageProp?: string;
     /**
-     * Nome da chave usada em storage para o refresh token.
+     * Storage key name for the 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).
+     * Internal route the user is redirected to when the
+     * session expires (or on auth errors, if `redirectOnError` is
+     * enabled).
      *
      * @defaultValue `'/'`
      */
     loginRoute?: string;
     /**
-     * Liga logs verbosos (útil em desenvolvimento). Não habilite em
-     * produção.
+     * Turns on verbose logs (useful in development). Do not enable in
+     * production.
      *
      * @defaultValue false
      */
     useDebug?: boolean;
     /**
-     * Habilita retries em caso de erro/timeout, usando os delays de
+     * Enables retries on error/timeout, using the delays from
      * `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.
+     * Redirects the user to `loginRoute` when an error with a status
+     * in `authenticationErrors` is detected and the session is considered
+     * invalid.
      *
      * @defaultValue false
      */
     redirectOnError?: boolean;
     /**
-     * Lista de status HTTP que disparam retry (quando `useRetries` é
-     * `true`). Defaults cobrem erros típicos de Cloudflare.
+     * List of HTTP statuses that trigger a retry (when `useRetries` is
+     * `true`). Defaults cover typical Cloudflare errors.
      *
      * @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`.
+     * Statuses treated as authentication errors for the
+     * `redirectOnError` flow.
      *
      * @defaultValue `[401, 403]`
      */
     authenticationErrors?: number[];
     /**
-     * Estratégia de storage no browser para tokens.
+     * Browser storage strategy for tokens.
      *
      * @defaultValue `'localStorage'`
      */
     storageType?: 'cookie' | 'localStorage';
     /**
-     * Identificador de parceiro enviado em todas as requests via
-     * header `X-Partner`. Útil para tenants/whitelabels.
+     * Partner identifier sent on every request via the
+     * `X-Partner` header. Useful for tenants/whitelabels.
      *
      * @defaultValue undefined
      */
     partner?: string;
+    /**
+     * Enables **persisted queries**: the request carries only the
+     * operation hash generated at build time by `relay-compiler`
+     * (`persistConfig`) plus the variables — the GraphQL text never
+     * leaves the build.
+     *
+     * The server must hold the matching query map (hash → text) and
+     * accept the hash in the field named by `persistedOperationField`
+     * — in the JSON body for queries/mutations, or in
+     * `payload.extensions` for subscriptions over `graphql-ws`.
+     *
+     * Requires the consumer's `relay.config.json` to define
+     * `persistConfig` — with the flag on, an artifact without an `id`
+     * (compiler ran without `persistConfig`) throws a descriptive error
+     * instead of silently sending nothing.
+     *
+     * @defaultValue false
+     */
+    usePersistedQueries?: boolean;
+    /**
+     * Name of the request field that carries the persisted-operation
+     * hash when `usePersistedQueries` is on. Lets the client match
+     * whatever field the server's allowlist middleware expects.
+     *
+     * @defaultValue `'doc_id'`
+     */
+    persistedOperationField?: string;
 }

package/lib/setupRelayEnvironment/executeEnvironment.d.ts

@@ -1,27 +1,27 @@
 /**
- * @fileoverview Detecção de ambiente de execução (browser/DOM,
- * Worker, viewport) usada por `setupRelayEnvironment` para alternar
- * comportamento entre browser e SSR.
+ * @fileoverview Execution environment detection (browser/DOM,
+ * Worker, viewport) used by `setupRelayEnvironment` to switch
+ * behavior between browser and SSR.
  *
- * Não exposto pelo barrel raiz — implementação interna de
+ * Not exposed by the root barrel — internal implementation of
  * `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.
+ * Set of boolean flags indicating the current environment's capabilities.
+ * Inspired by the old `fbjs/ExecutionEnvironment`. Used to avoid
+ * circular dependencies and let code react to SSR without
+ * importing React directly.
  */
 declare const _default: {
-    /** `true` em browsers. */
+    /** `true` in browsers. */
     canUseDOM: boolean;
-    /** `true` se `Worker` está disponível globalmente. */
+    /** `true` if `Worker` is globally available. */
     canUseWorkers: boolean;
-    /** `true` em browsers que suportam `addEventListener` ou IE `attachEvent`. */
+    /** `true` in browsers supporting `addEventListener` or IE `attachEvent`. */
     canUseEventListeners: boolean;
-    /** `true` em browsers com `window.screen` (viewport mensurável). */
+    /** `true` in browsers with `window.screen` (measurable viewport). */
     canUseViewport: boolean;
-    /** `true` quando rodando em um Worker (sem DOM). */
+    /** `true` when running in a Worker (no DOM). */
     isInWorker: boolean;
 };
 export default _default;

package/lib/setupRelayEnvironment/fetchQuery.d.ts

@@ -1,29 +1,29 @@
 /**
- * @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.
+ * @fileoverview Factory for the Relay `fetchFn` used by
+ * `setupRelayEnvironment`. Encapsulates response caching, retries via
+ * `fetchWithRetries`, error handling (including redirect when the
+ * session expires) and the adaptation to the `Observable` model that
+ * Relay's `Network.create` expects.
  *
- * Não exposto pelo barrel raiz — implementação interna de
+ * Not exposed by the root barrel — internal implementation of
  * `CreateRelayEnvironment`.
  */
 import { CacheConfig, Observable, RequestParameters, UploadableMap, Variables } from 'relay-runtime';
 /**
- * Cria a fetch function que será passada para `Network.create` do Relay.
+ * Creates the fetch function that will be passed to Relay's `Network.create`.
  *
- * 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, verifica/renova a sessão
- *   (modo bearer: probe `${authUrl}user/me`; modo cookie httpOnly:
- *   refresh em `authUrl` com `credentials:'include'`) e, se inválida,
- *   limpa storage e redireciona para `loginRoute`.
- * - Erros são propagados via `sink.error()`.
+ * Behavior:
+ * - For queries with `useCache` on, tries to serve from the cache
+ *   (`QueryResponseCache`) before making the request.
+ * - For mutations with `useCache` on, clears the cache (full
+ *   invalidation — Relay will re-fetch affected queries).
+ * - When an authentication error is detected, verifies/renews the session
+ *   (bearer mode: `${authUrl}user/me` probe; httpOnly cookie mode:
+ *   refresh at `authUrl` with `credentials:'include'`) and, if invalid,
+ *   clears storage and redirects to `loginRoute`.
+ * - Errors are propagated via `sink.error()`.
  *
- * @param config - Instância de `CreateRelayEnvironment` configurada.
- * @returns Função compatível com `Network.create(fetchFn, ...)`.
+ * @param config - Configured `CreateRelayEnvironment` instance.
+ * @returns Function compatible with `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

@@ -1,19 +1,19 @@
 /**
- * @fileoverview Implementação de `fetch` com retries e timeout, usada
- * internamente por `fetchQuery` no `setupRelayEnvironment`.
+ * @fileoverview `fetch` implementation with retries and timeout, used
+ * internally by `fetchQuery` in `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`.
+ * Adds on top of the native `fetch`:
+ * - per-request timeout (`AbortController`);
+ * - retry with configurable delays (`retries` in the config) when the
+ *   HTTP status is in `retryWhen` or a timeout occurred;
+ * - optional debug logs via `useDebug`.
  *
- * Não exposto pelo barrel raiz — implementação interna de
+ * Not exposed by the root barrel — internal implementation of
  * `CreateRelayEnvironment`.
  */
 /**
- * Subconjunto de `RequestInit` aceito por `fetchWithRetries`. Mantemos
- * apenas os campos efetivamente repassados ao `fetch` nativo.
+ * Subset of `RequestInit` accepted by `fetchWithRetries`. We keep
+ * only the fields actually forwarded to the native `fetch`.
  */
 export type InitWithRetries = {
     body?: BodyInit | null;
@@ -24,18 +24,18 @@ export type InitWithRetries = {
     mode?: RequestMode;
 };
 /**
- * Cria uma função `fetch` configurada com timeout e retries.
+ * Creates a `fetch` function configured with timeout and 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.
+ * Behavior:
+ * - Each attempt has a timeout of `config.timeout` ms (via `AbortController`).
+ * - On timeout, or when the status is in `config.retryWhen`, it schedules
+ *   the next attempt with the corresponding delay in `config.retries`.
+ * - Retries only happen when a DOM is available and `config.useRetries`
+ *   is `true` — in SSR the first attempt is the only one.
+ * - Errors unrelated to `AbortError` are rejected immediately.
  *
- * @param config - Configuração do environment (timeout, retries,
+ * @param config - Environment configuration (timeout, retries,
  *   retryWhen, useRetries, useDebug, url).
- * @returns Função que recebe `RequestInit` e retorna `Promise<Response>`.
+ * @returns Function that takes a `RequestInit` and returns a `Promise<Response>`.
  */
 export declare function fetchWithRetries(config: any): (init?: InitWithRetries | null) => Promise<any>;

package/lib/setupRelayEnvironment/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public barrel for the `setupRelayEnvironment` module.
+ *
+ * Exports only the public surface: the `CreateRelayEnvironment` class
+ * (default export of the `setupRelayEnvironment.ts` file). The internals
+ * `fetchQuery`, `fetchWithRetries`, `storage`, `subscriptionHandler`,
+ * `executeEnvironment` and `setupRelayEnvironment.helpers` stay hidden
+ * — they are part of the implementation and not part of the contract.
+ */
+export { default as CreateRelayEnvironment } from './setupRelayEnvironment';
+export { default } from './setupRelayEnvironment';

package/lib/setupRelayEnvironment/index.esm.js

@@ -0,0 +1 @@
+import{a}from"../chunks/chunk-KIA6YWO5.esm.js";import"../chunks/chunk-GZONWSRB.esm.js";export{a as CreateRelayEnvironment,a as default};