8000 Merge pull request #1775 from iclanton/ianc/extract-typings-generator · JavaScriptExpert/rushstack@68fb131 · GitHub
[go: up one dir, main page]
Skip to content

Commit 68fb131

Browse files
iclantoniclanton
authored
Merge pull request microsoft#1775 from iclanton/ianc/extract-typings-generator
Genericize the TypingsGenerator utility from @rushstack/localization-plugin.
2 parents 15f7963 + 7b0bc3c commit 68fb131

24 files changed

+690
-208
lines changed

‎common/changes/@rushstack/localization-plugin/ianc-extract-typings-generator_2020-03-12-00-36.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@rushstack/localization-plugin",
5+
"comment": "Extract the TypingsGen 8000 erator logic to a new package.",
6+
"type": "patch"
7+
}
8+
],
9+
"packageName": "@rushstack/localization-plugin",
10+
"email": "iclanton@users.noreply.github.com"
11+
}

‎common/changes/@rushstack/typings-generator/ianc-extract-typings-generator_2020-03-12-00-36.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"packageName": "@rushstack/typings-generator",
5+
"comment": "Initial implementation.",
6+
"type": "minor"
7+
}
8+
],
9+
"packageName": "@rushstack/typings-generator",
10+
"email": "iclanton@users.noreply.github.com"
11+
}

