@onerb/core 1.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/dist/index.cjs

@@ -20,24 +20,77 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AppError: () => AppError
+  AppError: () => AppError,
+  Left: () => Left,
+  Right: () => Right,
+  left: () => left,
+  right: () => right
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors/app-error.ts
 var AppError = class extends Error {
-  message;
   code;
   detail;
   constructor(message, options) {
     super(message);
-    this.message = message;
+    this.name = "AppError";
     this.code = options.code;
     this.detail = options.detail;
   }
 };
+
+// src/errors/either.ts
+var Left = class _Left {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  isLeft() {
+    return true;
+  }
+  isRight() {
+    return false;
+  }
+  map(_fn) {
+    return new _Left(this._value);
+  }
+  mapLeft(fn) {
+    return new _Left(fn(this._value));
+  }
+  fold(fl, _fr) {
+    return fl(this._value);
+  }
+};
+var Right = class _Right {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  isLeft() {
+    return false;
+  }
+  isRight() {
+    return true;
+  }
+  map(fn) {
+    return new _Right(fn(this._value));
+  }
+  mapLeft(_fn) {
+    return new _Right(this._value);
+  }
+  fold(_fl, fr) {
+    return fr(this._value);
+  }
+};
+var left = (l) => new Left(l);
+var right = (r) => new Right(r);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AppError
+  AppError,
+  Left,
+  Right,
+  left,
+  right
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/errors/app-error.ts"],"sourcesContent":["export * from './errors'\n","export class AppError extends Error {\n    readonly message: string;\n    readonly code: string;\n    readonly detail?: string;\n\n    constructor(\n        message: string, options: { code: string; detail?: string; }\n    ) {\n        super(message);\n        this.message = message;\n        this.code = options.code;\n        this.detail = options.detail;\n    }\n}"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,WAAN,cAAuB,MAAM;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACI,SAAiB,SACnB;AACE,UAAM,OAAO;AACb,SAAK,UAAU;AACf,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,QAAQ;AAAA,EAC1B;AACJ;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/errors/app-error.ts","../src/errors/either.ts"],"sourcesContent":["export * from './errors'\n","export class AppError extends Error {\n  readonly code: string;\n  readonly detail?: string;\n\n  constructor(message: string, options: { code: string; detail?: string }) {\n    super(message);\n    this.name = 'AppError';\n    this.code = options.code;\n    this.detail = options.detail;\n  }\n}\n","export type Either<L, R> = Left<L, R> | Right<R, L>;\n\nexport class Left<L, R = never> {\n  private readonly _value: L;\n\n  constructor(value: L) {\n    this._value = value;\n  }\n\n  isLeft(): this is Left<L, R> {\n    return true;\n  }\n\n  isRight(): this is Left<L, R> {\n    return false;\n  }\n\n  map<T>(_fn: (v: R) => T): Left<L, T> {\n    return new Left<L, T>(this._value);\n  }\n\n  mapLeft<T>(fn: (l: L) => T): Left<T, R> {\n    return new Left<T, R>(fn(this._value));\n  }\n\n  fold<T>(fl: (l: L) => T, _fr: (r: R) => R): T {\n    return fl(this._value);\n  }\n}\n\nexport class Right<R, L = never> {\n  private readonly _value: R;\n\n  constructor(value: R) {\n    this._value = value;\n  }\n\n  isLeft(): this is Right<R, L> {\n    return false;\n  }\n\n  isRight(): this is Right<R, L> {\n    return true;\n  }\n\n  map<T>(fn: (v: R) => T): Right<T, L> {\n    return new Right<T, L>(fn(this._value));\n  }\n\n  mapLeft<T>(_fn: (l: L) => T): Right<R, T> {\n    return new Right<R, T>(this._value);\n  }\n\n  fold<T>(_fl: (l: L) => L, fr: (r: R) => T): T {\n    return fr(this._value);\n  }\n}\n\nexport const left = <L, R = never>(l: L) =>\n  new Left<L, R>(l);\n\nexport const right = <R, L = never>(r: R) =>\n  new Right<R, L>(r);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,WAAN,cAAuB,MAAM;AAAA,EACzB;AAAA,EACA;AAAA,EAET,YAAY,SAAiB,SAA4C;AACvE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,QAAQ;AAAA,EACxB;AACF;;;ACRO,IAAM,OAAN,MAAM,MAAmB;AAAA,EACb;AAAA,EAEjB,YAAY,OAAU;AACpB,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,SAA6B;AAC3B,WAAO;AAAA,EACT;AAAA,EAEA,UAA8B;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,IAAO,KAA8B;AACnC,WAAO,IAAI,MAAW,KAAK,MAAM;AAAA,EACnC;AAAA,EAEA,QAAW,IAA6B;AACtC,WAAO,IAAI,MAAW,GAAG,KAAK,MAAM,CAAC;AAAA,EACvC;AAAA,EAEA,KAAQ,IAAiB,KAAqB;AAC5C,WAAO,GAAG,KAAK,MAAM;AAAA,EACvB;AACF;AAEO,IAAM,QAAN,MAAM,OAAoB;AAAA,EACd;AAAA,EAEjB,YAAY,OAAU;AACpB,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,SAA8B;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,UAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,IAAO,IAA8B;AACnC,WAAO,IAAI,OAAY,GAAG,KAAK,MAAM,CAAC;AAAA,EACxC;AAAA,EAEA,QAAW,KAA+B;AACxC,WAAO,IAAI,OAAY,KAAK,MAAM;AAAA,EACpC;AAAA,EAEA,KAAQ,KAAkB,IAAoB;AAC5C,WAAO,GAAG,KAAK,MAAM;AAAA,EACvB;AACF;AAEO,IAAM,OAAO,CAAe,MACjC,IAAI,KAAW,CAAC;AAEX,IAAM,QAAQ,CAAe,MAClC,IAAI,MAAY,CAAC;","names":[]}

