refactor: update jsdoc syntax (#656)

Author: bluwy

packages/vite-plugin-svelte/src/handle-hot-update.ts

@@ -8,7 +8,7 @@ import { toRollupError } from './utils/error.js';
  * @param {import('vite').HmrContext} ctx
  * @param {import('./types/id.d.ts').SvelteRequest} svelteRequest
  * @param {import('./utils/vite-plugin-svelte-cache').VitePluginSvelteCache} cache
- * @param options {import('./types/options.d.ts').ResolvedOptions}
+ * @param {import('./types/options.d.ts').ResolvedOptions} options
  * @returns {Promise<import('vite').ModuleNode[] | void>}
  */
 export async function handleHotUpdate(compileSvelte, ctx, svelteRequest, cache, options) {
@@ -71,18 +71,18 @@ export async function handleHotUpdate(compileSvelte, ctx, svelteRequest, cache,
 }
 
 /**
- * @param {import('./types/compile.d.ts').Code=} prev
- * @param {import('./types/compile.d.ts').Code=} next
+ * @param {import('./types/compile.d.ts').Code} [prev]
+ * @param {import('./types/compile.d.ts').Code} [next]
  * @returns {boolean}
  */
 function cssChanged(prev, next) {
 	return !isCodeEqual(prev?.code, next?.code);
 }
 
 /**
- * @param {import('./types/compile.d.ts').Code=} prev
- * @param {import('./types/compile.d.ts').Code=} next
- * @param {string=} filename
+ * @param {import('./types/compile.d.ts').Code} [prev]
+ * @param {import('./types/compile.d.ts').Code} [next]
+ * @param {string} [filename]
  * @returns {boolean}
  */
 function jsChanged(prev, next, filename) {
@@ -102,8 +102,8 @@ function jsChanged(prev, next, filename) {
 }
 
 /**
- * @param {string=} prev
- * @param {string=} next
+ * @param {string} [prev]
+ * @param {string} [next]
  * @returns {boolean}
  */
 function isCodeEqual(prev, next) {
@@ -121,7 +121,8 @@ function isCodeEqual(prev, next) {
  *
  * 1) add_location() calls. These add location metadata to elements, only used by some dev tools
  * 2) ... maybe more (or less) in the future
- * @param {string=} code
+ *
+ * @param {string} [code]
  * @returns {string | undefined}
  */
 function normalizeJsCode(code) {

packages/vite-plugin-svelte/src/index.d.ts

@@ -1,12 +1,10 @@
-import { InlineConfig, ResolvedConfig, UserConfig, Plugin } from 'vite';
-
-import { CompileOptions, Warning } from 'svelte/types/compiler/interfaces';
-
-import { PreprocessorGroup } from 'svelte/types/compiler/preprocess';
-
+import type { InlineConfig, ResolvedConfig, UserConfig, Plugin } from 'vite';
+import type { CompileOptions, Warning } from 'svelte/types/compiler/interfaces';
+import type { PreprocessorGroup } from 'svelte/types/compiler/preprocess';
 import type { Options as InspectorOptions } from '@sveltejs/vite-plugin-svelte-inspector';
 
 type Options = Omit<SvelteOptions, 'vitePlugin'> & PluginOptionsInline;
+
 interface PluginOptionsInline extends PluginOptions {
 	/**
 	 * Path to a svelte config file, either absolute or relative to Vite root
@@ -17,6 +15,7 @@ interface PluginOptionsInline extends PluginOptions {
 	 */
 	configFile?: string | false;
 }
+
 interface PluginOptions {
 	/**
 	 * A `picomatch` pattern, or array of patterns, which specifies the files the plugin should
@@ -100,6 +99,7 @@ interface PluginOptions {
 	 */
 	experimental?: ExperimentalOptions;
 }
+
 interface SvelteOptions {
 	/**
 	 * A list of file extensions to be compiled by Svelte
@@ -130,6 +130,7 @@ interface SvelteOptions {
 	 */
 	vitePlugin?: PluginOptions;
 }
+
 /**
  * These options are considered experimental and breaking changes to them can occur in any release
  */
@@ -170,6 +171,7 @@ interface ExperimentalOptions {
 	 */
 	disableSvelteResolveWarnings?: boolean;
 }
+
 type ModuleFormat = NonNullable<CompileOptions['format']>;
 type CssHashGetter = NonNullable<CompileOptions['cssHash']>;
 type Arrayable<T> = T | T[];

packages/vite-plugin-svelte/src/index.ts

@@ -29,11 +29,7 @@ import { FAQ_LINK_CONFLICTS_IN_SVELTE_RESOLVE } from './utils/constants.js';
 const isVite4_0 = viteVersion.startsWith('4.0');
 const isSvelte3 = svelteVersion.startsWith('3');
 
-/**
- *
- * @param {Partial<import('./index.d.ts').Options>=} inlineOptions
- * @returns {import('vite').Plugin[]}
- */
+/** @type {import('./index.d.ts').svelte} */
 export function svelte(inlineOptions) {
 	if (process.env.DEBUG != null) {
 		log.setLevel('debug');

packages/vite-plugin-svelte/src/preprocess.ts

@@ -1,18 +1,18 @@
 import { preprocessCSS, resolveConfig, transformWithEsbuild } from 'vite';
 import { mapToRelative, removeLangSuffix } from './utils/sourcemaps.js';
 
+/**
+ * @typedef {(code: string, filename: string) => Promise<{ code: string; map?: any; deps?: Set<string> }>} CssTransform
+ */
+
 const supportedStyleLangs = ['css', 'less', 'sass', 'scss', 'styl', 'stylus', 'postcss', 'sss'];
 const supportedScriptLangs = ['ts'];
 
 export const lang_sep = '.vite-preprocess.';
 
-/**
- *
- * @param {import('./index.d.ts').VitePreprocessOptions=} opts
- * @returns {import('svelte/types/compiler/preprocess').PreprocessorGroup}
- */
+/** @type {import('./index.d.ts').vitePreprocess} */
 export function vitePreprocess(opts) {
-	/**@type {import('svelte/types/compiler/preprocess').PreprocessorGroup} */
+	/** @type {import('svelte/types/compiler/preprocess').PreprocessorGroup} */
 	const preprocessor = {};
 	if (opts?.script !== false) {
 		preprocessor.script = viteScript().script;
@@ -25,8 +25,7 @@ export function vitePreprocess(opts) {
 }
 
 /**
- *
- * @returns {{script:import('svelte/types/compiler/preprocess').Preprocessor}}
+ * @returns {{ script: import('svelte/types/compiler/preprocess').Preprocessor }}
  */
 function viteScript() {
 	return {
@@ -57,12 +56,12 @@ function viteScript() {
 
 /**
  * @param {import('vite').ResolvedConfig | import('vite').InlineConfig} config
- * @returns {{style:import('svelte/types/compiler/preprocess').Preprocessor}}
+ * @returns {{ style: import('svelte/types/compiler/preprocess').Preprocessor }}
  */
 function viteStyle(config = {}) {
-	/** @type import('./types/preprocess.d.ts').CssTransform */
+	/** @type {CssTransform} */
 	let transform;
-	/** @type import('svelte/types/compiler/preprocess').Preprocessor */
+	/** @type {import('svelte/types/compiler/preprocess').Preprocessor} */
 	const style = async ({ attributes, content, filename = '' }) => {
 		const lang = /** @type {string} */ (attributes.lang);
 		if (!supportedStyleLangs.includes(lang)) return;
@@ -102,13 +101,14 @@ function viteStyle(config = {}) {
 
 /**
  * @param {import('vite').ResolvedConfig} config
- * @returns {import('./types/preprocess.d.ts').CssTransform}
+ * @returns {CssTransform}
  */
 function getCssTransformFn(config) {
 	return async (code, filename) => {
 		return preprocessCSS(code, filename, config);
 	};
 }
+
 /**
  * @param {any} config
  * @returns {config is import('vite').ResolvedConfig}

packages/vite-plugin-svelte/src/types/compile.d.ts

@@ -1,6 +1,7 @@
 import type { Processed } from 'svelte/types/compiler/preprocess';
 import type { SvelteRequest } from './id.d.ts';
 import type { ResolvedOptions } from './options.d.ts';
+
 export type CompileSvelte = (
 	svelteRequest: SvelteRequest,
 	code: string,

packages/vite-plugin-svelte/src/types/dependencies.d.ts

@@ -1,8 +1,6 @@
 import type { CompileOptions } from 'svelte/types/compiler/interfaces';
 import type { ViteDevServer } from 'vite';
 import { VitePluginSvelteStats } from '../utils/vite-plugin-svelte-stats.js';
-
-import type { Options as InspectorOptions } from '@sveltejs/vite-plugin-svelte-inspector';
 import type { Options } from '../index.d.ts';
 
 export interface PreResolvedOptions extends Options {

packages/vite-plugin-svelte/src/types/esbuild.d.ts

@@ -26,6 +26,5 @@ export interface PackageStats {
 
 export interface CollectionOptions {
 	logInProgress: (collection: StatCollection, now: number) => boolean;
-
 	logResult: (collection: StatCollection) => boolean;
 }

packages/vite-plugin-svelte/src/types/options.d.ts

@@ -10,15 +10,14 @@ import { mapToRelative } from './sourcemaps.js';
 const scriptLangRE = /<script [^>]*lang=["']?([^"' >]+)["']?[^>]*>/;
 
 /**
- *
- * @param {Function=} makeHot
+ * @param {Function} [makeHot]
  * @returns {import('../types/compile.d.ts').CompileSvelte}
  */
 export const _createCompileSvelte = (makeHot) => {
 	/** @type {import('../types/vite-plugin-svelte-stats.d.ts').StatCollection | undefined} */
 	let stats;
 	const devStylePreprocessor = createInjectScopeEverythingRulePreprocessorGroup();
-	/**@type {import('../types/compile.d.ts').CompileSvelte} */
+	/** @type {import('../types/compile.d.ts').CompileSvelte} */
 	return async function compileSvelte(svelteRequest, code, options) {
 		const { filename, normalizedFilename, cssId, ssr, raw } = svelteRequest;
 		const { emitCss = true } = options;
@@ -95,8 +94,8 @@ export const _createCompileSvelte = (makeHot) => {
 			mapToRelative(preprocessed?.map, filename);
 		}
 		if (raw && svelteRequest.query.type === 'preprocessed') {
-			// shortcut
-			return /**@type {import('../types/compile.d.ts').CompileData} */ {
+			// @ts-expect-error shortcut
+			return /** @type {import('../types/compile.d.ts').CompileData} */ {
 				preprocessed: preprocessed ?? { code }
 			};
 		}
@@ -168,10 +167,10 @@ export const _createCompileSvelte = (makeHot) => {
 		};
 	};
 };
+
 /**
- *
  * @param {import('../types/options.d.ts').ResolvedOptions} options
- * @returns {Function|undefined}
+ * @returns {Function | undefined}
  */
 function buildMakeHot(options) {
 	const needsMakeHot = options.hot !== false && options.isServe && !options.isProduction;
@@ -184,12 +183,12 @@ function buildMakeHot(options) {
 			walk,
 			hotApi,
 			adapter,
-			hotOptions: { noOverlay: true, .../** @type {object} */ options.hot }
+			hotOptions: { noOverlay: true, .../** @type {object} */ (options.hot) }
 		});
 	}
 }
+
 /**
- *
  * @param {import('../types/options.d.ts').ResolvedOptions} options
  * @returns {import('../types/compile.d.ts').CompileSvelte}
  */

packages/vite-plugin-svelte/src/types/preprocess.d.ts

@@ -1,13 +1,18 @@
 import path from 'path';
 import fs from 'fs/promises';
-
 import { findDepPkgJsonPath } from 'vitefu';
 
 /**
- *
+ * @typedef {{
+ *  dir: string;
+ *	pkg: Record<string, any>;
+ * }} DependencyData
+ */
+
+/**
  * @param {string} dep
  * @param {string} parent
- * @returns {Promise<import('../types/dependencies.d.ts').DependencyData|undefined>}
+ * @returns {Promise<DependencyData | undefined>}
  */
 export async function resolveDependencyData(dep, parent) {
 	const depDataPath = await findDepPkgJsonPath(dep, parent);

packages/vite-plugin-svelte/src/types/sourcemaps.d.ts

@@ -2,13 +2,13 @@ import { buildExtendedLogMessage } from './log.js';
 
 /**
  * convert an error thrown by svelte.compile to a RollupError so that vite displays it in a user friendly way
- * @param {import('../index.d.ts').Warning & Error} error a svelte compiler error, which is a mix of Warning and an error
+ * @param {import('svelte/types/compiler/interfaces').Warning & Error} error a svelte compiler error, which is a mix of Warning and an error
  * @param {import('../types/options.d.ts').ResolvedOptions} options
  * @returns {import('rollup').RollupError} the converted error
  */
 export function toRollupError(error, options) {
 	const { filename, frame, start, code, name, stack } = error;
-	/** @type  {import('rollup').RollupError} */
+	/** @type {import('rollup').RollupError} */
 	const rollupError = {
 		name, // needed otherwise sveltekit coalesce_to_error turns it into a string
 		id: filename,
@@ -29,7 +29,7 @@ export function toRollupError(error, options) {
 
 /**
  * convert an error thrown by svelte.compile to an esbuild PartialMessage
- * @param {import('../index.d.ts').Warning & Error} error a svelte compiler error, which is a mix of Warning and an error
+ * @param {import('svelte/types/compiler/interfaces').Warning & Error} error a svelte compiler error, which is a mix of Warning and an error
  * @param {import('../types/options.d.ts').ResolvedOptions} options
  * @returns {import('esbuild').PartialMessage} the converted error
  */
@@ -57,7 +57,7 @@ export function toESBuildError(error, options) {
  * extract line with number from codeframe
  *
  * @param {number} lineNo
- * @param {string=} frame
+ * @param {string} [frame]
  * @returns {string}
  */
 function lineFromFrame(lineNo, frame) {
@@ -88,8 +88,8 @@ function lineFromFrame(lineNo, frame) {
  *  3 | baz
  * ```
  * @see https://github.com/vitejs/vite/blob/96591bf9989529de839ba89958755eafe4c445ae/packages/vite/src/client/overlay.ts#L116
- * @param {string=} frame
- * @returns string
+ * @param {string} [frame]
+ * @returns {string}
  */
 function formatFrameForVite(frame) {
 	if (!frame) {