AspectScript

An implementation of the AspectScript extension language for JavaScript, based on the AOSD 2010 paper "AspectScript: Expressive Aspects for the Web".

Quick start (npm)

Install:

npm install aspectscript

JavaScript example

const AJS = require("aspectscript");
const PCs = AJS.Pointcuts;

AJS.before(PCs.event("purchase"), function (jp) {
  console.log("purchase observed:", jp.orderId, jp.total);
});

AJS.event("purchase", { orderId: "A-100", total: 42 }, function () {
  console.log("inside purchase block");
});

TypeScript example

import AspectScript = require("aspectscript");

const AJS = AspectScript;
const PCs = AJS.Pointcuts;

AJS.around(PCs.event("audit"), (jp) => {
  console.log("audit event:", jp.action);
  return jp.proceed();
});

AJS.event("audit", { action: "DELETE_USER" }, () => {
  console.log("business logic");
});

Running instrumented scripts (exec, call, get, set, ...)

Use the CLI runner so your file is instrumented automatically:

npx aspectscript run your-script.js

What is included

• A runtime and source instrumenter for AspectScript.
• A Node-based test runner that executes the original tests/test*.js suite while ignoring legacy load(...) lines.
• A CLI command (aspectscript) for running scripts and tests.
• TypeScript type definitions (index.d.ts).
• A static playground in docs/ with:
  • editable examples
  • execution output
  • join point tracing

Local usage

Install dependencies:

npm install

Run the test suite:

npm test

Run with cache statistics:

node run-tests.js --cache-stats

Run only failed tests from the previous run:

npm run test:failed

Run any script/example file with AspectScript runtime + instrumentation:

npm run run:script -- tests/test-ex.js

Run and export execution trace as JSON:

npm run run:script -- tests/test-ex.js --trace-json trace.json

Disable transform cache for a run:

npm run run:script -- tests/test-ex.js --no-cache
node run-tests.js --no-cache

Run paper-aligned conformance examples:

npm run test:conformance

Use the CLI command:

npx aspectscript run tests/test-ex.js
npx aspectscript test
npx aspectscript test --failed

Serve the playground locally from docs/:

cd docs
python3 -m http.server 4173

Then open http://127.0.0.1:4173.

GitHub guide

For a full command-line and GitHub usage guide, see GITHUB_USAGE.md. For practical examples/patterns, see PATTERNS.md. For package publishing readiness, see NPM_PUBLISH.md.

Current test status

The current implementation passes 105 of 105 legacy tests.