tessl/npm-patch-package

Fix broken node modules with no fuss - create and apply patches to npm dependencies instantly

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Rebase Operations

Name: tessl/npm-patch-package
Author: tessl

Advanced patch sequence management for reordering, editing, and managing complex patch workflows. The rebase functionality enables developers to modify patch history, insert changes at specific points, and manage complex patch sequences with confidence.

Capabilities

Main Rebase Function

Core function for rebasing patch sequences to different targets.

/**
 * Rebase patches to a specific target in the sequence
 * @param options - Rebase configuration options
 */
function rebase(options: RebaseOptions): void;

interface RebaseOptions {
  /** Application root path */
  appPath: string;
  /** Directory containing patch files */
  patchDir: string;
  /** Package path specifier to rebase */
  packagePathSpecifier: string;
  /** Target patch identifier (file name, number, name, or "0") */
  targetPatch: string;
}

Usage Examples:

import { rebase } from "patch-package/dist/rebase";
import { getAppRootPath } from "patch-package/dist/getAppRootPath";

// Rebase to specific patch file
rebase({
  appPath: getAppRootPath(),
  patchDir: "patches",
  packagePathSpecifier: "lodash",
  targetPatch: "lodash+4.17.21.patch"
});

// Rebase to sequence number
rebase({
  appPath: process.cwd(),
  patchDir: "patches", 
  packagePathSpecifier: "react",
  targetPatch: "3"
});

// Reset to beginning (un-apply all patches)
rebase({
  appPath: process.cwd(),
  patchDir: "patches",
  packagePathSpecifier: "lodash", 
  targetPatch: "0"
});

Rebase Target Types

Patch File Names

Target a specific patch file by its exact filename.

patch-package --rebase "lodash+4.17.21.patch" lodash

Sequence Numbers

Target patches by their position in the sequence (1-based indexing).

patch-package --rebase "3" lodash

Sequence Names

Target patches by their descriptive names (if using named sequences).

patch-package --rebase "security-fix" lodash

Reset to Beginning

Use "0" to un-apply all patches and start fresh.

patch-package --rebase "0" lodash

Rebase Workflow

1. State Validation

Before rebasing, patch-package validates:

All current patches are properly applied
State file integrity matches actual patches
No existing rebase operation is in progress

2. Un-apply Patches

Patches after the target are reversed in order:

Last patch applied is removed first
Each patch is verified before reversal
State is updated after each successful removal

3. Rebasing State

The package enters "rebasing" state where:

Normal patch application is blocked
Only patch creation/modification is allowed
State file tracks the rebase progress

4. Making Changes

During rebase, you can:

Modify files in the package directory
Use standard patch creation commands
Create new patches or update existing ones

5. Completing Rebase

# Update the target patch
patch-package my-package

# Add new patch after target
patch-package my-package --append="description"

Advanced Rebase Features

State Management Integration

Rebase operations integrate with patch application state for safe operation.

/**
 * Internal function for un-applying patches during rebase
 * @param options - Un-apply configuration
 */
function unApplyPatches(options: UnApplyPatchesOptions): void;

interface UnApplyPatchesOptions {
  /** Array of patches to un-apply */
  patches: PatchedPackageDetails[];
  /** Application path */
  appPath: string;
  /** Patch directory */
  patchDir: string;
}

Error Handling

Comprehensive error handling for rebase operations:

No Patches Found: Clear message when no patches exist
Invalid Target: Helpful listing of available patches
State Mismatch: Guidance for resolving inconsistent state
Un-apply Failures: Recovery instructions for failed reversals

Error Recovery:

# If rebase fails, you can:
# 1. Reinstall node_modules to reset state
npm install

# 2. Delete problematic patch files
rm patches/broken-package+1.0.0.patch

# 3. Restart the rebase process
patch-package --rebase 0 my-package

Interactive Rebase Guidance

When rebase enters interactive mode, patch-package provides clear instructions:

# Output example during rebase
Make any changes you need inside /path/to/package

When you are done, do one of the following:

  To update lodash+4.17.21.patch run
    patch-package lodash
    
  To create a new patch file after lodash+4.17.21.patch run
    patch-package lodash --append 'MyChangeDescription'

Rebase Use Cases

1. Insert Patch in Middle of Sequence

# Rebase to position 2
patch-package --rebase 2 my-package

# Make changes and insert new patch
patch-package my-package --append="hotfix"

2. Modify Early Patch

# Rebase to first patch
patch-package --rebase 1 my-package

# Modify files and update the patch
patch-package my-package

3. Remove Patches from End

# Rebase to earlier position
patch-package --rebase 3 my-package

# Don't add new patches - effectively truncates sequence

4. Completely Restart Patch Sequence

# Reset to beginning
patch-package --rebase 0 my-package

# Create entirely new patch sequence
patch-package my-package --append="complete-rewrite"

Best Practices

Before Rebasing

Commit Current Work: Ensure your changes are saved
Backup Patches: Copy patch files before major rebase operations
Clean Working Directory: Commit or stash uncommitted changes

During Rebase

Follow Instructions: patch-package provides clear guidance
Test Changes: Verify your modifications work as expected
Use Descriptive Names: Name new patches clearly

After Rebase

Test Patch Application: Run patch-package to verify patches apply
Update Documentation: Document significant patch sequence changes
Commit New Patches: Add updated patch files to version control

Complete Rebase Example:

import { rebase } from "patch-package/dist/rebase";
import { getAppRootPath } from "patch-package/dist/getAppRootPath";
import { getPatchApplicationState } from "patch-package/dist/stateFile"; 

// Check current state before rebasing
const appPath = getAppRootPath();
const packageDetails = { name: "lodash", path: "/path/to/lodash" };
const currentState = getPatchApplicationState(packageDetails);

if (currentState && !currentState.isRebasing) {
  // Safe to begin rebase
  rebase({
    appPath,
    patchDir: "patches",
    packagePathSpecifier: "lodash",
    targetPatch: "2" // Rebase to second patch
  });
  
  console.log("Rebase initiated - make your changes and run patch-package");
} else {
  console.log("Cannot rebase: operation already in progress or no state");
}

This comprehensive rebase system enables sophisticated patch management workflows while maintaining safety and providing clear guidance throughout the process.

Install with Tessl CLI