@es-joy/jsoe 0.28.1 → 0.29.0

package/src/search/queryTree.js

@@ -0,0 +1,235 @@
+/**
+ * JSDoc-only typedefs for the schema-driven search query tree. No runtime
+ * exports live here; construct nodes through `queryTreeBuilders.js` instead
+ * so every search module (and every test fixture) goes through one place.
+ *
+ * Leaf `path` values reuse the existing JSON-Pointer convention from
+ * `src/utils/jsonPointer.js` (`makeJSONPointer`/`getJSONPointerParts`)
+ * rather than Mongo's dot-notation, so the search tree shares a path format
+ * with the rest of jsoe (e.g. `arrayType.js`'s `currentPath`).
+ *
+ * The leaf vocabulary borrows MongoDB's own operator names (`$and`/`$or`,
+ * `$gt`/`$gte`/`$lt`/`$lte`, `$in`/`$nin`, `$regex`/`$options`, `$exists`)
+ * wherever a leaf kind has a clean Mongo equivalent, so a host can adapt the
+ * common cases to `sift()` (or real MongoDB) almost for free - this is not a
+ * claim of full drop-in Mongo query-document compatibility: several
+ * jsoe-specific leaf kinds have no Mongo equivalent and stay custom, and
+ * every leaf keeps jsoe's own `kind`-discriminated, path-carrying shape
+ * rather than Mongo's field-keyed document shape.
+ *
+ * A path segment of `*` (e.g. `#/tags/*`) means "any element of the array
+ * at this point" - `arraySearchType.js`/`setSearchType.js`/`filelistSearchType.js`
+ * (element/value length/count constraint aside) and `tupleSearchType.js`'s
+ * `rest` portion use it when recursing into their element/value schema's
+ * own search widget, so a single nested leaf expresses "the collection
+ * contains at least one element matching this" (Mongo's `$elemMatch` is the
+ * natural translation target for a host walking a path that contains this
+ * segment) without needing a dedicated wrapper leaf kind - the collection's
+ * own `lengthSize` leaf and the recursed element leaf simply combine via
+ * `$and`. `recordSearchType.js`/`mapSearchType.js` similarly recurse into
+ * their `key`/`value` schemas at `*key`/`*value` segments, feeding the
+ * results into a single `mapRecordJoint` leaf (below) rather than combining
+ * via `$and`, since a host needs to know whether the two must match the
+ * same entry. `functionSearchType.js` recurses into its `input`/`output`
+ * schemas at `*args`/`*output` segments (the former itself a tuple, so its
+ * own per-position segments nest under `*args`), combined via `$and`.
+ * `promiseSearchType.js`/`catchSearchType.js` recurse into their wrapped
+ * value/`innerType` at the same path (there being exactly one value, no
+ * segment to add) and wrap the result in a `passThrough` leaf (below)
+ * rather than returning it bare, so the tree keeps visible that the leaf
+ * was reached through one of these transparent wrappers.
+ */
+
+/**
+ * @typedef {{$and: QueryNode[]}} QueryAnd
+ */
+
+/**
+ * @typedef {{$or: QueryNode[]}} QueryOr
+ */
+
+/**
+ * `object` (via `$exists: true/false`).
+ * @typedef {{kind: 'hasProperty', path: string, $exists: boolean}} QueryHasPropertyLeaf
+ */
+
+/**
+ * `array`/`set`/tuple-with-rest/`filelist` (via `$size`, or a range of
+ * operators when the schema doesn't pin an exact length), +`sparseCheck`
+ * for array sparse/not-sparse.
+ * @typedef {{
+ *   kind: 'lengthSize',
+ *   path: string,
+ *   $size?: number,
+ *   $gt?: number, $gte?: number, $lt?: number, $lte?: number,
+ *   sparseCheck?: boolean
+ * }} QueryLengthSizeLeaf
+ */
+
+/**
+ * `number`/`NumberObject`/`bigint`/`date`/`buffersource`, with `valueType`
+ * distinguishing them. Bounds are Mongo-style `$gt`/`$gte`/`$lt`/`$lte`
+ * rather than a `min`/`max` pair plus an inclusive boolean - inclusivity is
+ * simply which operator is present. The README's "Is Not Range" variant
+ * wraps the same leaf in `$not` rather than being a separate kind.
+ * @typedef {{
+ *   kind: 'range',
+ *   path: string,
+ *   valueType: 'number'|'NumberObject'|'bigint'|'date'|'buffersource',
+ *   $gt?: number|bigint|string,
+ *   $gte?: number|bigint|string,
+ *   $lt?: number|bigint|string,
+ *   $lte?: number|bigint|string
+ * }} QueryRangeLeaf
+ */
+
+/**
+ * @typedef {{kind: 'not', query: QueryNode}} QueryNotLeaf
+ */
+
+/**
+ * `number`/`NumberObject`: is/is-not an integer.
+ * @typedef {{kind: 'integerCheck', path: string, isInteger: boolean}} QueryIntegerCheckLeaf
+ */
+
+/**
+ * `string`/`StringObject`/`Blob`/`File`/regexp-source/symbol-description
+ * (via `$in`/`$nin`).
+ * @typedef {{
+ *   kind: 'literalSet',
+ *   path: string,
+ *   $in?: unknown[],
+ *   $nin?: unknown[]
+ * }} QueryLiteralSetLeaf
+ */
+
+/**
+ * `string`/`StringObject`/`Blob`/`File`/regexp-source/symbol-description
+ * (via `$regex`/`$options`, matching Mongo's own field names).
+ * @typedef {{
+ *   kind: 'regex',
+ *   path: string,
+ *   $regex: string,
+ *   $options?: string
+ * }} QueryRegexLeaf
+ */
+
+/**
+ * `string`/`StringObject`/`Blob`/`File`/regexp-source/symbol-description:
+ * a substring the value must not contain.
+ * @typedef {{
+ *   kind: 'notContains',
+ *   path: string,
+ *   value: string
+ * }} QueryNotContainsLeaf
+ */
+
+/**
+ * `enum`, SpecialNumber's `Infinity`/`-Infinity`/`NaN`/`-0` (via
+ * `$in`/`$nin`).
+ * @typedef {{
+ *   kind: 'multiSelect',
+ *   path: string,
+ *   $in?: unknown[],
+ *   $nin?: unknown[]
+ * }} QueryMultiSelectLeaf
+ */
+
+/**
+ * Native enum key-vs-value; no Mongo equivalent, stays custom.
+ * @typedef {{
+ *   kind: 'keyValueEnum',
+ *   path: string,
+ *   matchKeys: boolean,
+ *   values: unknown[]
+ * }} QueryKeyValueEnumLeaf
+ */
+
+/**
+ * Union/xor/discriminatedUnion "has type", carrying `discriminatorValue`
+ * when applicable, including when nested under a Map/Record key or value;
+ * no Mongo equivalent, stays custom.
+ * @typedef {{
+ *   kind: 'typeOf',
+ *   path: string,
+ *   searchType: string,
+ *   discriminatorValue?: unknown
+ * }} QueryTypeOfLeaf
+ */
+
+/**
+ * XPath/CSS-selector/full-text/raw-HTML-regex; no Mongo equivalent.
+ * @typedef {{
+ *   kind: 'blobHTML',
+ *   path: string,
+ *   mode: 'xpath'|'cssSelector'|'fullText'|'rawHTMLRegex',
+ *   value: string
+ * }} QueryBlobHTMLLeaf
+ */
+
+/**
+ * Per-dimension ranges for DOMRect/Point/Matrix, each dimension itself a
+ * `range` leaf, + `readonlyCheck`/`dimensionCheck` (is/is-not readonly,
+ * is/is-not 3d); no Mongo equivalent.
+ * @typedef {{
+ *   kind: 'domShape',
+ *   path: string,
+ *   dimensions: {[dimension: string]: QueryRangeLeaf},
+ *   readonlyCheck?: boolean,
+ *   dimensionCheck?: 2|3
+ * }} QueryDomShapeLeaf
+ */
+
+/**
+ * Paired key+value leaves with a joint-match flag; no Mongo equivalent.
+ * @typedef {{
+ *   kind: 'mapRecordJoint',
+ *   path: string,
+ *   keyQuery?: QueryNode,
+ *   valueQuery?: QueryNode,
+ *   joint: boolean
+ * }} QueryMapRecordJointLeaf
+ */
+
+/**
+ * Promise/literal/catch/function: forwards to a nested `QueryNode` for the
+ * child schema so the tree stays uniform even where a type adds no
+ * constraint of its own; purely structural, no Mongo equivalent.
+ * @typedef {{
+ *   kind: 'passThrough',
+ *   path: string,
+ *   query?: QueryNode
+ * }} QueryPassThroughLeaf
+ */
+
+/**
+ * Undefined/void/null (via `$exists`).
+ * @typedef {{kind: 'presence', path: string, $exists: boolean}} QueryPresenceLeaf
+ */
+
+/**
+ * Boolean/BooleanObject - Mongo would normally express this as a bare
+ * `{field: true}` shorthand, which doesn't fit our path-carrying leaf
+ * shape, so this stays a custom kind.
+ * @typedef {{
+ *   kind: 'booleanEquals',
+ *   path: string,
+ *   value: boolean
+ * }} QueryBooleanEqualsLeaf
+ */
+
+/**
+ * @typedef {QueryHasPropertyLeaf|QueryLengthSizeLeaf|QueryRangeLeaf|
+ *   QueryNotLeaf|QueryIntegerCheckLeaf|QueryLiteralSetLeaf|QueryRegexLeaf|
+ *   QueryNotContainsLeaf|QueryMultiSelectLeaf|QueryKeyValueEnumLeaf|
+ *   QueryTypeOfLeaf|QueryBlobHTMLLeaf|QueryDomShapeLeaf|
+ *   QueryMapRecordJointLeaf|QueryPassThroughLeaf|QueryPresenceLeaf|
+ *   QueryBooleanEqualsLeaf
+ * } QueryLeaf
+ */
+
+/**
+ * @typedef {QueryAnd|QueryOr|QueryLeaf} QueryNode
+ */
+
+export {};

