feat: automatic localstorage cleaning

core/static/bundled/alpine-index.js

@@ -1,12 +0,0 @@
-import sort from "@alpinejs/sort";
-import Alpine from "alpinejs";
-import { limitedChoices } from "#core:alpine/limited-choices.ts";
-import { alpinePlugin as notificationPlugin } from "#core:utils/notifications.ts";
-
-Alpine.plugin([sort, limitedChoices]);
-Alpine.magic("notifications", notificationPlugin);
-window.Alpine = Alpine;
-
-window.addEventListener("DOMContentLoaded", () => {
-  Alpine.start();
-});

core/static/bundled/base-bundle-index.ts

@@ -0,0 +1,49 @@
+import sort from "@alpinejs/sort";
+import Alpine from "alpinejs";
+import { polyfillCountryFlagEmojis } from "country-flag-emoji-polyfill";
+import htmx from "htmx.org";
+import { limitedChoices } from "#core:alpine/limited-choices";
+import { cacheBuster } from "#core:core/cache";
+import { default as navbar } from "#core:core/navbar";
+import { alpinePlugin as notificationPlugin } from "#core:utils/notifications";
+
+/**
+ * Alpine
+ */
+Alpine.plugin([sort, limitedChoices]);
+Alpine.magic("notifications", notificationPlugin);
+
+// biome-ignore lint/style/useNamingConvention: it's how it's named
+Object.assign(window, { Alpine });
+
+window.addEventListener("DOMContentLoaded", () => {
+  Alpine.start();
+});
+
+/**
+ * Polyfill for country flags (used for language choice)
+ */
+polyfillCountryFlagEmojis();
+
+/**
+ * HTMX
+ */
+document.body.addEventListener("htmx:beforeRequest", (event: CustomEvent) => {
+  event.detail.target.ariaBusy = true;
+});
+
+document.body.addEventListener("htmx:beforeSwap", (event: CustomEvent) => {
+  event.detail.target.ariaBusy = null;
+});
+
+Object.assign(window, { htmx });
+
+/**
+ * navbar
+ */
+navbar();
+
+/**
+ * Script that clears the cache when the cache version changes
+ */
+cacheBuster();

core/static/bundled/core/cache.ts

@@ -0,0 +1,24 @@
+// increment this number when a breaking change is made with localStorage
+const CURRENT_CACHE_VERSION = 1;
+
+export function cacheBuster() {
+  const version = Number.parseInt(localStorage.getItem("version") ?? "0", 10);
+  if (version === CURRENT_CACHE_VERSION) {
+    // The cache schema is up-to-date. Nothing to do.
+    return;
+  }
+  localStorage.removeItem("basket");
+  localStorage.removeItem("basket1");
+  // remove all storage items which key is in the form
+  // `userXXXPictures` or `userXXXPicturesNumber`
+  Object.keys(localStorage)
+    .filter(
+      (key) =>
+        key.startsWith("user") &&
+        (key.endsWith("Pictures") || key.endsWith("PicturesNumber")),
+    )
+    .forEach((key) => {
+      localStorage.removeItem(key);
+    });
+  localStorage.setItem("version", CURRENT_CACHE_VERSION.toString());
+}

core/static/bundled/core/navbar.ts

@@ -1,12 +1,10 @@
-import { exportToHtml } from "#core:utils/globals.ts";
+function showMenu() {
-
-exportToHtml("showMenu", () => {
   const navbar = document.getElementById("navbar-content");
   const current = navbar.getAttribute("mobile-display");
   navbar.setAttribute("mobile-display", current === "hidden" ? "revealed" : "hidden");
-});
+}
 
-document.addEventListener("alpine:init", () => {
+function navbarInit() {
   const menuItems = document.querySelectorAll(".navbar details[name='navbar'].menu");
   const isDesktop = () => {
     return window.innerWidth >= 500;
@@ -33,4 +31,9 @@ document.addEventListener("alpine:init", () => {
       }
     });
   }
-});
+}
+
+export default () => {
+  Object.assign(document, { showMenu });
+  document.addEventListener("alpine:init", navbarInit);
+};

core/static/bundled/country-flags-index.ts

@@ -1,3 +0,0 @@
-import { polyfillCountryFlagEmojis } from "country-flag-emoji-polyfill";
-
-polyfillCountryFlagEmojis();

core/static/bundled/htmx-index.js

@@ -1,11 +0,0 @@
-import htmx from "htmx.org";
-
-document.body.addEventListener("htmx:beforeRequest", (event) => {
-  event.detail.target.ariaBusy = true;
-});
-
-document.body.addEventListener("htmx:beforeSwap", (event) => {
-  event.detail.target.ariaBusy = null;
-});
-
-Object.assign(window, { htmx });

