Metal.js AOP Utility

Common errors

• TypeError: Aop.before is not a function

  cause The Aop object was not correctly imported or is not available in the scope, or the `before` method does not exist on the imported object.
  fix Ensure `const Aop = require('metal-aop');` is at the top of your file and that `metal-aop` is correctly installed. Verify the AOP object provides a `before` method as expected.

• Cannot read properties of undefined (reading 'doSomething')

  cause The target object passed to an AOP method (e.g., `Aop.before`) is `undefined` or `null`, meaning the aspect is trying to attach to a non-existent object.
  fix Ensure the object you are trying to apply AOP to (e.g., `myServiceInstance`) is properly instantiated and not `null` or `undefined` before calling any `Aop` methods on it.

Warnings

• breaking The Metal.js framework, which metal-aop is built upon, has been officially deprecated. This means metal-aop is effectively abandoned and will not receive updates, bug fixes, or security patches. Running this library in modern environments without careful consideration may lead to compatibility issues or unpatched vulnerabilities.
  Fix: Migrate to a actively maintained AOP solution or a different framework. If continued use is unavoidable, significant testing and custom patching may be required.
• gotcha Compatibility with modern JavaScript (ESM, async/await, newer Node.js versions) is not guaranteed due to the library's age and abandoned status. Its design predates many modern language features and module systems.
  Fix: Use a CommonJS environment or a transpilation step that targets older JavaScript versions. Avoid using with module bundlers that heavily rely on ESM unless configured for CJS compatibility.
• gotcha Integrating `metal-aop` with other modern frontend libraries or frameworks (e.g., React, Vue, Angular) is highly discouraged. It was designed for the Metal.js ecosystem and may cause unexpected conflicts or performance issues outside of it.
  Fix: For new projects or integrations, choose AOP solutions that are actively maintained and compatible with your current technology stack.

Install

• npm install metal-aop npm
• yarn add metal-aop yarn
• pnpm add metal-aop pnpm

Imports

• Aop
  wrong:

  import { Aop } from 'metal-aop';

  correct:

  const Aop = require('metal-aop');

  Given the package's age (last published ~8 years ago) and Node.js engine requirement (>=0.12.0), CommonJS `require` is the primary and most compatible import mechanism. ESM `import` syntax is unlikely to be supported without a transpiler or later version.
• Aspect
  wrong:

  import Aspect from 'metal-aop';

  correct:

  const { Aspect } = require('metal-aop');

  If specific AOP constructs like an 'Aspect' factory or class were exposed, they would likely be named exports via CommonJS `require` destructuring, consistent with the package's publication era.
• before
  wrong:

  import { before } from 'metal-aop';

  correct:

  const { before } = require('metal-aop/src/aop'); // Example for a specific advice type

  Specific advice types (like 'before', 'after', 'around') might have been exposed as individual functions or part of a main 'Aop' object. Direct import from internal paths (`src/aop`) would be a common CJS pattern for older libraries exposing smaller utilities.

Quickstart

This quickstart demonstrates how to apply 'before', 'after', and 'around' advice to methods of a class using metal-aop, illustrating basic Aspect-Oriented Programming (AOP) concepts like interception.

const Aop = require('metal-aop');

class MyService {
  doSomething(data) {
    console.log(`Processing data: ${data}`);
    return `Result for ${data}`;
  }

  anotherMethod() {
    console.log('Another method called.');
  }
}

const myServiceInstance = new MyService();

// Define a 'before' advice
Aop.before(myServiceInstance, 'doSomething', function(originalArgs) {
  console.log(`[AOP-Before] Preparing to call doSomething with: ${originalArgs[0]}`);
});

// Define an 'after' advice
Aop.after(myServiceInstance, 'doSomething', function(originalArgs, result) {
  console.log(`[AOP-After] doSomething finished. Original args: ${originalArgs[0]}, Result: ${result}`);
});

// Define an 'around' advice
Aop.around(myServiceInstance, 'anotherMethod', function(originalFn) {
  console.log('[AOP-Around] Before calling anotherMethod');
  const result = originalFn(); // Call the original method
  console.log('[AOP-Around] After calling anotherMethod');
  return result;
});

console.log('--- Calling doSomething ---');
myServiceInstance.doSomething('input123');

console.log('\n--- Calling anotherMethod ---');
myServiceInstance.anotherMethod();