@noeva/etl-core 1.0.1 → 1.1.0
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.
- package/CHANGELOG.md +128 -0
- package/README.md +6 -11
- package/dist/{ai-BoTwcmUg.d.ts → ai-DyDIf-hQ.d.ts} +1 -1
- package/dist/{ambiente-della-pipeline-BoymQ6uN.d.ts → ambiente-della-pipeline-BhWsyLUR.d.ts} +2 -2
- package/dist/chunk-47NVGHUY.js +2 -0
- package/dist/chunk-5OE6F2MK.js +2 -0
- package/dist/{chunk-NZR6TZ42.js → chunk-5XVANFXO.js} +1 -1
- package/dist/chunk-672L5BGQ.js +1 -0
- package/dist/{chunk-4NPSBPBY.js → chunk-6QVYBDIS.js} +1 -1
- package/dist/{chunk-PE2QKU34.js → chunk-CEAMQIRO.js} +1 -1
- package/dist/chunk-DHQ3YOPX.js +5 -0
- package/dist/chunk-FBSNZG34.js +1 -0
- package/dist/{chunk-J3PBMWSP.js → chunk-GZWYRO3V.js} +1 -1
- package/dist/chunk-IODXIHU2.js +1 -0
- package/dist/{chunk-P6B2KLNJ.js → chunk-KEFIGSRS.js} +2 -2
- package/dist/chunk-KGWA46Y6.js +2 -0
- package/dist/chunk-L25W2QNS.js +1 -0
- package/dist/{chunk-JLPK6MMQ.js → chunk-OK3XRTGA.js} +1 -1
- package/dist/chunk-UHGHK6NP.js +1 -0
- package/dist/chunk-VL7DZWWO.js +2 -0
- package/dist/chunk-VVXT66DC.js +1 -0
- package/dist/chunk-ZKDCUSM2.js +6 -0
- package/dist/cli.js +2 -2
- package/dist/{client-DYA3wIyb.d.ts → client-BC_mLuT2.d.ts} +2 -2
- package/dist/config-BSdGSRPG.d.ts +37 -0
- package/dist/{config-BSUwK4p_.d.ts → config-DMafsY4H.d.ts} +3 -3
- package/dist/connector-kit.d.ts +14 -9
- package/dist/connector-kit.js +1 -1
- package/dist/connectors/excel.d.ts +391 -0
- package/dist/connectors/excel.js +10 -0
- package/dist/connectors/file.d.ts +12 -5
- package/dist/connectors/file.js +1 -1
- package/dist/connectors/http.d.ts +7 -7
- package/dist/connectors/http.js +1 -1
- package/dist/connectors/imap.d.ts +6 -6
- package/dist/connectors/imap.js +1 -1
- package/dist/connectors/jira.d.ts +6 -6
- package/dist/connectors/jira.js +2 -2
- package/dist/connectors/mail.d.ts +7 -7
- package/dist/connectors/mail.js +1 -1
- package/dist/connectors/mysql.d.ts +238 -0
- package/dist/connectors/mysql.js +2 -0
- package/dist/connectors/noeva.d.ts +6 -6
- package/dist/connectors/noeva.js +1 -1
- package/dist/connectors/oauth.d.ts +5 -5
- package/dist/connectors/oauth.js +1 -1
- package/dist/connectors/odoo.d.ts +309 -0
- package/dist/connectors/odoo.js +3 -0
- package/dist/connectors/postgres.d.ts +7 -6
- package/dist/connectors/postgres.js +1 -1
- package/dist/connectors/process.d.ts +1 -1
- package/dist/connectors/process.js +1 -1
- package/dist/connectors/sendgrid.d.ts +7 -7
- package/dist/connectors/sendgrid.js +1 -1
- package/dist/connectors/smtp.d.ts +8 -8
- package/dist/connectors/smtp.js +1 -1
- package/dist/connectors/sqlserver.d.ts +7 -6
- package/dist/connectors/sqlserver.js +1 -1
- package/dist/connectors/zoho.d.ts +6 -6
- package/dist/connectors/zoho.js +1 -1
- package/dist/contract.d.ts +2 -2
- package/dist/{credenziali-posta-f7HB2cYW.d.ts → credenziali-posta-C0az04uV.d.ts} +2 -2
- package/dist/{errors-bgSO6lGO.d.ts → errors-CRq1uNYZ.d.ts} +8 -1
- package/dist/etl.config.js +3 -3
- package/dist/guida/404.html +2 -2
- package/dist/guida/GUIDA_SVILUPPO.html +7 -7
- package/dist/guida/TECHNICAL_OVERVIEW.html +7 -7
- package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.js → GUIDA_SVILUPPO.md.Bvr7RKHN.js} +2 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.C6HYc5_h.js +10 -0
- package/dist/guida/assets/{app.DeVEBaIz.js → app.zL1wgTBx.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.B5GjWddx.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.CsTQzJUK.js → VPLocalSearchBox.BSMd0tSF.js} +1 -1
- package/dist/guida/assets/chunks/{theme.Dfy0C_Zf.js → theme.CRpFq7vp.js} +2 -2
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.js +1 -0
- package/dist/guida/assets/connectors_README.md.B5QWzWUK.lean.js +1 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.js +92 -0
- package/dist/guida/assets/connectors_excel.md.CqGtwEB4.lean.js +1 -0
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.js → connectors_file.md.Dbofo9W5.js} +3 -3
- package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.lean.js → connectors_file.md.Dbofo9W5.lean.js} +1 -1
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.js +34 -0
- package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.lean.js +1 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.js +19 -0
- package/dist/guida/assets/connectors_odoo.md.DprabV5e.lean.js +1 -0
- package/dist/guida/assets/{conventions_node-descriptor.md.MQaGlm8a.js → conventions_node-descriptor.md.C19dB-Tb.js} +4 -4
- package/dist/guida/assets/conventions_node-descriptor.md.C19dB-Tb.lean.js +1 -0
- package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.js → conventions_run-report.md.iVSN9fNV.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.js → conventions_versioni-di-pipeline.md.DJPSthZ8.js} +1 -1
- package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.lean.js → conventions_versioni-di-pipeline.md.DJPSthZ8.lean.js} +1 -1
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.js → nodes_README.md.BNAiSoJJ.js} +2 -2
- package/dist/guida/assets/{nodes_README.md.CHGy_go6.lean.js → nodes_README.md.BNAiSoJJ.lean.js} +1 -1
- package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.js → nodes_lookup.md.DrJFsfOJ.js} +1 -1
- package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.js → nodes_sink.md.C1S-lAh2.js} +2 -2
- package/dist/guida/assets/{nodes_source.md.DP2i3GFv.js → nodes_source.md.BitUNtug.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.js → nodes_task.md.CejEQZcD.js} +2 -2
- package/dist/guida/assets/{nodes_task.md.Dk6VB7as.lean.js → nodes_task.md.CejEQZcD.lean.js} +1 -1
- package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.js → nodes_transform.md.Ciycywnb.js} +1 -1
- package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js} +1 -1
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.js +16 -0
- package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.lean.js +1 -0
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.js → runbooks_sql-task-truncate-swap.md.DAz41942.js} +5 -3
- package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.lean.js → runbooks_sql-task-truncate-swap.md.DAz41942.lean.js} +1 -1
- package/dist/guida/connectors/README.html +5 -5
- package/dist/guida/connectors/excel.html +118 -0
- package/dist/guida/connectors/file.html +7 -7
- package/dist/guida/connectors/http.html +4 -4
- package/dist/guida/connectors/imap.html +4 -4
- package/dist/guida/connectors/jira.html +5 -5
- package/dist/guida/connectors/mysql.html +60 -0
- package/dist/guida/connectors/noeva.html +5 -5
- package/dist/guida/connectors/oauth.html +5 -5
- package/dist/guida/connectors/odoo.html +45 -0
- package/dist/guida/connectors/postgres.html +5 -5
- package/dist/guida/connectors/process.html +4 -4
- package/dist/guida/connectors/sendgrid.html +4 -4
- package/dist/guida/connectors/smtp.html +4 -4
- package/dist/guida/connectors/sqlserver.html +4 -4
- package/dist/guida/connectors/zoho.html +4 -4
- package/dist/guida/conventions/node-columns.html +4 -4
- package/dist/guida/conventions/node-descriptor.html +8 -8
- package/dist/guida/conventions/run-report.html +6 -6
- package/dist/guida/conventions/run-trace.html +4 -4
- package/dist/guida/conventions/variabili-del-core.html +4 -4
- package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
- package/dist/guida/guide/claude-code/index.html +4 -4
- package/dist/guida/guide/claude-code/prompt.html +5 -5
- package/dist/guida/guide/claude-code/strumenti.html +4 -4
- package/dist/guida/guide/grafo.html +4 -4
- package/dist/guida/guide/usare/app-desktop.html +4 -4
- package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
- package/dist/guida/guide/usare/index.html +4 -4
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +4 -4
- package/dist/guida/nodes/README.html +5 -5
- package/dist/guida/nodes/action.html +4 -4
- package/dist/guida/nodes/ai.html +4 -4
- package/dist/guida/nodes/join.html +4 -4
- package/dist/guida/nodes/lookup.html +6 -6
- package/dist/guida/nodes/pipeline.html +4 -4
- package/dist/guida/nodes/route.html +4 -4
- package/dist/guida/nodes/sink.html +7 -7
- package/dist/guida/nodes/source.html +7 -7
- package/dist/guida/nodes/task.html +6 -6
- package/dist/guida/nodes/transform.html +6 -6
- package/dist/guida/nodes/try-catch.html +4 -4
- package/dist/guida/nodes/union.html +4 -4
- package/dist/guida/pagine.json +4 -0
- package/dist/guida/pipelines/README.html +4 -4
- package/dist/guida/pipelines/crm-leads-sync.html +4 -4
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
- package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
- package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
- package/dist/guida/pipelines/test-posta.html +4 -4
- package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
- package/dist/guida/runbooks/deploy-ecr.html +4 -4
- package/dist/guida/runbooks/deployment.html +6 -6
- package/dist/guida/runbooks/etl-worker.html +5 -5
- package/dist/guida/runbooks/excel-operazioni-distruttive.html +42 -0
- package/dist/guida/runbooks/graph-server.html +5 -5
- package/dist/guida/runbooks/mask-key.html +4 -4
- package/dist/guida/runbooks/oauth-google-posta.html +4 -4
- package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
- package/dist/guida/runbooks/scd2-rehash.html +4 -4
- package/dist/guida/runbooks/sql-task-truncate-swap.html +8 -6
- package/dist/guida/runbooks/stato-incrementale.html +4 -4
- package/dist/guida/sub-pipelines/README.html +4 -4
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
- package/dist/index.d.ts +9 -9
- package/dist/index.js +1 -1
- package/dist/{invio-Dwz3J7sP.d.ts → invio-9Ubb_cdR.d.ts} +3 -3
- package/dist/{istanza-per-il-piano-CucqUF7b.d.ts → istanza-per-il-piano-74NYhIHc.d.ts} +1 -1
- package/dist/{manifest-variabili-U1UfPDfF.d.ts → manifest-variabili-DRWUzmxU.d.ts} +1 -1
- package/dist/pipelines.d.ts +3 -3
- package/dist/pipelines.js +1 -1
- package/dist/{runnable-pipeline-CArkLzfv.d.ts → runnable-pipeline-CWgPwi6w.d.ts} +2 -2
- package/dist/{config-DIthC7n7.d.ts → sql-watermark-CQVvxhPZ.d.ts} +9 -40
- package/dist/testing.d.ts +3 -3
- package/dist/testing.js +1 -1
- package/dist/{trasporto-DpPLCEQ1.d.ts → trasporto-BaRdP6Wl.d.ts} +4 -4
- package/dist/{types-BVA7BIou.d.ts → types-_3rgLhje.d.ts} +21 -2
- package/dist/{variabili-dichiarate-DmfcxsT9.d.ts → variabili-dichiarate-CS-eC53K.d.ts} +1 -1
- package/kit/skills/etl-graph/SKILL.md +6 -3
- package/kit/skills/etl-graph/references/data-patterns.md +1 -1
- package/kit/skills/etl-graph/references/error-handling.md +3 -3
- package/kit/skills/etl-graph/references/wiring.md +10 -10
- package/kit/skills/new-connector/SKILL.md +2 -2
- package/package.json +16 -1
- package/dist/chunk-BVUOUBLW.js +0 -1
- package/dist/chunk-CRR3Q2C7.js +0 -2
- package/dist/chunk-LJ7DVP5F.js +0 -2
- package/dist/chunk-PKBSETMV.js +0 -2
- package/dist/chunk-QPJC4GWR.js +0 -1
- package/dist/chunk-RCRMQPFH.js +0 -5
- package/dist/chunk-RS5SGDUU.js +0 -1
- package/dist/chunk-RWPHH4E2.js +0 -1
- package/dist/chunk-SRFFKE5W.js +0 -6
- package/dist/chunk-WVODQB6Z.js +0 -1
- package/dist/chunk-XZMCC6VQ.js +0 -1
- package/dist/chunk-ZCYGHS7P.js +0 -2
- package/dist/guida/assets/TECHNICAL_OVERVIEW.md.DTIhkkg9.js +0 -10
- package/dist/guida/assets/chunks/@localSearchIndexroot.NgfCNDyz.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +0 -1
- package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +0 -1
- package/dist/guida/assets/conventions_node-descriptor.md.MQaGlm8a.lean.js +0 -1
- /package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.lean.js → GUIDA_SVILUPPO.md.Bvr7RKHN.lean.js} +0 -0
- /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js → TECHNICAL_OVERVIEW.md.C6HYc5_h.lean.js} +0 -0
- /package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.lean.js → conventions_run-report.md.iVSN9fNV.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.lean.js → nodes_lookup.md.DrJFsfOJ.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.lean.js → nodes_sink.md.C1S-lAh2.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_source.md.DP2i3GFv.lean.js → nodes_source.md.BitUNtug.lean.js} +0 -0
- /package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.lean.js → nodes_transform.md.Ciycywnb.lean.js} +0 -0
- /package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.lean.js → runbooks_deployment.md.BV8Izw4I.lean.js} +0 -0
|
@@ -21,7 +21,7 @@ import{_ as o,o as i,c as a,a5 as s}from"./chunks/framework.qdetmeNX.js";const g
|
|
|
21
21
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineEtlConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
22
22
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> client: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"acme"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
23
23
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pipelines: [fattureDaily, testPosta],</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><strong>Le pipeline pronte</strong> arrivano dal core: si dichiarano nel catalogo come le altre, importate da <code>@noeva/etl-core/pipelines</code>. Hanno versione, scheda e scopi nel core, quindi il repo cliente non le versiona e non le documenta: <code>etl list</code> le marca con <code>pronta</code>, e l'indice del catalogo del cliente le linka nella sezione «Pipeline pronte» di questa guida.</p><p><strong>Il nome</strong> di una pipeline combacia con <code>processes.function</code> e con <code>scheduled_jobs.process_function</code>: il worker risolve per nome, senza traduzione.</p><h2 id="_3-l-api-pubblica" tabindex="-1">3. L'API pubblica <a class="header-anchor" href="#_3-l-api-pubblica" aria-label="Permalink to "3. L'API pubblica""></a></h2><p>Un repo cliente importa solo dal pacchetto e dai suoi subpath, mai da percorsi interni: è l'unico confine, e i tipi del core arrivano con il pacchetto, nelle sue <code>.d.ts</code>.</p><table tabindex="0"><thead><tr><th>Import</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>@noeva/etl-core</code></td><td>il DSL <code>graph()</code>, i tipi dei nodi, le transform, gli errori, <code>z</code> di Zod, <code>defineEtlConfig</code></td></tr><tr><td><code>@noeva/etl-core/connectors/<nome></code></td><td>un connettore: <code>file</code>, <code>http</code>, <code>imap</code>, <code>jira</code>, <code>mail</code>, <code>noeva</code>, <code>oauth</code>, <code>postgres</code>, <code>process</code>, <code>sendgrid</code>, <code>smtp</code>, <code>sqlserver</code></td></tr><tr><td><code>@noeva/etl-core/connector-kit</code></td><td>gli strumenti per scrivere un connettore o leggere l'ambiente di una pipeline</td></tr><tr><td><code>@noeva/etl-core/testing</code></td><td>i doppi in memoria dei sistemi esterni (IMAP, Noeva, SendGrid), per i test</td></tr><tr><td><code>@noeva/etl-core/pipelines</code></td><td>le pipeline pronte</td></tr><tr><td><code>@noeva/etl-core/contract</code></td><td>i tipi del contratto fra <code>etl serve</code> e l'app desktop</td></tr><tr><td><code>@noeva/etl-core/tsconfig</code>, <code>/eslint</code>, <code>/vitest</code></td><td>i preset della toolchain</td></tr><tr><td><code>@noeva/etl-core/pm2</code>, <code>/deploy/Dockerfile</code></td><td>le confezioni del deploy: la configurazione PM2 e il Dockerfile dell'immagine</td></tr></tbody></table><p>Due regole valgono per ogni pipeline:</p><ul><li><strong><code>z</code> arriva dalla radice del pacchetto</strong>, non da <code>zod</code>: così i contratti usano l'istanza e la versione del core.</li><li><strong>Un driver passa dal suo connettore</strong>: una pipeline non importa <code>pg</code> o <code>
|
|
24
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><strong>Le pipeline pronte</strong> arrivano dal core: si dichiarano nel catalogo come le altre, importate da <code>@noeva/etl-core/pipelines</code>. Hanno versione, scheda e scopi nel core, quindi il repo cliente non le versiona e non le documenta: <code>etl list</code> le marca con <code>pronta</code>, e l'indice del catalogo del cliente le linka nella sezione «Pipeline pronte» di questa guida.</p><p><strong>Il nome</strong> di una pipeline combacia con <code>processes.function</code> e con <code>scheduled_jobs.process_function</code>: il worker risolve per nome, senza traduzione.</p><h2 id="_3-l-api-pubblica" tabindex="-1">3. L'API pubblica <a class="header-anchor" href="#_3-l-api-pubblica" aria-label="Permalink to "3. L'API pubblica""></a></h2><p>Un repo cliente importa solo dal pacchetto e dai suoi subpath, mai da percorsi interni: è l'unico confine, e i tipi del core arrivano con il pacchetto, nelle sue <code>.d.ts</code>.</p><table tabindex="0"><thead><tr><th>Import</th><th>Cosa contiene</th></tr></thead><tbody><tr><td><code>@noeva/etl-core</code></td><td>il DSL <code>graph()</code>, i tipi dei nodi, le transform, gli errori, <code>z</code> di Zod, <code>defineEtlConfig</code></td></tr><tr><td><code>@noeva/etl-core/connectors/<nome></code></td><td>un connettore: <code>excel</code>, <code>file</code>, <code>http</code>, <code>imap</code>, <code>jira</code>, <code>mail</code>, <code>mysql</code>, <code>noeva</code>, <code>oauth</code>, <code>odoo</code>, <code>postgres</code>, <code>process</code>, <code>sendgrid</code>, <code>smtp</code>, <code>sqlserver</code>, <code>zoho</code></td></tr><tr><td><code>@noeva/etl-core/connector-kit</code></td><td>gli strumenti per scrivere un connettore o leggere l'ambiente di una pipeline</td></tr><tr><td><code>@noeva/etl-core/testing</code></td><td>i doppi in memoria dei sistemi esterni (IMAP, Noeva, SendGrid), per i test</td></tr><tr><td><code>@noeva/etl-core/pipelines</code></td><td>le pipeline pronte</td></tr><tr><td><code>@noeva/etl-core/contract</code></td><td>i tipi del contratto fra <code>etl serve</code> e l'app desktop</td></tr><tr><td><code>@noeva/etl-core/tsconfig</code>, <code>/eslint</code>, <code>/vitest</code></td><td>i preset della toolchain</td></tr><tr><td><code>@noeva/etl-core/pm2</code>, <code>/deploy/Dockerfile</code></td><td>le confezioni del deploy: la configurazione PM2 e il Dockerfile dell'immagine</td></tr></tbody></table><p>Due regole valgono per ogni pipeline:</p><ul><li><strong><code>z</code> arriva dalla radice del pacchetto</strong>, non da <code>zod</code>: così i contratti usano l'istanza e la versione del core.</li><li><strong>Un driver passa dal suo connettore</strong>: una pipeline non importa <code>pg</code>, <code>mssql</code> o <code>mysql2</code> direttamente.</li></ul><p>I <strong>preset della toolchain</strong> rendono di una riga i tre file di configurazione del repo:</p><div class="language-jsonc vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">jsonc</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;">// tsconfig.json</span></span>
|
|
25
25
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">"extends"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"@noeva/etl-core/tsconfig"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span></code></pre></div><div class="language-js vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">js</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;">// eslint.config.js</span></span>
|
|
26
26
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@noeva/etl-core/eslint"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</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;">// vitest.config.ts</span></span>
|
|
27
27
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@noeva/etl-core/vitest"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre></div><p><code>./tsconfig</code> ha <code>moduleResolution: bundler</code>, che legge i subpath della mappa <code>exports</code>, e <code>noEmit</code>; <code>./eslint</code> mette <code>no-explicit-any</code> e <code>no-console</code> a <code>error</code>; <code>./vitest</code> cerca i test in <code>src/</code> e <code>tests/</code>, senza globali e senza soglia di coverage.</p><h2 id="_4-le-primitive" tabindex="-1">4. Le primitive <a class="header-anchor" href="#_4-le-primitive" aria-label="Permalink to "4. Le primitive""></a></h2><p>Tutto ruota attorno a quattro concetti base, mappati ai componenti Talend:</p><table tabindex="0"><thead><tr><th>Primitiva</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>Source<T></code></td><td>estrae record da un sistema esterno come <code>AsyncIterable<T></code> (streaming, mai tutto in memoria)</td></tr><tr><td><code>Transform<I,O></code></td><td>trasforma uno stream <code>I</code> in uno stream <code>O</code>; <strong>pura</strong>, senza side-effect esterni</td></tr><tr><td><code>Sink<T></code></td><td>carica i record su un sistema di destinazione; <strong>deve essere idempotente</strong> (upsert/MERGE)</td></tr><tr><td><code>GraphPipeline</code></td><td>il processo: un grafo di nodi costruito col DSL <code>graph(name)…build()</code></td></tr></tbody></table><p>Il <strong>grafo è l'unico modo di costruire un processo</strong>. Anche una catena semplice è un grafo con un nodo per stadio:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">graph</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"orders-daily"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
@@ -32,7 +32,7 @@ import{_ as o,o as i,c as a,a5 as s}from"./chunks/framework.qdetmeNX.js";const g
|
|
|
32
32
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"raw-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">mapTransform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, toFact))</span></span>
|
|
33
33
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">transform</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"to-fact"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">validate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, factSchema))</span></span>
|
|
34
34
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fact-contract"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sink)</span></span>
|
|
35
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>Gli undici tipi di nodo. A questi si aggiunge il nodo <a href="./nodes/pipeline"><code>pipeline</code></a>, <code>.pipeline(from, id, sub, { params?, deps?, fromPort?, deadLetter?, purpose? })</code>, che istanzia una sub-pipeline e alla costruzione diventa i suoi nodi:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>source</code></td><td><code>.source(id, source)</code></td><td>punto d'ingresso di uno stream</td></tr><tr><td><code>transform</code></td><td><code>.transform(from, id, t, opts)</code></td><td>trasformazione pura; accetta <code>deadLetter</code></td></tr><tr><td><code>lookup</code></td><td><code>.lookup(from, id, config, opts)</code></td><td>lettura <strong>in sola lettura</strong> in mezzo al grafo, a batch, da un DB o un'API REST; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>ai</code></td><td><code>.ai(from, id, config, opts)</code></td><td>domanda a un <strong>modello</strong> per ogni record, con la risposta che arricchisce il record (es. <code>noevaAiExtract</code>); si esegue come un <code>lookup</code>; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>action</code></td><td><code>.action(from, id, action, opts)</code></td><td><strong>scrittura per record</strong> in mezzo al grafo, con un record in uscita su cui il grafo prosegue; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>route</code></td><td><code>.route(from, id, { routes }, opts)</code></td><td><strong>smistamento esclusivo</strong>: ogni record esce sulla porta della prima condizione vera, o su <code>default</code>; ogni porta va collegata; accetta <code>deadLetter</code></td></tr><tr><td><code>join</code></td><td><code>.join(id, { build, probe, … })</code></td><td>fan-in <strong>a chiave</strong>: join inner/left, lato <code>build</code> in memoria e <code>probe</code> in streaming; accetta <code>deadLetter</code></td></tr><tr><td><code>union</code></td><td><code>.union(id, { from, order })</code></td><td>fan-in di N flussi con la stessa forma, record invariati: <code>interleave</code> (default) nell'ordine di arrivo, <code>concat</code> nell'ordine di <code>from</code></td></tr><tr><td><code>try-catch</code></td><td><code>.tryCatch(from, id, opts)</code></td><td>apre uno scope di gestione errori sui nodi a valle, con una porta <code>catch</code></td></tr><tr><td><code>sink</code></td><td><code>.sink(from, sink)</code></td><td>scrittura verso l'esterno; l'id del nodo è <code>sink.name</code></td></tr><tr><td><code>task</code></td><td><code>.task(id, task, opts)</code></td><td>operazione <strong>senza record</strong> (truncate, scambio di tabelle), avviata dagli edge di controllo <code>after</code></td></tr></tbody></table><p>Il cheatsheet dei nodi, con una scheda di dettaglio per ciascuno (opzioni, errori, esempi), è in <a href="./nodes/README">Tipi di nodo</a>.</p><p>Il <strong>fan-out</strong> invece è libero: basta agganciare più nodi allo stesso <code>from</code>, e il runner duplica lo stream. La forma del grafo è validata <strong>a runtime</strong> su <code>.build()</code>: cicli, id sconosciuti o più di un ingresso su un nodo diverso da <code>join</code> e <code>union</code> esplodono come <code>GraphValidationError</code> alla costruzione. Esempio di riferimento completo: <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a>.</p><p>Oltre agli edge di dati ci sono gli <strong>edge di controllo</strong>: l'opzione <code>after</code> di <code>.task()</code> e <code>.source()</code> dice «parti solo dopo che questi nodi sono riusciti». Partono da un <code>task</code> o da un <code>sink</code> e arrivano a un <code>task</code> o a una <code>source</code>. Dettagli nella scheda <a href="./nodes/task"><code>task</code></a>.</p><p>Ogni nodo ha uno <strong>scopo</strong>, <code>purpose</code>, scritto per chi legge il grafo nell'app: che cosa fa il nodo e perché serve, in una-tre frasi di business. Lo verificano <code>etl catalog check</code> ed <code>etl docs build</code>.</p><p>Il <code>RunContext</code> che ogni nodo riceve porta env, parametri di lancio (<code>ctx.params</code>), logger, metriche, il segnale d'arresto e lo store dello stato di pipeline. Gli errori di dominio sono <code>EtlError</code> (<code>ValidationError</code>, <code>ExtractError</code>, <code>LoadError</code>, <code>ConfigError</code>, <code>GraphValidationError</code>, <code>JoinError</code>, <code>LookupError</code>, <code>ActionError</code>, <code>TaskError</code>, <code>AssertionError</code>, <code>GraphRunFailure</code>): un errore che non lo è conta come bug.</p><h2 id="_5-come-gira-una-pipeline" tabindex="-1">5. Come gira una pipeline <a class="header-anchor" href="#_5-come-gira-una-pipeline" aria-label="Permalink to "5. Come gira una pipeline""></a></h2><p>Il grafo è <strong>pull-based</strong>: la domanda parte dai sink e risale verso le source, quindi è il ritmo di scrittura a regolare quello di lettura (backpressure gratis). I record scorrono in streaming, mai tutti in memoria — tranne il lato <code>build</code> di un <code>join</code> e le transform che trattengono lo stream, come <code>sort</code>, che hanno un tetto obbligatorio.</p><p>Quando un record fallisce ci sono tre percorsi, dal più locale al più drastico:</p><ul><li><strong>Dead-letter per nodo</strong> — <code>{ deadLetter: sink }</code> su un <code>transform</code>, <code>lookup</code>, <code>ai</code>, <code>action</code>, <code>route</code> o <code>join</code>. Il record che solleva <code>EtlError</code> esce come envelope <code>DeadLetter</code> su quel sink e <strong>lo stream continua</strong>. Adatto alle trasformazioni <strong>stateless</strong> (map/mapColumns/flatMap/explode/unpivot/filter/validate, <code>parse</code>, <code>hashRow</code>, <code>surrogateKey</code>, <code>mask</code>). Sul <code>.pipeline()</code> della root la <code>deadLetter</code> si distribuisce a ogni nodo isolabile dell'istanza, istanze annidate comprese (<a href="./nodes/pipeline#deadletter-sull-istanza"><code>deadLetter</code> sull'istanza</a>).</li><li><strong>Nodo <code>try-catch</code></strong> — protegge tutti i nodi raggiungibili dalla sua porta <code>out</code>, sink compresi. Di default è <code>per-record</code>: ogni record che fallisce va sul ramo <code>catch</code>, che è fatto di nodi veri e può loggare, rimappare o instradare altrove. In <code>circuit-breaker</code> al primo errore la sub-stream si ferma.</li><li><strong>Fail-fast</strong> — il default, senza dead-letter né guard: l'errore aborta la run. È l'unica scelta sensata per le trasformazioni <strong>stateful</strong> (es. <code>groupBy</code>, <code>sort</code>, <code>serialize</code>): un'aggregazione spezzata per record darebbe un risultato falso. Vale per tutto il grafo: al primo errore fatale il runner annulla anche i rami indipendenti e aspetta che ogni sink e ogni task chiuda prima di riportare la run fallita. Un <code>task</code> che fallisce è sempre fatale.</li></ul><p>Un errore che <strong>non</strong> è un <code>EtlError</code> (un <code>TypeError</code>, un bug) aborta sempre la run, anche dentro un guard: un bug non va scaricato in un sink di scarto, va visto. Qualunque sia la scelta, nessun record sparisce in silenzio: ogni scarto è contato nel report.</p><p>Ogni <code>run()</code> produce un <code>GraphRunReport</code>:</p><ul><li><strong>stato</strong> — <code>success</code>, <code>partial</code> (arrivata in fondo con scarti o errori catturati) o <code>failed</code>;</li><li><strong>totali</strong> — <code>extracted</code> (somma delle source), <code>written</code> (somma dei sink: su un fan-out lo stesso record scritto due volte conta due), <code>rejected</code>, <code>rejectedReasons</code>;</li><li><strong>per nodo</strong> — <code>nodes[]</code> ed <code>edges[]</code> con la topologia reale e i contatori di ogni nodo, <code>caught</code> sui guard, tempi di attraversamento;</li><li><strong>stato di pipeline</strong> — <code>state</code>, una voce per source incrementale: da dove ha letto, cosa propone, se il watermark è stato committato;</li><li>metriche ed errore — <strong>mai segreti o payload</strong>.</li></ul><p>È il "prodotto" del servizio: chi invoca la pipeline decide se archiviarlo, alertare, ecc. Schema completo in <a href="./conventions/run-report">Il report di run</a>.</p><h2 id="_6-cosa-c-e-gia-pronto" tabindex="-1">6. Cosa c'è già pronto <a class="header-anchor" href="#_6-cosa-c-e-gia-pronto" aria-label="Permalink to "6. Cosa c'è già pronto""></a></h2><p><strong>Connettori</strong>, uno per subpath di <code>@noeva/etl-core/connectors/</code>:</p><ul><li><strong>PostgreSQL</strong> (<code>postgres</code>) — source con cursor streaming, sink con upsert <code>ON CONFLICT</code> o in modalità SCD2 (dimensioni storicizzate), task SQL <code>postgresSqlTask</code> (statement in una transazione, per il nodo <code>task</code>).</li><li><strong>SQL Server</strong> (<code>sqlserver</code>) — source streaming, sink con <code>MERGE</code> o in modalità SCD2, task SQL <code>mssqlSqlTask</code>.</li><li><strong>File</strong> (<code>file</code>) — architettura a due assi componibili: <ul><li><em>storage</em>: dove vivono i file (locale, <strong>S3</strong>, <strong>SFTP</strong>, <strong>FTP/FTPS</strong>);</li><li><em>codec</em>: come si (de)serializzano — <strong>CSV</strong> (anche grezzo, <code>csvRawCodec</code>), <strong>JSON/NDJSON</strong>, <strong>XML</strong>, <strong>XLSX</strong>, <strong>Parquet</strong>. Storage e codec si combinano liberamente (es. CSV su S3, Parquet su SFTP).</li></ul></li><li><strong>Noeva</strong> (<code>noeva</code>) — file dei workspace Noeva via noeva-server-api: lettura di un file o di una cartella intera, scrittura di uno o più file in <code>overwrite</code> o <code>new-version</code>, upload con elaborazione AI (<code>noevaUploadAction</code>), lookup su stato e testo estratto ed estrazione AI di campi strutturati (<code>noevaAiExtract</code>, nodo <code>ai</code>).</li><li><strong>IMAP</strong> (<code>imap</code>) — caselle di posta: <code>imapSource</code> legge i messaggi di una cartella (allegati ed EML grezzo), le action <code>imapFlagAction</code> e <code>imapSpostaAction</code> marcano e spostano, con la cartella come coda.</li><li><strong>SMTP</strong> (<code>smtp</code>) — notifiche email: <code>smtpAction</code> e <code>smtpSink</code> inviano una mail costruita da una funzione del record, con Message-ID deterministico contro i doppioni.</li><li><strong>SendGrid</strong> (<code>sendgrid</code>) — mail via API REST v3: <code>sendgridAction</code> e <code>sendgridSink</code>, con la stessa mail di SMTP (<code>MailInUscita</code>), sandbox per le prove, retry di <code>429</code> e <code>5xx</code>; <code>mailAction</code> e <code>mailSink</code> (<code>mail</code>) scelgono fra SMTP e SendGrid da configurazione.</li><li><strong>HTTP</strong> (<code>http</code>) — API REST per i nodi <code>lookup</code> e <code>action</code>: <code>httpLookup</code> legge in sola lettura, una richiesta per batch o una <code>GET</code> per chiave, <code>httpAction</code> scrive e prosegue con l'esito; la risposta è validata da uno schema Zod e le credenziali vengono dal registry <code>HTTP_INSTANCES</code>. Il loro trasporto, <code>richiestaHttp</code>, è condiviso con i connettori REST di dominio, come Jira.</li><li><strong>Jira Cloud</strong> (<code>jira</code>) — <code>jiraIssues</code> legge le issue di una JQL, pagina dopo pagina, con i siti nel registry <code>JIRA_INSTANCES</code>; i campi si dichiarano per id o per nome e diventano colonne normalizzate, con gli ADF convertiti in testo. <code>jiraIssueLookup</code> legge le stesse issue per chiave, e <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code> e <code>jiraWorklogsLookup</code> danno a ogni issue la sua lista completa. <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> (per ID esterno), <code>jiraAddComment</code> e <code>jiraAddWorklog</code> (con una chiave di deduplica obbligatoria) e <code>jiraLinkIssues</code> scrivono come nodi <code>action</code>, con l'esito come dato.</li><li><strong>Zoho CRM</strong> (<code>zoho</code>) — <code>zohoCrmRecords</code> legge i record di un modulo con i soli campi dichiarati, che sono anche la regola di privacy, in ordine di <code>id</code>: con la Records API fino a 100.000 record, con la Query API (COQL) a chiavi crescenti di <code>id</code> oltre. Le organizzazioni stanno nel registry <code>ZOHO_INSTANCES</code>, il token lo rinnova un'identità OAuth2 e il trasporto è quello condiviso di <code>http</code>.</li><li><strong>Processo esterno</strong> (<code>process</code>) — <code>processoEsternoAction</code> lancia un programma per record, senza shell, in una cartella temporanea sempre cancellata: i file del record entrano, i file di <code>uscita/</code> e un riepilogo JSON validato con Zod escono. Ambiente da allowlist e timeout obbligatorio.</li><li><strong>OAuth2</strong> (<code>oauth</code>) — non un connettore ma l'<strong>identità</strong> che IMAP e SMTP usano dove la password non basta più (Gmail, Workspace, Microsoft 365), e con cui Zoho CRM autentica le sue richieste: tiene il refresh token e ne scambia uno nuovo quando l'access token scade, con un registry proprio <code>OAUTH_INSTANCES</code>.</li></ul><p>Le schede, con configurazione e variabili d'ambiente di ognuno, sono in <a href="./connectors/README">Connettori</a>.</p><p><strong>Trasformazioni riusabili</strong>, dalla radice del pacchetto: <code>groupBy</code> (aggregazione stateful generica init/reduce/finalize), <code>dedup</code> (duplicati per chiave), <code>mapColumns</code> (select, rename, cast e colonne calcolate, con lineage di colonna) e <code>castValue</code> (i suoi cast stretti, usabili da soli), <code>explode</code> (un campo array → un record per elemento), <code>unpivot</code> e <code>pivot</code> (dal formato largo al lungo e ritorno, con colonne dichiarate), <code>sort</code> (ordinamento stabile su più chiavi), <code>chunk</code> (record in lotti di N per un sink o un'API con limite di payload), <code>parse</code> (byte di un file → righe, con un <code>FileCodec</code>) e <code>serialize</code> (record → un file per gruppo, stateful), <code>hashRow</code> e <code>surrogateKey</code> (hash di riga e chiave surrogata deterministici), <code>mask</code> (mascheramento e pseudonimizzazione delle colonne con dati personali), <code>profile</code> (profilo delle colonne nel report del nodo, a memoria costante), <code>assert</code> (controlli sul dataset a fine stream). Il catalogo completo è in <a href="./nodes/transform#transform-pronte">transform</a>.</p><p><strong>Pipeline d'esempio</strong>, con la loro scheda nella sezione «Esempi» di questa guida:</p><ul><li><a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> — dataset demo in memoria, esempio di riferimento per una pipeline <strong>a grafo</strong>: due sorgenti, join a chiave, fan-out su due sink, dead-letter isolato su due nodi indipendenti, try/catch e un'istanza della sub-pipeline <a href="./sub-pipelines/riepilogo-ordini"><code>riepilogo-ordini</code></a>.</li><li><a href="./pipelines/movimenti-per-conto"><code>movimenti-per-conto</code></a> — dataset demo in memoria, esempio di riferimento per le transform di file e di ordinamento in mezzo al grafo: <code>parse</code>, <code>sort</code> e <code>serialize</code>, da estratti conto CSV a un CSV per conto.</li><li><a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> — copia fra due istanze Postgres dello stesso registry, con un try/catch per record.</li><li><a href="./pipelines/cross-workspace-csv-merge"><code>cross-workspace-csv-merge</code></a> — merge di un CSV fra due workspace Noeva, con un <code>union</code> e la scrittura in <code>new-version</code> su entrambi.</li></ul><p><strong>Pipeline pronte</strong>, da dichiarare nel catalogo: <a href="./pipelines/test-posta"><code>test-posta</code></a>, la prova dei connettori IMAP e SMTP di un'installazione.</p><h2 id="_7-i-comandi" tabindex="-1">7. I comandi <a class="header-anchor" href="#_7-i-comandi" aria-label="Permalink to "7. I comandi""></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:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # in una cartella vuota: il boilerplate di un repo cliente</span></span>
|
|
35
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">build</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>Gli undici tipi di nodo. A questi si aggiunge il nodo <a href="./nodes/pipeline"><code>pipeline</code></a>, <code>.pipeline(from, id, sub, { params?, deps?, fromPort?, deadLetter?, purpose? })</code>, che istanzia una sub-pipeline e alla costruzione diventa i suoi nodi:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Metodo</th><th>Cosa fa</th></tr></thead><tbody><tr><td><code>source</code></td><td><code>.source(id, source)</code></td><td>punto d'ingresso di uno stream</td></tr><tr><td><code>transform</code></td><td><code>.transform(from, id, t, opts)</code></td><td>trasformazione pura; accetta <code>deadLetter</code></td></tr><tr><td><code>lookup</code></td><td><code>.lookup(from, id, config, opts)</code></td><td>lettura <strong>in sola lettura</strong> in mezzo al grafo, a batch, da un DB o un'API REST; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>ai</code></td><td><code>.ai(from, id, config, opts)</code></td><td>domanda a un <strong>modello</strong> per ogni record, con la risposta che arricchisce il record (es. <code>noevaAiExtract</code>); si esegue come un <code>lookup</code>; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>action</code></td><td><code>.action(from, id, action, opts)</code></td><td><strong>scrittura per record</strong> in mezzo al grafo, con un record in uscita su cui il grafo prosegue; accetta <code>deadLetter</code> e <code>recordReport</code></td></tr><tr><td><code>route</code></td><td><code>.route(from, id, { routes }, opts)</code></td><td><strong>smistamento esclusivo</strong>: ogni record esce sulla porta della prima condizione vera, o su <code>default</code>; ogni porta va collegata; accetta <code>deadLetter</code></td></tr><tr><td><code>join</code></td><td><code>.join(id, { build, probe, … })</code></td><td>fan-in <strong>a chiave</strong>: join inner/left, lato <code>build</code> in memoria e <code>probe</code> in streaming; accetta <code>deadLetter</code></td></tr><tr><td><code>union</code></td><td><code>.union(id, { from, order })</code></td><td>fan-in di N flussi con la stessa forma, record invariati: <code>interleave</code> (default) nell'ordine di arrivo, <code>concat</code> nell'ordine di <code>from</code></td></tr><tr><td><code>try-catch</code></td><td><code>.tryCatch(from, id, opts)</code></td><td>apre uno scope di gestione errori sui nodi a valle, con una porta <code>catch</code></td></tr><tr><td><code>sink</code></td><td><code>.sink(from, sink)</code></td><td>scrittura verso l'esterno; l'id del nodo è <code>sink.name</code></td></tr><tr><td><code>task</code></td><td><code>.task(id, task, opts)</code></td><td>operazione <strong>senza record</strong> (truncate, scambio di tabelle), avviata dagli edge di controllo <code>after</code></td></tr></tbody></table><p>Il cheatsheet dei nodi, con una scheda di dettaglio per ciascuno (opzioni, errori, esempi), è in <a href="./nodes/README">Tipi di nodo</a>.</p><p>Il <strong>fan-out</strong> invece è libero: basta agganciare più nodi allo stesso <code>from</code>, e il runner duplica lo stream. La forma del grafo è validata <strong>a runtime</strong> su <code>.build()</code>: cicli, id sconosciuti o più di un ingresso su un nodo diverso da <code>join</code> e <code>union</code> esplodono come <code>GraphValidationError</code> alla costruzione. Esempio di riferimento completo: <a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a>.</p><p>Oltre agli edge di dati ci sono gli <strong>edge di controllo</strong>: l'opzione <code>after</code> di <code>.task()</code> e <code>.source()</code> dice «parti solo dopo che questi nodi sono riusciti». Partono da un <code>task</code> o da un <code>sink</code> e arrivano a un <code>task</code> o a una <code>source</code>. Dettagli nella scheda <a href="./nodes/task"><code>task</code></a>.</p><p>Ogni nodo ha uno <strong>scopo</strong>, <code>purpose</code>, scritto per chi legge il grafo nell'app: che cosa fa il nodo e perché serve, in una-tre frasi di business. Lo verificano <code>etl catalog check</code> ed <code>etl docs build</code>.</p><p>Il <code>RunContext</code> che ogni nodo riceve porta env, parametri di lancio (<code>ctx.params</code>), logger, metriche, il segnale d'arresto e lo store dello stato di pipeline. Gli errori di dominio sono <code>EtlError</code> (<code>ValidationError</code>, <code>ExtractError</code>, <code>LoadError</code>, <code>ConfigError</code>, <code>GraphValidationError</code>, <code>JoinError</code>, <code>LookupError</code>, <code>ActionError</code>, <code>TaskError</code>, <code>AssertionError</code>, <code>GraphRunFailure</code>): un errore che non lo è conta come bug.</p><h2 id="_5-come-gira-una-pipeline" tabindex="-1">5. Come gira una pipeline <a class="header-anchor" href="#_5-come-gira-una-pipeline" aria-label="Permalink to "5. Come gira una pipeline""></a></h2><p>Il grafo è <strong>pull-based</strong>: la domanda parte dai sink e risale verso le source, quindi è il ritmo di scrittura a regolare quello di lettura (backpressure gratis). I record scorrono in streaming, mai tutti in memoria — tranne il lato <code>build</code> di un <code>join</code> e le transform che trattengono lo stream, come <code>sort</code>, che hanno un tetto obbligatorio.</p><p>Quando un record fallisce ci sono tre percorsi, dal più locale al più drastico:</p><ul><li><strong>Dead-letter per nodo</strong> — <code>{ deadLetter: sink }</code> su un <code>transform</code>, <code>lookup</code>, <code>ai</code>, <code>action</code>, <code>route</code> o <code>join</code>. Il record che solleva <code>EtlError</code> esce come envelope <code>DeadLetter</code> su quel sink e <strong>lo stream continua</strong>. Adatto alle trasformazioni <strong>stateless</strong> (map/mapColumns/flatMap/explode/unpivot/filter/validate, <code>parse</code>, <code>hashRow</code>, <code>surrogateKey</code>, <code>mask</code>). Sul <code>.pipeline()</code> della root la <code>deadLetter</code> si distribuisce a ogni nodo isolabile dell'istanza, istanze annidate comprese (<a href="./nodes/pipeline#deadletter-sull-istanza"><code>deadLetter</code> sull'istanza</a>).</li><li><strong>Nodo <code>try-catch</code></strong> — protegge tutti i nodi raggiungibili dalla sua porta <code>out</code>, sink compresi. Di default è <code>per-record</code>: ogni record che fallisce va sul ramo <code>catch</code>, che è fatto di nodi veri e può loggare, rimappare o instradare altrove. In <code>circuit-breaker</code> al primo errore la sub-stream si ferma.</li><li><strong>Fail-fast</strong> — il default, senza dead-letter né guard: l'errore aborta la run. È l'unica scelta sensata per le trasformazioni <strong>stateful</strong> (es. <code>groupBy</code>, <code>sort</code>, <code>serialize</code>): un'aggregazione spezzata per record darebbe un risultato falso. Vale per tutto il grafo: al primo errore fatale il runner annulla anche i rami indipendenti e aspetta che ogni sink e ogni task chiuda prima di riportare la run fallita. Un <code>task</code> che fallisce è sempre fatale.</li></ul><p>Un errore che <strong>non</strong> è un <code>EtlError</code> (un <code>TypeError</code>, un bug) aborta sempre la run, anche dentro un guard: un bug non va scaricato in un sink di scarto, va visto. Qualunque sia la scelta, nessun record sparisce in silenzio: ogni scarto è contato nel report.</p><p>Ogni <code>run()</code> produce un <code>GraphRunReport</code>:</p><ul><li><strong>stato</strong> — <code>success</code>, <code>partial</code> (arrivata in fondo con scarti o errori catturati) o <code>failed</code>;</li><li><strong>totali</strong> — <code>extracted</code> (somma delle source), <code>written</code> (somma dei sink: su un fan-out lo stesso record scritto due volte conta due), <code>rejected</code>, <code>rejectedReasons</code>;</li><li><strong>per nodo</strong> — <code>nodes[]</code> ed <code>edges[]</code> con la topologia reale e i contatori di ogni nodo, <code>caught</code> sui guard, tempi di attraversamento;</li><li><strong>stato di pipeline</strong> — <code>state</code>, una voce per source incrementale: da dove ha letto, cosa propone, se il watermark è stato committato;</li><li>metriche ed errore — <strong>mai segreti o payload</strong>.</li></ul><p>È il "prodotto" del servizio: chi invoca la pipeline decide se archiviarlo, alertare, ecc. Schema completo in <a href="./conventions/run-report">Il report di run</a>.</p><h2 id="_6-cosa-c-e-gia-pronto" tabindex="-1">6. Cosa c'è già pronto <a class="header-anchor" href="#_6-cosa-c-e-gia-pronto" aria-label="Permalink to "6. Cosa c'è già pronto""></a></h2><p><strong>Connettori</strong>, uno per subpath di <code>@noeva/etl-core/connectors/</code>:</p><ul><li><strong>PostgreSQL</strong> (<code>postgres</code>) — source con cursor streaming, sink con upsert <code>ON CONFLICT</code> o in modalità SCD2 (dimensioni storicizzate), task SQL <code>postgresSqlTask</code> (statement in una transazione, per il nodo <code>task</code>).</li><li><strong>SQL Server</strong> (<code>sqlserver</code>) — source streaming, sink con <code>MERGE</code> o in modalità SCD2, task SQL <code>mssqlSqlTask</code>.</li><li><strong>MySQL e MariaDB</strong> (<code>mysql</code>) — source streaming, sink con <code>ON DUPLICATE KEY UPDATE</code>, lookup <code>mysqlLookup</code>, task SQL <code>mysqlSqlTask</code> (senza SCD2). Date e <code>BIGINT</code> arrivano come stringhe.</li><li><strong>Excel</strong> (<code>excel</code>) — workbook <code>.xlsx</code>/<code>.xlsm</code> che si leggono e si modificano senza perdere ciò che non si è scritto: <code>excelSource</code> (uno o più fogli, a flusso), <code>excelSink</code> (<code>append</code>, <code>upsert</code> per chiave, <code>replace</code>; fogli nuovi, formati, formule, modelli) ed <code>excelTask</code> (fogli e colonne), più la transform <code>excelValidate</code>. Solo storage <code>filesystem</code> per scrivere. Vedi la <a href="./connectors/excel">scheda</a> e l'ADR-0110.</li><li><strong>File</strong> (<code>file</code>) — architettura a due assi componibili: <ul><li><em>storage</em>: dove vivono i file (locale, <strong>S3</strong>, <strong>SFTP</strong>, <strong>FTP/FTPS</strong>);</li><li><em>codec</em>: come si (de)serializzano — <strong>CSV</strong> (anche grezzo, <code>csvRawCodec</code>), <strong>JSON/NDJSON</strong>, <strong>XML</strong>, <strong>XLSX</strong>, <strong>Parquet</strong>. Storage e codec si combinano liberamente (es. CSV su S3, Parquet su SFTP).</li></ul></li><li><strong>Noeva</strong> (<code>noeva</code>) — file dei workspace Noeva via noeva-server-api: lettura di un file o di una cartella intera, scrittura di uno o più file in <code>overwrite</code> o <code>new-version</code>, upload con elaborazione AI (<code>noevaUploadAction</code>), lookup su stato e testo estratto ed estrazione AI di campi strutturati (<code>noevaAiExtract</code>, nodo <code>ai</code>).</li><li><strong>IMAP</strong> (<code>imap</code>) — caselle di posta: <code>imapSource</code> legge i messaggi di una cartella (allegati ed EML grezzo), le action <code>imapFlagAction</code> e <code>imapSpostaAction</code> marcano e spostano, con la cartella come coda.</li><li><strong>SMTP</strong> (<code>smtp</code>) — notifiche email: <code>smtpAction</code> e <code>smtpSink</code> inviano una mail costruita da una funzione del record, con Message-ID deterministico contro i doppioni.</li><li><strong>SendGrid</strong> (<code>sendgrid</code>) — mail via API REST v3: <code>sendgridAction</code> e <code>sendgridSink</code>, con la stessa mail di SMTP (<code>MailInUscita</code>), sandbox per le prove, retry di <code>429</code> e <code>5xx</code>; <code>mailAction</code> e <code>mailSink</code> (<code>mail</code>) scelgono fra SMTP e SendGrid da configurazione.</li><li><strong>HTTP</strong> (<code>http</code>) — API REST per i nodi <code>lookup</code> e <code>action</code>: <code>httpLookup</code> legge in sola lettura, una richiesta per batch o una <code>GET</code> per chiave, <code>httpAction</code> scrive e prosegue con l'esito; la risposta è validata da uno schema Zod e le credenziali vengono dal registry <code>HTTP_INSTANCES</code>. Il loro trasporto, <code>richiestaHttp</code>, è condiviso con i connettori REST di dominio, come Jira.</li><li><strong>Jira Cloud</strong> (<code>jira</code>) — <code>jiraIssues</code> legge le issue di una JQL, pagina dopo pagina, con i siti nel registry <code>JIRA_INSTANCES</code>; i campi si dichiarano per id o per nome e diventano colonne normalizzate, con gli ADF convertiti in testo. <code>jiraIssueLookup</code> legge le stesse issue per chiave, e <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code> e <code>jiraWorklogsLookup</code> danno a ogni issue la sua lista completa. <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code> (per ID esterno), <code>jiraAddComment</code> e <code>jiraAddWorklog</code> (con una chiave di deduplica obbligatoria) e <code>jiraLinkIssues</code> scrivono come nodi <code>action</code>, con l'esito come dato.</li><li><strong>Zoho CRM</strong> (<code>zoho</code>) — <code>zohoCrmRecords</code> legge i record di un modulo con i soli campi dichiarati, che sono anche la regola di privacy, in ordine di <code>id</code>: con la Records API fino a 100.000 record, con la Query API (COQL) a chiavi crescenti di <code>id</code> oltre. Le organizzazioni stanno nel registry <code>ZOHO_INSTANCES</code>, il token lo rinnova un'identità OAuth2 e il trasporto è quello condiviso di <code>http</code>.</li><li><strong>Odoo</strong> (<code>odoo</code>) — <code>odooRecords</code> legge i record di un modello con i soli campi dichiarati, a pagine in ordine di <code>id</code>, e <code>odooConteggi</code> i <code>search_count</code> da confrontare con le righe caricate. Solo metodi di lettura, al più una chiamata al secondo per database e mai due in parallelo (Acceptable Use Policy di Odoo); XML-RPC oggi, JSON-2 con Odoo 19. I database stanno nel registry <code>ODOO_INSTANCES</code>.</li><li><strong>Processo esterno</strong> (<code>process</code>) — <code>processoEsternoAction</code> lancia un programma per record, senza shell, in una cartella temporanea sempre cancellata: i file del record entrano, i file di <code>uscita/</code> e un riepilogo JSON validato con Zod escono. Ambiente da allowlist e timeout obbligatorio.</li><li><strong>OAuth2</strong> (<code>oauth</code>) — non un connettore ma l'<strong>identità</strong> che IMAP e SMTP usano dove la password non basta più (Gmail, Workspace, Microsoft 365), e con cui Zoho CRM autentica le sue richieste: tiene il refresh token e ne scambia uno nuovo quando l'access token scade, con un registry proprio <code>OAUTH_INSTANCES</code>.</li></ul><p>Le schede, con configurazione e variabili d'ambiente di ognuno, sono in <a href="./connectors/README">Connettori</a>.</p><p><strong>Trasformazioni riusabili</strong>, dalla radice del pacchetto: <code>groupBy</code> (aggregazione stateful generica init/reduce/finalize), <code>dedup</code> (duplicati per chiave), <code>mapColumns</code> (select, rename, cast e colonne calcolate, con lineage di colonna) e <code>castValue</code> (i suoi cast stretti, usabili da soli), <code>explode</code> (un campo array → un record per elemento), <code>unpivot</code> e <code>pivot</code> (dal formato largo al lungo e ritorno, con colonne dichiarate), <code>sort</code> (ordinamento stabile su più chiavi), <code>chunk</code> (record in lotti di N per un sink o un'API con limite di payload), <code>parse</code> (byte di un file → righe, con un <code>FileCodec</code>) e <code>serialize</code> (record → un file per gruppo, stateful), <code>hashRow</code> e <code>surrogateKey</code> (hash di riga e chiave surrogata deterministici), <code>mask</code> (mascheramento e pseudonimizzazione delle colonne con dati personali), <code>profile</code> (profilo delle colonne nel report del nodo, a memoria costante), <code>assert</code> (controlli sul dataset a fine stream). Il catalogo completo è in <a href="./nodes/transform#transform-pronte">transform</a>.</p><p><strong>Pipeline d'esempio</strong>, con la loro scheda nella sezione «Esempi» di questa guida:</p><ul><li><a href="./pipelines/orders-enriched-daily"><code>orders-enriched-daily</code></a> — dataset demo in memoria, esempio di riferimento per una pipeline <strong>a grafo</strong>: due sorgenti, join a chiave, fan-out su due sink, dead-letter isolato su due nodi indipendenti, try/catch e un'istanza della sub-pipeline <a href="./sub-pipelines/riepilogo-ordini"><code>riepilogo-ordini</code></a>.</li><li><a href="./pipelines/movimenti-per-conto"><code>movimenti-per-conto</code></a> — dataset demo in memoria, esempio di riferimento per le transform di file e di ordinamento in mezzo al grafo: <code>parse</code>, <code>sort</code> e <code>serialize</code>, da estratti conto CSV a un CSV per conto.</li><li><a href="./pipelines/crm-leads-sync"><code>crm-leads-sync</code></a> — copia fra due istanze Postgres dello stesso registry, con un try/catch per record.</li><li><a href="./pipelines/cross-workspace-csv-merge"><code>cross-workspace-csv-merge</code></a> — merge di un CSV fra due workspace Noeva, con un <code>union</code> e la scrittura in <code>new-version</code> su entrambi.</li></ul><p><strong>Pipeline pronte</strong>, da dichiarare nel catalogo: <a href="./pipelines/test-posta"><code>test-posta</code></a>, la prova dei connettori IMAP e SMTP di un'installazione.</p><h2 id="_7-i-comandi" tabindex="-1">7. I comandi <a class="header-anchor" href="#_7-i-comandi" aria-label="Permalink to "7. I comandi""></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:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # in una cartella vuota: il boilerplate di un repo cliente</span></span>
|
|
36
36
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ci</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # il gate completo del repo, lo stesso della CI</span></span>
|
|
37
37
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sync</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # riscrive il kit dell'agente dal core installato (§10)</span></span>
|
|
38
38
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> upgrade</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --check</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # versione installata e ultima, changelog e deriva dei file gestiti</span></span>
|
|
@@ -0,0 +1,10 @@
|
|
|
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 "noeva-etl — Technical Overview""></a></h1><blockquote><p>Documento condivisibile. Spiega <strong>cos'è</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 "1. In una frase""></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'integrazione con l'orchestrazione job del prodotto) e <strong>server + daemon</strong> (<code>etl serve</code>, il default dell'immagine: espone i grafi e le run all'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 "2. Per cosa è stato pensato""></a></h2><p>Sostituire l'approccio "ETL a scatola nera" (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'unica immagine container gira sull'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'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 "3. Cosa può fare oggi""></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<T></code> (estrazione), <code>Transform<I,O></code> (trasformazione), <code>Sink<T></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'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>MySQL e MariaDB</strong> (streaming + <code>ON DUPLICATE KEY UPDATE</code> + lookup + task SQL), <strong>file</strong> (filesystem/S3/SFTP/FTP × CSV/JSON/XML/XLSX/Parquet), <strong>Excel</strong> (<code>excelSource</code>, <code>excelSink</code> con <code>append</code>/<code>upsert</code>/<code>replace</code> e <code>excelTask</code>: modifica workbook <code>.xlsx</code>/<code>.xlsm</code> conservando grafici, pivot e macro, solo su filesystem), <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>Odoo</strong> (<code>odooRecords</code>: i record di un modello con i soli campi dichiarati, in ordine di <code>id</code>, via XML-RPC in sola lettura, al più una chiamata al secondo; <code>odooConteggi</code> per i controlli), <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 & container</strong></td><td><code>etl list</code> / <code>etl run <pipeline></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 "4. Come funziona (architettura)""></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'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 ≥ 26, <code>pnpm</code>, <code>tsup</code>, <code>vitest</code>, ESLint/Prettier, Zod. Dipendenze runtime: i driver dei database (<code>pg</code>, <code>mssql</code>, <code>mysql2</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 "5. Come si usa e si distribuisce""></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
|
+
<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
|
+
<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;"> <</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;">></span></span>
|
|
4
|
+
<span class="line"></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># server + daemon: grafi e run via HTTP per l'app desktop, più i worker</span></span>
|
|
6
|
+
<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;"> serve</span></span>
|
|
7
|
+
<span class="line"></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># solo daemon: polling continuo su processes (worker_type da env; uno o più</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># workspace — NOEVA_WORKSPACE_IDS per il multi-workspace)</span></span>
|
|
10
|
+
<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;"> worker</span></span></code></pre></div><ul><li><strong>Configurazione solo da variabili d'ambiente</strong> (<code>PG*</code>, <code>MSSQL_*</code>, <code>MYSQL_*</code>, <code>ETL_ENV</code>, …); <strong>nessun segreto</strong> nel codice o nell'immagine.</li><li><strong>Tre modalità di invocazione</strong>: <strong>batch</strong> (<code>etl run</code>, un container = una esecuzione, poi termina — vedi <a href="./runbooks/deployment">il deploy</a>); <strong>daemon</strong> (<code>etl worker</code>, resta in polling su <code>processes</code> finché non riceve <code>SIGTERM</code>/<code>SIGINT</code> — vedi <a href="./runbooks/etl-worker">il worker</a>); <strong>server + daemon</strong> (<code>etl serve</code>, il <code>CMD</code> di default dell'immagine: un solo container per tutta la piattaforma — vedi <a href="./runbooks/graph-server"><code>etl serve</code></a>).</li><li><strong>App desktop</strong> <code>noeva-etl-ui</code>: si distribuisce come applicazione Tauri, uguale per tutti i deploy.</li><li><strong>Modello di deploy</strong>: il deploy esegue un repo cliente, come immagine container o sotto PM2 dai sorgenti. Vedi <a href="./runbooks/deployment">il deploy</a>.</li></ul><h2 id="_6-il-report-di-run-e-il-prodotto" tabindex="-1">6. Il report di run è il "prodotto" <a class="header-anchor" href="#_6-il-report-di-run-e-il-prodotto" aria-label="Permalink to "6. Il report di run è il "prodotto"""></a></h2><p>Il nucleo di esecuzione <strong>non persiste nulla</strong>: esegue e <strong>restituisce un risultato completo</strong>. È il chiamante a conservarlo: la CLI tiene le ultime run in locale (<code>etl runs list</code>), il worker lo scrive nel job Noeva, ed <code>etl serve</code> conserva nello stesso storico locale le run tracciate che lancia lui.</p><ul><li><strong><code>stdout</code></strong> = report in JSON (un oggetto, parsabile con <code>jq</code>); <strong><code>stderr</code></strong> = log.</li><li><strong>exit code</strong>: <code>0</code> se <code>success</code>/<code>partial</code>, <code>≠0</code> se <code>failed</code>.</li><li><strong>Anche in errore</strong> emette un report (<code>status: failed</code>) con dettagli e conteggi parziali.</li><li>Contiene: stato, tempi, versione, topologia reale del grafo (nodi e archi, con i conteggi e i tempi di ogni nodo), parametri, volumi (<code>extracted</code>/<code>written</code>/<code>rejected</code>), <strong>categorie di scarto</strong>, metriche, errore — <strong>senza segreti né payload/PII</strong>.</li></ul><p>Chi invoca decide cosa farne (archiviarlo, mandarlo in alert, ignorarlo). Vedi <a href="./conventions/run-report">run-report.md</a>.</p><h2 id="_7-come-si-espande" tabindex="-1">7. Come si espande <a class="header-anchor" href="#_7-come-si-espande" aria-label="Permalink to "7. Come si espande""></a></h2><p>Crescita <strong>per composizione</strong>, senza toccare il core. Comandi di scaffold coerenti generano struttura + test + doc:</p><ul><li><strong>Nuova pipeline</strong> → <code>/new-pipeline <nome></code> (schema, definizione, changelog, snapshot del piano, run, test, scheda doc).</li><li><strong>Nuovo connettore</strong> → <code>/new-connector <nome> [source|sink]</code> (verso un nuovo sistema: API, file/CSV, altri DB, code…).</li><li><strong>Nuova trasformazione</strong> → <code>/new-transform <nome></code> (logica riusabile, pura e testabile).</li></ul><p>Aggiungere un sistema = scrivere un <code>Source</code>/<code>Sink</code> che rispetta l'interfaccia; tutte le pipeline esistenti possono usarlo subito (DI). La logica di dominio vive nelle trasformazioni, riusabili tra pipeline.</p><h2 id="_8-perche-ci-si-puo-fidare-governance" tabindex="-1">8. Perché ci si può fidare (governance) <a class="header-anchor" href="#_8-perche-ci-si-puo-fidare-governance" aria-label="Permalink to "8. Perché ci si può fidare (governance)""></a></h2><ul><li><strong>Test obbligatori</strong> con soglie di coverage come <strong>gate di CI</strong> (GitHub Actions).</li><li><strong>Documentazione nello stesso commit</strong> del codice (schede pipeline, runbook, decisioni), e <code>etl docs build</code> che non costruisce il sito con una scheda o uno scopo mancante o un link rotto.</li><li><strong>Decisioni tracciate</strong>: il core e ogni repo cliente registrano le loro scelte strutturali.</li><li><strong>Assistenti di qualità</strong> versionati nel kit dell'agente: review ETL, audit dei contratti, sync della doc, autore dei test. Vedi <a href="./guide/claude-code/strumenti">Skill e subagent</a>.</li></ul><h2 id="_9-direzione-del-prodotto-chiara-e-semplice" tabindex="-1">9. Direzione del prodotto (chiara e semplice) <a class="header-anchor" href="#_9-direzione-del-prodotto-chiara-e-semplice" aria-label="Permalink to "9. Direzione del prodotto (chiara e semplice)""></a></h2><blockquote><p><strong>Un motore ETL piccolo, code-first e agnostico, che esegue pipeline affidabili e restituisce un risultato completo — e cresce per connettori e pipeline, non per complessità.</strong></p></blockquote><p>Principi guida (stabili):</p><ol><li><strong>Semplice e stateless</strong> — il servizio è una funzione <code>pipeline + config → report</code>.</li><li><strong>Agnostico</strong> — nessun DB interno, nessun cloud obbligato, nessun push integrato.</li><li><strong>Code-first</strong> — niente builder grafici; le pipeline restano codice testato e documentato.</li><li><strong>Portabile</strong> — un'immagine, eseguibile ovunque, configurata da env.</li><li><strong>Espandibile per composizione</strong> — nuovi connettori/trasformazioni/pipeline, core stabile.</li></ol><h3 id="cosa-non-e-non-obiettivi-per-scelta" tabindex="-1">Cosa NON è (non-obiettivi, per scelta) <a class="header-anchor" href="#cosa-non-e-non-obiettivi-per-scelta" aria-label="Permalink to "Cosa NON è (non-obiettivi, per scelta)""></a></h3><ul><li>❌ Non è un <strong>pipeline builder</strong> grafico: l'app desktop <code>noeva-etl-ui</code> mostra i DAG e le run, ma le pipeline si scrivono in codice.</li><li>❌ Non è uno <strong>strumento di visualizzazione BI</strong> (per i grafici si collega Metabase/Grafana/Power BI alle tabelle prodotte).</li><li>❌ Non possiede un <strong>database di stato</strong> (storico/audit = archiviazione dei report, a cura del chiamante). Lo stato di pipeline delle source incrementali, cioè i loro watermark, vive in uno store che il chiamante inietta: <code>noeva-server-api</code> per il worker, un file locale per la CLI.</li></ul><h3 id="evoluzioni-possibili-senza-tradire-i-principi" tabindex="-1">Evoluzioni possibili (senza tradire i principi) <a class="header-anchor" href="#evoluzioni-possibili-senza-tradire-i-principi" aria-label="Permalink to "Evoluzioni possibili (senza tradire i principi)""></a></h3><ul><li><strong>Scheduling</strong> esterno (cron / ECS Scheduled Task) — l'idempotenza rende sicure retry e sovrapposizioni.</li><li><strong>Nuovi connettori</strong> (data warehouse, code di messaggi) e nuovi resolver per il nodo <code>lookup</code> (oggi PostgreSQL, SQL Server, Noeva, API REST con <code>httpLookup</code> e Jira Cloud con <code>jiraIssueLookup</code> e i lookup delle liste Jira; un nuovo DBMS riusa <code>connectors/shared/sql-lookup.ts</code>).</li><li><strong>Orchestrazione</strong> per dipendenze/backfill complessi (es. Temporal TS), solo se e quando servirà.</li><li><strong>Persistenza opzionale dei report</strong> come <em>adapter</em> lato chiamante, mai dentro il servizio.</li></ul><hr><p><em>Riferimenti: <a href="./GUIDA_SVILUPPO">guida allo sviluppo</a> · <a href="./connectors/README">connettori</a> · <a href="./conventions/run-report">report di run</a> · <a href="./runbooks/deployment">deployment</a> · <a href="./runbooks/etl-worker">etl worker</a> · <a href="./runbooks/graph-server">etl serve</a>.</em></p>`,25))])}const k=t(c,[["render",d]]);export{v as __pageData,k as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{t as p}from"./chunks/theme.
|
|
1
|
+
import{t as p}from"./chunks/theme.CRpFq7vp.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};
|