true-pg 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # true-pg
 
-A truthful and complete[1] TypeScript code generator for PostgreSQL database schemas.
+A truthful and complete [^1] TypeScript code generator for PostgreSQL database schemas.
 
 ## Installation
 
@@ -12,7 +12,49 @@ yarn add true-pg
 bun add true-pg
 ```
 
-## Usage
+## Quickstart
+
+```bash
+npx true-pg --all-adapters --uri postgres://user:password@localhost:5432/database --out ./models
+```
+
+This will generate a `models` directory with the following structure:
+
+```
+models/
+├── index.ts
+├── public/
+│   ├── index.ts
+│   ├── tables/
+│   │   ├── index.ts
+│   │   └── User.ts
+│   └── views/
+│   ├── enums/
+│   └── ...
+```
+
+You can then import the `Database` type from the `index.ts` file and pass it to Kysely:
+
+```typescript
+import { Kysely } from "kysely";
+import { Database } from "./models/index.ts";
+
+const db = new Kysely<Database>( ... );
+```
+
+## Sample Database
+
+A sample database and generated models are available in the `sample` directory. You can browse the generated models in the `sample/models` directory.
+
+To run the sample yourself, run:
+
+```bash
+bun install # install dependencies
+cd sample
+bun run ../src/bin.ts
+```
+
+## Detailed Usage
 
 ### Command Line Interface
 
@@ -33,20 +75,23 @@ You can configure true-pg either through command-line arguments or a config file
 
 ### Configuration file
 
-The tool looks for configuration in the following locations (in order):
+If an explicit config file is not provided via `--config`, true-pg will look for a config file in the current working directory.
 
-1. `.truepgrc.json`
-2. `.config/.truepgrc.json`
+We use cosmiconfig to load the config file. See the [cosmiconfig docs](https://github.com/cosmiconfig/cosmiconfig#usage-for-end-users) for all possible config file formats.
+
+The recommended default is `truepg.config.ts`, or `.config/truepg.ts`.
 
 Example config file:
 
-```json
-{
-	"uri": "postgres://user:password@localhost:5432/database",
-	"out": "src/models",
-	"adapters": ["kysely", "zod"],
-	"defaultSchema": "public"
-}
+```typescript
+import { config } from "true-pg";
+
+export default config({
+	uri: "postgres://user:password@localhost:5432/database",
+	out: "src/models",
+	adapters: ["kysely", "zod"],
+	defaultSchema: "public",
+});
 ```
 
 ## Configuration Options
