text: # Copyright 2019 The Bazel Authors. All rights reserved.
  #
  # 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.
  
  #This contains references to the symbols we want documented.
  #We can't point stardoc to the top-level index.bzl since then it will see macros rather than the rules they wrap.
  #So this is a copy of index.bzl with macro indirection removed.
  
  """
  # TypeScript rules for Bazel
  
  The TypeScript rules integrate the TypeScript compiler with Bazel.
  
  ## Alternatives
  
  This package provides Bazel wrappers around the TypeScript compiler.
  
  At a high level, there are three alternatives provided: `tsc`, `ts_project`, `ts_library`.
  This section describes the trade-offs between these rules.
  
  ### tsc
  
  `tsc` is the TypeScript compiler published by the team at Microsoft.
  You can call it without any custom Bazel rules.
  
  To use this option, you **do not need to install the `@bazel/typescript` package**.
  
  The only reason to use raw `tsc` is if you want to compile a directory of `.ts` files and cannot enumerate them ahead-of-time in your BUILD file so that Bazel can predict all the output files.
  (For example if the `.ts` files are generated by some tool).
  This will produce an opaque directory of `.js` file outputs, which you won't be able to individually reference.
  
  Any other use case for `tsc` is better served by using `ts_project`, see below.
  
  Like we do for any npm package that exposes a binary, rules_nodejs will see your dependency on
  `typescript` and will generate an `index.bzl` file allowing you to run `tsc`.
  To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc")` to your BUILD file.
  (Possibly replacing `@npm` with the name of the repository where you installed dependencies)
  
  Then call it, using the [`npm_package_bin`](Built-ins#npm_package_bin) documentation.
  
  Here is an example:
  https://github.com/bazelbuild/rules_nodejs/blob/3.2.2/internal/node/test/BUILD.bazel#L491-L507
  
  ### tsc_test
  
  `tsc_test` is generated alongside `tsc`.
  It is identical, except that Bazel treats it as a test target, producing only an exit code
  rather than files to be consumed by other steps in the build.
  
  This can be used for a build with `--noEmit`, so that TypeScript is purely used for
  type-checking and not for producing any build outputs.
  
  To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc_test")` to your BUILD file.
  (Possibly replacing `@npm` with the name of the repository where you installed dependencies)
  
  See example in https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/tsc_test
  
  ### ts_project
  
  `ts_project` simply runs `tsc --project`, with Bazel knowing which outputs to expect based on the TypeScript compiler options,
  and with interoperability with other TypeScript rules via the [DeclarationInfo] Provider that transmits the type information.
  
  It is intended as an easy on-boarding for existing TypeScript code and should be familiar if your background is in frontend ecosystem idioms.
  
  Any behavior of `ts_project` should be reproducible outside of Bazel, with a couple of caveats noted in the rule documentation below.
  
  `ts_project` is recommended for all new code.
  
  Exhaustive examples of calling `ts_project` are in the test suite:
  https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project
  
  And there are also many uses of it in our <examples>
  
  [DeclarationInfo]: Built-ins#declarationinfo
  
  ### ts_library
  
  `ts_library` should not be used for new code, and may be deprecated in the future.
  
  `ts_library` is an open-sourced version of the rule used to compile TS code at Google.
  However there is no support from the team that maintains that internal version.
  It is very complex, involving code generation of the `tsconfig.json` file, a custom compiler binary, and a lot of extra features.
  
  It is also opinionated, and may not work with existing TypeScript code. For example:
  
  - Your TS code must compile under the `--declaration` flag so that downstream libraries depend only on types, not implementation. This makes Bazel faster by avoiding cascading rebuilds in cases where the types aren't changed.
  - We control the output format and module syntax so that downstream rules can rely on them.
  - Some other options are incompatible. For example you cannot use the `--noEmit` compiler option in `tsconfig.json`.
  
  The only reason to use `ts_library` for new code is if you are bought-in to using a [concatjs] bundler, which requires the named AMD module format. This may be faster than other tooling, and this format can be consumed by the Closure Compiler (via integration with [tsickle](https://github.com/angular/tsickle)).
  However it is very challenging to configure and there is little available support for problems you'll run into.
  
  [concatjs]: https://www.npmjs.com/package/@bazel/concatjs
  
  ## Installation
  
  Add a `devDependency` on `@bazel/typescript`
  
  ```sh
  $ yarn add -D @bazel/typescript
  # or
  $ npm install --save-dev @bazel/typescript
  ```
  
  Watch for any `peerDependency` warnings - we assume you have already installed the `typescript` package from npm.
  
  ## Typical Usage
  
  The `ts_project` rule invokes the TypeScript compiler on one compilation unit,
  or "library" (generally one directory of source files). In TypeScript terms, this is one "Project"
  which can use "Project References" to break up a large application.
  
  Create a `BUILD` file next to your sources:
  
  ```starlark
  load("//packages/typescript:index.bzl", "ts_project")
  
  ts_project(
      name = "my_code",
      # glob is a quick way to select all the code,
      # but has performance penalty in that Bazel must evaluate it.
      srcs = glob(["*.ts"]),
      deps = ["//path/to/other:library"],
  )
  ```
  
  Here, `//path/to/other:library` is another target in your repo that produces TypeScript typings (for example, another `ts_project` rule).
  Be sure to set the `rootDirs` in your tsconfig.json as noted below, so that TypeScript can find the `.d.ts` files produced by that other target.
  
  To use third-party libraries from npm, first install them (likely using `npm_install` or `yarn_install` rules) then add those to the `deps` as well:
  
  ```starlark
  ts_project(
      name = "my_code",
      srcs = glob(["*.ts"]),
      deps = [
        "@npm//@types/node",
        "@npm//@types/foo",
        "@npm//somelib",
        "//path/to/other:library",
      ],
  )
  ```
  
  You can also use the `@npm//@types` grouping target which will include all
  packages in the `@types` scope as dependencies.
  
  To build a `ts_library` target run:
  
  `bazel build //path/to/package:target`
  
  Note that the `tsconfig.json` file used for compilation should be the same one
  your editor references, or `extends` from it, to keep consistent settings for the TypeScript compiler.
  
  Anything you do with TypeScript is possible with `ts_project`, including json imports, type-checking only,
  transpile only, outdir, rootdir, and so on.
  
  > To use `ts_project` for typecheck-only, you'll still need to use --declaration so that .d.ts files are produced.
  > Alternatively, see the `tsc_test` rule documented above.
  
  See many examples in our test cases:
  https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project
  """
  
  load("//packages/typescript/internal:build_defs.bzl", _ts_library = "ts_library")
  load("//packages/typescript/internal:ts_config.bzl", _ts_config = "ts_config")
  load("//packages/typescript/internal:ts_project.bzl", _ts_project = "ts_project_macro")
  
  ts_library = _ts_library
  ts_config = _ts_config
  ts_project = _ts_project
  