Asset System

/**
 * Base asset interface with core properties and methods
 */
interface BaseAsset {
  /** Unique asset identifier */
  readonly id: string;
  /** File system instance for this asset */
  readonly fs: FileSystem;
  /** Path to the source file */
  readonly filePath: FilePath;
  /** Asset type (e.g., 'js', 'css', 'html') */
  readonly type: string;
  /** Query string from import (e.g., '?inline') */
  readonly query: URLSearchParams;
  /** Target environment for this asset */
  readonly env: Environment;
  /** Whether this is a source file (not generated) */
  readonly isSource: boolean;
  /** Plugin-specific metadata */
  readonly meta: Meta;
  /** Pipeline configuration for this asset */
  readonly pipeline: ?string;
  /** Asset statistics */
  readonly stats: Stats;
  
  /** Get the source code as a string */
  getCode(): Promise<string>;
  /** Get the source code as a buffer */
  getBuffer(): Promise<Buffer>;
  /** Get the source code as a readable stream */
  getStream(): Readable;
  /** Get the parsed AST for this asset */
  getAST(): Promise<AST>;
  /** Get the source map for this asset */
  getMap(): Promise<?SourceMap>;
  /** Get all dependencies of this asset */
  getDependencies(): Array<Dependency>;
  /** Get exported symbols from this asset */
  getSymbols(): Promise<AssetSymbols>;
}

/**
 * Mutable asset interface for transformation phase
 */
interface MutableAsset extends BaseAsset {
  /** Asset type (mutable) */
  type: string;
  /** Whether this is a source file (mutable) */
  isSource: boolean;
  /** Target environment (mutable) */
  env: Environment;
  /** Plugin-specific metadata (mutable) */
  meta: Meta;
  /** Asset statistics (mutable) */
  stats: Stats;
  
  /** Set the source code */
  setCode(code: string): void;
  /** Set the source buffer */
  setBuffer(buffer: Buffer): void;
  /** Set the source stream */
  setStream(stream: Readable): void;
  /** Set the parsed AST */
  setAST(ast: AST): void;
  /** Set the source map */
  setMap(map: ?SourceMap): void;
  
  /** Add a dependency to another asset */
  addDependency(dep: DependencyOptions): string;
  /** Add a URL dependency (for assets like images, fonts) */
  addURLDependency(url: string, opts?: $Shape<DependencyOptions>): string;
  
  /** Invalidate the asset when a file is created */
  invalidateOnFileCreate(invalidation: FileCreateInvalidation): void;
  /** Invalidate the asset when environment variables change */
  invalidateOnEnvChange(env: string): void;
  /** Invalidate the asset when build options change */
  invalidateOnOptionChange(option: string): void;
  
  /** Get mutable exported symbols */
  getSymbols(): Promise<MutableAssetSymbols>;
}

/**
 * Immutable asset interface for final build output
 */
interface Asset extends BaseAsset {
  /** Asset file statistics */
  readonly stats: Stats;
}

/**
 * Asset dependency interface
 */
interface Dependency {
  /** Unique dependency identifier */
  readonly id: string;
  /** Import specifier (e.g., './utils', 'lodash') */
  readonly specifier: DependencySpecifier;
  /** Type of import specifier */
  readonly specifierType: SpecifierType;
  /** Loading priority */
  readonly priority: DependencyPriority;
  /** Bundle behavior for this dependency */
  readonly bundleBehavior: ?BundleBehavior;
  /** Whether this dependency needs a stable name */
  readonly needsStableName: boolean;
  /** Whether this dependency is optional */
  readonly isOptional: boolean;
  /** Whether this is an entry point */
  readonly isEntry: boolean;
  /** Location in source code */
  readonly loc: ?SourceLocation;
  /** Target environment */
  readonly env: Environment;
  /** Imported/exported symbols */
  readonly symbols: MutableDependencySymbols;
  /** Pipeline to use for resolution */
  readonly pipeline: ?string;
  /** Plugin-specific metadata */
  readonly meta: Meta;
  /** Asset that owns this dependency */
  readonly sourcePath: FilePath;
  /** Asset location that created this dependency */
  readonly sourceAssetId: ?string;
}

/**
 * Options for creating a dependency
 */
