Refactor configuration options in README, update SQL type handling, and clean up ignore files

seralexeev · seralexeev · commit 4f5dc4d5b01f · 2025-02-09T11:22:06.000+11:00
diff --git a/.gitignore b/.gitignore
@@ -86,7 +86,7 @@ web_modules/
 # Next.js build output
 .next
 out
-.sqlc
+**/.sqlc
 
 # Nuxt.js build / generate output
 .nuxt
diff --git a/.npmignore b/.npmignore
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -1,5 +1,7 @@
 {
     "cSpell.words": [
+        "dbsource",
+        "dbtype",
         "execrows",
         "sqlc",
         "tstype"
diff --git a/README.md b/README.md
@@ -98,19 +98,43 @@ yarn add sqlc-typescript
 pnpm add sqlc-typescript
 ```
 
-## 📝 Configuration
+## 📝 Configuration Options
 
-Create a `sqlc.json` in your project root:
+The following configuration options can be set in your `sqlc.json` file:
+
+| Option      | Type                        | Default         | Description                                                                                                                                                                                                 |
+| ----------- | --------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`    | `string`                    | `"schema.sql"`  | Path to your SQL schema file, typically generated using `pg_dump --schema-only`. This file should contain your database schema definitions including tables, views, and types.                              |
+| `include`   | `string`                    | `"src/**/*.ts"` | Glob pattern for TypeScript files to scan for SQL queries. The generator will look for queries marked with `/*sql*/` in these files.                                                                        |
+| `output`    | `string`                    | `"src/sqlc.ts"` | Location where the generated TypeScript types file will be written. This file will contain all the type definitions and the `sqlc` function.                                                                |
+| `tmp_dir`   | `string`                    | `".sqlc"`       | Directory used for temporary files during type generation. This directory will contain intermediate files used by sqlc.                                                                                     |
+| `clear_tmp` | `boolean`                   | `true`          | Whether to remove the temporary directory after type generation is complete. Set to `false` if you need to inspect the intermediate files for debugging.                                                    |
+| `types`     | `{ [key: string]: string }` | `{}`            | Map of PostgreSQL types to TypeScript types. Use this to override the default type mappings for specific database types.                                                                                    |
+| `columns`   | `{ [key: string]: string }` | `{}`            | Map of specific column types to TypeScript types. This takes precedence over both default type mappings and `types` overrides. The key should be in the format `"table.column"` or `"schema.table.column"`. |
+| `imports`   | `string[]`                  | `[]`            | Array of import statements to include in the generated file. Use this when you need to import custom types used in your `types` or `columns` mappings.                                                      |
+
+### Example Configuration
 
 ```json
 {
-    "include": "src/**/*.ts",
-    "schema": "schema.sql",
-    "output": "src/sqlc.ts",
+    "schema": "db/schema.sql",
+    "include": "src/**/*.{ts,tsx}",
+    "output": "src/generated/sqlc.ts",
+    "tmp_dir": ".sqlc-temp",
+    "clear_tmp": true,
+    "types": {
+        "timestamptz": "DateTime",
+        "json": "JSONValue"
+    },
     "columns": {
-        "customer.customer_id": "UUID"
+        "users.id": "UUID",
+        "orders.status": "OrderStatus"
     },
-    "imports": ["import { UUID } from '../types'"]
+    "imports": [
+        "import type { UUID } from '../types'",
+        "import type { OrderStatus } from '../db-types'",
+        "import type { JSONValue } from '../json-types'"
+    ]
 }
 ```
 
diff --git a/src/render.ts b/src/render.ts
@@ -20,7 +20,7 @@ export const generate_types = ({
             line += `{ `;
             line += query.columns
                 .map((column) => {
-                    return `"${column.name}": ${column_to_tstype({ column, config, schema_types })}`;
+                    return `"${column.name}": ${column_to_tstype({ column, config, schema_types, branded: true })}`;
                 })
                 .join(';');
             line += ` },`;
@@ -32,7 +32,7 @@ export const generate_types = ({
             line += `{`;
             line += query.params
                 .map((param) => {
-                    return `"${param.column.name}": ${column_to_tstype({ column: param.column, config, schema_types })}`;
+                    return `"${param.column.name}": ${column_to_tstype({ column: param.column, config, schema_types, branded: false })}`;
                 })
                 .join(';');
             line += `}`;
@@ -99,12 +99,14 @@ const column_to_tstype = ({
     column,
     schema_types,
     config,
+    branded,
 }: {
     column: Column;
     schema_types: Set<string>;
     config: Pick<Config, 'types' | 'columns'>;
+    branded: boolean;
 }) => {
-    let type = get_column_type({ config, column, schema_types });
+    let type = get_column_type({ config, column, schema_types, branded });
 
     if (column.is_array) {
         type = `Array<${type}>`;
@@ -121,10 +123,12 @@ const get_column_type = ({
     column,
     schema_types,
     config,
+    branded,
 }: {
     column: Column;
     schema_types: Set<string>;
     config: Pick<Config, 'types' | 'columns'>;
+    branded: boolean;
 }) => {
     const source = [
         ...[column.table?.schema, ...(column.table?.name.split('.') ?? [])].filter(
@@ -133,20 +137,29 @@ const get_column_type = ({
         column.original_name,
     ].join('.');
 
-    if (config.columns[source]) {
-        return config.columns[source];
-    }
-
     const parts = [column.type.schema, column.type.name.split('.')]
         .flat()
         .filter((x) => x != null && x !== '' && x !== 'public' && x !== 'pg_catalog');
 
-    const type = parts.join('.');
-    if (schema_types.has(type)) {
-        return [column.type.schema, column.type.name].join('.');
+    const db_type = parts.join('.');
+
+    const final_type = (() => {
+        if (config.columns[source]) {
+            return config.columns[source];
+        }
+
+        if (schema_types.has(db_type)) {
+            return [column.type.schema, column.type.name].join('.');
+        }
+
+        return DEFAULT_TYPES[db_type] || config.types[db_type] || DEFAULT_TYPES[db_type] || 'unknown';
+    })();
+
+    if (branded) {
+        return `SqlType<${final_type}, '${db_type}', '${source}'>`;
     }
 
-    return config.types[type] || DEFAULT_TYPES[type] || 'unknown';
+    return final_type;
 };
 
 export const render_template = ({
@@ -191,6 +204,13 @@ type ExecFn<TRow, TParam> = [TParam] extends [never]
           params: TParam & Record<string, unknown>,
       ) => Promise<Array<ApplyOverride<TSpec, TRow>>>;
 
+class BrandedSqlType<TDbType, TDbSource> {
+    protected __dbtype: TDbType;
+    protected __dbsource: TDbSource;
+}
+    
+type SqlType<T, TDbType, TDbSource> = T & BrandedSqlType<TDbType, TDbSource>;
+
 class Query<TRow, TParam> {
     public query;
     public params;
diff --git a/tests/sqlc.json b/tests/sqlc.json
@@ -2,6 +2,7 @@
   "include": "src/**/*.ts",
   "output": "src/sqlc.ts",
   "schema": "schema.sql",
+  "clear_tmp": true,
   "columns": {
     "customer.customer_id": "UUID"
   },
diff --git a/tests/src/index.ts b/tests/src/index.ts
@@ -4,7 +4,7 @@ const client = {
     query: (query: string, params: unknown[]) => Promise.resolve({ rows: [] }),
 };
 
-sqlc(/*sql*/ `
+const ss = await sqlc(/*sql*/ `
     SELECT
         first_name,
         last_name,
diff --git a/tests/src/sqlc.ts b/tests/src/sqlc.ts
@@ -30,6 +30,13 @@ type ExecFn<TRow, TParam> = [TParam] extends [never]
           params: TParam & Record<string, unknown>,
       ) => Promise<Array<ApplyOverride<TSpec, TRow>>>;
 
+class BrandedSqlType<TDbType, TDbSource> {
+    protected __dbtype: TDbType;
+    protected __dbsource: TDbSource;
+}
+
+type SqlType<T, TDbType, TDbSource> = T & BrandedSqlType<TDbType, TDbSource>;
+
 class Query<TRow, TParam> {
     public query;
     public params;
@@ -68,14 +75,14 @@ const queries = {
         customer_id = @customer_id
 `]: new Query<
         {
-            first_name: string;
-            last_name: string;
-            email: string | null;
-            address_id: number;
-            store_id: number;
-            activebool: boolean;
-            create_date: Date;
-            last_update: Date | null;
+            first_name: SqlType<string, 'text', 'customer.first_name'>;
+            last_name: SqlType<string, 'text', 'customer.last_name'>;
+            email: SqlType<string, 'text', 'customer.email'> | null;
+            address_id: SqlType<number, 'int4', 'customer.address_id'>;
+            store_id: SqlType<number, 'int4', 'customer.store_id'>;
+            activebool: SqlType<boolean, 'bool', 'customer.activebool'>;
+            create_date: SqlType<Date, 'date', 'customer.create_date'>;
+            last_update: SqlType<Date, 'timestamptz', 'customer.last_update'> | null;
         },
         { customer_id: UUID }
     >(
@@ -106,7 +113,13 @@ const queries = {
     WHERE
         title LIKE '%' || @film_title || '%';
 `]: new Query<
-        { film_id: number; title: string; description: string | null; release_year: unknown | null; rental_rate: number },
+        {
+            film_id: SqlType<number, 'int4', 'film.film_id'>;
+            title: SqlType<string, 'text', 'film.title'>;
+            description: SqlType<string, 'text', 'film.description'> | null;
+            release_year: SqlType<unknown, 'year', 'film.release_year'> | null;
+            rental_rate: SqlType<number, 'numeric', 'film.rental_rate'>;
+        },
         { film_title: string | null }
     >(
         `SELECT
@@ -137,7 +150,15 @@ const queries = {
         r.customer_id = @customer_id
     ORDER BY
         r.rental_date DESC;
-`]: new Query<{ rental_id: number; rental_date: Date; film_title: string; return_date: Date | null }, { customer_id: number }>(
+`]: new Query<
+        {
+            rental_id: SqlType<number, 'int4', 'rental.rental_id'>;
+            rental_date: SqlType<Date, 'timestamptz', 'rental.rental_date'>;
+            film_title: SqlType<string, 'text', 'film.title'>;
+            return_date: SqlType<Date, 'timestamptz', 'rental.return_date'> | null;
+        },
+        { customer_id: number }
+    >(
         `SELECT
         r.rental_id,
         r.rental_date,
@@ -165,7 +186,10 @@ const queries = {
         customer_id
     HAVING
         customer_id = @customer_id
-`]: new Query<{ customer_id: number; rental_count: number }, { customer_id: number }>(
+`]: new Query<
+        { customer_id: SqlType<number, 'int4', 'rental.customer_id'>; rental_count: SqlType<number, 'bigint', ''> },
+        { customer_id: number }
+    >(
         `SELECT
         customer_id,
         COUNT(*) AS rental_count
@@ -205,7 +229,13 @@ const queries = {
     ORDER BY
         total_revenue DESC
     LIMIT 5
-`]: new Query<{ category_name: string; total_revenue: number }, never>(
+`]: new Query<
+        {
+            category_name: SqlType<string, 'text', 'categoryrevenue.category_name'>;
+            total_revenue: SqlType<number, 'bigint', 'categoryrevenue.total_revenue'>;
+        },
+        never
+    >(
         `WITH CategoryRevenue AS (
         SELECT
             c.name AS category_name,

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"cSpell.words": [`
	`3`	`+ "dbsource",`
	`4`	`+ "dbtype",`
`3`	`5`	`"execrows",`
`4`	`6`	`"sqlc",`
`5`	`7`	`"tstype"`