vsrepo 1.0.5 → 1.0.6

package/README.md

@@ -616,7 +616,7 @@ Cada entrada em `methods` aceita as seguintes opções:
 | `whereType`         | `'extending'` \| `'overwrite'`  | `extending`  | `extending` combina com `requiredWhere`. `overwrite` ignora o `requiredWhere`.                      |
 | `selectModel`       | `keyof SelectModels \| false`   | —            | Sobrescreve o `defaultSelectModel` para este método.                                                        |
 | `fbMode`            | `'one'` \| `'list'`             | `'list'`     | Somente para `findBy`. `'one'` retorna `T \| null`; `'list'` retorna `T[]`.                                 |
-| `proxyTo`           | `ValidMethodPatterns`           | —            | Delega a lógica para outro padrão de método válido. Útil para methods com nomes personalizados.       |
+| `proxyTo`           | `Padrão de método válido`           | —            | Delega a lógica para outro padrão de método válido. Útil para methods com nomes personalizados.       |
 | `pushWhere`         | `WhereModel<M>`                 | —            | Where extra adicionado à query além do `requiredWhere`.                                                     |
 | `injectOrdenation`  | `OrdenationModel<M>`            | —            | Ordenação fixa injetada automaticamente na query.                                                           |
 | `injectPagination`  | `PaginationModel<M>`            | —            | Paginação fixa injetada automaticamente na query.                                                           |

package/VSRepository/VSRepoError.d.ts

@@ -1,54 +1,54 @@
-/**
- * Literal types representing the library's internal error codes.
- */
-export type VSRepoErrorType = 
-    | 'VSREPO_CONFIG'
-    | 'VSREPO_BUILD'
-    | 'VSREPO_EXTEND'
-    | 'VSREPO_RUNTIME';
-
-/**
- * Base class for all errors thrown by the Virtual Schema Repository.
- */
-export declare abstract class VSRepoError extends Error {
-    /** Internal code used to identify the error category. */
-    abstract readonly type: VSRepoErrorType;
-    
-    constructor(message: string, type: VSRepoErrorType);
-}
-
-/**
- * Thrown when an invalid configuration or setup inconsistency is detected
- * before or during repository initialization.
- */
-export declare class VSRepoConfigError extends VSRepoError {
-    readonly type: 'VSREPO_CONFIG';
-    constructor(message: string);
-}
-
-/**
- * Thrown when the Prisma instance injection fails or when the repository
- * cannot be finalized through `.build()`.
- */
-export declare class VSRepoBuildError extends VSRepoError {
-    readonly type: 'VSREPO_BUILD';
-    constructor(message: string);
-}
-
-/**
- * Thrown when an error occurs while injecting new methods into the
- * repository through `.extend()`.
- */
-export declare class VSRepoExtendError extends VSRepoError {
-    readonly type: 'VSREPO_EXTEND';
-    constructor(message: string);
-}
-
-/**
- * Thrown when dynamic operations fail at runtime, such as when invalid
- * arguments are passed to methods.
- */
-export declare class VSRepoRuntimeError extends VSRepoError {
-    readonly type: 'VSREPO_RUNTIME';
-    constructor(message: string);
-}
+/**
+ * Tipos literais que representam os códigos de erro internos da biblioteca.
+ */
+export type VSRepoErrorType = 
+    | 'VSREPO_CONFIG'
+    | 'VSREPO_BUILD'
+    | 'VSREPO_EXTEND'
+    | 'VSREPO_RUNTIME';
+
+/**
+ * Classe base para todos os erros lançados pelo Virtual Schema Repository.
+ */
+export declare abstract class VSRepoError extends Error {
+    /** Código interno usado para identificar a categoria do erro. */
+    abstract readonly type: VSRepoErrorType;
+    
+    constructor(message: string, type: VSRepoErrorType);
+}
+
+/**
+ * Lançado quando uma configuração inválida ou uma inconsistência de
+ * configuração é detectada antes ou durante a inicialização do repositório.
+ */
+export declare class VSRepoConfigError extends VSRepoError {
+    readonly type: 'VSREPO_CONFIG';
+    constructor(message: string);
+}
+
+/**
+ * Lançado quando a injeção da instância do Prisma falha ou quando o
+ * repositório não pode ser finalizado por meio de `.build()`.
+ */
+export declare class VSRepoBuildError extends VSRepoError {
+    readonly type: 'VSREPO_BUILD';
+    constructor(message: string);
+}
+
+/**
+ * Lançado quando ocorre um erro ao injetar novos métodos no repositório
+ * por meio de `.extend()`.
+ */
+export declare class VSRepoExtendError extends VSRepoError {
+    readonly type: 'VSREPO_EXTEND';
+    constructor(message: string);
+}
+
+/**
+ * Lançado quando operações dinâmicas falham em tempo de execução, como
+ * quando argumentos inválidos são passados para métodos.
+ */
+export declare class VSRepoRuntimeError extends VSRepoError {
+    readonly type: 'VSREPO_RUNTIME';
+    constructor(message: string);
+}

package/VSRepository/VSRepository.d.ts

@@ -1,8 +1,19 @@
-import { Prisma, PrismaClient } from '@vsrepo/prisma/types';
-
-export type DbClient = PrismaClient;
-export type DbTransaction = Prisma.TransactionClient;
-export type ClientOrTransaction = DbClient | DbTransaction;
+import { Prisma, PrismaClient } from '@vsrepo/prisma/types';
+
+/**
+ * Instância completa do Prisma Client usada para construir repositories.
+ */
+export type DbClient = PrismaClient;
+
+/**
+ * Cliente transacional do Prisma retornado por `prisma.$transaction`.
+ */
+export type DbTransaction = Prisma.TransactionClient;
+
+/**
+ * Aceita tanto o cliente principal do Prisma quanto um cliente de transação.
+ */
+export type ClientOrTransaction = DbClient | DbTransaction;
 
 export * from './VSRepoError.js';
 
@@ -10,13 +21,26 @@ type OrderPattern = {
     [key: string]: 'asc' | 'desc' | { _count: 'asc' | 'desc' } | OrderPattern;
 };
 
-export type PaginationOptions<TCursor = unknown> = {
-    skip?: number;
-    take?: number;
-    cursor?: TCursor;
-};
-
-export type OrderOptions = OrderPattern | OrderPattern[];
+/**
+ * Opções de paginação aceitas pelos métodos com sufixo `Paginated`.
+ *
+ * @template TCursor Tipo do cursor usado pelo modelo Prisma.
+ */
+export type PaginationOptions<TCursor = unknown> = {
+    /** Quantidade de registros a ignorar. */
+    skip?: number;
+    /** Quantidade máxima de registros retornados. */
+    take?: number;
+    /** Cursor tipado para paginação baseada em posição. */
+    cursor?: TCursor;
+};
+
+/**
+ * Ordenação aceita pelos métodos do repository.
+ *
+ * Pode ser uma única ordenação ou uma lista de ordenações encadeadas.
+ */
+export type OrderOptions = OrderPattern | OrderPattern[];
 
 type ValidMethodPatterns =
     | `existsBy${string}` | `findBy${string}` | `findUniqueBy${string}`
@@ -27,14 +51,18 @@ type ValidMethodPatterns =
     | `deleteBy${string}` | `countBy${string}` | `count${string}`
     | `findWhere${string}` | `findListWhere${string}`;
 
-// Modificadores consolidados em Unions para processamento rápido
-type Modifiers =
-    | 'NotStartsWith' | 'StartsWith' | 'NotEndsWith' | 'EndsWith'
-    | 'NotContains' | 'Contains' | 'LessThanEqual' | 'LessThan'
-    | 'GreaterThanEqual' | 'GreaterThan' | 'NotIn' | 'In' | 'Not'
-    | 'Insensitive' | 'NotInsensitive' | 'InInsensitive' | 'ContainsInsensitive';
+type StringModifiers = 
+    | 'NotStartsWith' | 'StartsWith' | 'NotEndsWith' | 'EndsWith' 
+    | 'NotContains' | 'Contains' | 'NotIn' | 'In' | 'Not';
 
-type StripModifier<S extends string> = S extends `${infer Base}${Modifiers}` ? Base : S;
+type NumberModifiers = 
+    | 'LessThanEqual' | 'LessThan' | 'GreaterThanEqual' | 'GreaterThan';
+
+type StripModifier<S extends string> =
+  S extends `${infer Base}${`${StringModifiers}Insensitive`}` ? Base :
+  S extends `${infer Base}${StringModifiers | NumberModifiers}` ? Base :
+  S extends `${infer Base}Insensitive` ? Base :
+  S;
 
 type ExtractFieldName<S extends string> = Uncapitalize<StripModifier<S>>;
 
