Edge Cases and Advanced Scenarios

Advanced scenarios, error handling patterns, and edge cases for npq.

Error Handling Edge Cases

Network Timeouts

const Marshall = require('npq/lib/marshall');

// Handle network timeouts
async function auditWithTimeout(packages, timeoutMs = 30000) {
  const marshall = new Marshall({ pkgs: packages });
  
  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Audit timeout')), timeoutMs);
  });
  
  try {
    const results = await Promise.race([
      marshall.run(),
      timeoutPromise
    ]);
    return results;
  } catch (error) {
    if (error.message === 'Audit timeout') {
      console.error('Security audit timed out');
      throw error;
    }
    throw error;
  }
}

Partial Failures

// Handle partial failures
async function auditWithPartialResults(packages) {
  const marshall = new Marshall({ pkgs: packages });
  
  try {
    const results = await marshall.run();
    return results;
  } catch (error) {
    // Even if some marshalls fail, return partial results
    if (error.partialResults) {
      console.warn('Some marshalls failed, returning partial results');
      return error.partialResults;
    }
    throw error;
  }
}

Rate Limiting

// Handle rate limiting
async function auditWithRetry(packages, maxRetries = 3) {
  const marshall = new Marshall({ pkgs: packages });
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await marshall.run();
    } catch (error) {
      if (error.statusCode === 429 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.warn(`Rate limited, retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Error Handling in Programmatic Usage

Complete Error Handling

const Marshall = require('npq/lib/marshall');

try {
  const marshall = new Marshall({
    pkgs: ['nonexistent-package@latest']
  });
  
  const results = await marshall.run();
} catch (error) {
  if (error.code === 'PACKAGE_NOT_FOUND') {
    console.error(`Package not found: ${error.packageName}`);
  } else if (error.code === 'USER_ABORT') {
    console.log('Operation aborted by user');
  } else if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
    console.error('Network error:', error.message);
    console.error('URL:', error.url);
  } else if (error.code === 'EMISSINGSIGNATUREKEY') {
    console.error('Missing signature key for package verification');
  } else if (error.code === 'EEXPIREDSIGNATUREKEY') {
    console.warn('Expired signature key detected');
  } else if (error.code === 'EINTEGRITYSIGNATURE') {
    console.error('Invalid package signature detected');
  } else {
    console.error('Unexpected error:', error.message);
    console.error('Error code:', error.code);
    console.error('Stack:', error.stack);
  }
}

Programmatic Usage with Progress Indicator

const Marshall = require('npq/lib/marshall');
const ora = require('ora');

// Create spinner for progress indication
const spinner = ora('Running security checks...').start();

const marshall = new Marshall({
  pkgs: ['express@latest'],
  progressManager: spinner
});

try {
  const results = await marshall.run();
  spinner.succeed('Security checks completed');
  
  // Process results...
} catch (error) {
  spinner.fail('Security checks failed');
  throw error;
}

Marshall-Specific Edge Cases

Age Marshall Edge Cases

• Packages with no time metadata: Falls back to version-specific time
• Invalid date formats: Handles gracefully, may skip check
• Packages with only one version: Uses package creation date for both checks

Author Marshall Edge Cases

• Packages with no maintainers: Checks _npmUser field as fallback
• Invalid email formats: Skips email validation, checks other fields
• Multiple authors: Checks all authors, error if any author is new
• Missing publish dates: Uses package creation date as fallback

Deprecation Marshall Edge Cases

• Repository URL not GitHub: Skips archive check, only checks deprecation
• Invalid repository URL format: Skips archive check gracefully
• GitHub API rate limit exceeded: Falls back to deprecation check only
• Missing repository field: Only checks deprecation status
• Private repositories: Archive check may fail if no token provided

Downloads Marshall Edge Cases

• API returns null/undefined: Treats as 0 downloads (error)
• Network timeout: May skip check or retry
• New packages with no download data: May return 0 (error)
• Scoped packages: Downloads counted correctly

Expired Domains Marshall Edge Cases

• Invalid email format: Skips DNS check, no error
• DNS resolution timeout: Treats as potentially expired (error)
• No maintainers: Skips check (no error)
• DNS server unavailable: May retry with alternate DNS (1.1.1.1, 8.8.8.8)

License Marshall Edge Cases

• License field is empty string: Treated as no license (error)
• License field is object: Extracts type field
• Security placeholder packages: Detected by package name pattern
• Multiple license formats: Handles string, object, and array formats

New Binary Marshall Edge Cases

• First version of package: All binaries are considered new (warning)
• Binary path changed but name same: Not detected as new
• Bin field format changes: Normalized before comparison
• Missing previous version: Uses empty object for comparison

Provenance Marshall Edge Cases

• Registry keys unavailable: May skip verification (warning)
• Malformed attestation data: Handles gracefully (warning)
• Expired registry keys: Still verifies if key was valid at publish time
• Multiple attestations: Verifies all, warning if any invalid

Repository Marshall Edge Cases

• Timeout (5 seconds): Treats as not accessible (warning/error)
• HTTP redirects: Follows redirects, checks final URL
• HTTPS certificate errors: May treat as not accessible
• Private repositories: Returns 403/404, treated as not accessible

Scripts Marshall Edge Cases

• Scripts field missing: Treated as no scripts (success)
• Empty scripts object: Treated as no scripts (success)
• Only non-install scripts: Not flagged (success)
• Script command is empty string: Still flagged (error)

Signatures Marshall Edge Cases

• No signature present: Not an error (signatures are optional)
• Registry keys API unavailable: May skip verification
• Key cache expired: Refetches keys from registry
• Multiple signatures: Verifies all, error if any invalid

Snyk Marshall Edge Cases

• Snyk API unavailable: Falls back to OSV API
• No Snyk token: Uses OSV API (no authentication required)
• OSV API unavailable: May skip check or error
• Rate limiting: May retry or fall back to OSV
• Package not in database: Returns 0 vulnerabilities (success)

Typosquatting Marshall Edge Cases

• Package in allowlist: Skips check (success)
• Empty top-packages list: Skips check (success)
• Case sensitivity: Comparison is case-sensitive
• Scoped packages: Compares unscoped name only

Version Maturity Marshall Edge Cases

• Missing publish date: Uses package creation date as fallback
• Invalid date format: Handles gracefully, may skip check
• Future dates: Handles gracefully, treats as recent (error)

See Also

• Real-World Scenarios - Common usage patterns
• Reference: Error Handling - Complete error documentation
• Reference: API - Programmatic usage details