Contract First e @feelai/contract: Un nuovo approccio per lo sviluppo di applicazioni sicure dal punto di vista dei tipi di dati

Nel mondo dello sviluppo software moderno, garantire la coerenza tra client e server è una sfida non da poco. Il metodo Contract First è emerso come una soluzione efficace, ed è ora fortemente supportato dalla libreria @feelai/contract.

Contract First: Il metodo di programmazione che definisce prima il contratto

Contract First è un metodo di sviluppo software in cui la definizione dell'interfaccia di programmazione dell'applicazione (API) viene stabilita prima dell'implementazione dettagliata. Invece di scrivere prima il codice e poi definire l'API, questo metodo richiede:

Definizione chiara degli endpoint, degli input e degli output
Creazione di un contratto tra client e server
Sviluppo parallelo di entrambi i lati basato sul contratto definito

I vantaggi di Contract First includono:

Minimizzare gli errori di comunicazione tra i team
Consentire lo sviluppo parallelo di frontend e backend
Garantire la coerenza dei tipi di dati
Semplificare il testing e la generazione di dati mock

@feelai/contract: Una libreria TypeScript per Contract First

@feelai/contract è una libreria npm che aiuta a implementare il metodo Contract First nei progetti TypeScript. Questa libreria fornisce strumenti per definire contratti API in modo type-safe, condivisibili tra client e server senza problemi di dipendenza circolare.

Funzionalità principali

Sicurezza dei tipi di dati: Utilizza typebox per definire gli schemi
Definizione centralizzata dei contratti: Gestisce i contratti API, Stream e Socket in un unico posto
Inferenza statica dei tipi: Estrae i tipi TypeScript dalle definizioni dei contratti runtime
Separazione delle responsabilità: Separa la definizione dell'API dai dettagli di implementazione

Installazione

bun add @feelai/contract
# oppure
npm install @feelai/contract
# oppure
yarn add @feelai/contract

Utilizzo pratico

Di seguito è riportato un esempio di definizione di contratto per un'applicazione di gestione delle attività:

import { Contract, defineApiMap, defineSocketMap } from "@feelai/contract";
import { Type } from "typebox";

// Definizione dello schema
export const TaskSchema = Type.Object({
  id: Type.String(),
  title: Type.String(),
  completed: Type.Boolean(),
  createdAt: Type.Number(),
});

// Definizione degli endpoint API
const api = defineApiMap({
  getTasks: {
    output: Type.Array(TaskSchema),
  },
  createTask: {
    input: Type.Object({
      title: Type.String(),
    }),
    output: TaskSchema,
  },
});

// Definizione degli eventi Socket
const socket = defineSocketMap({
  taskUpdates: {
    client: {
      subscribe: Type.Object({}),
    },
    server: {
      taskCreated: TaskSchema,
      taskUpdated: TaskSchema,
    },
  },
});

// Creazione ed esportazione del contratto
export const todoListContract = new Contract().api(api).socket(socket);
export type TodoListContract = typeof todoListContract;

Inferenza dei tipi di dati

Uno dei punti di forza di @feelai/contract è la sua capacità di inferenza automatica dei tipi:

import { StaticApiMap, StaticSocketMap } from "@feelai/contract";
import { todoListContract } from "./todoListContract";

// Tipi per l'implementazione dell'API
export type ApiTypes = StaticApiMap<typeof todoListContract>;

// Tipi per l'implementazione del Socket
export type SocketTypes = StaticSocketMap<typeof todoListContract>;

Vantaggi nell'uso di @feelai/contract

Sviluppo parallelo: I team frontend e backend possono lavorare in modo indipendente basandosi sul contratto definito
Riduzione degli errori: Il controllo dei tipi di dati al momento della compilazione aiuta a individuare gli errori precocemente
Documentazione automatica: Il contratto funge da documentazione vivente per l'API
Manutenzione facilitata: Le modifiche all'API sono gestite centralmente in un unico posto

Conclusione

Il metodo Contract First combinato con la libreria @feelai/contract offre un approccio sistematico allo sviluppo di applicazioni web moderne. Con la sua capacità di garantire la sicurezza dei tipi di dati end-to-end, minimizzare gli errori di comunicazione tra client e server e supportare lo sviluppo parallelo, è uno strumento prezioso per progetti TypeScript di medie e grandi dimensioni.

Per saperne di più su @feelai/contract, visita: https://www.npmjs.com/package/@feelai/contract