true-pg 0.0.1

package/.github/workflows/releases.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: oven-sh/setup-bun@v2
+    - run : bun install
+    - run : bun run prepare
+    - name: Publish to npm
+      run : |
+        bun run version.ts
+        bun publish --ignore-scripts --access=public
+      env :
+        NPM_CONFIG_TOKEN: ${{ secrets.NPM_CONFIG_TOKEN }}
+        NPM_CONFIG_PROVENANCE: true
+    - name: Publish to JSR
+      run: bunx jsr publish --allow-dirty

package/README.md

@@ -0,0 +1,133 @@
+# true-pg
+
+A truthful and complete<sup>†</sup> TypeScript code generator for PostgreSQL database schemas.
+
+## Installation
+
+```bash
+npm install true-pg
+# or
+yarn add true-pg
+# or
+bun add true-pg
+```
+
+## Usage
+
+### Command Line Interface
+
+```bash
+true-pg [options]
+```
+
+Options:
+
+- `-h, --help` - Show help information
+- `-c, --config [path]` - Path to config file (JSON)
+- `-u, --uri [uri]` - Database URI (Postgres only!)
+- `-o, --out [path]` - Path to output directory (defaults to "models")
+- `-a, --adapter [adapter]` - Adapter to use (e.g. `kysely`, `zod`). Can be specified multiple times.
+- `-A, --all-adapters` - Enable all built-in adapters
+
+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):
+
+1. `.truepgrc.json`
+2. `.config/.truepgrc.json`
+
+Example config file:
+
+```json
+{
+	"uri": "postgres://user:password@localhost:5432/database",
+	"out": "src/models",
+	"adapters": ["kysely", "zod"],
+	"defaultSchema": "public"
+}
+```
+
+## Configuration Options
+
+| Option          | Description                                              | Default    |
+| --------------- | -------------------------------------------------------- | ---------- |
+| `uri`           | PostgreSQL connection URI                                | Required   |
+| `out`           | Output directory for generated files                     | `"models"` |
+| `adapters`      | Adapters to use (e.g. `kysely`, `zod`)                   | `"kysely"` |
+| `defaultSchema` | Default schema to use (Kysely schema will be unprefixed) | `"public"` |
+
+## Customising Code Generation
+
+> 🔔 HERE BE DRAGONS!
+>
+> Keep in mind that programmatic usage of `true-pg` is not yet stable. Functions and methods may change until we're comfortable with the API.
+>
+> However, if you're interested, we welcome your feedback and contributions!
+
+You can create a custom generator to control how code is generated:
+
+```typescript
+import { createGenerator, generate } from "true-pg";
+
+const generator = createGenerator(opts => ({
+	formatSchema: name => `${name}Schema`,
+	formatSchemaType: type => `${type}Type`,
+	formatType: type => `${type}Interface`,
+	table: (imports, table) => {
+		// Custom table type generation
+	},
+	enum: (imports, en) => {
+		// Custom enum type generation
+	},
+	composite: (imports, composite) => {
+		// Custom composite type generation
+	},
+	function: (imports, func) => {
+		// Custom function type generation
+	},
+	schemaKindIndex: (schema, kind) => {
+		// Custom schema kind index generation
+	},
+	schemaIndex: schema => {
+		// Custom schema index generation
+	},
+	fullIndex: schemas => {
+		// Custom full index generation
+	},
+}));
+
+await generate(
+	{
+		uri: "postgres://user:password@localhost:5432/database",
+		out: "src/models",
+	},
+	[generator],
+);
+```
+
+Filenames will be created using the `format*` methods of the FIRST generator passed to `generate` or via the `--adapter` CLI option.
+
+## Schema Generator Interface
+
+The `SchemaGenerator` interface provides methods to customize code generation:
+
+| Method                          | Description                                                       |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `formatSchema(name)`            | Formats schema names (public -> PublicSchema)                     |
+| `formatSchemaType(type)`        | Formats schema type names (user_sessions -> UserSessions)         |
+| `formatType(type)`              | Formats type names (pg_catalog.int4 -> number)                    |
+| `table(types, table)`           | Generates code for tables                                         |
+| `enum(types, en)`               | Generates code for enums                                          |
+| `composite(types, composite)`   | Generates code for composite types                                |
+| `function(types, func)`         | Generates code for functions                                      |
+| `schemaKindIndex(schema, kind)` | Generates index for a schema kind (models/public/tables/index.ts) |
+| `schemaIndex(schema)`           | Generates index for a schema (models/public/index.ts)             |
+| `fullIndex(schemas)`            | Generates full index (models/index.ts)                            |
+
+## License
+
+[MIT](LICENSE)
+
+<sup>†</sup> We only support tables, enums, composite types, and functions at the moment, but we're working on adding support for views, materialised views, domains, and more.

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "true-pg",
+	"version": "0.0.1",
+	"module": "src/index.ts",
+	"type": "module",
+	"main": "src/index.ts",
+	"bin": {
+		"true-pg": "src/bin.ts"
+	},
+	"scripts": {
+		"check": "tsc --noEmit",
+		"build": "tsc"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"kysely": "^0.27",
+		"typescript": "^5",
+		"zod": "^3"
+	},
+	"dependencies": {
+		"mri": "^1.2.0",
+		"pg-extract": "^0.0.3"
+	}
+}

