Polycons

A framework for building polymorphic constructs. Think of polycons like dependency injection for constructs.

polycons can be used with any CDK framework, including AWS CDK, cdktf, and cdk8s.

🚀 Getting started

Polycons can be used just like ordinary constructs:

import{Dog}from"@acme/shared-polycons";import{Construct}from"constructs";classPetsextendsConstruct{constructor(scope: Construct,id: string){super(scope,id);// this is a polycon!newDog(this,"Dog",{treats: 5});// like ordinary constructs, polycons can have methods, properties, etc.dog.giveBone();}}

This Pets construct contains a Dog from a library of polycons. The dog could have multiple implementations -- a Labrador, a Terrier, or your own implementation.

To use polycons in an application, you need to register a factory that specifies how to turn polycons into concrete constructs. In the example below, a PetFactory is used, which has been defined to resolve each Dog in the construct tree into a Labrador. By registering it to the root App construct, each Dog in the construct tree will be created as a Labrador.

import{App}from"<cdk-framework>";import{PetFactory}from"@acme/shared-polycons";import{Polycons}from"polycons";constapp=newApp();Polycons.register(app,newPetFactory());newPets(app,"MyPets");

Check out the usage guide for more details about how to create your own polycons and polycon factories.

📖 Documentation

Click here to visit the polycons API reference.

🏭 Polycon factories

A polycon factory is a class that implements the IPolyconFactory interface, which has a single resolve() method. This method accepts a type and a list of construct arguments, and returns a concrete construct. For example:

import{DOG_TYPE,CAT_TYPE,Labrador,Kitten}from"@acme/shared-polycons";classPetFactoryimplementsIPolyconFactory{publicresolve(type: string,scope: Construct,id: string,
...args: any[]): Construct{switch(type){caseDOG_TYPE:
returnnewLabrador(scope,id, ...args);caseCAT_TYPE:
returnnewKitten(scope,id, ...args);default:
thrownewError(`Type "${type}" not implemented.`);}}}

In the above example, DOG_TYPE and CAT_TYPE are unique string constants associated with the respective polycons.

By customizing the resolve() method, it's possible to change construct IDs, override properties, or even make factories that call other factories.

✍️ Creating polycons

You can define a new polycon by creating a class that returns a new Polycon instance in its constructor. Each polycon must be associated with a unique identifying string.

import{Constructs}from"constructs";import{Polycons}from"polycons";exportinterfaceDogProps{readonlyname?: string;readonlytreats?: number;}// make sure your polycon has a globally unique name!exportconstDOG_TYPE="@acme/shared-polycons.Dog";exportclassDogextendsConstruct{constructor(scope: Construct,id: string,props: DogProps){super(nullasany,id);// (1)returnPolycons.newInstance(DOG_TYPE,scope,id,props)asDog;}}

The Dog class definition serves as an empty shell, or placeholder -- only when a user calls new Dog(), a real construct will be returned.

In the constructor of Dog, a null value MUST be passed as the first argument to super() (1). This is because actually two constructs are made by the constructor, and the first one should be thrown away (and not be added to the construct tree).

Concrete implementations of a polycon can be written like ordinary constructs:

exportclassLabradorextendsConstruct{publicreadonlyname: string;privatereadonlytreats: number;constructor(scope: Construct,id: string,props: DogProps){super(scope,id);this.name=props.name;this.treats=props.treats;}publictoString(){return`Labrador with ${this.treats} treats.`;}}

🤝 Sharing behavior

Oftentimes, you may want all polycons to share some properties or methods.

You can achieve this by defining a base class, and having the polycon extend the base class:

exportinterfaceDogProps{readonlyname?: string;readonlytreats?: number;}exportconstDOG_TYPE="@acme/shared-polycons.Dog";// This is the polycon.exportclassDogextendsDogBase{constructor(scope: Construct,id: string,props: DogProps){super(nullasany,id,props);// [1]returnPolycons.newInstance(DOG_TYPE,scope,id,props)asDog;}publictoString(){thrownewError("Method not implemented");// [2]}}// This is the base class.exportabstractclassDogBaseextendsConstruct{publicreadonlyspecies="Canis familiaris";publicreadonlytreats: number;constructor(scope: Construct,id: string,props: DogProps){super(scope,id);// [3]if(!scope){this.treats=0;return;}this.treats=props.treats;}publicabstracttoString(): string;}

Please take note:

1. In the constructor of the polycon (Dog), a null value MUST be passed as the first argument to super().
2. Since the Dog class is just an empty shell, and does not get returned to the user, any methods required by the abstract base class can be left unimplemented.
3. In the constructor of the base class (DogBase), the constructor should have no side effects or mutations when an empty scope is passed (otherwise, side effects may occur multiple times). In the example above, we set dummy values when the scope is empty (this.treats = 0;) and return early.

When a polycon has a base class, every polycon implementation should extend it instead of extending Construct:

exportclassLabradorextendsDogBase{publicreadonlyname: string;constructor(scope: Construct,id: string,props: DogProps){super(scope,id,props);this.name=props.name;}publictoString(){return`Labrador with ${this.treats} treats.`;}}

✋ Contributing

We welcome community contributions and pull requests. See CONTRIBUTING.md for information on how to set up a development environment and submit code on GitHub.

⚖️ License

This library is licensed under the Apache-2.0 license.