vite-plugin-taro 0.3.2 → 0.4.0

package/src/node/plugins/wx/render/capsule-wrapper.ts

@@ -0,0 +1,86 @@
+import { type PluginObject, types } from '@babel/core'
+import { resolveChunkReference } from '../../../utils/modules.ts'
+
+/** Wraps System.register as an inert CommonJS capsule tuple with canonical final dependency IDs. */
+export function wrapCapsulePlugin(fileName: string): PluginObject {
+    return {
+        name: 'vpt:wrap-capsule',
+        visitor: {},
+
+        post(file) {
+            const program = file.ast.program
+            const [statement] = program.body
+            const registration = statement && types.isExpressionStatement(statement) ? statement.expression : undefined
+
+            if (
+                program.body.length !== 1 ||
+                !types.isCallExpression(registration) ||
+                !types.isMemberExpression(registration.callee) ||
+                registration.callee.computed ||
+                !types.isIdentifier(registration.callee.object, { name: 'System' }) ||
+                !types.isIdentifier(registration.callee.property, { name: 'register' })
+            ) {
+                throw new Error(`Expected one anonymous System.register call in ${fileName}`)
+            }
+
+            const [dependencies, declaration] = registration.arguments
+            if (
+                registration.arguments.length !== 2 ||
+                !types.isArrayExpression(dependencies) ||
+                !types.isFunctionExpression(declaration)
+            ) {
+                throw new Error(`Expected System.register(dependencies, declaration) in ${fileName}`)
+            }
+
+            dependencies.elements.forEach((dependency) => {
+                canonicalizeStaticReference(dependency, fileName)
+            })
+
+            const context = declaration.params[1]
+            if (types.isIdentifier(context)) {
+                file.path.traverse({
+                    CallExpression(callPath) {
+                        const callee = callPath.node.callee
+                        if (
+                            !types.isMemberExpression(callee) ||
+                            callee.computed ||
+                            !types.isIdentifier(callee.object, { name: context.name }) ||
+                            !types.isIdentifier(callee.property, { name: 'import' })
+                        ) {
+                            return
+                        }
+
+                        const [dependency] = callPath.node.arguments
+                        canonicalizeDynamicReference(dependency, fileName)
+                    }
+                })
+            }
+
+            program.directives = []
+            program.body = [
+                types.expressionStatement(
+                    types.assignmentExpression(
+                        '=',
+                        types.memberExpression(types.identifier('module'), types.identifier('exports')),
+                        types.arrayExpression([dependencies, declaration])
+                    )
+                )
+            ]
+        }
+    }
+}
+
+/** Resolves one generated static reference while the final importing chunk filename is known. */
+function canonicalizeStaticReference(reference: types.Node | null | undefined, fileName: string): void {
+    if (!types.isStringLiteral(reference)) {
+        throw new Error(`Expected a literal System.register dependency in ${fileName}`)
+    }
+    reference.value = resolveChunkReference(fileName, reference.value)
+}
+
+/** Resolves application literals while preserving runtime-computed IDs injected by the development runtime. */
+function canonicalizeDynamicReference(reference: types.Node | null | undefined, fileName: string): void {
+    if (types.isStringLiteral(reference) && (reference.value.startsWith('./') || reference.value.startsWith('../'))) {
+        reference.value = resolveChunkReference(fileName, reference.value)
+    }
+}

package/src/node/plugins/wx/render/capsule.ts

@@ -0,0 +1,21 @@
+import type { PluginTarget } from '@babel/core'
+import transformDynamicImport from '@babel/plugin-transform-dynamic-import'
+import transformModulesSystemjs from '@babel/plugin-transform-modules-systemjs'
+import type { Rolldown } from 'vite'
+import { type AstTransformResult, transformWithBabel } from '../../../utils/transform.ts'
+import { wrapCapsulePlugin } from './capsule-wrapper.ts'
+
+/** Renders one ESM chunk as an inert SystemJS capsule. */
+export function renderCapsule(code: string, chunk: Rolldown.RenderedChunk, sourcemap = true): AstTransformResult {
+    return transformWithBabel(
+        code,
+        chunk.fileName,
+        [
+            transformDynamicImport,
+            // Erase Babel's internal plugin pass type.
+            transformModulesSystemjs as PluginTarget,
+            wrapCapsulePlugin(chunk.fileName) as PluginTarget
+        ],
+        sourcemap
+    )
+}