@@ -61,7 +89,6 @@ type GetFieldType<T, S extends string, I> = ExtractFieldName<S> extends infer Fi
             : unknown
     : unknown;
 
-// Otimização: Validação O(1) com Union Strings
 type NoArgModifiers = 'IsNull' | 'IsNotNull' | 'IsTrue' | 'IsFalse' | 'None' | 'Some' | 'Every' | 'Without';
 
 type IsNoArgModifier<S extends string> = 
@@ -128,7 +155,6 @@ type ExtraArgs<M extends string, R extends string, I> = [
       : [])
 ];
 
-// A resolução do modelo é feita instantaneamente pela Engine nativa do Prisma Client usando `Prisma.Result`.
 type PrismaDelegate<M extends Prisma.ModelName> = Uncapitalize<M> extends keyof DbClient ? DbClient[Uncapitalize<M>] : never;
 
 type FullModelType<M extends Prisma.ModelName> = 
@@ -150,13 +176,32 @@ type CleanFields<R extends string> =
     R extends `${infer F}Ordered` ? F :
     R extends `${infer F}SkipDuplicates` ? F : R;
 
-export type MethodOptions<S> = { selectModel?: S | false; db?: ClientOrTransaction };
-export type MethodOptionsModel<T> = MethodOptions<keyof T | false>;
+/**
+ * Opções adicionais aceitas pelos métodos do repository.
+ *
+ * @template S Chaves disponíveis em `selectModels`.
+ */
+export type MethodOptions<S> = {
+    /**
+     * Select model a ser aplicado na operação.
+     *
+     * Use `false` para retornar o payload completo do Prisma, sem select.
+     */
+    selectModel?: S | false;
+    /**
+     * Cliente Prisma ou transação que deve executar a operação.
+     */
+    db?: ClientOrTransaction;
+};
+
+/**
+ * Versão de `MethodOptions` derivada de um mapa de select models.
+ */
+export type MethodOptionsModel<T> = MethodOptions<keyof T | false>;
 
 type MethodFn<MethodName extends string, T, M extends Prisma.ModelName, R extends string, SelectModels, DefaultSelect extends keyof SelectModels | false, I> = 
     <S extends keyof SelectModels | false = DefaultSelect>(...args: [...ExtractFields<T, CleanFields<R>, I>, ...ExtraArgs<MethodName, R, I>, options?: MethodOptions<S>]) => Promise<ResolveReturnType<MethodName, SelectedModel<M, S, SelectModels>>>;
 
-// Otimização: Achatamento da inferência de padrões
 type GetMappedMethod<K extends string, MethodConf> = 
     K extends `findBy${string}` ? (MethodConf extends { fbMode: 'one' } ? 'findByOne' : 'findByList') :
     K extends `existsBy${string}` ? 'existsBy' :
@@ -165,13 +210,13 @@ type GetMappedMethod<K extends string, MethodConf> =
     K extends `findManyBy${string}` | `findMany${string}` ? 'findMany' :
     K extends `createManyAndReturn${string}` ? 'createManyAndReturn' :
     K extends `createMany${string}` ? 'createMany' :
-    K extends `create${string}` ? 'create' : // Precisa ficar depois dos createMany
+    K extends `create${string}` ? 'create' :
     K extends `updateManyAndReturnBy${string}` ? 'updateManyAndReturnBy' :
     K extends `updateManyBy${string}` ? 'updateManyBy' :
-    K extends `updateBy${string}` ? 'updateBy' : // Precisa ficar depois dos updateMany
+    K extends `updateBy${string}` ? 'updateBy' :
     K extends `upsertBy${string}` ? 'upsertBy' :
     K extends `deleteManyBy${string}` ? 'deleteManyBy' :
-    K extends `deleteBy${string}` ? 'deleteBy' : // Precisa ficar depois do deleteMany
+    K extends `deleteBy${string}` ? 'deleteBy' :
     K extends `countBy${string}` | `count${string}` ? 'count' :
     K extends `findListWhere${string}` ? 'findListWhere' :
     K extends `findWhere${string}` ? 'findWhere' :
@@ -201,52 +246,118 @@ type DynamicMethods<T, M extends Prisma.ModelName, Config, I> = Config extends {
       }
     : {};
 
