Genera tipi TypeScript da DynamoDB

In Postgres dovresti analizzare information_schema e generare tipi da esso. DynamoDB non ha equivalenti: DynamoDB non memorizza alcuno schema di elementi. Gli unici attributi service conosce sono quelli utilizzati nelle chiavi. "DescribeTable". AttributeDefinitions è esplicito riguardo al proprio ambito: ogni voce "descrive un attributo nella tabella e nello schema delle chiavi dell'indice" (riferimento AWS API) — gli altri cinquanta attributi della tua tabella semplicemente non vengono registrati da nessuna parte.

Quindi "genera tipi TypeScript da DynamoDB" significa sempre una delle tre cose: dichiara tu stesso la forma, derivala da uno schema di cui sei autore codice, o dedurlo dagli elementi realmente esistenti.

Come posso ottenere i tipi TypeScript per una tabella DynamoDB?

Non esiste API che restituisca la forma dell'elemento di una tabella: lo sa solo DescribeTable gli attributi chiave. Le tue opzioni: scrivi a mano un'"interfaccia" e convalidala su il confine (uno schema Zod rende i tipi e il controllo di runtime uno artefatto), utilizzare una libreria schema-first in cui lo schema creato produce il file tipi o dedurre la forma da oggetti reali tramite script o con uno strumento come DynoTable che scansiona la tabella ed esporta un TypeScript interfaccia, schema Zod o schema JSON.

Metodo 1: scrivere a mano l'interfaccia (+ Zod al confine)
Metodo 2: librerie schema-first (tipi da uno schema creato da te)
Metodo 3: dedurre dai dati stessi

Metodo 1: scrivere a mano l'interfaccia + convalidare al confine

L'AWS SDK non può digitare i tuoi articoli per te. Il client Document v3 ritorna elementi come record non tipizzati: ogni risultato GetCommand / QueryCommand è effettivamente Registra<stringa, sconosciuto> finché tu non affermi il contrario. Uno nudo Il cast as Order viene compilato correttamente e giace in fase di esecuzione, motivo per cui un file strict La versione accoppia l'interfaccia con un controllo di runtime:

import {z} from 'zod';

const Order = z.object({
  PK: z.string(), // ORDER#<id>
  SK: z.string(), // META
  status: z.enum(['open', 'shipped', 'cancelled']),
  total: z.number(),
  couponCode: z.string().optional() // sparse attribute
});
type Order = z.infer<typeof Order>;

const {Item} = await doc.send(new GetCommand({TableName: 'Orders', Key: key}));
const order = Order.parse(Item); // typed AND verified

Uno schema, due lavori: z.infer ti dà il tipo statico, parse cattura il tipo elemento che non corrisponde ad esso, che in un negozio senza schema è un when, non un se. Il problema è altrettanto chiaro: lo schema documenta il tuo intento, non la tua tabella. Niente impedisce a un vecchio scrittore di memorizzare total come file string e i tipi scritti a mano si spostano silenziosamente man mano che i dati si evolvono.

Se stai lavorando dall'output API grezzo (non-Document-client), ricorda il cavo la forma è contrassegnata dal tipo DynamoDB-JSON ({"S": "..."}, {"N": "123"}) — vedi marshalling e utilizzare il file DynamoDB JSON convertitore per capovolgere un campione tra il filo e la forma semplice mentre scrivi lo schema.

Metodo 2: librerie schema-first

Toolkit come ElectroDB e DynamoDB-Toolbox affrontano il problema della deriva dal lato di scrittura: crei uno schema di entità nel codice e la libreria deriva i tipi TypeScript e impone la forma a ogni lettura e scrittura si esibisce. Questa è la garanzia più forte disponibile, ma tieni presente il direzione: scrivi tu lo schema; la biblioteca non lo scopre. Indicazione uno su una tabella esistente significa ancora decodificare le forme dell'oggetto prima te stesso e gli elementi scritti fuori dalla libreria sono fuori dalla sua garanzie. Brillano sui greenfield design a tabella singola dove ogni entità passa attraverso il toolkit dal primo giorno.

Metodo 3: dedurre i tipi da oggetti reali

Per una tabella esistente, la verità fondamentale sono i dati. Scan un campione, unisci le forme:

const seen = new Map<string, Set<string>>(); // attr -> observed types
let count = 0;
let key: Record<string, unknown> | undefined;
do {
  const page = await doc.send(new ScanCommand({TableName: 'Orders', ExclusiveStartKey: key}));
  for (const item of page.Items ?? []) {
    count++;
    for (const [attr, value] of Object.entries(item)) {
      const t = Array.isArray(value) ? 'array' : typeof value;
      (seen.get(attr) ?? seen.set(attr, new Set()).get(attr)!).add(t);
    }
  }
  key = page.LastEvaluatedKey;
} while (key && count < 5000);
// emit: attribute -> type union, optional if seen in < count items

