@remix-run/assets 0.0.0 → 0.1.0

package/src/lib/asset-server.ts

@@ -0,0 +1,415 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import { isAssetServerCompilationError } from './compilation-error.ts'
+import { createAccessPolicy } from './access.ts'
+import { createModuleCompiler, createResponseForModule } from './scripts/compiler.ts'
+import { normalizeFilePath } from './paths.ts'
+import { compileRoutes } from './routes.ts'
+import type { CompiledRoutes } from './routes.ts'
+import { createAssetServerWatcher } from './watch.ts'
+import type { ChokidarWatcher } from './watch.ts'
+import type { AssetServerWatcher } from './watch.ts'
+
+interface AssetServerWatchOptions {
+  /**
+   * Ignore matching glob patterns or file paths. Relative values are resolved
+   * from `rootDir`.
+   */
+  ignore?: readonly string[]
+  /**
+   * Use polling instead of native filesystem events. Defaults to `false`.
+   */
+  poll?: boolean
+  /**
+   * Polling interval in milliseconds when `poll` is enabled. Defaults to `100`.
+   */
+  pollInterval?: number
+}
+
+interface FingerprintOptions {
+  /**
+   * Per-build invalidation token that must change whenever fingerprinted module URLs
+   * should be invalidated together.
+   */
+  buildId: string
+}
+
+const scriptTargets = [
+  'es2015',
+  'es2016',
+  'es2017',
+  'es2018',
+  'es2019',
+  'es2020',
+  'es2021',
+  'es2022',
+  'es2023',
+  'es2024',
+  'es2025',
+  'es2026',
+  'esnext',
+] as const
+const scriptTargetSet = new Set<string>(scriptTargets)
+
+export type ScriptsTarget = (typeof scriptTargets)[number]
+
+export interface AssetServerOptions {
+  /** File patterns keyed by public URL patterns. */
+  fileMap: Readonly<Record<string, string>>
+  /**
+   * Root directory used to resolve relative file paths. Defaults to `process.cwd()`.
+   */
+  rootDir?: string
+  /**
+   * Glob patterns or file paths that are allowed to be served. Relative values are resolved from `rootDir`.
+   */
+  allow: readonly string[]
+  /**
+   * Glob patterns or file paths that are denied from being served. Relative values are resolved from `rootDir`.
+   */
+  deny?: readonly string[]
+  /**
+   * Controls optional source-based URL fingerprinting for rewritten import URLs.
+   *
+   * When omitted, all served modules use stable non-fingerprinted URLs with `Cache-Control: no-cache`.
+   * Cannot be used together with active watch mode. Set `watch: false` when fingerprinting.
+   */
+  fingerprint?: FingerprintOptions
+  /**
+   * Script pipeline configuration. Omit to use defaults.
+   */
+  scripts?: {
+    /**
+     * Source map mode (disabled when omitted).
+     * - `'external'`: serve source maps as separate `.map` files; adds `//# sourceMappingURL=` comment
+     * - `'inline'`: embed source maps as a base64 data URL directly in the JS; no separate `.map` file
+     */
+    sourceMaps?: 'inline' | 'external'
+    /**
+     * Controls the source paths written into source map `sources`.
+     * - `'url'` (default): use the stable server path (e.g. `'/assets/app/entry.ts'`)
+     * - `'absolute'`: use the original filesystem path on disk
+     */
+    sourceMapSourcePaths?: 'url' | 'absolute'
+    /**
+     * Minify emitted modules.
+     */
+    minify?: boolean
+    /**
+     * Replace global expressions with constant values during transform, e.g.
+     * `{ 'process.env.NODE_ENV': '"production"' }`
+     */
+    define?: Record<string, string>
+    /**
+     * Lower emitted syntax to a specific ECMAScript target. Omit this option to preserve
+     * modern syntax unless project configuration already requests a lower target.
+     */
+    target?: ScriptsTarget
+    /** Import specifiers to leave unrewritten (CDN URLs, import map entries, etc.) */
+    external?: string[]
+  }
+  /**
+   * Enable filesystem-backed cache invalidation for long-lived server instances.
+   * Enabled by default. Pass `true` to use the default watcher options, an options
+   * object to customize watcher behavior, or `false` to disable watching.
+   */
+  watch?: boolean | AssetServerWatchOptions
+  /**
+   * Handles unexpected request-time compilation errors. Return a `Response` to override the
+   * default `500 Internal Server Error` response, or return nothing to use the default.
+   */
+  onError?: (error: unknown) => void | Response | Promise<void | Response>
+}
+
+export interface AssetServer {
+  /**
+   * Serves a script request. Returns `Response | null` — null means the request was not
+   * handled by this server, letting the router fall through to a 404.
+   */
+  fetch(request: Request): Promise<Response | null>
+  /**
+   * Returns the request href for a served module file.
+   */
+  getHref(filePath: string): Promise<string>
+  /**
+   * Returns preload URLs for one or more served module files, ordered shallowest-first.
+   */
+  getPreloads(filePath: string | readonly string[]): Promise<string[]>
+  /**
+   * Closes any watcher resources owned by this server instance.
+   */
+  close(): Promise<void>
+}
+
+type ResolvedAssetServerOptions = {
+  allow: readonly string[]
+  buildId?: string
+  define?: Record<string, string>
+  deny?: readonly string[]
+  external: string[]
+  fingerprintModules: boolean
+  minify: boolean
+  onError: NonNullable<AssetServerOptions['onError']>
+  rootDir: string
+  routes: CompiledRoutes
+  sourceMapSourcePaths: 'url' | 'absolute'
+  sourceMaps?: 'inline' | 'external'
+  scriptsTarget?: ScriptsTarget
+  watchOptions: AssetServerWatchOptions | null
+}
+
+const chokidarWatcherByAssetServer = new WeakMap<AssetServer, ChokidarWatcher>()
+const watcherByAssetServer = new WeakMap<AssetServer, AssetServerWatcher>()
+
+export function getInternalChokidarWatcher(assetServer: AssetServer): ChokidarWatcher | undefined {
+  return chokidarWatcherByAssetServer.get(assetServer)
+}
+
+export function getInternalWatchTargets(assetServer: AssetServer): readonly string[] {
+  return watcherByAssetServer.get(assetServer)?.getWatchedTargets() ?? []
+}
+
+/**
+ * Create an asset server instance
+ *
+ * Compiles TypeScript/JavaScript modules on demand with optional source-based URL
+ * fingerprinting, caching, and configurable file mapping.
+ *
+ * @param options Server configuration
+ * @returns A {@link AssetServer} with `fetch()`, `getHref()`, and `getPreloads()` methods
+ *
+ * @example
+ * ```ts
+ * let assetServer = createAssetServer({
+ *   fileMap: {
+ *     '/assets/app/*path': 'app/*path',
+ *   },
+ *   allow: ['app/**'],
+ * })
+ *
+ * route('/assets/*path', ({ request }) => assetServer.fetch(request))
+ * ```
+ */
+export function createAssetServer(options: AssetServerOptions): AssetServer {
+  let resolvedOptions = resolveAssetServerOptions(options)
+  let accessPolicy = createAccessPolicy({
+    allow: resolvedOptions.allow,
+    deny: resolvedOptions.deny,
+    rootDir: resolvedOptions.rootDir,
+  })
+  let watcher: AssetServerWatcher | null = null
+  let chokidarWatcher: ChokidarWatcher | null = null
+  let moduleCompiler = createModuleCompiler({
+    buildId: resolvedOptions.buildId,
+    define: resolvedOptions.define,
+    external: resolvedOptions.external,
+    fingerprintModules: resolvedOptions.fingerprintModules,
+    isAllowed: accessPolicy.isAllowed,
+    minify: resolvedOptions.minify,
+    onWatchDirectoriesChange: (delta) => {
+      if (!watcher) return
+      watcher.updateWatchedDirectories(delta)
+    },
+    rootDir: resolvedOptions.rootDir,
+    routes: resolvedOptions.routes,
+    sourceMapSourcePaths: resolvedOptions.sourceMapSourcePaths,
+    sourceMaps: resolvedOptions.sourceMaps,
+    target: resolvedOptions.scriptsTarget,
+    watchIgnore: resolvedOptions.watchOptions?.ignore,
+    watchMode: resolvedOptions.watchOptions !== null,
+  })
+  if (resolvedOptions.watchOptions) {
+    watcher = createAssetServerWatcher({
+      ...resolvedOptions.watchOptions,
+      onChokidarWatcherCreated(createdWatcher) {
+        chokidarWatcher = createdWatcher
+      },
+      onFileEvent: handleWatchEvent,
+      rootDir: resolvedOptions.rootDir,
+    })
+  }
+
+  async function responseForError(error: unknown): Promise<Response> {
+    try {
+      return (await resolvedOptions.onError(error)) ?? internalServerError()
+    } catch (error) {
+      console.error(`There was an error in the asset server error handler: ${error}`)
+      return internalServerError()
+    }
+  }
+
+  async function handleWatchEvent(filePath: string, event: 'add' | 'change' | 'unlink') {
+    try {
+      let normalizedFilePath = normalizeFilePath(filePath)
+      await moduleCompiler.handleFileEvent(normalizedFilePath, event)
+    } catch (error) {
+      console.error(`There was an error invalidating the asset server cache: ${error}`)
+    }
+  }
+
+  let assetServer: AssetServer = {
+    async fetch(request) {
+      if (request.method !== 'GET' && request.method !== 'HEAD') return null
+
+      let parsedRequestPathname = moduleCompiler.parseRequestPathname(new URL(request.url).pathname)
+      if (!parsedRequestPathname) return null
+
+      try {
+        let ifNoneMatch = request.headers.get('If-None-Match')
+        let moduleResult = await moduleCompiler.getModule(parsedRequestPathname.filePath, {
+          ifNoneMatch,
+          isSourceMapRequest: parsedRequestPathname.isSourceMapRequest,
+          requestedFingerprint: parsedRequestPathname.requestedFingerprint,
+        })
+        if (moduleResult.type === 'not-modified') {
+          return new Response(null, {
+            status: 304,
+            headers: { ETag: moduleResult.etag },
+          })
+        }
+
+        let compiledModule = moduleResult.module
+
+        if (parsedRequestPathname.requestedFingerprint !== null) {
+          if (compiledModule.fingerprint !== parsedRequestPathname.requestedFingerprint) return null
+        }
+
+        return createResponseForModule(compiledModule, {
+          cacheControl: parsedRequestPathname.cacheControl,
+          ifNoneMatch,
+          isSourceMapRequest: parsedRequestPathname.isSourceMapRequest,
+          method: request.method,
+        })
+      } catch (error) {
+        // A direct request can race with the filesystem or fail a deeper allow check while
+        // compiling imports. In this fetch context, both cases should fall through as "not
+        // handled here" so the outer router can continue to its own 404 behavior.
+        if (
+          isAssetServerCompilationError(error) &&
+          (error.code === 'MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_ALLOWED')
+        ) {
+          return null
+        }
+
+        return responseForError(error)
+      }
+    },
+
+    async getHref(filePath) {
+      return moduleCompiler.getHref(filePath)
+    },
+    async getPreloads(filePath) {
+      return moduleCompiler.getPreloadUrls(filePath)
+    },
+    async close() {
+      await watcher?.close()
+    },
+  }
+
+  if (chokidarWatcher) {
+    chokidarWatcherByAssetServer.set(assetServer, chokidarWatcher)
+  }
+  if (watcher) {
+    watcherByAssetServer.set(assetServer, watcher)
+  }
+
+  return assetServer
+}
+
+function internalServerError(): Response {
+  return new Response('Internal Server Error', {
+    status: 500,
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  })
+}
+
+function defaultErrorHandler(error: unknown): void {
+  console.error(error)
+}
+
+function resolveAssetServerOptions(options: AssetServerOptions): ResolvedAssetServerOptions {
+  let rootDir = normalizeFilePath(fs.realpathSync(path.resolve(options.rootDir ?? process.cwd())))
+  let scriptOptions = options.scripts ?? {}
+  let fingerprintOptions = normalizeFingerprintOptions({
+    fingerprint: options.fingerprint,
+    watch: options.watch,
+  })
+
+  return {
+    allow: options.allow,
+    buildId: fingerprintOptions.buildId,
+    define: scriptOptions.define,
+    deny: options.deny,
+    external: scriptOptions.external ?? [],
+    fingerprintModules: fingerprintOptions.enabled,
+    minify: scriptOptions.minify ?? false,
+    onError: options.onError ?? defaultErrorHandler,
+    rootDir,
+    routes: compileRoutes({
+      fileMap: options.fileMap,
+      rootDir,
+    }),
+    sourceMapSourcePaths: scriptOptions.sourceMapSourcePaths ?? 'url',
+    sourceMaps: scriptOptions.sourceMaps,
+    scriptsTarget: normalizeTarget(scriptOptions.target),
+    watchOptions: normalizeWatchOptions(options.watch),
+  }
+}
+
+function normalizeTarget(
+  target: NonNullable<AssetServerOptions['scripts']>['target'],
+): ScriptsTarget | undefined {
+  if (target == null) return undefined
+
+  if (typeof target !== 'string' || !scriptTargetSet.has(target)) {
+    throw new TypeError(
+      `Expected target to be one of ${scriptTargets.map((value) => `"${value}"`).join(', ')}. Received "${target}".`,
+    )
+  }
+
+  return target as ScriptsTarget
+}
+
+function normalizeFingerprintOptions(options: {
+  fingerprint: AssetServerOptions['fingerprint']
+  watch: AssetServerOptions['watch']
+}):
+  | {
+      enabled: false
+      buildId?: string
+    }
+  | {
+      enabled: true
+      buildId: string
+    } {
+  if (!options.fingerprint) {
+    return {
+      enabled: false,
+    }
+  }
+
+  if (typeof options.fingerprint.buildId !== 'string') {
+    throw new TypeError('fingerprint.buildId must be a string')
+  }
+
+  if (options.fingerprint.buildId.length === 0) {
+    throw new TypeError('fingerprint.buildId must be a non-empty string')
+  }
+
+  if (options.watch !== false) {
+    throw new TypeError('fingerprint cannot be used with watch mode')
+  }
+
+  return {
+    enabled: true,
+    buildId: options.fingerprint.buildId,
+  }
+}
+
+function normalizeWatchOptions(
+  options: AssetServerOptions['watch'],
+): AssetServerWatchOptions | null {
+  if (options === false) return null
+  if (options == null || options === true) return {}
+  return options
+}