-export type PrismaModelInputs<M extends Prisma.ModelName> = {
-    select: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['select'];
-    createInput: Prisma.TypeMap['model'][M]['operations']['create']['args']['data'];
-    createManyInput: Prisma.TypeMap['model'][M]['operations']['createMany']['args']['data'];
-    updateInput: Prisma.TypeMap['model'][M]['operations']['update']['args']['data'];
-    updateManyInput: Prisma.TypeMap['model'][M]['operations']['updateMany']['args']['data'];
-    whereInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['where'];
-    orderByInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['orderBy'];
-    cursorInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['cursor'];
-    upsertCreateInput: Prisma.TypeMap['model'][M]['operations']['upsert']['args']['create'];
-    upsertUpdateInput: Prisma.TypeMap['model'][M]['operations']['upsert']['args']['update'];
-};
-
-export type SelectModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['select'];
-export type SelectModels<M extends Prisma.ModelName> = Record<string, SelectModel<M>>;
-export type WhereModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['whereInput'];
-export type OrdenationModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['orderByInput'];
-export type PaginationModel<M extends Prisma.ModelName> = PaginationOptions<PrismaModelInputs<M>['cursorInput']>;
-export type ModelUpsertInput<M extends Prisma.ModelName> = PrismaModelInputs<M>['upsertCreateInput'];
-
-export type MethodConfig<M extends Prisma.ModelName, SelectModels = any> = {
-    readonly map: boolean;
-    readonly selectModel?: keyof SelectModels | false;
-    readonly whereType?: 'overwrite' | 'extending';
-    readonly proxyTo?: ValidMethodPatterns;
-    readonly pushWhere?: WhereModel<M>;
-    readonly fbMode?: 'one' | 'list';
-    readonly injectOrdenation?: OrdenationModel<M>;
-    readonly injectPagination?: PaginationModel<M>;
-};
-
-type BaseMethodConfig<TSelectKeys extends PropertyKey = string> = {
-    active?: boolean;
-    defaultSelect?: TSelectKeys;
-    ignoreRequiredWhere?: boolean;
-};
-
-export type BuildConfig<TSelectKeys extends PropertyKey = string> = {
-    freeze?: boolean;
-    showWorking?: boolean;
-    baseMethods?: {
-        get?: BaseMethodConfig<TSelectKeys>;
-        remove?: BaseMethodConfig<TSelectKeys>;
-        save?: BaseMethodConfig<TSelectKeys>;
-    };
-};
+/**
+ * Agrupa os principais tipos de input do Prisma derivados de um modelo.
+ *
+ * @template M Nome do modelo Prisma.
+ */
+export type PrismaModelInputs<M extends Prisma.ModelName> = {
+    /** Tipo do argumento `select` usado em consultas do modelo. */
+    select: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['select'];
+    /** Tipo do `data` usado em `create`. */
+    createInput: Prisma.TypeMap['model'][M]['operations']['create']['args']['data'];
+    /** Tipo do `data` usado em `createMany`. */
+    createManyInput: Prisma.TypeMap['model'][M]['operations']['createMany']['args']['data'];
+    /** Tipo do `data` usado em `update`. */
+    updateInput: Prisma.TypeMap['model'][M]['operations']['update']['args']['data'];
+    /** Tipo do `data` usado em `updateMany`. */
+    updateManyInput: Prisma.TypeMap['model'][M]['operations']['updateMany']['args']['data'];
+    /** Tipo do `where` usado nas buscas do modelo. */
+    whereInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['where'];
+    /** Tipo do `orderBy` usado nas buscas do modelo. */
+    orderByInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['orderBy'];
+    /** Tipo do cursor usado nas buscas do modelo. */
+    cursorInput: Prisma.TypeMap['model'][M]['operations']['findMany']['args']['cursor'];
+    /** Tipo do payload `create` usado em `upsert`. */
+    upsertCreateInput: Prisma.TypeMap['model'][M]['operations']['upsert']['args']['create'];
+    /** Tipo do payload `update` usado em `upsert`. */
+    upsertUpdateInput: Prisma.TypeMap['model'][M]['operations']['upsert']['args']['update'];
+};
+
+/**
+ * Tipo do objeto `select` de um modelo Prisma.
+ */
+export type SelectModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['select'];
+
+/**
+ * Mapa de selects nomeados e reutilizáveis para um modelo Prisma.
+ */
+export type SelectModels<M extends Prisma.ModelName> = Record<string, SelectModel<M>>;
+
+/**
+ * Tipo do objeto `where` de um modelo Prisma.
+ */
+export type WhereModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['whereInput'];
+
+/**
+ * Tipo do objeto `orderBy` de um modelo Prisma.
+ */
+export type OrdenationModel<M extends Prisma.ModelName> = PrismaModelInputs<M>['orderByInput'];
+
+/**
+ * Opções de paginação com cursor tipado para um modelo Prisma.
+ */
+export type PaginationModel<M extends Prisma.ModelName> = PaginationOptions<PrismaModelInputs<M>['cursorInput']>;
+
+/**
+ * Payload base usado para criar um registro no `save`/`upsert` do modelo.
+ */
+export type ModelUpsertInput<M extends Prisma.ModelName> = PrismaModelInputs<M>['upsertCreateInput'];
+
+/**
+ * Configuração de um método dinâmico definido em `methods`.
+ *
+ * @template M Nome do modelo Prisma.
+ * @template SelectModels Mapa de select models disponíveis no repository.
+ */
+export type MethodConfig<M extends Prisma.ModelName, SelectModels = any> = {
+    /** Define se o método será exposto no repository. */
+    readonly map: boolean;
+    /** Sobrescreve o `defaultSelectModel` apenas para este método. */
+    readonly selectModel?: keyof SelectModels | false;
+    /** Controla se o método combina ou sobrescreve o `requiredWhere`. */
+    readonly whereType?: 'overwrite' | 'extending';
+    /** Redireciona a lógica para outro padrão de método válido. */
+    readonly proxyTo?: ValidMethodPatterns;
+    /** Adiciona um `where` extra além do `requiredWhere`. */
+    readonly pushWhere?: WhereModel<M>;
+    /** Define se `findBy` retorna um item (`one`) ou uma lista (`list`). */
+    readonly fbMode?: 'one' | 'list';
+    /** Injeta uma ordenação fixa automaticamente na query. */
+    readonly injectOrdenation?: OrdenationModel<M>;
+    /** Injeta uma paginação fixa automaticamente na query. */
+    readonly injectPagination?: PaginationModel<M>;
+};
+
+type BaseMethodConfig<TSelectKeys extends PropertyKey = string> = {
+    /** Ativa ou desativa o método base no `build`. */
+    active?: boolean;
+    /** Select model padrão usado pelo método base. */
+    defaultSelect?: TSelectKeys;
+    /** Ignora o `requiredWhere` no `save`. */
+    ignoreRequiredWhere?: boolean;
+};
+
+/**
+ * Configuração aplicada durante o `.build(prisma, config?)`.
+ *
+ * @template TSelectKeys Chaves válidas de `selectModels`.
+ */
+export type BuildConfig<TSelectKeys extends PropertyKey = string> = {
+    /** Congela o objeto final do repository. */
+    freeze?: boolean;
+    /** Exibe logs internos de funcionamento no console. */
+    showWorking?: boolean;
+    /** Personaliza o comportamento dos métodos base automáticos. */
+    baseMethods?: {
+        /** Configuração do método `get`. */
+        get?: BaseMethodConfig<TSelectKeys>;
+        /** Configuração do método `remove`. */
+        remove?: BaseMethodConfig<TSelectKeys>;
+        /** Configuração do método `save`. */
+        save?: BaseMethodConfig<TSelectKeys>;
+    };
+};
 
 type ResolveMethodDefaultSelect<Config, C, Method extends 'get' | 'remove' | 'save', TSelects = ExtractSelectModels<Config>> =
     C extends { baseMethods?: { [_ in Method]?: { defaultSelect?: infer D } } }
