importmapify 1.3.1 → 1.4.0

package/README.md

@@ -109,7 +109,7 @@ const out = writeImportMap({
 
 | Export            | Signature                                                  | Purpose                                                                               |
 | ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `defineConfig`    | `(config: Config) => Config`                               | Identity helper that types a config object for export and reuse.                      |
+| `defineConfig`    | `<T extends Config>(config: T) => T`                       | Identity helper that types a config object for export and reuse.                      |
 | `createImportMap` | `(options: CreateImportMapOptions) => ImportMapDocument`   | Build the import map in memory.                                                       |
 | `formatImportMap` | `(map: ImportMapDocument) => string`                       | Serialize to the canonical sorted, tab-indented JSON text.                            |
 | `writeImportMap`  | `(options: WriteImportMapOptions) => string`               | Build, serialize, and write to disk; returns the written path.                        |
@@ -133,11 +133,18 @@ resolved against `root` and accepts a relative path, an absolute path, or a `fil
 automatically against `out`'s directory, so a nested `out` (for example `.cache/maps/import_map.json`) still produces
 targets that resolve correctly from the map's own location.
 
-`Config` is an alias for `WriteImportMapOptions` — the shape a config file's default export and `defineConfig` take.
+`Config` extends `Partial<WriteImportMapOptions>` with an optional `hooks` field — the shape a config file's default
+export and `defineConfig` take, with every field optional. An omitted `root` defaults to the config file's own
+directory; the CLI supplies the remaining defaults.
 
 `defineConfig` returns its argument unchanged; it exists only to type a config object for export and reuse without a
 manual annotation.
 
+`hooks` are lifecycle functions the CLI runs around generation, modeled on tsdown's hooks. `generate:before` runs before
+the filesystem is scanned, so building generated targets there keeps them out of a stale map; `generate:done` runs after
+the map is emitted. Each receives `{ root, out }` (`generate:done` also gets the finished `map`) and may be async. The
+synchronous library functions ignore `hooks`.
+
 ### Recipes
 
 Add dependencies with `packages`. Each entry expands to the bare specifier plus its conformant trailing-slash entry
@@ -184,6 +191,20 @@ const map = createImportMap(config);
 const written = writeImportMap(config);
 ```
 
+Build before scanning with a `generate:before` hook, so a map that includes build output does not drop entries when it
+runs before the build:
+
+```ts
+import { execSync } from 'node:child_process';
+import { defineConfig } from 'importmapify';
+
+export default defineConfig({
+  hooks: {
+    'generate:before': () => execSync('bun run build', { stdio: 'inherit' }),
+  },
+});
+```
+
 `root`, `relativeTo`, and `out` accept a path or a `file://` URL, so `import.meta.url` needs no `.pathname`:
 
 ```ts

package/deno.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://raw.githubusercontent.com/denoland/deno/refs/heads/main/cli/schemas/config-file.v1.json",
 	"name": "@kjanat/importmapify",
-	"version": "1.3.1",
+	"version": "1.4.0",
 	"exports": "./src/mod.ts",
 	"publish": {
 		"include": [

package/dist/mod.d.mts

@@ -33,8 +33,35 @@ interface WriteImportMapOptions extends CreateImportMapOptions {
    */
   readonly out?: string | URL;
 }
-/** An importmapify config: the shape a config file's default export and {@linkcode defineConfig} take. */
-type Config = WriteImportMapOptions;
+/** Resolved paths shared by every generation hook. */
+interface HookContext {
+  /** Absolute project root that gets scanned. */
+  readonly root: string;
+  /** Absolute output path the map resolves against. */
+  readonly out: string;
+}
+/**
+ * Lifecycle hooks the CLI runs around import map generation, modeled on tsdown's hooks.
+ *
+ * Each hook may be async; the CLI awaits it. The synchronous library functions ignore hooks.
+ */
+interface ImportMapHooks {
+  /** Runs before the filesystem is scanned. Build pattern targets here so they exist when patterns expand. */
+  readonly "generate:before": (context: HookContext) => void | Promise<void>;
+  /** Runs after the map is generated and emitted. */
+  readonly "generate:done": (context: HookContext & {
+    readonly map: ImportMapDocument;
+  }) => void | Promise<void>;
+}
+/**
+ * An importmapify config file: the shape a config file's default export and {@linkcode defineConfig} take.
+ * Every field is optional; the config loader and CLI supply {@linkcode CreateImportMapOptions.root | root}
+ * and the remaining defaults.
+ */
+interface Config extends Partial<WriteImportMapOptions> {
+  /** Lifecycle hooks the CLI runs around generation. Ignored by {@link writeImportMap} and {@link createImportMap}. */
+  readonly hooks?: Partial<ImportMapHooks>;
+}
 /**
  * Expand a package's exact and patterned `imports` into a Deno import map.
  *
@@ -131,9 +158,10 @@ declare function packageEntries(name: string, target: string): Record<string, st
  * writeImportMap(config);
  * ```
  *
- * @param config Import map configuration, with an optional `out`.
- * @returns The same `config` value, typed as {@link Config}.
+ * @param config Import map configuration; every field is optional.
+ * @returns The same `config` value with its exact type preserved, so a config that includes `root` stays
+ * assignable to {@link writeImportMap} while one that omits it is still a valid config file.
  */
-declare function defineConfig(config: Config): Config;
+declare function defineConfig<T extends Config>(config: T): T;
 //#endregion
-export { type Config, type CreateImportMapOptions, type ImportMapDocument, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };
+export { type Config, type CreateImportMapOptions, type HookContext, type ImportMapDocument, type ImportMapHooks, type WriteImportMapOptions, createImportMap, defineConfig, formatImportMap, packageEntries, writeImportMap };

package/dist/mod.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { bold, cyan, detectHyperlinkSupport } from "ansispeck";
 import { CLIError, cli, command, flag } from "dreamcli";
-import fs, { existsSync, readFileSync } from "node:fs";
-import path, { dirname } from "node:path";
+import fs, { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path, { dirname, resolve } from "node:path";
 import { argv, cwd } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/expand.ts
@@ -191,20 +191,34 @@ function asScopes(value) {
 	}
 	return scopes;
 }
+function isHook(value) {
+	return typeof value === "function";
+}
+function asHooks(value) {
+	if (!isRecord(value)) return;
+	const hooks = {};
+	const before = value["generate:before"];
+	if (isHook(before)) hooks["generate:before"] = before;
+	const done = value["generate:done"];
+	if (isHook(done)) hooks["generate:done"] = done;
+	return hooks["generate:before"] === void 0 && hooks["generate:done"] === void 0 ? void 0 : hooks;
+}
 /**
 * Parse a raw config object into typed import map options.
 *
-* Only known fields are read; a relative string `root` is resolved against the config
-* file's own directory so a config can anchor itself with `root: '.'`.
+* Only known fields are read. An omitted `root` defaults to the config file's own directory; a relative
+* string `root` resolves against it, so a config can anchor itself with `root: '.'`.
 *
 * @param config Raw default-exported config object.
 * @param configDir Directory containing the config file.
-* @returns The subset of {@link WriteImportMapOptions} the config declares.
+* @returns The subset of {@link WriteImportMapOptions} the config declares, plus any hooks.
 */
 function configToOptions(config, configDir) {
 	const result = {};
 	const root = asPath(config.root);
-	if (root !== void 0) result.root = typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://") ? path.resolve(configDir, root) : root;
+	if (root === void 0) result.root = configDir;
+	else if (typeof root === "string" && !path.isAbsolute(root) && !root.startsWith("file://")) result.root = path.resolve(configDir, root);
+	else result.root = root;
 	const manifest = asString(config.manifest);
 	if (manifest !== void 0) result.manifest = manifest;
 	const out = asPath(config.out);
@@ -221,6 +235,8 @@ function configToOptions(config, configDir) {
 	if (additionalImports !== void 0) result.additionalImports = additionalImports;
 	const scopes = asScopes(config.scopes);
 	if (scopes !== void 0) result.scopes = scopes;
+	const hooks = asHooks(config.hooks);
+	if (hooks !== void 0) result.hooks = hooks;
 	return result;
 }
 /**
@@ -471,8 +487,9 @@ function packageEntries(name, target) {
 * writeImportMap(config);
 * ```
 *
-* @param config Import map configuration, with an optional `out`.
-* @returns The same `config` value, typed as {@link Config}.
+* @param config Import map configuration; every field is optional.
+* @returns The same `config` value with its exact type preserved, so a config that includes `root` stays
+* assignable to {@link writeImportMap} while one that omits it is still a valid config file.
 */
 function defineConfig(config) {
 	return config;
@@ -574,6 +591,7 @@ async function resolveGenerateOptions(flags) {
 	if (base.relativeTo !== void 0) options.relativeTo = base.relativeTo;
 	if (conditions !== void 0) options.conditions = conditions;
 	if (extensions !== void 0) options.extensions = extensions;
+	if (base.hooks !== void 0) options.hooks = base.hooks;
 	return options;
 }
 /** DreamCLI command that writes, checks, or prints an expanded Deno import map. */
@@ -593,22 +611,28 @@ const generateCommand = command("generate").description("Expand package.json sub
 		...options,
 		relativeTo: options.relativeTo ?? dirname(outPath)
 	};
-	if (stdout) {
-		log(formatImportMap(createImportMap(createOptions)));
-		return;
-	}
-	if (check) {
-		const expected = formatImportMap(createImportMap(createOptions));
-		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== expected) {
+	const hookContext = {
+		root: resolve(toPath(options.root)),
+		out: outPath
+	};
+	await options.hooks?.["generate:before"]?.(hookContext);
+	const map = createImportMap(createOptions);
+	const text = formatImportMap(map);
+	if (stdout) log(text);
+	else if (check) {
+		if ((existsSync(outPath) ? readFileSync(outPath, "utf8") : void 0) !== text) {
 			error(`${outPath} is stale`);
 			setExitCode(1);
-			return;
-		}
-		if (!quiet) warn(`${outPath} is up to date`);
-		return;
+		} else if (!quiet) warn(`${outPath} is up to date`);
+	} else {
+		mkdirSync(dirname(outPath), { recursive: true });
+		writeFileSync(outPath, text);
+		if (!quiet) warn(`Wrote ${outPath}`);
 	}
-	const written = writeImportMap(options);
-	if (!quiet) warn(`Wrote ${written}`);
+	await options.hooks?.["generate:done"]?.({
+		...hookContext,
+		map
+	});
 });
 //#endregion
 //#region src/mod.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "importmapify",
-	"version": "1.3.1",
+	"version": "1.4.0",
 	"description": "Expand package.json subpath-pattern imports into explicit Deno import map entries.",
 	"keywords": [
 		"deno",