@gblikas/querykit 0.0.0 → 0.2.0

package/.github/workflows/publish.yml

@@ -18,18 +18,18 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      id-token: write  # Required for NPM Trusted Publishers (OIDC)
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.release.tag_name }}
+          ref: ${{ github.event.release.tag_name || inputs.tag }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
-          always-auth: true
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v3
@@ -53,9 +53,7 @@ jobs:
           TAG: ${{ github.event.release.tag_name || inputs.tag }}
         run: node -e 'const v=require("./package.json").version; const tag=(process.env.TAG||"").replace(/^v/,""); if(v!==tag){console.error("package.json version "+v+" does not match tag "+tag); process.exit(1)} else {console.log("Version matches tag:", v)}'
 
-      - name: Publish package to npmjs
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: pnpm publish --no-git-checks --access public
+      - name: Publish package to npmjs with provenance
+        run: pnpm publish --no-git-checks --access public --provenance
 
 

package/README.md

@@ -124,6 +124,16 @@ const qk = createQueryKit({
     allowedFields: ['name', 'email', 'priority', 'status'], // Only these fields can be queried
     denyFields: ['password', 'secretKey'],            // These fields can never be queried
     
+    // Value restrictions - deny specific values for fields
+    denyValues: {
+      status: ['deleted', 'banned'],      // Block queries for deleted/banned records
+      role: ['superadmin', 'system'],     // Prevent querying privileged roles
+      'user.type': ['internal', 'bot']    // Supports dot-notation for nested fields
+    },
+    
+    // Field name restrictions
+    allowDotNotation: true,    // Set to false to block "table.field" or "json.path" queries
+    
     // Query complexity limits
     maxQueryDepth: 5,          // Maximum nesting level of expressions
     maxClauseCount: 20,        // Maximum number of clauses (AND/OR operations)
@@ -150,6 +160,8 @@ const DEFAULT_SECURITY = {
   // Field restrictions - by default, all schema fields are allowed
   allowedFields: [],           // Empty means "use schema fields"
   denyFields: [],              // Empty means no denied fields
+  denyValues: {},              // Empty means no denied values for any field
+  allowDotNotation: true,      // Allow "table.field" and "json.path" notation
   
   // Query complexity limits
   maxQueryDepth: 10,           // Maximum nesting level of expressions
@@ -174,6 +186,10 @@ Security configurations can be stored in a separate file and imported:
 // security-config.json
 {
   "allowedFields": ["name", "email", "priority", "status"],
+  "denyValues": {
+    "status": ["deleted", "banned"],
+    "role": ["superadmin", "system"]
+  },
   "maxQueryDepth": 5,
   "maxClauseCount": 20,
   "defaultLimit": 100
@@ -199,6 +215,66 @@ When using QueryKit in production, consider these additional security practices:
 4. **Field-Level Access Control**: Use dynamic allowedFields based on user roles/permissions.
 5. **Separate Query Context**: Consider separate QueryKit instances with different security settings for different contexts (admin vs. user).
 
+### Controlling Dot Notation in Field Names
+
+QueryKit supports dot notation in field names (e.g., `user.name`, `metadata.tags`) which is useful for:
+
+- **Table-qualified columns**: When joining tables with overlapping column names (`users.id` vs `orders.id`)
+- **JSON/JSONB fields**: Querying nested data in PostgreSQL JSON columns (`metadata.dimensions.width`)
+- **Related data**: Accessing data through ORM relations (`order.customer.name`)
+
+However, you may want to **disable dot notation** for public-facing APIs:
+
+```typescript
+const qk = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { products },
+  security: {
+    allowDotNotation: false,  // Reject queries like "user.password" or "config.secret"
+    allowedFields: ['name', 'price', 'category', 'inStock']
+  }
+});
+
+// ✅ Allowed: Simple field names
+qk.query('products').where('name:"Widget" AND price:<100');
+
+// ❌ Rejected: Dot notation
+qk.query('products').where('user.password:"secret"');
+// Error: Dot notation is not allowed in field names. Found "user.password" - use a simple field name without dots instead.
+```
+
+**When to disable dot notation:**
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Public search API | Disable - prevents probing internal table structures |
+| Admin dashboard | Enable - admins may need cross-table queries |
+| Simple flat schema | Disable - simplifies security model |
+| JSON/JSONB columns | Enable - needed for nested data access |
+| Multi-tenant app | Disable - prevents `tenant.secret` style access |
+
+**Concrete example - Public e-commerce search:**
+
+```typescript
+// For a public product search endpoint, disable dot notation
+// to prevent users from attempting queries like:
+// - "orders.creditCard" (accessing other tables)
+// - "internal.costPrice" (accessing internal JSON fields)
+// - "admin.notes" (accessing admin-only data)
+
+const publicSearchKit = createQueryKit({
+  adapter: drizzleAdapter,
+  schema: { products },
+  security: {
+    allowDotNotation: false,
+    allowedFields: ['name', 'description', 'price', 'category'],
+    denyValues: {
+      category: ['internal', 'discontinued']
+    }
+  }
+});
+```
+
 ## Roadmap
 
 ### Core Parsing Engine and DSL

package/dist/parser/parser.d.ts

@@ -15,6 +15,35 @@ export declare class QueryParser implements IQueryParser {
      * Parse a query string into a QueryKit AST
      */
     parse(query: string): QueryExpression;
+    /**
+     * Pre-process a query string to convert non-standard syntax to Liqe-compatible syntax.
+     * Supports:
+     * - `field:[val1, val2, val3]` → `(field:val1 OR field:val2 OR field:val3)`
+     *
+     * This keeps the syntax consistent with the `key:value` pattern used throughout QueryKit:
+     * - `priority:>2` (comparison)
+     * - `status:active` (equality)
+     * - `status:[todo, doing, done]` (IN / multiple values)
+     */
+    private preprocessQuery;
+    /**
+     * Convert a field and comma-separated values to an OR expression string
+     */
+    private convertToOrExpression;
+    /**
+     * Parse a comma-separated string into values, respecting quoted strings.
+     * Commas inside quoted strings are preserved as part of the value.
+     *
+     * Examples:
+     * - `a, b, c` → ['a', 'b', 'c']
+     * - `"John, Jr.", Jane` → ['"John, Jr."', 'Jane']
+     * - `'hello, world', test` → ["'hello, world'", 'test']
+     */
+    private parseCommaSeparatedValues;
+    /**
+     * Format a field:value pair, quoting the value if necessary
+     */
+    private formatFieldValue;
     /**
      * Validate a query string
      */
@@ -35,6 +64,11 @@ export declare class QueryParser implements IQueryParser {
      * Create a comparison expression
      */
     private createComparisonExpression;
+    /**
+     * Convert a Liqe RangeExpression to a QueryKit logical AND expression
+     * E.g., `field:[2 TO 5]` becomes `(field >= 2 AND field <= 5)`
+     */
+    private convertRangeExpression;
     /**
      * Convert a Liqe operator to a QueryKit operator
      */

package/dist/parser/parser.js

@@ -27,19 +27,142 @@ class QueryParser {
      */
     parse(query) {
         try {
-            const liqeAst = (0, liqe_1.parse)(query);
+            // Pre-process the query to handle IN operator syntax
+            const preprocessedQuery = this.preprocessQuery(query);
+            const liqeAst = (0, liqe_1.parse)(preprocessedQuery);
             return this.convertLiqeAst(liqeAst);
         }
         catch (error) {
             throw new QueryParseError(`Failed to parse query: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    /**
+     * Pre-process a query string to convert non-standard syntax to Liqe-compatible syntax.
+     * Supports:
+     * - `field:[val1, val2, val3]` → `(field:val1 OR field:val2 OR field:val3)`
+     *
+     * This keeps the syntax consistent with the `key:value` pattern used throughout QueryKit:
+     * - `priority:>2` (comparison)
+     * - `status:active` (equality)
+     * - `status:[todo, doing, done]` (IN / multiple values)
+     */
+    preprocessQuery(query) {
+        let result = query;
+        // Handle `field:[val1, val2, ...]` syntax (array-like, not range)
+        // Pattern: fieldName:[value1, value2, ...]
+        // We distinguish from range by checking for commas without "TO"
+        const bracketArrayPattern = /(\w+):\[([^\]]+)\]/g;
+        result = result.replace(bracketArrayPattern, (fullMatch, field, values) => {
+            // Check if this looks like a range expression (contains " TO ")
+            if (/\s+TO\s+/i.test(values)) {
+                // This is a range expression, keep as-is
+                return fullMatch;
+            }
+            // This is an array-like expression, convert to OR
+            return this.convertToOrExpression(field, values);
+        });
+        return result;
+    }
+    /**
+     * Convert a field and comma-separated values to an OR expression string
+     */
+    convertToOrExpression(field, valuesStr) {
+        // Parse values respecting quoted strings (commas inside quotes are preserved)
+        const values = this.parseCommaSeparatedValues(valuesStr);
+        if (values.length === 0) {
+            return `${field}:""`;
+        }
+        if (values.length === 1) {
+            return this.formatFieldValue(field, values[0]);
+        }
+        // Build OR expression: (field:val1 OR field:val2 OR ...)
+        const orClauses = values.map((v) => this.formatFieldValue(field, v));
+        return `(${orClauses.join(' OR ')})`;
+    }
+    /**
+     * Parse a comma-separated string into values, respecting quoted strings.
+     * Commas inside quoted strings are preserved as part of the value.
+     *
+     * Examples:
+     * - `a, b, c` → ['a', 'b', 'c']
+     * - `"John, Jr.", Jane` → ['"John, Jr."', 'Jane']
+     * - `'hello, world', test` → ["'hello, world'", 'test']
+     */
+    parseCommaSeparatedValues(input) {
+        const values = [];
+        let current = '';
+        let inDoubleQuotes = false;
+        let inSingleQuotes = false;
+        let i = 0;
+        while (i < input.length) {
+            const char = input[i];
+            const nextChar = input[i + 1];
+            // Handle escape sequences inside quotes
+            if ((inDoubleQuotes || inSingleQuotes) && char === '\\' && nextChar) {
+                // Include both the backslash and the escaped character
+                current += char + nextChar;
+                i += 2;
+                continue;
+            }
+            // Toggle double quote state
+            if (char === '"' && !inSingleQuotes) {
+                inDoubleQuotes = !inDoubleQuotes;
+                current += char;
+                i++;
+                continue;
+            }
+            // Toggle single quote state
+            if (char === "'" && !inDoubleQuotes) {
+                inSingleQuotes = !inSingleQuotes;
+                current += char;
+                i++;
+                continue;
+            }
+            // Handle comma as separator (only when not inside quotes)
+            if (char === ',' && !inDoubleQuotes && !inSingleQuotes) {
+                const trimmed = current.trim();
+                if (trimmed.length > 0) {
+                    values.push(trimmed);
+                }
+                current = '';
+                i++;
+                continue;
+            }
+            // Regular character
+            current += char;
+            i++;
+        }
+        // Don't forget the last value
+        const trimmed = current.trim();
+        if (trimmed.length > 0) {
+            values.push(trimmed);
+        }
+        return values;
+    }
+    /**
+     * Format a field:value pair, quoting the value if necessary
+     */
+    formatFieldValue(field, value) {
+        // If the value is already quoted, use it as-is
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            return `${field}:${value}`;
+        }
+        // If value contains spaces or special characters, quote it
+        if (/\s|[():]/.test(value)) {
+            // Escape quotes within the value
+            const escapedValue = value.replace(/"/g, '\\"');
+            return `${field}:"${escapedValue}"`;
+        }
+        return `${field}:${value}`;
+    }
     /**
      * Validate a query string
      */
     validate(query) {
         try {
-            const ast = (0, liqe_1.parse)(query);
+            const preprocessedQuery = this.preprocessQuery(query);
+            const ast = (0, liqe_1.parse)(preprocessedQuery);
             this.convertLiqeAst(ast);
             return true;
         }
@@ -72,10 +195,16 @@ class QueryParser {
                     throw new QueryParseError('Invalid field or expression in Tag node');
                 }
                 const fieldName = this.normalizeFieldName(field.name);
+                // Handle RangeExpression (e.g., field:[min TO max])
+                if (expression.type === 'RangeExpression') {
+                    return this.convertRangeExpression(fieldName, expression);
+                }
                 const operator = this.convertLiqeOperator(tagNode.operator.operator);
                 const value = this.convertLiqeValue(expression.value);
                 // Check for wildcard patterns in string values
-                if (operator === '==' && typeof value === 'string' && (value.includes('*') || value.includes('?'))) {
+                if (operator === '==' &&
+                    typeof value === 'string' &&
+                    (value.includes('*') || value.includes('?'))) {
                     return this.createComparisonExpression(fieldName, 'LIKE', value);
                 }
                 return this.createComparisonExpression(fieldName, operator, value);
@@ -133,6 +262,31 @@ class QueryParser {
             value
         };
     }
+    /**
+     * Convert a Liqe RangeExpression to a QueryKit logical AND expression
+     * E.g., `field:[2 TO 5]` becomes `(field >= 2 AND field <= 5)`
+     */
+    convertRangeExpression(fieldName, expression) {
+        const range = expression.range;
+        // Handle null/undefined range values
+        if (range === null || range === undefined) {
+            throw new QueryParseError('Invalid range expression: missing range data');
+        }
+        const { min, max, minInclusive, maxInclusive } = range;
+        // Determine the operators based on inclusivity
+        const minOperator = minInclusive ? '>=' : '>';
+        const maxOperator = maxInclusive ? '<=' : '<';
+        // Create comparison expressions for min and max
+        const minComparison = this.createComparisonExpression(fieldName, minOperator, min);
+        const maxComparison = this.createComparisonExpression(fieldName, maxOperator, max);
+        // Combine with AND
+        return {
+            type: 'logical',
+            operator: 'AND',
+            left: minComparison,
+            right: maxComparison
+        };
+    }
     /**
      * Convert a Liqe operator to a QueryKit operator
      */
@@ -142,7 +296,9 @@ class QueryParser {
             return '==';
         }
         // Check if the operator is prefixed with a colon
-        const actualOperator = operator.startsWith(':') ? operator.substring(1) : operator;
+        const actualOperator = operator.startsWith(':')
+            ? operator.substring(1)
+            : operator;
         // Map Liqe operators to QueryKit operators
         const operatorMap = {
             '=': '==',
@@ -151,7 +307,7 @@ class QueryParser {
             '>=': '>=',
             '<': '<',
             '<=': '<=',
-            'in': 'IN',
+            in: 'IN',
             'not in': 'NOT IN'
         };
         const queryKitOperator = operatorMap[actualOperator.toLowerCase()];
@@ -169,7 +325,9 @@ class QueryParser {
         if (value === null) {
             return null;
         }
-        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        if (typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean') {
             return value;
         }
         if (Array.isArray(value)) {

package/dist/security/types.d.ts

@@ -54,6 +54,54 @@ export interface ISecurityOptions {
      * ```
      */
     denyFields?: string[];
+    /**
+     * Map of field names to arrays of values that are denied for that field.
+     * This provides granular control over what values can be used in queries.
+     * Use this to protect against queries targeting specific sensitive values.
+     *
+     * The keys are field names (can include table prefixes like "user.role")
+     * and the values are arrays of denied values for that field.
+     *
+     * @example
+     * ```typescript
+     * // Prevent certain values from being queried
+     * denyValues: {
+     *   'status': ['deleted', 'banned'],
+     *   'role': ['superadmin', 'system'],
+     *   'user.type': ['internal', 'bot']
+     * }
+     *
+     * // This would block queries like:
+     * // status == "deleted"
+     * // role IN ["superadmin", "admin"]
+     * // user.type == "internal"
+     * ```
+     */
+    denyValues?: Record<string, Array<string | number | boolean | null>>;
+    /**
+     * Whether to allow dot notation in field names (e.g., "user.name", "metadata.tags").
+     * When disabled, queries with dots in field names will be rejected.
+     *
+     * Use cases for DISABLING dot notation:
+     * - Public-facing search APIs where users should only query flat, top-level fields
+     * - Preventing access to table-qualified columns in SQL joins (e.g., "users.password")
+     * - Simpler security model when your schema doesn't have nested/JSON data
+     * - Preventing users from probing internal table structures
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // Disable dot notation for a public search API
+     * allowDotNotation: false
+     *
+     * // This would block queries like:
+     * // user.email == "test@example.com"  // Rejected
+     * // metadata.tags == "sale"           // Rejected
+     * // email == "test@example.com"       // Allowed
+     * ```
+     */
+    allowDotNotation?: boolean;
     /**
      * Maximum nesting depth of query expressions.
      * Prevents deeply nested queries that could impact performance.

package/dist/security/types.js

@@ -29,6 +29,8 @@ exports.DEFAULT_SECURITY_OPTIONS = {
     // Field restrictions - by default, all schema fields are allowed
     allowedFields: [], // Empty means "use schema fields"
     denyFields: [], // Empty means no denied fields
+    denyValues: {}, // Empty means no denied values for any field
+    allowDotNotation: true, // Allow dot notation by default for backward compatibility
     // Query complexity limits
     maxQueryDepth: 10, // Maximum nesting level of expressions
     maxClauseCount: 50, // Maximum number of clauses (AND/OR operations)

package/dist/security/validator.d.ts

@@ -141,6 +141,41 @@ export declare class QuerySecurityValidator {
      * @param schema - Optional schema definition to validate fields against
      */
     private validateFields;
+    /**
+     * Validate that field names do not contain dot notation
+     *
+     * When allowDotNotation is disabled, this method ensures no field names
+     * contain dots, which could be used for:
+     * - Table-qualified column access (e.g., "users.password")
+     * - Nested JSON/JSONB field access (e.g., "metadata.secret")
+     * - Probing internal table structures
+     *
+     * @private
+     * @param expression - The query expression to validate
+     * @throws {QuerySecurityError} If a field name contains dot notation
+     */
+    private validateNoDotNotation;
+    /**
+     * Validate that query values are not in the denied values list for their field
+     *
+     * This method checks each comparison expression to ensure the value being
+     * queried is not in the denyValues list for that field. This provides
+     * granular control over what values can be queried for specific fields.
+     *
+     * @private
+     * @param expression - The query expression to validate
+     * @throws {QuerySecurityError} If a denied value is found in the query
+     */
+    private validateDenyValues;
+    /**
+     * Check if a value is in the denied values list
+     *
+     * @private
+     * @param value - The value to check
+     * @param deniedValues - The list of denied values
+     * @returns true if the value is denied, false otherwise
+     */
+    private isValueDenied;
     /**
      * Validate that query depth does not exceed the maximum
      *

package/dist/security/validator.js

@@ -143,8 +143,14 @@ class QuerySecurityValidator {
      * ```
      */
     validate(expression, schema) {
+        // Check for dot notation if disabled
+        if (!this.options.allowDotNotation) {
+            this.validateNoDotNotation(expression);
+        }
         // Check for field restrictions if specified
         this.validateFields(expression, schema);
+        // Check for denied values if specified
+        this.validateDenyValues(expression);
         // Check query complexity
         this.validateQueryDepth(expression, 0);
         this.validateClauseCount(expression);
@@ -192,6 +198,108 @@ class QuerySecurityValidator {
             }
         }
     }
+    /**
+     * Validate that field names do not contain dot notation
+     *
+     * When allowDotNotation is disabled, this method ensures no field names
+     * contain dots, which could be used for:
+     * - Table-qualified column access (e.g., "users.password")
+     * - Nested JSON/JSONB field access (e.g., "metadata.secret")
+     * - Probing internal table structures
+     *
+     * @private
+     * @param expression - The query expression to validate
+     * @throws {QuerySecurityError} If a field name contains dot notation
+     */
+    validateNoDotNotation(expression) {
+        if (expression.type === 'comparison') {
+            const { field } = expression;
+            if (field.includes('.')) {
+                throw new QuerySecurityError(`Dot notation is not allowed in field names. ` +
+                    `Found "${field}" - use a simple field name without dots instead.`);
+            }
+        }
+        else {
+            // Recursively validate logical expressions
+            this.validateNoDotNotation(expression.left);
+            if (expression.right) {
+                this.validateNoDotNotation(expression.right);
+            }
+        }
+    }
+    /**
+     * Validate that query values are not in the denied values list for their field
+     *
+     * This method checks each comparison expression to ensure the value being
+     * queried is not in the denyValues list for that field. This provides
+     * granular control over what values can be queried for specific fields.
+     *
+     * @private
+     * @param expression - The query expression to validate
+     * @throws {QuerySecurityError} If a denied value is found in the query
+     */
+    validateDenyValues(expression) {
+        // Skip if no denyValues configured
+        if (Object.keys(this.options.denyValues).length === 0) {
+            return;
+        }
+        if (expression.type === 'comparison') {
+            const { field, value } = expression;
+            const deniedValues = this.options.denyValues[field];
+            if (deniedValues && deniedValues.length > 0) {
+                // Check if the value is an array (for IN/NOT IN operators)
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        if (this.isValueDenied(item, deniedValues)) {
+                            throw new QuerySecurityError('Invalid query parameters');
+                        }
+                    }
+                }
+                else {
+                    // Single value comparison
+                    if (this.isValueDenied(value, deniedValues)) {
+                        throw new QuerySecurityError('Invalid query parameters');
+                    }
+                }
+            }
+        }
+        else {
+            // Recursively validate logical expressions
+            this.validateDenyValues(expression.left);
+            if (expression.right) {
+                this.validateDenyValues(expression.right);
+            }
+        }
+    }
+    /**
+     * Check if a value is in the denied values list
+     *
+     * @private
+     * @param value - The value to check
+     * @param deniedValues - The list of denied values
+     * @returns true if the value is denied, false otherwise
+     */
+    isValueDenied(value, deniedValues) {
+        // Use strict equality to match values, handling type coercion properly
+        return deniedValues.some(deniedValue => {
+            // Handle null comparison explicitly
+            if (value === null && deniedValue === null) {
+                return true;
+            }
+            // Handle same-type comparison with strict equality
+            if (typeof value === typeof deniedValue) {
+                return value === deniedValue;
+            }
+            // Handle string/number comparison (common case)
+            if (typeof value === 'string' && typeof deniedValue === 'number') {
+                return value === String(deniedValue);
+            }
+            if (typeof value === 'number' && typeof deniedValue === 'string') {
+                return String(value) === deniedValue;
+            }
+            return false;
+        });
+    }
     /**
      * Validate that query depth does not exceed the maximum
      *

package/examples/qk-next/app/globals.css

@@ -116,7 +116,30 @@
   * {
     @apply border-border outline-ring/50;
   }
+
   body {
     @apply bg-background text-foreground;
+    overscroll-behavior: none;
+    overflow: hidden;
+  }
+}
+
+@layer components {
+  .quick-start-snippet {
+    @apply !m-0 !bg-transparent whitespace-pre-wrap break-words px-3 py-3 pr-14 text-xs leading-[1.4] font-mono sm:text-sm;
   }
+}
+
+/* Prevent mobile zoom on inputs by ensuring font-size >= 16px */
+input,
+textarea,
+select {
+  font-size: 16px;
+}
+
+/* Ensure the root takes full viewport and no scrollbars appear */
+html,
+body,
+#__next {
+  height: 100%;
 }