vsrepo 2.5.0-beta → 2.5.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/CHANGELOG.md +12 -0
- package/README.md +10 -10
- package/README.pt-BR.md +10 -10
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,18 @@ All notable changes to this project will be documented in this file.
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [2.5.0] - 2026-09-20
|
|
10
|
+
|
|
11
|
+
> Promotes `2.5.0-beta` to stable.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## [2.5.0] - 2026-09-20 (Português)
|
|
16
|
+
|
|
17
|
+
> Promove `2.5.0-beta` para estável.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
9
21
|
## [2.5.0-beta] - 2026-09-19
|
|
10
22
|
|
|
11
23
|
### Added
|
package/README.md
CHANGED
|
@@ -41,7 +41,7 @@ VSRepository lets you create strongly-typed repositories with:
|
|
|
41
41
|
- [Which fields are eligible](#which-fields-are-eligible)
|
|
42
42
|
- [Writing an adapter](#writing-an-adapter)
|
|
43
43
|
- [`select` and `relations`](#select-and-relations)
|
|
44
|
-
- [Strict return typing with `InferMethodReturn`
|
|
44
|
+
- [Strict return typing with `InferMethodReturn`](#strict-return-typing-with-infermethodreturn)
|
|
45
45
|
- [Dynamic methods](#dynamic-methods)
|
|
46
46
|
- [Available prefixes](#available-prefixes)
|
|
47
47
|
- [Field filters](#field-filters)
|
|
@@ -49,7 +49,7 @@ VSRepository lets you create strongly-typed repositories with:
|
|
|
49
49
|
- [Relation filters](#relation-filters)
|
|
50
50
|
- [Ordering, pagination and distinct](#ordering-pagination-and-distinct)
|
|
51
51
|
- [Decorator options](#decorator-options)
|
|
52
|
-
- [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype
|
|
52
|
+
- [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype)
|
|
53
53
|
- [Query methods (raw SQL)](#query-methods-raw-sql)
|
|
54
54
|
- [Spread arguments with `spreadArgs`](#spread-arguments-with-spreadargs)
|
|
55
55
|
- [Ad-hoc raw queries with `query()`](#ad-hoc-raw-queries-with-query)
|
|
@@ -373,7 +373,7 @@ const userWithAddress = await userRepository.get(id, {
|
|
|
373
373
|
>
|
|
374
374
|
> Custom adapters may map `relations` differently — consult the adapter's documentation for the exact semantics.
|
|
375
375
|
|
|
376
|
-
### Strict return typing with `InferMethodReturn`
|
|
376
|
+
### Strict return typing with `InferMethodReturn`
|
|
377
377
|
|
|
378
378
|
By default, methods are typed as returning the **whole entity**, ignoring the `select` and `relations` you pass (the same approach TypeORM takes). If you prefer a stricter type, `InferMethodReturn<T, Options>` narrows it to what was actually requested. It is opt-in and purely a type-level utility — nothing changes at runtime.
|
|
379
379
|
|
|
@@ -411,7 +411,7 @@ const users: InferMethodReturn<User[], typeof options> = await userRepository.ge
|
|
|
411
411
|
- `see` and `db` don't affect the result.
|
|
412
412
|
- Keep the options' literal types, using `satisfies MethodOptions<T>` (as above) or passing them inline. If they are typed as a plain `MethodOptions<T>` (e.g. `const options: MethodOptions<User> = ...`), nothing is known at compile time and `T` is returned unchanged.
|
|
413
413
|
- Optional (`?`) fields and relations of the entity stay optional.
|
|
414
|
-
- To get this inference directly on dynamic methods, see [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype
|
|
414
|
+
- To get this inference directly on dynamic methods, see [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype).
|
|
415
415
|
|
|
416
416
|
---
|
|
417
417
|
|
|
@@ -449,7 +449,7 @@ class UserRepository extends VSRepository<User, string> {
|
|
|
449
449
|
}
|
|
450
450
|
```
|
|
451
451
|
|
|
452
|
-
> Want the return type to follow the `select`/`relations` you pass, instead of always being the whole entity? Declare the method with [`InferMethodType`](#strict-return-typing-with-infermethodtype
|
|
452
|
+
> Want the return type to follow the `select`/`relations` you pass, instead of always being the whole entity? Declare the method with [`InferMethodType`](#strict-return-typing-with-infermethodtype).
|
|
453
453
|
|
|
454
454
|
### Available prefixes
|
|
455
455
|
|
|
@@ -626,9 +626,9 @@ declare buscarPorEmail: (email: string, options?: MethodOptions<User>) => Promis
|
|
|
626
626
|
declare findByStatus: (status: string) => Promise<User[]>;
|
|
627
627
|
```
|
|
628
628
|
|
|
629
|
-
### Strict return typing with `InferMethodType`
|
|
629
|
+
### Strict return typing with `InferMethodType`
|
|
630
630
|
|
|
631
|
-
Normally you write a dynamic method's signature by hand, and its return is whatever you declare (usually the whole entity). `InferMethodType<Args, Return, OrmTypes?>` declares the method for you and infers the return **on each call** from the `select`/`relations` you pass — with the same rules as [`InferMethodReturn`](#strict-return-typing-with-infermethodreturn
|
|
631
|
+
Normally you write a dynamic method's signature by hand, and its return is whatever you declare (usually the whole entity). `InferMethodType<Args, Return, OrmTypes?>` declares the method for you and infers the return **on each call** from the `select`/`relations` you pass — with the same rules as [`InferMethodReturn`](#strict-return-typing-with-infermethodreturn):
|
|
632
632
|
|
|
633
633
|
```typescript
|
|
634
634
|
class UserRepository extends VSRepository<User, string, MyOrmTypes> {
|
|
@@ -657,7 +657,7 @@ await userRepository.findOneByEmail("john@example.com", { relations: { address:
|
|
|
657
657
|
| `OrmTypes` | _Optional._ `VSRepoOrmTypes` for your ORM, used to type the `db` option (see [Creating a repository](#creating-a-repository)). Defaults to `VSRepoOrmTypes`. |
|
|
658
658
|
|
|
659
659
|
- `options` (`MethodOptions<Entity, OrmTypes>`) is always the **last**, optional parameter, after every argument in `Args`. If one of those arguments is optional, pass `undefined` explicitly to reach `options`.
|
|
660
|
-
- Without `options` the result has only the scalar fields; with them it follows the [same rules](#strict-return-typing-with-infermethodreturn
|
|
660
|
+
- Without `options` the result has only the scalar fields; with them it follows the [same rules](#strict-return-typing-with-infermethodreturn) as `InferMethodReturn` (including `select` winning over `relations`).
|
|
661
661
|
- Unknown keys in `select`/`relations` (at any depth) are rejected at compile time, and the editor autocompletes them — just like with a plain `MethodOptions<Entity>` parameter.
|
|
662
662
|
- It works together with the [decorator options](#decorator-options) (`proxyTo`, `injectOrdering`).
|
|
663
663
|
- It is meant for dynamic methods that return entities (`findBy…`, `findOneBy…`, `findWhere…`, …). Methods that don't — `countBy…`, `existsBy…` — keep their regular signature.
|
|
@@ -832,8 +832,8 @@ import type {
|
|
|
832
832
|
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
833
833
|
| `MethodOptions<T, K>` | Options accepted as the last argument by all dynamic methods and most base methods: `select`, `relations`, `see`, `db`. | [Base methods](#base-methods), [Dynamic methods](#dynamic-methods). |
|
|
834
834
|
| `RestrictMethodOptions<T, K>` | Narrowed `MethodOptions<T, K>` exposing only `see`/`db` — used by methods that don't shape/return an `Entity` (`total`, `has`, `sum`, `average`, `min`, `max`, `removeList`, `softRemoveList`, `restoreList`). | [Base methods](#base-methods), [Atomic and aggregate methods](#atomic-and-aggregate-methods). |
|
|
835
|
-
| `InferMethodReturn<T, Options>` | Opt-in strict return typing: narrows `T` (`Entity`, `Entity \| null` or `Entity[]`) to the fields and relations actually requested through `select`/`relations`. `select` wins over `relations`. | [Strict return typing with `InferMethodReturn`](#strict-return-typing-with-infermethodreturn
|
|
836
|
-
| `InferMethodType<Args, Return, OrmTypes?>` | Declares a dynamic method whose return is inferred on each call from the `select`/`relations` passed as `options`. `OrmTypes` is optional and types the `db` option. | [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype
|
|
835
|
+
| `InferMethodReturn<T, Options>` | Opt-in strict return typing: narrows `T` (`Entity`, `Entity \| null` or `Entity[]`) to the fields and relations actually requested through `select`/`relations`. `select` wins over `relations`. | [Strict return typing with `InferMethodReturn`](#strict-return-typing-with-infermethodreturn). |
|
|
836
|
+
| `InferMethodType<Args, Return, OrmTypes?>` | Declares a dynamic method whose return is inferred on each call from the `select`/`relations` passed as `options`. `OrmTypes` is optional and types the `db` option. | [Strict return typing with `InferMethodType`](#strict-return-typing-with-infermethodtype). |
|
|
837
837
|
| `Pagination` | `{ limit?, offset? }` accepted by `getAll` and by `Paginated` dynamic methods. | [Base methods](#base-methods), [Ordering, pagination and distinct](#ordering-pagination-and-distinct). |
|
|
838
838
|
| `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Ordering shape accepted by `getAll`, `defaultOrdering`, `injectOrdering` and by `Ordered` dynamic methods. A single object or a chained array. | [Constructor options](#constructor-options), [Decorator options](#decorator-options), [Ordering, pagination and distinct](#ordering-pagination-and-distinct). |
|
|
839
839
|
| `SeeMode` | `"active" \| "removed" \| "all"` — controls visibility of soft-deleted records. | [Soft-delete](#soft-delete). |
|
package/README.pt-BR.md
CHANGED
|
@@ -41,7 +41,7 @@ O VSRepository permite criar repositories fortemente tipados com:
|
|
|
41
41
|
- [Quais campos são elegíveis](#quais-campos-são-elegíveis)
|
|
42
42
|
- [Escrevendo um adapter](#escrevendo-um-adapter)
|
|
43
43
|
- [`select` e `relations`](#select-e-relations)
|
|
44
|
-
- [Tipagem de retorno restrita com `InferMethodReturn`
|
|
44
|
+
- [Tipagem de retorno restrita com `InferMethodReturn`](#tipagem-de-retorno-restrita-com-infermethodreturn)
|
|
45
45
|
- [Métodos dinâmicos](#métodos-dinâmicos)
|
|
46
46
|
- [Prefixos disponíveis](#prefixos-disponíveis)
|
|
47
47
|
- [Filtros de campo](#filtros-de-campo)
|
|
@@ -49,7 +49,7 @@ O VSRepository permite criar repositories fortemente tipados com:
|
|
|
49
49
|
- [Filtros de relação](#filtros-de-relação)
|
|
50
50
|
- [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct)
|
|
51
51
|
- [Options do decorador](#options-do-decorador)
|
|
52
|
-
- [Tipagem de retorno restrita com `InferMethodType`
|
|
52
|
+
- [Tipagem de retorno restrita com `InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype)
|
|
53
53
|
- [Query methods (SQL raw)](#query-methods-sql-raw)
|
|
54
54
|
- [Argumentos via spread com `spreadArgs`](#argumentos-via-spread-com-spreadargs)
|
|
55
55
|
- [Queries raw pontuais com `query()`](#queries-raw-pontuais-com-query)
|
|
@@ -373,7 +373,7 @@ const usuarioComEndereco = await userRepository.get(id, {
|
|
|
373
373
|
>
|
|
374
374
|
> Adapters customizados podem mapear `relations` de forma diferente — consulte a documentação do adapter para a semântica exata.
|
|
375
375
|
|
|
376
|
-
### Tipagem de retorno restrita com `InferMethodReturn`
|
|
376
|
+
### Tipagem de retorno restrita com `InferMethodReturn`
|
|
377
377
|
|
|
378
378
|
Por padrão, os métodos são tipados como se retornassem a **entidade inteira**, ignorando o `select` e o `relations` que você passa (a mesma abordagem do TypeORM). Se você prefere uma tipagem mais restrita, `InferMethodReturn<T, Options>` a estreita para o que foi realmente pedido. É opt-in e puramente em nível de tipos — nada muda em runtime.
|
|
379
379
|
|
|
@@ -411,7 +411,7 @@ const users: InferMethodReturn<User[], typeof options> = await userRepository.ge
|
|
|
411
411
|
- `see` e `db` não afetam o resultado.
|
|
412
412
|
- Mantenha os tipos literais das options, usando `satisfies MethodOptions<T>` (como acima) ou passando-as inline. Se estiverem tipadas como um `MethodOptions<T>` genérico (ex.: `const options: MethodOptions<User> = ...`), nada é conhecido em tempo de compilação e `T` é retornado sem alterações.
|
|
413
413
|
- Campos e relações opcionais (`?`) da entidade continuam opcionais.
|
|
414
|
-
- Para ter essa inferência direto nos métodos dinâmicos, veja [Tipagem de retorno restrita com `InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype
|
|
414
|
+
- Para ter essa inferência direto nos métodos dinâmicos, veja [Tipagem de retorno restrita com `InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype).
|
|
415
415
|
|
|
416
416
|
---
|
|
417
417
|
|
|
@@ -449,7 +449,7 @@ class UserRepository extends VSRepository<User, string> {
|
|
|
449
449
|
}
|
|
450
450
|
```
|
|
451
451
|
|
|
452
|
-
> Quer que o tipo de retorno acompanhe o `select`/`relations` passados, em vez de ser sempre a entidade inteira? Declare o método com [`InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype
|
|
452
|
+
> Quer que o tipo de retorno acompanhe o `select`/`relations` passados, em vez de ser sempre a entidade inteira? Declare o método com [`InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype).
|
|
453
453
|
|
|
454
454
|
### Prefixos disponíveis
|
|
455
455
|
|
|
@@ -626,9 +626,9 @@ declare buscarPorEmail: (email: string, options?: MethodOptions<User>) => Promis
|
|
|
626
626
|
declare findByStatus: (status: string) => Promise<User[]>;
|
|
627
627
|
```
|
|
628
628
|
|
|
629
|
-
### Tipagem de retorno restrita com `InferMethodType`
|
|
629
|
+
### Tipagem de retorno restrita com `InferMethodType`
|
|
630
630
|
|
|
631
|
-
Normalmente você escreve à mão a assinatura de um método dinâmico, e o retorno é o que você declarar (em geral a entidade inteira). `InferMethodType<Args, Return, OrmTypes?>` declara o método para você e infere o retorno **a cada chamada** a partir do `select`/`relations` passados — com as mesmas regras do [`InferMethodReturn`](#tipagem-de-retorno-restrita-com-infermethodreturn
|
|
631
|
+
Normalmente você escreve à mão a assinatura de um método dinâmico, e o retorno é o que você declarar (em geral a entidade inteira). `InferMethodType<Args, Return, OrmTypes?>` declara o método para você e infere o retorno **a cada chamada** a partir do `select`/`relations` passados — com as mesmas regras do [`InferMethodReturn`](#tipagem-de-retorno-restrita-com-infermethodreturn):
|
|
632
632
|
|
|
633
633
|
```typescript
|
|
634
634
|
class UserRepository extends VSRepository<User, string, MyOrmTypes> {
|
|
@@ -657,7 +657,7 @@ await userRepository.findOneByEmail("john@example.com", { relations: { address:
|
|
|
657
657
|
| `OrmTypes` | _Opcional._ `VSRepoOrmTypes` do seu ORM, usado para tipar a option `db` (veja [Criando um repository](#criando-um-repository)). Padrão: `VSRepoOrmTypes`. |
|
|
658
658
|
|
|
659
659
|
- `options` (`MethodOptions<Entity, OrmTypes>`) é sempre o **último** parâmetro, opcional, depois de todos os argumentos de `Args`. Se algum desses argumentos for opcional, passe `undefined` explicitamente para alcançar `options`.
|
|
660
|
-
- Sem `options` o resultado tem apenas os campos escalares; com elas, segue as [mesmas regras](#tipagem-de-retorno-restrita-com-infermethodreturn
|
|
660
|
+
- Sem `options` o resultado tem apenas os campos escalares; com elas, segue as [mesmas regras](#tipagem-de-retorno-restrita-com-infermethodreturn) do `InferMethodReturn` (inclusive `select` vencendo `relations`).
|
|
661
661
|
- Chaves inexistentes em `select`/`relations` (em qualquer profundidade) são rejeitadas em tempo de compilação, e o editor as sugere via autocomplete — igual a um parâmetro `MethodOptions<Entity>` comum.
|
|
662
662
|
- Funciona junto com as [options do decorador](#options-do-decorador) (`proxyTo`, `injectOrdering`).
|
|
663
663
|
- Foi pensado para métodos dinâmicos que retornam entidades (`findBy…`, `findOneBy…`, `findWhere…`, …). Os que não retornam — `countBy…`, `existsBy…` — mantêm a assinatura normal.
|
|
@@ -835,8 +835,8 @@ import type {
|
|
|
835
835
|
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
836
836
|
| `MethodOptions<T, K>` | Options aceitas como último argumento por todos os métodos dinâmicos e pela maioria dos métodos base: `select`, `relations`, `see`, `db`. | [Métodos base](#métodos-base), [Métodos Dinâmicos](#métodos-dinâmicos). |
|
|
837
837
|
| `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). |
|
|
838
|
-
| `InferMethodReturn<T, Options>` | Tipagem de retorno restrita (opt-in): estreita `T` (`Entity`, `Entity \| null` ou `Entity[]`) para os campos e relações realmente pedidos via `select`/`relations`. `select` vence `relations`. | [Tipagem de retorno restrita com `InferMethodReturn`](#tipagem-de-retorno-restrita-com-infermethodreturn
|
|
839
|
-
| `InferMethodType<Args, Return, OrmTypes?>` | Declara um método dinâmico cujo retorno é inferido a cada chamada a partir do `select`/`relations` passados como `options`. `OrmTypes` é opcional e tipa a option `db`. | [Tipagem de retorno restrita com `InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype
|
|
838
|
+
| `InferMethodReturn<T, Options>` | Tipagem de retorno restrita (opt-in): estreita `T` (`Entity`, `Entity \| null` ou `Entity[]`) para os campos e relações realmente pedidos via `select`/`relations`. `select` vence `relations`. | [Tipagem de retorno restrita com `InferMethodReturn`](#tipagem-de-retorno-restrita-com-infermethodreturn). |
|
|
839
|
+
| `InferMethodType<Args, Return, OrmTypes?>` | Declara um método dinâmico cujo retorno é inferido a cada chamada a partir do `select`/`relations` passados como `options`. `OrmTypes` é opcional e tipa a option `db`. | [Tipagem de retorno restrita com `InferMethodType`](#tipagem-de-retorno-restrita-com-infermethodtype). |
|
|
840
840
|
| `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). |
|
|
841
841
|
| `Ordering<T>` / `OrderByField<T>` / `SortDirection` | Formato de ordenação aceito por `getAll`, `defaultOrdering`, `injectOrdering` e pelos métodos dinâmicos com `Ordered`. Pode ser um único objeto ou um array encadeado. | [Options do construtor](#options-do-construtor), [Options do decorador](#options-do-decorador), [Ordenação, paginação e distinct](#ordenação-paginação-e-distinct). |
|
|
842
842
|
| `SeeMode` | `"active" \| "removed" \| "all"` — controla a visibilidade de registros com soft-delete. | [Soft-delete](#soft-delete). |
|