github-typescript-utils

Features

📋 Complete Function Reference

✨ Key Features

Installation

# With pnpm (recommended)
pnpm add github-typescript-utils
# With npm
npm install github-typescript-utils
# With yarn
yarn add github-typescript-utils

Usage with github-typescript

Dependency Setup

Option A: Root Dependencies (Simplest)

{
 "dependencies": {
 "github-typescript-utils": "^0.2.0"
 }
}

- uses: actions/setup-node@v4
 with:
 node-version: 22
 cache: pnpm
- run: pnpm install
- uses: tkstang/github-typescript@v1
 with:
 ts-file: .github/scripts/manage-pr.ts

Option B: Isolated CI Dependencies

{
 "name": "ci-scripts",
 "private": true,
 "type": "module",
 "dependencies": {
 "github-typescript-utils": "^0.2.0"
 }
}

- uses: actions/setup-node@v4
 with:
 node-version: 22
 cache: pnpm
 cache-dependency-path: .github/scripts/pnpm-lock.yaml
- run: pnpm install
 working-directory: .github/scripts
- uses: tkstang/github-typescript@v1
 with:
 working-directory: .github/scripts
 ts-file: manage-pr.ts

Script Example

// .github/scripts/manage-pr.ts
import {
 createStickyComment,
 findPullRequestsByLabels,
 getRepoInfo,
 getCurrentPullRequestNumber,
 type GitHubContext,
} from "github-typescript-utils";
type Args = {
 message: string;
 labels: string[];
};
export default async function run({
 core,
 github,
 context,
 args,
}: GitHubContext & { args: Args }) {
 const repo = getRepoInfo({ core, github, context });
 const prNumber = getCurrentPullRequestNumber({ core, github, context });
 if (!prNumber) {
 core.setFailed("This action must run on a pull request");
 return;
 }
 // Create a sticky comment
 await createStickyComment({
 ctx: { core, github, context },
 repo,
 issueNumber: prNumber,
 options: {
 identifier: "status-update",
 body: `## PR Status\n\n${args.message}`,
 },
 });
 // Find PRs with specific labels
 const prs = await findPullRequestsByLabels({
 ctx: { core, github, context },
 repo,
 options: { labels: args.labels },
 });
 core.info(`Found ${prs.length} PRs with labels: ${args.labels.join(", ")}`);
 return { success: true, prCount: prs.length };
}

- name: Manage PR
 uses: tkstang/github-typescript@v1
 with:
 ts-file: .github/scripts/manage-pr.ts
 args: ${{ toJson({ message: 'Build completed!', labels: ['ready-for-review'] }) }}

API Reference

Comments

createStickyComment(options)

await createStickyComment({
 ctx: { core, github, context },
 repo: { owner: "tkstang", repo: "my-repo" },
 issueNumber: 123,
 options: {
 identifier: "build-status",
 body: "✅ Build completed successfully!",
 updateIfExists: true, // default: true
 },
});

searchComments(options)

const comments = await searchComments({
 ctx: { core, github, context },
 repo,
 issueNumber: 123,
 options: {
 bodyContains: "error",
 author: "dependabot[bot]",
 createdAfter: new Date("2024-01-01"),
 limit: 10,
 },
});

deleteComment(options) / deleteStickyComment(options)

// Delete by ID
await deleteComment({
 ctx: { core, github, context },
 repo,
 commentId: 456789,
});
// Delete sticky comment
await deleteStickyComment({
 ctx: { core, github, context },
 repo,
 issueNumber: 123,
 identifier: "build-status",
});

Pull Requests

findPullRequestsByLabels(options)

const prs = await findPullRequestsByLabels({
 ctx: { core, github, context },
 repo,
 options: {
 labels: ["bug", "ready-for-review"],
 state: "open", // 'open' | 'closed' | 'all'
 limit: 20,
 },
});

addLabelsToPullRequest(options) / removeLabelsFromPullRequest(options)

