@gblikas/querykit 0.0.0 → 0.2.0

package/examples/qk-next/lib/utils.ts

@@ -1,6 +1,80 @@
 import { clsx, type ClassValue } from 'clsx';
 import { twMerge } from 'tailwind-merge';
+// Use the signature from @vercel/analytics: Record<string, AllowedPropertyValues>
+type AnalyticsEventProps = Record<string, string | number | boolean | null>;
 
 export function cn(...inputs: ClassValue[]): string {
   return twMerge(clsx(inputs));
 }
+
+// Lightweight telemetry helpers using Vercel Analytics custom events
+// See: https://vercel.com/docs/analytics#events
+export interface IQueryKitIssueEvent {
+  errorName: string;
+  errorMessage: string;
+  stage: 'parse' | 'translate' | 'execute' | 'explain' | 'seed' | 'search';
+  query?: string;
+}
+
+export async function trackQueryKitIssue(event: IQueryKitIssueEvent): Promise<void> {
+  try {
+    const { track } = await import('@vercel/analytics');
+    const props: AnalyticsEventProps = {
+      errorName: event.errorName,
+      errorMessage: event.errorMessage,
+      stage: event.stage,
+      query: event.query ?? null
+    };
+    track('qk_issue', props);
+  } catch {
+    // no-op in dev or if analytics not available
+  }
+}
+
+export interface IQueryKitUsageEvent {
+  usedQueryKit: boolean;
+  operators: string[];
+}
+
+export async function trackQueryKitUsage(event: IQueryKitUsageEvent): Promise<void> {
+  try {
+    const { track } = await import('@vercel/analytics');
+    const props: AnalyticsEventProps = {
+      usedQueryKit: event.usedQueryKit,
+      operators: (event.operators || []).join(',')
+    };
+    track('qk_usage', props);
+  } catch {
+    // no-op
+  }
+}
+
+export interface IQueryKitSpeedEvent {
+  usedQueryKit: boolean;
+  baselineMs?: number | null;
+  parseTranslateMs?: number | null;
+  explainLatencyMs?: number | null;
+  dbExecutionMs?: number | null;
+  totalMs?: number | null;
+  rowsScanned?: number | null;
+  results?: number | null;
+}
+
+export async function trackQueryKitSpeed(event: IQueryKitSpeedEvent): Promise<void> {
+  try {
+    const { track } = await import('@vercel/analytics');
+    const props: AnalyticsEventProps = {
+      usedQueryKit: event.usedQueryKit,
+      baselineMs: event.baselineMs ?? null,
+      parseTranslateMs: event.parseTranslateMs ?? null,
+      explainLatencyMs: event.explainLatencyMs ?? null,
+      dbExecutionMs: event.dbExecutionMs ?? null,
+      totalMs: event.totalMs ?? null,
+      rowsScanned: event.rowsScanned ?? null,
+      results: event.results ?? null
+    };
+    track('qk_speed', props);
+  } catch {
+    // no-op
+  }
+}

package/examples/qk-next/package.json

@@ -11,15 +11,17 @@
   "dependencies": {
     "@electric-sql/pglite": "^0.3.7",
     "@electric-sql/pglite-react": "^0.2.25",
-    "@gblikas/querykit": "file:../..",
+    "@gblikas/querykit": "^0.0.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-hover-card": "^1.1.15",
+    "@vercel/analytics": "^1.5.0",
+    "@vercel/speed-insights": "^1.2.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.0.0",
     "drizzle-orm": "^0.44.4",
     "lucide-react": "^0.539.0",
-    "next": "15.4.6",
+    "next": "15.4.10",
     "next-themes": "^0.4.6",
     "ogl": "^1.0.11",
     "prism-react-renderer": "^2.4.1",
@@ -45,4 +47,4 @@
     "tw-animate-css": "^1.3.6",
     "typescript": "^5"
   }
-}
+}

package/examples/qk-next/pnpm-lock.yaml

