ts-repo-utils

Documentation

• API reference: https://noshiro-pf.github.io/ts-repo-utils/

Utilities for TypeScript Repositories.

A comprehensive toolkit for managing TypeScript projects with strict ESM support, providing essential utilities for file validation, code formatting, git operations, and project automation.

Installation

npm add --save-dev ts-repo-utils
Copy

yarn add --dev ts-repo-utils
Copy

pnpm add --save-dev ts-repo-utils
Copy

CLI Commands

ts-repo-utils provides several CLI commands that can be used directly or through npm scripts.

assert-repo-is-clean

Checks if the repository is clean (i.e., there are no uncommitted changes, untracked files, or staged files) and exits with code 1 if any are present.

# Basic usage
npm exec -- assert-repo-is-clean

# Silent mode
npm exec -- assert-repo-is-clean --silent
Copy

# Example in GitHub Actions
- name: Format check
  run: npm run fmt
- name: Check if there is no file diff
  run: npm exec -- assert-repo-is-clean
Copy

Options:

• --silent - Suppress output messages (optional)

format-uncommitted

Formats only untracked/modified files using Prettier.

# Basic usage
npm exec -- format-uncommitted

# Silent mode
npm exec -- format-uncommitted --silent
Copy

Options:

• --exclude-untracked - Exclude untracked files (default: false)
• --exclude-modified - Exclude modified files (default: false)
• --exclude-staged - Exclude staged files (default: false)
• --silent - Suppress output messages (default: false)
• --ignore-unknown - Skip files without a Prettier parser instead of erroring (default: true)

format-diff-from

Formats only files that differ from the specified base branch or commit.

# Format files different from main branch
npm exec -- format-diff-from main

# Format files different from origin/main
npm exec -- format-diff-from origin/main

# Exclude untracked files
npm exec -- format-diff-from main --exclude-untracked

# Silent mode
npm exec -- format-diff-from main --silent
Copy

Example in npm scripts:

{
    "scripts": {
        "fmt": "npm exec -- format-diff-from origin/main"
    }
}
Copy

Options:

• <base> - Base branch name or commit hash to compare against (required)
• --exclude-untracked - Exclude untracked files (default: false)
• --exclude-modified - Exclude modified files (default: false)
• --exclude-staged - Exclude staged files (default: false)
• --silent - Suppress output messages (default: false)
• --ignore-unknown - Skip files without a Prettier parser instead of erroring (default: true)

gen-index-ts

Generates index.ts files recursively in target directories with automatic barrel exports.

# Basic usage with required options
npm exec -- gen-index-ts ./src --target-ext .mts --index-ext .mts --export-ext .mjs

# With formatting command
npm exec -- gen-index-ts ./src --target-ext .mts --index-ext .mts --export-ext .mjs --fmt 'npm run fmt'

# Multiple target extensions
npm exec -- gen-index-ts ./src --target-ext .mts --target-ext .tsx --index-ext .mts --export-ext .mjs

# With exclude patterns
npm exec -- gen-index-ts ./src --target-ext .ts --index-ext .ts --export-ext .js --exclude '*.test.ts' --exclude '*.spec.ts'

# Skip generating index files at the root level (depth 0), only generate from depth 1 onwards
npm exec -- gen-index-ts ./src --target-ext .mts --index-ext .mts --export-ext .mjs --min-depth 1

# Example in npm scripts
"gi": "gen-index-ts ./src --index-ext .mts --export-ext .mjs --target-ext .mts --target-ext .tsx --fmt 'npm run fmt'"
Copy

Features:

• Creates barrel exports for all subdirectories
• Supports complex glob exclusion patterns (using micromatch)
• Automatically formats generated files using the project's Prettier config
• Works with both single directories and directory arrays
• Respects source and export extension configuration

Benefits:

• Prevents forgetting to export modules
• TypeScript can detect duplicate variables, type names, etc.

Options:

• <target-directory> - Directory where the index file will be generated (comma-separated list can be used)
• --target-ext - File extensions to include in the index file (required, can be specified multiple times)
• --index-ext - Extension of the index file to be generated (required)
• --export-ext - Extension of the export statements in the index file (required, or 'none')
• --exclude - Glob patterns of files to exclude (optional, can be specified multiple times)
• --fmt - Command to format after generating the index file (optional)
• --min-depth - Minimum depth to start generating index files (default: 0)
• --silent - Suppress output messages (optional)

check-should-run-type-checks

Checks whether TypeScript type checks should run based on file changes from the base branch. Optimizes CI/CD pipelines by skipping type checks when only non-TypeScript files have changed. The determination of "non-TypeScript files" is based on configurable ignore patterns, which can be specified using the --paths-ignore option.

# Basic usage (compares against origin/main)
npm exec -- check-should-run-type-checks

# Custom base branch
npm exec -- check-should-run-type-checks --base-branch origin/develop

# Custom ignore patterns
npm exec -- check-should-run-type-checks \
  --paths-ignore '.github/' \
  --paths-ignore 'docs/' \
  --paths-ignore '**.md' \
  --paths-ignore '**.yml'
Copy

# Example in GitHub Actions
- name: Check if type checks should run
  id: check_diff
  run: npm exec -- check-should-run-type-checks

- name: Run type checks
  if: steps.check_diff.outputs.should_run == 'true'
  run: npm run type-check
Copy

Options:

