@gblikas/querykit 0.0.0

package/.cursor/rules/liqe-readme-docs.mdc

@@ -0,0 +1,438 @@
+---
+description: the readme of liqe; a poor man's documentation for liqe
+globs: 
+alwaysApply: false
+---
+# liqe
+
+[![Coveralls](https://img.shields.io/coveralls/gajus/liqe.svg?style=flat-square)](https://coveralls.io/github/gajus/liqe)
+[![NPM version](http://img.shields.io/npm/v/liqe.svg?style=flat-square)](https://www.npmjs.org/package/liqe)
+[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)
+[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social&label=Follow)](https://twitter.com/kuizinas)
+
+Lightweight and performant Lucene-like parser, serializer and search engine.
+
+* [Motivation](#motivation)
+* [Usage](#usage)
+* [Query Syntax](#query-syntax)
+  * [Liqe syntax cheat sheet](#liqe-syntax-cheat-sheet)
+  * [Keyword matching](#keyword-matching)
+  * [Number matching](#number-matching)
+  * [Range matching](#range-matching)
+  * [Wildcard matching](#wildcard-matching)
+  * [Boolean operators](#boolean-operators)
+* [Serializer](#serializer)
+* [AST](#ast)
+* [Utilities](#utilities)
+* [Compatibility with Lucene](#compatibility-with-lucene)
+* [Recipes](#recipes)
+  * [Handling syntax errors](#handling-syntax-errors)
+  * [Highlighting matches](#highlighting-matches)
+* [Development](#development)
+* [Tutorials](#tutorials)
+
+## Motivation
+
+Originally built Liqe to enable [Roarr](https://github.com/gajus/roarr) log filtering via [cli](https://github.com/gajus/roarr-cli#filtering-logs). I have since been polishing this project as a hobby/intellectual exercise. I've seen it being adopted by [various](https://github.com/gajus/liqe/network/dependents) CLI and web applications that require advanced search. To my knowledge, it is currently the most complete Lucene-like syntax parser and serializer in JavaScript, as well as a compatible in-memory search engine.
+
+Liqe use cases include:
+
+* parsing search queries
+* serializing parsed queries
+* searching JSON documents using the Liqe query language (LQL)
+
+Note that the [Liqe AST](#ast) is treated as a public API, i.e., one could implement their own search mechanism that uses Liqe query language (LQL).
+
+## Usage
+
+```ts
+import {
+  filter,
+  highlight,
+  parse,
+  test,
+} from 'liqe';
+
+const persons = [
+  {
+    height: 180,
+    name: 'John Morton',
+  },
+  {
+    height: 175,
+    name: 'David Barker',
+  },
+  {
+    height: 170,
+    name: 'Thomas Castro',
+  },
+];
+```
+
+Filter a collection:
+
+```ts
+filter(parse('height:>170'), persons);
+// [
+//   {
+//     height: 180,
+//     name: 'John Morton',
+//   },
+//   {
+//     height: 175,
+//     name: 'David Barker',
+//   },
+// ]
+```
+
+Test a single object:
+
+```ts
+test(parse('name:John'), persons[0]);
+// true
+test(parse('name:David'), persons[0]);
+// false
+```
+
+Highlight matching fields and substrings:
+
+```ts
+highlight(parse('name:john'), persons[0]);
+// [
+//   {
+//     path: 'name',
+//     query: /(John)/,
+//   }
+// ]
+highlight(parse('height:180'), persons[0]);
+// [
+//   {
+//     path: 'height',
+//   }
+// ]
+```
+
+## Query Syntax
+
+Liqe uses Liqe Query Language (LQL), which is heavily inspired by Lucene but extends it in various ways that allow a more powerful search experience.
+
+### Liqe syntax cheat sheet
+
+```rb
+# search for "foo" term anywhere in the document (case insensitive)
+foo
+
+# search for "foo" term anywhere in the document (case sensitive)
+'foo'
+"foo"
+
+# search for "foo" term in `name` field
+name:foo
+
+# search for "foo" term in `full name` field
+'full name':foo
+"full name":foo
+
+# search for "foo" term in `first` field, member of `name`, i.e.
+# matches {name: {first: 'foo'}}
+name.first:foo
+
+# search using regex
+name:/foo/
+name:/foo/o
+
+# search using wildcard
+name:foo*bar
+name:foo?bar
+
+# boolean search
+member:true
+member:false
+
+# null search
+member:null
+
+# search for age =, >, >=, <, <=
+height:=100
+height:>100
+height:>=100
+height:<100
+height:<=100
+
+# search for height in range (inclusive, exclusive)
+height:[100 TO 200]
+height:{100 TO 200}
+
+# boolean operators
+name:foo AND height:=100
+name:foo OR name:bar
+
+# unary operators
+NOT foo
+-foo
+NOT foo:bar
+-foo:bar
+name:foo AND NOT (bio:bar OR bio:baz)
+
+# implicit AND boolean operator
+name:foo height:=100
+
+# grouping
+name:foo AND (bio:bar OR bio:baz)
+```
+
+### Keyword matching
+
+Search for word "foo" in any field (case insensitive).
+
+```rb
+foo
+```
+
+Search for word "foo" in the `name` field.
+
+```rb
+name:foo
+```
+
+Search for `name` field values matching `/foo/i` regex.
+
+```rb
+name:/foo/i
+```
+
+Search for `name` field values matching `f*o` wildcard pattern.
+
+```rb
+name:f*o
+```
+
+Search for `name` field values matching `f?o` wildcard pattern.
+
+```rb
+name:f?o
+```
+
+Search for phrase "foo bar" in the `name` field (case sensitive).
+
+```rb
+name:"foo bar"
+```
+
+### Number matching
+
+Search for value equal to 100 in the `height` field.
+
+```rb
+height:=100
+```
+
+Search for value greater than 100 in the `height` field.
+
+```rb
+height:>100
+```
+
+Search for value greater than or equal to 100 in the `height` field.
+
+```rb
+height:>=100
+```
+
+### Range matching
+
+Search for value greater or equal to 100 and lower or equal to 200 in the `height` field.
+
+```rb
+height:[100 TO 200]
+```
+
+Search for value greater than 100 and lower than 200 in the `height` field.
+
+```rb
+height:{100 TO 200}
+```
+
+### Wildcard matching
+
+Search for any word that starts with "foo" in the `name` field.
+
+```rb
+name:foo*
+```
+
+Search for any word that starts with "foo" and ends with "bar" in the `name` field.
+
+```rb
+name:foo*bar
+```
+
+Search for any word that starts with "foo" in the `name` field, followed by a single arbitrary character.
+
+```rb
+name:foo?
+```
+
+Search for any word that starts with "foo", followed by a single arbitrary character and immediately ends with "bar" in the `name` field.
+
+```rb
+name:foo?bar
+```
+
+### Boolean operators
+
+Search for phrase "foo bar" in the `name` field AND the phrase "quick fox" in the `bio` field.
+
+```rb
+name:"foo bar" AND bio:"quick fox"
+```
+
+Search for either the phrase "foo bar" in the `name` field AND the phrase "quick fox" in the `bio` field, or the word "fox" in the `name` field.
+
+```rb
+(name:"foo bar" AND bio:"quick fox") OR name:fox
+```
+
+## Serializer
+
+Serializer allows to convert Liqe tokens back to the original search query.
+
+```ts
+import {
+  parse,
+  serialize,
+} from 'liqe';
+
+const tokens = parse('foo:bar');
+
+// {
+//   expression: {
+//     location: {
+//       start: 4,
+//     },
+//     quoted: false,
+//     type: 'LiteralExpression',
+//     value: 'bar',
+//   },
+//   field: {
+//     location: {
+//       start: 0,
+//     },
+//     name: 'foo',
+//     path: ['foo'],
+//     quoted: false,
+//     type: 'Field',
+//   },
+//   location: {
+//     start: 0,
+//   },
+//   operator: {
+//     location: {
+//       start: 3,
+//     },
+//     operator: ':',
+//     type: 'ComparisonOperator',
+//   },
+//   type: 'Tag',
+// }
+
+serialize(tokens);
+// 'foo:bar'
+```
+
+## AST
+
+```ts
+import {
+  type BooleanOperatorToken,
+  type ComparisonOperatorToken,
+  type EmptyExpression,
+  type FieldToken,
+  type ImplicitBooleanOperatorToken,
+  type ImplicitFieldToken,
+  type LiteralExpressionToken,
+  type LogicalExpressionToken,
+  type RangeExpressionToken,
+  type RegexExpressionToken,
+  type TagToken,
+  type UnaryOperatorToken,
+} from 'liqe';
+```
+
+There are 11 AST tokens that describe a parsed Liqe query.
+
+If you are building a serializer, then you must implement all of them for the complete coverage of all possible query inputs. Refer to the [built-in serializer](./src/serialize.ts) for an example.
+
+## Utilities
+
+```ts
+import {
+  isSafeUnquotedExpression,
+} from 'liqe';
+
+/**
+ * Determines if an expression requires quotes.
+ * Use this if you need to programmatically manipulate the AST
+ * before using a serializer to convert the query back to text.
+ */
+isSafeUnquotedExpression(expression: string): boolean;
+```
+
+## Compatibility with Lucene
+
+The following Lucene abilities are not supported:
+
+* [Fuzzy Searches](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#Fuzzy%20Searches)
+* [Proximity Searches](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#Proximity%20Searches)
+* [Boosting a Term](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html#Boosting%20a%20Term)
+
+## Recipes
+
+### Handling syntax errors
+
+In case of a syntax error, Liqe throws `SyntaxError`.
+
+```ts
+import {
+  parse,
+  SyntaxError,
+} from 'liqe';
+
+try {
+  parse('foo bar');
+} catch (error) {
+  if (error instanceof SyntaxError) {
+    console.error({
+      // Syntax error at line 1 column 5
+      message: error.message,
+      // 4
+      offset: error.offset,
+      // 1
+      offset: error.line,
+      // 5
+      offset: error.column,
+    });
+  } else {
+    throw error;
+  }
+}
+```
+
+### Highlighting matches
+
+Consider using [`highlight-words`](https://github.com/tricinel/highlight-words) package to highlight Liqe matches.
+
+## Development
+
+### Compiling Parser
+
+If you are going to modify parser, then use `npm run watch` to run compiler in watch mode.
+
+### Benchmarking Changes
+
+Before making any changes, capture the current benchmark on your machine using `npm run benchmark`. Run benchmark again after making any changes. Before committing changes, ensure that performance is not negatively impacted.
+
+
+## Tutorials
+
+* [Building advanced SQL search from a user text input](https://contra.com/p/WobOBob7-building-advanced-sql-search-from-a-user-text-input)

package/.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
+{
+	"name": "Ubuntu",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/base:jammy",
+	"features": {
+		"ghcr.io/devcontainers/features/node:1": {}
+	}
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "uname -a",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

package/.eslintignore

@@ -0,0 +1 @@
+examples/qk-next/components/**

package/.eslintrc.js

@@ -0,0 +1,39 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier'
+  ],
+  env: {
+    node: true,
+    jest: true
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'error',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': 'error',
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'interface',
+        format: ['PascalCase'],
+        prefix: ['I']
+      },
+      {
+        selector: 'class',
+        format: ['PascalCase']
+      },
+      {
+        selector: 'typeAlias',
+        format: ['PascalCase']
+      },
+      {
+        selector: 'enum',
+        format: ['PascalCase']
+      }
+    ]
+  }
+}; 

package/.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for more information:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+# https://containers.dev/guide/dependabot
+
+version: 2
+updates:
+ - package-ecosystem: "devcontainers"
+   directory: "/"
+   schedule:
+     interval: weekly

package/.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+name: QueryKit CI
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main, staging]
+
+jobs:
+  test:
+    name: Test & Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm i
+
+      - name: Lint code
+        run: pnpm run lint
+
+      - name: Check TypeScript compilation
+        run: pnpm exec tsc --noEmit
+
+      - name: Run tests
+        run: pnpm run test
+
+  build:
+    name: Build Package
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        id: pnpm-cache
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-node-${{ matrix.node-version }}-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-node-${{ matrix.node-version }}-
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build package
+        run: pnpm run build
+
+      - name: Create test package
+        run: pnpm pack
+
+      - name: Verify package exports
+        run: |
+          # Ensure package can be imported
+          mkdir -p test-import
+          cd test-import
+          echo '{ "type": "module" }' > package.json
+          echo 'import * as querykit from "../dist/index.js"; console.log("Package import successful!")' > test.js
+          node test.js
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: querykit-package-${{ matrix.node-version }}
+          path: querykit-*.tgz
+
+  

package/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish public release
+
+on:
+  release:
+    types: [published]
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag name (e.g., v0.0.0)'
+        required: true
+        type: string
+
+jobs:
+  publish-npm:
+    name: Publish package to npm registry
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          always-auth: true
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 8
+          run_install: false
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build package
+        run: pnpm run build
+
+      - name: Verify tag is set
+        run: test -n "${TAG}" || { echo "TAG missing"; exit 1; }
+        env:
+          TAG: ${{ github.event.release.tag_name || inputs.tag || '' }}
+
+      - name: Verify tag matches package.json version
+        env:
+          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
+
+