introspeql 0.0.1 → 0.0.2

package/README.md

@@ -1,14 +1,113 @@
 # IntrospeQL
 
-IntrospeQL is a simple package for introspecting PostgreSQL tables and functions
-and generating TypeScript types from them. The aim of the package is to
-make the capturing of PostgreSQL types and the generation of TypeScript types
-easy, comprehensive, and accurate.
+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.
 
-## Not Production Ready
+> ⚠️ **Warning: Alpha / Not Production Ready**  
+> This library is currently in alpha. Use with caution; it is not yet hardened
+> for production.
 
-This project is currently in alpha. Do not use it in production at this time.
-Full documentation will be available in subsequent releases.
+## Features
+
+- 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.
+
+## Example Usage
+
+```typescript
+// src/scripts/gen-db-types.ts
+import 'dotenv/config';
+import path from 'node:path';
+import { generateTypes, type IntrospeQLConfig } from 'introspeql';
+
+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'
+  },
+};
+
+generateTypes(config);
+```
+
+## Example Output
+
+```typescript
+// src/db/types.ts
+
+/* This file was generated by IntrospeQL. Do not edit manually. */
+// Custom header:
+import type { Geography } from '../model/geography';
+
+export namespace Public {
+  export const SchemaName = 'public';
+
+  export namespace Enums {
+    export enum DistanceUnits {
+      METERS = 'METERS',
+      KILOMETERS = 'KILOMETERS',
+      MILES = 'MILES',
+    }
+  }
+
+  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;
+      }
+    }
+  }
+
+  export namespace Procedures {
+    export namespace DistanceWithUnits {
+      export const ProcedureName = 'distance_with_units';
+
+      export const ArgNames = ['point_a', 'point_b', 'units'] as const;
+
+      export type ArgTypes = [Geography, Geography, Enums.DistanceUnits];
+
+      export type ReturnType = number;
+    }
+  }
+}
+```
 
 ## License
 

package/dist/append-schema.d.ts

@@ -1,2 +1,8 @@
-import type { Schema } from "./prepare-data-for-writing";
+import type { Schema } from './prepare-data-for-writing';
+/**
+ * Appends a namespace representing the given schema to the provided output file.
+ *
+ * @param outputPath
+ * @param schema
+ */
 export declare function appendSchema(outputPath: string, schema: Schema): void;

package/dist/append-schema.js

