@noeva/etl-core 1.0.0-next.4 → 1.0.0-next.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +2 -1
  2. package/dist/chunk-BVUOUBLW.js +1 -0
  3. package/dist/chunk-CRR3Q2C7.js +2 -0
  4. package/dist/chunk-J3PBMWSP.js +2 -0
  5. package/dist/{chunk-KMUNED7K.js → chunk-LJ7DVP5F.js} +1 -1
  6. package/dist/{chunk-ZBKP2UOF.js → chunk-P6B2KLNJ.js} +2 -2
  7. package/dist/chunk-PKBSETMV.js +2 -0
  8. package/dist/chunk-QPJC4GWR.js +1 -0
  9. package/dist/chunk-RCRMQPFH.js +5 -0
  10. package/dist/chunk-RS5SGDUU.js +1 -0
  11. package/dist/chunk-RWPHH4E2.js +1 -0
  12. package/dist/chunk-SRFFKE5W.js +6 -0
  13. package/dist/chunk-WVODQB6Z.js +1 -0
  14. package/dist/chunk-XZMCC6VQ.js +1 -0
  15. package/dist/chunk-ZCYGHS7P.js +2 -0
  16. package/dist/cli.js +2 -2
  17. package/dist/connector-kit.d.ts +4 -2
  18. package/dist/connector-kit.js +1 -1
  19. package/dist/connectors/file.js +1 -1
  20. package/dist/connectors/http.js +1 -1
  21. package/dist/connectors/imap.js +1 -1
  22. package/dist/connectors/jira.js +2 -2
  23. package/dist/connectors/mail.js +1 -1
  24. package/dist/connectors/noeva.js +1 -1
  25. package/dist/connectors/oauth.js +1 -1
  26. package/dist/connectors/postgres.js +1 -1
  27. package/dist/connectors/sendgrid.js +1 -1
  28. package/dist/connectors/smtp.js +1 -1
  29. package/dist/connectors/sqlserver.js +1 -1
  30. package/dist/connectors/zoho.d.ts +304 -0
  31. package/dist/connectors/zoho.js +2 -0
  32. package/dist/etl.config.js +2 -2
  33. package/dist/guida/404.html +2 -2
  34. package/dist/guida/GUIDA_SVILUPPO.html +6 -6
  35. package/dist/guida/TECHNICAL_OVERVIEW.html +5 -5
  36. package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.js → GUIDA_SVILUPPO.md.CrN52ZDN.js} +1 -1
  37. package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.js} +1 -1
  38. package/dist/guida/assets/{app.CzIZwOrR.js → app.BrI3mcoI.js} +1 -1
  39. package/dist/guida/assets/chunks/@localSearchIndexroot.DjrQYH6x.js +1 -0
  40. package/dist/guida/assets/chunks/{VPLocalSearchBox.Cv9o56BQ.js → VPLocalSearchBox.BlKLVNlB.js} +1 -1
  41. package/dist/guida/assets/chunks/{theme.CsUxYN72.js → theme.Cuah39Zj.js} +2 -2
  42. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +1 -0
  43. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +1 -0
  44. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.js +7 -0
  45. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.lean.js +1 -0
  46. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.js +17 -0
  47. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.lean.js +1 -0
  48. package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.js → conventions_node-descriptor.md.MQaGlm8a.js} +1 -1
  49. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.js → nodes_source.md.DP2i3GFv.js} +3 -3
  50. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.lean.js → nodes_source.md.DP2i3GFv.lean.js} +1 -1
  51. package/dist/guida/connectors/README.html +5 -5
  52. package/dist/guida/connectors/file.html +4 -4
  53. package/dist/guida/connectors/http.html +4 -4
  54. package/dist/guida/connectors/imap.html +4 -4
  55. package/dist/guida/connectors/jira.html +4 -4
  56. package/dist/guida/connectors/noeva.html +5 -5
  57. package/dist/guida/connectors/oauth.html +6 -6
  58. package/dist/guida/connectors/postgres.html +5 -5
  59. package/dist/guida/connectors/process.html +4 -4
  60. package/dist/guida/connectors/sendgrid.html +4 -4
  61. package/dist/guida/connectors/smtp.html +4 -4
  62. package/dist/guida/connectors/sqlserver.html +5 -5
  63. package/dist/guida/connectors/zoho.html +43 -0
  64. package/dist/guida/conventions/node-columns.html +4 -4
  65. package/dist/guida/conventions/node-descriptor.html +6 -6
  66. package/dist/guida/conventions/run-report.html +4 -4
  67. package/dist/guida/conventions/run-trace.html +4 -4
  68. package/dist/guida/conventions/variabili-del-core.html +4 -4
  69. package/dist/guida/conventions/versioni-di-pipeline.html +4 -4
  70. package/dist/guida/guide/claude-code/index.html +4 -4
  71. package/dist/guida/guide/claude-code/prompt.html +5 -5
  72. package/dist/guida/guide/claude-code/strumenti.html +4 -4
  73. package/dist/guida/guide/grafo.html +4 -4
  74. package/dist/guida/guide/usare/app-desktop.html +4 -4
  75. package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
  76. package/dist/guida/guide/usare/index.html +4 -4
  77. package/dist/guida/hashmap.json +1 -1
  78. package/dist/guida/index.html +4 -4
  79. package/dist/guida/nodes/README.html +4 -4
  80. package/dist/guida/nodes/action.html +4 -4
  81. package/dist/guida/nodes/ai.html +4 -4
  82. package/dist/guida/nodes/join.html +4 -4
  83. package/dist/guida/nodes/lookup.html +4 -4
  84. package/dist/guida/nodes/pipeline.html +4 -4
  85. package/dist/guida/nodes/route.html +4 -4
  86. package/dist/guida/nodes/sink.html +4 -4
  87. package/dist/guida/nodes/source.html +6 -6
  88. package/dist/guida/nodes/task.html +4 -4
  89. package/dist/guida/nodes/transform.html +4 -4
  90. package/dist/guida/nodes/try-catch.html +4 -4
  91. package/dist/guida/nodes/union.html +4 -4
  92. package/dist/guida/pagine.json +1 -0
  93. package/dist/guida/pipelines/README.html +5 -5
  94. package/dist/guida/pipelines/crm-leads-sync.html +4 -4
  95. package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
  96. package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
  97. package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
  98. package/dist/guida/pipelines/test-posta.html +4 -4
  99. package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
  100. package/dist/guida/runbooks/deploy-ecr.html +4 -4
  101. package/dist/guida/runbooks/deployment.html +4 -4
  102. package/dist/guida/runbooks/etl-worker.html +4 -4
  103. package/dist/guida/runbooks/graph-server.html +4 -4
  104. package/dist/guida/runbooks/mask-key.html +4 -4
  105. package/dist/guida/runbooks/oauth-google-posta.html +4 -4
  106. package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
  107. package/dist/guida/runbooks/scd2-rehash.html +4 -4
  108. package/dist/guida/runbooks/sql-task-truncate-swap.html +4 -4
  109. package/dist/guida/runbooks/stato-incrementale.html +4 -4
  110. package/dist/guida/sub-pipelines/README.html +4 -4
  111. package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
  112. package/dist/index.js +1 -1
  113. package/dist/pipelines.js +1 -1
  114. package/dist/testing.js +1 -1
  115. package/kit/skills/etl-graph/references/wiring.md +4 -3
  116. package/kit/skills/new-connector/SKILL.md +1 -1
  117. package/package.json +8 -3
  118. package/dist/chunk-BFW7HTF6.js +0 -2
  119. package/dist/chunk-BPRH262Y.js +0 -2
  120. package/dist/chunk-DPWGI266.js +0 -1
  121. package/dist/chunk-H75NY6Z4.js +0 -1
  122. package/dist/chunk-HMED2UDJ.js +0 -2
  123. package/dist/chunk-MOHJWOCB.js +0 -1
  124. package/dist/chunk-MXSKD3Z4.js +0 -2
  125. package/dist/chunk-PGJWGJEB.js +0 -5
  126. package/dist/chunk-R53642SH.js +0 -1
  127. package/dist/chunk-RU6CZIDB.js +0 -1
  128. package/dist/chunk-UN3BPCPA.js +0 -1
  129. package/dist/chunk-XFHTODDW.js +0 -6
  130. package/dist/guida/assets/chunks/@localSearchIndexroot.08YFQ5n8.js +0 -1
  131. package/dist/guida/assets/connectors_README.md.ChyXSf73.js +0 -1
  132. package/dist/guida/assets/connectors_README.md.ChyXSf73.lean.js +0 -1
  133. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.js +0 -7
  134. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.lean.js +0 -1
  135. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.lean.js → GUIDA_SVILUPPO.md.CrN52ZDN.lean.js} +0 -0
  136. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.lean.js} +0 -0
  137. /package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.lean.js → conventions_node-descriptor.md.MQaGlm8a.lean.js} +0 -0