package/src/bin.ts

@@ -0,0 +1,81 @@
+import mri from "mri";
+import { existsSync } from "fs";
+import { generate, adapters } from "./index.ts";
+
+const args = process.argv.slice(2);
+const opts = mri<{
+	"help"?: boolean;
+	"config"?: string;
+	"uri"?: string;
+	"out"?: string;
+	"adapter"?: string | string[];
+	"all-adapters"?: boolean;
+}>(args, {
+	boolean: ["help", "all-adapters"],
+	string: ["config", "uri", "out", "adapter"],
+	alias: {
+		h: "help",
+		c: "config",
+		u: "uri",
+		o: "out",
+		a: "adapter",
+		A: "all-adapters",
+	},
+});
+
+const help = opts.help || (!opts.config && !opts.uri);
+
+if (help) {
+	// if help is triggered unintentionally, it's a user error
+	const type = opts.help ? "log" : "error";
+	const log = console[type];
+
+	log();
+	log("Usage: true-pg [options]");
+	log();
+	log("Options:");
+	log("  -h, --help                  Show help");
+	log("  -u, --uri      [uri]        Database URI (Postgres only!)");
+	log("  -o, --out      [path]       Path to output directory");
+	log("  -a, --adapter  [adapter]    Output adapter to use (default: 'kysely')");
+	log("  -A, --all-adapters          Output all adapters");
+	log("  -c, --config   [path]       Path to config file (JSON)");
+	log("                              Defaults to '.truepgrc.json' or '.config/.truepgrc.json'");
+	log("Example:");
+	log("  true-pg -u postgres://user:pass@localhost:5432/my-database -o models -a kysely -a zod");
+	log();
+	if (opts.help) process.exit(0);
+	else process.exit(1);
+}
+
+let configfile = opts.config;
+if (!configfile) {
+	const candidates = [".truepgrc.json", ".config/.truepgrc.json"];
+	for (const candidate of candidates) {
+		if (await existsSync(candidate)) {
+			configfile = candidate;
+			break;
+		}
+	}
+}
+
+const config = configfile ? await Bun.file(configfile).json() : {};
+
+if (opts["all-adapters"]) {
+	opts.adapter = Object.keys(adapters);
+	console.log("Enabling all built-in adapters:", opts.adapter);
+}
+
+if (!(opts.adapter || config.adapters)) console.warn('No adapters specified, using default: ["kysely"]');
+
+opts.out ??= "models";
+// allow single adapter or comma-separated list of adapters
+if (typeof opts.adapter === "string") opts.adapter = opts.adapter.split(",");
+opts.adapter ??= ["kysely"];
+
+// CLI args take precedence over config file
+config.uri = opts.uri ?? config.uri;
+config.out = opts.out ?? config.out;
+config.adapters = opts.adapter ?? config.adapters;
+
+await generate(config);

package/src/consumer.ts