Le insidie del mondo reale che la versione ingenua colpisce immediatamente:

Attributi sparsi. Gli elementi DynamoDB in una tabella possono avere diversi attributi; un attributo presente nell'80% degli articoli è opzionale, no mancante. Tieni traccia della frequenza per attributo, non solo della presenza.
Entità miste. In una progettazione a tabella singola, Gli elementi "USER#" e "ORDER#" condividono la tabella: un'interfaccia unita per entrambi è inutile. Suddividere il campione in base a attributo tipo ed emette un tipo per entità.
Collisioni di tipi. Lo stesso attributo memorizzato come N qui e S lì è presente un bug di dati reale (e comune): mostralo come un'unione anziché silenziosamente scegliendone uno. Il set completo di tag si trova in tipi di dati.
Un campione è un campione. Gli attributi che appaiono solo su oggetti rari potrebbero non esserlo essere tra i primi 5.000 e la scansione costa in ogni caso la capacità di lettura (query vs scansione).

Inferenza con un clic in DynoTable

Quello script di inferenza: campionamento, monitoraggio della frequenza, percorsi nidificati, il Suddivisione per entità: è integrata nelle Statistiche tabella di DynoTable pannello:

Apri una tabella, premi il pulsante Statistiche (l'icona del grafico a barre) e fai clic Tabella indice. DynoTable campiona la tabella con progressi e record in tempo reale gli attributi che trova, inclusi quelli nidificati tramite percorso tratteggiato, come commonData.status — con il tipo di ciascuno e se era richiesto o opzionale tra le righe scansionate. La scansione è limitata, quindi è un attributo appare solo in oggetti rari e può mancare; vedere Panoramica e indicizzazione della tabella.
Fai clic su Esporta e scegli un formato:
- TypeScript: un'"interfaccia".
- Zod — uno schema z.object(...) (compatibile con lo schema standard).
- JSON Schema — bozza 2020-12.
Copialo negli appunti o salvalo in un file.

Pannello Statistiche tabella di DynoTable: l'elenco dei campi indicizzati con tipi e flag obbligatori/facoltativi e il pulsante Esporta schema.

Ogni schema generato si apre con a si noti che è stato dedotto dagli elementi campionati: un buon inizio punto, non un contratto autorevole. L'opzionalità riflette la frequenza con cui ciascuno l'attributo è apparso durante l'indicizzazione e gli attributi della chiave primaria lo sono sempre contrassegnato come richiesto. L'indicizzazione comporta normali costi di lettura DynamoDB e Reindicizzazione aggiorna l'immagine dopo la modifica dei dati.

FAQ

Posso generare tipi da DescribeTable? Solo per gli attributi chiave. "AttributeDefinitions" copre la tabella e schema della chiave dell'indice: nient'altro sui tuoi articoli viene archiviato dal servizio, quindi non esiste uno schema lato server da analizzare.

Qual è il modo migliore per digitare una tabella di produzione esistente? Prima deduci, poi rafforza: prova gli elementi reali (script o DynoTable's esportazione indicizzata) per ottenere la forma effettiva, rivederla, e promuoverlo in uno schema Zod di proprietà manuale o in un'entità di libreria con primo schema la deriva futura è catturata al confine.

Come posso gestire più tipi di entità in un'unica tabella? Un tipo per entità, mai un tipo unito. Dividi il campione sul tuo tipo attributo (o prefisso chiave) e generare un'interfaccia separata per ciascuno: l'unione discriminata di questi è tua tipo di tabella.

Perché i tipi generati indicano che un campo obbligatorio è facoltativo? Perché alcuni articoli campionati non ce l'avevano. In un negozio senza schema opzionale è un'osservazione, non una dichiarazione: controlla se tali elementi sono legacy righe da riempire (vedi migrazioni) o un file veramente attributo facoltativo.

I tipi coprono insiemi DynamoDB e binari? Un convertitore deve scegliere rappresentazioni semplici JSON: gli insiemi diventano array e Il binario diventa una stringa codificata: le stesse stranezze di mappatura coperte marshalling. Viaggio di andata e ritorno attraverso un campione il convertitore DynamoDB JSON per vedere esattamente come appaiono i tuoi attributi su ciascun lato.

Smetti di indovinare la forma della tua tabella: download DynoTable, indicizza il table ed esportare uno schema TypeScript, Zod o JSON con un clic.