Simpledi-decorators NPM

Simple DI

Ever just want a simple way to inject your values? Well now you can!

This package is just that. Simple.

It IS simple.
It WORKS simple.
Don't make your live harder then it has to be.

This package is made to be a simple dependecy injector, so no over complicated fancy features. Just injecting values into properties or methods.

It probably doesn't have the fancy (over-)complicated features some other TypeScript dependcy injectors would have. But that's why it's called Simple DI.

NOTE: When I tried to publish under the name simpledi it already seem to exist by someone named nerdbeere but mine is different enough (I think) to co-exist.

If you want to check out his project click here.

Prerequisites

This project requires NodeJS (version 16 or later) and NPM (or Yarn). Node and NPM (or Yarn) are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
8.6.0
v16.13.0

For yarn:

$ yarn -v
1.22.19

Simple DI

Getting Started

To get started you just have to follow the Installation process. Then check out the Example and/or the API and you should be good to go!

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

$ npm install -S simpledi-decorators

Or if you prefer using yarn:

$ yarn add simpledi-decorators

Example Usage

If you clone this repository, you can run the following commands to run the same example. You can find the source of these example files in ./src/Example.

Via npm:

npm install --include=dev
npm run build-example
npm run example

Or for yarn:

yarn install
yarn build-example
yarn example

Built-in example

// Registrer.ts
import { LiveContainer } from "simpledi-decorators";

// No real reason registrating values is here.
// It's just for clarity, you can move this where ever you want.
export function run()
{
  // Run 'LiveContainer.registerValue' with your key and value.
  // SimpleDI will look at variable and argument names
  // and replaces these with the value given here.
  //
  // If it can't find a registered value
  // it will just pass the whatever was passed originally.
  // 
  // You can register any value you want,
  // it will pass it exactly how you registered it.
  //
  // Classes, instancieted classes, strings, functions, numbers, booleans, anything
  LiveContainer.registerValue("greetmsg", "My name is")
  LiveContainer.registerValue("myname", "Jeff")
}
// At this moment you should NOT make your own container
// unless you want to handle the exporting of it and injection handling yourself.
// 
// Support for this is on the way!

// Entity.ts
import { Inject } from "simpledi-decorators";

export class Entity
{

  // You can auto inject by just adding @Inject() as an annotation above a property.
  // You can also choose to override/set the injection key on properties.
  // Override/setting the injection key doesn't work on methods.
  // @Inject("greetmsg")
  // 
  @Inject()
  greetmsg: string;

  // Great thing is, you won't need to set any properties in your constructor
  // in order for this to work!
  public constructor()
  {
  }

  // Or even on a method, but you won't be able to override any injection keys.
  // Make sure your first argument is a destructured object with your injection keys.
  // It's okay to mix in other keys that doesn't have any injection values.
  // 
  // If the injected value is not registered/set the original argument will be used.
  @Inject()
  public printGreet({myname, meetmsg}: {myname: string, meetmsg?: string})
  {
    console.log(`${this.greetmsg} ${myname}. ${meetmsg}`)
  }
}

// This even works on static properties and methods.
export class StaticEntity
{
  // Here we will override the greetmsg just as an example.
  @Inject("greetmsg")
  static greetmsg: string

  @Inject()
  public static printGreet({myname, meetmsg}: {myname: string, meetmsg?: string})
  {
    console.log(`${this.greetmsg} ${myname}. ${meetmsg}`)
  }
}

// Main.ts (Entry Point)
import { Entity, StaticEntity } from "./Entity";
import * as Register from "./Register";

// Entry point
function main()
{
  // Run the value registration processing.
  // You could run it manually here but for clarity it's moved to it's own file.
  Register.run()
  // Create any entity with the @Inject() decorators.
  // This could be any class with @Inject() decorators.
  let entity = new Entity()
  // Lets greet the user with injected values!
  // If you want to inject a value you do have to pass it and set it to something.
  // If it can't find your injected value the original value will be used.
  entity.printGreet({myname: "Heisenberg", meetmsg: "Nice to meet you."})
  // It even works on static properties and entities.
  StaticEntity.printGreet({myname: "Heisenberg", meetmsg: "Nice to meet you."})
}
main()

Your result should be:

My name is Jeff. Nice to meet you.
My name is Jeff. Nice to meet you.

API

Every method and property should have JSDocs. If not here you go.

Inject (@Inject)

@Inject(ivName?: string)

Inject a value by ivName.

Options

Argument	Type	Default value	Description	Usage
`ivName`	string?	undefined	Injection name (key)	If set this will override the property/argument name when getting the injected value from `LiveContainer`.

Example: See Entry.ts in Built-In Example.

getInjectedValue

This also works on new Container() but at this moment is NOT recommanded unless you know what you're doing.

LiveContainer.getInjectedValue(name: string): any

Get the injected value by name/key.

You probably won't need this since you have @Inject but if you ever need it here you go.

Options

Argument	Type	Default value	Description	Usage
`name`	string	undefined	Injection name (key)	The name of the injection value you want.

Example:

import { LiveContainer } from "../Container";

LiveContainer.registerValue("name", "somevalue")

let ivValue = LiveContainer.getInjectedValue("name")
console.log(ivValue) // "somevalue"

LiveContainer.registerValue

This also works on new Container() but at this moment is NOT recommanded unless you know what you're doing.

LiveContainer.registerValue(name: string, value: any): void

Registers a new value eligible for injection.

Options

Argument	Type	Default value	Description	Usage
`name`	string	undefined	Injection name (key)	The name of the injection value you want.
`value`	string	undefined	Injection value	The value you want it to inject.

Example: See Built-In Example.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

But to summarize it:

Fork it!
Create your feature branch: git checkout -b my-new-feature
Add your changes: git add .
Commit your changes: git commit -am 'Add some feature'
- Your commit message must follow the Conventional Commits rules.
Push to the branch: git push origin my-new-feature
Submit a pull request :sunglasses: