#SingleRecordResource

Resource voltado para um único registro: os dados são um único objeto, suportando busca por chave primária, criação/atualização (save) e exclusão. É adequado para cenários de "registro único", como detalhes e formulários. Diferente do MultiRecordResource, o método getData() do SingleRecordResource retorna um único objeto. Você especifica a chave primária via setFilterByTk(id), e o save() chamará automaticamente create ou update com base no estado de isNewRecord.

Herança: FlowResource → APIResource → BaseRecordResource → SingleRecordResource.

Formas de criação: ctx.makeResource('SingleRecordResource') ou ctx.initResource('SingleRecordResource'). Antes de usar, é necessário chamar setResourceName('nome_da_coleção'); ao realizar operações por chave primária, chame setFilterByTk(id). No RunJS, o ctx.api é injetado pelo ambiente de execução.

#Cenários de Uso

#Formato dos Dados

• getData() retorna um único objeto de registro, que corresponde ao campo data da resposta da API get.
• getMeta() retorna metadados (se disponíveis).

#Nome do Recurso e Chave Primária

#Estado

#Parâmetros da Requisição (Filtro / Campos)

#CRUD

#Configurações e Eventos

#Exemplos

#Busca básica e atualização

ctx.initResource('SingleRecordResource');
ctx.resource.setResourceName('users');
ctx.resource.setFilterByTk(1);
await ctx.resource.refresh();
const user = ctx.resource.getData();

// Atualização
await ctx.resource.save({ name: 'João Silva' });

#Criar novo registro

const newRes = ctx.makeResource('SingleRecordResource');
newRes.setResourceName('users');
await newRes.save({ name: 'Maria Souza', email: 'maria@example.com' });

#Excluir registro

ctx.resource.setResourceName('users');
ctx.resource.setFilterByTk(1);
await ctx.resource.destroy();
// Após o destroy, o getData() retorna null

#Carregamento de associações e campos

ctx.resource.setResourceName('users');
ctx.resource.setFilterByTk(1);
ctx.resource.setFields(['id', 'nickname', 'email']);
ctx.resource.setAppends(['profile', 'roles']);
await ctx.resource.refresh();
const user = ctx.resource.getData();

#Recursos de associação (ex: users.profile)

const res = ctx.makeResource('SingleRecordResource');
res.setResourceName('users.profile');
res.setSourceId(ctx.record?.id); // Chave primária do registro pai
res.setFilterByTk(profileId);    // se profile for um relacionamento hasOne, o filterByTk pode ser omitido
await res.refresh();
const profile = res.getData();

#save sem atualização automática

await ctx.resource.save({ status: 'active' }, { refresh: false });
// o getData() mantém o valor antigo, pois a atualização (refresh) não é disparada após salvar

#Ouvir eventos refresh / saved

ctx.resource?.on?.('refresh', () => {
  const data = ctx.resource.getData();
  ctx.render(<div>Usuário: {data?.nickname}</div>);
});
ctx.resource?.on?.('saved', (savedData) => {
  ctx.message.success('Salvo com sucesso');
});
await ctx.resource?.refresh?.();

#Observações

• setResourceName é obrigatório: Você deve chamar setResourceName('nome_da_coleção') antes de usar, caso contrário, a URL da requisição não poderá ser construída.
• filterByTk e isNewRecord: Se o setFilterByTk não for chamado, isNewRecord será true e o refresh() não iniciará uma requisição; o save() executará uma ação create.
• Recursos de associação: Quando o nome do recurso estiver no formato pai.filho (ex: users.profile), você deve chamar setSourceId(chave_primária_do_pai) primeiro.
• getData retorna um objeto: O data retornado pelas APIs de registro único é um objeto de registro; o getData() retorna esse objeto diretamente. Ele se torna null após o destroy().

#Relacionados

• ctx.resource - A instância de resource no contexto atual
• ctx.initResource() - Inicializa e vincula ao ctx.resource
• ctx.makeResource() - Cria uma nova instância de resource sem vincular
• APIResource - Recurso de API geral solicitado por URL
• MultiRecordResource - Voltado para coleções/listas, suporta CRUD e paginação