@@ -1,4 +1,10 @@
-import fs from "node:fs";
+import fs from 'node:fs';
+/**
+ * Appends a namespace representing the given schema to the provided output file.
+ *
+ * @param outputPath
+ * @param schema
+ */
 export function appendSchema(outputPath, schema) {
     let schemaTypeDefinitions = `export namespace ${schema.formattedName} {\n`;
     schemaTypeDefinitions += `  export const SchemaName = '${schema.rawName}';\n`;
@@ -12,81 +18,79 @@ export function appendSchema(outputPath, schema) {
         schemaTypeDefinitions = appendProcedures(schemaTypeDefinitions, schema);
     }
     schemaTypeDefinitions += `};`;
-    fs.appendFileSync(outputPath, schemaTypeDefinitions, "utf-8");
+    fs.appendFileSync(outputPath, schemaTypeDefinitions, 'utf-8');
 }
 function appendEnums(typeDefs, schema) {
-    typeDefs += "\n" + " ".repeat(2) + "export namespace Enums {";
+    typeDefs += '\n' + ' '.repeat(2) + 'export namespace Enums {';
     for (const e of schema.enums) {
-        typeDefs += "\n" + " ".repeat(4) + `export enum ${e.name} {\n`;
-        typeDefs += e.values
-            .map((v) => " ".repeat(6) + `${v} = '${v}',\n`)
-            .join("");
-        typeDefs += " ".repeat(4) + "};\n";
+        typeDefs += '\n' + ' '.repeat(4) + `export enum ${e.name} {\n`;
+        typeDefs += e.values.map(v => ' '.repeat(6) + `${v} = '${v}',\n`).join('');
+        typeDefs += ' '.repeat(4) + '};\n';
     }
-    typeDefs += " ".repeat(2) + `};\n`;
+    typeDefs += ' '.repeat(2) + `};\n`;
     return typeDefs;
 }
 function appendTables(typeDefs, schema) {
-    typeDefs += "\n" + " ".repeat(2) + "export namespace Tables {";
+    typeDefs += '\n' + ' '.repeat(2) + 'export namespace Tables {';
     for (const t of schema.tables) {
         typeDefs +=
-            "\n" + " ".repeat(4) + `export namespace ${t.formattedName} {\n`;
-        typeDefs += " ".repeat(6) + `export const TableName = '${t.rawName}';\n`;
+            '\n' + ' '.repeat(4) + `export namespace ${t.formattedName} {\n`;
+        typeDefs += ' '.repeat(6) + `export const TableName = '${t.rawName}';\n`;
         if (Object.entries(t.columnNames).length > 0) {
-            typeDefs += "\n" + " ".repeat(6) + "export enum ColumnNames {\n";
+            typeDefs += '\n' + ' '.repeat(6) + 'export enum ColumnNames {\n';
             for (const [formattedName, rawName] of Object.entries(t.columnNames)) {
-                typeDefs += " ".repeat(8) + `${formattedName} = '${rawName}',\n`;
+                typeDefs += ' '.repeat(8) + `${formattedName} = '${rawName}',\n`;
             }
-            typeDefs += " ".repeat(6) + "};\n";
+            typeDefs += ' '.repeat(6) + '};\n';
         }
         if (Object.entries(t.rowType).length > 0) {
-            typeDefs += "\n" + " ".repeat(6) + "export interface RowType {\n";
+            typeDefs += '\n' + ' '.repeat(6) + 'export interface RowType {\n';
             for (const [rawName, type] of Object.entries(t.rowType)) {
-                const columnName = Object.entries(t.columnNames).find((entry) => {
+                const columnName = Object.entries(t.columnNames).find(entry => {
                     return entry[1] === rawName;
                 })[0];
-                typeDefs += " ".repeat(8) + `[ColumnNames.${columnName}]: ${type};\n`;
+                typeDefs += ' '.repeat(8) + `[ColumnNames.${columnName}]: ${type};\n`;
             }
-            typeDefs += " ".repeat(6) + "};\n";
+            typeDefs += ' '.repeat(6) + '};\n';
         }
-        typeDefs += " ".repeat(4) + "};\n";
+        typeDefs += ' '.repeat(4) + '};\n';
     }
-    typeDefs += " ".repeat(2) + "};\n";
+    typeDefs += ' '.repeat(2) + '};\n';
     return typeDefs;
 }
 function appendProcedures(typeDefs, schema) {
-    typeDefs += "\n" + " ".repeat(2) + "export namespace Procedures {";
+    typeDefs += '\n' + ' '.repeat(2) + 'export namespace Procedures {';
     for (const proc of schema.procedures) {
         typeDefs +=
-            "\n" + " ".repeat(4) + `export namespace ${proc.formattedName} {\n`;
+            '\n' + ' '.repeat(4) + `export namespace ${proc.formattedName} {\n`;
         typeDefs +=
-            " ".repeat(6) + `export const ProcedureName = '${proc.rawName}';\n`;
+            ' '.repeat(6) + `export const ProcedureName = '${proc.rawName}';\n`;
         typeDefs +=
-            "\n" +
-                " ".repeat(6) +
+            '\n' +
+                ' '.repeat(6) +
                 `export const ArgNames = [\n` +
                 proc.argNames
-                    .map((n) => {
-                    return " ".repeat(8) + `'${n}',\n`;
+                    .map(n => {
+                    return ' '.repeat(8) + `'${n}',\n`;
                 })
-                    .join("") +
-                " ".repeat(6) +
-                "] as const;\n";
+                    .join('') +
+                ' '.repeat(6) +
+                '] as const;\n';
         typeDefs +=
-            "\n" +
-                " ".repeat(6) +
+            '\n' +
+                ' '.repeat(6) +
                 `export type ArgTypes = [\n` +
                 proc.argTypes
-                    .map((t) => {
-                    return " ".repeat(8) + t + ",\n";
+                    .map(t => {
+                    return ' '.repeat(8) + t + ',\n';
                 })
-                    .join("") +
-                " ".repeat(6) +
-                "];\n";
+                    .join('') +
+                ' '.repeat(6) +
+                '];\n';
         typeDefs +=
-            "\n" + " ".repeat(6) + `export type ReturnType = ${proc.returnType};\n`;
-        typeDefs += " ".repeat(4) + "};\n";
+            '\n' + ' '.repeat(6) + `export type ReturnType = ${proc.returnType};\n`;
+        typeDefs += ' '.repeat(4) + '};\n';
     }
-    typeDefs += " ".repeat(2) + "};\n";
+    typeDefs += ' '.repeat(2) + '};\n';
     return typeDefs;
 }

package/dist/generate-types.d.ts

@@ -0,0 +1,8 @@
+import { type IntrospeQLConfig } from './introspeql-config';
+/**
+ * Reads table, function, and enum metadata from a database and writes
+ * corresponding TypeScript type definitions to the provided output path.
+ *
+ * @param config
+ */
+export declare function generateTypes(config: IntrospeQLConfig): Promise<void>;

package/dist/{introspect-database.js → generate-types.js}

@@ -1,17 +1,24 @@
-import path from "node:path";
-import { Client } from "pg";
-import { introspectTables } from "./introspect-tables";
-import { introspectColumns } from "./introspect-columns";
-import { introspectProcedures } from "./introspect-procedures";
-import { introspectEnum, } from "./introspect-enum";
-import { writeHeader } from "./write-header";
-import { prepareDataForWriting } from "./prepare-data-for-writing";
-import { appendSchema } from "./append-schema";
-import { introspeqlConfig } from "./introspeql-config";
-export async function introspectDatabase(config) {
+import fs from 'node:fs';
+import path from 'node:path';
+import { Client } from 'pg';
+import { introspectTables } from './introspect-tables';
+import { introspectColumns } from './introspect-columns';
+import { introspectProcedures } from './introspect-procedures';
+import { introspectEnum, } from './introspect-enum';
+import { writeHeader } from './write-header';
+import { prepareDataForWriting } from './prepare-data-for-writing';
+import { appendSchema } from './append-schema';
+import { introspeqlConfig } from './introspeql-config';
+/**
+ * Reads table, function, and enum metadata from a database and writes
+ * corresponding TypeScript type definitions to the provided output path.
+ *
+ * @param config
+ */
+export async function generateTypes(config) {
     const parsedConfig = introspeqlConfig.parse(config);
-    const client = "dbConnectionString" in parsedConfig
-        ? new Client({
+    const client = 'dbConnectionString' in parsedConfig ?
+        new Client({
             connectionString: parsedConfig.dbConnectionString,
         })
         : new Client({
@@ -21,7 +28,7 @@ export async function introspectDatabase(config) {
         await client.connect();
     }
     catch (e) {
-        throw new Error("Failed to connect to the database.", { cause: e });
+        throw new Error('Failed to connect to the database.', { cause: e });
     }
     // Read table data
     let tableDataObjects;
@@ -29,7 +36,7 @@ export async function introspectDatabase(config) {
         tableDataObjects = await introspectTables(client, parsedConfig);
     }
     catch (e) {
-        throw new Error("Failed to introspect tables.", { cause: e });
+        throw new Error('Failed to introspect tables.', { cause: e });
     }
     // Read column data and update enums object when enum types are found
     const columnDataObjectsByTableId = {};
@@ -40,7 +47,7 @@ export async function introspectDatabase(config) {
             columnDataObjectsByTableId[tableDataObj.id] = columnDataObjects;
             for (const columnDataObj of columnDataObjects) {
                 if (columnDataObj.is_enum &&
-                    !partialEnumDataObjects.find((d) => d.id === columnDataObj.column_type_id)) {
+                    !partialEnumDataObjects.find(d => d.id === columnDataObj.column_type_id)) {
                     partialEnumDataObjects.push({
                         id: columnDataObj.column_type_id,
                         schema: columnDataObj.column_type_schema,
@@ -50,7 +57,7 @@ export async function introspectDatabase(config) {
             }
         }
         catch (e) {
-            throw new Error("Failed to introspect columns.", { cause: e });
+            throw new Error('Failed to introspect columns.', { cause: e });
         }
     }
     // Read procedure data and update enums object when enum types are found
@@ -59,12 +66,12 @@ export async function introspectDatabase(config) {
         procedureDataObjects = await introspectProcedures(client, parsedConfig);
     }
     catch (e) {
-        throw new Error("Failed to introspect procedures.", { cause: e });
+        throw new Error('Failed to introspect procedures.', { cause: e });
     }
     for (const procedureDataObject of procedureDataObjects) {
         for (const argType of procedureDataObject.arg_types) {
             if (argType.is_enum &&
-                !partialEnumDataObjects.find((d) => d.id === argType.id)) {
+                !partialEnumDataObjects.find(d => d.id === argType.id)) {
                 partialEnumDataObjects.push({
                     id: argType.id,
                     schema: argType.schema,
@@ -73,7 +80,7 @@ export async function introspectDatabase(config) {
             }
         }
         if (procedureDataObject.return_type.is_enum &&
-            !partialEnumDataObjects.find((d) => d.id === procedureDataObject.return_type.id)) {
+            !partialEnumDataObjects.find(d => d.id === procedureDataObject.return_type.id)) {
             partialEnumDataObjects.push({
                 id: procedureDataObject.return_type.id,
                 schema: procedureDataObject.return_type.schema,
@@ -81,7 +88,7 @@ export async function introspectDatabase(config) {
             });
         }
     }
-    // introspect enums
+    // Read enum metadata for all enums that were featured in tables or procedures
     const enumDataObjects = [];
     for (const partialEnumDataObj of partialEnumDataObjects) {
         try {
@@ -89,14 +96,16 @@ export async function introspectDatabase(config) {
             enumDataObjects.push(enumData);
         }
         catch (e) {
-            throw new Error("Failed to introspect enum.", { cause: e });
+            throw new Error('Failed to introspect enum.', { cause: e });
         }
     }
     await client.end();
-    const outputPath = "outFile" in parsedConfig
-        ? parsedConfig.outFile
-        : path.join(parsedConfig.outDir, "introspeql-types.ts");
-    writeHeader(outputPath, parsedConfig);
+    const outDir = path.dirname(config.outFile);
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    if (!fs)
+        writeHeader(parsedConfig.outFile, parsedConfig);
     const schemas = prepareDataForWriting(enumDataObjects, tableDataObjects, columnDataObjectsByTableId, procedureDataObjects, parsedConfig);
-    schemas.forEach((schema) => appendSchema(outputPath, schema));
+    schemas.forEach(schema => appendSchema(parsedConfig.outFile, schema));
 }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { introspectDatabase as introspeql } from "./introspect-database";
-export type { IntrospeQLConfig } from "./introspeql-config";
+export { generateTypes } from './generate-types';
+export type { IntrospeQLConfig } from './introspeql-config';

package/dist/index.js

@@ -1 +1 @@
-export { introspectDatabase as introspeql } from "./introspect-database";
+export { generateTypes } from './generate-types';

package/dist/introspect-columns.d.ts

@@ -1,5 +1,5 @@
-import { z } from "zod";
-import type { Client } from "pg";
+import { z } from 'zod';
+import type { Client } from 'pg';
 declare const columnDataSchema: z.ZodObject<{
     column_name: z.ZodString;
     column_type_schema: z.ZodString;
@@ -10,13 +10,12 @@ declare const columnDataSchema: z.ZodObject<{
     nullable: z.ZodBoolean;
 }, z.core.$strip>;
 export type ColumnData = z.infer<typeof columnDataSchema>;
-export declare function introspectColumns(client: Client, tableId: number): Promise<{
-    column_name: string;
-    column_type_schema: string;
-    column_type_id: number;
-    column_type: string;
-    is_enum: boolean;
-    num_dimensions: number;
-    nullable: boolean;
-}[]>;
+/**
+ * Reads metadata for each column of a given table.
+ *
+ * @param client
+ * @param tableId
+ * @returns A {@link Promise}<{@link ColumnData}[]>
+ */
+export declare function introspectColumns(client: Client, tableId: number): Promise<ColumnData[]>;
 export {};

package/dist/introspect-columns.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from 'zod';
 const columnDataSchema = z.object({
     column_name: z.string(),
     column_type_schema: z.string(),
@@ -8,6 +8,13 @@ const columnDataSchema = z.object({
     num_dimensions: z.number(),
     nullable: z.boolean(),
 });
+/**
+ * Reads metadata for each column of a given table.
+ *
+ * @param client
+ * @param tableId
+ * @returns A {@link Promise}<{@link ColumnData}[]>
+ */
 export async function introspectColumns(client, tableId) {
     const result = await client.query(`
 SELECT

package/dist/introspect-enum.d.ts

@@ -1,10 +1,20 @@
-import type { Client } from "pg";
+import type { Client } from 'pg';
 export type PartialEnumData = {
+    /** The OID of the enum. */
     id: number;
+    /** The name of the schema in which the enum was defined. */
     schema: string;
+    /** The name of the enum. */
     name: string;
 };
 export type EnumData = PartialEnumData & {
     values: string[];
 };
+/**
+ * Reads metadata for the provided enum.
+ *
+ * @param client
+ * @param data
+ * @returns A {@link Promise}<{@link EnumData}[]>
+ */
 export declare function introspectEnum(client: Client, data: PartialEnumData): Promise<EnumData>;

package/dist/introspect-enum.js

@@ -1,4 +1,11 @@
-import { z } from "zod";
+import { z } from 'zod';
+/**
+ * Reads metadata for the provided enum.
+ *
+ * @param client
+ * @param data
+ * @returns A {@link Promise}<{@link EnumData}[]>
+ */
 export async function introspectEnum(client, data) {
     const query = `
 SELECT ARRAY(SELECT enumlabel FROM pg_enum WHERE enumtypid = $1)::text[] AS enum_values;

package/dist/introspect-procedures.d.ts

@@ -1,11 +1,11 @@
-import { z } from "zod";
-import type { Client } from "pg";
-import type { ParsedIntrospeQLConfig } from "./introspeql-config";
+import { z } from 'zod';
+import type { Client } from 'pg';
+import type { ParsedIntrospeQLConfig } from './introspeql-config';
 declare const procedureDataSchema: z.ZodObject<{
     id: z.ZodNumber;
     schema: z.ZodString;
     name: z.ZodString;
-    arg_names: z.ZodPipe<z.ZodNullable<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[]>>;
+    arg_names: z.ZodPipe<z.ZodNullable<z.ZodArray<z.ZodString>>, z.ZodTransform<string[], string[] | null>>;
     arg_types: z.ZodArray<z.ZodObject<{
         id: z.ZodCoercedNumber<unknown>;
         schema: z.ZodString;
@@ -22,10 +22,19 @@ declare const procedureDataSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type ProcedureData = z.infer<typeof procedureDataSchema>;
+/**
+ * Reads information about procedures in the provided schema(s), including their
+ * ids, names, schema names, argument names, argument types, and return type.
+ *
+ * @param client
+ * @param config
+ * @returns A {@link Promise}<{@link ProcedureData}[]>
+ */
 export declare function introspectProcedures(client: Client, config: ParsedIntrospeQLConfig): Promise<{
     id: number;
     schema: string;
     name: string;
+    arg_names: string[];
     arg_types: {
         id: number;
         schema: string;
@@ -40,6 +49,5 @@ export declare function introspectProcedures(client: Client, config: ParsedIntro
         is_array: boolean;
         is_enum: boolean;
     };
-    arg_names?: string[];
 }[]>;
 export {};

package/dist/introspect-procedures.js

@@ -1,27 +1,61 @@
-import { z } from "zod";
+import { z } from 'zod';
 const typeSchema = z.object({
+    /** The OID of the type. */
     id: z.coerce.number(),
+    /** The name of the schema in which the type was defined. */
     schema: z.string(),
+    /**
+     * The name of the type, or the name of the type of each element if the type
+     * is an array.
+     */
     name: z.string(),
+    /** Whether or not the type is an array. */
     is_array: z.boolean(),
+    /**
+     * Whether or not the type (or the type of each element if the type is an
+     * array) is an enum.
+     */
     is_enum: z.boolean(),
 });
 const procedureDataSchema = z.object({
+    /** The OID of the procedure. */
     id: z.number(),
+    /** The name of the schema in which the procedure was defined. */
     schema: z.string(),
+    /** The name of the procedure. */
     name: z.string(),
+    /**
+     * An array containing the names of the procedure's arguments. Note that this
+     * array can be empty even for procedures with arguments if those arguments
+     * are unnamed.
+     */
     arg_names: z
         .string()
         .array()
         .nullable()
-        .transform((v) => (v ? v : [])),
+        .transform(v => (v ? v : [])),
+    /**
+     * An array containing type information for each of the procedure's
+     * arguments.
+     */
     arg_types: typeSchema.array(),
+    /**
+     * Type information for the procedure's return type.
+     */
     return_type: typeSchema,
 });
+/**
+ * Reads information about procedures in the provided schema(s), including their
+ * ids, names, schema names, argument names, argument types, and return type.
+ *
+ * @param client
+ * @param config
+ * @returns A {@link Promise}<{@link ProcedureData}[]>
+ */
 export async function introspectProcedures(client, config) {
     const schemaPlaceholders = config.schemas
         .map((_, i) => `$${i + 1}`)
-        .join(", ");
+        .join(', ');
     let query = `
 SELECT 
   p.oid AS id, 
@@ -86,9 +120,9 @@ WHERE n.nspname IN (${schemaPlaceholders})
             parameters.push(procedureToIgnore.schema);
             parameters.push(procedureToIgnore.name);
         }
-        query += `AND NOT (${filters.join(" OR\n")})`;
+        query += `AND NOT (${filters.join(' OR\n')})`;
     }
-    query += ";";
+    query += ';';
     const result = await client.query(query, parameters);
     const procedureData = procedureDataSchema.array().parse(result.rows);
     return procedureData;

package/dist/introspect-tables.d.ts

@@ -1,15 +1,19 @@
-import { z } from "zod";
-import type { Client } from "pg";
-import type { ParsedIntrospeQLConfig } from "./introspeql-config";
+import { z } from 'zod';
+import type { Client } from 'pg';
+import type { ParsedIntrospeQLConfig } from './introspeql-config';
 declare const tableDataSchema: z.ZodObject<{
     id: z.ZodNumber;
     schema: z.ZodString;
     name: z.ZodString;
 }, z.core.$strip>;
 export type TableData = z.infer<typeof tableDataSchema>;
-export declare function introspectTables(client: Client, config: ParsedIntrospeQLConfig): Promise<{
-    id: number;
-    schema: string;
-    name: string;
-}[]>;
+/**
+ * Returns information about tables in the provided schema(s), including their
+ * ids, names, and schema names.
+ *
+ * @param client
+ * @param config
+ * @returns A {@link Promise}<{@link TableData}[]>
+ */
+export declare function introspectTables(client: Client, config: ParsedIntrospeQLConfig): Promise<TableData[]>;
 export {};

package/dist/introspect-tables.js

@@ -1,13 +1,24 @@
-import { z } from "zod";
+import { z } from 'zod';
 const tableDataSchema = z.object({
+    /** The OID of the table. */
     id: z.number(),
+    /** The name of the schema containing the table. */
     schema: z.string(),
+    /** The name of the table. */
     name: z.string(),
 });
+/**
+ * Returns information about tables in the provided schema(s), including their
+ * ids, names, and schema names.
+ *
+ * @param client
+ * @param config
+ * @returns A {@link Promise}<{@link TableData}[]>
+ */
 export async function introspectTables(client, config) {
     const schemaPlaceholders = config.schemas
         .map((_, i) => `$${i + 1}`)
-        .join(", ");
+        .join(', ');
     let query = `
 SELECT c.oid AS id, n.nspname AS schema, c.relname AS name 
 FROM pg_catalog.pg_class AS c
@@ -23,9 +34,9 @@ WHERE c.relkind = 'r' AND n.nspname IN (${schemaPlaceholders})
             parameters.push(tableToIgnore.schema);
             parameters.push(tableToIgnore.name);
         }
-        query += `AND NOT (${filters.join(" OR\n")})`;
+        query += `AND NOT (${filters.join(' OR\n')})`;
     }
-    query += ";";
+    query += ';';
     const result = await client.query(query, parameters);
     const tableData = tableDataSchema.array().parse(result.rows);
     return tableData;

package/dist/introspeql-config.d.ts

@@ -1,5 +1,5 @@
-import { z } from "zod";
-declare const introspeqlConfig: z.ZodIntersection<z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
+import { z } from 'zod';
+declare const introspeqlConfig: z.ZodIntersection<z.ZodUnion<readonly [z.ZodObject<{
     dbConnectionString: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     dbConnectionParams: z.ZodObject<{
@@ -9,26 +9,23 @@ declare const introspeqlConfig: z.ZodIntersection<z.ZodIntersection<z.ZodUnion<r
         port: z.ZodOptional<z.ZodNumber>;
         database: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-}, z.core.$strip>]>, z.ZodUnion<readonly [z.ZodObject<{
-    outDir: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strip>]>, z.ZodObject<{
     outFile: z.ZodString;
-}, z.core.$strip>]>>, z.ZodObject<{
     schemas: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
     header: z.ZodOptional<z.ZodString>;
     types: z.ZodPipe<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>, z.ZodTransform<{
-        "pg_catalog.bool": string;
-        "pg_catalog.int2": string;
-        "pg_catalog.int4": string;
-        "pg_catalog.float4": string;
-        "pg_catalog.float8": string;
-        "pg_catalog.json": string;
-        "pg_catalog.jsonb": string;
-        "pg_catalog.date": string;
-        "pg_catalog.timestamp": string;
-        "pg_catalog.timestamptz": string;
-        "pg_catalog.void": string;
-    }, Record<string, string>>>;
+        'pg_catalog.bool': string;
+        'pg_catalog.int2': string;
+        'pg_catalog.int4': string;
+        'pg_catalog.float4': string;
+        'pg_catalog.float8': string;
+        'pg_catalog.json': string;
+        'pg_catalog.jsonb': string;
+        'pg_catalog.date': string;
+        'pg_catalog.timestamp': string;
+        'pg_catalog.timestamptz': string;
+        'pg_catalog.void': string;
+    }, Record<string, string> | undefined>>;
     ignoreTables: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
         schema: z.ZodString;
         name: z.ZodString;

package/dist/introspeql-config.js

@@ -1,8 +1,17 @@
-import { z } from "zod";
+import { z } from 'zod';
 const databaseConnectionConfig = z.union([
+    /**
+     * A PostgreSQL connection string specifying the database to connect to.
+     * Useful if you are already storing such a string as an environment variable.
+     */
     z.object({
         dbConnectionString: z.string(),
     }),
+    /**
+     * An object containing the components of a PostgreSQL connection string that
+     * together specify the database to connect to. Useful if you are already
+     * storing such values as individual environment variables.
+     */
     z.object({
         dbConnectionParams: z.object({
             user: z.string().optional(),
@@ -13,53 +22,83 @@ const databaseConnectionConfig = z.union([
         }),
     }),
 ]);
-const outputConfig = z.union([
-    z.object({
-        outDir: z.string(),
-    }),
-    z.object({
-        outFile: z.string(),
-    }),
-]);
 const entityData = z.object({
     schema: z.string(),
     name: z.string(),
 });
 const otherConfig = z.object({
+    /**
+     * The file to which TypeScript types will be written.
+     */
+    outFile: z.string(),
+    /**
+     * The database schemas from which types should be generated.
+     */
     schemas: z
         .string()
         .array()
         .nonempty({
-        message: "Please provide at least one schema.",
+        message: 'Please provide at least one schema.',
     })
         .optional()
-        .default(() => ["public"]),
+        .default(() => ['public']),
+    /**
+     * An optional header that will be written to the generated type definition
+     * file before the types. Useful when you want to define or import types
+     * directly in the generated file.
+     */
     header: z.string().optional(),
+    /**
+     * Custom type mappings. Default settings align with transformations applied
+     * by node-postgres. To override these settings for a type, provide the
+     * name of the schema in which the type is defined and the name of the type
+     * (separated by a dot) as the key, and a string representation of the
+     * desired type as the value.
+     *
+     * @example
+     * ```
+     * {
+     *   types: {
+     *     "pg_catalog.int8" : "bigint"
+     *   }
+     * }
+     * ```
+     */
     types: z
         .record(z.string(), z.string())
         .optional()
-        .transform((t) => ({
-        "pg_catalog.bool": "boolean",
-        "pg_catalog.int2": "number",
-        "pg_catalog.int4": "number",
-        "pg_catalog.float4": "number",
-        "pg_catalog.float8": "number",
-        "pg_catalog.json": "object",
-        "pg_catalog.jsonb": "object",
-        "pg_catalog.date": "Date",
-        "pg_catalog.timestamp": "Date",
-        "pg_catalog.timestamptz": "Date",
-        "pg_catalog.void": "void",
+        .transform(t => ({
+        'pg_catalog.bool': 'boolean',
+        'pg_catalog.int2': 'number',
+        'pg_catalog.int4': 'number',
+        'pg_catalog.float4': 'number',
+        'pg_catalog.float8': 'number',
+        'pg_catalog.json': 'object',
+        'pg_catalog.jsonb': 'object',
+        'pg_catalog.date': 'Date',
+        'pg_catalog.timestamp': 'Date',
+        'pg_catalog.timestamptz': 'Date',
+        'pg_catalog.void': 'void',
         ...t,
     })),
+    /**
+     * An array of tables that should NOT be included in the generated type
+     * definitions. Useful for ignoring tables such as `spatial_ref_sys`
+     * when using PostGIS, or tables containing information about
+     * migrations.
+     */
     ignoreTables: entityData
         .array()
         .optional()
         .default(() => []),
+    /**
+     * An array of procedures that should NOT be included in the generated type
+     * definitions.
+     */
     ignoreProcedures: entityData
         .array()
         .optional()
         .default(() => []),
 });
-const introspeqlConfig = z.intersection(z.intersection(databaseConnectionConfig, outputConfig), otherConfig);
+const introspeqlConfig = z.intersection(databaseConnectionConfig, otherConfig);
 export { introspeqlConfig };

package/dist/prepare-data-for-writing.d.ts

@@ -1,8 +1,8 @@
-import type { EnumData } from "./introspect-enum";
-import type { TableData } from "./introspect-tables";
-import type { ColumnData } from "./introspect-columns";
-import type { ProcedureData } from "./introspect-procedures";
-import type { ParsedIntrospeQLConfig } from "./introspeql-config";
+import type { EnumData } from './introspect-enum';
+import type { TableData } from './introspect-tables';
+import type { ColumnData } from './introspect-columns';
+import type { ProcedureData } from './introspect-procedures';
+import type { ParsedIntrospeQLConfig } from './introspeql-config';
 export interface Schema {
     formattedName: string;
     rawName: string;
@@ -24,4 +24,15 @@ export interface Schema {
         returnType: string;
     }>;
 }
+/**
+ * Organizes data by schema, table, and procedure, and formats it in
+ * preparation for type generation.
+ *
+ * @param enumDataObjects
+ * @param tableDataObjects
+ * @param columnDataObjectsByTableId
+ * @param procedureDataObjects
+ * @param config
+ * @returns An array of {@link Schema} objects.
+ */
 export declare function prepareDataForWriting(enumDataObjects: EnumData[], tableDataObjects: TableData[], columnDataObjectsByTableId: Record<number, ColumnData[]>, procedureDataObjects: ProcedureData[], config: ParsedIntrospeQLConfig): Schema[];

package/dist/prepare-data-for-writing.js

@@ -1,4 +1,15 @@
-import { snakeCaseToPascalCase } from "./snake-case-to-pascal-case";
+import { snakeCaseToPascalCase } from './snake-case-to-pascal-case';
+/**
+ * Organizes data by schema, table, and procedure, and formats it in
+ * preparation for type generation.
+ *
+ * @param enumDataObjects
+ * @param tableDataObjects
+ * @param columnDataObjectsByTableId
+ * @param procedureDataObjects
+ * @param config
+ * @returns An array of {@link Schema} objects.
+ */
 export function prepareDataForWriting(enumDataObjects, tableDataObjects, columnDataObjectsByTableId, procedureDataObjects, config) {
     const schemas = [];
     prepareEnums(enumDataObjects, schemas, config);
@@ -46,11 +57,11 @@ function prepareTables(tableDataObjects, columnDataObjectsByTableId, schemas, co
                     }
                 }
                 else {
-                    type = "string";
+                    type = 'string';
                 }
-                type += "[]".repeat(current.num_dimensions);
+                type += '[]'.repeat(current.num_dimensions);
                 if (current.nullable) {
-                    type += " | null";
+                    type += ' | null';
                 }
                 acc[current.column_name] = type;
                 return acc;
@@ -62,15 +73,15 @@ function prepareTables(tableDataObjects, columnDataObjectsByTableId, schemas, co
 function prepareProcedures(procedureDataObjects, schemas, config) {
     for (const procDataObj of procedureDataObjects) {
         const schema = findOrInsertSchema(schemas, procDataObj.schema);
-        const extantProcedureDeclarations = schema.procedures.filter((p) => p.rawName === procDataObj.name).length;
+        const extantProcedureDeclarations = schema.procedures.filter(p => p.rawName === procDataObj.name).length;
         const procData = {
             formattedName: snakeCaseToPascalCase(procDataObj.name) +
-                (extantProcedureDeclarations > 0
-                    ? "_" + extantProcedureDeclarations
-                    : ""),
+                (extantProcedureDeclarations > 0 ?
+                    '_' + extantProcedureDeclarations
+                    : ''),
             rawName: procDataObj.name,
             argNames: procDataObj.arg_names,
-            argTypes: procDataObj.arg_types.map((a) => {
+            argTypes: procDataObj.arg_types.map(a => {
                 let type;
                 const typeMappingKey = `${a.schema}.${a.name}`;
                 if (typeMappingKey in config.types) {
@@ -85,10 +96,10 @@ function prepareProcedures(procedureDataObjects, schemas, config) {
                     }
                 }
                 else {
-                    type = "string";
+                    type = 'string';
                 }
                 if (a.is_array) {
-                    type += "[]";
+                    type += '[]';
                 }
                 return type;
             }),
@@ -107,10 +118,10 @@ function prepareProcedures(procedureDataObjects, schemas, config) {
                     }
                 }
                 else {
-                    type = "string";
+                    type = 'string';
                 }
                 if (procDataObj.return_type.is_array) {
-                    type += "[]";
+                    type += '[]';
                 }
                 return type;
             })(),
@@ -119,7 +130,7 @@ function prepareProcedures(procedureDataObjects, schemas, config) {
     }
 }
 function findOrInsertSchema(schemas, rawName) {
-    let schema = schemas.find((s) => s.rawName === rawName);
+    let schema = schemas.find(s => s.rawName === rawName);
     if (schema)
         return schema;
     schema = {

package/dist/snake-case-to-pascal-case.d.ts

@@ -1 +1,8 @@
+/**
+ * Converts snake_case to PascalCase, preserving one leading underscore, if
+ * present.
+ *
+ * @param str - A snake_case string.
+ * @returns A PascalCase string.
+ */
 export declare function snakeCaseToPascalCase(str: string): string;

package/dist/snake-case-to-pascal-case.js

@@ -1,10 +1,17 @@
+/**
+ * Converts snake_case to PascalCase, preserving one leading underscore, if
+ * present.
+ *
+ * @param str - A snake_case string.
+ * @returns A PascalCase string.
+ */
 export function snakeCaseToPascalCase(str) {
     let formatted = str
-        .split("_")
-        .map((s) => s.slice(0, 1).toUpperCase() + s.slice(1))
-        .join("");
-    if (str.startsWith("_")) {
-        formatted = "_" + formatted;
+        .split('_')
+        .map(s => s.slice(0, 1).toUpperCase() + s.slice(1))
+        .join('');
+    if (str.startsWith('_')) {
+        formatted = '_' + formatted;
     }
     return formatted;
 }

package/dist/write-header.d.ts

@@ -1,2 +1,2 @@
-import type { ParsedIntrospeQLConfig } from "./introspeql-config";
+import type { ParsedIntrospeQLConfig } from './introspeql-config';
 export declare function writeHeader(outputPath: string, config: ParsedIntrospeQLConfig): void;

package/dist/write-header.js

@@ -1,10 +1,10 @@
-import fs from "node:fs";
+import fs from 'node:fs';
 export function writeHeader(outputPath, config) {
     const comment = `/* This file was generated by IntrospeQL. Do not edit manually. */\n\n`;
-    const header = config.header
-        ? comment +
+    const header = config.header ?
+        comment +
             config.header +
-            "\n".repeat(config.header.endsWith("\n") ? 1 : 2)
+            '\n'.repeat(config.header.endsWith('\n') ? 1 : 2)
         : comment;
-    fs.writeFileSync(outputPath, header, "utf-8");
+    fs.writeFileSync(outputPath, header, 'utf-8');
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "introspeql",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Easy Postgres to TypeScript type generation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
+    "format": "npx prettier . --write",
     "test": "echo \"Error: no test specified\" && exit 1",
     "build": "tsc"
   },
@@ -18,10 +19,11 @@
     "TypeScript"
   ],
   "author": "Joseph Dvorak",
-  "license": "ISC",
+  "license": "MIT",
   "type": "commonjs",
   "devDependencies": {
     "@types/node": "^24.5.2",
+    "prettier": "^3.6.2",
     "tsx": "^4.20.6",
     "typescript": "^5.9.2"
   },

package/dist/introspect-database.d.ts

@@ -1,2 +0,0 @@
-import { type IntrospeQLConfig } from "./introspeql-config";
-export declare function introspectDatabase(config: IntrospeQLConfig): Promise<void>;