|
|
@@ -0,0 +1,305 @@
|
|
|
+// @vitest-environment jsdom
|
|
|
+/**
|
|
|
+ * ClientModuleLoaderImpl behavior: lazy CJS arrival (bundle execution only
|
|
|
+ * registers the factory), materialization on first import/require with
|
|
|
+ * memoization and recursive self-sequencing, the resolution branch order,
|
|
|
+ * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
|
|
|
+ * default transport seams, and the loud failure modes (duplicate
|
|
|
+ * registration, cycles, table misses, double boot).
|
|
|
+ */
|
|
|
+import { afterEach, describe, expect, it, vi } from 'vitest'
|
|
|
+import {
|
|
|
+ ClientModuleLoaderImpl, createClientModuleLoader,
|
|
|
+ type ClientModuleLoader, type ClientPluginHandoff, type DshWindow, type WebBootEntry,
|
|
|
+} from '../src/index.ts'
|
|
|
+
|
|
|
+const win = globalThis as DshWindow
|
|
|
+
|
|
|
+type Factory = ClientPluginHandoff['factory']
|
|
|
+
|
|
|
+afterEach(() => {
|
|
|
+ vi.unstubAllGlobals()
|
|
|
+ delete win.__ModuleLoader__
|
|
|
+ delete (document as unknown as Record<string, unknown>).__realmBridge
|
|
|
+ for (const el of document.querySelectorAll('style, script')) el.remove()
|
|
|
+})
|
|
|
+
|
|
|
+const row = (id: string): WebBootEntry => ({ id, url: `/plugins/${id}/client.js?rev=0` })
|
|
|
+
|
|
|
+interface Bench {
|
|
|
+ loader: ClientModuleLoader
|
|
|
+ fetched: string[]
|
|
|
+ gates: Map<string, () => void>
|
|
|
+}
|
|
|
+
|
|
|
+/**
|
|
|
+ * Loader over scripted bundles: fetch resolves to the row url (optionally
|
|
|
+ * gated on a release callback); execute registers the scripted factory
|
|
|
+ * through the window sink (`null` scripts a bundle that never calls load).
|
|
|
+ */
|
|
|
+function bench(
|
|
|
+ entries: WebBootEntry[],
|
|
|
+ bundles: Record<string, Factory | null> = {},
|
|
|
+ opts: { seed?: Record<string, unknown>; gated?: string[] } = {},
|
|
|
+): Bench {
|
|
|
+ const fetched: string[] = []
|
|
|
+ const gates = new Map<string, () => void>()
|
|
|
+ const loader = createClientModuleLoader({
|
|
|
+ graph: { rev: 'test', entries },
|
|
|
+ staticModules: opts.seed ?? {},
|
|
|
+ fetchBundle: (url) => {
|
|
|
+ fetched.push(url)
|
|
|
+ if (opts.gated?.includes(url) === true) {
|
|
|
+ return new Promise((resolve) => { gates.set(url, () => { resolve(url) }) })
|
|
|
+ }
|
|
|
+ return Promise.resolve(url)
|
|
|
+ },
|
|
|
+ executeBundle: (code) => {
|
|
|
+ const id = /\/plugins\/(.+)\/client\.js/.exec(code)?.[1]
|
|
|
+ const factory = id === undefined ? undefined : bundles[id]
|
|
|
+ if (factory == null || id === undefined) return
|
|
|
+ win.__ModuleLoader__?.load({ id, factory })
|
|
|
+ },
|
|
|
+ })
|
|
|
+ return { loader, fetched, gates }
|
|
|
+}
|
|
|
+
|
|
|
+describe('lazy CJS arrival', () => {
|
|
|
+ it('prefetch fetches and executes but does not run the factory', async () => {
|
|
|
+ const ran: string[] = []
|
|
|
+ const b = bench([row('a')], { a: () => { ran.push('a'); return {} } })
|
|
|
+ await b.loader.prefetch('a')
|
|
|
+ expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
|
|
|
+ expect(ran).toEqual([])
|
|
|
+ expect(b.loader.loadCache.size).toBe(0)
|
|
|
+ })
|
|
|
+
|
|
|
+ it('import materializes once and memoizes the export surface', async () => {
|
|
|
+ const ran: string[] = []
|
|
|
+ const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } })
|
|
|
+ const first = await b.loader.import('a', '', {})
|
|
|
+ const second = await b.loader.import('a', '', {})
|
|
|
+ expect(first).toBe(second)
|
|
|
+ expect((first as { marker: string }).marker).toBe('a')
|
|
|
+ expect(ran).toEqual(['a'])
|
|
|
+ expect(b.loader.loadCache.get('a')?.id).toBe('a')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('import without prefetch fetches, executes, and materializes in one call', async () => {
|
|
|
+ const b = bench([row('a')], { a: () => ({ marker: 'direct' }) })
|
|
|
+ const surface = await b.loader.import('a', '', {})
|
|
|
+ expect((surface as { marker: string }).marker).toBe('direct')
|
|
|
+ expect(b.fetched).toHaveLength(1)
|
|
|
+ })
|
|
|
+
|
|
|
+ it('concurrent callers share one in-flight arrival and materialize once', async () => {
|
|
|
+ const ran: string[] = []
|
|
|
+ const url = '/plugins/a/client.js?rev=0'
|
|
|
+ const b = bench([row('a')], { a: () => { ran.push('a'); return { marker: 'a' } } }, { gated: [url] })
|
|
|
+ const first = b.loader.import('a', '', {})
|
|
|
+ const second = b.loader.import('a', '', {})
|
|
|
+ const third = b.loader.prefetch('a')
|
|
|
+ b.gates.get(url)?.()
|
|
|
+ const [s1, s2] = await Promise.all([first, second, third])
|
|
|
+ expect(s1).toBe(s2)
|
|
|
+ expect(b.fetched).toEqual([url])
|
|
|
+ expect(ran).toEqual(['a'])
|
|
|
+ })
|
|
|
+
|
|
|
+ it('prefetch after registration is a no-op without invalidate', async () => {
|
|
|
+ const b = bench([row('a')], { a: () => ({}) })
|
|
|
+ await b.loader.prefetch('a')
|
|
|
+ await b.loader.prefetch('a')
|
|
|
+ expect(b.fetched).toHaveLength(1)
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('require resolution', () => {
|
|
|
+ it('a factory requiring a registered-but-unmaterialized module materializes it recursively', async () => {
|
|
|
+ const order: string[] = []
|
|
|
+ const b = bench([row('a'), row('b')], {
|
|
|
+ a: (req) => {
|
|
|
+ order.push('a')
|
|
|
+ const dep = req('b/client') as { helper: string }
|
|
|
+ return { got: dep.helper }
|
|
|
+ },
|
|
|
+ b: () => { order.push('b'); return { helper: 'from-b' } },
|
|
|
+ })
|
|
|
+ await b.loader.prefetch('a')
|
|
|
+ await b.loader.prefetch('b')
|
|
|
+ const surface = await b.loader.import('a', '', {})
|
|
|
+ expect((surface as { got: string }).got).toBe('from-b')
|
|
|
+ expect(order).toEqual(['a', 'b'])
|
|
|
+ expect(b.loader.loadCache.get('a')?.edges.has('b/client')).toBe(true)
|
|
|
+ expect(b.loader.loadCache.has('b')).toBe(true)
|
|
|
+ })
|
|
|
+
|
|
|
+ it('require prefers the platform seed word over the module table', async () => {
|
|
|
+ const react = { marker: 'react' }
|
|
|
+ const b = bench([row('a')], {
|
|
|
+ a: (req) => ({ dep: req('react') }),
|
|
|
+ }, { seed: { react } })
|
|
|
+ const surface = await b.loader.import('a', '', {})
|
|
|
+ expect((surface as { dep: unknown }).dep).toBe(react)
|
|
|
+ expect(await b.loader.import('react', '', {})).toBe(react)
|
|
|
+ expect(b.loader.loadCache.has('react')).toBe(false)
|
|
|
+ })
|
|
|
+
|
|
|
+ it('require answers an already-materialized module from the cache', async () => {
|
|
|
+ let built = 0
|
|
|
+ const b = bench([row('a'), row('c')], {
|
|
|
+ a: (req) => ({ dep: req('c') }),
|
|
|
+ c: () => { built += 1; return { marker: 'c' } },
|
|
|
+ })
|
|
|
+ const c = await b.loader.import('c', '', {})
|
|
|
+ const a = await b.loader.import('a', '', {})
|
|
|
+ expect((a as { dep: unknown }).dep).toBe(c)
|
|
|
+ expect(built).toBe(1)
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a require that misses the module table is loud', async () => {
|
|
|
+ const b = bench([row('a')], { a: (req) => ({ dep: req('ghost') }) })
|
|
|
+ await expect(b.loader.import('a', '', {})).rejects.toThrow('require("ghost") missed the module table')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a require cycle is fatal', async () => {
|
|
|
+ const b = bench([row('a'), row('b')], {
|
|
|
+ a: (req) => ({ dep: req('b') }),
|
|
|
+ b: (req) => ({ dep: req('a') }),
|
|
|
+ })
|
|
|
+ await b.loader.prefetch('b')
|
|
|
+ await expect(b.loader.import('a', '', {})).rejects.toThrow('require cycle through "a"')
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('static registry', () => {
|
|
|
+ it('serves shell-own modules to import and require without any fetch', async () => {
|
|
|
+ const shell = { marker: 'app-shell' }
|
|
|
+ const b = bench([row('a'), { id: 'app-shell' }], {
|
|
|
+ a: (req) => ({ dep: req('app-shell') }),
|
|
|
+ })
|
|
|
+ b.loader.registerStatic('app-shell', shell)
|
|
|
+ await b.loader.prefetch('app-shell')
|
|
|
+ expect(await b.loader.import('app-shell', '', {})).toBe(shell)
|
|
|
+ expect(b.loader.loadCache.get('app-shell')?.styles).toEqual([])
|
|
|
+ expect((await b.loader.import('a', '', {}) as { dep: unknown }).dep).toBe(shell)
|
|
|
+ expect(b.fetched).toEqual(['/plugins/a/client.js?rev=0'])
|
|
|
+ })
|
|
|
+
|
|
|
+ it('duplicate static registration is loud', () => {
|
|
|
+ const b = bench([])
|
|
|
+ b.loader.registerStatic('app-shell', {})
|
|
|
+ expect(() => { b.loader.registerStatic('app-shell', {}) }).toThrow('registered twice')
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('failure modes', () => {
|
|
|
+ it('duplicate factory registration is loud', () => {
|
|
|
+ bench([])
|
|
|
+ win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) })
|
|
|
+ expect(() => win.__ModuleLoader__?.load({ id: 'x', factory: () => ({}) }))
|
|
|
+ .toThrow('duplicate factory registration for "x"')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a bundle that never registers its id is loud', async () => {
|
|
|
+ const b = bench([row('a')], { a: null })
|
|
|
+ await expect(b.loader.import('a', '', {})).rejects.toThrow('without registering "a"')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('an unknown import specifier is loud', async () => {
|
|
|
+ const b = bench([])
|
|
|
+ await expect(b.loader.import('nope', '', {})).rejects.toThrow('cannot resolve "nope"')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('an unknown prefetch id is loud', async () => {
|
|
|
+ const b = bench([])
|
|
|
+ await expect(b.loader.prefetch('nope')).rejects.toThrow('prefetch("nope") — not a graph entry')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a graph row with no url and no static registration is loud', async () => {
|
|
|
+ const b = bench([{ id: 'ghost' }])
|
|
|
+ await expect(b.loader.import('ghost', '', {})).rejects.toThrow('no bundle url and no static registration')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a duplicate graph entry is loud at construction', () => {
|
|
|
+ expect(() => bench([row('a'), row('a')])).toThrow('duplicate graph entry "a"')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('double boot is loud', () => {
|
|
|
+ bench([])
|
|
|
+ expect(() => new ClientModuleLoaderImpl({ graph: { rev: 't', entries: [] }, staticModules: {} }))
|
|
|
+ .toThrow('already installed (double boot?)')
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('HMR reset', () => {
|
|
|
+ it('invalidate drops the factory and record so the module refetches and re-registers', async () => {
|
|
|
+ let generation = 0
|
|
|
+ const b = bench([row('a')], { a: () => ({ generation: ++generation }) })
|
|
|
+ const first = await b.loader.import('a', '', {})
|
|
|
+ b.loader.invalidate('a')
|
|
|
+ expect(b.loader.loadCache.has('a')).toBe(false)
|
|
|
+ await b.loader.prefetch('a')
|
|
|
+ const second = await b.loader.import('a', '', {})
|
|
|
+ expect(b.fetched).toHaveLength(2)
|
|
|
+ expect((first as { generation: number }).generation).toBe(1)
|
|
|
+ expect((second as { generation: number }).generation).toBe(2)
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('style claiming', () => {
|
|
|
+ it('claims untagged style tags for the materializing plugin and inventories owned css ids', async () => {
|
|
|
+ const foreign = document.createElement('style')
|
|
|
+ foreign.setAttribute('data-plugin', 'other')
|
|
|
+ document.head.appendChild(foreign)
|
|
|
+ const b = bench([row('a')], {
|
|
|
+ a: () => {
|
|
|
+ document.head.appendChild(document.createElement('style'))
|
|
|
+ const tagged = document.createElement('style')
|
|
|
+ tagged.setAttribute('data-plugin', 'a')
|
|
|
+ tagged.setAttribute('data-plugin-css', 'sheet-1')
|
|
|
+ document.head.appendChild(tagged)
|
|
|
+ return {}
|
|
|
+ },
|
|
|
+ })
|
|
|
+ await b.loader.import('a', '', {})
|
|
|
+ expect(b.loader.loadCache.get('a')?.styles).toEqual(['a', 'sheet-1'])
|
|
|
+ expect(document.querySelectorAll('style[data-plugin="a"]')).toHaveLength(2)
|
|
|
+ expect(foreign.getAttribute('data-plugin')).toBe('other')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('materialization without a document skips the style inventory', async () => {
|
|
|
+ const b = bench([row('a')], { a: () => ({}) })
|
|
|
+ vi.stubGlobal('document', undefined)
|
|
|
+ try {
|
|
|
+ await b.loader.import('a', '', {})
|
|
|
+ } finally {
|
|
|
+ vi.unstubAllGlobals()
|
|
|
+ }
|
|
|
+ expect(b.loader.loadCache.get('a')?.styles).toEqual([])
|
|
|
+ })
|
|
|
+})
|
|
|
+
|
|
|
+describe('default transport seams', () => {
|
|
|
+ it('fetches same-origin and executes through an inline script tag', async () => {
|
|
|
+ // In a browser the loader's globalThis IS the page window; vitest's jsdom
|
|
|
+ // evaluates <script> in a separate realm that shares only the document,
|
|
|
+ // so the fixture bundle restores the sink from a document bridge before
|
|
|
+ // using the normal calling convention.
|
|
|
+ const code = 'window.__ModuleLoader__ = document.__realmBridge;\n'
|
|
|
+ + 'window.__ModuleLoader__.load({ id: "dee", factory: function () { return { marker: "via-script" } } })'
|
|
|
+ vi.stubGlobal('fetch', async () => ({ ok: true, text: async () => code }))
|
|
|
+ const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
|
|
|
+ ;(document as unknown as Record<string, unknown>).__realmBridge = win.__ModuleLoader__
|
|
|
+ const surface = await loader.import('dee', '', {})
|
|
|
+ expect((surface as { marker: string }).marker).toBe('via-script')
|
|
|
+ const script = [...document.querySelectorAll('script')].at(-1)
|
|
|
+ expect(script?.textContent).toContain('//# sourceURL=/plugins/dee/client.js?rev=0')
|
|
|
+ })
|
|
|
+
|
|
|
+ it('a non-ok bundle response is loud with the status', async () => {
|
|
|
+ vi.stubGlobal('fetch', async () => ({ ok: false, status: 404 }))
|
|
|
+ const loader = createClientModuleLoader({ graph: { rev: 't', entries: [row('dee')] }, staticModules: {} })
|
|
|
+ await expect(loader.prefetch('dee')).rejects.toThrow('answered 404')
|
|
|
+ })
|
|
|
+})
|
imccyu