@jsenv/core 27.0.0-alpha.9 → 27.0.0-alpha.92

package/src/omega/kitchen.js

@@ -1,162 +1,221 @@
 import {
   urlIsInsideOf,
-  writeFileSync,
-  isFileSystemPath,
-  fileSystemPathToUrl,
   moveUrl,
-  fileSystemRootUrl,
-} from "@jsenv/filesystem"
-
-import { stringifyUrlSite } from "@jsenv/utils/urls/url_trace.js"
+  getCallerPosition,
+  stringifyUrlSite,
+  normalizeUrl,
+  setUrlFilename,
+} from "@jsenv/urls"
+import { writeFileSync, ensureWindowsDriveLetter } from "@jsenv/filesystem"
+import { createDetailedMessage } from "@jsenv/log"
+import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js"
 
+import { createPluginController } from "../plugins/plugin_controller.js"
+import { urlSpecifierEncoding } from "./url_specifier_encoding.js"
 import { createUrlInfoTransformer } from "./url_graph/url_info_transformations.js"
-import { RUNTIME_SUPPORT } from "./runtime_support/runtime_support.js"
-import { fileUrlConverter } from "./file_url_converter.js"
-import { parseUrlMentions } from "./url_mentions/parse_url_mentions.js"
+import { RUNTIME_COMPAT } from "./compat/runtime_compat.js"
 import {
-  createResolveError,
-  createLoadError,
-  createParseError,
-  createTransformError,
+  createResolveUrlError,
+  createFetchUrlContentError,
+  createTransformUrlContentError,
+  createFinalizeUrlContentError,
 } from "./errors.js"
