Data RESTorage, overview tecnico

^ Panoramica Architetturale e Whitepaper Funzionalità

Data RESTorage (DRS) è un motore di backend ibrido documentale e relazionale a zero overhead, progettato per eliminare la complessità, il consumo di risorse e l'imprevedibilità prestazionale tipici dei database NoSQL tradizionali e dei pesanti layer ORM.

Sostituendo i linguaggi di query astratti e i query optimizer dinamici con moduli asincroni scolpiti e deterministici (TypeScript/JavaScript) e introducendo il concetto di Deep Indexing ibrido, DRS garantisce tempi di risposta sub-millisecondo prevedibili, integrità transazionale unificata e massima agilità di sviluppo.

^ Innovazioni Architetturali Chiave

                      ┌────────────────────────────────────────────────────────┐
                      │    Client REST (GET / POST - Payload JSON / XML)       │
                      └───────────────────────────┬────────────────────────────┘
                                                  │
                                                  ▼
                      ┌────────────────────────────────────────────────────────┐
                      │ Middleware Autoexec a Cascata (Dataset/Schema/Entity)  │
                      └───────────────────────────┬────────────────────────────┘
                                                  │
                                                  ▼
                      ┌────────────────────────────────────────────────────────┐
                      │ Modulo Operazione Target: op-*.ts / op-*.mjs           │
                      │ (Logica di Business Deterministica e Flusso Diretto)   │
                      └───────────────────────────┬────────────────────────────┘
                                                  │
                        ┌─────────────────────────┴──────────────────────────┐
                        ▼                                                    ▼
          [ 1. Documento Alberato Completo ]                    [ 2. Deep Indexing Puntuale ]
          Memorizzazione documento JSON ricco                   Tabelle Indice SQL Relazionali
          (Sfrutta la Page Cache del kernel OS)                (Proiezioni MariaDB / PostgreSQL)
                        │                                                    │
                        ▼                                                    ▼
              `drs.set(docId, json)`                                  `drs.sql(query, values)`
            Accesso rapido O(1) Chiave/File                  Indici piatti e fortemente tipizzati
                        │                                                    │
                        └─────────────────────────┬──────────────────────────┘
                                                  │
                                                  ▼
                                           `drs.commit()`
                       Transazione Atomica Unificata (Filesystem + DB Relazionale)

^ 1. Eliminati sia lo scoglio del linguaggio di query che il peso del query optimizer

I motori di database convenzionali (sia relazionali che documentali come MongoDB) si basano su complessi Query Optimizer incaricati di tradurre query dichiarative (SQL, MQL, GraphQL) in piani di esecuzione fisici.

^ Il Problema dei Query Optimizer Tradizionali

• Plan Regression e Imprevedibilità: Gli ottimizzatori operano su stime statistiche e campionamenti. All'aumentare dei dati o al variare della cardinalità, l'ottimizzatore può improvvisamente cambiare il piano di esecuzione, trasformando una query da 2 ms in un blocco di diversi secondi senza alcuna modifica al codice applicativo.
• Overhead Computazionale Continuo: Ogni richiesta in ingresso richiede parsing sintattico, generazione dell'albero AST (Abstract Syntax Tree), riscrittura algebrica e valutazione del piano prima ancora di leggere un singolo record.
• Il Debito Tecnico degli ORM: Per mappare i dati nel codice applicativo, vengono introdotti ORM pesanti che causano latenza aggiuntiva, consumo di memoria e problemi endemici come le query N+1.

^ La Soluzione DRS: Determinismo Procedurale Esplicito

• Nessun Overhead di Query Language: Gli endpoint REST mappano direttamente su funzioni asincrone JavaScript/TypeScript (op-*.ts / op-*.mjs).
• Accesso Deterministico O(1) e O(log N): Lo sviluppatore definisce con precisione l'accesso al dato. La complessità algoritmica è esplicita, trasparente e costante nel tempo.
• Stored Procedures Moderne: Unisce i vantaggi storici delle Stored Procedure (vicinanza al dato, esecuzione istantanea, incapsulamento) con il linguaggio standard del web (TypeScript/JavaScript puro), con pieno supporto a Git, hot-reloading e debug nativo.

^ 2. Deep Indexing e Proiezione Relazionale Ibrida

L'interrogazione e l'indicizzazione di dati JSON ricchi, fortemente nidificati o con array interni è storicamente uno dei nodi più critici dei database documentali.

