@m2c2kit/build-helpers 0.3.12 → 0.3.14

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { InputOptions } from 'rollup';
+import { Plugin } from 'rollup';
+import { PackageJSON, AsyncOpts } from 'resolve';
 
 /**
  * rollup plugin to hash m2c2kit assets and enable cache busting.
@@ -6,52 +7,223 @@ import { InputOptions } from 'rollup';
  * @remarks On repeated deployments, a file with the same name may be
  * cached by browsers. Thus, the old file will be used, not the updated
  * one. To enable cache busting, this rollup plugin adds hashes to filenames
- * for m2c2kit assets: index.js, canvaskit.wasm, images, and fonts. This is
- * done by: 1) parsing index.html and finding the links to css and index.js,
- * calculating a hash of these assets, adding a hash to the asset filenames,
- * and updating the links in index.html to reflect the hash. 2) parsing
- * index.js into an AST, finding string literals that are the urls of fonts,
- * images, and canvaskit.wam, calculating a hash of these assets, adding a
- * hash to the asset filenames, and updating the urls to reflect the hash.
- *
- * Note: index.js is transpiled from TypeScript and no longer has types, so
- * finding the asset urls in the AST assumes that there will be no
- * user code with the same structure as the asset urls. In other words:
- * Don't use a define a property named "canvasKitWasmUrl" that refers to
- * a string literal, don't define a property named "fonts" that that refers
- * to an array expression of object expressions with properties named
- * "fontName" and "url", and don't define a property called "images" that
- * refers to an array expression of object expressions with properties named
- * "imageName", "height", "width", and "url". Otherwise, this plugin may alter
- * your code in unexpected ways (although most likely it will simply give
- * warnings, because it's unlikely there will be valid file assets that will
- * be found and hashed).
+ * for files except .html and .htm files, and javascript files that are not
+ * index.js (index.js is the main entry point bundle file we have created
+ * and is referenced in index.html).
+ *
+ * In the renderChunk plugin hook, this is done by:
+ * 1) Replacing the string __NO_M2C2KIT_MANIFEST_JSON_URL__ with manifest.json
+ * in the bundled index.js file. This is done so that the game knows it must
+ * look up hashed filenames.
+ *
+ * In the writeBundle plugin hook, this is done by:
+ * 1) Creating an MD5 hash of the file contents of each file and adding the
+ * hash of the first 16 digits to the filename.
+ *
+ * 2) Creating a manifest.json file that maps the original filename to the
+ * hashed filename. This manifest will be used by the game to look up and
+ * load the hashed filenames.
+ *
+ * 3) Parsing index.html to find the links to css and index.js files and
+ * updating the links with the hashed filenames.
  *
  * @param rootDir - root directory of build, usually "dist" because you
  * usually hash only production builds
  * @param cwd - current working directory; used only for testing.
- * @returns
+ * @returns a rollup Plugin
  */
-declare function hashM2c2kitAssets(rootDir: string, cwd?: string): {
-    name: string;
-    closeBundle: {
-        sequential: boolean;
-        handler(): Promise<void>;
-    };
-};
+declare function hashM2c2kitAssets(rootDir: string, cwd?: string): Plugin;
+
+declare function makeM2c2kitServiceWorker(rootDir: string, additionalFiles?: Array<string>): Plugin;
+
+/**
+ * Restores `import.meta` to the code after the bundler has removed it.
+ *
+ * @remarks esbuild removes usage of `import.meta` (by substituting an empty
+ * object named `import_meta`) if it is not supported in the target environment.
+ * However, we will polyfill it in the browser, so we need to restore it.
+ * If not using esbuild, this plugin is not needed.
+ *
+ * @param pattern - the string to replace. Defaults to `import_meta = {};`
+ * @param replacement - the string to replace with. Defaults to `import_meta = import.meta;`
+ */
+declare function restoreImportMeta(pattern?: string, replacement?: string): Plugin;
 
