@noeva/etl-core 1.0.0 → 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.
Files changed (212) hide show
  1. package/CHANGELOG.md +137 -0
  2. package/README.md +6 -11
  3. package/deploy/Dockerfile +2 -1
  4. package/dist/{ai-BoTwcmUg.d.ts → ai-DyDIf-hQ.d.ts} +1 -1
  5. package/dist/{ambiente-della-pipeline-BoymQ6uN.d.ts → ambiente-della-pipeline-BhWsyLUR.d.ts} +2 -2
  6. package/dist/chunk-47NVGHUY.js +2 -0
  7. package/dist/chunk-5OE6F2MK.js +2 -0
  8. package/dist/{chunk-NZR6TZ42.js → chunk-5XVANFXO.js} +1 -1
  9. package/dist/chunk-672L5BGQ.js +1 -0
  10. package/dist/{chunk-4NPSBPBY.js → chunk-6QVYBDIS.js} +1 -1
  11. package/dist/{chunk-PE2QKU34.js → chunk-CEAMQIRO.js} +1 -1
  12. package/dist/chunk-DHQ3YOPX.js +5 -0
  13. package/dist/chunk-FBSNZG34.js +1 -0
  14. package/dist/{chunk-J3PBMWSP.js → chunk-GZWYRO3V.js} +1 -1
  15. package/dist/chunk-IODXIHU2.js +1 -0
  16. package/dist/{chunk-P6B2KLNJ.js → chunk-KEFIGSRS.js} +2 -2
  17. package/dist/chunk-KGWA46Y6.js +2 -0
  18. package/dist/chunk-L25W2QNS.js +1 -0
  19. package/dist/{chunk-JLPK6MMQ.js → chunk-OK3XRTGA.js} +1 -1
  20. package/dist/chunk-UHGHK6NP.js +1 -0
  21. package/dist/chunk-VL7DZWWO.js +2 -0
  22. package/dist/chunk-VVXT66DC.js +1 -0
  23. package/dist/chunk-ZKDCUSM2.js +6 -0
  24. package/dist/cli.js +2 -2
  25. package/dist/{client-DYA3wIyb.d.ts → client-BC_mLuT2.d.ts} +2 -2
  26. package/dist/config-BSdGSRPG.d.ts +37 -0
  27. package/dist/{config-BSUwK4p_.d.ts → config-DMafsY4H.d.ts} +3 -3
  28. package/dist/connector-kit.d.ts +14 -9
  29. package/dist/connector-kit.js +1 -1
  30. package/dist/connectors/excel.d.ts +391 -0
  31. package/dist/connectors/excel.js +10 -0
  32. package/dist/connectors/file.d.ts +12 -5
  33. package/dist/connectors/file.js +1 -1
  34. package/dist/connectors/http.d.ts +7 -7
  35. package/dist/connectors/http.js +1 -1
  36. package/dist/connectors/imap.d.ts +6 -6
  37. package/dist/connectors/imap.js +1 -1
  38. package/dist/connectors/jira.d.ts +6 -6
  39. package/dist/connectors/jira.js +2 -2
  40. package/dist/connectors/mail.d.ts +7 -7
  41. package/dist/connectors/mail.js +1 -1
  42. package/dist/connectors/mysql.d.ts +238 -0
  43. package/dist/connectors/mysql.js +2 -0
  44. package/dist/connectors/noeva.d.ts +6 -6
  45. package/dist/connectors/noeva.js +1 -1
  46. package/dist/connectors/oauth.d.ts +5 -5
  47. package/dist/connectors/oauth.js +1 -1
  48. package/dist/connectors/odoo.d.ts +309 -0
  49. package/dist/connectors/odoo.js +3 -0
  50. package/dist/connectors/postgres.d.ts +7 -6
  51. package/dist/connectors/postgres.js +1 -1
  52. package/dist/connectors/process.d.ts +1 -1
  53. package/dist/connectors/process.js +1 -1
  54. package/dist/connectors/sendgrid.d.ts +7 -7
  55. package/dist/connectors/sendgrid.js +1 -1
  56. package/dist/connectors/smtp.d.ts +8 -8
  57. package/dist/connectors/smtp.js +1 -1
  58. package/dist/connectors/sqlserver.d.ts +7 -6
  59. package/dist/connectors/sqlserver.js +1 -1
  60. package/dist/connectors/zoho.d.ts +6 -6
  61. package/dist/connectors/zoho.js +1 -1
  62. package/dist/contract.d.ts +2 -2
  63. package/dist/{credenziali-posta-f7HB2cYW.d.ts → credenziali-posta-C0az04uV.d.ts} +2 -2
  64. package/dist/{errors-bgSO6lGO.d.ts → errors-CRq1uNYZ.d.ts} +8 -1
  65. package/dist/etl.config.js +3 -3
  66. package/dist/guida/404.html +2 -2
  67. package/dist/guida/GUIDA_SVILUPPO.html +7 -7
  68. package/dist/guida/TECHNICAL_OVERVIEW.html +7 -7
  69. package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.js → GUIDA_SVILUPPO.md.Bvr7RKHN.js} +2 -2
  70. package/dist/guida/assets/TECHNICAL_OVERVIEW.md.C6HYc5_h.js +10 -0
  71. package/dist/guida/assets/{app.DlsuGVZn.js → app.zL1wgTBx.js} +1 -1
  72. package/dist/guida/assets/chunks/@localSearchIndexroot.B5GjWddx.js +1 -0
  73. package/dist/guida/assets/chunks/{VPLocalSearchBox.v4vBLemj.js → VPLocalSearchBox.BSMd0tSF.js} +1 -1
  74. package/dist/guida/assets/chunks/{theme.D9XEK7o0.js → theme.CRpFq7vp.js} +2 -2
  75. package/dist/guida/assets/connectors_README.md.B5QWzWUK.js +1 -0
  76. package/dist/guida/assets/connectors_README.md.B5QWzWUK.lean.js +1 -0
  77. package/dist/guida/assets/connectors_excel.md.CqGtwEB4.js +92 -0
  78. package/dist/guida/assets/connectors_excel.md.CqGtwEB4.lean.js +1 -0
  79. package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.js → connectors_file.md.Dbofo9W5.js} +3 -3
  80. package/dist/guida/assets/{connectors_file.md.B1NJe0VJ.lean.js → connectors_file.md.Dbofo9W5.lean.js} +1 -1
  81. package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.js +34 -0
  82. package/dist/guida/assets/connectors_mysql.md.fVCxQWUW.lean.js +1 -0
  83. package/dist/guida/assets/connectors_odoo.md.DprabV5e.js +19 -0
  84. package/dist/guida/assets/connectors_odoo.md.DprabV5e.lean.js +1 -0
  85. package/dist/guida/assets/{conventions_node-descriptor.md.MQaGlm8a.js → conventions_node-descriptor.md.C19dB-Tb.js} +4 -4
  86. package/dist/guida/assets/conventions_node-descriptor.md.C19dB-Tb.lean.js +1 -0
  87. package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.js → conventions_run-report.md.iVSN9fNV.js} +1 -1
  88. package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.js → conventions_versioni-di-pipeline.md.DJPSthZ8.js} +1 -1
  89. package/dist/guida/assets/{conventions_versioni-di-pipeline.md.cy5nsizS.lean.js → conventions_versioni-di-pipeline.md.DJPSthZ8.lean.js} +1 -1
  90. package/dist/guida/assets/{nodes_README.md.CHGy_go6.js → nodes_README.md.BNAiSoJJ.js} +2 -2
  91. package/dist/guida/assets/{nodes_README.md.CHGy_go6.lean.js → nodes_README.md.BNAiSoJJ.lean.js} +1 -1
  92. package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.js → nodes_lookup.md.DrJFsfOJ.js} +1 -1
  93. package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.js → nodes_sink.md.C1S-lAh2.js} +2 -2
  94. package/dist/guida/assets/{nodes_source.md.DP2i3GFv.js → nodes_source.md.BitUNtug.js} +2 -2
  95. package/dist/guida/assets/{nodes_task.md.Dk6VB7as.js → nodes_task.md.CejEQZcD.js} +2 -2
  96. package/dist/guida/assets/{nodes_task.md.Dk6VB7as.lean.js → nodes_task.md.CejEQZcD.lean.js} +1 -1
  97. package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.js → nodes_transform.md.Ciycywnb.js} +1 -1
  98. package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.js → runbooks_deployment.md.BV8Izw4I.js} +1 -1
  99. package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.js +16 -0
  100. package/dist/guida/assets/runbooks_excel-operazioni-distruttive.md.CEygSROg.lean.js +1 -0
  101. package/dist/guida/assets/{runbooks_sql-task-truncate-swap.md.C8viT-fp.js → runbooks_sql-task-truncate-swap.md.DAz41942.js} +5 -3
  102. 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
  103. package/dist/guida/connectors/README.html +5 -5
  104. package/dist/guida/connectors/excel.html +118 -0
  105. package/dist/guida/connectors/file.html +7 -7
  106. package/dist/guida/connectors/http.html +4 -4
  107. package/dist/guida/connectors/imap.html +4 -4
  108. package/dist/guida/connectors/jira.html +5 -5
  109. package/dist/guida/connectors/mysql.html +60 -0
  110. package/dist/guida/connectors/noeva.html +5 -5
  111. package/dist/guida/connectors/oauth.html +5 -5
  112. package/dist/guida/connectors/odoo.html +45 -0
  113. package/dist/guida/connectors/postgres.html +5 -5
  114. package/dist/guida/connectors/process.html +4 -4
  115. package/dist/guida/connectors/sendgrid.html +4 -4
  116. package/dist/guida/connectors/smtp.html +4 -4
  117. package/dist/guida/connectors/sqlserver.html +4 -4
  118. package/dist/guida/connectors/zoho.html +4 -4
  119. package/dist/guida/conventions/node-columns.html +4 -4
  120. package/dist/guida/conventions/node-descriptor.html +8 -8
  121. package/dist/guida/conventions/run-report.html +6 -6
  122. package/dist/guida/conventions/run-trace.html +4 -4
  123. package/dist/guida/conventions/variabili-del-core.html +4 -4
  124. package/dist/guida/conventions/versioni-di-pipeline.html +6 -6
  125. package/dist/guida/guide/claude-code/index.html +4 -4
  126. package/dist/guida/guide/claude-code/prompt.html +5 -5
  127. package/dist/guida/guide/claude-code/strumenti.html +4 -4
  128. package/dist/guida/guide/grafo.html +4 -4
  129. package/dist/guida/guide/usare/app-desktop.html +4 -4
  130. package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
  131. package/dist/guida/guide/usare/index.html +4 -4
  132. package/dist/guida/hashmap.json +1 -1
  133. package/dist/guida/index.html +4 -4
  134. package/dist/guida/nodes/README.html +5 -5
  135. package/dist/guida/nodes/action.html +4 -4
  136. package/dist/guida/nodes/ai.html +4 -4
  137. package/dist/guida/nodes/join.html +4 -4
  138. package/dist/guida/nodes/lookup.html +6 -6
  139. package/dist/guida/nodes/pipeline.html +4 -4
  140. package/dist/guida/nodes/route.html +4 -4
  141. package/dist/guida/nodes/sink.html +7 -7
  142. package/dist/guida/nodes/source.html +7 -7
  143. package/dist/guida/nodes/task.html +6 -6
  144. package/dist/guida/nodes/transform.html +6 -6
  145. package/dist/guida/nodes/try-catch.html +4 -4
  146. package/dist/guida/nodes/union.html +4 -4
  147. package/dist/guida/pagine.json +4 -0
  148. package/dist/guida/pipelines/README.html +4 -4
  149. package/dist/guida/pipelines/crm-leads-sync.html +4 -4
  150. package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
  151. package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
  152. package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
  153. package/dist/guida/pipelines/test-posta.html +4 -4
  154. package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
  155. package/dist/guida/runbooks/deploy-ecr.html +4 -4
  156. package/dist/guida/runbooks/deployment.html +6 -6
  157. package/dist/guida/runbooks/etl-worker.html +5 -5
  158. package/dist/guida/runbooks/excel-operazioni-distruttive.html +42 -0
  159. package/dist/guida/runbooks/graph-server.html +5 -5
  160. package/dist/guida/runbooks/mask-key.html +4 -4
  161. package/dist/guida/runbooks/oauth-google-posta.html +4 -4
  162. package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
  163. package/dist/guida/runbooks/scd2-rehash.html +4 -4
  164. package/dist/guida/runbooks/sql-task-truncate-swap.html +8 -6
  165. package/dist/guida/runbooks/stato-incrementale.html +4 -4
  166. package/dist/guida/sub-pipelines/README.html +4 -4
  167. package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
  168. package/dist/index.d.ts +9 -9
  169. package/dist/index.js +1 -1
  170. package/dist/{invio-Dwz3J7sP.d.ts → invio-9Ubb_cdR.d.ts} +3 -3
  171. package/dist/{istanza-per-il-piano-CucqUF7b.d.ts → istanza-per-il-piano-74NYhIHc.d.ts} +1 -1
  172. package/dist/{manifest-variabili-U1UfPDfF.d.ts → manifest-variabili-DRWUzmxU.d.ts} +1 -1
  173. package/dist/pipelines.d.ts +3 -3
  174. package/dist/pipelines.js +1 -1
  175. package/dist/{runnable-pipeline-CArkLzfv.d.ts → runnable-pipeline-CWgPwi6w.d.ts} +2 -2
  176. package/dist/{config-DIthC7n7.d.ts → sql-watermark-CQVvxhPZ.d.ts} +9 -40
  177. package/dist/testing.d.ts +3 -3
  178. package/dist/testing.js +1 -1
  179. package/dist/{trasporto-DpPLCEQ1.d.ts → trasporto-BaRdP6Wl.d.ts} +4 -4
  180. package/dist/{types-BVA7BIou.d.ts → types-_3rgLhje.d.ts} +21 -2
  181. package/dist/{variabili-dichiarate-DmfcxsT9.d.ts → variabili-dichiarate-CS-eC53K.d.ts} +1 -1
  182. package/kit/skills/etl-graph/SKILL.md +6 -3
  183. package/kit/skills/etl-graph/references/data-patterns.md +1 -1
  184. package/kit/skills/etl-graph/references/error-handling.md +3 -3
  185. package/kit/skills/etl-graph/references/wiring.md +10 -10
  186. package/kit/skills/new-connector/SKILL.md +2 -2
  187. package/package.json +16 -1
  188. package/dist/chunk-BVUOUBLW.js +0 -1
  189. package/dist/chunk-CRR3Q2C7.js +0 -2
  190. package/dist/chunk-LJ7DVP5F.js +0 -2
  191. package/dist/chunk-PKBSETMV.js +0 -2
  192. package/dist/chunk-QPJC4GWR.js +0 -1
  193. package/dist/chunk-RCRMQPFH.js +0 -5
  194. package/dist/chunk-RS5SGDUU.js +0 -1
  195. package/dist/chunk-RWPHH4E2.js +0 -1
  196. package/dist/chunk-SRFFKE5W.js +0 -6
  197. package/dist/chunk-WVODQB6Z.js +0 -1
  198. package/dist/chunk-XZMCC6VQ.js +0 -1
  199. package/dist/chunk-ZCYGHS7P.js +0 -2
  200. package/dist/guida/assets/TECHNICAL_OVERVIEW.md.DTIhkkg9.js +0 -10
  201. package/dist/guida/assets/chunks/@localSearchIndexroot.LnC621Vy.js +0 -1
  202. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +0 -1
  203. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +0 -1
  204. package/dist/guida/assets/conventions_node-descriptor.md.MQaGlm8a.lean.js +0 -1
  205. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.CrN52ZDN.lean.js → GUIDA_SVILUPPO.md.Bvr7RKHN.lean.js} +0 -0
  206. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DTIhkkg9.lean.js → TECHNICAL_OVERVIEW.md.C6HYc5_h.lean.js} +0 -0
  207. /package/dist/guida/assets/{conventions_run-report.md.D_pG07VG.lean.js → conventions_run-report.md.iVSN9fNV.lean.js} +0 -0
  208. /package/dist/guida/assets/{nodes_lookup.md.BI8tgBIq.lean.js → nodes_lookup.md.DrJFsfOJ.lean.js} +0 -0
  209. /package/dist/guida/assets/{nodes_sink.md.yAf_z4wO.lean.js → nodes_sink.md.C1S-lAh2.lean.js} +0 -0
  210. /package/dist/guida/assets/{nodes_source.md.DP2i3GFv.lean.js → nodes_source.md.BitUNtug.lean.js} +0 -0
  211. /package/dist/guida/assets/{nodes_transform.md.Bv5fg2Xx.lean.js → nodes_transform.md.Ciycywnb.lean.js} +0 -0
  212. /package/dist/guida/assets/{runbooks_deployment.md.CwG77qGO.lean.js → runbooks_deployment.md.BV8Izw4I.lean.js} +0 -0