^ I limiti di MongoDB e dei Document Store Puri

• Esplosione degli Indici (Index Bloat) e Pressione sulla RAM: L'indicizzazione di percorsi profondi o array annidati in MongoDB richiede Multikey Index o Wildcard Index. Questi indici crescono rapidamente a dismisura, saturando la RAM del motore di storage (WiredTiger) e generando una forte amplificazione delle scritture (write amplification).
• Rigidità dei Dati Indicizzabili: Nei database documentali è possibile indicizzare solo i campi grezzi presenti nel documento. Indicizzare valori calcolati, normalizzati o derivati da logiche di business richiede pipeline di aggregazione asincrone o Change Streams complessi.
• Scansioni e Aggregazioni Onerose: I filtri su strutture nidificate richiedono operatori pesanti ($unwind, $elemMatch, $lookup), con elevato consumo di CPU e limiti di memoria per stage.

^ La Soluzione DRS: Proiezione Relazionale Mirata

• Separazione tra Storage e Ricerca:
  • Documento Completo: L'albero JSON nativo risiede direttamente sul filesystem, sfruttando la cache delle pagine di memoria del sistema operativo a costo computazionale zero.
  • Proiezioni SQL Compatte: Operazioni dedicate estraggono espressioni XPath/JSONPath, nodi foglia o campi calcolati inserendoli in tabelle relazionali snelle e tipizzate (MariaDB o PostgreSQL).
• La Potenza delle JOIN Relazionali: Le ricerche complesse avvengono tramite query SQL ultra-veloci (con JOIN, WHERE, ORDER BY e paginazione nativa) che restituiscono esclusivamente gli ID dei documenti pertinenti (doc_id).
• Recupero Istantaneo: I documenti JSON completi vengono caricati tramite accesso puntuale O(1) su chiave (drs.get(id)).

^ 3. Transazionalità Atomica Unificata e Rollback

Coordinare scritture su disco e database relazionali richiede solitamente pesanti transazioni distribuite (2PC/XA).

• Pipeline Transazionale Unificata: Le operazioni accumulano le modifiche tramite drs.set() (filesystem) e drs.sql() / drs.pgInsert() (database).
• Commit Tutto-o-Niente: La chiamata drs.commit() applica in modo coordinato e atomico sia i file JSON pendenti che le transazioni SQL.
• Rollback Automatico: Qualsiasi errore (violazione di vincoli SQL, eccezioni nel codice o errori di validazione) scatena il rollback immediato delle modifiche su DB e l'annullamento dei file pendenti.
• Dry Run Nativo: Supporto integrato alla simulazione sicura (dry_run: true): l'operazione viene eseguita per intero ma le modifiche vengono annullate al termine, restituendo il payload di risposta reale.

^ 4. Esperienza di Sviluppo ad Alto Rendimento (Zero-Friction)

• Minima curva di apprendimento: non c'è nessun linguaggio di query proprietario. Si usano JavaScript e/o TypeScript insieme a SQL.
• Hot-Reloading a Zero Downtime: Grazie ad HotPluggableDir, qualsiasi modifica a file .ts o .mjs ha effetto immediato alla successiva richiesta REST senza riavviare il processo server.
• Supporto Nativo TypeScript a Zero Configurazione: Sfrutta il Type Stripping nativo di Node.js (v22/v23+), eliminando compilatori esterni (tsc), bundler o loader aggiuntivi (ts-node, tsx).
• Middleware Gerarchico a Cascata (autoexec): File autoexec.ts / autoexec.mjs eseguiti in sequenza a livello Dataset, Schema ed Entity per condividere helper, normalizzare contesti o implementare guardie di sicurezza precoci.
• Supporto Trasparente Duale JSON & XML: Deserializzazione e serializzazione automatica di payload JSON e XML sia in ingresso (POST body) che in uscita (risposte REST).

^ Matrice Comparativa delle Funzionalità

^ Sintesi

Data RESTorage unisce la flessibilità dei documenti JSON non strutturati con la velocità e la precisione di ricerca dei database relazionali.
Eliminando l'ottimizzatore di query, separando la conservazione del dato dalla proiezione degli indici ed eseguendo TypeScript/JavaScript nativo direttamente sul percorso REST, DRS offre prevedibilità prestazionale assoluta, consumi infrastrutturali minimi e massima velocità di rilascio.