@deorta-dev/nestjs-repository-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,260 @@
+**Idioma:** Español · [English](./README.md)
+
+# @deorta-dev/nestjs-repository-core
+
+Librería para NestJS + Mongoose que genera, para cualquier entidad, un
+servicio de repositorio genérico (`BaseRepositoryService<T>`) con caché
+read-through y réplicas de respaldo (backups), **sin tener que crear una
+clase `XxxOrmService` / `XxxOrmModule` por cada entidad**.
+
+Reemplaza el patrón de `PositionOrmService` + `PositionOrmModule` por entidad
+con una sola llamada a `RepositoryOrmModule.register(...)`.
+
+Compilado y verificado con `tsc --strict` contra `@nestjs/common`,
+`@nestjs/mongoose`, `mongoose` y `class-transformer`.
+
+## Instalación
+
+```bash
+npm install @deorta-dev/nestjs-repository-core
+```
+
+Necesitas tener instalados (son `peerDependencies`, no se instalan solos):
+
+```bash
+npm install @nestjs/common @nestjs/mongoose mongoose class-transformer reflect-metadata rxjs
+```
+
+## Uso básico
+
+```ts
+import { RepositoryOrmModule, RepositoryInject, IBaseRepositoryService } from '@deorta-dev/nestjs-repository-core';
+
+// position-repository.module.ts
+export const PositionRepositoryModule = RepositoryOrmModule.register({
+  entity: Position,
+  schema: positionSchema,
+  connectionName: ConnectionNames.OPERATION_MDB,
+});
+
+// en cualquier @Module:
+@Module({ imports: [PositionRepositoryModule] })
+export class SomeModule {}
+
+// en cualquier servicio: inyecta contra la INTERFAZ, no contra la clase concreta
+// (así, si luego cambias a un customService, no tienes que tocar nada aquí).
+constructor(
+  @RepositoryInject(PositionRepositoryModule)
+  private readonly positionRepository: IBaseRepositoryService<Position>,
+) {}
+```
+
+El token de inyección siempre es `${Entidad.name}RepositoryService` (ej.
+`PositionRepositoryService`), así que no importa cuántas veces llames
+`.register()` para la misma entidad: el token es consistente y
+`@RepositoryInject(loQueSeaQueDevolvióRegister)` siempre apunta al mismo
+provider.
+
+Ver `src/examples/position-repository.example.ts` para el ejemplo completo
+migrando `Position`.
+
+## API de `BaseRepositoryService<T>` (contrato `IBaseRepositoryService<T>`)
+
+| Método | Qué hace |
+|---|---|
+| `findOne(filter, opts?)` | Por defecto: caché primero, si no encuentra cae a `main` y repuebla caché. `opts.target = 'main' \| 'cache'` para forzar una conexión específica (sin fallback). |
+| `find(filter, opts?)` | Igual que `findOne` pero lista. Soporta `opts.sort/limit/skip/projection`. |
+| `create(dto)` | Inserta en `main`; el documento resultante (con su `_id`) se replica en caché y en todos los backups. |
+| `insertMany(dtos[])` | Igual que `create` pero en bulk (`insertMany` + `bulkWrite` hacia caché/backups). |
+| `updateOne(filter, update)` | Actualiza `main` primero, luego replica el documento resultante en caché y backups. |
+| `updateMany(filter, update)` | Igual en bulk. |
+| `deleteOne(filter)` / `deleteMany(filter)` | Borra en `main` primero, luego en caché y backups, y registra un "tombstone" para que la sincronización periódica también lo sepa. |
+
+## Resiliencia: ¿qué pasa si caché o backups están caídos?
+
+**Si `main` funciona, el servicio funciona**, sin importar el estado de
+`cache` o de los `backups`.
+
+- **Lecturas (`findOne`/`find`)**: si la conexión de caché no está lista o la
+  consulta falla, se trata como "cache miss" y se consulta `main`
+  directamente — nunca se propaga el error.
+- **Escrituras (`create`/`insertMany`/`updateOne`/`updateMany`/`deleteOne`/`deleteMany`)**:
+  siempre se ejecutan en `main` primero. La propagación hacia `cache` y cada
+  `backup` se intenta de inmediato; si una conexión no está lista
+  (`readyState !== 1`) o la operación falla, **esa operación queda pendiente
+  en una cola en memoria** (una por conexión secundaria) en vez de hacer
+  fallar la operación completa.
+- La cola de pendientes se reintenta sola:
+    - Cada `pendingOps.retryIntervalMs` (default 5000 ms).
+    - Apenas la conexión emite el evento `connected` de mongoose (reacción
+      inmediata, no espera al próximo tick).
+    - Si se acumulan más de `pendingOps.maxQueueSize` operaciones (default
+        1000) porque una conexión estuvo caída mucho tiempo, se descartan las
+              más antiguas para no consumir memoria indefinidamente — eso está bien
+              porque, para backups, `BackupSyncService` los pone al día de todos
+              modos comparando contra `main`; y para caché, el próximo `find`/`findOne`
+              simplemente la repuebla.
+- Las operaciones encoladas son siempre upserts/deletes por `_id`
+  (idempotentes), así que reintentarlas en orden, incluso varias veces, es
+  seguro.
+- **Cada backup es independiente**: si tienes dos backups y uno está caído,
+  el otro sigue avanzando con su propio checkpoint; el caído se pondrá al
+  día solo cuando vuelva (no hay un checkpoint compartido que se bloquee por
+  una sola conexión problemática).
+- Los tombstones (usados para propagar deletes a los backups) solo se borran
+  de la colección una vez que **todos** los backups configurados ya los
+  aplicaron — así uno que estuvo caído no se queda sin la información que
+  necesita para ponerse al día.
+
+```ts
+RepositoryOrmModule.register({
+  // ...
+  pendingOps: {
+    retryIntervalMs: 5000, // cada cuánto se reintentan las operaciones pendientes
+    maxQueueSize: 1000,    // tope en memoria por conexión secundaria
+  },
+});
+```
+
+## Servicio personalizado (`customService`)
+
+Por defecto, `register(...)` usa `BaseRepositoryService`. Si necesitas una
+lógica distinta para una entidad en particular, puedes pasar tu propia clase
+en `customService`:
+
+```ts
+RepositoryOrmModule.register({
+  entity: Position,
+  schema: positionSchema,
+  connectionName: ConnectionNames.OPERATION_MDB,
+  customService: PositionRepositoryService, // tu clase
+});
+```
+
+`customService` está tipado como `Type<IBaseRepositoryService<T>>`, así que
+**TypeScript no te deja asignar ahí una clase que no cumpla la interfaz**
+(`findOne`, `find`, `create`, `insertMany`, `updateOne`, `updateMany`,
+`deleteOne`, `deleteMany`, con las firmas exactas de `IBaseRepositoryService<T>`).
+
+Dos formas de escribirla (ambas en `src/examples/custom-repository-service.example.ts`):
+
+1. **Extender `BaseRepositoryService<T>`** (recomendado): heredas toda la
+   resiliencia de caché/backups y solo sobreescribes el método que te
+   interese, llamando `super.metodo(...)` si quieres conservar el
+   comportamiento original.
+
+   ```ts
+   class PositionRepositoryService extends BaseRepositoryService<Position> {
+     async create(dto: Partial<Position>) {
+       const created = await super.create(dto);
+       console.log('Position creada:', created);
+       return created;
+     }
+   }
+   ```
+
+2. **Implementar `IBaseRepositoryService<T>` desde cero**: útil si quieres
+   una estrategia totalmente distinta (ej. ignorar caché/backups). El
+   constructor que recibe debe aceptar los mismos 9 parámetros que
+   `register(...)` ya resuelve por ti: `entity, options, mainModel,
+   cacheModel, cacheConfig, backupModels, backupLabels, tombstoneModel,
+   pendingOpsConfig` (aunque no los uses todos).
+
+Sea cualquiera de las dos, inyectas tu servicio personalizado exactamente
+igual que el default, con `@RepositoryInject(...)` — no cambia nada en el
+resto de tu código, porque ambos cumplen `IBaseRepositoryService<T>`.
+
+## Configuración de `RepositoryOrmModule.register(...)`
+
+```ts
+{
+  entity: Position,            // clase de la entidad
+  schema: positionSchema,      // schema de mongoose
+  connectionName: '...',       // conexión principal
+  options: {},                 // tus BaseOrmOptions actuales
+
+  cache: {                     // OPCIONAL
+    connectionName: '...',
+    ttlSeconds: 300,           // TTL del documento en la conexión de caché
+  },
+
+  backups: [                   // OPCIONAL, array de conexiones de solo-escritura
+    { connectionName: '...' },
+    { connectionName: '...' },
+  ],
+
+  backupSync: {                // OPCIONAL, solo aplica si hay `backups`
+    enabled: true,              // si es false, nadie sincroniza automáticamente
+    intervalMs: 60_000,         // cada cuánto se revisa main vs backups
+    runOnStart: true,           // corre una verificación apenas arranca el módulo
+    batchSize: 500,             // documentos por lote en cada verificación
+  },
+
+  pendingOps: {                // OPCIONAL
+    retryIntervalMs: 5000,
+    maxQueueSize: 1000,
+  },
+
+  customService: PositionRepositoryService, // OPCIONAL, default: BaseRepositoryService
+}
+```
+
+## Notas de diseño
+
+Algunas decisiones de implementación que vale la pena conocer si vas a
+extender la librería:
+
+1. **Caché vs. main en lecturas**: `findOne`/`find` sin `target` explícito
+   consultan primero caché y si no hay nada caen a `main` (y repueblan la
+   caché en segundo plano, sin bloquear la respuesta). Con `target: 'main'`
+   o `target: 'cache'` consultan *solo* esa conexión, sin fallback.
+
+2. **TTL de caché**: usa un índice TTL "a fecha exacta"
+   (`expireAfterSeconds: 0` sobre un campo `_cacheExpiresAt`) en vez del TTL
+   clásico de Mongo, porque así cada escritura define su propio vencimiento
+   según `cache.ttlSeconds`, sin depender de cuándo se creó el índice.
+
+3. **Cómo se detecta qué le falta a un backup**: para inserts/updates se
+   compara `updatedTime` contra un checkpoint guardado por entidad (asume
+   que tu modelo mantiene `updatedTime` actualizado en cada escritura). Para
+   deletes, en vez de comparar todo el set de `_id` (caro a escala),
+   `deleteOne`/`deleteMany` registran un "tombstone" (`_id` + fecha de
+   borrado) en la conexión `main`, y el sync lo consume y lo borra.
+   > Si tus "deletes" en realidad son soft-deletes (un flag como
+   > `trashed: true`), el mecanismo de tombstones simplemente no se usa —
+   > la sincronización por `updatedTime` ya es suficiente, porque marcar
+   > `trashed: true` también actualiza `updatedTime`.
+
+4. **Disparo de la sincronización de backups**: por defecto, si
+   `backupSync.enabled` es `true`, el propio servicio arranca un
+   `setInterval` interno (`onModuleInit`/`onModuleDestroy`). Si prefieres que
+   un proceso externo de bajo esfuerzo decida cuándo sincronizar, deja
+   `enabled: false` y llama tú mismo al método público `syncNow()` del
+   `BackupSyncService` (expuesto como provider `${Entidad}BackupSyncService`)
+   desde donde quieras (cron externo, endpoint, etc.).
+
+5. **`BaseOrmOptions`** se deja intencionalmente abierta
+   (`{ [key: string]: any }`) para que la librería no dependa de la forma
+   exacta de opciones de ningún proyecto en particular. Si quieres tipado
+   estricto, define tu propia interfaz y úsala en su lugar.
+
+6. **Superficie de CRUD**: `findOne`/`find`, `create`/`insertMany`,
+   `updateOne`/`updateMany`, `deleteOne`/`deleteMany` cubren las operaciones
+   más comunes. Si necesitas más (`count`, `exists`, `aggregate`,
+   paginación, etc.), agrégalas a `IBaseRepositoryService`/
+   `BaseRepositoryService` siguiendo el mismo patrón de propagación a
+   caché/backups, o impleméntalas en un `customService`.
+
+## Limitación conocida
+
+En `updateMany`, para propagar a caché/backups se vuelve a consultar `main`
+con el mismo `filter` original. Si el `update` cambia campos que forman
+parte de ese `filter` (ej. `updateMany({ status: 'pending' }, { status:
+'done' })`), esos documentos ya no harán match y no se propagarán
+correctamente. Si esto te afecta, la alternativa es capturar los `_id`
+afectados *antes* de actualizar — puedes hacerlo sobreescribiendo
+`updateMany` en un `customService`.
+
+## Licencia
+
+MIT