interface DependencyOptions {
  /** Import specifier */
  specifier: DependencySpecifier;
  /** Type of import specifier */
  specifierType?: SpecifierType;
  /** Loading priority */
  priority?: DependencyPriority;
  /** Bundle behavior */
  bundleBehavior?: BundleBehavior;
  /** Whether dependency needs stable name */
  needsStableName?: boolean;
  /** Whether dependency is optional */
  isOptional?: boolean;
  /** Whether this is an entry point */
  isEntry?: boolean;
  /** Location in source code */
  loc?: SourceLocation;
  /** Target environment */
  env?: Environment;
  /** Plugin-specific metadata */
  meta?: Meta;
  /** Resolution pipeline */
  pipeline?: string;
  /** Imported symbols */
  symbols?: Map<Symbol, {local: Symbol, loc: ?SourceLocation, isWeak: boolean}>;
}

/**
 * Import specifier types
 */
type SpecifierType = 'commonjs' | 'esm' | 'url' | 'custom';

/**
 * Dependency loading priority
 */
type DependencyPriority = 'sync' | 'parallel' | 'lazy';

/**
 * Bundle behavior for dependencies
 */
type BundleBehavior = 'inline' | 'isolated';

/**
 * Asset exported symbols interface
 */
interface AssetSymbols {
  /** Get exported symbol by name */
  get(exportSymbol: Symbol): ?AssetSymbol;
  /** Check if symbol is exported */
  has(exportSymbol: Symbol): boolean;
  /** Iterate over all exported symbols */
  [Symbol.iterator](): Iterator<[Symbol, AssetSymbol]>;
}

/**
 * Mutable asset symbols interface
 */
interface MutableAssetSymbols extends AssetSymbols {
  /** Set exported symbol */
  set(exportSymbol: Symbol, symbol: AssetSymbol): void;
  /** Delete exported symbol */
  delete(exportSymbol: Symbol): boolean;
  /** Ensure symbol exists */
  ensure(exportSymbol: Symbol, loc: ?SourceLocation): AssetSymbol;
}

/**
 * Individual asset symbol
 */
interface AssetSymbol {
  /** Local name in asset */
  local: Symbol;
  /** Location in source code */
  loc: ?SourceLocation;
  /** Plugin-specific metadata */
  meta?: Meta;
}

/**
 * Dependency symbol mapping
 */
interface MutableDependencySymbols {
  /** Get imported symbol mapping */
  get(exportSymbol: Symbol): ?DependencySymbol;
  /** Set imported symbol mapping */
  set(exportSymbol: Symbol, local: Symbol, opts?: {loc?: SourceLocation, isWeak?: boolean}): void;
  /** Check if symbol is imported */
  has(exportSymbol: Symbol): boolean;
  /** Delete imported symbol */
  delete(exportSymbol: Symbol): boolean;
  /** Ensure symbol mapping exists */
  ensure(exportSymbol: Symbol, local: Symbol, opts?: {loc?: SourceLocation, isWeak?: boolean}): DependencySymbol;
  /** Iterate over symbol mappings */
  [Symbol.iterator](): Iterator<[Symbol, DependencySymbol]>;
}

/**
 * Individual dependency symbol mapping
 */
interface DependencySymbol {
  /** Local name in importing asset */
  local: Symbol;
  /** Location in source code */
  loc: ?SourceLocation;
  /** Whether this is a weak reference */
  isWeak: boolean;
}

/**
 * Asset file and build statistics
 */
interface Stats {
  /** File size in bytes */
  size: number;
  /** Last modified time */
  time: number;
}

import type { 
  MutableAsset, 
  DependencyOptions, 
  TransformerResult 
} from '@parcel/types';

// Transform an asset
async function transformAsset(asset: MutableAsset): Promise<Array<TransformerResult>> {
  // Get the source code
  const code = await asset.getCode();
  
  // Add a dependency
  const depId = asset.addDependency({
    specifier: './utils',
    specifierType: 'esm',
    priority: 'sync'
  });
  
  // Add a URL dependency for an image
  asset.addURLDependency('./logo.png', {
    priority: 'lazy'
  });
  
  // Modify the code
  const transformedCode = `// Generated code\n${code}`;
  asset.setCode(transformedCode);
  
  // Set metadata
  asset.meta.transformed = true;
  
  return [asset];
}

// Work with asset symbols
async function processSymbols(asset: MutableAsset) {
  const symbols = await asset.getSymbols();
  
  // Export a new symbol
  symbols.set('myExport', {
    local: 'internalName',
    loc: { line: 1, column: 0 }
  });
  
  // Check for existing export
  if (symbols.has('default')) {
    const defaultSymbol = symbols.get('default');
    console.log('Default export:', defaultSymbol?.local);
  }
}