@remix-run/assets 0.0.0 → 0.2.0

package/src/lib/file-matcher.ts

@@ -0,0 +1,63 @@
+import * as fs from 'node:fs'
+import picomatch from 'picomatch'
+
+import { normalizeFilePath, resolveFilePath } from './paths.ts'
+
+export type FileMatcher = (filePath: string) => boolean
+
+export function createFileMatcher(
+  pattern: string,
+  rootDir: string,
+  options: {
+    allowDirectories?: boolean
+    allowMissing?: boolean
+  } = {},
+): FileMatcher {
+  let resolvedPatternPath = resolveFilePath(rootDir, pattern)
+  let allowDirectories = options.allowDirectories ?? true
+  let allowMissing = options.allowMissing ?? true
+
+  if (!containsGlobSyntax(pattern)) {
+    try {
+      resolvedPatternPath = normalizeFilePath(fs.realpathSync(resolvedPatternPath))
+    } catch (error) {
+      if (!allowMissing || !isPathNotFoundError(error)) throw error
+    }
+
+    if (allowDirectories) {
+      try {
+        if (fs.statSync(resolveFilePath(rootDir, pattern)).isDirectory()) {
+          return (filePath) => isSameOrDescendantPath(filePath, resolvedPatternPath)
+        }
+      } catch (error) {
+        if (!isPathNotFoundError(error)) throw error
+      }
+    }
+
+    return (filePath) => filePath === resolvedPatternPath
+  }
+
+  let globMatcher = picomatch(resolvedPatternPath, { dot: true })
+  return (filePath) => globMatcher(filePath)
+}
+
+function isSameOrDescendantPath(filePath: string, directoryPath: string): boolean {
+  let normalizedDirectoryPath = directoryPath.replace(/\/+$/, '')
+
+  return filePath === normalizedDirectoryPath || filePath.startsWith(`${normalizedDirectoryPath}/`)
+}
+
+function containsGlobSyntax(pattern: string): boolean {
+  return /[*?[\]{}()!+@]/.test(pattern)
+}
+
+function isPathNotFoundError(
+  error: unknown,
+): error is NodeJS.ErrnoException & { code: 'ENOENT' | 'ENOTDIR' } {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    ((error as NodeJS.ErrnoException).code === 'ENOENT' ||
+      (error as NodeJS.ErrnoException).code === 'ENOTDIR')
+  )
+}

package/src/lib/fingerprint.ts

@@ -0,0 +1,65 @@
+const fingerprintedExtensionRE = /^(.+)\.@([A-Za-z0-9_-]+)(\.[^./]+)$/
+const fingerprintedBasenameRE = /^(.+)\.@([A-Za-z0-9_-]+)$/
+
+export async function hashContent(content: string): Promise<string> {
+  let encoder = new TextEncoder()
+  let data = encoder.encode(content)
+  let hashBuffer = await crypto.subtle.digest('SHA-256', data)
+  return Buffer.from(hashBuffer).toString('base64url').slice(0, 6)
+}
+
+export async function generateFingerprint(options: {
+  buildId: string
+  content: string
+}): Promise<string> {
+  return hashContent(JSON.stringify([options.content, options.buildId]))
+}
+
+export function parseFingerprintSuffix(pathname: string): {
+  pathname: string
+  requestedFingerprint: string | null
+} {
+  let lastSlashIndex = pathname.lastIndexOf('/')
+  let directory = lastSlashIndex >= 0 ? pathname.slice(0, lastSlashIndex + 1) : ''
+  let basename = lastSlashIndex >= 0 ? pathname.slice(lastSlashIndex + 1) : pathname
+  let extensionMatch = basename.match(fingerprintedExtensionRE)
+
+  if (extensionMatch) {
+    return {
+      pathname: `${directory}${extensionMatch[1]}${extensionMatch[3]}`,
+      requestedFingerprint: extensionMatch[2],
+    }
+  }
+
+  let basenameMatch = basename.match(fingerprintedBasenameRE)
+  if (basenameMatch) {
+    return {
+      pathname: `${directory}${basenameMatch[1]}`,
+      requestedFingerprint: basenameMatch[2],
+    }
+  }
+
+  return {
+    pathname,
+    requestedFingerprint: null,
+  }
+}
+
+export function formatFingerprintedPathname(pathname: string, fingerprint: string | null): string {
+  if (fingerprint === null) return pathname
+
+  let lastSlashIndex = pathname.lastIndexOf('/')
+  let directory = lastSlashIndex >= 0 ? pathname.slice(0, lastSlashIndex + 1) : ''
+  let basename = lastSlashIndex >= 0 ? pathname.slice(lastSlashIndex + 1) : pathname
+  let lastDotIndex = basename.lastIndexOf('.')
+
+  if (lastDotIndex <= 0) {
+    return `${pathname}.@${fingerprint}`
+  }
+
+  return `${directory}${basename.slice(0, lastDotIndex)}.@${fingerprint}${basename.slice(lastDotIndex)}`
+}
+
+export function getFingerprintRequestCacheControl(requestedFingerprint: string | null): string {
+  return requestedFingerprint === null ? 'no-cache' : 'public, max-age=31536000, immutable'
+}