core/static/bundled/utils/csv.ts

@@ -1,4 +1,4 @@
-import type { NestedKeyOf } from "#core:utils/types.ts";
+import type { NestedKeyOf } from "#core:types/nested-key";
 
 interface StringifyOptions<T extends object> {
   /** The columns to include in the resulting CSV. */

core/templates/core/base.jinja

@@ -35,12 +35,9 @@
       <noscript><link rel="stylesheet" href="{{ static('bundled/fontawesome-index.css') }}"></noscript>
 
       <script src="{{ url('javascript-catalog') }}"></script>
-      <script type="module" src="{{ static("bundled/core/navbar-index.ts") }}"></script>
+      <script type="module" src="{{ static("bundled/base-bundle-index.ts") }}"></script>
       <script type="module" src="{{ static("bundled/core/components/include-index.ts") }}"></script>
-      <script type="module" src="{{ static('bundled/alpine-index.js') }}"></script>
+      <script type="module" src="{{ static("bundled/core/tooltips-index.ts") }}"></script>
-      <script type="module" src="{{ static('bundled/htmx-index.js') }}"></script>
-      <script type="module" src="{{ static('bundled/country-flags-index.ts') }}"></script>
-      <script type="module" src="{{ static('bundled/core/tooltips-index.ts') }}"></script>
 
       {% block additional_css %}{% endblock %}
       {% block additional_js %}{% endblock %}

counter/static/bundled/counter/product-list-index.ts

@@ -1,9 +1,9 @@
 import { showSaveFilePicker } from "native-file-system-adapter";
 import type TomSelect from "tom-select";
+import type { NestedKeyOf } from "#core:types/nested-key";
 import { paginated } from "#core:utils/api";
 import { csv } from "#core:utils/csv";
 import { getCurrentUrlParams, History, updateQueryString } from "#core:utils/history";
-import type { NestedKeyOf } from "#core:utils/types";
 import {
   type ProductSchema,
   type ProductSearchProductsDetailedData,

docs/tutorial/front/localstorage.md

@@ -0,0 +1,56 @@
+[Documentation du localStorage (mozilla)](https://developer.mozilla.org/fr/docs/Web/API/Window/localStorage)
+
+## Utilité et limitations
+
+Le `localStorage` est un cache géré directement par le navigateur.
+Il permet de stocker des données directement chez le client.
+Il s'agit donc d'un outil extrêmement puissant, qui permet d'éviter
+beaucoup de requêtes au serveur, améliorant ainsi les temps de chargement.
+
+Cependant, il y a deux limitations majeures à prendre en compte :
+
+- le `localStorage` est entièrement géré par le client,
+  une fois le déploiement effectué, vous ne pouvez plus y toucher ;
+  vous devez donc être sûr de vous avant d'apporter des modifications
+  reposant sur le `localStorage`.
+- la quantité de données stockable est limitée à 10Mo ;
+  une fois ce quota rempli, le navigateur lèvera une `QuotaExceededError`.
+
+## Invalidation du `localStorage`
+
+Pour résoudre le premier de ces deux problèmes, il y a un script permettant
+d'annuler une partie du cache.
+Ce dernier se trouve dans le fichier `core/static/bundled/core/cache.ts`.
+
+Vous devrez modifier ce cache chaque fois que vous effectuerez
+un changement de schéma, c'est-à-dire dans un des cas suivants :
+
+- une des clefs du cache n'est plus utilisée
+- la clef n'a pas changé, mais la manière dont les données attachées à cette clef
+  sont formées a été modifiée.
+
+!!!Note
+
+    Si vous ne faites qu'ajouter des données, sans modifier ni supprimer
+    celles qui sont là, vous n'avez pas besoin d'invalider le cache.
+
+Vous devez effectuer deux modifications dans ce fichier :
+
+- incrémenter la version du cache
+- ajouter une ligne permettant de retirer votre clef du cache
+
+```ts hl_lines="2 11"
+// increment this number when a breaking change is made with localStorage
+const CURRENT_CACHE_VERSION = 2;  // <-- changez cette ligne
+
+export function cacheBuster() {
+  const version = Number.parseInt(localStorage.getItem("version") ?? "0", 10);
+  if (version === CURRENT_CACHE_VERSION) {
+    // The cache schema is up-to-date. Nothing to do.
+    return;
+  }
+  // ...
+  localStorage.removeItem("<clef>");  // <-- et rajoutez cette ligne
+  localStorage.setItem("version", CURRENT_CACHE_VERSION.toString());
+}
+```

eboutic/static/bundled/eboutic/eboutic-index.ts

@@ -7,8 +7,7 @@ interface BasketItem {
   unitPrice: number;
 }
 
-// increment the key number if the data schema of the cached basket changes
+const BASKET_CACHE_KEY = "basket";
-const BASKET_CACHE_KEY = "basket1";
 
 document.addEventListener("alpine:init", () => {
   Alpine.data("basket", (lastPurchaseTime?: number) => ({

mkdocs.yml

@@ -66,6 +66,8 @@ nav:
     - Gestion des permissions: tutorial/perms.md
     - Gestion des groupes: tutorial/groups.md
     - Les fragments: tutorial/fragments.md
+    - Frontend:
+      - localStorage: tutorial/front/localstorage.md
     - API:
       - Développement: tutorial/api/dev.md
       - Connexion à l'API: tutorial/api/connect.md

package-lock.json

@@ -44,6 +44,7 @@
         "@biomejs/biome": "^2.4.13",
         "@hey-api/openapi-ts": "^0.94.5",
         "@types/alpinejs": "^3.13.11",
+        "@types/alpinejs__sort": "^3.13.0",
         "@types/cytoscape-cxtmenu": "^3.4.5",
         "@types/cytoscape-klay": "^3.1.5",
         "@types/js-cookie": "^3.0.6",
@@ -2481,6 +2482,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/alpinejs__sort": {
+      "version": "3.13.0",
+      "resolved": "https://registry.npmjs.org/@types/alpinejs__sort/-/alpinejs__sort-3.13.0.tgz",
+      "integrity": "sha512-iR9vEy6e3yXbYAK45/hpulzlt8SSKTsvYUl/t5nuWjtbJPoGxzxUUqOm3egp83Gqtf//TyJnDCI4OTebAKDRAA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/alpinejs": "*"
+      }
+    },
     "node_modules/@types/codemirror": {
       "version": "5.60.17",
       "resolved": "https://registry.npmjs.org/@types/codemirror/-/codemirror-5.60.17.tgz",

package.json

@@ -29,6 +29,7 @@
     "@biomejs/biome": "^2.4.13",
     "@hey-api/openapi-ts": "^0.94.5",
     "@types/alpinejs": "^3.13.11",
+    "@types/alpinejs__sort": "^3.13.0",
     "@types/cytoscape-cxtmenu": "^3.4.5",
     "@types/cytoscape-klay": "^3.1.5",
     "@types/js-cookie": "^3.0.6",

sas/static/bundled/sas/user/pictures-index.ts

@@ -22,35 +22,35 @@ document.addEventListener("alpine:init", () => {
     albums: [] as Album[],
 
     async fetchPictures(): Promise<PictureSchema[]> {
-      const localStorageKey = `user${config.userId}Pictures`;
+      // Check the cache before hitting the API.
-      const localStorageInvalidationKey = `user${config.userId}PicturesNumber`;
+      const localStorageKey = "userPictures";
-      const lastCachedNumber = localStorage.getItem(localStorageInvalidationKey);
+      const cacheContent: { userId: number; pictures: PictureSchema[] }[] = JSON.parse(
+        localStorage.getItem(localStorageKey) || "[]",
+      );
+      const userPictures = cacheContent.find((obj) => obj.userId === config.userId);
       if (
-        lastCachedNumber !== null &&
+        userPictures !== undefined &&
-        Number.parseInt(lastCachedNumber, 10) === config.nbPictures
+        userPictures.pictures.length === config.nbPictures
       ) {
-        return JSON.parse(localStorage.getItem(localStorageKey));
+        // The cached value is considered valid
+        // if it contains the right amount of pictures.
+        // This amount is known because it is given in the template.
+        return userPictures.pictures;
       }
       const pictures = await paginated(picturesFetchPictures, {
         // biome-ignore lint/style/useNamingConvention: from python api
         query: { users_identified: [config.userId] },
       } as PicturesFetchPicturesData);
+
+      cacheContent.push({ userId: config.userId, pictures: pictures });
       try {
-        localStorage.setItem(localStorageInvalidationKey, config.nbPictures.toString());
+        // cache only the pictures of the last 4 visited profiles
-        localStorage.setItem(localStorageKey, JSON.stringify(pictures));
+        localStorage.setItem(localStorageKey, JSON.stringify(cacheContent.slice(-4)));
       } catch {
-        // an exception is raised if the localstorage is entirely filled
+        // an exception is raised if the localstorage is entirely filled.
-        // so just delete all cached user pictures.
+        // To be as safe as possible, delete the cached pictures.
         // A cache hit is not worth the page breaking.
-        Object.keys(localStorage)
+        localStorage.removeItem(localStorageKey);
-          .filter(
-            (key) =>
-              key.startsWith("user") &&
-              (key.endsWith("Pictures") || key.endsWith("PicturesNumber")),
-          )
-          .forEach((key) => {
-            localStorage.removeItem(key);
-          });
       }
       return pictures;
     },