@@ -290,7 +401,10 @@ type InjectedRemove<
     ): Promise<ResolveCurrentReturn<M, TSelects, S, TDefault>>;
 };
 
-export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+/**
+ * Versão distributiva de `Omit`, preservando unions ao remover propriedades.
+ */
+export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 type ExtractUnionProp<T, K extends PropertyKey> = T extends any ? (K extends keyof T ? T[K] : never) : never;
 
 type ExtractNestedCreateInput<M extends Prisma.ModelName, K extends PropertyKey> = 
@@ -304,10 +418,16 @@ type RelationPayload<TField, TRelationConfig, M extends Prisma.ModelName, K exte
       ? ExtractNestedCreateInput<M, K> | (TRelationConfig extends { mode: 'oto'; restriction: 'set' } | { mode: 'mto'; nullAble: true } ? null : never)
       : never;
 
-export type UpsertWithRelations<T, M extends Prisma.ModelName, TRelations> = 
-    DistributiveOmit<ModelUpsertInput<M>, keyof TRelations> & {
-        [K in Extract<keyof TRelations, keyof T>]?: RelationPayload<T[K], TRelations[K], M, K>;
-    };
+/**
+ * Payload aceito pelo `save` quando o repository possui relações configuradas.
+ *
+ * Substitui os campos relacionais pelo formato compatível com os modos
+ * configurados em `relations`.
+ */
+export type UpsertWithRelations<T, M extends Prisma.ModelName, TRelations> = 
+    DistributiveOmit<ModelUpsertInput<M>, keyof TRelations> & {
+        [K in Extract<keyof TRelations, keyof T>]?: RelationPayload<T[K], TRelations[K], M, K>;
+    };
 
 type InjectedSave<
     T, M extends Prisma.ModelName, Config, C extends BuildConfig<any> | undefined,