package/src/node/plugins/wx/render/native.ts

@@ -0,0 +1,84 @@
+import { type PluginObject, type PluginTarget, types } from '@babel/core'
+import transformModulesCommonjs from '@babel/plugin-transform-modules-commonjs'
+import type { Rolldown } from 'vite'
+import { resolveChunkReference } from '../../../utils/modules.ts'
+import { type AstTransformResult, transformWithBabel } from '../../../utils/transform.ts'
+import { getWxEntryRole } from '../module.ts'
+
+/** Renders a native module while activating its statically imported capsules through SystemJS. */
+export function renderNative({
+    code,
+    chunk,
+    chunks,
+    sourcemap
+}: {
+    code: string
+    chunk: Rolldown.RenderedChunk
+    chunks: Readonly<Record<string, Rolldown.RenderedChunk>>
+    sourcemap: boolean
+}): AstTransformResult {
+    return transformWithBabel(
+        code,
+        chunk.fileName,
+        [connectNativeCapsulesPlugin(chunk.fileName, chunks) as PluginTarget, transformModulesCommonjs as PluginTarget],
+        sourcemap
+    )
+}
+
+/** Converts only cross-runtime static imports; ordinary native dependencies remain CommonJS imports. */
+function connectNativeCapsulesPlugin(
+    fileName: string,
+    chunks: Readonly<Record<string, Rolldown.RenderedChunk>>
+): PluginObject {
+    return {
+        name: 'vpt:connect-native-capsules',
+        visitor: {
+            ImportDeclaration(importPath) {
+                const reference = importPath.node.source.value
+                if (!reference.startsWith('./') && !reference.startsWith('../')) {
+                    return
+                }
+
+                const chunkId = resolveChunkReference(fileName, reference)
+                const importedChunk = chunks[chunkId]
+                if (!importedChunk || getWxEntryRole(importedChunk) !== 'capsule') {
+                    return
+                }
+
+                const [specifier] = importPath.node.specifiers
+                if (
+                    importPath.node.specifiers.length !== 1 ||
+                    !specifier ||
+                    types.isImportNamespaceSpecifier(specifier)
+                ) {
+                    throw new Error(`Expected one capsule value import from ${chunkId} in ${fileName}`)
+                }
+
+                const imported = types.isImportDefaultSpecifier(specifier)
+                    ? types.identifier('default')
+                    : specifier.imported
+                const importedConfig = types.memberExpression(
+                    createSyncImport(chunkId),
+                    types.cloneNode(imported),
+                    types.isStringLiteral(imported)
+                )
+                importPath.replaceWith(
+                    types.variableDeclaration('const', [
+                        types.variableDeclarator(types.cloneNode(specifier.local), importedConfig)
+                    ])
+                )
+            }
+        }
+    }
+}
+
+/** Creates one synchronous lookup through the canonical output chunk ID. */
+function createSyncImport(chunkId: string): types.CallExpression {
+    return types.callExpression(
+        types.memberExpression(
+            types.memberExpression(types.identifier('global'), types.identifier('System')),
+            types.identifier('importSync')
+        ),
+        [types.stringLiteral(chunkId)]
+    )
+}

package/src/node/plugins/wx/render/transport.ts

