imccyu
c12277b4bb
The node half is ClientModuleHostService (ctx.clientModuleHost): it composes the __DSH_BOOT__ graph by scanning loader entries for dshClient packages, serves /plugins/<id>/client.js, taps the index render, and exposes rebuilt/onRebuilt/onGraphChanged. Scanning is incremental per package — no full-rescan path exists: internal/plugin marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata (including negative verdicts) caches forever, and re-hashing is reachable only through rebuilt(id). The browser half moves wholesale to the standard ./client export (ClientModuleSystem, parseBootManifest with the dual-view BootManifest, and the adoption plugin face that reads the window.__DSH_MODULES__ slot and provides ctx.modules).
302 lines
12 KiB
TypeScript
302 lines
12 KiB
TypeScript
// @vitest-environment jsdom
|
|
/**
|
|
* ClientModuleSystem 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 {
|
|
ClientModuleSystem,
|
|
type BootModuleRow, type ClientModuleLoader, type ClientPluginHandoff, type DshWindow,
|
|
} from '../src/client/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): BootModuleRow => ({ id, url: `/plugins/${id}/client.js?rev=0`, 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: BootModuleRow[],
|
|
bundles: Record<string, Factory | null> = {},
|
|
opts: { seed?: Record<string, unknown>; gated?: string[] } = {},
|
|
): Bench {
|
|
const fetched: string[] = []
|
|
const gates = new Map<string, () => void>()
|
|
const loader = new ClientModuleSystem({
|
|
modules: 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')], {
|
|
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 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 ClientModuleSystem({ modules: [], 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: ClientModuleLoader = new ClientModuleSystem({ modules: [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')
|
|
// The script node is removed right after its synchronous execution —
|
|
// repeated HMR rebuilds must not accumulate dead script nodes.
|
|
expect([...document.querySelectorAll('script')]).toEqual([])
|
|
})
|
|
|
|
it('a non-ok bundle response is loud with the status', async () => {
|
|
vi.stubGlobal('fetch', async () => ({ ok: false, status: 404 }))
|
|
const loader = new ClientModuleSystem({ modules: [row('dee')], staticModules: {} })
|
|
await expect(loader.prefetch('dee')).rejects.toThrow('answered 404')
|
|
})
|
|
})
|