@@ -15,14 +15,20 @@ importers:
         specifier: ^0.2.25
         version: 0.2.25(@electric-sql/pglite@0.3.7)(react@19.1.0)
       '@gblikas/querykit':
-        specifier: file:../..
-        version: file:../..(@electric-sql/pglite@0.3.7)(@types/react@19.1.10)(react@19.1.0)
+        specifier: ^0.0.0
+        version: 0.0.0(@electric-sql/pglite@0.3.7)(@types/react@19.1.10)(react@19.1.0)
       '@radix-ui/react-dialog':
         specifier: ^1.1.15
         version: 1.1.15(@types/react-dom@19.1.7(@types/react@19.1.10))(@types/react@19.1.10)(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
       '@radix-ui/react-hover-card':
         specifier: ^1.1.15
         version: 1.1.15(@types/react-dom@19.1.7(@types/react@19.1.10))(@types/react@19.1.10)(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
+      '@vercel/analytics':
+        specifier: ^1.5.0
+        version: 1.5.0(next@15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0))(react@19.1.0)
+      '@vercel/speed-insights':
+        specifier: ^1.2.0
+        version: 1.2.0(next@15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0))(react@19.1.0)
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -39,8 +45,8 @@ importers:
         specifier: ^0.539.0
         version: 0.539.0(react@19.1.0)
       next:
-        specifier: 15.4.6
-        version: 15.4.6(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
+        specifier: 15.4.10
+        version: 15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
       next-themes:
         specifier: ^0.4.6
         version: 0.4.6(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
@@ -489,8 +495,8 @@ packages:
   '@floating-ui/utils@0.2.10':
     resolution: {integrity: sha512-aGTxbpbg8/b5JfU1HXSrbH3wXZuLPJcNEcZQFMxLs3oSzgtVu6nFPkbbGGUvBcUjKV2YyB9Wxxabo+HEH9tcRQ==}
 
-  '@gblikas/querykit@file:../..':
-    resolution: {directory: ../.., type: directory}
+  '@gblikas/querykit@0.0.0':
+    resolution: {integrity: sha512-kmCkPhc/YCmPJ3/WNGBEEbnHRMNeVrvWDvn3w6xi1cVOagN5Gff7s7sy6vqpXZ5fnhB3XSSnD0oj4KNDLZXdIA==}
 
   '@humanfs/core@0.19.1':
     resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==}
@@ -657,56 +663,56 @@ packages:
   '@napi-rs/wasm-runtime@0.2.12':
     resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==}
 
-  '@next/env@15.4.6':
-    resolution: {integrity: sha512-yHDKVTcHrZy/8TWhj0B23ylKv5ypocuCwey9ZqPyv4rPdUdRzpGCkSi03t04KBPyU96kxVtUqx6O3nE1kpxASQ==}
+  '@next/env@15.4.10':
+    resolution: {integrity: sha512-knhmoJ0Vv7VRf6pZEPSnciUG1S4bIhWx+qTYBW/AjxEtlzsiNORPk8sFDCEvqLfmKuey56UB9FL1UdHEV3uBrg==}
 
   '@next/eslint-plugin-next@15.4.6':
     resolution: {integrity: sha512-2NOu3ln+BTcpnbIDuxx6MNq+pRrCyey4WSXGaJIyt0D2TYicHeO9QrUENNjcf673n3B1s7hsiV5xBYRCK1Q8kA==}
 
