@jarenjs/json 0.9.2

package/schemas/jaren-query.schema.json

@@ -0,0 +1,375 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-query/0.1",
+  "title": "Jaren JSON Query format 0.1",
+  "description": "Structural grammar of Jaren JSON Query documents (see packages/json/docs/QUERY-FORMAT.md). This schema is structural validation only: the compiler remains authoritative for semantic rules it cannot express - FLWOR clause keys apply in the fixed semantic order $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order; variable scoping, duplicate-binding detection, external-parameter collection and $as name binding are compiler rules (JQ0005/JQ0007); variable-rooted path strings are only head-checked here (full RFC 9535 segment grammar is JQ0004); embedded JSON Schema literals are taken verbatim and never meta-validated here (the type-test compiler is authoritative, JQ0008/JQ0009); per-argument runtime typing is JQ2xxx. Authored in a draft-neutral keyword subset; the draft-07 twin is a mechanical derivation.",
+  "allOf": [
+    { "$ref": "#/$defs/queryDocument" }
+  ],
+  "$defs": {
+    "queryDocument": {
+      "description": "A query document is either the version envelope or a bare expression (a bare RFC 9535 JSONPath string is the degenerate query).",
+      "oneOf": [
+        { "$ref": "#/$defs/versionEnvelope" },
+        { "$ref": "#/$defs/expression" }
+      ]
+    },
+    "versionEnvelope": {
+      "description": "Top-level version envelope. Only recognized at the top level of a query document.",
+      "type": "object",
+      "properties": {
+        "$query": { "const": "0.1" },
+        "$expr": { "$ref": "#/$defs/expression" }
+      },
+      "required": ["$query", "$expr"],
+      "additionalProperties": false
+    },
+    "expression": {
+      "description": "Any expression per the encoding rules: scalars are literals, strings split on the leading '$', arrays are array constructors, objects partition into map constructors (no $-prefixed key) and operator phrases (all keys $-prefixed).",
+      "oneOf": [
+        { "$ref": "#/$defs/scalarLiteral" },
+        { "$ref": "#/$defs/stringExpression" },
+        { "$ref": "#/$defs/arrayConstructor" },
+        { "$ref": "#/$defs/objectExpression" }
+      ]
+    },
+    "scalarLiteral": {
+      "description": "Numbers, booleans and null are literal items.",
+      "type": ["null", "boolean", "number"]
+    },
+    "stringExpression": {
+      "description": "Rule 2: a string starting with '$' is a query expression ('$$' escapes a literal); any other string is a literal.",
+      "type": "string",
+      "anyOf": [
+        { "$ref": "#/$defs/literalString" },
+        { "$ref": "#/$defs/escapedStringLiteral" },
+        { "$ref": "#/$defs/absolutePathString" },
+        { "$ref": "#/$defs/variablePathString" }
+      ]
+    },
+    "literalString": {
+      "description": "A string that does not start with '$' denotes itself.",
+      "type": "string",
+      "pattern": "^([^$]|$)"
+    },
+    "escapedStringLiteral": {
+      "description": "A string starting with '$$' denotes the literal string with one leading '$' dropped.",
+      "type": "string",
+      "pattern": "^\\$\\$"
+    },
+    "absolutePathString": {
+      "description": "An absolute RFC 9535 JSONPath query rooted at the input document: '$' alone or starting '$.', '$[' or '$..'. The json-path format asserts the full RFC 9535 grammar where format assertion is enabled (format is annotation-only by default from draft 2020-12).",
+      "type": "string",
+      "pattern": "^\\$($|[.\\[])",
+      "format": "json-path"
+    },
+    "variablePathString": {
+      "description": "A variable-rooted path: '$name' with name matching [A-Za-z_][A-Za-z0-9_]*, optionally followed by RFC 9535 segments. Only the head is pattern-checked; the full segment grammar is enforced by the compiler (JQ0004).",
+      "type": "string",
+      "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*($|[.\\[])"
+    },
+    "arrayConstructor": {
+      "description": "An array in expression position constructs an array; element results are concatenated per XQuery sequence flattening.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/expression" }
+    },
+    "objectExpression": {
+      "description": "Rule 1: objects partition by $-prefixed keys. A mixed object matches neither branch and is invalid (JQ0001).",
+      "oneOf": [
+        { "$ref": "#/$defs/mapConstructor" },
+        { "$ref": "#/$defs/constPhrase" },
+        { "$ref": "#/$defs/mapPhrase" },
+        { "$ref": "#/$defs/flworPhrase" },
+        { "$ref": "#/$defs/somePhrase" },
+        { "$ref": "#/$defs/everyPhrase" },
+        { "$ref": "#/$defs/unaryOperatorPhrase" },
+        { "$ref": "#/$defs/binaryOperatorPhrase" },
+        { "$ref": "#/$defs/variadicOperatorPhrase" },
+        { "$ref": "#/$defs/nonEmptyVariadicOperatorPhrase" },
+        { "$ref": "#/$defs/conditionalArityOperatorPhrase" },
+        { "$ref": "#/$defs/stringJoinPhrase" },
+        { "$ref": "#/$defs/replacePhrase" },
+        { "$ref": "#/$defs/schemaOperatorPhrase" }
+      ]
+    },
+    "mapConstructor": {
+      "description": "An object with no $-prefixed key: keys are literal member names, values are expressions. Use $map or $const for member names that start with '$'.",
+      "type": "object",
+      "patternProperties": {
+        "^\\$": false
+      },
+      "additionalProperties": { "$ref": "#/$defs/expression" }
+    },
+    "constPhrase": {
+      "description": "Quote: the value is returned verbatim, nothing inside is evaluated.",
+      "type": "object",
+      "properties": {
+        "$const": true
+      },
+      "required": ["$const"],
+      "additionalProperties": false
+    },
+    "mapPhrase": {
+      "description": "General map constructor for computed keys or keys starting with '$'. Each entry is a [keyExpr, valueExpr] pair; keyExpr must evaluate to a single string at runtime (JQ2004); later pairs win on duplicate keys.",
+      "type": "object",
+      "properties": {
+        "$map": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/mapEntry" }
+        }
+      },
+      "required": ["$map"],
+      "additionalProperties": false
+    },
+    "mapEntry": {
+      "description": "One [keyExpr, valueExpr] pair of a $map phrase.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/expression" },
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "flworPhrase": {
+      "description": "FLWOR phrase. Clauses apply in the fixed semantic order $for, $let, $as, $where, $groupby, $orderby, $count, $return regardless of JSON key order (D7); interleavings are expressed by nesting phrases. $return is required, plus at least one of $for/$let.",
+      "type": "object",
+      "properties": {
+        "$for": { "$ref": "#/$defs/forBindings" },
+        "$let": { "$ref": "#/$defs/bindingMap" },
+        "$as": { "$ref": "#/$defs/asClause" },
+        "$where": { "$ref": "#/$defs/expression" },
+        "$groupby": { "$ref": "#/$defs/bindingMap" },
+        "$orderby": { "$ref": "#/$defs/orderBySpec" },
+        "$count": { "$ref": "#/$defs/variableName" },
+        "$return": { "$ref": "#/$defs/expression" }
+      },
+      "required": ["$return"],
+      "anyOf": [
+        { "required": ["$for"] },
+        { "required": ["$let"] }
+      ],
+      "additionalProperties": false
+    },
+    "variableName": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "forBindings": {
+      "description": "Iteration bindings: variable name to source expression or extended {$in, $at} binding. Bindings nest left-to-right in document key order and may be correlated; key-order-hostile producers should nest phrases instead.",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/forSource" }
+    },
+    "forSource": {
+      "oneOf": [
+        { "$ref": "#/$defs/expression" },
+        { "$ref": "#/$defs/extendedForBinding" }
+      ]
+    },
+    "extendedForBinding": {
+      "description": "Extended $for binding: iterates $in and binds $at to the 0-based (D6) position variable.",
+      "type": "object",
+      "properties": {
+        "$in": { "$ref": "#/$defs/expression" },
+        "$at": { "$ref": "#/$defs/variableName" }
+      },
+      "required": ["$in", "$at"],
+      "additionalProperties": false
+    },
+    "bindingMap": {
+      "description": "Variable name to expression map, used by $let, $groupby and quantifier bindings.",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/expression" }
+    },
+    "orderBySpec": {
+      "description": "A single key spec or a major-to-minor list of key specs. An array value is by specification ALWAYS a list of key specs, so the single form excludes arrays; write a single array-constructor key as {\"$key\": [...]}.",
+      "oneOf": [
+        { "$ref": "#/$defs/singleOrderByKey" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/orderByKey" },
+          "minItems": 1
+        }
+      ]
+    },
+    "singleOrderByKey": {
+      "description": "A key spec in non-list position: any non-array expression, or the explicit {$key, $dir, $empty} form.",
+      "oneOf": [
+        { "$ref": "#/$defs/scalarLiteral" },
+        { "$ref": "#/$defs/stringExpression" },
+        { "$ref": "#/$defs/objectExpression" },
+        { "$ref": "#/$defs/orderByKeySpec" }
+      ]
+    },
+    "orderByKey": {
+      "oneOf": [
+        { "$ref": "#/$defs/expression" },
+        { "$ref": "#/$defs/orderByKeySpec" }
+      ]
+    },
+    "orderByKeySpec": {
+      "description": "Explicit order key: direction defaults to 'asc', empty-sequence placement to 'least'.",
+      "type": "object",
+      "properties": {
+        "$key": { "$ref": "#/$defs/expression" },
+        "$dir": { "enum": ["asc", "desc"] },
+        "$empty": { "enum": ["least", "greatest"] }
+      },
+      "required": ["$key"],
+      "additionalProperties": false
+    },
+    "somePhrase": {
+      "description": "Existential quantifier: true iff some binding tuple satisfies the EBV of $satisfies; short-circuits.",
+      "type": "object",
+      "properties": {
+        "$some": { "$ref": "#/$defs/bindingMap" },
+        "$satisfies": { "$ref": "#/$defs/expression" }
+      },
+      "required": ["$some", "$satisfies"],
+      "additionalProperties": false
+    },
+    "everyPhrase": {
+      "description": "Universal quantifier: true iff every binding tuple satisfies the EBV of $satisfies; short-circuits.",
+      "type": "object",
+      "properties": {
+        "$every": { "$ref": "#/$defs/bindingMap" },
+        "$satisfies": { "$ref": "#/$defs/expression" }
+      },
+      "required": ["$every", "$satisfies"],
+      "additionalProperties": false
+    },
+    "unaryOperatorPhrase": {
+      "description": "Operators whose value is a single operand expression.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": [
+          "$exists", "$empty", "$not", "$neg",
+          "$count", "$sum", "$avg", "$min", "$max",
+          "$distinct", "$reverse", "$sort", "$head", "$tail",
+          "$upper", "$lower", "$string-length", "$normalize-space",
+          "$string", "$number", "$boolean",
+          "$is-string", "$is-number", "$is-boolean", "$is-null", "$is-array", "$is-object"
+        ]
+      },
+      "additionalProperties": { "$ref": "#/$defs/expression" }
+    },
+    "binaryOperatorPhrase": {
+      "description": "Operators whose value is an array of exactly two operand expressions.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": [
+          "$eq", "$ne", "$lt", "$le", "$gt", "$ge",
+          "$add", "$sub", "$mul", "$div", "$idiv", "$mod",
+          "$contains", "$starts-with", "$ends-with", "$match", "$search",
+          "$index-of", "$range", "$get", "$default"
+        ]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/expression" },
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "variadicOperatorPhrase": {
+      "description": "Variadic operators accepting zero or more operand expressions.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": ["$seq", "$concat"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/expression" }
+      }
+    },
+    "nonEmptyVariadicOperatorPhrase": {
+      "description": "Variadic operators requiring at least one operand expression.",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": ["$and", "$or", "$coalesce"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/expression" },
+        "minItems": 1
+      }
+    },
+    "conditionalArityOperatorPhrase": {
+      "description": "Operators taking two or three operand expressions: $if [cond, then, else?], $substring [str, start, len?], $subsequence [seq, start, len?].",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": ["$if", "$substring", "$subsequence"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/expression" },
+        "minItems": 2,
+        "maxItems": 3
+      }
+    },
+    "stringJoinPhrase": {
+      "description": "$string-join [seq, separator?]: one or two operand expressions.",
+      "type": "object",
+      "properties": {
+        "$string-join": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/expression" },
+          "minItems": 1,
+          "maxItems": 2
+        }
+      },
+      "required": ["$string-join"],
+      "additionalProperties": false
+    },
+    "replacePhrase": {
+      "description": "$replace [input, pattern, replacement]: exactly three operand expressions (I-Regexp has no flags argument, D5).",
+      "type": "object",
+      "properties": {
+        "$replace": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/expression" },
+          "minItems": 3,
+          "maxItems": 3
+        }
+      },
+      "required": ["$replace"],
+      "additionalProperties": false
+    },
+    "schemaLiteral": {
+      "description": "A JSON Schema literal, taken verbatim - never interpreted as a query expression, so JSON Schema's $-prefixed keywords ($ref, $defs, ...) do not collide with Rule 1. Deliberately unconstrained (a true schema is draft-neutral by definition): embedded schemas are not meta-validated by this artifact; the consumer's type-test compiler is authoritative (JQ0009)."
+    },
+    "schemaOperatorPhrase": {
+      "description": "Schema operators $valid/$assert: [expr, schema] - exactly two elements, an operand expression and a verbatim JSON Schema literal. Tuple validation is outside the draft-neutral subset, so both positions validate uniformly as schema literals here; the operand position is normalized as an ordinary expression by the compiler (JQ0xxx).",
+      "type": "object",
+      "minProperties": 1,
+      "maxProperties": 1,
+      "propertyNames": {
+        "enum": ["$valid", "$assert"]
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": { "$ref": "#/$defs/schemaLiteral" },
+        "minItems": 2,
+        "maxItems": 2
+      }
+    },
+    "asClause": {
+      "description": "The $as clause: variable-name to JSON Schema literal members, applied per tuple after $for/$let binding and before $where. Each name must be bound by the same phrase's $for (including $at names) or $let - a compiler rule (JQ0005); each binding validates per item at runtime (JQ2008).",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "$ref": "#/$defs/schemaLiteral" }
+    }
+  }
+}

package/src/basic.js

@@ -0,0 +1,300 @@
+import {
+  CC_SLASH,
+  CC_HASH,
+  CC_PERCENT,
+  CC_TILDE,
+  CC_0,
+  CC_1,
+  isDigitCode,
+  isHexDigitCode,
+} from '@jarenjs/core/scan';
+
+//#region JSON validation
+// JSON whitespace characters: space, tab, newline, carriage return
+const JSON_WHITESPACE = new Set([0x20, 0x09, 0x0A, 0x0D]);
+
+export function isValidJSONCheap(data) {
+  const len = data.length;
+  // Too short to be valid JSON (minimum is 2 for {} or [])
+  if (len < 2) return true; // Definitely NOT valid JSON
+
+  // Check first char
+  const first = data.charCodeAt(0);
+
+  // Objects and arrays - check matching brackets
+  if (first === 0x7B || first === 0x5B) { // '{' or '['
+    // Find last non-whitespace character (JSON allows trailing whitespace)
+    let lastIdx = len - 1;
+    while (lastIdx >= 0) {
+      const code = data.charCodeAt(lastIdx);
+      if (!JSON_WHITESPACE.has(code)) break;
+      lastIdx--;
+    }
+
+    // Must end with matching bracket
+    const last = data.charCodeAt(lastIdx);
+    if (first === 0x7B && last !== 0x7D) return true; // {} must match - definitely NOT valid
+    if (first === 0x5B && last !== 0x5D) return true; // [] must match - definitely NOT valid
+
+    // Looks like JSON object/array, might be valid
+    return false;
+  }
+
+  // Check if first char is a valid JSON starting character:
+  // '"' (0x22) for strings, '-' (0x2D) or digit (0x30-0x39) for numbers,
+  // 't' (0x74) for true, 'f' (0x66) for false, 'n' (0x6E) for null
+  const isValidStart = (
+    first === 0x22 || // '"'
+    first === 0x2D || // '-'
+    (first >= 0x30 && first <= 0x39) || // '0'-'9'
+    first === 0x74 || // 't' (true)
+    first === 0x66 || // 'f' (false)
+    first === 0x6E    // 'n' (null)
+  );
+
+  // If it starts with a valid JSON character, it might be valid JSON
+  // Return false to indicate "might be JSON, need to parse"
+  if (isValidStart) return false;
+
+  // Doesn't start with valid JSON character - definitely NOT valid JSON
+  return true;
+}
+
+export function isValidJSON(data) {
+  if (isValidJSONCheap(data)) return false;
+
+  try {
+    JSON.parse(data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+//#endregion
+
+//#region JPtr Tests
+// Single-pass char-code scanners (no regex, no allocation), shared by the
+// `json-pointer`/`relative-json-pointer` string formats.
+
+// scan the pointer body `str[pos..)`: '/'-delimited segments where every
+// '~' must be followed by '0' or '1' (RFC 6901 section 3)
+function isValidPointerBody(str, pos) {
+  const len = str.length;
+  for (; pos < len; pos++) {
+    if (str.charCodeAt(pos) === CC_TILDE) {
+      const d = pos + 1 < len ? str.charCodeAt(pos + 1) : -1;
+      if (d !== CC_0 && d !== CC_1)
+        return false;
+      pos++;
+    }
+  }
+  return true;
+}
+
+// JSON-pointer: https://tools.ietf.org/html/rfc6901
+export function isValidJSONPointer(str) {
+  if (typeof str !== 'string')
+    return false;
+  if (str.length === 0)
+    return true;
+  if (str.charCodeAt(0) !== CC_SLASH)
+    return false;
+  return isValidPointerBody(str, 1);
+}
+
+// unreserved / sub-delims / ':' / '@' per RFC 3986 pchar, minus the
+// pointer-significant '~' and '/' handled by the caller
+function isFragmentPointerCode(c) {
+  return (c >= 0x61 && c <= 0x7A) // a-z
+    || (c >= 0x41 && c <= 0x5A) // A-Z
+    || isDigitCode(c)
+    || (c >= 0x26 && c <= 0x2E) // & ' ( ) * + , - .
+    || c === 0x21 // !
+    || c === 0x24 // $
+    || c === 0x3A // :
+    || c === 0x3B // ;
+    || c === 0x3D // =
+    || c === 0x40 // @
+    || c === 0x5F; // _
+}
+
+// uri fragment: https://tools.ietf.org/html/rfc3986#appendix-A
+export function isValidJSONPointerUriFragment(str) {
+  if (typeof str !== 'string')
+    return false;
+  const len = str.length;
+  if (len === 0 || str.charCodeAt(0) !== CC_HASH)
+    return false;
+  if (len > 1 && str.charCodeAt(1) !== CC_SLASH)
+    return false;
+  for (let pos = 1; pos < len; pos++) {
+    const c = str.charCodeAt(pos);
+    if (c === CC_SLASH || isFragmentPointerCode(c))
+      continue;
+    if (c === CC_PERCENT) { // percent-encoded octet
+      if (pos + 2 >= len
+        || !isHexDigitCode(str.charCodeAt(pos + 1))
+        || !isHexDigitCode(str.charCodeAt(pos + 2)))
+        return false;
+      pos += 2;
+      continue;
+    }
+    if (c === CC_TILDE) {
+      const d = pos + 1 < len ? str.charCodeAt(pos + 1) : -1;
+      if (d !== CC_0 && d !== CC_1)
+        return false;
+      pos++;
+      continue;
+    }
+    return false;
+  }
+  return true;
+}
+
+// relative JSON-pointer: http://tools.ietf.org/html/draft-luff-relative-json-pointer-00
+export function isValidRelativeJSONPointer(str) {
+  if (typeof str !== 'string')
+    return false;
+  const len = str.length;
+  if (len === 0)
+    return false;
+  const first = str.charCodeAt(0);
+  if (!isDigitCode(first))
+    return false;
+  let pos = 1;
+  if (first !== CC_0) {
+    while (pos < len && isDigitCode(str.charCodeAt(pos)))
+      pos++;
+  }
+  if (pos === len)
+    return true;
+  const c = str.charCodeAt(pos);
+  if (c === CC_HASH)
+    return pos + 1 === len;
+  if (c !== CC_SLASH)
+    return false;
+  return isValidPointerBody(str, pos + 1);
+}
+//#endregion
+
+//#region JSONPath Tests (RFC 9535)
+// JSONPath syntax: https://www.rfc-editor.org/rfc/rfc9535.html
+
+// Basic JSONPath structure:
+// $                         - root
+// $.store.book[0].title     - dot notation with array index
+// $['store']['book'][0]     - bracket notation
+// $..name                   - recursive descent
+// $.*                       - wildcard
+// $[?(@.price < 10)]        - filter expression
+// $[0:5:2]                  - slice
+// $[0,1,2]                  - multiple indices
+
+// Simplified regex that covers common JSONPath patterns
+// This validates the structure without fully parsing filter expressions
+// Pattern breakdown:
+//   (\$|@) - starts with $ or @
+//   (?:\.\.[a-zA-Z_][a-zA-Z0-9_]*| - recursive descent with name (e.g., $..name)
+//   \.\.| - recursive descent (e.g., $..)
+//   \.[a-zA-Z_][a-zA-Z0-9_]*| - dot notation (e.g., $.store)
+//   \.[*]| - dot wildcard (e.g., $.*)
+//   \[\s*(?:'[^']*'|"[^"]*"|\d+|\*|\?[^\]]*|\d*:\d*(?::\d*)?)\s*\] - bracket notation
+const CONST_REGEXP_JSONPATH = /^(\$|@)(?:\.\.[a-zA-Z_][a-zA-Z0-9_]*|\.\.|\.[a-zA-Z_][a-zA-Z0-9_]*|\.[*]|\[\s*(?:'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|\d+|\*|\?[^\]]*|\d*:\d*(?::\d*)?|\d+(?:\s*,\s*\d+)*|'(?:[^'\\]|\\.)*'(?:\s*,\s*'(?:[^'\\]|\\.)*')*|\"(?:[^"\\]|\\.)*\"(?:\s*,\s*\"(?:[^"\\]|\\.)*\")*)\s*\])*$/;
+
+/**
+ * Validates a JSONPath expression string per RFC 9535.
+ *
+ * JSONPath syntax includes:
+ * - $ - root node selector
+ * - @ - current node selector (used in filter expressions)
+ * - .name - dot notation for child member
+ * - ['name'] or ["name"] - bracket notation for child member
+ * - [index] - array index
+ * - [*] - wildcard selector
+ * - [start:end:step] - array slice
+ * - [?expression] - filter expression
+ * - .. - recursive descent
+ *
+ * @param {string} str - The JSONPath expression to validate
+ * @returns {boolean} - True if the string is a valid JSONPath expression
+ * @example
+ * isValidJSONPath('$.store.book[0].title'); // true
+ * isValidJSONPath('$..name'); // true
+ * isValidJSONPath('$[*]'); // true
+ * isValidJSONPath('$[?(@.price < 10)]'); // true
+ * isValidJSONPath('$.store.book[0:5]'); // true
+ * isValidJSONPath('@.name'); // true (current node selector)
+ * isValidJSONPath('store'); // false (must start with $ or @)
+ * isValidJSONPath(''); // false (empty string)
+ */
+export function isValidJSONPath(str) {
+  if (typeof str !== 'string')
+    return false;
+
+  // Must start with $ (root) or @ (current node in filters)
+  if (!str || (str[0] !== '$' && str[0] !== '@'))
+    return false;
+
+  // Single $ or @ is valid
+  if (str.length === 1)
+    return true;
+
+  // Use the regex for basic validation
+  if (!CONST_REGEXP_JSONPATH.test(str))
+    return false;
+
+  // Additional validation for bracket contents
+  return validateJSONPathBrackets(str);
+}
+
+/**
+ * Validates that brackets in JSONPath are balanced and well-formed
+ * @param {string} str - The JSONPath string to validate
+ * @returns {boolean} - True if brackets are valid
+ * @private
+ */
+function validateJSONPathBrackets(str) {
+  let depth = 0;
+  let inString = false;
+  let stringChar = null;
+  let escapeNext = false;
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str[i];
+
+    if (escapeNext) {
+      escapeNext = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escapeNext = true;
+      continue;
+    }
+
+    if (inString) {
+      if (char === stringChar) {
+        inString = false;
+        stringChar = null;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      inString = char;
+      stringChar = char;
+      continue;
+    }
+
+    if (char === '[') {
+      depth++;
+    } else if (char === ']') {
+      depth--;
+      if (depth < 0)
+        return false; // Unbalanced brackets
+    }
+  }
+
+  return depth === 0 && !inString;
+}
+//#endregion

package/src/index.js

@@ -0,0 +1,4 @@
+export * from './basic.js';
+export * from './pointer.js';
+export * from './path.js';
+export * from './query/index.js';