Skip to content
ECP-SolutionsPublic

About

The Advanced Scripting Framework is a modern scripting for VBA: JavaScript-like syntax, classes with inheritance, map/filter/reduce, closures, regex. No COM, works everywhere. Transform Excel automation.

Topics

Resources

Contributing

Stars

41 stars

Watchers

2 watching

Forks

Latest commit

 

History

522 Commits

Folders and files

Repository files navigation

Advanced Scripting Framework (ASF)

ASF FOSSA Status

Tests (Rubberduck) License: MIT GitHub release (latest by date) Mentioned in Awesome VBA

JavaScript-like scripting language implemented entirely in VBA. Zero COM dependencies. Native Office object model integration with runtime monkey patching capabilities.

Dim engine As New ASF
engine.Run engine.Compile("return [1,2,3,4,5].filter(fun(x){ return x > 2 }).reduce(fun(a,x){ return a+x }, 0)")
Debug.Print engine.OUTPUT_  ' => 12

Official Extension

ASF VS Code extension provides syntax highlighting and language support.

✔️ Live Coding 🚀
VS Code Integration ASF-code

Excel add-in

excel/ASF.xlam installs ASF once for every workbook: the worksheet functions ASF_RUN and ASF_CALL run scripts in plain .xlsx files, with the regex functions RX_TEST, RX_EXTRACT, RX_REPLACE and RX_COUNT, and macros of other workbooks get an engine from it. Build, installation and the security model: excel/README.md.

LibreOffice

ASF also runs on LibreOffice as the ASF.oxt extension, generated from the same sources. Installation, usage and differences: libreoffice/README.md.

The same .vas scripts run in the whole of both suites: the seven of examples/portable write a sheet in Excel or Calc, a document in Word or Writer and slides in PowerPoint or Impress, through one small host per suite.

examples/use-cases shows four ways to put ASF to work, each with code that runs and is checked: business rules that users edit in a sheet, regular expressions as worksheet functions in Excel (Windows and Mac) and Calc, data pipelines that read a sheet once and write it once, and JavaScript-style classes and modules across the office suites.

GlobalScope.BasicLibraries.LoadLibrary "ASF"
Dim engine As Object: Set engine = ASF.LOhelper.NewASF()
engine.Run engine.Compile("return [1,2,3,4,5].filter(fun(x){ return x > 2 }).reduce(fun(a,x){ return a+x }, 0)")
MsgBox engine.OUTPUT_   ' => 12

📚 Documentation

Core Features

Language Features:

  • Full JavaScript-like syntax with lexical scoping
  • First-class functions, closures, and arrow function equivalents
  • ES6+ array methods (map, filter, reduce, find, etc.)
  • Object/array literals with spread/rest operators
  • Classes with inheritance (extends, super)
  • Built-in regex engine with lookarounds
  • Template literals and destructuring assignment

VBA Integration:

  • Seamless VBA Object model integration.
  • A lot of advanced function available through VBA-Expressions via @(...) syntax
  • Variable injection between VBA and ASF contexts
  • Native array/collection marshalling
  • Error containment and debugging support

Architecture:

  • Pure VBA implementation (no external dependencies)
  • Sandboxed VM execution with call stack tracing and toggle configuration for object model accessibility
  • 32-bit and 64-bit Office compatibility
  • Module system with import/export support

Advanced Office Integration

COM Object Model Extension

ASF can dynamically extend native Office objects at runtime using prototype-based monkey patching:

// Extend Excel ListRow objects with custom methods
prototype.COM.ListRow asDictionary() {
    let headers = this.parent.listcolumns;
    let values = this.range.value2;
    let result = {};
    for (let i = 1, i <= headers.count, i+=1) {
        result.set(headers.item(i).name, values[1][i]);
    };
    return result;
};

// Usage: ListRows now have .asDictionary() method
let data = $1.Sheets(1).ListObjects('Table1').ListRows.map(
    fun(row) { return row.asDictionary().get('email'); }
);

This enables:

  • Runtime method injection into COM objects
  • JavaScript-like method chaining on Office objects
  • Functional programming patterns on traditional VBA collections
  • Context-aware this binding preserving COM object references

Collection Method Override

The OverrideCollMethods option replaces native VBA collection behavior with JavaScript array semantics:

' Enable collection override (USE WITH CAUTION)
engine.OverrideCollMethods = True

This transforms VBA Collections into JavaScript-like arrays with:

  • Array iteration methods (map, filter, forEach)
  • Immutable operations (slice, concat, toSorted)
  • Modern array methods (find, includes, at)
  • Destructuring and spread operator support

⚠️ Warning: This modifies fundamental Office object behavior and may break existing VBA code expectations.

Quick Start (5 Minutes)

Step 1: Installation

  1. Download the latest release
  2. Import these class modules into your VBA project:
    • ASF.cls (main engine)
    • ASF_Compiler.cls
    • ASF_VM.cls
    • ASF_Runtime.cls
    • ASF_Parser.cls
    • ASF_Globals.cls
    • ASF_Map.cls
    • ASF_RegexEngine.cls
    • UDFunctions.cls
    • VBAcallBack.cls
    • VBAexpressions.cls
    • VBAexpressionsScope.cls

Step 2: Hello World

Sub HelloASF()
    Dim engine As New ASF
    Dim idx As Long
    
    ' Compile ASF code
    idx = engine.Compile("print('Hello from ASF!')")
    
    ' Run it
    engine.Run idx
End Sub

Step 3: Real-World Example

Scenario: Filter and sum sales data over $1000

