@marianmeres/condition-parser 1.7.0 → 1.7.2

package/AGENTS.md

@@ -0,0 +1,201 @@
+# Agent Context: @marianmeres/condition-parser
+
+## Package Overview
+
+- **Name**: `@marianmeres/condition-parser`
+- **Version**: 1.7.1
+- **Purpose**: Human-friendly search conditions notation parser (Gmail-style search syntax)
+- **License**: MIT
+- **Runtime**: Deno (primary), Node.js (via NPM distribution)
+
+## File Structure
+
+```
+src/
+├── mod.ts          # Public entry point (re-exports parser.ts)
+└── parser.ts       # Main parser implementation (705 lines)
+
+tests/
+└── all.test.ts     # Test suite (682 lines, 30 tests)
+
+scripts/
+└── build-npm.ts    # NPM distribution builder
+```
+
+## Public API
+
+### Main Export: `ConditionParser`
+
+Static class with two public methods:
+
+```typescript
+// Primary method - parses search expressions
+ConditionParser.parse(
+  input: string,
+  options?: Partial<ConditionParserOptions>
+): ConditionParserResult
+
+// Error helper (prefixed __ for internal use)
+ConditionParser.__createError(
+  input: string,
+  pos: number,
+  message: string,
+  contextRadius?: number
+): Error
+```
+
+### Static Properties
+
+```typescript
+ConditionParser.DEFAULT_OPERATOR: string = "eq"
+ConditionParser.DEBUG: boolean = false
+```
+
+### Exported Types
+
+```typescript
+interface ConditionParserOptions {
+  defaultOperator: string;      // default: "eq"
+  debug: boolean;               // default: false
+  transform?: (ctx: ExpressionContext) => ExpressionContext;
+  preAddHook?: (ctx: ExpressionContext) => null | undefined | ExpressionContext;
+}
+
+interface ConditionParserResult {
+  parsed: ConditionDump;        // from @marianmeres/condition-builder
+  unparsed: string;
+  meta: Meta;
+}
+
+interface Meta {
+  keys: string[];
+  operators: string[];
+  values: any[];
+  expressions: ExpressionData[];
+}
+
+interface ExpressionData {
+  key: string;
+  operator: string;
+  value: string;
+}
+```
+
+## Parser Grammar
+
+```
+condition      := term (conditionOp term)*
+term           := basicExpr | "(" condition ")"
+basicExpr      := identifier ":" identifier (":" identifier)?
+identifier     := quotedString | unquotedString | parenthesizedValue
+quotedString   := ("'" | '"') ... ("'" | '"')
+unquotedString := [^:\s()]+
+parenthesizedValue := "(" ... ")"
+conditionOp    := "and" | "or" | "and not" | "or not" | <implicit and>
+```
+
+## Expression Formats
+
+| Input | Parsed Key | Parsed Operator | Parsed Value |
+|-------|-----------|-----------------|--------------|
+| `key:value` | key | eq (default) | value |
+| `key:op:value` | key | op | value |
+| `"k k":"o o":"v v"` | k k | o o | v v |
+| `key:(complex value)` | key | eq | complex value |
+
+## Logical Operators
+
+| Syntax | ConditionJoinOperator |
+|--------|----------------------|
+| `and` | "and" |
+| `or` | "or" |
+| `and not` | "andNot" |
+| `or not` | "orNot" |
+| (implicit) | "and" |
+
+## Dependencies
+
+### Runtime
+
+- `@marianmeres/condition-builder` - Type definitions and integration target
+
+### Development
+
+- `@marianmeres/npmbuild` - NPM distribution builder
+- `@std/assert` - Deno test assertions
+- `@std/fs`, `@std/path` - File system utilities
+
+## Build Commands
+
+```bash
+deno task test          # Run tests
+deno task test:watch    # Run tests in watch mode
+deno task npm:build     # Build NPM distribution
+deno task publish       # Publish to JSR and NPM
+deno task release       # Patch version release
+deno task release minor # Minor version release
+```
+
+## Key Implementation Details
+
+1. **Recursive Descent Parser**: Layered parsing methods handle grammar levels
+2. **Fault Tolerance**: Parse errors don't throw; unparsable content preserved in `unparsed`
+3. **Escape Support**: Backslash escapes for `'`, `"`, `:`, `)` within strings
+4. **Case Insensitive**: Operators `and`, `or`, `not` are case-insensitive
+5. **Metadata Collection**: Unique keys, operators, values tracked in `meta`
+6. **Transform Pipeline**: Optional expression transformation before output
+7. **Pre-add Hook**: Optional filtering/routing of expressions
+
+## Integration Pattern
+
+```typescript
+import { ConditionParser } from "@marianmeres/condition-parser";
+import { Condition } from "@marianmeres/condition-builder";
+
+const { parsed, unparsed } = ConditionParser.parse(userInput);
+const condition = Condition.restore(parsed);
+```
+
+## Test Coverage
+
+30 tests covering:
+- Basic expression parsing
+- Quoted identifiers (single/double quotes)
+- Escaped characters
+- Logical operators (and, or, and not, or not)
+- Parenthesized grouping
+- Nested conditions
+- Free text handling
+- Transform function
+- Pre-add hook
+- Error handling
+- Metadata collection
+
+## Error Handling
+
+Parser is fault-tolerant:
+- Malformed input doesn't throw exceptions
+- Partially parsed content preserved in `parsed`
+- Unparsable remainder preserved in `unparsed`
+- Error positions tracked internally for debugging
+
+## Common Tasks
+
+### Adding new operators
+Operators are strings - no code changes needed. Use `defaultOperator` option or explicit `key:operator:value` syntax.
+
+### Custom transformations
+Use `transform` option to normalize keys/values:
+```typescript
+ConditionParser.parse(input, {
+  transform: (ctx) => ({ ...ctx, key: ctx.key.toLowerCase() })
+});
+```
+
+### Routing expressions
+Use `preAddHook` to filter or route expressions:
+```typescript
+ConditionParser.parse(input, {
+  preAddHook: (ctx) => ctx.key === "special" ? null : ctx
+});
+```

