Utility Functions

/**
 * Download an NPM package and execute a processing function in its directory
 * @param pkg - NPM package specifier (e.g., "package@version")
 * @param block - Function to execute in the package directory
 * @returns Promise resolving to download result with success/failure status
 */
function downloadNpmPackage<T>(
  pkg: string,
  block: (dir: string) => Promise<T>
): Promise<NpmDownloadResult<T>>;

import { downloadNpmPackage } from "jsii-diff/lib/util";
import * as reflect from "jsii-reflect";

// Download and load a package for analysis
const result = await downloadNpmPackage("my-package@1.0.0", async (pkgDir) => {
  const ts = new reflect.TypeSystem();
  return ts.loadModule(pkgDir);
});

if (result.success) {
  const assembly = result.result;
  console.log(`Loaded assembly: ${assembly.name}@${assembly.version}`);
} else {
  console.error(`Download failed: ${showDownloadFailure(result.reason)}`);
}

/**
 * Convert download failure code to human-readable message
 * @param f - Download failure code
 * @returns Human-readable error message or undefined for unknown failures
 */
function showDownloadFailure(f: DownloadFailure): string | undefined;

/**
 * Execute a block of code in a temporary directory with automatic cleanup
 * @param block - Function to execute in temporary directory
 * @returns Promise resolving to block return value
 */
function inTempDir<T>(block: () => T | Promise<T>): Promise<T>;

import { inTempDir } from "jsii-diff/lib/util";
import * as fs from "fs-extra";

// Perform work in isolated temporary directory
const result = await inTempDir(async () => {
  // Current working directory is now a temp dir
  await fs.writeFile("test.txt", "temporary data");
  const content = await fs.readFile("test.txt", "utf8");
  return content;
}); // Temp directory is automatically cleaned up

console.log(result); // "temporary data"

/**
 * Map each element to an array and flatten the results
 * @param xs - Input array
 * @param fn - Function that maps elements to arrays
 * @returns Flattened array of all mapped results
 */
function flatMap<T, U>(xs: T[], fn: (x: T) => U[]): U[];

import { flatMap } from "jsii-diff/lib/util";

// Split strings and flatten results
const words = flatMap(["hello world", "foo bar"], (str) => str.split(" "));
console.log(words); // ["hello", "world", "foo", "bar"]

// Extract nested properties
const data = [
  { items: [1, 2] },
  { items: [3, 4, 5] }
];
const allItems = flatMap(data, (obj) => obj.items);
console.log(allItems); // [1, 2, 3, 4, 5]

/**
 * Utility class to prevent infinite recursion by tracking visited elements
 */
class RecursionBreaker<A> {
  /**
   * Execute block only if key hasn't been seen before in current call stack
   * @param key - Unique identifier for the operation
   * @param block - Function to execute if not already in progress
   */
  do(key: A, block: () => void): void;
}

import { RecursionBreaker } from "jsii-diff/lib/util";

// Prevent infinite recursion when processing circular references
const breaker = new RecursionBreaker<string>();

function processType(type: any): void {
  breaker.do(type.name, () => {
    // Process type properties
    for (const prop of type.properties) {
      if (prop.type) {
        processType(prop.type); // Won't infinitely recurse
      }
    }
  });
}

/**
 * Possible failure reasons for NPM package downloads
 */
type DownloadFailure = 'no_such_package';

/**
 * Result type for NPM package download operations
 */
type NpmDownloadResult<T> =
  | { success: true; result: T }
  | { success: false; reason: DownloadFailure };

/**
 * Options for loading assemblies from the filesystem
 */
interface LoadOptions {
  /** Whether to validate assembly format during loading */
  validate: boolean;
}