com.google.javascript.jscomp.modules.Module Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of closure-compiler Show documentation

Closure Compiler is a JavaScript optimizing compiler. It parses your JavaScript, analyzes it, removes dead code and rewrites and minimizes what's left. It also checks syntax, variable references, and types, and warns about common JavaScript pitfalls. It is used in many of Google's JavaScript apps, including Gmail, Google Web Search, Google Maps, and Google Docs.

There is a newer version: v20240317

Show newest version

/*
 * Copyright 2018 The Closure Compiler Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.javascript.jscomp.modules;

import com.google.auto.value.AutoValue;
import com.google.common.collect.ImmutableMap;
import com.google.javascript.jscomp.deps.ModuleLoader.ModulePath;
import com.google.javascript.jscomp.modules.ModuleMetadataMap.ModuleMetadata;
import org.jspecify.nullness.Nullable;

/**
 * Information for modules, particularly ES modules, that is useful for rewriting. The primary
 * pieces of information are what variables are exported (transitive or local), and what names are
 * imported.
 */
@AutoValue
public abstract class Module {
  // Prevent unwanted subclasses.
  Module() {}

  public abstract ModuleMetadata metadata();

  /** Path of this module. Null if this module is a nested {@code goog.loadModule}. */
  public abstract @Nullable ModulePath path();

  /**
   * Map of exported identifiers to originating binding.
   *
   * Note that the keys are different than {@link #boundNames()}. Here the keys are the exported
   * name, not the local name.
   *
   * 
Examples:
   *
   * 

   *   Locally defined exports (e.g. export let x;, let x; export {x as v};
   *       ) creates an entry with the exported name for the local module's export
   *       definition.
   *   
export default function foo() {}; creates an entry with the name "default"
   *       for the local module's default export definition.
   *   
export {x as v} from 'mod'; creates an entry with the name "v" for the
   *       export definition x from 'mod'.
   *   
import statements make no entries on their own. If imported values are
   *       exported with  export {}; then an entry is created like export {} from
   *       .
   *   
exports.foo = bar; creates an entry with the name "foo" for the expression
   *       on the right-hand side. This is not bound to a local name.
   * 
   */
  public abstract ImmutableMap namespace();

  /**
   * Map of local identifiers to originating binding.
   *
   * This includes all names bound by import and exported names which originate in this module.
   * Used for rewriting in later stages of the compiler.
   *
   * 
ES modules may have names bound by both imports and exports. Closure modules only have names
   * bound by imports, as it is impossible to create a new local identifier in an export.
   *
   * 
Examples:
   *
   * 

   *   import {x as v} from 'mod'; creates an entry with the name "v" for the
   *       export definition x from 'mod'.
   *   
import * as ns from 'mod'; creates an entry with the name "ns" with a
   *       binding containing all of mod's bindings.
   *   
export default function foo() {} creates an entry with the name "foo" for
   *       the local module's export definition.
   *   
export {x as v} from 'mod'; does not create any entry in this module.
   *   
const C = goog.require('mod.C') creates an entry with the name "C" for the
   *       binding containing the default export of 'mod.C'
   * 
   */
  public abstract ImmutableMap boundNames();

  /** Map of local identifier name to local export definition. */
  public abstract ImmutableMap localNameToLocalExport();

  /**
   * The specific Closure namespace this module represents, if any. This can be from {@code
   * goog.provide}, {@code goog.module}, or {@code goog.module.declareNamespace}. Null otherwise.
   */
  public abstract @Nullable String closureNamespace();

  /** Creates a new builder. */
  public static Builder builder() {
    return new AutoValue_Module.Builder();
  }

  /** Returns this module in builder form. */
  public abstract Builder toBuilder();

  /** Builder for {@link Module}. */
  @AutoValue.Builder
  public abstract static class Builder {
    public abstract Builder metadata(ModuleMetadata value);

    public abstract Builder path(@Nullable ModulePath value);

    public abstract Builder namespace(ImmutableMap value);

    public abstract Builder boundNames(ImmutableMap value);

    public abstract Builder localNameToLocalExport(ImmutableMap value);

    public abstract Builder closureNamespace(@Nullable String value);

    public abstract Module build();
  }
}