@xoid/feature

@xoid/feature is a tiny plugin system oriented in JavaScript classes. It provides a type-safe dependency injection mechanism for the classes that refer to each other's instance variables. It especially improves the developer experience for TypeScript users, by reducing the types and the runtime code that needs to be written (demonstrated below). It provides a neat pattern for tree-shakable plugins.

It has 2 exports: Feature and compose .

Classes that extend from Feature, has the following properties by default:
- There's no need for .constructor.
- .from can be used to share data between sibling instances. (dependency injection part)
- .options can be used anywhere.
- .getOptions can be used to merge external options onto the default options.
- .main will run when all the instances are ready.

Example:

``js
import { Feature, compose } from '@xoid/feature'

class Alpha extends Feature<{ alpha?: number }> {
options = this.getOptions({ alpha: 3 })
alpha = this.options.alpha
}

class Beta extends Feature<{ beta: number }> {
beta = this.options.beta
main() {
console.log('alpha:', this.from(Alpha).alpha)
}
}

class Gamma extends Feature<{ message: string }> {
getSum() {
return ${this.options.message}${this.from(Alpha).alpha + this.from(Beta).beta}
}
}

const init = compose([Alpha, Beta, Gamma], (from) => from(Gamma).getSum())

const result = init({ beta: 2, message: 'The answer is: ' })

console.log(result)
`

Console output:

`
alpha: 3
The answer is: 5
`

Without @xoid/feature, the same functionality would require:

`js
class Alpha {
alpha: number
static defaultOptions = { alpha: 3 }
constructor(options: { alpha?: number }) {
this.alpha = options.alpha ?? Alpha.defaultOptions.alpha
}
}

class Beta {
instances!: { Alpha: Alpha }
beta: number
constructor(options: { beta: number }) {
this.beta = options.beta
}
main(instances: { Alpha: Alpha }) {
this.instances = instances
console.log('alpha:', this.instances.Alpha.alpha)
}
}

class Gamma {
instances!: { Alpha: Alpha; Beta: Beta }
options: { message: string }
constructor(options: { message: string }) {
this.options = options
}
main(instances: { Alpha: Alpha; Beta: Beta }) {
this.instances = instances
}
getResult() {
return ${this.options.message}${this.instances.Alpha.alpha + this.instances.Beta.beta}
}
}

const init = (
options: ConstructorParameters[0] &
ConstructorParameters[0] &
ConstructorParameters[0]
) => {
const context = {} as Record
[Alpha, Beta, Gamma].forEach((item) => {
context[item.name] = new item(options)
})
Object.keys(context).forEach((key) => context[key]?.main(context))
return context.Gamma.getSum()
}

const result = init({ beta: 2, message: 'foo' })

console.log(result)
`

Tree-shaking methodology

/ids/Alpha.tsx (identity module)

`js
export const id = Symbol()
export const type = {} as import('../Alpha').default
`

Modify the following lines in existing files:

/Alpha.tsx (real module)

`diff
import { Feature } from '@xoid/feature'
import { id } from './ids/Alpha'

export default class Alpha extends Feature<{ alpha?: number }> {
+ id = id
options = this.getOptions({ alpha: 3 })
alpha = this.options.alpha
}
`

/Beta.tsx
`diff
- import Alpha from './Alpha'
+ import * as Alpha from './ids/Alpha'

class Beta extends Feature() {
main() {
console.log(this.from(Alpha).alpha) // This used to work, and still works after the diff
}
}
`

Augmentation technique

There's a neat type-safety helper built-in to @xoid/feature. The callback argument of compose has a second agrument called types. types should not be used in the runtime, it only serves as a type aggregator. types merges the types of all the classes that are composed. In the following example, draggableProps key is used multiple times in different features, so that each feature "augments" the same interface. Finally types is fed as a parameter type to useDraggable

`js
import { Feature, compose } from '@xoid/feature'

class DragHelper extends Feature() {
draggableProps!: {
onDragStart: () => void
onDragEnd: () => void
}
}

class DropHelper extends Feature() {
draggableProps!: {
onDrop: () => void
}
}

const createDraggable = compose(
[DragHelper, DropHelper],
(from, types) => {
const useDraggable = (props: typeof types.draggableProps) => {
// TODO: implement helper
}
return { useDraggable }
}
)

const { useDraggable } = createDraggable({})

// This whole thing would be typesafe thanks to the types
useDraggable({ onDragStart, onDragEnd, onDrop })
`

Note

@xoid/feature doesn't depend on xoid. It can be used standalone, however using it with xoid` is synergetically amazing.