@danielfgray/pg-sourcerer 0.1.8 → 0.1.10

package/dist/plugins/kysely-queries.js

@@ -6,39 +6,71 @@
  */
 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, cast } from "../lib/conjure.js";
 import { resolveFieldType, tsTypeToAst } from "../lib/field-utils.js";
 import { inflect } from "../services/inflection.js";
 const { ts, b } = conjure;
 const { toExpr } = cast;
-// ============================================================================
-// Configuration
-// ============================================================================
-const KyselyQueriesPluginConfig = S.Struct({
-    outputDir: S.String,
-    header: S.optional(S.String),
+/** Default export name: entityName + methodName (e.g., "UserFindById") */
+const defaultExportName = (entityName, methodName) => `${entityName}${methodName}`;
+/** Default function export name: camelCase of pg function name */
+const defaultFunctionExportName = (pgFunctionName) => inflect.camelCase(pgFunctionName);
+/**
+ * Schema for serializable config options (JSON/YAML compatible).
+ * Function options are typed separately in KyselyQueriesConfigInput.
+ */
+const KyselyQueriesPluginConfigSchema = S.Struct({
+    outputDir: S.optionalWith(S.String, { default: () => "kysely-queries" }),
     /**
      * Path to import DB type from (relative to outputDir).
-     * Defaults to "../DB.js" which works with kysely-codegen's DB.d.ts output.
-     * For node16/nodenext module resolution, use ".js" extension even for .d.ts files.
+     * Defaults to "../db.js" which works with kysely-types plugin output.
+     * For node16/nodenext module resolution, use ".js" extension even for .ts files.
      */
-    dbTypesPath: S.optional(S.String),
+    dbTypesPath: S.optionalWith(S.String, { default: () => "../db.js" }),
     /**
      * Whether to call .execute() / .executeTakeFirst() on queries.
      * When true (default), methods return Promise<Row> or Promise<Row[]>.
      * When false, methods return the query builder for further customization.
      */
-    executeQueries: S.optional(S.Boolean),
+    executeQueries: S.optionalWith(S.Boolean, { default: () => true }),
+    /**
+     * Whether to generate listMany() method for unfiltered table scans.
+     * Disabled by default since unfiltered scans don't use indexes.
+     * When enabled, generates: listMany(db, limit = 50, offset = 0)
+     */
+    generateListMany: S.optionalWith(S.Boolean, { default: () => false }),
+    /**
+     * Whether to generate function wrappers for stored functions.
+     * When true (default), generates queries/mutations namespaces in functions.ts.
+     */
+    generateFunctions: S.optionalWith(S.Boolean, { default: () => true }),
+    /**
+     * Output file name for function wrappers (relative to outputDir).
+     */
+    functionsFile: S.optionalWith(S.String, { default: () => "functions.ts" }),
+    /**
+     * Export name function (validated as Any, properly typed in KyselyQueriesConfigInput)
+     */
+    exportName: S.optional(S.Any),
+    /**
+     * Function export name function (validated as Any, properly typed in KyselyQueriesConfigInput)
+     */
+    functionExportName: S.optional(S.Any),
 });
 /**
  * Get the Kysely table interface name from the entity.
- * Converts schema.table to PascalCase: app_public.users -> AppPublicUsers
- * Uses the inflection utility to match kysely-codegen's naming convention.
+ * Uses entity.name which is already PascalCase from inflection (e.g., Users).
+ */
+const getTableTypeName = (entity) => entity.name;
+/**
+ * Get the table reference for Kysely queries.
+ * Uses schema-qualified name only if the schema is NOT in defaultSchemas.
+ * This matches the keys in the DB interface from kysely-types plugin.
  */
-const getTableTypeName = (entity) => `${inflect.pascalCase(entity.schemaName)}${inflect.pascalCase(entity.pgName)}`;
-/** Get the schema-qualified table name for Kysely */
-const getTableRef = (entity) => `${entity.schemaName}.${entity.pgName}`;
+const getTableRef = (entity, defaultSchemas) => defaultSchemas.includes(entity.schemaName)
+    ? entity.pgName
+    : `${entity.schemaName}.${entity.pgName}`;
 /** Find a field in the row shape by column name */
 const findRowField = (entity, columnName) => entity.shapes.row.fields.find(f => f.columnName === columnName);
 /** Get the TypeScript type AST for a field */
@@ -49,6 +81,41 @@ const getFieldTypeAst = (field, ctx) => {
     return resolved.enumDef ? ts.ref(resolved.enumDef.name) : tsTypeToAst(resolved.tsType);
 };
 // ============================================================================
+// FK Semantic Naming Helpers
+// ============================================================================
+/**
+ * Find a belongsTo relation that uses the given column as its local FK column.
+ * For single-column indexes only.
+ */
+const findRelationForColumn = (entity, columnName) => entity.relations.find(r => r.kind === "belongsTo" && r.columns.length === 1 && r.columns[0]?.local === columnName);
+/**
+ * Derive semantic name for an FK-based lookup.
+ * Priority: @fieldName tag → column minus _id suffix → target entity name
+ */
+const deriveSemanticName = (relation, columnName) => {
+    // 1. Check for @fieldName smart tag
+    if (relation.tags.fieldName && typeof relation.tags.fieldName === "string") {
+        return relation.tags.fieldName;
+    }
+    // 2. Strip common FK suffixes from column name
+    const suffixes = ["_id", "_fk", "Id", "Fk"];
+    for (const suffix of suffixes) {
+        if (columnName.endsWith(suffix)) {
+            const stripped = columnName.slice(0, -suffix.length);
+            if (stripped.length > 0)
+                return stripped;
+        }
+    }
+    // 3. Fall back to target entity name (lowercased first char)
+    const target = relation.targetEntity;
+    return target.charAt(0).toLowerCase() + target.slice(1);
+};
+/**
+ * Convert to PascalCase for use in method names.
+ * Handles snake_case (created_at → CreatedAt) and regular strings.
+ */
+const toPascalCase = (s) => inflect.pascalCase(s);
+// ============================================================================
 // AST Building Helpers
 // ============================================================================
 /** Create identifier */
@@ -91,6 +158,15 @@ const deleteFrom = (tableRef) => call(id("db"), "deleteFrom", [str(tableRef)]);
  * Chain method call onto existing expression
  */
 const chain = (expr, method, args = []) => call(expr, method, args);
+/**
+ * Create an exported const declaration: export const name = value
+ */
+const exportConst = (name, value) => {
+    const constDecl = b.variableDeclaration("const", [
+        b.variableDeclarator(id(name), toExpr(value))
+    ]);
+    return b.exportNamedDeclaration(constDecl, []);
+};
 /**
  * Build arrow function expression: (params) => body
  */
@@ -106,21 +182,398 @@ const objProp = (key, value) => {
     return prop;
 };
 // ============================================================================
+// PostgreSQL Type Name to TypeScript Mapping
+// ============================================================================
+/**
+ * Map PostgreSQL type name to TypeScript type string.
+ * Used for function argument and return type resolution.
+ */
+const pgTypeNameToTs = (typeName) => {
+    // Normalize: strip schema prefix if present
+    const baseName = typeName.includes(".") ? typeName.split(".").pop() : typeName;
+    switch (baseName) {
+        // Boolean
+        case "bool":
+        case "boolean":
+            return "boolean";
+        // Integer types → number
+        case "int2":
+        case "smallint":
+        case "int4":
+        case "integer":
+        case "int":
+        case "oid":
+        case "float4":
+        case "real":
+        case "float8":
+        case "double precision":
+            return "number";
+        // Big integers/numeric → string (to avoid precision loss)
+        case "int8":
+        case "bigint":
+        case "numeric":
+        case "decimal":
+        case "money":
+            return "string";
+        // Text types → string
+        case "text":
+        case "varchar":
+        case "character varying":
+        case "char":
+        case "character":
+        case "bpchar":
+        case "name":
+        case "xml":
+        case "bit":
+        case "varbit":
+        case "bit varying":
+        case "uuid":
+        case "inet":
+        case "cidr":
+        case "macaddr":
+        case "macaddr8":
+        case "time":
+        case "timetz":
+        case "time with time zone":
+        case "time without time zone":
+        case "interval":
+            return "string";
+        // Date/Time with date component → Date
+        case "date":
+        case "timestamp":
+        case "timestamptz":
+        case "timestamp with time zone":
+        case "timestamp without time zone":
+            return "Date";
+        // JSON → unknown
+        case "json":
+        case "jsonb":
+        case "jsonpath":
+            return "unknown";
+        // Binary → Buffer
+        case "bytea":
+            return "Buffer";
+        // Void
+        case "void":
+            return "void";
+        // Default to unknown
+        default:
+            return "unknown";
+    }
+};
+/**
+ * Check if a function argument type matches a table/view entity (row type argument).
+ * Functions with row-type arguments are computed fields (e.g., posts_short_body(posts))
+ * and should be excluded from function wrapper generation.
+ */
+const hasRowTypeArg = (arg, ir) => {
+    const tableEntities = getTableEntities(ir);
+    // Check if arg.typeName matches a table entity's qualified name
+    // Format: "schema.tablename" or just "tablename" for public schema
+    return tableEntities.some(entity => {
+        const qualifiedName = `${entity.schemaName}.${entity.pgName}`;
+        return arg.typeName === qualifiedName || arg.typeName === entity.pgName;
+    });
+};
+/**
+ * Check if a function should be included in generated wrappers.
+ *
+ * Includes functions that:
+ * - Have canExecute permission
+ * - Are not trigger functions
+ * - Are not from extensions
+ * - Are not @omit tagged
+ * - Don't have row-type arguments (computed fields)
+ */
+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;
+    // Check for row-type args (computed field pattern)
+    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
+    // Handle "schema.typename" format by extracting just the 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
+    // Handle "schema.typename" format
+    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));
+// ============================================================================
+// Function Wrapper AST Generation
+// ============================================================================
+/**
+ * Generate a typed parameter with explicit type annotation from type string.
+ */
+const typedParamFromString = (name, typeStr) => {
+    const param = id(name);
+    // Map type string to AST
+    let typeAst;
+    switch (typeStr) {
+        case "string":
+            typeAst = ts.string();
+            break;
+        case "number":
+            typeAst = ts.number();
+            break;
+        case "boolean":
+            typeAst = ts.boolean();
+            break;
+        case "Date":
+            typeAst = ts.ref("Date");
+            break;
+        case "Buffer":
+            typeAst = ts.ref("Buffer");
+            break;
+        case "unknown":
+            typeAst = ts.unknown();
+            break;
+        case "void":
+            typeAst = ts.void();
+            break;
+        default:
+            // Handle array types like "string[]"
+            if (typeStr.endsWith("[]")) {
+                const elemType = typeStr.slice(0, -2);
+                const elemAst = elemType === "string" ? ts.string()
+                    : elemType === "number" ? ts.number()
+                        : elemType === "boolean" ? ts.boolean()
+                            : ts.ref(elemType);
+                typeAst = ts.array(elemAst);
+            }
+            else {
+                // Assume it's a type reference (composite, enum, etc.)
+                typeAst = ts.ref(typeStr);
+            }
+    }
+    param.typeAnnotation = b.tsTypeAnnotation(cast.toTSType(typeAst));
+    return param;
+};
+/**
+ * Generate an optional typed parameter with explicit type annotation.
+ */
+const optionalTypedParamFromString = (name, typeStr) => {
+    const param = typedParamFromString(name, typeStr);
+    param.optional = true;
+    return param;
+};
+/**
+ * Get the fully qualified function name for use in eb.fn call.
+ */
+const getFunctionQualifiedName = (fn) => `${fn.schemaName}.${fn.pgName}`;
+/**
+ * Generate a function wrapper method as an object property.
+ *
+ * Patterns:
+ * - SETOF/table return: db.selectFrom(eb => eb.fn<Type>(...).as('f')).selectAll().execute()
+ * - Single row return: db.selectFrom(eb => eb.fn<Type>(...).as('f')).selectAll().executeTakeFirst()
+ * - Scalar return: db.selectNoFrom(eb => eb.fn<Type>(...).as('result')).executeTakeFirst().then(r => r?.result)
+ */
+const generateFunctionWrapper = (fn, ir, executeQueries, functionExportName) => {
+    const resolvedReturn = resolveReturnType(fn, ir);
+    const resolvedArgs = resolveArgs(fn, ir);
+    const qualifiedName = getFunctionQualifiedName(fn);
+    // Build eb.val(arg) for each argument
+    const fnArgs = resolvedArgs.map(arg => call(id("eb"), "val", [id(arg.name)]));
+    // Build eb.fn<Type>('schema.fn_name', [args]).as('alias')
+    // The type parameter is the return type
+    const returnTypeAst = resolvedReturn.isScalar
+        ? typedParamFromString("_", resolvedReturn.tsType).typeAnnotation.typeAnnotation
+        : ts.ref(resolvedReturn.tsType);
+    // Create eb.fn with type parameter: eb.fn<Type>
+    const fnMember = b.memberExpression(id("eb"), id("fn"));
+    const fnWithType = b.tsInstantiationExpression(fnMember, b.tsTypeParameterInstantiation([cast.toTSType(returnTypeAst)]));
+    // Call it: eb.fn<Type>(name, args)
+    const fnCallBase = b.callExpression(fnWithType, [str(qualifiedName), b.arrayExpression(fnArgs.map(toExpr))]);
+    // .as('f') or .as('result') for scalar
+    const alias = resolvedReturn.isScalar ? "result" : "f";
+    const fnCallWithAlias = call(fnCallBase, "as", [str(alias)]);
+    // Arrow function for selectFrom callback: eb => eb.fn<...>(...).as('f')
+    const selectCallback = arrowFn([id("eb")], fnCallWithAlias);
+    // Build the query chain
+    let query;
+    if (resolvedReturn.isScalar) {
+        // Scalar: db.selectNoFrom(eb => ...).executeTakeFirst()
+        // Returns { result: T } | undefined - caller accesses .result
+        query = call(id("db"), "selectNoFrom", [selectCallback]);
+        if (executeQueries) {
+            query = chain(query, "executeTakeFirst");
+        }
+    }
+    else {
+        // Table/composite: db.selectFrom(eb => ...).selectAll()
+        query = chain(call(id("db"), "selectFrom", [selectCallback]), "selectAll");
+        if (executeQueries) {
+            // SETOF → .execute(), single row → .executeTakeFirst()
+            query = chain(query, resolvedReturn.isArray ? "execute" : "executeTakeFirst");
+        }
+    }
+    // Build the parameters: (db: Kysely<DB>, arg1: Type1, arg2?: Type2, ...)
+    const params = [
+        typedParam("db", ts.ref("Kysely", [ts.ref("DB")])),
+        ...resolvedArgs.map(arg => arg.isOptional
+            ? optionalTypedParamFromString(arg.name, arg.tsType)
+            : typedParamFromString(arg.name, arg.tsType))
+    ];
+    const wrapperFn = arrowFn(params, query);
+    const exportName = functionExportName(fn.pgName);
+    const constDecl = b.variableDeclaration("const", [
+        b.variableDeclarator(id(exportName), wrapperFn)
+    ]);
+    return b.exportNamedDeclaration(constDecl, []);
+};
+/**
+ * Collect all 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);
+            }
+        }
+    }
+    return imports;
+};
+// ============================================================================
 // CRUD Method Generators
 // ============================================================================
 /**
  * Generate findById method:
- * findById: (db, id) => db.selectFrom('table').selectAll().where('id', '=', id).executeTakeFirst()
+ * export const UserFindById = (db, id) => db.selectFrom('table').selectAll().where('id', '=', id).executeTakeFirst()
  */
 const generateFindById = (ctx) => {
-    const { entity, executeQueries } = ctx;
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
     if (!entity.primaryKey || !entity.permissions.canSelect)
         return undefined;
     const pkColName = entity.primaryKey.columns[0];
     const pkField = findRowField(entity, pkColName);
     if (!pkField)
         return undefined;
-    const tableRef = getTableRef(entity);
+    const tableRef = getTableRef(entity, defaultSchemas);
     const fieldName = pkField.name;
     const fieldType = getFieldTypeAst(pkField, ctx);
     // db.selectFrom('table').selectAll().where('col', '=', id)
@@ -129,71 +582,49 @@ const generateFindById = (ctx) => {
         query = chain(query, "executeTakeFirst");
     }
     const fn = arrowFn([typedParam("db", ts.ref("Kysely", [ts.ref("DB")])), typedParam(fieldName, fieldType)], query);
-    return objProp("findById", fn);
+    return exportConst(exportName(entityName, "FindById"), fn);
 };