• --paths-ignore - Patterns to ignore when checking if type checks should run (optional, can be specified multiple times)
  • Supports exact file matches: .cspell.config.yaml
  • Directory prefixes: docs/ (matches any file in docs directory)
  • File extensions: **.md (matches any markdown file)
  • Default: ['LICENSE', '.editorconfig', '.gitignore', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']
• --base-branch - Base branch to compare against for determining changed files (default: origin/main)

GitHub Actions Integration:

When running in GitHub Actions, the command sets the GITHUB_OUTPUT environment variable with should_run=true or should_run=false, which can be used in subsequent steps.

API Reference

Command Execution

$(command: string, options?: ExecOptions): Promise<ExecResult>

Executes a shell command asynchronously with type-safe results.

import { $, Result } from 'ts-repo-utils';

const result = await $('npm test');

if (Result.isOk(result)) {
    console.log('Tests passed:', result.value.stdout);
} else {
    console.error('Tests failed:', result.value.message);
}
Copy

Options:

• silent?: boolean - Don't log command/output (default: false)
• 'node:child_process' exec function options

Return Type:

import { type ExecException } from 'node:child_process';
import { type Result } from 'ts-data-forge';

type Ret = Promise<
    Result<
        Readonly<{ stdout: string | Buffer; stderr: string | Buffer }>,
        ExecException
    >
>;
Copy

Script Execution Utilities

isDirectlyExecuted(fileUrl: string): boolean

Determines whether a script is being executed directly via CLI or imported as a module. This is useful for creating scripts that can both be imported as libraries and executed directly.

import { isDirectlyExecuted } from 'ts-repo-utils';

// calculator.mjs
export const add = (a: number, b: number): number => a + b;

export const multiply = (a: number, b: number): number => a * b;

// Only run main logic when executed directly: node calculator.mjs (or tsx calculator.mts)
// When imported elsewhere, only the functions are available
if (isDirectlyExecuted(import.meta.url)) {
    console.log('Calculator CLI');

    console.log('2 + 3 =', add(2, 3));

    console.log('4 × 5 =', multiply(4, 5));
}
Copy

When executed directly (node calculator.mjs), it runs the main function and prints the results. When imported (import { add } from './calculator.mjs'), it only provides the functions without executing the main logic.

NOTE: If you use tsx or ts-node, run your scripts with the extension .(m)ts instead of .(m)js so that isDirectlyExecuted can correctly determine if the script is executed directly.

Use Cases:

• Creating CLI tools that can also be used as libraries
• Preventing automatic execution when a file is imported
• Running initialization code only during direct execution

Path and File System Utilities

pathExists(filePath: string): Promise<boolean>

Checks if a file or directory exists at the specified path.

import { pathExists } from 'ts-repo-utils';

const exists = await pathExists('./src/index.ts');

console.log(exists satisfies boolean); // true or false
Copy

assertPathExists(filePath: string, description?: string): Promise<void>

Validates that a path exists and exits with code 1 if it doesn't.

import { assertPathExists } from 'ts-repo-utils';

// If the file doesn't exist, this will exit the process with code 1
await assertPathExists('./src/index.ts', 'Entry point file');
Copy

checkExt(config: CheckExtConfig): Promise<Result<undefined, Readonly<{ message: string; files: readonly string[] }>>>

Runs the extension validation and reports findings without exiting the process. Useful when you want to combine extension checks with other validations or surface the failure information in a custom way.

import { Result } from 'ts-data-forge';
import { checkExt } from 'ts-repo-utils';

const result = await checkExt({
    directories: [
        { path: './src', extension: '.ts' },
        { path: './scripts', extension: '.mjs' },
    ],
});

if (Result.isErr(result)) {
    console.error(result.value.message);

    console.error('Files with wrong extensions:', result.value.files);
}
Copy

assertExt(config: CheckExtConfig): Promise<void>

Validates that all files in specified directories have the correct extensions. Exits with code 1 if any files have incorrect extensions.

import { assertExt } from 'ts-repo-utils';

await assertExt({
    directories: [
        {
            path: './src',
            extension: '.ts',
            ignorePatterns: ['*.d.ts', '*.test.ts'],
        },
        {
            path: './scripts',
            extension: '.mjs',
        },
    ],
});
Copy

Configuration Type:

type CheckExtConfig = Readonly<{
    directories: readonly Readonly<{
        path: string; // Directory path to check
        extension: string; // Expected file extension (including the dot)
        ignorePatterns?: readonly string[]; // Optional glob patterns to ignore
    }>[];
}>;
Copy

Result Utilities

createResultAssert(options): (config) => Promise<TOk>

Creates an assert-style wrapper around a function that returns a Result, exiting the process with a non-zero code when the underlying function yields an error. The wrapper keeps success handling customizable while reusing the composable Result-based variant elsewhere.

import { hasKey, isNumber, isRecord, isString, Result } from 'ts-data-forge';
import { createResultAssert } from 'ts-repo-utils';

type AppConfig = Readonly<{ port: number; host: string }>;

const parseConfig = (
    raw: string,
): Promise<Result<AppConfig, Readonly<{ message: string }>>> => {
    const parsed: unknown = ((): unknown => {
        try {
            return JSON.parse(raw);
        } catch {
            return undefined;
        }
    })();

    if (
        !isRecord(parsed) ||
        !hasKey(parsed, 'port') ||
        !hasKey(parsed, 'host') ||
        !isNumber(parsed.port) ||
        !isString(parsed.host)
    ) {
        return Promise.resolve(Result.err({ message: 'Invalid config shape' }));
    }

    return Promise.resolve(Result.ok({ port: parsed.port, host: parsed.host }));
};

const assertValidConfig = createResultAssert({
    run: parseConfig,
    onSuccess: (config) => {
        console.log(`✓ Config loaded: ${config.host}:${config.port}`);
    },
});

await assertValidConfig('{"port":3000,"host":"localhost"}');
Copy

Options:

• run - Function returning a Result to assert (required)
• onSuccess - Optional callback invoked with the OK value
• onError - Optional callback invoked with the Err value before exiting
• exitCode - Custom exit code on failure (default: 1)

makeEmptyDir(dir: string): Promise<void>

Removes any existing directory at dir and recreates it, ensuring a clean target for generated assets or build output.

import { makeEmptyDir } from 'ts-repo-utils';

// Reset ./tmp/build before writing artifacts
await makeEmptyDir('./tmp/build');
Copy

This helper uses fs.rm with recursive cleanup before calling fs.mkdir, so prefer it over manual rimraf + mkdir sequences when scripting workflows.

Git Repository Utilities

repoIsDirty(): Promise<boolean>

Checks if the repository has uncommitted changes.

import { repoIsDirty } from 'ts-repo-utils';

const isDirty = await repoIsDirty();

if (isDirty) {
    console.log('Repository has uncommitted changes');
}
Copy

assertRepoIsClean(): Promise<void>

Checks if the repository is clean and exits with code 1 if it has uncommitted changes (shows changes and diff). (Function version of the assert-repo-is-clean command)

import { assertRepoIsClean } from 'ts-repo-utils';

// Use in CI/build scripts to ensure clean state
await assertRepoIsClean();
Copy

Options:

• silent? - Suppress output messages (default: false)

Getting Git diff files

getUntrackedFiles(options?)

Gets untracked files from the working tree (files not added to git).
Runs git ls-files --others --exclude-standard [--deleted]

getModifiedFiles(options?)

Gets modified files from the working tree (files that have been changed but not staged).
Runs git diff --name-only [--diff-filter=d]

getStagedFiles(options?)

Gets files that are staged for commit (files added with git add).
Runs git diff --staged --name-only [--diff-filter=d]

getDiffFrom(base: string, options?)

Gets files that differ from the specified base branch or commit.
Runs git diff --name-only <base> [--diff-filter=d]

Common options:

• excludeDeleted?: boolean - Exclude deleted files (for formatters etc.) (default: true)
• silent?: boolean - Don't log command/output (default: false)

Common Return Type:

import { type ExecException } from 'node:child_process';
import { type Result } from 'ts-data-forge';

type Ret = Result<
    readonly string[],
    ExecException | Readonly<{ message: string }>
>;
Copy

Build Optimization Utilities

checkShouldRunTypeChecks(options?): Promise<boolean>

Checks whether TypeScript type checks should run based on file changes from the base branch. Optimizes CI/CD pipelines by skipping type checks when only non-TypeScript files have changed. (Function version of the check-should-run-type-checks command)

import { $, checkShouldRunTypeChecks } from 'ts-repo-utils';

// Use default settings (compare against origin/main)
const shouldRun = await checkShouldRunTypeChecks();

if (shouldRun) {
    await $('npm run type-check');
}

// Custom ignore patterns and base branch
const shouldRun2 = await checkShouldRunTypeChecks({
    pathsIgnore: ['.eslintrc.json', 'docs/', '**.md', 'scripts/'],
    baseBranch: 'origin/develop',
});
Copy

Options:

• pathsIgnore? - Patterns to ignore when checking if type checks should run:
  • Exact file matches: .cspell.config.yaml
  • Directory prefixes: docs/ (matches any file in docs directory)
  • File extensions: **.md (matches any markdown file)
  • Default: ['LICENSE', '.editorconfig', '.gitignore', '.cspell.config.yaml', '.markdownlint-cli2.mjs', '.npmignore', '.prettierignore', '.prettierrc', 'docs/', '**.md', '**.txt']
• baseBranch? - Base branch to compare against (default: origin/main)

Code Formatting Utilities

formatFilesGlob(pathGlob: string, options?): Promise<Result<undefined, unknown>>

Formats files matching a glob pattern using Prettier.

import { formatFilesGlob } from 'ts-repo-utils';

// Format all TypeScript files in src
await formatFilesGlob('src/**/*.ts');

// Format specific files
await formatFilesGlob('src/{index,utils}.ts');

// With custom ignore function
await formatFilesGlob('src/**/*.ts', {
    ignore: (filePath) => filePath.includes('generated'),
    ignoreUnknown: false, // Error on files without parser
});
Copy

Options:

• silent? - Suppress output messages (default: false)
• ignoreUnknown? - Skip files without a Prettier parser instead of erroring (default: true)
• ignore? - Custom function to ignore files (default: built-in ignore list)

formatUncommittedFiles(options?): Promise<Result>

Formats only files that have been changed according to git status. (Function version of the format-uncommitted command)

import { formatUncommittedFiles } from 'ts-repo-utils';

// Format only modified files
await formatUncommittedFiles();

// With custom options
await formatUncommittedFiles({
    untracked: false, // Skip untracked files
    ignore: (filePath) => filePath.includes('test'),
});
Copy

Options:

• untracked? - Format untracked files (default: true)
• modified? - Format modified files (default: true)
• staged? - Format staged files (default: true)
• silent? - Suppress output messages (default: false)
• ignoreUnknown? - Skip files without a Prettier parser instead of erroring (default: true)
• ignore? - Custom function to ignore files (default: built-in ignore list)

Return Type:

import { type ExecException } from 'node:child_process';
import { type Result } from 'ts-data-forge';

type Ret = Promise<
    Result<
        undefined,
        ExecException | Readonly<{ message: string }> | readonly unknown[]
    >
>;
Copy

formatDiffFrom(base: string, options?): Promise<Result>

Formats only files that differ from the specified base branch or commit. (Function version of the format-diff-from command)

import { formatDiffFrom } from 'ts-repo-utils';

// Format files different from main branch
await formatDiffFrom('main');

// Format files different from specific commit
await formatDiffFrom('abc123');

// With custom options
await formatDiffFrom('main', {
    includeUntracked: false,
    ignore: (filePath) => filePath.includes('vendor'),
    ignoreUnknown: false, // Error on files without parser
});
Copy

Options:

• includeUntracked? - Include untracked files in addition to diff files (default: true)
• includeModified? - Include modified files in addition to diff files (default: true)
• includeStaged? - Include staged files in addition to diff files (default: true)
• silent? - Suppress output messages (default: false)
• ignoreUnknown? - Skip files without a Prettier parser instead of erroring (default: true)
• ignore? - Custom function to ignore files (default: built-in ignore list)

Return Type:

import { type ExecException } from 'node:child_process';
import { type Result } from 'ts-data-forge';

type Ret = Promise<
    Result<
        undefined,
        ExecException | Readonly<{ message: string }> | readonly unknown[]
    >
>;
Copy

Index File Generation

genIndex(config: GenIndexConfig): Promise<Result<undefined, unknown>>

Generates index files recursively in target directories with automatic barrel exports. (Function version of the gen-index-ts command)

import { genIndex } from 'ts-repo-utils';

await genIndex({
    targetDirectory: './src',
    exclude: ['*.test.ts', '*.spec.ts'],
});
Copy

Configuration Type:

type GenIndexConfig = Readonly<{
    /** Target directories to generate index files for (string or array of strings) */
    targetDirectory: string | readonly string[];

    /**
     * Glob patterns for files or predicate function to exclude from exports
     * (default: excludes `'**\/*.{test,spec}.?(c|m)[jt]s?(x)'` and
     * `'**\/*.d.?(c|m)ts'`)
     */
    exclude?:
        | readonly string[]
        | ((
              args: Readonly<{
                  absolutePath: string;
                  relativePath: string;
                  fileName: string;
              }>,
          ) => boolean);

    /**
     * File extensions of source files to include in exports (default: ['.ts',
     * '.tsx'])
     */
    targetExtensions?: readonly `.${string}`[];

    /** File extension of index files to generate (default: '.ts') */
    indexFileExtension?: `.${string}`;

    /** File extension to use in export statements (default: '.js') */
    exportStatementExtension?: `.${string}` | 'none';

    /** Command to run for formatting generated files (optional) */
    formatCommand?: string;

    /** Whether to suppress output during execution (default: false) */
    silent?: boolean;
}>;
Copy

Features:

• Creates barrel exports for all subdirectories
• Supports complex glob exclusion patterns (using micromatch)
• Automatically formats generated files using the project's Prettier config
• Works with both single directories and directory arrays
• Respects source and export extension configuration

Benefits:

• Prevents forgetting to export modules
• TypeScript can detect duplicate variables, type names, etc.

Monorepo Workspace Management Utilities

runCmdInStagesAcrossWorkspaces(options): Promise<void>

Executes an npm script command across all workspace packages in dependency order stages. Packages are grouped into stages where each stage contains packages whose dependencies have been completed in previous stages. Uses fail-fast behavior.

import { runCmdInStagesAcrossWorkspaces } from 'ts-repo-utils';

// Run build in dependency order
await runCmdInStagesAcrossWorkspaces({
    rootPackageJsonDir: '../',
    cmd: 'build',
    concurrency: 3,
    filterWorkspacePattern: (name) => !name.includes('experimental'),
});
Copy

Options:

• rootPackageJsonDir - Directory containing the root package.json file
• cmd - The npm script command to execute in each package
• concurrency? - Maximum packages to process simultaneously within each stage (default: 3)
• filterWorkspacePattern? - Optional function to filter packages by name

runCmdInParallelAcrossWorkspaces(options): Promise<void>

Executes an npm script command across all workspace packages in parallel. Uses fail-fast behavior - stops execution immediately when any package fails.

import { runCmdInParallelAcrossWorkspaces } from 'ts-repo-utils';

// Run tests in parallel across all packages
await runCmdInParallelAcrossWorkspaces({
    rootPackageJsonDir: '../',
    cmd: 'test',
    concurrency: 5,
    filterWorkspacePattern: (name) => !name.includes('experimental'),
});
Copy

Options:

• rootPackageJsonDir - Directory containing the root package.json file
• cmd - The npm script command to execute in each package
• concurrency? - Maximum packages to process simultaneously (default: 3)
• filterWorkspacePattern? - Optional function to filter packages by name

getWorkspacePackages(rootPackageJsonDir): Promise<readonly Package[]>

Retrieves all workspace packages from a monorepo based on the workspace patterns defined in the root package.json file.

import { getWorkspacePackages } from 'ts-repo-utils';

const packages = await getWorkspacePackages('.');

console.log(packages.map((pkg) => pkg.name));
// ['@myorg/package-a', '@myorg/package-b', ...]
Copy

Return Type:

import { type JsonValue } from 'ts-type-forge';

type Package = Readonly<{
    name: string;
    path: string;
    packageJson: JsonValue;
    dependencies: Readonly<Record<string, string>>;
}>;
Copy

executeParallel(packages, scriptName, concurrency?): Promise<readonly Result[]>

Executes an npm script across multiple packages in parallel with a concurrency limit. Lower-level function used by runCmdInParallelAcrossWorkspaces.

import { executeParallel, getWorkspacePackages } from 'ts-repo-utils';

const packages = await getWorkspacePackages('.');

await executeParallel(packages, 'lint', 4);
Copy

executeStages(packages, scriptName, concurrency?): Promise<void>

Executes an npm script across packages in dependency order stages. Lower-level function used by runCmdInStagesAcrossWorkspaces.

import { executeStages, getWorkspacePackages } from 'ts-repo-utils';

const packages = await getWorkspacePackages('.');

await executeStages(packages, 'build', 3);
Copy

Features:

• Automatic dependency graph construction
• Topological sorting for correct build order
• Parallel execution within each stage
• Fail-fast behavior on errors
• Circular dependency detection

Common Patterns

Pre-commit Hook

import {
    assertExt,
    assertRepoIsClean,
    formatUncommittedFiles,
} from 'ts-repo-utils';

// Validate file extensions
await assertExt({
    directories: [{ path: './src', extension: '.ts' }],
});

// Format changed files
await formatUncommittedFiles();

// Ensure repository is clean (exits if dirty)
await assertRepoIsClean();
Copy

Build Pipeline

import { $, formatFilesGlob, genIndex } from 'ts-repo-utils';

// Generate barrel exports
await genIndex({ targetDirectory: './src' });

// Type check
await $('tsc --noEmit');

// Build
await $('rollup -c');

// Format output
await formatFilesGlob('dist/**/*.js');
Copy

Project Validation

import { assertExt, assertPathExists, assertRepoIsClean } from 'ts-repo-utils';

// Check required files exist (exits with code 1 if files don't exist)
await assertPathExists('./package.json', 'Package manifest');

await assertPathExists('./tsconfig.json', 'TypeScript config');

// Validate extensions
await assertExt({
    directories: [
        { path: './src', extension: '.ts' },
        { path: './scripts', extension: '.mjs' },
    ],
});

// Verify clean repository state (exits with code 1 if repo is dirty)
await assertRepoIsClean();
Copy

License

Apache-2.0