Getting Started

Installazione

Installazione di @pzeta/postgrest, peer dependencies opzionali (axios, vue, @pzeta/mfe-contracts), subpath exports core e /mfe, verifica con esempio minimo.

Installazione

npm install @pzeta/postgrest

Zero dipendenze runtime obbligatorie: la libreria usa la Fetch API nativa di default. Tutte le peer dependencies sono dichiarate come optional e vanno installate solo se serve la funzionalità corrispondente.

Peer dependencies opzionali

Pacchetto	Versione	Quando installarlo
`axios`	`^1.8.2`	Se vuoi usare `AxiosHttpClient` invece di `FetchHttpClient` (interceptors avanzati, progress tracking)
`vue`	`^3.4.0`	Se usi i composables MFE (`usePostgrestPagination`, `useReferenceData`) o l'entry `/mfe` in un'app Vue
`@pzeta/mfe-contracts`	`>=0.1.0`	Se importi `@pzeta/postgrest/mfe` (subpath microfrontend con `MFEHttpClient` da shell host)

# Esempio: client Axios + integrazione MFE
npm install @pzeta/postgrest axios @pzeta/mfe-contracts

Engine

Tool	Versione minima
Node.js	`>=22.0.0`
npm	`>=10.0.0`

Subpath exports

La libreria espone due entry point distinti per consentire bundle ottimizzati:

// Entry principale - facade, repository, factory, auth/cache strategies
import {
  PostgRESTClient,
  BasePostgrestService,
  EnhancedPostgRESTRepository,
  AuthStrategyFactory,
  CacheStrategyFactory,
  type FilterCriteria,
} from '@pzeta/postgrest'

// Entry MFE - service pattern per microfrontend basati su @pzeta/mfe-contracts
import {
  PostgrestMfeService,
  BaseMfePostgrestService,
  usePostgrestPagination,
  useReferenceData,
} from '@pzeta/postgrest/mfe'

Subpath	Cosa esporta	Quando usarlo
`.`	Facade, repository, strategy factory, value objects, tutte le primitive core	App standalone che gestiscono HTTP/auth/cache internamente
`/mfe`	`PostgrestMfeService`, `BaseMfePostgrestService`, composables Vue, utils	Microfrontend Vue che ricevono `MFEHttpClient` dalla shell host

ESM only

Il pacchetto è ESM puro ("type": "module"). Build via tsc, output in dist/. I consumer devono usare ESM o tooling con interop (Vite, esbuild, Webpack 5+).

{
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./mfe": {
      "import": "./dist/mfe/index.js",
      "types": "./dist/mfe/index.d.ts"
    }
  }
}

NPM registry PZeta

Il pacchetto è pubblicato sul registry privato PZeta. Aggiungi questa riga al file .npmrc del progetto consumer:

@pzeta:registry=https://gitea.pzetatouch.it/api/packages/pzeta_touch/npm/

Verifica installazione

Prova minima per verificare che import e tipi siano disponibili:

import { PostgRESTClient } from '@pzeta/postgrest'
import type { FilterCriteria } from '@pzeta/postgrest'

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

console.log('Autenticato?', client.isAuthenticated()) // false

client.destroy()

Se la compilazione TypeScript passa e l'esecuzione non lancia errori prima di destroy(), l'installazione è OK.

Chiama sempre client.destroy() quando il client non serve più (es. onUnmounted in un componente Vue, prima di navigare via in una SPA). Senza cleanup, i timer interni del CacheService causano memory leak.

Architettura

Modello Clean Architecture + DDD a tre layer (domain, application, infrastructure). Dependency Rule, Strategy Pattern per auth e cache, Repository Pattern, Factory Pattern, Facade Pattern.

Quick Start

Tre approcci per iniziare con @pzeta/postgrest - facade PostgRESTClient (semplice), setup manuale con EnhancedPostgRESTRepository (controllo), service pattern con BasePostgrestService (consigliato per progetti strutturati).