Container

An AST node can be a container. This determines the kinds of SymbolTables the Node and associated Symbol will have. Container is an abstract concept (i.e. has no associated data structure). The concept is driven by a few things, one being the ContainerFlags enum. The function getContainerFlags (in binder.ts) drives this flag and is presented below:

  1. function getContainerFlags(node: Node): ContainerFlags {
  2.     switch (node.kind) {
  3.         case SyntaxKind.ClassExpression:
  4.         case SyntaxKind.ClassDeclaration:
  5.         case SyntaxKind.InterfaceDeclaration:
  6.         case SyntaxKind.EnumDeclaration:
  7.         case SyntaxKind.TypeLiteral:
  8.         case SyntaxKind.ObjectLiteralExpression:
  9.             return ContainerFlags.IsContainer;
  11.         case SyntaxKind.CallSignature:
  12.         case SyntaxKind.ConstructSignature:
  13.         case SyntaxKind.IndexSignature:
  14.         case SyntaxKind.MethodDeclaration:
  15.         case SyntaxKind.MethodSignature:
  16.         case SyntaxKind.FunctionDeclaration:
  17.         case SyntaxKind.Constructor:
  18.         case SyntaxKind.GetAccessor:
  19.         case SyntaxKind.SetAccessor:
  20.         case SyntaxKind.FunctionType:
  21.         case SyntaxKind.ConstructorType:
  22.         case SyntaxKind.FunctionExpression:
  23.         case SyntaxKind.ArrowFunction:
  24.         case SyntaxKind.ModuleDeclaration:
  25.         case SyntaxKind.SourceFile:
  26.         case SyntaxKind.TypeAliasDeclaration:
  27.             return ContainerFlags.IsContainerWithLocals;
  29.         case SyntaxKind.CatchClause:
  30.         case SyntaxKind.ForStatement:
  31.         case SyntaxKind.ForInStatement:
  32.         case SyntaxKind.ForOfStatement:
  33.         case SyntaxKind.CaseBlock:
  34.             return ContainerFlags.IsBlockScopedContainer;
  36.         case SyntaxKind.Block:
  37.             // do not treat blocks directly inside a function as a block-scoped-container.
  38.             // Locals that reside in this block should go to the function locals. Othewise 'x'
  39.             // would not appear to be a redeclaration of a block scoped local in the following
  40.             // example:
  41.             //
  42.             //      function foo() {
  43.             //          var x;
  44.             //          let x;
  45.             //      }
  46.             //
  47.             // If we placed 'var x' into the function locals and 'let x' into the locals of
  48.             // the block, then there would be no collision.
  49.             //
  50.             // By not creating a new block-scoped-container here, we ensure that both 'var x'
  51.             // and 'let x' go into the Function-container's locals, and we do get a collision
  52.             // conflict.
  53.             return isFunctionLike(node.parent) ? ContainerFlags.None : ContainerFlags.IsBlockScopedContainer;
  54.     }
  56.     return ContainerFlags.None;
  57. }

It is only invoked from the binder’s bindChildren function which sets up a node as a container and/or a blockScopedContainer depending upon the evaluation of the getContainerFlags function. The function bindChildren is presented below:

  1. // All container nodes are kept on a linked list in declaration order. This list is used by
  2. // the getLocalNameOfContainer function in the type checker to validate that the local name
  3. // used for a container is unique.
  4. function bindChildren(node: Node) {
  5.     // Before we recurse into a node's chilren, we first save the existing parent, container
  6.     // and block-container.  Then after we pop out of processing the children, we restore
  7.     // these saved values.
  8.     let saveParent = parent;
  9.     let saveContainer = container;
  10.     let savedBlockScopeContainer = blockScopeContainer;
  12.     // This node will now be set as the parent of all of its children as we recurse into them.
  13.     parent = node;
  15.     // Depending on what kind of node this is, we may have to adjust the current container
  16.     // and block-container.   If the current node is a container, then it is automatically
  17.     // considered the current block-container as well.  Also, for containers that we know
  18.     // may contain locals, we proactively initialize the .locals field. We do this because
  19.     // it's highly likely that the .locals will be needed to place some child in (for example,
  20.     // a parameter, or variable declaration).
  21.     //
  22.     // However, we do not proactively create the .locals for block-containers because it's
  23.     // totally normal and common for block-containers to never actually have a block-scoped
  24.     // variable in them.  We don't want to end up allocating an object for every 'block' we
  25.     // run into when most of them won't be necessary.
  26.     //
  27.     // Finally, if this is a block-container, then we clear out any existing .locals object
  28.     // it may contain within it.  This happens in incremental scenarios.  Because we can be
  29.     // reusing a node from a previous compilation, that node may have had 'locals' created
  30.     // for it.  We must clear this so we don't accidently move any stale data forward from
  31.     // a previous compilation.
  32.     let containerFlags = getContainerFlags(node);
  33.     if (containerFlags & ContainerFlags.IsContainer) {
  34.         container = blockScopeContainer = node;
  36.         if (containerFlags & ContainerFlags.HasLocals) {
  37.             container.locals = {};
  38.         }
  40.         addToContainerChain(container);
  41.     }
  43.     else if (containerFlags & ContainerFlags.IsBlockScopedContainer) {
  44.         blockScopeContainer = node;
  45.         blockScopeContainer.locals = undefined;
  46.     }
  48.     forEachChild(node, bind);
  50.     container = saveContainer;
  51.     parent = saveParent;
  52.     blockScopeContainer = savedBlockScopeContainer;
  53. }

As you might recall from section on binder functions : bindChildren is called from the bind function. So we have the recursive binding setup : bind calls bindChildren calls bind for each child.