@bytecodealliance/jco/src/cmd/types.js

JavaScript tooling for working with WebAssembly Components

import { stat, mkdir } from 'node:fs/promises';
import { extname, basename, resolve } from 'node:path';

import {
    $init,
    generateTypes,
} from '../../obj/js-component-bindgen-component.js';

import {
    isWindows,
    writeFiles,
    resolveDefaultWITPath,
    styleText,
    ASYNC_WASI_IMPORTS,
    ASYNC_WASI_EXPORTS,
    DEFAULT_ASYNC_MODE,
} from '../common.js';

/** Default relative path for guest type declaration generation */
const DEFAULT_GUEST_TYPES_OUTPUT_DIR_PATH = './types/generated/wit/guest';

/** Default relative path for host type declaration generation */
const DEFAULT_HOST_TYPES_OUTPUT_DIR_PATH = './types/generated/wit/host';

export async function types(witPath, opts) {
    witPath = await resolveDefaultWITPath(witPath);

    // Use the default output directory if one was not provided
    if (!opts.outDir) {
        await mkdir(DEFAULT_HOST_TYPES_OUTPUT_DIR_PATH, { recursive: true });
        opts.outDir = resolve(DEFAULT_HOST_TYPES_OUTPUT_DIR_PATH);
        console.error(
            `no output directory specified for host type declarations, using [${DEFAULT_HOST_TYPES_OUTPUT_DIR_PATH}]`
        );
    }

    const files = await typesComponent(witPath, opts);

    await writeFiles(files, opts.quiet ? false : 'Generated Type Files');
}

export async function guestTypes(witPath, opts) {
    witPath = await resolveDefaultWITPath(witPath);

    // Use the default output directory if one was not provided
    if (!opts.outDir) {
        await mkdir(DEFAULT_GUEST_TYPES_OUTPUT_DIR_PATH, { recursive: true });
        opts.outDir = resolve(DEFAULT_GUEST_TYPES_OUTPUT_DIR_PATH);
        console.error(
            `no output directory specified for guest type declarations, using [${DEFAULT_GUEST_TYPES_OUTPUT_DIR_PATH}]`
        );
    }

    const files = await typesComponent(witPath, { ...opts, guest: true });
    await writeFiles(
        files,
        opts.quiet
            ? false
            : 'Generated Guest Typescript Definition Files (.d.ts)'
    );
}

/**
 * @param {string} witPath
 * @param {{
 *   name?: string,
 *   worldName?: string,
 *   instantiation?: 'async' | 'sync',
 *   tlaCompat?: bool,
 *   asyncMode?: string,
 *   asyncImports?: string[],
 *   asyncExports?: string[],
 *   outDir?: string,
 *   allFeatures?: bool,
 *   feature?: string[] | 'all', // backwards compat
 *   features?: string[] | 'all',
 *   asyncWasiImports?: string[],
 *   asyncWasiExports?: string[],
 *   asyncExports?: string[],
 *   asyncImports?: string[],
 *   guest?: bool,
 * }} opts
 * @returns {Promise<{ [filename: string]: Uint8Array }>}
 */
export async function typesComponent(witPath, opts) {
    await $init;
    const name =
        opts.name ||
        (opts.worldName
            ? opts.worldName.split(':').pop().split('/').pop()
            : basename(witPath.slice(0, -extname(witPath).length || Infinity)));
    let instantiation;
    if (opts.instantiation) {
        instantiation = { tag: opts.instantiation };
    }
    let outDir = (opts.outDir ?? '').replace(/\\/g, '/');
    if (!outDir.endsWith('/') && outDir !== '') {
        outDir += '/';
    }

    // Bulid list of enabled features
    let features = null;
    if (opts.allFeatures) {
        features = { tag: 'all' };
    } else if (Array.isArray(opts.feature)) {
        features = { tag: 'list', val: opts.feature };
    } else if (Array.isArray(opts.features)) {
        features = { tag: 'list', val: opts.features };
    }

    // Build list of async imports/exports
    let asyncImports = new Set([...(opts.asyncImports ?? [])]);
    if (opts.asyncWasiImports) {
        ASYNC_WASI_IMPORTS.forEach((v) => asyncImports.add(v));
    }
    let asyncExports = new Set([...(opts.asyncExports ?? [])]);
    if (opts.asyncWasiExports) {
        ASYNC_WASI_EXPORTS.forEach((v) => asyncExports.add(v));
    }

    // For simple type generation, we choose the "async mode" for the user
    // even though it is not relevant here (JSPI may not be used, as types may
    // be used to generate a guest that is never transpiled).
    let asyncMode = opts.asyncMode ?? DEFAULT_ASYNC_MODE;
    let asyncModeObj;
    if (asyncMode === 'jspi' || asyncExports.size > 0) {
        asyncModeObj = {
            tag: 'jspi',
            val: {
                imports: [...asyncImports],
                exports: [...asyncExports],
            },
        };
    } else if (asyncMode === 'sync') {
        asyncModeObj = null;
    } else {
        throw new Error(`invalid/unrecognized async mode [${asyncMode}]`);
    }

    // Run the type generation
    let types;
    const absWitPath = resolve(witPath);
    try {
        types = generateTypes(name, {
            wit: { tag: 'path', val: (isWindows ? '//?/' : '') + absWitPath },
            instantiation,
            tlaCompat: opts.tlaCompat ?? false,
            world: opts.worldName,
            features,
            guest: opts.guest ?? false,
            asyncMode: asyncModeObj,
        }).map(([name, file]) => [`${outDir}${name}`, file]);
    } catch (err) {
        if (err.toString().includes('does not match previous package name')) {
            const hint = await printWITLayoutHint(absWitPath);
            if (err.message) {
                err.message += `\n${hint}`;
            }
            throw err;
        }
        throw err;
    }

    return Object.fromEntries(types);
}

/**
 * Print a hint about WIT folder layout
 *
 * @param {(string, any) => void} consoleFn
 */
async function printWITLayoutHint(witPath) {
    const warningPrefix = styleText(['yellow', 'bold'], 'warning');
    const pathMeta = await stat(witPath);
    let output = '\n';
    if (!pathMeta.isFile() && !pathMeta.isDirectory()) {
        output += `${warningPrefix} The supplited WIT path [${witPath}] is neither a file or directory.\n`;
        return output;
    }
    const ftype = pathMeta.isDirectory() ? 'directory' : 'file';
    output += `${warningPrefix} Your WIT ${ftype} [${witPath}] may be laid out incorrectly\n`;
    output += `${warningPrefix} Keep in mind the following rules:\n`;
    output += `${warningPrefix}     - Top level WIT files are in the same package (i.e. "ns:pkg" in "wit/*.wit")\n`;
    output += `${warningPrefix}     - All package dependencies should be in "wit/deps" (i.e. "some:dep" in "wit/deps/some-dep.wit"\n`;
    return output;
}

// see: https://github.com/vitest-dev/vitest/issues/6953#issuecomment-2505310022
if (typeof __vite_ssr_import_meta__ !== 'undefined') {
    __vite_ssr_import_meta__.resolve = (path) =>
        'file://' + globalCreateRequire(import.meta.url).resolve(path);
}