-  '@next/swc-darwin-arm64@15.4.6':
-    resolution: {integrity: sha512-667R0RTP4DwxzmrqTs4Lr5dcEda9OxuZsVFsjVtxVMVhzSpo6nLclXejJVfQo2/g7/Z9qF3ETDmN3h65mTjpTQ==}
+  '@next/swc-darwin-arm64@15.4.8':
+    resolution: {integrity: sha512-Pf6zXp7yyQEn7sqMxur6+kYcywx5up1J849psyET7/8pG2gQTVMjU3NzgIt8SeEP5to3If/SaWmaA6H6ysBr1A==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
 
-  '@next/swc-darwin-x64@15.4.6':
-    resolution: {integrity: sha512-KMSFoistFkaiQYVQQnaU9MPWtp/3m0kn2Xed1Ces5ll+ag1+rlac20sxG+MqhH2qYWX1O2GFOATQXEyxKiIscg==}
+  '@next/swc-darwin-x64@15.4.8':
+    resolution: {integrity: sha512-xla6AOfz68a6kq3gRQccWEvFC/VRGJmA/QuSLENSO7CZX5WIEkSz7r1FdXUjtGCQ1c2M+ndUAH7opdfLK1PQbw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
-  '@next/swc-linux-arm64-gnu@15.4.6':
-    resolution: {integrity: sha512-PnOx1YdO0W7m/HWFeYd2A6JtBO8O8Eb9h6nfJia2Dw1sRHoHpNf6lN1U4GKFRzRDBi9Nq2GrHk9PF3Vmwf7XVw==}
+  '@next/swc-linux-arm64-gnu@15.4.8':
+    resolution: {integrity: sha512-y3fmp+1Px/SJD+5ntve5QLZnGLycsxsVPkTzAc3zUiXYSOlTPqT8ynfmt6tt4fSo1tAhDPmryXpYKEAcoAPDJw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-arm64-musl@15.4.6':
-    resolution: {integrity: sha512-XBbuQddtY1p5FGPc2naMO0kqs4YYtLYK/8aPausI5lyOjr4J77KTG9mtlU4P3NwkLI1+OjsPzKVvSJdMs3cFaw==}
+  '@next/swc-linux-arm64-musl@15.4.8':
+    resolution: {integrity: sha512-DX/L8VHzrr1CfwaVjBQr3GWCqNNFgyWJbeQ10Lx/phzbQo3JNAxUok1DZ8JHRGcL6PgMRgj6HylnLNndxn4Z6A==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
 
-  '@next/swc-linux-x64-gnu@15.4.6':
-    resolution: {integrity: sha512-+WTeK7Qdw82ez3U9JgD+igBAP75gqZ1vbK6R8PlEEuY0OIe5FuYXA4aTjL811kWPf7hNeslD4hHK2WoM9W0IgA==}
+  '@next/swc-linux-x64-gnu@15.4.8':
+    resolution: {integrity: sha512-9fLAAXKAL3xEIFdKdzG5rUSvSiZTLLTCc6JKq1z04DR4zY7DbAPcRvNm3K1inVhTiQCs19ZRAgUerHiVKMZZIA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-linux-x64-musl@15.4.6':
-    resolution: {integrity: sha512-XP824mCbgQsK20jlXKrUpZoh/iO3vUWhMpxCz8oYeagoiZ4V0TQiKy0ASji1KK6IAe3DYGfj5RfKP6+L2020OQ==}
+  '@next/swc-linux-x64-musl@15.4.8':
+    resolution: {integrity: sha512-s45V7nfb5g7dbS7JK6XZDcapicVrMMvX2uYgOHP16QuKH/JA285oy6HcxlKqwUNaFY/UC6EvQ8QZUOo19cBKSA==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
 
-  '@next/swc-win32-arm64-msvc@15.4.6':
-    resolution: {integrity: sha512-FxrsenhUz0LbgRkNWx6FRRJIPe/MI1JRA4W4EPd5leXO00AZ6YU8v5vfx4MDXTvN77lM/EqsE3+6d2CIeF5NYg==}
+  '@next/swc-win32-arm64-msvc@15.4.8':
+    resolution: {integrity: sha512-KjgeQyOAq7t/HzAJcWPGA8X+4WY03uSCZ2Ekk98S9OgCFsb6lfBE3dbUzUuEQAN2THbwYgFfxX2yFTCMm8Kehw==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
-  '@next/swc-win32-x64-msvc@15.4.6':
-    resolution: {integrity: sha512-T4ufqnZ4u88ZheczkBTtOF+eKaM14V8kbjud/XrAakoM5DKQWjW09vD6B9fsdsWS2T7D5EY31hRHdta7QKWOng==}
+  '@next/swc-win32-x64-msvc@15.4.8':
+    resolution: {integrity: sha512-Exsmf/+42fWVnLMaZHzshukTBxZrSwuuLKFvqhGHJ+mC1AokqieLY/XzAl3jc/CqhXLqLY3RRjkKJ9YnLPcRWg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
@@ -1244,6 +1250,55 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@vercel/analytics@1.5.0':
+    resolution: {integrity: sha512-MYsBzfPki4gthY5HnYN7jgInhAZ7Ac1cYDoRWFomwGHWEX7odTEzbtg9kf/QSo7XEsEAqlQugA6gJ2WS2DEa3g==}
+    peerDependencies:
+      '@remix-run/react': ^2
+      '@sveltejs/kit': ^1 || ^2
+      next: '>= 13'
+      react: ^18 || ^19 || ^19.0.0-rc
+      svelte: '>= 4'
+      vue: ^3
+      vue-router: ^4
+    peerDependenciesMeta:
+      '@remix-run/react':
+        optional: true
+      '@sveltejs/kit':
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      svelte:
+        optional: true
+      vue:
+        optional: true
+      vue-router:
+        optional: true
+
+  '@vercel/speed-insights@1.2.0':
+    resolution: {integrity: sha512-y9GVzrUJ2xmgtQlzFP2KhVRoCglwfRQgjyfY607aU0hh0Un6d0OUyrJkjuAlsV18qR4zfoFPs/BiIj9YDS6Wzw==}
+    peerDependencies:
+      '@sveltejs/kit': ^1 || ^2
+      next: '>= 13'
+      react: ^18 || ^19 || ^19.0.0-rc
+      svelte: '>= 4'
+      vue: ^3
+      vue-router: ^4
+    peerDependenciesMeta:
+      '@sveltejs/kit':
+        optional: true
+      next:
+        optional: true
+      react:
+        optional: true
+      svelte:
+        optional: true
+      vue:
+        optional: true
+      vue-router:
+        optional: true
+
   acorn-jsx@5.3.2:
     resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
     peerDependencies:
@@ -2329,8 +2384,8 @@ packages:
       react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
       react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
 
-  next@15.4.6:
-    resolution: {integrity: sha512-us++E/Q80/8+UekzB3SAGs71AlLDsadpFMXVNM/uQ0BMwsh9m3mr0UNQIfjKed8vpWXsASe+Qifrnu1oLIcKEQ==}
+  next@15.4.10:
+    resolution: {integrity: sha512-itVlc79QjpKMFMRhP+kbGKaSG/gZM6RCvwhEbwmCNF06CdDiNaoHcbeg0PqkEa2GOcn8KJ0nnc7+yL7EjoYLHQ==}
     engines: {node: ^18.18.0 || ^19.8.0 || >= 20.0.0}
     hasBin: true
     peerDependencies:
@@ -2723,6 +2778,7 @@ packages:
   tar@7.4.3:
     resolution: {integrity: sha512-5S7Va8hKfV7W5U6g3aYxXmlPoZVAwUMy9AOKyF2fVuZa2UD3qZjg578OrLRt8PcNN1PleVaL/5/yYATNL0ICUw==}
     engines: {node: '>=18'}
+    deprecated: Old versions of tar are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exhorbitant rates) by contacting i@izs.me
 
   tinyglobby@0.2.14:
     resolution: {integrity: sha512-tX5e7OM1HnYr2+a2C/4V0htOcSQcoSTH9KgJnVvNm5zm/cyEWKJ7j7YutsH9CxMdtOkkLFy2AHrMci9IM8IPZQ==}
@@ -3097,11 +3153,10 @@ snapshots:
 
   '@floating-ui/utils@0.2.10': {}
 
-  '@gblikas/querykit@file:../..(@electric-sql/pglite@0.3.7)(@types/react@19.1.10)(react@19.1.0)':
+  '@gblikas/querykit@0.0.0(@electric-sql/pglite@0.3.7)(@types/react@19.1.10)(react@19.1.0)':
     dependencies:
       drizzle-orm: 0.30.10(@electric-sql/pglite@0.3.7)(@types/react@19.1.10)(react@19.1.0)
       liqe: 3.8.3
-      ogl: 1.0.11
     transitivePeerDependencies:
       - '@aws-sdk/client-rds-data'
       - '@cloudflare/workers-types'
@@ -3258,34 +3313,34 @@ snapshots:
       '@tybys/wasm-util': 0.10.0
     optional: true
 
-  '@next/env@15.4.6': {}
+  '@next/env@15.4.10': {}
 
   '@next/eslint-plugin-next@15.4.6':
     dependencies:
       fast-glob: 3.3.1
 
-  '@next/swc-darwin-arm64@15.4.6':
+  '@next/swc-darwin-arm64@15.4.8':
     optional: true
 
-  '@next/swc-darwin-x64@15.4.6':
+  '@next/swc-darwin-x64@15.4.8':
     optional: true
 
-  '@next/swc-linux-arm64-gnu@15.4.6':
+  '@next/swc-linux-arm64-gnu@15.4.8':
     optional: true
 
-  '@next/swc-linux-arm64-musl@15.4.6':
+  '@next/swc-linux-arm64-musl@15.4.8':
     optional: true
 
-  '@next/swc-linux-x64-gnu@15.4.6':
+  '@next/swc-linux-x64-gnu@15.4.8':
     optional: true
 
-  '@next/swc-linux-x64-musl@15.4.6':
+  '@next/swc-linux-x64-musl@15.4.8':
     optional: true
 
-  '@next/swc-win32-arm64-msvc@15.4.6':
+  '@next/swc-win32-arm64-msvc@15.4.8':
     optional: true
 
-  '@next/swc-win32-x64-msvc@15.4.6':
+  '@next/swc-win32-x64-msvc@15.4.8':
     optional: true
 
   '@nodelib/fs.scandir@2.1.5':
@@ -3772,6 +3827,16 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
+  '@vercel/analytics@1.5.0(next@15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0))(react@19.1.0)':
+    optionalDependencies:
+      next: 15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
+      react: 19.1.0
+
+  '@vercel/speed-insights@1.2.0(next@15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0))(react@19.1.0)':
+    optionalDependencies:
+      next: 15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0)
+      react: 19.1.0
+
   acorn-jsx@5.3.2(acorn@8.15.0):
     dependencies:
       acorn: 8.15.0
@@ -4901,9 +4966,9 @@ snapshots:
       react: 19.1.0
       react-dom: 19.1.0(react@19.1.0)
 
-  next@15.4.6(react-dom@19.1.0(react@19.1.0))(react@19.1.0):
+  next@15.4.10(react-dom@19.1.0(react@19.1.0))(react@19.1.0):
     dependencies:
-      '@next/env': 15.4.6
+      '@next/env': 15.4.10
       '@swc/helpers': 0.5.15
       caniuse-lite: 1.0.30001735
       postcss: 8.4.31
@@ -4911,14 +4976,14 @@ snapshots:
       react-dom: 19.1.0(react@19.1.0)
       styled-jsx: 5.1.6(react@19.1.0)
     optionalDependencies:
-      '@next/swc-darwin-arm64': 15.4.6
-      '@next/swc-darwin-x64': 15.4.6
-      '@next/swc-linux-arm64-gnu': 15.4.6
-      '@next/swc-linux-arm64-musl': 15.4.6
-      '@next/swc-linux-x64-gnu': 15.4.6
-      '@next/swc-linux-x64-musl': 15.4.6
-      '@next/swc-win32-arm64-msvc': 15.4.6
-      '@next/swc-win32-x64-msvc': 15.4.6
+      '@next/swc-darwin-arm64': 15.4.8
+      '@next/swc-darwin-x64': 15.4.8
+      '@next/swc-linux-arm64-gnu': 15.4.8
+      '@next/swc-linux-arm64-musl': 15.4.8
+      '@next/swc-linux-x64-gnu': 15.4.8
+      '@next/swc-linux-x64-musl': 15.4.8
+      '@next/swc-win32-arm64-msvc': 15.4.8
+      '@next/swc-win32-x64-msvc': 15.4.8
       sharp: 0.34.3
     transitivePeerDependencies:
       - '@babel/core'

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@gblikas/querykit",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "A comprehensive query toolkit for TypeScript that simplifies building and executing data queries across different environments",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gblikas/querykit.git"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "lint-staged": {

package/src/parser/parser.test.ts

@@ -1,5 +1,9 @@
 import { QueryParser, QueryParseError } from './parser';
-import { QueryExpression } from './types';
+import {
+  IComparisonExpression,
+  ILogicalExpression,
+  QueryExpression
+} from './types';
 
 // Replace the type definition with this approach
 type QueryParserPrivate = {
@@ -863,6 +867,210 @@ describe('QueryParser', () => {
 
       expect(parser.parse(query)).toEqual(expected);
     });
+
+    // IN operator syntax tests using consistent key:[values] pattern
+    describe('IN operator syntax (key:[values])', () => {
+      it('should parse "field:[val1, val2, val3]" bracket array syntax', () => {
+        const query = 'status:[todo, doing, done]';
+        const expected: QueryExpression = {
+          type: 'logical',
+          operator: 'OR',
+          left: {
+            type: 'logical',
+            operator: 'OR',
+            left: {
+              type: 'comparison',
+              field: 'status',
+              operator: '==',
+              value: 'todo'
+            },
+            right: {
+              type: 'comparison',
+              field: 'status',
+              operator: '==',
+              value: 'doing'
+            }
+          },
+          right: {
+            type: 'comparison',
+            field: 'status',
+            operator: '==',
+            value: 'done'
+          }
+        };
+
+        expect(parser.parse(query)).toEqual(expected);
+      });
+
+      it('should parse numeric values in bracket syntax', () => {
+        const query = 'id:[2, 3]';
+        const expected: QueryExpression = {
+          type: 'logical',
+          operator: 'OR',
+          left: {
+            type: 'comparison',
+            field: 'id',
+            operator: '==',
+            value: 2
+          },
+          right: {
+            type: 'comparison',
+            field: 'id',
+            operator: '==',
+            value: 3
+          }
+        };
+
+        expect(parser.parse(query)).toEqual(expected);
+      });
+
+      it('should parse single value in bracket syntax', () => {
+        const query = 'status:[active]';
+        const expected: QueryExpression = {
+          type: 'comparison',
+          field: 'status',
+          operator: '==',
+          value: 'active'
+        };
+
+        expect(parser.parse(query)).toEqual(expected);
+      });
+
+      it('should preserve range syntax "field:[min TO max]"', () => {
+        const query = 'id:[2 TO 5]';
+        const expected: QueryExpression = {
+          type: 'logical',
+          operator: 'AND',
+          left: {
+            type: 'comparison',
+            field: 'id',
+            operator: '>=',
+            value: 2
+          },
+          right: {
+            type: 'comparison',
+            field: 'id',
+            operator: '<=',
+            value: 5
+          }
+        };
+
+        expect(parser.parse(query)).toEqual(expected);
+      });
+
+      it('should parse exclusive range syntax "field:{min TO max}"', () => {
+        const query = 'id:{2 TO 5}';
+        const expected: QueryExpression = {
+          type: 'logical',
+          operator: 'AND',
+          left: {
+            type: 'comparison',
+            field: 'id',
+            operator: '>',
+            value: 2
+          },
+          right: {
+            type: 'comparison',
+            field: 'id',
+            operator: '<',
+            value: 5
+          }
+        };
+
+        expect(parser.parse(query)).toEqual(expected);
+      });
+
+      it('should parse bracket syntax combined with other expressions', () => {
+        const query = 'status:[todo, doing] AND priority:>2';
+        const parsed = parser.parse(query);
+
+        // Verify it's a logical AND at the top level
+        expect(parsed.type).toBe('logical');
+        expect((parsed as ILogicalExpression).operator).toBe('AND');
+
+        // Left side should be OR of status values
+        const left = (parsed as ILogicalExpression).left as ILogicalExpression;
+        expect(left.type).toBe('logical');
+        expect(left.operator).toBe('OR');
+      });
+
+      it('should handle values with spaces using quotes', () => {
+        const query = 'name:[John, "Jane Doe"]';
+        const parsed = parser.parse(query);
+
+        expect(parsed.type).toBe('logical');
+        expect((parsed as ILogicalExpression).operator).toBe('OR');
+
+        const right = (parsed as ILogicalExpression)
+          .right as IComparisonExpression;
+        expect(right.value).toBe('Jane Doe');
+      });
+
+      it('should validate bracket syntax queries', () => {
+        expect(parser.validate('status:[todo, doing, done]')).toBe(true);
+        expect(parser.validate('id:[1, 2, 3]')).toBe(true);
+        expect(parser.validate('id:[1 TO 10]')).toBe(true);
+      });
+
+      it('should handle mixed types in bracket syntax', () => {
+        const query = 'priority:[1, 2, 3]';
+        const parsed = parser.parse(query);
+
+        expect(parsed.type).toBe('logical');
+        // All values should be numbers
+        const getLeftmost = (expr: QueryExpression): IComparisonExpression => {
+          if (expr.type === 'comparison') return expr;
+          return getLeftmost((expr as ILogicalExpression).left);
+        };
+        expect(typeof getLeftmost(parsed).value).toBe('number');
+      });
+
+      it('should handle quoted values with commas inside', () => {
+        const query = 'name:["John, Jr.", "Jane"]';
+        const parsed = parser.parse(query);
+
+        expect(parsed.type).toBe('logical');
+        expect((parsed as ILogicalExpression).operator).toBe('OR');
+
+        const left = (parsed as ILogicalExpression)
+          .left as IComparisonExpression;
+        const right = (parsed as ILogicalExpression)
+          .right as IComparisonExpression;
+
+        expect(left.value).toBe('John, Jr.');
+        expect(right.value).toBe('Jane');
+      });
+
+      it('should handle single-quoted values with commas inside', () => {
+        const query = "name:['Hello, World', 'test']";
+        const parsed = parser.parse(query);
+
+        expect(parsed.type).toBe('logical');
+        const left = (parsed as ILogicalExpression)
+          .left as IComparisonExpression;
+        expect(left.value).toBe('Hello, World');
+      });
+
+      it('should handle mixed quoted and unquoted values with commas', () => {
+        const query = 'tags:["a,b,c", simple, "x,y"]';
+        const parsed = parser.parse(query);
+
+        expect(parsed.type).toBe('logical');
+        // Should have 3 values: "a,b,c", "simple", "x,y"
+        const getValues = (expr: QueryExpression): string[] => {
+          if (expr.type === 'comparison') {
+            return [String(expr.value)];
+          }
+          const logical = expr as ILogicalExpression;
+          return [...getValues(logical.left), ...getValues(logical.right!)];
+        };
+
+        const values = getValues(parsed);
+        expect(values).toContain('a,b,c');
+        expect(values).toContain('simple');
+        expect(values).toContain('x,y');
+      });
+    });
   });
 
   describe('validate', () => {