@lakeql/query-builder 0.1.1 → 0.1.2

package/dist/index.d.mts

@@ -2,10 +2,20 @@ import { GraphQLResolveInfo } from "graphql";
 import { CompiledQuery, ExpressionBuilder, ExpressionWrapper, SelectExpression, SqlBool } from "kysely";
 
 //#region src/index.d.ts
+/**
+ * Logical operators for combining filter conditions.
+ */
 declare enum WhereOperator {
   AND = "and",
   OR = "or"
 }
+/**
+ * Comparison operators available for filtering a single field.
+ * Only one operator should be set per FieldOptions object.
+ *
+ * String operators compare the field value against the provided string.
+ * Boolean operators (`is`/`isNot`) check for equality with `true`/`false`.
+ */
 interface FieldOptions {
   eq?: string;
   neq?: string;
@@ -20,15 +30,32 @@ interface FieldOptions {
   is?: boolean;
   isNot?: boolean;
 }
+/**
+ * Defines the sort order for a query result.
+ *
+ * @template TableDefinition - The table type used to constrain the `field` to valid column names.
+ */
 interface SortInput<TableDefinition> {
   field: SelectExpression<KyselyDatabase<TableDefinition>, keyof KyselyDatabase<TableDefinition>>;
   direction: string;
 }
+/**
+ * Controls offset-based pagination.
+ * When `limit` is not specified, defaults to 100 rows.
+ */
 interface PagingInput {
   limit?: number;
   offset?: number;
 }
+/**
+ * A single field condition — a record where the key is the field name
+ * and the value is a [FieldOptions](#field-options) object describing the comparison.
+ */
 type Field = Record<string, FieldOptions>;
+/**
+ * A recursive filter structure that can contain AND/OR groups,
+ * each holding field conditions or further nested groups.
+ */
 type Where = Partial<Record<WhereOperator, (Where | Field)[]>>;
 /**
  * KyselyDatabase is our generic interface which simulates
@@ -38,37 +65,74 @@ interface KyselyDatabase<TableDefinition> {
   tablename: TableDefinition;
 }
 /**
- * We have to pass `TableDefinition` since we use some
- * kysely types e.g. to get the select fields
- * i don't think this is required, but it seems to be the right solution,
- * because we don't have to use `@ts-ignore` or `@ts-expect-error`
+ * 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.
  */
 interface GenerateQueryProps<TableDefinition> {
+  /** The Trino catalog name (e.g. "hive"). */
   catalog: string;
+  /** The Trino schema name (e.g. "sales"). */
   schema: string;
+  /** The table name to query. */
   table: string;
+  /** The columns to select, derived from GraphQL field selections. */
   selectFields: SelectExpression<KyselyDatabase<TableDefinition>, keyof KyselyDatabase<TableDefinition>>[];
+  /** The user-provided filter query (WHERE clause). */
   userQuery: Where;
+  /** Pagination parameters (limit and offset). */
   paging?: PagingInput;
+  /** Sort order definitions. */
   sorting: SortInput<TableDefinition>[];
+  /** Maps GraphQL field names to database column names. */
   transformFields?: Record<string, string>;
+  /** Fields that should be wrapped in `to_unixtime()` for date conversion. */
   dateFields?: string[];
 }
+/**
+ * Parameters for building a single field comparison expression.
+ */
+interface GetFieldQueryProps<TableDefinition> {
+  /** The Kysely expression builder for constructing SQL expressions. */
+  eb: ExpressionBuilder<KyselyDatabase<TableDefinition>, "tablename">;
+  /** The column name to filter on. */
+  fieldName: string;
+  /** The comparison operator (eq, neq, lt, like, etc.). */
+  operator: string;
+  /** The value to compare against. */
+  value: unknown;
+}
+/**
+ * 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.
+ */
 declare function getFieldQuery<TableDefinition>({
   eb,
   fieldName,
   operator,
   value
-}: {
-  eb: ExpressionBuilder<KyselyDatabase<TableDefinition>, "tablename">;
-  fieldName: string;
-  operator: string;
-  value: unknown;
-}): ExpressionWrapper<KyselyDatabase<TableDefinition>, "tablename", SqlBool>;
+}: GetFieldQueryProps<TableDefinition>): ExpressionWrapper<KyselyDatabase<TableDefinition>, "tablename", SqlBool>;
 /**
- * Normalizes filter objects by ensuring each field is in its own object within and/or arrays
+ * Normalizes filter objects by ensuring each field is in its own object within and/or arrays.
+ *
+ * Splits multi-field filter objects into separate entries so the query builder
+ * can process each field condition independently.
+ *
+ * @param filter - The filter object to normalize.
+ * @returns A normalized filter with individual field entries.
  */
 declare function normalizeFilter(filter: Where): Where;
+/**
+ * Wraps bare field-level filters into an AND-rooted structure.
+ *
+ * If the query already has a single `and` or `or` key at the root, it is returned as-is.
+ * Otherwise, all entries are combined under an `and` key.
+ *
+ * @param userQuery - The user-provided filter query.
+ * @returns A normalized query with a logical operator at the root.
+ */
 declare function normalizeUserQuery(userQuery: Where): Where;
 declare function generateQuery<TableDefinition>({
   catalog,
@@ -83,11 +147,31 @@ declare function generateQuery<TableDefinition>({
 }: GenerateQueryProps<TableDefinition>): CompiledQuery<{
   total_records: number;
 }>;
+/**
+ * Parameters for formatting a compiled SQL query.
+ */
+interface FormatQueryProps<T> {
+  /** The compiled Kysely query to format. */
+  query: CompiledQuery<T>;
+}
+/**
+ * Formats a compiled SQL query for readability.
+ *
+ * Applies uppercase keywords, PostgreSQL dialect, and interpolates parameters.
+ *
+ * @param props - The format query parameters.
+ * @returns The formatted SQL string with interpolated parameters.
+ */
 declare function formatQuery<T>({
   query
-}: {
-  query: CompiledQuery<T>;
-}): string;
+}: FormatQueryProps<T>): string;
+/**
+ * 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"];
 //#endregion
-export { Field, FieldOptions, PagingInput, SortInput, Where, WhereOperator, formatQuery, generateQuery, getFieldQuery, getSelectFields, normalizeFilter, normalizeUserQuery };
+export { Field, FieldOptions, FormatQueryProps, GenerateQueryProps, GetFieldQueryProps, PagingInput, SortInput, Where, WhereOperator, formatQuery, generateQuery, getFieldQuery, getSelectFields, normalizeFilter, normalizeUserQuery };

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@lakeql/query-builder",
-  "version": "0.1.1",
+  "version": "0.1.2",
+  "description": "Kysely-based SQL query builder that translates GraphQL queries into Trino SQL",
+  "keywords": [
+    "graphql",
+    "kysely",
+    "lakeql",
+    "query-builder",
+    "sql",
+    "trino"
+  ],
   "homepage": "https://lakeql.dev",
   "license": "Apache-2.0",
   "author": {