json-rest-api 1.0.20 → 1.0.22

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__fractional-positioning.js.txt

@@ -0,0 +1,188 @@
+     1	import { requirePackage } from 'hooked-api'
+     2	
+     3	let generateKeyBetween
+     4	try {
+     5	  ({ generateKeyBetween } = await import('fractional-indexing'))
+     6	} catch (e) {
+     7	  requirePackage('fractional-indexing', 'positioning',
+     8	    'Fractional indexing is required for the positioning plugin to generate sortable position keys. This is a peer dependency.')
+     9	}
+    10	
+    11	/**
+    12	 * Helper functions for fractional positioning
+    13	 * Uses the fractional-indexing library for generating position keys
+    14	 */
+    15	
+    16	/**
+    17	 * Calculate position for a new/moved item based on beforeId
+    18	 * @param {Array} items - Array of items with position field
+    19	 * @param {string} beforeId - ID to position before (null = last)
+    20	 * @param {string} idField - Name of the ID field
+    21	 * @param {string} positionField - Name of the position field
+    22	 * @returns {string} New position key
+    23	 */
+    24	export function calculatePosition (items, beforeId, idField, positionField) {
+    25	  // Sort items by position using simple string comparison
+    26	  // Important: fractional-indexing expects ASCII/Unicode ordering, not locale-specific
+    27	  const sorted = [...items].sort((a, b) => {
+    28	    const posA = a[positionField] || ''
+    29	    const posB = b[positionField] || ''
+    30	    return posA < posB ? -1 : posA > posB ? 1 : 0
+    31	  })
+    32	
+    33	  // If no items, start in the middle
+    34	  if (sorted.length === 0) {
+    35	    return generateKeyBetween(null, null) // Returns 'a0'
+    36	  }
+    37	
+    38	  // Position at end
+    39	  if (beforeId === null || beforeId === undefined) {
+    40	    const lastItem = sorted[sorted.length - 1]
+    41	    return generateKeyBetween(lastItem[positionField], null)
+    42	  }
+    43	
+    44	  // Find the item to position before
+    45	  const beforeIndex = sorted.findIndex(item => String(item[idField]) === String(beforeId))
+    46	
+    47	  // If beforeId not found, position at end
+    48	  if (beforeIndex === -1) {
+    49	    const lastItem = sorted[sorted.length - 1]
+    50	    return generateKeyBetween(lastItem[positionField], null)
+    51	  }
+    52	
+    53	  // Position before the found item
+    54	  const beforeItem = sorted[beforeIndex]
+    55	  const prevItem = beforeIndex > 0 ? sorted[beforeIndex - 1] : null
+    56	
+    57	  const result = generateKeyBetween(
+    58	    prevItem ? prevItem[positionField] : null,
+    59	    beforeItem[positionField]
+    60	  )
+    61	
+    62	  return result
+    63	}
+    64	
+    65	/**
+    66	 * Initialize position for first item in a group
+    67	 * @returns {string} Initial position key
+    68	 */
+    69	export function getInitialPosition () {
+    70	  return generateKeyBetween(null, null) // Returns 'a0'
+    71	}
+    72	
+    73	/**
+    74	 * Rebalance positions if they get too long (optional maintenance)
+    75	 * @param {Array} items - Array of items to rebalance
+    76	 * @param {string} positionField - Name of the position field
+    77	 * @param {number} maxLength - Maximum position string length before rebalancing
+    78	 * @returns {Array} Items with new positions (or original if no rebalance needed)
+    79	 */
+    80	export function rebalancePositions (items, positionField, maxLength = 50) {
+    81	  // Check if rebalancing is needed
+    82	  const needsRebalance = items.some(item =>
+    83	    item[positionField] && item[positionField].length > maxLength
+    84	  )
+    85	
+    86	  if (!needsRebalance) {
+    87	    return items
+    88	  }
+    89	
+    90	  // Sort by current position
+    91	  const sorted = [...items].sort((a, b) => {
+    92	    const posA = a[positionField] || ''
+    93	    const posB = b[positionField] || ''
+    94	    return posA < posB ? -1 : posA > posB ? 1 : 0
+    95	  })
+    96	
+    97	  // Generate evenly spaced positions
+    98	  const rebalanced = []
+    99	  let prevKey = null
+   100	
+   101	  for (let i = 0; i < sorted.length; i++) {
+   102	    // For even spacing, we generate keys sequentially
+   103	    const newPosition = generateKeyBetween(prevKey, null)
+   104	
+   105	    rebalanced.push({
+   106	      ...sorted[i],
+   107	      [positionField]: newPosition
+   108	    })
+   109	
+   110	    prevKey = newPosition
+   111	  }
+   112	
+   113	  return rebalanced
+   114	}
+   115	
+   116	/**
+   117	 * Check if a position value is valid
+   118	 * @param {string} position - Position value to check
+   119	 * @returns {boolean} True if valid
+   120	 */
+   121	export function isValidPosition (position) {
+   122	  if (!position || typeof position !== 'string') {
+   123	    return false
+   124	  }
+   125	
+   126	  // Fractional keys should match pattern: lowercase letters and digits
+   127	  return /^[a-z0-9]+$/i.test(position)
+   128	}
+   129	
+   130	/**
+   131	 * Get items that need position assignment (for migration)
+   132	 * @param {Array} items - Array of items
+   133	 * @param {string} positionField - Name of the position field
+   134	 * @returns {Array} Items without valid positions
+   135	 */
+   136	export function getUnpositionedItems (items, positionField) {
+   137	  return items.filter(item => !isValidPosition(item[positionField]))
+   138	}
+   139	
+   140	/**
+   141	 * Assign initial positions to items that don't have them
+   142	 * @param {Array} items - Array of items
+   143	 * @param {string} positionField - Name of the position field
+   144	 * @param {string} orderByField - Optional field to order by initially
+   145	 * @returns {Array} Items with positions assigned
+   146	 */
+   147	export function assignInitialPositions (items, positionField, orderByField = null) {
+   148	  const positioned = items.filter(item => isValidPosition(item[positionField]))
+   149	  const unpositioned = items.filter(item => !isValidPosition(item[positionField]))
+   150	
+   151	  if (unpositioned.length === 0) {
+   152	    return items
+   153	  }
+   154	
+   155	  // Sort unpositioned items if orderBy field provided
+   156	  if (orderByField) {
+   157	    unpositioned.sort((a, b) => {
+   158	      const valA = a[orderByField]
+   159	      const valB = b[orderByField]
+   160	      if (valA < valB) return -1
+   161	      if (valA > valB) return 1
+   162	      return 0
+   163	    })
+   164	  }
+   165	
+   166	  // Get the last positioned item
+   167	  const sortedPositioned = [...positioned].sort((a, b) => {
+   168	    const posA = a[positionField] || ''
+   169	    const posB = b[positionField] || ''
+   170	    return posA < posB ? -1 : posA > posB ? 1 : 0
+   171	  })
+   172	  const lastPositioned = sortedPositioned[sortedPositioned.length - 1]
+   173	
+   174	  let lastKey = lastPositioned ? lastPositioned[positionField] : null
+   175	
+   176	  // Assign positions to unpositioned items
+   177	  const newlyPositioned = unpositioned.map(item => {
+   178	    const newKey = generateKeyBetween(lastKey, null)
+   179	    lastKey = newKey
+   180	
+   181	    return {
+   182	      ...item,
+   183	      [positionField]: newKey
+   184	    }
+   185	  })
+   186	
+   187	  return [...positioned, ...newlyPositioned]
+   188	}

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__querying-writing__compile-schemas.js.txt