package/API.md

@@ -0,0 +1,355 @@
+# API Reference
+
+Complete API documentation for `@marianmeres/condition-parser`.
+
+## Table of Contents
+
+- [ConditionParser](#conditionparser)
+  - [Static Properties](#static-properties)
+  - [Static Methods](#static-methods)
+- [Types](#types)
+  - [ConditionParserOptions](#conditionparseroptions)
+  - [ConditionParserResult](#conditionparserresult)
+  - [Meta](#meta)
+  - [ExpressionData](#expressiondata)
+
+---
+
+## ConditionParser
+
+The main parser class. All methods are static.
+
+```ts
+import { ConditionParser } from "@marianmeres/condition-parser";
+```
+
+### Static Properties
+
+#### `DEFAULT_OPERATOR`
+
+```ts
+static DEFAULT_OPERATOR: string = "eq"
+```
+
+Default operator used when none is specified in the expression (e.g., `key:value` uses `"eq"`).
+
+#### `DEBUG`
+
+```ts
+static DEBUG: boolean = false
+```
+
+Global debug flag. When `true`, all parser instances log debug information to the console.
+
+---
+
+### Static Methods
+
+#### `parse()`
+
+```ts
+static parse(
+  input: string,
+  options?: Partial<ConditionParserOptions>
+): ConditionParserResult
+```
+
+Parses a human-friendly search condition string into a structured format.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `input` | `string` | The search expression string to parse |
+| `options` | `Partial<ConditionParserOptions>` | Optional configuration for parsing behavior |
+
+**Returns:** [`ConditionParserResult`](#conditionparserresult)
+
+**Example:**
+
+```ts
+// Basic parsing
+const { parsed, unparsed } = ConditionParser.parse("foo:bar and baz:bat");
+
+// With options
+const result = ConditionParser.parse("FOO:bar", {
+  defaultOperator: "contains",
+  transform: (ctx) => ({ ...ctx, key: ctx.key.toLowerCase() })
+});
+
+// Handling unparsed content
+const { parsed, unparsed } = ConditionParser.parse(
+  "category:books free text search"
+);
+// parsed: [{ expression: { key: "category", operator: "eq", value: "books" }, ... }]
+// unparsed: "free text search"
+```
+
+---
+
+#### `__createError()`
+
+```ts
+static __createError(
+  input: string,
+  pos: number,
+  message: string,
+  contextRadius?: number
+): Error
+```
+
+Public helper for creating formatted error messages with position and context information.
+
+> **Note:** Prefixed with `__` to indicate this is a special-purpose method not intended for general use. Exposed primarily for testing and advanced use cases.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `input` | `string` | - | The full input string being parsed |
+| `pos` | `number` | - | The position where the error occurred |
+| `message` | `string` | - | The error message |
+| `contextRadius` | `number` | `20` | Number of characters to show before/after error position |
+
+**Returns:** `Error` - Error object with formatted message including position and context
+
+**Example:**
+
+```ts
+const error = ConditionParser.__createError(
+  "foo:bar and baz:bat",
+  12,
+  "Unexpected character",
+  20
+);
+// Error message includes:
+// - The error message
+// - Position: 12
+// - Context snippet with visual marker (^)
+```
+
+---
+
+## Types
+
+### ConditionParserOptions
+
+Configuration options for the parser.
+
+```ts
+interface ConditionParserOptions {
+  defaultOperator: string;
+  debug: boolean;
+  transform: (context: ExpressionContext) => ExpressionContext;
+  preAddHook: (context: ExpressionContext) => null | undefined | ExpressionContext;
+}
+```
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `defaultOperator` | `string` | `"eq"` | Default operator when not explicitly specified |
+| `debug` | `boolean` | `false` | Enable debug logging to console |
+| `transform` | `function` | identity | Transform function applied to each parsed expression |
+| `preAddHook` | `function` | - | Hook called before adding each expression; return falsy to skip |
+
+**Transform Example:**
+
+```ts
+const result = ConditionParser.parse("FOO:BAR", {
+  transform: (ctx) => ({
+    ...ctx,
+    key: ctx.key.toLowerCase(),
+    value: ctx.value.toUpperCase()
+  })
+});
+// Result: key="foo", value="BAR"
+```
+
+**PreAddHook Example:**
+
+```ts
+const otherConditions = [];
+
+const result = ConditionParser.parse("foo:bar baz:bat", {
+  preAddHook: (ctx) => {
+    if (ctx.key === "foo") return ctx; // include in parsed
+    otherConditions.push(ctx); // route elsewhere
+    return null; // skip in parsed
+  }
+});
+```
+
+---
+
+### ConditionParserResult
+
+Result returned by `ConditionParser.parse()`.
+
+```ts
+interface ConditionParserResult {
+  parsed: ConditionDump;
+  unparsed: string;
+  meta: Meta;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `parsed` | `ConditionDump` | Array of parsed condition expressions (compatible with `@marianmeres/condition-builder`) |
+| `unparsed` | `string` | Any trailing text that couldn't be parsed (useful for free-text search) |
+| `meta` | [`Meta`](#meta) | Metadata about the parsed expressions |
+
+---
+
+### Meta
+
+Metadata about the parsed expressions.
+
+```ts
+interface Meta {
+  keys: string[];
+  operators: string[];
+  values: any[];
+  expressions: ExpressionData[];
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `keys` | `string[]` | Array of unique keys found in parsed expressions |
+| `operators` | `string[]` | Array of unique operators found in parsed expressions |
+| `values` | `any[]` | Array of unique values found in parsed expressions |
+| `expressions` | [`ExpressionData[]`](#expressiondata) | Array of unique expressions as objects |
+
+**Example:**
+
+```ts
+const { meta } = ConditionParser.parse("a:eq:1 or b:gt:2 a:eq:1");
+// meta = {
+//   keys: ["a", "b"],
+//   operators: ["eq", "gt"],
+//   values: ["1", "2"],
+//   expressions: [
+//     { key: "a", operator: "eq", value: "1" },
+//     { key: "b", operator: "gt", value: "2" }
+//   ]
+// }
+```
+
+---
+
+### ExpressionData
+
+Represents a parsed expression with key, operator, and value.
+
+```ts
+interface ExpressionData {
+  key: string;
+  operator: string;
+  value: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | The key/field name of the expression |
+| `operator` | `string` | The operator (e.g., `"eq"`, `"gt"`, `"contains"`) |
+| `value` | `string` | The value to compare against |
+
+---
+
+## Expression Syntax
+
+### Basic Expressions
+
+```
+key:value              -> { key: "key", operator: "eq", value: "value" }
+key:operator:value     -> { key: "key", operator: "operator", value: "value" }
+```
+
+### Quoted Identifiers
+
+Use single or double quotes for identifiers containing spaces or special characters:
+
+```
+"my key":"my value"
+'key with spaces':'value with spaces'
+"key":"operator":"value"
+```
+
+### Escaped Characters
+
+Escape special characters with backslash:
+
+```
+"value with \" quote"    -> value with " quote
+'value with \' quote'    -> value with ' quote
+key\:colon:value         -> key: "key:colon"
+```
+
+### Parenthesized Values
+
+Wrap values in parentheses (useful for complex values):
+
+```
+key:(value with spaces)
+key:eq:(complex value)
+key:eq:(value with \) paren)
+```
+
+### Logical Operators
+
+```
+a:b and c:d       -> AND join
+a:b or c:d        -> OR join
+a:b and not c:d   -> AND NOT join
+a:b or not c:d    -> OR NOT join
+a:b c:d           -> implicit AND (same as "a:b and c:d")
+```
+
+### Grouping
+
+Use parentheses for logical grouping:
+
+```
+(a:b or c:d) and e:f
+a:b and (c:d or (e:f and g:h))
+```
+
+### Free Text
+
+Any trailing unparsable content is preserved:
+
+```
+category:books the search query
+// parsed: category:books
+// unparsed: "the search query"
+```
+
+---
+
+## Integration with condition-builder
+
+The parser output is designed to work seamlessly with `@marianmeres/condition-builder`:
+
+```ts
+import { ConditionParser } from "@marianmeres/condition-parser";
+import { Condition } from "@marianmeres/condition-builder";
+
+const userSearchInput = '(folder:"my projects" or folder:inbox) foo bar';
+
+const options = {
+  renderKey: (ctx) => `"${ctx.key.replaceAll('"', '""')}"`,
+  renderValue: (ctx) => `'${ctx.value.toString().replaceAll("'", "''")}'`,
+};
+
+const { parsed, unparsed } = ConditionParser.parse(userSearchInput);
+
+const c = new Condition(options);
+c.and("user_id", "eq", 123).and(
+  Condition.restore(parsed, options).and("text", "match", unparsed)
+);
+
+console.log(c.toString());
+// "user_id"='123' and (("folder"='my projects' or "folder"='inbox') and "text"~*'foo bar')
+```

package/README.md

@@ -1,5 +1,9 @@
 # @marianmeres/condition-parser
 
+[![NPM version](https://img.shields.io/npm/v/@marianmeres/condition-parser.svg)](https://www.npmjs.com/package/@marianmeres/condition-parser)
+[![JSR version](https://jsr.io/badges/@marianmeres/condition-parser)](https://jsr.io/@marianmeres/condition-parser)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Human friendly search conditions notation parser. Somewhat similar to Gmail "Search email" input.
 
 The parsed output is designed to match [condition-builder](https://github.com/marianmeres/condition-builder) 
@@ -87,21 +91,15 @@ const result = ConditionParser.parse(
     unparsed: "this is free text"
 }
 
-// supported ConditionParser.parse options:
-export interface ConditionParserOptions {
-    /** Operator is optional. If not present will default to this option, which is by default "eq" */
-    defaultOperator: string;
-    /** Will print debug info to console. Defaults to false */
-    debug: boolean;
-    /** If provided, will use the output of this fn as a final parsed expression output. */
-    transform: (context: Context) => Context;
-    /** Applied as the last step before adding the currently parsed expression. 
-     * If returns falsey, will skip adding the currently parsed expression. */
-    preAddHook: (context: Context) => null | undefined | Context;
-}
-
+// ConditionParser.parse options (all optional):
+// - defaultOperator: string (default "eq") - operator when not specified
+// - debug: boolean (default false) - enable debug logging
+// - transform: (ctx) => ctx - transform each parsed expression
+// - preAddHook: (ctx) => ctx|null - filter/route expressions before adding
 ```
 
+See [API.md](./API.md) for complete API documentation.
+
 ## In friends harmony with condition-builder
 
 See [condition-builder](https://github.com/marianmeres/condition-builder) for more.
@@ -133,4 +131,11 @@ assertEquals(
 
 ## Related
 
-[@marianmeres/condition-builder](https://github.com/marianmeres/condition-builder)
+[@marianmeres/condition-builder](https://github.com/marianmeres/condition-builder)
+
+## Package Identity
+
+- **Name:** @marianmeres/condition-parser
+- **Author:** Marian Meres
+- **Repository:** https://github.com/marianmeres/condition-parser
+- **License:** MIT

package/dist/mod.d.ts

@@ -1 +1,32 @@
+/**
+ * @module
+ *
+ * Human-friendly search conditions notation parser.
+ *
+ * Parses expressions like `"key:value"` or `"key:operator:value"` and supports
+ * logical operators (`and`, `or`, `and not`, `or not`), parenthesized grouping,
+ * quoted strings with escaping, and graceful handling of unparsable content.
+ *
+ * Designed to work seamlessly with
+ * {@link https://github.com/marianmeres/condition-builder | @marianmeres/condition-builder}.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { ConditionParser } from "@marianmeres/condition-parser";
+ *
+ * const result = ConditionParser.parse("foo:bar and baz:bat");
+ * // result.parsed contains the parsed conditions
+ * // result.unparsed contains any trailing unparsable text
+ * // result.meta contains metadata about parsed expressions
+ * ```
+ *
+ * @example With free text
+ * ```ts
+ * const { parsed, unparsed } = ConditionParser.parse(
+ *   "category:books free text search"
+ * );
+ * // parsed: structured conditions
+ * // unparsed: "free text search"
+ * ```
+ */
 export * from "./parser.js";

package/dist/mod.js

@@ -1 +1,32 @@
+/**
+ * @module
+ *
+ * Human-friendly search conditions notation parser.
+ *
+ * Parses expressions like `"key:value"` or `"key:operator:value"` and supports
+ * logical operators (`and`, `or`, `and not`, `or not`), parenthesized grouping,
+ * quoted strings with escaping, and graceful handling of unparsable content.
+ *
+ * Designed to work seamlessly with
+ * {@link https://github.com/marianmeres/condition-builder | @marianmeres/condition-builder}.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { ConditionParser } from "@marianmeres/condition-parser";
+ *
+ * const result = ConditionParser.parse("foo:bar and baz:bat");
+ * // result.parsed contains the parsed conditions
+ * // result.unparsed contains any trailing unparsable text
+ * // result.meta contains metadata about parsed expressions
+ * ```
+ *
+ * @example With free text
+ * ```ts
+ * const { parsed, unparsed } = ConditionParser.parse(
+ *   "category:books free text search"
+ * );
+ * // parsed: structured conditions
+ * // unparsed: "free text search"
+ * ```
+ */
 export * from "./parser.js";

package/dist/parser.d.ts

@@ -1,15 +1,49 @@
 import type { ConditionDump, ExpressionContext } from "@marianmeres/condition-builder";
-interface ExpressionData {
+/**
+ * Represents a parsed expression with key, operator, and value.
+ * This is used in the metadata returned by the parser.
+ */
+export interface ExpressionData {
+    /** The key/field name of the expression */
     key: string;
+    /** The operator (e.g., "eq", "gt", "contains") */
     operator: string;
+    /** The value to compare against */
     value: string;
 }
-interface Meta {
+/**
+ * Metadata about the parsed expressions.
+ * Contains arrays of unique keys, operators, values, and full expressions.
+ */
+export interface Meta {
+    /** Array of unique keys found in the parsed expressions */
     keys: string[];
+    /** Array of unique operators found in the parsed expressions */
     operators: string[];
+    /** Array of unique values found in the parsed expressions */
     values: any[];
+    /** Array of unique expressions as {key, operator, value} objects */
     expressions: ExpressionData[];
 }
+/**
+ * Result returned by {@link ConditionParser.parse}.
+ */
+export interface ConditionParserResult {
+    /**
+     * Array of parsed condition expressions in ConditionDump format.
+     * Compatible with {@link https://github.com/marianmeres/condition-builder | @marianmeres/condition-builder}.
+     */
+    parsed: ConditionDump;
+    /**
+     * Any trailing text that couldn't be parsed.
+     * Useful for free-text search terms.
+     */
+    unparsed: string;
+    /**
+     * Metadata about the parsed expressions (unique keys, operators, values).
+     */
+    meta: Meta;
+}
 /**
  * Configuration options for the ConditionParser.
  */
@@ -164,10 +198,5 @@ export declare class ConditionParser {
      * // unparsed: "free text search"
      * ```
      */
-    static parse(input: string, options?: Partial<ConditionParserOptions>): {
-        parsed: ConditionDump;
-        unparsed: string;
-        meta: Meta;
-    };
+    static parse(input: string, options?: Partial<ConditionParserOptions>): ConditionParserResult;
 }
-export {};

package/package.json

@@ -1,19 +1,25 @@
 {
 	"name": "@marianmeres/condition-parser",
-	"version": "1.7.0",
+	"version": "1.7.2",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
 	"author": "Marian Meres",
 	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/condition-builder": "^1.9.3"
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/marianmeres/condition-parser.git"
 	},
 	"bugs": {
 		"url": "https://github.com/marianmeres/condition-parser/issues"
-	},
-	"dependencies": {
-		"@marianmeres/condition-builder": "^1.9.0"
 	}
 }