### Install and Run QL Input Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/README.md

Provides instructions on how to install and run any of the example projects. Users need to navigate into an example folder and use npm commands to install dependencies and start the application.

```bash
cd examples/[example-name]
npm install
npm start
```

--------------------------------

### Quick Start: Clone, Install, and Run Development Server

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Instructions to quickly set up the development environment for the QL input project. This involves cloning the repository, installing dependencies, starting the development server, and building packages.

```bash
# Clone and install dependencies
git clone <repository-url>
cd ql-input
npm install

# Start development server
npm run dev

# Build packages
npm run build:packages
```

--------------------------------

### Install @abaktiar/ql-parser Example

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Instructions to install the necessary dependencies for the parser-only example. Navigate to the `examples/parser-only` directory and run `npm install`.

```bash
cd examples/parser-only
npm install
```

--------------------------------

### Development Setup for QL Input Project

Source: https://github.com/abaktiar/ql-input/blob/main/README.md

Provides instructions for setting up the development environment, including cloning the repository, installing dependencies, starting the local development server, and building the project packages.

```bash
# Clone and install dependencies
git clone <repository-url>
cd ql-input
npm install

# Start development server
npm run dev

# Build packages
npm run build:packages
```

--------------------------------

### Install @abaktiar/ql-input React Example Dependencies

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Instructions to navigate to the example directory and install necessary npm packages for the React component example.

```Bash
cd examples/react-component
npm install
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Navigate to the example directory and install required Node.js packages using npm.

```Bash
cd examples/react-vite-api
npm install
```

--------------------------------

### Run @abaktiar/ql-input React Example Development Server

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Command to start the development server for the React component example, typically opening it in a browser at `http://localhost:3000`.

```Bash
npm run dev
```

--------------------------------

### Run @abaktiar/ql-parser Example

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Commands to run the parser-only example. Use `npm start` for a standard run or `npm run dev` for development with auto-reload.

```bash
npm start
```

```bash
npm run dev
```

--------------------------------

### Install QL Parser Package

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Command to install the `@abaktiar/ql-parser` package, which provides framework-agnostic QL parsing capabilities.

```bash
npm install @abaktiar/ql-parser
```

--------------------------------

### Complete Project Reset - Fresh Start Script - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This shell script automates a full project reset, removing all generated artifacts and caches, then reinstalling npm dependencies and Playwright browsers. It provides a guided, one-command solution for a clean project setup.

```bash
#!/bin/bash
echo "🧹 Performing complete project cleanup..."

# Remove all artifacts
rm -rf node_modules dist test-results playwright-report .playwright-cache .tsbuildinfo

echo "📦 Reinstalling dependencies..."
npm install

echo "🎭 Installing Playwright browsers..."
npm run test:install

echo "✅ Project reset complete!"
```

--------------------------------

### Verify Published Packages and Installation

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Commands to check the published versions of `@abaktiar/ql-parser` and `@abaktiar/ql-input` on npm and to test their local installation.

```bash
npm view @abaktiar/ql-parser

npm view @abaktiar/ql-input

npm install @abaktiar/ql-parser
npm install @abaktiar/ql-input
```

--------------------------------

### Install QL Input React Component

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Command to install the `@abaktiar/ql-input` package, which provides a React component with UI for the QL parser.

```bash
npm install @abaktiar/ql-input
```

--------------------------------

### Start Frontend Development Server Separately

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Launches only the React frontend development server, typically running on `http://localhost:3000`.

```Bash
npm run dev
```

--------------------------------

### Install QL Parser Package

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Command to install the framework-agnostic QL parser package using npm, enabling its usage in any JavaScript/TypeScript project.

```bash
npm install @abaktiar/ql-parser
```

--------------------------------

### Install QLInput React Component

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Installs the `@abaktiar/ql-input` package using npm, which includes the React component and its default styles.

```bash
npm install @abaktiar/ql-input
```

--------------------------------

### Troubleshooting with a Fresh Installation (Bash)

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This 'nuclear option' command sequence removes `node_modules` and `package-lock.json` to ensure a completely fresh start, then reinstalls all dependencies and runs a test installation script. It's used when facing persistent dependency or build issues.

```bash
rm -rf node_modules package-lock.json
npm install
npm run test:install
```

--------------------------------

### QLInput Component Development Workflow Commands

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Outlines essential `npm` scripts for developing, building, and testing the `ql-input` component and its associated packages. Commands cover starting development servers, building artifacts, running various test suites, and maintaining code quality through linting.

```bash
# Development
npm run dev                    # Start development server
npm run build                  # Build demo application
npm run preview               # Preview built application

# Package Building
npm run build:parser          # Build parser package
npm run build:input           # Build input component package
npm run build:packages        # Build both packages

# Testing
npm test                      # Run all tests
npm run test:unit             # Run unit tests
npm run test:integration      # Run integration tests
npm run test:e2e              # Run end-to-end tests
npm run test:clean            # Clean test artifacts

# Linting and Formatting
npm run lint                  # Run ESLint
npm run lint:fix              # Fix ESLint issues
npm run type-check            # Run TypeScript checks
```

--------------------------------

