@lakeql/query-builder 0.1.4 → 0.2.0

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { GraphQLResolveInfo } from "graphql";
 import { CompiledQuery, ExpressionBuilder, ExpressionWrapper, SelectExpression, SqlBool } from "kysely";
-
 //#region src/index.d.ts
 /**
  * Logical operators for combining filter conditions.
@@ -33,13 +32,17 @@ interface FieldOptions {
 /**
  * Defines the sort order for a query result.
  *
- * @template TableDefinition - The table type used to constrain the `field` to valid column names.
+ * @template TableDefinition - The table type used to constrain the `field` to valid column names. See [Introduction](/docs/query-builder/overview/introduction) for details.
  */
 interface SortInput<TableDefinition> {
-  /** Column name to sort by. Constrained to valid column names from the table type. */
+  /**
+   * Column name to sort by. Constrained to valid column names from the table type.
+   *
+   * @see {@link https://kysely-org.github.io/kysely-apidoc/types/SelectExpression.html | Kysely API Docs - SelectExpression}
+   */
   field: SelectExpression<KyselyDatabase<TableDefinition>, keyof KyselyDatabase<TableDefinition>>;
-  /** Sort direction — `"asc"` for ascending, `"desc"` for descending. */
-  direction: string;
+  /** Sort direction */
+  direction: "asc" | "desc";
 }
 /**
  * Controls offset-based pagination.
@@ -73,7 +76,7 @@ interface KyselyDatabase<TableDefinition> {
 /**
  * Parameters for generating a Trino-compatible SQL query from GraphQL resolve info.
  *
- * @template TableDefinition - The table type definition used by Kysely for type-safe column references.
+ * @template TableDefinition - The table type definition used by Kysely for type-safe column references. See [Introduction](/docs/query-builder/overview/introduction) for details.
  */
 interface GenerateQueryProps<TableDefinition> {
   /** The Trino catalog name (e.g. "hive"). */
@@ -82,7 +85,11 @@ interface GenerateQueryProps<TableDefinition> {
   schema: string;
   /** The table name to query. */
   table: string;
-  /** The columns to select, derived from GraphQL field selections. */
+  /**
+   * The columns to select, derived from GraphQL field selections.
+   *
+   * @see {@link https://kysely-org.github.io/kysely-apidoc/types/SelectExpression.html | Kysely API Docs - SelectExpression}
+   */
   selectFields: SelectExpression<KyselyDatabase<TableDefinition>, keyof KyselyDatabase<TableDefinition>>[];
   /** The user-provided filter query (WHERE clause). */
   userQuery: Where;
@@ -97,9 +104,16 @@ interface GenerateQueryProps<TableDefinition> {
 }
 /**
  * Parameters for building a single field comparison expression.
+ *
+ * @template TableDefinition - The table type definition. See [Introduction](/docs/query-builder/overview/introduction) for details.
  */
 interface GetFieldQueryProps<TableDefinition> {
-  /** The Kysely expression builder for constructing SQL expressions. */
+  /**
+   * The Kysely expression builder for constructing SQL expressions.
+   *
+   * @see {@link https://kysely.dev/docs/recipes/expressions | Kysely Docs - Expressions}
+   * @see {@link https://kysely-org.github.io/kysely-apidoc/interfaces/ExpressionBuilder.html | Kysely API Docs - ExpressionBuilder}
+   */
   eb: ExpressionBuilder<KyselyDatabase<TableDefinition>, "tablename">;
   /** The column name to filter on. */
   fieldName: string;
@@ -112,14 +126,9 @@ interface GetFieldQueryProps<TableDefinition> {
  * Builds a single field comparison expression for use in WHERE clauses.
  *
  * @param props - The field query parameters.
- * @returns A Kysely expression wrapper representing the comparison.
+ * @returns A Kysely [ExpressionWrapper](https://kysely-org.github.io/kysely-apidoc/classes/ExpressionWrapper.html) representing the comparison.
  */
-declare function getFieldQuery<TableDefinition>({
-  eb,
-  fieldName,
-  operator,
-  value
-}: GetFieldQueryProps<TableDefinition>): ExpressionWrapper<KyselyDatabase<TableDefinition>, "tablename", SqlBool>;
+declare function getFieldQuery<TableDefinition>({ eb, fieldName, operator, value }: GetFieldQueryProps<TableDefinition>): ExpressionWrapper<KyselyDatabase<TableDefinition>, "tablename", SqlBool>;
 /**
  * Normalizes filter objects by ensuring each field is in its own object within and/or arrays.
  *
@@ -143,33 +152,26 @@ declare function normalizeUserQuery(userQuery: Where): Where;
 /**
  * Generates a compiled SQL query with pagination metadata for Trino.
  *
- * Returns a Kysely `CompiledQuery` containing the generated SQL and parameters.
  * The query uses two CTEs internally:
  * - `total_count` — provides `total_records` (total matching rows before paging)
  * - `records` — the actual rows based on `selectFields`, filtering, sorting, and paging
  *
  * The compiled query is executed by the Trino client which returns the row data.
  *
- * @returns A compiled SQL query ready for execution via the Trino client.
- */
-declare function generateQuery<TableDefinition>({
-  catalog,
-  schema,
-  table,
-  selectFields,
-  userQuery,
-  sorting,
-  paging,
-  transformFields,
-  dateFields
-}: GenerateQueryProps<TableDefinition>): CompiledQuery<{
+ * @returns A [CompiledQuery](https://kysely-org.github.io/kysely-apidoc/interfaces/CompiledQuery.html) ready for execution via the Trino client.
+ */
+declare function generateQuery<TableDefinition>({ catalog, schema, table, selectFields, userQuery, sorting, paging, transformFields, dateFields }: GenerateQueryProps<TableDefinition>): CompiledQuery<{
   total_records: number;
 }>;
 /**
  * Parameters for formatting a compiled SQL query.
  */
 interface FormatQueryProps<T> {
-  /** The compiled Kysely query to format. */
+  /**
+   * The compiled Kysely query to format.
+   *
+   * @see {@link https://kysely-org.github.io/kysely-apidoc/interfaces/CompiledQuery.html | Kysely API Docs - CompiledQuery}
+   */
   query: CompiledQuery<T>;
 }
 /**
@@ -180,16 +182,25 @@ interface FormatQueryProps<T> {
  * @param props - The format query parameters.
  * @returns The formatted SQL string with interpolated parameters.
  */
-declare function formatQuery<T>({
-  query
-}: FormatQueryProps<T>): string;
+declare function formatQuery<T>({ query }: FormatQueryProps<T>): string;
+interface GetSelectFieldProps {
+  /**
+   * The GraphQL resolve info from the resolver.
+   *
+   * @see {@link https://the-guild.dev/graphql/tools/docs/api/utils/src/interfaces/graphqlresolveinfo | GraphQL Tools - GraphQLResolveInfo}
+   */
+  graphqlInfo: GraphQLResolveInfo;
+  /**
+   * When true, looks inside the `nodes` selection (for Connection types).
+   * @default false
+   */
+  withNodes?: boolean;
+}
 /**
  * Extracts selected field names from a GraphQL resolve info object.
  *
- * @param graphqlInfo - The GraphQL resolve info from the resolver.
- * @param withNodes - When true, looks inside the `nodes` selection (for Connection types).
  * @returns An array of field names to use as SELECT columns.
  */
-declare function getSelectFields<T>(graphqlInfo: GraphQLResolveInfo, withNodes?: boolean): GenerateQueryProps<T>["selectFields"];
+declare function getSelectFields<T>({ graphqlInfo, withNodes }: GetSelectFieldProps): GenerateQueryProps<T>["selectFields"];
 //#endregion
-export { Field, FieldOptions, FormatQueryProps, GenerateQueryProps, GetFieldQueryProps, PagingInput, SortInput, Where, WhereOperator, formatQuery, generateQuery, getFieldQuery, getSelectFields, normalizeFilter, normalizeUserQuery };
+export { Field, FieldOptions, FormatQueryProps, GenerateQueryProps, GetFieldQueryProps, GetSelectFieldProps, PagingInput, SortInput, Where, WhereOperator, formatQuery, generateQuery, getFieldQuery, getSelectFields, normalizeFilter, normalizeUserQuery };

package/dist/index.mjs

@@ -1 +1 @@
-import{GraphQLError as e}from"graphql";import{DummyDriver as t,Kysely as n,PostgresAdapter as r,PostgresIntrospector as i,PostgresQueryCompiler as a,sql as o}from"kysely";import{format as s}from"sql-formatter";const c=()=>new n({dialect:{createAdapter(){return new r},createDriver(){return new t},createIntrospector(e){return new i(e)},createQueryCompiler(){return new a}}});let l=function(e){return e.AND=`and`,e.OR=`or`,e}({});const u={eq:`=`,gt:`>`,gte:`>=`,in:`in`,is:`=`,isnot:`!=`,lt:`<`,lte:`<=`,neq:`!=`,notin:`not in`};function d({eb:e,fieldName:t,operator:n,value:r}){let i=t,a=n.toLowerCase();switch(a){case`eq`:case`neq`:case`lt`:case`lte`:case`gt`:case`gte`:case`is`:case`isnot`:return e(o.id(i),u[a]??`=`,r);case`in`:case`notin`:return e(o.id(i),u[a]??`=`,r);case`like`:return e(o.id(i),`like`,`%${r}%`);case`notlike`:return e.not(e(o.id(i),`like`,`%${r}%`));case`startswith`:return e(o.id(i),`like`,`${r}%`);case`notstartswith`:return e.not(e(o.id(i),`like`,`${r}%`));case`endswith`:return e(o.id(i),`like`,`%${r}`);case`notendswith`:return e.not(e(o.id(i),`like`,`%${r}`));default:return e(o.id(i),`=`,r)}}function f({eb:e,query:t,transformFields:n}){let r=[];for(let[i,a]of Object.entries(t))switch(i.toLowerCase()){case`and`:for(let t of a){let i=f({eb:e,query:t,transformFields:n});i!==void 0&&r.push(i)}return e.and(r);case`or`:for(let t of a){let i=f({eb:e,query:t,transformFields:n});i&&r.push(i)}return e.or(r);default:{let[t,r]=Object.entries(a).flat();return d({eb:e,fieldName:n?.[i]??i,operator:t,value:r})}}}function p(e){if(!e)return e;let t={...e};return t.and&&Array.isArray(t.and)&&(t.and=t.and.flatMap(e=>{let t=e,n=Object.keys(t),r=n.filter(e=>e===`and`||e===`or`),i=n.filter(e=>e!==`and`&&e!==`or`);if(i.length>0&&r.length>0){let e=i.map(e=>({[e]:t[e]})),n=r.map(e=>({[e]:p({[e]:t[e]})[e]}));return[...e,...n]}if(i.length>1&&r.length===0)return i.map(e=>({[e]:t[e]}));if(r.length>0){let e={...t};for(let n of r)e[n]=p({[n]:t[n]})[n];return e}return e})),t.or&&Array.isArray(t.or)&&(t.or=t.or.flatMap(e=>{let t=e,n=Object.keys(t),r=n.filter(e=>e===`and`||e===`or`),i=n.filter(e=>e!==`and`&&e!==`or`);if(i.length>0&&r.length>0){let e=i.map(e=>({[e]:t[e]})),n=r.map(e=>({[e]:p({[e]:t[e]})[e]}));return[...e,...n]}if(i.length>1&&r.length===0)return i.map(e=>({[e]:t[e]}));if(r.length>0){let e={...t};for(let n of r)e[n]=p({[n]:t[n]})[n];return e}return e})),t}function m(e){let t=Object.keys(e);return t.length===1&&(t[0]===`and`||t[0]===`or`)?e:{and:Object.entries(e).map(([e,t])=>({[e]:t}))}}function h({catalog:e,schema:t,table:n,selectFields:r,userQuery:i,sorting:a,paging:s,transformFields:l,dateFields:u=[]}){let d=c(),{ref:h}=d.dynamic;return d.with(`total_count`,r=>r.selectFrom(o.id(e,t,n)).select(({fn:e})=>e.countAll().as(`total_records`)).$if(Object.keys(i).length>0,e=>e.where(e=>f({eb:e,query:p(m(i)),transformFields:l})??e.and([])))).with(`records`,c=>{let d=c.selectFrom(o.id(e,t,n)).select(r.map(e=>u.includes(e)?l?.[e]?o.raw(`to_unixtime(${l[e]})`).as(l[e]):o.raw(`to_unixtime(${e})`).as(e):l?.[e]?o.id(l[e]).as(l[e]):typeof e==`string`?h(e):e)).$if(Object.keys(i).length>0,e=>e.where(e=>f({eb:e,query:p(m(i)),transformFields:l})??e.and([])));for(let e of a){let t=l?.[e.field]||e.field;d=d.orderBy(t,e.direction.toLowerCase())}return d=!s?.offset||s.offset<=0?d.modifyEnd(o.raw(`FETCH FIRST ${s?.limit??100} ROWS ONLY`)):d.offset(s.offset??100).modifyEnd(o.raw(`FETCH NEXT ${s.limit??100} ROWS ONLY`)),d}).selectFrom(`total_count`).selectAll().fullJoin(`records`,e=>e.onTrue()).compile()}function g({query:e}){let t={};for(let[n,r]of e.parameters.entries())t[n+1]=String(typeof r==`string`?`'${r}'`:r);return s(e.sql,{keywordCase:`upper`,language:`postgresql`,params:t,tabWidth:0,useTabs:!1})}function _(t,n=!1){return t.fieldNodes.flatMap(t=>{let r=t.selectionSet?.selections,i=[];if(n){let t=r.find(e=>e.name.value===`nodes`);if(!t)throw new e("No fields to return defined. Please specify at least one field inside `nodes`.");i=t.selectionSet?.selections??[]}else i=t.selectionSet?.selections??[];return i.flatMap(e=>e.name.value)})}export{l as WhereOperator,g as formatQuery,h as generateQuery,d as getFieldQuery,_ as getSelectFields,p as normalizeFilter,m as normalizeUserQuery};
+import{GraphQLError as e}from"graphql";import{DummyDriver as t,Kysely as n,PostgresAdapter as r,PostgresIntrospector as i,PostgresQueryCompiler as a,sql as o}from"kysely";import{format as s}from"sql-formatter";const c=()=>new n({dialect:{createAdapter(){return new r},createDriver(){return new t},createIntrospector(e){return new i(e)},createQueryCompiler(){return new a}}});let l=function(e){return e.AND=`and`,e.OR=`or`,e}({});const u={eq:`=`,gt:`>`,gte:`>=`,in:`in`,is:`=`,isnot:`!=`,lt:`<`,lte:`<=`,neq:`!=`,notin:`not in`};function d({eb:e,fieldName:t,operator:n,value:r}){let i=t,a=n.toLowerCase();switch(a){case`eq`:case`neq`:case`lt`:case`lte`:case`gt`:case`gte`:case`is`:case`isnot`:return e(o.id(i),u[a]??`=`,r);case`in`:case`notin`:return e(o.id(i),u[a]??`=`,r);case`like`:return e(o.id(i),`like`,`%${r}%`);case`notlike`:return e.not(e(o.id(i),`like`,`%${r}%`));case`startswith`:return e(o.id(i),`like`,`${r}%`);case`notstartswith`:return e.not(e(o.id(i),`like`,`${r}%`));case`endswith`:return e(o.id(i),`like`,`%${r}`);case`notendswith`:return e.not(e(o.id(i),`like`,`%${r}`));default:return e(o.id(i),`=`,r)}}function f({eb:e,query:t,transformFields:n}){let r=[];for(let[i,a]of Object.entries(t))switch(i.toLowerCase()){case`and`:for(let t of a){let i=f({eb:e,query:t,transformFields:n});i!==void 0&&r.push(i)}return e.and(r);case`or`:for(let t of a){let i=f({eb:e,query:t,transformFields:n});i&&r.push(i)}return e.or(r);default:{let[t,r]=Object.entries(a).flat();return d({eb:e,fieldName:n?.[i]??i,operator:t,value:r})}}}function p(e){if(!e)return e;let t={...e};return t.and&&Array.isArray(t.and)&&(t.and=t.and.flatMap(e=>{let t=e,n=Object.keys(t),r=n.filter(e=>e===`and`||e===`or`),i=n.filter(e=>e!==`and`&&e!==`or`);if(i.length>0&&r.length>0){let e=i.map(e=>({[e]:t[e]})),n=r.map(e=>({[e]:p({[e]:t[e]})[e]}));return[...e,...n]}if(i.length>1&&r.length===0)return i.map(e=>({[e]:t[e]}));if(r.length>0){let e={...t};for(let n of r)e[n]=p({[n]:t[n]})[n];return e}return e})),t.or&&Array.isArray(t.or)&&(t.or=t.or.flatMap(e=>{let t=e,n=Object.keys(t),r=n.filter(e=>e===`and`||e===`or`),i=n.filter(e=>e!==`and`&&e!==`or`);if(i.length>0&&r.length>0){let e=i.map(e=>({[e]:t[e]})),n=r.map(e=>({[e]:p({[e]:t[e]})[e]}));return[...e,...n]}if(i.length>1&&r.length===0)return i.map(e=>({[e]:t[e]}));if(r.length>0){let e={...t};for(let n of r)e[n]=p({[n]:t[n]})[n];return e}return e})),t}function m(e){let t=Object.keys(e);return t.length===1&&(t[0]===`and`||t[0]===`or`)?e:{and:Object.entries(e).map(([e,t])=>({[e]:t}))}}function h({catalog:e,schema:t,table:n,selectFields:r,userQuery:i,sorting:a,paging:s,transformFields:l,dateFields:u=[]}){let d=c(),{ref:h}=d.dynamic;return d.with(`total_count`,r=>r.selectFrom(o.id(e,t,n)).select(({fn:e})=>e.countAll().as(`total_records`)).$if(Object.keys(i).length>0,e=>e.where(e=>f({eb:e,query:p(m(i)),transformFields:l})??e.and([])))).with(`records`,c=>{let d=c.selectFrom(o.id(e,t,n)).select(r.map(e=>u.includes(e)?l?.[e]?o.raw(`to_unixtime(${l[e]})`).as(l[e]):o.raw(`to_unixtime(${e})`).as(e):l?.[e]?o.id(l[e]).as(l[e]):typeof e==`string`?h(e):e)).$if(Object.keys(i).length>0,e=>e.where(e=>f({eb:e,query:p(m(i)),transformFields:l})??e.and([])));for(let e of a){let t=l?.[e.field]||e.field;d=d.orderBy(t,e.direction.toLowerCase())}return d=!s?.offset||s.offset<=0?d.modifyEnd(o.raw(`FETCH FIRST ${s?.limit??100} ROWS ONLY`)):d.offset(s.offset??100).modifyEnd(o.raw(`FETCH NEXT ${s.limit??100} ROWS ONLY`)),d}).selectFrom(`total_count`).selectAll().fullJoin(`records`,e=>e.onTrue()).compile()}function g({query:e}){let t={};for(let[n,r]of e.parameters.entries())t[n+1]=String(typeof r==`string`?`'${r}'`:r);return s(e.sql,{keywordCase:`upper`,language:`postgresql`,params:t,tabWidth:0,useTabs:!1})}function _({graphqlInfo:t,withNodes:n=!1}){return t.fieldNodes.flatMap(t=>{let r=t.selectionSet?.selections,i=[];if(n){let t=r.find(e=>e.name.value===`nodes`);if(!t)throw new e("No fields to return defined. Please specify at least one field inside `nodes`.");i=t.selectionSet?.selections??[]}else i=t.selectionSet?.selections??[];return i.flatMap(e=>e.name.value)})}export{l as WhereOperator,g as formatQuery,h as generateQuery,d as getFieldQuery,_ as getSelectFields,p as normalizeFilter,m as normalizeUserQuery};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakeql/query-builder",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Kysely-based SQL query builder that translates GraphQL queries into Trino SQL",
   "keywords": [
     "graphql",
@@ -41,16 +41,16 @@
   },
   "dependencies": {
     "date-fns": "4.4.0",
-    "kysely": "0.29.2",
-    "sql-formatter": "15.8.1"
+    "kysely": "0.29.4",
+    "sql-formatter": "15.8.2"
   },
   "devDependencies": {
-    "@pothos/core": "4.12.0",
-    "@types/node": "24.13.2",
+    "@pothos/core": "4.13.1",
+    "@types/node": "24.13.3",
     "graphql": "16.14.2",
-    "tsdown": "0.22.3",
+    "tsdown": "0.22.13",
     "typescript": "6.0.3",
-    "vitest": "4.1.9",
+    "vitest": "4.1.10",
     "@lakeql/tsconfig": "0.1.0"
   },
   "scripts": {