@onerb/core 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,150 @@
+# @onerb/core
+
+Utilitários centrais para projetos Onerb. Este pacote fornece uma classe de erro de aplicação e um tipo `Either` para modelar sucesso/erro sem exceções no domínio.
+
+## Requisitos
+
+- Node.js com suporte a ESM.
+- TypeScript (opcional, recomendado para tipagem).
+
+## Instalação
+
+```bash
+npm i @onerb/core
+```
+
+```bash
+yarn add @onerb/core
+```
+
+```bash
+pnpm add @onerb/core
+```
+
+## O que está disponível
+
+- `AppError`: erro de aplicação com `code` e `detail`.
+- `Either`, `Left`, `Right`, `left`, `right`: utilitários para fluxo de sucesso/erro sem `throw` no domínio.
+
+## Importação
+
+```ts
+import { AppError, Either, left, right } from '@onerb/core';
+```
+
+## Uso
+
+### 1) Domínio: só repassa o erro (sem `throw`)
+
+Exemplo de caso de uso no domínio que valida dados e retorna `Either`. Se ocorrer erro, ele é repassado (retornando `Left`).
+
+```ts
+import { AppError, Either, left, right } from '@onerb/core';
+
+type CreateUserInput = {
+  email: string;
+  name: string;
+};
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+};
+
+function createUser(input: CreateUserInput): Either<AppError, User> {
+  if (!input.email.includes('@')) {
+    return left(
+      new AppError('Email inválido', {
+        code: 'USER_EMAIL_INVALID',
+        detail: `email recebido: ${input.email}`,
+      })
+    );
+  }
+
+  const user: User = {
+    id: crypto.randomUUID(),
+    email: input.email,
+    name: input.name,
+  };
+
+  return right(user);
+}
+```
+
+### 2) Aplicação: coordena e pode lançar `throw`
+
+Na camada de aplicação, você pode coordenar chamadas do domínio e decidir transformar `Left` em exceção (por exemplo para integração com frameworks HTTP).
+
+```ts
+import { AppError } from '@onerb/core';
+
+async function handleCreateUser(input: { email: string; name: string }) {
+  const result = createUser(input);
+
+  if (result.isLeft()) {
+    // Aqui a aplicação decide lançar o erro
+    throw result.fold((err) => err, (user) => user);
+  }
+
+  return result.fold(
+    () => {
+      // Este ramo não será chamado porque já checamos isLeft
+      throw new AppError('Erro inesperado', { code: 'UNEXPECTED' });
+    },
+    (user) => user
+  );
+}
+```
+
+### 3) Coordenação entre domínio e aplicação
+
+A aplicação pode orquestrar múltiplas operações de domínio, repassando `Left` sem `throw` e só convertendo para exceção no ponto de integração.
+
+```ts
+import { AppError, Either, left, right } from '@onerb/core';
+
+function validateEmail(email: string): Either<AppError, true> {
+  if (!email.includes('@')) {
+    return left(new AppError('Email inválido', { code: 'USER_EMAIL_INVALID' }));
+  }
+  return right(true);
+}
+
+function ensureName(name: string): Either<AppError, true> {
+  if (name.trim().length === 0) {
+    return left(new AppError('Nome obrigatório', { code: 'USER_NAME_REQUIRED' }));
+  }
+  return right(true);
+}
+
+function createUserDomain(input: { email: string; name: string }): Either<AppError, { id: string; email: string; name: string }> {
+  const emailCheck = validateEmail(input.email);
+  if (emailCheck.isLeft()) return emailCheck;
+
+  const nameCheck = ensureName(input.name);
+  if (nameCheck.isLeft()) return nameCheck;
+
+  return right({ id: crypto.randomUUID(), email: input.email, name: input.name });
+}
+
+async function createUserApp(input: { email: string; name: string }) {
+  const result = createUserDomain(input);
+
+  if (result.isLeft()) {
+    throw result.fold((err) => err, () => new Error('Inalcançável'));
+  }
+
+  return result.fold(
+    () => {
+      throw new AppError('Erro inesperado', { code: 'UNEXPECTED' });
+    },
+    (user) => user
+  );
+}
+```
+
+## Notas
+
+- O `Either` ajuda a manter o domínio livre de exceções, favorecendo retornos explícitos.
+- A decisão de lançar erros (`throw`) fica na camada de aplicação, onde há integração com infraestrutura (HTTP, filas, etc.).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onerb/core",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Core utilities for Onerb projects.",
   "license": "MIT",
   "type": "module",