@danielfgray/pg-sourcerer 0.2.0 → 0.2.2

package/dist/plugins/sql-queries.js

@@ -1,24 +1,65 @@
 /**
- * SQL Queries Plugin - Generate raw SQL query functions using template strings
+ * SQL Queries Provider - Generate raw SQL query functions using template strings
  */
 import { Schema as S } from "effect";
 import { definePlugin } from "../services/plugin.js";
-import { getTableEntities, getEnumEntities } from "../ir/semantic-ir.js";
+import { getTableEntities, getEnumEntities, getFunctionEntities, getCompositeEntities, } from "../ir/semantic-ir.js";
 import { conjure } from "../lib/conjure.js";
 import { hex } from "../lib/hex.js";
 import { resolveFieldType, tsTypeToAst } from "../lib/field-utils.js";
 import { inflect } from "../services/inflection.js";
-const { ts, b, param } = conjure;
-// ============================================================================
-// Configuration
-// ============================================================================
-const SqlQueriesPluginConfig = S.Struct({
+const { ts, b, param, asyncFn } = conjure;
+/** Default export name: camelCase of methodName + entityName (e.g., "findUserById") */
+const defaultExportName = (entityName, methodName) => {
+    // methodName is like "FindById", "Insert", "GetByUsername"
+    // We want: findUserById, insertUser, getUserByUsername
+    const camelMethod = methodName.charAt(0).toLowerCase() + methodName.slice(1);
+    // Insert entity name after the verb (find, insert, get, delete)
+    // Pattern: verb + Entity + rest (e.g., find + User + ById)
+    const verbMatch = camelMethod.match(/^(find|insert|delete|get)(.*)$/);
+    if (verbMatch) {
+        const [, verb, rest] = verbMatch;
+        return `${verb}${entityName}${rest}`;
+    }
+    // Fallback: just prepend entity
+    return `${camelMethod}${entityName}`;
+};
+const SqlQueriesPluginConfigSchema = S.Struct({
     outputDir: S.optionalWith(S.String, { default: () => "sql-queries" }),
+    /**
+     * Header content to prepend to each generated file.
+     * Must include the SQL client import (e.g., `import { sql } from "../db"`).
+     */
+    header: S.String,
     /** SQL query style. Defaults to "tag" (tagged template literals) */
-    sqlStyle: S.optionalWith(S.Union(S.Literal("tag"), S.Literal("string")), { default: () => "tag" }),
+    sqlStyle: S.optionalWith(S.Union(S.Literal("tag"), S.Literal("string")), {
+        default: () => "tag",
+    }),
+    /**
+     * Use explicit column lists instead of SELECT *.
+     * When true, generates "SELECT col1, col2" which excludes omitted fields at runtime.
+     * Defaults to true.
+     */
+    explicitColumns: S.optionalWith(S.Boolean, { default: () => true }),
+    /** Generate wrappers for PostgreSQL functions. Defaults to true. */
+    generateFunctions: S.optionalWith(S.Boolean, { default: () => true }),
+    /** Output file for scalar-returning functions. Defaults to "functions.ts". */
+    functionsFile: S.optionalWith(S.String, { default: () => "functions.ts" }),
+    /** Export name function - use S.Any for schema, properly typed after resolution */
+    exportName: S.optional(S.Any),
+    /**
+     * Export style for generated query functions.
+     * - "flat": Individual exports (e.g., `export async function findById() {...}`)
+     * - "namespace": Single object export (e.g., `export const User = { findById: ... }`)
+     */
+    exportStyle: S.optionalWith(S.Literal("flat", "namespace"), { default: () => "flat" }),
 });
 /** Find a field in the row shape by column name */
 const findRowField = (entity, columnName) => entity.shapes.row.fields.find(f => f.columnName === columnName);
+/** Build comma-separated column list from row shape fields */
+const buildColumnList = (entity) => entity.shapes.row.fields.map(f => f.columnName).join(", ");
+/** Build SELECT clause - explicit columns or * based on config */
+const buildSelectClause = (entity, explicitColumns) => explicitColumns ? `select ${buildColumnList(entity)}` : "select *";
 /** Get the TypeScript type AST for a field */
 const getFieldTypeAst = (field, ctx) => {
     if (!field)
@@ -67,9 +108,16 @@ const toPascalCase = (s) => inflect.pascalCase(s);
 // ============================================================================
 // CRUD Function Generators
 // ============================================================================
-/** Generate findById function if entity has a primary key and canSelect permission */
+/** Get TypeScript type string for a field */
+const getFieldTypeString = (field, ctx) => {
+    if (!field)
+        return "string";
+    const resolved = resolveFieldType(field, ctx.enums, ctx.ir.extensions);
+    return resolved.enumDef ? resolved.enumDef.name : resolved.tsType;
+};
+/** Generate findById method if entity has a primary key and canSelect permission */
 const generateFindById = (ctx) => {
-    const { entity, sqlStyle } = ctx;
+    const { entity, sqlStyle, entityName, exportName, explicitColumns } = ctx;
     if (!entity.primaryKey || !entity.permissions.canSelect)
         return undefined;
     const pkColName = entity.primaryKey.columns[0];
@@ -78,38 +126,73 @@ const generateFindById = (ctx) => {
         return undefined;
     const rowType = entity.shapes.row.name;
     const fieldName = pkField.name; // JS property name (e.g., "id")
+    const selectClause = buildSelectClause(entity, explicitColumns);
     const parts = {
-        templateParts: [`select * from ${entity.schemaName}.${entity.pgName} where ${pkColName} = `, ""],
+        templateParts: [
+            `${selectClause} from ${entity.schemaName}.${entity.pgName} where ${pkColName} = `,
+            "",
+        ],
         params: [b.identifier(fieldName)],
     };
     // Build query and extract first row
     const queryExpr = hex.query(sqlStyle, parts, ts.array(ts.ref(rowType)));
     const varDecl = hex.firstRowDecl(sqlStyle, "result", queryExpr);
-    return hex.exportFn(hex.asyncFn(`find${entity.name}ById`, [param.pick([fieldName], rowType)], [
-        varDecl,
-        b.returnStatement(b.identifier("result")),
-    ]));
+    const name = exportName(entityName, "FindById");
+    const fn = asyncFn(name, [param.pick([fieldName], rowType)], [varDecl, b.returnStatement(b.identifier("result"))]);
+    const meta = {
+        name,
+        kind: "read",
+        params: [
+            {
+                name: fieldName,
+                type: getFieldTypeString(pkField, ctx),
+                required: true,
+                columnName: pkColName,
+                source: "pk",
+            },
+        ],
+        returns: { type: rowType, nullable: true, isArray: false },
+        callSignature: { style: "named" },
+    };
+    return { name, fn, meta };
 };
-/** Generate findMany function with pagination if entity has canSelect permission */
+/** Generate findMany method with pagination if entity has canSelect permission */
 const generateFindMany = (ctx) => {
-    const { entity, sqlStyle } = ctx;
+    const { entity, sqlStyle, entityName, exportName, explicitColumns } = ctx;
     if (!entity.permissions.canSelect)
         return undefined;
     const rowType = entity.shapes.row.name;
+    const selectClause = buildSelectClause(entity, explicitColumns);
     const parts = {
-        templateParts: [`select * from ${entity.schemaName}.${entity.pgName} limit `, ` offset `, ""],
+        templateParts: [
+            `${selectClause} from ${entity.schemaName}.${entity.pgName} limit `,
+            ` offset `,
+            "",
+        ],
         params: [b.identifier("limit"), b.identifier("offset")],
     };
-    return hex.exportFn(hex.asyncFn(`findMany${entity.name}s`, [
+    const name = exportName(entityName, "FindManys");
+    const fn = asyncFn(name, [
         param.destructured([
             { name: "limit", type: ts.number(), optional: true, defaultValue: b.numericLiteral(50) },
             { name: "offset", type: ts.number(), optional: true, defaultValue: b.numericLiteral(0) },
         ]),
-    ], hex.returnQuery(sqlStyle, parts, ts.array(ts.ref(rowType)))));
+    ], hex.returnQuery(sqlStyle, parts, ts.array(ts.ref(rowType))));
+    const meta = {
+        name,
+        kind: "list",
+        params: [
+            { name: "limit", type: "number", required: false, source: "pagination" },
+            { name: "offset", type: "number", required: false, source: "pagination" },
+        ],
+        returns: { type: rowType, nullable: false, isArray: true },
+        callSignature: { style: "named" },
+    };
+    return { name, fn, meta };
 };
-/** Generate delete function if entity has a primary key and canDelete permission */
+/** Generate delete method if entity has a primary key and canDelete permission */
 const generateDelete = (ctx) => {
-    const { entity, sqlStyle } = ctx;
+    const { entity, sqlStyle, entityName, exportName } = ctx;
     if (!entity.primaryKey || !entity.permissions.canDelete)
         return undefined;
     const pkColName = entity.primaryKey.columns[0];
@@ -124,13 +207,28 @@ const generateDelete = (ctx) => {
     };
     // Delete returns void, no type parameter needed
     const queryExpr = hex.query(sqlStyle, parts);
-    return hex.exportFn(hex.asyncFn(`delete${entity.name}`, [param.pick([fieldName], rowType)], [
-        b.expressionStatement(queryExpr),
-    ]));
+    const name = exportName(entityName, "Delete");
+    const fn = asyncFn(name, [param.pick([fieldName], rowType)], [b.expressionStatement(queryExpr)]);
+    const meta = {
+        name,
+        kind: "delete",
+        params: [
+            {
+                name: fieldName,
+                type: getFieldTypeString(pkField, ctx),
+                required: true,
+                columnName: pkColName,
+                source: "pk",
+            },
+        ],
+        returns: { type: "void", nullable: false, isArray: false },
+        callSignature: { style: "named" },
+    };
+    return { name, fn, meta };
 };
-/** Generate insert function if entity has canInsert permission */
+/** Generate insert method if entity has canInsert permission */
 const generateInsert = (ctx) => {
-    const { entity, sqlStyle } = ctx;
+    const { entity, sqlStyle, entityName, exportName } = ctx;
     if (!entity.permissions.canInsert)
         return undefined;
     // Use insert shape if available, otherwise fall back to row
@@ -142,10 +240,15 @@ const generateInsert = (ctx) => {
     if (insertableFields.length === 0)
         return undefined;
     const columnNames = insertableFields.map(f => f.columnName);
-    const fieldNames = insertableFields.map(f => f.name);
-    // Build: insert into schema.table (col1, col2) values ($data.field1, $data.field2) returning *
+    // Build: insert into schema.table (col1, col2) values ($field1, $field2) returning *
     const columnList = columnNames.join(", ");
-    const valuePlaceholders = fieldNames.map((_, i) => (i === 0 ? "" : ", "));
+    const valuePlaceholders = insertableFields.map((_, i) => (i === 0 ? "" : ", "));
+    // For optional fields (nullable or has default), use DEFAULT when undefined
+    // Required fields use the value directly
+    const paramExprs = insertableFields.map(f => {
+        const isOptional = f.optional || f.nullable;
+        return isOptional ? hex.defaultIfUndefined(f.name) : b.identifier(f.name);
+    });
     // Template parts: "insert into ... values (" + "" + ", " + ", " + ... + ") returning *"
     const parts = {
         templateParts: [
@@ -153,21 +256,33 @@ const generateInsert = (ctx) => {
             ...valuePlaceholders.slice(1),
             `) returning *`,
         ],
-        params: fieldNames.map(f => b.memberExpression(b.identifier("data"), b.identifier(f), false)),
+        params: paramExprs,
     };
     const queryExpr = hex.query(sqlStyle, parts, ts.array(ts.ref(rowType)));
     const varDecl = hex.firstRowDecl(sqlStyle, "result", queryExpr);
-    // Simple typed parameter: data: InsertType
-    const dataParam = param.typed("data", ts.ref(insertType));
-    return hex.exportFn(hex.asyncFn(`insert${entity.name}`, [dataParam], [varDecl, b.returnStatement(b.identifier("result"))]));
+    // Destructured parameter - use Pick from insert type
+    const fieldNames = insertableFields.map(f => f.name);
+    const dataParam = param.pick(fieldNames, insertType);
+    const name = exportName(entityName, "Insert");
+    const fn = asyncFn(name, [dataParam], [varDecl, b.returnStatement(b.identifier("result"))]);
+    const meta = {
+        name,
+        kind: "create",
+        params: [
+            {
+                name: "data",
+                type: insertType,
+                required: true,
+                source: "body",
+            },
+        ],
+        returns: { type: rowType, nullable: false, isArray: false },
+        callSignature: { style: "named", bodyStyle: "spread" },
+    };
+    return { name, fn, meta };
 };
-/** Generate all CRUD functions for an entity */
-const generateCrudFunctions = (ctx) => [
-    generateFindById(ctx),
-    generateFindMany(ctx),
-    generateInsert(ctx),
-    generateDelete(ctx),
-].filter((s) => s != null);
+/** Generate all CRUD methods for an entity */
+const generateCrudMethods = (ctx) => [generateFindById(ctx), generateFindMany(ctx), generateInsert(ctx), generateDelete(ctx)].filter((m) => m != null);
 // ============================================================================
 // Index-based Lookup Functions
 // ============================================================================
@@ -178,27 +293,22 @@ const shouldGenerateLookup = (index) => !index.isPartial &&
     index.method !== "gin" &&
     index.method !== "gist";
 /**
- * Generate a function name for an index-based lookup.
- * Uses semantic naming when the column corresponds to an FK relation.
+ * Generate the method name portion for an index-based lookup.
+ * Returns PascalCase like "GetByUsername" or "GetsByUser" for use with exportName.
  */
-const generateLookupName = (entity, index, relation) => {
+const generateLookupMethodName = (index, relation, columnName) => {
     const isUnique = index.isUnique || index.isPrimary;
-    const entityName = isUnique
-        ? entity.name.replace(/s$/, "") // singular for unique
-        : entity.name.replace(/s$/, "") + "s"; // plural for non-unique
+    const prefix = isUnique ? "GetBy" : "GetsBy";
     // Use semantic name if FK relation exists, otherwise fall back to column name
-    const columnName = index.columnNames[0];
-    const byName = relation
-        ? deriveSemanticName(relation, columnName)
-        : index.columns[0];
-    return `get${entityName}By${toPascalCase(byName)}`;
+    const byName = relation ? deriveSemanticName(relation, columnName) : index.columns[0];
+    return `${prefix}${toPascalCase(byName)}`;
 };
 /**
- * Generate a lookup function for a single-column index.
+ * Generate a lookup method for a single-column index.
  * Uses semantic parameter naming when the column corresponds to an FK relation.
  */
-const generateLookupFunction = (index, ctx) => {
-    const { entity, sqlStyle } = ctx;
+const generateLookupMethod = (index, ctx) => {
+    const { entity, sqlStyle, entityName, exportName, explicitColumns } = ctx;
     const rowType = entity.shapes.row.name;
     const columnName = index.columnNames[0];
     const field = findRowField(entity, columnName);
@@ -207,105 +317,621 @@ const generateLookupFunction = (index, ctx) => {
     // Check if this index column corresponds to an FK relation
     const relation = findRelationForColumn(entity, columnName);
     // Use semantic param name if FK relation exists, otherwise use field name
-    const paramName = relation
-        ? deriveSemanticName(relation, columnName)
-        : fieldName;
+    const paramName = relation ? deriveSemanticName(relation, columnName) : fieldName;
     // For semantic naming, use indexed access type (Post["userId"])
     // For regular naming, use Pick<Post, "fieldName">
     const useSemanticNaming = relation !== undefined && paramName !== fieldName;
+    const selectClause = buildSelectClause(entity, explicitColumns);
     const parts = {
-        templateParts: [`select * from ${entity.schemaName}.${entity.pgName} where ${columnName} = `, ""],
+        templateParts: [
+            `${selectClause} from ${entity.schemaName}.${entity.pgName} where ${columnName} = `,
+            "",
+        ],
         params: [b.identifier(paramName)],
     };
-    const fnName = generateLookupName(entity, index, relation);
-    // Build the parameter - use indexed access type for semantic naming
-    const paramNode = useSemanticNaming
-        ? param.typed(paramName, ts.indexedAccess(ts.ref(rowType), ts.literal(fieldName)))
-        : param.pick([fieldName], rowType);
+    const methodName = generateLookupMethodName(index, relation, columnName);
+    const name = exportName(entityName, methodName);
+    // Build the parameter - use destructured style for both cases
+    // Lookup params must be non-nullable (you're searching FOR a value, not handling null)
+    // Semantic naming: { user }: { user: NonNullable<Post["user_id"]> }
+    // Regular naming: { fieldName }: { fieldName: NonNullable<Post["fieldName"]> }
+    const indexedType = ts.indexedAccess(ts.ref(rowType), ts.literal(fieldName));
+    const paramType = ts.ref("NonNullable", [indexedType]);
+    const paramNode = param.destructured([{ name: paramName, type: paramType }]);
+    // Build metadata for the lookup method
+    const meta = {
+        name,
+        kind: "lookup",
+        params: [
+            {
+                name: paramName,
+                type: getFieldTypeString(field, ctx),
+                required: true,
+                columnName,
+                source: relation ? "fk" : "lookup",
+            },
+        ],
+        returns: {
+            type: rowType,
+            nullable: isUnique,
+            isArray: !isUnique,
+        },
+        lookupField: fieldName,
+        isUniqueLookup: isUnique,
+        callSignature: { style: "named" },
+    };
     if (isUnique) {
         // Extract first row for unique lookups
         const queryExpr = hex.query(sqlStyle, parts, ts.array(ts.ref(rowType)));
         const varDecl = hex.firstRowDecl(sqlStyle, "result", queryExpr);
-        return hex.exportFn(hex.asyncFn(fnName, [paramNode], [
-            varDecl,
-            b.returnStatement(b.identifier("result")),
-        ]));
+        const fn = asyncFn(name, [paramNode], [varDecl, b.returnStatement(b.identifier("result"))]);
+        return { name, fn, meta };
     }
     // Non-unique: return all matching rows
-    return hex.exportFn(hex.asyncFn(fnName, [paramNode], hex.returnQuery(sqlStyle, parts, ts.array(ts.ref(rowType)))));
+    const fn = asyncFn(name, [paramNode], hex.returnQuery(sqlStyle, parts, ts.array(ts.ref(rowType))));
+    return { name, fn, meta };
 };
-/** Generate lookup functions for all eligible indexes, deduplicating by name */
-const generateLookupFunctions = (ctx) => {
+/** Generate lookup methods for all eligible indexes, deduplicating by name */
+const generateLookupMethods = (ctx) => {
     const seen = new Set();
     return ctx.entity.indexes
         .filter(index => shouldGenerateLookup(index) && !index.isPrimary)
         .filter(index => {
         const columnName = index.columnNames[0];
         const relation = findRelationForColumn(ctx.entity, columnName);
-        const name = generateLookupName(ctx.entity, index, relation);
+        const methodName = generateLookupMethodName(index, relation, columnName);
+        const name = ctx.exportName(ctx.entityName, methodName);
         if (seen.has(name))
             return false;
         seen.add(name);
         return true;
     })
-        .map(index => generateLookupFunction(index, ctx));
+        .map(index => generateLookupMethod(index, ctx));
 };
 // ============================================================================
-// Plugin Definition
+// Function Wrapper Generation
 // ============================================================================
-export const sqlQueriesPlugin = definePlugin({
-    name: "sql-queries",
-    provides: ["queries", "queries:sql"],
-    requires: ["types"],
-    configSchema: SqlQueriesPluginConfig,
-    inflection: {
-        outputFile: ctx => `${ctx.entityName}.ts`,
-        symbolName: (entityName, artifactKind) => `${entityName}${artifactKind}`,
-    },
-    run: (ctx, config) => {
-        const enums = getEnumEntities(ctx.ir);
-        const { sqlStyle } = config;
-        getTableEntities(ctx.ir)
-            .filter(entity => entity.tags.omit !== true)
-            .forEach(entity => {
-            const genCtx = { entity, enums, ir: ctx.ir, sqlStyle };
-            const statements = [...generateCrudFunctions(genCtx), ...generateLookupFunctions(genCtx)];
-            if (statements.length === 0)
-                return;
-            const entityName = ctx.inflection.entityName(entity.pgClass, entity.tags);
-            const fileNameCtx = {
-                entityName,
-                pgName: entity.pgName,
-                schema: entity.schemaName,
-                inflection: ctx.inflection,
-                entity,
-            };
-            const filePath = `${config.outputDir}/${ctx.pluginInflection.outputFile(fileNameCtx)}`;
-            const file = ctx.file(filePath);
-            // Import the appropriate SQL client based on style
-            if (sqlStyle === "tag") {
-                file.import({ kind: "relative", names: ["sql"], from: "../db" });
+/**
+ * Map PostgreSQL type names to TypeScript types.
+ * Simplified version - covers common scalar types.
+ */
+const pgTypeNameToTs = (typeName) => {
+    const typeMap = {
+        // Numeric
+        int2: "number",
+        int4: "number",
+        int8: "string", // bigint as string
+        float4: "number",
+        float8: "number",
+        numeric: "string",
+        decimal: "string",
+        // Text
+        text: "string",
+        varchar: "string",
+        char: "string",
+        citext: "string",
+        name: "string",
+        // Boolean
+        bool: "boolean",
+        // Date/time
+        date: "Date",
+        timestamp: "Date",
+        timestamptz: "Date",
+        time: "string",
+        timetz: "string",
+        interval: "string",
+        // UUID
+        uuid: "string",
+        // JSON
+        json: "unknown",
+        jsonb: "unknown",
+        // Binary
+        bytea: "Buffer",
+        // Other
+        void: "void",
+    };
+    return typeMap[typeName] ?? "unknown";
+};
+/**
+ * Check if a function argument has a row type (composite type matching a table).
+ * Functions with row-type arguments are computed fields, not standalone functions.
+ */
+const hasRowTypeArg = (arg, ir) => {
+    const tables = getTableEntities(ir);
+    return tables.some(t => {
+        const qualifiedName = `${t.schemaName}.${t.pgName}`;
+        return arg.typeName === qualifiedName || arg.typeName === t.pgName;
+    });
+};
+/**
+ * Check if a function can be wrapped (not a trigger, computed field, etc.)
+ */
+const isGeneratableFunction = (fn, ir) => {
+    if (!fn.canExecute)
+        return false;
+    if (fn.returnTypeName === "trigger")
+        return false;
+    if (fn.isFromExtension)
+        return false;
+    if (fn.tags.omit === true)
+        return false;
+    // Filter out computed field functions (have row-type args)
+    if (fn.args.some(arg => hasRowTypeArg(arg, ir)))
+        return false;
+    return true;
+};
+/**
+ * Categorize functions by volatility.
+ * Volatile functions go in mutations namespace, stable/immutable in queries.
+ */
+const categorizeFunction = (fn) => fn.volatility === "volatile" ? "mutations" : "queries";
+/**
+ * Get all generatable functions from the IR, categorized by volatility.
+ */
+const getGeneratableFunctions = (ir) => {
+    const all = getFunctionEntities(ir).filter(fn => isGeneratableFunction(fn, ir));
+    return {
+        queries: all.filter(fn => categorizeFunction(fn) === "queries"),
+        mutations: all.filter(fn => categorizeFunction(fn) === "mutations"),
+    };
+};
+/**
+ * Resolve a function's return type to TypeScript type information.
+ */
+const resolveReturnType = (fn, ir) => {
+    const returnTypeName = fn.returnTypeName;
+    const isArray = fn.returnsSet;
+    // 1. Check if it's a table return type
+    const tableEntities = getTableEntities(ir);
+    const tableMatch = tableEntities.find(entity => {
+        const qualifiedName = `${entity.schemaName}.${entity.pgName}`;
+        return returnTypeName === qualifiedName || returnTypeName === entity.pgName;
+    });
+    if (tableMatch) {
+        return {
+            tsType: tableMatch.name,
+            isArray,
+            isScalar: false,
+            needsImport: tableMatch.name,
+            returnEntity: tableMatch,
+        };
+    }
+    // 2. Check if it's a composite type return
+    const compositeEntities = getCompositeEntities(ir);
+    const compositeMatch = compositeEntities.find(entity => {
+        const qualifiedName = `${entity.schemaName}.${entity.pgName}`;
+        return returnTypeName === qualifiedName || returnTypeName === entity.pgName;
+    });
+    if (compositeMatch) {
+        return {
+            tsType: compositeMatch.name,
+            isArray,
+            isScalar: false,
+            needsImport: compositeMatch.name,
+            returnEntity: compositeMatch,
+        };
+    }
+    // 3. It's a scalar type - map via type name
+    const baseTypeName = returnTypeName.includes(".")
+        ? returnTypeName.split(".").pop()
+        : returnTypeName;
+    const tsType = pgTypeNameToTs(baseTypeName);
+    return {
+        tsType,
+        isArray,
+        isScalar: true,
+    };
+};
+/**
+ * Resolve a function argument to TypeScript type information.
+ */
+const resolveArg = (arg, ir) => {
+    const typeName = arg.typeName;
+    // Check if it's an array type (ends with [])
+    const isArrayType = typeName.endsWith("[]");
+    const baseTypeName = isArrayType ? typeName.slice(0, -2) : typeName;
+    // Check enums
+    const enums = getEnumEntities(ir);
+    const enumMatch = enums.find(e => {
+        const qualifiedName = `${e.schemaName}.${e.pgName}`;
+        return baseTypeName === qualifiedName || baseTypeName === e.pgName;
+    });
+    if (enumMatch) {
+        const tsType = isArrayType ? `${enumMatch.name}[]` : enumMatch.name;
+        return {
+            name: arg.name || "arg",
+            tsType,
+            isOptional: arg.hasDefault,
+            needsImport: enumMatch.name,
+        };
+    }
+    // Check composites
+    const composites = getCompositeEntities(ir);
+    const compositeMatch = composites.find(e => {
+        const qualifiedName = `${e.schemaName}.${e.pgName}`;
+        return baseTypeName === qualifiedName || baseTypeName === e.pgName;
+    });
+    if (compositeMatch) {
+        const tsType = isArrayType ? `${compositeMatch.name}[]` : compositeMatch.name;
+        return {
+            name: arg.name || "arg",
+            tsType,
+            isOptional: arg.hasDefault,
+            needsImport: compositeMatch.name,
+        };
+    }
+    // Scalar type - map via type name
+    const scalarBase = baseTypeName.includes(".") ? baseTypeName.split(".").pop() : baseTypeName;
+    const scalarTs = pgTypeNameToTs(scalarBase);
+    const tsType = isArrayType ? `${scalarTs}[]` : scalarTs;
+    return {
+        name: arg.name || "arg",
+        tsType,
+        isOptional: arg.hasDefault,
+    };
+};
+/**
+ * Resolve all arguments for a function.
+ */
+const resolveArgs = (fn, ir) => fn.args.map(arg => resolveArg(arg, ir));
+/**
+ * Get the fully qualified function name for SQL.
+ */
+const getFunctionQualifiedName = (fn) => `${fn.schemaName}.${fn.pgName}`;
+/**
+ * Generate a function wrapper for a PostgreSQL function.
+ *
+ * Patterns:
+ * - SETOF/table return: select * from schema.fn(args)
+ * - Single row return: select * from schema.fn(args) (same SQL, single result)
+ * - Scalar return: select schema.fn(args)
+ */
+const generateFunctionWrapper = (fn, ir, sqlStyle) => {
+    const resolvedReturn = resolveReturnType(fn, ir);
+    const resolvedArgs = resolveArgs(fn, ir);
+    const qualifiedName = getFunctionQualifiedName(fn);
+    // Use fn.name which is already inflected by the IR builder
+    const name = fn.name;
+    // Helper to convert resolved type string to AST
+    const typeStrToAst = (typeStr) => {
+        if (typeStr.endsWith("[]")) {
+            const elemType = typeStr.slice(0, -2);
+            return ts.array(typeStrToAst(elemType));
+        }
+        switch (typeStr) {
+            case "string":
+                return ts.string();
+            case "number":
+                return ts.number();
+            case "boolean":
+                return ts.boolean();
+            case "void":
+                return ts.void();
+            case "unknown":
+                return ts.unknown();
+            case "Date":
+                return ts.ref("Date");
+            case "Buffer":
+                return ts.ref("Buffer");
+            default:
+                return ts.ref(typeStr);
+        }
+    };
+    // Build parameter: destructured object for named style (zero-arg functions have no params)
+    const params = resolvedArgs.length === 0
+        ? []
+        : [
+            param.destructured(resolvedArgs.map(arg => ({
+                name: arg.name,
+                type: typeStrToAst(arg.tsType),
+                optional: arg.isOptional,
+            }))),
+        ];
+    // Build SQL based on return type
+    let sql;
+    let resultType;
+    if (resolvedReturn.isScalar) {
+        // Scalar: select schema.fn(args)
+        const argPlaceholders = resolvedArgs.map((_, i) => `$${i + 1}`).join(", ");
+        sql = `select ${qualifiedName}(${argPlaceholders})`;
+        // Return type is a record with the function name as key
+        resultType = ts.array(ts.ref("Record", [ts.string(), typeStrToAst(resolvedReturn.tsType)]));
+    }
+    else {
+        // Table/composite: select * from schema.fn(args)
+        const argPlaceholders = resolvedArgs.map((_, i) => `$${i + 1}`).join(", ");
+        sql = `select * from ${qualifiedName}(${argPlaceholders})`;
+        resultType = ts.array(ts.ref(resolvedReturn.tsType));
+    }
+    const paramExprs = resolvedArgs.map(arg => b.identifier(arg.name));
+    // Build template parts by splitting on $N placeholders
+    let templateParts = sql.split(/\$\d+/);
+    // For zero-arg functions, template is just the SQL string
+    if (resolvedArgs.length === 0) {
+        templateParts = [sql];
+    }
+    const parts = {
+        templateParts,
+        params: paramExprs,
+    };
+    // Build the function body
+    let body;
+    if (resolvedReturn.isScalar) {
+        // Scalar: extract the result from the first row's first column
+        const queryExpr = hex.query(sqlStyle, parts, resultType);
+        const varDecl = hex.firstRowDecl(sqlStyle, "row", queryExpr);
+        // Use optional chaining: row?.[fn.pgName]
+        const optionalReturn = b.optionalMemberExpression(b.identifier("row"), b.identifier(fn.pgName), false, true);
+        body = [varDecl, b.returnStatement(optionalReturn)];
+    }
+    else if (resolvedReturn.isArray) {
+        // SETOF: return all rows
+        body = hex.returnQuery(sqlStyle, parts, resultType);
+    }
+    else {
+        // Single row: extract first row
+        const queryExpr = hex.query(sqlStyle, parts, resultType);
+        const varDecl = hex.firstRowDecl(sqlStyle, "result", queryExpr);
+        body = [varDecl, b.returnStatement(b.identifier("result"))];
+    }
+    const fnDecl = asyncFn(name, params, body);
+    // Build metadata for the function wrapper
+    const meta = {
+        name,
+        kind: "function",
+        params: resolvedArgs.map(arg => ({
+            name: arg.name,
+            type: arg.tsType,
+            required: !arg.isOptional,
+        })),
+        returns: {
+            type: resolvedReturn.tsType,
+            nullable: resolvedReturn.isScalar || !resolvedReturn.isArray, // Scalars and single rows can be null
+            isArray: resolvedReturn.isArray,
+        },
+        callSignature: { style: "named" },
+    };
+    return { name, fn: fnDecl, meta };
+};
+/**
+ * Collect type imports needed for function wrappers.
+ */
+const collectFunctionTypeImports = (functions, ir) => {
+    const imports = new Set();
+    for (const fn of functions) {
+        const resolvedReturn = resolveReturnType(fn, ir);
+        if (resolvedReturn.needsImport) {
+            imports.add(resolvedReturn.needsImport);
+        }
+        for (const arg of resolveArgs(fn, ir)) {
+            if (arg.needsImport) {
+                imports.add(arg.needsImport);
             }
-            else {
-                file.import({ kind: "relative", names: ["pool"], from: "../db" });
+        }
+    }
+    return imports;
+};
+// ============================================================================
+// Export Style Helpers
+// ============================================================================
+/**
+ * Convert MethodDef array to flat export statements.
+ * Each method becomes: export function methodName(...) { ... }
+ */
+const toFlatExports = (methods) => methods.map(m => conjure.export.fn(m.fn));
+/**
+ * Convert a FunctionDeclaration to a FunctionExpression for object property use.
+ */
+const fnDeclToExpr = (fn) => {
+    const expr = b.functionExpression(null, fn.params, fn.body);
+    expr.async = fn.async;
+    expr.generator = fn.generator;
+    return expr;
+};
+/**
+ * Convert MethodDef array to a single namespace object export.
+ * All methods become: export const EntityName = { methodName: async function(...) { ... }, ... }
+ */
+const toNamespaceExport = (entityName, methods) => {
+    const properties = methods.map(m => b.objectProperty(b.identifier(m.name), fnDeclToExpr(m.fn)));
+    const obj = b.objectExpression(properties);
+    return conjure.export.const(entityName, obj);
+};
+/**
+ * Convert MethodDef array to statements based on export style.
+ */
+const toStatements = (methods, exportStyle, entityName) => {
+    if (methods.length === 0)
+        return [];
+    return exportStyle === "namespace"
+        ? [toNamespaceExport(entityName, methods)]
+        : toFlatExports(methods);
+};
+/**
+ * Create a SQL queries provider that generates raw SQL query functions.
+ *
+ * @example
+ * ```typescript
+ * import { sqlQueries } from "pg-sourcerer"
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     types(),
+ *     sqlQueries({ header: 'import { sql } from "../db"' }),
+ *   ],
+ * })
+ * ```
+ */
+export function sqlQueries(config) {
+    const parsed = S.decodeUnknownSync(SqlQueriesPluginConfigSchema)(config);
+    // Resolve config with properly typed exportName
+    const resolvedConfig = {
+        ...parsed,
+        exportName: config.exportName ?? defaultExportName,
+    };
+    return definePlugin({
+        name: "sql-queries",
+        kind: "queries",
+        singleton: true,
+        canProvide: () => true,
+        provide: (_params, _deps, ctx) => {
+            const { ir, inflection } = ctx;
+            const enums = getEnumEntities(ir);
+            const { sqlStyle, generateFunctions, exportName, exportStyle, outputDir, header, functionsFile, explicitColumns, } = resolvedConfig;
+            // Pre-compute function groupings by return entity name
+            // Functions returning entities go in that entity's file; scalars go in functions.ts
+            const functionsByEntity = new Map();
+            const scalarFunctions = [];
+            if (generateFunctions) {
+                const { queries, mutations } = getGeneratableFunctions(ir);
+                const allFunctions = [...queries, ...mutations];
+                for (const fn of allFunctions) {
+                    const resolved = resolveReturnType(fn, ir);
+                    if (resolved.returnEntity) {
+                        const entityName = resolved.returnEntity.name;
+                        const existing = functionsByEntity.get(entityName) ?? [];
+                        functionsByEntity.set(entityName, [...existing, fn]);
+                    }
+                    else {
+                        scalarFunctions.push(fn);
+                    }
+                }
             }
-            file.import({
-                kind: "symbol",
-                ref: { capability: "types", entity: entity.name, shape: "row" },
+            getTableEntities(ir)
+                .filter(entity => entity.tags.omit !== true)
+                .forEach(entity => {
+                const entityName = inflection.entityName(entity.pgClass, entity.tags);
+                const genCtx = {
+                    entity,
+                    enums,
+                    ir,
+                    sqlStyle,
+                    entityName,
+                    exportName,
+                    explicitColumns,
+                };
+                // Generate CRUD and lookup methods
+                const crudMethods = [...generateCrudMethods(genCtx), ...generateLookupMethods(genCtx)];
+                // Get functions that return this entity
+                const entityFunctions = functionsByEntity.get(entity.name) ?? [];
+                if (crudMethods.length === 0 && entityFunctions.length === 0)
+                    return;
+                const filePath = `${outputDir}/${entityName}.ts`;
+                // Convert methods to statements based on export style
+                const statements = toStatements(crudMethods, exportStyle, entityName);
+                // Add function wrappers (these are always flat exports for now)
+                for (const fn of entityFunctions) {
+                    const wrapper = generateFunctionWrapper(fn, ir, sqlStyle);
+                    statements.push(conjure.export.fn(wrapper.fn));
+                }
+                const file = ctx.file(filePath);
+                // Add user-provided header (must include SQL client import)
+                file.header(header);
+                file.import({
+                    kind: "symbol",
+                    ref: { capability: "types", entity: entity.name, shape: "row" },
+                });
+                // Import insert type if insert function is generated
+                if (entity.permissions.canInsert) {
+                    const insertShape = entity.shapes.insert ?? entity.shapes.row;
+                    // Only import if it's a different type than row
+                    if (insertShape !== entity.shapes.row) {
+                        file.import({
+                            kind: "symbol",
+                            ref: { capability: "types", entity: entity.name, shape: "insert" },
+                        });
+                    }
+                }
+                // Import types needed by function args (for functions grouped into this file)
+                if (entityFunctions.length > 0) {
+                    const fnTypeImports = collectFunctionTypeImports(entityFunctions, ir);
+                    // Remove the entity's own type (already in scope)
+                    fnTypeImports.delete(entity.name);
+                    for (const typeName of fnTypeImports) {
+                        file.import({
+                            kind: "symbol",
+                            ref: { capability: "types", entity: typeName },
+                        });
+                    }
+                }
+                file.ast(conjure.program(...statements)).emit();
+                // Collect metadata for QueryArtifact
+                const pkField = entity.primaryKey?.columns[0]
+                    ? findRowField(entity, entity.primaryKey.columns[0])
+                    : undefined;
+                const pkType = pkField ? getFieldTypeString(pkField, genCtx) : undefined;
+                // Combine CRUD method metadata with entity-function metadata
+                const allMethodMetas = [
+                    ...crudMethods.map(m => m.meta),
+                    ...entityFunctions.map(fn => generateFunctionWrapper(fn, ir, sqlStyle).meta),
+                ];
+                // Register entity methods to symbol registry for HTTP providers
+                ctx.symbols.registerEntityMethods({
+                    entity: entityName,
+                    importPath: filePath,
+                    pkType,
+                    hasCompositePk: (entity.primaryKey?.columns.length ?? 0) > 1,
+                    methods: allMethodMetas.map(m => ({
+                        name: m.name,
+                        file: filePath,
+                        entity: entityName,
+                        kind: m.kind,
+                        params: m.params,
+                        returns: m.returns,
+                        lookupField: m.lookupField,
+                        isUniqueLookup: m.isUniqueLookup,
+                        callSignature: m.callSignature,
+                    })),
+                }, "sql-queries");
             });
-            // Import insert type if insert function is generated
-            if (entity.permissions.canInsert) {
-                const insertShape = entity.shapes.insert ?? entity.shapes.row;
-                // Only import if it's a different type than row
-                if (insertShape !== entity.shapes.row) {
+            // Generate files for composite types that have functions returning them
+            if (generateFunctions) {
+                const composites = getCompositeEntities(ir);
+                for (const composite of composites) {
+                    const compositeFunctions = functionsByEntity.get(composite.name) ?? [];
+                    if (compositeFunctions.length === 0)
+                        continue;
+                    const filePath = `${outputDir}/${composite.name}.ts`;
+                    const methods = compositeFunctions.map(fn => generateFunctionWrapper(fn, ir, sqlStyle));
+                    // Function wrappers are always flat exports
+                    const statements = methods.map(m => conjure.export.fn(m.fn));
+                    const file = ctx.file(filePath);
+                    // Add user-provided header (must include SQL client import)
+                    file.header(header);
+                    // Import the composite type and any types needed by function args
+                    const fnTypeImports = collectFunctionTypeImports(compositeFunctions, ir);
+                    fnTypeImports.add(composite.name); // Always import the composite type
+                    for (const typeName of fnTypeImports) {
+                        file.import({
+                            kind: "symbol",
+                            ref: { capability: "types", entity: typeName },
+                        });
+                    }
+                    file.ast(conjure.program(...statements)).emit();
+                }
+            }
+            // Generate functions.ts for scalar-returning functions only
+            if (generateFunctions && scalarFunctions.length > 0) {
+                const filePath = `${outputDir}/${functionsFile}`;
+                const methods = scalarFunctions.map(fn => generateFunctionWrapper(fn, ir, sqlStyle));
+                // Function wrappers are always flat exports
+                const statements = methods.map(m => conjure.export.fn(m.fn));
+                const file = ctx.file(filePath);
+                // Add user-provided header (must include SQL client import)
+                file.header(header);
+                // Import types needed by function args
+                const fnTypeImports = collectFunctionTypeImports(scalarFunctions, ir);
+                for (const typeName of fnTypeImports) {
                     file.import({
                         kind: "symbol",
-                        ref: { capability: "types", entity: entity.name, shape: "insert" },
+                        ref: { capability: "types", entity: typeName },
                     });
                 }
+                file.ast(conjure.program(...statements)).emit();
+                // TODO: Register standalone functions to symbol registry when HTTP plugins need them
+                // For now, standalone functions are not exposed via routes
             }
-            file.ast(conjure.program(...statements)).emit();
-        });
-    },
-});
+        },
+    });
+}
 //# sourceMappingURL=sql-queries.js.map