Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darky/ts-fp-di

Tiny TypeScript functional dependency injection, based on AsyncLocalStorage. Supports Node.js, Deno
https://github.com/darky/ts-fp-di

async asynclocalstorage deno dependency di fp functional injection local nodejs storage ts typescript

Last synced: 3 months ago
JSON representation

Tiny TypeScript functional dependency injection, based on AsyncLocalStorage. Supports Node.js, Deno

Awesome Lists containing this project

README 

        
# ts-fp-di

Tiny TypeScript functional dependency injection, based on AsyncLocalStorage. Supports Node.js, Deno



## Get started

Firstly, need init DI container for each life cycle of your backend application (each HTTP request/response, handle MQ message, ...).



Example of middleware for typical Koa application, where on each HTTP request will be created particular DI container:



```typescript

app.use(async (ctx, next) => {

  await diInit(async () => return await next());

});

```



Further, simply use **ts-fp-di** API "as is" in code, it will consider particular DI scope.



## Examples



#### Basic



```typescript

const fn = di(() => 1);

fn() // call `fn` function inside DI scope, it's return 1

```



#### Override dependency (method 1)



```typescript

const fn = di(() => 1);

diSet(fn, () => 2); // Override `fn` function inside DI scope. Useful for unit tests.

fn() // returns 2, because it rewriten.

```



#### Override dependency (method 2)



```typescript

const fn = () => 1;

diSet(fn, () => 2); // Override `fn` function inside DI scope. Useful for unit tests.

diDep(fn)() // returns 2, because it rewriten.

```



#### Dependency by string key



```typescript

diSet('user', {login: 'xxx'}); // Useful to setup current user in DI scope

diDep('user') // Extract current user from anywhere

```



#### State managment in DI scope



```typescript

// setup Redux like state with reducer in DI scope

const inc = dis((sum, n: number) => sum + n, 0); 

inc(1); // mutate state

inc(); // 1, "inc" without argument returns current state



const num = div(); // alias to dis((sum, n: number) => n, void 0)

num(5); // mutate state

num(); // 5

```



#### State managment in global scope



```typescript

// setup Redux like state with reducer in global scope (pass true as isGlobal flag)

const inc = dis((sum, n: number) => sum + n, 0, true); 

inc(1); // mutate state

inc(); // 1, "inc" without argument returns current state



clearGlobalState(); // you can clear global state (useful in tests)

inc() // 0, "inc" returns default value now

```



#### Singleton for DI scope



```typescript

let i = 0;

const fn = diOnce(() => { // <- setup Singleton function for DI scope

  i += 1;

  return i;

});



fn(); // 1

fn(); // also 1, because fn is singleton for DI scope

```



#### Singleton constant for DI scope



```typescript

const cache = dic()



cache(1)

cache() // 1

```



#### Override Singleton for DI scope



```typescript

const fn = diOnce((n: number) => { // <- setup Singleton function for DI scope

  return n + 1;

});



diOnceSet(fn, -1); // Override diOnceSet. For example, use this in your unit tests

fn(4) // -1 instead 5, because -1 set on prev line

```



#### Check that runtime in DI scope



```typescript

diExists() // false



diInit(() => {

  diExists() // true

});

```



#### Share DI context



```typescript

const ctx = diContext()



diInit(() => {

  // ctx will be considered here

}, ctx)



diInit(() => {

  // same ctx will be considered here too

}, ctx)

```



#### DI Scope (OOP incapsulation alternative)



```typescript

const inc = dis((resp: number, n: number) => resp + n, 0)



const scope = diScope({ inc }, () => {

  // optional "constructor" function

  // some `diSet` can be used here

})



scope.inc(5) // this mutation occur only inside this scope

scope.inc() // 5 

```



#### Functional reactive programming, mapping



```typescript

const cacheNumber = dic()

const calcString = diMap(n => `string - ${n}`, cacheNumber)



cacheNumber(5)

calcString() // "string - 5"



const onceNumber = diOnce((n: number) => {

  return n;

});

const calcString = diMap(n => `string - ${n}`, onceNumber)



onceNumber(5)

calcString() // "string - 5"



const inc = dis((sum, n: number) => sum + n, 0);

const calcString = diMap(s => `string - ${s}`, inc)

inc(1);

inc(4);

calcString() // "string - 5"



calcString.raw(1) // direct call of function, useful for unit tests



const cacheNumber = dic()

let i = 0

const onceString = diMapOnce(n => ((i = i + 1), `string - ${n}`), cacheNumber)



cacheNumber(5)

onceString() // "string - 5"

onceString() // i = 1, because onceString is singleton for DI scope

```



#### Attach async effect to State



```typescript

const numberState = dic()

numberState(5)

const stringState = diMap(n => `string - ${n}`, numberState)

const seState = div() // will be populated via side effect

const se = dise(

  async (n, s) => `${n} ${s}`, // side effect async function

  seState, // this state will be populated via async response

  numberState, // optional arg1 for effect function

  stringState) // optional arg2 for effect function



await se()



seState() // "5 string - 5"



// dise function can be overriden for unit tests

diseSet(se, async (n, s) => n + parseInt(s.match(/\d/)))



await se()



seState() // 10

```



## Plugins



Internal AsyncLocalStorage instance exposed as `als` property. You can implement your own plugin around it.



‼️ If you use ts-fp-di with plugins on your project, please consider, that you have only one ts-fp-di *node_module*


For example you can freeze as singleton you dependency via *package.json* `overrides`



```json

{

  "overrides": {

    "ts-fp-di": "^x.x.x"

  }

}



```



* [ts-fp-di-mikroorm](https://github.com/darky/ts-fp-di-mikroorm) - Use MikroORM Entities inside ts-fp-di State and achieve auto persistence in DB

* [ts-fp-di-rxjs](https://github.com/darky/ts-fp-di-rxjs) - Utils for RxJS for working with ts-fp-di

* [rxjs-wait-next](https://github.com/darky/rxjs-wait-next) - Wait RxJS Subject.next emition for all subscribers