Sub ProcessSalesData()
    Dim engine As New ASF
    Dim script As String
    
    script = _
        "sales = [850, 1200, 950, 2500, 1100, 600];" & _
        "highValue = sales.filter(fun(x) { return x > 1000 });" & _
        "total = highValue.reduce(fun(sum, item) { return sum + item }, 0);" & _
        "return total;"
    
    engine.Run engine.Compile(script)
    Debug.Print "High-value sales total: $" & engine.OUTPUT_  ' => $4800
End Sub

Step 4: VBA Integration

Call VBA-Expressions functions from ASF using @(...):

' In UDFunctions.cls
Public Function GetTaxRate(fakeArg As Variant) As Variant
    GetTaxRate = 0.08
End Function

' In your VBA code
Sub CalculateTotal()
    Dim asfGlobals As New ASF_Globals
    asfGlobals.ASF_InitGlobals
    asfGlobals.gExprEvaluator.DeclareUDF "GetTaxRate", "UserDefFunctions"
    
    Dim engine As New ASF
    engine.SetGlobals asfGlobals
    
    Dim script As String
    script = _
        "price = 100;" & _
        "tax = price * @(GetTaxRate());" & _
        "return price + tax;"
    
    engine.Run engine.Compile(script)
    Debug.Print "Total with tax: $" & engine.OUTPUT_  ' => $108
End Sub

That's it! You're now using modern scripting in VBA.

NOTE: VBA function calls require a single Variant parameter as per VBA-Expressions requirements.


Technical Architecture

Compilation Pipeline

  1. Lexical Analysis: Pure VBA tokenizer with support for ES6+ syntax
  2. Compilation: One pass from the tokens to bytecode in Long arrays, with the scope analysis (locals, closures over shared cells, globals by slot) and constant folding; no AST is built
  3. Execution: A virtual machine that runs the bytecode in one dispatch loop, with frames on arrays and a preallocated value stack, and proper this binding

VM Features

  • Lexical Scoping: Names resolved at compile time to local slots, closure cells or global slots; closures share cells with the function that created them
  • Prototype Chain: JavaScript-like prototype inheritance
  • Call Stack Management: Frames on arrays inside the dispatch loop: a call between script functions is not a VBA call
  • Memory Management: Cells and closure environments live in arrays of the VM, cleared at the end of each Run (those of loaded modules stay until ClearModuleCache), so closures do not form reference cycles
  • Error Handling: Contained exceptions with full stack traces

Bytecode (ASF 4)

Since version 4.0, ASF compiles every script to bytecode: ASF_Compiler compiles from the tokens, ASF_VM runs the code, and ASF_Runtime holds the library of values (methods of arrays, strings, objects and collections, Math, regex, printing, host objects, @(...)). Scripts run 2.5 to 80 times faster than on ASF 3.2.1, which walked an AST (about 20 times on typical scripts), with no option to set: every engine runs bytecode. src/BYTECODE.md describes the design.

ASF 3.2.1 is kept in src/old/: the AST engine as ASF 3 users run it (ASF 3.3 and 3.4 added their speed-ups behind conditional compilation arguments and a setting of each engine). Its classes have the suffix _OLD (ASF_OLD, ASF_VM_OLD...), so both versions can be imported into one project, to compare them or to keep a script on the old engine while it is checked on the new one.

When to Use ASF

✅ Optimal Use Cases

  • Complex Data Processing: ETL pipelines, JSON parsing, nested transformations
  • Dynamic Business Logic: User-configurable rules without VBA recompilation
  • Functional Programming: When map/filter/reduce patterns improve readability
  • Office Object Extension: Adding custom methods to native Excel/Word objects
  • Developer Productivity: Rapid prototyping with familiar JavaScript syntax

⚠️ Use Native VBA For

  • Performance-Critical Code: Tight loops processing millions of items
  • Direct COM Interop: Extensive Office API manipulation
  • Memory-Constrained Environments: When every KB matters
  • Type Safety Requirements: Compile-time checking and IntelliSense

🤝 Hybrid Approach

Use ASF for complex logic and VBA for performance hotspots:

' ASF for business logic
Dim businessRules As String: businessRules = "return data.filter(fun(x) { return x.status == 'active' }).map(fun(x) { return x.value * 1.08; })"
Dim processedData As Variant: processedData = engine.Run(engine.Compile(businessRules))

' VBA for bulk Excel operations
Range("A1").Resize(UBound(processedData), 1).Value2 = Application.Transpose(processedData)

Debugging & Troubleshooting

Common Issues

Type mismatch with arrays

' ❌ Won't work
engine.Compile("arr = " & Join(myArray, ","))

' ✅ Correct
engine.InjectVariable "arr", myArray
engine.Compile("print(arr[1])")

COM object access

' ❌ Won't work
script = "Range('A1').Value2 = 10"

' ✅ Use placeholder pseudo injection 
script = "$1.Range('A1').Value2 = 10"
pid = engine.Compile(script)
engine.Run pid, ThisWorkbook.Sheets(1)

Contributing

  • Issues: GitHub Issues
  • Pull Requests: Include comprehensive tests
  • Documentation: Examples and technical deep-dives welcome
  • Enterprise Support: Tag issues with "Enterprise"

License

MIT License - Copyright © 2026 W. García

FOSSA Status

Star History

Star History Chart


Modern scripting for VBA. Zero compromises.

📚 Documentation • 🐛 Report Bug • 💡 Request Feature • ⭐ Star on GitHub

About

The Advanced Scripting Framework is a modern scripting for VBA: JavaScript-like syntax, classes with inheritance, map/filter/reduce, closures, regex. No COM, works everywhere. Transform Excel automation.

Topics

Resources

Contributing

Stars

41 stars

Watchers

2 watching

Forks

Releases

Sponsor this project

Contributors

Languages