@gblikas/querykit 0.0.0 → 0.1.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/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%;
 }

package/examples/qk-next/app/hooks/use-viewport-info.ts

@@ -0,0 +1,89 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export interface IViewportInfo {
+  innerWidth: number;
+  innerHeight: number;
+  shortViewportHeightPx: number;
+  isLessThanHeight: (px: number) => boolean;
+  shortSidePx: number;
+  isShortSideLessThan: (px: number) => boolean;
+}
+
+/**
+ * Returns robust viewport dimensions using small viewport units (svh/svw) fallbacks.
+ * Ensures height reflects the visual viewport on mobile, avoiding URL bar issues.
+ */
+export function useViewportInfo(): IViewportInfo {
+  const readInnerHeight = (): number => {
+    // Prefer visualViewport when available to avoid browser UI chrome affecting measurements
+    const visual = window.visualViewport;
+    if (visual && typeof visual.height === 'number')
+      return Math.round(visual.height);
+    // Fallbacks in order of reliability
+    return Math.round(
+      window.innerHeight || document.documentElement.clientHeight
+    );
+  };
+  const readInnerWidth = (): number => {
+    const visual = window.visualViewport;
+    if (visual && typeof visual.width === 'number')
+      return Math.round(visual.width);
+    return Math.round(
+      window.innerWidth || document.documentElement.clientWidth
+    );
+  };
+
+  const [state, setState] = useState<IViewportInfo>((): IViewportInfo => {
+    const w =
+      typeof window !== 'undefined'
+        ? typeof window.visualViewport?.width === 'number'
+          ? Math.round(window.visualViewport.width)
+          : window.innerWidth
+        : 0;
+    const h = typeof window !== 'undefined' ? readInnerHeight() : 0;
+    const shortSide = Math.min(w, h);
+    return {
+      innerWidth: w,
+      innerHeight: h,
+      shortViewportHeightPx: h,
+      isLessThanHeight: (px: number) => h < px,
+      shortSidePx: shortSide,
+      isShortSideLessThan: (px: number) => shortSide < px
+    };
+  });
+
+  useEffect(() => {
+    let frame = 0;
+    const measure = (): void => {
+      const w = readInnerWidth();
+      const h = readInnerHeight();
+      const shortSide = Math.min(w, h);
+      setState({
+        innerWidth: w,
+        innerHeight: h,
+        shortViewportHeightPx: h,
+        isLessThanHeight: (px: number) => h < px,
+        shortSidePx: shortSide,
+        isShortSideLessThan: (px: number) => shortSide < px
+      });
+    };
+    frame = requestAnimationFrame(measure);
+    const onResize = (): void => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(measure);
+    };
+    window.addEventListener('resize', onResize);
+    window.visualViewport?.addEventListener('resize', onResize);
+    window.visualViewport?.addEventListener('scroll', onResize);
+    return (): void => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener('resize', onResize);
+      window.visualViewport?.removeEventListener('resize', onResize);
+      window.visualViewport?.removeEventListener('scroll', onResize);
+    };
+  }, []);
+
+  return state;
+}

package/examples/qk-next/app/layout.tsx

@@ -1,4 +1,4 @@
-import type { Metadata } from 'next';
+import type { Metadata, Viewport } from 'next';
 import { Geist, Geist_Mono } from 'next/font/google';
 import './globals.css';
 import { Toaster } from '@/components/ui/sonner';
@@ -7,6 +7,8 @@ import { ThemeProvider } from '@/components/theme-provider';
 import { GitHubStars } from '@/components/github-stars';
 import AuroraBackground from '@/components/aurora-background';
 import { JSX } from 'react';
+import { Analytics } from '@vercel/analytics/next';
+import { SpeedInsights } from '@vercel/speed-insights/next';
 
 const geistSans = Geist({
   variable: '--font-geist-sans',
@@ -19,9 +21,7 @@ const geistMono = Geist_Mono({
 });
 
 export const metadata: Metadata = {
-  metadataBase: new URL(
-    process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'
-  ),
+  metadataBase: new URL('https://www.querykit.dev/'),
   title: {
     default: 'QueryKit · Next.js Demo',
     template: '%s · QueryKit'
@@ -37,7 +37,12 @@ export const metadata: Metadata = {
     'drizzle orm',
     'pglite',
     'typescript',
-    'next.js'
+    'next.js',
+    'drizzle',
+    'sql',
+    'npm',
+    'npm-package',
+    'nextjs'
   ],
   authors: [{ name: 'gblikas', url: 'https://github.com/gblikas' }],
   creator: 'QueryKit',
@@ -79,15 +84,27 @@ export const metadata: Metadata = {
   ]
 };
 
+export const viewport: Viewport = {
+  width: 'device-width',
+  initialScale: 1,
+  maximumScale: 1,
+  userScalable: false,
+  viewportFit: 'cover'
+};
+
 export default function RootLayout({
   children
 }: {
   children: React.ReactNode;
 }): JSX.Element {
   return (
-    <html lang="en" suppressHydrationWarning className="min-h-screen">
+    <html
+      lang="en"
+      suppressHydrationWarning
+      className="min-h-screen overflow-hidden"
+    >
       <body
-        className={`${geistSans.variable} ${geistMono.variable} antialiased min-h-screen`}
+        className={`${geistSans.variable} ${geistMono.variable} antialiased min-h-screen overflow-hidden`}
       >
         <ThemeProvider
           attribute="class"
@@ -113,6 +130,8 @@ export default function RootLayout({
             </div>
             <Providers>{children}</Providers>
             <Toaster />
+            <Analytics />
+            <SpeedInsights />
           </div>
         </ThemeProvider>
       </body>