@danielfgray/pg-sourcerer 0.2.1 → 0.3.0

package/dist/plugins/sql-queries.js

@@ -1,28 +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, getFunctionEntities, getCompositeEntities } from "../ir/semantic-ir.js";
-import { conjure, cast } from "../lib/conjure.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)
@@ -71,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];
@@ -82,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 conjure.export.fn(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 conjure.export.fn(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];
@@ -128,13 +207,28 @@ const generateDelete = (ctx) => {
     };
     // Delete returns void, no type parameter needed
     const queryExpr = hex.query(sqlStyle, parts);
-    return conjure.export.fn(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
@@ -146,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: [
@@ -157,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 conjure.export.fn(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
 // ============================================================================
@@ -182,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);
@@ -211,48 +317,76 @@ 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 conjure.export.fn(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 conjure.export.fn(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));
 };
 // ============================================================================
 // Function Wrapper Generation
@@ -427,9 +561,7 @@ const resolveArg = (arg, ir) => {
         };
     }
     // Scalar type - map via type name
-    const scalarBase = baseTypeName.includes(".")
-        ? baseTypeName.split(".").pop()
-        : baseTypeName;
+    const scalarBase = baseTypeName.includes(".") ? baseTypeName.split(".").pop() : baseTypeName;
     const scalarTs = pgTypeNameToTs(scalarBase);
     const tsType = isArrayType ? `${scalarTs}[]` : scalarTs;
     return {
@@ -458,8 +590,8 @@ const generateFunctionWrapper = (fn, ir, sqlStyle) => {
     const resolvedReturn = resolveReturnType(fn, ir);
     const resolvedArgs = resolveArgs(fn, ir);
     const qualifiedName = getFunctionQualifiedName(fn);
-    // Build camelCase function name
-    const exportName = inflect.camelCase(fn.pgName);
+    // 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("[]")) {
@@ -467,24 +599,34 @@ const generateFunctionWrapper = (fn, ir, sqlStyle) => {
             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);
+            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 list for the generated function
-    const params = resolvedArgs.map(arg => {
-        const p = b.identifier(arg.name);
-        p.typeAnnotation = b.tsTypeAnnotation(cast.toTSType(typeStrToAst(arg.tsType)));
-        if (arg.isOptional)
-            p.optional = true;
-        return p;
-    });
+    // 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;
@@ -532,7 +674,24 @@ const generateFunctionWrapper = (fn, ir, sqlStyle) => {
         const varDecl = hex.firstRowDecl(sqlStyle, "result", queryExpr);
         body = [varDecl, b.returnStatement(b.identifier("result"))];
     }
-    return conjure.export.fn(hex.asyncFn(exportName, params, body));
+    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.
@@ -553,136 +712,226 @@ const collectFunctionTypeImports = (functions, ir) => {
     return imports;
 };
 // ============================================================================
-// Plugin Definition
+// Export Style Helpers
 // ============================================================================
-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, generateFunctions } = config;
-        // 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(ctx.ir);
-            const allFunctions = [...queries, ...mutations];
-            for (const fn of allFunctions) {
-                const resolved = resolveReturnType(fn, ctx.ir);
-                if (resolved.returnEntity) {
-                    const entityName = resolved.returnEntity.name;
-                    const existing = functionsByEntity.get(entityName) ?? [];
-                    functionsByEntity.set(entityName, [...existing, fn]);
-                }
-                else {
-                    scalarFunctions.push(fn);
+/**
+ * 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);
+                    }
                 }
             }
-        }
-        getTableEntities(ctx.ir)
-            .filter(entity => entity.tags.omit !== true)
-            .forEach(entity => {
-            const genCtx = { entity, enums, ir: ctx.ir, sqlStyle };
-            const crudStatements = [...generateCrudFunctions(genCtx), ...generateLookupFunctions(genCtx)];
-            // Get functions that return this entity
-            const entityFunctions = functionsByEntity.get(entity.name) ?? [];
-            if (crudStatements.length === 0 && entityFunctions.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)}`;
-            // All statements for the file: CRUD methods + function wrappers
-            const statements = [...crudStatements];
-            // Add function wrappers
-            for (const fn of entityFunctions) {
-                statements.push(generateFunctionWrapper(fn, ctx.ir, sqlStyle));
-            }
-            const file = ctx.file(filePath);
-            // Import the appropriate SQL client based on style
-            if (sqlStyle === "tag") {
-                file.import({ kind: "relative", names: ["sql"], from: "../db" });
-            }
-            else {
-                file.import({ kind: "relative", names: ["pool"], from: "../db" });
-            }
-            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" },
-                    });
+            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));
                 }
-            }
-            // Import types needed by function args (for functions grouped into this file)
-            if (entityFunctions.length > 0) {
-                const fnTypeImports = collectFunctionTypeImports(entityFunctions, ctx.ir);
-                // Remove the entity's own type (already in scope)
-                fnTypeImports.delete(entity.name);
-                // TODO: Import these types when symbol registry supports it
-            }
-            file.ast(conjure.program(...statements)).emit();
-        });
-        // Generate files for composite types that have functions returning them
-        if (generateFunctions) {
-            const composites = getCompositeEntities(ctx.ir);
-            for (const composite of composites) {
-                const compositeFunctions = functionsByEntity.get(composite.name) ?? [];
-                if (compositeFunctions.length === 0)
-                    continue;
-                const filePath = `${config.outputDir}/${composite.name}.ts`;
-                const statements = compositeFunctions.map(fn => generateFunctionWrapper(fn, ctx.ir, sqlStyle));
                 const file = ctx.file(filePath);
-                // Import the appropriate SQL client based on style
-                if (sqlStyle === "tag") {
-                    file.import({ kind: "relative", names: ["sql"], from: "../db" });
+                // 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" },
+                        });
+                    }
                 }
-                else {
-                    file.import({ kind: "relative", names: ["pool"], from: "../db" });
+                // 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 },
+                        });
+                    }
                 }
-                // Import the composite type and any types needed by function args
-                const fnTypeImports = collectFunctionTypeImports(compositeFunctions, ctx.ir);
-                fnTypeImports.add(composite.name); // Always import the composite type
-                // TODO: Import these types when symbol registry supports it
                 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");
+            });
+            // 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 = `${config.outputDir}/${config.functionsFile}`;
-            const statements = scalarFunctions.map(fn => generateFunctionWrapper(fn, ctx.ir, sqlStyle));
-            const file = ctx.file(filePath);
-            // Import the appropriate SQL client based on style
-            if (sqlStyle === "tag") {
-                file.import({ kind: "relative", names: ["sql"], from: "../db" });
-            }
-            else {
-                file.import({ kind: "relative", names: ["pool"], from: "../db" });
+            // 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: 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
             }
-            // Import types needed by function args
-            const fnTypeImports = collectFunctionTypeImports(scalarFunctions, ctx.ir);
-            // TODO: Import these types when symbol registry supports it
-            file.ast(conjure.program(...statements)).emit();
-        }
-    },
-});
+        },
+    });
+}
 //# sourceMappingURL=sql-queries.js.map