@@ -0,0 +1,92 @@
1
+ import{_ as o,o as i,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Excel","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/excel.md","filePath":"connectors/excel.md"}'),s={name:"connectors/excel.md"};function n(l,e,r,c,d,p){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="excel" tabindex="-1">Excel <a class="header-anchor" href="#excel" aria-label="Permalink to &quot;Excel&quot;">​</a></h1><p>Il connettore Excel legge e scrive <strong>workbook</strong> <code>.xlsx</code> e <code>.xlsm</code>, e modifica quelli che qualcuno ha già rifinito a mano senza perdere ciò che non ha scritto. Subpath <code>@noeva/etl-core/connectors/excel</code>, tre nodi:</p><table tabindex="0"><thead><tr><th>Nodo</th><th>Che cosa fa</th></tr></thead><tbody><tr><td><code>excelSource</code></td><td>Legge uno o più fogli, a flusso, con le colonne abbinate per titolo.</td></tr><tr><td><code>excelSink</code></td><td>Crea e aggiorna workbook: <code>append</code>, <code>upsert</code> per chiave, <code>replace</code>; fogli nuovi, colonne nuove, formati, formule.</td></tr><tr><td><code>excelTask</code></td><td>Operazioni strutturali senza record su fogli e colonne (riordina, rinomina, cancella, inserisci), con i riferimenti.</td></tr></tbody></table><p>Più la transform <code>excelValidate</code>, gli stessi controlli del sink record per record. Lavora solo con lo storage <code>filesystem</code> (vedi «Che cosa non si copre»). Decisioni: ADR-0110 (il motore), ADR-0111 (modalità e <code>retrySafe</code>), ADR-0112 (scrittura atomica).</p><p>Vocabolario: <em>workbook</em> (il file), <em>foglio</em> (una tabella con nome), <em>riga d&#39;intestazione</em> (la riga che dà un titolo a ogni colonna). Vedi <code>CONTEXT.md</code>, sezione «File Excel».</p><h2 id="excelsource" tabindex="-1"><code>excelSource</code> <a class="header-anchor" href="#excelsource" aria-label="Permalink to &quot;\`excelSource\`&quot;">​</a></h2><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { filesystemStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
2
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { excelSource } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/excel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
3
+ <span class="line"></span>
4
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> source</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> excelSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">filesystemStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ baseDir: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }), {</span></span>
5
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ordini.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
6
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Ordini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
7
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> columns: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Cliente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Importo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Data&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
8
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Lo storage è quello del <a href="./file">connettore file</a>: il source riceve i byte da lì (legge da qualunque storage del connettore file; è il sink a volere il filesystem).</p><table tabindex="0"><thead><tr><th>Opzione</th><th>Significato</th></tr></thead><tbody><tr><td><code>path</code></td><td>Il workbook da leggere. Serve <code>path</code> <strong>oppure</strong> <code>prefix</code>, non entrambi.</td></tr><tr><td><code>prefix</code></td><td>Legge in sequenza tutti i <code>.xlsx</code>/<code>.xlsm</code> sotto il prefisso (i lock <code>~$…</code> si saltano).</td></tr><tr><td><code>sheet</code></td><td>Il foglio, per nome, senza distinguere maiuscole e minuscole. Serve <code>sheet</code> <strong>oppure</strong> <code>sheets</code>.</td></tr><tr><td><code>sheets</code></td><td>Più fogli: l&#39;elenco dei nomi o <code>&quot;all&quot;</code> (tutti, nell&#39;ordine del workbook). Ogni foglio ha la sua intestazione.</td></tr><tr><td><code>sheetField</code></td><td>Il campo che in ogni record dà il nome del foglio d&#39;origine, come lo scrive il workbook. <strong>Obbligatorio con più fogli</strong> (elenco di più nomi o <code>&quot;all&quot;</code>).</td></tr><tr><td><code>headerRow</code></td><td>La riga d&#39;intestazione, da 1 (default 1). Le righe sopra non sono dati.</td></tr><tr><td><code>columns</code></td><td>I titoli da leggere: il record contiene solo quelli, abbinati <strong>per titolo</strong> e non per posizione.</td></tr><tr><td><code>onMissingSheet</code></td><td><code>error</code> (default) ferma la run; <code>skip</code> salta quel workbook (scelta esplicita, con un warning nel log).</td></tr><tr><td><code>instanceId</code></td><td>Id dell&#39;istanza storage, mostrato nel descriptor.</td></tr></tbody></table><h3 id="cosa-esce" tabindex="-1">Cosa esce <a class="header-anchor" href="#cosa-esce" aria-label="Permalink to &quot;Cosa esce&quot;">​</a></h3><ul><li><strong>Cella vuota</strong> → <code>null</code>. <strong>Riga del tutto vuota</strong> → saltata.</li><li><strong>Formula</strong> → il valore che Excel ha salvato nel file. Senza valore in cache, o se è un errore di Excel (<code>#DIV/0!</code>, <code>#N/A</code>), vale <code>null</code>; gli errori si contano in <code>&lt;nome&gt;:excel.errori-di-formula</code> su <code>ctx.metrics</code> e non fanno fallire la run.</li><li><strong>Date</strong> → <code>Date</code> in UTC; la base 1900 o 1904 la legge il file.</li><li><strong>Celle unite</strong> → il valore sta solo nella cella master, le altre sono <code>null</code>.</li><li><strong>Testo ricco e collegamenti</strong> → il loro testo.</li></ul><h3 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h3><p>Ogni errore nomina file, foglio e, dove ha senso, riga e colonna (<code>riga 1, colonna E</code>): foglio inesistente (con l&#39;elenco di quelli che il workbook ha), riga d&#39;intestazione assente o vuota, <strong>titolo duplicato</strong>, <strong>titolo vuoto</strong> dentro l&#39;intestazione (solo senza <code>columns</code>), colonna dichiarata assente. Con <code>columns</code> contano solo i titoli dichiarati: un&#39;intestazione con altre colonne vuote o ripetute non dà errore finché non le riguardano.</p><h3 id="memoria" tabindex="-1">Memoria <a class="header-anchor" href="#memoria" aria-label="Permalink to &quot;Memoria&quot;">​</a></h3><p>Il foglio si legge <strong>a flusso</strong>: lo zip si apre con accesso casuale (JSZip), si leggono prima le stringhe condivise e gli stili, poi il foglio passa dal parser SAX un pezzo alla volta e ogni riga esce appena si chiude. In memoria stanno il file <strong>compresso</strong> (lo storage lo dà a pezzi, ma lo zip ha bisogno dell&#39;accesso casuale), le stringhe condivise e una riga alla volta; il foglio decompresso no. Un workbook con milioni di stringhe condivise le paga tutte, perché il foglio le referenzia per indice.</p><p>Perché non il lettore a flusso di exceljs: sui file salvati da Excel lo zip mette i fogli <strong>prima</strong> delle stringhe condivise, e quel lettore, a seconda dei tempi del flusso, a volte non emette il foglio (osservato fra lo 0 e il 6% delle letture sulle fixture <code>Prova.xlsx</code>). Con l&#39;accesso casuale l&#39;ordine delle voci nello zip non conta, e il test <code>lettura.test.ts</code> legge le fixture 100 volte verificando che il risultato non cambi.</p><p>Il parser XML è <code>saxes</code> (licenza ISC, circa 100 kB con la sua unica dipendenza <code>xmlchars</code>): è un parser SAX che accetta i dati a pezzi, come serve qui, e <code>fast-xml-parser</code> no. Era già nell&#39;albero come dipendenza di exceljs, quindi dichiararlo diretto non aggiunge pacchetti installati.</p><p><strong>Misura</strong> (<code>memoria.test.ts</code>, workbook generato nel test, 200.000 righe e 3 colonne, file di 4,3 MB; Node 24 al momento della misura, picco di <code>heapUsed</code> oltre la base): <strong>circa 12 MB</strong> a flusso (fino a 28 MB nelle misure con più rumore del garbage collector) contro <strong>circa 360 MB</strong> del caricamento intero con exceljs, che è come leggeva la versione precedente. Il test fallisce se il flusso supera un quarto del caricamento intero.</p><p>Il codec <code>xlsx</code> del connettore file e il nodo <code>parse</code> restano invariati.</p><h3 id="descriptor" tabindex="-1">Descriptor <a class="header-anchor" href="#descriptor" aria-label="Permalink to &quot;Descriptor&quot;">​</a></h3><p><code>kind: &quot;excel&quot;</code>, con <code>storage</code>, <code>path</code> o <code>prefix</code>, <code>foglio</code> e <code>riga d&#39;intestazione</code>. Nessun segreto. Con <code>columns</code> il nodo dichiara le colonne (tipo <code>unknown</code>) per il DAG.</p><h2 id="excelsink" tabindex="-1"><code>excelSink</code> <a class="header-anchor" href="#excelsink" aria-label="Permalink to &quot;\`excelSink\`&quot;">​</a></h2><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { filesystemStorage } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
9
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { excelSink } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/excel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
10
+ <span class="line"></span>
11
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> sink</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">filesystemStorage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ baseDir: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }), {</span></span>
12
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;append&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
13
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;note-spese.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
14
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Mario&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
15
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> columns: [</span></span>
16
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;descrizione&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Descrizione&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
17
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;importo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
18
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
19
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Se il workbook <strong>non esiste</strong> lo crea: lo scheletro minimo del pacchetto (tipi di contenuto, relazioni, <code>workbook.xml</code>, <code>styles.xml</code>) e un foglio con la riga d&#39;intestazione e una riga per record, nell&#39;ordine in cui arrivano. Se <strong>esiste</strong> (salvato da Excel), aggiunge le righe <strong>in fondo al foglio</strong> e basta, come descrive la sezione seguente. In entrambi i casi il file scritto si rilegge con <code>excelSource</code> (stesso <code>columns</code> per titolo e stessa <code>headerRow</code>).</p><table tabindex="0"><thead><tr><th>Opzione</th><th>Significato</th></tr></thead><tbody><tr><td><code>mode</code></td><td><code>&quot;append&quot;</code>, <code>&quot;upsert&quot;</code> o <code>&quot;replace&quot;</code> (vedi sotto). Le opzioni di una modalità sono vietate dal tipo nelle altre: <code>key</code>, <code>cancellaQuando</code> e <code>cancellaRighe</code> esistono solo in <code>upsert</code>.</td></tr><tr><td><code>destructive</code></td><td><code>true</code> obbligatorio con <code>replace</code> e con <code>cancellaQuando</code>: senza, <code>ConfigError</code> alla costruzione. Compare nel descriptor. Vedi «Operazioni distruttive».</td></tr><tr><td><code>path</code></td><td>Il workbook, percorso fisso.</td></tr><tr><td><code>sheet</code></td><td>Il foglio: un nome fisso oppure <code>{ field }</code>, il campo del record che lo dà (vedi «Foglio nuovo e colonne nuove»). Un nome fisso non valido (vuoto, oltre 31 caratteri, <code>/ \\ ? * : [ ]</code>, apostrofo ai bordi, «History») → <code>ConfigError</code> alla costruzione, mai normalizzato.</td></tr><tr><td><code>columns</code></td><td><code>{ field, title?, format?, width?, formula? }</code> nell&#39;ordine delle colonne; il titolo è il campo se manca. Senza <code>columns</code>, i campi dei record nell&#39;ordine in cui si incontrano. Un campo non dichiarato è un errore.</td></tr><tr><td><code>repeatFormulas</code></td><td><code>true</code> (default): nelle righe nuove le colonne senza <code>formula</code> ripetono, traslata, la formula della riga precedente. Vedi «Append su un workbook esistente».</td></tr><tr><td><code>onMissingSheet</code></td><td>Il foglio che manca in un workbook esistente: <code>create</code> (default) lo aggiunge, <code>error</code> ferma la run.</td></tr><tr><td><code>headerRow</code></td><td>La riga d&#39;intestazione, da 1 (default 1). In un workbook nuovo le righe sopra restano vuote; in uno esistente restano come sono.</td></tr><tr><td><code>onMissingFile</code></td><td><code>create</code> (default) crea il workbook; <code>error</code> ferma la run se manca.</td></tr><tr><td><code>template</code></td><td>Il file modello (<code>.xlsx</code> o <code>.xlsm</code>, nello stesso storage) che si copia al posto dello scheletro minimo quando il workbook manca. Stessa estensione di <code>path</code>, altrimenti <code>ConfigError</code>. Vedi «Modelli e file <code>.xlsm</code>».</td></tr><tr><td><code>sheetTemplate</code></td><td>Il foglio <strong>del workbook</strong> che si clona per ogni foglio nuovo, con la sua tabella a nome rigenerato. Errore se ha grafici, pivot o disegni. Vedi «Modelli e file <code>.xlsm</code>».</td></tr><tr><td><code>instanceId</code></td><td>Id dell&#39;istanza storage, mostrato nel descriptor.</td></tr><tr><td><code>name</code></td><td>Nome del nodo, per il report e le metriche (default <code>&lt;storage&gt;:excel</code>).</td></tr><tr><td><code>onFileApertoInExcel</code></td><td><code>error</code> (default) blocca la scrittura se esiste <code>~$nome.xlsx</code>; <code>ignore</code> lo ignora.</td></tr><tr><td><code>maxSheetBytes</code></td><td>Tetto in byte decompressi del foglio da riscrivere, default 64 MiB.</td></tr></tbody></table><h3 id="foglio-nuovo-e-colonne-nuove" tabindex="-1">Foglio nuovo e colonne nuove <a class="header-anchor" href="#foglio-nuovo-e-colonne-nuove" aria-label="Permalink to &quot;Foglio nuovo e colonne nuove&quot;">​</a></h3><ul><li><strong>Il foglio sceglie il record.</strong> <code>sheet: { field: &quot;utente&quot; }</code> smista i record, un foglio per valore del campo. «Mario» e «mario» sono lo stesso foglio (come per Excel) e si scrive con l&#39;ortografia di quello che c&#39;è; se non c&#39;è, con quella del primo record. Il campo non è una colonna, a meno che non lo dichiari in <code>columns</code>. Un valore che non è un testo o non è un nome di foglio valido ferma il batch prima di toccare il file (il messaggio dice record e motivo, mai il valore).</li><li><strong>Foglio nuovo.</strong> Con <code>onMissingSheet: &quot;create&quot;</code> (default) il foglio che manca si aggiunge in fondo: la parte del foglio, la voce in <code>workbook.xml</code>, la relazione e il tipo di contenuto. Gli altri fogli e ogni altra parte restano identici (hash). Le stringhe sono <code>inlineStr</code> e gli elementi stanno nell&#39;ordine dello schema. Le date di una colonna senza <code>format</code> usano <strong>il primo stile di data che il workbook ha già</strong>; se non ne ha nessuno il sink ne aggiunge uno (<code>yyyy-mm-dd hh:mm:ss</code>), così la data si rilegge come data. <code>fullCalcOnLoad</code> resta acceso se ci sono formule.</li><li><strong>Colonna nuova.</strong> Un campo dichiarato che il foglio non ha diventa una colonna in fondo, col suo titolo in intestazione. Accanto a una tabella Excel, se la colonna è libera, la tabella si estende (<code>ref</code>, filtro automatico e <code>tableColumn</code> col nome nuovo, con lo stile dell&#39;ultima intestazione); altrimenti va dopo l&#39;ultima colonna occupata del foglio. Le colonne sconosciute del file restano intatte, e le colonne si riconoscono per titolo: un foglio riordinato a mano funziona.</li><li><strong>Campo assente / <code>null</code>.</strong> Un campo assente dal record non scrive nulla; <code>null</code> lascia la cella vuota con lo stile della colonna (le righe nuove copiano lo stile della precedente).</li></ul><h3 id="formati-e-stili-di-cio-che-il-sink-crea" tabindex="-1">Formati e stili di ciò che il sink crea <a class="header-anchor" href="#formati-e-stili-di-cio-che-il-sink-crea" aria-label="Permalink to &quot;Formati e stili di ciò che il sink crea&quot;">​</a></h3><p>Il sink dichiara come appare <strong>ciò che crea</strong> (un workbook nuovo, un foglio nuovo, una colonna aggiunta). Su un foglio e su una colonna che il file ha già <strong>decide l&#39;utente</strong>: il sink non li tocca.</p><table tabindex="0"><thead><tr><th>Opzione</th><th>Dove</th><th>Significato</th></tr></thead><tbody><tr><td><code>columns[].format</code></td><td>colonna</td><td><code>&quot;text&quot;</code>, <code>&quot;number&quot;</code> (<code>#,##0.00</code>), <code>&quot;integer&quot;</code>, <code>&quot;currency&quot;</code> (<code>#,##0.00 &quot;€&quot;</code>), <code>&quot;percent&quot;</code> (<code>0.00%</code>), <code>&quot;date&quot;</code>, <code>&quot;datetime&quot;</code> o <code>{ code: &quot;0.000&quot; }</code></td></tr><tr><td><code>columns[].width</code></td><td>colonna</td><td>Larghezza in caratteri, da 0 (escluso) a 255. Solo nei fogli creati.</td></tr><tr><td><code>columns[].formula</code></td><td>colonna</td><td>Una formula al posto del valore, scritta nelle righe nuove (<code>{row}</code>, <code>{prev}</code>). Vedi «Append su un workbook esistente».</td></tr><tr><td><code>boldHeader</code></td><td>foglio</td><td>Intestazione in grassetto.</td></tr><tr><td><code>freezeHeader</code></td><td>foglio</td><td>Blocca le righe fino all&#39;intestazione (<code>headerRow</code>) compresa.</td></tr><tr><td><code>autoFilter</code></td><td>foglio</td><td>Filtro automatico su intestazione e righe; con <code>table</code> sono i pulsanti di filtro della tabella (che senza non li ha).</td></tr><tr><td><code>table: &quot;Nome&quot;</code></td><td>foglio</td><td>Una tabella Excel su intestazione e righe. Un secondo <code>append</code> la estende come qualunque tabella.</td></tr></tbody></table><ul><li><strong>Stili solo in aggiunta.</strong> <code>styles.xml</code> cambia soltanto con elementi in coda (<code>numFmt</code>, un font in grassetto, gli <code>xf</code> di <code>cellXfs</code>): gli indici esistenti non si spostano, i formati già presenti con lo stesso codice si riusano, e un test confronta gli <code>xf</code> di prima con quelli di dopo. Se non serve alcuno stile la parte resta identica byte per byte.</li><li><strong>Colonne già presenti.</strong> Un <code>format</code> dichiarato su una colonna che il foglio ha già non la cambia; le righe nuove copiano lo stile della precedente. Una colonna <strong>aggiunta</strong> a un foglio esistente riceve il suo <code>format</code> (non <code>width</code>, che richiederebbe di riscrivere i <code>cols</code> dell&#39;utente).</li><li><strong>Date.</strong> Una <code>Date</code> in una colonna con <code>format</code> ha quel formato; senza, il primo stile di data del workbook (o uno aggiunto): si rilegge sempre come <code>Date</code>.</li><li><strong><code>table</code>.</strong> Il nome è valido (lettere, cifre, <code>_</code> e <code>.</code>; senza spazi; non <code>R</code>, <code>C</code> né un riferimento di cella come <code>A1</code>) e <strong>unico nel workbook</strong>, senza badare alle maiuscole e contando i nomi definiti; altrimenti <code>ConfigError</code> (nome non valido) o rifiuto senza toccare il file (nome già usato). Non si combina con <code>sheet: { field }</code>. I titoli delle colonne devono essere unici senza badare alle maiuscole e senza a capo. Il filtro vive dentro la tabella: il foglio non ha un <code>autoFilter</code> suo, perché Excel ripara una tabella sovrapposta a un filtro di foglio.</li><li><strong>Ordine dello schema.</strong> <code>sheetViews</code> (blocco), <code>cols</code>, <code>sheetData</code>, <code>autoFilter</code>, <code>pageMargins</code>, <code>tableParts</code> stanno nell&#39;ordine di <code>ORDINE_ELEMENTI_FOGLIO</code>; la parte tabella, le relazioni del foglio e il tipo di contenuto si aggiungono senza toccare quelle esistenti. L&#39;apertura in Excel vero resta nella verifica manuale finale.</li></ul><h3 id="che-cosa-vuol-dire-«completo»" tabindex="-1">Che cosa vuol dire «completo» <a class="header-anchor" href="#che-cosa-vuol-dire-«completo»" aria-label="Permalink to &quot;Che cosa vuol dire «completo»&quot;">​</a></h3><p>Il connettore non crea tutto ciò che un file Excel può contenere; «completo» ha tre livelli:</p><ol><li><strong>Preservare.</strong> Ciò che il file ha già e il connettore non sa creare (grafici, pivot, macro, forme, sparkline, commenti, convalide, formattazione condizionale) resta identico byte per byte.</li><li><strong>Dichiarare.</strong> Ciò che il connettore crea da configurazione: workbook, fogli, colonne, formati e larghezze, intestazione in grassetto, blocco, filtro, tabella (questa sezione).</li><li><strong>Fornire da un modello.</strong> Grafici, pivot, sparkline, forme e macro non si dichiarano: si portano in un file modello (<code>template</code>, <code>sheetTemplate</code>): vedi «Modelli e file <code>.xlsm</code>».</li></ol><h3 id="modelli-e-file-xlsm" tabindex="-1">Modelli e file <code>.xlsm</code> <a class="header-anchor" href="#modelli-e-file-xlsm" aria-label="Permalink to &quot;Modelli e file \`.xlsm\`&quot;">​</a></h3><p>Ciò che il connettore non sa creare da configurazione (grafici, pivot, sparkline, forme, macro) arriva da un <strong>file modello</strong> salvato da Excel.</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;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
20
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;append&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
21
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;report-2026.xlsm&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
22
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> template: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;modelli/report.xlsm&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// copiato se report-2026.xlsm manca</span></span>
23
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;utente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
24
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheetTemplate: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Modello&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// un foglio del modello, clonato per ogni utente</span></span>
25
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><ul><li><strong><code>template</code>.</strong> Se il workbook manca (e <code>onMissingFile</code> è <code>create</code>) si copia il modello, byte per byte, e si scrive nei suoi fogli: grafici, pivot, macro, stili e commenti arrivano con lui. Il modello sta nello stesso storage di <code>path</code>; se manca è un errore e il file non si crea. Se il workbook esiste il modello <strong>non si legge</strong>. Le righe che il modello ha già nel foglio restano: un modello utile ha l&#39;intestazione e al massimo una riga di formule.</li><li><strong><code>sheetTemplate</code>.</strong> Il foglio che manca si crea <strong>clonando</strong> un foglio del workbook (di solito arrivato dal <code>template</code>) invece di uno scheletro vuoto: celle, stili, larghezze, intestazione e formule restano quelli del modello, poi le righe si aggiungono in fondo come in un foglio esistente (colonne per titolo, tabella estesa). Ogni tabella Excel del modello diventa una tabella nuova con <code>id</code>, <code>name</code> e <code>displayName</code> rigenerati e unici (<code>tblVendite</code> → <code>tblVendite_2</code>, <code>_3</code>…; i riferimenti strutturati nelle formule seguono il nome). Il foglio clonato non è selezionato, non porta il <code>codeName</code> del modello (in un <code>.xlsm</code> deve essere unico) e ha GUID nuovi. Il modello resta nel workbook. In un foglio clonato <code>table</code> e <code>width</code> non si applicano (la tabella e le larghezze sono quelle del modello); i <code>format</code> delle colonne aggiunte sì. Non si clonano i nomi definiti locali al foglio (<code>definedName</code> con <code>localSheetId</code>).</li><li><strong>Il modello non deve avere</strong> grafici, pivot, disegni, commenti, sparkline, controlli né impostazioni di stampa collegate (<code>printerSettings</code>): il layer non sa duplicarli e la run si ferma con un <code>LoadError</code> che li elenca, <strong>senza toccare il file</strong>. Un foglio per i grafici e uno per i dati è il modo di tenerli separati: si clona il secondo.</li><li><strong><code>.xlsm</code>.</strong> Il sink scrive conservando <code>vbaProject.bin</code> <strong>byte per byte</strong> (un test lo prova sulla fixture creata da Excel). Estensione e contenuto devono coincidere: un <code>.xlsm</code> che in realtà è un <code>.xlsx</code> (o il contrario) ferma la run, perché Excel non lo apre. Il layer non crea macro, quindi un <code>.xlsm</code> nuovo nasce <strong>solo da un <code>template</code> <code>.xlsm</code></strong>. Il source legge un <code>.xlsm</code> in streaming come un <code>.xlsx</code>.</li><li><strong>Grafici.</strong> Un grafico che punta a una <strong>tabella Excel</strong> o a <strong>colonne intere</strong> vede i dati nuovi; uno con <strong>range fisso</strong> (<code>Dati!$A$2:$A$21</code>, com&#39;è nella fixture) <strong>no</strong>: il sink non riscrive i riferimenti del grafico, quindi nel modello conviene fondarlo su una tabella.</li><li><strong>Apertura in Excel.</strong> I test aprono il pacchetto con JSZip ed <code>excelSource</code>; che Excel lo apra senza richiesta di riparazione si verifica a mano (kit <code>docs/research/excel-verifica/</code>).</li></ul><h3 id="append-su-un-workbook-esistente" tabindex="-1">Append su un workbook esistente <a class="header-anchor" href="#append-su-un-workbook-esistente" aria-label="Permalink to &quot;Append su un workbook esistente&quot;">​</a></h3><p>Il sink apre il pacchetto e modifica <strong>solo</strong> il foglio, la sua tabella e <code>workbook.xml</code>. Ogni altra parte (grafici, pivot, commenti, convalide, stili, macro di un <code>.xlsm</code>) resta <strong>identica byte per byte</strong>: un test confronta l&#39;hash di ogni parte prima e dopo. Le parti si riscrivono tagliando il testo originale nei punti che cambiano, non rigenerando il documento.</p><ul><li><strong>Colonne per titolo.</strong> I titoli di <code>columns</code> (o i campi dei record) si cercano nella riga d&#39;intestazione del foglio (<code>headerRow</code>); l&#39;ordine delle colonne nel foglio non conta e le colonne non dichiarate restano vuote. Un titolo che il foglio non ha diventa una colonna nuova (sotto).</li><li><strong>Stile.</strong> Ogni riga nuova copia lo stile della riga dati precedente, colonna per colonna. Una <code>Date</code> si scrive solo in una colonna che ha già un formato data nella riga precedente: il sink non aggiunge stili (<code>styles.xml</code> non cambia) e non scrive una data che Excel mostrerebbe come numero.</li><li><strong>Tabella.</strong> Se il foglio ha una tabella Excel che parte dalla riga d&#39;intestazione, il suo <code>ref</code> e il suo filtro automatico si estendono alle righe nuove. <code>dimension</code> si aggiorna; un <code>autoFilter</code> del foglio senza tabella si estende se arriva all&#39;ultima riga.</li><li><strong>Formule dichiarate.</strong> Una colonna può avere <code>formula</code>: invece di leggere il campo, il sink scrive quella formula <strong>nelle righe nuove</strong> (mai sulle aggiornate di un <code>upsert</code>). Il testo ha i segnaposto <code>{row}</code> (la riga della cella) e <code>{prev}</code> (quella sopra), con o senza <code>=</code> iniziale: <code>{ field: &quot;iva&quot;, title: &quot;Iva&quot;, formula: &quot;=B{row}*0.22&quot; }</code>. Nel file le funzioni stanno <strong>in inglese</strong> (<code>SUM</code>, <code>IF</code>), anche se l&#39;Excel in italiano le mostra come <code>SOMMA</code> e <code>SE</code>. La cella si scrive senza valore in cache: la calcola Excel all&#39;apertura (<code>fullCalcOnLoad</code>). Vale anche per un foglio o un workbook che il sink crea. Una formula vuota, un segnaposto sconosciuto (<code>{riga}</code>) o una colonna con formula dentro <code>key</code> sono un <code>ConfigError</code>.</li><li><strong>Formule ripetute (<code>repeatFormulas</code>, default <code>true</code>).</strong> Nelle colonne <strong>non</strong> dichiarate con <code>formula</code> che nella riga dati precedente hanno una formula, la riga nuova ne riceve una copia traslata: i riferimenti A1 relativi seguono la riga (<code>B7</code> diventa <code>B8</code>), quelli con <code>$</code> sulla riga restano, e i riferimenti strutturati di tabella (<code>tblOrdini[[#This Row],[Quantità]]</code>) si copiano uguali perché non dipendono dalla riga. Una formula con un riferimento ad <strong>un altro foglio</strong> (<code>Altro!A1</code>) non si sa traslare: la run si ferma con un <code>LoadError</code> che nomina cella e formula, senza toccare il file; dichiara la formula della colonna o metti <code>repeatFormulas: false</code>, che lascia quelle celle vuote. Una formula dichiarata prevale sulla ripetuta. Le formule fuori dalla tabella o dalle colonne scritte non si toccano.</li><li><strong>Formattazione condizionale e convalide.</strong> Gli <code>sqref</code> di <code>conditionalFormatting</code> e <code>dataValidation</code> (e gli <code>xm:sqref</code> delle versioni estese <code>x14</code>) che arrivano <strong>esattamente all&#39;ultima riga dati</strong> si allungano fino alla riga nuova, anche quando lo <code>sqref</code> ha più intervalli (<code>A2:A21 C2:C15</code>: si estende solo il primo); gli altri restano com&#39;erano. Excel non lo fa da solo su un file scritto da fuori. Con <code>replace</code> non si toccano.</li><li><strong>Pivot.</strong> Se una pivot ha per sorgente la tabella che cresce (<code>worksheetSource name=&quot;…&quot;</code>) la sua cache riceve <code>refreshOnLoad=&quot;1&quot;</code> e Excel la ricarica all&#39;apertura. Una sorgente a intervallo fisso (<code>ref=&quot;A1:D21&quot;</code>) non vede le righe nuove e la sua cache resta com&#39;è.</li><li><strong>Ricalcolo.</strong> Se il workbook contiene formule si imposta <code>fullCalcOnLoad</code>: senza, Excel mostra i valori in cache, ormai vecchi. La <code>calcChain</code> si toglie (con il suo tipo di contenuto e la sua relazione) solo se il sink scrive una formula; altrimenti resta com&#39;è.</li><li><strong>Ordine dello schema.</strong> Gli elementi aggiunti stanno nella posizione dello schema (<code>calcPr</code> dopo <code>definedNames</code>, prima di <code>pivotCaches</code>): fuori posto Excel ripara il file scartando il foglio. Un test lo verifica sul pacchetto.</li><li><strong>Si rifiuta, non si corrompe.</strong> Con un <code>LoadError</code> che dice il motivo e <strong>senza toccare il file</strong>: file che non è un pacchetto zip, foglio inesistente con <code>onMissingSheet: &quot;error&quot;</code> (elenca quelli che ci sono), righe <strong>sotto</strong> la tabella, tabella con la <strong>riga dei totali</strong>, data in una colonna senza formato data, oltre 1.048.576 righe.</li></ul><p>Le formule condivise o matriciali della riga precedente non si ripetono (la cella resta vuota con il suo stile). Le stringhe nuove sono sempre in linea, non entrano in <code>sharedStrings.xml</code>. L&#39;apertura in Excel vero non è automatizzata (kit <code>docs/research/excel-verifica/</code>). Il caso «file aperto in Excel» e l&#39;impronta cambiata sono in «Concorrenza, file aperto in Excel e memoria».</p><h3 id="cosa-si-scrive" tabindex="-1">Cosa si scrive <a class="header-anchor" href="#cosa-si-scrive" aria-label="Permalink to &quot;Cosa si scrive&quot;">​</a></h3><ul><li><strong>Stringa</strong> → sempre testo (cella in linea), mai formula, anche se inizia con <code>=</code> o <code>@</code>.</li><li><strong>Numero</strong> → cella numerica; un <strong>intero oltre 15 cifre significative</strong> (e un <code>bigint</code>) si scrive come testo, perché Excel lo arrotonderebbe e un identificativo cambierebbe. Un <strong>decimale</strong> resta un numero anche con più di 15 cifre significative: è un importo o una misura, e come testo uscirebbe dai calcoli. Il tetto vale quindi per gli interi, che sono gli identificativi.</li><li><strong><code>Date</code></strong> → numero seriale base 1900 con il <code>format</code> della colonna, o <code>yyyy-mm-dd hh:mm:ss</code>. <strong>Booleano</strong> → booleano.</li><li><strong><code>null</code> / <code>undefined</code></strong> → cella non scritta.</li></ul><h3 id="validazione-e-atomicita" tabindex="-1">Validazione e atomicità <a class="header-anchor" href="#validazione-e-atomicita" aria-label="Permalink to &quot;Validazione e atomicità&quot;">​</a></h3><p>Il sink raccoglie il batch e lo <strong>valida tutto prima di toccare il file</strong>: se qualcosa non va si ferma con un <code>LoadError</code> che elenca i record invalidi (riga e campo, fino a 20). Rifiutati: <code>NaN</code>, <code>Infinity</code>, testi oltre 32.767 caratteri, caratteri non validi in XML, date prima del 01/03/1900, tipi che una cella non sa tenere, titoli vuoti o ripetuti, oltre 1.048.576 righe o 16.384 colonne. Il workbook si scrive con la <strong>sostituzione atomica</strong> dello storage (<code>atomic-replace</code>): se la scrittura fallisce non resta un file a metà. <code>excelSink</code> rifiuta (con <code>ConfigError</code>) uno storage che non dichiara quella capacità; oggi è il solo <code>filesystem</code>.</p><p>Se un solo record è invalido il file resta <strong>identico</strong> a prima (i test ne confrontano l&#39;hash), anche quando esiste già.</p><h3 id="excelvalidate-gli-stessi-controlli-record-per-record" tabindex="-1"><code>excelValidate</code>: gli stessi controlli, record per record <a class="header-anchor" href="#excelvalidate-gli-stessi-controlli-record-per-record" aria-label="Permalink to &quot;\`excelValidate\`: gli stessi controlli, record per record&quot;">​</a></h3><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { excelSink, excelValidate } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/excel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
26
+ <span class="line"></span>
27
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> columns</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [{ field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;nota&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }];</span></span>
28
+ <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;">&quot;note&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
29
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;src&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, source)</span></span>
30
+ <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;">&quot;src&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;valida&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">excelValidate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;valida&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { columns }), {</span></span>
31
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> deadLetter: rejects,</span></span>
32
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
33
+ <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>
34
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;valida&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
35
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
36
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;append&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
37
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;note.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
38
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;A&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
39
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> columns,</span></span>
40
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
41
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span></code></pre></div><p>Mettila prima del sink con un <code>deadLetter</code> sul nodo: i record invalidi vanno negli scarti e gli altri si scrivono, invece di fermare l&#39;intero batch. Usa la <strong>stessa funzione</strong> del sink, quindi stesse regole e stessi messaggi (nel sink con il prefisso <code>riga N, </code>). Il record valido passa invariato; l&#39;errore (<code>ValidationError</code>) elenca tutti i motivi del record e non contiene mai i valori. Con <code>columns</code> un campo non dichiarato è un errore; con <code>sheet</code> un nome non valido è un <code>ConfigError</code> alla costruzione. I limiti del batch (righe e colonne del foglio) restano al sink.</p><h3 id="upsert-aggiorna-per-chiave-o-aggiunge" tabindex="-1"><code>upsert</code>: aggiorna per chiave o aggiunge <a class="header-anchor" href="#upsert-aggiorna-per-chiave-o-aggiunge" aria-label="Permalink to &quot;\`upsert\`: aggiorna per chiave o aggiunge&quot;">​</a></h3><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;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
42
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;note-spesa.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
43
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;upsert&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
44
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> key: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
45
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;utente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
46
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>key</code> è obbligatoria (uno o più campi, ciascuno in <code>columns</code> se dichiarate) e si cerca <strong>solo nel foglio di destinazione</strong>: se una riga ha la stessa chiave se ne aggiornano le celle, altrimenti il record va in fondo come in <code>append</code> (stessi fogli nuovi, colonne nuove, stili e tabelle).</p><ul><li><strong>Confronto canonico</strong>: tutto a testo, spazi ai lati tolti, date in ISO, maiuscole distinte; «42» e 42 sono la stessa chiave.</li><li><strong>Chiave assente, nulla o vuota</strong> (anche una sola parte di una chiave composta): record invalido, il batch non si scrive.</li><li><strong>Stessa chiave due volte nel batch</strong>: si applicano in ordine, <strong>vince l&#39;ultimo</strong> (la riga resta dove l&#39;ha messa il primo).</li><li><strong>Più righe del foglio con la stessa chiave</strong> sono un errore <strong>solo se un record del batch le incontra</strong>; il messaggio nomina foglio, chiave e righe. Quelle che nessun record incontra non contano.</li><li><strong>Cella nulla</strong> in un record che aggiorna: la cella del foglio non si tocca. Una cella aggiornata tiene il suo stile; una data si scrive solo in una cella che ha già un formato data (nessuno stile nuovo). Se si sovrascrive una formula si toglie la <code>calcChain</code> e si imposta <code>fullCalcOnLoad</code>.</li><li><strong>Report</strong>: <code>&lt;nome&gt;:excel.righe-aggiunte</code>, <code>.righe-aggiornate</code>, <code>.righe-invariate</code>; <code>written</code> è aggiunte più aggiornate. Con tutto invariato il file <strong>non si riscrive</strong>.</li></ul><p>Il caso guida delle note spesa — un foglio per utente, <code>sheet: { field: &quot;utente&quot; }</code>, <code>key: [&quot;id&quot;]</code> — è coperto da un test che fa i quattro passi (file assente creato col foglio di A; l&#39;utente B crea il suo foglio; A aggiunge in fondo; la stessa nota con id esistente aggiorna la riga) e rilegge tutto con <code>excelSource({ sheets: &quot;all&quot;, sheetField: &quot;utente&quot; })</code>.</p><h3 id="operazioni-distruttive-replace-e-cancellaquando" tabindex="-1">Operazioni distruttive: <code>replace</code> e <code>cancellaQuando</code> <a class="header-anchor" href="#operazioni-distruttive-replace-e-cancellaquando" aria-label="Permalink to &quot;Operazioni distruttive: \`replace\` e \`cancellaQuando\`&quot;">​</a></h3><p>Sono le due operazioni che <strong>tolgono dati</strong>. Runbook, con come tornare indietro: <a href="./../runbooks/excel-operazioni-distruttive">operazioni distruttive di <code>excelSink</code></a>.</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:#6A737D;--shiki-dark:#6A737D;">// replace: svuota il foglio e lo riscrive</span></span>
47
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
48
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;replace&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
49
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> destructive: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
50
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;report.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
51
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
52
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
53
+ <span class="line"></span>
54
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// upsert che cancella: il record che soddisfa la condizione toglie la sua riga</span></span>
55
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
56
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;upsert&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
57
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> key: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
58
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cancellaQuando: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stato&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, equals: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;annullata&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
59
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cancellaRighe: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;rimuovi&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// il default; &quot;svuota&quot; lascia un buco</span></span>
60
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> destructive: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
61
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;note.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
62
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: { field: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;utente&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
63
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><ul><li><strong><code>replace</code></strong> toglie le righe sotto l&#39;intestazione e scrive il batch (stile e formule delle colonne calcolate si prendono dall&#39;ultima riga dati che c&#39;era; la tabella si restringe). Intestazione, righe sopra, altri fogli e ogni altra parte del pacchetto restano identiche. Se il workbook o il foglio mancano si creano come in <code>append</code>. Un batch vuoto non tocca il file. <strong>Non è <code>retrySafe</code>.</strong></li><li><strong><code>cancellaQuando: { field, equals }</code></strong> (solo <code>upsert</code>): il record con <code>record[field] === equals</code> cancella la riga con la sua chiave; se la riga non c&#39;è, nessun effetto (e il record non si aggiunge). Vale l&#39;<strong>ordine di arrivo</strong>: l&#39;ultimo record con una chiave decide. Il campo non è una colonna, a meno che non sia in <code>columns</code>. Il record che cancella deve avere la chiave; gli altri campi possono mancare.</li><li><strong><code>cancellaRighe</code></strong> dice come si cancella. <strong><code>&quot;rimuovi&quot;</code></strong> (default) toglie la riga e fa salire quelle sotto, riscrivendo i riferimenti del foglio (tabella sotto); dove il layer non sa riscriverli l&#39;operazione <strong>fallisce prima di scrivere</strong>, con un errore che nomina cosa lo impedisce, e il file resta quello di prima. <strong><code>&quot;svuota&quot;</code></strong> lascia la riga come buco, con le celle vuote e il loro stile, senza spostare nulla né toccare riferimenti: è la via d&#39;uscita quando <code>&quot;rimuovi&quot;</code> rifiuta. <code>excelSource</code> salta le righe vuote.</li><li><strong><code>destructive: true</code></strong> è richiesto da <code>replace</code> e da <code>cancellaQuando</code>: senza, <code>excelSink</code> fa fallire la costruzione del grafo. Il flag compare nel descriptor (DAG e report).</li><li><strong>Report</strong>: <code>.righe-cancellate</code> conta le righe svuotate; <code>written</code> non le include.</li><li>Se una cella svuotata aveva una formula, o <code>replace</code> toglie righe con formule, si toglie la <code>calcChain</code> e si imposta <code>fullCalcOnLoad</code>. Lo stesso vale per <code>&quot;rimuovi&quot;</code>, che toglie sempre la <code>calcChain</code> (le sue voci puntano a celle che si spostano) e ricalcola all&#39;apertura.</li></ul><h4 id="cosa-riscrive-rimuovi-e-cosa-rifiuta-v1" tabindex="-1">Cosa riscrive <code>&quot;rimuovi&quot;</code> e cosa rifiuta (v1) <a class="header-anchor" href="#cosa-riscrive-rimuovi-e-cosa-rifiuta-v1" aria-label="Permalink to &quot;Cosa riscrive \`&quot;rimuovi&quot;\` e cosa rifiuta (v1)&quot;">​</a></h4><p>Togliere la riga 5 sposta in su le righe 6 in poi; un riferimento a un intervallo si restringe delle righe tolte che contiene, uno a una riga tolta diventa <code>#REF!</code> (come in Excel). Il resto del pacchetto resta identico byte per byte.</p><table tabindex="0"><thead><tr><th>Elemento</th><th>v1</th><th>Come</th></tr></thead><tbody><tr><td>Righe e celle (<code>row r</code>, <code>c r</code>, <code>dimension</code>)</td><td>riscrive</td><td>rinumerate</td></tr><tr><td>Formule del foglio e degli altri fogli</td><td>riscrive</td><td>riferimenti A1 (anche con <code>$</code>, righe intere, <code>&#39;Foglio&#39;!</code>)</td></tr><tr><td>Formule con un riferimento che sparisce</td><td>riscrive</td><td><code>#REF!</code>, come Excel</td></tr><tr><td>Formule condivise (<code>t=&quot;shared&quot;</code>)</td><td>rifiuta</td><td>se citano le righe del foglio, o se l&#39;origine sta in una riga tolta</td></tr><tr><td>Formule di matrice (<code>t=&quot;array&quot;</code>)</td><td>riscrive</td><td>rifiuta se si estendono su una riga tolta</td></tr><tr><td>Tabelle (<code>ref</code>, filtro)</td><td>riscrive</td><td>rifiuta se togliere le righe cancella l&#39;intestazione, la riga dei totali o tutte le righe di dati</td></tr><tr><td>Filtro automatico, ordinamento (<code>sortState</code>)</td><td>riscrive</td><td><code>ref</code> ristretto</td></tr><tr><td>Celle unite</td><td>riscrive</td><td>un&#39;unione ridotta a una cella si toglie</td></tr><tr><td>Formattazione condizionale, convalide</td><td>riscrive</td><td><code>sqref</code>; le formule solo se con riferimenti assoluti, altrimenti rifiuta</td></tr><tr><td>Nomi definiti (anche area di stampa e filtro)</td><td>riscrive</td><td>testo del nome</td></tr><tr><td>Collegamenti interni, errori ignorati, intervalli protetti</td><td>riscrive</td><td><code>ref</code>/<code>sqref</code></td></tr><tr><td>Grafici, immagini, disegni</td><td>rifiuta</td><td>il foglio ha un disegno; o un grafico di un altro foglio ne usa gli intervalli</td></tr><tr><td>Tabelle pivot</td><td>rifiuta</td><td>sul foglio, o con il foglio come sorgente</td></tr><tr><td>Commenti</td><td>rifiuta</td><td>posizione legata alla cella</td></tr><tr><td><code>extLst</code> con riferimenti (formattazioni e sparkline estese)</td><td>rifiuta</td><td><code>xm:sqref</code>, <code>xm:f</code></td></tr><tr><td>Scenari, viste personalizzate, celle osservate, consolidamento dati, tabelle dati (what-if)</td><td>rifiuta</td><td></td></tr></tbody></table><p><code>INDIRECT</code> e simili, che costruiscono il riferimento da un testo, non si riscrivono: stessa cosa che fa Excel. I rifiuti nominano l&#39;elemento e suggeriscono <code>cancellaRighe: &quot;svuota&quot;</code>.</p><h3 id="retrysafe" tabindex="-1"><code>retrySafe</code> <a class="header-anchor" href="#retrysafe" aria-label="Permalink to &quot;\`retrySafe\`&quot;">​</a></h3><p><code>upsert</code> <strong>è <code>retrySafe</code></strong> (anche con <code>cancellaQuando</code>): ripetere lo stesso <code>load</code> dà lo stesso foglio (le righe già presenti risultano invariate). <code>append</code> <strong>non lo è</strong>: ripeterlo aggiungerebbe le righe due volte, e <code>replace</code> nemmeno, e <code>retry</code> e <code>rateLimit</code> sul nodo fanno fallire <code>build()</code>.</p><h3 id="concorrenza-file-aperto-in-excel-e-memoria" tabindex="-1">Concorrenza, file aperto in Excel e memoria <a class="header-anchor" href="#concorrenza-file-aperto-in-excel-e-memoria" aria-label="Permalink to &quot;Concorrenza, file aperto in Excel e memoria&quot;">​</a></h3><p><strong>Una sola pipeline scrive un dato workbook.</strong> Il sink protegge da una scrittura altrui, non coordina due scrittori: due pipeline sullo stesso file si contendono l&#39;impronta e una delle due fallisce.</p><ul><li><strong>Impronta.</strong> Il sink legge l&#39;impronta del file prima di leggerlo e la ricontrolla subito prima di sostituirlo. Se è cambiata (qualcuno ha salvato nel frattempo) non sostituisce e dà un errore <strong>transitorio</strong>: la modifica di altri non si perde. Resta una finestra minima fra il controllo e la rinomina atomica. Vale per gli storage con la capacità <code>fingerprint</code> (oggi il filesystem).</li><li><strong>File aperto in Excel.</strong> Se accanto al file esiste <code>~$nome.xlsx</code> il sink non scrive e dà un errore transitorio che lo spiega. <code>onFileApertoInExcel: &quot;ignore&quot;</code> lo ignora (default <code>&quot;error&quot;</code>).</li><li><strong>Due sink sullo stesso workbook.</strong> Il sink dichiara <code>exclusiveTarget</code> (storage e percorso): <code>build()</code> rifiuta un grafo con due sink Excel sulla stessa chiave. Rimedio: un solo sink, o una <code>union</code> dei flussi prima del sink.</li><li><strong>Tetto di memoria.</strong> Il foglio da riscrivere si tiene intero in memoria (circa 16 volte i suoi byte in heap: 200k righe sono circa 400 MB). <code>maxSheetBytes</code> è il tetto in <strong>byte decompressi</strong> del foglio, default 64 MiB; oltre, la run si ferma con un errore che nomina l&#39;opzione e il file resta intatto.</li><li><strong>Storage senza sostituzione atomica.</strong> <code>excelSink</code> lo rifiuta alla costruzione (<code>ConfigError</code>).</li></ul><h3 id="layer-ooxml" tabindex="-1">Layer OOXML <a class="header-anchor" href="#layer-ooxml" aria-label="Permalink to &quot;Layer OOXML&quot;">​</a></h3><p>Il sink usa un layer proprio su JSZip (<code>src/connectors/excel/ooxml/</code>), non exceljs, che resta solo per la lettura. <code>creaWorkbook</code> crea un pacchetto nuovo, <code>aggiungiRighe</code>, <code>upsertRighe</code> e (con <code>sostituisci</code>) la sostituzione modificano uno esistente; lo stesso layer serve <code>excelTask</code> (rinomina e cancellazione di fogli, colonne, riscrittura dei riferimenti). Excel pretende l&#39;<strong>ordine dello schema</strong> degli elementi di un foglio (un <code>legacyDrawing</code> dopo <code>extLst</code> fa scartare il foglio pur aprendosi in LibreOffice): <code>ORDINE_ELEMENTI_FOGLIO</code> lo fissa in un posto solo e un test lo verifica aprendo il pacchetto. Il test apre il file con <code>excelSource</code> e con JSZip; <strong>l&#39;apertura in Excel vero non è automatizzata</strong> (vedi il kit <code>docs/research/excel-verifica/</code>, da rifare prima di un rilascio che tocca il layer).</p><h3 id="descriptor-e-report" tabindex="-1">Descriptor e report <a class="header-anchor" href="#descriptor-e-report" aria-label="Permalink to &quot;Descriptor e report&quot;">​</a></h3><p><code>kind: &quot;excel&quot;</code>, con <code>storage</code>, <code>path</code>, <code>foglio</code>, <code>modalità</code> e <code>destructive</code> (<code>true</code> per <code>replace</code> e <code>cancellaQuando</code>, altrimenti <code>no</code>; con <code>cancellaQuando</code> anche <code>cancellaQuando</code> col solo nome del campo e <code>cancellaRighe</code>, <code>rimuovi</code> o <code>svuota</code>). Le righe aggiunte si contano in <code>&lt;nome&gt;:excel.righe-aggiunte</code> su <code>ctx.metrics</code> (e in <code>written</code>); in <code>upsert</code> anche <code>.righe-aggiornate</code> e <code>.righe-invariate</code>, e con <code>cancellaQuando</code> <code>.righe-cancellate</code>.</p><h2 id="exceltask-operazioni-senza-record" tabindex="-1"><code>excelTask</code>: operazioni senza record <a class="header-anchor" href="#exceltask-operazioni-senza-record" aria-label="Permalink to &quot;\`excelTask\`: operazioni senza record&quot;">​</a></h2><p>Un <a href="./../nodes/task">nodo <code>task</code></a> che modifica la <strong>struttura</strong> del workbook, senza record: parte dagli edge di controllo (<code>after</code>), per esempio dopo il caricamento del sink sullo stesso file.</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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { excelSink, excelTask } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/excel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
64
+ <span class="line"></span>
65
+ <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;">&quot;carica-e-sistema&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
66
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">source</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;righe&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, righe)</span></span>
67
+ <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>
68
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;righe&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
69
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> excelSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
70
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
71
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vendite.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
72
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
73
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;append&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
74
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
75
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
76
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">task</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
77
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;sistema&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
78
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> excelTask</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, {</span></span>
79
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;vendite.xlsx&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
80
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> operations: [</span></span>
81
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { op: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;reorderSheets&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, order: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Report&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] },</span></span>
82
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { op: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;renameColumn&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, sheet: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Dati&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, from: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Importo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, to: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Totale&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
83
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { op: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;renameSheet&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, from: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Report&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, to: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Riepilogo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
84
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
85
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
86
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
87
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> after: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;carica&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
88
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> purpose:</span></span>
89
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Mette i fogli in ordine e rinomina la colonna dopo il caricamento.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
90
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
91
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
92
+ <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><strong>Una lettura, tutte le operazioni in ordine, un solo salvataggio atomico.</strong> Le operazioni lavorano sullo stesso pacchetto in memoria: se una è rifiutata (con il suo numero nel messaggio) non si scrive nulla e il file resta com&#39;era. Le parti che nessuna operazione tocca restano identiche byte per byte. Valgono le regole del sink su impronta, <code>onFileApertoInExcel</code>, <code>maxSheetBytes</code> e storage con <code>atomic-replace</code>; il workbook deve esistere (altrimenti <code>TaskError</code>).</p><table tabindex="0"><thead><tr><th>Operazione</th><th>Che cosa cambia</th></tr></thead><tbody><tr><td><code>{ op: &quot;reorderSheets&quot;, order }</code></td><td>L&#39;ordine dei <code>&lt;sheet&gt;</code>; gli indici dei nomi locali (<code>localSheetId</code>) e il foglio attivo (<code>activeTab</code>, <code>firstSheet</code>) li seguono. I fogli citati vanno in testa nell&#39;ordine dato (senza badare alle maiuscole), gli altri seguono. Nessun altro riferimento.</td></tr><tr><td><code>{ op: &quot;renameColumn&quot;, sheet, from, to, headerRow? }</code></td><td>La cella d&#39;intestazione (testo in linea, stile invariato) <strong>e</strong>, se la colonna sta in una tabella, il nome della colonna nella tabella, le sue formule calcolate e le formule con riferimento strutturato che la citano (<code>tbl[Importo]</code>, <code>[@Importo]</code>, <code>tbl[[#This Row],[Importo]]</code>, anche nei nomi definiti). Fuori da una tabella cambia solo la cella.</td></tr><tr><td><code>{ op: &quot;renameSheet&quot;, from, to }</code></td><td>Il nome del foglio e <strong>ogni riferimento per nome</strong>: formule di tutti i fogli (<code>Dati!A1</code>, <code>&#39;Dati 2&#39;!$B:$B</code>, riferimenti 3D), nomi definiti, formattazione condizionale e convalide (anche quelle estese <code>xm:f</code>), colonne calcolate e riga dei totali di tabella, collegamenti interni. Gli apici si aggiungono o si tolgono secondo il nome nuovo. Un grafico, una tabella pivot o una forma collegata a una cella che citano il foglio <strong>fanno rifiutare</strong> l&#39;operazione, nominandoli.</td></tr><tr><td><code>{ op: &quot;deleteSheet&quot;, sheet }</code></td><td><strong>Distruttiva.</strong> Toglie il foglio, la sua relazione, e ciò che solo lui possedeva (tabelle, disegni con grafici e immagini, commenti); i nomi locali del foglio spariscono, gli indici dei nomi locali degli altri e il foglio attivo si riallineano. Se qualcosa <strong>fuori</strong> dal foglio lo cita (formule, nomi, grafici, pivot, collegamenti) rifiuta <strong>elencando i riferimenti</strong> che diventerebbero <code>#REF!</code>. Rifiuta anche se il foglio ha una tabella pivot o è l&#39;unico visibile. Assente: «già assente».</td></tr><tr><td><code>{ op: &quot;deleteColumns&quot;, sheet, columns, headerRow? }</code></td><td><strong>Distruttiva.</strong> Cancella le colonne con quei titoli (riga d&#39;intestazione, senza badare alle maiuscole), dati compresi; quelle a destra scalano. Titoli assenti: «già assente».</td></tr><tr><td><code>{ op: &quot;reorderColumns&quot;, sheet, order, headerRow? }</code></td><td>Le colonne citate prendono, <strong>nell&#39;ordine dato</strong>, le posizioni che occupano (da sinistra a destra); le altre restano. Serve almeno due titoli; un titolo che non c&#39;è è un rifiuto; l&#39;ordine già raggiunto è «già fatto».</td></tr><tr><td><code>{ op: &quot;insertColumns&quot;, sheet, columns, headerRow? }</code></td><td>Per ogni <code>{ title, after }</code>, in ordine, una colonna nuova col titolo subito a destra di <code>after</code> (può essere una appena inserita); la cella d&#39;intestazione ha lo stile di quella di <code>after</code>. Dentro una tabella la colonna entra nella tabella (<code>ref</code>, <code>tableColumns</code>, filtro); a destra dell&#39;ultima colonna no. Un titolo già presente è «già fatto».</td></tr></tbody></table><p><code>destructive: true</code> (opzione del task) è <strong>obbligatorio</strong> se c&#39;è <code>deleteSheet</code> o <code>deleteColumns</code>: senza, <code>excelTask</code> fa fallire la costruzione del grafo (<code>ConfigError</code>). Compare nel descriptor e nel report. Runbook: <a href="./../runbooks/excel-operazioni-distruttive">operazioni distruttive</a>.</p><h4 id="cosa-riscrivono-le-operazioni-che-spostano-o-rinominano-e-cosa-rifiutano" tabindex="-1">Cosa riscrivono le operazioni che spostano o rinominano, e cosa rifiutano <a class="header-anchor" href="#cosa-riscrivono-le-operazioni-che-spostano-o-rinominano-e-cosa-rifiutano" aria-label="Permalink to &quot;Cosa riscrivono le operazioni che spostano o rinominano, e cosa rifiutano&quot;">​</a></h4><p>Le colonne seguono la regola unica <strong>«rifiuta se non sa riscrivere i riferimenti»</strong>: tutto si calcola prima, quindi un rifiuto (con il numero dell&#39;operazione e cosa lo impedisce) non lascia nessun file modificato. Le formule ricalcolano all&#39;apertura e la <code>calcChain</code> si toglie. Per le colonne valgono le stesse regole di <code>cancellaRighe: &quot;rimuovi&quot;</code> (tabella sopra), con la colonna al posto della riga:</p><table tabindex="0"><thead><tr><th>Elemento</th><th>Colonne</th><th>Come</th></tr></thead><tbody><tr><td>Celle (<code>c r</code>), <code>dimension</code>, <code>cols</code> (larghezze e stili)</td><td>riscrive</td><td>spostate, tolte o aggiunte; <code>spans</code> delle righe cambiate si toglie</td></tr><tr><td>Formule del foglio e degli altri, nomi definiti</td><td>riscrive</td><td>riferimenti A1 (con <code>$</code>, colonne intere <code>B:D</code>, <code>&#39;Foglio&#39;!</code>); cancellazione: <code>#REF!</code> o intervallo ristretto; inserimento: intervallo che attraversa si allarga</td></tr><tr><td>Intervalli che dopo un <strong>riordino</strong> non sono più contigui</td><td>rifiuta</td><td>nomina la formula o il nome</td></tr><tr><td>Formule condivise (<code>t=&quot;shared&quot;</code>) e di matrice</td><td>rifiuta</td><td>se citano colonne che cambiano o si estendono su una colonna tolta / spezzata</td></tr><tr><td>Tabelle: <code>ref</code>, <code>tableColumns</code> (nomi, ordine, <code>count</code>), filtro (<code>colId</code>), colonne calcolate</td><td>riscrive</td><td>rifiuta se perderebbe tutte le colonne, se un riordino porta colonne dentro o fuori, se è legata a una query o a una mappa XML</td></tr><tr><td>Riferimenti strutturati a una colonna cancellata</td><td>rifiuta</td><td><code>tbl[Importo]</code>, <code>[@Importo]</code> in formule, colonne calcolate e nomi; vale anche per intervalli <code>tbl[[A]:[C]]</code> se si cancella o riordina</td></tr><tr><td>Filtro, ordinamento, celle unite, collegamenti, convalide, formattazione condizionale</td><td>riscrive</td><td><code>ref</code>/<code>sqref</code> (un&#39;unione ridotta a una cella e un intervallo sparito si tolgono); formule solo con colonne assolute, altrimenti rifiuta</td></tr><tr><td>Grafici</td><td>rifiuta</td><td>se ne usano intervalli che cambierebbero; un grafico che cita colonne non toccate non impedisce nulla</td></tr><tr><td>Tabelle pivot</td><td>rifiuta</td><td>con il foglio (o una sua tabella) come sorgente</td></tr><tr><td>Immagini, disegni, commenti, altre parti legate al foglio</td><td>rifiuta</td><td>il foglio ha un disegno o commenti</td></tr><tr><td><code>extLst</code> con riferimenti, interruzioni di pagina di colonna, scenari, viste personalizzate, celle osservate, consolidamento dati, tabelle dati (what-if)</td><td>rifiuta</td><td></td></tr><tr><td>Viste del foglio (selezione, riquadri bloccati)</td><td>non riscrive</td><td>cosmetico: un riquadro bloccato resta dov&#39;era</td></tr></tbody></table><p><code>INDIRECT</code> e simili, che costruiscono il riferimento da un testo, non si riscrivono, come in Excel. <code>renameSheet</code> non vede il codice VBA di un <code>.xlsm</code> né i file esterni che citano il workbook.</p><p><strong>Idempotenza.</strong> Riordinare fogli o colonne già in ordine, rinominare con origine assente e destinazione presente, inserire un titolo già presente è «già fatto»; cancellare ciò che non c&#39;è è «già assente»: il file non si riscrive e il report lo dice. Origine e destinazione entrambe assenti, o entrambe presenti, è un errore (per <code>renameColumn</code> anche se differiscono per sole maiuscole; per <code>renameSheet</code> una rinomina di sole maiuscole è una rinomina vera). Per questo il task è <strong><code>retrySafe</code></strong> e ammette <code>retry</code>.</p><p><strong>Descriptor e report.</strong> <code>kind: &quot;excel-task&quot;</code>, con <code>storage</code>, <code>path</code>, una voce per operazione e <code>destructive</code> (<code>true</code> se c&#39;è <code>deleteSheet</code> o <code>deleteColumns</code>). Il report del nodo ha <code>operations</code> (<code>done</code>, <code>already-done</code> o <code>already-absent</code> per ciascuna), <code>done</code>, <code>alreadyDone</code> (le ultime due insieme) e <code>destructive</code>; le metriche sono <code>&lt;nome&gt;:excel.operazioni-fatte</code> e <code>.operazioni-gia-fatte</code>.</p><h2 id="promesse-provate-con-excel" tabindex="-1">Promesse provate con Excel <a class="header-anchor" href="#promesse-provate-con-excel" aria-label="Permalink to &quot;Promesse provate con Excel&quot;">​</a></h2><p>Excel per Mac 16.103.4 (ETL-326) è il giudice di ciò che promette il layer; i test automatici non lo sostituiscono e non lo possono: aprono il pacchetto con JSZip ed <code>excelSource</code>.</p><table tabindex="0"><thead><tr><th>Promessa</th><th>Dove si vede</th></tr></thead><tbody><tr><td>Un file scritto dal connettore si apre <strong>senza richiesta di riparazione</strong> (ordine degli elementi, tabelle, relazioni).</td><td>Ogni file del kit, colonna «si apre senza avviso?».</td></tr><tr><td>Con formule nel workbook i valori sono <strong>ricalcolati all&#39;apertura</strong> (<code>fullCalcOnLoad</code>); la <code>calcChain</code> tolta non dà avvisi.</td><td>File con formule, colonna «i valori sono ricalcolati?».</td></tr><tr><td>La <strong>pivot</strong> con per sorgente una tabella si aggiorna all&#39;apertura (<code>refreshOnLoad</code>); con sorgente a intervallo fisso no.</td><td>File con righe aggiunte in fondo a una tabella con pivot.</td></tr><tr><td>Rinominare una colonna di tabella cambia cella e nome insieme: Excel non ripara la tabella.</td><td>File di <code>excelTask</code> con <code>renameColumn</code>.</td></tr><tr><td>Grafici, pivot, commenti, convalide, formattazione condizionale, forme e macro restano al loro posto.</td><td>File di append, upsert e rimozione righe su <code>Prova.xlsx</code> e <code>ProvaMacro.xlsm</code>.</td></tr><tr><td>La macro di un <code>.xlsm</code> resta identica e si lancia.</td><td>File <code>.xlsm</code>.</td></tr></tbody></table><p><strong>Stato.</strong> La verifica sui file prodotti dal connettore <strong>finito</strong> è stata eseguita il 2026-11-06 con Excel per Mac 16.103.4, a mano, con il kit <code>docs/research/excel-verifica/</code>: esito <strong>pulito</strong> (nessun avviso di riparazione, valori come attesi su 19 file aperti, 4 rifiuti attesi confermati dal manifest), in <code>docs/research/excel-verifica/ESITO.md</code>. Vale per quella versione di Excel, su Mac: Excel per Windows, Excel online e le versioni precedenti non sono provati. Va rifatta prima di ogni rilascio che tocca il layer.</p><h2 id="che-cosa-non-si-copre" tabindex="-1">Che cosa non si copre <a class="header-anchor" href="#che-cosa-non-si-copre" aria-label="Permalink to &quot;Che cosa non si copre&quot;">​</a></h2><ul><li><strong>Grafici, pivot, sparkline, forme e macro da configurazione.</strong> Si preservano e, dove possibile, si estendono (intervalli); per averli in un file nuovo si porta un modello (<code>template</code>, <code>sheetTemplate</code>). Non si modifica il VBA.</li><li><strong>Formattazione condizionale e convalide da configurazione.</strong> Si preservano e si estendono; non si creano.</li><li><strong>Formati <code>.xls</code> e <code>.ods</code></strong> in ingresso.</li><li><strong>Storage remoti.</strong> <code>ftp</code>, <code>s3</code> e <code>sftp</code> non offrono la sostituzione atomica né l&#39;impronta: il sink e il task li rifiutano alla costruzione.</li><li><strong>Riordinare o inserire righe «in mezzo»:</strong> si usano <code>sort</code> con <code>replace</code>, e <code>append</code>/<code>upsert</code>.</li><li><strong>Lettura incrementale</strong> con watermark.</li><li><strong>Un motore di calcolo:</strong> Excel ricalcola all&#39;apertura; il source legge il valore in cache.</li><li><strong>Lock fra run, backup automatici, percorso del file da campo, file protetti da password.</strong></li></ul><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p>I test usano i file salvati da Excel in <code>tests/fixtures/excel/</code> (<code>Prova.xlsx</code>, <code>ProvaMacro.xlsm</code>): Excel ripara ciò che altri produttori scrivono, quindi le fixture non si costruiscono a mano. Base 1904, formule in errore e celle unite si provano su workbook prodotti da exceljs nel test.</p>`,92)])])}const g=o(s,[["render",n]]);export{u as __pageData,g as default};
@@ -0,0 +1 @@
1
+ import{_ as o,o as i,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const u=JSON.parse('{"title":"Excel","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/excel.md","filePath":"connectors/excel.md"}'),s={name:"connectors/excel.md"};function n(l,e,r,c,d,p){return i(),a("div",null,[...e[0]||(e[0]=[t("",92)])])}const g=o(s,[["render",n]]);export{u as __pageData,g as default};
@@ -1,8 +1,8 @@
1
- import{_ as i,o as e,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: File (storage × codec)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/file.md","filePath":"connectors/file.md"}'),n={name:"connectors/file.md"};function o(l,s,r,d,p,c){return e(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="connettore-file-storage-×-codec" tabindex="-1">Connettore: File (storage × codec) <a class="header-anchor" href="#connettore-file-storage-×-codec" aria-label="Permalink to &quot;Connettore: File (storage × codec)&quot;">​</a></h1><p>Astrazione componibile per leggere/scrivere file su qualunque storage in qualunque formato. Codice: <code>src/connectors/file/</code>.</p><h2 id="modello" tabindex="-1">Modello <a class="header-anchor" href="#modello" aria-label="Permalink to &quot;Modello&quot;">​</a></h2><p>Due concern ortogonali che si <strong>compongono</strong>:</p><ul><li><strong><code>StorageProvider</code></strong> — stream di byte: <code>list(prefix)</code>, <code>get(path)</code>, <code>put(path, data)</code>. (filesystem, S3, Azure Blob, GCS, FTP, SFTP — ognuno nella sua issue/connettore)</li><li><strong><code>FileCodec&lt;T&gt;</code></strong> — byte ↔ record: <code>decode(bytes)</code>, <code>encode(records)</code>. (CSV, JSON/NDJSON, XLSX, XML, Parquet — ognuno nella sua issue/connettore)</li></ul><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { fileSource, fileSink } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
1
+ import{_ as s,o as e,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: File (storage × codec)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/file.md","filePath":"connectors/file.md"}'),n={name:"connectors/file.md"};function o(l,i,r,d,c,p){return e(),a("div",null,[...i[0]||(i[0]=[t(`<h1 id="connettore-file-storage-×-codec" tabindex="-1">Connettore: File (storage × codec) <a class="header-anchor" href="#connettore-file-storage-×-codec" aria-label="Permalink to &quot;Connettore: File (storage × codec)&quot;">​</a></h1><p>Astrazione componibile per leggere/scrivere file su qualunque storage in qualunque formato. Codice: <code>src/connectors/file/</code>.</p><h2 id="modello" tabindex="-1">Modello <a class="header-anchor" href="#modello" aria-label="Permalink to &quot;Modello&quot;">​</a></h2><p>Due concern ortogonali che si <strong>compongono</strong>:</p><ul><li><strong><code>StorageProvider</code></strong> — stream di byte: <code>list(prefix)</code>, <code>get(path)</code>, <code>put(path, data)</code>. Capacità facoltative, dichiarate in <code>capabilities</code>: <code>replace</code> (sostituzione atomica) e <code>fingerprint</code> (impronta del contenuto); oggi le offre solo <code>filesystemStorage</code>, gli altri storage non cambiano. (filesystem, S3, Azure Blob, GCS, FTP, SFTP — ognuno nella sua issue/connettore)</li><li><strong><code>FileCodec&lt;T&gt;</code></strong> — byte ↔ record: <code>decode(bytes)</code>, <code>encode(records)</code>. (CSV, JSON/NDJSON, XLSX, XML, Parquet — ognuno nella sua issue/connettore)</li></ul><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { fileSource, fileSink } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
2
2
  <span class="line"></span>
3
3
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &quot;CSV da SFTP&quot; = sftpStorage + csvCodec; &quot;Parquet su S3&quot; = s3Storage + parquetCodec</span></span>
4
4
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> source</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fileSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, codec, { prefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;in/&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// o { path: &quot;in/file&quot; }</span></span>
5
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> sink</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fileSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, codec, { path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;out/result.csv&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre></div><ul><li><code>fileSource</code>: legge un <code>path</code> singolo o tutti i file di un <code>prefix</code> (concatenando i record); errori → <code>ExtractError</code>.</li><li><code>fileSink</code>: serializza i record col codec e li scrive sullo storage; <code>written</code> = record passati; errori → <code>LoadError</code>.</li></ul><h3 id="i-codec-anche-come-transform" tabindex="-1">I codec anche come transform <a class="header-anchor" href="#i-codec-anche-come-transform" aria-label="Permalink to &quot;I codec anche come transform&quot;">​</a></h3><p>Un codec non è legato allo storage: quando i byte arrivano da un&#39;altra source (una cartella Noeva, un allegato di posta) o vanno a un altro sink insieme ai metadati del file, si usa in mezzo al grafo con le transform <code>parse(name, codec, …)</code> e <code>serialize(name, codec, …)</code>. <code>parse</code> decodifica i byte portati da ogni record in una riga per riga del file; <code>serialize</code> compone un file per gruppo, anche con un codec diverso per ogni file. Dettagli, errori e tetto di memoria nel <a href="./../nodes/transform#file-parse-e-serialize">nodo transform</a>.</p><p>Un codec può dichiarare <code>columns</code>, le colonne dei record decodificati quando le conosce prima di leggere il file: oggi <code>csvCodec</code> con <code>header: false</code> e <code>columns</code>, e <code>xlsxCodec</code> con <code>columns</code>. <code>parse</code> le mostra nel DAG.</p><h2 id="storage-disponibili" tabindex="-1">Storage disponibili <a class="header-anchor" href="#storage-disponibili" aria-label="Permalink to &quot;Storage disponibili&quot;">​</a></h2><h3 id="filesystem-locale-—-filesystemstorage" tabindex="-1">Filesystem locale — <code>filesystemStorage</code> <a class="header-anchor" href="#filesystem-locale-—-filesystemstorage" aria-label="Permalink to &quot;Filesystem locale — \`filesystemStorage\`&quot;">​</a></h3><p>Legge/scrive file su disco (<code>node:fs</code>, nessuna dipendenza). I path sono relativi a <code>baseDir</code> (<strong>sandbox</strong>: un path che ne esce è rifiutato). <code>list</code> è ricorsiva e restituisce path relativi con separatore <code>/</code>. <code>get</code> streamma i byte; <code>put</code> crea le directory mancanti.</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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
5
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> sink</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fileSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(storage, codec, { path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;out/result.csv&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre></div><ul><li><code>fileSource</code>: legge un <code>path</code> singolo o tutti i file di un <code>prefix</code> (concatenando i record); errori → <code>ExtractError</code>.</li><li><code>fileSink</code>: serializza i record col codec e li scrive sullo storage; <code>written</code> = record passati; errori → <code>LoadError</code>.</li></ul><h3 id="i-codec-anche-come-transform" tabindex="-1">I codec anche come transform <a class="header-anchor" href="#i-codec-anche-come-transform" aria-label="Permalink to &quot;I codec anche come transform&quot;">​</a></h3><p>Un codec non è legato allo storage: quando i byte arrivano da un&#39;altra source (una cartella Noeva, un allegato di posta) o vanno a un altro sink insieme ai metadati del file, si usa in mezzo al grafo con le transform <code>parse(name, codec, …)</code> e <code>serialize(name, codec, …)</code>. <code>parse</code> decodifica i byte portati da ogni record in una riga per riga del file; <code>serialize</code> compone un file per gruppo, anche con un codec diverso per ogni file. Dettagli, errori e tetto di memoria nel <a href="./../nodes/transform#file-parse-e-serialize">nodo transform</a>.</p><p>Un codec può dichiarare <code>columns</code>, le colonne dei record decodificati quando le conosce prima di leggere il file: oggi <code>csvCodec</code> con <code>header: false</code> e <code>columns</code>, e <code>xlsxCodec</code> con <code>columns</code>. <code>parse</code> le mostra nel DAG.</p><h2 id="storage-disponibili" tabindex="-1">Storage disponibili <a class="header-anchor" href="#storage-disponibili" aria-label="Permalink to &quot;Storage disponibili&quot;">​</a></h2><h3 id="filesystem-locale-—-filesystemstorage" tabindex="-1">Filesystem locale — <code>filesystemStorage</code> <a class="header-anchor" href="#filesystem-locale-—-filesystemstorage" aria-label="Permalink to &quot;Filesystem locale — \`filesystemStorage\`&quot;">​</a></h3><p>Legge/scrive file su disco (<code>node:fs</code>, nessuna dipendenza). I path sono relativi a <code>baseDir</code> (<strong>sandbox</strong>: un path che ne esce è rifiutato). <code>list</code> è ricorsiva e restituisce path relativi con separatore <code>/</code>. <code>get</code> streamma i byte; <code>put</code> crea le directory mancanti.</p><p>Offre le due <strong>capacità facoltative</strong> dell&#39;interfaccia (<code>capabilities: [&quot;atomic-replace&quot;, &quot;fingerprint&quot;]</code>):</p><ul><li><code>replace(path, data)</code> sostituisce il file in modo <strong>atomico</strong>: scrive su un temporaneo nella stessa cartella (<code>.&lt;nome&gt;.noeva-tmp-&lt;casuale&gt;</code>, nascosto da <code>list</code>) e lo rinomina sul destinatario. Se lo stream fallisce a metà il temporaneo è rimosso e l&#39;originale resta intatto.</li><li><code>fingerprint(path)</code> dà un&#39;impronta opaca (<code>dimensione:mtime:inode</code>) che cambia se il file cambia, anche per una sostituzione atomica; <code>undefined</code> se il file non esiste. Serve a chi scrive per accorgersi di una modifica concorrente.</li></ul><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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
6
6
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> filesystemStorage,</span></span>
7
7
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> csvCodec,</span></span>
8
8
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fileSource,</span></span>
@@ -73,4 +73,4 @@ import{_ as i,o as e,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k
73
73
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">xmlCodec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ recordTag: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;item&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// &lt;root&gt;&lt;item&gt;…&lt;/item&gt;&lt;/root&gt;</span></span>
74
74
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">xmlCodec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ rootTag: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;orders&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, recordTag: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;order&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// encode</span></span></code></pre></div><p>Opzioni: <code>recordTag</code> (default <code>record</code>), <code>rootTag</code> (default <code>root</code>, per l&#39;encode).</p><h3 id="parquet-—-parquetcodec" tabindex="-1">Parquet — <code>parquetCodec</code> <a class="header-anchor" href="#parquet-—-parquetcodec" aria-label="Permalink to &quot;Parquet — \`parquetCodec\`&quot;">​</a></h3><p>Formato <strong>colonnare</strong> tipato (<code>@dsnp/parquetjs</code>). <code>decode</code> legge l&#39;intero file; <code>encode</code> richiede uno <strong>schema</strong> (esplicito o inferito dal primo record).</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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { parquetCodec } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@noeva/etl-core/connectors/file&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
75
75
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parquetCodec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// schema inferito dal primo record</span></span>
76
- <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parquetCodec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ schema: { id: { type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INT64&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, nome: { type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;UTF8&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } } });</span></span></code></pre></div><p>Opzioni: <code>schema</code> (mappa campo → tipo Parquet <code>UTF8</code>/<code>DOUBLE</code>/<code>BOOLEAN</code>/<code>INT64</code>/…).</p><h2 id="stato" tabindex="-1">Stato <a class="header-anchor" href="#stato" aria-label="Permalink to &quot;Stato&quot;">​</a></h2><p>Disponibili: interfacce + <code>fileSource</code>/<code>fileSink</code> (#21), codec <strong>CSV</strong> (#22), storage <strong>filesystem</strong> + <code>memoryStorage</code> (#27), storage <strong>Amazon S3</strong> (#28), <strong>SFTP</strong> (#29), <strong>FTP/FTPS</strong> (#30), codec <strong>XLSX</strong> (#23), <strong>JSON/NDJSON</strong> (#24), <strong>XML</strong> (#25), <strong>Parquet</strong> (#26). In arrivo (issue dedicate): storage <strong>Azure/GCS</strong> — ognuno con il proprio ADR per la dipendenza.</p><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p><code>src/connectors/file/file-connector.test.ts</code>: round-trip (write→read) via <code>memoryStorage</code> + codec di prova, lettura per prefisso, e gestione errori (<code>ExtractError</code>/<code>LoadError</code>).</p>`,70)])])}const g=i(n,[["render",o]]);export{k as __pageData,g as default};
76
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parquetCodec</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ schema: { id: { type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;INT64&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, nome: { type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;UTF8&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } } });</span></span></code></pre></div><p>Opzioni: <code>schema</code> (mappa campo → tipo Parquet <code>UTF8</code>/<code>DOUBLE</code>/<code>BOOLEAN</code>/<code>INT64</code>/…).</p><h2 id="stato" tabindex="-1">Stato <a class="header-anchor" href="#stato" aria-label="Permalink to &quot;Stato&quot;">​</a></h2><p>Disponibili: interfacce + <code>fileSource</code>/<code>fileSink</code> (#21), codec <strong>CSV</strong> (#22), storage <strong>filesystem</strong> + <code>memoryStorage</code> (#27), storage <strong>Amazon S3</strong> (#28), <strong>SFTP</strong> (#29), <strong>FTP/FTPS</strong> (#30), codec <strong>XLSX</strong> (#23), <strong>JSON/NDJSON</strong> (#24), <strong>XML</strong> (#25), <strong>Parquet</strong> (#26). In arrivo (issue dedicate): storage <strong>Azure/GCS</strong> — ognuno con il proprio ADR per la dipendenza.</p><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p><code>src/connectors/file/file-connector.test.ts</code>: round-trip (write→read) via <code>memoryStorage</code> + codec di prova, lettura per prefisso, e gestione errori (<code>ExtractError</code>/<code>LoadError</code>).</p>`,72)])])}const g=s(n,[["render",o]]);export{k as __pageData,g as default};
@@ -1 +1 @@
1
- import{_ as i,o as e,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: File (storage × codec)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/file.md","filePath":"connectors/file.md"}'),n={name:"connectors/file.md"};function o(l,s,r,d,p,c){return e(),a("div",null,[...s[0]||(s[0]=[t("",70)])])}const g=i(n,[["render",o]]);export{k as __pageData,g as default};
1
+ import{_ as s,o as e,c as a,a5 as t}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: File (storage × codec)","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/file.md","filePath":"connectors/file.md"}'),n={name:"connectors/file.md"};function o(l,i,r,d,c,p){return e(),a("div",null,[...i[0]||(i[0]=[t("",72)])])}const g=s(n,[["render",o]]);export{k as __pageData,g as default};
@@ -0,0 +1,34 @@
1
+ import{_ as a,o as i,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: MySQL e MariaDB","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/mysql.md","filePath":"connectors/mysql.md"}'),n={name:"connectors/mysql.md"};function t(l,e,d,r,c,p){return i(),s("div",null,[...e[0]||(e[0]=[o(`<h1 id="connettore-mysql-e-mariadb" tabindex="-1">Connettore: MySQL e MariaDB <a class="header-anchor" href="#connettore-mysql-e-mariadb" aria-label="Permalink to &quot;Connettore: MySQL e MariaDB&quot;">​</a></h1><p>Source, Sink, lookup e task per <strong>MySQL</strong> e <strong>MariaDB</strong>, sul driver <strong><code>mysql2</code></strong> (puro JS). Un connettore solo per i due motori: provato su MySQL 8.4 e MariaDB 11. Codice: <code>src/connectors/mysql/</code>. Decisioni in ADR-0109.</p><h2 id="configurazione" tabindex="-1">Configurazione <a class="header-anchor" href="#configurazione" aria-label="Permalink to &quot;Configurazione&quot;">​</a></h2><p><code>loadMysqlPoolConfig(prefix?, env?)</code> costruisce le <code>PoolOptions</code> di <code>mysql2</code> dalle variabili <code>&lt;PREFIX&gt;HOST|PORT|USER|PASSWORD|DATABASE</code> (default prefisso <code>MYSQL_</code>) e opzionali <code>&lt;PREFIX&gt;SSL</code> e <code>&lt;PREFIX&gt;SSL_VERIFY</code>. Le variabili sono dichiarate una volta in <code>MANIFEST_MYSQL</code>: cinque obbligatorie, senza default nemmeno per la porta, e <code>SSL</code> (default <code>false</code>) e <code>SSL_VERIFY</code> (default <code>true</code>). Con variabili mancanti il loader lancia <strong>un</strong> <code>ConfigError</code> che le elenca tutte, anche nel campo <code>mancanti</code>. Charset <code>utf8mb4</code>, <code>timezone: &quot;Z&quot;</code>.</p><ul><li>Senza <code>MYSQL_SSL=true</code> la connessione <strong>non è cifrata</strong>.</li><li>Con <code>MYSQL_SSL=true</code> il certificato del server <strong>si verifica</strong>. Per un self-signed in sviluppo si scrive <code>MYSQL_SSL_VERIFY=false</code>, di proposito.</li><li>Credenziali solo in <code>.env</code> (vedi <code>.env.example</code>).</li></ul><p>Le istanze passano dal registry (<code>loadMysqlRegistry</code>, <code>MYSQL_INSTANCES</code>): la <code>default</code> usa <code>MYSQL_HOST</code>…, la <code>dwh</code> usa <code>MYSQL_DWH_HOST</code>…. Per <code>etl env check</code>, <code>istanzaMysqlDichiarata(id)</code> è l&#39;istanza da passare ad <code>ambienteDellaPipeline</code> nell&#39;<code>environment</code> della pipeline.</p><p><code>createMysqlPool(config)</code> apre il pool di <code>mysql2</code> senza connettersi: una pipeline non importa il driver, e ne chiude il ciclo di vita con <code>end()</code>. Ogni connessione nuova imposta la sessione su <strong>UTC</strong> (<code>SET time_zone = &#39;+00:00&#39;</code>), e <code>multipleStatements</code> è sempre spento.</p><p><strong>Nel piano</strong>, dove non c&#39;è un pool, <code>istanzaMysqlPerIlPiano(id, env)</code> dà host, porta e database dell&#39;istanza <code>id</code> con le loro variabili, o l&#39;esempio (<code>mysql.esempio</code>) se l&#39;istanza non si costruisce; <code>dettagliConnessioneSql</code> ne fa le righe del descriptor. Vedi la <a href="./../conventions/node-descriptor">convenzione dei descriptor</a>.</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:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
2
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> createMysqlPool,</span></span>
3
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> loadMysqlRegistry,</span></span>
4
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mysqlSink,</span></span>
5
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mysqlSource,</span></span>
6
+ <span class="line"><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;"> &quot;@noeva/etl-core/connectors/mysql&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
7
+ <span class="line"></span>
8
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> pool</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createMysqlPool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadMysqlRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;dwh&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">));</span></span>
9
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
10
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> source</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> mysqlSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Order</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;({</span></span>
11
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pool,</span></span>
12
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> instanceId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;dwh&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
13
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> query:</span></span>
14
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;SELECT id, amount, updated_at FROM orders WHERE updated_at &gt;= :watermark AND kind = ? ORDER BY updated_at&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
15
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> values: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fattura&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
16
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> watermark: {</span></span>
17
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> column: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;updated_at&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
18
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;timestamp&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
19
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> initial: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;1970-01-01 00:00:00&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
20
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
21
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
22
+ <span class="line"></span>
23
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> sink</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> mysqlSink</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">FactOrder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;({</span></span>
24
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pool,</span></span>
25
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> table: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;dwh.fact_orders&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
26
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> columns: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;amount&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;updated_at&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
27
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> conflictTarget: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
28
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
29
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // ... graph().source(source).sink(sink).build()</span></span>
30
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">finally</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
31
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pool.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">end</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
32
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="cosa-arriva-nei-record" tabindex="-1">Cosa arriva nei record <a class="header-anchor" href="#cosa-arriva-nei-record" aria-label="Permalink to &quot;Cosa arriva nei record&quot;">​</a></h2><p><code>mysql2</code> farebbe <code>Date</code> di <code>DATE</code>, <code>DATETIME</code> e <code>TIMESTAMP</code> nel fuso del processo, e <code>number</code> di <code>BIGINT</code>. Il connettore legge invece <strong>come testo</strong>, con un <code>typeCast</code> per query (vale con qualunque pool):</p><table tabindex="0"><thead><tr><th>Tipo MySQL / MariaDB</th><th>Nel record</th></tr></thead><tbody><tr><td><code>DATE</code></td><td><code>&quot;2026-03-29&quot;</code></td></tr><tr><td><code>DATETIME</code>, <code>TIMESTAMP</code></td><td><code>&quot;2026-03-29 02:30:00.123456&quot;</code>, precisione intera</td></tr><tr><td><code>BIGINT</code></td><td><code>&quot;9007199254740993&quot;</code>, nessuna perdita oltre 2^53</td></tr><tr><td><code>DECIMAL</code></td><td>stringa, come in <code>mysql2</code></td></tr><tr><td><code>JSON</code></td><td>l&#39;oggetto su MySQL; su MariaDB <code>JSON</code> è <code>LONGTEXT</code>, quindi stringa</td></tr><tr><td>ogni altro</td><td>il default del driver</td></tr></tbody></table><p>Così la stessa riga letta da due macchine con <code>TZ</code> diverse è identica, e lo stesso vale per il suo hash di riga (ADR-0070). Uno <strong>zero-date</strong> (<code>0000-00-00</code>) arriva com&#39;è: escluderlo spetta allo schema della pipeline. Un <code>TIMESTAMP</code> è nel fuso della sessione: con <code>createMysqlPool</code> è UTC, con un pool costruito a mano è quello del server.</p><p>Nella scrittura vale l&#39;inverso, con <code>paramValue</code>: una <code>Date</code> si scrive in <strong>UTC</strong> (<code>YYYY-MM-DD HH:mm:ss.mmm</code>), un oggetto o un array come <strong>JSON</strong> (non come lista), un <code>bigint</code> come testo, <code>undefined</code> come <code>NULL</code>.</p><h2 id="source-—-mysqlsource" tabindex="-1">Source — <code>mysqlSource</code> <a class="header-anchor" href="#source-—-mysqlsource" aria-label="Permalink to &quot;Source — \`mysqlSource\`&quot;">​</a></h2><p>Streamma i risultati di una query: le righe arrivano dal socket con backpressure, e il result-set non è mai in memoria (<code>batchSize</code> è la coda dello stream, default 500). I valori dinamici sono <code>?</code>, legati nell&#39;ordine in cui compaiono; il numero di <code>?</code> deve essere quello di <code>values</code>, e si controlla alla costruzione. I <code>?</code> dentro letterali, identificatori con backtick e commenti (<code>-- </code>, <code>#</code>, <code>/* */</code>) non contano.</p><p>Se lo stream non si legge fino in fondo (un errore a valle, un annullo) la <strong>connessione si chiude</strong>, non torna al pool: aveva ancora righe in arrivo.</p><h3 id="source-incrementale-watermark" tabindex="-1">Source incrementale: <code>watermark</code> <a class="header-anchor" href="#source-incrementale-watermark" aria-label="Permalink to &quot;Source incrementale: \`watermark\`&quot;">​</a></h3><p>Come per Postgres e SQL Server (ADR-0068): <code>watermark: { column, type, initial }</code> e un predicato scritto per esteso con <code>:watermark</code>, che si scrive <strong>dove serve</strong>, anche prima dei <code>?</code> e anche più volte. Il valore è il testo del database (<code>&quot;2026-03-29 02:30:00.123456&quot;</code>), con la precisione intera. La colonna va selezionata. Senza <code>:watermark</code> nella query, o con <code>:watermark</code> senza <code>watermark</code>, la costruzione fallisce.</p><h2 id="sink-—-mysqlsink" tabindex="-1">Sink — <code>mysqlSink</code> <a class="header-anchor" href="#sink-—-mysqlsink" aria-label="Permalink to &quot;Sink — \`mysqlSink\`&quot;">​</a></h2><p><code>INSERT … ON DUPLICATE KEY UPDATE col = VALUES(col)</code> in batch, dentro una transazione: rieseguire non duplica. <code>conflictTarget</code> non è un target come in Postgres: MySQL scatta su <strong>qualunque</strong> indice univoco o chiave primaria, e <code>conflictTarget</code> dice quali colonne sono la chiave naturale e quindi <strong>non</strong> si aggiornano. Deve corrispondere a un indice univoco della tabella, e il connettore non può verificarlo.</p><ul><li>Con tutte le colonne nella chiave la riga esistente resta com&#39;è (<code>a = a</code>).</li><li>Senza <code>conflictTarget</code> la INSERT non è idempotente: sconsigliato.</li><li>La tabella deve essere <strong>InnoDB</strong>: su un motore non transazionale un errore a metà lascia i batch già scritti.</li><li>Un solo statement porta al più 65535 segnaposto: <code>batchSize × columns</code> non deve superarlo.</li><li><code>VALUES()</code> è deprecato da MySQL 8.0.20 (un avviso, non un errore), ma è l&#39;unica forma che capisce anche MariaDB.</li><li><strong>Non c&#39;è la modalità SCD2</strong>: per ora i sink SQL storicizzati sono Postgres e SQL Server.</li></ul><h2 id="task-—-mysqlsqltask" tabindex="-1">Task — <code>mysqlSqlTask</code> <a class="header-anchor" href="#task-—-mysqlsqltask" aria-label="Permalink to &quot;Task — \`mysqlSqlTask\`&quot;">​</a></h2><p>Statement statici in una transazione, valori solo come parametri <code>@nome</code> dichiarati in <code>params</code> (diventano <code>?</code>). Come per gli altri task SQL (ADR-0071): niente <code>;</code> in mezzo, niente <code>BEGIN</code>/<code>COMMIT</code>, <code>destructive</code> dichiarato.</p><blockquote><p>⚠️ <strong>Il DDL non è transazionale.</strong> <code>TRUNCATE</code>, <code>DROP</code>, <code>ALTER</code>, <code>CREATE</code> e <code>RENAME TABLE</code> fanno un <strong>commit implicito</strong>: un errore dopo uno di loro non lo annulla. Lo scambio atomico di due tabelle è <strong>uno statement solo</strong>:</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;">statements</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
33
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;RENAME TABLE dwh.ordini TO dwh.ordini_old, dwh.ordini_staging TO dwh.ordini&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
34
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span></code></pre></div><p>Vedi il <a href="./../runbooks/sql-task-truncate-swap#mysql-e-mariadb">runbook</a>.</p></blockquote><p>Una variabile utente di MySQL (<code>@x</code>) non dichiarata in <code>params</code> resta com&#39;è.</p><h2 id="lookup-—-mysqllookup" tabindex="-1">Lookup — <code>mysqlLookup</code> <a class="header-anchor" href="#lookup-—-mysqllookup" aria-label="Permalink to &quot;Lookup — \`mysqlLookup\`&quot;">​</a></h2><p>Risolve un batch di chiavi con un solo round-trip, con lo stesso segnaposto <code>@chiavi</code> degli altri DBMS (diventa <code>?, ?, …</code>): vedi il <a href="./../nodes/lookup">nodo lookup</a>. La query è validata alla costruzione (una sola <code>SELECT</code>; <code>INTO</code> è vietato, quindi anche <code>INTO OUTFILE</code>). Con zero chiavi non si interroga il database.</p><p>Le chiavi arrivano <strong>normalizzate</strong> (trim + maiuscolo). Le collation di default di MySQL e MariaDB (<code>*_ci</code>) ignorano le maiuscole; con una <code>_bin</code> o <code>_cs</code> il confronto nella <code>WHERE</code> va normalizzato allo stesso modo (<code>UPPER(codice)</code>).</p><h2 id="errori-transitori" tabindex="-1">Errori transitori <a class="header-anchor" href="#errori-transitori" aria-label="Permalink to &quot;Errori transitori&quot;">​</a></h2><p>Un <code>LoadError</code> o un <code>LookupError</code> portano <code>transient: true</code> (ADR-0059) per <code>ER_LOCK_DEADLOCK</code>, <code>ER_LOCK_WAIT_TIMEOUT</code> e <code>PROTOCOL_CONNECTION_LOST</code>, oltre a <code>ECONNRESET</code> e <code>ETIMEDOUT</code>.</p><h2 id="sicurezza-sql" tabindex="-1">Sicurezza SQL <a class="header-anchor" href="#sicurezza-sql" aria-label="Permalink to &quot;Sicurezza SQL&quot;">​</a></h2><ul><li>Gli identificatori (tabella, colonne) sono validati e quotati con i backtick; i <strong>valori</strong> viaggiano sempre come <code>?</code>, mai nel testo.</li><li><code>mysql2</code> interpola i <code>?</code> lato client (serve per lo streaming): per questo ogni valore passa da <code>paramValue</code>, che toglie le sorprese (array come liste, oggetti come <code>chiave = valore</code>).</li><li><code>multipleStatements</code> è spento: un <code>;</code> in una query è un errore, non due comandi.</li><li>La garanzia che una pipeline non scriva dove non deve resta l&#39;<strong>utenza di sola lettura</strong> sul database; il controllo sintattico del lookup non è un modello di sicurezza.</li></ul><h2 id="ambiente-di-test" tabindex="-1">Ambiente di test <a class="header-anchor" href="#ambiente-di-test" aria-label="Permalink to &quot;Ambiente di test&quot;">​</a></h2><p><code>tests/integration/mysql.integration.test.ts</code> si salta senza <code>MYSQL_HOST</code> e <code>MYSQL_DATABASE</code>, e si lancia <strong>una volta per motore</strong> (MySQL e MariaDB). Le istruzioni per i container usa e getta sono nel runbook dei database di test del repo del core (<code>docs/runbooks/local-test-databases.md</code>).</p><h2 id="test" tabindex="-1">Test <a class="header-anchor" href="#test" aria-label="Permalink to &quot;Test&quot;">​</a></h2><p>Unitari colocati in <code>src/connectors/mysql/*.test.ts</code>, con un pool finto (<code>fake-pool.ts</code>): senza rete.</p>`,37)])])}const E=a(n,[["render",t]]);export{k as __pageData,E as default};
@@ -0,0 +1 @@
1
+ import{_ as a,o as i,c as s,a5 as o}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Connettore: MySQL e MariaDB","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/mysql.md","filePath":"connectors/mysql.md"}'),n={name:"connectors/mysql.md"};function t(l,e,d,r,c,p){return i(),s("div",null,[...e[0]||(e[0]=[o("",37)])])}const E=a(n,[["render",t]]);export{k as __pageData,E as default};