package/src/search/queryTreeBuilders.js

@@ -0,0 +1,224 @@
+/**
+ * The only runtime pieces for building `queryTree.js` nodes - every search
+ * module builds nodes through these factories rather than hand-rolling leaf
+ * objects, so tests can import the same constructors to build expected-value
+ * fixtures.
+ */
+
+/**
+ * @param {import('./queryTree.js').QueryNode[]} nodes
+ * @returns {import('./queryTree.js').QueryAnd}
+ */
+export function makeAndNode (nodes) {
+  return {$and: nodes};
+}
+
+/**
+ * Combines the leaves a single widget contributes (e.g. a number leaf's
+ * range plus its separate "Is/Is Not Integer" check) into one `QueryNode`:
+ * drops any `undefined` (no constraint entered there), returns `undefined`
+ * if nothing is left, the bare node if only one is left, else an `$and` of
+ * the rest - so a widget with several independent controls still honors
+ * `getQuery`'s "`undefined` means no constraint" convention without every
+ * such widget re-implementing this collapsing logic itself.
+ * @param {(import('./queryTree.js').QueryNode|undefined)[]} nodes
+ * @returns {import('./queryTree.js').QueryNode|undefined}
+ */
+export function combineAnd (nodes) {
+  const filtered = /** @type {import('./queryTree.js').QueryNode[]} */ (
+    nodes.filter((node) => node !== undefined)
+  );
+  if (filtered.length === 0) {
+    return undefined;
+  }
+  if (filtered.length === 1) {
+    return filtered[0];
+  }
+  return makeAndNode(filtered);
+}
+
+/**
+ * @param {import('./queryTree.js').QueryNode[]} nodes
+ * @returns {import('./queryTree.js').QueryOr}
+ */
+export function makeOrNode (nodes) {
+  return {$or: nodes};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} $exists
+ * @returns {import('./queryTree.js').QueryHasPropertyLeaf}
+ */
+export function makeHasPropertyLeaf (path, $exists) {
+  return {kind: 'hasProperty', path, $exists};
+}
+
+/**
+ * @param {string} path
+ * @param {{
+ *   $size?: number,
+ *   $gt?: number, $gte?: number, $lt?: number, $lte?: number,
+ *   sparseCheck?: boolean
+ * }} cfg
+ * @returns {import('./queryTree.js').QueryLengthSizeLeaf}
+ */
+export function makeLengthSizeLeaf (path, cfg = {}) {
+  return {kind: 'lengthSize', path, ...cfg};
+}
+
+/**
+ * @param {string} path
+ * @param {import('./queryTree.js').QueryRangeLeaf['valueType']} valueType
+ * @param {{
+ *   $gt?: number|bigint|string, $gte?: number|bigint|string,
+ *   $lt?: number|bigint|string, $lte?: number|bigint|string
+ * }} cfg
+ * @returns {import('./queryTree.js').QueryRangeLeaf}
+ */
+export function makeRangeLeaf (path, valueType, cfg = {}) {
+  return {kind: 'range', path, valueType, ...cfg};
+}
+
+/**
+ * @param {import('./queryTree.js').QueryNode} query
+ * @returns {import('./queryTree.js').QueryNotLeaf}
+ */
+export function makeNotLeaf (query) {
+  return {kind: 'not', query};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} isInteger
+ * @returns {import('./queryTree.js').QueryIntegerCheckLeaf}
+ */
+export function makeIntegerCheckLeaf (path, isInteger) {
+  return {kind: 'integerCheck', path, isInteger};
+}
+
+/**
+ * @param {string} path
+ * @param {{$in?: unknown[], $nin?: unknown[]}} cfg
+ * @returns {import('./queryTree.js').QueryLiteralSetLeaf}
+ */
+export function makeLiteralSetLeaf (path, cfg = {}) {
+  return {kind: 'literalSet', path, ...cfg};
+}
+
+/**
+ * @param {string} path
+ * @param {string} $regex
+ * @param {string} [$options]
+ * @returns {import('./queryTree.js').QueryRegexLeaf}
+ */
+export function makeRegexLeaf (path, $regex, $options) {
+  return {kind: 'regex', path, $regex, ...($options ? {$options} : {})};
+}
+
+/**
+ * @param {string} path
+ * @param {string} value
+ * @returns {import('./queryTree.js').QueryNotContainsLeaf}
+ */
+export function makeNotContainsLeaf (path, value) {
+  return {kind: 'notContains', path, value};
+}
+
+/**
+ * @param {string} path
+ * @param {{$in?: unknown[], $nin?: unknown[]}} cfg
+ * @returns {import('./queryTree.js').QueryMultiSelectLeaf}
+ */
+export function makeMultiSelectLeaf (path, cfg = {}) {
+  return {kind: 'multiSelect', path, ...cfg};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} matchKeys
+ * @param {unknown[]} values
+ * @returns {import('./queryTree.js').QueryKeyValueEnumLeaf}
+ */
+export function makeKeyValueEnumLeaf (path, matchKeys, values) {
+  return {kind: 'keyValueEnum', path, matchKeys, values};
+}
+
+/**
+ * @param {string} path
+ * @param {string} searchType
+ * @param {unknown} [discriminatorValue]
+ * @returns {import('./queryTree.js').QueryTypeOfLeaf}
+ */
+export function makeTypeOfLeaf (path, searchType, discriminatorValue) {
+  return {
+    kind: 'typeOf',
+    path,
+    searchType,
+    ...(discriminatorValue === undefined ? {} : {discriminatorValue})
+  };
+}
+
+/**
+ * @param {string} path
+ * @param {import('./queryTree.js').QueryBlobHTMLLeaf['mode']} mode
+ * @param {string} value
+ * @returns {import('./queryTree.js').QueryBlobHTMLLeaf}
+ */
+export function makeBlobHTMLLeaf (path, mode, value) {
+  return {kind: 'blobHTML', path, mode, value};
+}
+
+/**
+ * @param {string} path
+ * @param {{[dimension: string]: import('./queryTree.js').QueryRangeLeaf}} dimensions
+ * @param {{readonlyCheck?: boolean, dimensionCheck?: 2|3}} [cfg]
+ * @returns {import('./queryTree.js').QueryDomShapeLeaf}
+ */
+export function makeDomShapeLeaf (path, dimensions, cfg = {}) {
+  return {kind: 'domShape', path, dimensions, ...cfg};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} joint
+ * @param {import('./queryTree.js').QueryNode} [keyQuery]
+ * @param {import('./queryTree.js').QueryNode} [valueQuery]
+ * @returns {import('./queryTree.js').QueryMapRecordJointLeaf}
+ */
+export function makeMapRecordJointLeaf (path, joint, keyQuery, valueQuery) {
+  return {
+    kind: 'mapRecordJoint',
+    path,
+    joint,
+    ...(keyQuery ? {keyQuery} : {}),
+    ...(valueQuery ? {valueQuery} : {})
+  };
+}
+
+/**
+ * @param {string} path
+ * @param {import('./queryTree.js').QueryNode} [query]
+ * @returns {import('./queryTree.js').QueryPassThroughLeaf}
+ */
+export function makePassThroughLeaf (path, query) {
+  return {kind: 'passThrough', path, ...(query ? {query} : {})};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} $exists
+ * @returns {import('./queryTree.js').QueryPresenceLeaf}
+ */
+export function makePresenceLeaf (path, $exists) {
+  return {kind: 'presence', path, $exists};
+}
+
+/**
+ * @param {string} path
+ * @param {boolean} value
+ * @returns {import('./queryTree.js').QueryBooleanEqualsLeaf}
+ */
+export function makeBooleanEqualsLeaf (path, value) {
+  return {kind: 'booleanEquals', path, value};
+}