-import { createPluginController } from "./plugin_controller.js"
+import { assertFetchedContentCompliance } from "./fetched_content_compliance.js"
+import { isWebWorkerEntryPointReference } from "./web_workers.js"
 
 export const createKitchen = ({
   signal,
   logger,
   rootDirectoryUrl,
   urlGraph,
+
   plugins,
   scenario,
-
   sourcemaps = {
     dev: "inline", // "programmatic" and "file" also allowed
     test: "inline",
     build: "none",
   }[scenario],
-  // we don't need sources in sourcemap as long as the url in the
-  // sourcemap uses file:/// (chrome will understand and read from filesystem)
-  sourcemapsSources = false,
-  loadInlineUrlInfos = (urlInfo) => {
-    return {
-      contentType: urlInfo.contentType,
-      content: urlInfo.content,
-    }
-  },
-
-  writeOnFileSystem = true,
+  sourcemapsSourcesContent = {
+    // during dev/test, chrome is able to find the sourcemap sources
+    // as long as they use file:// protocol in the sourcemap files
+    dev: false,
+    test: false,
+    build: true,
+  }[scenario],
+  sourcemapsRelativeSources,
+  runtimeCompat,
+  writeGeneratedFiles,
 }) => {
   const pluginController = createPluginController({
     plugins,
     scenario,
   })
   const jsenvDirectoryUrl = new URL(".jsenv/", rootDirectoryUrl).href
-  const baseContext = {
+  const kitchenContext = {
     signal,
     logger,
     rootDirectoryUrl,
     sourcemaps,
     urlGraph,
     scenario,
+    runtimeCompat,
+    isSupportedOnFutureClients: (feature) => {
+      return RUNTIME_COMPAT.isSupported(runtimeCompat, feature)
+    },
   }
   const createReference = ({
     data = {},
+    node,
     trace,
     parentUrl,
     type,
     subtype,
+    expectedContentType,
+    expectedType,
+    expectedSubtype,
+    filename,
+    integrity,
+    crossorigin,
     specifier,
+    specifierStart,
+    specifierEnd,
+    specifierLine,
+    specifierColumn,
+    baseUrl,
+    isOriginalPosition,
+    shouldHandle,
     isInline = false,
+    injected = false,
+    isRessourceHint = false,
     content,
     contentType,
+    assert,
+    assertNode,
+    typePropertyNode,
   }) => {
+    if (typeof specifier !== "string") {
+      throw new TypeError(`"specifier" must be a string, got ${specifier}`)
+    }
     return {
+      original: null,
+      prev: null,
+      next: null,
       data,
+      node,
       trace,
       parentUrl,
       type,
       subtype,
+      expectedContentType,
+      expectedType,
+      expectedSubtype,
+      filename,
+      integrity,
+      crossorigin,
       specifier,
+      specifierStart,
+      specifierEnd,
+      specifierLine,
+      specifierColumn,
+      baseUrl,
+      isOriginalPosition,
+      shouldHandle,
       isInline,
+      injected,
+      isRessourceHint,
       // for inline ressources the reference contains the content
       content,
       contentType,
+      timing: {},
+      assert,
+      assertNode,
+      typePropertyNode,
     }
   }
+  const mutateReference = (reference, newReference) => {
+    reference.next = newReference
+    newReference.prev = reference
+    newReference.original = reference.original || reference
+  }
   const resolveReference = (reference) => {
     try {
-      const resolvedUrl = pluginController.callHooksUntil(
-        "resolve",
+      let resolvedUrl = pluginController.callHooksUntil(
+        "resolveUrl",
         reference,
-        baseContext,
+        kitchenContext,
       )
       if (!resolvedUrl) {
         throw new Error(`NO_RESOLVE`)
       }
+      resolvedUrl = normalizeUrl(resolvedUrl)
       reference.url = resolvedUrl
       pluginController.callHooks(
-        "normalize",
+        "redirectUrl",
         reference,
-        baseContext,
+        kitchenContext,
         (returnValue) => {
-          reference.url = returnValue
+          const normalizedReturnValue = normalizeUrl(returnValue)
+          if (normalizedReturnValue === reference.url) {
+            return
+          }
+          const previousReference = { ...reference }
+          reference.url = normalizedReturnValue
+          mutateReference(previousReference, reference)
         },
       )
-      // force a last normalization regarding on url search params
-      // some plugin use URLSearchParams to alter the url search params
-      // which can result into "file:///file.css?css_module"
-      // becoming "file:///file.css?css_module="
-      // we want to get rid of the "=" and consider it's the same url
-      if (
-        // disable on data urls (would mess up base64 encoding)
-        !reference.url.startsWith("data:")
-      ) {
-        reference.url = reference.url.replace(/[=](?=&|$)/g, "")
-      }
+
       const urlInfo = urlGraph.reuseOrCreateUrlInfo(reference.url)
-      Object.assign(urlInfo.data, reference.data)
+      applyReferenceEffectsOnUrlInfo(reference, urlInfo, kitchenContext)
 
-      // create a copy because .url will be mutated
-      const referencedCopy = {
-        ...reference,
-        data: urlInfo.data,
-      }
+      const referenceUrlObject = new URL(reference.url)
+      reference.searchParams = referenceUrlObject.searchParams
+      reference.generatedUrl = reference.url
+      // This hook must touch reference.generatedUrl, NOT reference.url
+      // And this is because this hook inject query params used to:
+      // - bypass browser cache (?v)
+      // - convey information (?hmr)
+      // But do not represent an other ressource, it is considered as
+      // the same ressource under the hood
       pluginController.callHooks(
-        "transformReferencedUrl",
-        referencedCopy,
-        baseContext,
+        "transformUrlSearchParams",
+        reference,
+        kitchenContext,
         (returnValue) => {
-          referencedCopy.url = returnValue
+          Object.keys(returnValue).forEach((key) => {
+            referenceUrlObject.searchParams.set(key, returnValue[key])
+          })
+          reference.generatedUrl = normalizeUrl(referenceUrlObject.href)
         },
       )
-      reference.generatedUrl = referencedCopy.url
       const returnValue = pluginController.callHooksUntil(
-        "formatReferencedUrl",
-        referencedCopy,
-        baseContext,
+        "formatUrl",
+        reference,
+        kitchenContext,
       )
       reference.generatedSpecifier = returnValue || reference.generatedUrl
-      reference.generatedSpecifier = specifierFormat.encode(reference)
+      reference.generatedSpecifier = urlSpecifierEncoding.encode(reference)
       return urlInfo
     } catch (error) {
-      throw createResolveError({
+      throw createResolveUrlError({
         pluginController,
         reference,
         error,
       })
     }
   }
+  kitchenContext.resolveReference = resolveReference
   const urlInfoTransformer = createUrlInfoTransformer({
     logger,
     urlGraph,
     sourcemaps,
-    sourcemapsSources,
+    sourcemapsSourcesContent,
+    sourcemapsRelativeSources,
     injectSourcemapPlaceholder: ({ urlInfo, specifier }) => {
       const sourcemapReference = createReference({
         trace: `sourcemap comment placeholder for ${urlInfo.url}`,
         type: "sourcemap_comment",
-        subtype:
-          urlInfo.contentType === "application/javascript" ? "js" : "css",
+        subtype: urlInfo.contentType === "text/javascript" ? "js" : "css",
         parentUrl: urlInfo.url,
         specifier,
       })
@@ -164,19 +223,27 @@ export const createKitchen = ({
       sourcemapUrlInfo.type = "sourcemap"
       return [sourcemapReference, sourcemapUrlInfo]
     },
-    foundSourcemap: ({ urlInfo, line, column, type, specifier }) => {
+    foundSourcemap: ({
+      urlInfo,
+      type,
+      specifier,
+      specifierLine,
+      specifierColumn,
+    }) => {
       const sourcemapReference = createReference({
         trace: stringifyUrlSite(
           adjustUrlSite(urlInfo, {
             urlGraph,
             url: urlInfo.url,
-            line,
-            column,
+            line: specifierLine,
+            column: specifierColumn,
           }),
         ),
         type,
         parentUrl: urlInfo.url,
         specifier,
+        specifierLine,
+        specifierColumn,
       })
       const sourcemapUrlInfo = resolveReference(sourcemapReference)
       sourcemapUrlInfo.type = "sourcemap"
@@ -184,61 +251,82 @@ export const createKitchen = ({
     },
   })
 
-  const load = async ({ reference, urlInfo, context }) => {
+  const fetchUrlContent = async (urlInfo, { reference, context }) => {
     try {
-      const loadReturnValue = urlInfo.isInline
-        ? loadInlineUrlInfos(urlInfo)
-        : await pluginController.callAsyncHooksUntil("load", urlInfo, context)
-      if (!loadReturnValue) {
-        throw new Error("NO_LOAD")
+      const fetchUrlContentReturnValue =
+        await pluginController.callAsyncHooksUntil(
+          "fetchUrlContent",
+          urlInfo,
+          context,
+        )
+      if (!fetchUrlContentReturnValue) {
+        logger.warn(
+          createDetailedMessage(
+            `no plugin has handled url during "fetchUrlContent" hook -> url will be ignored`,
+            {
+              "url": urlInfo.url,
+              "url reference trace": reference.trace,
+            },
+          ),
+        )
+        return
       }
-
-      const {
-        contentType = "application/octet-stream",
-        content, // can be a buffer (used for binary files) or a string
-        sourcemap,
-        // during build urls info are reused and load returns originalContent
-        // that we want to keep
-        originalContent = content,
-        data,
-      } = loadReturnValue
-      Object.assign(urlInfo, {
+      let {
+        content,
         contentType,
+        data,
+        type,
+        subtype,
+        originalUrl,
         originalContent,
-        content,
         sourcemap,
-      })
+        filename,
+
+        status = 200,
+        headers = {},
+        body,
+      } = fetchUrlContentReturnValue
+      if (status !== 200) {
+        throw new Error(`unexpected status, ${status}`)
+      }
+      if (content === undefined) {
+        content = body
+      }
+      if (contentType === undefined) {
+        contentType = headers["content-type"] || "application/octet-stream"
+      }
+      urlInfo.contentType = contentType
+      urlInfo.headers = headers
+      urlInfo.type =
+        type ||
+        reference.expectedType ||
+        inferUrlInfoType({ url: urlInfo.url, contentType })
+      urlInfo.subtype =
+        subtype ||
+        reference.expectedSubtype ||
+        inferUrlInfoSubtype({
+          url: urlInfo.url,
+          type: urlInfo.type,
+          subtype: urlInfo.subtype,
+        })
+      // during build urls info are reused and load returns originalUrl/originalContent
+      urlInfo.originalUrl = originalUrl || urlInfo.originalUrl
+      urlInfo.originalContent =
+        originalContent === undefined ? content : originalContent
+      urlInfo.content = content
+      urlInfo.sourcemap = sourcemap
       if (data) {
         Object.assign(urlInfo.data, data)
       }
-      if (!urlInfo.type) {
-        const type = inferUrlInfoType(urlInfo)
-        if (type === "js") {
-          const urlObject = new URL(urlInfo.url)
-          if (urlObject.searchParams.has("worker_type_classic")) {
-            urlInfo.type = "js_classic"
-            urlInfo.subtype = "worker"
-          } else if (
-            urlObject.searchParams.has("service_worker_type_classic")
-          ) {
-            urlInfo.type = "js_classic"
-            urlInfo.subtype = "service_worker"
-          } else if (urlObject.searchParams.has("js_classic")) {
-            urlInfo.type = "js_classic"
-          } else {
-            urlInfo.type = "js_module"
-          }
-          if (urlObject.searchParams.has("worker")) {
-            urlInfo.subtype = "worker"
-          } else if (urlObject.searchParams.has("service_worker")) {
-            urlInfo.subtype = "service_worker"
-          }
-        } else {
-          urlInfo.type = type
-        }
+      if (filename) {
+        urlInfo.filename = filename
       }
+      assertFetchedContentCompliance({
+        reference,
+        urlInfo,
+      })
     } catch (error) {
-      throw createLoadError({
+      throw createFetchUrlContentError({
         pluginController,
         urlInfo,
         reference,
@@ -246,270 +334,238 @@ export const createKitchen = ({
       })
     }
     urlInfo.generatedUrl = determineFileUrlForOutDirectory({
-      rootDirectoryUrl,
-      outDirectoryUrl: context.outDirectoryUrl,
-      url: urlInfo.url,
+      urlInfo,
+      context,
     })
     await urlInfoTransformer.initTransformations(urlInfo, context)
   }
 
-  const _cook = async ({
-    reference,
-    urlInfo,
-    outDirectoryUrl,
-    runtimeSupport,
-    cookDuringCook = cook,
-  }) => {
+  const _cook = async (urlInfo, dishContext) => {
+    // during dev/test clientRuntimeCompat is a single runtime
+    // during build clientRuntimeCompat is runtimeCompat
+    const { clientRuntimeCompat = runtimeCompat } = dishContext
+    kitchenContext.isSupportedOnCurrentClients = (feature) => {
+      return RUNTIME_COMPAT.isSupported(clientRuntimeCompat, feature)
+    }
     const context = {
-      ...baseContext,
-      reference,
-      outDirectoryUrl,
-      runtimeSupport,
-      isSupportedOnRuntime: (feature) => {
-        return RUNTIME_SUPPORT.isSupported(runtimeSupport, feature)
-      },
-      cook: (params) => {
-        return cookDuringCook({
-          outDirectoryUrl,
-          runtimeSupport,
-          ...params,
-        })
-      },
-      load: (params) => {
-        return load({
-          context,
-          ...params,
-        })
-      },
+      ...kitchenContext,
+      ...dishContext,
+      clientRuntimeCompat,
     }
-
-    // "load" hook
-    await load({ reference, urlInfo, context })
-
-    // parsing
-    const references = []
-    const addReference = (props) => {
-      const reference = createReference({
-        parentUrl: urlInfo.url,
-        ...props,
+    const { cookDuringCook = cook } = dishContext
+    context.cook = (urlInfo, nestedDishContext) => {
+      return cookDuringCook(urlInfo, {
+        ...dishContext,
+        ...nestedDishContext,
       })
-      references.push(reference)
-      return [reference, resolveReference(reference)]
     }
-    const referenceUtils = {
-      inject: ({ trace, ...rest }) => {
-        if (trace === undefined) {
-          const { prepareStackTrace } = Error
-          Error.prepareStackTrace = (error, stack) => {
-            Error.prepareStackTrace = prepareStackTrace
-            return stack
+    context.fetchUrlContent = (urlInfo, { reference }) => {
+      return fetchUrlContent(urlInfo, { reference, context })
+    }
+
+    if (urlInfo.shouldHandle) {
+      // "fetchUrlContent" hook
+      await fetchUrlContent(urlInfo, { reference: context.reference, context })
+
+      // parsing
+      const references = []
+      const addReference = (props) => {
+        const reference = createReference({
+          parentUrl: urlInfo.url,
+          ...props,
+        })
+        references.push(reference)
+        const referencedUrlInfo = resolveReference(reference)
+        return [reference, referencedUrlInfo]
+      }
+      const referenceUtils = {
+        readGeneratedSpecifier: async (reference) => {
+          // "formatReferencedUrl" can be async BUT this is an exception
+          // for most cases it will be sync. We want to favor the sync signature to keep things simpler
+          // The only case where it needs to be async is when
+          // the specifier is a `data:*` url
+          // in this case we'll wait for the promise returned by
+          // "formatReferencedUrl"
+          if (reference.generatedSpecifier.then) {
+            return reference.generatedSpecifier.then((value) => {
+              reference.generatedSpecifier = value
+              return value
+            })
           }
-          const { stack } = new Error()
-          const callerCallsite = stack[1]
-          const fileName = callerCallsite.getFileName()
-          trace = stringifyUrlSite({
-            url:
-              fileName && isFileSystemPath(fileName)
-                ? fileSystemPathToUrl(fileName)
-                : fileName,
-            line: callerCallsite.getLineNumber(),
-            column: callerCallsite.getColumnNumber(),
+          return reference.generatedSpecifier
+        },
+        found: ({ trace, ...rest }) => {
+          if (trace === undefined) {
+            trace = stringifyUrlSite(
+              adjustUrlSite(urlInfo, {
+                urlGraph,
+                url: urlInfo.url,
+                line: rest.specifierLine,
+                column: rest.specifierColumn,
+              }),
+            )
+          }
+          // console.log(trace)
+          return addReference({
+            trace,
+            ...rest,
           })
-        }
-        return addReference({
-          trace,
-          ...rest,
-        })
-      },
-      foundInline: ({
-        type,
-        isOriginal,
-        line,
-        column,
-        specifier,
-        contentType,
-        content,
-      }) => {
-        const parentUrl = isOriginal ? urlInfo.url : urlInfo.generatedUrl
-        const parentContent = isOriginal
-          ? urlInfo.originalContent
-          : urlInfo.content
-        const [inlineReference, inlineUrlInfo] = addReference({
-          trace: stringifyUrlSite({
-            url: parentUrl,
-            content: parentContent,
+        },
+        foundInline: ({ isOriginalPosition, line, column, ...rest }) => {
+          const parentUrl = isOriginalPosition
+            ? urlInfo.url
+            : urlInfo.generatedUrl
+          const parentContent = isOriginalPosition
+            ? urlInfo.originalContent
+            : urlInfo.content
+          return addReference({
+            trace: stringifyUrlSite({
+              url: parentUrl,
+              content: parentContent,
+              line,
+              column,
+            }),
+            isOriginalPosition,
             line,
             column,
-          }),
-          type,
-          specifier,
-          isInline: true,
-          contentType,
-          content,
-        })
-        inlineUrlInfo.isInline = true
-        inlineUrlInfo.inlineUrlSite = {
-          url: urlInfo.url,
-          content: parentContent,
-          line,
-          column,
-        }
-        inlineUrlInfo.contentType = contentType
-        inlineUrlInfo.originalContent = inlineUrlInfo.content = content
-        return [inlineReference, inlineUrlInfo]
-      },
-      updateSpecifier: (generatedSpecifier, newSpecifier, data) => {
-        const index = references.findIndex(
-          (ref) => ref.generatedSpecifier === generatedSpecifier,
-        )
-        if (index === -1) {
-          throw new Error(
-            `Cannot find a reference for the following generatedSpecifier "${generatedSpecifier}"`,
+            isInline: true,
+            ...rest,
+          })
+        },
+        update: (currentReference, newReferenceParams) => {
+          const index = references.indexOf(currentReference)
+          if (index === -1) {
+            throw new Error(`reference do not exists`)
+          }
+          const previousReference = currentReference
+          const nextReference = createReference({
+            ...previousReference,
+            ...newReferenceParams,
+          })
+          references[index] = nextReference
+          mutateReference(previousReference, nextReference)
+          const newUrlInfo = resolveReference(nextReference)
+          const currentUrlInfo = context.urlGraph.getUrlInfo(
+            currentReference.url,
           )
-        }
-        const referenceFound = references[index]
-        const newReference = createReference({
-          ...referenceFound,
-          specifier: newSpecifier,
-          data: {
-            ...referenceFound.data,
-            ...data,
+          if (
+            currentUrlInfo &&
+            currentUrlInfo !== newUrlInfo &&
+            currentUrlInfo.dependents.size === 0
+          ) {
+            context.urlGraph.deleteUrlInfo(currentReference.url)
+          }
+          return [nextReference, newUrlInfo]
+        },
+        becomesInline: (
+          reference,
+          {
+            isOriginalPosition,
+            specifier,
+            specifierLine,
+            specifierColumn,
+            contentType,
+            content,
           },
-        })
-        references[index] = newReference
-        newReference.data.originalReference = referenceFound
-        const newUrlInfo = resolveReference(newReference)
-        return [newReference, newUrlInfo]
-      },
-      becomesInline: (
-        reference,
-        { isOriginal, line, column, specifier, contentType, content },
-      ) => {
-        const parentUrl = isOriginal ? urlInfo.url : urlInfo.generatedUrl
-        const parentContent = isOriginal
-          ? urlInfo.originalContent
-          : urlInfo.content
-        reference.trace = stringifyUrlSite({
-          url: parentUrl,
-          content: parentContent,
-          line,
-          column,
-        })
-        reference.isInline = true
-        reference.specifier = specifier
-        reference.contentType = contentType
-        reference.content = content
-        const inlineUrlInfo = resolveReference(reference)
-        inlineUrlInfo.isInline = true
-        inlineUrlInfo.inlineUrlSite = {
-          url: urlInfo.url,
-          content: parentContent,
-          line,
-          column,
-        }
-        inlineUrlInfo.contentType = contentType
-        inlineUrlInfo.content = content
-        return reference
-      },
-    }
-
-    let parseResult
-    try {
-      parseResult = await parseUrlMentions({
-        type: urlInfo.type,
-        url: urlInfo.data.sourceUrl || urlInfo.url,
-        generatedUrl: urlInfo.generatedUrl,
-        content: urlInfo.content,
-      })
-    } catch (error) {
-      throw createParseError({
-        reference,
-        urlInfo,
-        error,
-      })
-    }
-    if (parseResult) {
-      Object.assign(urlInfo.data, parseResult.data)
-      const { urlMentions, replaceUrls } = parseResult
-      for (const urlMention of urlMentions) {
-        const [reference] = addReference({
-          trace: stringifyUrlSite(
-            adjustUrlSite(urlInfo, {
-              urlGraph,
-              url: urlInfo.url,
-              line: urlMention.line,
-              column: urlMention.column,
+        ) => {
+          const parentUrl = isOriginalPosition
+            ? urlInfo.url
+            : urlInfo.generatedUrl
+          const parentContent = isOriginalPosition
+            ? urlInfo.originalContent
+            : urlInfo.content
+          return referenceUtils.update(reference, {
+            trace: stringifyUrlSite({
+              url: parentUrl,
+              content: parentContent,
+              line: specifierLine,
+              column: specifierColumn,
             }),
-          ),
-          type: urlMention.type,
-          subtype: urlMention.subtype,
-          specifier: urlMention.specifier,
-        })
-        urlMention.reference = reference
+            isOriginalPosition,
+            isInline: true,
+            specifier,
+            specifierLine,
+            specifierColumn,
+            contentType,
+            content,
+          })
+        },
+        inject: ({ trace, ...rest }) => {
+          if (trace === undefined) {
+            const { url, line, column } = getCallerPosition()
+            trace = stringifyUrlSite({
+              url,
+              line,
+              column,
+            })
+          }
+          return addReference({
+            trace,
+            injected: true,
+            ...rest,
+          })
+        },
+        findByGeneratedSpecifier: (generatedSpecifier) => {
+          const reference = references.find(
+            (ref) => ref.generatedSpecifier === generatedSpecifier,
+          )
+          if (!reference) {
+            throw new Error(
+              `No reference found using the following generatedSpecifier: "${generatedSpecifier}"`,
+            )
+          }
+          return reference
+        },
       }
-      if (references.length) {
-        // "formatReferencedUrl" can be async BUT this is an exception
-        // for most cases it will be sync. We want to favor the sync signature to keep things simpler
-        // The only case where it needs to be async is when
-        // the specifier is a `data:*` url
-        // in this case we'll wait for the promise returned by
-        // "formatReferencedUrl"
-        await Promise.all(
-          references.map(async (reference) => {
-            if (reference.generatedSpecifier.then) {
-              const value = await reference.generatedSpecifier
-              reference.generatedSpecifier = value
-            }
-          }),
+
+      // "transform" hook
+      urlInfo.references = references
+      context.referenceUtils = referenceUtils
+      try {
+        await pluginController.callAsyncHooks(
+          "transformUrlContent",
+          urlInfo,
+          context,
+          async (transformReturnValue) => {
+            await urlInfoTransformer.applyIntermediateTransformations(
+              urlInfo,
+              transformReturnValue,
+            )
+          },
         )
-        const replaceReturnValue = await replaceUrls((urlMention) => {
-          return urlMention.reference.generatedSpecifier
+      } catch (error) {
+        throw createTransformUrlContentError({
+          pluginController,
+          reference: context.reference,
+          urlInfo,
+          error,
         })
-        await urlInfoTransformer.applyIntermediateTransformations(
+      }
+      // after "transform" all references from originalContent
+      // and the one injected by plugin are known
+      urlGraph.updateReferences(urlInfo, references)
+
+      // "finalize" hook
+      try {
+        const finalizeReturnValue = await pluginController.callAsyncHooksUntil(
+          "finalizeUrlContent",
+          urlInfo,
+          context,
+        )
+        await urlInfoTransformer.applyFinalTransformations(
           urlInfo,
-          replaceReturnValue,
+          finalizeReturnValue,
         )
+      } catch (error) {
+        throw createFinalizeUrlContentError({
+          pluginController,
+          reference: context.reference,
+          urlInfo,
+          error,
+        })
       }
     }
 
-    // "transform" hook
-    urlInfo.references = references
-    context.referenceUtils = referenceUtils
-    try {
-      await pluginController.callAsyncHooks(
-        "transform",
-        urlInfo,
-        context,
-        async (transformReturnValue) => {
-          await urlInfoTransformer.applyIntermediateTransformations(
-            urlInfo,
-            transformReturnValue,
-          )
-        },
-      )
-    } catch (error) {
-      throw createTransformError({
-        pluginController,
-        reference,
-        urlInfo,
-        error,
-      })
-    }
-    // after "transform" all references from originalContent
-    // and the one injected by plugin are known
-    urlGraph.updateReferences(urlInfo, references)
-
-    // "finalize" hook
-    const finalizeReturnValue = await pluginController.callHooksUntil(
-      "finalize",
-      urlInfo,
-      context,
-    )
-    await urlInfoTransformer.applyFinalTransformations(
-      urlInfo,
-      finalizeReturnValue,
-    )
-
     // "cooked" hook
     pluginController.callHooks(
       "cooked",
@@ -532,53 +588,165 @@ export const createKitchen = ({
       },
     )
   }
-  const cook = async ({ urlInfo, outDirectoryUrl, ...rest }) => {
-    outDirectoryUrl = outDirectoryUrl ? String(outDirectoryUrl) : undefined
-
-    const writeFiles = ({ gotError }) => {
-      if (!writeOnFileSystem || !outDirectoryUrl) {
-        return
-      }
+  const cook = memoizeCook(async (urlInfo, context) => {
+    if (!writeGeneratedFiles || !context.outDirectoryUrl) {
+      await _cook(urlInfo, context)
+      return
+    }
+    // writing result inside ".jsenv" directory (debug purposes)
+    try {
+      await _cook(urlInfo, context)
+    } finally {
       const { generatedUrl } = urlInfo
-      // writing result inside ".jsenv" directory (debug purposes)
-      if (!generatedUrl || !generatedUrl.startsWith("file:")) {
-        return
-      }
-      // use writeSync to avoid concurrency on writing the file
-      const write = gotError ? writeFileSync : writeFileSync
-      write(new URL(generatedUrl), urlInfo.content)
-      const { sourcemapGeneratedUrl, sourcemap } = urlInfo
-      if (sourcemapGeneratedUrl && sourcemap) {
-        write(
-          new URL(sourcemapGeneratedUrl),
-          JSON.stringify(sourcemap, null, "  "),
-        )
+      if (generatedUrl && generatedUrl.startsWith("file:")) {
+        if (urlInfo.type === "directory") {
+          // no need to write the directory
+        } else {
+          writeFileSync(new URL(generatedUrl), urlInfo.content)
+          const { sourcemapGeneratedUrl, sourcemap } = urlInfo
+          if (sourcemapGeneratedUrl && sourcemap) {
+            writeFileSync(
+              new URL(sourcemapGeneratedUrl),
+              JSON.stringify(sourcemap, null, "  "),
+            )
+          }
+        }
       }
     }
+  })
+  kitchenContext.fetchUrlContent = fetchUrlContent
+  kitchenContext.cook = cook
 
-    try {
-      await _cook({
-        urlInfo,
-        outDirectoryUrl,
-        ...rest,
-      })
-      writeFiles({ gotError: false })
-    } catch (e) {
-      writeFiles({ gotError: true })
-      throw e
-    }
+  const prepareEntryPoint = (params) => {
+    const entryReference = createReference(params)
+    const entryUrlInfo = resolveReference(entryReference)
+    return [entryReference, entryUrlInfo]
   }
 
-  baseContext.cook = cook
+  const injectReference = (params) => {
+    const ref = createReference(params)
+    const urlInfo = resolveReference(ref)
+    return [ref, urlInfo]
+  }
+
+  const fetchOriginalUrlInfo = async ({
+    urlInfo,
+    context,
+    searchParam,
+    expectedType,
+  }) => {
+    const urlObject = new URL(urlInfo.url)
+    const { searchParams } = urlObject
+    if (!searchParams.has(searchParam)) {
+      return null
+    }
+    searchParams.delete(searchParam)
+    const originalUrl = urlObject.href
+    const originalReference = {
+      ...(context.reference.original || context.reference),
+      expectedType,
+    }
+    originalReference.url = originalUrl
+    const originalUrlInfo = context.urlGraph.reuseOrCreateUrlInfo(
+      originalReference.url,
+    )
+    if (originalUrlInfo.originalUrl === undefined) {
+      applyReferenceEffectsOnUrlInfo(
+        originalReference,
+        originalUrlInfo,
+        context,
+      )
+    }
+    await context.fetchUrlContent(originalUrlInfo, {
+      reference: originalReference,
+    })
+    if (originalUrlInfo.dependents.size === 0) {
+      context.urlGraph.deleteUrlInfo(originalUrlInfo.url)
+    }
+    return originalUrlInfo
+  }
+  kitchenContext.fetchOriginalUrlInfo = fetchOriginalUrlInfo
 
   return {
     pluginController,
     urlInfoTransformer,
     rootDirectoryUrl,
     jsenvDirectoryUrl,
-    createReference,
-    resolveReference,
+    kitchenContext,
     cook,
+    prepareEntryPoint,
+    injectReference,
+  }
+}
+
+const memoizeCook = (cook) => {
+  const pendingDishes = new Map()
+  return async (urlInfo, context) => {
+    const { url, modifiedTimestamp } = urlInfo
+    const pendingDish = pendingDishes.get(url)
+    if (pendingDish) {
+      if (!modifiedTimestamp) {
+        await pendingDish.promise
+        return
+      }
+      if (pendingDish.timestamp > modifiedTimestamp) {
+        await pendingDish.promise
+        return
+      }
+      pendingDishes.delete(url)
+    }
+    const timestamp = Date.now()
+    const promise = cook(urlInfo, context)
+    pendingDishes.set(url, {
+      timestamp,
+      promise,
+    })
+    try {
+      await promise
+    } finally {
+      pendingDishes.delete(url)
+    }
+  }
+}
+
+const applyReferenceEffectsOnUrlInfo = (reference, urlInfo, context) => {
+  if (reference.shouldHandle) {
+    urlInfo.shouldHandle = true
+  } else {
+    urlInfo.shouldHandle = false
+  }
+  urlInfo.originalUrl = urlInfo.originalUrl || reference.url
+
+  Object.assign(urlInfo.data, reference.data)
+  Object.assign(urlInfo.timing, reference.timing)
+  if (reference.injected) {
+    urlInfo.data.injected = true
+  }
+  if (reference.filename) {
+    urlInfo.filename = reference.filename
+  }
+  if (reference.isInline) {
+    urlInfo.isInline = true
+    const parentUrlInfo = context.urlGraph.getUrlInfo(reference.parentUrl)
+    urlInfo.inlineUrlSite = {
+      url: parentUrlInfo.url,
+      content: reference.isOriginalPosition
+        ? parentUrlInfo.originalContent
+        : parentUrlInfo.content,
+      line: reference.specifierLine,
+      column: reference.specifierColumn,
+    }
+    urlInfo.contentType = reference.contentType
+    urlInfo.originalContent =
+      context === "build"
+        ? urlInfo.originalContent === undefined
+          ? reference.content
+          : urlInfo.originalContent
+        : reference.content
+    urlInfo.content = reference.content
+  }
+  if (isWebWorkerEntryPointReference(reference)) {
+    urlInfo.data.isWebWorkerEntryPoint = true
   }
 }
 
@@ -616,104 +784,77 @@ const adjustUrlSite = (urlInfo, { urlGraph, url, line, column }) => {
   )
 }
 
-const inferUrlInfoType = ({ contentType }) => {
+const inferUrlInfoType = ({ url, contentType }) => {
   if (contentType === "text/html") {
     return "html"
   }
   if (contentType === "text/css") {
     return "css"
   }
-  if (contentType === "application/javascript") {
-    return "js"
-  }
-  if (contentType === "application/json") {
-    return "json"
+  if (contentType === "text/javascript") {
+    const urlObject = new URL(url)
+    if (urlObject.searchParams.has("js_classic")) {
+      return "js_classic"
+    }
+    return "js_module"
   }
   if (contentType === "application/importmap+json") {
     return "importmap"
   }
-  return "other"
-}
-
-const determineFileUrlForOutDirectory = ({
-  rootDirectoryUrl,
-  outDirectoryUrl,
-  url,
-}) => {
-  if (!outDirectoryUrl) {
-    return url
+  if (contentType === "application/manifest+json") {
+    return "webmanifest"
   }
-  if (!url.startsWith("file:")) {
-    return url
+  if (contentType === "image/svg+xml") {
+    return "svg"
   }
-  if (!urlIsInsideOf(url, rootDirectoryUrl)) {
-    url = `${rootDirectoryUrl}@fs/${url.slice(fileSystemRootUrl.length)}`
+  if (CONTENT_TYPE.isJson(contentType)) {
+    return "json"
   }
-  return moveUrl({
-    url: fileUrlConverter.asUrlWithoutSpecialParams(url),
-    from: rootDirectoryUrl,
-    to: outDirectoryUrl,
-    preferAbsolute: true,
-  })
+  if (CONTENT_TYPE.isTextual(contentType)) {
+    return "text"
+  }
+  return "other"
 }
 
-const specifierFormat = {
-  encode: (reference) => {
-    const { generatedSpecifier } = reference
-    if (generatedSpecifier.then) {
-      return generatedSpecifier.then((value) => {
-        reference.generatedSpecifier = value
-        return specifierFormat.encode(reference)
-      })
+const inferUrlInfoSubtype = ({ type, subtype, url }) => {
+  if (type === "js_classic" || type === "js_module") {
+    const urlObject = new URL(url)
+    if (urlObject.searchParams.has("worker")) {
+      return "worker"
     }
-    // allow plugin to return a function to bypas default formatting
-    // (which is to use JSON.stringify when url is referenced inside js)
-    if (typeof generatedSpecifier === "function") {
-      return generatedSpecifier()
+    if (urlObject.searchParams.has("service_worker")) {
+      return "service_worker"
     }
-    const formatter = formatters[reference.type]
-    const value = formatter
-      ? formatter.encode(generatedSpecifier)
-      : generatedSpecifier
-    if (reference.escape) {
-      return reference.escape(value)
+    if (urlObject.searchParams.has("shared_worker")) {
+      return "shared_worker"
     }
-    return value
-  },
-  decode: (reference) => {
-    const formatter = formatters[reference.type]
-    return formatter
-      ? formatter.decode(reference.generatedSpecifier)
-      : reference.generatedSpecifier
-  },
+    // if we are currently inside a worker, all deps are consider inside worker too
+    return subtype
+  }
+  return ""
 }
-const formatters = {
-  js_import_export: { encode: JSON.stringify, decode: JSON.parse },
-  js_import_meta_url_pattern: { encode: JSON.stringify, decode: JSON.parse },
-  // https://github.com/webpack-contrib/css-loader/pull/627/files
-  css_url: {
-    encode: (url) => {
-      // If url is already wrapped in quotes, remove them
-      url = formatters.css_url.decode(url)
-      // Should url be wrapped?
-      // See https://drafts.csswg.org/css-values-3/#urls
-      if (/["'() \t\n]/.test(url)) {
-        return `"${url.replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`
-      }
-      return url
-    },
-    decode: (url) => {
-      const firstChar = url[0]
-      const lastChar = url[url.length - 1]
-      if (firstChar === `"` && lastChar === `"`) {
-        return url.slice(1, -1)
-      }
-      if (firstChar === `'` && lastChar === `'`) {
-        return url.slice(1, -1)
-      }
-      return url
-    },
-  },
+
+const determineFileUrlForOutDirectory = ({ urlInfo, context }) => {
+  if (!context.outDirectoryUrl) {
+    return urlInfo.url
+  }
+  if (!urlInfo.url.startsWith("file:")) {
+    return urlInfo.url
+  }
+  let url = urlInfo.url
+  if (!urlIsInsideOf(urlInfo.url, context.rootDirectoryUrl)) {
+    const fsRootUrl = ensureWindowsDriveLetter("file:///", urlInfo.url)
+    url = `${context.rootDirectoryUrl}@fs/${url.slice(fsRootUrl.length)}`
+  }
+  if (urlInfo.filename) {
+    url = setUrlFilename(url, urlInfo.filename)
+  }
+  return moveUrl({
+    url,
+    from: context.rootDirectoryUrl,
+    to: context.outDirectoryUrl,
+    preferAbsolute: true,
+  })
 }
 
 // import { getOriginalPosition } from "@jsenv/core/src/utils/sourcemap/original_position.js"