-declare function makeM2c2kitServiceWorker(rootDir: string, additionalFiles?: Array<string>): {
+interface PackageAndExtras {
+    /** Package name */
     name: string;
-    buildStart: {
-        handler(options: InputOptions): void;
-    };
-    transform: {
-        handler(code: string, id: any): string;
-    };
-    closeBundle: {
-        sequential: boolean;
-        handler(): Promise<void>;
-    };
-};
-
-export { hashM2c2kitAssets, makeM2c2kitServiceWorker };
+    /** Extra files to copy from package */
+    extras?: Array<ExtraFile>;
+}
+/**
+ * Extra file to copy from package.
+ */
+interface ExtraFile {
+    /** Source path, within the package folder structure, of extra file to copy. @remarks IMPORTANT: Add a wildcard * to the end of the source (`index.html*`), otherwise it will be interpreted as a folder. */
+    source: string;
+    /** Destination path, within the build output folder structure, of extra file to copy. Use the empty string (`""`) for the destination root. */
+    dest: string;
+}
+interface CopyAssetsOptions {
+    /**
+     * For assets in an external m2c2kit package, the name of the m2c2kit package
+     * or array of names of m2c2kit packages that need assets copied, e.g.,
+     * `@m2c2kit/assessment-symbol-search` or
+     * `["@m2c2kit/assessment-symbol-search", "@m2c2kit/survey"]`, or a
+     * `PackageAndExtras` object, e.g.,
+     * `{name: "@m2c2kit/survey", extras: [{ source: "assets/index.html*", dest: "" }]}`
+     */
+    package?: string | PackageAndExtras | Array<string | PackageAndExtras>;
+    /**
+     * For assets within this package, the _id_ or _ids_ of the
+     * assessment(s) to copy assets for. If the assessment is not within this
+     * package, then the assessment _package name_ should be provided in the
+     * `package` option.
+     */
+    id?: string | Array<string>;
+    /**
+     * Output folder, e.g. `dist` or `build`.
+     */
+    outputFolder: string;
+    /**
+     * Whether to log verbose output. Useful for debugging when assets can not
+     * be found. Default is false.
+     */
+    verbose?: boolean;
+}
+/**
+ * Copies m2c2kit assets to the bundle output folder.
+ *
+ * @remarks Assets such as images, fonts, CSS, and WebAssembly files are
+ * needed by assessments. This plugin copies those assets from their
+ * respective packages to the output folder.
+ *
+ * Packages and ids are assumed to be assessments (see exception below), and
+ * their assets folders **and** the wasm file from the required version of
+ * `@m2c2kit/core` are copied.
+ *
+ * At the end of the copy process, the `index.html` file from the `src` folder
+ * is copied to the output folder. This `index.html` file will have been
+ * created by the CLI or the user.
+ *
+ * A typical use case: Here, there is a new assessment with the id
+ * `my-new-assessment` being developed in this package. In addition, two
+ * existing assessments, `@m2c2kit/assessment-symbol-search` and
+ * `@m2c2kit/assessment-grid-memory`, are being used.
+ *
+ * @example
+ * ```
+ * copyAssets({
+ *   id: "my-new-assessment",
+ *   package: [
+ *     "@m2c2kit/assessment-symbol-search",
+ *     "@m2c2kit/assessment-grid-memory"
+ *   ],
+ *  outputFolder: "dist",
+ * })
+ * ```
+ *
+ * Exception: if the `package` option is specified and it includes
+ * `@m2c2kit/db`, `@m2c2kit/survey`, or `@m2c2kit/session`, then the following
+ * assets are copied:
+ * - `@m2c2kit/db`: `data.js` and `data.html`
+ * - `@m2c2kit/survey`: assets css folder contents
+ * - `@m2c2kit/session`: assets folder contents, except `index.html`
+ *
+ * A typical use case: Here, in addition to assessments, a survey will be
+ * administered, and thus survey CSS assets are needed.
+ *
+ * @example
+ * ```
+ * copyAssets({
+ *   id: "my-new-assessment",
+ *   package: [
+ *     "@m2c2kit/assessment-symbol-search",
+ *     "@m2c2kit/assessment-grid-memory",
+ *     "@m2c2kit/survey"
+ *   ],
+ *  outputFolder: "dist",
+ * })
+ * ```
+ *
+ * If the `index.html` from `@m2c2kit/session` or `@m2c2kit/survey` is needed, it
+ * can be added as an extra file to copy, but this will be done only in special
+ * cases, such as when creating library demos within this repository.
+ *
+ * This is a very atypical, unusual use case: Here, the `index.html` file from
+ * `@m2c2kit/survey` is copied to the output folder on every build.
+ *
+ * @example
+ * ```
+ * copyAssets({
+ *   package: [
+ *     "@m2c2kit/assessment-symbol-search",
+ *     {
+ *       name: "@m2c2kit/survey",
+ *       extras: [{
+ *         source: "assets/index.html*",
+ *         dest: "",
+ *       }]
+ *     }
+ *   ],
+ *  outputFolder: "dist",
+ * })
+ * ```
+ *
+ * Usually, the `index.html` **should not** be copied from `@m2c2kit/session` or
+ * `@m2c2kit/survey` on every build with the `extras` option because the
+ * `index.html` file in the `src` folder should be used. Thus, the `extras`
+ * option is only for special cases, such as when creating library demos within
+ * this repository (see `@m2c2kit/assessments-demo`).
+ *
+ * @param options - {@link CopyAssetsOptions}
+ * @returns the copyAssets rollup plugin
+ */
+declare function copyAssets(options: CopyAssetsOptions): Plugin;
+
+/**
+ * Adds module metadata to the assessment code.
+ *
+ * @remarks Use this plugin when creating an assessment that will be used
+ * as a module and imported into other projects. This plugin reads metadata
+ * from `package.json` and embeds it in the assessment code.
+ *
+ * This module metadata is important so that the m2c2kit library can locate
+ * assessment resources that are not bundled. The module metadata contains the
+ * assessment name, version, and m2c2kit dependencies.
+ *
+ * To use: add `moduleMetadata: Constants.MODULE_METADATA_PLACEHOLDER` to the
+ * `GameOptions` object. At build time, this plugin will replace this
+ * placeholder with the actual assessment metadata.
+ */
+declare function addModuleMetadata(): Plugin;
+
+/**
+ * Replaces the string `__PACKAGE_JSON_VERSION__` with version information.
+ *
+ * @remarks This plugin gets the version string from the `package.json` file
+ * and the short commit hash from git. It finds the string
+ * `__PACKAGE_JSON_VERSION__` and replaces it with the version string and the
+ * short commit hash in the form of `version (shortCommitHash)`.
+ */
+declare const insertVersionString: () => Plugin;
+
+interface ResolveAsyncResult {
+    /** Absolute path to resolved package */
+    path: string;
+    /** package.json of resolved package */
+    package: PackageJSON;
+}
+/**
+ * Resolves a package asynchronously.
+ *
+ * @remarks This is a wrapper around https://www.npmjs.com/package/resolve
+ * that returns a promise, rather than using the callback style.
+ *
+ * @param id - Identifier to resolve
+ * @param options - Options to use for resolving, optional.
+ * @returns Promise of {@link ResolveAsyncResult}
+ */
+declare function resolveAsync(id: string, options: AsyncOpts): Promise<ResolveAsyncResult>;
+
+export { type CopyAssetsOptions, type ResolveAsyncResult, addModuleMetadata, copyAssets, hashM2c2kitAssets, insertVersionString, makeM2c2kitServiceWorker, resolveAsync, restoreImportMeta };