Class: ImageCache

ImageCache()

ImageCache provides persistent IndexedDB storage for coin images (obverse/reverse) and enriched Numista metadata. Images are resized and compressed to JPEG before storage.

Schema: DB: StakTrakrImages v3 Store "coinImages" — keyPath: catalogId (Numista N# string) Store "coinMetadata" — keyPath: catalogId (Numista N# string) Store "userImages" — keyPath: uuid (item UUID string) Store "patternImages" — keyPath: ruleId (pattern rule ID string)

Constructor

new ImageCache()

Source:

Members

_available :boolean

Type:
  • boolean
Source:

_db :IDBDatabase|null

Type:
  • IDBDatabase | null
Source:

_maxDim :number

Max image dimension (px) for resize

Type:
  • number
Source:

_quality :number

Compression quality (0-1)

Type:
  • number
Source:

_quotaBytes :number

Default storage quota in bytes (50 MB)

Type:
  • number
Source:

Methods

(async) _delete() → {Promise.<boolean>}

Source:
Returns:
Type
Promise.<boolean>

(async) _ensureDb() → {Promise.<boolean>}

Ensure the DB connection is alive, reconnecting if stale. Call this before every public operation to guard against browser-initiated connection closures (storage pressure, tab backgrounding, etc.).

Source:
Returns:
Type
Promise.<boolean>

(async) _fetchAndResize(url) → {Promise.<(Blob|null)>}

Fetch an image URL using a multi-strategy cascade that gracefully degrades when CORS headers are unavailable (e.g. Numista CDN).

Strategy A: fetch(CORS) → createImageBitmap → canvas resize → JPEG blob Strategy B: fetch(CORS) succeeded but canvas tainted → store raw blob Strategy C: Image element (no crossOrigin) → canvas → JPEG blob Strategy D: fetch(no-cors) → non-opaque blob if available (opaque blobs rejected — lose data in IDB)

Parameters:
Name Type Description
url string
Source:
Returns:
Type
Promise.<(Blob|null)>

(async) _fetchBlobDirect(url) → {Promise.<(Blob|null)>}

Try to get a raw blob for a URL without canvas processing. Falls back to no-cors fetch (opaque blob — still displayable via object URL).

Parameters:
Name Type Description
url string
Source:
Returns:
Type
Promise.<(Blob|null)>

_get() → {Promise.<(Object|null)>}

Source:
Returns:
Type
Promise.<(Object|null)>

_getAll() → {Promise.<Array>}

Source:
Returns:
Type
Promise.<Array>

_loadImageElement(url, useCorsopt) → {Promise.<ImageBitmap>}

Load an image via HTMLImageElement.

Parameters:
Name Type Attributes Default Description
url string
useCors boolean <optional>
 false

Whether to set crossOrigin='anonymous'
Source:
Returns:
Type
Promise.<ImageBitmap>

(async) _put() → {Promise.<boolean>}

Source:
Returns:
Type
Promise.<boolean>

(async) _resizeAndCompress(source) → {Promise.<(Blob|null)>}

Resize and compress an image source using ImageProcessor (STACK-95). Falls back to inline Canvas JPEG if ImageProcessor is unavailable.

Parameters:
Name Type Description
source ImageBitmap | HTMLImageElement
Source:
Returns:
Type
Promise.<(Blob|null)>

_txComplete()

Wait for a transaction to complete.

Source:

(async) cacheImages(catalogId, obverseUrl, reverseUrl) → {Promise.<boolean>}

Fetch, resize, compress, and store obverse/reverse images for a coin type.

Parameters:
Name Type Description
catalogId string

Numista N# identifier
obverseUrl string

CDN URL for obverse image
reverseUrl string

CDN URL for reverse image
Source:
Returns:

true if at least one image was cached

Type
Promise.<boolean>

(async) cacheMetadata(catalogId, numistaResult) → {Promise.<boolean>}

Store enriched Numista metadata for a coin type.

Parameters:
Name Type Description
catalogId string

Numista N# identifier
numistaResult Object

Normalized Numista result object
Source:
Returns:
Type
Promise.<boolean>

(async) cachePatternImage(ruleId, obverseBlob, reverseBlob) → {Promise.<boolean>}

Store pattern rule images (obverse/reverse blobs).

Parameters:
Name Type Description
ruleId string

Pattern rule ID
obverseBlob Blob | null
reverseBlob Blob | null
Source:
Returns:
Type
Promise.<boolean>

(async) cacheUserImage(uuid, obverse, reverseopt) → {Promise.<boolean>}

Store a user-uploaded image for an inventory item.

Parameters:
Name Type Attributes Default Description
uuid string

Item UUID
obverse Blob

Processed obverse image blob
reverse Blob <optional>
 null

Optional reverse image blob
Source:
Returns:
Type
Promise.<boolean>

(async) clearAll() → {Promise.<boolean>}

Clear both object stores.

Source:
Returns:
Type
Promise.<boolean>

(async) deleteImages(catalogId) → {Promise.<boolean>}

Remove a single image record.

Parameters:
Name Type Description
catalogId string
Source:
Returns:
Type
Promise.<boolean>

(async) deleteMetadata(catalogId) → {Promise.<boolean>}

Delete cached metadata for a catalog ID.

Parameters:
Name Type Description
catalogId string
Source:
Returns:
Type
Promise.<boolean>

(async) deletePatternImage(ruleId) → {Promise.<boolean>}

Delete a pattern image record.

Parameters:
Name Type Description
ruleId string
Source:
Returns:
Type
Promise.<boolean>

(async) deleteUserImage(uuid) → {Promise.<boolean>}

Delete a user-uploaded image.

Parameters:
Name Type Description
uuid string

Item UUID
Source:
Returns:
Type
Promise.<boolean>

(async) exportAllCoinImages() → {Promise.<Array>}

Export all coin (CDN) image records for backup.

Source:
Returns:
Type
Promise.<Array>

(async) exportAllImages() → {Promise.<Array>}

Export all image records (with blobs) for backup.

Source:
Returns:
Type
Promise.<Array>

(async) exportAllMetadata() → {Promise.<Array>}

Export all metadata records for backup.

Source:
Returns:
Type
Promise.<Array>

(async) exportAllPatternImages() → {Promise.<Array>}

Export all pattern image records for backup.

Source:
Returns:
Type
Promise.<Array>

(async) exportAllUserImages() → {Promise.<Array>}

Export all user images for backup.

Source:
Returns:
Type
Promise.<Array>

(async) getImageUrl(catalogId, side) → {Promise.<(string|null)>}

Create an object URL from a cached image blob. Caller is responsible for revoking via URL.revokeObjectURL().

Parameters:
Name Type Description
catalogId string
side 'obverse' | 'reverse'
Source:
Returns:

Object URL or null

Type
Promise.<(string|null)>

(async) getImages(catalogId) → {Promise.<(Object|null)>}

Retrieve the full image record for a coin type.

Parameters:
Name Type Description
catalogId string
Source:
Returns:
Type
Promise.<(Object|null)>

(async) getMetadata(catalogId) → {Promise.<(Object|null)>}

Retrieve the metadata record for a coin type.

Parameters:
Name Type Description
catalogId string
Source:
Returns:
Type
Promise.<(Object|null)>

(async) getPatternImage(ruleId) → {Promise.<(Object|null)>}

Retrieve a pattern image record by rule ID.

Parameters:
Name Type Description
ruleId string
Source:
Returns:
Type
Promise.<(Object|null)>

(async) getPatternImageUrl(ruleId, sideopt) → {Promise.<(string|null)>}

Get a pattern image as an object URL. Caller must revoke the URL when done.

Parameters:
Name Type Attributes Default Description
ruleId string
side 'obverse' | 'reverse' <optional>
 'obverse'
Source:
Returns:
Type
Promise.<(string|null)>

(async) getStorageUsage() → {Promise.<{count: number, totalBytes: number, limitBytes: number, metadataCount: number, userImageCount: number, patternImageCount: number, numistaCount: number}>}

Calculate current storage usage across all stores.

Source:
Returns:
Type
Promise.<{count: number, totalBytes: number, limitBytes: number, metadataCount: number, userImageCount: number, patternImageCount: number, numistaCount: number}>

(async) getUserImage(uuid) → {Promise.<(Object|null)>}

Retrieve a user-uploaded image record.

Parameters:
Name Type Description
uuid string

Item UUID
Source:
Returns:
Type
Promise.<(Object|null)>

(async) getUserImageUrl(uuid, sideopt) → {Promise.<(string|null)>}

Get a user-uploaded image as an object URL. Caller must revoke the URL when done.

Parameters:
Name Type Attributes Default Description
uuid string

Item UUID
side 'obverse' | 'reverse' <optional>
 'obverse'
Source:
Returns:
Type
Promise.<(string|null)>

(async) hasImages(catalogId) → {Promise.<boolean>}

Quick existence check without loading blobs.

Parameters:
Name Type Description
catalogId string
Source:
Returns:
Type
Promise.<boolean>

(async) importImageRecord(record) → {Promise.<boolean>}

Import a single image record (from ZIP restore).

Parameters:
Name Type Description
record Object

Image record with catalogId, obverse, reverse blobs
Source:
Returns:
Type
Promise.<boolean>

(async) importMetadataRecord(record) → {Promise.<boolean>}

Import a single metadata record (from ZIP restore).

Parameters:
Name Type Description
record Object

Metadata record with catalogId key
Source:
Returns:
Type
Promise.<boolean>

(async) importPatternImageRecord(record) → {Promise.<boolean>}

Import a single pattern image record (from ZIP restore).

Parameters:
Name Type Description
record Object

Pattern image record with ruleId key
Source:
Returns:
Type
Promise.<boolean>

(async) importUserImageRecord(record) → {Promise.<boolean>}

Import a single user image record (from ZIP restore).

Parameters:
Name Type Description
record Object

User image record with uuid key
Source:
Returns:
Type
Promise.<boolean>

(async) init() → {Promise.<boolean>}

Open (or create) the IndexedDB database. Safe to call multiple times.

Source:
Returns:

true if DB opened successfully

Type
Promise.<boolean>

isAvailable() → {boolean}

Whether IndexedDB opened successfully.

Source:
Returns:
Type
boolean

(async) listAllCachedIds() → {Promise.<Array.<string>>}

List all cached catalog IDs without loading blob data. Uses key-only cursor for minimal memory footprint.

Source:
Returns:
Type
Promise.<Array.<string>>

(async) resolveImageForItem(item) → {Promise.<({catalogId: string, source: ('user'|'pattern'|'numista')}|null)>}

Resolve the best available image for an inventory item. Default: user upload → pattern image → numista cache → null. Override: numista cache → user upload → pattern image → null.

Parameters:
Name Type Description
item Object

Inventory item with uuid, numistaId, name, metal, type fields
Source:
Returns:
Type
Promise.<({catalogId: string, source: ('user'|'pattern'|'numista')}|null)>

(async) resolveImageUrlForItem(item, sideopt) → {Promise.<(string|null)>}

Resolves and returns an object URL for the best available image side. Uses resolveImageForItem() to select source, then loads the requested side.

Parameters:
Name Type Attributes Default Description
item Object

Inventory item with uuid/numistaId/name metadata
side 'obverse' | 'reverse' <optional>
 'obverse'
Source:
Returns:

Object URL (caller must revoke) or null

Type
Promise.<(string|null)>

(static) isValidImageUrl(url) → {boolean}

Check whether a string looks like a usable image URL. Rejects corrupted URLs that have had special characters stripped.

Parameters:
Name Type Description
url string
Source:
Returns:
Type
boolean