@@ -0,0 +1,336 @@
+     1	import { createSchema } from 'json-rest-schema'
+     2	import { ensureSearchFieldsAreIndexed, generateSearchSchemaFromSchema, sortFieldsByDependencies } from './schema-helpers.js'
+     3	
+     4	/**
+     5	 * Compiles and enriches schemas for a resource scope
+     6	 *
+     7	 * @param {Object} scope - Scope containing raw schema options
+     8	 * @param {Object} deps - Dependencies with context and hooks
+     9	 * @returns {Promise<void>} Resolves when compilation complete
+    10	 *
+    11	 * @example
+    12	 * // Input: Raw schema with computed field
+    13	 * const rawFields = {
+    14	 *   title: { type: 'string', required: true },
+    15	 *   content: { type: 'string' },
+    16	 *   author_id: { belongsTo: 'users', as: 'author' },  // Missing type
+    17	 *   word_count: {
+    18	 *     type: 'number',
+    19	 *     computed: true,
+    20	 *     compute: (record) => record.content.split(' ').length
+    21	 *   }
+    22	 * };
+    23	 *
+    24	 * await compileSchemas(scope, deps);
+    25	 *
+    26	 * // Output in scope.vars.schemaInfo:
+    27	 * // {
+    28	 * //   schema: Schema {},           // json-rest-schema instance
+    29	 * //   schemaStructure: {
+    30	 * //     title: { type: 'string', required: true },
+    31	 * //     content: { type: 'string' },
+    32	 * //     author_id: { type: 'id', belongsTo: 'users', as: 'author' }  // Type added!
+    33	 * //     // Note: word_count removed (it's computed)
+    34	 * //   },
+    35	 * //   computed: {
+    36	 * //     word_count: { type: 'number', computed: true, compute: [Function] }
+    37	 * //   }
+    38	 * // }
+    39	 *
+    40	 * @example
+    41	 * // Input: Schema with search fields
+    42	 * const rawFields = {
+    43	 *   title: { type: 'string', search: true },    // Searchable
+    44	 *   status: { type: 'string' },                 // Not searchable
+    45	 *   author_id: { belongsTo: 'users', as: 'author' }
+    46	 * };
+    47	 *
+    48	 * // Output: Auto-generated searchSchema
+    49	 * // searchSchemaObject contains:
+    50	 * // {
+    51	 * //   title: {
+    52	 * //     type: 'string',
+    53	 * //     indexed: true,        // Added for DB optimization
+    54	 * //     filterOperator: '='   // Default operator
+    55	 * //   }
+    56	 * // }
+    57	 *
+    58	 * @example
+    59	 * // Input: Pivot table auto-detection
+    60	 * const pivotSchema = {
+    61	 *   article_id: { belongsTo: 'articles', as: 'article' },
+    62	 *   tag_id: { belongsTo: 'tags', as: 'tag' },
+    63	 *   display_order: { type: 'number' }
+    64	 * };
+    65	 *
+    66	 * // Output: Both foreign keys become searchable
+    67	 * // schemaStructure will have:
+    68	 * // {
+    69	 * //   article_id: { type: 'id', belongsTo: 'articles', as: 'article', search: true },
+    70	 * //   tag_id: { type: 'id', belongsTo: 'tags', as: 'tag', search: true },
+    71	 * //   display_order: { type: 'number' }
+    72	 * // }
+    73	 * // This enables efficient many-to-many filtering!
+    74	 *
+    75	 * @example
+    76	 * // Input: Schema with dependent getters
+    77	 * const schema = {
+    78	 *   first_name: { type: 'string' },
+    79	 *   last_name: { type: 'string' },
+    80	 *   full_name: {
+    81	 *     type: 'string',
+    82	 *     getter: (record) => `${record.first_name} ${record.last_name}`,
+    83	 *     runGetterAfter: ['first_name', 'last_name']  // Dependencies
+    84	 *   },
+    85	 *   email: {
+    86	 *     type: 'string',
+    87	 *     setter: (value) => value.toLowerCase().trim()
+    88	 *   }
+    89	 * };
+    90	 *
+    91	 * // Output includes dependency-sorted fields:
+    92	 * // {
+    93	 * //   fieldGetters: { full_name: { getter: [Function], runGetterAfter: [...] } },
+    94	 * //   sortedGetterFields: ['full_name'],    // Topologically sorted
+    95	 * //   fieldSetters: { email: { setter: [Function], runSetterAfter: [] } },
+    96	 * //   sortedSetterFields: ['email']
+    97	 * // }
+    98	 *
+    99	 * @description
+   100	 * Used by:
+   101	 * - Every REST method calls this before any operations
+   102	 * - Compilation happens once per scope (cached)
+   103	 *
+   104	 * Purpose:
+   105	 * - Separates computed fields from database fields
+   106	 * - Adds missing types to belongsTo relationships
+   107	 * - Auto-detects pivot tables for many-to-many
+   108	 * - Generates search schemas from field markers
+   109	 * - Validates getter/setter dependencies
+   110	 * - Provides hooks for schema enrichment
+   111	 * - Caches everything for performance
+   112	 *
+   113	 * Data flow:
+   114	 * 1. Extracts computed fields to separate object
+   115	 * 2. Adds type:'id' to belongsTo fields
+   116	 * 3. Detects pivot tables (2+ foreign keys, 40%+ of fields)
+   117	 * 4. Runs schema:enrich hook for plugins
+   118	 * 5. Creates json-rest-schema validation instance
+   119	 * 6. Generates searchSchema from search:true fields
+   120	 * 7. Runs searchSchema:enrich hook
+   121	 * 8. Extracts and topologically sorts getters/setters
+   122	 * 9. Caches all results in scope.vars.schemaInfo
+   123	 */
+   124	export async function compileSchemas (scope, deps) {
+   125	  // Extract scopeName from context
+   126	  const { context, runHooks } = deps
+   127	  const scopeName = context.scopeName
+   128	
+   129	  // Get raw schema
+   130	  const rawFields = scope.scopeOptions?.schema || {}
+   131	
+   132	  // Extract computed fields from schema and build enriched schema
+   133	  const computedFields = {}
+   134	  const enrichedFields = {}
+   135	
+   136	  for (const [fieldName, fieldDef] of Object.entries(rawFields)) {
+   137	    if (fieldDef.computed === true) {
+   138	      // Extract computed field - copy entire definition
+   139	      computedFields[fieldName] = { ...fieldDef }
+   140	
+   141	      // Validate computed field
+   142	      if (!fieldDef.type) {
+   143	        throw new Error(`Computed field '${fieldName}' in scope '${scopeName}' must have a type`)
+   144	      }
+   145	
+   146	      if (fieldDef.compute && typeof fieldDef.compute !== 'function') {
+   147	        throw new Error(`Computed field '${fieldName}' in scope '${scopeName}' has invalid compute function`)
+   148	      }
+   149	
+   150	      // Don't include computed fields in the validation schema
+   151	    } else {
+   152	      enrichedFields[fieldName] = { ...fieldDef }
+   153	    }
+   154	  }
+   155	
+   156	  // Default enrichment: Add type to belongsTo fields
+   157	  for (const [fieldName, fieldDef] of Object.entries(enrichedFields)) {
+   158	    if (fieldDef.belongsTo && !fieldDef.type) {
+   159	      fieldDef.type = 'id'
+   160	    }
+   161	  }
+   162	
+   163	  // ADD LOGIC TO MAKE FIELDS SEARCHABLE HERE
+   164	  // Auto-detect pivot tables and make their foreign key fields searchable
+   165	  // This is critical for many-to-many relationship operations which need to filter pivot records
+   166	  const fields = Object.entries(enrichedFields)
+   167	  const belongsToFields = fields.filter(([_, def]) => def.belongsTo)
+   168	
+   169	  // If 2+ belongsTo fields and they make up 40%+ of non-id fields, likely a pivot table
+   170	  const nonIdFields = fields.filter(([name, _]) => name !== 'id')
+   171	  const isProbablyPivot = belongsToFields.length >= 2 &&
+   172	    (nonIdFields.length === 0 || belongsToFields.length / nonIdFields.length >= 0.4)
+   173	
+   174	  if (isProbablyPivot) {
+   175	    // Make all belongsTo fields searchable for pivot operations
+   176	    for (const [fieldName, fieldDef] of belongsToFields) {
+   177	      if (!fieldDef.search) {
+   178	        fieldDef.search = true
+   179	      }
+   180	    }
+   181	  }
+   182	
+   183	  // Hook: schema:enrich
+   184	  const schemaContext = {
+   185	    fields: enrichedFields,    // Mutable
+   186	    originalFields: rawFields,  // Read-only
+   187	    scopeName,
+   188	    scopeOptions: scope.scopeOptions || {}
+   189	  }
+   190	  await runHooks('schema:enrich', schemaContext)
+   191	
+   192	  // Create schema object
+   193	  const schemaObject = createSchema(schemaContext.fields)
+   194	
+   195	  // Generate searchSchema by merging explicit searchSchema with fields marked search:true.
+   196	  // This allows two ways to define searchable fields: either mark fields with search:true
+   197	  // in the main schema, or provide an explicit searchSchema with more control over filtering.
+   198	  // The explicit searchSchema takes precedence when there are conflicts - it can override
+   199	  // fields marked with search:true. Fields with search:true that are NOT in the explicit
+   200	  // searchSchema will be added automatically.
+   201	  // Example: title: {search: true} auto-generates a searchable field with sensible defaults,
+   202	  // while searchSchema can specify filterOperator: 'contains' or complex join configurations.
+   203	  const rawSearchFields = generateSearchSchemaFromSchema(
+   204	    schemaContext.fields,
+   205	    scope.scopeOptions.searchSchema
+   206	  )
+   207	
+   208	  if (rawSearchFields) {
+   209	    // Mark all search fields as indexed for database optimization.
+   210	    // This ensures that any field used for filtering will have a database index created,
+   211	    // dramatically improving query performance. Without indexes, filtering large tables
+   212	    // would require full table scans. The storage plugin uses these hints to create indexes.
+   213	    // Example: A status field marked for search gets indexed: true, enabling efficient
+   214	    // WHERE status = 'published' queries that can use index lookups instead of scanning all rows.
+   215	    ensureSearchFieldsAreIndexed(rawSearchFields)
+   216	
+   217	    // Hook: searchSchema:enrich
+   218	    const searchSchemaContext = {
+   219	      fields: schemaContext.fields,       // Mutable
+   220	      originalFields: rawSearchFields,    // Read-only enriched schema
+   221	      scopeName
+   222	    }
+   223	    await runHooks('searchSchema:enrich', searchSchemaContext)
+   224	
+   225	    // Create searchSchema object
+   226	    var searchSchemaObject = createSchema(rawSearchFields)
+   227	  } else {
+   228	    var searchSchemaObject = createSchema({})
+   229	  }
+   230	
+   231	  // Build schemaRelationships including polymorphic fields from schema
+   232	  const schemaRelationships = { ...(scope.scopeOptions.relationships || {}) }
+   233	
+   234	  // Validate belongsTo fields
+   235	  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
+   236	    // Validate that belongsTo fields have 'as' property
+   237	    if (fieldDef.belongsTo && !fieldDef.as) {
+   238	      throw new Error(
+   239	        `Field '${fieldName}' in resource '${scopeName}' has belongsTo: '${fieldDef.belongsTo}' but is missing the required 'as' property. ` +
+   240	        'The \'as\' property defines the relationship name used in JSON:API payloads. ' +
+   241	        `Example: ${fieldName}: { type: 'number', belongsTo: '${fieldDef.belongsTo}', as: '${fieldName.replace(/_id$/, '')}' }`
+   242	      )
+   243	    }
+   244	  }
+   245	
+   246	  // Extract and validate getter definitions
+   247	  const fieldGetters = {}
+   248	  const getterFields = []
+   249	
+   250	  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
+   251	    if (fieldDef.getter && typeof fieldDef.getter === 'function') {
+   252	      fieldGetters[fieldName] = {
+   253	        getter: fieldDef.getter,
+   254	        runGetterAfter: fieldDef.runGetterAfter || [],
+   255	        fieldDef
+   256	      }
+   257	      getterFields.push(fieldName)
+   258	
+   259	      // Validate dependencies exist
+   260	      if (fieldDef.runGetterAfter && Array.isArray(fieldDef.runGetterAfter)) {
+   261	        for (const dep of fieldDef.runGetterAfter) {
+   262	          if (!schemaContext.fields[dep]) {
+   263	            throw new Error(
+   264	              `Field '${fieldName}' in resource '${scopeName}' has getter dependency '${dep}' that does not exist in schema`
+   265	            )
+   266	          }
+   267	        }
+   268	      }
+   269	    }
+   270	  }
+   271	
+   272	  // Sort getters by dependencies
+   273	  let sortedGetterFields = []
+   274	  if (Object.keys(fieldGetters).length > 0) {
+   275	    try {
+   276	      sortedGetterFields = sortFieldsByDependencies(fieldGetters, 'runGetterAfter')
+   277	    } catch (error) {
+   278	      throw new Error(`Invalid getter dependencies in ${scopeName}: ${error.message}`)
+   279	    }
+   280	  }
+   281	
+   282	  // Extract and validate setter definitions
+   283	  const fieldSetters = {}
+   284	  const setterFields = []
+   285	
+   286	  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
+   287	    if (fieldDef.setter && typeof fieldDef.setter === 'function') {
+   288	      fieldSetters[fieldName] = {
+   289	        setter: fieldDef.setter,
+   290	        runSetterAfter: fieldDef.runSetterAfter || [],
+   291	        fieldDef
+   292	      }
+   293	      setterFields.push(fieldName)
+   294	
+   295	      // Validate dependencies exist
+   296	      if (fieldDef.runSetterAfter && Array.isArray(fieldDef.runSetterAfter)) {
+   297	        for (const dep of fieldDef.runSetterAfter) {
+   298	          if (!schemaContext.fields[dep]) {
+   299	            throw new Error(
+   300	              `Field '${fieldName}' in resource '${scopeName}' has setter dependency '${dep}' that does not exist in schema`
+   301	            )
+   302	          }
+   303	        }
+   304	      }
+   305	    }
+   306	  }
+   307	
+   308	  // Sort setters by dependencies
+   309	  let sortedSetterFields = []
+   310	  if (Object.keys(fieldSetters).length > 0) {
+   311	    try {
+   312	      sortedSetterFields = sortFieldsByDependencies(fieldSetters, 'runSetterAfter')
+   313	    } catch (error) {
+   314	      throw new Error(`Invalid setter dependencies in ${scopeName}: ${error.message}`)
+   315	    }
+   316	  }
+   317	
+   318	  // Cache everything
+   319	  scope.vars.schemaInfo = {
+   320	
+   321	    schemaInstance: schemaObject,
+   322	    schemaStructure: schemaObject.structure,
+   323	
+   324	    searchSchemaInstance: searchSchemaObject,
+   325	    searchSchemaStructure: searchSchemaObject.structure,
+   326	
+   327	    computed: computedFields,
+   328	    schemaRelationships,
+   329	    tableName: scope.scopeOptions.tableName || scopeName,
+   330	    idProperty: scope.scopeOptions.idProperty || scope.vars.idProperty,
+   331	    fieldGetters,
+   332	    sortedGetterFields,
+   333	    fieldSetters,
+   334	    sortedSetterFields
+   335	  }
+   336	}

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__querying-writing__connectors-query-parser.js.txt

