@es-joy/jsoe 0.28.2 → 0.30.0

package/src/search/queryTreeBuilders.js

@@ -0,0 +1,233 @@
+/**
+ * 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 {boolean} isValid
+ * @returns {import('./queryTree.js').QueryValidDateCheckLeaf}
+ */
+export function makeValidDateCheckLeaf (path, isValid) {
+  return {kind: 'validDateCheck', path, isValid};
+}
+
+/**
+ * @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};
+}

package/src/search/searchDispatch.js

@@ -0,0 +1,291 @@
+import {getSchemaType, getTypesForSchema} from '../formats/schema.js';
+
+import dateSearchType from './fundamentalTypes/dateSearchType.js';
+import numberSearchType from './fundamentalTypes/numberSearchType.js';
+import bigintSearchType from './fundamentalTypes/bigintSearchType.js';
+import stringSearchType from './fundamentalTypes/stringSearchType.js';
+import regexpSearchType from './fundamentalTypes/regexpSearchType.js';
+import booleanSearchType from './fundamentalTypes/booleanSearchType.js';
+import symbolSearchType from './fundamentalTypes/symbolSearchType.js';
+import undefinedSearchType from './fundamentalTypes/undefinedSearchType.js';
+import nullSearchType from './fundamentalTypes/nullSearchType.js';
+import nanSearchType from './fundamentalTypes/nanSearchType.js';
+import enumSearchType from './fundamentalTypes/enumSearchType.js';
+import arraySearchType from './fundamentalTypes/arraySearchType.js';
+import setSearchType from './fundamentalTypes/setSearchType.js';
+import objectSearchType from './fundamentalTypes/objectSearchType.js';
+import filelistSearchType from './fundamentalTypes/filelistSearchType.js';
+import tupleSearchType from './subTypes/tupleSearchType.js';
+import recordSearchType from './subTypes/recordSearchType.js';
+import mapSearchType from './fundamentalTypes/mapSearchType.js';
+import promiseSearchType from './fundamentalTypes/promiseSearchType.js';
+import catchSearchType from './fundamentalTypes/catchSearchType.js';
+import functionSearchType from './fundamentalTypes/functionSearchType.js';
+import fileSearchType from './fundamentalTypes/fileSearchType.js';
+import blobSearchType from './fundamentalTypes/blobSearchType.js';
+import unionSearchType from './unions/unionSearchType.js';
+import xorSearchType from './unions/xorSearchType.js';
+import discriminatedUnionSearchType from './unions/discriminatedUnionSearchType.js';
+import errorSearchType from './fundamentalTypes/errorSearchType.js';
+import errorsSpecialSearchType from './superTypes/errorsSpecialSearchType.js';
+import domexceptionSearchType from './fundamentalTypes/domexceptionSearchType.js';
+import domrectSearchType from './superTypes/domrectSearchType.js';
+import dompointSearchType from './superTypes/dompointSearchType.js';
+import dommatrixSearchType from './superTypes/dommatrixSearchType.js';
+import SpecialRealNumberSearchType from './superTypes/SpecialRealNumberSearchType.js';
+import buffersourceSearchType from './superTypes/buffersourceSearchType.js';
+import blobHTMLSearchType from './subTypes/blobHTMLSearchType.js';
+
+/**
+ * @typedef {import('./queryTree.js').QueryNode} QueryNode
+ */
+
+/**
+ * The search-side analogue of `TypeObject` (`src/types.js:308-408`): two
+ * methods, `buildUI` (a `jml` array) and `getQuery` (reads the built DOM
+ * back into a `QueryNode`, or `undefined` when no constraint was entered).
+ * @typedef {{
+ *   buildUI: (cfg: {
+ *     schemaObject: import('../formats/schema.js').ZodexSchema,
+ *     path: string,
+ *     typeNamespace?: string,
+ *     topRoot?: import('../types.js').RootElement,
+ *     types?: import('../types.js').default,
+ *     originalJSON?: import('../formats/schema.js').ZodexSchema
+ *   }) => import('../types.js').JamilihArray,
+ *   getQuery: (cfg: {
+ *     root: HTMLElement,
+ *     path: string
+ *   }) => QueryNode|undefined
+ * }} SearchTypeObject
+ */
+
+/**
+ * Temporary placeholder used while a given search type's real module is
+ * still to-do (build order, `docs/proposals/search-plan.md` §6). Renders a
+ * plainly-labelled marker rather than throwing, so the full dispatch table
+ * is exercisable end-to-end before every leaf/composite is implemented.
+ * @param {string} searchSchemaType
+ * @returns {SearchTypeObject}
+ */
+function stubSearchType (searchSchemaType) {
+  return {
+    buildUI: () => ['span', [`TODO: ${searchSchemaType}`]],
+    getQuery: () => undefined
+  };
+}
+
+/**
+ * Escape hatch for `instanceof`-outside-`FileList` and any schema shape not
+ * (yet) recognized: no widget is rendered for it, only this stand-in.
+ * @type {SearchTypeObject}
+ */
+const noneditableSearchType = stubSearchType('noneditable');
+
+/**
+ * `Record<string, SearchTypeObject>` registry, analogous to
+ * `Types.prototype.availableTypes` (`src/types.js:473-581`). Every entry is
+ * a stub for now (build order step 1); later steps replace individual
+ * entries with their real `*SearchType.js` module, one at a time, without
+ * touching this shape.
+ *
+ * A few keys deliberately share one module reference rather than getting
+ * their own: `BooleanObject`/`NumberObject`/`StringObject`/`bigintObject`
+ * point at their primitive counterpart's module because a search leaf only
+ * cares about the query semantics (e.g. "true or false"), never about how
+ * the value-editing side constructs the boxed wrapper at runtime. Likewise
+ * `arrayNonindexKeys` mirrors `array`, `looseRecord` mirrors `record`, and
+ * `templateLiteral` mirrors `string` (README: a template literal is still
+ * fundamentally a string-shape constraint for this pass; see §3 of the
+ * search plan).
+ * @type {{[key: string]: SearchTypeObject}}
+ */
+const availableSearchTypes = {
+  // fundamentalTypes
+  date: dateSearchType,
+  number: numberSearchType,
+  NumberObject: numberSearchType,
+  bigint: bigintSearchType,
+  bigintObject: bigintSearchType,
+  string: stringSearchType,
+  StringObject: stringSearchType,
+  regexp: regexpSearchType,
+  boolean: booleanSearchType,
+  BooleanObject: booleanSearchType,
+  symbol: symbolSearchType,
+  undef: undefinedSearchType,
+  null: nullSearchType,
+  nan: nanSearchType,
+  array: arraySearchType,
+  arrayNonindexKeys: arraySearchType,
+  object: objectSearchType,
+  map: mapSearchType,
+  set: setSearchType,
+  filelist: filelistSearchType,
+  file: fileSearchType,
+  blob: blobSearchType,
+  error: errorSearchType,
+  domexception: domexceptionSearchType,
+  promise: promiseSearchType,
+  function: functionSearchType,
+  enum: enumSearchType,
+
+  // subTypes
+  tuple: tupleSearchType,
+  record: recordSearchType,
+  looseRecord: recordSearchType,
+  blobHTML: blobHTMLSearchType,
+
+  // superTypes
+  domrect: domrectSearchType,
+  dompoint: dompointSearchType,
+  dommatrix: dommatrixSearchType,
+  errors: errorsSpecialSearchType,
+  SpecialNumber: stubSearchType('SpecialNumber'),
+  SpecialRealNumber: SpecialRealNumberSearchType,
+  buffersource: buffersourceSearchType,
+
+  // unions
+  union: unionSearchType,
+  xor: xorSearchType,
+  discriminatedUnion: discriminatedUnionSearchType,
+
+  // string-shape alias (§3)
+  templateLiteral: stringSearchType,
+
+  // `getSchemaType` has no case for `catch` at all (unlike `promise`/
+  //   `function`, already in `zodexToStructuredCloningTypeMap`), so it's
+  //   added as its own extra case in `getSearchSchemaType` below
+  catch: catchSearchType,
+
+  // escape hatch, also the fallback for any unrecognized/not-yet-supported
+  //   schema shape (see `getSearchTypeObject`)
+  resurrectable: noneditableSearchType
+};
+
+/**
+ * Schema-only analogue of `getSchemaType` (`src/formats/schema.js:145-166`).
+ * Must not reimplement that function's special-casing (stringbool pipe,
+ * `codec`/filelist, `instanceof`, `literal`, `enum`, `templateLiteral`,
+ * `getCheckedType` fallback) - it calls straight through to it, and only
+ * adds the extra shape distinctions `getSchemaType`'s own
+ * `AvailableArbitraryType` output collapses (tuple, record/looseRecord,
+ * union/xor/discriminatedUnion all currently reduce to `'array'`/`'object'`/
+ * nothing, per `zodexToStructuredCloningTypeMap`,
+ * `src/formats/schema.js:30-56`).
+ *
+ * Intersection schemas are deliberately not a case here - they're resolved
+ * before dispatch, by the search-widget walker calling `getTypesForSchema`
+ * (search plan §3), reusing jsoe's existing intersection-merging machinery
+ * rather than this function reinventing it.
+ * @param {import('../formats/schema.js').ZodexSchema} schemaObject
+ * @returns {string}
+ */
+export function getSearchSchemaType (schemaObject) {
+  if (schemaObject.type === 'tuple') {
+    return 'tuple';
+  }
+  if (schemaObject.type === 'record' || schemaObject.type === 'looseRecord') {
+    return schemaObject.type;
+  }
+  if (['union', 'xor', 'discriminatedUnion'].includes(schemaObject.type)) {
+    return schemaObject.type;
+  }
+
+  // An `enum` control can show a multiple-select list and template literal
+  //   parts might justify their own search controls, so need to detect
+  //   these schema types.
+  if (['templateLiteral', 'enum'].includes(schemaObject.type)) {
+    return schemaObject.type;
+  }
+
+  // `getSchemaType` (`src/formats/schema.js`) has no `catch` case at all -
+  //   its `zodexToStructuredCloningTypeMap` never mapped it, unlike
+  //   `promise`/`function` - so it's added here rather than there, matching
+  //   how tuple/record/union already extend the search-only shape space.
+  if (schemaObject.type === 'catch') {
+    return 'catch';
+  }
+
+  return /** @type {string} */ (
+    getSchemaType(schemaObject)
+  ); // inherits stringbool/codec/instanceof/checks handling verbatim
+}
+
+/**
+ * The one exported call site every recursive search widget uses (analogous
+ * to `types.getTypeObject(type)`, `src/types.js:1106-1108`, but schema-in
+ * rather than type-string-in, since there's no value to key off). Falls
+ * back to `noneditableSearchType` for any schema shape `getSearchSchemaType`
+ * reports that isn't (yet) registered, rather than throwing - the same
+ * escape hatch a bare top-level `instanceof` schema falls through to.
+ * @param {import('../formats/schema.js').ZodexSchema} schemaObject
+ * @returns {SearchTypeObject}
+ */
+export function getSearchTypeObject (schemaObject) {
+  const searchSchemaType = getSearchSchemaType(schemaObject);
+  return availableSearchTypes[searchSchemaType] ?? noneditableSearchType;
+}
+
+/**
+ * Intersection schemas are never registered in `availableSearchTypes` -
+ * resolved here instead of in `getSearchSchemaType`, reusing jsoe's
+ * existing intersection-merging machinery (`getTypesForSchema`,
+ * `src/formats/schema.js`) rather than reinventing it (search plan §3/§5).
+ * A single merged result replaces the intersection outright; more than one
+ * (e.g. one side of the intersection is itself a union) is handed to
+ * `unionSearchType.js` unchanged via a synthesized `union` wrapper, the
+ * same way `unionSearchType.js` already treats distinguishable branches.
+ * @param {import('../formats/schema.js').ZodexSchema} schemaObject
+ * @param {import('../formats/schema.js').ZodexSchema} originalJSON
+ * @returns {import('../formats/schema.js').ZodexSchema}
+ */
+function resolveIntersection (schemaObject, originalJSON) {
+  if (schemaObject.type !== 'intersection') {
+    return schemaObject;
+  }
+  const merged = [...getTypesForSchema(schemaObject, originalJSON)];
+  return merged.length === 1
+    ? merged[0]
+    : /** @type {import('../formats/schema.js').ZodexSchema} */ (
+      /** @type {unknown} */ ({type: 'union', options: merged})
+    );
+}
+
+/**
+ * The call site every *recursive* search widget uses in place of calling
+ * `getSearchTypeObject(...).buildUI(...)` directly - it's the same thing,
+ * plus `resolveIntersection` run first, so an intersection schema at any
+ * depth (not just the one `buildSearchChoices` is called with) still
+ * resolves instead of falling through to the `noneditableSearchType`
+ * escape hatch. `originalJSON` (needed for the `getTypesForSchema` call's
+ * own `$ref` resolution) defaults to `schemaObject` itself only as a last
+ * resort for a call site that has none to pass down - every recursive
+ * caller should be threading the true document root through via its own
+ * `originalJSON` parameter instead.
+ * @param {{
+ *   schemaObject: import('../formats/schema.js').ZodexSchema,
+ *   path: string,
+ *   typeNamespace?: string,
+ *   topRoot?: import('../types.js').RootElement,
+ *   types?: import('../types.js').default,
+ *   originalJSON?: import('../formats/schema.js').ZodexSchema
+ * }} cfg
+ * @returns {import('../types.js').JamilihArray}
+ */
+export function buildSearchWidget ({
+  schemaObject, path, typeNamespace, topRoot, types, originalJSON
+}) {
+  const resolvedOriginalJSON = originalJSON ?? schemaObject;
+  const resolvedSchema = resolveIntersection(schemaObject, resolvedOriginalJSON);
+  return getSearchTypeObject(resolvedSchema).buildUI({
+    schemaObject: resolvedSchema,
+    path,
+    typeNamespace,
+    topRoot,
+    types,
+    originalJSON: resolvedOriginalJSON
+  });
+}
+
+export {availableSearchTypes, noneditableSearchType, resolveIntersection};