vsrepo 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +112 -108
- package/README.pt-BR.md +148 -144
- package/dist/VSRepoAdapter.js +1 -0
- package/dist/VSRepoAdapter.js.map +1 -0
- package/dist/VSRepository.d.ts +3 -8
- package/dist/VSRepository.js +4 -2
- package/dist/VSRepository.js.map +1 -0
- package/dist/decorators/dynamic-method.decorator.js +1 -0
- package/dist/decorators/dynamic-method.decorator.js.map +1 -0
- package/dist/decorators/query-method.decorator.d.ts +7 -4
- package/dist/decorators/query-method.decorator.js +8 -4
- package/dist/decorators/query-method.decorator.js.map +1 -0
- package/dist/errors/VSRepoAdapterError.js +1 -0
- package/dist/errors/VSRepoAdapterError.js.map +1 -0
- package/dist/errors/VSRepoError.js +1 -0
- package/dist/errors/VSRepoError.js.map +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -0
- package/dist/internal/constants/debug-arg-symbol.constant.js +1 -0
- package/dist/internal/constants/debug-arg-symbol.constant.js.map +1 -0
- package/dist/internal/constants/dynamic-methods-key.constant.js +1 -0
- package/dist/internal/constants/dynamic-methods-key.constant.js.map +1 -0
- package/dist/internal/constants/query-methods-key.constant.js +1 -0
- package/dist/internal/constants/query-methods-key.constant.js.map +1 -0
- package/dist/internal/enums/adapter-error-code.enum.d.ts +4 -0
- package/dist/internal/enums/adapter-error-code.enum.js +5 -0
- package/dist/internal/enums/adapter-error-code.enum.js.map +1 -0
- package/dist/internal/enums/transaction-isolation-level.enum.js +1 -0
- package/dist/internal/enums/transaction-isolation-level.enum.js.map +1 -0
- package/dist/internal/enums/vs-log-level.enum.js +1 -0
- package/dist/internal/enums/vs-log-level.enum.js.map +1 -0
- package/dist/internal/enums/vsrepo-error-type.enum.js +1 -0
- package/dist/internal/enums/vsrepo-error-type.enum.js.map +1 -0
- package/dist/internal/resolvers/dynamic-methods.resolver.js +1 -0
- package/dist/internal/resolvers/dynamic-methods.resolver.js.map +1 -0
- package/dist/internal/resolvers/merge-wheres.resolver.js +1 -0
- package/dist/internal/resolvers/merge-wheres.resolver.js.map +1 -0
- package/dist/internal/utils/db-arg.util.js +1 -0
- package/dist/internal/utils/db-arg.util.js.map +1 -0
- package/dist/internal/utils/uncapitalize.util.js +1 -0
- package/dist/internal/utils/uncapitalize.util.js.map +1 -0
- package/dist/internal/utils/vs-logger.util.js +1 -0
- package/dist/internal/utils/vs-logger.util.js.map +1 -0
- package/dist/internal/utils/with-db.util.js +1 -0
- package/dist/internal/utils/with-db.util.js.map +1 -0
- package/dist/internal/validators/decorators.validator.js +1 -0
- package/dist/internal/validators/decorators.validator.js.map +1 -0
- package/dist/internal/validators/schemas/ordering.schema.js +1 -0
- package/dist/internal/validators/schemas/ordering.schema.js.map +1 -0
- package/dist/internal/validators/schemas/pagination.schema.js +1 -0
- package/dist/internal/validators/schemas/pagination.schema.js.map +1 -0
- package/dist/internal/validators/schemas/where.schema.js +1 -0
- package/dist/internal/validators/schemas/where.schema.js.map +1 -0
- package/dist/internal/validators/vsrepo.validator.js +1 -0
- package/dist/internal/validators/vsrepo.validator.js.map +1 -0
- package/dist/types/adapter/adapter-method-options.type.js +1 -0
- package/dist/types/adapter/adapter-method-options.type.js.map +1 -0
- package/dist/types/adapter/adapter-query-options.type.js +1 -0
- package/dist/types/adapter/adapter-query-options.type.js.map +1 -0
- package/dist/types/decorators/dynamic-method-options.type.js +1 -0
- package/dist/types/decorators/dynamic-method-options.type.js.map +1 -0
- package/dist/types/decorators/query-method-options.type.js +1 -0
- package/dist/types/decorators/query-method-options.type.js.map +1 -0
- package/dist/types/dynamic-methods/dynamic-method-customization.type.js +1 -0
- package/dist/types/dynamic-methods/dynamic-method-customization.type.js.map +1 -0
- package/dist/types/dynamic-methods/dynamic-method-info.type.js +1 -0
- package/dist/types/dynamic-methods/dynamic-method-info.type.js.map +1 -0
- package/dist/types/dynamic-methods/dynamic-method-where-ops.type.js +1 -0
- package/dist/types/dynamic-methods/dynamic-method-where-ops.type.js.map +1 -0
- package/dist/types/utils/count-result.type.js +1 -0
- package/dist/types/utils/count-result.type.js.map +1 -0
- package/dist/types/utils/decimal-like.type.js +1 -0
- package/dist/types/utils/decimal-like.type.js.map +1 -0
- package/dist/types/utils/deep-partial.type.js +1 -0
- package/dist/types/utils/deep-partial.type.js.map +1 -0
- package/dist/types/utils/keys-of-type.type.js +1 -0
- package/dist/types/utils/keys-of-type.type.js.map +1 -0
- package/dist/types/utils/methods-options.type.js +1 -0
- package/dist/types/utils/methods-options.type.js.map +1 -0
- package/dist/types/utils/numeric-keys.type.js +1 -0
- package/dist/types/utils/numeric-keys.type.js.map +1 -0
- package/dist/types/utils/numeric-like.type.js +1 -0
- package/dist/types/utils/numeric-like.type.js.map +1 -0
- package/dist/types/utils/ordering.type.js +1 -0
- package/dist/types/utils/ordering.type.js.map +1 -0
- package/dist/types/utils/pagination.type.js +1 -0
- package/dist/types/utils/pagination.type.js.map +1 -0
- package/dist/types/utils/perform-data.type.js +1 -0
- package/dist/types/utils/perform-data.type.js.map +1 -0
- package/dist/types/utils/primitive.type.js +1 -0
- package/dist/types/utils/primitive.type.js.map +1 -0
- package/dist/types/utils/query-args.type.js +1 -0
- package/dist/types/utils/query-args.type.js.map +1 -0
- package/dist/types/utils/query-method-arg.type.d.ts +4 -2
- package/dist/types/utils/query-method-arg.type.js +1 -0
- package/dist/types/utils/query-method-arg.type.js.map +1 -0
- package/dist/types/utils/restrict-method-options.type.js +1 -0
- package/dist/types/utils/restrict-method-options.type.js.map +1 -0
- package/dist/types/utils/see-mode.type.js +1 -0
- package/dist/types/utils/see-mode.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-args.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-args.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-method.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-method.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-options.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-options.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-orm-types.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-orm-types.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-pretty-where.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-pretty-where.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-query-options.type.d.ts +1 -1
- package/dist/types/vsrepo/vsrepo-query-options.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-query-options.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-query.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-query.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-relations.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-relations.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-resolve-args-data.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-resolve-args-data.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-select.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-select.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-transaction-options.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-transaction-options.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-ugly-where.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-ugly-where.type.js.map +1 -0
- package/dist/types/vsrepo/vsrepo-where.type.js +1 -0
- package/dist/types/vsrepo/vsrepo-where.type.js.map +1 -0
- package/package.json +1 -1
package/README.pt-BR.md
CHANGED
|
@@ -84,7 +84,7 @@ Se você vem do código/docs da [v1](https://github.com/jaobrabo123/VSRepository
|
|
|
84
84
|
| Tipos de erro | `VSRepoError` + subclasses (`VSRepoConfigError`, `VSRepoBuildError`, `VSRepoExtendError`, `VSRepoRuntimeError`) | Uma classe base `VSRepoError` com um campo `type: VSRepoErrorType` (`DECORATOR`, `RESOLVER`, `DYNAMIC`, `VALIDATOR`, `BASE`, `ADAPTER`), além de uma subclasse `VSRepoAdapterError` que carrega um `AdapterErrorCode` e o erro original do ORM |
|
|
85
85
|
| Log de debug | Boolean `showWorking: true` | `logLevel: VSLogLevel` (`DEBUG`/`INFO`/`WARN`/`ERROR`) + `logSlowThresholdMs` para avisos de queries lentas |
|
|
86
86
|
| CLI `vsrepo generate` (etapa de geração de tipos) | Obrigatória antes de usar | Não faz parte do núcleo da v2 — os tipos vêm diretamente das suas entidades/tipos do ORM |
|
|
87
|
-
| Extras de CRUD | `patchList`, `options.select`/`options.include` raw | `select`/`relations` já são o padrão (sempre "raw"); `patch`/`merge` mantêm a mesma semântica. **`patchList` foi removido** — para uma atualização parcial em lote, use um dynamic method `updateManyBy`/`updateManyWhere`
|
|
87
|
+
| Extras de CRUD | `patchList`, `options.select`/`options.include` raw | `select`/`relations` já são o padrão (sempre "raw"); `patch`/`merge` mantêm a mesma semântica. **`patchList` foi removido** — para uma atualização parcial em lote, use um dynamic method `updateManyBy`/`updateManyWhere` |
|
|
88
88
|
|
|
89
89
|
---
|
|
90
90
|
|
|
@@ -99,12 +99,13 @@ O VSRepository v2 é **agnóstico de ORM por design**. O pacote core (`vsrepo`)
|
|
|
99
99
|
|
|
100
100
|
O adapter do Prisma 7 já foi publicado no npm como `@vsrepo/prisma7-adapter` — por enquanto é o **único** adapter publicado. Os adapters para os outros ORMs listados acima (Prisma 8, TypeORM, Drizzle) estão **planejados**; eles só ainda não foram publicados. Até que exista um pacote `@vsrepo/*-adapter` oficial para o seu ORM, você pode escrever o seu próprio para o seu projeto e, se quiser, publicá-lo e abrir um PR para ajudar a fazer o ecossistema crescer — contribuições nesse sentido são muito bem-vindas.
|
|
101
101
|
|
|
102
|
-
| Adapter
|
|
103
|
-
|
|
|
104
|
-
| Prisma 7 (`@vsrepo/prisma7-adapter`)
|
|
105
|
-
|
|
|
106
|
-
|
|
|
107
|
-
|
|
|
102
|
+
| Adapter | Status |
|
|
103
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| Prisma 7 (`@vsrepo/prisma7-adapter`) | 🟢 **Lançado** — publicado no npm, implementa o contrato de `VSRepoAdapter` (CRUD, relations, transactions, `merge`, logging) com testes; veja o [`VSRepoPrisma7Adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) para o código-fonte e docs. **Nota:** os métodos atômicos/de agregação (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — veja [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação)) foram adicionados ao contrato do `VSRepoAdapter` depois do último release desse adapter; confirme no changelog/versão dele se já implementam esses métodos antes de depender de `increment`/`sum`/etc. contra o Prisma 7. |
|
|
105
|
+
| Drizzle (`@vsrepo/drizzle-adapter`) | 🔵 **Em desenvolvimento** — O adapter para o Drizzle ORM já está em desenvolvimento e aceita contribuições da comunidade; veja o estado atual do [`DrizzleAdapter`](https://github.com/jaobrabo123/VSRepoDrizzleAdapter) |
|
|
106
|
+
| TypeORM (`@vsrepo/typeorm-adapter`) | 🟡 **Planejado, ainda não publicado.** Só foi escrito um parser de referência da cláusula `where` (`parseVSRepoWhere`) para validar o design; é o ponto de partida planejado do futuro pacote `@vsrepo/typeorm-adapter`. Contribuições da comunidade nessa frente são bem-vindas. |
|
|
107
|
+
| Outros ORMs (Prisma 8, etc.) | 🟡 **Planejados, ainda não publicados.** Nenhum pacote oficial existe ainda — por enquanto, escreva o seu próprio adapter (veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)) e considere publicá-lo/contribuir de volta com o projeto. |
|
|
108
|
+
| Adapters customizados | 🟢 Totalmente suportados hoje — implemente você mesmo a classe abstrata [`VSRepoAdapter`](#escrevendo-seu-próprio-adapter) para qualquer ORM/banco que precisar, no seu próprio projeto ou pacote, seguindo o mesmo formato esperado dos `@vsrepo/*-adapter`. |
|
|
108
109
|
|
|
109
110
|
Resumindo: a classe de repository, os decoradores `@DynamicMethod`/`@QueryMethod`, o engine de parsing de nomes, o tratamento de erros e o logging já funcionam de ponta a ponta, e o suporte ao Prisma 7 agora é um adapter lançado e publicado. Adapters oficiais para os demais ORMs estão no roadmap e serão distribuídos como pacotes `@vsrepo/*-adapter` separados, e não como parte do pacote core `vsrepo` — mas você não precisa esperar por isso: escrever (e opcionalmente publicar) o seu próprio adapter enquanto isso é uma forma totalmente suportada de usar a v2 hoje e de contribuir de volta com o projeto.
|
|
110
111
|
|
|
@@ -172,6 +173,7 @@ export default new UserRepository();
|
|
|
172
173
|
> A API do core (`VSRepository`, `VSRepoAdapter`, `DynamicMethod`, `QueryMethod`, `VSRepoError`, enums e tipos) é importada do entry point único `vsrepo`. O adapter concreto vem de um pacote **separado** (`@vsrepo/*-adapter`). No Prisma 7, instale o [`@vsrepo/prisma7-adapter`](https://github.com/jaobrabo123/VSRepoPrisma7Adapter) já publicado (o construtor dele recebe um objeto de config — `tableName`, `pkName`, `relations`/`logLevel` opcionais — como no exemplo acima). Adapters oficiais para outros ORMs estão planejados, mas ainda não publicados; até lá, você pode implementar o contrato `VSRepoAdapter` você mesmo (veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)) — e publicá-lo para ajudar o projeto é muito bem-vindo.
|
|
173
174
|
|
|
174
175
|
> **O terceiro generic (`OrmTypes`):** `VSRepository<Entity, PKType, OrmTypes>` aceita um terceiro type parameter opcional descrevendo os tipos de client/transaction do seu ORM, via `VSRepoOrmTypes` (`{ dbClient; dbTransaction }`). Ao fornecê-lo, `getDbClient()`, o callback de `transaction()` e a option `db` de todo método passam a ser tipados corretamente, em vez de `any`:
|
|
176
|
+
>
|
|
175
177
|
> ```typescript
|
|
176
178
|
> type PrismaOrmTypes = { dbClient: PrismaClient; dbTransaction: Prisma.TransactionClient };
|
|
177
179
|
>
|
|
@@ -179,6 +181,7 @@ export default new UserRepository();
|
|
|
179
181
|
> // getDbClient() agora retorna PrismaClient, e transaction(fn) tipa `tx` como Prisma.TransactionClient
|
|
180
182
|
> }
|
|
181
183
|
> ```
|
|
184
|
+
>
|
|
182
185
|
> Se omitido, o padrão é `VSRepoOrmTypes` (`dbClient`/`dbTransaction` como `any`).
|
|
183
186
|
|
|
184
187
|
### Usando o repository
|
|
@@ -221,31 +224,31 @@ await userRepository.remove(usuario.id);
|
|
|
221
224
|
|
|
222
225
|
Disponíveis automaticamente em toda subclasse de `VSRepository`:
|
|
223
226
|
|
|
224
|
-
| Método
|
|
225
|
-
|
|
|
226
|
-
| `get(pk, options?)`
|
|
227
|
-
| `getOrThrow(pk, options?)`
|
|
228
|
-
| `getList(pks, options?)`
|
|
229
|
-
| `getAll(options?)`
|
|
230
|
-
| `save(obj, options?)`
|
|
231
|
-
| `saveList(objs, options?)`
|
|
232
|
-
| `patch(pk, obj, options?)`
|
|
233
|
-
| `merge(pk, obj, options?)`
|
|
234
|
-
| `remove(pk, options?)`
|
|
235
|
-
| `removeList(pks, options?)`
|
|
236
|
-
| `total(options?)`
|
|
237
|
-
| `has(pk, options?)`
|
|
238
|
-
| `increment(pk, field, value, options?)` | Adiciona `value` a um campo numérico de forma atômica. Veja [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação).
|
|
239
|
-
| `decrement(pk, field, value, options?)` | Subtrai `value` de um campo numérico de forma atômica.
|
|
240
|
-
| `multiply(pk, field, value, options?)` | Multiplica um campo numérico por `value` de forma atômica.
|
|
241
|
-
| `divide(pk, field, value, options?)` | Divide um campo numérico por `value` de forma atômica.
|
|
242
|
-
| `sum(field, where?, options?)` | Soma um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.
|
|
243
|
-
| `average(field, where?, options?)` | Média aritmética de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.
|
|
244
|
-
| `min(field, where?, options?)` | Valor mínimo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.
|
|
245
|
-
| `max(field, where?, options?)` | Valor máximo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater.
|
|
246
|
-
| `transaction(fn, options?)`
|
|
247
|
-
| `getDbClient()`
|
|
248
|
-
| `query<T>(query, options?)`
|
|
227
|
+
| Método | Descrição |
|
|
228
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
+
| `get(pk, options?)` | Busca um registro pela primary key. |
|
|
230
|
+
| `getOrThrow(pk, options?)` | Busca um registro pela primary key, lançando erro se não encontrar. |
|
|
231
|
+
| `getList(pks, options?)` | Busca vários registros por uma lista de primary keys. |
|
|
232
|
+
| `getAll(options?)` | Busca todos os registros; aceita `pagination` e `order` em `options`. |
|
|
233
|
+
| `save(obj, options?)` | Cria ou atualiza (upsert) um único registro. |
|
|
234
|
+
| `saveList(objs, options?)` | Cria ou atualiza (upsert) vários registros em uma única chamada. |
|
|
235
|
+
| `patch(pk, obj, options?)` | Atualiza parcialmente um registro pela primary key. |
|
|
236
|
+
| `merge(pk, obj, options?)` | Busca um registro e o retorna mesclado (deep-merge), em memória, com o objeto informado — **não** persiste nada. |
|
|
237
|
+
| `remove(pk, options?)` | Remove um registro pela primary key. |
|
|
238
|
+
| `removeList(pks, options?)` | Remove vários registros pela primary key, retornando `{ count }`. |
|
|
239
|
+
| `total(options?)` | Retorna o total de registros. |
|
|
240
|
+
| `has(pk, options?)` | Verifica se um registro existe, retornando `boolean`. |
|
|
241
|
+
| `increment(pk, field, value, options?)` | Adiciona `value` a um campo numérico de forma atômica. Veja [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação). |
|
|
242
|
+
| `decrement(pk, field, value, options?)` | Subtrai `value` de um campo numérico de forma atômica. |
|
|
243
|
+
| `multiply(pk, field, value, options?)` | Multiplica um campo numérico por `value` de forma atômica. |
|
|
244
|
+
| `divide(pk, field, value, options?)` | Divide um campo numérico por `value` de forma atômica. |
|
|
245
|
+
| `sum(field, where?, options?)` | Soma um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater. |
|
|
246
|
+
| `average(field, where?, options?)` | Média aritmética de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater. |
|
|
247
|
+
| `min(field, where?, options?)` | Valor mínimo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater. |
|
|
248
|
+
| `max(field, where?, options?)` | Valor máximo de um campo numérico em todos os registros que baterem no filtro; `null` se nenhum bater. |
|
|
249
|
+
| `transaction(fn, options?)` | Executa `fn` dentro de uma transação nativa do ORM. |
|
|
250
|
+
| `getDbClient()` | Retorna a instância do client do ORM usada fora de transações. |
|
|
251
|
+
| `query<T>(query, options?)` | Executa uma instrução SQL raw diretamente contra o banco. Veja [Queries raw pontuais com `query()`](#queries-raw-pontuais-com-query). |
|
|
249
252
|
|
|
250
253
|
A maioria dos métodos acima aceita um objeto `MethodOptions<Entity, OrmTypes>` como último argumento (`select`, `relations`, `see`, `db`). Alguns — `total`, `has`, `removeList`, `sum`, `average`, `min`, `max`, e os métodos em lote de soft-delete (`softRemoveList`/`restoreList`) — não retornam/moldam uma `Entity`, então aceitam o tipo mais restrito `RestrictMethodOptions<Entity, OrmTypes>` (só `see`, `db`; sem `select`/`relations`). `transaction`, `query` e `getDbClient` recebem options próprias ou nenhuma.
|
|
251
254
|
|
|
@@ -286,7 +289,7 @@ await userRepository.getAll({ see: "all" }); // todos, ignorando o soft-delete
|
|
|
286
289
|
|
|
287
290
|
Toda subclasse de `VSRepository` ganha 8 métodos extras para trabalhar com campos numéricos, divididos em dois grupos:
|
|
288
291
|
|
|
289
|
-
**Updates atômicos** — avaliados no servidor contra o valor
|
|
292
|
+
**Updates atômicos** — avaliados no servidor contra o valor _atual_ da linha (`UPDATE ... SET field = field + value`), não um read-modify-write feito no client:
|
|
290
293
|
|
|
291
294
|
```typescript
|
|
292
295
|
await userRepository.increment("user-1", "balance", 50); // balance = balance + 50
|
|
@@ -334,7 +337,7 @@ Vale notar que vários ORMs (Drizzle, MikroORM, TypeORM) representam colunas `de
|
|
|
334
337
|
|
|
335
338
|
### Escrevendo um adapter
|
|
336
339
|
|
|
337
|
-
O `VSRepoAdapter` espelha as mesmas 8 operações (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)). Cada adapter traduz isso para o que o ORM/banco considera "nativo": o Prisma tem um formato de update embutido (`{ field: { increment: value } }`) e uma chamada `aggregate()`; outros ORMs em geral precisam de um `QueryBuilder`/expressão `sql` raw (ex.: `SET field = field * :value`, `SELECT SUM(field) ...`). Os métodos atômicos precisam retornar o registro refletindo o estado
|
|
340
|
+
O `VSRepoAdapter` espelha as mesmas 8 operações (`incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `sum`, `average`, `min`, `max` — veja [Escrevendo seu próprio adapter](#escrevendo-seu-próprio-adapter)). Cada adapter traduz isso para o que o ORM/banco considera "nativo": o Prisma tem um formato de update embutido (`{ field: { increment: value } }`) e uma chamada `aggregate()`; outros ORMs em geral precisam de um `QueryBuilder`/expressão `sql` raw (ex.: `SET field = field * :value`, `SELECT SUM(field) ...`). Os métodos atômicos precisam retornar o registro refletindo o estado _depois_ do write — se a API de update atômico do ORM só retorna a quantidade de linhas afetadas, faça uma leitura extra em vez de devolver uma cópia desatualizada que já estava em memória.
|
|
338
341
|
|
|
339
342
|
---
|
|
340
343
|
|
|
@@ -418,38 +421,38 @@ class UserRepository extends VSRepository<User, string> {
|
|
|
418
421
|
|
|
419
422
|
### Prefixos disponíveis
|
|
420
423
|
|
|
421
|
-
| Prefixo | Método do adapter | Observações
|
|
422
|
-
| -------------------------- | --------------------- |
|
|
423
|
-
| `findBy` | `findMany` | Filtros de campo seguem o prefixo.
|
|
424
|
-
| `findOneBy` | `findOne` | Filtros de campo seguem o prefixo; resultado único.
|
|
425
|
-
| `findOneOrThrowBy` | `findOneOrThrow` | Lança erro se não encontrar.
|
|
426
|
-
| `findOneOrThrow` | `findOneOrThrow` | Sem filtros de campo; aplica só soft-delete/`see`.
|
|
427
|
-
| `findOneOrThrowWhere` | `findOneOrThrow` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
428
|
-
| `findWhere` | `findMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
429
|
-
| `findOneWhere` | `findOne` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
430
|
-
| `findOne` | `findOne` | Sem filtros de campo; aplica só soft-delete/`see`.
|
|
431
|
-
| `countBy` | `count` | Filtros de campo seguem o prefixo.
|
|
432
|
-
| `countWhere` | `count` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
433
|
-
| `count` | `count` | Sem filtros de campo.
|
|
434
|
-
| `existsBy` | `exists` | Retorna `boolean`.
|
|
435
|
-
| `existsWhere` | `exists` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
436
|
-
| `create` | `create` | Recebe `data` como argumento.
|
|
437
|
-
| `createMany` | `createMany` | Recebe `data[]` como argumento; suporta `IgnoreConflicts`.
|
|
424
|
+
| Prefixo | Método do adapter | Observações |
|
|
425
|
+
| -------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
426
|
+
| `findBy` | `findMany` | Filtros de campo seguem o prefixo. |
|
|
427
|
+
| `findOneBy` | `findOne` | Filtros de campo seguem o prefixo; resultado único. |
|
|
428
|
+
| `findOneOrThrowBy` | `findOneOrThrow` | Lança erro se não encontrar. |
|
|
429
|
+
| `findOneOrThrow` | `findOneOrThrow` | Sem filtros de campo; aplica só soft-delete/`see`. |
|
|
430
|
+
| `findOneOrThrowWhere` | `findOneOrThrow` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
431
|
+
| `findWhere` | `findMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
432
|
+
| `findOneWhere` | `findOne` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
433
|
+
| `findOne` | `findOne` | Sem filtros de campo; aplica só soft-delete/`see`. |
|
|
434
|
+
| `countBy` | `count` | Filtros de campo seguem o prefixo. |
|
|
435
|
+
| `countWhere` | `count` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
436
|
+
| `count` | `count` | Sem filtros de campo. |
|
|
437
|
+
| `existsBy` | `exists` | Retorna `boolean`. |
|
|
438
|
+
| `existsWhere` | `exists` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
439
|
+
| `create` | `create` | Recebe `data` como argumento. |
|
|
440
|
+
| `createMany` | `createMany` | Recebe `data[]` como argumento; suporta `IgnoreConflicts`. |
|
|
438
441
|
| `createManyReturning` | `createManyReturning` | Recebe `data[]` como argumento; suporta `IgnoreConflicts`; retorna os registros criados (`T[]`), em vez de `CountResult`. |
|
|
439
|
-
| `updateBy` | `update` | Filtros de campo + `data` como argumento.
|
|
440
|
-
| `updateWhere` | `update` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`.
|
|
441
|
-
| `updateManyBy` | `updateMany` | Filtros de campo + `data`.
|
|
442
|
-
| `updateManyWhere` | `updateMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`.
|
|
443
|
-
| `updateManyReturningBy` | `updateManyReturning` | Filtros de campo + `data`; retorna os registros atualizados.
|
|
444
|
-
| `updateManyReturningWhere` | `updateManyReturning` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`; retorna os registros atualizados.
|
|
445
|
-
| `upsertBy` | `upsert` | Filtros de campo + payloads `create`/`update`.
|
|
446
|
-
| `upsertWhere` | `upsert` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois os payloads `create`/`update`.
|
|
447
|
-
| `deleteBy` | `delete` | Filtros de campo seguem o prefixo.
|
|
448
|
-
| `deleteWhere` | `delete` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
449
|
-
| `deleteManyBy` | `deleteMany` | Filtros de campo seguem o prefixo.
|
|
450
|
-
| `deleteManyWhere` | `deleteMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento.
|
|
451
|
-
| `deleteManyReturningBy` | `deleteManyReturning` | Filtros de campo seguem o prefixo; retorna os registros removidos.
|
|
452
|
-
| `deleteManyReturningWhere` | `deleteManyReturning` | Recebe um `VSRepoWhere<T>` como primeiro argumento; retorna os registros removidos.
|
|
442
|
+
| `updateBy` | `update` | Filtros de campo + `data` como argumento. |
|
|
443
|
+
| `updateWhere` | `update` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`. |
|
|
444
|
+
| `updateManyBy` | `updateMany` | Filtros de campo + `data`. |
|
|
445
|
+
| `updateManyWhere` | `updateMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`. |
|
|
446
|
+
| `updateManyReturningBy` | `updateManyReturning` | Filtros de campo + `data`; retorna os registros atualizados. |
|
|
447
|
+
| `updateManyReturningWhere` | `updateManyReturning` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois `data`; retorna os registros atualizados. |
|
|
448
|
+
| `upsertBy` | `upsert` | Filtros de campo + payloads `create`/`update`. |
|
|
449
|
+
| `upsertWhere` | `upsert` | Recebe um `VSRepoWhere<T>` como primeiro argumento, depois os payloads `create`/`update`. |
|
|
450
|
+
| `deleteBy` | `delete` | Filtros de campo seguem o prefixo. |
|
|
451
|
+
| `deleteWhere` | `delete` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
452
|
+
| `deleteManyBy` | `deleteMany` | Filtros de campo seguem o prefixo. |
|
|
453
|
+
| `deleteManyWhere` | `deleteMany` | Recebe um `VSRepoWhere<T>` como primeiro argumento. |
|
|
454
|
+
| `deleteManyReturningBy` | `deleteManyReturning` | Filtros de campo seguem o prefixo; retorna os registros removidos. |
|
|
455
|
+
| `deleteManyReturningWhere` | `deleteManyReturning` | Recebe um `VSRepoWhere<T>` como primeiro argumento; retorna os registros removidos. |
|
|
453
456
|
|
|
454
457
|
> `aggregate` e `groupBy` **ainda não estão implementados** na v2 (existiam na v1). Está planejado, mas não disponível no momento.
|
|
455
458
|
|
|
@@ -590,7 +593,7 @@ declare findByStatus: (status: string) => Promise<User[]>;
|
|
|
590
593
|
|
|
591
594
|
## Query methods (SQL raw)
|
|
592
595
|
|
|
593
|
-
`@QueryMethod` ignora totalmente o engine de parsing por nome e executa uma instrução SQL raw através do método `query()` do adapter. Use placeholders
|
|
596
|
+
`@QueryMethod` ignora totalmente o engine de parsing por nome e executa uma instrução SQL raw através do método `query()` do adapter. Use placeholders para os valores passados via `args` — nunca interpole valores diretamente na string SQL. **A sintaxe dos placeholders depende do banco/driver usado pelo seu adapter:** o estilo `$1`, `$2`, ... usado nos exemplos abaixo é a convenção do PostgreSQL — o MySQL, por exemplo, usa `?`. Consulte a documentação do seu adapter para saber a sintaxe exata.
|
|
594
597
|
|
|
595
598
|
```typescript
|
|
596
599
|
class UserRepository extends VSRepository<User, string> {
|
|
@@ -607,9 +610,9 @@ class UserRepository extends VSRepository<User, string> {
|
|
|
607
610
|
}
|
|
608
611
|
```
|
|
609
612
|
|
|
610
|
-
| Option | Tipo | Padrão | Descrição
|
|
611
|
-
| -------------- | --------- | ------- |
|
|
612
|
-
| `modifying` | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado.
|
|
613
|
+
| Option | Tipo | Padrão | Descrição |
|
|
614
|
+
| -------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
615
|
+
| `modifying` | `boolean` | `false` | Quando `true`, executa como `INSERT`/`UPDATE`/`DELETE` e o método resolve para o número de linhas afetadas. Quando `false`, executa como query de leitura e resolve para o tipo de retorno declarado. |
|
|
613
616
|
| `singleResult` | `boolean` | `false` | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio), permitindo declarar o tipo de retorno como um objeto único em vez de array. Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
|
|
614
617
|
|
|
615
618
|
Query methods aceitam `{ args, db? }` na chamada — `db` permite que participem de um bloco `transaction()`, assim como os métodos base e dinâmicos.
|
|
@@ -634,7 +637,7 @@ const admins = await userRepository.findByEmailAndType("joao@email.com", "admin"
|
|
|
634
637
|
Para rodar a query com um client ou transação específico em vez do client padrão do repository, passe `withDb(tx)` como argumento final — ele embrulha `tx` em um `DbArg`, que o resolver reconhece via `instanceof`, então nunca é confundido com um argumento posicional comum, mesmo que esse argumento seja um objeto:
|
|
635
638
|
|
|
636
639
|
```typescript
|
|
637
|
-
await userRepository.transaction(async
|
|
640
|
+
await userRepository.transaction(async tx => {
|
|
638
641
|
await userRepository.findByEmailAndType("joao@email.com", "admin", withDb(tx));
|
|
639
642
|
});
|
|
640
643
|
```
|
|
@@ -661,18 +664,18 @@ const linhasAfetadas = await userRepository.query<number>(
|
|
|
661
664
|
|
|
662
665
|
// Aqui só se espera uma linha, então `singleResult` transforma o array
|
|
663
666
|
// em um único objeto (ou `null` quando nenhuma linha corresponde).
|
|
664
|
-
const user = await userRepository.query<User | null>(
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
);
|
|
667
|
+
const user = await userRepository.query<User | null>('SELECT * FROM "user" WHERE id = $1 LIMIT 1', {
|
|
668
|
+
args: ["123"],
|
|
669
|
+
singleResult: true,
|
|
670
|
+
});
|
|
668
671
|
```
|
|
669
672
|
|
|
670
|
-
| Option | Tipo | Padrão | Descrição
|
|
671
|
-
| -------------- | --------- |
|
|
672
|
-
| `args` | `any[]` | `undefined`
|
|
673
|
-
| `db` | `any` | Client padrão do repository
|
|
674
|
-
| `modifying` | `boolean` | `false`
|
|
675
|
-
| `singleResult` | `boolean` | `false`
|
|
673
|
+
| Option | Tipo | Padrão | Descrição |
|
|
674
|
+
| -------------- | --------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
675
|
+
| `args` | `any[]` | `undefined` | Parâmetros posicionais injetados nos placeholders do SQL — a sintaxe dos placeholders depende do banco/driver usado pelo seu adapter. Nunca interpole valores diretamente na string SQL. |
|
|
676
|
+
| `db` | `any` | Client padrão do repository | Client ou transação do banco em que essa query deve rodar. |
|
|
677
|
+
| `modifying` | `boolean` | `false` | Quando `true`, trata a instrução como `INSERT`/`UPDATE`/`DELETE`. |
|
|
678
|
+
| `singleResult` | `boolean` | `false` | Quando `true`, transforma um resultado em array no seu primeiro elemento (`null` se vazio). Não tem efeito em resultados que não são array (ex.: o número de linhas afetadas de uma query `modifying`). |
|
|
676
679
|
|
|
677
680
|
Assim como os métodos base, dinâmicos e query, `query()` aceita `db` em `options` para participar de um bloco `transaction()`.
|
|
678
681
|
|
|
@@ -711,10 +714,10 @@ await userRepository.transaction(
|
|
|
711
714
|
);
|
|
712
715
|
```
|
|
713
716
|
|
|
714
|
-
| Option | Type
|
|
715
|
-
|
|
|
717
|
+
| Option | Type | Descrição |
|
|
718
|
+
| ---------------- | --------------------------- | ---------------------------------------------------------------------------------- |
|
|
716
719
|
| `isolationLevel` | `TransactionIsolationLevel` | Nível de isolamento usado na transação. O padrão é o default do ORM por trás dela. |
|
|
717
|
-
| `timeoutMs`
|
|
720
|
+
| `timeoutMs` | `number` | Tempo máximo (em ms) que a transação pode rodar antes de ser abortada. |
|
|
718
721
|
|
|
719
722
|
`TransactionIsolationLevel` espelha os níveis de isolamento SQL padrão: `READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`. O suporte a um determinado nível depende do adapter/ORM e do banco de dados por trás dele.
|
|
720
723
|
|
|
@@ -749,26 +752,26 @@ import type {
|
|
|
749
752
|
} from "vsrepo";
|
|
750
753
|
```
|
|
751
754
|
|
|
752
|
-
| Tipo | Descrição
|
|
753
|
-
| --------------------------------------------------- |
|
|
754
|
-
| `MethodOptions<T, K>` | Options aceitas como último argumento pela maioria dos métodos base e dinâmicos: `select`, `relations`, `see`, `db`.
|
|
755
|
-
| `RestrictMethodOptions<T, K>` | `MethodOptions<T, K>` restrito, expondo só `see`/`db` — usado pelos métodos que não retornam/moldam uma `Entity` (`total`, `has`, `sum`, `average`, `min`, `max`, `removeList`, `softRemoveList`, `restoreList`).
|
|
756
|
-
| `Pagination` | `{ limit?, offset? }` aceito por `getAll` e pelos métodos dinâmicos com `Paginated`.
|
|
757
|
-
| `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Formato de ordenação aceito por `getAll`, `defaultOrdering` e `injectOrdering`, e pelos métodos dinâmicos com `Ordered`. Pode ser um único objeto ou um array encadeado; objetos aninhados ordenam relações to-one.
|
|
758
|
-
| `SeeMode` | `"active" \| "removed" \| "all"` — controla a visibilidade de registros com soft-delete.
|
|
759
|
-
| `DeepPartial<T>` | Torna todas as propriedades de `T` opcionais recursivamente, incluindo objetos aninhados e elementos de array.
|
|
760
|
-
| `CountResult` | `{ count: number }` — o formato retornado por operações em lote.
|
|
761
|
-
| `QueryMethodArg<T>` | `{ args?: T, db? }` — parâmetros posicionais do SQL (`$1`, `$2`, ...) e cliente de transação para o `@QueryMethod`.
|
|
762
|
-
| `QueryArgs<T, O>` | Tipa a lista de parâmetros via spread de um `@QueryMethod` declarado com `{ spreadArgs: true }`: os valores de `T`, em ordem, seguidos de um `DbArg<O>` opcional construído via `withDb()`.
|
|
763
|
-
| `KeysOfType<T, K>` | Extrai as chaves de `T` cujo tipo de valor é atribuível a `K`.
|
|
764
|
-
| `NumericKeys<T>` | Extrai as chaves de `T` cujo tipo de valor (ignorando `null`/`undefined`) é atribuível a `NumericLike`. Campos numéricos nullable (`number \| null`) são incluídos.
|
|
765
|
-
| `NumericLike` | `number \| bigint \| DecimalLike`.
|
|
766
|
-
| `DecimalLike` | Formato estrutural de um valor decimal de precisão arbitrária (`{ toNumber(): number; decimalPlaces(): number }`), compatível com o `Prisma.Decimal` do Prisma sem precisar importá-lo diretamente.
|
|
767
|
-
| `Primitive` | União de tipos escalares (`string \| number \| boolean \| bigint \| symbol \| undefined \| null \| Date`) tratados como valores-folha — e não relações — ao percorrer o formato de uma entidade.
|
|
768
|
-
| `VSRepoWhere<T>` | Tipo de filtro agnóstico de ORM aceito pelos métodos dinâmicos `*Where` (ex.: `findWhere`, `findOneWhere`, `updateWhere`). Suporta filtros de campo, operadores lógicos (`AND`/`OR`/`NOT`) e filtros de relação.
|
|
755
|
+
| Tipo | Descrição | Usado por |
|
|
756
|
+
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
757
|
+
| `MethodOptions<T, K>` | Options aceitas como último argumento pela maioria dos métodos base e dinâmicos: `select`, `relations`, `see`, `db`. | [Métodos base](#métodos-base), [Métodos Dinâmicos](#métodos-dinâmicos). |
|
|
758
|
+
| `RestrictMethodOptions<T, K>` | `MethodOptions<T, K>` restrito, expondo só `see`/`db` — usado pelos métodos que não retornam/moldam uma `Entity` (`total`, `has`, `sum`, `average`, `min`, `max`, `removeList`, `softRemoveList`, `restoreList`). | [Métodos base](#métodos-base), [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação). |
|
|
759
|
+
| `Pagination` | `{ limit?, offset? }` aceito por `getAll` e pelos métodos dinâmicos com `Paginated`. | [Métodos base](#métodos-base), [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct). |
|
|
760
|
+
| `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Formato de ordenação aceito por `getAll`, `defaultOrdering` e `injectOrdering`, e pelos métodos dinâmicos com `Ordered`. Pode ser um único objeto ou um array encadeado; objetos aninhados ordenam relações to-one. | [Options do construtor](#options-do-construtor), [Options do decorador](#options-do-decorador), [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct). |
|
|
761
|
+
| `SeeMode` | `"active" \| "removed" \| "all"` — controla a visibilidade de registros com soft-delete. | [Soft-delete](#soft-delete). |
|
|
762
|
+
| `DeepPartial<T>` | Torna todas as propriedades de `T` opcionais recursivamente, incluindo objetos aninhados e elementos de array. | `save`, `saveList`, `patch`, `merge`, e todo método de escrita do `VSRepoAdapter`. |
|
|
763
|
+
| `CountResult` | `{ count: number }` — o formato retornado por operações em lote. | `removeList`, `softRemoveList`, `restoreList`, `createManyIgnoreConflicts`. |
|
|
764
|
+
| `QueryMethodArg<T>` | `{ args?: T, db? }` — parâmetros posicionais do SQL (a sintaxe dos placeholders depende do banco/driver usado pelo seu adapter: `$1`, `$2`, ... para PostgreSQL, `?` para MySQL) e cliente de transação para o `@QueryMethod`. | [Query methods (SQL raw)](#query-methods-sql-raw). |
|
|
765
|
+
| `QueryArgs<T, O>` | Tipa a lista de parâmetros via spread de um `@QueryMethod` declarado com `{ spreadArgs: true }`: os valores de `T`, em ordem, seguidos de um `DbArg<O>` opcional construído via `withDb()`. | [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs). |
|
|
766
|
+
| `KeysOfType<T, K>` | Extrai as chaves de `T` cujo tipo de valor é atribuível a `K`. | Restringe `pkName`, em [Options do construtor](#options-do-construtor), aos campos da entidade compatíveis com o tipo de chave primária configurado. |
|
|
767
|
+
| `NumericKeys<T>` | Extrai as chaves de `T` cujo tipo de valor (ignorando `null`/`undefined`) é atribuível a `NumericLike`. Campos numéricos nullable (`number \| null`) são incluídos. | Restringe `field` em [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação) (`increment`, `sum`, etc). |
|
|
768
|
+
| `NumericLike` | `number \| bigint \| DecimalLike`. | [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação). |
|
|
769
|
+
| `DecimalLike` | Formato estrutural de um valor decimal de precisão arbitrária (`{ toNumber(): number; decimalPlaces(): number }`), compatível com o `Prisma.Decimal` do Prisma sem precisar importá-lo diretamente. | [Quais campos são elegíveis](#quais-campos-são-elegíveis). |
|
|
770
|
+
| `Primitive` | União de tipos escalares (`string \| number \| boolean \| bigint \| symbol \| undefined \| null \| Date`) tratados como valores-folha — e não relações — ao percorrer o formato de uma entidade. | Usado por `Ordering<T>` para distinguir campos escalares de campos de relação. |
|
|
771
|
+
| `VSRepoWhere<T>` | Tipo de filtro agnóstico de ORM aceito pelos métodos dinâmicos `*Where` (ex.: `findWhere`, `findOneWhere`, `updateWhere`). Suporta filtros de campo, operadores lógicos (`AND`/`OR`/`NOT`) e filtros de relação. | [Prefixos `findWhere`, `findOneWhere` e demais `*Where`](#prefixos-disponíveis). |
|
|
769
772
|
| `VSRepoOrmTypes` | `{ dbClient; dbTransaction }` — descreve os tipos de client/transaction do seu ORM. Passado como terceiro generic de `VSRepository<Entity, PKType, OrmTypes>` para tipar `getDbClient()`, `transaction()` e a option `db` em vez de `any`. | [Criando um repository](#criando-um-repository). |
|
|
770
|
-
| `VSRepoTransactionOptions` | `{ isolationLevel?, timeoutMs? }` — options aceitas como segundo argumento de `transaction()`.
|
|
771
|
-
| `TransactionIsolationLevel` | Enum dos níveis de isolamento SQL padrão (`READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`) aceitos por `VSRepoTransactionOptions.isolationLevel`.
|
|
773
|
+
| `VSRepoTransactionOptions` | `{ isolationLevel?, timeoutMs? }` — options aceitas como segundo argumento de `transaction()`. | [Transações](#transações). |
|
|
774
|
+
| `TransactionIsolationLevel` | Enum dos níveis de isolamento SQL padrão (`READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`) aceitos por `VSRepoTransactionOptions.isolationLevel`. | [Transações](#transações). |
|
|
772
775
|
|
|
773
776
|
### `DeepPartial<T>`
|
|
774
777
|
|
|
@@ -947,13 +950,13 @@ export class MyOrmAdapter<T> extends VSRepoAdapter<T> {
|
|
|
947
950
|
}
|
|
948
951
|
```
|
|
949
952
|
|
|
950
|
-
| Método
|
|
951
|
-
|
|
|
952
|
-
| `new VSLogger(logLevel, name, slowThresholdMs?)`
|
|
953
|
-
| `logDebug/logInfo/logWarn(text, obj?)`
|
|
954
|
-
| `logError(text, err?)`
|
|
953
|
+
| Método | Descrição |
|
|
954
|
+
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
955
|
+
| `new VSLogger(logLevel, name, slowThresholdMs?)` | Cria um logger; `name` prefixa cada linha, `slowThresholdMs` tem default 300. |
|
|
956
|
+
| `logDebug/logInfo/logWarn(text, obj?)` | Loga no nível dado se `logLevel` permitir; `obj` é anexado como JSON formatado. |
|
|
957
|
+
| `logError(text, err?)` | Loga em `ERROR`; se `err` for uma `Error`, só `name`/`message`/`stack`/`cause` são logados. |
|
|
955
958
|
| `startPerformLog(operation)` / `endPerformLog(data)` | Envolve um trecho de código para logar sua duração, escalando pra `WARN` se ultrapassar `slowThresholdMs`. |
|
|
956
|
-
| `getLogLevel()`
|
|
959
|
+
| `getLogLevel()` | Retorna o `VSLogLevel` configurado do logger. |
|
|
957
960
|
|
|
958
961
|
Isso é puramente uma conveniência para autores de adapters — nada no core exige que seu adapter o utilize.
|
|
959
962
|
|
|
@@ -979,7 +982,7 @@ try {
|
|
|
979
982
|
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
980
983
|
| `DECORATOR` | Argumentos inválidos foram passados para `@DynamicMethod` ou `@QueryMethod`. |
|
|
981
984
|
| `RESOLVER` | A biblioteca falhou ao resolver a configuração de um método dinâmico/de query em um método chamável (ex.: um nome de método desconhecido). |
|
|
982
|
-
| `DYNAMIC` | Um dynamic/query method já resolvido falhou em tempo de execução (ex.: argumentos faltando).
|
|
985
|
+
| `DYNAMIC` | Um dynamic/query method já resolvido falhou em tempo de execução (ex.: argumentos faltando). |
|
|
983
986
|
| `VALIDATOR` | Options ou argumentos de método inválidos foram detectados durante a validação. |
|
|
984
987
|
| `BASE` | Uso inválido de um método base (`get`, `save`, `remove`, etc). |
|
|
985
988
|
| `ADAPTER` | Um `VSRepoAdapter` falhou ao falar com o ORM/banco subjacente — sempre é lançado como `VSRepoAdapterError`. |
|
|
@@ -1034,41 +1037,42 @@ import { AdapterErrorCode } from "vsrepo";
|
|
|
1034
1037
|
console.log(AdapterErrorCode.UNIQUE_CONSTRAINT_VIOLATION); // "UNIQUE_CONSTRAINT_VIOLATION"
|
|
1035
1038
|
```
|
|
1036
1039
|
|
|
1037
|
-
| Código | Significado
|
|
1038
|
-
| ----------------------------- |
|
|
1039
|
-
| `UNKNOWN` | Erro não classificado/desconhecido; o fallback quando nenhum código mais específico corresponde.
|
|
1040
|
-
| `
|
|
1041
|
-
| `
|
|
1042
|
-
| `
|
|
1043
|
-
| `
|
|
1044
|
-
| `
|
|
1045
|
-
| `
|
|
1046
|
-
| `
|
|
1047
|
-
| `
|
|
1048
|
-
| `
|
|
1049
|
-
| `
|
|
1050
|
-
| `
|
|
1051
|
-
| `
|
|
1052
|
-
| `
|
|
1053
|
-
| `
|
|
1054
|
-
| `
|
|
1055
|
-
| `
|
|
1056
|
-
| `
|
|
1057
|
-
| `
|
|
1058
|
-
| `
|
|
1059
|
-
| `
|
|
1060
|
-
| `
|
|
1061
|
-
| `
|
|
1062
|
-
| `
|
|
1063
|
-
| `
|
|
1064
|
-
| `
|
|
1065
|
-
| `
|
|
1066
|
-
| `
|
|
1067
|
-
| `
|
|
1068
|
-
| `
|
|
1069
|
-
| `
|
|
1070
|
-
| `
|
|
1071
|
-
| `
|
|
1040
|
+
| Código | Significado |
|
|
1041
|
+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
1042
|
+
| `UNKNOWN` | Erro não classificado/desconhecido; o fallback quando nenhum código mais específico corresponde. |
|
|
1043
|
+
| `TRANSACTION_ROLLED_BACK` | Alguns adapters podem usar esse código para rollbacks forçados de transações (como o `tx.rollback()` do Drizzle) |
|
|
1044
|
+
| `MISSING_DB_CLIENT` | Cliente de banco (ou pool de conexões) não fornecido ou que não pôde ser resolvido. |
|
|
1045
|
+
| `CONNECTION_FAILED` | Não foi possível alcançar/conectar ao banco, ou uma conexão estabelecida foi perdida/terminada. |
|
|
1046
|
+
| `CONNECTION_POOL_EXHAUSTED` | Pool de conexões esgotado/depletado — nenhuma conexão disponível, todas ocupadas ou o limite foi atingido. |
|
|
1047
|
+
| `TIMEOUT` | O banco não respondeu a tempo; uma query excedeu o timeout permitido. |
|
|
1048
|
+
| `UNIQUE_CONSTRAINT_VIOLATION` | Violação de constraint unique (chave duplicada). Ex.: Postgres/SQLite `23505`, MySQL `1062`. |
|
|
1049
|
+
| `FOREIGN_KEY_VIOLATION` | Violação de constraint de foreign key (linha referenciada não existe). |
|
|
1050
|
+
| `NOT_NULL_VIOLATION` | Violação de constraint NOT NULL. |
|
|
1051
|
+
| `CHECK_VIOLATION` | Violação de constraint CHECK. |
|
|
1052
|
+
| `CONSTRAINT_VIOLATION` | Violação geral de integridade/constraint não coberta por um código mais específico. |
|
|
1053
|
+
| `NOT_FOUND` | Registro solicitado não encontrado (ex.: uma operação tipo `findOneOrThrow`). |
|
|
1054
|
+
| `INVALID_DATA` | Valor de campo inválido para o tipo/tamanho, ou um valor obrigatório ausente. |
|
|
1055
|
+
| `VALUE_TOO_LONG` | Valor fornecido excede o limite de tamanho da coluna/campo. |
|
|
1056
|
+
| `CONVERSION_ERROR` | Um valor não pôde ser convertido/convertido para o tipo alvo. Ex.: Postgres `22P02`, MySQL `1366`. |
|
|
1057
|
+
| `INVALID_QUERY` | A query/stored procedure SQL está malformada ou é inválida. |
|
|
1058
|
+
| `TABLE_OR_COLUMN_NOT_FOUND` | A tabela/coluna/relação referenciada não existe. |
|
|
1059
|
+
| `DEADLOCK` | Operação abortada por timeout de lock ou deadlock entre transações concorrentes. |
|
|
1060
|
+
| `LOCK_TIMEOUT` | Não foi possível adquirir um lock de banco obrigatório a tempo. |
|
|
1061
|
+
| `LOCKED` | O registro está travado e não pode ser modificado. |
|
|
1062
|
+
| `ACCESS_DENIED` | O usuário/role atual não tem permissão para a operação. |
|
|
1063
|
+
| `INVALID_CREDENTIALS` | Credenciais de conexão inválidas (host/usuário/senha). |
|
|
1064
|
+
| `ROW_NOT_ALLOWED` | O usuário autenticado não é dono do registro / a segurança em nível de linha rejeitou. |
|
|
1065
|
+
| `MODEL_NOT_FOUND` | Entidade/modelo ou tabela não definida/mapeada no ORM, ou o adapter não tem os metadados do modelo. |
|
|
1066
|
+
| `FIELD_NOT_FOUND` | Nome de campo/coluna nos dados ou no `where` não existe na entidade/modelo. |
|
|
1067
|
+
| `TRANSACTION_CLOSED` | Transação usada depois de commit/rollback. |
|
|
1068
|
+
| `TRANSACTION_ALREADY_STARTED` | Uma transação aninhada não pôde ser aberta (ex.: chamadas `transaction()` aninhadas). |
|
|
1069
|
+
| `TRANSACTION_CONFLICT` | Uma transação falhou ao commitar e foi desfeita. |
|
|
1070
|
+
| `TRANSACTION_NOT_STARTED` | Nenhuma transação ativa quando uma era obrigatória. |
|
|
1071
|
+
| `CONNECTION_CLOSED` | Conexão fechada/terminada enquanto uma transação ou query estava em andamento. |
|
|
1072
|
+
| `INVALID_PARTIAL` | `merge`/`upsert`/`update` recebeu um objeto parcial inválido ou faltando chaves obrigatórias. |
|
|
1073
|
+
| `NOT_SUPPORTED` | Feature/operação não suportada solicitada ao adapter (ex.: `query()` bruto não suportado). |
|
|
1074
|
+
| `INVALID_ADAPTER_CONFIG` | Configuração do adapter inválida ou incompleta (options obrigatórias ausentes, ou com tipo/valor inválido). |
|
|
1075
|
+
| `INTERNAL` | Bug interno do adapter ou estado irrecuperável; deve raramente ser usado — prefira um código mais específico. |
|
|
1072
1076
|
|
|
1073
1077
|
#### `VSRepoError` vs. erros brutos do ORM
|
|
1074
1078
|
|
package/dist/VSRepoAdapter.js
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"VSRepoAdapter.js","sourceRoot":"","sources":["../src/VSRepoAdapter.ts"],"names":[],"mappings":";;;AAQA;;;;;;;;;;;GAWG;AACH,MAAsB,aAAa;CAyMlC;AAzMD,sCAyMC"}
|
package/dist/VSRepository.d.ts
CHANGED
|
@@ -9,7 +9,6 @@ import { VSRepoTransactionOptions } from "./types/vsrepo/vsrepo-transaction-opti
|
|
|
9
9
|
import { MethodOptions } from "./types/utils/methods-options.type";
|
|
10
10
|
import { Ordering } from "./types/utils/ordering.type";
|
|
11
11
|
import { Pagination } from "./types/utils/pagination.type";
|
|
12
|
-
import { VSRepoArgs } from "./types/vsrepo/vsrepo-args.type";
|
|
13
12
|
import { VSRepoQueryOptions } from "./types/vsrepo/vsrepo-query-options.type";
|
|
14
13
|
import { NumericKeys } from "./types/utils/numeric-keys.type";
|
|
15
14
|
import { RestrictMethodOptions } from "./types/utils/restrict-method-options.type";
|
|
@@ -52,11 +51,6 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
|
|
|
52
51
|
private readonly validator;
|
|
53
52
|
private readonly softRemoveKey?;
|
|
54
53
|
private readonly defaultOrdering?;
|
|
55
|
-
/**
|
|
56
|
-
* This is a property managed by VSRepository, please don't modify it!!
|
|
57
|
-
* @internal
|
|
58
|
-
*/
|
|
59
|
-
$vsrepocache: Map<string, (args: any[], methodOptions?: MethodOptions<Entity, OrmTypes>) => VSRepoArgs<Entity>>;
|
|
60
54
|
/**
|
|
61
55
|
* Creates a configured instance of `VSRepository`, resolving and validating
|
|
62
56
|
* every `@DynamicMethod`/`@QueryMethod` declared on the subclass.
|
|
@@ -76,8 +70,9 @@ export declare abstract class VSRepository<Entity, PKType, OrmTypes extends VSRe
|
|
|
76
70
|
/**
|
|
77
71
|
* Executes a raw query/statement directly against the underlying database.
|
|
78
72
|
*
|
|
79
|
-
* Use
|
|
80
|
-
*
|
|
73
|
+
* Use placeholders for values passed via `options.args` — never interpolate
|
|
74
|
+
* values directly into `query`, to avoid SQL injection. The placeholder
|
|
75
|
+
* syntax depends on the database/driver behind your adapter.
|
|
81
76
|
* Set `options.modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
|
|
82
77
|
* Set `options.singleResult: true` to collapse an array result into its
|
|
83
78
|
* first element (`null` if empty) — see {@link VSRepoQueryOptions.singleResult}.
|
package/dist/VSRepository.js
CHANGED
|
@@ -138,8 +138,9 @@ class VSRepository {
|
|
|
138
138
|
/**
|
|
139
139
|
* Executes a raw query/statement directly against the underlying database.
|
|
140
140
|
*
|
|
141
|
-
* Use
|
|
142
|
-
*
|
|
141
|
+
* Use placeholders for values passed via `options.args` — never interpolate
|
|
142
|
+
* values directly into `query`, to avoid SQL injection. The placeholder
|
|
143
|
+
* syntax depends on the database/driver behind your adapter.
|
|
143
144
|
* Set `options.modifying: true` for `INSERT`/`UPDATE`/`DELETE` statements.
|
|
144
145
|
* Set `options.singleResult: true` to collapse an array result into its
|
|
145
146
|
* first element (`null` if empty) — see {@link VSRepoQueryOptions.singleResult}.
|
|
@@ -345,3 +346,4 @@ class VSRepository {
|
|
|
345
346
|
}
|
|
346
347
|
}
|
|
347
348
|
exports.VSRepository = VSRepository;
|
|
349
|
+
//# sourceMappingURL=VSRepository.js.map
|