vsrepo 1.2.1 → 1.2.3

package/README.md

@@ -497,6 +497,8 @@ Os filtros são sufixos aplicados ao nome do campo dentro do método. O campo em
 | `GreaterThanEqual` | `gte`                 | sim                  |
 | `LessThan`         | `lt`                  | sim                  |
 | `LessThanEqual`    | `lte`                 | sim                  |
+| `Between`          | `gte` + `lte`         | sim (tupla `[min, max]`) |
+| `NotBetween`       | `not.gte` + `not.lte` | sim (tupla `[min, max]`) |
 | `IsNull`           | `null`                | não                  |
 | `IsNotNull`        | `not: null`           | não                  |
 | `IsTrue`           | `true`                | não                  |
@@ -511,6 +513,37 @@ findByEmailStartsWithInsensitive // { email: { startsWith: valor, mode: 'insensi
 findByNomeInsensitive            // { nome: { equals: valor, mode: 'insensitive' } }
 ```
 
+`Between` e `NotBetween` recebem uma **tupla `[minValue, maxValue]`** e são ideais para filtros de intervalo em números, datas ou qualquer campo comparável:
+
+```ts
+methods: {
+  findManyByIdadeBetween:          { map: true },
+  findManyBySalarioNotBetween:     { map: true },
+  findManyByCriadoEmBetween:       { map: true },
+}
+
+// Uso
+await usuarioRepository.findManyByIdadeBetween([18, 65]);
+await usuarioRepository.findManyBySalarioNotBetween([1000, 5000]);
+await usuarioRepository.findManyByCriadoEmBetween([new Date("2024-01-01"), new Date("2024-12-31")]);
+```
+
+Gera (`findManyByIdadeBetween`):
+
+```ts
+{
+  idade: { gte: 18, lte: 65 }
+}
+```
+
+Gera (`findManyBySalarioNotBetween`):
+
+```ts
+{
+  salario: { not: { gte: 1000, lte: 5000 } }
+}
+```
+
 O sufixo `Optional` pode ser adicionado a qualquer campo para tornar o argumento opcional:
 
 ```ts
@@ -621,14 +654,18 @@ Exemplos:
 
 ```ts
 methods: {
-  findByPostagensSomeTituloContains:  { map: true },   // postagens: { some: { titulo: { contains: valor } } }
-  findByPerfilWith:                   { map: true },   // perfil: { is: {} }
-  findByPerfilWithout:                { map: true },   // perfil: { isNot: {} }
-  findByPostagensSome:                { map: true },   // postagens: { some: {} }
-  findByPostagensEveryAtivoIsTrue:    { map: true },   // postagens: { every: { ativo: true } }
+  findByPostagensSomeTituloContains:  { map: true },   // postagens: { some: { titulo: { contains: valor } } } >> (Busca usuários que o título de alguma postagem contém um valor)
+  findByPerfilWithDescricaoIsNotNull: { map: true },   // perfil: { is: { descricao: { not: null } } } >> (Busca usuários em que a descrição do perfil não é nula)
+  findByPerfilWithout:                { map: true },   // perfil: { isNot: {} } >> (Busca usuários sem perfil)
+  findByPostagensSome:                { map: true },   // postagens: { some: {} } >> (Busca usuários com alguma postagem)
+  findByPostagensEveryAtivoIsTrue:    { map: true },   // postagens: { every: { ativo: true } } >> (Busca usuários que todas as postagens estão ativas)
+  findByPostagensNone:                { map: true },   // postagens: { none: {} } >> (Busca usuários sem postagens)
 }
 ```
 
+> [!NOTE]
+> Teoricamente você pode usar `Every` sem `Field` (ele geraria { every: {} }), porém isso não produz um filtro efetivo. A condição é considerada verdadeira para qualquer relação, inclusive quando não existem registros relacionados, tornando o resultado equivalente a não aplicar filtro algum.
+
 ---
 
 ### Sufixos de paginação e ordenação
@@ -1018,8 +1055,9 @@ import type { MethodOptions, MethodOptionsModel } from "../../generated/vsrepo";
 // S = chave do select model ou false
 type Opts = MethodOptions<"public" | "minimal">;
 
-// MethodOptionsModel<T> — versão derivada do tipo do repository
-type OptsModel = MethodOptionsModel<typeof usuarioSelectModels>;
+// MethodOptionsModel<TRepo> — derivado diretamente de uma instância VSRepository configurada
+const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()(config);
+type OptsModel = MethodOptionsModel<typeof usuarioVSRepo>;
 ```
 
 ### Tipos de configuração
@@ -1031,7 +1069,6 @@ import type {
   BuildConfig,
   RepositoryRelations,
   ExtractRelationConfig,
-  UpsertWithRelations,
 } from "../../generated/vsrepo";
 
 // Configuração de um método dinâmico
@@ -1048,18 +1085,12 @@ type UsuarioRelations = RepositoryRelations<Usuario>;
 
 // Configuração de relação inferida a partir de um campo
 type PerfilRelationConfig = ExtractRelationConfig<Usuario["perfil"]>;
-
-// Payload do save com relações
-type UsuarioComRelacoes = UpsertWithRelations<Usuario, "usuario", typeof relations>;
 ```
 
 ### Tipo do repository construído
 
 ```ts
-import type { BuiltRepository, RepositoryOf } from "../../generated/vsrepo";
-
-// Tipo completo de um repository construído
-type MeuRepo = BuiltRepository<Usuario, "usuario", typeof config, typeof buildConfig>;
+import type { RepositoryOf } from "../../generated/vsrepo";
 
 // Inferência a partir de uma instância VSRepository (útil para injeção de dependência)
 const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({ ... });
@@ -1080,15 +1111,31 @@ const extension = { buscarPorDominio: (dominio: string) => Promise<Usuario[]> };
 type UsuarioRepositoryExtended = RepositoryOf<typeof usuarioVSRepo, undefined, typeof extension>;
 ```
 
-### Tipo auxiliar
+### Tipos do payload dos métodos `save` e `patch`
+
+Use `SaveObject` e `PatchObject` para extrair o tipo do payload esperado pelos métodos `save` e `patch` diretamente a partir de uma instância `VSRepository` configurada. Esses tipos já levam em conta as relações configuradas.
 
 ```ts
-import type { DistributiveOmit } from "../../generated/vsrepo";
+import type { SaveObject, PacthObject } from "../../generated/vsrepo";
 
-// Omit distributivo — preserva unions ao omitir propriedades
-type SemEmail = DistributiveOmit<Usuario | Perfil, "email">;
+const usuarioVSRepo = setupVSRepo<Usuario, "usuario">()({
+  tableName: "usuario",
+  pkName: "id",
+  relations: {
+    perfil: { pk: "id", mode: "oto", restriction: "set" },
+    postagens: { pk: "id", mode: "otm", restriction: "add" },
+  },
+});
+
+// Tipo do objeto aceito pelo .save()
+type UsuarioSavePayload = SaveObject<typeof usuarioVSRepo>;
+
+// Tipo do objeto aceito pelo .patch()
+type UsuarioPatchPayload = PacthObject<typeof usuarioVSRepo>;
 ```
 
+> Útil para tipar DTOs, funções auxiliares ou serviços que chamam `save`/`patch` e precisam do tipo correto do payload sem referenciar diretamente os tipos internos do Prisma.
+
 ---
 
 ## API Reference