js api: fall back to js-based metafile json parser

Author: evanw

CHANGELOG.md

@@ -46,6 +46,14 @@
     export { default as 'window.jQuery' } from 'jquery';
     ```
 
+* Attempt to improve API handling of huge metafiles ([#4329](https://github.com/evanw/esbuild/issues/4329), [#4415](https://github.com/evanw/esbuild/issues/4415))
+
+    This release contains a few changes that attempt to improve the behavior of esbuild's JavaScript API with huge metafiles (esbuild's name for the build metadata, formatted as a JSON object). The JavaScript API is designed to return the metafile JSON as a JavaScript object in memory, which makes it easy to access from within a JavaScript-based plugin. Multiple people have encountered issues where this API breaks down with a pathologically-large metafile.
+
+    The primary issue is that V8 has an implementation-specific maximum string length, so using the `JSON.parse` API with large enough strings is impossible. This release will now attempt to use a fallback JavaScript-based JSON parser that operates directly on the UTF8-encoded JSON bytes instead of using `JSON.parse` when the JSON metafile is too big to fit in a JavaScript string. The new fallback path has not yet been heavily-tested. The metafile will also now be generated with whitespace removed if the bundle is significantly large, which will reduce the size of the metafile JSON slightly.
+
+    However, hitting this case is potentially a sign that something else is wrong. Ideally you wouldn't be building something so enormous that the build metadata can't even fit inside a JavaScript string. You may want to consider optimizing your project, or breaking up your project into multiple parts that are built independently. Another option could potentially be to use esbuild's command-line API instead of its JavaScript API, which is more efficient (although of course then you can't use JavaScript plugins, so it may not be an option).
+
 ## 0.27.3
 
 * Preserve URL fragments in data URLs ([#4370](https://github.com/evanw/esbuild/issues/4370))

cmd/esbuild/service.go

@@ -660,7 +660,7 @@ func (service *serviceType) handleBuildRequest(id uint32, request map[string]int
 			response["outputFiles"] = encodeOutputFiles(result.OutputFiles)
 		}
 		if options.Metafile {
-			response["metafile"] = result.Metafile
+			response["metafile"] = []byte(result.Metafile)
 		}
 		if options.MangleCache != nil {
 			response["mangleCache"] = result.MangleCache

lib/shared/common.ts

@@ -1,5 +1,6 @@
 import type * as types from "./types"
 import * as protocol from "./stdio_protocol"
+import { JSON_parse } from "./uint8array_json_parser"
 
 declare const ESBUILD_VERSION: string
 
@@ -952,7 +953,7 @@ function buildOrContextImpl(
       const originalErrors = result.errors.slice()
       const originalWarnings = result.warnings.slice()
       if (response!.outputFiles) result.outputFiles = response!.outputFiles.map(convertOutputFiles)
-      if (response!.metafile) result.metafile = JSON.parse(response!.metafile)
+      if (response!.metafile) result.metafile = parseJSON(response!.metafile)
       if (response!.mangleCache) result.mangleCache = response!.mangleCache
       if (response!.writeToStdout !== void 0) console.log(protocol.decodeUTF8(response!.writeToStdout).replace(/\n$/, ''))
       runOnEndCallbacks(result, (onEndErrors, onEndWarnings) => {
@@ -1858,3 +1859,20 @@ function jsRegExpToGoRegExp(regexp: RegExp): string {
   if (regexp.flags) result = `(?${regexp.flags})${result}`
   return result
 }
+
+function parseJSON(bytes: Uint8Array): any {
+  let text: string
+  try {
+    // This may fail in V8 with the error "Cannot create a string longer than
+    // 0x1fffffe8 characters". Other JS engines may have similar limitations.
+    text = protocol.decodeUTF8(bytes)
+  } catch {
+    // In that case, we attempt to parse the JSON ourselves directly from the
+    // Uint8Array. This bypasses the string length limit as we no longer need
+    // to construct a string that's the length of the input. However, doing
+    // this is likely significantly slower (perhaps around ~4x slower?), so we
+    // only do it if we have to.
+    return JSON_parse(bytes)
+  }
+  return JSON.parse(text)
+}

lib/shared/stdio_protocol.ts

@@ -51,7 +51,7 @@ export interface BuildResponse {
   errors: types.Message[]
   warnings: types.Message[]
   outputFiles?: BuildOutputFile[]
-  metafile?: string
+  metafile?: Uint8Array
   mangleCache?: Record<string, string | false>
   writeToStdout?: Uint8Array
 }