feat: add exportTo option to write rendered SQL to file

Author: bug3

README.md

@@ -132,6 +132,17 @@ const query = defineQuery('./query.sql', {
 
 A type descriptor is any object with a `validate(val: unknown) => boolean` method.
 
+## Exporting Rendered SQL
+
+Pass an `exportTo` path to write the rendered SQL to disk for debugging or audit purposes. Missing parent directories are created automatically.
+
+```typescript
+const { sql } = getEvents(
+  { tableName: 'prod_events', status: 'active', startDate: '2022-02-22', orderBy: 'created_at', limit: 99 },
+  { exportTo: './debug/getEvents.sql' },
+);
+```
+
 ## SQL Injection Protection
 
 `schema.string` and the generic `string` type check values against built-in patterns:

ROADMAP.md

@@ -3,7 +3,7 @@
 ## v0.2
 
 - [ ] **Inline template support** - Allow passing SQL strings directly without requiring a `.sql` file, reducing boilerplate for short one-off queries
-- [ ] **Export rendered SQL to file** - Add an option to write the rendered SQL to a file for debugging and audit purposes
+- [x] **Export rendered SQL to file** - Add an option to write the rendered SQL to a file for debugging and audit purposes
 - [ ] **TypeDescriptor `description` field** - Add an optional `description` property to `TypeDescriptor` so schema validation errors can display the expected format (e.g. `Expected: ISO date YYYY-MM-DD`)
 
 ## Maybe

llms.txt

@@ -88,12 +88,20 @@ ORDER BY {{orderBy}}
 LIMIT {{limit}}
 ```
 
+### Exporting rendered SQL
+
+Pass `{ exportTo: string }` as the second argument to write the rendered SQL to disk. Missing parent directories are created recursively.
+
+```typescript
+const { sql } = getEvents(params, { exportTo: './debug/getEvents.sql' });
+```
+
 ### Exports
 
 - `defineQuery` - main function (overloaded for generic and schema modes)
 - `schema` - built-in schema type descriptors
 - `SQL_INJECTION_PATTERNS` - array of { name, regex } patterns used for injection detection
-- Types: `TypeDescriptor`, `SchemaDefinition`, `InferParams`, `QueryResult`, `GenericQueryFn`, `SchemaQueryFn`
+- Types: `TypeDescriptor`, `SchemaDefinition`, `InferParams`, `QueryResult`, `QueryOptions`, `GenericQueryFn`, `SchemaQueryFn`
 
 ## Key details
 

src/index.ts

@@ -1,16 +1,17 @@
 import { loadTemplate } from './loader';
 import { validateAndConvert, escapeValue } from './validator';
 import { render } from './renderer';
+import { writeRendered } from './writer';
 import type { SchemaDefinition } from './schema';
 import type {
-    QueryResult, GenericQueryFn, SchemaQueryFn,
+    QueryResult, QueryOptions, GenericQueryFn, SchemaQueryFn,
 } from './types';
 
 export { SQL_INJECTION_PATTERNS } from './validator';
 export { schema } from './schema';
 export type { TypeDescriptor, SchemaDefinition, InferParams } from './schema';
 export type {
-    QueryResult, GenericQueryFn, SchemaQueryFn,
+    QueryResult, QueryOptions, GenericQueryFn, SchemaQueryFn,
 } from './types';
 
 export function defineQuery<S extends SchemaDefinition>(
@@ -23,7 +24,7 @@ export function defineQuery<T extends Record<string, string | number | boolean>>
 export function defineQuery(
     filePath: string,
     schemaDef?: SchemaDefinition,
-): (params: Record<string, unknown>) => QueryResult {
+): (params: Record<string, unknown>, options?: QueryOptions) => QueryResult {
     const { template, tokens } = loadTemplate(filePath);
 
     if (schemaDef) {
@@ -53,7 +54,7 @@ export function defineQuery(
         }
     }
 
-    return (params) => {
+    return (params, options) => {
         const paramKeys = Object.keys(params);
 
         const missing = tokens.filter((tok) => !paramKeys.includes(tok));
@@ -87,6 +88,12 @@ export function defineQuery(
             }
         }
 
-        return { sql: render(template, values) };
+        const sql = render(template, values);
+
+        if (options?.exportTo) {
+            writeRendered(options.exportTo, sql);
+        }
+
+        return { sql };
     };
 }

src/types.ts

@@ -4,6 +4,13 @@ export interface QueryResult {
     sql: string;
 }
 
-export type GenericQueryFn<T> = (params: T) => QueryResult;
+export interface QueryOptions {
+    exportTo?: string;
+}
+
+export type GenericQueryFn<T> = (params: T, options?: QueryOptions) => QueryResult;
 
-export type SchemaQueryFn<S extends SchemaDefinition> = (params: InferParams<S>) => QueryResult;
+export type SchemaQueryFn<S extends SchemaDefinition> = (
+    params: InferParams<S>,
+    options?: QueryOptions,
+) => QueryResult;

src/writer.ts

@@ -0,0 +1,8 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function writeRendered(filePath: string, sql: string): void {
+    const resolved = path.resolve(filePath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, sql, 'utf-8');
+}

tests/define-query.test.ts

@@ -1,5 +1,7 @@
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { defineQuery, schema } from '../src/index';
 
 const fixture = (name: string) => path.join(__dirname, 'fixtures', name);
@@ -240,6 +242,54 @@ describe('defineQuery — schema mode', () => {
         });
     });
 
+    describe('exportTo option', () => {
+        let tmpDir: string;
+
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'sql-render-'));
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it('writes rendered sql to the given file', () => {
+            const query = defineQuery(fixture('simple.sql'), {
+                table: schema.identifier,
+                id: schema.number,
+            });
+            const outPath = path.join(tmpDir, 'rendered.sql');
+            const { sql } = query({ table: 'users', id: 33 }, { exportTo: outPath });
+            expect(fs.readFileSync(outPath, 'utf-8')).toBe(sql);
+        });
+
+        it('creates parent directories recursively', () => {
+            const query = defineQuery(fixture('simple.sql'), {
+                table: schema.identifier,
+                id: schema.number,
+            });
+            const outPath = path.join(tmpDir, 'nested', 'deep', 'out.sql');
+            query({ table: 'users', id: 1 }, { exportTo: outPath });
+            expect(fs.existsSync(outPath)).toBe(true);
+        });
+
+        it('does not write a file when exportTo is omitted', () => {
+            const query = defineQuery(fixture('simple.sql'), {
+                table: schema.identifier,
+                id: schema.number,
+            });
+            query({ table: 'users', id: 1 });
+            expect(fs.readdirSync(tmpDir)).toHaveLength(0);
+        });
+
+        it('works in generic mode', () => {
+            const query = defineQuery<{ table: string; id: number }>(fixture('simple.sql'));
+            const outPath = path.join(tmpDir, 'generic.sql');
+            const { sql } = query({ table: 'users', id: 7 }, { exportTo: outPath });
+            expect(fs.readFileSync(outPath, 'utf-8')).toBe(sql);
+        });
+    });
+
     describe('custom schema types', () => {
         it('accepts a custom type descriptor', () => {
             const prodTable = {