grfn
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published
    grfn

    grfn

    A tiny (~400B) utility that executes a dependency graph of async functions as concurrently as possible.

    Features

    • Lightweight: less than 400 bytes gzipped
    • Unobtrusive and Unopiniated: takes normal functions; returns a normal function!
    • Isomorphic: works in node and the browser
    • Easy Debugging: provides cycle detection through a grfn/debug module as well as PNG, SVG, and GIF dependency graph previews through the grfnviz package!
    • Awesome Logo: designed by Jill Marbach!

    Table of Contents

    Install

    $ npm i grfn

    Usage

    Check out grfn's very own build file for a real world usage example!

    An illustrative example (with a GIF generated using grfnviz!):

    import grfn from 'grfn'
    
    const delay = timeout => new Promise(resolve => setTimeout(resolve, timeout))
    
    async function taskA(n1, n2, n3) {
      await delay(15)
      return n1 + n2 + n3
    }
    
    async function taskB(n1, n2, n3) {
      await delay(10)
      return n1 * n2 * n3
    }
    
    async function taskC(a, b) {
      await delay(5)
      return a + b
    }
    
    async function taskD(b) {
      await delay(1)
      return b * 2
    }
    
    async function taskE(a, c, d) {
      await delay(10)
      return a * c * d
    }
    
    const runTasks = grfn([
      // `taskE` depends on `taskA`, `taskC`, and `taskD`
      // Call `taskE` with the results of the functions
      // once their returned promises resolve
      [taskE, [taskA, taskC, taskD]],
    
      [taskD, [taskB]], // `taskD` depends on `taskB`
      [taskC, [taskA, taskB]], // `taskC` depends on `taskA` and `taskB`
    
      // `taskA` and `taskB` have no dependencies! (But they must still be listed)
      // They take the input given to `runTasks`
      taskA,
      taskB
    ])
    
    const output = await runTasks(4, 2, 3)
    
    // This will be the output of `taskE`
    // because no function depends on it!
    console.log(`final output: ${output}`)

    Output:

    final output: 14256
    

    Debugging

    To enable cycle detection and other validation import grfn/debug in addition to grfn:

    import grfn from 'grfn'
    import 'grfn/debug'

    To generate previews and GIFs (like above!) use the grfnviz package!

    API

    grfn(vertices) => (...args) => Promise

    Returns a function that runs the dependency graph of functions described by vertices:

    • Input: passed to the functions that don't have dependencies in the graph
    • Output: a Promise that resolves to the value returned from the graph's output function, the function that is not depended on by any function

    vertices

    Type: (Function | [Function, Function[]])[]

    An array describing a dependency graph of functions.

    Each value in vertices must be either:

    • A pair containing a function and its array of function dependencies (e.g. [fnA, [fnB, fnC]])
    • Or a function (equivalent to [fn, []])

    The following constraints, which are verified when grfn/debug is imported before calling grfn, must also be met:

    • Each dependency in vertices must also appear as a non-dependency:
      • Not okay (fnB doesn't appear as a non-dependency):
        grfn([
          [fnA, [fnB]]
        ])
      • Okay:
        grfn([
          [fnA, [fnB]],
          fnB
        ])
    • vertices must describe an acyclic dependency graph:
      • Not okay (cycle: fnA -> fnB -> fnA):
        grfn([
          [fnA, [fnB]],
          [fnB, [fnA]]
        ])
      • Okay:
        grfn([
          [fnA, [fnB]],
          fnB
        ])
    • vertices must have exactly one output function, a function that is not depended on by any function:
      • Not okay (both fnB and fnC are not depended on by any function):
        grfn([
          [fnB, [fnA]],
          [fnC, [fnA]],
          fnA
        ])
      • Okay:
        grfn([
          [fnD, [fnB, fnC]],
          [fnB, [fnA]],
          [fnC, [fnA]],
          fnA
        ])

    Contributing

    Stars are always welcome!

    For bugs and feature requests, please create an issue.

    For pull requests, please read the contributing guidelines.

    License

    Apache 2.0

    This is not an official Google product.

    Install

    npm i grfn

    DownloadsWeekly Downloads

    18

    Version

    1.0.0

    License

    Apache-2.0

    Unpacked Size

    21.2 kB

    Total Files

    7

    Last publish

    Collaborators

    • tomeraberbach