Repositories

RepositoryFactory

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

Overview

RepositoryFactory è una classe statica che incapsula la creazione di EnhancedPostgRESTRepository con configurazioni standard PZeta. Implementa il pattern Factory + Configuration Default per garantire coerenza e ridurre il boilerplate.

import { RepositoryFactory, DEFAULT_REPOSITORY_CONFIG } from '@pzeta/postgrest'

RepositoryFactory.create() è il modo consigliato per istanziare un repository nel 90% dei casi. I metodi preset (createWithJwt, createCached, ecc.) sono shortcut semantici che esprimono l'intento di alto livello.

`DEFAULT_REPOSITORY_CONFIG`

Il preset di base applicato a tutti i metodi della factory (override-abile per call):

export const DEFAULT_REPOSITORY_CONFIG = {
  cacheTTL: 3_600_000,            // 1 ora
  useBackgroundRefresh: true,
  isAuthRequired: true,
  useCache: true,
  authStrategy: AuthStrategyType.JWT,
}

Campo	Valore	Significato
`cacheTTL`	1h	Caching aggressivo ma con refresh in background
`useBackgroundRefresh`	`true`	Stale-while-revalidate (UX prioritaria)
`isAuthRequired`	`true`	JWT incluso di default
`useCache`	`true`	Cache abilitata
`authStrategy`	`JWT`	Strategia di default

`RepositoryConfig`

export interface RepositoryConfig {
  schema?: string
  cacheTTL?: number
  useBackgroundRefresh?: boolean
  isAuthRequired?: boolean
  useCache?: boolean
  authStrategy?: IAuthStrategy | AuthStrategyType
}

Tutti i campi sono opzionali — RepositoryFactory.create() fa il merge con DEFAULT_REPOSITORY_CONFIG.

API

`create<T, K>(baseUrl, path, keyName, config?)`

Metodo principale — applica DEFAULT_REPOSITORY_CONFIG con override selettivi.

static create<T extends Record<string, unknown>, K>(
  baseUrl: string,
  path: string,
  keyName: keyof T,
  config?: Partial<RepositoryConfig>,
): EnhancedPostgRESTRepository<T, K>

Preset disponibili

Metodo	Uso tipico	Config applicata
`create()`	Standard enterprise	`DEFAULT_REPOSITORY_CONFIG` (auth JWT + cache 1h)
`createPublic()`	Endpoint pubblici (categorie, lookup)	`isAuthRequired: false`, `useCache: false`, `authStrategy: NONE`
`createWithJwt()`	Auth JWT esplicita con override	Default + `authStrategy: JWT`
`createWithCookie()`	Sessioni server-side cookie-based	Default + `authStrategy: COOKIE`
`createCached()`	Dati raramente mutevoli (config, traduzioni)	`cacheTTL: 86_400_000` (24h)
`createRealtime()`	Dati ad alta freschezza (notifiche, stock)	`useCache: false`

Esempi per preset

Standard

const userRepo = RepositoryFactory.create<User, number>(
  'https://api.example.com',
  '/utenti',
  'idutente',
)
// → JWT, cache 1h, background refresh

Public (no auth, no cache)

interface Categoria extends Record<string, unknown> {
  idcategoria: number
  nome: string
}

const categorieRepo = RepositoryFactory.createPublic<Categoria, number>(
  'https://api.example.com',
  '/categorie',
  'idcategoria',
)

JWT con override

const productRepo = RepositoryFactory.createWithJwt<Product, number>(
  'https://api.example.com',
  '/prodotti',
  'idprodotto',
  { cacheTTL: 7_200_000, schema: 'shop' }, // override 2h + schema custom
)

const sessionRepo = RepositoryFactory.createWithCookie<Session, string>(
  'https://api.example.com',
  '/sessioni',
  'idsessione',
)

Cached aggressivo (24h)

const configRepo = RepositoryFactory.createCached<Config, string>(
  'https://api.example.com',
  '/configurazioni',
  'chiave',
)

Ideale per lookup tables, traduzioni i18n, feature flags.

Realtime (no cache)

const notificheRepo = RepositoryFactory.createRealtime<Notifica, number>(
  'https://api.example.com',
  '/notifiche',
  'idnotifica',
)

Ogni read va al server — usa per stock, messaggi, notifiche live.

Esempio combinato in un service

import { RepositoryFactory } from '@pzeta/postgrest'

const baseUrl = import.meta.env.VITE_API_URL

export const repositories = {
  utenti: RepositoryFactory.createWithJwt<User, number>(baseUrl, '/utenti', 'idutente'),
  categorie: RepositoryFactory.createCached<Categoria, number>(baseUrl, '/categorie', 'idcategoria'),
  notifiche: RepositoryFactory.createRealtime<Notifica, number>(baseUrl, '/notifiche', 'idnotifica'),
  pubblicoStats: RepositoryFactory.createPublic<Stat, string>(baseUrl, '/stats_pubbliche', 'chiave'),
}

Il campo authStrategy di RepositoryConfig viene utilizzato solo a livello di dichiarazione di intento: EnhancedPostgRESTRepository riceve isAuthRequired ma non un authHandler esplicito tramite la factory. L'auth handler effettivo deve essere configurato a livello di PostgRESTClient.

Cross-reference

EnhancedPostgRESTRepository — tipo di ritorno
PostgRESTClient — facade che usa la factory internamente
AuthStrategy — strategie di autenticazione (JWT, Cookie, NGINX, ApiKey)
CacheService — caching sottostante

PostgRESTRepository

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

RepositoryUtils

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