@@ -1,4 +1,4 @@
1
- import{_ as t,C as r,o as n,c as a,a5 as o,E as s}from"./chunks/framework.qdetmeNX.js";const v=JSON.parse('{"title":"noeva-etl — Technical Overview","description":"","frontmatter":{},"headers":[],"relativePath":"TECHNICAL_OVERVIEW.md","filePath":"TECHNICAL_OVERVIEW.md"}'),c={name:"TECHNICAL_OVERVIEW.md"};function d(l,e,p,u,g,h){const i=r("MermaidDiagram");return n(),a("div",null,[e[0]||(e[0]=o('<h1 id="noeva-etl-—-technical-overview" tabindex="-1">noeva-etl — Technical Overview <a class="header-anchor" href="#noeva-etl-—-technical-overview" aria-label="Permalink to &quot;noeva-etl — Technical Overview&quot;">​</a></h1><blockquote><p>Documento condivisibile. Spiega <strong>cos&#39;è</strong>, <strong>per cosa è pensato</strong>, <strong>cosa può fare</strong>, <strong>come si espande</strong> e <strong>qual è la direzione</strong> del prodotto.</p></blockquote><hr><h2 id="_1-in-una-frase" tabindex="-1">1. In una frase <a class="header-anchor" href="#_1-in-una-frase" aria-label="Permalink to &quot;1. In una frase&quot;">​</a></h2><p><strong>noeva-etl</strong> è una <strong>piattaforma BI/ETL code-first in TypeScript</strong>: si costruiscono pipeline di integrazione dati (estrazione → trasformazione → caricamento) come <strong>software versionato, testato e documentato</strong>, non come job grafici opachi. Il nucleo di esecuzione di ogni pipeline è <strong>semplice, stateless e portabile</strong>: esegue una pipeline e restituisce un risultato completo (report di run), senza possedere database né stato proprio.</p><p>Il servizio si invoca in tre modi (vedi §5): <strong>batch</strong> (<code>etl run</code>, un container = una esecuzione, esito su stdout), <strong>daemon</strong> (<code>etl worker</code>, poller sulla tabella <code>processes</code> di Noeva, per l&#39;integrazione con l&#39;orchestrazione job del prodotto) e <strong>server + daemon</strong> (<code>etl serve</code>, il default dell&#39;immagine: espone i grafi e le run all&#39;app desktop <code>noeva-etl-ui</code> e avvia i worker nello stesso processo).</p><h2 id="_2-per-cosa-e-stato-pensato" tabindex="-1">2. Per cosa è stato pensato <a class="header-anchor" href="#_2-per-cosa-e-stato-pensato" aria-label="Permalink to &quot;2. Per cosa è stato pensato&quot;">​</a></h2><p>Sostituire l&#39;approccio &quot;ETL a scatola nera&quot; (es. Talend) con uno <strong>code-first</strong>:</p><ul><li><strong>Versionabile</strong> — ogni pipeline è codice in git, rivedibile in Pull Request.</li><li><strong>Testabile</strong> — connettori, trasformazioni e pipeline hanno test automatici (gate in CI).</li><li><strong>Documentato</strong> — ogni pipeline/decisione ha la sua scheda/ADR, aggiornati nello stesso commit.</li><li><strong>Portabile</strong> — un&#39;unica immagine container gira sull&#39;infra del cliente (Docker locale, ECS proprio o gestito da noi).</li><li><strong>Agnostico</strong> — nessun lock-in: sorgenti e destinazioni sono intercambiabili; il servizio non impone un DB o un cloud.</li></ul><p>Target d&#39;uso: integrazioni dati ricorrenti e affidabili (sincronizzazioni, fatti per la BI, normalizzazioni cross-database) dove <strong>correttezza, ripetibilità e tracciabilità</strong> contano.</p><h2 id="_3-cosa-puo-fare-oggi" tabindex="-1">3. Cosa può fare oggi <a class="header-anchor" href="#_3-cosa-puo-fare-oggi" aria-label="Permalink to &quot;3. Cosa può fare oggi&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Capacità</th><th>Dettaglio</th></tr></thead><tbody><tr><td><strong>Primitive componibili</strong></td><td><code>Source&lt;T&gt;</code> (estrazione), <code>Transform&lt;I,O&gt;</code> (trasformazione), <code>Sink&lt;T&gt;</code> (caricamento), <code>GraphPipeline</code> (DSL a grafo <code>graph()...build()</code>)</td></tr><tr><td><strong>Nodi del grafo</strong></td><td><code>source</code>, <code>transform</code>, <strong><code>lookup</code></strong> (lettura a metà grafo da un DB o da un&#39;API REST), <strong><code>ai</code></strong> (domanda a un modello per record), <strong><code>action</code></strong> (scrittura per record con un record in uscita), <strong><code>route</code></strong> (smistamento esclusivo su porte), <code>join</code> (fan-in a chiave), <strong><code>union</code></strong> (fan-in di flussi con la stessa forma), <code>try-catch</code> (ramo di gestione errori), <code>sink</code>, <strong><code>task</code></strong> (operazione senza record, prima o dopo il caricamento, ordinata dagli edge di controllo <code>after</code>)</td></tr><tr><td><strong>Streaming</strong></td><td>I connettori lavorano su <code>AsyncIterable</code>: dataset grandi senza caricarli in memoria</td></tr><tr><td><strong>Contratti dati (Zod)</strong></td><td>Validazione di schema su input e output di ogni pipeline (<code>validate</code>)</td></tr><tr><td><strong>Trasformazioni</strong></td><td><code>map</code>, <code>filter</code>, mappatura dichiarativa di colonne <code>mapColumns</code> (select, rename, cast, colonne calcolate, con lineage di colonna), espansione 1:N (<code>flatMapTransform</code>, <code>explode</code>), aggregazione stateful riusabile <code>groupBy</code> (init/reduce/finalize), deduplica <code>dedup</code>, passaggio fra formato largo e lungo <code>unpivot</code>/<code>pivot</code>, ordinamento stabile <code>sort</code>, lotti di dimensione fissa <code>chunk</code>, decodifica e codifica di file in mezzo al grafo <code>parse</code>/<code>serialize</code>, hash di riga <code>hashRow</code> e chiave surrogata <code>surrogateKey</code>, mascheramento e pseudonimizzazione dei dati personali <code>mask</code>, profilo delle colonne nel report del nodo <code>profile</code>, controlli sul dataset <code>assert</code></td></tr><tr><td><strong>Gestione errori</strong></td><td><strong>dead-letter</strong> per nodo (record invalidi instradati altrove, la run prosegue), ramo <strong>catch</strong> di un nodo <code>try-catch</code>, o <strong>fail-fast</strong> esplicito, che al primo errore fatale annulla anche i rami indipendenti — mai scarti silenziosi</td></tr><tr><td><strong>Idempotenza</strong></td><td>Sink con upsert/MERGE su chiave naturale: rieseguire non duplica</td></tr><tr><td><strong>Connettori reali</strong></td><td><strong>PostgreSQL</strong> (cursor streaming + upsert <code>ON CONFLICT</code> o SCD2 + lookup + task SQL), <strong>SQL Server</strong> (streaming + <code>MERGE</code> o SCD2 + lookup + task SQL), <strong>file</strong> (filesystem/S3/SFTP/FTP × CSV/JSON/XML/XLSX/Parquet), <strong>Noeva</strong> (file e cartelle dei workspace + upload con elaborazione AI come <code>action</code> + lookup su stato e testo estratto), <strong>HTTP</strong> (lookup e action su API REST, <code>httpLookup</code> e <code>httpAction</code>), <strong>Jira Cloud</strong> (<code>jiraIssues</code>: le issue di una JQL su API REST v3, in colonne normalizzate, e <code>jiraIssueLookup</code> per chiave; changelog, commenti e worklog completi come lista; <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> per ID esterno, <code>jiraAddComment</code> e <code>jiraAddWorklog</code> con chiave di deduplica e <code>jiraLinkIssues</code> come <code>action</code>, testo in markdown), <strong>IMAP</strong>, <strong>SMTP</strong> e <strong>SendGrid</strong> (posta in lettura e invio, con OAuth2 dove la casella lo richiede), <strong>processo esterno</strong> (<code>processoEsternoAction</code>: un programma lanciato per record in un nodo <code>action</code>, senza shell)</td></tr><tr><td><strong>Cross-database</strong></td><td>Una pipeline può leggere da un DB e scrivere su un altro (es. PG → SQL Server)</td></tr><tr><td><strong>GraphRunReport</strong></td><td>Risultato auto-descrittivo di ogni run (vedi §6)</td></tr><tr><td><strong>CLI &amp; container</strong></td><td><code>etl list</code> / <code>etl run &lt;pipeline&gt;</code> / <code>etl serve</code> / <code>etl runs list</code> / <code>etl state show</code> / <code>etl versions snapshot</code> (anche <code>--realign</code>) / <code>etl versions check</code> / <code>etl versions rollback</code> / <code>etl env check</code> / <code>etl catalog check</code> / <code>etl docs build</code> / <code>etl ci</code> / <code>etl init</code> / <code>etl agent sync</code> / <code>etl upgrade</code>; immagine Docker</td></tr><tr><td><strong>App desktop</strong></td><td><code>noeva-etl-ui</code> (Tauri): DAG delle pipeline, avvio manuale, storico ed esito delle run, nodo per nodo — mostra, non costruisce</td></tr><tr><td><strong>Worker daemon</strong></td><td><code>etl worker</code> — poller su <code>processes</code> via <code>noeva-server-api</code> (claim/progress HTTP, mai Supabase diretto), dispatch verso il catalogo di <code>etl.config.ts</code>; una istanza serve N workspace</td></tr></tbody></table><p><strong>Esempi inclusi</strong>: le pipeline della sezione «Esempi» di questa guida, come <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> (join a chiave, fan-out, try/catch) e <a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> (copia fra due istanze Postgres).</p><h2 id="_4-come-funziona-architettura" tabindex="-1">4. Come funziona (architettura) <a class="header-anchor" href="#_4-come-funziona-architettura" aria-label="Permalink to &quot;4. Come funziona (architettura)&quot;">​</a></h2><p>Ogni pipeline è un <strong>grafo</strong> di nodi (DAG), costruito in codice col DSL <code>graph()…build()</code>:</p>',15)),s(i,{code:"flowchart%20LR%0A%20%20ordini%5B%22source%3Cbr%2F%3Eordini%22%5D%20--%3E%20valida%5B%22transform%3Cbr%2F%3Evalidate%20(contratto)%22%5D%0A%20%20clienti%5B%22source%3Cbr%2F%3Eclienti%22%5D%20--%3E%20join%5B%22join%3Cbr%2F%3E(a%20chiave)%22%5D%0A%20%20valida%20-.record%20invalido.-%3E%20scarti%5B%22dead-letter%22%5D%0A%20%20valida%20--%3E%20join%0A%20%20join%20--%3E%20lookup%5B%22lookup%3Cbr%2F%3E(lettura%20DB%20o%20API)%22%5D%0A%20%20lookup%20--%3E%20guard%5B%22try-catch%22%5D%0A%20%20guard%20--%3E%20dwh%5B%22sink%3Cbr%2F%3EDWH%22%5D%0A%20%20guard%20--%3E%20file%5B%22sink%3Cbr%2F%3Efile%22%5D%0A%20%20guard%20-.catch.-%3E%20errori%5B%22ramo%20errori%22%5D%0A"}),e[1]||(e[1]=o(`<ul><li><strong>Core</strong> (<code>src/core</code>) — primitive + runner; <strong>non contiene logica di dominio</strong>.</li><li><strong>Dependency Injection</strong> — la <em>definizione</em> della pipeline è agnostica: sorgente e sink concreti si iniettano all&#39;avvio. Per questo lo stesso codice gira su DB diversi e si testa con connettori in-memory.</li><li><strong>Streaming pull-based</strong> — i record scorrono dai source ai sink senza essere caricati tutti in memoria; è il ritmo di scrittura a regolare quello di lettura.</li><li><strong>Tre percorsi per un record che fallisce</strong>: <em>dead-letter</em> sul nodo (il record va altrove, la run prosegue), ramo <em>catch</em> di un nodo <code>try-catch</code> (gli errori di un intero tratto del grafo finiscono su nodi di gestione dedicati), <em>fail-fast</em> (la run si ferma — obbligatorio per le aggregazioni stateful).</li><li><strong>Osservabilità</strong> — logger JSON strutturato + metriche; ogni run produce un <code>GraphRunReport</code> con i conteggi di ogni nodo.</li></ul><p>Stack: TypeScript ESM strict, Node ≥ 20, <code>pnpm</code>, <code>tsup</code>, <code>vitest</code>, ESLint/Prettier, Zod. Dipendenze runtime: i driver dei database (<code>pg</code>, <code>mssql</code>), le librerie per storage e formati dei file (AWS SDK, SFTP, FTP, CSV, XLSX, XML, Parquet), <code>express</code> per il server locale di <code>etl serve</code>. Nessuna dipendenza Supabase: il claim/report sulla tabella <code>processes</code> passa da <code>noeva-server-api</code> via HTTP (<code>fetch</code> nativo).</p><h2 id="_5-come-si-usa-e-si-distribuisce" tabindex="-1">5. Come si usa e si distribuisce <a class="header-anchor" href="#_5-come-si-usa-e-si-distribuisce" aria-label="Permalink to &quot;5. Come si usa e si distribuisce&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># in un repo cliente, in sviluppo</span></span>
1
+ import{_ as t,C as r,o as n,c as a,a5 as o,E as s}from"./chunks/framework.qdetmeNX.js";const v=JSON.parse('{"title":"noeva-etl — Technical Overview","description":"","frontmatter":{},"headers":[],"relativePath":"TECHNICAL_OVERVIEW.md","filePath":"TECHNICAL_OVERVIEW.md"}'),c={name:"TECHNICAL_OVERVIEW.md"};function d(l,e,p,u,g,h){const i=r("MermaidDiagram");return n(),a("div",null,[e[0]||(e[0]=o('<h1 id="noeva-etl-—-technical-overview" tabindex="-1">noeva-etl — Technical Overview <a class="header-anchor" href="#noeva-etl-—-technical-overview" aria-label="Permalink to &quot;noeva-etl — Technical Overview&quot;">​</a></h1><blockquote><p>Documento condivisibile. Spiega <strong>cos&#39;è</strong>, <strong>per cosa è pensato</strong>, <strong>cosa può fare</strong>, <strong>come si espande</strong> e <strong>qual è la direzione</strong> del prodotto.</p></blockquote><hr><h2 id="_1-in-una-frase" tabindex="-1">1. In una frase <a class="header-anchor" href="#_1-in-una-frase" aria-label="Permalink to &quot;1. In una frase&quot;">​</a></h2><p><strong>noeva-etl</strong> è una <strong>piattaforma BI/ETL code-first in TypeScript</strong>: si costruiscono pipeline di integrazione dati (estrazione → trasformazione → caricamento) come <strong>software versionato, testato e documentato</strong>, non come job grafici opachi. Il nucleo di esecuzione di ogni pipeline è <strong>semplice, stateless e portabile</strong>: esegue una pipeline e restituisce un risultato completo (report di run), senza possedere database né stato proprio.</p><p>Il servizio si invoca in tre modi (vedi §5): <strong>batch</strong> (<code>etl run</code>, un container = una esecuzione, esito su stdout), <strong>daemon</strong> (<code>etl worker</code>, poller sulla tabella <code>processes</code> di Noeva, per l&#39;integrazione con l&#39;orchestrazione job del prodotto) e <strong>server + daemon</strong> (<code>etl serve</code>, il default dell&#39;immagine: espone i grafi e le run all&#39;app desktop <code>noeva-etl-ui</code> e avvia i worker nello stesso processo).</p><h2 id="_2-per-cosa-e-stato-pensato" tabindex="-1">2. Per cosa è stato pensato <a class="header-anchor" href="#_2-per-cosa-e-stato-pensato" aria-label="Permalink to &quot;2. Per cosa è stato pensato&quot;">​</a></h2><p>Sostituire l&#39;approccio &quot;ETL a scatola nera&quot; (es. Talend) con uno <strong>code-first</strong>:</p><ul><li><strong>Versionabile</strong> — ogni pipeline è codice in git, rivedibile in Pull Request.</li><li><strong>Testabile</strong> — connettori, trasformazioni e pipeline hanno test automatici (gate in CI).</li><li><strong>Documentato</strong> — ogni pipeline/decisione ha la sua scheda/ADR, aggiornati nello stesso commit.</li><li><strong>Portabile</strong> — un&#39;unica immagine container gira sull&#39;infra del cliente (Docker locale, ECS proprio o gestito da noi).</li><li><strong>Agnostico</strong> — nessun lock-in: sorgenti e destinazioni sono intercambiabili; il servizio non impone un DB o un cloud.</li></ul><p>Target d&#39;uso: integrazioni dati ricorrenti e affidabili (sincronizzazioni, fatti per la BI, normalizzazioni cross-database) dove <strong>correttezza, ripetibilità e tracciabilità</strong> contano.</p><h2 id="_3-cosa-puo-fare-oggi" tabindex="-1">3. Cosa può fare oggi <a class="header-anchor" href="#_3-cosa-puo-fare-oggi" aria-label="Permalink to &quot;3. Cosa può fare oggi&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Capacità</th><th>Dettaglio</th></tr></thead><tbody><tr><td><strong>Primitive componibili</strong></td><td><code>Source&lt;T&gt;</code> (estrazione), <code>Transform&lt;I,O&gt;</code> (trasformazione), <code>Sink&lt;T&gt;</code> (caricamento), <code>GraphPipeline</code> (DSL a grafo <code>graph()...build()</code>)</td></tr><tr><td><strong>Nodi del grafo</strong></td><td><code>source</code>, <code>transform</code>, <strong><code>lookup</code></strong> (lettura a metà grafo da un DB o da un&#39;API REST), <strong><code>ai</code></strong> (domanda a un modello per record), <strong><code>action</code></strong> (scrittura per record con un record in uscita), <strong><code>route</code></strong> (smistamento esclusivo su porte), <code>join</code> (fan-in a chiave), <strong><code>union</code></strong> (fan-in di flussi con la stessa forma), <code>try-catch</code> (ramo di gestione errori), <code>sink</code>, <strong><code>task</code></strong> (operazione senza record, prima o dopo il caricamento, ordinata dagli edge di controllo <code>after</code>)</td></tr><tr><td><strong>Streaming</strong></td><td>I connettori lavorano su <code>AsyncIterable</code>: dataset grandi senza caricarli in memoria</td></tr><tr><td><strong>Contratti dati (Zod)</strong></td><td>Validazione di schema su input e output di ogni pipeline (<code>validate</code>)</td></tr><tr><td><strong>Trasformazioni</strong></td><td><code>map</code>, <code>filter</code>, mappatura dichiarativa di colonne <code>mapColumns</code> (select, rename, cast, colonne calcolate, con lineage di colonna), espansione 1:N (<code>flatMapTransform</code>, <code>explode</code>), aggregazione stateful riusabile <code>groupBy</code> (init/reduce/finalize), deduplica <code>dedup</code>, passaggio fra formato largo e lungo <code>unpivot</code>/<code>pivot</code>, ordinamento stabile <code>sort</code>, lotti di dimensione fissa <code>chunk</code>, decodifica e codifica di file in mezzo al grafo <code>parse</code>/<code>serialize</code>, hash di riga <code>hashRow</code> e chiave surrogata <code>surrogateKey</code>, mascheramento e pseudonimizzazione dei dati personali <code>mask</code>, profilo delle colonne nel report del nodo <code>profile</code>, controlli sul dataset <code>assert</code></td></tr><tr><td><strong>Gestione errori</strong></td><td><strong>dead-letter</strong> per nodo (record invalidi instradati altrove, la run prosegue), ramo <strong>catch</strong> di un nodo <code>try-catch</code>, o <strong>fail-fast</strong> esplicito, che al primo errore fatale annulla anche i rami indipendenti — mai scarti silenziosi</td></tr><tr><td><strong>Idempotenza</strong></td><td>Sink con upsert/MERGE su chiave naturale: rieseguire non duplica</td></tr><tr><td><strong>Connettori reali</strong></td><td><strong>PostgreSQL</strong> (cursor streaming + upsert <code>ON CONFLICT</code> o SCD2 + lookup + task SQL), <strong>SQL Server</strong> (streaming + <code>MERGE</code> o SCD2 + lookup + task SQL), <strong>file</strong> (filesystem/S3/SFTP/FTP × CSV/JSON/XML/XLSX/Parquet), <strong>Noeva</strong> (file e cartelle dei workspace + upload con elaborazione AI come <code>action</code> + lookup su stato e testo estratto), <strong>HTTP</strong> (lookup e action su API REST, <code>httpLookup</code> e <code>httpAction</code>), <strong>Jira Cloud</strong> (<code>jiraIssues</code>: le issue di una JQL su API REST v3, in colonne normalizzate, e <code>jiraIssueLookup</code> per chiave; changelog, commenti e worklog completi come lista; <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> per ID esterno, <code>jiraAddComment</code> e <code>jiraAddWorklog</code> con chiave di deduplica e <code>jiraLinkIssues</code> come <code>action</code>, testo in markdown), <strong>Zoho CRM</strong> (<code>zohoCrmRecords</code>: i record di un modulo con i soli campi dichiarati, in ordine di <code>id</code>, con la Records API v8 o, oltre i 100.000 record, con COQL), <strong>IMAP</strong>, <strong>SMTP</strong> e <strong>SendGrid</strong> (posta in lettura e invio, con OAuth2 dove la casella lo richiede), <strong>processo esterno</strong> (<code>processoEsternoAction</code>: un programma lanciato per record in un nodo <code>action</code>, senza shell)</td></tr><tr><td><strong>Cross-database</strong></td><td>Una pipeline può leggere da un DB e scrivere su un altro (es. PG → SQL Server)</td></tr><tr><td><strong>GraphRunReport</strong></td><td>Risultato auto-descrittivo di ogni run (vedi §6)</td></tr><tr><td><strong>CLI &amp; container</strong></td><td><code>etl list</code> / <code>etl run &lt;pipeline&gt;</code> / <code>etl serve</code> / <code>etl runs list</code> / <code>etl state show</code> / <code>etl versions snapshot</code> (anche <code>--realign</code>) / <code>etl versions check</code> / <code>etl versions rollback</code> / <code>etl env check</code> / <code>etl catalog check</code> / <code>etl docs build</code> / <code>etl ci</code> / <code>etl init</code> / <code>etl agent sync</code> / <code>etl upgrade</code>; immagine Docker</td></tr><tr><td><strong>App desktop</strong></td><td><code>noeva-etl-ui</code> (Tauri): DAG delle pipeline, avvio manuale, storico ed esito delle run, nodo per nodo — mostra, non costruisce</td></tr><tr><td><strong>Worker daemon</strong></td><td><code>etl worker</code> — poller su <code>processes</code> via <code>noeva-server-api</code> (claim/progress HTTP, mai Supabase diretto), dispatch verso il catalogo di <code>etl.config.ts</code>; una istanza serve N workspace</td></tr></tbody></table><p><strong>Esempi inclusi</strong>: le pipeline della sezione «Esempi» di questa guida, come <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> (join a chiave, fan-out, try/catch) e <a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> (copia fra due istanze Postgres).</p><h2 id="_4-come-funziona-architettura" tabindex="-1">4. Come funziona (architettura) <a class="header-anchor" href="#_4-come-funziona-architettura" aria-label="Permalink to &quot;4. Come funziona (architettura)&quot;">​</a></h2><p>Ogni pipeline è un <strong>grafo</strong> di nodi (DAG), costruito in codice col DSL <code>graph()…build()</code>:</p>',15)),s(i,{code:"flowchart%20LR%0A%20%20ordini%5B%22source%3Cbr%2F%3Eordini%22%5D%20--%3E%20valida%5B%22transform%3Cbr%2F%3Evalidate%20(contratto)%22%5D%0A%20%20clienti%5B%22source%3Cbr%2F%3Eclienti%22%5D%20--%3E%20join%5B%22join%3Cbr%2F%3E(a%20chiave)%22%5D%0A%20%20valida%20-.record%20invalido.-%3E%20scarti%5B%22dead-letter%22%5D%0A%20%20valida%20--%3E%20join%0A%20%20join%20--%3E%20lookup%5B%22lookup%3Cbr%2F%3E(lettura%20DB%20o%20API)%22%5D%0A%20%20lookup%20--%3E%20guard%5B%22try-catch%22%5D%0A%20%20guard%20--%3E%20dwh%5B%22sink%3Cbr%2F%3EDWH%22%5D%0A%20%20guard%20--%3E%20file%5B%22sink%3Cbr%2F%3Efile%22%5D%0A%20%20guard%20-.catch.-%3E%20errori%5B%22ramo%20errori%22%5D%0A"}),e[1]||(e[1]=o(`<ul><li><strong>Core</strong> (<code>src/core</code>) — primitive + runner; <strong>non contiene logica di dominio</strong>.</li><li><strong>Dependency Injection</strong> — la <em>definizione</em> della pipeline è agnostica: sorgente e sink concreti si iniettano all&#39;avvio. Per questo lo stesso codice gira su DB diversi e si testa con connettori in-memory.</li><li><strong>Streaming pull-based</strong> — i record scorrono dai source ai sink senza essere caricati tutti in memoria; è il ritmo di scrittura a regolare quello di lettura.</li><li><strong>Tre percorsi per un record che fallisce</strong>: <em>dead-letter</em> sul nodo (il record va altrove, la run prosegue), ramo <em>catch</em> di un nodo <code>try-catch</code> (gli errori di un intero tratto del grafo finiscono su nodi di gestione dedicati), <em>fail-fast</em> (la run si ferma — obbligatorio per le aggregazioni stateful).</li><li><strong>Osservabilità</strong> — logger JSON strutturato + metriche; ogni run produce un <code>GraphRunReport</code> con i conteggi di ogni nodo.</li></ul><p>Stack: TypeScript ESM strict, Node ≥ 20, <code>pnpm</code>, <code>tsup</code>, <code>vitest</code>, ESLint/Prettier, Zod. Dipendenze runtime: i driver dei database (<code>pg</code>, <code>mssql</code>), le librerie per storage e formati dei file (AWS SDK, SFTP, FTP, CSV, XLSX, XML, Parquet), <code>express</code> per il server locale di <code>etl serve</code>. Nessuna dipendenza Supabase: il claim/report sulla tabella <code>processes</code> passa da <code>noeva-server-api</code> via HTTP (<code>fetch</code> nativo).</p><h2 id="_5-come-si-usa-e-si-distribuisce" tabindex="-1">5. Come si usa e si distribuisce <a class="header-anchor" href="#_5-come-si-usa-e-si-distribuisce" aria-label="Permalink to &quot;5. Come si usa e si distribuisce&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># in un repo cliente, in sviluppo</span></span>
2
2
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</span></span>
3
3
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
4
4
  <span class="line"></span>
@@ -1 +1 @@
1
- import{t as p}from"./chunks/theme.CsUxYN72.js";import{R as s,a8 as i,a9 as u,aa as c,ab as l,ac as f,ad as d,ae as m,af as h,ag as g,ah as A,d as v,u as y,v as C,s as P,ai as b,aj as w,ak as R,a7 as E}from"./chunks/framework.qdetmeNX.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
1
+ import{t as p}from"./chunks/theme.Cuah39Zj.js";import{R as s,a8 as i,a9 as u,aa as c,ab as l,ac as f,ad as d,ae as m,af as h,ag as g,ah as A,d as v,u as y,v as C,s as P,ai as b,aj as w,ak as R,a7 as E}from"./chunks/framework.qdetmeNX.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=D(),a=j();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function j(){return A(S)}function D(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};