package/src/lib/module-store.ts

@@ -0,0 +1,340 @@
+import { getFilePathDirectory } from './paths.ts'
+
+export type ModuleTracking = {
+  trackedFiles: readonly string[]
+  trackedDirectories?: readonly string[]
+}
+
+export type ModuleWatchEvent = 'change' | 'add' | 'unlink'
+
+export type FileSnapshot = {
+  mtimeNs: bigint
+  size: bigint
+}
+
+export type ModuleSnapshot = ReadonlyMap<string, FileSnapshot>
+
+type ModuleRecordState<transformed, resolved, emitted> = {
+  identityPath: string
+  invalidationVersion: number
+  transformed?: transformed
+  resolved?: resolved
+  emitted?: emitted
+  emittedSnapshot?: ModuleSnapshot
+  staleEmitted?: emitted
+  staleEmittedSnapshot?: ModuleSnapshot
+  trackedFiles: ReadonlySet<string>
+  trackedDirectories: ReadonlySet<string>
+}
+
+export type ModuleRecord<transformed, resolved, emitted> = Readonly<
+  ModuleRecordState<transformed, resolved, emitted>
+>
+
+type MutableModuleRecord<transformed, resolved, emitted> = {
+  identityPath: string
+  invalidationVersion: number
+  transformed?: transformed
+  resolved?: resolved
+  emitted?: emitted
+  emittedSnapshot?: ModuleSnapshot
+  staleEmitted?: emitted
+  staleEmittedSnapshot?: ModuleSnapshot
+  trackedFiles: Set<string>
+  trackedDirectories: Set<string>
+}
+
+export type ModuleStore<transformed, resolved, emitted> = {
+  get(identityPath: string): ModuleRecord<transformed, resolved, emitted>
+  clearTransformed(identityPath: string, tracking: readonly ModuleTracking[]): void
+  setTransformed(
+    identityPath: string,
+    transformed: transformed,
+    tracking: readonly ModuleTracking[],
+  ): void
+  setResolved(identityPath: string, resolved: resolved, tracking: readonly ModuleTracking[]): void
+  clearResolved(identityPath: string, tracking: readonly ModuleTracking[]): void
+  setEmitted(identityPath: string, emitted: emitted, snapshot: ModuleSnapshot | null): void
+  invalidateForFileEvent(filePath: string, event: ModuleWatchEvent): void
+  invalidateAll(): void
+}
+
+export function createModuleStore<transformed, resolved, emitted>(
+  options: {
+    onWatchDirectoriesChange?: (delta: { add: string[]; remove: string[] }) => void
+  } = {},
+): ModuleStore<transformed, resolved, emitted> {
+  let recordsByIdentityPath = new Map<string, MutableModuleRecord<transformed, resolved, emitted>>()
+  let recordsByTrackedFile = new Map<string, Set<string>>()
+  let watchDirectoryRefCountByPath = new Map<string, number>()
+
+  return {
+    get(identityPath) {
+      let existing = recordsByIdentityPath.get(identityPath)
+      if (existing) return existing
+
+      let record: MutableModuleRecord<transformed, resolved, emitted> = {
+        identityPath,
+        invalidationVersion: 0,
+        trackedFiles: new Set(),
+        trackedDirectories: new Set(),
+      }
+      recordsByIdentityPath.set(identityPath, record)
+      return record
+    },
+    clearTransformed(identityPath, tracking) {
+      let record = getOrCreateMutableRecord(identityPath)
+      record.transformed = undefined
+      record.resolved = undefined
+      record.emitted = undefined
+      record.emittedSnapshot = undefined
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+      setTracking(record, tracking)
+    },
+
+    setTransformed(identityPath, transformed, tracking) {
+      let record = getOrCreateMutableRecord(identityPath)
+      record.transformed = transformed
+      record.resolved = undefined
+      record.emitted = undefined
+      record.emittedSnapshot = undefined
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+      setTracking(record, tracking)
+    },
+
+    setResolved(identityPath, resolved, tracking) {
+      let record = getOrCreateMutableRecord(identityPath)
+      record.resolved = resolved
+      record.emitted = undefined
+      record.emittedSnapshot = undefined
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+      setTracking(record, tracking)
+    },
+
+    clearResolved(identityPath, tracking) {
+      let record = getOrCreateMutableRecord(identityPath)
+      record.resolved = undefined
+      record.emitted = undefined
+      record.emittedSnapshot = undefined
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+      setTracking(record, tracking)
+    },
+
+    setEmitted(identityPath, emitted, snapshot) {
+      let record = getOrCreateMutableRecord(identityPath)
+      record.emitted = emitted
+      record.emittedSnapshot = snapshot ?? undefined
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+    },
+
+    invalidateForFileEvent(filePath, event) {
+      let affected = new Set<string>(recordsByTrackedFile.get(filePath) ?? [])
+
+      if (event !== 'change') {
+        for (let record of recordsByIdentityPath.values()) {
+          if (matchesTrackedDirectory(record.trackedDirectories, filePath)) {
+            affected.add(record.identityPath)
+          }
+        }
+      }
+
+      for (let identityPath of affected) {
+        let record = recordsByIdentityPath.get(identityPath)
+        if (record) invalidateRecord(record, { retainStale: event === 'change' })
+      }
+
+      if (event === 'unlink') {
+        let deletedRecord = recordsByIdentityPath.get(filePath)
+        if (deletedRecord) {
+          clearTracking(deletedRecord)
+        }
+      }
+    },
+
+    invalidateAll() {
+      for (let record of recordsByIdentityPath.values()) {
+        invalidateRecord(record, { retainStale: false })
+      }
+    },
+  }
+
+  function getOrCreateMutableRecord(
+    identityPath: string,
+  ): MutableModuleRecord<transformed, resolved, emitted> {
+    let existing = recordsByIdentityPath.get(identityPath)
+    if (existing) return existing
+
+    let record: MutableModuleRecord<transformed, resolved, emitted> = {
+      identityPath,
+      invalidationVersion: 0,
+      trackedFiles: new Set(),
+      trackedDirectories: new Set(),
+    }
+    recordsByIdentityPath.set(identityPath, record)
+    return record
+  }
+
+  function invalidateRecord(
+    record: MutableModuleRecord<transformed, resolved, emitted>,
+    options: { retainStale: boolean },
+  ) {
+    if (!options.retainStale) {
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+    } else if (record.emitted && record.emittedSnapshot) {
+      record.staleEmitted = record.emitted
+      record.staleEmittedSnapshot = record.emittedSnapshot
+    } else if (!record.staleEmitted || !record.staleEmittedSnapshot) {
+      record.staleEmitted = undefined
+      record.staleEmittedSnapshot = undefined
+    }
+
+    record.emitted = undefined
+    record.emittedSnapshot = undefined
+    record.resolved = undefined
+    record.transformed = undefined
+    record.invalidationVersion += 1
+  }
+
+  function setTracking(
+    record: MutableModuleRecord<transformed, resolved, emitted>,
+    tracking: readonly ModuleTracking[],
+  ) {
+    let previousWatchedDirectories = getWatchedDirectories(record)
+    removeIndexes(record)
+
+    let normalizedTracking = mergeTracking(tracking)
+    record.trackedFiles = normalizedTracking.trackedFiles
+    record.trackedDirectories = normalizedTracking.trackedDirectories
+
+    for (let trackedFile of record.trackedFiles) {
+      addToIndexedSet(recordsByTrackedFile, trackedFile, record.identityPath)
+    }
+
+    let nextWatchedDirectories = getWatchedDirectories(record)
+    let delta = updateWatchDirectoryRefCounts(previousWatchedDirectories, nextWatchedDirectories)
+    emitWatchDirectoryDelta(delta)
+  }
+
+  function clearTracking(record: MutableModuleRecord<transformed, resolved, emitted>) {
+    setTracking(record, [])
+  }
+
+  function removeIndexes(record: MutableModuleRecord<transformed, resolved, emitted>) {
+    for (let trackedFile of record.trackedFiles) {
+      removeFromIndexedSet(recordsByTrackedFile, trackedFile, record.identityPath)
+    }
+  }
+
+  function updateWatchDirectoryRefCounts(
+    previousWatchedDirectories: ReadonlySet<string>,
+    nextWatchedDirectories: ReadonlySet<string>,
+  ): { add: string[]; remove: string[] } {
+    let add: string[] = []
+    let remove: string[] = []
+
+    for (let directory of previousWatchedDirectories) {
+      if (nextWatchedDirectories.has(directory)) continue
+      let previousCount = watchDirectoryRefCountByPath.get(directory)
+      if (!previousCount) continue
+      if (previousCount === 1) {
+        watchDirectoryRefCountByPath.delete(directory)
+        remove.push(directory)
+      } else {
+        watchDirectoryRefCountByPath.set(directory, previousCount - 1)
+      }
+    }
+
+    for (let directory of nextWatchedDirectories) {
+      if (previousWatchedDirectories.has(directory)) continue
+      let previousCount = watchDirectoryRefCountByPath.get(directory) ?? 0
+      watchDirectoryRefCountByPath.set(directory, previousCount + 1)
+      if (previousCount === 0) {
+        add.push(directory)
+      }
+    }
+
+    return { add, remove }
+  }
+
+  function emitWatchDirectoryDelta(delta: { add: string[]; remove: string[] }): void {
+    if (!options.onWatchDirectoriesChange) return
+    if (delta.add.length === 0 && delta.remove.length === 0) return
+    options.onWatchDirectoriesChange(delta)
+  }
+}
+
+function addToIndexedSet(map: Map<string, Set<string>>, key: string, value: string) {
+  let existing = map.get(key) ?? new Set<string>()
+  existing.add(value)
+  map.set(key, existing)
+}
+
+function removeFromIndexedSet(map: Map<string, Set<string>>, key: string, value: string) {
+  let existing = map.get(key)
+  if (!existing) return
+  existing.delete(value)
+  if (existing.size === 0) {
+    map.delete(key)
+  }
+}
+
+function matchesTrackedDirectory(
+  trackedDirectories: ReadonlySet<string>,
+  filePath: string,
+): boolean {
+  for (let trackedDirectory of trackedDirectories) {
+    if (filePath === trackedDirectory || filePath.startsWith(`${trackedDirectory}/`)) return true
+  }
+
+  return false
+}
+
+function normalizeTrackedDirectory(trackedDirectory: string): string {
+  return trackedDirectory.replace(/\/+$/, '') || '/'
+}
+
+function mergeTracking(tracking: readonly ModuleTracking[]): {
+  trackedFiles: Set<string>
+  trackedDirectories: Set<string>
+} {
+  let trackedFiles = new Set<string>()
+  let trackedDirectories = new Set<string>()
+
+  for (let fragment of tracking) {
+    for (let trackedFile of fragment.trackedFiles) {
+      trackedFiles.add(trackedFile)
+    }
+
+    for (let trackedDirectory of fragment.trackedDirectories ?? []) {
+      trackedDirectories.add(normalizeTrackedDirectory(trackedDirectory))
+    }
+  }
+
+  return {
+    trackedFiles,
+    trackedDirectories,
+  }
+}
+
+function getWatchedDirectories(record: {
+  trackedFiles: ReadonlySet<string>
+  trackedDirectories: ReadonlySet<string>
+}): Set<string> {
+  let watchedDirectories = new Set<string>()
+
+  for (let trackedFile of record.trackedFiles) {
+    watchedDirectories.add(getFilePathDirectory(trackedFile))
+  }
+
+  for (let trackedDirectory of record.trackedDirectories) {
+    watchedDirectories.add(trackedDirectory)
+  }
+
+  return watchedDirectories
+}

