TypeScript Reference

Overview

expressCode includes full TypeScript support for writing After Effects scripts. TypeScript provides:

• Type safety: Catch errors before running
• IntelliSense: Auto-completion and parameter hints
• Documentation: Hover over APIs to see descriptions
• Modern syntax: Use ES6+ features that transpile to ES3

Enabling TypeScript

1. Switch to Script mode using the mode toggle in the header
2. Click the TS toggle in the footer to switch from JavaScript to TypeScript
3. Start writing TypeScript code

The editor will immediately provide type checking and IntelliSense.

Type Definitions

expressCode includes type definitions for:

• After Effects API: Full types for app, project, CompItem, Layer, etc.
• ExtendScript: Types for File, Folder, Socket, etc.
• Standard Library: ES3/ES5 types for Array, String, Object, etc.

After Effects Types

All After Effects scripting API types are available:

// Get the active composition with proper typing
const comp = app.project.activeItem as CompItem;

// Access properties with autocomplete
const width = comp.width;
const height = comp.height;
const duration = comp.duration;

// Create layers with type safety
const layer = comp.layers.addSolid([1, 0, 0], "Red Solid", width, height, 1.0);

// Access transform properties
const transform = layer.property("ADBE Transform Group") as PropertyGroup;
const position = transform.property("ADBE Position") as Property;

// Access effects (note: use .effect, not .Effects)
const blur = layer.effect.addProperty("ADBE Gaussian Blur 2");

Type Assertions

Use type assertions when the type system can't infer the exact type:

// Assert that activeItem is a CompItem
const comp = app.project.activeItem as CompItem;

// Assert property types
const position = layer.property("Position") as Property;
const effects = layer.property("ADBE Effect Parade") as PropertyGroup;

Type Guards

Create type guards to safely check types at runtime:

function isCompItem(item: any): item is CompItem {
  return item && item instanceof CompItem;
}

const activeItem = app.project.activeItem;
if (isCompItem(activeItem)) {
  // TypeScript knows activeItem is a CompItem here
  alert("Composition: " + activeItem.name);
}

Transpilation

When you run a TypeScript script, expressCode automatically:

1. Type checks your code
2. Transpiles to ES3-compatible JavaScript
3. Transforms ES5 methods (see ES5 Helper Reference)
4. Prepends helper functions
5. Runs in After Effects

Transpilation Settings

The TypeScript compiler is configured for After Effects:

• Target: ES3 (ExtendScript compatibility)
• Module: None (no module system)
• Strict: Enabled (maximum type safety)
• Lib: ES5 (for type definitions, not runtime)

What Gets Transpiled

TypeScript features that are transpiled to ES3:

• ✅ Arrow functions → function declarations
• ✅ const/let → var
• ✅ Template literals → String concatenation
• ✅ Destructuring → Individual assignments
• ✅ Classes → ES3 constructor functions
• ✅ Default parameters → Runtime checks
• ✅ Spread operator → Manual copying
• ✅ For-of loops → Traditional for loops

Features that are NOT available (ES6+ runtime features):

• ❌ Promises, async/await
• ❌ Symbols
• ❌ Proxies
• ❌ WeakMap/WeakSet
• ❌ Generators

IntelliSense Features

Auto-Completion

Type to see suggestions:

// Type "app." to see all Application methods
app.

// Type "comp." to see all CompItem properties
comp.

// Type "layer." to see all Layer properties
layer.

Parameter Hints

See function signatures as you type:

// Shows: addSolid(color: [number, number, number],
//                 name: string,
//                 width: number,
//                 height: number,
//                 pixelAspect: number): AVLayer,
//                 duration?: number | undefined
const comp = app.project.activeItem as CompItem;
comp.layers.addSolid([1, 0, 0], "Red", 1920, 1080, 1.0);

Hover Documentation

Hover over any API to see its description:

// Hover over "selection" to see:
// "All items selected in the Project panel"
app.project.selection

Error Detection

TypeScript catches errors before you run:

// Error: Type 'string' is not assignable to type 'number'
const width: number = "1920";

const comp = app.project.activeItem as CompItem;

// Error: Property 'nonexistent' does not exist on type 'CompItem'
comp.nonexistent;

// Error: Expected 5-6 arguments, but got 3
comp.layers.addSolid([1, 0, 0], "Red", 1920);

Troubleshooting

Type Errors

If you see type errors that you believe are incorrect:

1. Check the type definitions: Hover over the API to see the expected type
2. Use type assertions: Cast to the correct type if you know better
3. Report issues: If the type definitions are wrong, file an issue

Transpilation Errors

If your script fails to transpile:

1. Check for ES6+ features: Not all features are supported
2. Review error messages: TypeScript errors are usually very descriptive
3. Simplify your code: Break complex expressions into multiple statements

Runtime Errors

If your script transpiles but fails at runtime:

1. Check the error message: Look for line numbers and stack traces
2. Test incrementally: Run small parts of your script first
3. Use try-catch: Wrap risky operations in error handling

See Also

• ES5 Helper Reference - Modern array/string methods in TypeScript
• User Guide - Complete guide to using expressCode
• After Effects Scripting Guide - Official Adobe documentation