### Start Backend API Server Separately

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Initiates only the Express.js backend API server, typically running on `http://localhost:3001`.

```Bash
npm run server
```

--------------------------------

### Run Frontend and Backend Together

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Starts both the Express.js backend API server on `http://localhost:3001` and the React frontend development server on `http://localhost:3000` concurrently.

```Bash
npm run dev:full
```

--------------------------------

### Git Post-merge Hook for Cleanup and Install - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This script, placed in `.git/hooks/post-merge`, automatically runs `npm run test:clean` and `npm install` after a successful `git merge`. It ensures the project is clean and dependencies are up-to-date after integrating changes from another branch.

```bash
#!/bin/sh
npm run test:clean
npm install  # Update dependencies if needed
```

--------------------------------

### Publishing Workflow: First Time Steps

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Commands for the initial publishing workflow, including building packages, publishing the parser first, and then rebuilding and publishing the input component after updating its dependency.

```bash
npm run build:packages
```

```bash
npm run publish:parser
```

```bash
npm run build:input
npm run publish:input
```

--------------------------------

### Install @abaktiar/ql-input npm package

Source: https://github.com/abaktiar/ql-input/blob/main/README.md

Instructions to install the `@abaktiar/ql-input` package using npm.

```bash
npm install @abaktiar/ql-input
```

--------------------------------

### Basic React Component Setup with QLInput

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Demonstrates how to integrate the `QLInput` component into a React application. This example includes defining a `QLInputConfig` for fields, operators, and options, and handling `onChange` and `onExecute` events for query management.

```tsx
import React from 'react';
import { QLInput } from '@abaktiar/ql-input';
import '@abaktiar/ql-input/styles.css';
import type { QLInputConfig, QLQuery } from '@abaktiar/ql-input';

const config: QLInputConfig = {
  fields: [
    {
      name: 'status',
      displayName: 'Status',
      type: 'option',
      operators: ['=', '!=', 'IN', 'NOT IN'],
      options: [
        { value: 'open', label: 'Open' },
        { value: 'closed', label: 'Closed' },
        { value: 'pending', label: 'Pending' }
      ]
    },
    {
      name: 'assignee',
      displayName: 'Assignee',
      type: 'user',
      operators: ['=', '!=', 'IS EMPTY', 'IS NOT EMPTY']
    },
    {
      name: 'created',
      displayName: 'Created Date',
      type: 'date',
      operators: ['=', '>', '<', '>=', '<='],
      sortable: true
    }
  ],
  maxSuggestions: 10,
  caseSensitive: false,
  allowParentheses: true,
  allowOrderBy: true,
  allowFunctions: true
};

function MyComponent() {
  const handleChange = (value: string, query: QLQuery) => {
    console.log('Query changed:', value);
    console.log('Parsed query:', query);
  };

  const handleExecute = (query: QLQuery) => {
    console.log('Query executed:', query);
    // Handle query execution (e.g., API call)
  };

  return (
    <QLInput
      config={config}
      placeholder="Enter your query..."
      onChange={handleChange}
      onExecute={handleExecute}
    />
  );
}
```

--------------------------------

### Use QL Parser in TypeScript

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

TypeScript example demonstrating how to import and instantiate the `QLParser` class from `@abaktiar/ql-parser` to parse a query string.

```typescript
import { QLParser } from '@abaktiar/ql-parser';

const parser = new QLParser(config);
const query = parser.parse('status = "open"');
```

--------------------------------

### Basic Query Language Function Examples

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Provides examples of basic function usage within the QLInput component's query language. These examples demonstrate user-related, date-related, and project-related functions, showcasing how to incorporate simple functions into queries.

```sql
-- User functions
assignee = currentUser()
assignee = userInRole("admin")
assignee IN (currentUser(), userInRole("manager"))

-- Date functions
created >= daysAgo(30)
updated <= daysFromNow(7)
created = dateRange("2023-01-01", "2023-12-31")

-- Project functions
project = projectsWithPrefix("PROJ")
```

--------------------------------

### Real-World QL Query Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/README.md

Illustrates practical applications of the QL parser with examples for filtering recent items, role-based assignment, and complex combined conditions involving multiple logical operators and functions.

```QL
created >= daysAgo(7)
```

```QL
assignee = userInRole("admin")
```

```QL
(status = "open" OR status = "pending") AND assignee IN (currentUser(), userInRole("manager"))
```

--------------------------------

### Cleanup - Remove and Reinstall Node.js Dependencies - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This sequence of commands first removes the entire `node_modules` directory, effectively deleting all installed project dependencies. It then runs `npm install` to reinstall all dependencies from scratch, ensuring a clean and consistent environment.

```bash
rm -rf node_modules
npm install
```

--------------------------------

### Basic QL Query Parsing Examples

Source: https://github.com/abaktiar/ql-input/blob/main/README-parser.md

Demonstrates how to initialize the QLParser and parse various simple and complex QL query strings. Examples include single conditions, multiple conditions with AND/OR, and complex grouping using parentheses.