+/** Default limit for findMany queries */
+const DEFAULT_LIMIT = 50;
+/** Default offset for findMany queries */
+const DEFAULT_OFFSET = 0;
+/**
+ * Create a parameter with a default value: name = defaultValue
+ * Type is inferred from the default value, no explicit annotation.
+ */
+const paramWithDefault = (name, defaultValue) => b.assignmentPattern(id(name), toExpr(defaultValue));
 /**
- * Generate findMany method with optional pagination:
- * findMany: (db, opts?) => db.selectFrom('table').selectAll()
- *   .$if(opts?.limit != null, q => q.limit(opts!.limit!))
- *   .$if(opts?.offset != null, q => q.offset(opts!.offset!))
- *   .execute()
+ * Generate listMany method with pagination defaults:
+ * export const UserListMany = (db, limit = 50, offset = 0) => db.selectFrom('table').selectAll()
+ *   .limit(limit).offset(offset).execute()
  */
-const generateFindMany = (ctx) => {
-    const { entity, executeQueries } = ctx;
+const generateListMany = (ctx) => {
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
     if (!entity.permissions.canSelect)
         return undefined;
-    const tableRef = getTableRef(entity);
-    // Build the base query
-    let query = chain(selectFrom(tableRef), "selectAll");
-    // Add $if for limit
-    // q => q.limit(opts!.limit!)
-    const limitCallback = arrowFn([id("q")], call(id("q"), "limit", [
-        member(b.tsNonNullExpression(member(id("opts"), "limit")), 
-        // This creates opts!.limit, we need to wrap the whole thing
-        // Actually we want: opts!.limit!
-        "")
-    ]));
-    // Simpler approach - just use opts?.limit directly with non-null assertion where needed
-    const limitCheck = b.binaryExpression("!=", toExpr(member(b.optionalMemberExpression(id("opts"), id("limit"), false, true), "")), b.nullLiteral());
-    // Actually let's simplify - use a cleaner pattern
-    // $if(opts?.limit != null, q => q.limit(opts!.limit!))
-    query = call(query, "$if", [
-        b.binaryExpression("!=", toExpr(b.optionalMemberExpression(id("opts"), id("limit"), false, true)), b.nullLiteral()),
-        arrowFn([id("q")], call(id("q"), "limit", [
-            b.tsNonNullExpression(toExpr(member(b.tsNonNullExpression(toExpr(id("opts"))), "limit")))
-        ]))
-    ]);
-    // Add $if for offset
-    query = call(query, "$if", [
-        b.binaryExpression("!=", toExpr(b.optionalMemberExpression(id("opts"), id("offset"), false, true)), b.nullLiteral()),
-        arrowFn([id("q")], call(id("q"), "offset", [
-            b.tsNonNullExpression(toExpr(member(b.tsNonNullExpression(toExpr(id("opts"))), "offset")))
-        ]))
-    ]);
+    const tableRef = getTableRef(entity, defaultSchemas);
+    // Build query: db.selectFrom('table').selectAll().limit(limit).offset(offset)
+    let query = chain(chain(chain(selectFrom(tableRef), "selectAll"), "limit", [id("limit")]), "offset", [id("offset")]);
     // Add .execute() if executeQueries is true
     if (executeQueries) {
         query = chain(query, "execute");
     }
-    // Build opts parameter type: { limit?: number; offset?: number }
-    const optsType = ts.objectType([
-        { name: "limit", type: ts.number(), optional: true },
-        { name: "offset", type: ts.number(), optional: true },
-    ]);
     const fn = arrowFn([
         typedParam("db", ts.ref("Kysely", [ts.ref("DB")])),
-        optionalTypedParam("opts", optsType),
+        paramWithDefault("limit", b.numericLiteral(DEFAULT_LIMIT)),
+        paramWithDefault("offset", b.numericLiteral(DEFAULT_OFFSET)),
     ], query);
-    return objProp("findMany", fn);
+    return exportConst(exportName(entityName, "ListMany"), fn);
 };
 /**
  * Generate create method:
- * create: (db, data) => db.insertInto('table').values(data).returningAll().executeTakeFirstOrThrow()
+ * export const UserCreate = (db, data) => db.insertInto('table').values(data).returningAll().executeTakeFirstOrThrow()
  */
 const generateCreate = (ctx) => {
-    const { entity, executeQueries } = ctx;
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
     if (!entity.permissions.canInsert)
         return undefined;
-    const tableRef = getTableRef(entity);
+    const tableRef = getTableRef(entity, defaultSchemas);
     const tableTypeName = getTableTypeName(entity);
     // db.insertInto('table').values(data).returningAll()
     let query = chain(chain(insertInto(tableRef), "values", [id("data")]), "returningAll");
@@ -205,21 +636,21 @@ const generateCreate = (ctx) => {
         typedParam("db", ts.ref("Kysely", [ts.ref("DB")])),
         typedParam("data", ts.ref("Insertable", [ts.ref(tableTypeName)])),
     ], query);
-    return objProp("create", fn);
+    return exportConst(exportName(entityName, "Create"), fn);
 };
 /**
  * Generate update method:
- * update: (db, id, data) => db.updateTable('table').set(data).where('id', '=', id).returningAll().executeTakeFirstOrThrow()
+ * export const UserUpdate = (db, id, data) => db.updateTable('table').set(data).where('id', '=', id).returningAll().executeTakeFirstOrThrow()
  */
 const generateUpdate = (ctx) => {
-    const { entity, executeQueries } = ctx;
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
     if (!entity.primaryKey || !entity.permissions.canUpdate)
         return undefined;
     const pkColName = entity.primaryKey.columns[0];
     const pkField = findRowField(entity, pkColName);
     if (!pkField)
         return undefined;
-    const tableRef = getTableRef(entity);
+    const tableRef = getTableRef(entity, defaultSchemas);
     const fieldName = pkField.name;
     const fieldType = getFieldTypeAst(pkField, ctx);
     const tableTypeName = getTableTypeName(entity);
@@ -234,21 +665,21 @@ const generateUpdate = (ctx) => {
         typedParam(fieldName, fieldType),
         typedParam("data", ts.ref("Updateable", [ts.ref(tableTypeName)])),
     ], query);