package/src/lib/compilation-error.ts

@@ -0,0 +1,61 @@
+type AssetServerCompilationErrorCode =
+  | 'MODULE_NOT_FOUND'
+  | 'MODULE_NOT_ALLOWED'
+  | 'MODULE_OUTSIDE_FILE_MAP'
+  | 'MODULE_COMMONJS_NOT_SUPPORTED'
+  | 'MODULE_TRANSFORM_FAILED'
+  | 'MODULE_EMIT_FAILED'
+  | 'IMPORT_RESOLUTION_FAILED'
+  | 'IMPORT_NOT_SUPPORTED'
+  | 'IMPORT_NOT_ALLOWED'
+  | 'IMPORT_OUTSIDE_FILE_MAP'
+
+/**
+ * Internal error used by the request-time module compilation pipeline.
+ */
+export class AssetServerCompilationError extends Error {
+  code: AssetServerCompilationErrorCode
+
+  constructor(
+    message: string,
+    options: {
+      cause?: unknown
+      code: AssetServerCompilationErrorCode
+    },
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'AssetServerCompilationError'
+    this.code = options.code
+  }
+}
+
+/**
+ * Returns true when a value is an `AssetServerCompilationError`.
+ *
+ * @param error Value thrown by the compilation pipeline.
+ * @returns Whether the value is an `AssetServerCompilationError`.
+ */
+export function isAssetServerCompilationError(
+  error: unknown,
+): error is AssetServerCompilationError {
+  return error instanceof AssetServerCompilationError
+}
+
+/**
+ * Creates an `AssetServerCompilationError` with a stable internal code.
+ *
+ * @param message Human-readable error message.
+ * @param options Structured internal error details.
+ * @param options.cause Original error cause, when available.
+ * @param options.code Stable internal compilation error code.
+ * @returns A `AssetServerCompilationError`.
+ */
+export function createAssetServerCompilationError(
+  message: string,
+  options: {
+    cause?: unknown
+    code: AssetServerCompilationErrorCode
+  },
+): AssetServerCompilationError {
+  return new AssetServerCompilationError(message, options)
+}

package/src/lib/file-matcher.ts

@@ -0,0 +1,62 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+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
+  }
+
+  return (filePath) => path.posix.matchesGlob(filePath, resolvedPatternPath)
+}
+
+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/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
+}