```typescript
const parser = new QLParser(config);

// Simple condition
const simple = parser.parse('status = "open"');

// Multiple conditions with AND
const multiple = parser.parse('status = "open" AND priority = "high"');

// Conditions with OR
const withOr = parser.parse('status = "open" OR status = "pending"');

// Complex grouping with parentheses
const complex = parser.parse('(status = "open" OR status = "pending") AND assignee = currentUser()');
```

--------------------------------

### Install @abaktiar/ql-input and Peer Dependencies

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Instructions for installing the `@abaktiar/ql-input` component and its required peer dependencies (`react`, `react-dom`) using npm, yarn, or pnpm package managers.

```bash
npm install @abaktiar/ql-input
```

```bash
yarn add @abaktiar/ql-input
```

```bash
pnpm add @abaktiar/ql-input
```

```bash
npm install react react-dom
```

--------------------------------

### Backend Deployment

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Instructions for deploying the Node.js backend server. The `server/` folder should be deployed to a Node.js hosting service, and the `PORT` environment variable may need to be configured.

```bash
# Deploy server/ folder to your Node.js hosting service
# Set PORT environment variable if needed
```

--------------------------------

### Frontend Deployment

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Provides the command to build the frontend application for deployment. The resulting `dist/` folder contains the static assets ready to be served by a hosting service.

```bash
npm run build
# Deploy dist/ folder to your hosting service
```

--------------------------------

### Install @abaktiar/ql-parser

Source: https://github.com/abaktiar/ql-input/blob/main/README-parser.md

Instructions for installing the @abaktiar/ql-parser library using npm, yarn, or pnpm package managers. Choose the command appropriate for your project's package manager.

```bash
npm install @abaktiar/ql-parser
```

```bash
yarn add @abaktiar/ql-parser
```

```bash
pnpm add @abaktiar/ql-parser
```

--------------------------------

### Use QL Input React Component

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

React (TSX) example showing how to import and render the `QLInput` component from `@abaktiar/ql-input`, including its required stylesheet.

```tsx
import { QLInput } from '@abaktiar/ql-input';
import '@abaktiar/ql-input/styles.css';

function App() {
  return <QLInput config={config} />;
}
```

--------------------------------

### Cleanup in CI/CD Pipeline - npm

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This example demonstrates integrating cleanup into a CI/CD pipeline. After running tests, test artifacts are cleaned before archiving or deploying, ensuring that only necessary build outputs are retained.

```bash
npm test
npm run test:clean  # Clean artifacts before archiving
```

--------------------------------

### Complete QL-Input Configuration Example

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Provides a comprehensive example of `QLInputConfig` for the `@abaktiar/ql-input` library. It demonstrates defining multiple field types (text, option, number, user, date, multiselect), global settings like `maxSuggestions`, `caseSensitive`, and custom functions with parameters.

```typescript
import { QLInputConfig } from '@abaktiar/ql-input';

const fullConfig: QLInputConfig = {
  fields: [
    {
      name: 'title',
      displayName: 'Title',
      type: 'text',
      operators: ['=', '!=', '~', '!~', 'IS EMPTY', 'IS NOT EMPTY'],
      description: 'Issue title or summary'
    },
    {
      name: 'status',
      displayName: 'Status',
      type: 'option',
      operators: ['=', '!=', 'IN', 'NOT IN'],
      options: [
        { value: 'open', label: 'Open' },
        { value: 'in-progress', label: 'In Progress' },
        { value: 'closed', label: 'Closed' },
        { value: 'pending', label: 'Pending Review' }
      ]
    },
    {
      name: 'priority',
      displayName: 'Priority',
      type: 'number',
      operators: ['=', '!=', '>', '<', '>=', '<='],
      sortable: true,
      options: [
        { value: '1', label: 'Low' },
        { value: '2', label: 'Medium' },
        { value: '3', label: 'High' },
        { value: '4', label: 'Critical' }
      ]
    },
    {
      name: 'assignee',
      displayName: 'Assignee',
      type: 'user',
      operators: ['=', '!=', 'IS EMPTY', 'IS NOT EMPTY'],
      asyncValueSuggestions: true
    },
    {
      name: 'created',
      displayName: 'Created Date',
      type: 'date',
      operators: ['=', '!=', '>', '<', '>=', '<='],
      sortable: true
    },
    {
      name: 'tags',
      displayName: 'Tags',
      type: 'multiselect',
      operators: ['IN', 'NOT IN'],
      options: [
        { value: 'bug', label: 'Bug' },
        { value: 'feature', label: 'Feature' },
        { value: 'enhancement', label: 'Enhancement' }
      ]
    }
  ],
  maxSuggestions: 15,
  caseSensitive: false,
  allowParentheses: true,
  allowOrderBy: true,
  allowFunctions: true,
  functions: [
    {
      name: 'currentUser',
      displayName: 'currentUser()',
      description: 'The currently logged-in user',
    },
    {
      name: 'now',
      displayName: 'now()',
      description: 'Current date and time',
    },
    {
      name: 'today',
      displayName: 'today()',
      description: 'Today\'s date',
    },
    {
      name: 'daysAgo',
      displayName: 'daysAgo(days)',
      description: 'Date N days ago from today',
      parameters: [{
        name: 'days',
        type: 'number',
        required: true,
        description: 'Number of days'
      }]
    },
    {
      name: 'userInRole',
      displayName: 'userInRole(role)',
      description: 'Users with specific role',
      parameters: [{
        name: 'role',
        type: 'text',
        required: true,
        description: 'User role name'
      }]
    }
  ]
};
```