@@ -0,0 +1,157 @@
+import path from 'node:path'
+import { types } from '@babel/core'
+import type { Rolldown } from 'vite'
+import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
+import { getWxExecutionKind } from '../module.ts'
+
+const transportPlaceholder = '__VITE_PLUGIN_TARO_TRANSPORT__'
+const moduleIdParameter = 'moduleId'
+const exportBindingParameter = 'exportBinding'
+
+type TransportedChunk = {
+    chunk: Rolldown.RenderedChunk
+    kind: 'capsule' | 'amphibious'
+}
+
+/**
+ * Materializes transport while Rolldown's preliminary hash placeholders are still active, so every injected physical
+ * reference participates in final hash calculation instead of changing code after its filename has been fixed.
+ *
+ * This intentionally creates broad hash invalidation: changing one capsule can rename transport, then bootstrap, then
+ * chunks that import bootstrap. A Mini Program ships one application package rather than independently cached HTTP
+ * chunks, so honest content hashes and automatic graph linking are more valuable than minimizing that hash fan-out.
+ */
+export async function materializeTransport({
+    code,
+    transportChunk,
+    chunks,
+    getLoadMode,
+    sourcemap = true
+}: {
+    code: string
+    transportChunk: Rolldown.RenderedChunk
+    chunks: Readonly<Record<string, Rolldown.RenderedChunk>>
+    getLoadMode(chunk: Rolldown.RenderedChunk): 'sync' | 'async'
+    sourcemap?: boolean
+}): Promise<AstTransformResult> {
+    // Babel constructs and safely serializes an expression shaped like:
+    // (moduleId) => {
+    //     switch (moduleId) {
+    //         case 'assets/app.js': return require('./app.js')
+    //         case 'sub/p_account/page.js': return require.async('../sub/p_account/page.js')
+    //         case 'assets/bootstrap.js':
+    //             return [[], (exportBinding) => ({ execute() { exportBinding(require('./bootstrap.js')) } })]
+    //         default: throw new Error(`Unknown System module: ${moduleId}`)
+    //     }
+    // }
+    const cases = getTransportedChunks(chunks)
+        .sort((left, right) => left.chunk.fileName.localeCompare(right.chunk.fileName))
+        .map(({ chunk, kind }) => {
+            const loadMode = getLoadMode(chunk)
+            if (kind === 'amphibious' && loadMode !== 'sync') {
+                throw new Error(`Amphibious wx module must be in the main package: ${chunk.fileName}`)
+            }
+
+            return createTransportCase({
+                chunkId: chunk.fileName,
+                transportFileName: transportChunk.fileName,
+                loadMode,
+                kind
+            })
+        })
+
+    return await replaceWithAst(
+        code,
+        transportChunk.fileName,
+        {
+            [transportPlaceholder]: types.arrowFunctionExpression(
+                [types.identifier(moduleIdParameter)],
+                types.blockStatement([
+                    types.switchStatement(types.identifier(moduleIdParameter), [
+                        ...cases,
+                        createUnknownModuleCase(moduleIdParameter)
+                    ])
+                ])
+            )
+        },
+        sourcemap
+    )
+}
+
+/** Keeps only capsule and amphibious chunks and carries their narrowed kind into source generation. */
+function getTransportedChunks(chunks: Readonly<Record<string, Rolldown.RenderedChunk>>): TransportedChunk[] {
+    const transportedChunks: TransportedChunk[] = []
+
+    for (const chunk of Object.values(chunks)) {
+        const kind = getWxExecutionKind(chunk)
+        if (kind !== 'native') {
+            transportedChunks.push({ chunk, kind })
+        }
+    }
+
+    return transportedChunks
+}
+
+/** Creates one canonical-ID switch case while keeping its native require argument literal. */
+function createTransportCase({
+    chunkId,
+    transportFileName,
+    loadMode,
+    kind
+}: {
+    chunkId: string
+    transportFileName: string
+    loadMode: 'sync' | 'async'
+    kind: 'capsule' | 'amphibious'
+}): ReturnType<typeof types.switchCase> {
+    const requirePath = toNativeRequirePath(transportFileName, chunkId)
+
+    const requireCallee =
+        loadMode === 'sync'
+            ? types.identifier('require')
+            : types.memberExpression(types.identifier('require'), types.identifier('async'))
+
+    const loadedModule = types.callExpression(requireCallee, [types.stringLiteral(requirePath)])
+    const registration = kind === 'capsule' ? loadedModule : createAmphibiousRegistrationExpression(loadedModule)
+
+    return types.switchCase(types.stringLiteral(chunkId), [types.returnStatement(registration)])
+}
+
+/** Creates a registration that loads and publishes an amphibious CommonJS namespace only when executed. */
+function createAmphibiousRegistrationExpression(namespace: types.Expression): ReturnType<typeof types.arrayExpression> {
+    return types.arrayExpression([
+        types.arrayExpression([]),
+        types.arrowFunctionExpression(
+            [types.identifier(exportBindingParameter)],
+            types.objectExpression([
+                types.objectMethod(
+                    'method',
+                    types.identifier('execute'),
+                    [],
+                    types.blockStatement([
+                        types.expressionStatement(
+                            types.callExpression(types.identifier(exportBindingParameter), [namespace])
+                        )
+                    ])
+                )
+            ])
+        )
+    ])
+}
+
+/** Rejects module IDs absent from the closed output graph. */
+function createUnknownModuleCase(moduleId: string): ReturnType<typeof types.switchCase> {
+    return types.switchCase(null, [
+        types.throwStatement(
+            types.newExpression(types.identifier('Error'), [
+                types.binaryExpression('+', types.stringLiteral('Unknown System module: '), types.identifier(moduleId))
+            ])
+        )
+    ])
+}
+
+/** Converts one preliminary output path to a literal require path relative to transport. */
+function toNativeRequirePath(fromFileName: string, toFileName: string): string {
+    const relativePath = path.posix.relative(path.posix.dirname(fromFileName), toFileName)
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`
+}

package/src/node/plugins/wx/resolve/resolver.ts

@@ -0,0 +1,125 @@
+import type { VitePluginTaroOptions, VitePluginTaroPageOption } from '../../../../options.ts'
+import { normalizeModuleId, resolveAppComponentPath, resolvePageComponentPath } from '../../../utils/modules.ts'
+import { createAppConfig } from '../../../utils/project-config.ts'
+import { appComponentId } from '../../client/constant.ts'
+import {
+    appCapsulePath,
+    appShellFileName,
+    appShellPath,
+    bootstrapPath,
+    componentCapsulePath,
+    componentShellFileName,
+    componentShellPath,
+    pageCapsuleId,
+    pageCapsulePath,
+    pageComponentId,
+    pageShellPath,
+    transportPath,
+    vitePreloadId
+} from '../module.ts'
+import { specializeBootstrap } from './specialize-bootstrap.ts'
+import { specializePageCapsule } from './specialize-page-capsule.ts'
+
+/** Resolves one exact plugin-private ID using its importer and configured project root. */
+type PrivateIdResolver = (importer: string | undefined, projectRoot: string) => string
+
+/** Creates the resolver and source specializer for the wx module graph. */
+export function createResolver(options: VitePluginTaroOptions) {
+    const normalizedBootstrapPath = normalizeModuleId(bootstrapPath)
+    const normalizedPageCapsulePath = normalizeModuleId(pageCapsulePath)
+
+    // Provide constant-time route validation and access to each configured Page JSON object.
+    const pageByPath = new Map(options.pages.map((page) => [page.path, page]))
+
+    const privateIdResolvers = new Map<string, PrivateIdResolver>([
+        // Share bootstrap's preload identity through native require and its amphibious SystemJS registration.
+        [vitePreloadId, () => bootstrapPath],
+        // Keep the configured App component behind one stable private import in the App capsule.
+        [appComponentId, (_importer, projectRoot) => resolveAppComponentPath({ appPath: options.app, projectRoot })],
+        [
+            pageComponentId,
+            (importer, projectRoot) => {
+                const page = requireConfiguredPage({ moduleId: importer, pageByPath })
+
+                return resolvePageComponentPath({ pagePath: page.path, projectRoot })
+            }
+        ],
+        [
+            pageCapsuleId,
+            (importer) => {
+                // Query-qualify the capsule source so every Page retains a distinct graph identity.
+                const page = requireConfiguredPage({ moduleId: importer, pageByPath })
+
+                return createRouteModuleId({ moduleId: pageCapsulePath, pagePath: page.path })
+            }
+        ]
+    ])
+
+    return {
+        input: createInput(options.pages),
+
+        resolveId(id: string, importer: string | undefined, projectRoot: string): string | undefined {
+            // Unknown IDs fall through so Vite and other plugins retain normal resolution.
+            return privateIdResolvers.get(id)?.(importer, projectRoot)
+        },
+
+        specialize(code: string, id: string, sourcemap = true) {
+            const normalizedId = normalizeModuleId(id)
+
+            if (normalizedId === normalizedBootstrapPath) {
+                return specializeBootstrap({ code, id, appConfig: createAppConfig(options), sourcemap })
+            }
+
+            if (normalizedId === normalizedPageCapsulePath) {
+                return specializePageCapsule({
+                    code,
+                    id,
+                    page: requireConfiguredPage({ moduleId: id, pageByPath }),
+                    sourcemap
+                })
+            }
+        }
+    }
+}
+
+/** Declares native shells, infrastructure, and capsules as independent output entries. */
+function createInput(pages: readonly VitePluginTaroPageOption[]): Record<string, string> {
+    return Object.fromEntries([
+        ['bootstrap', bootstrapPath],
+        ['transport', transportPath],
+        [appShellFileName, appShellPath],
+        ['app-capsule', appCapsulePath],
+        [componentShellFileName, componentShellPath],
+        ['component-capsule', componentCapsulePath],
+        ...pages.flatMap((page) => {
+            return [
+                [`${page.path}.js`, createRouteModuleId({ moduleId: pageShellPath, pagePath: page.path })],
+                [`${page.path}-capsule`, createRouteModuleId({ moduleId: pageCapsulePath, pagePath: page.path })]
+            ]
+        })
+    ])
+}
+
+/** Creates one route-qualified module ID. */
+function createRouteModuleId({ moduleId, pagePath }: { moduleId: string; pagePath: string }): string {
+    return `${moduleId}?route=${encodeURIComponent(pagePath)}`
+}
+
+/** Returns the configured Page identified by a route-qualified capsule ID. */
+function requireConfiguredPage({
+    moduleId,
+    pageByPath
+}: {
+    moduleId: string | undefined
+    pageByPath: ReadonlyMap<string, VitePluginTaroPageOption>
+}): VitePluginTaroPageOption {
+    const queryIndex = moduleId?.indexOf('?') ?? -1
+    const pagePath = queryIndex === -1 ? undefined : new URLSearchParams(moduleId?.slice(queryIndex + 1)).get('route')
+    const page = pagePath ? pageByPath.get(pagePath) : undefined
+    if (!page) {
+        throw new Error(
+            pagePath ? `Unknown Page capsule: ${pagePath}` : 'Page capsule import must originate from a route module'
+        )
+    }
+    return page
+}

package/src/node/plugins/wx/resolve/specialize-bootstrap.ts

@@ -0,0 +1,27 @@
+import { types } from '@babel/core'
+import type { JsonObject } from '../../../../options.ts'
+import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
+
+const appConfigPlaceholder = '__VITE_PLUGIN_TARO_APP_CONFIG__'
+
+/** Specializes the amphibious bootstrap with the shared App configuration. */
+export function specializeBootstrap({
+    code,
+    id,
+    appConfig,
+    sourcemap = true
+}: {
+    code: string
+    id: string
+    appConfig: JsonObject
+    sourcemap?: boolean
+}): Promise<AstTransformResult> {
+    return replaceWithAst(
+        code,
+        id,
+        {
+            [appConfigPlaceholder]: types.valueToNode(appConfig)
+        },
+        sourcemap
+    )
+}

package/src/node/plugins/wx/resolve/specialize-page-capsule.ts

@@ -0,0 +1,29 @@
+import { types } from '@babel/core'
+import type { VitePluginTaroPageOption } from '../../../../options.ts'
+import { type AstTransformResult, replaceWithAst } from '../../../utils/transform.ts'
+
+const pagePathPlaceholder = '__VITE_PLUGIN_TARO_PAGE_PATH__'
+const pageConfigPlaceholder = '__VITE_PLUGIN_TARO_PAGE_CONFIG__'
+
+/** Specializes the Page capsule for one configured route. */
+export function specializePageCapsule({
+    code,
+    id,
+    page,
+    sourcemap = true
+}: {
+    code: string
+    id: string
+    page: VitePluginTaroPageOption
+    sourcemap?: boolean
+}): Promise<AstTransformResult> {
+    return replaceWithAst(
+        code,
+        id,
+        {
+            [pagePathPlaceholder]: types.stringLiteral(page.path),
+            [pageConfigPlaceholder]: types.valueToNode(page.config)
+        },
+        sourcemap
+    )
+}

package/src/node/utils/constant.ts

@@ -0,0 +1 @@
+export const esTarget = 'es2018'

package/src/node/utils/memoize.ts

@@ -0,0 +1,149 @@
+/**
+ * Creates a memoized version of the provided function. The memoized function caches
+ * results based on the argument it receives, so if the same argument is passed again,
+ * it returns the cached result instead of recomputing it.
+ *
+ * This function works with functions that take zero or just one argument. If your function
+ * originally takes multiple arguments, you should refactor it to take a single object or array
+ * that combines those arguments.
+ *
+ * If the argument is not primitive (e.g., arrays or objects), provide a
+ * `getCacheKey` function to generate a unique cache key for proper caching.
+ *
+ * @template F - The type of the function to be memoized.
+ * @param fn - The function to be memoized. It should accept a single argument and return a value.
+ * @param [options={}] - Optional configuration for the memoization.
+ * @param [options.cache] - The cache object used to store results. Defaults to a new `Map`.
+ * @param [options.getCacheKey] - An optional function to generate a unique cache key for each argument.
+ *
+ * @returns The memoized function with an additional `cache` property that exposes the internal cache.
+ *
+ * @example
+ * // Example using the default cache
+ * const add = (x: number) => x + 10;
+ * const memoizedAdd = memoize(add);
+ *
+ * console.log(memoizedAdd(5)); // 15
+ * console.log(memoizedAdd(5)); // 15 (cached result)
+ * console.log(memoizedAdd.cache.size); // 1
+ *
+ * @example
+ * // Example using a custom resolver
+ * const sum = (arr: number[]) => arr.reduce((x, y) => x + y, 0);
+ * const memoizedSum = memoize(sum, { getCacheKey: (arr: number[]) => arr.join(',') });
+ * console.log(memoizedSum([1, 2])); // 3
+ * console.log(memoizedSum([1, 2])); // 3 (cached result)
+ * console.log(memoizedSum.cache.size); // 1
+ *
+ * @example
+ * // Example using a custom cache implementation
+ * class CustomCache<K, T> implements MemoizeCache<K, T> {
+ *   private cache = new Map<K, T>();
+ *
+ *   set(key: K, value: T): void {
+ *     this.cache.set(key, value);
+ *   }
+ *
+ *   get(key: K): T | undefined {
+ *     return this.cache.get(key);
+ *   }
+ *
+ *   has(key: K): boolean {
+ *     return this.cache.has(key);
+ *   }
+ *
+ *   delete(key: K): boolean {
+ *     return this.cache.delete(key);
+ *   }
+ *
+ *   clear(): void {
+ *     this.cache.clear();
+ *   }
+ *
+ *   get size(): number {
+ *     return this.cache.size;
+ *   }
+ * }
+ * const customCache = new CustomCache<string, number>();
+ * const memoizedSumWithCustomCache = memoize(sum, { cache: customCache });
+ * console.log(memoizedSumWithCustomCache([1, 2])); // 3
+ * console.log(memoizedSumWithCustomCache([1, 2])); // 3 (cached result)
+ * console.log(memoizedSumWithCustomCache.cache.size); // 1
+ */
+export function memoize<F extends (arg: never) => unknown>(
+    fn: F,
+    options: {
+        cache?: MemoizeCache<unknown, ReturnType<F>>
+        getCacheKey?: (arg: Parameters<F>[0]) => unknown
+    } = {}
+): F & { cache: MemoizeCache<unknown, ReturnType<F>> } {
+    const { cache = new Map<unknown, ReturnType<F>>(), getCacheKey } = options
+
+    const memoizedFn = function (this: unknown, arg: Parameters<F>[0]): ReturnType<F> {
+        const key = getCacheKey ? getCacheKey(arg) : arg
+
+        if (cache.has(key)) {
+            return cache.get(key)!
+        }
+
+        const result = fn.call(this, arg) as ReturnType<F>
+
+        cache.set(key, result)
+
+        return result
+    }
+
+    memoizedFn.cache = cache
+
+    return memoizedFn as F & { cache: MemoizeCache<unknown, ReturnType<F>> }
+}
+
+/**
+ * Represents a cache for memoization, allowing storage and retrieval of computed values.
+ *
+ * @template K - The type of keys used to store values in the cache.
+ * @template V - The type of values stored in the cache.
+ */
+export interface MemoizeCache<K, V> {
+    /**
+     * Stores a value in the cache with the specified key.
+     *
+     * @param key - The key to associate with the value.
+     * @param value - The value to store in the cache.
+     */
+    set(key: K, value: V): void
+
+    /**
+     * Retrieves a value from the cache by its key.
+     *
+     * @param key - The key of the value to retrieve.
+     * @returns The value associated with the key, or undefined if the key does not exist.
+     */
+    get(key: K): V | undefined
+
+    /**
+     * Checks if a value exists in the cache for the specified key.
+     *
+     * @param key - The key to check for existence in the cache.
+     * @returns True if the cache contains the key, false otherwise.
+     */
+    has(key: K): boolean
+
+    /**
+     * Deletes a value from the cache by its key.
+     *
+     * @param key - The key of the value to delete.
+     * @returns True if the value was successfully deleted, false otherwise.
+     */
+    delete(key: K): boolean
+
+    /**
+     * Clears all values from the cache.
+     */
+    clear(): void
+
+    /**
+     * The number of entries in the cache.
+     */
+    size: number
+}