0
# Asset System
1

2
Asset representation and manipulation for the build pipeline, including dependency tracking, transformation, and immutable/mutable interfaces.
3

4
## Capabilities
5

6
### Base Asset Interface
7

8
Core asset properties and methods shared by all asset types.
9

10
```typescript { .api }
11
/**
12
 * Base asset interface with core properties and methods
13
 */
14
interface BaseAsset {
15
  /** Unique asset identifier */
16
  readonly id: string;
17
  /** File system instance for this asset */
18
  readonly fs: FileSystem;
19
  /** Path to the source file */
20
  readonly filePath: FilePath;
21
  /** Asset type (e.g., 'js', 'css', 'html') */
22
  readonly type: string;
23
  /** Query string from import (e.g., '?inline') */
24
  readonly query: URLSearchParams;
25
  /** Target environment for this asset */
26
  readonly env: Environment;
27
  /** Whether this is a source file (not generated) */
28
  readonly isSource: boolean;
29
  /** Plugin-specific metadata */
30
  readonly meta: Meta;
31
  /** Pipeline configuration for this asset */
32
  readonly pipeline: ?string;
33
  /** Asset statistics */
34
  readonly stats: Stats;
35
  
36
  /** Get the source code as a string */
37
  getCode(): Promise<string>;
38
  /** Get the source code as a buffer */
39
  getBuffer(): Promise<Buffer>;
40
  /** Get the source code as a readable stream */
41
  getStream(): Readable;
42
  /** Get the parsed AST for this asset */
43
  getAST(): Promise<AST>;
44
  /** Get the source map for this asset */
45
  getMap(): Promise<?SourceMap>;
46
  /** Get all dependencies of this asset */
47
  getDependencies(): Array<Dependency>;
48
  /** Get exported symbols from this asset */
49
  getSymbols(): Promise<AssetSymbols>;
50
}
51
```
52

53
### Mutable Asset Interface
54

55
Asset interface used during transformation with methods to modify content and dependencies.
56

57
```typescript { .api }
58
/**
59
 * Mutable asset interface for transformation phase
60
 */
61
interface MutableAsset extends BaseAsset {
62
  /** Asset type (mutable) */
63
  type: string;
64
  /** Whether this is a source file (mutable) */
65
  isSource: boolean;
66
  /** Target environment (mutable) */
67
  env: Environment;
68
  /** Plugin-specific metadata (mutable) */
69
  meta: Meta;
70
  /** Asset statistics (mutable) */
71
  stats: Stats;
72
  
73
  /** Set the source code */
74
  setCode(code: string): void;
75
  /** Set the source buffer */
76
  setBuffer(buffer: Buffer): void;
77
  /** Set the source stream */
78
  setStream(stream: Readable): void;
79
  /** Set the parsed AST */
80
  setAST(ast: AST): void;
81
  /** Set the source map */
82
  setMap(map: ?SourceMap): void;
83
  
84
  /** Add a dependency to another asset */
85
  addDependency(dep: DependencyOptions): string;
86
  /** Add a URL dependency (for assets like images, fonts) */
87
  addURLDependency(url: string, opts?: $Shape<DependencyOptions>): string;
88
  
89
  /** Invalidate the asset when a file is created */
90
  invalidateOnFileCreate(invalidation: FileCreateInvalidation): void;
91
  /** Invalidate the asset when environment variables change */
92
  invalidateOnEnvChange(env: string): void;
93
  /** Invalidate the asset when build options change */
94
  invalidateOnOptionChange(option: string): void;
95
  
96
  /** Get mutable exported symbols */
97
  getSymbols(): Promise<MutableAssetSymbols>;
98
}
99
```
100

101
### Immutable Asset Interface
102

103
Final asset interface after transformation with immutable properties.
104

105
```typescript { .api }
106
/**
107
 * Immutable asset interface for final build output
108
 */
109
interface Asset extends BaseAsset {
110
  /** Asset file statistics */
111
  readonly stats: Stats;
112
}
113
```
114

115
### Dependency System
116

117
Asset dependency representation and configuration.
118

119
```typescript { .api }
120
/**
121
 * Asset dependency interface
122
 */
123
interface Dependency {
124
  /** Unique dependency identifier */
125
  readonly id: string;
126
  /** Import specifier (e.g., './utils', 'lodash') */
127
  readonly specifier: DependencySpecifier;
128
  /** Type of import specifier */
129
  readonly specifierType: SpecifierType;
130
  /** Loading priority */
131
  readonly priority: DependencyPriority;
132
  /** Bundle behavior for this dependency */
133
  readonly bundleBehavior: ?BundleBehavior;
134
  /** Whether this dependency needs a stable name */
135
  readonly needsStableName: boolean;
136
  /** Whether this dependency is optional */
137
  readonly isOptional: boolean;
138
  /** Whether this is an entry point */
139
  readonly isEntry: boolean;
140
  /** Location in source code */
141
  readonly loc: ?SourceLocation;
142
  /** Target environment */
143
  readonly env: Environment;
144
  /** Imported/exported symbols */
145
  readonly symbols: MutableDependencySymbols;
146
  /** Pipeline to use for resolution */
147
  readonly pipeline: ?string;
148
  /** Plugin-specific metadata */
149
  readonly meta: Meta;
150
  /** Asset that owns this dependency */
151
  readonly sourcePath: FilePath;
152
  /** Asset location that created this dependency */
153
  readonly sourceAssetId: ?string;
154
}
155

156
/**
157
 * Options for creating a dependency
158
 */
159
interface DependencyOptions {
160
  /** Import specifier */
161
  specifier: DependencySpecifier;
162
  /** Type of import specifier */
163
  specifierType?: SpecifierType;
164
  /** Loading priority */
165
  priority?: DependencyPriority;
166
  /** Bundle behavior */
167
  bundleBehavior?: BundleBehavior;
168
  /** Whether dependency needs stable name */
169
  needsStableName?: boolean;
170
  /** Whether dependency is optional */
171
  isOptional?: boolean;
172
  /** Whether this is an entry point */
173
  isEntry?: boolean;
174
  /** Location in source code */
175
  loc?: SourceLocation;
176
  /** Target environment */
177
  env?: Environment;
178
  /** Plugin-specific metadata */
179
  meta?: Meta;
180
  /** Resolution pipeline */
181
  pipeline?: string;
182
  /** Imported symbols */
183
  symbols?: Map<Symbol, {local: Symbol, loc: ?SourceLocation, isWeak: boolean}>;
184
}
185
```
186