--------------------------------

### Install QL Parser npm Package

Source: https://github.com/abaktiar/ql-input/blob/main/README.md

Command to install the `@abaktiar/ql-parser` package, which provides framework-agnostic query parsing capabilities, into your project using npm.

```bash
npm install @abaktiar/ql-parser
```

--------------------------------

### API Testing with cURL

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Shows how to interact with the QL Input API endpoints using `curl` for various operations. Examples include fetching all issues, performing a QL search with a JSON body, and getting user suggestions via query parameters.

```bash
# Get all issues
curl http://localhost:3001/api/issues

# Search with QL query
curl -X POST http://localhost:3001/api/issues/search \
  -H "Content-Type: application/json" \
  -d '{"query": "status = \"open\" AND priority >= 3"}'

# Get user suggestions
curl "http://localhost:3001/api/suggestions/users?q=john"
```

--------------------------------

### Update Input Package Dependency Version

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Example JSON snippet showing how to update the version of the `@abaktiar/ql-parser` dependency within the `package-input.json` file.

```json
{
  "dependencies": {
    "@abaktiar/ql-parser": "^1.1.0"
  }
}
```

--------------------------------

### Example QL Query Syntax

Source: https://github.com/abaktiar/ql-input/blob/main/README.md

Illustrates various complex query examples supported by the QL Input component, including basic filtering, user functions, parameterized functions, date functions, text search, and complex grouping.

```sql
# Basic field filtering
project = PROJ1 AND status = "In Progress"

# User functions
assignee = currentUser() AND priority IN (High, Highest)

# Parameterized functions with arguments
assignee = currentUser() AND created >= daysAgo(30)
assignee = userInRole("admin") AND status = Open
created >= daysAgo(7) AND updated <= daysFromNow(1)

# Functions with multiple parameters
created = dateRange("2023-01-01", "2023-12-31")
project = projectsWithPrefix("PROJ") AND assignee = currentUser()

# Functions in IN lists
assignee IN (currentUser(), userInRole("manager")) AND priority = High

# Date functions with ordering
created >= startOfWeek() ORDER BY priority DESC

# Text search
summary ~ "bug" AND status != Done

# Complex grouping with functions
(created >= daysAgo(30) AND assignee = currentUser()) OR priority = Highest
```

--------------------------------

### Monorepo File Structure Overview

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

A textual representation of the monorepo's key directories and files, illustrating the organization of source code, build outputs, and package metadata.

```text
├── dist/
│   ├── parser/           # Built parser package
│   │   ├── index.js
│   │   ├── index.mjs
│   │   ├── index.d.mts
│   │   ├── package.json
│   │   └── README.md
│   └── input/            # Built input package
│       ├── index.js
│       ├── index.mjs
│       ├── index.d.mts
│       ├── styles.css
│       ├── package.json
│       └── README.md
├── src/                  # Source code
├── package-parser.json   # Parser package metadata
├── package-input.json    # Input package metadata
├── README-parser.md      # Parser documentation
├── README-input.md       # Input documentation
├── vite.config.parser.ts # Parser build config
└── vite.config.input.ts  # Input build config
```

--------------------------------

### QL Input & Parser Package Installation

Source: https://github.com/abaktiar/ql-input/blob/main/RELEASE-1.5.0.md

Provides the npm commands to install the @abaktiar/ql-input and @abaktiar/ql-parser packages at version 1.5.0. These commands are used to set up the libraries in a project.

```bash
npm install @abaktiar/ql-input@1.5.0
# or
npm install @abaktiar/ql-parser@1.5.0
```

--------------------------------

### GitHub Actions Workflow for Automated Package Publishing

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

This YAML configuration defines a GitHub Actions workflow that automatically publishes packages when a new release is published. It checks out the repository, sets up Node.js, installs dependencies, builds packages, and then publishes them to the configured npm registry using a `NPM_TOKEN` secret.

```YAML
name: Publish Packages
on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      - run: npm run build:packages
      - run: npm run publish:all
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

--------------------------------

### Build Individual or Both Packages

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Commands to build the `@abaktiar/ql-parser` and `@abaktiar/ql-input` packages separately or both at once, generating CommonJS, ES modules, and TypeScript declarations.

```bash
npm run build:parser

npm run build:input

npm run build:packages
```

--------------------------------

### Publishing Workflow: Subsequent Updates

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Command for subsequent updates, which involves updating versions and then using a single command to build and publish both packages.

```bash
npm run publish:all
```

--------------------------------

### QL: Real-World Query Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Presents practical, complete QL query examples that simulate common real-world use cases. These queries combine filtering and sorting to retrieve specific sets of data, such as high-priority open issues, unassigned critical items, recent bug reports, project-specific entries, and security-related items.

```sql
-- High priority open issues
status = "open" AND priority >= 3 ORDER BY priority DESC

