ORMA: Orm per Google Apps Script

Se usi Google Apps Script sarai sicuramente stanco come me di ottenere i dati dai fogli di Google sottoforma di array multidimensionali, eseguire infiniti cicli per identificare la riga in cui l'elemento è inserito per modificarlo senza rischiare di compromettere i valori di altre righe.

Per questo motivo insieme a Sintropia ho realizzato ORMA un orm per Google Apps Script che ha l'obiettivo di essere semplice ed immediato.

Prima di iniziare

Ci sono alcuni punti fondamentali da conoscere prima di capire se Orma può fare al caso tuo, vediamoli subito

• Orma sfrutta i fogli di Google come se fossero dei database relazionali e dunque è fondamentale che la riga 1 sia usata come header.
• Per funzionare correttamente Orma necessita che nell'header di tutti i database collegati sia presente una colonna id
• Per agevolare il lavoro degli sviluppatori Orma non crea delle classi proprie, ma sfrutta le classi Spreadsheet & Sheet potenziandole aggiungendo i metodi necessari al funzionamento della libreria.

Dunque se utilizzi Google Sheets come database e utilizzi Google Apps Script per creare, modificare ed eliminare i dati, Orma è lo strumento che fa per te.

‍

Come si usa Orma

La documentazione completa è disponibile a questo link, qui di seguito vedremo solamente alcuni dei passi fondamentali per utilizzare la libreria in Google Apps Script.

‍

Installazione

Accedi al file Google Apps Script in cui vuoi installare Orma ed inserisci il seguente Script Id come nuova libreria.

  1CA-kvfiZjY2Ex2C84hL46Vn2F8GijPbfSy9J3vZQUzzbal5ExhQyG0Z7

‍

Come ottenere i dati con Orma

Qui di seguito ci sono solo alcuni dei metodi disponibili per l'ottenimento dei dati dai tuoi fogli di Google. Per visionare tutti gli altri metodi consulta la documentazione disponibile qui.

//Collegarsi al File Spreadsheet
const ssId = "your_spreadsheet_id";
const db = ORMA.openDbById(ssId);

//Ottenere gli Sheets disponibili
const tables = db._getTables();
const {users} = tables;

//Ottenere tutti i record del foglio
const allUsers = users._all();

//Ottenere un record cercandolo per id
const userById = users._find(1);

//Ottenere un record cercandolo secondo la corrispondenza del valore di una colonna
const firstUserBy = users._firstBy("name","Matteo");

//Ottenere un record secondo la corrispondenza di una query 
const firstUserByQuery = users._firstByQuery(`{}.email !== "matteo@sintropia.io"`)

‍

In che formato ottieni i dati?

Invece di ottenere i dati in un array bidimensionale come solitamente Google Apps Script li restituisce, Orma ci semplifica nettamente la vita permettendoci anche di scrivere un codice più pulito e ci restituisce i valori sotto forma di oggetto.

Per esempio: questo sarebbe l'output della variabile userById inizializzata nel riquadro qui sopra:

{
  id: 1, 
  name: Matteo, 
  password: 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5, 
  email: matteo@sintropia.io, 
  _delete: function () { [native code] }, 
  _save: function () { [native code] }
 }

Come avrai notato oltre ai dati presenti nel database l'oggetto contiene funzioni necessarie al modificare i dati, e ad eliminarli. Nei paragrafi successivi vedremo come utilizzarle.

‍

Come modificare i dati con Orma

Orma prevede una sintassi moderna che è ormai lo standard dei principali ORM di tutto il mondo, con però le limitazioni imposte da Google Apps Script. Qui di seguito vedremo un esempio di quanto è semplice ed intuitivo modificare dei dati a Database.

//Ottengo il record che voglio modificare
const userToEdit = users._find(1);

//Effettuo le modifiche necessarie
userToEdit.name = "Luca";

//Diffondo le modifiche a database
userToEdit._save();

Per effettuare modifiche in bulk consulta la documentazione ufficiale a questo link.

‍

Come eliminare i dati con Orma

Eliminare i dati in Orma è semplicissimo, come vedrai nell'esempio qui sotto basterà ottenere il record o i record da eliminare e basterà invocare la funzione necessaria.

//Ottego il record da eliminare
const user = users._find(1);

//Procedo con l'eliminazione
user._delete(); 

Per eliminare elementi in bulk consulta la documentazione ufficiale a questo link.

‍

Come Creare nuovi record con Orma

Ovviamente manipolando i dati sotto forma di oggetti, Orma prevede che anche l'inserimento dei dati sia fatto sotto forma di oggetti. Ecco un esempio su come inserire a Database dei nuovi record.

const newUser = users._create(
    {
        id: users._id(), //Questa funzione genera un id incrementale
        name: "Matteo",
        email: "matteo@sintropia.io",
        password: ENDO.hash("superPassword1!") //Questa funzione cripterà la password prima di salvarla.
    }
)

Per creare elementi in bulk consulta la documentazione ufficiale a questo link.

‍

Perché usare Orma

Se non sei ancora convinto di testare Orma nei tuoi progetti, ti lascio i motivi che ci hanno spinti a sviluppare Orma e perché la utilizzo quotidianamente con i miei clienti.

• La posizione delle colonne diventerà ininfluente, potrai riorganizzarla come vuoi.
• Abbandona gli array bidimensionali in Google Apps Script.
• Scriverai il 50% di righe di codice in meno.
• Il codice sarà più leggibile.
• Previeni errori di alcun tipo durante le operazioni Crud.
• Segue gli standard più moderni di sviluppo.
• Si aggiornerà con nuove implementazioni.
• È gratuita ed openSource.

‍

Concludendo

Sarei davvero felice di ricevere un qualsiasi feedback sull'uso della libreria. Per qualsiasi idea, consiglio o riscontro, scrivimi pure a matteo@sintropia.io