refactor(core): consolidate options validation and cleanup into core

Author: mcous

src/__tests__/render-runes.test-d.ts

@@ -29,8 +29,9 @@ describe('types', () => {
   test('render result has container and component', () => {
     const result = subject.render(Component, { name: 'Alice', count: 42 })
 
-    expectTypeOf(result).toMatchTypeOf<{
+    expectTypeOf(result).toExtend<{
       container: HTMLElement
+      baseElement: HTMLElement
       component: { hello: string }
       debug: (el?: HTMLElement) => void
       rerender: (props: { name?: string; count?: number }) => Promise<void>
@@ -55,7 +56,7 @@ describe('legacy component types', () => {
       count: 42,
     })
 
-    expectTypeOf(component).toMatchTypeOf<{ hello: string }>()
+    expectTypeOf(component).toExtend<{ hello: string }>()
 
     // @ts-expect-error: Svelte 5 mount does not return `$set`
     component.$on('greeting', onGreeting)

src/__tests__/render-utilities.test-d.ts

@@ -8,7 +8,7 @@ describe('render query and utility types', () => {
   test('render result has default queries', () => {
     const result = subject.render(Component, { name: 'Alice' })
 
-    expectTypeOf(result.getByRole).parameters.toMatchTypeOf<
+    expectTypeOf(result.getByRole).parameters.toExtend<
       [role: subject.ByRoleMatcher, options?: subject.ByRoleOptions]
     >()
   })
@@ -27,25 +27,25 @@ describe('render query and utility types', () => {
       { queries: { getByVibes } }
     )
 
-    expectTypeOf(result.getByVibes).parameters.toMatchTypeOf<[vibes: string]>()
+    expectTypeOf(result.getByVibes).parameters.toExtend<[vibes: string]>()
   })
 
   test('act is an async function', () => {
-    expectTypeOf(subject.act).toMatchTypeOf<() => Promise<void>>()
+    expectTypeOf(subject.act).toExtend<() => Promise<void>>()
   })
 
   test('act accepts a sync function', () => {
-    expectTypeOf(subject.act).toMatchTypeOf<(fn: () => void) => Promise<void>>()
+    expectTypeOf(subject.act).toExtend<(fn: () => void) => Promise<void>>()
   })
 
   test('act accepts an async function', () => {
-    expectTypeOf(subject.act).toMatchTypeOf<
+    expectTypeOf(subject.act).toExtend<
       (fn: () => Promise<void>) => Promise<void>
     >()
   })
 
   test('fireEvent is an async function', () => {
-    expectTypeOf(subject.fireEvent).toMatchTypeOf<
+    expectTypeOf(subject.fireEvent).toExtend<
       (
         element: Element | Node | Document | Window,
         event: Event
@@ -54,7 +54,7 @@ describe('render query and utility types', () => {
   })
 
   test('fireEvent[eventName] is an async function', () => {
-    expectTypeOf(subject.fireEvent.click).toMatchTypeOf<
+    expectTypeOf(subject.fireEvent.click).toExtend<
       (
         element: Element | Node | Document | Window,
         // eslint-disable-next-line @typescript-eslint/no-empty-object-type

src/__tests__/render.test-d.ts

@@ -37,8 +37,9 @@ describe('types', () => {
   test('render result has container and component', () => {
     const result = subject.render(Component, { name: 'Alice', count: 42 })
 
-    expectTypeOf(result).toMatchTypeOf<{
+    expectTypeOf(result).toExtend<{
       container: HTMLElement
+      baseElement: HTMLElement
       component: { hello: string }
       debug: (el?: HTMLElement) => void
       rerender: (props: { name?: string; count?: number }) => Promise<void>

src/core/cleanup.js

@@ -0,0 +1,32 @@
+/** @type {Set<() => void>} */
+const cleanupTasks = new Set()
+
+/**
+ * Register later cleanup task
+ *
+ * @param {() => void} onCleanup
+ */
+const addCleanupTask = (onCleanup) => {
+  cleanupTasks.add(onCleanup)
+  return onCleanup
+}
+
+/**
+ * Remove a cleanup task without running it.
+ *
+ * @param {() => void} onCleanup
+ */
+const removeCleanupTask = (onCleanup) => {
+  cleanupTasks.delete(onCleanup)
+}
+
+/** Clean up all components and elements added to the document. */
+const cleanup = () => {
+  for (const handleCleanup of cleanupTasks.values()) {
+    handleCleanup()
+  }
+
+  cleanupTasks.clear()
+}
+
+export { addCleanupTask, cleanup, removeCleanupTask }

src/core/index.js

@@ -5,20 +5,6 @@
  * Will switch to legacy, class-based mounting logic
  * if it looks like we're in a Svelte <= 4 environment.
  */
-import * as MountLegacy from './mount-legacy.js'
-import * as MountModern from './mount-modern.svelte.js'
-import { createValidateOptions, UnknownSvelteOptionsError } from './prepare.js'
-
-const { mount, unmount, updateProps, allowedOptions } =
-  MountModern.IS_MODERN_SVELTE ? MountModern : MountLegacy
-
-/** Validate component options. */
-const validateOptions = createValidateOptions(allowedOptions)
-
-export {
-  mount,
-  UnknownSvelteOptionsError,
-  unmount,
-  updateProps,
-  validateOptions,
-}
+export { cleanup } from './cleanup.js'
+export { mount } from './mount.js'
+export { prepare, UnknownSvelteOptionsError } from './prepare.js'

src/core/mount-legacy.js

@@ -4,8 +4,10 @@
  * Supports Svelte <= 4.
  */
 
+import { addCleanupTask, removeCleanupTask } from './cleanup.js'
+
 /** Allowed options for the component constructor. */
-const allowedOptions = [
+const ALLOWED_OPTIONS = [
   'target',
   'accessors',
   'anchor',
@@ -15,32 +17,31 @@ const allowedOptions = [
   'context',
 ]
 
-/**
- * Mount the component into the DOM.
- *
- * The `onDestroy` callback is included for strict backwards compatibility
- * with previous versions of this library. It's mostly unnecessary logic.
- */
-const mount = (Component, options, onDestroy) => {
+/** Mount the component into the DOM. */
+const mount = (Component, options) => {
   const component = new Component(options)
 
-  if (typeof onDestroy === 'function') {
-    component.$$.on_destroy.push(() => {
-      onDestroy(component)
-    })
+  /** Remove the component from the DOM. */
+  const unmount = () => {
+    component.$destroy()
+    removeCleanupTask(unmount)
   }
 
-  return component
-}
+  /** Update the component's props. */
+  const rerender = (nextProps) => {
+    component.$set(nextProps)
+  }
 
-/** Remove the component from the DOM. */
-const unmount = (component) => {
-  component.$destroy()
-}
+  // This `$$.on_destroy` listener is included for strict backwards compatibility
+  // with previous versions of `@testing-library/svelte`.
+  // It's unnecessary and will be removed in a future major version.
+  component.$$.on_destroy.push(() => {
+    removeCleanupTask(unmount)
+  })
+
+  addCleanupTask(unmount)
 
-/** Update the component's props. */
-const updateProps = (component, nextProps) => {
-  component.$set(nextProps)
+  return { component, unmount, rerender }
 }
 
-export { allowedOptions, mount, unmount, updateProps }
+export { ALLOWED_OPTIONS, mount }

src/core/mount-modern.svelte.js

@@ -5,14 +5,13 @@
  */
 import * as Svelte from 'svelte'
 
-/** Props signals for each rendered component. */
-const propsByComponent = new Map()
+import { addCleanupTask, removeCleanupTask } from './cleanup.js'
 
 /** Whether we're using Svelte >= 5. */
 const IS_MODERN_SVELTE = typeof Svelte.mount === 'function'
 
 /** Allowed options to the `mount` call. */
-const allowedOptions = [
+const ALLOWED_OPTIONS = [
   'target',
   'anchor',
   'props',
@@ -26,26 +25,21 @@ const mount = (Component, options) => {
   const props = $state(options.props ?? {})
   const component = Svelte.mount(Component, { ...options, props })
 
-  Svelte.flushSync()
-  propsByComponent.set(component, props)
+  /** Remove the component from the DOM. */
+  const unmount = () => {
+    Svelte.flushSync(() => Svelte.unmount(component))
+    removeCleanupTask(unmount)
+  }
 
-  return component
-}
+  /** Update the component's props. */
+  const rerender = (nextProps) => {
+    Svelte.flushSync(() => Object.assign(props, nextProps))
+  }
 
-/** Remove the component from the DOM. */
-const unmount = (component) => {
-  propsByComponent.delete(component)
-  Svelte.flushSync(() => Svelte.unmount(component))
-}
+  addCleanupTask(unmount)
+  Svelte.flushSync()
 
-/**
- * Update the component's props.
- *
- * Relies on the `$state` signal added in `mount`.
- */
-const updateProps = (component, nextProps) => {
-  const prevProps = propsByComponent.get(component)
-  Object.assign(prevProps, nextProps)
+  return { component, unmount, rerender }
 }
 
-export { allowedOptions, IS_MODERN_SVELTE, mount, unmount, updateProps }
+export { ALLOWED_OPTIONS, IS_MODERN_SVELTE, mount }

src/core/mount.js

@@ -0,0 +1,36 @@
+import { tick } from 'svelte'
+
+import * as MountLegacy from './mount-legacy.js'
+import * as MountModern from './mount-modern.svelte.js'
+
+const mountComponent = MountModern.IS_MODERN_SVELTE
+  ? MountModern.mount
+  : MountLegacy.mount
+
+/**
+ * Render a Svelte component into the document.
+ *
+ * @template {import('./types.js').Component} C
+ * @param {import('./types.js').ComponentType<C>} Component
+ * @param {import('./types.js').MountOptions<C>} options
+ * @returns {{
+ *   component: C
+ *   unmount: () => void
+ *   rerender: (props: Partial<import('./types.js').Props<C>>) => Promise<void>
+ * }}
+ */
+const mount = (Component, options = {}) => {
+  const { component, unmount, rerender } = mountComponent(Component, options)
+
+  return {
+    component,
+    unmount,
+    rerender: async (props) => {
+      rerender(props)
+      // Await the next tick for Svelte 4, which cannot flush changes synchronously
+      await tick()
+    },
+  }
+}
+
+export { mount }

src/core/prepare.js

@@ -1,9 +1,18 @@
+import { addCleanupTask } from './cleanup.js'
+import * as MountLegacy from './mount-legacy.js'
+import * as MountModern from './mount-modern.svelte.js'
+
+const ALLOWED_OPTIONS = MountModern.IS_MODERN_SVELTE
+  ? MountModern.ALLOWED_OPTIONS
+  : MountLegacy.ALLOWED_OPTIONS
+
+/** An error thrown for incorrect options and clashes between props and Svelte options. */
 class UnknownSvelteOptionsError extends TypeError {
-  constructor(unknownOptions, allowedOptions) {
+  constructor(unknownOptions) {
     super(`Unknown options.
 
     Unknown: [ ${unknownOptions.join(', ')} ]
-    Allowed: [ ${allowedOptions.join(', ')} ]
+    Allowed: [ ${ALLOWED_OPTIONS.join(', ')} ]
 
     To pass both Svelte options and props to a component,
     or to use props that share a name with a Svelte option,
@@ -15,9 +24,41 @@ class UnknownSvelteOptionsError extends TypeError {
   }
 }
 
-const createValidateOptions = (allowedOptions) => (options) => {
+/**
+ * Prepare DOM elements for rendering.
+ *
+ * @template {import('./types.js').Component} C
+ * @param {import('./types.js').PropsOrMountOptions<C>} propsOrOptions
+ * @param {{ baseElement?: HTMLElement }} renderOptions
+ * @returns {{
+ *   baseElement: HTMLElement
+ *   target: HTMLElement
+ *   mountOptions: import('./types.js').MountOptions<C>
+ * }}
+ */
+const prepare = (propsOrOptions = {}, renderOptions = {}) => {
+  const mountOptions = validateMountOptions(propsOrOptions)
+
+  const baseElement =
+    renderOptions.baseElement ?? mountOptions.target ?? document.body
+
+  const target =
+    mountOptions.target ??
+    baseElement.appendChild(document.createElement('div'))
+
+  addCleanupTask(() => {
+    if (target.parentNode === document.body) {
+      document.body.removeChild(target)
+    }
+  })
+
+  return { baseElement, target, mountOptions: { ...mountOptions, target } }
+}
+
+/** Prevent incorrect options and clashes between props and Svelte options. */
+const validateMountOptions = (options) => {
   const isProps = !Object.keys(options).some((option) =>
-    allowedOptions.includes(option)
+    ALLOWED_OPTIONS.includes(option)
   )
 
   if (isProps) {
@@ -26,14 +67,14 @@ const createValidateOptions = (allowedOptions) => (options) => {
 
   // Check if any props and Svelte options were accidentally mixed.
   const unknownOptions = Object.keys(options).filter(
-    (option) => !allowedOptions.includes(option)
+    (option) => !ALLOWED_OPTIONS.includes(option)
   )
 
   if (unknownOptions.length > 0) {
-    throw new UnknownSvelteOptionsError(unknownOptions, allowedOptions)
+    throw new UnknownSvelteOptionsError(unknownOptions)
   }
 
   return options
 }
 
-export { createValidateOptions, UnknownSvelteOptionsError }
+export { prepare, UnknownSvelteOptionsError }

src/core/types.d.ts

@@ -59,3 +59,8 @@ export type Exports<C> = IS_MODERN_SVELTE extends true
 export type MountOptions<C extends Component> = IS_MODERN_SVELTE extends true
   ? Parameters<typeof mount<Props<C>, Exports<C>>>[1]
   : LegacyConstructorOptions<Props<C>>
+
+/** Component props or partial mount options. */
+export type PropsOrMountOptions<C extends Component> =
+  | Props<C>
+  | Partial<MountOptions<C>>