-- Unassigned critical issues
assignee IS EMPTY AND priority = 4

-- Recent bug reports
title ~ "bug" AND created >= "2024-01-10" ORDER BY created DESC

-- Project-specific open issues
project = "project-alpha" AND status != "closed" ORDER BY priority DESC

-- Security-related items
tags IN ("security", "audit") ORDER BY priority DESC, created ASC
```

--------------------------------

### Parameterized Function Query Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/README.md

Demonstrates various parameterized functions supported by the QL parser, showcasing date calculations, role-based user filtering, and date range queries, including functions used within IN lists.

```QL
daysAgo(30)
```

```QL
userInRole("admin")
```

```QL
dateRange("start", "end")
```

```QL
assignee IN (currentUser(), userInRole("manager"))
```

--------------------------------

### Publish Individual Packages

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Commands to publish the `@abaktiar/ql-parser` or `@abaktiar/ql-input` package independently to the npm registry.

```bash
npm run publish:parser

npm run publish:input
```

--------------------------------

### QL Query Function Syntax Examples

Source: https://github.com/abaktiar/ql-input/blob/main/README-parser.md

Illustrates various contexts in which functions can be utilized within QL queries, including single conditions, IN lists, complex expressions, and nested function calls. These examples demonstrate the flexibility of QL's function integration.

```QL
created >= daysAgo(30)
```

```QL
assignee IN (currentUser(), userInRole("admin"))
```

```QL
(created >= daysAgo(30) AND assignee = currentUser()) OR priority = "High"
```

```QL
dateRange("2023-01-01", daysAgo(30))
```

--------------------------------

### Log in to npm Registry

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

Command to authenticate with the npm registry, a prerequisite for publishing packages to ensure proper access.

```bash
npm login
```

--------------------------------

### Publish Both Packages Simultaneously

Source: https://github.com/abaktiar/ql-input/blob/main/docs/PUBLISHING.md

A single command to build and publish both `@abaktiar/ql-parser` and `@abaktiar/ql-input` packages to the npm registry.

```bash
npm run publish:all
```

--------------------------------

### QL: Sorting Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Provides various examples of sorting query results using the `ORDER BY` clause. It covers single-field and multi-field sorting, specifying ascending (`ASC`) or descending (`DESC`) order, and combining sorting with filtering conditions.

```sql
-- Single field sorting
ORDER BY priority DESC
ORDER BY created ASC

-- Multi-field sorting
ORDER BY priority DESC, created ASC
ORDER BY status ASC, priority DESC, created ASC

-- Filtering with sorting
status = "open" ORDER BY priority DESC, created ASC
priority >= 3 ORDER BY priority DESC, created ASC
```

--------------------------------

### Project Architecture: Directory Structure Overview

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Illustrates the hierarchical organization of files and folders within the QL input project, highlighting key components like UI, parser libraries, hooks, and package entry points.

```text
src/
├── components/
│   ├── ui/
│   │   ├── ql-input.tsx       # Main QL input component
│   │   └── icons.tsx          # Icon components
│   └── ql-demo.tsx            # Demo component
├── lib/
│   ├── ql-types.ts            # TypeScript types
│   ├── ql-parser.ts           # Query parser
│   ├── ql-expression-parser.ts # Expression tree builder
│   ├── ql-query-builder.ts    # Query format converters
│   ├── ql-suggestions.ts      # Suggestion engine
│   └── utils.ts               # Utility functions
├── hooks/
│   ├── use-ql-input.ts        # Main input logic
│   └── use-debounce.ts        # Debouncing utility
├── styles.css                 # Component styles
├── index.input.ts             # Input package entry point
└── lib/index.parser.ts        # Parser package entry point
```

--------------------------------

### Real-World Query Language Use Cases

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Presents practical examples of QLInput queries for common scenarios like finding recent work, admin oversight, project timeline queries, and team management. These examples demonstrate how the query language can be applied to solve real-world data filtering challenges.

```sql
-- Find my recent work
assignee = currentUser() AND updated >= daysAgo(7)

-- Admin oversight
assignee = userInRole("admin") AND status = "In Progress"

-- Project timeline queries
project = projectsWithPrefix("PROJ") AND created >= dateRange("2023-01-01", "2023-12-31")

-- Team management
assignee IN (userInRole("developer"), userInRole("qa")) AND priority >= High
```

--------------------------------

### QL Query Basic Filtering Examples

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Demonstrates common QL query syntax for filtering data based on status, priority, and assignee using equality, comparison, and null operators.

```SQL
-- Status filtering
status = "open"
status IN ("open", "pending")
status NOT IN ("closed")

-- Priority filtering
priority >= 3
priority = 4

