feat: hoist function declarations to be compliant with default js hoisting behavior

Author: skoshx

src/core/types.ts

@@ -161,6 +161,11 @@ export type FlytrapConfig = {
 	 * Use this to limit the size of your captures or limit the amount of files that context gets sent from.
 	 */
 	captureAmountLimit?: CaptureAmountLimit
+	/**
+	 * Allows you to disable the default hoisting behavior of function declarations that Flytrap enforces. If you disable function declaration hoisting, wrapped function declarations will no longer go to the top of their respective scopes, and you might run into runtime errors. [Learn more](https://docs.useflytrap.com/troubleshoot/runtime-problems#cannot-access-functionname-before-initialization)
+	 * @default false
+	 */
+	disableFunctionDeclarationHoisting?: boolean
 }
 
 export type ErrorType = {

src/transform/index.ts

@@ -20,7 +20,8 @@ import {
 	isMemberExpression,
 	isNumericLiteral,
 	isStringLiteral,
-	Identifier
+	Identifier,
+	ImportDeclaration
 } from '@babel/types'
 import generate from '@babel/generator'
 
@@ -178,6 +179,44 @@ export function flytrapTransformUff(
 						)
 					])
 
+					// Handle function declaration hoisting
+					if (config?.disableFunctionDeclarationHoisting) {
+						path.replaceWith(transformedNode)
+						return
+					}
+
+					const scopePath = path.findParent((parentPath) => {
+						return parentPath.isBlockStatement() || parentPath.isProgram()
+					})
+
+					if (scopePath) {
+						let lastImportPath: NodePath<ImportDeclaration> | undefined = undefined
+						const bodyNode = scopePath.get('body')
+						if (Array.isArray(bodyNode)) {
+							bodyNode.forEach((bodyPath) => {
+								if (bodyPath.isImportDeclaration()) {
+									lastImportPath = bodyPath
+								}
+							})
+						} else if (bodyNode.isImportDeclaration()) {
+							lastImportPath = bodyNode
+						}
+
+						if (lastImportPath) {
+							// Insert after the last import statement
+							lastImportPath.insertAfter(transformedNode)
+						} else {
+							// @ts-expect-error: Otherwise, insert at the top of the current scope
+							scopePath.unshiftContainer('body', transformedNode)
+						}
+
+						// Remove the original function declaration
+						path.remove()
+						return
+					} else {
+						// @todo: add warning
+					}
+					// No hoisting if there is no parent scope
 					path.replaceWith(transformedNode)
 				}
 			}),

test/transform-uff.test.ts

@@ -205,3 +205,160 @@ describe('calls', () => {
 		})
 	}
 })
+
+const functionHoistingFixture: Record<string, TransformFixture[]> = {
+	'hoists top level scope': [
+		{
+			fixture: `
+			console.log(foo());
+			function foo() {}
+			`,
+			expected: `
+			const foo = uff(function foo() {}, '/file.js-_foo');
+			console.log(foo());
+			`
+		}
+	],
+	'hoists inside arrow functions': [
+		{
+			fixture: `
+			() => {
+				console.log(foo());
+				function foo() {}
+			}
+			`,
+			expected: `
+			uff(() => {
+				const foo = uff(function foo() {}, '/file.js-_anonymousFoo');
+				console.log(foo());
+			}, '/file.js-_anonymous')
+			`
+		}
+	],
+	'hoists inside function expressions': [
+		{
+			fixture: `
+			const x = function() {
+				console.log(foo());
+				function foo() {}
+			}
+			`,
+			expected: `
+			const x = uff(function() {
+				const foo = uff(function foo() {}, '/file.js-_anonymousFoo');
+				console.log(foo());
+			}, '/file.js-_x')
+			`
+		}
+	],
+	'hoists inside function declarations': [
+		{
+			fixture: `
+			function bar() {
+				console.log(foo());
+				function foo() {}
+			}
+			`,
+			expected: `
+			const bar = uff(function bar() {
+				const foo = uff(function foo() {}, '/file.js-_barFoo');
+				console.log(foo());
+			}, '/file.js-_bar')
+			`
+		}
+	],
+	'hoists inside block scopes': [
+		{
+			fixture: `
+			{
+				console.log(foo());
+				function foo() {}
+			}
+			`,
+			expected: `
+			{
+				const foo = uff(function foo() {}, '/file.js-_foo');
+				console.log(foo());
+			}`
+		}
+	],
+	'hoisted functions continue being traversed and transformed': [
+		{
+			fixture: `
+			console.log(foo())
+			function foo() {
+				const bar = () => {};
+			}
+			`,
+			expected: `
+			const foo = uff(function foo() {
+				const bar = uff(() => {}, '/file.js-_fooBar')
+			}, '/file.js-_foo')
+			console.log(foo())
+			`
+		}
+	],
+	'code doesnt get hoisted above directives': [
+		{
+			fixture: `
+			'use client';
+			
+			console.log(foo());
+			function foo() {}
+			`,
+			expected: `
+			'use client';
+
+			const foo = uff(function foo() {}, '/file.js-_foo');
+			console.log(foo());`
+		},
+		{
+			fixture: `
+			async function myAction() {
+				'use server'
+
+				console.log(foo());
+				function foo() {}
+			}`,
+			expected: `
+			const myAction = uff(async function myAction() {
+				'use server'
+
+				const foo = uff(function foo() {}, '/file.js-_myActionFoo');
+				console.log(foo());
+			}, '/file.js-_myAction')
+			`
+		}
+	],
+	'code doesnt get hoisted above imports': [
+		{
+			fixture: `
+			import { uff } from 'useflytrap';
+
+			console.log(foo());
+			function foo() {}
+			`,
+			expected: `
+			import { uff } from 'useflytrap';
+			const foo = uff(function foo() {}, '/file.js-_foo');
+			console.log(foo());
+			`
+		}
+	]
+}
+
+describe('function declaration hoisting', () => {
+	for (const [suiteName, suiteFixtures] of Object.entries(functionHoistingFixture)) {
+		it(suiteName, () => {
+			for (let i = 0; i < suiteFixtures.length; i++) {
+				const { code } = flytrapTransformUff(suiteFixtures[i].fixture, '/file.js', {
+					transformOptions: {
+						disableTransformation: ['call-expression']
+					}
+				})
+
+				expect(toOneLine(code)).toBe(toOneLine(suiteFixtures[i].expected))
+			}
+		})
+	}
+})