{"_id":"@brianleishman/tsickle","name":"@brianleishman/tsickle","dist-tags":{"latest":"0.46.3-1"},"versions":{"0.46.3-1":{"name":"@brianleishman/tsickle","version":"0.46.3-1","description":"Transpile TypeScript code to JavaScript with Closure annotations.","main":"out/src/tsickle.js","typings":"out/src/tsickle.d.ts","directories":{"test":"test"},"peerDependencies":{"typescript":"~4.7.2"},"devDependencies":{"@types/diff-match-patch":"^1.0.32","@types/glob":"7.2.0","@types/jasmine":"^4.0.2","@types/node":"^17.0.24","@types/source-map-support":"^0.5.3","diff-match-patch":"^1.0.5","glob":"8.0.1","google-closure-compiler":"^20220405.0.0","jasmine":"^4.1.0","jasmine-node":"^3.0.0","source-map":"^0.7.3","source-map-support":"^0.5.19","tslib":"^2.2.0","tslint":"^6.1.3","typescript":"4.7.2"},"scripts":{"build":"tsc","clean":"rm -r out","lint":"tslint -c tslint.json -p tsconfig.json","test":"jasmine out/test/*.js && (cd demo && yarn && tsc) && yarn run lint","prepack":"yarn run clean && yarn run build"},"repository":{"type":"git","url":"git+https://github.com/angular/tsickle.git"},"keywords":["typescript","closure"],"contributors":[{"name":"Evan Martin","email":"evanm@google.com","url":"https://angular.io/"},{"name":"Alex Eagle","email":"alexeagle@google.com","url":"https://angular.io/"},{"name":"Martin Probst","email":"martinprobst@google.com","url":"https://angular.io/"},{"name":"Rado Kirov","email":"radokirov@google.com","url":"https://angular.io/"},{"name":"Thomas Deegan","email":"tdeegan@google.com"}],"license":"MIT","bugs":{"url":"https://github.com/angular/tsickle/issues"},"homepage":"https://github.com/angular/tsickle","dependencies":{"@types/minimist":"^1.2.1"},"gitHead":"bc20891ca1f93008b39d5bafdad8657c92eac85e","_id":"@brianleishman/tsickle@0.46.3-1","_nodeVersion":"19.4.0","_npmVersion":"9.2.0","dist":{"integrity":"sha512-Iq7HZDXbT4gdy8iS1Rl7iVz7kT8C5QXIGmSJDdGmbLs3fy6Vih+X0zovPjh82J+oa+BZu6XMXBbY5FJuVh284w==","shasum":"ffb3e4b5e628e3042f22ab27169873c0866dd30b","tarball":"https://registry.npmjs.org/@brianleishman/tsickle/-/tsickle-0.46.3-1.tgz","fileCount":60,"unpackedSize":688419,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIDk5nTMWjEu3AAClvzQUcUFa4KgUN2lJRxFDGOYhfQaMAiBokr/zVfeDGMttMLKALltcAnXwXFJs8gDEyA7u6XGI+A=="}]},"_npmUser":{"name":"brianleishman","email":"b@rian.gg"},"maintainers":[{"name":"brianleishman","email":"b@rian.gg"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/tsickle_0.46.3-1_1725400439186_0.34198664103298637"},"_hasShrinkwrap":false}},"time":{"created":"2024-09-03T21:53:59.083Z","0.46.3-1":"2024-09-03T21:53:59.420Z","modified":"2024-09-03T21:53:59.689Z"},"maintainers":[{"name":"brianleishman","email":"b@rian.gg"}],"description":"Transpile TypeScript code to JavaScript with Closure annotations.","homepage":"https://github.com/angular/tsickle","keywords":["typescript","closure"],"repository":{"type":"git","url":"git+https://github.com/angular/tsickle.git"},"contributors":[{"name":"Evan Martin","email":"evanm@google.com","url":"https://angular.io/"},{"name":"Alex Eagle","email":"alexeagle@google.com","url":"https://angular.io/"},{"name":"Martin Probst","email":"martinprobst@google.com","url":"https://angular.io/"},{"name":"Rado Kirov","email":"radokirov@google.com","url":"https://angular.io/"},{"name":"Thomas Deegan","email":"tdeegan@google.com"}],"bugs":{"url":"https://github.com/angular/tsickle/issues"},"license":"MIT","readme":"# Tsickle - TypeScript to Closure Translator [![Build Status](https://github.com/angular/tsickle/actions/workflows/node.js.yml/badge.svg)](https://github.com/angular/tsickle/actions/workflows/node.js.yml)\n\nTsickle converts TypeScript code into a form acceptable to the [Closure\nCompiler]. This allows using TypeScript to transpile your sources, and then\nusing Closure Compiler to bundle and optimize them, while taking advantage of\ntype information in Closure Compiler.\n\n[closure compiler]: https://github.com/google/closure-compiler/\n\n## What conversion means\n\nA (non-exhaustive) list of the sorts of transformations Tsickle applies:\n\n- inserts Closure-compatible JSDoc annotations on functions/classes/etc\n- converts ES6 modules into `goog.module` modules\n- generates externs.js from TypeScript d.ts (and `declare`, see below)\n- declares types for class member variables\n- translates `export * from ...` into a form Closure accepts\n- converts TypeScript enums into a form Closure accepts\n- reprocesses all jsdoc to strip Closure-invalid tags\n\nIn general the goal is that you write valid TypeScript and Tsickle handles\nmaking it valid Closure Compiler code.\n\n## Warning: work in progress\n\nWe already use tsickle within Google to minify our apps (including those using\nAngular), but we have less experience using tsickle with the various JavaScript\nbuilds that are seen outside of Google.\n\nWe would like to make tsickle usable for everyone but right now if you'd like\nto try it you should expect to spend some time debugging and reporting bugs.\n\n## Usage\n\nTsickle is a library, designed to be used by a larger program that interacts\nwith TypeScript and the Closure compiler.\n\nSome known clients are:\n\n1. Within Google we use tsickle inside the [Bazel build\n   system](https://bazel.build/). That code is published as\n   open source as part of [Bazel's nodejs/TypeScript\n   build rules](https://bazelbuild.github.io/rules_nodejs/).\n1. [tscc](https://github.com/theseanl/tscc) wraps tsickle and\n   closure compiler, and interops with rollup.\n1. We publish a simple demo program in the `demo/` subdirectory.\n\n## Design details\n\n### Output format\n\nTsickle is designed to do whatever is necessary to make the code acceptable by\nClosure compiler. We view its output as a necessary intermediate form for\ncommunicating to the Closure compiler, and not something for humans. This means\nthe tsickle output may be kind of ugly to read. Its only real use is to pass it\non to the compiler.\n\nFor one example, the syntax of types tsickle produces are specific to Closure.\nThe type `{!Foo}` means \"Foo, excluding null\" and a type alias becomes a `var`\nstatement that is tagged with `@typedef`.\n\nTsickle emits modules using Closure's `goog.module` module system. This system\nis similar to but different from ES modules, and was supported by Closure before\nthe ES module system was finalized.\n\n### Differences from TypeScript\n\nClosure and TypeScript are not identical. Tsickle hides most of the\ndifferences, but users must still be aware of some differences.\n\n#### `declare`\n\nAny declaration in a `.d.ts` file, as well as any declaration tagged with\n`declare ...`, is intepreted by Tsickle as a name that should be preserved\nthrough Closure compilation (i.e. not renamed into something shorter). Use it\nany time the specific string names of your fields are significant. That would\nmost often happen when the object either coming from outside your program, or\nbeing passed out of the program.\n\nExample:\n\n    declare interface JSONResult {\n        username: string;\n    }\n    let r = JSON.parse(input) as JSONResult;\n    console.log(r.username);\n\nBy adding `declare` to the interface (or if it were in a `.d.ts` file), Tsickle\nwill inform Closure that it must use exactly the field name `.username` (and not\ne.g. `.a`) in the output JS. This matters for this example because the input\nJSON probably uses the string `'username'` and not whatever name Closure would\ninvent for it. (Note: `declare` on an interface has no additional meaning in\npure TypeScript.)\n\n#### Exporting decorators\n\nAn exporting decorator is a decorator that has `@ExportDecoratedItems` in its\nJSDoc.\n\nThe names of elements that have an exporting decorator are preserved through\nthe Closure compilation process by applying an `@export` tag to them.\n\nExample:\n\n    /** @ExportDecoratedItems */\n    function myDecorator() {\n      // ...\n    }\n\n    @myDecorator()\n    class DoNotRenameThisClass { ... }\n\n## Development\n\n### Dependencies\n\n- nodejs. Install from your operating system's package manger, by following\n  instructions on https://nodejs.org/en/, or by using\n  [NVM](https://github.com/nvm-sh/nvm)\n- yarn. Install from your operating system's package manager or by following\n  [instructions on yarnpkg.com](https://yarnpkg.com/en/docs/install).\n\n### One-time setup\n\nRun `yarn` to install dependencies.\n\n### Build & Test commands\n\n- `yarn build` builds the code base.\n- Run `tsc --watch` for an interactive, incremental, and continuous build.\n- `yarn lint` checks for lint.\n- `yarn test` runs unit tests, e2e tests and checks for lint (but make sure to\n  `yarn build` first or run tsc!). Set the `TEST_FILTER` environment variable\n  to filter what golden tests to run.\n\n### TypeScript AST help\n\nhttps://astexplorer.net/ and https://ts-ast-viewer.com/ are convenient tools to\nvisualize and inspect a TypeScript AST.\n\n### Debugging\n\nYou can debug tests by passing `--node_options=--inspect` or\n`--node_options=--inspect-brk` (to suspend execution directly after startup).\n\nFor example, to debug a specific golden test:\n\n```shell\nTEST_FILTER=my_golden_test node --inspect-brk=4332 ./node_modules/.bin/jasmine out/test/*.js\n```\n\nThen open [about:inspect] in Chrome and choose \"about:inspect\". Chrome will\nlaunch a debugging session on any node process that starts with a debugger\nlistening on one of the listed ports. The tsickle tests and Chrome both default\nto `localhost:9229`, so things should work out of the box.\n\nThe break in specific code locations you can add `debugger;` statements in the\nsource code.\n\n### Updating Goldens\n\nRun `UPDATE_GOLDENS=y yarn test` to have the test suite update the goldens in\n`test_files/...`.\n\n### Environment variables\n\nSet the environment variable `TEST_FILTER=<REGEX>` to limit the golden tests\n(found in `test_files/...`) to only run tests with a name matching the regex.\n\n### Releasing\n\nOn a new branch, run\n\n```\n# tsickle releases are all minor releases for now, see npm help version.\n$ npm version minor\n```\n\nThis will update the version in `package.json`, commit the changes, and\ncreate a git tag.\n\nPush the branch and get it reviewed, but _do not merge_. If you click\nthe \"rebase and merge\" button in the Github UI it changes the commit,\nso the git tag that was created would point at the wrong commit.\n\nInstead, push the branch to master directly via:\n\n```\n$ git push origin mybranch:master\n```\n\nNote that Github will block non-fast-forward pushes to master, so if\nthere have been other intervening commits you'll need to recreate the\nrelease.\n\nAlso push the tag.\n\n```\n$ git push origin v0.32.0  # but use correct version\n```\n\nOnce the versioned tag is pushed to Github the release (as found on\nhttps://github.com/angular/tsickle/releases) will be implicitly created.\n\nFrom the master branch run:\n\n```\nnpm config set registry https://wombat-dressing-room.appspot.com\nnpm login\nnpm publish  # runs a clean build & test automatically\n```\n","readmeFilename":"README.md"}