Refactor duplicated patterns into shared helpers

This commit is contained in:
Alan Grainger
2026-06-05 12:46:28 +12:00
parent c1b58011aa
commit cefe2e81ff
7 changed files with 294 additions and 110 deletions
+63 -48
View File
@@ -123,6 +123,10 @@ function writePersistedState (open: boolean) {
}
// ----- content rendering ---------------------------------------------------
//
// Sidebar UI placement for each metadata field. Server-side gating lives in
// `gallery/exif.ts` (rules table); legacy-config migration lives in
// `config/migrations.ts`. Adding a new field requires updating all three.
function renderContents (root: HTMLElement, item: GalleryItem | undefined) {
root.replaceChildren()
@@ -213,67 +217,78 @@ function renderDateRow (iso: string): HTMLElement {
return row
}
function renderFileRow (exif: GalleryExif): HTMLElement | null {
if (!exif.fileName && !exif.width && !exif.fileSizeInByte) return null
const row = makeRow(ICON_IMAGE)
interface RowSpec {
icon: string
// Title paragraph at the top of the row body. Falsy values are omitted.
label?: string | null
labelClass?: string
// Stats rendered as `<span>` chips in a flex row beneath the label.
// Nullish entries are skipped, so callers can write
// `exif.iso != null ? 'ISO ' + exif.iso : null` and not branch.
stats: Array<string | null | undefined>
}
/**
* Build one info-sidebar row. Returns `null` when the row would have
* neither a label nor any non-null stat, so the caller can skip appending.
*/
function renderRow (spec: RowSpec): HTMLElement | null {
const presentStats = spec.stats.filter((s): s is string => s != null && s !== '')
if (!spec.label && presentStats.length === 0) return null
const row = makeRow(spec.icon)
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement
if (exif.fileName) {
const name = document.createElement('p')
name.className = 'ipp-sidebar-filename'
name.textContent = exif.fileName
body.appendChild(name)
if (spec.label) {
const p = document.createElement('p')
if (spec.labelClass) p.className = spec.labelClass
p.textContent = spec.label
body.appendChild(p)
}
if (exif.width && exif.height) {
if (presentStats.length) {
const stats = document.createElement('div')
stats.className = 'ipp-sidebar-stats'
const mp = Math.round((exif.width * exif.height) / 1_000_000)
if (mp >= 1) stats.appendChild(makeStat(mp + ' MP'))
stats.appendChild(makeStat(exif.width + ' x ' + exif.height))
if (exif.fileSizeInByte) stats.appendChild(makeStat(formatBytes(exif.fileSizeInByte)))
body.appendChild(stats)
} else if (exif.fileSizeInByte) {
const stats = document.createElement('div')
stats.className = 'ipp-sidebar-stats'
stats.appendChild(makeStat(formatBytes(exif.fileSizeInByte)))
for (const s of presentStats) stats.appendChild(makeStat(s))
body.appendChild(stats)
}
return row
}
function renderFileRow (exif: GalleryExif): HTMLElement | null {
const hasDims = !!(exif.width && exif.height)
const mp = hasDims ? Math.round((exif.width! * exif.height!) / 1_000_000) : 0
return renderRow({
icon: ICON_IMAGE,
label: exif.fileName,
labelClass: 'ipp-sidebar-filename',
stats: [
hasDims && mp >= 1 ? mp + ' MP' : null,
hasDims ? exif.width + ' x ' + exif.height : null,
exif.fileSizeInByte ? formatBytes(exif.fileSizeInByte) : null
]
})
}
function renderCameraRow (exif: GalleryExif): HTMLElement | null {
if (!exif.make && !exif.model && exif.exposureTime == null && exif.iso == null) return null
const row = makeRow(ICON_CAMERA)
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement
const label = [exif.make, exif.model].filter(Boolean).join(' ').trim()
if (label) {
const p = document.createElement('p')
p.textContent = label
body.appendChild(p)
}
const stats = document.createElement('div')
stats.className = 'ipp-sidebar-stats'
if (exif.exposureTime) stats.appendChild(makeStat(exif.exposureTime + ' s'))
if (exif.iso != null) stats.appendChild(makeStat('ISO ' + exif.iso))
if (stats.childElementCount) body.appendChild(stats)
return row
return renderRow({
icon: ICON_CAMERA,
label: [exif.make, exif.model].filter(Boolean).join(' ').trim() || null,
stats: [
exif.exposureTime ? exif.exposureTime + ' s' : null,
exif.iso != null ? 'ISO ' + exif.iso : null
]
})
}
function renderLensRow (exif: GalleryExif): HTMLElement | null {
if (!exif.lensModel && exif.fNumber == null && exif.focalLength == null) return null
const row = makeRow(ICON_IRIS)
const body = row.querySelector('.ipp-sidebar-row-body') as HTMLElement
if (exif.lensModel) {
const p = document.createElement('p')
p.className = 'ipp-sidebar-lens'
p.textContent = exif.lensModel
body.appendChild(p)
}
const stats = document.createElement('div')
stats.className = 'ipp-sidebar-stats'
if (exif.fNumber != null) stats.appendChild(makeStat('f/' + exif.fNumber))
if (exif.focalLength != null) stats.appendChild(makeStat(exif.focalLength + ' mm'))
if (stats.childElementCount) body.appendChild(stats)
return row
return renderRow({
icon: ICON_IRIS,
label: exif.lensModel,
labelClass: 'ipp-sidebar-lens',
stats: [
exif.fNumber != null ? 'f/' + exif.fNumber : null,
exif.focalLength != null ? exif.focalLength + ' mm' : null
]
})
}
function renderLocation (exif: GalleryExif): HTMLElement {
+30 -21
View File
@@ -56,18 +56,7 @@ export function virtualize () {
if (l.top > bottom) break
neededTiles.add(l.index)
}
for (const [index, el] of state.renderedTiles) {
if (!neededTiles.has(index)) {
el.remove()
state.renderedTiles.delete(index)
}
}
for (const index of neededTiles) {
if (state.renderedTiles.has(index)) continue
const tile = createTile(index)
state.container.appendChild(tile)
state.renderedTiles.set(index, tile)
}
syncRendered(neededTiles, state.renderedTiles, createTile)
// Group headers (when grouping is enabled; headers is empty otherwise)
const neededHeaders = new Set<string>()
@@ -76,19 +65,39 @@ export function virtualize () {
if (h.top > bottom) break
neededHeaders.add(h.label)
}
for (const [label, el] of state.renderedHeaders) {
if (!neededHeaders.has(label)) {
syncRendered(neededHeaders, state.renderedHeaders, (label) => {
const h = state.headers.find(x => x.label === label)
return h ? createHeader(h) : null
})
}
/**
* Reconcile a Map of rendered DOM elements against the set of keys that
* should currently be on screen: remove elements whose key is no longer
* needed, then create + append elements for keys that aren't rendered yet.
*
* The `create` callback may return `null` when the key can't be resolved
* (e.g. a stale header label that no longer matches any layout entry); in
* that case nothing is added for the key and the Map is left alone.
*/
function syncRendered<K> (
needed: Set<K>,
rendered: Map<K, HTMLElement>,
create: (key: K) => HTMLElement | null
): void {
if (!state.container) return
for (const [key, el] of rendered) {
if (!needed.has(key)) {
el.remove()
state.renderedHeaders.delete(label)
rendered.delete(key)
}
}
for (const label of neededHeaders) {
if (state.renderedHeaders.has(label)) continue
const h = state.headers.find(x => x.label === label)
if (!h) continue
const el = createHeader(h)
for (const key of needed) {
if (rendered.has(key)) continue
const el = create(key)
if (!el) continue
state.container.appendChild(el)
state.renderedHeaders.set(label, el)
rendered.set(key, el)
}
}
+6
View File
@@ -146,6 +146,12 @@ function applyDescriptionSplitShim (config: Config): void {
* users - which is the safer privacy default and matches the policy the
* new design is establishing.
*/
// These lists are frozen at v2.3.0 and intentionally do NOT track the
// current field set. The server's source-of-truth rules table lives in
// `gallery/exif.ts`, and the sidebar's UI placement lives in
// `client/sidebar.ts`. New fields added in future versions deliberately
// won't auto-appear for legacy `enabled: true` users via this shim - they
// should opt in explicitly.
const LEGACY_EXIF_FIELDS = [
'dateTimeOriginal', 'fileName', 'dimensions', 'fileSize',
'make', 'model', 'lensModel', 'exposureTime', 'iso',
+9
View File
@@ -31,6 +31,15 @@ function copy (key: keyof ExifInfo & keyof GalleryExif): FieldRule {
same string. `copy` handles the whole if/copy dance for each. Fields
that need special handling (fileName, dimensions, fileSize, gps) appear
inline in the `*_RULES` arrays below.
Adding a new metadata field: this rules table is the server-side source
of truth. Two other places carry parallel knowledge of the field set:
- `client/sidebar.ts` (renderRow specs decide where the field appears
in the info sidebar UI)
- `config/migrations.ts` LEGACY_* arrays (frozen v2.x field list used
by the `enabled -> per-field` shim; do NOT extend when adding new
fields - new fields should not retroactively appear for legacy
`enabled: true` users).
*/
const EXIF_FIELDS = [
'dateTimeOriginal', 'make', 'model', 'lensModel',
+8 -41
View File
@@ -23,6 +23,7 @@ import { renderPage } from './view/render'
import { Password } from './view/password'
import { respondToInvalidRequest } from './invalidRequestHandler'
import { encrypt } from './encrypt'
import { TtlLruCache } from './utils/ttlLruCache'
/*
In-process cache for share-link lookups. Each direct-asset request (e.g.
@@ -40,15 +41,8 @@ import { encrypt } from './encrypt'
across concurrent requests. Current callers (notably the in-place
`share.assets.sort(...)` in render.ts) happen to be idempotent so this is
safe today, but new callers should clone before mutating.
Eviction is LRU: each cache hit moves the entry to the end of the Map's
insertion order, and overflow drops the oldest (least-recently-used)
entry. TTL handles freshness; size cap handles memory.
*/
type ShareCacheEntry = { promise: Promise<SharedLinkResult>; expiresAt: number }
const shareCache = new Map<string, ShareCacheEntry>()
const shareCacheTtlMs = 120_000
const shareCacheMax = 100
const shareCache = new TtlLruCache<Promise<SharedLinkResult>>({ ttlMs: 120_000, max: 100 })
/*
Immich replaced the deprecated `?password=...` query-param auth for shared
@@ -60,10 +54,7 @@ const shareCacheMax = 100
cache key (often empty) and falls through to a fresh login that Immich will
reject - IPP never serves cached tokens to unauthenticated visitors.
*/
type TokenCacheEntry = { promise: Promise<string | null>; expiresAt: number }
const tokenCache = new Map<string, TokenCacheEntry>()
const tokenCacheTtlMs = 120_000
const tokenCacheMax = 100
const tokenCache = new TtlLruCache<Promise<string | null>>({ ttlMs: 120_000, max: 100 })
/**
* Make a request to Immich API. We're not using the SDK to limit
@@ -197,24 +188,11 @@ export async function handleShareRequest (req: IncomingShareRequest, res: Respon
*/
export async function getShareByKey (key: string, password?: string, keyType: KeyType = KeyType.key): Promise<SharedLinkResult> {
const cacheKey = `${keyType}:${key}:${password ?? ''}`
const now = Date.now()
const cached = shareCache.get(cacheKey)
if (cached && cached.expiresAt > now) {
// Move-to-end to mark this entry as most-recently-used for LRU eviction
shareCache.delete(cacheKey)
shareCache.set(cacheKey, cached)
return cached.promise
}
if (cached) return cached
const promise = fetchShareByKey(key, password, keyType)
shareCache.set(cacheKey, {
promise,
expiresAt: now + shareCacheTtlMs
})
if (shareCache.size > shareCacheMax) {
const oldest = shareCache.keys().next().value
if (oldest !== undefined && oldest !== cacheKey) shareCache.delete(oldest)
}
shareCache.set(cacheKey, promise)
promise.then(
(result) => { if (!result?.valid) shareCache.delete(cacheKey) },
() => { shareCache.delete(cacheKey) }
@@ -352,22 +330,11 @@ export async function authHeaders (keyType: KeyType, key: string, password?: str
*/
async function getSharedLinkToken (key: string, password: string, keyType: KeyType): Promise<string | null> {
const cacheKey = `${keyType}:${key}:${password}`
const now = Date.now()
const cached = tokenCache.get(cacheKey)
if (cached && cached.expiresAt > now) {
tokenCache.delete(cacheKey)
tokenCache.set(cacheKey, cached)
return cached.promise
}
if (cached) return cached
const promise = sharedLinkLogin(key, password, keyType)
tokenCache.set(cacheKey, {
promise,
expiresAt: now + tokenCacheTtlMs
})
if (tokenCache.size > tokenCacheMax) {
const oldest = tokenCache.keys().next().value
if (oldest !== undefined && oldest !== cacheKey) tokenCache.delete(oldest)
}
tokenCache.set(cacheKey, promise)
promise.then(
(token) => { if (!token) tokenCache.delete(cacheKey) },
() => { tokenCache.delete(cacheKey) }
+68
View File
@@ -0,0 +1,68 @@
/*
Time-to-live + size-bounded LRU cache. Used by `immich.ts` to memoise
share-link lookups and `POST /shared-links/login` tokens, where:
- TTL gives us freshness without rebuilding share state on every asset
request.
- LRU + size cap keeps memory bounded under a wide key space (one entry
per `(keyType, key, password)` combination).
- Move-to-end on `get` makes "recently accessed" stay alive across
bursts and lets long-tail keys age out.
The cache is intentionally storage-only. Callers handle the "should this
value stay cached?" decision after the underlying fetch resolves (e.g.
delete on null result, delete on rejection). Keeping that policy at the
call site means we don't bake validation rules into a generic cache.
*/
interface Entry<V> {
value: V
expiresAt: number
}
export class TtlLruCache<V> {
private readonly entries = new Map<string, Entry<V>>()
private readonly ttlMs: number
private readonly max: number
constructor (opts: { ttlMs: number, max: number }) {
this.ttlMs = opts.ttlMs
this.max = opts.max
}
/**
* Get the value for `key`, refreshing its LRU position. Returns
* `undefined` if the entry is missing or expired (expired entries are
* dropped on access).
*/
get (key: string): V | undefined {
const entry = this.entries.get(key)
if (!entry) return undefined
if (entry.expiresAt <= Date.now()) {
this.entries.delete(key)
return undefined
}
// Move-to-end so LRU eviction drops the least recently accessed.
this.entries.delete(key)
this.entries.set(key, entry)
return entry.value
}
/**
* Insert or replace `key` with `value` and a fresh TTL. Evicts the
* oldest entry when the cache exceeds its size cap (unless the oldest
* is the entry we just wrote, which shouldn't happen but is guarded
* just in case).
*/
set (key: string, value: V): void {
this.entries.set(key, { value, expiresAt: Date.now() + this.ttlMs })
if (this.entries.size > this.max) {
const oldest = this.entries.keys().next().value
if (oldest !== undefined && oldest !== key) this.entries.delete(oldest)
}
}
delete (key: string): void {
this.entries.delete(key)
}
}