-- Assignee filtering
assignee IS EMPTY
assignee IS NOT EMPTY
assignee = "john.doe"
```

--------------------------------

### Define QLInput Configuration for Fields and Features

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Provides an example of the `QLInputConfig` object, detailing how to define fields with their names, display names, types, operators, and options. It also shows how to enable global features like parentheses, order by, and functions.

```tsx
const config: QLInputConfig = {
  fields: [
    {
      name: 'status',
      displayName: 'Status',
      type: 'option',
      operators: ['=', '!=', 'IN', 'NOT IN'],
      options: [/* predefined options */]
    },
    {
      name: 'assignee',
      displayName: 'Assignee',
      type: 'user',
      operators: ['=', '!=', 'IS EMPTY', 'IS NOT EMPTY'],
      asyncValueSuggestions: true // Enable async suggestions
    },
    // ... more fields
  ],
  allowParentheses: true,
  allowOrderBy: true,
  allowFunctions: true
};
```

--------------------------------

### Parse Query with @abaktiar/ql-parser

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Demonstrates how to parse a query string using the `parser.parse()` method. It shows how to check for validity and retrieve any errors.

```javascript
const query = parser.parse('status = "open" AND priority >= 3');
console.log(query.valid); // true/false
console.log(query.errors); // Array of error messages
```

--------------------------------

### QL Parser Parameterized Function Examples

Source: https://github.com/abaktiar/ql-input/blob/main/RELEASE-1.5.0.md

Showcases the enhanced support for parameterized functions within QL queries. Examples include filtering by user roles, project prefixes, and date ranges, demonstrating robust parsing for complex function calls.

```sql
-- Enhanced function support with parameters
assignee = userInRole("admin") AND created >= daysAgo(30)
project = projectsWithPrefix("PROJ") AND status IN ("open", "pending")
created = dateRange("2023-01-01", "2023-12-31") ORDER BY priority DESC
```

--------------------------------

### Basic QLInput Component Integration in React

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Demonstrates the fundamental usage of the `QLInput` component, including importing necessary modules and passing essential props like `config`, `value`, `onChange`, `onExecute`, `placeholder`, and optional display icons.

```tsx
import { QLInput, QLQuery, QLInputConfig } from '@abaktiar/ql-input';
import '@abaktiar/ql-input/styles.css';

<QLInput
  config={config}
  value={currentQuery}
  onChange={handleQueryChange}
  onExecute={handleQueryExecute}
  placeholder="Enter your query..."
  showSearchIcon={true}  // Optional: default is true
  showClearIcon={true}   // Optional: default is true
/>
```

--------------------------------

### Preparing for Git Commit (Bash)

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This sequence of commands cleans tests, stages all changes, and then commits them with a user-provided message. It ensures that only clean, tested code is committed to the repository.

```bash
npm run test:clean
git add .
git commit -m "Your changes"
```

--------------------------------

### QL Input API Endpoints

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Overview of the available REST API endpoints for issues, suggestions, and health checks, including their HTTP methods and paths.

```APIDOC
Issues:
- GET /api/issues - Get all issues
- POST /api/issues/search - Search with QL query

Suggestions:
- GET /api/suggestions/users?q=search - User autocomplete
- GET /api/suggestions/projects?q=search - Project autocomplete

Utility:
- GET /api/health - Server health check
```

--------------------------------

### Troubleshooting - Cleanup Files In Use - npm

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command attempts to clean test artifacts. If files are in use by other processes (e.g., open browsers or editors), the cleanup might fail. The description advises closing such applications before running the command.

```bash
npm run test:clean
```

--------------------------------

### QL Input API Endpoints

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Documentation for the core API endpoints used by the QL Input component, including search, suggestions, and general issue retrieval. This section outlines the methods, paths, parameters, and expected responses for each endpoint.

```APIDOC
API Endpoints:

1. Get All Issues
   Method: GET
   Path: /api/issues
   Description: Retrieves a list of all available issues.
   Response: Array of issue objects.

2. Search Issues with QL Query
   Method: POST
   Path: /api/issues/search
   Description: Filters issues based on a provided QL (Query Language) string.
   Request Body:
     query: string (The QL query string, e.g., "status = \"open\" AND priority >= 3")
   Response:
     data: Array of filtered issue objects
     metadata: Object (Contains information about the query, e.g., validation status)

3. Get User Suggestions
   Method: GET
   Path: /api/suggestions/users
   Description: Provides user suggestions based on a search query.
   Parameters:
     q: string (Query string to filter user names, e.g., "john")
   Response: Array of user suggestion strings.
```

--------------------------------

### QL: Complex Conditions

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-vite-api/README.md

Illustrates the construction of complex QL queries by combining multiple conditions. Examples include using logical operators (`AND`, `OR`), grouping conditions with parentheses, checking for empty values (`IS EMPTY`), and performing text searches (`~`).

```sql
-- Multiple conditions with grouping
(status = "open" OR status = "pending") AND priority >= 3

-- Complex assignee and priority logic
(assignee IS EMPTY OR assignee = "john.doe") AND priority = 4

