Repositories

Repository Pattern type-safe per PostgREST — classi CRUD generiche, wrapper semplificati, factory con preset e utility runtime per errori, path e type guards.

Il layer Repository

Il package @pzeta/postgrest implementa il Repository Pattern come strato di astrazione tra le facade applicative (PostgRESTClient, BasePostgrestService) e il client HTTP. I repository sono type-safe, generici sui type parameter <T, K> e gestiscono nativamente cache, schema PostgreSQL multipli e operazioni bulk/RPC.

import {
  PostgRESTRepository,
  EnhancedPostgRESTRepository,
  BaseEnhancedRepository,
  CrudRepositoryBase,
  RepositoryFactory,
  RepositoryUtils,
  RestError,
} from '@pzeta/postgrest'

Panoramica classi

Classe / Utility	Ruolo	Quando usarla
`PostgRESTRepository`	Repository CRUD core — implementa tutte le operazioni HTTP verso PostgREST	Path multipli sulla stessa istanza, full control su schema/cache/auth
`EnhancedPostgRESTRepository`	Wrapper semplificato con `path` e `keyName` fissi	Una sola tabella/entità per istanza (caso più frequente)
`BaseEnhancedRepository`	Classe base astratta dietro `EnhancedPostgRESTRepository`	Estendere con metodi custom (`findByEmail`, query specifiche)
`CrudRepositoryBase`	Contratto astratto `ICrudRepository`	Implementare backend non-PostgREST mantenendo l'API CRUD
`RepositoryFactory`	Factory statica con preset (Public, JWT, Cookie, Cached, Realtime)	Setup veloce DRY, scelta semantica del preset
`RepositoryUtils`	Utility statiche: gestione errori, parsing path, cache key, `RestError`	Try/catch tipizzati su `RestError`, normalizzazione URL
`TypeGuards`	Type guards runtime per validazione sicura	Narrowing TypeScript su `unknown`, error handling difensivo

Architettura

         ┌──────────────────────────────┐
         │   RepositoryFactory          │  ← create() / createPublic() / createWithJwt() ...
         └──────────────┬───────────────┘
                        │ istanzia
                        ▼
         ┌──────────────────────────────┐
         │ EnhancedPostgRESTRepository  │  ← API semplificata per singola entità
         │   extends                    │
         │ BaseEnhancedRepository<T,K>  │
         └──────────────┬───────────────┘
                        │ delega a
                        ▼
         ┌──────────────────────────────┐
         │   PostgRESTRepository        │  ← implementazione concreta CRUD/RPC
         │   extends CrudRepositoryBase │
         │   implements ICrudRepository │
         └──────────────────────────────┘

Per il 90% dei casi usa RepositoryFactory.create<T, K>(...) — ottieni un EnhancedPostgRESTRepository già configurato con preset enterprise (cache 1h, JWT, background refresh). Estendi BaseEnhancedRepository solo quando devi aggiungere metodi custom di dominio.

Sotto-pagine

BaseEnhancedRepository

Classe base estendibile che fornisce CRUD + RPC + cache su path e keyName fissi — punto di estensione per repository di dominio con metodi custom type-safe.

CrudRepositoryBase

Classe base astratta che definisce il contratto CRUD implements ICrudRepository — punto di estensione per backend non-PostgREST mantenendo l'API uniforme.

EnhancedPostgRESTRepository

Wrapper semplificato di PostgRESTRepository con path e keyName fissi nel costruttore — API minimale type-safe per singola entità.

PostgRESTRepository

Repository CRUD core con supporto completo PostgREST — CRUD, bulk, RPC, paginazione cursor-based, caching, multi-schema e prefetch proattivo.

RepositoryFactory

Factory statica per creare EnhancedPostgRESTRepository con preset enterprise — JWT, Cookie, Cached 24h, Realtime, Public — applicando DEFAULT_REPOSITORY_CONFIG.

RepositoryUtils

Utility statiche per gestione errori PostgREST tipizzati (RestError), parsing path URL, generazione filter hash deterministici e costruzione cache key.

TypeGuards

Type guards runtime per validazione type-safe — narrowing TypeScript su unknown, gestione difensiva errori Axios e validazione struttura oggetti.

StrategyAwareHttpClient

Client HTTP basato su Axios che integra IAuthStrategy moderna mantenendo backward compatibility con IAuthHandler legacy.

BaseEnhancedRepository

Classe base estendibile che fornisce CRUD + RPC + cache su path e keyName fissi — punto di estensione per repository di dominio con metodi custom type-safe.