@@ -329,65 +449,124 @@ type InjectedBaseMethods<T, M extends Prisma.ModelName, Config, C extends BuildC
     InjectedRemove<T, M, Config, C> & 
     InjectedSave<T, M, Config, C>;
 
-export type ExtractRelationConfig<TField> = NonNullable<TField> extends infer NonNull
-    ? NonNull extends Date | Buffer | Uint8Array ? never
-    : NonNull extends any[] ? (NonNull[number] extends object ? { pk: keyof NonNull[number]; mode: 'otm' | 'mtm'; restriction: 'set' | 'add' } : never)
-    : NonNull extends object ? ({ pk: keyof NonNull; mode: 'oto'; restriction: 'set' | 'add' } | { pk: keyof NonNull; mode: 'mto'; restriction: 'set' | 'add'; nullAble?: boolean })
-    : never
-    : never;
-
-export type RepositoryRelations<T> = {
-    [K in keyof T as ExtractRelationConfig<T[K]> extends never ? never : K]?: ExtractRelationConfig<T[K]>;
-};
+/**
+ * Infere automaticamente a configuração de relação possível a partir de um campo.
+ */
+export type ExtractRelationConfig<TField> = NonNullable<TField> extends infer NonNull
+    ? NonNull extends Date | Buffer | Uint8Array ? never
+    : NonNull extends any[] ? (NonNull[number] extends object ? { pk: keyof NonNull[number]; mode: 'otm' | 'mtm'; restriction: 'set' | 'add' } : never)
+    : NonNull extends object ? ({ pk: keyof NonNull; mode: 'oto'; restriction: 'set' | 'add' } | { pk: keyof NonNull; mode: 'mto'; restriction: 'set' | 'add'; nullAble?: boolean })
+    : never
+    : never;
+
+/**
+ * Mapa das relações configuráveis de um tipo de entidade.
+ */
+export type RepositoryRelations<T> = {
+    [K in keyof T as ExtractRelationConfig<T[K]> extends never ? never : K]?: ExtractRelationConfig<T[K]>;
+};
 
 type AnySelect<M extends Prisma.ModelName> = Prisma.TypeMap['model'][M]['operations']['findMany']['args']['select'];
 
