@ts-for-gir/lib/src/types/options-generation.ts

Typescript .d.ts generator from GIR for gjs

import type { OptionsBase } from "./index.ts";

/**
 * Type for currently used config e.g. in GirModule
 */
export interface OptionsGeneration extends OptionsBase {
	/** root / working directory of your project */
	root: string;
	/** directory to output to */
	outdir: string | null;
	/** GIR directories */
	girDirectories: string[];
	/** Do not export all symbols for each module as a namespace */
	noNamespace: boolean;
	/** Do not generate documentation comments */
	noComments: boolean;
	/** Generate promisified functions for async/finish calls */
	promisify: boolean;
	/**
	 * Scope of the generated NPM packages
	 * @see https://docs.npmjs.com/cli/v7/using-npm/scope
	 */
	npmScope: string;
	/** Uses the workspace protocol for the generated packages which can be used with package managers like Yarn and PNPM */
	workspace: boolean;
	/** Format used for dependency version specifiers in generated package.json files */
	depVersionFormat?: "workspace" | "caret" | "any" | "exact";
	/** Disable GLib.Variant class with string parsing */
	noAdvancedVariants: boolean;
	/**
	 * Only use the version prefix for the ambient module exports.
	 * This is useful if, for whatever reason, you want to use different library versions of the same library in your project.
	 *
	 * @example
	 * ```ts
	 * declare module 'gi://Gtk?version=4.0' {...}
	 * declare module 'gi://Gtk?version=3.0' {...}
	 * ```
	 */
	onlyVersionPrefix: boolean;
	/** Disable pretty printing the output */
	noPrettyPrint: boolean;
	/**
	 * Generate the typescript types with package.json support
	 */
	package: boolean;
	/**
	 * Enable generation problem reporter and create a detailed report file
	 */
	reporter: boolean;
	/**
	 * Output file path for the reporter
	 */
	reporterOutput: string;
	/** Generate a single unified documentation for all modules instead of separate per-module docs */
	combined?: boolean;
	/** URL template for source links in generated documentation. Supports {path}, {line}, {gitRevision} placeholders */
	sourceLinkTemplate?: string;
	/** Theme for HTML documentation generation (default: "gi-docgen") */
	theme?: string;
	/** Path to a README file to use as the documentation index page (default: "none") */
	readme?: string;
	/** Use TypeDoc merge mode to generate HTML from pre-generated JSON files */
	merge?: boolean;
	/** Directory containing pre-generated TypeDoc JSON files for merge mode (from 'ts-for-gir json') */
	jsonDir?: string;
	/**
	 * External-deps mode: emit `import` statements that reference dependency types from
	 * already-installed npm packages (e.g. `@girs/glib-2.0`) instead of regenerating them.
	 * Designed for project-local GIRs (Vala bridges etc.) where the surrounding `@girs/*`
	 * ecosystem is already in node_modules. No GJS supporting files, no index aggregator.
	 */
	externalDeps: boolean;
	/**
	 * In `externalDeps` mode, allow generation to proceed even when some transitive dep GIRs
	 * cannot be found. Default is strict: missing deps abort the run, since divergent dep
	 * availability between environments (dev with -devel packages vs CI without) would
	 * silently produce inconsistent generated `.d.ts` output.
	 */
	allowMissingDeps: boolean;
	/**
	 * Override the default `<npmScope>/<importName>` mapping for individual namespaces when
	 * resolving external dependency imports in `externalDeps` mode.
	 *
	 * Example: `{ Soup: '@girs/soup-3.0', GLib: '@girs/glib-2.0' }`
	 */
	externalPackages?: Record<string, string>;
}