await addLabelsToPullRequest({
 ctx: { core, github, context },
 repo,
 pullNumber: 123,
 labels: ["approved", "ready-to-merge"],
});
await removeLabelsFromPullRequest({
 ctx: { core, github, context },
 repo,
 pullNumber: 123,
 labels: ["work-in-progress"],
});

getPullRequestFiles(options)

const files = await getPullRequestFiles({
 ctx: { core, github, context },
 repo,
 pullNumber: 123,
});
console.log(
 files.map((f) => `${f.filename} (+${f.additions}/-${f.deletions})`)
);

Context Utilities

Repository and Context Information

// Get repository info from context
const repo = getRepoInfo({ core, github, context });
// Returns: { owner: 'tkstang', repo: 'my-repo' }
// Get current PR/issue number
const prNumber = getCurrentPullRequestNumber({ core, github, context });
const issueNumber = getCurrentIssueNumber({ core, github, context });
// Check context type
const isPR = isPullRequestContext({ core, github, context });
const isIssue = isIssueContext({ core, github, context });
// Get commit/branch info
const sha = getCurrentSHA({ core, github, context });
const branch = getCurrentBranch({ core, github, context });

URL Helpers

const repoUrl = getRepositoryUrl({ core, github, context });
const prUrl = getPullRequestUrl({ core, github, context }, 123);
const issueUrl = getIssueUrl({ core, github, context }, 456);

Markdown Utilities

Text Formatting

import {
 escapeMarkdown,
 codeBlock,
 createMarkdownTable,
 truncateText,
} from "github-typescript-utils";
// Escape special markdown characters
const safe = escapeMarkdown("Text with *special* characters");
// Create code blocks
const code = codeBlock('console.log("hello");', "javascript");
// Create tables
const table = createMarkdownTable(
 ["File", "Status", "Changes"],
 [
 ["src/index.ts", "✅", "+15/-3"],
 ["README.md", "📝", "+2/-0"],
 ]
);
// Truncate long text
const short = truncateText("Very long text...", 50);

String Utilities

Case Conversion

import {
 snakeToCamel,
 camelToSnake,
 kebabToCamel,
 camelToKebab,
 capitalize,
 toTitleCase,
} from "github-typescript-utils";
// Convert between naming conventions
const camelCase = snakeToCamel("hello_world"); // "helloWorld"
const snakeCase = camelToSnake("helloWorld"); // "hello_world"
const kebabCase = camelToKebab("helloWorld"); // "hello-world"
const camelFromKebab = kebabToCamel("hello-world"); // "helloWorld"
// Text transformation
const capitalized = capitalize("hello"); // "Hello"
const titleCase = toTitleCase("hello world"); // "Hello World"

Branch Management

Branch Operations

import {
 checkBranchExists,
 listAllBranches,
 getBranchProtection,
 getDefaultBranch,
} from "github-typescript-utils";
// Check if branch exists
const exists = await checkBranchExists({
 ctx: { core, github, context },
 repo,
 branch: "feature-branch",
});
// List all branches
const branches = await listAllBranches({
 ctx: { core, github, context },
 repo,
 limit: 50,
});
// Get branch protection rules
const protection = await getBranchProtection({
 ctx: { core, github, context },
 repo,
 branch: "main",
});
// Get default branch
const defaultBranch = await getDefaultBranch({
 ctx: { core, github, context },
 repo,
});

Deployment Management

Deployment Lifecycle

import {
 listDeployments,
 createDeployment,
 setDeploymentStatus,
 getDeploymentStatuses,
 deleteDeployment,
} from "github-typescript-utils";
// Create a deployment
const deployment = await createDeployment({
 ctx: { core, github, context },
 repo,
 ref: "main",
 environment: "production",
 description: "Deploy v1.0.0",
});
// Set deployment status
await setDeploymentStatus({
 ctx: { core, github, context },
 repo,
 deploymentId: deployment.id,
 state: "success",
 description: "Deployment completed successfully",
});
// List deployments
const deployments = await listDeployments({
 ctx: { core, github, context },
 repo,
 environment: "production",
});

