@rushstack/typings-generator - npm Package Compare versions

Comparing version 0.10.37 to 0.11.0

dist/typings-generator.d.ts

@@ -14,3 +14,3 @@ /**
  */
-export declare interface IStringValuesTypingsGeneratorOptions extends ITypingsGeneratorOptions<IStringValueTypings | undefined> {
+export declare interface IStringValuesTypingsGeneratorBaseOptions {
     /**
@@ -30,2 +30,14 @@ * Setting this option wraps the typings export in a default property.
  */
+export declare interface IStringValuesTypingsGeneratorOptions<TFileContents extends string = string> extends ITypingsGeneratorOptions<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
+}
+
+/**
+ * @public
+ */
+export declare interface IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents = string> extends ITypingsGeneratorOptionsWithCustomReadFile<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
+}
+
+/**
+ * @public
+ */
 export declare interface IStringValueTyping {
@@ -57,5 +69,21 @@ exportName: string;
  */
-export declare interface ITypingsGeneratorOptions<TTypingsResult = string | undefined> extends ITypingsGeneratorBaseOptions {
+export declare interface ITypingsGeneratorOptions<TTypingsResult = string | undefined, TFileContents extends string = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
+    readFile?: ReadFile<TFileContents>;
+}
+
+/**
+ * Options for a TypingsGenerator that needs to customize how files are read.
+ *
+ * @public
+ */
+export declare interface ITypingsGeneratorOptionsWithCustomReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
+    readFile: ReadFile<TFileContents>;
+}
+
+/**
+ * @public
+ */
+export declare interface ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorBaseOptions {
     fileExtensions: string[];
-    parseAndGenerateTypings: (fileContents: string, filePath: string, relativePath: string) => TTypingsResult | Promise<TTypingsResult>;
+    parseAndGenerateTypings: (fileContents: TFileContents, filePath: string, relativePath: string) => TTypingsResult | Promise<TTypingsResult>;
     getAdditionalOutputFiles?: (relativePath: string) => string[];
@@ -71,2 +99,7 @@ /**
 /**
+ * @public
+ */
+export declare type ReadFile<TFileContents = string> = (filePath: string, relativePath: string) => Promise<TFileContents> | TFileContents;
+
+/**
  * This is a simple tool that generates .d.ts files for non-TS files that can be represented as
@@ -77,4 +110,5 @@ * a simple set of named string exports.
  */
-export declare class StringValuesTypingsGenerator extends TypingsGenerator {
-    constructor(options: IStringValuesTypingsGeneratorOptions);
+export declare class StringValuesTypingsGenerator<TFileContents = string> extends TypingsGenerator<TFileContents> {
+    constructor(options: TFileContents extends string ? IStringValuesTypingsGeneratorOptions<TFileContents> : never);
+    constructor(options: IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents>);
 }
@@ -87,7 +121,7 @@
  */
-export declare class TypingsGenerator {
+export declare class TypingsGenerator<TFileContents = string> {
     private readonly _dependenciesOfFile;
     private readonly _consumersOfFile;
     private readonly _relativePaths;
-    protected _options: ITypingsGeneratorOptions;
+    protected _options: ITypingsGeneratorOptionsWithCustomReadFile<string | undefined, TFileContents>;
     /**
@@ -105,3 +139,4 @@ * The folder path that contains all input source files.
     readonly ignoredFileGlobs: readonly string[];
-    constructor(options: ITypingsGeneratorOptions);
+    constructor(options: TFileContents extends string ? ITypingsGeneratorOptions<string | undefined, TFileContents> : never);
+    constructor(options: ITypingsGeneratorOptionsWithCustomReadFile<string | undefined, TFileContents>);
     /**
@@ -108,0 +143,0 @@ * Generate typings for the provided input files.

lib/index.d.ts

@@ -8,4 +8,4 @@ /**
  */
-export { ITypingsGeneratorBaseOptions, ITypingsGeneratorOptions, TypingsGenerator } from './TypingsGenerator';
-export { IStringValueTyping, IStringValueTypings, IStringValuesTypingsGeneratorOptions, StringValuesTypingsGenerator } from './StringValuesTypingsGenerator';
+export { type ReadFile, type ITypingsGeneratorBaseOptions, type ITypingsGeneratorOptionsWithoutReadFile, type ITypingsGeneratorOptions, type ITypingsGeneratorOptionsWithCustomReadFile, TypingsGenerator } from './TypingsGenerator';
+export { type IStringValueTyping, type IStringValueTypings, type IStringValuesTypingsGeneratorBaseOptions, type IStringValuesTypingsGeneratorOptions, type IStringValuesTypingsGeneratorOptionsWithCustomReadFile, StringValuesTypingsGenerator } from './StringValuesTypingsGenerator';
 //# sourceMappingURL=index.d.ts.map

lib/StringValuesTypingsGenerator.d.ts

@@ -1,2 +0,2 @@
-import { ITypingsGeneratorOptions, TypingsGenerator } from './TypingsGenerator';
+import { type ITypingsGeneratorOptions, TypingsGenerator, type ITypingsGeneratorOptionsWithCustomReadFile } from './TypingsGenerator';
 /**
@@ -18,3 +18,3 @@ * @public
  */
-export interface IStringValuesTypingsGeneratorOptions extends ITypingsGeneratorOptions<IStringValueTypings | undefined> {
+export interface IStringValuesTypingsGeneratorBaseOptions {
     /**
@@ -31,2 +31,12 @@ * Setting this option wraps the typings export in a default property.
 /**
+ * @public
+ */
+export interface IStringValuesTypingsGeneratorOptions<TFileContents extends string = string> extends ITypingsGeneratorOptions<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
+}
+/**
+ * @public
+ */
+export interface IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents = string> extends ITypingsGeneratorOptionsWithCustomReadFile<IStringValueTypings | undefined, TFileContents>, IStringValuesTypingsGeneratorBaseOptions {
+}
+/**
  * This is a simple tool that generates .d.ts files for non-TS files that can be represented as
@@ -37,5 +47,6 @@ * a simple set of named string exports.
  */
-export declare class StringValuesTypingsGenerator extends TypingsGenerator {
-    constructor(options: IStringValuesTypingsGeneratorOptions);
+export declare class StringValuesTypingsGenerator<TFileContents = string> extends TypingsGenerator<TFileContents> {
+    constructor(options: TFileContents extends string ? IStringValuesTypingsGeneratorOptions<TFileContents> : never);
+    constructor(options: IStringValuesTypingsGeneratorOptionsWithCustomReadFile<TFileContents>);
 }
 //# sourceMappingURL=StringValuesTypingsGenerator.d.ts.map

lib/StringValuesTypingsGenerator.js

@@ -9,2 +9,37 @@ "use strict";
 const EXPORT_AS_DEFAULT_INTERFACE_NAME = 'IExport';
+function convertToTypingsGeneratorOptions(options) {
+    async function parseAndGenerateTypings(fileContents, filePath, relativePath) {
+        const stringValueTypings = await options.parseAndGenerateTypings(fileContents, filePath, relativePath);
+        if (stringValueTypings === undefined) {
+            return;
+        }
+        const outputLines = [];
+        const interfaceName = options.exportAsDefaultInterfaceName
+            ? options.exportAsDefaultInterfaceName
+            : EXPORT_AS_DEFAULT_INTERFACE_NAME;
+        let indent = '';
+        if (options.exportAsDefault) {
+            outputLines.push(`export interface ${interfaceName} {`);
+            indent = '  ';
+        }
+        for (const stringValueTyping of stringValueTypings.typings) {
+            const { exportName, comment } = stringValueTyping;
+            if (comment && comment.trim() !== '') {
+                outputLines.push(`${indent}/**`, `${indent} * ${comment.replace(/\*\//g, '*\\/')}`, `${indent} */`);
+            }
+            if (options.exportAsDefault) {
+                outputLines.push(`${indent}'${exportName}': string;`, '');
+            }
+            else {
+                outputLines.push(`export declare const ${exportName}: string;`, '');
+            }
+        }
+        if (options.exportAsDefault) {
+            outputLines.push('}', '', `declare const strings: ${interfaceName};`, '', 'export default strings;');
+        }
+        return outputLines.join(os_1.EOL);
+    }
+    const convertedOptions = Object.assign(Object.assign({}, options), { parseAndGenerateTypings });
+    return convertedOptions;
+}
 /**
@@ -18,33 +53,3 @@ * This is a simple tool that generates .d.ts files for non-TS files that can be represented as
     constructor(options) {
-        super(Object.assign(Object.assign({}, options), { parseAndGenerateTypings: async (fileContents, filePath, relativePath) => {
-                const stringValueTypings = await options.parseAndGenerateTypings(fileContents, filePath, relativePath);
-                if (stringValueTypings === undefined) {
-                    return;
-                }
-                const outputLines = [];
-                const interfaceName = options.exportAsDefaultInterfaceName
-                    ? options.exportAsDefaultInterfaceName
-                    : EXPORT_AS_DEFAULT_INTERFACE_NAME;
-                let indent = '';
-                if (options.exportAsDefault) {
-                    outputLines.push(`export interface ${interfaceName} {`);
-                    indent = '  ';
-                }
-                for (const stringValueTyping of stringValueTypings.typings) {
-                    const { exportName, comment } = stringValueTyping;
-                    if (comment && comment.trim() !== '') {
-                        outputLines.push(`${indent}/**`, `${indent} * ${comment.replace(/\*\//g, '*\\/')}`, `${indent} */`);
-                    }
-                    if (options.exportAsDefault) {
-                        outputLines.push(`${indent}'${exportName}': string;`, '');
-                    }
-                    else {
-                        outputLines.push(`export declare const ${exportName}: string;`, '');
-                    }
-                }
-                if (options.exportAsDefault) {
-                    outputLines.push('}', '', `declare const strings: ${interfaceName};`, '', 'export default strings;');
-                }
-                return outputLines.join(os_1.EOL);
-            } }));
+        super(convertToTypingsGeneratorOptions(options));
     }
@@ -51,0 +56,0 @@ }

lib/TypingsGenerator.d.ts

@@ -15,5 +15,5 @@ import { ITerminal } from '@rushstack/node-core-library';
  */
-export interface ITypingsGeneratorOptions<TTypingsResult = string | undefined> extends ITypingsGeneratorBaseOptions {
+export interface ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorBaseOptions {
     fileExtensions: string[];
-    parseAndGenerateTypings: (fileContents: string, filePath: string, relativePath: string) => TTypingsResult | Promise<TTypingsResult>;
+    parseAndGenerateTypings: (fileContents: TFileContents, filePath: string, relativePath: string) => TTypingsResult | Promise<TTypingsResult>;
     getAdditionalOutputFiles?: (relativePath: string) => string[];
@@ -28,2 +28,20 @@ /**
 /**
+ * @public
+ */
+export type ReadFile<TFileContents = string> = (filePath: string, relativePath: string) => Promise<TFileContents> | TFileContents;
+/**
+ * @public
+ */
+export interface ITypingsGeneratorOptions<TTypingsResult = string | undefined, TFileContents extends string = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
+    readFile?: ReadFile<TFileContents>;
+}
+/**
+ * Options for a TypingsGenerator that needs to customize how files are read.
+ *
+ * @public
+ */
+export interface ITypingsGeneratorOptionsWithCustomReadFile<TTypingsResult = string | undefined, TFileContents = string> extends ITypingsGeneratorOptionsWithoutReadFile<TTypingsResult, TFileContents> {
+    readFile: ReadFile<TFileContents>;
+}
+/**
  * This is a simple tool that generates .d.ts files for non-TS files.
@@ -33,7 +51,7 @@ *
  */
-export declare class TypingsGenerator {
+export declare class TypingsGenerator<TFileContents = string> {
     private readonly _dependenciesOfFile;
     private readonly _consumersOfFile;
     private readonly _relativePaths;
-    protected _options: ITypingsGeneratorOptions;
+    protected _options: ITypingsGeneratorOptionsWithCustomReadFile<string | undefined, TFileContents>;
     /**
@@ -51,3 +69,4 @@ * The folder path that contains all input source files.
     readonly ignoredFileGlobs: readonly string[];
-    constructor(options: ITypingsGeneratorOptions);
+    constructor(options: TFileContents extends string ? ITypingsGeneratorOptions<string | undefined, TFileContents> : never);
+    constructor(options: ITypingsGeneratorOptionsWithCustomReadFile<string | undefined, TFileContents>);
     /**
@@ -54,0 +73,0 @@ * Generate typings for the provided input files.

lib/TypingsGenerator.js

@@ -44,27 +44,28 @@ "use strict";
     constructor(options) {
-        this._options = Object.assign({}, options);
+        var _a;
+        this._options = Object.assign(Object.assign({}, options), { readFile: (_a = options.readFile) !== null && _a !== void 0 ? _a : ((filePath, relativePath) => node_core_library_1.FileSystem.readFileAsync(filePath)) });
         if (options.filesToIgnore) {
             throw new Error('The filesToIgnore option is no longer supported. Please use globsToIgnore instead.');
         }
-        if (!this._options.generatedTsFolder) {
+        if (!options.generatedTsFolder) {
             throw new Error('generatedTsFolder must be provided');
         }
-        if (!this._options.srcFolder) {
+        if (!options.srcFolder) {
             throw new Error('srcFolder must be provided');
         }
-        this.sourceFolderPath = this._options.srcFolder;
-        if (node_core_library_1.Path.isUnder(this._options.srcFolder, this._options.generatedTsFolder)) {
+        this.sourceFolderPath = options.srcFolder;
+        if (node_core_library_1.Path.isUnder(options.srcFolder, options.generatedTsFolder)) {
             throw new Error('srcFolder must not be under generatedTsFolder');
         }
-        if (node_core_library_1.Path.isUnder(this._options.generatedTsFolder, this._options.srcFolder)) {
+        if (node_core_library_1.Path.isUnder(options.generatedTsFolder, options.srcFolder)) {
             throw new Error('generatedTsFolder must not be under srcFolder');
         }
-        if (!this._options.fileExtensions || this._options.fileExtensions.length === 0) {
+        if (!options.fileExtensions || options.fileExtensions.length === 0) {
             throw new Error('At least one file extension must be provided.');
         }
-        this.ignoredFileGlobs = this._options.globsToIgnore || [];
-        if (!this._options.terminal) {
+        this.ignoredFileGlobs = options.globsToIgnore || [];
+        if (!options.terminal) {
             this._options.terminal = new node_core_library_1.Terminal(new node_core_library_1.ConsoleTerminalProvider({ verboseEnabled: true }));
         }
-        this._options.fileExtensions = this._normalizeFileExtensions(this._options.fileExtensions);
+        this._options.fileExtensions = this._normalizeFileExtensions(options.fileExtensions);
         this._dependenciesOfFile = new Map();
@@ -214,3 +215,3 @@ this._consumersOfFile = new Map();
         try {
-            const fileContents = await node_core_library_1.FileSystem.readFileAsync(resolvedPath);
+            const fileContents = await this._options.readFile(resolvedPath, relativePath);
             const typingsData = await this._options.parseAndGenerateTypings(fileContents, resolvedPath, relativePath);
@@ -217,0 +218,0 @@ // Typings data will be undefined when no types should be generated for the parsed file.

package.json

 {
   "name": "@rushstack/typings-generator",
-  "version": "0.10.37",
+  "version": "0.11.0",
   "description": "This library provides functionality for automatically generating typings for non-TS files.",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -36,2 +36,25 @@ # @rushstack/typings-generator
 
+```TypeScript
+import { TypingsGenerator } from '@rushstack/typings-generator';
+
+const assetTypingsGenerator: TypingsGenerator = new TypingsGenerator({
+  srcFolder: '/repo/package/src',
+  generatedTsFolder: '/repo/package/temp/generated-typings',
+  fileExtensions: ['.jpg'],
+  parseAndGenerateTypings: (fileContents: false, filePath: string) => {
+    const parsedFile = parseFile(fileContents);
+    const typings: string = 'declare const path: string;\nexport default path;';
+    return typings;
+  },
+  // Don't read files at all
+  readFile: (filePath: string, relativePath: string) => false
+});
+
+// To run once before a compilation:
+await typingsGenerator.generateTypings();
+
+// To start a watcher:
+await typingsGenerator.runWatcher();
+```
+
 ## Options
@@ -54,3 +77,3 @@
 
-### `parseAndGenerateTypings = (fileContents: string, filePath: string) => string | Promise<string>`
+### `parseAndGenerateTypings = (fileContents: TFileContents, filePath: string, relativePath: string) => string | Promise<string>`
 
@@ -61,2 +84,10 @@ This property is used to specify the function that should be called on every file for which typings
 
+### `readFile = (filePath: string, relativePath: string) => TFileContents | Promise<TFileContents>`
+
+This property allows customizing the process by which files are read from the specified paths.
+Use cases include:
+- Disabling reads altogether, if the typings don't depend on file content
+- Reading from an alternate data source
+- Reading files with a different encoding than 'utf-8'
+
 ### `terminal`
@@ -63,0 +94,0 @@

No alert changes

Improved metrics

Total package byte prevSize

68919

increased by15.09%

Lines of code

653

increased by11.43%

Number of lines in readme file

164

increased by23.31%

No dependency changes