@poppinss/macroable

Extend classes from outside in using Macros and getters

Macroable offers a simple API for adding properties and getters to the class prototype. You might not even need this package, if you are happy writing Object.defineProperty calls yourself.

Usage

Install the package from npm packages registry as follows.

npm i @poppinss/macroable

# yarn lovers
yarn add @poppinss/macroable

And import the Macroable class.

import Macroable from '@poppinss/macroable'
export class Route extends Macroable {}

Now, you can add properties to the Route class from outside-in. This is usually needed, when you want the consumer of your classes to be able to extend them by adding custom properties.

Macros

Getters are added to the class prototype directly.

Route.macro('head', function (uri, callback) {
  return this.route(['HEAD'], uri, callback)
})

And now, you can will be use the head method from an instance of the Route class.

const route = new Route()
route.head('/', () => {})

Adding a macro is same as writing the following code in JavaScript.

Route.prototype.head = function () {
}

Instance properties

Since, macros are defined on the prototype of the class and therefore they loose the this context when destructured from the class instance. For example:

HttpContext.macro('getUser', function (this: HttpContext) {
  return this.auth.user
})

const { getUser } = ctx
getUser() // ❌ Error: Cannot read property auth of undefined

In order to fix this issue, the properties that can be destructured must be defined as instance properties on the class.

HttpContext.instanceProperty('getUser', function (this: HttpContext) {
  return this.auth.user
})

const { getUser } = ctx
getUser() // ✅ Works fine

Getters

Getters are added to the class prototype using the Object.defineProperty. The implementation of a getter is always a function.

Route.getter('version', function () {
  return 'v1'
})

And now access the version as follows.

const route = new Route()
route.version // v1

Adding a getter is same as writing the following code in JavaScript.

Object.defineProperty(Route.prototype, 'version', {
  get() {
    const value = callback()
    return value
  },
  configurable: false,
  enumerable: false,
})

Singleton getters

Singleton getters are also defined on the class prototype. However, their values are cached after the first access.

const singleton = true

Mysql.getter('version', function () {
  return this.config.driver.split('-')[1]
}, singleton)

Adding a singleton getter is same as writing the following code in JavaScript.

Object.defineProperty(Mysql.prototype, 'version', {
  get() {
    const value = callback()

    // Cache value on the class instance
    Object.defineProperty(this, 'version', {
      configurable: false,
      enumerable: false,
      value: value,
      writable: false,
    })

    return value
  },
  configurable: false,
  enumerable: false,
})

TypeScript types

You will have to use module augmentation in order to define the types for the dynamically added properties.

Contributing

One of our primary goals is to have a vibrant community of users and contributors who believes in the principles of the framework.

We encourage you to read the contribution guide before contributing to the framework.

Code of Conduct

In order to ensure that the community is welcoming to all, please review and abide by the Code of Conduct.

License

Poppinss macroable is open-sourced software licensed under the MIT license.