@webority/mobile-ui 0.0.38 → 0.0.39

package/README.md

@@ -10,7 +10,7 @@ npm install @webority/mobile-ui
 
 No external runtime dependencies beyond `@webority/mobile-core`. Requires
 `react-native-gesture-handler`, `react-native-reanimated` and `react-native-safe-area-context` as
-peers; `react-native-haptic-feedback` is optional. Gradients use React Native's own
+peers, and `expo-file-system`, where `AuthedImage` keeps its downloaded images; `react-native-haptic-feedback` is optional. Gradients use React Native's own
 `experimental_backgroundImage`, so no gradient library is needed.
 
 Full documentation lives in the repository's `docs/` directory.

package/lib/commonjs/components/AuthedImage/AuthedImage.js

@@ -82,10 +82,10 @@ const AuthedImage = props => {
         return;
       }
       if (cached && (0, _authedImageCache.isFresh)(cached.meta, ttlMs)) {
-        void (0, _authedImageCache.touchEntry)(key, cached.meta);
+        void (0, _authedImageCache.touchEntry)(key);
         finish({
           status: 'ready',
-          dataUri: cached.dataUri
+          fileUri: cached.fileUri
         });
         return;
       }
@@ -103,7 +103,7 @@ const AuthedImage = props => {
         const result = await entry.promise;
         finish({
           status: 'ready',
-          dataUri: result.dataUri
+          fileUri: result.fileUri
         });
       } catch (error) {
         if (cancelled) {
@@ -114,7 +114,7 @@ const AuthedImage = props => {
         if (cached) {
           finish({
             status: 'ready',
-            dataUri: cached.dataUri
+            fileUri: cached.fileUri
           });
           return;
         }
@@ -191,7 +191,7 @@ const AuthedImage = props => {
     testID: testID,
     style: style,
     source: {
-      uri: state.dataUri
+      uri: state.fileUri
     }
   });
 };

package/lib/commonjs/components/AuthedImage/authedImageCache.js

@@ -5,11 +5,21 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.touchEntry = exports.setAuthedImageCacheLimit = exports.releaseFetch = exports.readEntry = exports.isFresh = exports.getAuthedImageCacheLimit = exports.deriveCacheKey = exports.clearAuthedImageCache = exports.authedImageCacheStats = exports.acquireFetch = exports.DEFAULT_TTL_MS = void 0;
 var _mobileCore = require("@webority/mobile-core");
+var _expoFileSystem = require("expo-file-system");
 var _hashString = require("../../utils/hashString.js");
-const KEY_PREFIX = '@webority/authed-image/v1/';
-const DATA_PREFIX = `${KEY_PREFIX}d/`;
-const META_PREFIX = `${KEY_PREFIX}m/`;
+const INDEX_KEY = '@webority/authed-image/v2/index';
+// Releases before the file cache kept every image as a base64 string in the
+// key-value store, up to the 50 MB ceiling. Nothing reads those rows any more,
+// so they are removed the first time this version finds no index.
+const LEGACY_PREFIX = '@webority/authed-image/v1/';
+const FOLDER = 'authed-images';
 const DEFAULT_BYTE_CEILING = 50 * 1024 * 1024;
+
+// A hit only moves an entry's last access in memory. Writing the index on every
+// hit would put a storage write behind every row of a scrolling list, so a hit
+// persists only when the stored time is this old; least-recently-used order
+// survives a restart to within this window.
+const TOUCH_PERSIST_MS = 60 * 60 * 1000;
 const DEFAULT_TTL_MS = exports.DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 let byteCeiling = DEFAULT_BYTE_CEILING;
 
@@ -28,120 +38,196 @@ exports.setAuthedImageCacheLimit = setAuthedImageCacheLimit;
 const getAuthedImageCacheLimit = () => byteCeiling;
 
 /**
- * Hex only by construction, so it is always a safe storage key segment.
+ * Hex only by construction, so it is always a safe file name segment.
  */
 exports.getAuthedImageCacheLimit = getAuthedImageCacheLimit;
 const deriveCacheKey = (uri, override) => (0, _hashString.hashString)(override ?? uri);
+exports.deriveCacheKey = deriveCacheKey;
+const imageFile = fileName => new _expoFileSystem.File(_expoFileSystem.Paths.cache, FOLDER, fileName);
+const toMeta = ({
+  fetchedAt,
+  bytes,
+  contentType,
+  lastAccessedAt
+}) => ({
+  fetchedAt,
+  bytes,
+  contentType,
+  lastAccessedAt
+});
+
+// The image bytes live in files; only this small index goes to the key-value
+// store. A store that fails costs persistence across restarts, never an image:
+// Storage logs and returns false rather than throwing.
+let index = null;
+let indexLoad = null;
+const persistIndex = async entries => {
+  if (!(0, _mobileCore.isStorageAvailable)()) {
+    return;
+  }
+  const out = {};
+  for (const [cacheKey, entry] of entries) {
+    out[cacheKey] = {
+      ...entry,
+      persistedAccessAt: entry.lastAccessedAt
+    };
+  }
+  if (await _mobileCore.Storage.setItem(INDEX_KEY, JSON.stringify(out))) {
+    for (const entry of entries.values()) {
+      entry.persistedAccessAt = entry.lastAccessedAt;
+    }
+  }
+};
+const removeLegacyEntries = async () => {
+  const keys = await _mobileCore.Storage.getAllKeys();
+  const legacy = keys.filter(key => key.startsWith(LEGACY_PREFIX));
+  if (legacy.length > 0) {
+    await _mobileCore.Storage.multiRemove(legacy);
+  }
+};
 
 /**
- * The cache is an OPTIMISATION, so a failing store must never stop an image
- * rendering. That used to mean guarding on whether a backend existed at all,
- * warning once and skipping the cache; under Expo-first the backend ships with
- * the library, so "no backend" is no longer a state an app can be in and that
- * branch was unreachable.
- *
- * What remains is a store that exists and FAILS, which the per-operation error
- * handling below already covers: each read returns null and each write returns
- * false, the image still fetches, and nothing is logged per image.
+ * A file the index does not name is unreachable: written just before the app
+ * died, or left by an index write that failed. Removing them here, once per
+ * session and before anything new is written, keeps the byte ceiling true.
  */
-exports.deriveCacheKey = deriveCacheKey;
-const cacheUsable = () => (0, _mobileCore.isStorageAvailable)();
-const readEntry = async cacheKey => {
-  if (!cacheUsable()) {
-    return null;
+const removeOrphanFiles = entries => {
+  try {
+    const folder = new _expoFileSystem.Directory(_expoFileSystem.Paths.cache, FOLDER);
+    if (!folder.exists) {
+      return;
+    }
+    const known = new Set([...entries.values()].map(entry => imageFile(entry.fileName).uri));
+    for (const item of folder.list()) {
+      if (!known.has(item.uri)) {
+        item.delete();
+      }
+    }
+  } catch (error) {
+    _mobileCore.Logger.warn('[AuthedImage] could not tidy the image cache folder', error);
   }
-  const values = await _mobileCore.Storage.multiGet([`${DATA_PREFIX}${cacheKey}`, `${META_PREFIX}${cacheKey}`]);
-  const dataUri = values[`${DATA_PREFIX}${cacheKey}`];
-  const rawMeta = values[`${META_PREFIX}${cacheKey}`];
-  if (!dataUri || !rawMeta) {
-    return null;
+};
+const readStoredIndex = async () => {
+  const entries = new Map();
+  if (!(0, _mobileCore.isStorageAvailable)()) {
+    return entries;
+  }
+  const raw = await _mobileCore.Storage.getItem(INDEX_KEY);
+  if (!raw) {
+    await removeLegacyEntries();
+    return entries;
   }
   try {
-    return {
-      dataUri,
-      meta: JSON.parse(rawMeta)
-    };
+    for (const [cacheKey, entry] of Object.entries(JSON.parse(raw))) {
+      entries.set(cacheKey, entry);
+    }
   } catch {
+    // An index we cannot parse names no file, so every file becomes an orphan
+    // and is removed below: the cache starts empty rather than wrong.
+  }
+  return entries;
+};
+const loadIndex = () => {
+  if (index) {
+    return Promise.resolve(index);
+  }
+  if (!indexLoad) {
+    indexLoad = readStoredIndex().then(entries => {
+      removeOrphanFiles(entries);
+      index = entries;
+      return entries;
+    }).finally(() => {
+      indexLoad = null;
+    });
+  }
+  return indexLoad;
+};
+const deleteFile = fileName => {
+  try {
+    const file = imageFile(fileName);
+    if (file.exists) {
+      file.delete();
+    }
+  } catch (error) {
+    _mobileCore.Logger.warn('[AuthedImage] could not delete a cached image file', error);
+  }
+};
+const readEntry = async cacheKey => {
+  const entries = await loadIndex();
+  const entry = entries.get(cacheKey);
+  if (!entry) {
     return null;
   }
+  const file = imageFile(entry.fileName);
+  // The cache folder is the OS's to reclaim under storage pressure, so an
+  // entry can outlive its file.
+  if (!file.exists) {
+    entries.delete(cacheKey);
+    await persistIndex(entries);
+    return null;
+  }
+  return {
+    fileUri: file.uri,
+    meta: toMeta(entry)
+  };
 };
 exports.readEntry = readEntry;
 const isFresh = (meta, ttlMs, now = Date.now()) => now - meta.fetchedAt < ttlMs;
 exports.isFresh = isFresh;
-const touchEntry = async (cacheKey, meta) => {
-  if (!cacheUsable()) {
+const touchEntry = async cacheKey => {
+  const entries = await loadIndex();
+  const entry = entries.get(cacheKey);
+  if (!entry) {
     return;
   }
-  await _mobileCore.Storage.setItem(`${META_PREFIX}${cacheKey}`, JSON.stringify({
-    ...meta,
-    lastAccessedAt: Date.now()
-  }));
+  entry.lastAccessedAt = Date.now();
+  if (entry.lastAccessedAt - entry.persistedAccessAt >= TOUCH_PERSIST_MS) {
+    await persistIndex(entries);
+  }
 };
 exports.touchEntry = touchEntry;
-const listMeta = async () => {
-  if (!cacheUsable()) {
-    return [];
-  }
-  const keys = await _mobileCore.Storage.getAllKeys();
-  const metaKeys = keys.filter(key => key.startsWith(META_PREFIX));
-  if (metaKeys.length === 0) {
-    return [];
-  }
-  const values = await _mobileCore.Storage.multiGet(metaKeys);
-  const out = [];
-  for (const key of metaKeys) {
-    const raw = values[key];
-    if (!raw) {
-      continue;
-    }
-    try {
-      out.push({
-        cacheKey: key.slice(META_PREFIX.length),
-        meta: JSON.parse(raw)
-      });
-    } catch {
-      // A meta entry we cannot parse is unusable; dropping it from the ledger
-      // lets the next eviction pass remove its orphaned data entry.
-    }
+const evictIfNeeded = entries => {
+  let total = 0;
+  for (const entry of entries.values()) {
+    total += entry.bytes;
   }
-  return out;
-};
-const evictIfNeeded = async () => {
-  const entries = await listMeta();
-  let total = entries.reduce((sum, entry) => sum + entry.meta.bytes, 0);
   if (total <= byteCeiling) {
-    return;
+    return 0;
   }
-  const ordered = [...entries].sort((a, b) => a.meta.lastAccessedAt - b.meta.lastAccessedAt);
-  const doomed = [];
-  for (const entry of ordered) {
+  const ordered = [...entries].sort(([, a], [, b]) => a.lastAccessedAt - b.lastAccessedAt);
+  let evicted = 0;
+  for (const [cacheKey, entry] of ordered) {
     if (total <= byteCeiling) {
       break;
     }
-    doomed.push(`${DATA_PREFIX}${entry.cacheKey}`, `${META_PREFIX}${entry.cacheKey}`);
-    total -= entry.meta.bytes;
-  }
-  if (doomed.length > 0) {
-    await _mobileCore.Storage.multiRemove(doomed);
-    _mobileCore.Logger.info(`[AuthedImage] evicted ${doomed.length / 2} cached image(s) over the byte ceiling`);
+    entries.delete(cacheKey);
+    deleteFile(entry.fileName);
+    total -= entry.bytes;
+    evicted += 1;
   }
+  return evicted;
 };
 const clearAuthedImageCache = async () => {
-  if (!cacheUsable()) {
-    return;
+  const entries = await loadIndex();
+  entries.clear();
+  const folder = new _expoFileSystem.Directory(_expoFileSystem.Paths.cache, FOLDER);
+  if (folder.exists) {
+    folder.delete();
   }
-  const keys = await _mobileCore.Storage.getAllKeys();
-  const ours = keys.filter(key => key.startsWith(KEY_PREFIX));
-  if (ours.length > 0) {
-    await _mobileCore.Storage.multiRemove(ours);
+  if ((0, _mobileCore.isStorageAvailable)()) {
+    await _mobileCore.Storage.removeItem(INDEX_KEY);
   }
 };
 exports.clearAuthedImageCache = clearAuthedImageCache;
 const authedImageCacheStats = async () => {
-  const entries = await listMeta();
+  const entries = await loadIndex();
+  let bytes = 0;
+  for (const entry of entries.values()) {
+    bytes += entry.bytes;
+  }
   return {
-    entries: entries.length,
-    bytes: entries.reduce((sum, entry) => sum + entry.meta.bytes, 0)
+    entries: entries.size,
+    bytes
   };
 };
 exports.authedImageCacheStats = authedImageCacheStats;
@@ -179,29 +265,48 @@ const fetchAndStore = async (cacheKey, options, signal) => {
     }
     throw new Error(`[@webority/mobile-ui] AuthedImage could not load "${options.uri}": the server ` + `answered ${status}. Check the URL and whether the request needs to be signed in ` + '(pass the signed-in client as `client`, or authenticated={false} for public media).');
   }
-  const buffer = response.data ?? new ArrayBuffer(0);
+  const bytes = new Uint8Array(response.data ?? new ArrayBuffer(0));
   const rawType = responseHeader(response.headers, 'content-type');
   const contentType = (rawType ? rawType.split(';')[0].trim() : '') || 'image/jpeg';
-  const dataUri = `data:${contentType};base64,${(0, _mobileCore.encodeBase64)(buffer)}`;
+
+  // Loaded before the write, so the orphan sweep in loadIndex can never see
+  // this file before its entry exists.
+  const entries = await loadIndex();
   const now = Date.now();
-  // `bytes` measures the stored data URI, not the decoded image: the ceiling
-  // exists to bound what sits in storage, and base64 costs about a third more.
-  const meta = {
+  // A new name per fetch: native image caches key on the URI, so rewriting one
+  // path in place could keep showing the old picture after a refresh.
+  const fileName = `${cacheKey}-${now.toString(36)}`;
+  const file = imageFile(fileName);
+  try {
+    file.create({
+      intermediates: true,
+      overwrite: true
+    });
+    file.write(bytes);
+  } catch (error) {
+    throw new Error(`[@webority/mobile-ui] AuthedImage fetched "${options.uri}" but could not write it to ` + `the app's cache folder: ${error instanceof Error ? error.message : String(error)}. ` + 'The device may be out of storage.');
+  }
+  const entry = {
     fetchedAt: now,
-    bytes: dataUri.length,
+    bytes: bytes.byteLength,
     contentType,
-    lastAccessedAt: now
+    lastAccessedAt: now,
+    fileName,
+    persistedAccessAt: now
   };
-  if (cacheUsable()) {
-    await _mobileCore.Storage.multiSet({
-      [`${DATA_PREFIX}${cacheKey}`]: dataUri,
-      [`${META_PREFIX}${cacheKey}`]: JSON.stringify(meta)
-    });
-    await evictIfNeeded();
+  const previous = entries.get(cacheKey);
+  entries.set(cacheKey, entry);
+  if (previous && previous.fileName !== fileName) {
+    deleteFile(previous.fileName);
+  }
+  const evicted = evictIfNeeded(entries);
+  await persistIndex(entries);
+  if (evicted > 0) {
+    _mobileCore.Logger.info(`[AuthedImage] evicted ${evicted} cached image(s) over the byte ceiling`);
   }
   return {
-    dataUri,
-    meta
+    fileUri: file.uri,
+    meta: toMeta(entry)
   };
 };
 const inFlight = new Map();

package/lib/module/components/AuthedImage/AuthedImage.js

@@ -78,10 +78,10 @@ const AuthedImage = props => {
         return;
       }
       if (cached && isFresh(cached.meta, ttlMs)) {
-        void touchEntry(key, cached.meta);
+        void touchEntry(key);
         finish({
           status: 'ready',
-          dataUri: cached.dataUri
+          fileUri: cached.fileUri
         });
         return;
       }
@@ -99,7 +99,7 @@ const AuthedImage = props => {
         const result = await entry.promise;
         finish({
           status: 'ready',
-          dataUri: result.dataUri
+          fileUri: result.fileUri
         });
       } catch (error) {
         if (cancelled) {
@@ -110,7 +110,7 @@ const AuthedImage = props => {
         if (cached) {
           finish({
             status: 'ready',
-            dataUri: cached.dataUri
+            fileUri: cached.fileUri
           });
           return;
         }
@@ -187,7 +187,7 @@ const AuthedImage = props => {
     testID: testID,
     style: style,
     source: {
-      uri: state.dataUri
+      uri: state.fileUri
     }
   });
 };

package/lib/module/components/AuthedImage/authedImageCache.js

@@ -1,11 +1,21 @@
 "use strict";
 
-import { ACCESS_TOKEN_KEY, encodeBase64, getToken, isStorageAvailable, Logger, publicClient, Storage } from '@webority/mobile-core';
+import { ACCESS_TOKEN_KEY, getToken, isStorageAvailable, Logger, publicClient, Storage } from '@webority/mobile-core';
+import { Directory, File, Paths } from 'expo-file-system';
 import { hashString } from "../../utils/hashString.js";
-const KEY_PREFIX = '@webority/authed-image/v1/';
-const DATA_PREFIX = `${KEY_PREFIX}d/`;
-const META_PREFIX = `${KEY_PREFIX}m/`;
+const INDEX_KEY = '@webority/authed-image/v2/index';
+// Releases before the file cache kept every image as a base64 string in the
+// key-value store, up to the 50 MB ceiling. Nothing reads those rows any more,
+// so they are removed the first time this version finds no index.
+const LEGACY_PREFIX = '@webority/authed-image/v1/';
+const FOLDER = 'authed-images';
 const DEFAULT_BYTE_CEILING = 50 * 1024 * 1024;
+
+// A hit only moves an entry's last access in memory. Writing the index on every
+// hit would put a storage write behind every row of a scrolling list, so a hit
+// persists only when the stored time is this old; least-recently-used order
+// survives a restart to within this window.
+const TOUCH_PERSIST_MS = 60 * 60 * 1000;
 export const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 let byteCeiling = DEFAULT_BYTE_CEILING;
 
@@ -23,114 +33,190 @@ export const setAuthedImageCacheLimit = bytes => {
 export const getAuthedImageCacheLimit = () => byteCeiling;
 
 /**
- * Hex only by construction, so it is always a safe storage key segment.
+ * Hex only by construction, so it is always a safe file name segment.
  */
 export const deriveCacheKey = (uri, override) => hashString(override ?? uri);
+const imageFile = fileName => new File(Paths.cache, FOLDER, fileName);
+const toMeta = ({
+  fetchedAt,
+  bytes,
+  contentType,
+  lastAccessedAt
+}) => ({
+  fetchedAt,
+  bytes,
+  contentType,
+  lastAccessedAt
+});
+
+// The image bytes live in files; only this small index goes to the key-value
+// store. A store that fails costs persistence across restarts, never an image:
+// Storage logs and returns false rather than throwing.
+let index = null;
+let indexLoad = null;
+const persistIndex = async entries => {
+  if (!isStorageAvailable()) {
+    return;
+  }
+  const out = {};
+  for (const [cacheKey, entry] of entries) {
+    out[cacheKey] = {
+      ...entry,
+      persistedAccessAt: entry.lastAccessedAt
+    };
+  }
+  if (await Storage.setItem(INDEX_KEY, JSON.stringify(out))) {
+    for (const entry of entries.values()) {
+      entry.persistedAccessAt = entry.lastAccessedAt;
+    }
+  }
+};
+const removeLegacyEntries = async () => {
+  const keys = await Storage.getAllKeys();
+  const legacy = keys.filter(key => key.startsWith(LEGACY_PREFIX));
+  if (legacy.length > 0) {
+    await Storage.multiRemove(legacy);
+  }
+};
 
 /**
- * The cache is an OPTIMISATION, so a failing store must never stop an image
- * rendering. That used to mean guarding on whether a backend existed at all,
- * warning once and skipping the cache; under Expo-first the backend ships with
- * the library, so "no backend" is no longer a state an app can be in and that
- * branch was unreachable.
- *
- * What remains is a store that exists and FAILS, which the per-operation error
- * handling below already covers: each read returns null and each write returns
- * false, the image still fetches, and nothing is logged per image.
+ * A file the index does not name is unreachable: written just before the app
+ * died, or left by an index write that failed. Removing them here, once per
+ * session and before anything new is written, keeps the byte ceiling true.
  */
-const cacheUsable = () => isStorageAvailable();
-export const readEntry = async cacheKey => {
-  if (!cacheUsable()) {
-    return null;
+const removeOrphanFiles = entries => {
+  try {
+    const folder = new Directory(Paths.cache, FOLDER);
+    if (!folder.exists) {
+      return;
+    }
+    const known = new Set([...entries.values()].map(entry => imageFile(entry.fileName).uri));
+    for (const item of folder.list()) {
+      if (!known.has(item.uri)) {
+        item.delete();
+      }
+    }
+  } catch (error) {
+    Logger.warn('[AuthedImage] could not tidy the image cache folder', error);
   }
-  const values = await Storage.multiGet([`${DATA_PREFIX}${cacheKey}`, `${META_PREFIX}${cacheKey}`]);
-  const dataUri = values[`${DATA_PREFIX}${cacheKey}`];
-  const rawMeta = values[`${META_PREFIX}${cacheKey}`];
-  if (!dataUri || !rawMeta) {
-    return null;
+};
+const readStoredIndex = async () => {
+  const entries = new Map();
+  if (!isStorageAvailable()) {
+    return entries;
+  }
+  const raw = await Storage.getItem(INDEX_KEY);
+  if (!raw) {
+    await removeLegacyEntries();
+    return entries;
   }
   try {
-    return {
-      dataUri,
-      meta: JSON.parse(rawMeta)
-    };
+    for (const [cacheKey, entry] of Object.entries(JSON.parse(raw))) {
+      entries.set(cacheKey, entry);
+    }
   } catch {
+    // An index we cannot parse names no file, so every file becomes an orphan
+    // and is removed below: the cache starts empty rather than wrong.
+  }
+  return entries;
+};
+const loadIndex = () => {
+  if (index) {
+    return Promise.resolve(index);
+  }
+  if (!indexLoad) {
+    indexLoad = readStoredIndex().then(entries => {
+      removeOrphanFiles(entries);
+      index = entries;
+      return entries;
+    }).finally(() => {
+      indexLoad = null;
+    });
+  }
+  return indexLoad;
+};
+const deleteFile = fileName => {
+  try {
+    const file = imageFile(fileName);
+    if (file.exists) {
+      file.delete();
+    }
+  } catch (error) {
+    Logger.warn('[AuthedImage] could not delete a cached image file', error);
+  }
+};
+export const readEntry = async cacheKey => {
+  const entries = await loadIndex();
+  const entry = entries.get(cacheKey);
+  if (!entry) {
+    return null;
+  }
+  const file = imageFile(entry.fileName);
+  // The cache folder is the OS's to reclaim under storage pressure, so an
+  // entry can outlive its file.
+  if (!file.exists) {
+    entries.delete(cacheKey);
+    await persistIndex(entries);
     return null;
   }
+  return {
+    fileUri: file.uri,
+    meta: toMeta(entry)
+  };
 };
 export const isFresh = (meta, ttlMs, now = Date.now()) => now - meta.fetchedAt < ttlMs;
-export const touchEntry = async (cacheKey, meta) => {
-  if (!cacheUsable()) {
+export const touchEntry = async cacheKey => {
+  const entries = await loadIndex();
+  const entry = entries.get(cacheKey);
+  if (!entry) {
     return;
   }
-  await Storage.setItem(`${META_PREFIX}${cacheKey}`, JSON.stringify({
-    ...meta,
-    lastAccessedAt: Date.now()
-  }));
-};
-const listMeta = async () => {
-  if (!cacheUsable()) {
-    return [];
-  }
-  const keys = await Storage.getAllKeys();
-  const metaKeys = keys.filter(key => key.startsWith(META_PREFIX));
-  if (metaKeys.length === 0) {
-    return [];
-  }
-  const values = await Storage.multiGet(metaKeys);
-  const out = [];
-  for (const key of metaKeys) {
-    const raw = values[key];
-    if (!raw) {
-      continue;
-    }
-    try {
-      out.push({
-        cacheKey: key.slice(META_PREFIX.length),
-        meta: JSON.parse(raw)
-      });
-    } catch {
-      // A meta entry we cannot parse is unusable; dropping it from the ledger
-      // lets the next eviction pass remove its orphaned data entry.
-    }
+  entry.lastAccessedAt = Date.now();
+  if (entry.lastAccessedAt - entry.persistedAccessAt >= TOUCH_PERSIST_MS) {
+    await persistIndex(entries);
   }
-  return out;
 };
-const evictIfNeeded = async () => {
-  const entries = await listMeta();
-  let total = entries.reduce((sum, entry) => sum + entry.meta.bytes, 0);
+const evictIfNeeded = entries => {
+  let total = 0;
+  for (const entry of entries.values()) {
+    total += entry.bytes;
+  }
   if (total <= byteCeiling) {
-    return;
+    return 0;
   }
-  const ordered = [...entries].sort((a, b) => a.meta.lastAccessedAt - b.meta.lastAccessedAt);
-  const doomed = [];
-  for (const entry of ordered) {
+  const ordered = [...entries].sort(([, a], [, b]) => a.lastAccessedAt - b.lastAccessedAt);
+  let evicted = 0;
+  for (const [cacheKey, entry] of ordered) {
     if (total <= byteCeiling) {
       break;
     }
-    doomed.push(`${DATA_PREFIX}${entry.cacheKey}`, `${META_PREFIX}${entry.cacheKey}`);
-    total -= entry.meta.bytes;
-  }
-  if (doomed.length > 0) {
-    await Storage.multiRemove(doomed);
-    Logger.info(`[AuthedImage] evicted ${doomed.length / 2} cached image(s) over the byte ceiling`);
+    entries.delete(cacheKey);
+    deleteFile(entry.fileName);
+    total -= entry.bytes;
+    evicted += 1;
   }
+  return evicted;
 };
 export const clearAuthedImageCache = async () => {
-  if (!cacheUsable()) {
-    return;
+  const entries = await loadIndex();
+  entries.clear();
+  const folder = new Directory(Paths.cache, FOLDER);
+  if (folder.exists) {
+    folder.delete();
   }
-  const keys = await Storage.getAllKeys();
-  const ours = keys.filter(key => key.startsWith(KEY_PREFIX));
-  if (ours.length > 0) {
-    await Storage.multiRemove(ours);
+  if (isStorageAvailable()) {
+    await Storage.removeItem(INDEX_KEY);
   }
 };
 export const authedImageCacheStats = async () => {
-  const entries = await listMeta();
+  const entries = await loadIndex();
+  let bytes = 0;
+  for (const entry of entries.values()) {
+    bytes += entry.bytes;
+  }
   return {
-    entries: entries.length,
-    bytes: entries.reduce((sum, entry) => sum + entry.meta.bytes, 0)
+    entries: entries.size,
+    bytes
   };
 };
 const responseHeader = (headers, name) => {
@@ -167,29 +253,48 @@ const fetchAndStore = async (cacheKey, options, signal) => {
     }
     throw new Error(`[@webority/mobile-ui] AuthedImage could not load "${options.uri}": the server ` + `answered ${status}. Check the URL and whether the request needs to be signed in ` + '(pass the signed-in client as `client`, or authenticated={false} for public media).');
   }
-  const buffer = response.data ?? new ArrayBuffer(0);
+  const bytes = new Uint8Array(response.data ?? new ArrayBuffer(0));
   const rawType = responseHeader(response.headers, 'content-type');
   const contentType = (rawType ? rawType.split(';')[0].trim() : '') || 'image/jpeg';
-  const dataUri = `data:${contentType};base64,${encodeBase64(buffer)}`;
+
+  // Loaded before the write, so the orphan sweep in loadIndex can never see
+  // this file before its entry exists.
+  const entries = await loadIndex();
   const now = Date.now();
-  // `bytes` measures the stored data URI, not the decoded image: the ceiling
-  // exists to bound what sits in storage, and base64 costs about a third more.
-  const meta = {
+  // A new name per fetch: native image caches key on the URI, so rewriting one
+  // path in place could keep showing the old picture after a refresh.
+  const fileName = `${cacheKey}-${now.toString(36)}`;
+  const file = imageFile(fileName);
+  try {
+    file.create({
+      intermediates: true,
+      overwrite: true
+    });
+    file.write(bytes);
+  } catch (error) {
+    throw new Error(`[@webority/mobile-ui] AuthedImage fetched "${options.uri}" but could not write it to ` + `the app's cache folder: ${error instanceof Error ? error.message : String(error)}. ` + 'The device may be out of storage.');
+  }
+  const entry = {
     fetchedAt: now,
-    bytes: dataUri.length,
+    bytes: bytes.byteLength,
     contentType,
-    lastAccessedAt: now
+    lastAccessedAt: now,
+    fileName,
+    persistedAccessAt: now
   };
-  if (cacheUsable()) {
-    await Storage.multiSet({
-      [`${DATA_PREFIX}${cacheKey}`]: dataUri,
-      [`${META_PREFIX}${cacheKey}`]: JSON.stringify(meta)
-    });
-    await evictIfNeeded();
+  const previous = entries.get(cacheKey);
+  entries.set(cacheKey, entry);
+  if (previous && previous.fileName !== fileName) {
+    deleteFile(previous.fileName);
+  }
+  const evicted = evictIfNeeded(entries);
+  await persistIndex(entries);
+  if (evicted > 0) {
+    Logger.info(`[AuthedImage] evicted ${evicted} cached image(s) over the byte ceiling`);
   }
   return {
-    dataUri,
-    meta
+    fileUri: file.uri,
+    meta: toMeta(entry)
   };
 };
 const inFlight = new Map();

package/lib/typescript/commonjs/components/AuthedImage/authedImageCache.d.ts

@@ -7,7 +7,7 @@ export interface AuthedImageCacheMeta {
     lastAccessedAt: number;
 }
 export interface CachedImage {
-    dataUri: string;
+    fileUri: string;
     meta: AuthedImageCacheMeta;
 }
 /**
@@ -18,12 +18,12 @@ export interface CachedImage {
 export declare const setAuthedImageCacheLimit: (bytes: number) => void;
 export declare const getAuthedImageCacheLimit: () => number;
 /**
- * Hex only by construction, so it is always a safe storage key segment.
+ * Hex only by construction, so it is always a safe file name segment.
  */
 export declare const deriveCacheKey: (uri: string, override?: string) => string;
 export declare const readEntry: (cacheKey: string) => Promise<CachedImage | null>;
 export declare const isFresh: (meta: AuthedImageCacheMeta, ttlMs: number, now?: number) => boolean;
-export declare const touchEntry: (cacheKey: string, meta: AuthedImageCacheMeta) => Promise<void>;
+export declare const touchEntry: (cacheKey: string) => Promise<void>;
 export declare const clearAuthedImageCache: () => Promise<void>;
 export declare const authedImageCacheStats: () => Promise<{
     entries: number;

package/lib/typescript/module/components/AuthedImage/authedImageCache.d.ts

@@ -7,7 +7,7 @@ export interface AuthedImageCacheMeta {
     lastAccessedAt: number;
 }
 export interface CachedImage {
-    dataUri: string;
+    fileUri: string;
     meta: AuthedImageCacheMeta;
 }
 /**
@@ -18,12 +18,12 @@ export interface CachedImage {
 export declare const setAuthedImageCacheLimit: (bytes: number) => void;
 export declare const getAuthedImageCacheLimit: () => number;
 /**
- * Hex only by construction, so it is always a safe storage key segment.
+ * Hex only by construction, so it is always a safe file name segment.
  */
 export declare const deriveCacheKey: (uri: string, override?: string) => string;
 export declare const readEntry: (cacheKey: string) => Promise<CachedImage | null>;
 export declare const isFresh: (meta: AuthedImageCacheMeta, ttlMs: number, now?: number) => boolean;
-export declare const touchEntry: (cacheKey: string, meta: AuthedImageCacheMeta) => Promise<void>;
+export declare const touchEntry: (cacheKey: string) => Promise<void>;
 export declare const clearAuthedImageCache: () => Promise<void>;
 export declare const authedImageCacheStats: () => Promise<{
     entries: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/mobile-ui",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "Beautiful, animated, accessible React Native components, theme and form engine for Webority projects.",
   "keywords": [
     "react-native",
@@ -66,6 +66,7 @@
   "peerDependencies": {
     "@webority/mobile-core": ">=0.0.27 <0.1.0",
     "expo": ">=57.0.0",
+    "expo-file-system": ">=57.0.0",
     "expo-haptics": ">=57.0.0",
     "react": "^19.1.0",
     "react-native": ">=0.81.0",