introspeql 0.0.4 → 1.1.0

package/README.md

@@ -1,114 +1,344 @@
 # 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, views, materialized
+views, 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
+```
+
+Add the following entry to the scripts object in package.json:
+
+```
+"gen-types": "npx tsx scripts/gen-types.ts"
+```
 
-## Example Usage
+Create a scripts directory at the root level of your project, and inside this
+folder, create a new TypeScript file called `gen-types.ts`.
 
-```typescript
-// src/scripts/gen-db-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',
-    },
-  ],
+  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:
-`
-// Custom header:
-import type { Geography } from '../model/geography';
-`
+    '/* This file has been generated by IntrospeQL and should not be edited directly. */',
   types: {
-    'public.geography': 'Geography'
-  },
+    'pg_catalog.void': 'void'
+  }
 };
 
-generateTypes(config);
+genTypes();
+
+async function genTypes() {
+  await introspeql(config);
+  console.log("Type definition file created at " + outFile);
+}
 ```
 
-## Example Output
+Create a `.gitignore` file at the root of your project and make sure it includes
+`node_modules` and `.env`:
 
-```typescript
-// src/db/types.ts
+```
+# .gitignore
+node_modules/
+.env
+```
 
-/* This file was generated by IntrospeQL. Do not edit manually. */
-// Custom header:
-import type { Geography } from '../model/geography';
+Create a `.env` file at the root of your project and add your database connection
+information:
 
-export namespace Public {
-  export const SchemaName = 'public';
+```
+# .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
+```
 
-  export namespace Enums {
-    export enum DistanceUnits {
-      METERS = 'METERS',
-      KILOMETERS = 'KILOMETERS',
-      MILES = 'MILES',
-    }
-  }
+Execute your script:
 
-  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;
-      }
-    }
-  }
+```
+npm run gen-types
+```
 
-  export namespace Procedures {
-    export namespace DistanceWithUnits {
-      export const ProcedureName = 'distance_with_units';
+A type definition file will have been generated at `generated/type-definitions.ts`.
 
-      export const ArgNames = ['point_a', 'point_b', 'units'] as const;
+> ⚠️ **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 type ArgTypes = [Geography, Geography, Enums.DistanceUnits];
+## Output
 
-      export type ReturnType = number;
-    }
-  }
-}
+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, views, materialized views,
+functions, and enums, grouped by category into nested namespaces. Each table,
+view, materialized view and function, in turn, consists of a namespace.
+
+Relation (tables, views, and materialized views) namespaces contain the name of
+the relation, a union of string literals representing the names of its columns,
+and an object-type representing the structure of each of its rows.
+
+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.                                                                                                                                     |
+| `views`              | `ViewOptions`             | No          | —            | View filtering configuration.                                                                                                                                      |
+| `materializedViews`  | `MaterializedViewOptions` | No          | —            | Materialized view 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. |
+
+---
+
+### View Options
+
+Controls which views are included in the generated output.
+
+| Option         | Type                         | Required | Default       | Description                                        |
+| -------------- | ---------------------------- | -------- | ------------- | -------------------------------------------------- |
+| `mode`         | `'inclusive' \| 'exclusive'` | No       | `'inclusive'` | Determines how view filtering is applied.          |
+| `excludeViews` | `string[]`                   | No       | `[]`          | Views to exclude when operating in inclusive mode. |
+| `includeViews` | `string[]`                   | No       | `[]`          | Views to include when operating in exclusive mode. |
+
+---
+
+### Materialized View Options
+
+Controls which materialized views are included in the generated output.
+
+| Option                     | Type                         | Required | Default       | Description                                                     |
+| -------------------------- | ---------------------------- | -------- | ------------- | --------------------------------------------------------------- |
+| `mode`                     | `'inclusive' \| 'exclusive'` | No       | `'inclusive'` | Determines how materialized view filtering is applied.          |
+| `excludeMaterializedViews` | `string[]`                   | No       | `[]`          | Materialized views to exclude when operating in inclusive mode. |
+| `includeMaterializedViews` | `string[]`                   | No       | `[]`          | Materialized views 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, view, materialized view, 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. All columns of a view or
+materialized view will typically be 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, view, materialized view, or function overload when mode is `'inclusive'`                                                                                                                      |
+| Objects  | @introspeql-include                       | Includes a table, view, materialized view, 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, view, materialized view, 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, view, materialized view, 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:
+
+```
+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, view,
+materialized view, 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
 
 MIT License

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';