-    return objProp("update", fn);
+    return exportConst(exportName(entityName, "Update"), fn);
 };
 /**
  * Generate delete method:
- * delete: (db, id) => db.deleteFrom('table').where('id', '=', id).execute()
+ * export const UserRemove = (db, id) => db.deleteFrom('table').where('id', '=', id).execute()
  */
 const generateDelete = (ctx) => {
-    const { entity, executeQueries } = ctx;
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
     if (!entity.primaryKey || !entity.permissions.canDelete)
         return undefined;
     const pkColName = entity.primaryKey.columns[0];
     const pkField = findRowField(entity, pkColName);
     if (!pkField)
         return undefined;
-    const tableRef = getTableRef(entity);
+    const tableRef = getTableRef(entity, defaultSchemas);
     const fieldName = pkField.name;
     const fieldType = getFieldTypeAst(pkField, ctx);
     // db.deleteFrom('table').where('id', '=', id)
@@ -257,13 +688,12 @@ const generateDelete = (ctx) => {
         query = chain(query, "execute");
     }
     const fn = arrowFn([typedParam("db", ts.ref("Kysely", [ts.ref("DB")])), typedParam(fieldName, fieldType)], query);
-    // Use 'remove' since 'delete' is a reserved word
-    return objProp("remove", fn);
+    return exportConst(exportName(entityName, "Remove"), fn);
 };
 /** Generate all CRUD methods for an entity */
 const generateCrudMethods = (ctx) => [
     generateFindById(ctx),
-    generateFindMany(ctx),
+    ctx.generateListMany ? generateListMany(ctx) : undefined,
     generateCreate(ctx),
     generateUpdate(ctx),
     generateDelete(ctx),
@@ -277,42 +707,108 @@ const shouldGenerateLookup = (index) => !index.isPartial &&
     index.columns.length === 1 &&
     index.method !== "gin" &&
     index.method !== "gist";
-/** Generate a method name for an index-based lookup */
-const generateLookupName = (index) => {
-    const colName = index.columns[0];
-    const capitalizedCol = colName.charAt(0).toUpperCase() + colName.slice(1);
-    return `findBy${capitalizedCol}`;
+/**
+ * Generate the method name portion for an index-based lookup.
+ * Uses semantic naming when the column corresponds to an FK relation.
+ */
+const generateLookupMethodName = (entity, index, relation) => {
+    const isUnique = isUniqueLookup(entity, index);
+    // Uses "FindOneBy" or "FindManyBy" suffix
+    const suffix = isUnique ? "FindOneBy" : "FindManyBy";
+    // 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 `${suffix}${toPascalCase(byName)}`;
 };
-/** Generate a lookup method 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 generateLookupMethod = (index, ctx) => {
-    const { entity, executeQueries } = ctx;
-    const tableRef = getTableRef(entity);
+    const { entity, executeQueries, defaultSchemas, entityName, exportName } = ctx;
+    const tableRef = getTableRef(entity, defaultSchemas);
     const columnName = index.columnNames[0];
     const field = findRowField(entity, columnName);
     const fieldName = field?.name ?? index.columns[0];
-    const fieldType = getFieldTypeAst(field, ctx);
-    const isUnique = index.isUnique || index.isPrimary;
+    const isUnique = isUniqueLookup(entity, index);
+    // 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;
+    // For FK columns, use indexed access on Selectable<TableType> to get the unwrapped type
+    // (Kysely's Generated<T> types need Selectable to unwrap for use in where clauses)
+    // For regular columns, use the field's type directly
+    const useSemanticNaming = relation !== undefined && paramName !== fieldName;
+    const tableTypeName = getTableTypeName(entity);
+    const paramType = useSemanticNaming
+        ? ts.indexedAccess(ts.ref("Selectable", [ts.ref(tableTypeName)]), ts.literal(fieldName))
+        : getFieldTypeAst(field, ctx);
     // db.selectFrom('table').selectAll().where('col', '=', value)
-    let query = chain(chain(selectFrom(tableRef), "selectAll"), "where", [str(columnName), str("="), id(fieldName)]);
+    let query = chain(chain(selectFrom(tableRef), "selectAll"), "where", [str(columnName), str("="), id(paramName)]);
     if (executeQueries) {
         query = chain(query, isUnique ? "executeTakeFirst" : "execute");
     }
-    const fn = arrowFn([typedParam("db", ts.ref("Kysely", [ts.ref("DB")])), typedParam(fieldName, fieldType)], query);
-    return objProp(generateLookupName(index), fn);
+    const fn = arrowFn([typedParam("db", ts.ref("Kysely", [ts.ref("DB")])), typedParam(paramName, paramType)], query);
+    const methodName = generateLookupMethodName(entity, index, relation);
+    return exportConst(exportName(entityName, methodName), fn);
 };
-/** 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 && ctx.entity.permissions.canSelect)
-        .filter(index => {
-        const name = generateLookupName(index);
-        if (seen.has(name))
+/**
+ * Check if a column is covered by a unique constraint (not just unique index).
+ * This helps determine if a non-unique B-tree index on the column still
+ * returns at most one row.
+ */
+const columnHasUniqueConstraint = (entity, columnName) => {
+    const constraints = entity.pgClass.getConstraints();
+    return constraints.some(c => {
+        // 'u' = unique constraint, 'p' = primary key
+        if (c.contype !== "u" && c.contype !== "p")
             return false;
-        seen.add(name);
+        // Single-column constraint on our column?
+        const conkey = c.conkey ?? [];
+        if (conkey.length !== 1)
+            return false;
+        // Find the attribute with this attnum
+        const attrs = entity.pgClass.getAttributes();
+        const attr = attrs.find(a => a.attnum === conkey[0]);
+        return attr?.attname === columnName;
+    });
+};
+/**
+ * Determine if a lookup should be treated as unique (returns one row).
+ * True if: index is unique, index is primary, OR column has unique constraint.
+ */
+const isUniqueLookup = (entity, index) => {
+    if (index.isUnique || index.isPrimary)
         return true;
-    })
-        .map(index => generateLookupMethod(index, ctx));
+    // Check if the single column has a unique constraint
+    const columnName = index.columnNames[0];
+    return columnName ? columnHasUniqueConstraint(entity, columnName) : false;
+};
+/** Generate lookup methods for all eligible indexes, deduplicating by column */
+const generateLookupMethods = (ctx) => {
+    const eligibleIndexes = ctx.entity.indexes
+        .filter(index => shouldGenerateLookup(index) && !index.isPrimary && ctx.entity.permissions.canSelect);
+    // Group by column name, keeping only one index per column
+    // Prefer unique indexes, but also consider columns with unique constraints
+    const byColumn = new Map();
+    for (const index of eligibleIndexes) {
+        const columnName = index.columnNames[0];
+        const existing = byColumn.get(columnName);
+        if (!existing) {
+            byColumn.set(columnName, index);
+        }
+        else {
+            // Prefer explicitly unique index over non-unique
+            if (index.isUnique && !existing.isUnique) {
+                byColumn.set(columnName, index);
+            }
+        }
+    }
+    return Array.from(byColumn.values()).map(index => generateLookupMethod(index, ctx));
 };
 // ============================================================================
 // Plugin Definition