-export type RepoConfig<T, M extends Prisma.ModelName, SM extends Record<string, AnySelect<M>> = Record<string, AnySelect<M>>> = {
-    tableName: Uncapitalize<M>;
-    pkName: keyof T;
-    selectModels?: SM;
-    defaultSelectModel?: Extract<keyof SM, string>;
-    requiredWhere?: WhereModel<M>;
-    relations?: RepositoryRelations<T>;
-    methods?: Record<string, MethodConfig<M, SM>>;
-};
-
-export type BuiltRepository<T extends object, M extends Prisma.ModelName, Config extends RepoConfig<T, M, any>, C extends BuildConfig<any> | undefined> = {
-    extend<E>(extensionFunc: (repo: BuiltRepository<T, M, Config, C>) => E): BuiltRepository<T, M, Config, C> & E;
-} & DynamicMethods<T, M, Config, PrismaModelInputs<M>> & InjectedBaseMethods<T, M, Config, C>;
-
-export declare class VSRepository<T extends object, M extends Prisma.ModelName, const Config extends RepoConfig<T, M, any> = RepoConfig<T, M, any>> {
-    readonly config: Config;
-    constructor(config: Config);
-    build<C extends BuildConfig<any>>(prisma: DbClient, config?: C): BuiltRepository<T, M, Config, C>;
-    vsrepocache: never;
-}
-
-export type RepositoryOf<TRepo, C extends BuildConfig<any> | undefined = undefined, E = unknown> =
-    TRepo extends VSRepository<infer T, infer M, infer Config>
-        ? BuiltRepository<T, M, Config, C> & E
-        : never;
-
-export type ValidateRepoConfig<T extends object, M extends Prisma.ModelName, Config> = {
-    tableName: Uncapitalize<M>;
-    pkName: keyof T;
-    selectModels?: SelectModels<M>;
-    defaultSelectModel?: Config extends { selectModels: infer SM } ? (keyof SM extends never ? string : Extract<keyof SM, string>) : string;
-    requiredWhere?: WhereModel<M>;
-    relations?: RepositoryRelations<T>;
-    methods?: {
-        [K in keyof (Config extends { methods: infer Meth } ? Meth : {})]: K extends string
-            ? HasMultipleANDs<K> extends true
-                ? MethodConfig<M, Config extends { selectModels: infer SM } ? SM : any> & { proxyTo: ValidMethodPatterns }
-                : MethodConfig<M, Config extends { selectModels: infer SM } ? SM : any> & (K extends ValidMethodPatterns ? {} : { proxyTo: ValidMethodPatterns })
-            : never;
-    };
-};
-
-export declare function setupVSRepo<T extends object, M extends Prisma.ModelName>(): <
-    const SM extends Record<string, SelectModel<M>>,
-    const Config extends RepoConfig<T, M, SM>
->(
+/**
+ * Configuração principal usada em `setupVSRepo<T, M>()(config)`.
+ *
+ * @template T Tipo da entidade manipulada pelo repository.
+ * @template M Nome do modelo Prisma.
+ * @template SM Mapa de select models nomeados.
+ */
+export type RepoConfig<T, M extends Prisma.ModelName, SM extends Record<string, AnySelect<M>> = Record<string, AnySelect<M>>> = {
+    /** Nome da tabela/modelo no Prisma. */
+    tableName: Uncapitalize<M>;
+    /** Nome da chave primária da entidade. */
+    pkName: keyof T;
+    /** Projeções de dados nomeadas e reutilizáveis. */
+    selectModels?: SM;
+    /** Select model aplicado por padrão quando nenhum for informado. */
+    defaultSelectModel?: Extract<keyof SM, string>;
+    /** Filtros aplicados automaticamente em todas as queries do repository. */
+    requiredWhere?: WhereModel<M>;
+    /** Configuração das relações gerenciadas pelo `save`. */
+    relations?: RepositoryRelations<T>;
+    /** Métodos dinâmicos expostos pelo repository. */
+    methods?: Record<string, MethodConfig<M, SM>>;
+};
+
+/**
+ * Tipo final retornado por `.build(prisma)`.
+ *
+ * Combina métodos dinâmicos, métodos base e extensões personalizadas.
+ */
+export type BuiltRepository<T extends object, M extends Prisma.ModelName, Config extends RepoConfig<T, M, any>, C extends BuildConfig<any> | undefined> = {
+    /**
+     * Estende o repository com métodos personalizados sem perder a tipagem.
+     */
+    extend<E>(extensionFunc: (repo: BuiltRepository<T, M, Config, C>) => E): BuiltRepository<T, M, Config, C> & E;
+} & DynamicMethods<T, M, Config, PrismaModelInputs<M>> & InjectedBaseMethods<T, M, Config, C>;
+
+/**
+ * Fábrica tipada de repositories baseada na configuração do modelo Prisma.
+ */
+export declare class VSRepository<T extends object, M extends Prisma.ModelName, const Config extends RepoConfig<T, M, any> = RepoConfig<T, M, any>> {
+    /** Configuração original informada no `setupVSRepo`. */
+    readonly config: Config;
+    /**
+     * Cria uma instância configurável de `VSRepository`.
+     */
+    constructor(config: Config);
+    /**
+     * Constrói o repository final com os métodos base e dinâmicos.
+     */
+    build<C extends BuildConfig<any>>(prisma: DbClient, config?: C): BuiltRepository<T, M, Config, C>;
+    vsrepocache: never;
+}
+
+/**
+ * Infere o tipo de um repository já configurado a partir de uma instância de `VSRepository`.
+ *
+ * Também permite informar manualmente o `BuildConfig` e o tipo de extensões.
+ */
+export type RepositoryOf<TRepo, C extends BuildConfig<any> | undefined = undefined, E = unknown> =
+    TRepo extends VSRepository<infer T, infer M, infer Config>
+        ? BuiltRepository<T, M, Config, C> & E
+        : never;
+
+/**
+ * Tipo utilitário usado para validar a configuração de um repository em tempo de compilação.
+ */
+export type ValidateRepoConfig<T extends object, M extends Prisma.ModelName, Config> = {
+    /** Nome da tabela/modelo no Prisma. */
+    tableName: Uncapitalize<M>;
+    /** Nome da chave primária da entidade. */
+    pkName: keyof T;
+    /** Mapa de select models disponíveis. */
+    selectModels?: SelectModels<M>;
+    /** Chave do select model padrão. */
+    defaultSelectModel?: Config extends { selectModels: infer SM } ? (keyof SM extends never ? string : Extract<keyof SM, string>) : string;
+    /** Filtros globais aplicados às queries do repository. */
+    requiredWhere?: WhereModel<M>;
+    /** Relações gerenciadas automaticamente pelo `save`. */
+    relations?: RepositoryRelations<T>;
+    /** Mapa dos métodos dinâmicos e suas regras de validação. */
+    methods?: {
+        [K in keyof (Config extends { methods: infer Meth } ? Meth : {})]: K extends string
+            ? HasMultipleANDs<K> extends true
+                ? MethodConfig<M, Config extends { selectModels: infer SM } ? SM : any> & { proxyTo: ValidMethodPatterns }
+                : MethodConfig<M, Config extends { selectModels: infer SM } ? SM : any> & (K extends ValidMethodPatterns ? {} : { proxyTo: ValidMethodPatterns })
+            : never;
+    };
+};
+
+/**
+ * Cria uma fábrica tipada para definir repositories fortemente tipados com Prisma.
+ *
+ * Use esta função para declarar `tableName`, `pkName`, `selectModels`,
+ * `requiredWhere`, `relations` e `methods` do seu repository.
+ */
+export declare function setupVSRepo<T extends object, M extends Prisma.ModelName>(): <
+    const SM extends Record<string, SelectModel<M>>,
+    const Config extends RepoConfig<T, M, SM>
+>(
   config: Config extends ValidateRepoConfig<T, M, Config> 
     ? Config 
     : ValidateRepoConfig<T, M, Config>

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "vsrepo",
-  "version": "1.0.5",
-  "description": "Uma biblioteca de repositório virtual para Prisma",
+  "version": "1.0.6",
+  "description": "Uma biblioteca de repository pattern para Prisma",
+  "homepage": "https://github.com/jaobrabo123/VSRepository#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaobrabo123/VSRepository"
+  },
   "main": "./VSRepository/index.js",
   "types": "./VSRepository/index.d.ts",
   "exports": {
@@ -42,7 +47,7 @@
     "vsrepo",
     "vsrepository"
   ],
-  "author": "João Pedro Azevedo",
+  "author": "João Pedro Azevedo Freire Mecenas",
   "license": "MIT",
   "peerDependencies": {
     "@prisma/client": "^7.8.0"

package/scripts/configure-prisma-import.mjs

@@ -169,6 +169,17 @@ for (const file of tsFiles) {
   console.log(`Gerado: ${path.relative(workspaceRoot, targetFile)}`);
 }
 
+// Copia o README.md para o diretório de output, se existir
+const readmeSource = path.join(workspaceRoot, 'README.md');
+const readmeTarget = path.join(outputDir, 'README.md');
+
+if (fs.existsSync(readmeSource)) {
+  fs.copyFileSync(readmeSource, readmeTarget);
+  console.log(`Copiado: ${path.relative(workspaceRoot, readmeTarget)}`);
+} else {
+  console.warn('README.md nao encontrado, ignorando a copia.');
+}
+
 console.log('\nVSRepository gerado com tipagem do Prisma.');
 console.log(`Output: ${outputDir}`);
 console.log(`Prisma usado em: ${prismaTargetPath}`);