@@ -102,6 +147,7 @@ const generator = createGenerator(opts => ({
 await generate(
 	{
 		uri: "postgres://user:password@localhost:5432/database",
+		adapters: [], // empty array to disable adapters
 		out: "src/models",
 	},
 	[generator],
@@ -135,4 +181,4 @@ The `SchemaGenerator` interface provides methods to customize code generation:
 
 [MIT](LICENSE)
 
-[1]: We support codegen for tables, views, materialized views, enums, composite types, domains, ranges, and functions.
+[^1]: We support codegen for tables, views, materialized views, enums, composite types, domains, ranges, and functions.

package/lib/bin.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import mri from "mri";
-import { generate, adapters } from "./index.js";
+import { generate } from "./index.js";
+import { adapters } from "./config.js";
 const args = process.argv.slice(2);
 const opts = mri(args, {
     boolean: ["help", "all-adapters"],

package/lib/config.d.ts

@@ -0,0 +1,51 @@
+import type { Extractor } from "./extractor/index.ts";
+import { type Deunionise } from "./util.ts";
+export type ExtractorConfig = Exclude<ConstructorParameters<typeof Extractor>[0], string | undefined>;
+export interface BaseConfig {
+    /** The output directory for the generated models. Default: "models" */
+    out?: string;
+    /** Adapters to enable. Currently supported adapters are "kysely" and "zod". Default: ["kysely"] */
+    adapters?: ("kysely" | "zod")[];
+    /** The default schema to use for the generated models. These will be unprefixed in the final `Database` interface. Default: "public" */
+    defaultSchema?: string;
+}
+export interface PgConfig extends BaseConfig {
+    /** An instance of node-postgres Client or Pool, or an instance of Pglite. */
+    pg: ExtractorConfig["pg"];
+}
+export interface UriConfig extends BaseConfig {
+    /** A connection string for node-postgres Pool. */
+    uri: ExtractorConfig["uri"];
+}
+export interface ConfigConfig extends BaseConfig {
+    /** A configuration object for node-postgres Pool. */
+    config: ExtractorConfig["config"];
+}
+export type TruePGConfig = Deunionise<PgConfig | UriConfig | ConfigConfig>;
+export declare const adapters: {
+    kysely: import("./types.ts").createGenerator;
+    zod: import("./types.ts").createGenerator;
+};
+export declare function config(opts: TruePGConfig): {
+    out: string;
+    adapters: ("kysely" | "zod")[];
+    defaultSchema: string;
+    pg: ExtractorConfig["pg"];
+    uri?: undefined;
+    config?: undefined;
+} | {
+    out: string;
+    adapters: ("kysely" | "zod")[];
+    defaultSchema: string;
+    uri: ExtractorConfig["uri"];
+    pg?: undefined;
+    config?: undefined;
+} | {
+    out: string;
+    adapters: ("kysely" | "zod")[];
+    defaultSchema: string;
+    config: ExtractorConfig["config"];
+    pg?: undefined;
+    uri?: undefined;
+};
+export type ValidatedConfig = ReturnType<typeof config>;

package/lib/config.js

@@ -0,0 +1,32 @@
+import { normalize as normalise } from "node:path";
+import {} from "./util.js";
+import { Kysely } from "./kysely/index.js";
+import { Zod } from "./zod/index.js";
+export const adapters = {
+    kysely: Kysely,
+    zod: Zod,
+};
+const availableAdapters = Object.keys(adapters);
+export function config(opts) {
+    const out = normalise(opts.out || "./models");
+    const adapters = opts.adapters || ["kysely"];
+    const defaultSchema = opts.defaultSchema || "public";
+    for (const adapter of opts.adapters ?? []) {
+        if (!availableAdapters.includes(adapter)) {
+            console.error('Requested adapter "%s" not found.', adapter);
+            console.error("Available adapters: %s", availableAdapters.join(", "));
+            console.error("See documentation for more information.");
+            process.exit(1);
+        }
+    }
+    if (!("uri" in opts) && !("config" in opts) && !("pg" in opts)) {
+        console.error("One of these options are required in your config file: uri, config, pg. See documentation for more information.");
+        process.exit(1);
+    }
+    return {
+        ...opts,
+        out,
+        adapters,
+        defaultSchema,
+    };
+}

package/lib/extractor/adapter.d.ts

@@ -1,8 +1,9 @@
-import { Client as Pg } from "pg";
+import { Client as PgClient, Pool as PgPool } from "pg";
 import { PGlite as Pglite } from "@electric-sql/pglite";
 export declare class DbAdapter {
     private client;
-    constructor(client: Pg | Pglite);
+    private external?;
+    constructor(client: PgClient | PgPool | Pglite, external?: boolean | undefined);
     connect(): Promise<void>;
     /**
      * Execute a read query and return just the rows

package/lib/extractor/adapter.js

@@ -1,12 +1,19 @@
-import { Client as Pg } from "pg";
+import { Client as PgClient, Pool as PgPool } from "pg";
 import { PGlite as Pglite } from "@electric-sql/pglite";
 export class DbAdapter {
     client;
-    constructor(client) {
+    external;
+    constructor(client, external) {
         this.client = client;
+        this.external = external;
     }
     async connect() {
-        if (this.client instanceof Pg) {
+        if (this.external)
+            return;
+        if (this.client instanceof PgPool) {
+            // queries will automatically checkout a client and return it to the pool
+        }
+        else if (this.client instanceof PgClient) {
             return this.client.connect();
         }
         else if (this.client instanceof Pglite) {
@@ -43,7 +50,12 @@ export class DbAdapter {
      * Close the connection if needed
      */
     async close() {
-        if (this.client instanceof Pg) {
+        if (this.external)
+            return;
+        if (this.client instanceof PgPool) {
+            this.client.end();
+        }
+        else if (this.client instanceof PgClient) {
             await this.client.end();
         }
         else if (this.client instanceof Pglite) {

package/lib/extractor/index.d.ts

@@ -1,4 +1,4 @@
-import { Client as Pg, type ConnectionConfig } from "pg";
+import { Client as PgClient, Pool as PgPool, type ConnectionConfig } from "pg";
 import { PGlite as Pglite } from "@electric-sql/pglite";
 import { type TableDetails } from "./kinds/table.ts";
 import { type ViewDetails } from "./kinds/view.ts";
@@ -76,7 +76,7 @@ export declare class Extractor {
      * @param connectionConfig - Connection string or configuration object for Postgres connection
      */
     constructor(opts: {
-        pg?: Pg | Pglite;
+        pg?: PgClient | PgPool | Pglite;
         uri?: string;
         config?: ConnectionConfig;
     });

package/lib/extractor/index.js

@@ -1,4 +1,4 @@
-import { Client as Pg } from "pg";
+import { Client as PgClient, Pool as PgPool } from "pg";
 import { PGlite as Pglite } from "@electric-sql/pglite";
 import { DbAdapter } from "./adapter.js";
 import extractTable, {} from "./kinds/table.js";
@@ -43,14 +43,14 @@ export class Extractor {
         if (opts.pg)
             pg = opts.pg;
         else if (opts.uri)
-            pg = new Pg({ connectionString: opts.uri });
+            pg = new PgPool({ connectionString: opts.uri });
         else if (opts.config)
-            pg = new Pg(opts.config);
+            pg = new PgPool(opts.config);
         else {
             console.error("One of these options are required in your config file: pg, uri, config. See documentation for more information.");
             process.exit(1);
         }
-        this.db = new DbAdapter(pg);
+        this.db = new DbAdapter(pg, opts.pg ? true : false);
     }
     async canonicalise(types) {
         return canonicalise(this.db, types);

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import { type TruePGConfig, type createGenerator } from "./types.ts";
-export { config } from "./types.ts";
-export declare const adapters: Record<string, createGenerator>;
+import { type createGenerator } from "./types.ts";
+import { type TruePGConfig, type ValidatedConfig, config } from "./config.ts";
+export { type TruePGConfig, type ValidatedConfig, config };
 export declare function generate(opts: TruePGConfig, generators?: createGenerator[]): Promise<void>;

package/lib/index.js

@@ -1,14 +1,14 @@
 import { Extractor, FunctionReturnTypeKind } from "./extractor/index.js";
-import { rm, mkdir, writeFile } from "fs/promises";
+import { rm, mkdir, writeFile } from "node:fs/promises";
 import { Nodes, allowed_kind_names } from "./types.js";
-import { existsSync } from "fs";
+import { existsSync } from "node:fs";
 import { join } from "./util.js";
-export { config } from "./types.js";
-import { Kysely } from "./kysely/index.js";
-import { Zod } from "./zod/index.js";
-export const adapters = {
-    kysely: Kysely,
-    zod: Zod,
+import { join as joinpath } from "node:path";
+import { config, adapters } from "./config.js";
+export { config };
+const time = (start) => {
+    const end = performance.now();
+    return (end - start).toFixed(2);
 };
 const filter_function = (func) => {
     const typesToFilter = [
@@ -77,7 +77,7 @@ const multifile = async (generators, schemas, opts) => {
     };
     for (const schema of Object.values(schemas)) {
         console.log("Selected schema '%s':\n", schema.name);
-        const schemaDir = `${out}/${schema.name}`;
+        const schemaDir = joinpath(out, schema.name);
         // skip functions that cannot be represented in JavaScript
         schema.functions = schema.functions.filter(filter_function);
         {
@@ -92,11 +92,11 @@ const multifile = async (generators, schemas, opts) => {
             if (schema[kind].length < 1)
                 continue;
             createIndex = true;
-            await mkdir(`${schemaDir}/${kind}`, { recursive: true });
+            await mkdir(joinpath(schemaDir, kind), { recursive: true });
             console.log(" Creating %s:\n", kind);
             for (const [i, item] of schema[kind].entries()) {
                 const index = "[" + (i + 1 + "]").padEnd(3, " ");
-                const filename = `${schemaDir}/${kind}/${def_gen.formatSchemaType(item)}.ts`;
+                const filename = joinpath(schemaDir, kind, def_gen.formatSchemaType(item) + ".ts");
                 const exists = await existsSync(filename);
                 if (exists) {
                     warnings.push(`Skipping ${item.kind} "${item.name}": formatted name clashes. Wanted to create ${filename}`);
@@ -127,54 +127,52 @@ const multifile = async (generators, schemas, opts) => {
                 parts.push(file);
                 file = join(parts);
                 await write(filename, file);
+                console.log("  %s %s \x1b[32m(%sms)\x1B[0m", index, filename, time(start));
+            }
+            {
+                const start = performance.now();
+                const kindIndex = join(gens.map(gen => gen.schemaKindIndex(schema, kind, def_gen)));
+                const kindIndexFilename = joinpath(schemaDir, kind, "index.ts");
+                await write(kindIndexFilename, kindIndex);
                 const end = performance.now();
-                console.log("  %s %s \x1b[32m(%sms)\x1B[0m", index, filename, (end - start).toFixed(2));
+                console.log("  ✅   Created %s index: %s \x1b[32m(%sms)\x1B[0m\n", kind, kindIndexFilename, (end - start).toFixed(2));
             }
-            const kindIndex = join(gens.map(gen => gen.schemaKindIndex(schema, kind, def_gen)));
-            const kindIndexFilename = `${schemaDir}/${kind}/index.ts`;
-            await write(kindIndexFilename, kindIndex);
-            console.log('  ✅   Created "%s" %s index: %s\n', schema.name, kind, kindIndexFilename);
         }
         if (!createIndex)
             continue;
-        const index = join(gens.map(gen => gen.schemaIndex(schema, def_gen)));
-        const indexFilename = `${out}/${schema.name}/index.ts`;
-        await write(indexFilename, index);
-        console.log(" Created schema index: %s\n", indexFilename);
+        {
+            const start = performance.now();
+            const index = join(gens.map(gen => gen.schemaIndex(schema, def_gen)));
+            const indexFilename = joinpath(schemaDir, "index.ts");
+            await write(indexFilename, index);
+            console.log(" Created schema index: %s \x1b[32m(%sms)\x1B[0m\n", indexFilename, time(start));
+        }
+    }
+    {
+        const start = performance.now();
+        const fullIndex = join(gens.map(gen => gen.fullIndex(Object.values(schemas))));
+        const fullIndexFilename = joinpath(out, "index.ts");
+        await write(fullIndexFilename, fullIndex);
+        console.log("Created full index: %s \x1b[32m(%sms)\x1B[0m", fullIndexFilename, time(start));
     }
-    const fullIndex = join(gens.map(gen => gen.fullIndex(Object.values(schemas))));
-    const fullIndexFilename = `${out}/index.ts`;
-    await write(fullIndexFilename, fullIndex);
-    console.log("Created full index: %s", fullIndexFilename);
     if (warnings.length > 0) {
         console.log("\nWarnings generated:");
         console.log(warnings.map(warning => "* " + warning).join("\n"));
     }
 };
 export async function generate(opts, generators) {
-    const out = opts.out || "./models";
-    if (!("uri" in opts) && !("config" in opts) && !("pg" in opts)) {
-        console.error("One of these options are required in your config file: uri, config, pg. See documentation for more information.");
-        process.exit(1);
-    }
+    const validated = config(opts);
+    const out = validated.out;
     const extractor = new Extractor(opts);
     const start = performance.now();
     const schemas = await extractor.extractSchemas();
     const end = performance.now();
-    console.log("Extracted schemas in \x1b[32m%sms\x1b[0m", (end - start).toFixed(2));
-    console.info("Adapters enabled: %s\n", opts.adapters.join(", "));
-    generators ??= opts.adapters.map(adapter => {
-        const selected = adapters[adapter];
-        if (!selected)
-            throw new Error(`Requested adapter ${adapter} not found`);
-        return selected;
-    });
-    console.log("Clearing directory and generating schemas at '%s'", out);
+    console.log("Extracted schemas \x1b[32m(%sms)\x1b[0m\n", (end - start).toFixed(2));
+    console.info("Adapters enabled: %s\n", validated.adapters.join(", "));
+    generators = validated.adapters.map(adapter => adapters[adapter]).concat(generators ?? []);
+    console.log("Clearing directory and generating schemas at '%s'\n", out);
     await rm(out, { recursive: true, force: true });
     await mkdir(out, { recursive: true });
-    await multifile(generators, schemas, { ...opts, out });
-    {
-        const end = performance.now();
-        console.log("Completed in \x1b[32m%sms\x1b[0m", (end - start).toFixed(2));
-    }
+    await multifile(generators, schemas, validated);
+    console.log("Completed in \x1b[32m%sms\x1b[0m", time(start));
 }

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import { Canonical, type Extractor, type TableDetails, type ViewDetails, type MaterializedViewDetails, type EnumDetails, type CompositeTypeDetails, type DomainDetails, type RangeDetails, type FunctionDetails, type SchemaType, type Schema, type FunctionReturnType } from "./extractor/index.ts";
+import { Canonical, type TableDetails, type ViewDetails, type MaterializedViewDetails, type EnumDetails, type CompositeTypeDetails, type DomainDetails, type RangeDetails, type FunctionDetails, type SchemaType, type Schema, type FunctionReturnType } from "./extractor/index.ts";
 export declare const allowed_kind_names: readonly ["tables", "views", "materializedViews", "enums", "composites", "functions", "domains", "ranges"];
 export type allowed_kind_names = (typeof allowed_kind_names)[number];
 export interface FolderStructure {
@@ -64,23 +64,6 @@ export declare namespace Nodes {
         star: boolean;
     }
 }
-export type ExtractorConfig = Exclude<ConstructorParameters<typeof Extractor>[0], string | undefined>;
-export interface BaseConfig {
-    out: string;
-    adapters: string[];
-    defaultSchema?: string;
-}
-export interface PgConfig extends BaseConfig {
-    pg: ExtractorConfig["pg"];
-}
-export interface UriConfig extends BaseConfig {
-    uri: ExtractorConfig["uri"];
-}
-export interface ConfigConfig extends BaseConfig {
-    config: ExtractorConfig["config"];
-}
-export type TruePGConfig = PgConfig | UriConfig | ConfigConfig;
-export declare function config(opts: TruePGConfig): TruePGConfig;
 export interface CreateGeneratorOpts {
     defaultSchema?: string;
     warnings: string[];

package/lib/types.js

@@ -175,8 +175,5 @@ export var Nodes;
     }
     Nodes.ImportList = ImportList;
 })(Nodes || (Nodes = {}));
-export function config(opts) {
-    return opts;
-}
 /* convenience function to create a generator with type inference */
 export const createGenerator = (generatorCreator) => generatorCreator;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "true-pg",
-	"version": "0.3.1",
+	"version": "0.4.0",
 	"type": "module",
 	"module": "lib/index.js",
 	"main": "lib/index.js",
@@ -21,7 +21,8 @@
 		"prepare": "bun run build"
 	},
 	"devDependencies": {
-		"@types/bun": "latest"
+		"@types/bun": "latest",
+		"@types/pg": "^8.11.13"
 	},
 	"peerDependencies": {
 		"kysely": "^0.27",
@@ -29,7 +30,9 @@
 		"zod": "^3"
 	},
 	"dependencies": {
+		"@electric-sql/pglite": "^0.2.17",
 		"cosmiconfig": "^9.0.0",
-		"mri": "^1.2.0"
+		"mri": "^1.2.0",
+		"pg": "^8.14.1"
 	}
 }