@apollion-dsi/relay 0.27.1 → 0.27.3

package/README.MD

@@ -1,8 +1,8 @@
 # @apollion-dsi/relay
 
-Helpers para configurar e usar **Relay** (`react-relay` / `relay-runtime`)
-no padrão do Apollion DS. Cobre criação de Environment com auth,
-upload multipart, subscriptions via WebSocket e cookies de sessão.
+Helpers to configure and use **Relay** (`react-relay` / `relay-runtime`)
+the Apollion DS way. Covers Environment creation with auth,
+multipart upload, subscriptions via WebSocket, and session cookies.
 
 [![npm](https://img.shields.io/npm/v/@apollion-dsi/relay.svg)](https://www.npmjs.com/package/@apollion-dsi/relay)
 
@@ -13,20 +13,20 @@ upload multipart, subscriptions via WebSocket e cookies de sessão.
 - **graphql** 15.x
 - **graphql-ws** 6.x (subscriptions)
 - **fetch-multipart-graphql** (uploads)
-- **js-cookie** (sessão)
+- **js-cookie** (session)
 
-## Instalação
+## Installation
 
 ```bash
 yarn add @apollion-dsi/relay react@19.2.6
 ```
 
-> Para gerar artefatos Relay, o consumidor também precisa de
-> `relay-compiler` como dev dependency e configurar `relay.config.js`.
+> To generate Relay artifacts, the consumer also needs
+> `relay-compiler` as a dev dependency and a `relay.config.js` setup.
 
-## Uso básico
+## Basic usage
 
-Crie um Relay Environment para a aplicação:
+Create a Relay Environment for the application:
 
 ```ts
 import { CreateRelayEnvironment } from '@apollion-dsi/relay';
@@ -36,7 +36,7 @@ export const { Environment } = new CreateRelayEnvironment({
 });
 ```
 
-Depois, embrulhe a árvore React com `RelayEnvironmentProvider`:
+Then wrap the React tree with `RelayEnvironmentProvider`:
 
 ```tsx
 import { RelayEnvironmentProvider } from 'react-relay';
@@ -48,72 +48,72 @@ import { App } from './app';
 </RelayEnvironmentProvider>;
 ```
 
-## Recursos do helper
+## Helper features
 
-- **Autenticação** em dois modos: `Bearer` (token JS) ou **cookie
-  httpOnly** (ver abaixo).
-- **Multipart uploads** (`fetch-multipart-graphql`) — envie arquivos
-  diretamente em mutations.
+- **Authentication** in two modes: `Bearer` (JS token) or **httpOnly
+  cookie** (see below).
+- **Multipart uploads** (`fetch-multipart-graphql`) — send files
+  directly in mutations.
 - **Subscriptions** via `graphql-ws`.
-- **Network retry / refresh** plugável.
+- Pluggable **network retry / refresh**.
 
-## Autenticação: Bearer vs. cookie httpOnly
+## Authentication: Bearer vs. httpOnly cookie
 
-O Environment suporta dois modelos de auth via `authMode`.
+The Environment supports two auth models via `authMode`.
 
-### `authMode: 'bearer'` (default — retrocompat)
+### `authMode: 'bearer'` (default — backwards compatible)
 
-Lê o `sessionToken` do storage (`localStorage`/`cookie` JS-legível) e
-injeta `Authorization: Bearer <token>` em cada request. A verificação de
-sessão usa o probe `${authUrl}user/me`. Comportamento idêntico ao das
-versões anteriores — consumidores existentes não precisam mudar nada.
+Reads the `sessionToken` from storage (`localStorage`/JS-readable `cookie`) and
+injects `Authorization: Bearer <token>` into every request. Session
+verification uses the `${authUrl}user/me` probe. Behavior is identical to
+previous versions — existing consumers don't need to change anything.
 
 ```ts
 new CreateRelayEnvironment({
   url: 'https://api.example.com/graphql/',
   authUrl: 'https://api.example.com/auth/',
-  useAuthorization: true, // injeta Bearer
-  storageType: 'cookie', // cookie JS-legível ou 'localStorage'
+  useAuthorization: true, // injects Bearer
+  storageType: 'cookie', // JS-readable cookie or 'localStorage'
 });
 ```
 
-### `authMode: 'cookie'` (sessão por cookie httpOnly — recomendado p/ SPA)
+### `authMode: 'cookie'` (httpOnly cookie session — recommended for SPAs)
 
-Modelo seguro: o token de sessão vive num cookie **httpOnly + SameSite**
-(invisível ao JS, imune a XSS). O Environment **não** lê o token nem
-injeta `Authorization` — `credentials: 'include'` (default neste modo)
-faz o browser anexar o cookie automaticamente, inclusive cross-origin.
-Em erro de auth (ex: 401), o refresh é disparado com `POST` em `authUrl`
-e `credentials: 'include'` — **sem** probe a `user/me`.
+The secure model: the session token lives in an **httpOnly + SameSite**
+cookie (invisible to JS, immune to XSS). The Environment does **not** read
+the token or inject `Authorization` — `credentials: 'include'` (the default
+in this mode) makes the browser attach the cookie automatically, including
+cross-origin. On an auth error (e.g. 401), the refresh is fired as a `POST`
+to `authUrl` with `credentials: 'include'` — **without** probing `user/me`.
 
 ```ts
 new CreateRelayEnvironment({
   url: 'https://api.example.com/graphql/',
-  authUrl: 'https://api.example.com/auth/refresh/', // alvo do refresh on-401
+  authUrl: 'https://api.example.com/auth/refresh/', // on-401 refresh target
   authMode: 'cookie',
   redirectOnError: true,
   loginRoute: '/login',
 });
 ```
 
-Opções relacionadas:
+Related options:
 
-| Opção | Default | O que faz |
+| Option | Default | What it does |
 |---|---|---|
-| `authMode` | `'bearer'` | `'bearer'` (token + header) ou `'cookie'` (httpOnly). |
-| `credentials` | cookie→`'include'`; bearer→omitido | `RequestCredentials` repassado aos fetches GraphQL e de refresh. Funciona nos dois modos. |
-| `sessionCheckUrl` | modo-dependente | Sobrescreve a URL do probe; `false` desliga o probe (erro de auth → logout direto, sem request extra). |
+| `authMode` | `'bearer'` | `'bearer'` (token + header) or `'cookie'` (httpOnly). |
+| `credentials` | cookie→`'include'`; bearer→omitted | `RequestCredentials` forwarded to the GraphQL and refresh fetches. Works in both modes. |
+| `sessionCheckUrl` | mode-dependent | Overrides the probe URL; `false` disables the probe (auth error → direct logout, no extra request). |
 
 ## Scripts (workspace)
 
-| Script | O que faz |
+| Script | What it does |
 |---|---|
 | `yarn workspace @apollion-dsi/relay run validate` | Lint + types + prettier + Jest + build. |
 | `yarn workspace @apollion-dsi/relay run coverage` | Jest coverage. |
-| `yarn workspace @apollion-dsi/relay run build` | esbuild + emit de types. |
+| `yarn workspace @apollion-dsi/relay run build` | esbuild + types emit. |
 | `yarn workspace @apollion-dsi/relay run audit-dependencies` | audit-ci. |
-| `yarn workspace @apollion-dsi/relay run pretest` | `relay-compiler` (gera `__generated__` antes dos testes). |
+| `yarn workspace @apollion-dsi/relay run pretest` | `relay-compiler` (generates `__generated__` before the tests). |
 
-## Licença
+## License
 
 MIT.

package/lib/commitMutation/commitMutation.d.ts

@@ -1,27 +1,27 @@
 import { MutationConfig, MutationParameters } from 'relay-runtime';
 import { Environment } from 'relay-runtime/lib/store/RelayStoreTypes';
 /**
- * Wrapper Promise-based em torno do `commitMutation` do `relay-runtime`.
+ * Promise-based wrapper around `relay-runtime`'s `commitMutation`.
  *
- * 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`.
+ * Relay's original `commitMutation` exposes mutation completion via the
+ * `onCompleted` and `onError` callbacks. This function encapsulates those
+ * callbacks in a `Promise`, allowing natural `async/await` usage in the
+ * consumer — which typically covers 95% of the cases. For flows that need
+ * `optimisticResponse`, `updater`, `cacheConfig` etc., all the remaining
+ * `MutationConfig` options are still accepted 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.
+ * The `onCompleted` and `onError` fields are omitted from `config` on purpose:
+ * they are managed internally to feed the Promise's resolve/reject.
  *
- * @typeParam T - Tipo gerado pelo Relay Compiler para a mutação (`graphql`
- * tagged) — fornece o shape de `variables` e `response`.
+ * @typeParam T - Type generated by the Relay Compiler for the mutation
+ * (`graphql` tagged) — provides the shape of `variables` and `response`.
  *
- * @param environment - Ambiente Relay (geralmente o exposto por
+ * @param environment - Relay environment (usually the one exposed by
  * `CreateRelayEnvironment`).
- * @param config - Configuração da mutação, sem `onCompleted` e `onError`.
+ * @param config - Mutation configuration, without `onCompleted` and `onError`.
  *
- * @returns Promise que resolve com `T['response']` ou rejeita com o erro
- * retornado pelo Relay.
+ * @returns Promise that resolves with `T['response']` or rejects with the
+ * error returned by Relay.
  *
  * @example
  * ```tsx

package/lib/commitMutation/index.d.ts

@@ -1,8 +1,8 @@
 /**
- * Barrel público do módulo `commitMutation`.
+ * Public barrel for the `commitMutation` module.
  *
- * 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).
+ * Re-exports the `commitMutation` function so consumers can import it
+ * via `@apollion-dsi/relay/commitMutation` (granular import, avoiding
+ * loading the rest of the package) or via `@apollion-dsi/relay` (root barrel).
  */
 export * from './commitMutation';

package/lib/index.d.ts

@@ -1,15 +1,15 @@
 /**
- * Barrel público do package `@apollion-dsi/relay`.
+ * Public barrel for the `@apollion-dsi/relay` package.
  *
- * 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`.
+ * Re-exports the package's public surface: the Environment factory
+ * (`CreateRelayEnvironment`), the Context/hook (`EnvironmentProvider` /
+ * `useEnvironment`), the configuration types (`RelayArgsInterface`,
+ * `Sink`), the mutation updater utilities and the Promise-based
+ * `commitMutation` wrapper.
  *
- * Cada módulo também pode ser importado de forma granular via
- * `@apollion-dsi/relay/<nome>` quando o consumidor quiser carregar
- * menos código.
+ * Each module can also be imported granularly via
+ * `@apollion-dsi/relay/<name>` when the consumer wants to load
+ * less code.
  */
 export { default as CreateRelayEnvironment } from './setupRelayEnvironment/setupRelayEnvironment';
 export * from './useEnvironment';

package/lib/mutationUtils/index.d.ts

@@ -1,9 +1,9 @@
 /**
- * Barrel público do módulo `mutationUtils`.
+ * Public barrel for the `mutationUtils` module.
  *
- * 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).
+ * Re-exports the helpers for writing Relay mutation `updater`s
+ * (lists, connections, optimistic responses). Importable via
+ * `@apollion-dsi/relay/mutationUtils` (granular) or via
+ * `@apollion-dsi/relay` (root barrel).
  */
 export * from './mutationUtils';

package/lib/mutationUtils/mutationUtils.d.ts

@@ -1,28 +1,28 @@
 /**
- * @fileoverview Utilitários para escrever `updater`s de mutations Relay
- * de forma declarativa, sem precisar manipular `RecordProxy` /
- * `ConnectionHandler` à mão em cada caso comum.
+ * @fileoverview Utilities for writing Relay mutation `updater`s
+ * declaratively, without having to manipulate `RecordProxy` /
+ * `ConnectionHandler` by hand in every common case.
  *
- * 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).
+ * Covers the most frequent scenarios:
+ * - inserting/removing items in lists (`linked records`);
+ * - inserting/removing edges in connections (Relay pagination);
+ * - copying scalar fields from a JS object to a `RecordProxy`
+ *   (useful in optimistic responses).
  */
 import { RecordProxy, RecordSourceSelectorProxy } from 'relay-runtime';
 /**
- * Verifica se um valor é um objeto não-nulo (para detectar campos
- * escalares vs. linked records em `copyObjScalarsToProxy`).
+ * Checks whether a value is a non-null object (to detect scalar
+ * fields vs. linked records in `copyObjScalarsToProxy`).
  */
 export declare function isObject(obj: any): boolean;
-/** Argumentos de `listRecordRemoveUpdater`. */
+/** Arguments for `listRecordRemoveUpdater`. */
 type ListRecordRemoveUpdaterOptions = {
     parentId: string;
     itemId: string;
     parentFieldName: string;
     store: RecordSourceSelectorProxy;
 };
-/** Argumentos de `listRecordAddUpdater`. */
+/** Arguments for `listRecordAddUpdater`. */
 type ListRecordAddUpdaterOptions = {
     parentId: string;
     item: Record<string, any>;
@@ -30,7 +30,7 @@ type ListRecordAddUpdaterOptions = {
     parentFieldName: string;
     store: RecordSourceSelectorProxy;
 };
-/** Argumentos de `optimisticConnectionUpdater`. */
+/** Arguments for `optimisticConnectionUpdater`. */
 type OptimisticConnectionUpdaterOptions = {
     parentId: string;
     store: RecordSourceSelectorProxy;
@@ -39,95 +39,95 @@ type OptimisticConnectionUpdaterOptions = {
     customNode: RecordProxy;
     itemType: string;
 };
-/** Argumentos de `connectionDeleteEdgeUpdater`. */
+/** Arguments for `connectionDeleteEdgeUpdater`. */
 type ConnectionDeleteEdgeUpdaterOptions = {
     parentId: string;
     connectionName: string;
     nodeId: string;
     store: RecordSourceSelectorProxy;
 };
-/** Argumentos de `copyObjScalarsToProxy`. */
+/** Arguments for `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.
+ * Unique identifier generated once per module load,
+ * intended for the `clientMutationId` field expected by the Relay
+ * Modern pattern.
  */
 export declare const ClientMutationID: string;
 /**
- * Remove um item de uma lista de `linked records` num parent.
+ * Removes an item from a `linked records` list on a parent.
  *
- * Usa `getLinkedRecords` + `setLinkedRecords` com filtro por `dataID`.
- * Para connections paginadas, prefira `connectionDeleteEdgeUpdater`.
+ * Uses `getLinkedRecords` + `setLinkedRecords` with a `dataID` filter.
+ * For paginated connections, prefer `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.
+ * @param options.parentId - DataID of the parent that owns the linked field.
+ * @param options.itemId - DataID of the item to remove.
+ * @param options.parentFieldName - Name of the linked field on the parent.
+ * @param options.store - `RecordSourceSelectorProxy` received in the updater.
  */
 export declare function listRecordRemoveUpdater({ parentId, itemId, parentFieldName, store, }: ListRecordRemoveUpdaterOptions): void;
 /**
- * Adiciona um item ao final de uma lista de `linked records`.
+ * Adds an item to the end of a `linked records` list.
  *
- * 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`).
+ * Creates a new `RecordProxy` using `item.id` as the dataID and copies all
+ * fields from `item` to the new record (without validating types — scalars
+ * and linked refs both go through `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.
+ * @param options.parentId - DataID of the parent.
+ * @param options.item - Object with the new record's fields (must have `id`).
+ * @param options.type - GraphQL type of the record (e.g. `'Todo'`).
+ * @param options.parentFieldName - Name of the linked field on the parent.
+ * @param options.store - The updater's `RecordSourceSelectorProxy`.
  */
 export declare function listRecordAddUpdater({ parentId, item, type, parentFieldName, store, }: ListRecordAddUpdaterOptions): void;
 /**
- * Insere um edge em uma connection paginada (Relay Connections spec).
+ * Inserts an edge into a paginated connection (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`).
+ * @param store - The updater's `RecordSourceSelectorProxy`.
+ * @param parentId - DataID of the parent that owns the connection.
+ * @param connectionName - Connection name in the schema (`@connection(key: ...)`).
+ * @param edge - The edge's `RecordProxy`, already created by the caller.
+ * @param before - If `true`, inserts before the first 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.
+ * Variant of `connectionUpdater` used in optimistic responses: creates the
+ * node and the edge "from scratch" out of a JS object, simulating what the
+ * server would return.
  *
- * @param options.parentId - DataID do parent.
+ * @param options.parentId - DataID of the 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`.
+ * @param options.connectionName - Connection name.
+ * @param options.item - Object with the new node's fields (must have `id`).
+ * @param options.customNode - Pre-created `RecordProxy` (optional, avoids creating via `item`).
+ * @param options.itemType - GraphQL type of the node (e.g. `'Todo'`); the edge
+ *   will be created as `<itemType>Edge`.
  */
 export declare function optimisticConnectionUpdater({ parentId, store, connectionName, item, customNode, itemType, }: OptimisticConnectionUpdaterOptions): void;
 /**
- * Remove um node de uma connection paginada pelo seu `dataID`.
+ * Removes a node from a paginated connection by its `dataID`.
  *
- * Loga `console.warn` se a connection não for encontrada (geralmente
- * significa que o `connectionName` está errado).
+ * Logs a `console.warn` if the connection is not found (usually
+ * means the `connectionName` is wrong).
  *
- * @param options.parentId - DataID do parent.
- * @param options.connectionName - Nome da connection.
- * @param options.nodeId - DataID do node a remover.
+ * @param options.parentId - DataID of the parent.
+ * @param options.connectionName - Connection name.
+ * @param options.nodeId - DataID of the node to remove.
  * @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`.
+ * Copies the scalar fields of a JS object to a `RecordProxy`.
  *
- * Ignora campos que são objetos ou arrays (linked records / linked
- * record lists) — esses precisam ser manipulados com
+ * Ignores fields that are objects or arrays (linked records / linked
+ * record lists) — those must be handled with
  * `setLinkedRecord`/`setLinkedRecords`.
  *
- * @param options.object - Objeto JS de origem.
- * @param options.proxy - `RecordProxy` de destino.
+ * @param options.object - Source JS object.
+ * @param options.proxy - Destination `RecordProxy`.
  */
 export declare function copyObjScalarsToProxy({ object, proxy }: CopyObjScalarsToProxyOptions): void;
 export {};

package/lib/relayArgsInterface/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * Barrel público do módulo `relayArgsInterface`.
+ * Public barrel for the `relayArgsInterface` module.
  *
- * Reexporta os tipos `RelayArgsInterface` (config aceita por
- * `CreateRelayEnvironment`) e `Sink` (interface do Observable Relay).
+ * Re-exports the `RelayArgsInterface` type (config accepted by
+ * `CreateRelayEnvironment`) and `Sink` (the Relay Observable interface).
  */
 export * from './relayArgsInterface';