json-rest-api 1.0.29 → 2.1.0

package/plugins/core/lib/querying-writing/connectors-query-parser.js

@@ -1,119 +1,19 @@
+import { rejectRemovedOptions } from './response-options.js'
+import { RestApiPayloadError } from '../../../../lib/rest-api-errors.js'
+
 /**
- * Parses URL query strings into JSON:API compliant parameter objects
- *
- * @param {string} queryString - The query string part of URL (without ?)
- * @returns {object} Parsed query parameters in JSON:API format
- *
- * @example
- * // Input: Basic include and sort
- * const query = parseJsonApiQuery('include=author&sort=-created_at');
- *
- * // Output: Parsed into arrays
- * // {
- * //   include: ['author'],      // Split by comma
- * //   fields: {},
- * //   filters: {},
- * //   sort: ['-created_at'],    // Split by comma
- * //   page: {}
- * // }
- *
- * @example
- * // Input: Filters with bracket notation
- * const query = parseJsonApiQuery('filter[status]=published&filter[author_id]=123');
- *
- * // Output: Extracted filter keys
- * // {
- * //   include: [],
- * //   fields: {},
- * //   filters: {
- * //     status: 'published',   // filter[status] → filters.status
- * //     author_id: '123'       // Values kept as strings
- * //   },
- * //   sort: [],
- * //   page: {}
- * // }
- *
- * @example
- * // Input: Sparse fieldsets
- * const query = parseJsonApiQuery('fields[articles]=title,body&fields[users]=name');
- *
- * // Output: Fields kept as comma-separated strings
- * // {
- * //   include: [],
- * //   fields: {
- * //     articles: 'title,body',  // NOT split into array
- * //     users: 'name'            // Validation expects strings
- * //   },
- * //   filters: {},
- * //   sort: [],
- * //   page: {}
- * // }
- *
- * @example
- * // Input: Pagination with numeric conversion
- * const query = parseJsonApiQuery('page[size]=20&page[number]=3&page[cursor]=abc123');
+ * Parse JSON:API query parameters independently of a framework's query parser.
+ * Ordinary filters and sparse fields retain strings; filter[field][json] carries
+ * an explicit JSON value. Only page size/number are otherwise
+ * converted to numbers; opaque cursors keep their exact spelling. Retired
+ * controls fail clearly. Repeated keys use the final value.
  *
- * // Output: Numbers converted, strings preserved
- * // {
- * //   include: [],
- * //   fields: {},
- * //   filters: {},
- * //   sort: [],
- * //   page: {
- * //     size: 20,        // "20" → 20 (numeric)
- * //     number: 3,       // "3" → 3 (numeric)
- * //     cursor: 'abc123' // Non-numeric stays string
- * //   }
- * // }
- *
- * @example
- * // Input: Complex real-world query
- * const query = parseJsonApiQuery(
- *   'include=author,comments.user&' +
- *   'filter[status]=published&' +
- *   'filter[created_after]=2024-01-01&' +
- *   'fields[articles]=title,summary&' +
- *   'sort=-created_at,title&' +
- *   'page[size]=10'
- * );
- *
- * // Output: All parameters properly categorized
- * // {
- * //   include: ['author', 'comments.user'],
- * //   fields: { articles: 'title,summary' },
- * //   filters: {
- * //     status: 'published',
- * //     created_after: '2024-01-01'
- * //   },
- * //   sort: ['-created_at', 'title'],
- * //   page: { size: 10 }
- * // }
- *
- * @description
- * Used by:
- * - express-plugin parses req.query with this
- * - http-plugin parses URL query strings with this
- * - websocket-plugin parses message query parameters with this
- *
- * Purpose:
- * - Provides uniform JSON:API query parsing across all transports
- * - Handles bracket notation without regex complexity
- * - Converts data types appropriately (numbers for pagination)
- * - Ignores non-JSON:API parameters gracefully
- * - Returns consistent structure even for empty input
- *
- * Data flow:
- * 1. Uses URLSearchParams for reliable parsing
- * 2. Categorizes parameters by their prefix pattern
- * 3. Extracts bracketed keys (filter[x] → x)
- * 4. Splits comma-separated values for include/sort
- * 5. Converts numeric strings for pagination
- * 6. Returns normalized structure for REST API
+ * @param {string} queryString - Query string without the leading question mark
+ * @returns {object} Include/sort arrays and fields/filters/page maps
  */
 export function parseJsonApiQuery (queryString) {
   if (!queryString) {
     return {
-      include: [],
       fields: {},
       filters: {},
       sort: [],
@@ -122,8 +22,8 @@ export function parseJsonApiQuery (queryString) {
   }
 
   const params = new URLSearchParams(queryString)
+  rejectRemovedOptions(Object.fromEntries(params))
   const result = {
-    include: [],
     fields: {},
     filters: {},
     sort: [],
@@ -131,6 +31,15 @@ export function parseJsonApiQuery (queryString) {
   }
 
   for (const [key, value] of params) {
+    const jsonFilter = key.match(/^filter\[(.+)\]\[json\]$/)
+    if (jsonFilter) {
+      let parsed
+      try { parsed = JSON.parse(value) } catch {
+        throw new RestApiPayloadError(`Invalid JSON value for query parameter '${key}'`, { parameter: key, expected: 'valid JSON' })
+      }
+      Object.defineProperty(result.filters, jsonFilter[1], { value: parsed, enumerable: true, writable: true, configurable: true })
+      continue
+    }
     if (key === 'include') {
       // Parse include (comma-separated string to array)
       result.include = value.split(',').map(s => s.trim()).filter(s => s.length > 0)
@@ -141,21 +50,22 @@ export function parseJsonApiQuery (queryString) {
       // Parse filter[key] = value into filters: { key: value }
       const filterKey = key.slice(7, -1) // Remove 'filter[' and ']'
       if (filterKey) {
-        result.filters[filterKey] = value
+        Object.defineProperty(result.filters, filterKey, { value, enumerable: true, writable: true, configurable: true })
       }
     } else if (key.startsWith('fields[') && key.endsWith(']')) {
       // Parse fields[type] = fields into fields: { type: "field1,field2" }
       // Keep as comma-separated string to match REST API validation expectations
       const fieldType = key.slice(7, -1) // Remove 'fields[' and ']'
       if (fieldType) {
-        result.fields[fieldType] = value
+        Object.defineProperty(result.fields, fieldType, { value, enumerable: true, writable: true, configurable: true })
       }
     } else if (key.startsWith('page[') && key.endsWith(']')) {
       // Parse page[size] = 10 into page: { size: 10 }
       const pageKey = key.slice(5, -1) // Remove 'page[' and ']'
       if (pageKey) {
-        // Convert to number if it's a valid number, otherwise keep as string
-        result.page[pageKey] = isNaN(value) ? value : parseInt(value, 10)
+        // Keep fractional values intact so the existing integer contract rejects them.
+        const parsed = ['size', 'number'].includes(pageKey) && value.trim() !== '' && !isNaN(value) ? Number(value) : value
+        Object.defineProperty(result.page, pageKey, { value: parsed, enumerable: true, writable: true, configurable: true })
       }
     }
     // Ignore other query parameters that don't match JSON:API patterns
@@ -177,12 +87,12 @@ const stringifyQueryValue = (value) => {
 }
 
 const appendCommaList = (params, key, value) => {
-  if (!hasSerializableValue(value)) return
+  if (!hasSerializableValue(value) && !(key === 'include' && Array.isArray(value))) return
   const serialized = Array.isArray(value)
     ? value.map(stringifyQueryValue).filter((entry) => entry.length > 0).join(',')
     : stringifyQueryValue(value)
 
-  if (serialized) {
+  if (serialized || key === 'include') {
     params.set(key, serialized)
   }
 }
@@ -191,7 +101,12 @@ const appendScopedParams = (params, publicName, values) => {
   if (!values || typeof values !== 'object' || Array.isArray(values)) return
 
   for (const [key, value] of Object.entries(values)) {
-    if (!key || !hasSerializableValue(value)) continue
+    if (!key || value === undefined) continue
+    if (publicName === 'filter' && (value === null || (typeof value === 'object' && !(value instanceof Date)))) {
+      params.set(`${publicName}[${key}][json]`, JSON.stringify(value))
+      continue
+    }
+    if (!hasSerializableValue(value)) continue
     params.set(`${publicName}[${key}]`, stringifyQueryValue(value))
   }
 }

package/plugins/core/lib/querying-writing/database-capabilities.js

@@ -1,23 +1,13 @@
+// @ts-check
+
+import { errorMessage } from '../../../../lib/error-context.js'
+import { formatDiagnosticValue } from '../../../../lib/error-formatter.js'
+
 /**
  * Parses database version string to comparable format
  *
  * @param {string} versionString - Raw version string from database
- * @returns {Object|null} Parsed version with major, minor, patch
- *
- * @example
- * // Input: MySQL version
- * parseVersion("8.0.33");
- * // Output: { major: 8, minor: 0, patch: 33 }
- *
- * @example
- * // Input: PostgreSQL version with extra info
- * parseVersion("14.5 (Ubuntu 14.5-1.pgdg20.04+1)");
- * // Output: { major: 14, minor: 5, patch: 0 }
- *
- * @example
- * // Input: MariaDB version
- * parseVersion("10.6.12-MariaDB");
- * // Output: { major: 10, minor: 6, patch: 12 }
+ * @returns {{major: number, minor: number, patch: number}|null} Parsed version
  */
 const parseVersion = (versionString) => {
   // MySQL: "8.0.33"
@@ -29,237 +19,173 @@ const parseVersion = (versionString) => {
   if (!match) return null
 
   return {
-    major: parseInt(match[1]),
-    minor: parseInt(match[2]),
-    patch: match[3] ? parseInt(match[3]) : 0
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: match[3] ? Number(match[3]) : 0
   }
 }
 
 /**
  * Checks if the database supports window functions based on version
  *
- * @param {Object} knex - Knex instance
+ * @param {import('../storage/storage-types.js').StorageDatabase} knex - Knex instance
+ * @param {{ version: string }} [databaseInfo] - Already fetched version
+ * @param {import('../storage/storage-types.js').CapabilityLogger} [log] - Configured diagnostic sink
  * @returns {Promise<boolean>} True if window functions are supported
- *
- * @example
- * // Input: MySQL 8.0.33
- * const supports = await supportsWindowFunctions(knex);
- * // Output: true (MySQL 8.0+ supports window functions)
- *
- * @example
- * // Input: MySQL 5.7.42
- * const supports = await supportsWindowFunctions(knex);
- * // Output: false (MySQL < 8.0 doesn't support window functions)
- *
- * @example
- * // Input: PostgreSQL (any modern version)
- * const supports = await supportsWindowFunctions(knex);
- * // Output: true (PostgreSQL 8.4+ supports window functions)
- *
- * @example
- * // Input: SQLite 3.24.0
- * const supports = await supportsWindowFunctions(knex);
- * // Output: false (SQLite needs 3.25.0+)
- *
- * @description
- * Used by:
- * - buildWindowedIncludeSubquery to validate before using window functions
- * - rest-api-knex-plugin to determine query strategies
- *
- * Purpose:
- * - Prevents runtime errors by checking feature support
- * - Enables fallback strategies for older databases
- * - Provides clear error messages about version requirements
- *
- * Data flow:
- * 1. Identifies database client type from Knex config
- * 2. For version-dependent databases, queries version string
- * 3. Parses version and compares against known thresholds
- * 4. Returns boolean indicating support
- * 5. Falls back to false if version can't be determined
- *
- * Version requirements:
- * - PostgreSQL: 8.4+ (all modern versions)
- * - MySQL: 8.0+
- * - MariaDB: 10.2+
- * - SQLite: 3.25.0+
- * - SQL Server: 2005+ (all versions)
- * - Oracle: Supported (long-standing feature)
  */
-export const supportsWindowFunctions = async (knex) => {
-  try {
-    const client = knex.client.config.client
-
-    let versionString
-
-    switch (client) {
-      case 'pg':
-      case 'postgresql':
-        // PostgreSQL 8.4+ supports window functions (all modern versions)
-        return true
+export const supportsWindowFunctions = async (knex, databaseInfo, log) => {
+  const client = knex.client.config.client
+  if (['pg', 'postgresql', 'mssql', 'oracledb'].includes(client)) return true
+  if (!['mysql', 'mysql2', 'sqlite3', 'better-sqlite3'].includes(client) && !client.includes('maria')) return false
+
+  const info = databaseInfo || await getDatabaseInfo(knex, log)
+  const parsed = typeof info.version === 'string' ? parseVersion(info.version) : null
+  if (!parsed) return false
+  if (['mysql', 'mysql2'].includes(client)) return parsed.major >= 8
+  if (client.includes('sqlite')) return parsed.major > 3 || (parsed.major === 3 && parsed.minor >= 25)
+  return info.version.toLowerCase().includes('mariadb') &&
+    (parsed.major > 10 || (parsed.major === 10 && parsed.minor >= 2))
+}
 
-      case 'mysql':
-      case 'mysql2':
-        try {
-          const row = await knex.first(knex.raw('VERSION() as version'))
-          const mysqlVersion = parseVersion(row.version)
+// Built-in rules; custom field declarations still undergo their own validation.
+/** @type {import('../storage/storage-types.js').SerializationCapabilities} */
+export const SERIALIZATION_CAPABILITIES = Object.freeze({
+  customSerializerResult: 'synchronous',
+  structuredTypes: Object.freeze(['object', 'array']),
+  structuredEncoding: 'json',
+  wholeDocumentPredicates: false
+})
+
+/** @type {import('../storage/storage-types.js').RelationshipCapabilities} */
+export const RELATIONSHIP_CAPABILITIES = Object.freeze({
+  attributeKinds: Object.freeze(['belongsTo', 'belongsToPolymorphic']),
+  declaredCardinalities: Object.freeze({ hasOne: 'one', hasMany: 'many', manyToMany: 'many' })
+})
 
-          return mysqlVersion && mysqlVersion.major >= 8
-        } catch (dbError) {
-          console.warn(`[supportsWindowFunctions] Failed to get MySQL version: ${dbError.message}`)
-          return false
-        }
+/**
+ * Both storage plugins share one version observation during initialization.
+ * @param {import('../storage/storage-types.js').StorageDatabase} knex
+ * @param {import('../storage/storage-types.js').CapabilityLogger} [log]
+ * @returns {Promise<import('../storage/storage-types.js').DatabaseCapabilities>}
+ */
+export const getDatabaseCapabilities = async (knex, log) => {
+  const dbInfo = await getDatabaseInfo(knex, log)
+  return {
+    dbInfo,
+    windowFunctions: await supportsWindowFunctions(knex, dbInfo),
+    insertResult: getInsertResultMode(knex.client.config.client),
+    serialization: SERIALIZATION_CAPABILITIES,
+    relationships: RELATIONSHIP_CAPABILITIES,
+    temporal: {
+      native: getTemporalStorageCapabilities(knex.client.config.client),
+      text: getTemporalStorageCapabilities(knex.client.config.client, { textStorage: true })
+    },
+    schema: getSchemaCapabilities(knex.client.config.client)
+  }
+}
 
-      case 'sqlite3':
-      case 'better-sqlite3':
-        try {
-          versionString = await knex.raw('SELECT sqlite_version() as version')
-          const sqliteVersion = versionString[0].version
-          // SQLite 3.25.0+ supports window functions
-          const parsed = parseVersion(sqliteVersion)
-          return parsed && (parsed.major > 3 || (parsed.major === 3 && parsed.minor >= 25))
-        } catch (dbError) {
-          console.warn(`[supportsWindowFunctions] Failed to get SQLite version: ${dbError.message}`)
-          return false
-        }
+/**
+ * @param {unknown} dialect
+ * @returns {import('../storage/storage-types.js').InsertResultMode}
+ */
+export const getInsertResultMode = dialect => {
+  const client = String(dialect || '').toLowerCase()
+  if (['mysql', 'mysql2'].includes(client)) return 'insert-id'
+  if (['pg', 'postgresql', 'sqlite3', 'better-sqlite3'].includes(client)) return 'rows'
+  return 'driver-defined'
+}
 
-      case 'mssql':
-        // SQL Server 2005+ supports window functions
-        return true
+/**
+ * Choose the query form; each caller must still validate its driver's result.
+ * @param {import('knex').Knex.QueryBuilder<import('../storage/storage-types.js').StorageRow, unknown>} query
+ * @param {string|string[]|Record<string, string|import('knex').Knex.Raw<unknown>>} columns
+ * @returns {import('knex').Knex.QueryBuilder<import('../storage/storage-types.js').StorageRow, unknown>}
+ */
+export const applyInsertReturning = (query, columns) => {
+  if (getInsertResultMode(query.client.config.client) === 'insert-id') return query
+  // Knex supports alias dictionaries at runtime; its declarations omit that overload.
+  const returning = /** @type {(columns: string|string[]|Record<string, string|import('knex').Knex.Raw<unknown>>) => typeof query} */ (query.returning)
+  return returning.call(query, columns)
+}
 
-      case 'oracledb':
-        // Oracle has supported window functions for a long time
-        return true
+/**
+ * Built-in value conversion limits; schemas/custom serializers may differ.
+ * @param {unknown} dialect
+ * @param {{textStorage?: boolean}} [options]
+ * @returns {import('../storage/storage-types.js').TemporalStorageCapabilities}
+ */
+export const getTemporalStorageCapabilities = (dialect, { textStorage = false } = {}) => {
+  const client = String(dialect || '').toLowerCase()
+  const mysql = ['mysql', 'mysql2'].includes(client)
+  return {
+    dateMinYear: !textStorage && mysql ? 1000 : 0,
+    dateTimeMinYear: mysql ? 1000 : 0,
+    maxYear: 9999,
+    dateTimeFractionDigits: 3,
+    timeFractionDigits: !textStorage && (mysql || ['pg', 'postgresql'].includes(client)) ? 6 : null
+  }
+}
 
-      default:
-        // For MariaDB, we need to check if it's actually MariaDB or MySQL
-        if (client.includes('maria')) {
-          try {
-            versionString = await knex.raw('SELECT VERSION() as version')
-            const version = versionString[0].version.toLowerCase()
-            if (version.includes('mariadb')) {
-              const mariaVersion = parseVersion(version)
-              // MariaDB 10.2+ supports window functions
-              return mariaVersion && (mariaVersion.major > 10 ||
-                (mariaVersion.major === 10 && mariaVersion.minor >= 2))
-            }
-          } catch (dbError) {
-            console.warn(`[supportsWindowFunctions] Failed to get MariaDB version: ${dbError.message}`)
-            return false
-          }
-        }
-        return false
-    }
-  } catch (error) {
-    // Log error with context
-    console.error('[supportsWindowFunctions] Unexpected error checking database capabilities:', {
-      error: error.message,
-      stack: error.stack,
-      client: knex?.client?.config?.client || 'unknown'
-    })
-    // If we can't determine, assume no support for safety
-    return false
+/**
+ * Describe the existing field-alteration runner, not all database DDL.
+ * @param {unknown} dialect
+ * @returns {import('../storage/storage-types.js').SchemaCapabilities}
+ */
+export const getSchemaCapabilities = dialect => {
+  const client = String(dialect || '').toLowerCase()
+  const mysql = /mysql/.test(client)
+  const sqlite = client.includes('sqlite')
+  const postgres = ['pg', 'postgresql'].includes(client)
+  return {
+    recognizedDialect: mysql || sqlite || postgres,
+    fieldAlteration: mysql ? 'standalone' : sqlite ? 'sqlite-rebuild' : 'transaction',
+    callerFieldAlteration: mysql ? 'forbidden' : sqlite ? 'foreign-keys-off' : 'savepoint',
+    temporalColumnFractionDigits: mysql || postgres ? 6 : null,
+    setValues: mysql
   }
 }
 
 /**
  * Gets database info for error messages and capability checks
  *
- * @param {Object} knex - Knex instance
- * @returns {Promise<Object>} Database info with client and version
- *
- * @example
- * // Input: MySQL connection
- * const info = await getDatabaseInfo(knex);
- * // Output: { client: 'MySQL', version: '8.0.33' }
- *
- * @example
- * // Input: PostgreSQL connection
- * const info = await getDatabaseInfo(knex);
- * // Output: {
- * //   client: 'PostgreSQL',
- * //   version: 'PostgreSQL 14.5 (Ubuntu 14.5-1.pgdg20.04+1)'
- * // }
- *
- * @example
- * // Input: Connection error case
- * const info = await getDatabaseInfo(knexWithError);
- * // Output: {
- * //   client: 'MySQL',
- * //   version: 'unknown',
- * //   error: 'Connection refused'
- * // }
- *
- * @description
- * Used by:
- * - Error messages to show which database/version lacks a feature
- * - Capability detection for feature flags
- * - Debugging connection issues
- *
- * Purpose:
- * - Provides human-readable database identification
- * - Helps users understand version requirements
- * - Enables detailed error messages
- * - Gracefully handles query failures
- *
- * Data flow:
- * 1. Identifies client type from Knex config
- * 2. Runs version query specific to each database
- * 3. Returns formatted info object
- * 4. Includes error details if version query fails
- * 5. Falls back to 'unknown' for unsupported databases
+ * @param {import('../storage/storage-types.js').StorageDatabase} knex - Knex instance
+ * @param {import('../storage/storage-types.js').CapabilityLogger} [log] - Configured diagnostic sink
+ * @returns {Promise<import('../storage/storage-types.js').DatabaseInfo>} Database info with client and version
  */
-export const getDatabaseInfo = async (knex) => {
+export const getDatabaseInfo = async (knex, log) => {
+  const client = knex.client.config.client
+  let name = client
+  if (['mysql', 'mysql2'].includes(client)) name = 'MySQL'
+  else if (['sqlite3', 'better-sqlite3'].includes(client)) name = 'SQLite'
+  else if (['pg', 'postgresql'].includes(client)) name = 'PostgreSQL'
   try {
-    const client = knex.client.config.client
-
-    let versionString
-    switch (client) {
-      case 'mysql':
-      case 'mysql2':
-        try {
-          const row = await knex.first(knex.raw('VERSION() as version'))
-          return { client: 'MySQL', version: row.version }
-        } catch (dbError) {
-          console.warn(`[getDatabaseInfo] Failed to get MySQL version: ${dbError.message}`)
-          return { client: 'MySQL', version: 'unknown', error: dbError.message }
-        }
-
-      case 'sqlite3':
-      case 'better-sqlite3':
-        try {
-          versionString = await knex.raw('SELECT sqlite_version() as version')
-          return { client: 'SQLite', version: versionString[0].version }
-        } catch (dbError) {
-          console.warn(`[getDatabaseInfo] Failed to get SQLite version: ${dbError.message}`)
-          return { client: 'SQLite', version: 'unknown', error: dbError.message }
-        }
-
-      case 'pg':
-      case 'postgresql':
-        try {
-          versionString = await knex.raw('SELECT version() as version')
-          return { client: 'PostgreSQL', version: versionString.rows[0].version }
-        } catch (dbError) {
-          console.warn(`[getDatabaseInfo] Failed to get PostgreSQL version: ${dbError.message}`)
-          return { client: 'PostgreSQL', version: 'unknown', error: dbError.message }
-        }
-
+    /** @type {unknown} */
+    let version
+    switch (name) {
+      case 'MySQL': {
+        const row = await knex.first(knex.raw('VERSION() as version'))
+        version = row && 'version' in row ? row.version : undefined
+        break
+      }
+      case 'SQLite':
+        version = (await knex.raw('SELECT sqlite_version() as version'))?.[0]?.version
+        break
+      case 'PostgreSQL':
+        version = (await knex.raw('SELECT version() as version'))?.rows?.[0]?.version
+        break
       default:
-        return { client, version: 'unknown' }
+        if (!client.includes('maria')) return { client: name, version: 'unknown' }
+        version = (await knex.raw('SELECT VERSION() as version'))?.[0]?.version
     }
+    if (typeof version !== 'string') throw new Error('Database version query did not return a string')
+    return { client: name, version }
   } catch (error) {
-    // Log unexpected errors
-    console.error('[getDatabaseInfo] Unexpected error getting database info:', {
-      error: error.message,
-      stack: error.stack,
-      client: knex?.client?.config?.client || 'unknown'
-    })
-
-    return {
-      client: knex?.client?.config?.client || 'unknown',
-      version: 'unknown',
-      error: error.message
-    }
+    // Capability observation is advisory; a failing diagnostic must not replace it.
+    try {
+      await log?.warn('Database version observation failed', formatDiagnosticValue({
+        operation: 'database-capabilities', phase: 'version-observation', backend: client, error
+      }))
+    } catch {}
+    return { client: name, version: 'unknown', error: errorMessage(error) }
   }
 }