Document and structure more

desktop/src/main.ts

@@ -103,6 +103,8 @@ const logStartupBanner = () => {
  * Note that increasing the disk cache size does not guarantee that Chromium
  * will respect in verbatim, it uses its own heuristics atop this hint.
  * https://superuser.com/questions/378991/what-is-chrome-default-cache-size-limit/1577693#1577693
+ *
+ * See also: [Note: Caching files].
  */
 const increaseDiskCache = () =>
     app.commandLine.appendSwitch(

web/apps/photos/src/services/download/index.ts

@@ -6,7 +6,7 @@ import { CustomError } from "@ente/shared/error";
 import { Events, eventBus } from "@ente/shared/events";
 import {
     CacheStorageService,
-    type LimitedCache,
+    type EnteCache,
 } from "@ente/shared/storage/cache";
 import { Remote } from "comlink";
 import { FILE_TYPE } from "constants/file";
@@ -59,9 +59,9 @@ export interface DownloadClient {
 class DownloadManagerImpl {
     private ready: boolean = false;
     private downloadClient: DownloadClient;
-    private thumbnailCache?: LimitedCache;
+    private thumbnailCache?: EnteCache;
     // disk cache is only available on electron
-    private diskFileCache?: LimitedCache;
+    private diskFileCache?: EnteCache;
     private cryptoWorker: Remote<DedicatedCryptoWorker>;
 
     private fileObjectURLPromises = new Map<number, Promise<SourceURLs>>();

web/packages/shared/storage/cache.ts

@@ -5,15 +5,24 @@ const cacheNames = [
     "files",
 ] as const;
 
-/** Namespaces into which our caches data is divided */
+/**
+ * Namespaces into which our caches data is divided
+ *
+ * Note that namespaces are just arbitrary (but predefined) strings to split the
+ * cached data into "folders", so to speak.
+ * */
 export type CacheName = (typeof cacheNames)[number];
 
 /**
  * A namespaced cache.
  *
+ * This cache is suitable for storing large amounts of data (entire files).
+ *
  * To obtain a cache for a given namespace, use {@link openCache}. To clear all
  * cached data (e.g. during logout), use {@link clearCaches}.
  *
+ * [Note: Caching files]
+ *
  * The underlying implementation of the cache is different depending on the
  * runtime environment.
  *
@@ -39,22 +48,46 @@ export type CacheName = (typeof cacheNames)[number];
  * ([the WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=231706)), so it's
  * not trivial to use this as a full on replacement of the Web Cache in the
  * browser. So for now we go with this split implementation.
+ *
+ * See also: [Note: Increased disk cache for the desktop app].
  */
-export interface LimitedCache {
+export interface EnteCache {
+    /**
+     * Get the data corresponding to {@link key} (if found) from the cache.
+     */
     match: (key: string) => Promise<Response>;
+    /**
+     * Add the given {@link key}-value ({@link data}) pair to the cache.
+     */
     put: (key: string, data: Response) => Promise<void>;
+    /**
+     * Delete the data corresponding to the given {@link key}.
+     *
+     * The returned promise resolves to `true` if a cache entry was found,
+     * otherwise it resolves to `false`.
+     * */
     delete: (key: string) => Promise<boolean>;
 }
 
+/**
+ * Return the {@link EnteCache} corresponding to the given {@link name}.
+ *
+ * @param name One of the arbitrary but predefined namespaces of type
+ * {@link CacheName} which group related data and allow us to use the same key
+ * across namespaces.
+ */
 const openCache = async (name: CacheName) => {
     const cache = await caches.open(name);
     return {
         match: (key) => {
-            // options are not supported in the browser
             return cache.match(key);
         },
-        put: cache.put.bind(cache),
-        delete: cache.delete.bind(cache),
+        put: (key: string, data: Response) => {
+            return cache.put(key, data);
+        },
+        delete: (key: string) => {
+            return cache.delete(key);
+        },
     };
 };