-- Text search with status filter
title ~ "bug" AND status != "closed"
```

--------------------------------

### Performing Weekly Project Maintenance (Bash)

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

These commands perform routine weekly maintenance, including cleaning tests, auditing for security vulnerabilities, and updating project dependencies to their latest compatible versions.

```bash
npm run test:clean
npm audit
npm update
```

--------------------------------

### Troubleshooting - Cleanup Permission Errors (npm) - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command attempts to clean test artifacts using the defined npm script. It's the standard approach, but may require elevated permissions on some systems if permission errors occur.

```bash
npm run test:clean
```

--------------------------------

### Configure Fields for @abaktiar/ql-parser

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Illustrates a comprehensive field configuration object used by the parser. It defines field properties like name, display name, type, allowed operators, and options, along with global settings for parentheses, order by, and functions.

```javascript
const config = {
  fields: [
    {
      name: 'status',
      displayName: 'Status',
      type: 'option',
      operators: ['=', '!=', 'IN', 'NOT IN'],
      options: [/* ... */]
    },
    // ... more fields
  ],
  allowParentheses: true,
  allowOrderBy: true,
  allowFunctions: true
};
```

--------------------------------

### Tokenize Query String with @abaktiar/ql-parser

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Shows how to tokenize a query string using `parser.tokenize()`. This method breaks down the query into an array of tokens, each with its type, value, and position.

```javascript
const tokens = parser.tokenize('status = "open"');
// Returns array of tokens with type, value, and position
```

--------------------------------

### Troubleshooting - Clean Test Artifacts for Disk Space - npm

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command executes the predefined npm script to remove all test artifacts. It's recommended for immediate use when disk space is low due to accumulated test results and reports.

```bash
npm run test:clean
```

--------------------------------

### Cleanup After Testing Sessions - npm

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This sequence of commands first runs the project's tests and then immediately cleans up all generated test artifacts. It ensures that test results and reports are removed after each testing session, maintaining a clean workspace.

```bash
npm test
npm run test:clean
```

--------------------------------

### QL Query Language Core Concepts and Syntax

Source: https://github.com/abaktiar/ql-input/blob/main/README-parser.md

Comprehensive documentation of the QL (Query Language) syntax, including its query structure, supported comparison, text, list, null, and logical operators, and a list of built-in parameterless and parameterized functions with usage examples.

```APIDOC
Query Structure:
  A QL query consists of:
  1. WHERE clause - Conditions and logical operators
  2. ORDER BY clause - Sorting specifications (optional)
  Example: status = "open" AND assignee = currentUser() ORDER BY created DESC, priority ASC

Supported Operators:
  Comparison Operators:
    =   - Equals
    !=  - Not equals
    >   - Greater than
    <   - Less than
    >=  - Greater than or equal
    <=  - Less than or equal
  Text Operators:
    ~   - Contains (case-insensitive)
    !~  - Does not contain
  List Operators:
    IN  - Value in list
    NOT IN - Value not in list
  Null Operators:
    IS EMPTY    - Field is empty/null
    IS NOT EMPTY - Field is not empty/null
  Logical Operators:
    AND - Logical AND
    OR  - Logical OR
    NOT - Logical NOT (prefix)

Functions:
  Built-in functions for dynamic values:

  Parameterless Functions:
    currentUser()   - Current user identifier
    now()           - Current timestamp
    today()         - Today's date
    startOfWeek()   - Start of current week
    endOfWeek()     - End of current week
    startOfMonth()  - Start of current month
    endOfMonth()    - End of current month

  Parameterized Functions:
    daysAgo(days: number) - Date N days ago from today
      Example: daysAgo(30) // 30 days ago
      Example: daysAgo(7)  // 7 days ago
    daysFromNow(days: number) - Date N days from today
      Example: daysFromNow(14) // 14 days from now
    dateRange(start: string, end: string) - Date range between two dates (format: "YYYY-MM-DD")
      Example: dateRange("2023-01-01", "2023-12-31")
    userInRole(role: string) - Users with specific role
      Example: userInRole("admin")
      Example: userInRole("manager")
    projectsWithPrefix(prefix: string) - Projects with name prefix
      Example: projectsWithPrefix("PROJ")
      Example: projectsWithPrefix("DEV")
```

--------------------------------

### Development, Build, and Publishing Commands

Source: https://github.com/abaktiar/ql-input/blob/main/README.md

Lists essential `npm` commands for local development, including starting the development server, building the demo application, and previewing the build. It also covers commands for building and publishing the individual parser and input component packages, as well as both packages simultaneously.

```bash
# Development
npm run dev                    # Start development server
npm run build                  # Build demo application
npm run preview               # Preview built application

# Package Building
npm run build:parser          # Build parser package
npm run build:input           # Build input component package
npm run build:packages        # Build both packages

# Testing
npm test                      # Run all tests
npm run test:unit             # Run unit tests
npm run test:integration      # Run integration tests
npm run test:e2e              # Run end-to-end tests
npm run test:clean            # Clean test artifacts

# Publishing
npm run publish:parser        # Publish parser package
npm run publish:input         # Publish input component package
npm run publish:all           # Publish both packages
```

--------------------------------

### Cleanup Before Git Commit - npm

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This sequence ensures that no test artifacts are accidentally committed to the version control system. It cleans test artifacts before staging changes and committing them, promoting a clean repository history.

```bash
npm run test:clean
git add .
git commit -m "Your commit message"
```

--------------------------------

### Convert Parsed Query to Different Formats

Source: https://github.com/abaktiar/ql-input/blob/main/examples/parser-only/README.md

Illustrates how to convert a parsed query object into various output formats, including MongoDB queries, SQL WHERE clauses, and human-readable expressions. It also shows how to count conditions within the query.

```javascript
// Convert to MongoDB query
const mongoQuery = toMongooseQuery(query);

