sfioc

    1.0.3 • Public • Published

    Sfioc

    npm dependency Status devDependency Status Build Status Test coverage npm npm node

    Inversion of Control container for Node.JS. Inspired by awilix.

    Installation

    With npm:

    npm install sfioc --save

    Usage

    You need to do three basic things: create the container, register some modules in it, and then resolve the one you need and use it.

    Here is an example application code.

    import sf from 'sfioc'
     
    // Imagine that our app has an internal store...
    const appInternalStore = {
      isLoggedIn: false,
      currentUser: null
    }
     
    // ... and we have a database that we will connect to.
    const ourDatabase = {
      users: [
        { id: 1, name: `Lieutenant` },
        { id: 2, name: 'Colonel' }
      ],
      secretData: 42
    }
     
    // Let's create repo that depends on our database...
    class Repo {
      // Dependencies will be injected in the constructor.
      constructor({ database }) {
        this.db = database
      }
     
      findUser(id) {
        const user = this.db.users.find(dbUser => {
          if (dbUser.id === id) return dbUser
        })
     
        return new Promise((resolve, reject) => {
          setTimeout(() => {
            user ? resolve(user): reject('Could not find user!')
          }, 500)
        })
      }
     
      getSecretData() {
        return new Promise((resolve) => {
          setTimeout(() => resolve(this.db.secretData), 500)
        })
      }
    }
     
    // ... create some app operations that depends on our Repo and store.
    // Here dependencies will be injected inside the function.
    const login = ({ store, repo }) => {
      // This nested function will be used by our 'app' module after resolving...
      return (userId) => (new Promise((resolve, reject) => {
        // ... and we will be able to access the dependencies from here.
        repo.findUser(userId)
          .then(user => {
            store.isLoggedIn = true
            store.currentUser = user
            resolve(user)
          })
          .catch(err => reject(err))
      }))
    }
     
    // One more operation.
    const showSecretData = ({ repo }) => {
      return () => {
        repo.getSecretData()
          .then(data => {
            console.log(`Your secret data is: ${data}`)
          })
          .catch(err => {
            console.log(err)
          })
      }
    }
     
    // Finally let's create a factory function with our entry point.
    const appFactory = ({ store, login, showSecretData }) => {
      return { start }
     
      async function start(userId) {
        if (!store.isLoggedIn) {
          try {
            await login(userId)
          } catch (err) {
            console.log(err)
            return
          }
        }
     
        console.log(`Welcome, ${store.currentUser.name}!`)
        showSecretData()
      }
    }
     
    // Create the container.
    const container = sf.createContainer()
     
    // Register our app modules in the container.
    container.register({
      // Here we specify how to resolve our 'store' module.
      // It has no dependencies, we don't need to call it as a function,
      // we only need the data inside. So we can register our store as 'value'.
      store: sf.component(appInternalStore).value(),
      // Same for database.
      database: sf.component(ourDatabase).value(),
      // Here we have a class that have dependencies.
      // We need to specify which module it will depend on.
      // In this case, it's a database.
      repo: sf.component(Repo, { dependsOn: 'database' }).class(),
      // Everything is the same for this module.
      // Sfioc resolves all modules as a function by default.
      // So we don't need to specify how to resolve it...
      login: sf.component(login, { dependsOn: ['store', 'repo']}),
      // ... but is you want, you may specify it by calling a '.fn()' option...
      showSecretData: sf.component(showSecretData, { dependsOn: 'repo' }).fn(),
      // ... but we can do it in a different way...
      app: sf.component(appFactory, {
        // ... by specifying through the 'resolveAs' option.
        // This is the same as calling the '.fn()' option on our component
        resolveAs: sf.ResolveAs.FUNCTION,
        dependsOn: ['store', 'login', 'showSecretData']
      })
    })
     
    // We've set everything up. Let's resolve our 'app' module.
    const app = container.resolve('app')
    // Same as:
    // const app = container.get.app
     
    // Welcome, Lieutenant!
    // Your secret data is: 42
    const userId = 1
    app.start(userId)
     
    // Could not find user!
    const wrongUserId = 42
    app.start(wrongUserId)

    Injection modes

    The injection mode determines how a function/constructor receives its dependencies. Sfioc supports two injection modes: CLASSIC and PROXY.

    • InjectionMode.CLASSIC: In this case you need to explicitly specify which components each component depends on using dependsOn option.

      class UserService {
        constructor({ emailService, logger }) {
          this.emailService = emailService
          this.logger = logger
        }
      }
       
      container.register({
        userService: sf.component(UserService, {
          resolveAs: sf.ResolveAs.CLASS,
          dependsOn: ['emailService', 'logger']
        }),
        emailService: // ...
        logger: // ...
      })
    • InjectionMode.PROXY: Injects a proxy to functions/constructors which looks like a regular object. In this case you don't need to explicitly specify dependencies.

      class UserService {
        constructor({ emailService, logger }) {
          this.emailService = emailService
          this.logger = logger
        }
      }
       
      container.register({
        userService: sf.component(UserService).class(),
        emailService: // ...
        logger: // ...
      })

    CLASSIC mode is slightly faster than PROXY because it only reads the dependencies from the constructor/function once, whereas accessing dependencies on the Proxy may incur slight overhead for each resolve.

    Lifetime management

    Sfioc supports managing the lifetime of components. You can control whether objects are resolved and used once or cached for the lifetime of the process.

    There are 2 lifetime types available.

    • Lifetime.TRANSIENT: This is the default. The registration is resolved every time it is needed. This means if you resolve a class more than once, you will get back a new instance every time.
    • Lifetime.SINGLETON: The registration is always reused no matter what - that means that the resolved value is cached in the root container.

    To register a module with a specific lifetime:

    import { component, Lifetime } from 'sfioc'
     
    class SomeService() {}
     
    container.register({
      someService: component(SomeService, { lifetime: Lifetime.SINGLETON })
    })
     
    // this is the same
    container.register({
      someService: component(SomeService).setLifetime(Lifetime.SINGLETON)
    })
     
    // or even shorter
    container.register({
      someService: component(SomeService).singleton()
    })

    Components

    Component is needed in order to wrap your module, specify options for it, and store them inside. This method is used to wrap modules and prepare them for further registration.

    Groups

    In addition to components you also have the ability to use groups. It's used to combine components and other groups, specify common parameters or/and namespace for them.

    Imagine that you have some modules that can be assigned to the same group. For example: operations.

    import sf from 'sfioc'
     
    class MockRepo {}
    class MailService {}
     
    // Our operations
    const getUser = ({ mockRepo }) => (id) => {
      return mockRepo.getUser(id)
    }
     
    const sendGreetToUser = ({ mailService }) => (name) => {
      return mailService.send(`Hello, ${name}!`)
    }
     
    // Some controller that depends on operations
    class UserController {
      // Sfioc generated a namespace for operations
      constructor({ operations }) {
        this.operations = operations;
      }
     
      spamToUser(id) {
        // You can access any operation through this namespace
        const user = this.operations.getUser(id)
        this.operations.sendGreetToUser(user.name)
      }
    }
     
    const container = sf.createContainer({
      injectionMode: sf.InjectionMode.PROXY
    })
     
    container.register({
      mockRepo: // ...
      mailService: // ...
      userController: sf.component(UserController).class(),
      // So if you assign the group for 'operations' property, it will be used as
      // a namespace for all nested components.
      operations: sf.group({
        getUser: sf.component(getUser)
        sendGreetToUser: sf.component(sendGreetToUser)
      })
    })
     

    It's also possible to specify default options for nested components as well.

    container.register({
      //...
      operations: sf.group({
        getUser: sf.component(getUser)
        sendGreetToUser: sf.component(sendGreetToUser)
      }, {
        lifetime: sf.Lifetime.SINGLETON
      })
     
      // The same thing:
      operations: sf.group({
        getUser: sf.component(getUser)
        sendGreetToUser: sf.component(sendGreetToUser)
      }).singleton()
    })
     
    container.registrations['operations.getUser'].lifetime // SINGLETON
    container.registrations['operations.sendGreetToUser'].lifetime // SINGLETON

    Note: group options do not overwrite options of nested components, if they are specified.

    container.register({
      //...
      operations: sf.group({
        getUser: sf.component(getUser).transient() // Specified TRANSIENT lifetime.
        sendGreetToUser: sf.component(sendGreetToUser)
      }, {
        lifetime: sf.Lifetime.SINGLETON
      })
    })
     
    container.registrations['operations.getUser'].lifetime // TRANSIENT
    container.registrations['operations.sendGreetToUser'].lifetime // SINGLETON

    You can register other groups within group as well.

    API

    The sfioc object

    When importing sfioc, you get the following top-level API:

    • createContainer
    • component
    • group
    • Lifetime
    • ResolveAs
    • InjectionMode

    createContainer

    Creates a new Sfioc container.

    Args:

    • options: Options object. Optional.
      • options.injectionMode: Determines the method for resolving dependencies. Valid modes are:
        • CLASSIC: (default) Dependencies must be explicitly specified via dependsOn option.
        • PROXY: Injects a proxy object in module that is able to resolve its dependencies.
      • options.componentOptions: Global options for all components. They can be overwrited by container.register, sfioc.group and sfioc.component methods.

    component

    Used with container.register({ moduleName: component(module) }). Wraps dependencies and prepares them for further registration.

    Args:

    • target: Your dependency.
    • options: Options onject. Optional.
      • options.resolveAs: tells Sfioc hot to resolve given module. Valid params: ResolveAs.FUNCTION, ResolveAs.CLASS, ResolveAs.VALUE.

      • options.lifetime: sets the target's lifetime. Valid params: Lifetime.SINGLETON, Lifetime.TRANSIENT.

      • options.dependsOn: sets the component dependencies. Accepts the string with dependency name, or array with dependency names. dependsOn also accepts a callback that must return the dependency name, or an array of dependency names. Sfioc injects selectors with the names of registered modules in this callback. So if you registered, for example first and second modules, you can specify a dependency on them in this way:

        component(third).dependsOn((DP) => ([DP.first, DP.second]))
        // is the same as:
        component(third).dependsOn('first', 'second')

        Note: use this option only when the CLASSIC injection mode is selected. Otherwise this options is useless.

    The returned component has the following chainable API:

    • component(module).resolveAs(resolveAs: string): same as the resolveAs option.
    • component(module).fn(): same as component(module).resolveAs(ResolveAs.FUNCTION)
    • component(module).class(): same as component(module).resolveAs(ResolveAs.CLASS)
    • component(module).value(): same as component(module).resolveAs(ResolveAs.VALUE)
    • component(module).setLifetime(lifetime: string): same as the lifetime option.
    • component(module).transient(): same as component(module).setLifetime(Lifetime.TRANSIENT)
    • component(module).singleton(): same as component(module).setLifetime(Lifetime.SINGLETON)
    • component(module).dependsOn(dependencies: string | array | function): same as the dependsOn option.

    group

    Used with:

    container.register({
      namespace: group({
        component1: component(module1)
        component2: component(module2)
      })
    })

    Combines components, specify common parameters or/and namespace for them.

    Args:

    • elements: An object with components or/and groups.
    • options: Default options for nested components and groups. (Same as component options)

    The returned group has the following chainable API:

    • group(components).resolveAs(resolveAs: string): same as the resolveAs option.
    • group(components).fn(): same as group(components).resolveAs(ResolveAs.FUNCTION)
    • group(components).class(): same as group(components).resolveAs(ResolveAs.CLASS)
    • group(components).value(): same as group(components).resolveAs(ResolveAs.VALUE)
    • group(components).setLifetime(lifetime: string): same as the lifetime option.
    • group(components).transient(): same as group(components).setLifetime(Lifetime.TRANSIENT)
    • group(components).singleton(): same as group(components).setLifetime(Lifetime.SINGLETON)

    Lifetime

    Constant used with lifetime component options and related. It contains two values: TRANSIENT and SINGLETON.

    ResolveAs

    Constant used with resolveAs component options and related. It contains three values: FUNCTION, CLASS and VALUE.

    InjectionMode

    Constant used with sfioc.container options. It contains two values: CLASSIC and PROXY.

    The sfioc.container object

    The container returned from createContainer has some methods and properties.

    container.get

    The get is a proxy, and all getters will trigger a container.resolve. The get is actually being passed to the constructor/factory function, which is how everything gets wired up.

    container.registrations

    A read-only getter that returns the internal registrations.

    container.cache

    Used internally for caching resolutions.

    container.options

    Options passed to createContainer are stored here.

    container.resolve

    Resolves the registration with the given name. Used by the get.

    container.register({ test: component(() => 42) })
     
    container.resolve('test') === 42
    container.get.test === 42

    container.register

    Registers modules or/and groups in the container.

    There are multiple syntaxes for this function, you can pick the one you like the most, or combine them.

    The register method also accepts options for nested components and group as the last possible argument.

    // Register single component
    container.register('someOperationName', component(someOperationFactory))
     
    // Same, but with options
    container.register(
      'someOperationName',
      component(someOperationFactory),
      {
        // These options can't overwrite the "someOperationFactory"'s own options.
        // They will be used as default values for options that are not specified.
        lifetime: Lifetime.SINGLETON,
        resolveAs: ResolveAs.FUNCTION
      }
    )
     
    // Register single group
    container.register('operations', group({
      login: component(loginFactory),
      signup: component(signupFactory)
    }), { /* options */ })
     
    // Same as above
    container.register('operations', {
      login: component(loginFactory),
      signup: component(signupFactory)
    }, { /* options */ })
     
    // With single namespace
    container.register('operations', [
      group({
        sendSpam: component(sendSpamFactory),
        sendGreet: component(sendGreetFactory)
      }),
      group({
        login: component(loginFactory),
        signup: component(signupFactory)
      })
    ], { /* options */ })
     
    // Same as above
    container.register('operations', [
      { sendSpam: component(sendSpamFactory) },
      { sendGreet: component(sendGreetFactory) }
      group({
        login: component(loginFactory),
        signup: component(signupFactory)
      })
    ], { /* options */ })
     
    // Same as above
    container.register({
      operations: group({
        login: component(loginFactory),
        signup: component(signupFactory),
        sendSpam: component(sendSpamFactory),
        sendGreet: component(sendGreetFactory)
      })
    }, { /* options */ })
     
    // Classic registration
    container.register({
      login: component(loginFactory),
      signup: component(signupFactory)
    }, { /* options */ })
     
    // Same as above
    container.register(group({
      login: component(loginFactory),
      signup: component(signupFactory)
    }), { /* options */ })
     
    // Same as above
    container.register([
      ['login', component(loginFactory), { /* options */ }],
      ['signup', component(signupFactory), { /* options */ }]
    ], { /* options */ })

    Install

    npm i sfioc

    DownloadsWeekly Downloads

    0

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    65.4 kB

    Total Files

    22

    Last publish

    Collaborators

    • dqmrf