package/src/lib/paths.ts

@@ -0,0 +1,66 @@
+import * as path from 'node:path'
+
+const windowsDriveLetterRE = /^[A-Za-z]:\//
+const uncPrefixRE = /^\/\/[^/]+\/[^/]+/
+
+export function normalizeWindowsPath(filePath: string): string {
+  return filePath
+    .replace(/\\/g, '/')
+    .replace(windowsDriveLetterRE, (prefix) => `${prefix[0]!.toUpperCase()}${prefix.slice(1)}`)
+}
+
+export function normalizePathname(pathname: string): string {
+  let normalized = path.posix.normalize(normalizeWindowsPath(pathname))
+
+  if (!normalized.startsWith('/')) {
+    normalized = `/${normalized}`
+  }
+
+  return normalized
+}
+
+export function isAbsoluteFilePath(filePath: string): boolean {
+  let normalized = normalizeWindowsPath(filePath)
+  return normalized.startsWith('/') || windowsDriveLetterRE.test(normalized)
+}
+
+export function normalizeFilePath(filePath: string): string {
+  let normalized = normalizeWindowsPath(filePath)
+  let uncRoot = getUncRoot(normalized)
+
+  if (uncRoot) {
+    let remainder = normalized.slice(uncRoot.length)
+    let normalizedRemainder = path.posix.normalize(remainder || '/')
+    return `${uncRoot}${normalizedRemainder === '/' ? '' : normalizedRemainder}`
+  }
+
+  if (windowsDriveLetterRE.test(normalized)) {
+    return path.posix.normalize(normalized)
+  }
+
+  if (normalized.startsWith('/')) {
+    return path.posix.normalize(normalized)
+  }
+
+  return path.posix.normalize(normalizeWindowsPath(path.resolve(normalized)))
+}
+
+export function resolveFilePath(rootDir: string, filePath: string): string {
+  if (isAbsoluteFilePath(filePath)) {
+    return normalizeFilePath(filePath)
+  }
+
+  return normalizeFilePath(`${rootDir.replace(/\/+$/, '')}/${normalizeWindowsPath(filePath)}`)
+}
+
+export function getFilePathDirectory(filePath: string): string {
+  return path.posix.dirname(normalizeWindowsPath(filePath))
+}
+
+export function getFilePathBaseName(filePath: string): string {
+  return path.posix.basename(normalizeWindowsPath(filePath))
+}
+
+function getUncRoot(filePath: string): string | null {
+  return filePath.startsWith('//') ? (filePath.match(uncPrefixRE)?.[0] ?? null) : null
+}

package/src/lib/routes.ts

@@ -0,0 +1,164 @@
+import * as path from 'node:path'
+import { RoutePattern } from '@remix-run/route-pattern'
+
+import {
+  isAbsoluteFilePath,
+  normalizeFilePath,
+  normalizePathname,
+  resolveFilePath,
+} from './paths.ts'
+
+export interface AssetRouteDefinition {
+  urlPattern: string
+  filePattern: string
+}
+
+interface CompiledRoute {
+  rootDir: string
+  urlPattern: RoutePattern
+  filePattern: RoutePattern
+}
+
+export interface CompiledRoutes {
+  resolveUrlPathname(pathname: string): string | null
+  toUrlPathname(filePath: string): string | null
+}
+
+function normalizeFilePattern(pattern: string): string {
+  if (isAbsoluteFilePath(pattern)) {
+    throw new Error(
+      `File route patterns must be relative to the asset server root.\nPattern: ${pattern}`,
+    )
+  }
+
+  return normalizePathname(pattern)
+}
+
+export function compileRoutes(options: {
+  fileMap: Readonly<Record<string, string>>
+  rootDir: string
+}): CompiledRoutes {
+  if (Object.keys(options.fileMap).length === 0) {
+    throw new Error('createAssetServer() requires at least one configured fileMap entry.')
+  }
+
+  let compiledRoutes = Object.entries(options.fileMap).map(([urlPattern, filePattern]) =>
+    compileRoute(
+      {
+        urlPattern,
+        filePattern,
+      },
+      { rootDir: options.rootDir },
+    ),
+  )
+
+  return {
+    resolveUrlPathname(pathname) {
+      let normalizedPathname = normalizePathname(pathname)
+
+      for (let route of compiledRoutes) {
+        let match = route.urlPattern.match(`http://remix.run${normalizedPathname}`)
+        if (!match) continue
+        let relativeFilePath = route.filePattern.href(match.params).replace(/^\/+/, '')
+        return resolveFilePath(route.rootDir, relativeFilePath)
+      }
+
+      return null
+    },
+    toUrlPathname(filePath) {
+      let normalizedFilePath = normalizeFilePath(filePath)
+
+      for (let route of compiledRoutes) {
+        let relativeFilePath = getRelativeFilePath(normalizedFilePath, route.rootDir)
+        if (relativeFilePath === null) continue
+        let match = route.filePattern.ast.pathname.match(relativeFilePath)
+        if (!match) continue
+        return normalizePathname(route.urlPattern.href(getPathnameParams(route.filePattern, match)))
+      }
+
+      return null
+    },
+  }
+}
+
+function compileRoute(
+  route: AssetRouteDefinition,
+  options: {
+    rootDir: string
+  },
+): CompiledRoute {
+  let urlPatternSource = normalizePathname(route.urlPattern)
+  let filePatternSource = normalizeFilePattern(route.filePattern)
+
+  let urlPattern = new RoutePattern(urlPatternSource)
+  let filePattern = new RoutePattern(filePatternSource)
+
+  validateNoUnnamedWildcards(urlPattern, 'URL')
+  validateNoUnnamedWildcards(filePattern, 'File')
+  validateRoutePatterns(urlPattern, filePattern)
+
+  return {
+    rootDir: normalizeFilePath(options.rootDir).replace(/\/+$/, ''),
+    urlPattern,
+    filePattern,
+  }
+}
+
+function getRelativeFilePath(filePath: string, rootDir: string): string | null {
+  if (filePath[1] === ':' && rootDir[1] === ':' && filePath[0] !== rootDir[0]) return null
+  return path.posix.relative(rootDir, filePath)
+}
+
+function getPathnameParams(
+  pattern: RoutePattern,
+  match: Array<{ name: string; type: ':' | '*'; value: string }>,
+): Record<string, string | undefined> {
+  let params: Record<string, string | undefined> = {}
+
+  for (let param of pattern.ast.pathname.params) {
+    if (param.name === '*') continue
+    params[param.name] = undefined
+  }
+
+  for (let param of match) {
+    if (param.name === '*') continue
+    params[param.name] = param.value
+  }
+
+  return params
+}
+
+function validateRoutePatterns(urlPattern: RoutePattern, filePattern: RoutePattern): void {
+  let urlParams = urlPattern.ast.pathname.params.map(
+    (param: { name: string; type: ':' | '*' }) => `${param.type}:${param.name}`,
+  )
+  let fileParams = filePattern.ast.pathname.params.map(
+    (param: { name: string; type: ':' | '*' }) => `${param.type}:${param.name}`,
+  )
+
+  if (urlParams.length !== fileParams.length) {
+    throw new Error(
+      `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
+    )
+  }
+
+  for (let i = 0; i < urlParams.length; i++) {
+    if (urlParams[i] !== fileParams[i]) {
+      throw new Error(
+        `Route patterns must have matching capture structure.\nURL: ${urlPattern}\nFile: ${filePattern}`,
+      )
+    }
+  }
+}
+
+function validateNoUnnamedWildcards(pattern: RoutePattern, label: string): void {
+  if (
+    pattern.ast.pathname.params.some(
+      (param: { name: string; type: ':' | '*' }) => param.type === '*' && param.name === '*',
+    )
+  ) {
+    throw new Error(
+      `${label} route patterns must use named wildcards for reversible mapping.\nPattern: ${pattern}`,
+    )
+  }
+}