Advanced PR Search

Enhanced PR Operations

import {
 findPRsWithLabels,
 searchPullRequests,
 checkLabelConflicts,
 findOpenPRsWithLabel,
} from "github-typescript-utils";
// Find PRs with multiple labels
const prs = await findPRsWithLabels({
 ctx: { core, github, context },
 repo,
 labels: ["bug", "urgent"],
 excludePRs: [123], // Exclude specific PR numbers
});
// Advanced PR search
const searchResults = await searchPullRequests({
 ctx: { core, github, context },
 repo,
 options: {
 labels: ["feature"],
 author: "dependabot[bot]",
 state: "open",
 },
});
// Check for label conflicts
const conflict = await checkLabelConflicts({
 ctx: { core, github, context },
 repo,
 prNumber: 123,
 label: "sync-branch: main",
});
if (conflict.hasConflict) {
 core.warning(`Label conflict with PR #${conflict.conflictingPR?.number}`);
}

Input Processing

Input Sanitization and Branch Extraction

import {
 sanitizeInput,
 sanitizeInputs,
 getBranch,
} from "github-typescript-utils";
// Remove quotes from workflow inputs
const cleanInput = sanitizeInput('"quoted-value"'); // "quoted-value"
// Sanitize all string properties in an object
const cleanInputs = sanitizeInputs({
 name: '"John"',
 age: 30,
 title: '"Developer"',
}); // { name: "John", age: 30, title: "Developer" }
// Extract branch from any GitHub event
const branch = getBranch({ core, github, context });
// Works with: pull_request, push, workflow_run, etc.

Type Definitions

import type {
 // Core types
 GitHubContext,
 RepoInfo,
 PullRequest,
 IssueComment,
 // Comment types
 StickyCommentOptions,
 CommentSearchOptions,
 // Pull request types
 PullRequestSearchOptions,
 PullRequestFile,
 AdvancedPRSearchOptions,
 // Deployment types
 Deployment,
 DeploymentStatus,
} from "github-typescript-utils";

Examples

Build Status Updater

// .github/scripts/update-build-status.ts
import {
 createStickyComment,
 getRepoInfo,
 getCurrentPullRequestNumber,
} from "github-typescript-utils";
export default async function run({ core, github, context, args }) {
 const repo = getRepoInfo({ core, github, context });
 const prNumber = getCurrentPullRequestNumber({ core, github, context });
 if (!prNumber) return { skipped: true };
 const status = args.success ? "✅ Passed" : "❌ Failed";
 const details = args.details || "";
 await createStickyComment({
 ctx: { core, github, context },
 repo,
 issueNumber: prNumber,
 options: {
 identifier: "ci-status",
 body: `## 🚀 CI Status\n\n${status}\n\n${details}`,
 },
 });
 return { updated: true };
}

PR Triage Bot

// .github/scripts/triage-prs.ts
import {
 findPullRequestsByLabels,
 addLabelsToPullRequest,
 getRepoInfo,
} from "github-typescript-utils";
export default async function run({ core, github, context }) {
 const repo = getRepoInfo({ core, github, context });
 // Find stale PRs
 const stalePRs = await findPullRequestsByLabels({
 ctx: { core, github, context },
 repo,
 options: {
 labels: ["needs-review"],
 state: "open",
 sort: "updated",
 direction: "asc",
 limit: 10,
 },
 });
 // Label old PRs as stale
 for (const pr of stalePRs) {
 const daysSinceUpdate =
 (Date.now() - new Date(pr.updated_at).getTime()) / (1000 * 60 * 60 * 24);
 if (daysSinceUpdate > 7) {
 await addLabelsToPullRequest({
 ctx: { core, github, context },
 repo,
 pullNumber: pr.number,
 labels: ["stale"],
 });
 core.info(
 `Labeled PR #${pr.number} as stale (${Math.round(
 daysSinceUpdate
 )} days old)`
 );
 }
 }
 return { processed: stalePRs.length };
}

Contributing

License