@@ -321,23 +817,50 @@ export const kyselyQueriesPlugin = definePlugin({
     name: "kysely-queries",
     provides: ["queries", "queries:kysely"],
     requires: [], // No dependency on types:kysely for now - uses external kysely-codegen types
-    configSchema: KyselyQueriesPluginConfig,
+    configSchema: KyselyQueriesPluginConfigSchema,
     inflection: {
         outputFile: ctx => `${ctx.entityName}.ts`,
         symbolName: (entityName, artifactKind) => `${entityName}${artifactKind}`,
     },
-    run: (ctx, config) => {
+    run: (ctx, rawConfig) => {
+        // Resolve config with function defaults
+        const config = {
+            ...rawConfig,
+            exportName: rawConfig.exportName ?? defaultExportName,
+            functionExportName: rawConfig.functionExportName ?? defaultFunctionExportName,
+        };
         const enums = getEnumEntities(ctx.ir);
-        const dbTypesPath = config.dbTypesPath ?? "../DB.js";
-        const executeQueries = config.executeQueries ?? true;
+        const defaultSchemas = ctx.ir.schemas;
+        const { dbTypesPath, executeQueries, generateListMany, exportName, functionExportName } = 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 (config.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);
+                }
+            }
+        }
         getTableEntities(ctx.ir)
             .filter(entity => entity.tags.omit !== true)
             .forEach(entity => {
-            const genCtx = { entity, enums, ir: ctx.ir, dbTypesPath, executeQueries };
-            const methods = [...generateCrudMethods(genCtx), ...generateLookupMethods(genCtx)];
-            if (methods.length === 0)
-                return;
             const entityName = ctx.inflection.entityName(entity.pgClass, entity.tags);
+            const genCtx = { entity, enums, ir: ctx.ir, defaultSchemas, dbTypesPath, executeQueries, generateListMany, entityName, exportName };
+            const crudStatements = [...generateCrudMethods(genCtx), ...generateLookupMethods(genCtx)];
+            // Get functions that return this entity
+            const entityFunctions = functionsByEntity.get(entity.name) ?? [];
+            if (crudStatements.length === 0 && entityFunctions.length === 0)
+                return;
             const fileNameCtx = {
                 entityName,
                 pgName: entity.pgName,
@@ -346,35 +869,92 @@ export const kyselyQueriesPlugin = definePlugin({
                 entity,
             };
             const filePath = `${config.outputDir}/${ctx.pluginInflection.outputFile(fileNameCtx)}`;
-            // Build the namespace object: export const users = { findById, findMany, ... }
-            const namespaceObj = b.objectExpression(methods.map(m => m));
-            // Lowercase entity name for the namespace variable
-            const namespaceName = entity.pgName;
-            const constDecl = b.variableDeclaration("const", [
-                b.variableDeclarator(id(namespaceName), namespaceObj)
-            ]);
-            const exportDecl = b.exportNamedDeclaration(constDecl, []);
+            // All statements for the file: CRUD methods + function wrappers
+            const statements = [...crudStatements];
+            // Add function wrappers as flat exports
+            for (const fn of entityFunctions) {
+                statements.push(generateFunctionWrapper(fn, ctx.ir, executeQueries, config.functionExportName));
+            }
             const file = ctx
-                .file(filePath)
-                .header(config.header ? `${config.header}\n` : "// This file is auto-generated. Do not edit.\n");
+                .file(filePath);
             // Import Kysely type and DB from kysely-codegen output
             file.import({ kind: "package", types: ["Kysely"], from: "kysely" });
             file.import({ kind: "relative", types: ["DB"], from: dbTypesPath });
             // Import Insertable/Updateable helper types and table type if we generate create/update
             const tableTypeName = getTableTypeName(entity);
+            // Check if any lookup methods use semantic naming (FK with Selectable indexed access)
+            const hasSemanticLookups = entity.indexes.some(index => {
+                if (!shouldGenerateLookup(index) || index.isPrimary)
+                    return false;
+                const columnName = index.columnNames[0];
+                const relation = findRelationForColumn(entity, columnName);
+                if (!relation)
+                    return false;
+                const paramName = deriveSemanticName(relation, columnName);
+                const field = findRowField(entity, columnName);
+                const fieldName = field?.name ?? index.columns[0];
+                return paramName !== fieldName;
+            });
+            // Import table type if needed for Insertable/Updateable or semantic lookups
+            const needsTableType = entity.permissions.canInsert || entity.permissions.canUpdate || hasSemanticLookups;
+            if (needsTableType) {
+                file.import({ kind: "relative", types: [tableTypeName], from: dbTypesPath });
+            }
+            // Import Selectable if we have semantic lookups (for unwrapping Generated<T>)
+            if (hasSemanticLookups) {
+                file.import({ kind: "package", types: ["Selectable"], from: "kysely" });
+            }
             if (entity.permissions.canInsert) {
                 file.import({ kind: "package", types: ["Insertable"], from: "kysely" });
-                file.import({ kind: "relative", types: [tableTypeName], from: dbTypesPath });
             }
             if (entity.permissions.canUpdate) {
                 file.import({ kind: "package", types: ["Updateable"], from: "kysely" });
-                // Only import table type if not already imported by canInsert
-                if (!entity.permissions.canInsert) {
-                    file.import({ kind: "relative", types: [tableTypeName], from: dbTypesPath });
+            }
+            // 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 or self-referential)
+                fnTypeImports.delete(entity.name);
+                if (fnTypeImports.size > 0) {
+                    file.import({ kind: "relative", types: [...fnTypeImports], from: dbTypesPath });
                 }
             }
-            file.ast(conjure.program(exportDecl)).emit();
+            file.ast(conjure.program(...statements)).emit();
         });
+        // Generate files for composite types that have functions returning them
+        if (config.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, executeQueries, config.functionExportName));
+                const file = ctx.file(filePath);
+                file.import({ kind: "package", types: ["Kysely"], from: "kysely" });
+                file.import({ kind: "relative", types: ["DB"], from: dbTypesPath });
+                // 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
+                file.import({ kind: "relative", types: [...fnTypeImports], from: dbTypesPath });
+                file.ast(conjure.program(...statements)).emit();
+            }
+        }
+        // Generate functions.ts for scalar-returning functions only
+        if (config.generateFunctions && scalarFunctions.length > 0) {
+            const filePath = `${config.outputDir}/${config.functionsFile}`;
+            const statements = scalarFunctions.map(fn => generateFunctionWrapper(fn, ctx.ir, executeQueries, config.functionExportName));
+            const file = ctx.file(filePath);
+            // Import Kysely type and DB
+            file.import({ kind: "package", types: ["Kysely"], from: "kysely" });
+            file.import({ kind: "relative", types: ["DB"], from: dbTypesPath });
+            // Import any types needed for function args (scalars don't need return type imports)
+            const typeImports = collectFunctionTypeImports(scalarFunctions, ctx.ir);
+            if (typeImports.size > 0) {
+                file.import({ kind: "relative", types: [...typeImports], from: dbTypesPath });
+            }
+            file.ast(conjure.program(...statements)).emit();
+        }
     },
 });
 //# sourceMappingURL=kysely-queries.js.map