@@ -0,0 +1,165 @@
+     1	/**
+     2	 * Parses URL query strings into JSON:API compliant parameter objects
+     3	 *
+     4	 * @param {string} queryString - The query string part of URL (without ?)
+     5	 * @returns {object} Parsed query parameters in JSON:API format
+     6	 *
+     7	 * @example
+     8	 * // Input: Basic include and sort
+     9	 * const query = parseJsonApiQuery('include=author&sort=-created_at');
+    10	 *
+    11	 * // Output: Parsed into arrays
+    12	 * // {
+    13	 * //   include: ['author'],      // Split by comma
+    14	 * //   fields: {},
+    15	 * //   filters: {},
+    16	 * //   sort: ['-created_at'],    // Split by comma
+    17	 * //   page: {}
+    18	 * // }
+    19	 *
+    20	 * @example
+    21	 * // Input: Filters with bracket notation
+    22	 * const query = parseJsonApiQuery('filter[status]=published&filter[author_id]=123');
+    23	 *
+    24	 * // Output: Extracted filter keys
+    25	 * // {
+    26	 * //   include: [],
+    27	 * //   fields: {},
+    28	 * //   filters: {
+    29	 * //     status: 'published',   // filter[status] → filters.status
+    30	 * //     author_id: '123'       // Values kept as strings
+    31	 * //   },
+    32	 * //   sort: [],
+    33	 * //   page: {}
+    34	 * // }
+    35	 *
+    36	 * @example
+    37	 * // Input: Sparse fieldsets
+    38	 * const query = parseJsonApiQuery('fields[articles]=title,body&fields[users]=name');
+    39	 *
+    40	 * // Output: Fields kept as comma-separated strings
+    41	 * // {
+    42	 * //   include: [],
+    43	 * //   fields: {
+    44	 * //     articles: 'title,body',  // NOT split into array
+    45	 * //     users: 'name'            // Validation expects strings
+    46	 * //   },
+    47	 * //   filters: {},
+    48	 * //   sort: [],
+    49	 * //   page: {}
+    50	 * // }
+    51	 *
+    52	 * @example
+    53	 * // Input: Pagination with numeric conversion
+    54	 * const query = parseJsonApiQuery('page[size]=20&page[number]=3&page[cursor]=abc123');
+    55	 *
+    56	 * // Output: Numbers converted, strings preserved
+    57	 * // {
+    58	 * //   include: [],
+    59	 * //   fields: {},
+    60	 * //   filters: {},
+    61	 * //   sort: [],
+    62	 * //   page: {
+    63	 * //     size: 20,        // "20" → 20 (numeric)
+    64	 * //     number: 3,       // "3" → 3 (numeric)
+    65	 * //     cursor: 'abc123' // Non-numeric stays string
+    66	 * //   }
+    67	 * // }
+    68	 *
+    69	 * @example
+    70	 * // Input: Complex real-world query
+    71	 * const query = parseJsonApiQuery(
+    72	 *   'include=author,comments.user&' +
+    73	 *   'filter[status]=published&' +
+    74	 *   'filter[created_after]=2024-01-01&' +
+    75	 *   'fields[articles]=title,summary&' +
+    76	 *   'sort=-created_at,title&' +
+    77	 *   'page[size]=10'
+    78	 * );
+    79	 *
+    80	 * // Output: All parameters properly categorized
+    81	 * // {
+    82	 * //   include: ['author', 'comments.user'],
+    83	 * //   fields: { articles: 'title,summary' },
+    84	 * //   filters: {
+    85	 * //     status: 'published',
+    86	 * //     created_after: '2024-01-01'
+    87	 * //   },
+    88	 * //   sort: ['-created_at', 'title'],
+    89	 * //   page: { size: 10 }
+    90	 * // }
+    91	 *
+    92	 * @description
+    93	 * Used by:
+    94	 * - express-plugin parses req.query with this
+    95	 * - http-plugin parses URL query strings with this
+    96	 * - websocket-plugin parses message query parameters with this
+    97	 *
+    98	 * Purpose:
+    99	 * - Provides uniform JSON:API query parsing across all transports
+   100	 * - Handles bracket notation without regex complexity
+   101	 * - Converts data types appropriately (numbers for pagination)
+   102	 * - Ignores non-JSON:API parameters gracefully
+   103	 * - Returns consistent structure even for empty input
+   104	 *
+   105	 * Data flow:
+   106	 * 1. Uses URLSearchParams for reliable parsing
+   107	 * 2. Categorizes parameters by their prefix pattern
+   108	 * 3. Extracts bracketed keys (filter[x] → x)
+   109	 * 4. Splits comma-separated values for include/sort
+   110	 * 5. Converts numeric strings for pagination
+   111	 * 6. Returns normalized structure for REST API
+   112	 */
+   113	export function parseJsonApiQuery (queryString) {
+   114	  if (!queryString) {
+   115	    return {
+   116	      include: [],
+   117	      fields: {},
+   118	      filters: {},
+   119	      sort: [],
+   120	      page: {}
+   121	    }
+   122	  }
+   123	
+   124	  const params = new URLSearchParams(queryString)
+   125	  const result = {
+   126	    include: [],
+   127	    fields: {},
+   128	    filters: {},
+   129	    sort: [],
+   130	    page: {}
+   131	  }
+   132	
+   133	  for (const [key, value] of params) {
+   134	    if (key === 'include') {
+   135	      // Parse include (comma-separated string to array)
+   136	      result.include = value.split(',').map(s => s.trim()).filter(s => s.length > 0)
+   137	    } else if (key === 'sort') {
+   138	      // Parse sort (comma-separated string to array)
+   139	      result.sort = value.split(',').map(s => s.trim()).filter(s => s.length > 0)
+   140	    } else if (key.startsWith('filter[') && key.endsWith(']')) {
+   141	      // Parse filter[key] = value into filters: { key: value }
+   142	      const filterKey = key.slice(7, -1) // Remove 'filter[' and ']'
+   143	      if (filterKey) {
+   144	        result.filters[filterKey] = value
+   145	      }
+   146	    } else if (key.startsWith('fields[') && key.endsWith(']')) {
+   147	      // Parse fields[type] = fields into fields: { type: "field1,field2" }
+   148	      // Keep as comma-separated string to match REST API validation expectations
+   149	      const fieldType = key.slice(7, -1) // Remove 'fields[' and ']'
+   150	      if (fieldType) {
+   151	        result.fields[fieldType] = value
+   152	      }
+   153	    } else if (key.startsWith('page[') && key.endsWith(']')) {
+   154	      // Parse page[size] = 10 into page: { size: 10 }
+   155	      const pageKey = key.slice(5, -1) // Remove 'page[' and ']'
+   156	      if (pageKey) {
+   157	        // Convert to number if it's a valid number, otherwise keep as string
+   158	        result.page[pageKey] = isNaN(value) ? value : parseInt(value, 10)
+   159	      }
+   160	    }
+   161	    // Ignore other query parameters that don't match JSON:API patterns
+   162	  }
+   163	
+   164	  return result
+   165	}