187
### Dependency Types
188

189
Configuration types for different dependency characteristics.
190

191
```typescript { .api }
192
/**
193
 * Import specifier types
194
 */
195
type SpecifierType = 'commonjs' | 'esm' | 'url' | 'custom';
196

197
/**
198
 * Dependency loading priority
199
 */
200
type DependencyPriority = 'sync' | 'parallel' | 'lazy';
201

202
/**
203
 * Bundle behavior for dependencies
204
 */
205
type BundleBehavior = 'inline' | 'isolated';
206
```
207

208
### Symbol System
209

210
Asset symbol management for imports and exports.
211

212
```typescript { .api }
213
/**
214
 * Asset exported symbols interface
215
 */
216
interface AssetSymbols {
217
  /** Get exported symbol by name */
218
  get(exportSymbol: Symbol): ?AssetSymbol;
219
  /** Check if symbol is exported */
220
  has(exportSymbol: Symbol): boolean;
221
  /** Iterate over all exported symbols */
222
  [Symbol.iterator](): Iterator<[Symbol, AssetSymbol]>;
223
}
224

225
/**
226
 * Mutable asset symbols interface
227
 */
228
interface MutableAssetSymbols extends AssetSymbols {
229
  /** Set exported symbol */
230
  set(exportSymbol: Symbol, symbol: AssetSymbol): void;
231
  /** Delete exported symbol */
232
  delete(exportSymbol: Symbol): boolean;
233
  /** Ensure symbol exists */
234
  ensure(exportSymbol: Symbol, loc: ?SourceLocation): AssetSymbol;
235
}
236

237
/**
238
 * Individual asset symbol
239
 */
240
interface AssetSymbol {
241
  /** Local name in asset */
242
  local: Symbol;
243
  /** Location in source code */
244
  loc: ?SourceLocation;
245
  /** Plugin-specific metadata */
246
  meta?: Meta;
247
}
248

249
/**
250
 * Dependency symbol mapping
251
 */
252
interface MutableDependencySymbols {
253
  /** Get imported symbol mapping */
254
  get(exportSymbol: Symbol): ?DependencySymbol;
255
  /** Set imported symbol mapping */
256
  set(exportSymbol: Symbol, local: Symbol, opts?: {loc?: SourceLocation, isWeak?: boolean}): void;
257
  /** Check if symbol is imported */
258
  has(exportSymbol: Symbol): boolean;
259
  /** Delete imported symbol */
260
  delete(exportSymbol: Symbol): boolean;
261
  /** Ensure symbol mapping exists */
262
  ensure(exportSymbol: Symbol, local: Symbol, opts?: {loc?: SourceLocation, isWeak?: boolean}): DependencySymbol;
263
  /** Iterate over symbol mappings */
264
  [Symbol.iterator](): Iterator<[Symbol, DependencySymbol]>;
265
}
266

267
/**
268
 * Individual dependency symbol mapping
269
 */
270
interface DependencySymbol {
271
  /** Local name in importing asset */
272
  local: Symbol;
273
  /** Location in source code */
274
  loc: ?SourceLocation;
275
  /** Whether this is a weak reference */
276
  isWeak: boolean;
277
}
278
```
279

280
### Asset Statistics
281

282
File and build statistics for assets.
283

284
```typescript { .api }
285
/**
286
 * Asset file and build statistics
287
 */
288
interface Stats {
289
  /** File size in bytes */
290
  size: number;
291
  /** Last modified time */
292
  time: number;
293
}
294
```
295

296
**Usage Examples:**
297

298
```typescript
299
import type { 
300
  MutableAsset, 
301
  DependencyOptions, 
302
  TransformerResult 
303
} from '@parcel/types';
304

305
// Transform an asset
306
async function transformAsset(asset: MutableAsset): Promise<Array<TransformerResult>> {
307
  // Get the source code
308
  const code = await asset.getCode();
309
  
310
  // Add a dependency
311
  const depId = asset.addDependency({
312
    specifier: './utils',
313
    specifierType: 'esm',
314
    priority: 'sync'
315
  });
316
  
317
  // Add a URL dependency for an image
318
  asset.addURLDependency('./logo.png', {
319
    priority: 'lazy'
320
  });
321
  
322
  // Modify the code
323
  const transformedCode = `// Generated code\n${code}`;
324
  asset.setCode(transformedCode);
325
  
326
  // Set metadata
327
  asset.meta.transformed = true;
328
  
329
  return [asset];
330
}
331

332
// Work with asset symbols
333
async function processSymbols(asset: MutableAsset) {
334
  const symbols = await asset.getSymbols();
335
  
336
  // Export a new symbol
337
  symbols.set('myExport', {
338
    local: 'internalName',
339
    loc: { line: 1, column: 0 }
340
  });
341
  
342
  // Check for existing export
343
  if (symbols.has('default')) {
344
    const defaultSymbol = symbols.get('default');
345
    console.log('Default export:', defaultSymbol?.local);
346
  }
347
}
348
```