package/dist/index.d.cts

@@ -1,5 +1,4 @@
 declare class AppError extends Error {
-    readonly message: string;
     readonly code: string;
     readonly detail?: string;
     constructor(message: string, options: {
@@ -8,6 +7,26 @@ declare class AppError extends Error {
     });
 }
 
-type Either = {};
+type Either<L, R> = Left<L, R> | Right<R, L>;
+declare class Left<L, R = never> {
+    private readonly _value;
+    constructor(value: L);
+    isLeft(): this is Left<L, R>;
+    isRight(): this is Left<L, R>;
+    map<T>(_fn: (v: R) => T): Left<L, T>;
+    mapLeft<T>(fn: (l: L) => T): Left<T, R>;
+    fold<T>(fl: (l: L) => T, _fr: (r: R) => R): T;
+}
+declare class Right<R, L = never> {
+    private readonly _value;
+    constructor(value: R);
+    isLeft(): this is Right<R, L>;
+    isRight(): this is Right<R, L>;
+    map<T>(fn: (v: R) => T): Right<T, L>;
+    mapLeft<T>(_fn: (l: L) => T): Right<R, T>;
+    fold<T>(_fl: (l: L) => L, fr: (r: R) => T): T;
+}
+declare const left: <L, R = never>(l: L) => Left<L, R>;
+declare const right: <R, L = never>(r: R) => Right<R, L>;
 
-export { AppError, type Either };
+export { AppError, type Either, Left, Right, left, right };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 declare class AppError extends Error {
-    readonly message: string;
     readonly code: string;
     readonly detail?: string;
     constructor(message: string, options: {
@@ -8,6 +7,26 @@ declare class AppError extends Error {
     });
 }
 
-type Either = {};
+type Either<L, R> = Left<L, R> | Right<R, L>;
+declare class Left<L, R = never> {
+    private readonly _value;
+    constructor(value: L);
+    isLeft(): this is Left<L, R>;
+    isRight(): this is Left<L, R>;
+    map<T>(_fn: (v: R) => T): Left<L, T>;
+    mapLeft<T>(fn: (l: L) => T): Left<T, R>;
+    fold<T>(fl: (l: L) => T, _fr: (r: R) => R): T;
+}
+declare class Right<R, L = never> {
+    private readonly _value;
+    constructor(value: R);
+    isLeft(): this is Right<R, L>;
+    isRight(): this is Right<R, L>;
+    map<T>(fn: (v: R) => T): Right<T, L>;
+    mapLeft<T>(_fn: (l: L) => T): Right<R, T>;
+    fold<T>(_fl: (l: L) => L, fr: (r: R) => T): T;
+}
+declare const left: <L, R = never>(l: L) => Left<L, R>;
+declare const right: <R, L = never>(r: R) => Right<R, L>;
 
-export { AppError, type Either };
+export { AppError, type Either, Left, Right, left, right };

package/dist/index.js

@@ -1,16 +1,65 @@
 // src/errors/app-error.ts
 var AppError = class extends Error {
-  message;
   code;
   detail;
   constructor(message, options) {
     super(message);
-    this.message = message;
+    this.name = "AppError";
     this.code = options.code;
     this.detail = options.detail;
   }
 };
+
+// src/errors/either.ts
+var Left = class _Left {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  isLeft() {
+    return true;
+  }
+  isRight() {
+    return false;
+  }
+  map(_fn) {
+    return new _Left(this._value);
+  }
+  mapLeft(fn) {
+    return new _Left(fn(this._value));
+  }
+  fold(fl, _fr) {
+    return fl(this._value);
+  }
+};
+var Right = class _Right {
+  _value;
+  constructor(value) {
+    this._value = value;
+  }
+  isLeft() {
+    return false;
+  }
+  isRight() {
+    return true;
+  }
+  map(fn) {
+    return new _Right(fn(this._value));
+  }
+  mapLeft(_fn) {
+    return new _Right(this._value);
+  }
+  fold(_fl, fr) {
+    return fr(this._value);
+  }
+};
+var left = (l) => new Left(l);
+var right = (r) => new Right(r);
 export {
-  AppError
+  AppError,
+  Left,
+  Right,
+  left,
+  right
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors/app-error.ts"],"sourcesContent":["export class AppError extends Error {\n    readonly message: string;\n    readonly code: string;\n    readonly detail?: string;\n\n    constructor(\n        message: string, options: { code: string; detail?: string; }\n    ) {\n        super(message);\n        this.message = message;\n        this.code = options.code;\n        this.detail = options.detail;\n    }\n}"],"mappings":";AAAO,IAAM,WAAN,cAAuB,MAAM;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EAET,YACI,SAAiB,SACnB;AACE,UAAM,OAAO;AACb,SAAK,UAAU;AACf,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,QAAQ;AAAA,EAC1B;AACJ;","names":[]}
+{"version":3,"sources":["../src/errors/app-error.ts","../src/errors/either.ts"],"sourcesContent":["export class AppError extends Error {\n  readonly code: string;\n  readonly detail?: string;\n\n  constructor(message: string, options: { code: string; detail?: string }) {\n    super(message);\n    this.name = 'AppError';\n    this.code = options.code;\n    this.detail = options.detail;\n  }\n}\n","export type Either<L, R> = Left<L, R> | Right<R, L>;\n\nexport class Left<L, R = never> {\n  private readonly _value: L;\n\n  constructor(value: L) {\n    this._value = value;\n  }\n\n  isLeft(): this is Left<L, R> {\n    return true;\n  }\n\n  isRight(): this is Left<L, R> {\n    return false;\n  }\n\n  map<T>(_fn: (v: R) => T): Left<L, T> {\n    return new Left<L, T>(this._value);\n  }\n\n  mapLeft<T>(fn: (l: L) => T): Left<T, R> {\n    return new Left<T, R>(fn(this._value));\n  }\n\n  fold<T>(fl: (l: L) => T, _fr: (r: R) => R): T {\n    return fl(this._value);\n  }\n}\n\nexport class Right<R, L = never> {\n  private readonly _value: R;\n\n  constructor(value: R) {\n    this._value = value;\n  }\n\n  isLeft(): this is Right<R, L> {\n    return false;\n  }\n\n  isRight(): this is Right<R, L> {\n    return true;\n  }\n\n  map<T>(fn: (v: R) => T): Right<T, L> {\n    return new Right<T, L>(fn(this._value));\n  }\n\n  mapLeft<T>(_fn: (l: L) => T): Right<R, T> {\n    return new Right<R, T>(this._value);\n  }\n\n  fold<T>(_fl: (l: L) => L, fr: (r: R) => T): T {\n    return fr(this._value);\n  }\n}\n\nexport const left = <L, R = never>(l: L) =>\n  new Left<L, R>(l);\n\nexport const right = <R, L = never>(r: R) =>\n  new Right<R, L>(r);\n"],"mappings":";AAAO,IAAM,WAAN,cAAuB,MAAM;AAAA,EACzB;AAAA,EACA;AAAA,EAET,YAAY,SAAiB,SAA4C;AACvE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ;AACpB,SAAK,SAAS,QAAQ;AAAA,EACxB;AACF;;;ACRO,IAAM,OAAN,MAAM,MAAmB;AAAA,EACb;AAAA,EAEjB,YAAY,OAAU;AACpB,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,SAA6B;AAC3B,WAAO;AAAA,EACT;AAAA,EAEA,UAA8B;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,IAAO,KAA8B;AACnC,WAAO,IAAI,MAAW,KAAK,MAAM;AAAA,EACnC;AAAA,EAEA,QAAW,IAA6B;AACtC,WAAO,IAAI,MAAW,GAAG,KAAK,MAAM,CAAC;AAAA,EACvC;AAAA,EAEA,KAAQ,IAAiB,KAAqB;AAC5C,WAAO,GAAG,KAAK,MAAM;AAAA,EACvB;AACF;AAEO,IAAM,QAAN,MAAM,OAAoB;AAAA,EACd;AAAA,EAEjB,YAAY,OAAU;AACpB,SAAK,SAAS;AAAA,EAChB;AAAA,EAEA,SAA8B;AAC5B,WAAO;AAAA,EACT;AAAA,EAEA,UAA+B;AAC7B,WAAO;AAAA,EACT;AAAA,EAEA,IAAO,IAA8B;AACnC,WAAO,IAAI,OAAY,GAAG,KAAK,MAAM,CAAC;AAAA,EACxC;AAAA,EAEA,QAAW,KAA+B;AACxC,WAAO,IAAI,OAAY,KAAK,MAAM;AAAA,EACpC;AAAA,EAEA,KAAQ,KAAkB,IAAoB;AAC5C,WAAO,GAAG,KAAK,MAAM;AAAA,EACvB;AACF;AAEO,IAAM,OAAO,CAAe,MACjC,IAAI,KAAW,CAAC;AAEX,IAAM,QAAQ,CAAe,MAClC,IAAI,MAAY,CAAC;","names":[]}

package/package.json

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