// Convert to SQL WHERE clause
const sqlQuery = toSQLQuery(query);

// Get readable expression
const readable = printExpression(query.where);

// Count conditions
const count = countConditions(query);
```

--------------------------------

### Troubleshooting - Check Disk Usage of Test Artifacts - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command uses `du -sh` to display the human-readable disk usage of specific test artifact directories. It helps identify which cleanup targets are consuming the most disk space.

```bash
du -sh test-results playwright-report .playwright-cache
```

--------------------------------

### Troubleshooting - Cleanup Permission Errors (sudo npm) - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command attempts to clean test artifacts with elevated permissions using `sudo` (on Linux/Mac). It's a common solution when encountering permission denied errors during cleanup operations.

```bash
sudo npm run test:clean  # Linux/Mac
# Or run as Administrator on Windows
```

--------------------------------

### Configure Async Value Suggestions for QLInput Component

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Shows how to provide an asynchronous function to the `QLInput` component via the `getAsyncValueSuggestions` prop. This function simulates an API call to fetch suggestions based on the field and typed value.

```tsx
const getAsyncValueSuggestions = async (field: string, typedValue: string) => {
  // Simulate API call
  const response = await fetch(`/api/suggestions/${field}?q=${typedValue}`);
  return response.json();
};

<QLInput
  config={config}
  getAsyncValueSuggestions={getAsyncValueSuggestions}
/>
```

--------------------------------

### Enable Debug Logging for QLParser

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Shows how to activate detailed debug logging for the `QLParser` instance. Setting the `debug` option to `true` provides verbose output in the console, aiding in troubleshooting parsing and configuration issues.

```typescript
const parser = new QLParser(config, { debug: true });
```

--------------------------------

### Cleanup - Remove VS Code Settings - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This command removes the `.vscode` directory, which contains project-specific Visual Studio Code settings, launch configurations, and extensions recommendations. It's an optional cleanup step to reset editor configurations.

```bash
rm -rf .vscode
```

--------------------------------

### Apply Custom CSS Theme to QLInput Component

Source: https://github.com/abaktiar/ql-input/blob/main/README-input.md

Illustrates how to create a custom CSS theme by overriding specific QLInput custom properties. This example defines a `.my-custom-theme` class to change border color, ring color, background, and border radius.

```css
/* Custom theme */
.my-custom-theme {
  --ql-input-border: #3b82f6;
  --ql-input-ring: #1d4ed8;
  --ql-input-background: #f8fafc;
  --ql-input-radius: 0.75rem;
}
```

--------------------------------

### Implement Async User Value Suggestions for QLInput

Source: https://github.com/abaktiar/ql-input/blob/main/examples/react-component/README.md

Demonstrates a mock implementation of an asynchronous suggestion handler for a 'user' field. It filters a predefined list of mock user data based on the typed value, simulating an API call for user suggestions.

```tsx
// Mock user data
const mockUsers = [
  { value: 'john.doe', label: 'John Doe' },
  { value: 'jane.smith', label: 'Jane Smith' },
  // ...
];

// Async suggestion handler
const getAsyncValueSuggestions = async (field: string, typedValue: string) => {
  if (field === 'assignee') {
    return mockUsers.filter(user =>
      user.label.toLowerCase().includes(typedValue.toLowerCase())
    );
  }
  return [];
};
```

--------------------------------

### Git Pre-commit Hook for Test Cleanup - Bash

Source: https://github.com/abaktiar/ql-input/blob/main/docs/CLEANUP_GUIDE.md

This script, placed in `.git/hooks/pre-commit`, automatically runs the `npm run test:clean` command before every commit. It ensures that no test artifacts are ever committed to the repository, enforcing a clean commit history.

```bash
#!/bin/sh
npm run test:clean
```

--------------------------------

### Tokenize QLInput Queries

Source: https://github.com/abaktiar/ql-input/blob/main/README-parser.md

This TypeScript example shows how to tokenize a QLInput query string to get detailed information about each token, including its type, value, and position. It iterates through the tokens and logs their details.

```typescript
// Get detailed token information
const tokens = parser.tokenize('status = "open" AND assignee = currentUser()');

tokens.forEach(token => {
  console.log(`${token.type}: "${token.value}" at position ${token.start}-${token.end}`);
});
```

--------------------------------

### Optimize QLInput Performance with Debouncing and Memoization

Source: https://github.com/abaktiar/ql-input/blob/main/docs/DEVELOPMENT.md

Presents techniques for enhancing the performance of `QLInput` in React applications. Examples include debouncing asynchronous suggestion functions to reduce API calls and memoizing component configurations to prevent unnecessary re-renders.

```typescript
// Debounce async suggestions
const debouncedSuggestions = useMemo(
  () => debounce(getAsyncValueSuggestions, 300),
  [getAsyncValueSuggestions]
);

// Memoize configuration
const memoizedConfig = useMemo(() => config, [/* dependencies */]);
```