Dependency Relationships

/**
 * Create a new dependency edge
 * @param options - Edge configuration options
 */
constructor(options: EdgeOptions): Edge;

interface EdgeOptions {
  /** Edge type */
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
  /** Dependency name */
  name: string;
  /** Version specifier */
  spec: string;
  /** Source node that has the dependency */
  from: Node;
  /** Accept range (optional) */
  accept?: string;
  /** Override configuration (optional) */
  overrides?: object;
}

const { Edge } = require('@npmcli/arborist');

// Create a production dependency edge
const edge = new Edge({
  type: 'prod',
  name: 'express',
  spec: '^4.18.0',
  from: rootNode
});

interface EdgeStatics {
  /** Array of valid edge types */
  static types: ['prod', 'dev', 'optional', 'peer', 'peerOptional', 'workspace'];
  /** Array of possible error types */
  static errors: ['DETACHED', 'MISSING', 'PEER LOCAL', 'INVALID'];
}

interface EdgeBasicInfo {
  /** Dependency name */
  name: string;
  /** Edge type */
  type: 'prod' | 'dev' | 'optional' | 'peer' | 'peerOptional' | 'workspace';
  /** Version specifier (may be overridden) */
  spec: string;
  /** Original version specifier */
  rawSpec: string;
  /** Accept range */
  accept: string;
  /** Source node that has the dependency */
  from: Node;
  /** Target node that satisfies the dependency */
  to: Node | null;
}

// Examine edge properties
console.log(`Dependency: ${edge.name}@${edge.spec}`);
console.log(`Type: ${edge.type}`);
console.log(`From: ${edge.from.name}`);
console.log(`To: ${edge.to?.name || 'unresolved'}`);

interface EdgeTypeFlags {
  /** Is production dependency */
  prod: boolean;
  /** Is development dependency */
  dev: boolean;
  /** Is optional dependency */
  optional: boolean;
  /** Is peer dependency */
  peer: boolean;
  /** Is workspace dependency */
  workspace: boolean;
  /** Is bundled dependency */
  bundled: boolean;
}

// Check dependency type
if (edge.prod) {
  console.log('Production dependency');
} else if (edge.dev) {
  console.log('Development dependency');
} else if (edge.optional) {
  console.log('Optional dependency');
} else if (edge.peer) {
  console.log('Peer dependency');
}

interface EdgeValidation {
  /** Is edge valid (target satisfies spec) */
  valid: boolean;
  /** Error type if invalid, null if valid */
  error: string | null;
  /** Target is missing */
  missing: boolean;
  /** Target doesn't satisfy spec */
  invalid: boolean;
  /** Peer dependency found locally (invalid) */
  peerLocal: boolean;
  /** Has peer dependency conflicts */
  peerConflicted: boolean;
}

// Check validation status
if (edge.valid) {
  console.log('Dependency is satisfied');
} else {
  console.log(`Dependency error: ${edge.error}`);
  
  if (edge.missing) {
    console.log('Target package is missing');
  } else if (edge.invalid) {
    console.log('Target package version does not satisfy spec');
  } else if (edge.peerLocal) {
    console.log('Peer dependency found in local node_modules (invalid)');
  }
}

// Handle different error types
switch (edge.error) {
  case 'MISSING':
    console.log('Package needs to be installed');
    break;
  case 'INVALID':
    console.log('Package version is incompatible');
    break;
  case 'PEER LOCAL':
    console.log('Peer dependency incorrectly installed locally');
    break;
  case 'DETACHED':
    console.log('Edge has been detached from tree');
    break;
}

interface EdgeOverrides {
  /** Override configuration */
  overrides: object | null;
}

/**
 * Test if a node satisfies this dependency edge
 * @param node - Node to test for satisfaction
 * @returns True if the node satisfies this edge
 */
satisfiedBy(node: Node): boolean;

// Test if a node satisfies the dependency
const candidateNode = tree.resolve(edge.name);

if (candidateNode && edge.satisfiedBy(candidateNode)) {
  console.log(`${candidateNode.name}@${candidateNode.version} satisfies ${edge.spec}`);
} else {
  console.log('Candidate node does not satisfy dependency');
}

/**
 * Reload edge resolution, optionally forcing a hard reload
 * @param hard - Force complete re-resolution
 */
reload(hard?: boolean): void;

/**
 * Detach edge from the tree (marks as DETACHED)
 */
detach(): void;

// Reload edge resolution after tree changes
edge.reload();

// Force complete re-resolution
edge.reload(true);

// Detach edge when removing dependency
edge.detach();

/**
 * Explain the edge relationship and resolution
 * @param seen - Array of already seen edges (for cycle detection)
 * @returns Explanation object
 */
explain(seen?: Edge[]): any;

/**
 * Convert edge to JSON representation
 * @returns JSON representation of the edge
 */
toJSON(): object;

// Get detailed explanation of edge
const explanation = edge.explain();
console.log('Edge explanation:', explanation);

// Convert to JSON for inspection
const edgeData = edge.toJSON();
console.log('Edge data:', JSON.stringify(edgeData, null, 2));

const prodEdge = new Edge({
  type: 'prod',
  name: 'express',
  spec: '^4.18.0',
  from: rootNode
});

const devEdge = new Edge({
  type: 'dev',
  name: 'jest',
  spec: '^29.0.0',
  from: rootNode
});

const optionalEdge = new Edge({
  type: 'optional',
  name: 'fsevents',
  spec: '^2.3.0',
  from: rootNode
});

const peerEdge = new Edge({
  type: 'peer',
  name: 'react',
  spec: '>=16.8.0',
  from: componentNode
});

const peerOptionalEdge = new Edge({
  type: 'peerOptional',
  name: 'typescript',
  spec: '>=4.0.0',
  from: libNode
});

const workspaceEdge = new Edge({
  type: 'workspace',
  name: 'shared-utils',
  spec: '*',
  from: appNode
});

if (edge.error === 'MISSING') {
  console.log(`${edge.name} needs to be installed`);
}

if (edge.error === 'INVALID') {
  console.log(`${edge.name}@${edge.to.version} doesn't satisfy ${edge.spec}`);
}

if (edge.error === 'PEER LOCAL') {
  console.log(`Peer dependency ${edge.name} should not be installed locally`);
}

if (edge.error === 'DETACHED') {
  console.log(`Edge ${edge.name} has been detached from tree`);
}