PostgREST

Cos'è @pzeta/postgrest

@pzeta/postgrest è la libreria client TypeScript per consumare API PostgREST seguendo i principi di Domain-Driven Design e Clean Architecture. Espone un facade ad alto livello (PostgRESTClient), una classe base service (BasePostgrestService) per il pattern di adozione canonico nei progetti PZeta, e l'intera infrastruttura modulare (HTTP, cache, auth, repository) per casi che richiedono controllo fine.

Funzionalità principali

• Facade PostgRESTClient — setup in due righe, gestisce HTTP, auth, cache e repository factory
• Service Pattern — BasePostgrestService come classe base per service di dominio (CRUD + RPC + error messages italiani)
• Repository Pattern — PostgRESTRepository e EnhancedPostgRESTRepository CRUD type-safe
• 5 Cache Strategies — IndexedDB (default), LocalStorage, SessionStorage, Memory, None con auto-fallback
• 4 Auth Strategies — JWT (sessionStorage), Cookie HTTP-only, ApiKey, None — interfaccia IAuthStrategy per strategie custom
• Filtering type-safe — FilterCriteria<T> con tutti gli operatori PostgREST (eq, ilike, between, in, fts, ...), sort, paginazione, vertical filtering
• Dual HTTP Client — FetchHttpClient (nativo, zero deps) o AxiosHttpClient (opzionale)
• Schema PostgreSQL — header Accept-Profile / Content-Profile per multi-schema
• MFE entry point — subpath @pzeta/postgrest/mfe con PostgrestMfeService, BaseMfePostgrestService e composables Vue

Architettura

@pzeta/postgrest
├── domain/              # Zero dipendenze runtime
│   ├── entities/        # AuthEntity
│   ├── value-objects/   # FilterCriteria · CacheMetadata
│   └── interfaces/      # IAuthService · ICrudRepository · IHttpClient · ILogger · ICacheStrategy
├── application/
│   ├── facades/         # PostgRESTClient (entry point principale)
│   └── services/        # BasePostgrestService (classe base service di dominio)
├── infrastructure/
│   ├── http/            # FetchHttpClient · AxiosHttpClient · HttpClientFactory · FetchAdapter · CorsAdapter
│   ├── repositories/    # PostgRESTRepository · EnhancedPostgRESTRepository · RepositoryFactory
│   ├── auth/            # AuthService + strategies/ (JWT · Cookie · ApiKey · None) + factory
│   ├── cache/           # CacheService · IndexedDBStore + 5 strategies + factory
│   ├── logging/         # ConsoleLogger · NullLogger
│   └── utils/           # FilterUtils · TypeGuards
└── mfe/                 # Entry separato per microfrontend (subpath /mfe)
    ├── PostgrestMfeService
    ├── BaseMfePostgrestService
    ├── composables/     # usePostgrestPagination · useReferenceData
    └── utils/

Le dipendenze puntano sempre verso l'interno: infrastructure → application → domain. Il domain layer non importa nulla dall'esterno.

Sotto-pagine

Quick start

import { PostgRESTClient } from '@pzeta/postgrest'

interface User {
  iduser: number
  email: string
  nome: string
}

const client = new PostgRESTClient({
  apiUrl: 'https://api.example.com',
  schema: 'public',
})
await client.init()

await client.login({ email: 'mario@example.com', password: 'pwd' })

const userRepo = client.repository<User, number>('/users', 'iduser')

const utenti = await userRepo.readAll({
  nome: { operator: 'ilike', value: '%mario%' },
  sort: { field: 'iduser', direction: 'desc' },
  pagination: { limit: 20, offset: 0 },
})

client.destroy() // cleanup obbligatorio

Per progetti strutturati il pattern consigliato è estendere BasePostgrestService: vedi Service Pattern.

Quando usare cosa

Stack tecnico

• TypeScript ~6.0 — strict mode, zero any
• ESM only — "type": "module", build via tsc
• Subpath exports — . (core) e /mfe (microfrontend)
• Zero dipendenze runtime — Fetch API nativa di default
• Peer dependencies opzionali — axios, vue, @pzeta/mfe-contracts
• Vitest v4 per i test (1000+ test nella suite)
• Biome per lint e format