introspeql 0.0.3 → 1.0.0

package/README.md

@@ -1,113 +1,314 @@
 # IntrospeQL
 
-IntrospeQL is a TypeScript utility for **introspecting PostgreSQL** schemas
-(tables, functions, types) and **generating TypeScript types** from them.
-The aim is to make capturing PostgreSQL types and producing matching TypeScript
-types easy, comprehensive, and accurate.
+IntrospeQL reads information about the schemas, tables, columns, functions, and
+enums in your PostgreSQL database and produces a TypeScript file detailing
+type information for each database object.
 
-> ⚠️ **Warning: Alpha / Not Production Ready**  
-> This library is currently in alpha. Use with caution; it is not yet hardened
-> for production.
+## Installation
 
-## Features
+Install IntrospeQL as a dev dependency:
 
-- Connects to a PostgreSQL database and introspects table schemas, functions,
-  and enums.
-- Automatically emits corresponding TypeScript types.
-- Converts PostgreSQL types to TypeScript types in alignment with Node-Postgres
-  defaults. Can be extended to convert PostgreSQL types to any desired TypeScript
-  type.
+```
+npm install --save-dev introspeql
+```
+
+## Quick Start
+
+Install [tsx](https://tsx.is/) and [@types/node](https://www.npmjs.com/package/@types/node):
+
+```
+npm install --save-dev tsx @types/node
+```
+
+Install [dotenv](https://www.npmjs.com/package/dotenv):
+
+```
+npm install --save dotenv
+```
 
-## Example Usage
+Add the following entry to the scripts object in package.json:
 
-```typescript
-// src/scripts/gen-db-types.ts
+```
+"gen-types": "npx tsx scripts/gen-types.ts"
+```
+
+Create a scripts directory at the root level of your project, and inside this 
+folder, create a new TypeScript file called `gen-types.ts`.
+
+Add the following content to `scripts/gen-types.ts`:
+
+```
 import 'dotenv/config';
 import path from 'node:path';
-import { generateTypes, type IntrospeQLConfig } from 'introspeql';
+import { introspeql, type IntrospeQLConfig } from 'introspeql';
+
+const outFile = '/generated/type-definitions.ts';
 
 const config: IntrospeQLConfig = {
-  dbConnectionString: process.env.DATABASE_URL,
-  outFile: path.join(import.meta.dirname, '../db/types.ts'),
-  schemas: ['public'],
-  ignoreTables: [
-    {
-      schema: 'public',
-      name: 'spatial_ref_sys',
-    },
-  ],
-  header:
-`
-// Custom header:
-import type { Geography } from '../model/geography';
-`
-  types: {
-    'public.geography': 'Geography'
+  schemas: ['public'], // Add other schemas as necessary
+  dbConnectionParams: {
+    host: process.env.DB_HOST,
+    port: +process.env.DB_PORT!,
+    database: process.env.DB_NAME,
+    user: process.env.DB_USER,
+    password: process.env.DB_PASSWORD,
   },
+  writeToDisk: true,
+  outFile: path.join(__dirname, '..' + outFile),
+  header: 
+    '/* This file has been generated by IntrospeQL and should not be edited directly. */',
+  types: {
+    'pg_catalog.void': 'void'
+  }
 };
 
-generateTypes(config);
+genTypes();
+
+async function genTypes() {
+  await introspeql(config);
+  console.log("Type definition file created at " + outFile);
+}
+```
+
+Create a `.gitignore` file at the root of your project and make sure it includes 
+`node_modules` and `.env`:
+
+```
+# .gitignore
+node_modules/
+.env
 ```
 
-## Example Output
+Create a `.env` file at the root of your project and add your database connection 
+information:
+```
+# .env
+DB_HOST= # Add your host here, often just localhost
+DB_PORT= # Add your port here
+DB_NAME= # Add the name of the database you wish to connect to here
+DB_USER= # Add the PostgreSQL username that should be used to connect to the db
+DB_PASSWORD= # Add the password for this user here
+```
 
-```typescript
-// src/db/types.ts
+Execute your script:
 
-/* This file was generated by IntrospeQL. Do not edit manually. */
-// Custom header:
-import type { Geography } from '../model/geography';
+```
+npm run gen-types
+```
 
-export namespace Public {
-  export const SchemaName = 'public';
+A type definition file will have been generated at `generated/type-definitions.ts`.
 
-  export namespace Enums {
-    export enum DistanceUnits {
-      METERS = 'METERS',
-      KILOMETERS = 'KILOMETERS',
-      MILES = 'MILES',
-    }
-  }
+> ⚠️ **Important**  
+> Never hard code sensitive information directly into your project. Instead, 
+> load such information from environment variables and ensure that .env files 
+> are not committed to source control.
 
-  export namespace Tables {
-    export namespace StoreLocations {
-      export const TableName = 'store_locations';
-
-      export enum ColumnNames {
-        Id = 'id',
-        Coordinates = 'coordinates',
-        StreetAddressLine1 = 'street_address_line_1',
-        StreetAddressLine2 = 'street_address_line_2',
-        City = 'city',
-        State = 'state',
-        ZipCode = 'zip_code',
-      }
-
-      export interface RowType {
-        [ColumnNames.Id]: number;
-        [ColumnNames.Coordinates]: Geography;
-        [ColumnNames.StreetAddressLine1]: string;
-        [ColumnNames.StreetAddressLine2]: string | null;
-        [ColumnNames.City]: string;
-        [ColumnNames.State]: string;
-        [ColumnNames.ZipCode]: string;
-      }
-    }
-  }
+## Output
 
-  export namespace Procedures {
-    export namespace DistanceWithUnits {
-      export const ProcedureName = 'distance_with_units';
+The type definitions file consists of nested 
+[namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html). 
+Each top-level namespace represents a schema and contains the name of the schema 
+as well as type definitions for its tables, functions, and enums, grouped by 
+category into nested namespaces. Each table and function, in turn, consists of a 
+namespace. 
 
-      export const ArgNames = ['point_a', 'point_b', 'units'] as const;
+Table namespaces contain the name of the table, a union of string literals 
+representing the names of the columns of the table, and an object-type 
+representing the structure of each row.
 
-      export type ArgTypes = [Geography, Geography, Enums.DistanceUnits];
+Function namespaces contain the name of the function and an array of overloads. 
+Each overload contains an array of parameter types and (separately from the 
+array of parameter types) the return type.
+
+Enums are represented as unions of string literals, with each string literal 
+representing one possible value of the enum.
+
+A header can be added to the file. This is useful to import types that will be 
+used later in the file. In the example, we simply added a comment to the top of 
+the file indicating that the file was autogenerated and should not be changed 
+manually.
+
+## Configuration
+
+### Root-Level Configuration
+
+The following options exist directly on the top-level configuration object.
+
+| Option               | Type                     | Required    | Default      | Description                                                                                     |
+| -------------------- | ------------------------ | ----------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `schemas`            | `string[]`               | No          | `['public']` | PostgreSQL schemas to introspect. At least one schema must be specified.                        |
+| `header`             | `string`                 | No          | —            | Text inserted at the top of the generated output file (e.g., additional type imports or definitions).    |
+| `types`              | `Record<string, string>` | No          | —            | Custom PostgreSQL-to-TypeScript type mappings that override built-in defaults. These should be specified in the format `<schema>.<type>`, e.g. `'pg_catalog.int8'`               |
+| `copyComments`       | `boolean`                | No          | `true`       | Whether database comments are copied into generated TypeScript documentation comments.          |
+| `dbConnectionString` | `string`                 | Conditional | —            | PostgreSQL connection string. Exactly one of this or `dbConnectionParams` must be provided.     |
+| `dbConnectionParams` | `object`                 | Conditional | —            | PostgreSQL connection parameters. Exactly one of this or `dbConnectionString` must be provided. |
+| `writeToDisk`        | `boolean`                | Yes         | —            | Controls whether generated output is written to disk.                                           |
+| `outFile`            | `string`                 | Conditional | —            | Output file path. Required when `writeToDisk` is `true`.                                        |
+| `tables`             | `TableOptions`           | No          | —            | Table filtering configuration.                                                                  |
+| `functions`          | `FunctionOptions`        | No          | —            | Function filtering and typing configuration.                                                    |
+
+#### `dbConnectionParams`
+
+| Option     | Type     | Required | Description         |
+| ---------- | -------- | -------- | ------------------- |
+| `user`     | `string` | No       | Database user name. |
+| `password` | `string` | No       | Database password.  |
+| `host`     | `string` | No       | Database host.      |
+| `port`     | `number` | No       | Database port.      |
+| `database` | `string` | No       | Database name.      |
+
+---
+
+### Table Options
+
+Controls which database tables are included in the generated output.
+
+| Option          | Type                         | Required | Default       | Description                                         |
+| --------------- | ---------------------------- | -------- | ------------- | --------------------------------------------------- |
+| `mode`          | `'inclusive' \| 'exclusive'` | No       | `'inclusive'` | Determines how table filtering is applied.          |
+| `excludeTables` | `string[]`                   | No       | `[]`          | Tables to exclude when operating in inclusive mode. |
+| `includeTables` | `string[]`                   | No       | `[]`          | Tables to include when operating in exclusive mode. |
+
+---
+
+### Function Options
+
+Controls which PostgreSQL functions are included and how their types are generated.
+
+| Option                | Type                         | Required | Default       | Description                                                 |
+| --------------------- | ---------------------------- | -------- | ------------- | ----------------------------------------------------------- |
+| `mode`                | `'inclusive' \| 'exclusive'` | No       | `'inclusive'` | Determines how function filtering is applied.               |
+| `excludeFunctions`    | `string[]`                   | No       | `[]`          | Functions to exclude when operating in inclusive mode.      |
+| `includeFunctions`    | `string[]`                   | No       | `[]`          | Functions to include when operating in exclusive mode.      |
+| `nullableArgs`        | `boolean`                    | No       | `false`       | Treat function arguments as nullable in generated types.    |
+| `nullableReturnTypes` | `boolean`                    | No       | `true`        | Treat function return types as nullable in generated types. |
+
+## Types
+
+Default type mappings are based on the types produced by 
+[node-postgres](https://node-postgres.com/). These defaults can be added to or 
+overridden using configuration options described above. Type definitions for 
+enums will be generated automatically, provided that the enum is used somewhere 
+in a table or function definition.
+
+To define custom types, use the header to import or define them and use the 
+`types` configuration option to map PostgreSQL types to your custom types.
+
+Multi-dimensional-array-type columns are recognized. Columns to which a `NOT NULL`
+constraint has been applied will be non-nullable. Optional and variadic function 
+parameters are recognized.
+
+By default, node-postgres will transform the return value of a function that
+returns void into an empty string. Therefore, by default, the generated
+TypeScript return type of PostgreSQL functions that return void will be
+`string`. If desired, this can be overridden using the `types` configuration 
+option.
+
+The default value for unrecognized types is `string`.
+
+## Functions 
+
+Only functions whose `prokind` is `'f'` in `pg_catalog.pg_proc` are recognized 
+(i.e. normal functions, not procedures or aggregate functions). 
+
+Function overloads are recognized.
+
+## Directives
+
+IntrospeQL supports the inclusion of several directives which, when included in
+a PostgreSQL comment, can modify how IntrospeQL interacts with the database
+object to which that comment is applied.
+
+Directives are case-insensitive but must be separated from each other and from
+other text by a whitespace character (a space, newline, etc).
+
+Here is an example of adding a directive to the `config_key` column of a table 
+called `config` in the `reporting` schema:
+
+```
+COMMENT ON COLUMN reporting.config.config_key IS
+'@introspeql-enable-tsdoc-comments
+Unique configuration key.';
+```
+
+Below, please find a table of all valid directives:
+
+| Category | Directive                                 | Effect                                                                                                                                                                                                          |
+| -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Objects  | @introspeql-exclude                       | Excludes a table or function overload when mode is `'inclusive'`                                                                                                                                                |
+| Objects  | @introspeql-include                       | Includes a table or function overload when mode is `'exclusive'`                                                                                                                                                |
+| Types    | @introspeql-enable-nullable-args          | Makes each parameter of the function overload to which it is applied nullable when `nullableArgs` is `false` in `config.functions`                                                                              |
+| Types    | @introspeql-disable-nullable-args         | Makes each parameter of the function overload to which it is applied non-nullable when `nullableArgs` is `true` in `config.functions`                                                                           |
+| Types    | @introspeql-enable-nullable-return-types  | Makes the return type of the function overload to which it is applied nullable when `nullableReturnTypes` is `false` in `config.functions`                                                                      |
+| Types    | @introspeql-disable-nullable-return-types | Makes the return type of the function overload to which it is applied non-nullable when `nullableReturnTypes` is `true` in `config.functions`                                                                   |
+| Comments | @introspeql-enable-tsdoc-comments         | Copies the comments of the table, column, or enum to which it is applied even when `config.copyComments` is false or is an array that does not include the given database object type.                          |
+| Comments | @introspeql-disable-tsdoc-comments        | Ignores the comments of the table, column, or enum to which it is applied even when `config.copyComments` is true or is an array that includes the given database object type.                                  |
+| Comments | @introspeql-begin-tsdoc-comment           | Copies a portion of a PostgreSQL comment into the generated type definition file beginning after this directive and ending at the next `@introspeql-end-tsdoc-comment` directive or at the end of the comment.  |
+| Comments | @introspeql-end-tsdoc-comment             | Omits a portion of a PostgreSQL comment from the generated type definition file beginning after this directive and ending at the next `@introspeql-begin-tsdoc-comment` directive or at the end of the comment. |
+
+The package also exports a TypeScript enum of all valid directives:
+
+```
+import { Directives } from 'introspeql';
+```
+
+## Comments
+
+[Comments](https://www.postgresql.org/docs/current/sql-comment.html) can be 
+applied to PostgreSQL database objects with the following syntax:
 
-      export type ReturnType = number;
-    }
-  }
-}
 ```
+COMMENT ON COLUMN auth.users.user_id IS
+'Unique identifier for the user.';
+```
+
+If IntrospeQL is configured to copy the comments for a given table, enum, or
+column, PostgreSQL comments applied to that database object will be copied into
+the type definition file as [TSDoc](https://tsdoc.org/) comments.
+
+Note that all `@introspeql-` directives will always be removed when the copied
+comment is formatted.
+
+Comments cannot contain `*/` or a combination of
+characters that results in `*/` after directives are removed. Such comments
+will trigger a warning and will not be included in the output.
+
+Assuming comment copying is enabled for a particular database object, you can 
+use the `@introspeql-begin-tsdoc-comment` and `@introspeql-end-tsdoc-comment` 
+directives to copy only certain excerpts of the comment:
+
+### No Directive
+
+If neither `@introspeql-begin-tsdoc-comment` nor `@introspeql-end-tsdoc-comment`
+is included, the entire comment will be copied.
+
+### Using Only `@introspeql-begin-tsdoc-comment`
+
+If only `@introspeql-begin-tsdoc-comment` is included, everything before the
+directive will be excluded, and everything after it will be included.
+
+### Using Only `@introspeql-end-tsdoc-comment`
+
+If only `@introspeql-end-tsdoc-comment` is included, everything before the
+directive will be included, and everything after it will be excluded.
+
+### Using Both Directives
+
+You can alternate `@introspeql-begin-tsdoc-comment` and
+`@introspeql-end-tsdoc-comment`.
+
+You can begin or end with either directive, but you cannot include multiple
+instances of the same directive in a row within the same comment (in this case,
+a warning will be printed to the console and the comment will
+<strong>not</strong> be copied).
+
+When alternating between directives, content before
+`@introspeql-end-tsdoc-comment` or after `@introspeql-begin-tsdoc-comment` will
+be included and all other content will be excluded.
+
+## Contributing
+
+If you notice a bug or would like to request a feature, please submit an issue.
 
 ## License
 
@@ -131,4 +332,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/dist/comments/comment-converter.d.ts

@@ -0,0 +1,54 @@
+export declare class CommentConverter {
+    private static chunkExtractionDirectivesPattern;
+    private static chunkSanitizationDirectivesPattern;
+    /**
+     * Converts a PostgreSQL comment into TSDoc format, removing IntrospeQL
+     * directives, and formatting, prettifying, and validating the result.
+     */
+    static convertComment(pgComment: string): string;
+    /**
+     * Extracts the portions of a comment that have been flagged for inclusion
+     * with the `@introspeql-begin-tsdoc-comment` and/or
+     * `@introspeql-end-tsdoc-comment` directives, or the whole comment if no
+     * such directives are present.
+     */
+    private static extractChunks;
+    private static findNextChunkExtractionDirective;
+    private static extractChunk;
+    /**
+     * Extracts a directive from a comment at the provided index, regardless of
+     * the case of the directive as it appears in the comment.
+     */
+    private static extractDirective;
+    private static isEmptyChunk;
+    private static discardPreviousChunk;
+    /**
+     * Removes directives and leading/trailing new lines from each chunk. Filters
+     * out lines/chunks whose only content was directives.
+     */
+    private static sanitizeChunks;
+    /**
+     * All chunks are separated with empty lines by default, so leading and
+     * trailing new lines are removed from each chunk.
+     */
+    private static removeLeadingAndTrailingNewLines;
+    /**
+     * Removes all IntrospeQL directives from the provided chunks and filters
+     * out lines/chunks whose only contents were such directives.
+     */
+    private static removeDirectives;
+    /**
+     * Merges chunks and applies basic TSDoc formatting.
+     */
+    private static formatAndMergeChunks;
+    /**
+     * Prettifies a comment that has already received basic TSDoc formatting.
+     */
+    private static prettifyComment;
+    /**
+     * Verifies that *\/ occurs only at the very end of a TSDoc comment. This
+     * validation must occur after the TSDoc comment is produced to guarantee that
+     * the collapse of whitespace and/or removal of directives hasn't produced *\/.
+     */
+    private static validateComment;
+}

package/dist/comments/comment-converter.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommentConverter = void 0;
+var shared_1 = require("../shared");
+var prettify_comment_1 = require("./prettify-comment");
+var CommentConverter = /** @class */ (function () {
+    function CommentConverter() {
+    }
+    /**
+     * Converts a PostgreSQL comment into TSDoc format, removing IntrospeQL
+     * directives, and formatting, prettifying, and validating the result.
+     */
+    CommentConverter.convertComment = function (pgComment) {
+        // Break the comment into chunks and sanitize them.
+        var chunks = this.extractChunks(pgComment);
+        var sanitizedChunks = this.sanitizeChunks(chunks);
+        // Convert the comment and validate it.
+        var convertedComment = this.formatAndMergeChunks(sanitizedChunks);
+        this.validateComment(convertedComment);
+        // Prettify the comment and validate it.
+        var prettifiedComment = this.prettifyComment(convertedComment);
+        this.validateComment(prettifiedComment);
+        return prettifiedComment;
+    };
+    /**
+     * Extracts the portions of a comment that have been flagged for inclusion
+     * with the `@introspeql-begin-tsdoc-comment` and/or
+     * `@introspeql-end-tsdoc-comment` directives, or the whole comment if no
+     * such directives are present.
+     */
+    CommentConverter.extractChunks = function (pgComment) {
+        var chunks = [];
+        var previousDirective = null;
+        var indexOfDirective = this.findNextChunkExtractionDirective(pgComment);
+        var chunk = this.extractChunk(pgComment, indexOfDirective);
+        while (indexOfDirective >= 0) {
+            var directive = this.extractDirective(pgComment, indexOfDirective);
+            if (directive === previousDirective) {
+                throw new shared_1.ParsingError('Ambiguous directives: cannot have two instances of ' +
+                    directive +
+                    'in a row in the same comment.');
+            }
+            else if (directive === shared_1.Directives.EndTSDocComment &&
+                !this.isEmptyChunk(chunk)) {
+                chunks.push(chunk);
+            }
+            pgComment = this.discardPreviousChunk(pgComment);
+            indexOfDirective = this.findNextChunkExtractionDirective(pgComment);
+            chunk = this.extractChunk(pgComment, indexOfDirective);
+            previousDirective = directive;
+        }
+        if ((!previousDirective ||
+            previousDirective === shared_1.Directives.BeginTSDocComment) &&
+            !this.isEmptyChunk(chunk)) {
+            chunks.push(chunk);
+        }
+        return chunks;
+    };
+    CommentConverter.findNextChunkExtractionDirective = function (pgComment) {
+        return pgComment.search(this.chunkExtractionDirectivesPattern);
+    };
+    CommentConverter.extractChunk = function (pgComment, indexOfDirective) {
+        return pgComment.slice(0, indexOfDirective >= 0 ? indexOfDirective : pgComment.length);
+    };
+    /**
+     * Extracts a directive from a comment at the provided index, regardless of
+     * the case of the directive as it appears in the comment.
+     */
+    CommentConverter.extractDirective = function (pgComment, indexOfDirective) {
+        /*
+          Add 2 to the length of the longer directive because the pattern includes
+          up to 1 leading and 1 trailing whitespace character.
+        */
+        var maxSearchLength = Math.max(shared_1.Directives.BeginTSDocComment.length, shared_1.Directives.EndTSDocComment.length) + 2;
+        var searchString = pgComment
+            .slice(indexOfDirective, indexOfDirective + maxSearchLength)
+            .trim()
+            .toLowerCase();
+        if (searchString.startsWith(shared_1.Directives.BeginTSDocComment.toLowerCase())) {
+            return shared_1.Directives.BeginTSDocComment;
+        }
+        else if (searchString.startsWith(shared_1.Directives.EndTSDocComment.toLowerCase())) {
+            return shared_1.Directives.EndTSDocComment;
+        }
+        throw new shared_1.ParsingError('No directive at the provided index.');
+    };
+    CommentConverter.isEmptyChunk = function (chunk) {
+        return !chunk.trim();
+    };
+    CommentConverter.discardPreviousChunk = function (pgComment) {
+        var _b = pgComment.match(this.chunkExtractionDirectivesPattern), index = _b.index, length = _b[0].length;
+        return pgComment.slice(index + length);
+    };
+    /**
+     * Removes directives and leading/trailing new lines from each chunk. Filters
+     * out lines/chunks whose only content was directives.
+     */
+    CommentConverter.sanitizeChunks = function (chunks) {
+        var sanitizedChunks = this.removeLeadingAndTrailingNewLines(chunks);
+        sanitizedChunks = this.removeDirectives(sanitizedChunks);
+        return sanitizedChunks;
+    };
+    /**
+     * All chunks are separated with empty lines by default, so leading and
+     * trailing new lines are removed from each chunk.
+     */
+    CommentConverter.removeLeadingAndTrailingNewLines = function (chunks) {
+        return chunks.map(function (chunk) {
+            while (chunk.startsWith('\n')) {
+                chunk = chunk.slice(1);
+            }
+            while (chunk.endsWith('\n')) {
+                chunk = chunk.slice(0, chunk.length - 1);
+            }
+            return chunk;
+        });
+    };
+    /**
+     * Removes all IntrospeQL directives from the provided chunks and filters
+     * out lines/chunks whose only contents were such directives.
+     */
+    CommentConverter.removeDirectives = function (chunks) {
+        var _this = this;
+        var result = [];
+        chunks.forEach(function (chunk) {
+            var lines = chunk.split('\n');
+            var sanitizedLines = [];
+            lines.forEach(function (line) {
+                var sanitizedLine = line.replaceAll(_this.chunkSanitizationDirectivesPattern, function (match) {
+                    if (/\s\S+\s/.test(match)) {
+                        return ' ';
+                    }
+                    return '';
+                });
+                var directiveRemoved = sanitizedLine != line;
+                if (!directiveRemoved || sanitizedLine.trim() != '') {
+                    sanitizedLines.push(sanitizedLine);
+                }
+            });
+            if (sanitizedLines.length) {
+                var sanitizedChunk = sanitizedLines.join('\n');
+                result.push(sanitizedChunk);
+            }
+        });
+        return result;
+    };
+    /**
+     * Merges chunks and applies basic TSDoc formatting.
+     */
+    CommentConverter.formatAndMergeChunks = function (chunks) {
+        var mergedChunks = chunks
+            .map(function (chunk) {
+            var lines = chunk.split('\n');
+            return lines.map(function (line) { return " * ".concat(line); }).join('\n');
+        })
+            .join('\n *\n');
+        return mergedChunks.length ? '/**\n' + mergedChunks + '\n */' : '';
+    };
+    /**
+     * Prettifies a comment that has already received basic TSDoc formatting.
+     */
+    CommentConverter.prettifyComment = function (comment) {
+        var prettified = (0, prettify_comment_1.prettifyComment)(comment);
+        return prettified;
+    };
+    /**
+     * Verifies that *\/ occurs only at the very end of a TSDoc comment. This
+     * validation must occur after the TSDoc comment is produced to guarantee that
+     * the collapse of whitespace and/or removal of directives hasn't produced *\/.
+     */
+    CommentConverter.validateComment = function (comment) {
+        if (comment !== '' && comment.indexOf('*/') !== comment.length - 2) {
+            throw new shared_1.ParsingError('Comments cannot contain */');
+        }
+    };
+    var _a;
+    _a = CommentConverter;
+    CommentConverter.chunkExtractionDirectivesPattern = new RegExp("(^|\\s)(".concat(shared_1.Directives.BeginTSDocComment, "|").concat(shared_1.Directives.EndTSDocComment, ")($|\\s)"), 'i');
+    (function () {
+        var directivesPattern = "(".concat(Object.values(shared_1.Directives).join('|'), ")");
+        _a.chunkSanitizationDirectivesPattern = new RegExp("(^|\\s)(".concat(directivesPattern, ")(\\s+").concat(directivesPattern, ")*($|\\s)"), 'gi');
+    })();
+    return CommentConverter;
+}());
+exports.CommentConverter = CommentConverter;

package/dist/comments/index.d.ts

@@ -0,0 +1,2 @@
+export * from './comment-converter';
+export * from './prettify-comment';

package/dist/comments/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./comment-converter"), exports);
+__exportStar(require("./prettify-comment"), exports);

package/dist/comments/prettify-comment.d.ts

@@ -0,0 +1 @@
+export declare function prettifyComment(comment: string): string;