package/README.md

@@ -0,0 +1,259 @@
+**Language:** English · [Español](./README.es.md)
+
+# @deorta-dev/nestjs-repository-core
+
+A NestJS + Mongoose library that generates a generic repository service
+(`BaseRepositoryService<T>`) for any entity — with read-through caching and
+write-only backup replicas — **without having to write an `XxxOrmService` /
+`XxxOrmModule` class per entity**.
+
+Replaces the per-entity `PositionOrmService` + `PositionOrmModule` pattern
+with a single `RepositoryOrmModule.register(...)` call.
+
+Built and verified with `tsc --strict` against `@nestjs/common`,
+`@nestjs/mongoose`, `mongoose` and `class-transformer`.
+
+## Installation
+
+```bash
+npm install @deorta-dev/nestjs-repository-core
+```
+
+You also need these installed (they're `peerDependencies`, not installed
+automatically):
+
+```bash
+npm install @nestjs/common @nestjs/mongoose mongoose class-transformer reflect-metadata rxjs
+```
+
+## Basic usage
+
+```ts
+import { RepositoryOrmModule, RepositoryInject, IBaseRepositoryService } from '@deorta-dev/nestjs-repository-core';
+
+// position-repository.module.ts
+export const PositionRepositoryModule = RepositoryOrmModule.register({
+  entity: Position,
+  schema: positionSchema,
+  connectionName: ConnectionNames.OPERATION_MDB,
+});
+
+// in any @Module:
+@Module({ imports: [PositionRepositoryModule] })
+export class SomeModule {}
+
+// in any service: inject against the INTERFACE, not the concrete class
+// (so swapping in a customService later doesn't require touching this).
+constructor(
+  @RepositoryInject(PositionRepositoryModule)
+  private readonly positionRepository: IBaseRepositoryService<Position>,
+) {}
+```
+
+The injection token is always `${Entity.name}RepositoryService` (e.g.
+`PositionRepositoryService`), so it doesn't matter how many times you call
+`.register()` for the same entity — the token is consistent, and
+`@RepositoryInject(whateverRegisterReturned)` always resolves to the same
+provider.
+
+See `src/examples/position-repository.example.ts` for a complete migration
+example using `Position`.
+
+## `BaseRepositoryService<T>` API (the `IBaseRepositoryService<T>` contract)
+
+| Method | What it does |
+|---|---|
+| `findOne(filter, opts?)` | Cache-first by default; falls back to `main` on a miss. `opts.target = 'main' \| 'cache'` forces a specific connection (no fallback). |
+| `find(filter, opts?)` | Same as `findOne` but returns a list. Supports `opts.sort/limit/skip/projection`. |
+| `create(dto)` | Inserts into `main`; the resulting document (with its `_id`) is replicated to cache and all backups. |
+| `insertMany(dtos[])` | Same as `create`, in bulk (`insertMany` + `bulkWrite` against cache/backups). |
+| `updateOne(filter, update)` | Updates `main` first, then replicates the resulting document to cache and backups. |
+| `updateMany(filter, update)` | Same, in bulk. |
+| `deleteOne(filter)` / `deleteMany(filter)` | Deletes from `main` first, then from cache and backups, and records a "tombstone" so periodic sync knows about it too. |
+
+## Resilience: what happens if cache or backups are down?
+
+**As long as `main` is up, the service works** — regardless of the state of
+`cache` or any `backup` connection.
+
+- **Reads (`findOne`/`find`)**: if the cache connection isn't ready or the
+  query fails, it's treated as a cache miss and `main` is queried directly —
+  the error never propagates.
+- **Writes (`create`/`insertMany`/`updateOne`/`updateMany`/`deleteOne`/`deleteMany`)**:
+  always run against `main` first. Propagation to `cache` and each `backup`
+  is attempted immediately; if a connection isn't ready (`readyState !== 1`)
+  or the operation fails, **that write is queued in memory** (one queue per
+  secondary connection) instead of failing the whole operation.
+- The pending-ops queue retries itself:
+    - Every `pendingOps.retryIntervalMs` (default 5000 ms).
+    - As soon as the connection emits mongoose's `connected` event (immediate
+      reaction, no need to wait for the next tick).
+    - If more than `pendingOps.maxQueueSize` operations pile up (default
+        1000) because a connection has been down for a while, the oldest ones
+              are dropped to avoid unbounded memory growth — that's fine, because
+              `BackupSyncService` catches backups up against `main` anyway, and for
+              cache, the next `find`/`findOne` simply repopulates it.
+- Queued operations are always `_id`-based upserts/deletes (idempotent), so
+  retrying them in order, even multiple times, is safe.
+- **Each backup is independent**: if you have two backups and one is down,
+  the other keeps advancing with its own checkpoint; the one that was down
+  catches up on its own once it's back (there's no shared checkpoint that
+  one problematic connection can block).
+- Tombstones (used to propagate deletes to backups) are only purged from
+  the collection once **every** configured backup has already applied them
+  — so a backup that was down doesn't lose the information it needs to
+  catch up.
+
+```ts
+RepositoryOrmModule.register({
+  // ...
+  pendingOps: {
+    retryIntervalMs: 5000, // how often pending writes are retried
+    maxQueueSize: 1000,    // in-memory cap per secondary connection
+  },
+});
+```
+
+## Custom service (`customService`)
+
+By default, `register(...)` uses `BaseRepositoryService`. If you need
+different behavior for a particular entity, you can pass your own class via
+`customService`:
+
+```ts
+RepositoryOrmModule.register({
+  entity: Position,
+  schema: positionSchema,
+  connectionName: ConnectionNames.OPERATION_MDB,
+  customService: PositionRepositoryService, // your class
+});
+```
+
+`customService` is typed as `Type<IBaseRepositoryService<T>>`, so
+**TypeScript won't let you assign a class that doesn't satisfy the
+interface** (`findOne`, `find`, `create`, `insertMany`, `updateOne`,
+`updateMany`, `deleteOne`, `deleteMany`, matching the exact
+`IBaseRepositoryService<T>` signatures).
+
+Two ways to write one (both shown in
+`src/examples/custom-repository-service.example.ts`):
+
+1. **Extend `BaseRepositoryService<T>`** (recommended): you inherit all the
+   cache/backup resilience and only override the method(s) you care about,
+   calling `super.method(...)` if you want to keep the original behavior.
+
+   ```ts
+   class PositionRepositoryService extends BaseRepositoryService<Position> {
+     async create(dto: Partial<Position>) {
+       const created = await super.create(dto);
+       console.log('Position created:', created);
+       return created;
+     }
+   }
+   ```
+
+2. **Implement `IBaseRepositoryService<T>` from scratch**: useful if you
+   want a completely different strategy (e.g. skip cache/backups
+   entirely). Its constructor must accept the same 9 parameters that
+   `register(...)` already resolves for you: `entity, options, mainModel,
+   cacheModel, cacheConfig, backupModels, backupLabels, tombstoneModel,
+   pendingOpsConfig` (even if you don't use all of them).
+
+Either way, you inject your custom service exactly like the default one,
+with `@RepositoryInject(...)` — nothing else in your code changes, because
+both satisfy `IBaseRepositoryService<T>`.
+
+## `RepositoryOrmModule.register(...)` configuration reference
+
+```ts
+{
+  entity: Position,            // entity class
+  schema: positionSchema,      // mongoose schema
+  connectionName: '...',       // main connection
+  options: {},                 // your BaseOrmOptions
+
+  cache: {                     // OPTIONAL
+    connectionName: '...',
+    ttlSeconds: 300,           // how long a document lives in the cache connection
+  },
+
+  backups: [                   // OPTIONAL, array of write-only connections
+    { connectionName: '...' },
+    { connectionName: '...' },
+  ],
+
+  backupSync: {                // OPTIONAL, only applies if `backups` is set
+    enabled: true,              // if false, nothing syncs automatically
+    intervalMs: 60_000,         // how often main vs. backups is checked
+    runOnStart: true,           // run a check as soon as the module starts
+    batchSize: 500,             // documents per batch per check
+  },
+
+  pendingOps: {                // OPTIONAL
+    retryIntervalMs: 5000,
+    maxQueueSize: 1000,
+  },
+
+  customService: PositionRepositoryService, // OPTIONAL, default: BaseRepositoryService
+}
+```
+
+## Design notes
+
+A few implementation choices worth knowing about if you're extending this
+library:
+
+1. **Cache vs. main on reads**: `findOne`/`find` without an explicit
+   `target` query cache first and fall back to `main` on a miss (and
+   repopulate cache in the background, without blocking the response).
+   With `target: 'main'` or `target: 'cache'`, only that connection is
+   queried, with no fallback.
+
+2. **Cache TTL**: uses an "expire at a specific time" TTL index
+   (`expireAfterSeconds: 0` on a `_cacheExpiresAt` field) instead of
+   classic Mongo TTL, so every write can set its own expiration based on
+   `cache.ttlSeconds`, independent of when the index was created.
+
+3. **How backup catch-up is detected**: for inserts/updates, `updatedTime`
+   is compared against a per-entity, per-backup checkpoint (this assumes
+   your model keeps `updatedTime` current on every write). For deletes,
+   instead of diffing the entire `_id` set (expensive at scale),
+   `deleteOne`/`deleteMany` record a "tombstone" (`_id` + deletion time) on
+   the `main` connection, which the sync process consumes and clears.
+   > If your "deletes" are actually soft-deletes (a `trashed: true` flag),
+   > the tombstone mechanism simply goes unused — `updatedTime`-based sync
+   > already covers it, since flipping `trashed` also bumps `updatedTime`.
+
+4. **Triggering backup sync**: by default, if `backupSync.enabled` is
+   `true`, the service starts its own internal `setInterval`
+   (`onModuleInit`/`onModuleDestroy`). If you'd rather have a lightweight
+   external process decide when to sync, set `enabled: false` and call the
+   public `syncNow()` method on `BackupSyncService` yourself (exposed as
+   the `${Entity}BackupSyncService` provider) from wherever makes sense
+   (an external cron, an endpoint, etc.).
+
+5. **`BaseOrmOptions`** is intentionally left open
+   (`{ [key: string]: any }`) so the library doesn't depend on any
+   particular project's option shape. Define and use your own typed
+   interface if you want strict typing.
+
+6. **CRUD surface**: `findOne`/`find`, `create`/`insertMany`,
+   `updateOne`/`updateMany`, `deleteOne`/`deleteMany` cover the most common
+   operations. If you need more (`count`, `exists`, `aggregate`,
+   pagination, etc.), add them to `IBaseRepositoryService`/
+   `BaseRepositoryService` following the same cache/backup propagation
+   pattern, or implement them in a `customService`.
+
+## Known limitation
+
+`updateMany` re-queries `main` with the original `filter` to know which
+documents to propagate to cache/backups. If `update` changes a field that's
+part of `filter` (e.g. `updateMany({ status: 'pending' }, { status: 'done'
+})`), those documents will no longer match and won't be propagated
+correctly. If this affects you, the workaround is to capture the affected
+`_id`s *before* updating — you can do this by overriding `updateMany` in a
+`customService`.
+
+## License
+
+MIT

package/dist/base-repository.service.d.ts

@@ -0,0 +1,73 @@
+import { Logger, OnModuleDestroy, OnModuleInit, Type } from '@nestjs/common';
+import { FilterQuery, Model, UpdateQuery } from 'mongoose';
+import { BaseOrmOptions, CacheConnectionConfig, FindOptions, PendingOpsConfig } from './types';
+import { PendingOpsQueue } from './utils';
+import { Observable } from 'rxjs';
+interface PropagationEntry {
+    model: Model<any>;
+    queue: PendingOpsQueue;
+    label: string;
+    op: () => Promise<any>;
+}
+/**
+ * Reemplazo genérico de los antiguos `XxxOrmService` (ej. PositionOrmService).
+ * Una sola clase sirve para cualquier entidad: la instancia la crea
+ * `RepositoryOrmModule.register(...)`, tú nunca extiendes esta clase.
+ *
+ * Resiliencia: si la conexión de caché o alguna de backup no está lista o
+ * falla al escribir, la operación sobre `main` se completa igual y la
+ * escritura hacia esa conexión secundaria queda pendiente en una cola en
+ * memoria que se reintenta sola (ver `utils/pending-ops-queue.ts`).
+ */
+export declare class BaseRepositoryService<T = any> implements OnModuleInit, OnModuleDestroy {
+    protected readonly entity: Type<T>;
+    protected readonly options: BaseOrmOptions;
+    protected readonly mainModel: Model<T>;
+    protected readonly cacheModel: Model<T> | undefined;
+    protected readonly cacheConfig: CacheConnectionConfig | undefined;
+    protected readonly backupModels: Model<T>[];
+    protected readonly tombstoneModel: Model<any> | undefined;
+    protected readonly logger: Logger;
+    protected readonly cacheLabel?: string;
+    protected readonly cacheQueue?: PendingOpsQueue;
+    protected readonly backupLabels: string[];
+    protected readonly backupQueues: PendingOpsQueue[];
+    constructor(entity: Type<T>, options: BaseOrmOptions, mainModel: Model<T>, cacheModel: Model<T> | undefined, cacheConfig: CacheConnectionConfig | undefined, backupModels: Model<T>[] | undefined, backupConnectionNames: string[] | undefined, tombstoneModel: Model<any> | undefined, pendingOpsConfig?: PendingOpsConfig);
+    onModuleInit(): void;
+    onModuleDestroy(): void;
+    findOne(filter: FilterQuery<T>, opts?: FindOptions): Observable<T | null>;
+    find(filter?: FilterQuery<T>, opts?: FindOptions): Observable<T[]>;
+    count(filter?: FilterQuery<T>): Observable<number>;
+    aggregate<R = any>(pipeline: any[]): Observable<R[]>;
+    create(dto: Partial<T>): Observable<T>;
+    insertMany(dtos: Partial<T>[]): Observable<T[]>;
+    updateOne(filter: FilterQuery<T>, update: UpdateQuery<T>): Observable<T | null>;
+    updateMany(filter: FilterQuery<T>, update: UpdateQuery<T>): Observable<{
+        matched: number;
+        modified: number;
+    }>;
+    updateObject(object: any): Observable<T | null>;
+    upsertBulk(bulkData: any[]): Observable<any>;
+    updateBulk(bulkData: any[]): Observable<any>;
+    deleteOne(filter: FilterQuery<T>): Observable<boolean>;
+    deleteMany(filter: FilterQuery<T>): Observable<number>;
+    protected propagate(entries: PropagationEntry[]): Observable<void>;
+    protected guard(model: Model<any>, label: string, op: () => Promise<any>): () => Promise<void>;
+    protected buildSingleEntries(doc: any, kind: 'upsert' | 'delete'): PropagationEntry[];
+    protected buildBulkEntries(docs: any[], kind: 'upsert' | 'delete'): PropagationEntry[];
+    protected tryCacheRead<R>(fn: () => Promise<R>): Observable<R | undefined>;
+    protected scheduleWriteToCache(doc: any): void;
+    protected withUpdatedTime(update: UpdateQuery<T>): UpdateQuery<T>;
+    protected upsertInto(model: Model<T>, doc: any): Promise<void>;
+    protected bulkUpsertInto(model: Model<any>, docs: any[], isCache: boolean): Promise<void>;
+    protected withCacheExpiry(doc: any): any;
+    protected recordTombstone(id: any): Promise<void>;
+    protected applyCursorOptions<Q extends {
+        sort: Function;
+        skip: Function;
+        limit: Function;
+    }>(query: Q, opts: FindOptions): Q;
+    protected toEntity(doc: any): T;
+}
+export {};
+//# sourceMappingURL=base-repository.service.d.ts.map

package/dist/base-repository.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-repository.service.d.ts","sourceRoot":"","sources":["../src/base-repository.service.ts"],"names":[],"mappings":"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"}