‎common/config/rush/nonbrowser-approved-packages.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,10 @@
170170
"name": "@rushstack/localization-plugin",
171171
"allowedCategories": [ "tests" ]
172172
},
173+
{
174+
"name": "@rushstack/typings-generator",
175+
"allowedCategories": [ "libraries" ]
176+
},
173177
{
174178
"name": "@typescript-eslint/eslint-plugin",
175179
"allowedCategories": [ "libraries" ]

‎common/config/rush/pnpm-lock.yaml

Lines changed: 19 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎common/reviews/api/localization-plugin.api.md

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
```ts
66

77
import { loader } from 'webpack';
8+
import { StringValuesTypingsGenerator } from '@rushstack/typings-generator';
89
import { Terminal } from '@microsoft/node-core-library';
910
import * as Webpack from 'webpack';
1011

@@ -208,13 +209,9 @@ export class _LocFileParser {
208209
}
209210

210211
// @public
211-
export class TypingsGenerator {
212+
export class TypingsGenerator extends StringValuesTypingsGenerator {
212213
constructor(options: ITypingsGeneratorOptions);
213-
// (undocumented)
214-
generateTypings(): void;
215-
// (undocumented)
216-
runWatcher(): void;
217-
}
214+
}
218215

219216

220217
// (No @packageDocumentation comment for this package)

‎common/reviews/api/typings-generator.api.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
## API Report File for "@rushstack/typings-generator"
2+
3+
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
4+
5+
```ts
6+
7+
import { Terminal } from '@microsoft/node-core-library';
8+
9+
// @public (undocumented)
10+
export interface IStringValuesTypingsGeneratorOptions extends ITypingsGeneratorOptions<IStringValueTypings> {
11+
// (undocumented)
12+
exportAsDefault?: boolean;
13+
}
14+
15+
// @public (undocumented)
16+
export interface IStringValueTyping {
17+
// (undocumented)
18+
comment?: string;
19+
// (undocumented)
20+
exportName: string;
21+
}
22+
23+
// @public (undocumented)
24+
export interface IStringValueTypings {
25+
// (undocumented)
26+
typings: IStringValueTyping[];
27+
}
28+
29+
// @public (undocumented)
30+
export interface ITypingsGeneratorOptions<TTypingsResult = string> {
31+
// (undocumented)
32+
fileExtensions: string[];
33+
// (undocumented)
34+
filesToIgnore?: string[];
35+
// (undocumented)
36+
generatedTsFolder: string;
37+
// (undocumented)
38+
parseAndGenerateTypings: (fileContents: string, filePath: string) => TTypingsResult;
39+
// (undocumented)
40+
srcFolder: string;
41+
// (undocumented)
42+
terminal?: Terminal;
43+
}
44+
45+
// @public
46+
export class StringValuesTypingsGenerator extends TypingsGenerator {
47+
constructor(options: IStringValuesTypingsGeneratorOptions);
48+
}
49+
50+
// @public
51+
export class TypingsGenerator {
52+
constructor(options: ITypingsGeneratorOptions);
53+
// (undocumented)
54+
generateTypings(): void;
55+
// (undocumented)
56+
protected _options: ITypingsGeneratorOptions;
57+
// (undocumented)
58+
runWatcher(): void;
59+
}
60+
61+
62+
// (No @packageDocumentation comment for this package)
63+
64+
```

‎libraries/typings-generator/.eslintrc.js

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
// This is a workaround for https://github.com/eslint/eslint/issues/3458
2+
require("@rushstack/eslint-config/patch-eslint6");
3+
4+
module.exports = {
5+
extends: [ "@rushstack/eslint-config" ],
6+
parserOptions: { tsconfigRootDir: __dirname },
7+
};

‎libraries/typings-generator/.npmignore

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Ignore everything by default
2+
**
3+
4+
# Use negative patterns to bring back the specific things we want to publish
5+
!/bin/**
6+
!/lib/**
7+
!/dist/**
8+
!ThirdPartyNotice.txt
9+
10+
# Ignore certain files in the above folder
11+
/dist/*.stats.*
12+
/lib/**/test/*
13+
14+
# NOTE: These don't need to be specified, because NPM includes them automatically.
15+
#
16+
# package.json
17+
# README (and its variants)
18+
# CHANGELOG (and its variants)
19+
# LICENSE / LICENCE
20+
21+
## Project specific definitions
22+
# -----------------------------
23+
24+
# (Add your exceptions here)

‎libraries/typings-generator/LICENSE

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
@rushstack/typings-generator
2+
3+
Copyright (c) Microsoft Corporation. All rights reserved.
4+
5+
MIT License
6+
7+
Permission is hereby granted, free of charge, to any person obtaining
8+
a copy of this software and associated documentation files (the
9+
"Software"), to deal in the Software without restriction, including
10+
without limitation the rights to use, copy, modify, merge, publish,
11+
distribute, sublicense, and/or sell copies of the Software, and to
12+
permit persons to whom the Software is furnished to do so, subject to
13+
the following conditions:
14+
15+
The above copyright notice and this permission notice shall be
16+
included in all copies or substantial portions of the Software.
17+
18+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
21+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
22+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
23+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
24+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎libraries/typings-generator/README.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Typings Generator
2+
3+
## Installation
4+
5+
`npm install @rushstack/typings-generator --save-dev`
6+
7+
## Overview
8+
9+
This is a utility for generating typings for non-TS files. It can operate in either a single-run mode or
10+
a watch mode. It is designed to generate `.d.ts` files with a specified generation function for all files matching
11+
specified file extensions, with an option to ignore individual files.
12+
13+
## Usage
14+
15+
```TypeScript
16+
import { TypingsGenerator } from '@rushstack/typings-generator';
17+
18+
const typingsGenerator: TypingsGenerator = new TypingsGenerator({
19+
srcFolder: '/repo/package/src',
20+
generatedTsFolder: '/repo/package/temp/generated-typings',
21+
fileExtensions: ['file-extension'],
22+
parseAndGenerateTypings: (fileContents: string, filePath: string) => {
23+
const parsedFile = parseFile(fileContents);
24+
const typings: string = generateTypings(parsedFile);
25+
return typings;
26+
}
27+
});
28+
29+
// To run once before a compilation:
30+
typingsGenerator.generateTypings();
31+
32+
// To start a watcher:
33+
typingsGenerator.runWatcher();
34+
```
35+
36+
## Options
37+
38+
### `srcFolder = '...'`
39+
40+
This property is used as the source root folder for discovery of files for which typings should be generated.
41+
42+
### `generatedTsFolder = '...'`
43+
44+
This property specifies the folder in which `.d.ts` files should be dropped. It is recommended
45+
that this be a folder parallel to the source folder, specified in addition to the source folder in the
46+
[`rootDirs` `tsconfig.json` option](https://www.typescriptlang.org/docs/handbook/compiler-options.html).
47+
**The folder specified by this option is emptied when the utility is invoked.**
48+
49+
### `fileExtensions = [...]`
50+
51+
This property enumerates the file extensions that should be handled.
52+
53+
### `parseAndGenerateTypings = (fileContents: string, filePath: string) => string`
54+
55+
This property is used to specify the function that should be called on every file for which typings
56+
are being generated. In watch mode, this is called on every file creation and file update. It should
57+
return TypeScript declarations for the file it is called with.
58+
59+
### `terminal`
60+
61+
Optionally provide a [Terminal](https://github.com/microsoft/rushstack/blob/master/libraries/node-core-library/src/Terminal/Terminal.ts)
62+
object for logging. If one isn't provided, logs will go to the terminal.
63+
64+
### `filesToIgnore`
65+
66+
Optionally, provide an array of paths to files that should be ignored. These paths can either be absolute
67+
paths, or paths relative to the [`srcFolder`](#srcFolder--)
68+
69+
## `StringValuesTypingsGenerator`
70+
71+
There is an extension of this utility specifically for file types where typings should be a simple
72+
set of exported string values. This is useful for file types like CSS and RESX. This class takes
73+
the same options as the standard `TypingsGenerator`, with one additional option ([`exportAsDefault`](#exportAsDefault--)) and a different return value for `parseAndGenerateTypings`.
74+
75+
### `parseAndGenerateTypings = (fileContents: string, filePath: string) => { typings: ({ exportName: string, comment?: string })[] }`
76+
77+
This function should behave the same as the `parseAndGenerateTypings` function for the standard
78+
`TypingsGenerator`, except that it should return an object with a `typings` property, set to
79+
an array of objects with an `exportName` property and an optional `comment` property.
80+
See the example below.
81+
82+
#### Example return value:
83+
84+
```TypeScript
85+
{
86+
typings: [
87+
{
88+
exportName: 'myExport'
89+
},
90+
{
91+
exportName: 'myOtherExport',
92+
comment: 'This is the other export'
93+
}
94+
]
95+
}
96+
```
97+
98+
#### Example generated declaration file:
99+
100+
```TypeScript
101+
// This file was generated by a tool. Modifying it will produce unexpected behavior
102+
103+
export declare const myExport: string;
104+
105+
/**
106+
* This is the other export
107+
*/
108+
export declare const myOtherExport: string;
109+
110+
```
111+
112+
### `exportAsDefault = true | false`
113+
114+
If this option is set to `true`, the typings will be exported wrapped in a `default` property. This
115+
allows the file to be imported by using the `import myFile from './myFile.my-extension';` syntax instead of
116+
the `import { myExport } from './myFile.my-extension';` or the `import * as myFile from './myFile.my-extension';`
117+
syntax. This style of export is not recommended as it can prevent tree-shaking optimization.

0 commit comments

Comments
 (0)
0