A specification for people who want to argue about how to do async code in w/e language. Argumentation on equal ground > rambling.

Async Flamewar npm Builder.md

AsyncFlamewar/NpmBuilder

This project describes a complex application meant to stress all aspects of an asynchronous workflow.

Goal

The goal of the project is to create a build process that invokes npm on a supplied tar file that matches the output of npm pack. This build process should install any dependencies, place them into bundledDependencies, lock down any variables such as OS and architecture, and output the results as a tar file.

Definitions

These are some terms that may need clarification while reading the project description.

Workflow

A single chain of logic that does not branch into parallel/async tasks. This may be made up of a series of sub-workflows that have their entire lifecycle inside of the workflow. If a workflow does not completely contain the lifecycle of a sub-workflow, it cannot be considered a sub-workflow.

Hooks

Events are used for extensibility. They should interrupt the workflow until completion, and allow for the stack to unwind during execution (if necessary to achieve parallel/async processing).

Events

Events are used for notification. They should not interrupt the workflow, or allow the stack to unwind during execution.

Requirements

1. Code should run as many tasks in parallel (async) where possible.
2. Code should follow consistent conventions for passing state.
   1. State can be passed by arguments.
   2. State can be passed by object properties.
   3. State can be passed by variables.
   4. State can be passed by return values.
   5. State can be passed by any combination of the above, if done consistently.
3. Errors should be propagated to a single point.
4. Errors should stop the workflow, but do not need to stop sub-workflows.

API

This describes the generic components of the project. It does not specify how to accomplish the tasks listed. Some specific terms are avoided due to convention of implementations in languages. It aims to be as generic as possible and avoid implementation restrictions.

Build Scaffold

The Build Scaffold(Scaffold) is what is used in order to create a build.

Requirements

• Scaffolds should be allowed to create multiple builds.
• Scaffolds should be allowed to configure defaults values for builds.
• Scaffolds should be extensible via providing a means to hook into builds. NB this may be done on the build itself, the scaffold does not need to provide this directly.

Task build

There should be a single entry point to start a build.

input

• scaffold used to start the build.
• a tar file stream, uncompressed.
• any defaults that are to be overriden for configuration.

output

• any error encountered, if unsucessful.
• a tar stream, uncompressed, if successful.

Build

A build is a single instance of a workflow that is created by a Scaffold. It involves all the steps necessary to create a packaged application from the supplied parameters.

Requirements

• Builds should honor the "engines" field in package.json files, and allow multiple node versions.
• Builds should prepare any files on the filesystem for npm prior to calling npm.
• Builds should prepare the environment as necessary for node-gyp to work properly.
• Builds should unpack the tar stream without modification prior to the completion of the npm.configure hook.

Event npm.spawned

Fired when the npm process actually starts.

input

• the scaffold (not build) that this process' build is based upon.
• representation of the npm process.

Hook build.configure

Fired when a build has gathered all the default values for a build and is about to merge them with the overriden values.

input

• the scaffold (not build) that the build is based upon.
• the gathered defaults (may not match the Scaffold's current values).
• the defaults overriden by supplied arguments.

Hook npm.configure

Fired after configuration has been merged from default values and overriden values.

input

• the scaffold (not build) that the build is based upon.
• the gathered configuration.
• information about the directories, env, etc. used for spawning npm are.

Hook npm.package

• the scaffold (not build) that the build is based upon.
• the gathered configuration.
• information about the directories, env, etc. used for spawning npm are.

Fired after the build is complete.

Hook build.output

Fired just before the packaged tar file is given as a result of a build.

• the scaffold (not build) that the build is based upon.
• the gathered configuration.
• information about the directories, env, etc. used for spawning npm are.
• the tar file stream we are about to return as a result.