npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

polycons

v0.1.9

Published

A framework for building polymorphic [constructs](https://github.com/aws/constructs). Think of polycons like dependency injection for constructs.

Downloads

14

Readme

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";

class Pets extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    // this is a polycon!
    new Dog(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";

const app = new App();
Polycons.register(app, new PetFactory());
new Pets(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";

class PetFactory implements IPolyconFactory {
  public resolve(
    type: string,
    scope: Construct,
    id: string,
    ...args: any[]
  ): Construct {
    switch (type) {
      case DOG_TYPE:
        return new Labrador(scope, id, ...args);
      case CAT_TYPE:
        return new Kitten(scope, id, ...args);
      default:
        throw new Error(`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";

export interface DogProps {
  readonly name?: string;
  readonly treats?: number;
}

// make sure your polycon has a globally unique name!
export const DOG_TYPE = "@acme/shared-polycons.Dog";

export class Dog extends Construct {
  constructor(scope: Construct, id: string, props: DogProps) {
    super(null as any, id); // (1)
    return Polycons.newInstance(DOG_TYPE, scope, id, props) as Dog;
  }
}

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:

export class Labrador extends Construct {
  public readonly name: string;
  private readonly treats: number;
  constructor(scope: Construct, id: string, props: DogProps) {
    super(scope, id);
    this.name = props.name;
    this.treats = props.treats;
  }
  public toString() {
    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:

export interface DogProps {
  readonly name?: string;
  readonly treats?: number;
}

export const DOG_TYPE = "@acme/shared-polycons.Dog";

// This is the polycon.
export class Dog extends DogBase {
  constructor(scope: Construct, id: string, props: DogProps) {
    super(null as any, id, props); // [1]
    return Polycons.newInstance(DOG_TYPE, scope, id, props) as Dog;
  }
  public toString() {
    throw new Error("Method not implemented"); // [2]
  }
}

// This is the base class.
export abstract class DogBase extends Construct {
  public readonly species = "Canis familiaris";
  public readonly treats: number;
  constructor(scope: Construct, id: string, props: DogProps) {
    super(scope, id);

    // [3]
    if (!scope) {
      this.treats = 0;
      return;
    }

    this.treats = props.treats;
  }
  public abstract toString(): 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:

export class Labrador extends DogBase {
  public readonly name: string;
  constructor(scope: Construct, id: string, props: DogProps) {
    super(scope, id, props);
    this.name = props.name;
  }
  public toString() {
    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.