@@ -0,0 +1,38 @@
+export declare namespace True {
+	export type Column<Selectable, Insertable = Selectable, Updateable = Selectable> = {
+		"@true-pg/insert": Insertable;
+		"@true-pg/update": Updateable;
+		"@true-pg/select": Selectable;
+	};
+
+	export type Generated<T> = Column<T, T | undefined, T | undefined>;
+	export type HasDefault<T> = Column<T, T | undefined, T | undefined>;
+	export type AlwaysGenerated<T> = Column<T, never, never>;
+
+	type DrainOuterGeneric<T> = [T] extends [unknown] ? T : never;
+	type Simplify<T> = DrainOuterGeneric<{ [K in keyof T]: T[K] } & {}>;
+
+	export type Selectable<T extends Record<string, any>> = Simplify<{
+		[K in keyof T]: T[K] extends Record<string, any>
+			? Selectable<T[K]>
+			: T[K] extends Column<infer S, infer I, infer U>
+				? S
+				: T[K];
+	}>;
+
+	export type Insertable<T extends Record<string, any>> = Simplify<{
+		[K in keyof T]: T[K] extends Record<string, any>
+			? Insertable<T[K]>
+			: T[K] extends Column<infer S, infer I, infer U>
+				? I
+				: T[K];
+	}>;
+
+	export type Updateable<T extends Record<string, any>> = Simplify<{
+		[K in keyof T]?: T[K] extends Record<string, any>
+			? Updateable<T[K]>
+			: T[K] extends Column<infer S, infer I, infer U>
+				? U
+				: T[K];
+	}>;
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+import { Extractor, type FunctionDetails, type Schema } from "pg-extract";
+import { rm, mkdir, writeFile } from "fs/promises";
+import { Nodes, allowed_kind_names, type FolderStructure, type TruePGOpts, type createGenerator } from "./types.ts";
+import { existsSync } from "fs";
+import { join } from "./util.ts";
+
+import { Kysely } from "./kysely/index.ts";
+import { Zod } from "./zod/index.ts";
+
+export const adapters: Record<string, createGenerator> = {
+	kysely: Kysely,
+	zod: Zod,
+};
+
+export * from "./consumer.ts";
+
+const filter_function = (func: FunctionDetails, warnings: string[]) => {
+	const typesToFilter = [
+		"pg_catalog.trigger",
+		"pg_catalog.event_trigger",
+		"pg_catalog.internal",
+		"pg_catalog.language_handler",
+		"pg_catalog.fdw_handler",
+		"pg_catalog.index_am_handler",
+		"pg_catalog.tsm_handler",
+	];
+
+	const warn = (type: string) =>
+		warnings.push(`Skipping function ${func.name}: cannot represent ${type} (safe to ignore)`);
+
+	if (func.returnType.kind === "table") {
+		for (const col of func.returnType.columns) {
+			if (typesToFilter.includes(col.type.canonical_name)) {
+				warn(col.type.canonical_name);
+				return false;
+			}
+		}
+	} else {
+		if (typesToFilter.includes(func.returnType.type.canonical_name)) {
+			warn(func.returnType.type.canonical_name);
+			return false;
+		}
+	}
+
+	for (const param of func.parameters) {
+		if (typesToFilter.includes(param.type.canonical_name)) {
+			warn(param.type.canonical_name);
+			return false;
+		}
+	}
+
+	return func;
+};
+
+const write = (filename: string, file: string) => writeFile(filename, file + "\n");
+
+const multifile = async (generators: createGenerator[], schemas: Record<string, Schema>, opts: TruePGOpts) => {
+	const { out } = opts;
+
+	const warnings: string[] = [];
+	const gens = generators.map(g => g({ ...opts, warnings }));
+	const def_gen = gens[0]!;
+
+	const files: FolderStructure = {
+		name: out,
+		type: "root",
+		children: Object.fromEntries(
+			Object.values(schemas).map(schema => [
+				schema.name,
+				{
+					name: schema.name,
+					type: "schema",
+					children: Object.fromEntries(
+						allowed_kind_names.map(kind => [
+							kind,
+							{
+								kind: kind,
+								type: "kind",
+								children: Object.fromEntries(
+									schema[kind].map(item => [
+										item.name,
+										{
+											name: def_gen.formatSchemaType(item),
+											type: "type",
+										},
+									]),
+								),
+							},
+						]),
+					),
+				},
+			]),
+		),
+	};
+
+	const start = performance.now();
+
+	for (const schema of Object.values(schemas)) {
+		console.log("Selected schema '%s':\n", schema.name);
+
+		const schemaDir = `${out}/${schema.name}`;
+
+		// skip functions that cannot be represented in JavaScript
+		schema.functions = schema.functions.filter(f => filter_function(f, warnings));
+
+		for (const kind of allowed_kind_names) {
+			if (schema[kind].length < 1) continue;
+
+			await mkdir(`${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 exists = await existsSync(filename);
+
+				if (exists) {
+					warnings.push(
+						`Skipping ${item.kind} "${item.name}": formatted name clashes. Wanted to create ${filename}`,
+					);
+					continue;
+				}
+
+				const start = performance.now();
+
+				let file = "";
+
+				const imports = new Nodes.ImportList([]);
+
+				if (item.kind === "table") file += join(gens.map(gen => gen.table(imports, item)));
+				if (item.kind === "composite") file += join(gens.map(gen => gen.composite(imports, item)));
+				if (item.kind === "enum") file += join(gens.map(gen => gen.enum(imports, item)));
+				if (item.kind === "function") file += join(gens.map(gen => gen.function(imports, item)));
+
+				const parts: string[] = [];
+				parts.push(imports.stringify(filename, files));
+				parts.push(file);
+				file = join(parts);
+
+				await write(filename, file);
+
+				const end = performance.now();
+				console.log("  %s %s \x1b[32m(%sms)\x1B[0m", index, filename, (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);
+		}
+
+		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 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);
+	const end = performance.now();
+	console.log("Completed in \x1b[32m%sms\x1b[0m", (end - start).toFixed(2));
+
+	if (warnings.length > 0) {
+		console.log("\nWarnings generated:");
+		console.log(warnings.map(warning => "* " + warning).join("\n"));
+	}
+};
+
+export async function generate(opts: TruePGOpts, generators?: createGenerator[]) {
+	const out = opts.out || "./models";
+	const extractor = new Extractor(opts.uri);
+	const schemas = await extractor.extractSchemas();
+	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);
+	await rm(out, { recursive: true, force: true });
+	await mkdir(out, { recursive: true });
+	await multifile(generators, schemas, { ...opts, out });
+}

package/src/kysely/builtins.ts

@@ -0,0 +1,38 @@
+// extended from https://github.com/kristiandupont/kanel/blob/e9332f03ff5e38f5b844dd7a4563580c0d9d1444/packages/kanel/src/defaultTypeMap.ts
+
+export const builtins: Record<string, string> = {
+	"pg_catalog.int2": "number",
+	"pg_catalog.int4": "number",
+
+	// JS numbers are always floating point, so there is only 53 bits of precision
+	// for the integer part. Thus, storing a 64-bit integer in a JS number will
+	// result in potential data loss. We therefore use strings for 64-bit integers
+	// the same way that the pg driver does.
+	"pg_catalog.int8": "string",
+
+	"pg_catalog.float4": "number",
+	"pg_catalog.float8": "number",
+	"pg_catalog.numeric": "string",
+	"pg_catalog.bool": "boolean",
+	"pg_catalog.json": "unknown",
+	"pg_catalog.jsonb": "unknown",
+	"pg_catalog.char": "string",
+	"pg_catalog.bpchar": "string",
+	"pg_catalog.varchar": "string",
+	"pg_catalog.text": "string",
+	"pg_catalog.uuid": "string",
+	"pg_catalog.inet": "string",
+	"pg_catalog.date": "Date",
+	"pg_catalog.time": "Date",
+	"pg_catalog.timetz": "Date",
+	"pg_catalog.timestamp": "Date",
+	"pg_catalog.timestamptz": "Date",
+	"pg_catalog.int4range": "string",
+	"pg_catalog.int8range": "string",
+	"pg_catalog.numrange": "string",
+	"pg_catalog.tsrange": "string",
+	"pg_catalog.tstzrange": "string",
+	"pg_catalog.daterange": "string",
+	"pg_catalog.record": "Record<string, unknown>",
+	"pg_catalog.void": "void",
+};