@ayonli/jsext/types/module.d.ts

A JavaScript extension package for building strong and modern applications.

/**
 * Utility functions for working with JavaScript modules.
 * @module
 */
/// <reference types="node" />
import { getObjectURL } from "./module/util.ts";
/**
 * @deprecated There was some misunderstanding of this function in the past, it
 * should not be used in the user space anymore.
 */
declare const _getObjectURL: typeof getObjectURL;
export { _getObjectURL as getObjectURL };
/**
 * Performs interop on the given module. This functions is used to fix CommonJS
 * module imports in Node.js ES module files.
 *
 * By default, this function will check the module object for characteristics of
 * CommonJS modules and perform interoperability smartly.
 *
 * But sometimes, this behavior is not guaranteed, for example, when the `module`
 * is an ES module and it does have a default export as an object, or the
 * `module.exports` is the only export in the CommonJS file. In this case,
 * this function will be confused and may return an undesired object.
 *
 * To fix this, you can set the `strict` parameter to `true`, so this function
 * will only return the `exports` object when the module also has an `__esModule`
 * property, which is a common pattern generated by TypeScript for CommonJS
 * files.
 *
 * Or you can set the `strict` parameter to `false`, so this function will
 * always return the `default` object if it exists in `module`, which is the
 * target that Node.js uses to alias the `module.exports` object for CommonJS
 * modules.
 *
 * @example
 * ```ts
 * import { interop } from "@ayonli/jsext/module";
 *
 * const { decode } = await interop(() => import("iconv-lite"), false);
 * ```
 */
export declare function interop<T extends {
    [x: string]: any;
}>(module: () => Promise<T>, strict?: boolean): Promise<T>;
/**
 * @example
 * ```ts
 * import { interop } from "@ayonli/jsext/module";
 *
 * const { decode } = await interop(import("iconv-lite"), false);
 * ```
 */
export declare function interop<T extends {
    [x: string]: any;
}>(module: Promise<T>, strict?: boolean): Promise<T>;
/**
 * @example
 * ```ts
 * import { interop } from "@ayonli/jsext/module";
 *
 * const { decode } = interop(await import("iconv-lite"), false);
 * ```
 */
export declare function interop<T extends {
    [x: string]: any;
}>(module: T, strict?: boolean): T;
/**
 * Checks if the current file is the entry of the program.
 *
 * @example
 * ```ts
 * import { isMain } from "@ayonli/jsext/module";
 *
 * if (isMain(import.meta)) {
 *     console.log("This is the main module.");
 * }
 * ```
 */
export declare function isMain(importMeta: ImportMeta): boolean;
/**
 * @example
 * ```ts
 * // CommonJS
 * const { isMain } = require("@ayonli/jsext/module");
 *
 * if (isMain(module)) {
 *     console.log("This is the main module.");
 * }
 * ```
 */
export declare function isMain(module: NodeJS.Module): boolean;
/**
 * Imports a script from the given URL to the current document, useful for
 * loading 3rd-party libraries dynamically in the browser.
 *
 * NOTE: This function is only available in the browser.
 *
 * @example
 * ```ts
 * import { importScript } from "@ayonli/jsext/module";
 *
 * await importScript("https://code.jquery.com/jquery-3.7.1.min.js");
 *
 * console.assert(typeof jQuery === "function");
 * console.assert($ === jQuery);
 * ```
 */
export declare function importScript(url: string, options?: {
    type?: "classic" | "module";
}): Promise<void>;
/**
 * Imports a stylesheet from the given URL to the current document, useful for
 * loading 3rd-party libraries dynamically in the browser.
 *
 * NOTE: This function is only available in the browser.
 *
 * @example
 * ```ts
 * import { importStylesheet } from "@ayonli/jsext/module";
 *
 * await importStylesheet("https://cdn.jsdelivr.net/npm/bootstrap@3.4.1/dist/css/bootstrap.min.css");
 * ```
 */
export declare function importStylesheet(url: string): Promise<void>;