[pkg/inline-mod]: Implements new lazyValue utility

.changeset/wicked-fireants-switch.md

@@ -0,0 +1,6 @@
+---
+"@inox-tools/inline-mod": minor
+"@inox-tools/aik-mod": patch
+---
+
+Implements new `lazyValue` utility

docs/src/content/docs/inline-mod/aik-plugin.md

@@ -35,7 +35,7 @@ export default defineIntegration({
 
 ## API
 
-The plugin exposes multiple entrypoints, all of them accept normal values and [factory wrappers](/inline-mod/factory-wrappers) as values to be included in the virtual modules.
+The plugin exposes multiple entrypoints, all of them accept normal values, [factory wrappers](/inline-mod/factory-wrappers) and [lazy values](/inline-mod/lazy) as values to be included in the virtual modules.
 
 ### `inlineModule`
 

docs/src/content/docs/inline-mod/lazy.md

@@ -0,0 +1,47 @@
+---
+title: Lazy values
+sidebar:
+  order: 2
+  badge:
+    text: ADVANCED
+    variant: danger
+---
+
+:::danger
+Lazy values are an advanced utility, misuse of this feature may cause dealocks, infinite recursions or even serialization of unsafe values.
+In most cases, [`asyncFactory`](/inline-mod/factory-wrappers#asyncfactory) is a better choice.
+
+Make sure your use case comply with all the [requirements](#requirements) laid out on this page.
+:::
+
+Sometimes you can only get a valye after the module where it should be serialized to is created. When using the [AIK Plugin](/inline-mod/aik-plugin), for example, you can only define an inline module during the `astro:config:setup` hook, but you might want to serialize a value from other hooks.
+
+For such use cases, you can use the `lazyValue` utility to create a placeholder value that you can set later:
+
+```ts
+import { lazyValue } from '@inox-tools/inline-mod';
+import { defineModule } from '@inox-tools/inline-mod/vite';
+
+const value = lazyValue();
+
+defineModule('virtual:your-plugin/config', {
+  constExports: { value },
+});
+
+value.set('hello');
+```
+
+## Under the hood
+
+Internally this utility will park the module inspection and serialization in Node's event loop such that it can be resumed once, and only once, the value of the lazy value is set.
+This allows for as much of the inspection/serialization work to be done preemptively, and not wait for the value to be set.
+
+During the module resolution, anything awaiting on the `load` event of the virtual module will also be parked until the value is set.
+
+## Requirements
+
+When using `lazyValue` you must provide the following guarantees:
+
+- The value is set on all possible code paths
+- The value is set before Vite's bundling is expected to complete (and here we say expected because if you don't set the value, Vite will never complete the bundling)
+- The value being set does not depend on resolving the serialization of the value (neither directly or indirectly)

packages/aik-mod/src/index.ts

@@ -8,7 +8,13 @@ import { definePlugin } from 'astro-integration-kit';
 import { AstroError } from 'astro/errors';
 import type { PluginOption } from 'vite';
 
-export { asyncFactory, factory } from '@inox-tools/inline-mod';
+export {
+	asyncFactory,
+	factory,
+	lazyValue,
+	type LazyValue,
+	type ResolvedLazyValue,
+} from '@inox-tools/inline-mod';
 
 type HookParams = HookParameters<'astro:config:setup'>;
 

packages/inline-mod/src/closure/inspectCode.ts

@@ -118,7 +118,7 @@ class Inspector {
 	// a serialized function for each of those, we can emit them a single time.
 	private readonly simpleFunctions: Entry<'function'>[] = [];
 
-	public constructor(private readonly serialize: (o: unknown) => boolean) {}
+	public constructor(private readonly serialize: (o: unknown) => boolean) { }
 
 	public async inspect(
 		value: unknown,
@@ -284,6 +284,12 @@ class Inspector {
 			};
 		}
 
+		const lazyValue = tryExtractLazyValue(value);
+		if (lazyValue) {
+			const resolvedValue = await lazyValue;
+			return this.inspect(resolvedValue);
+		}
+
 		if (this.doNotCapture(value)) {
 			log('Value should skip capture');
 			return Entry.json();
@@ -1145,12 +1151,62 @@ export function magicFactory<T extends Record<any, any>>({
 	) as unknown as T;
 }
 
-function tryExtractMagicFactory(value: any): MagicPlaceholder[typeof factorySymbol] | undefined {
+function tryExtractMagicFactory(
+	value: any
+): MagicPlaceholder<any>[typeof factorySymbol] | undefined {
 	if (factorySymbol in value) {
 		return value[factorySymbol];
 	}
 }
 
+const lazyValueSymbol = Symbol('inox-tool/lazy-value');
+
+export interface LazyValue<T> {
+	[lazyValueSymbol]: Promise<T>;
+	resolved: boolean;
+	resolve(this: LazyValue<T>, value: T): asserts this is ResolvedLazyValue<T>;
+}
+
+export type ResolvedLazyValue<T> = {
+	[lazyValueSymbol]: Promise<T>;
+	resolved: true;
+	resolve: never;
+};
+
+const lazyProxyHandler: ProxyHandler<LazyValue<any>> = {
+	set: () => {
+		throw new Error('Cannot set properties on a lazy value');
+	},
+};
+
+export function makeLazyValue<T>(): LazyValue<T> {
+	let resolve: (value: T) => void;
+	const promise = new Promise<T>((_resolve) => {
+		resolve = _resolve;
+	});
+
+	const target: LazyValue<T> = {
+		[lazyValueSymbol]: promise,
+		resolved: false,
+		resolve(value) {
+			if (target.resolved) {
+				throw new Error('A lazy value can only be resolved once.');
+			}
+
+			resolve(value);
+			target.resolved = true;
+		},
+	};
+
+	return new Proxy<LazyValue<T>>(target, lazyProxyHandler);
+}
+
+function tryExtractLazyValue(value: any): Promise<unknown> | undefined {
+	if (lazyValueSymbol in value) {
+		return value[lazyValueSymbol];
+	}
+}
+
 /**
  * Cache of global entries
  */
@@ -1191,7 +1247,7 @@ class GlobalCache {
 		// these values can be cached once and reused across avery run.
 
 		// Add entries to allow proper serialization over generators and iterators.
-		const emptyGenerator = function* (): any {};
+		const emptyGenerator = function*(): any { };
 
 		this.cache.addUnchecked(Object.getPrototypeOf(emptyGenerator), {
 			type: 'expr',

packages/inline-mod/src/index.ts

@@ -1,4 +1,9 @@
 import { magicFactory } from './closure/inspectCode.js';
+export {
+	type LazyValue,
+	type ResolvedLazyValue,
+	makeLazyValue as lazyValue,
+} from './closure/inspectCode.js';
 
 export function factory<T>(factoryFn: () => T): T {
 	return magicFactory({

packages/inline-mod/tests/functions.test.ts

@@ -82,89 +82,3 @@ test('recurring function', async () => {
     export default __f;
   `);
 });
-
-test('factory values', async () => {
-	let callCount = 0;
-
-	const factoryValue = magicFactory({
-		isAsync: false,
-		fn: () => {
-			callCount++;
-
-			return {
-				value: 'foo',
-			};
-		},
-	});
-
-	const modInfo = await inspectInlineMod({
-		defaultExport: factoryValue,
-	});
-
-	expect(modInfo.text).toEqualIgnoringWhitespace(`
-    function __f0() {
-      return (function() {
-        const callCount = 0;
-        return () => {
-          callCount++;
-          return {
-            value: "foo"
-          };
-        };
-      }).apply(undefined, undefined).apply(this, arguments);
-    }
-
-    const __defaultExport = __f0();
-
-    export default __defaultExport;
-  `);
-
-	expect(callCount).toBe(0);
-
-	expect(factoryValue.value).toEqual('foo');
-
-	expect(callCount).toBe(1);
-
-	factoryValue.value = 'bar';
-	expect(factoryValue.value).toEqual('bar');
-
-	expect(callCount).toBe(1);
-});
-
-test('async factory values', async () => {
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used to test serialization
-	let callCount = 0;
-
-	const factoryValue = magicFactory({
-		isAsync: true,
-		fn: () => {
-			callCount++;
-
-			return Promise.resolve({
-				value: 'foo',
-			});
-		},
-	});
-
-	const modInfo = await inspectInlineMod({
-		defaultExport: factoryValue,
-	});
-
-	expect(modInfo.text).toEqualIgnoringWhitespace(`
-    function __f0() {
-      return (function() {
-        const callCount = 0;
-        return () => {
-          callCount++;
-          return Promise.resolve({
-            value: "foo"
-          });
-        };
-      }).apply(undefined, undefined).apply(this, arguments);
-    }
-
-    const __defaultExport = await __f0();
-
-    export default __defaultExport;
-  `);
-});

packages/inline-mod/tests/specialValues.test.ts

@@ -0,0 +1,99 @@
+import { expect, test } from 'vitest';
+import { inspectInlineMod } from '../src/inlining.js';
+import { asyncFactory, factory, lazyValue } from '../src/index.js';
+
+test('factory values', async () => {
+	let callCount = 0;
+
+	const factoryValue = factory(() => {
+		callCount++;
+
+		return {
+			value: 'foo',
+		};
+	});
+
+	const modInfo = await inspectInlineMod({
+		defaultExport: factoryValue,
+	});
+
+	expect(modInfo.text).toEqualIgnoringWhitespace(`
+    function __f0() {
+      return (function() {
+        const callCount = 0;
+        return () => {
+          callCount++;
+          return {
+            value: "foo"
+          };
+        };
+      }).apply(undefined, undefined).apply(this, arguments);
+    }
+
+    const __defaultExport = __f0();
+
+    export default __defaultExport;
+  `);
+
+	expect(callCount).toBe(0);
+
+	expect(factoryValue.value).toEqual('foo');
+
+	expect(callCount).toBe(1);
+
+	factoryValue.value = 'bar';
+	expect(factoryValue.value).toEqual('bar');
+
+	expect(callCount).toBe(1);
+});
+
+test('async factory values', async () => {
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Used to test serialization
+	let callCount = 0;
+
+	const factoryValue = asyncFactory(() => {
+		callCount++;
+
+		return Promise.resolve({
+			value: 'foo',
+		});
+	});
+
+	const modInfo = await inspectInlineMod({
+		defaultExport: factoryValue,
+	});
+
+	expect(modInfo.text).toEqualIgnoringWhitespace(`
+    function __f0() {
+      return (function() {
+        const callCount = 0;
+        return () => {
+          callCount++;
+          return Promise.resolve({
+            value: "foo"
+          });
+        };
+      }).apply(undefined, undefined).apply(this, arguments);
+    }
+
+    const __defaultExport = await __f0();
+
+    export default __defaultExport;
+  `);
+});
+
+test('lazy values', async () => {
+	const value = lazyValue<string>();
+
+	setTimeout(() => {
+		value.resolve('foo');
+	}, 500);
+
+	const modInfo = await inspectInlineMod({
+		defaultExport: value,
+	});
+
+	expect(modInfo.text).toEqualIgnoringWhitespace(`
+    export default "foo";
+  `);
+});

packages/inline-mod/tsconfig.json

@@ -1,4 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/tsconfig",
-  "extends": "../../tsconfig.base.json"
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  }
 }