json-rest-api 1.0.28 → 2.0.0

package/plugins/core/lib/querying-writing/database-value-normalizers.js

@@ -1,11 +1,40 @@
 import { createSchema } from 'json-rest-schema'
-import { RestApiTemporalDataError } from '../../../../lib/rest-api-errors.js'
+import { RestApiTemporalDataError, RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { filterResponseFields } from './field-utils.js'
+import { wrapUnexpectedError } from '../../../../lib/error-context.js'
+import { COMPUTED_DEPENDENCIES_KEY } from './knex-constants.js'
+import { getTemporalStorageCapabilities, SERIALIZATION_CAPABILITIES } from './database-capabilities.js'
 
 const DATE_VALUE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
 const RFC3339_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/
-const SQL_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2}) ((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?)$/
+const SQL_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2}) ((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?)(?:([+-])([01]\d|2[0-3])(?::([0-5]\d))?(?::([0-5]\d))?)?( BC)?$/
 const INTEGER_VALUE_PATTERN = /^-?\d+$/
 const temporalContractCache = new Map()
+const CACHED_TEMPORAL_TYPES = new Set(['date', 'dateTime', 'time', 'epochMilliseconds', 'epochSeconds'])
+
+export function applyDatabaseReadOptions (query) {
+  const client = query.client.config.client
+  if (client === 'pg' || client === 'postgresql') {
+    const types = query.client.config.connection?.types || query.client.driver.types
+    query.options({
+      types: {
+        getTypeParser: (oid, format) => [1082, 1114, 1184].includes(oid) && format !== 'binary'
+          ? value => value
+          : types.getTypeParser(oid, format)
+      }
+    })
+  } else if (client === 'mysql' || client === 'mysql2') {
+    query.options({ dateStrings: true, supportBigNumbers: true })
+  }
+  return query
+}
+
+// SQLite's driver decodes INTEGER as Number. Preserve only values it cannot represent.
+// Keep this in SELECT/RETURNING expressions; predicates and ordering use native columns.
+export function databaseIdentityExpression (db, column) {
+  if (!['better-sqlite3', 'sqlite3'].includes(db.client.config.client)) return column
+  return db.raw("CASE WHEN typeof(??) = 'integer' AND (?? > 9007199254740991 OR ?? < -9007199254740991) THEN CAST(?? AS TEXT) ELSE ?? END", [column, column, column, column, column])
+}
 
 const limitFractionalSecondPrecision = (value, temporalPrecision) => {
   if (!Number.isInteger(temporalPrecision)) return value
@@ -21,15 +50,18 @@ const limitFractionalSecondPrecision = (value, temporalPrecision) => {
 
 const getTemporalContract = (type, temporalPrecision) => {
   const cacheKey = `${type}:${Number.isInteger(temporalPrecision) ? temporalPrecision : 'default'}`
-  if (!temporalContractCache.has(cacheKey)) {
-    temporalContractCache.set(cacheKey, createSchema({
-      value: {
-        type,
-        ...(Number.isInteger(temporalPrecision) ? { temporalPrecision } : {})
-      }
-    }))
-  }
-  return temporalContractCache.get(cacheKey)
+  // Cache common SQL precision; unusual declarations retain validation without permanent entries.
+  const cacheable = CACHED_TEMPORAL_TYPES.has(type) &&
+    (!Number.isInteger(temporalPrecision) || (temporalPrecision >= 0 && temporalPrecision <= 6))
+  if (cacheable && temporalContractCache.has(cacheKey)) return temporalContractCache.get(cacheKey)
+  const contract = createSchema({
+    value: {
+      type,
+      ...(Number.isInteger(temporalPrecision) ? { temporalPrecision } : {})
+    }
+  })
+  if (cacheable) temporalContractCache.set(cacheKey, contract)
+  return contract
 }
 
 const throwTemporalDataError = ({ fieldName, resourceType, type, source }) => {
@@ -71,12 +103,12 @@ const parseEpochDatabaseValue = (value) => {
 
 const parseKnownDatabaseDate = (value, { fieldName, resourceType, type, source }) => {
   if (value instanceof Date) {
-    if (!Number.isNaN(value.getTime())) return value
+    if (!Number.isNaN(value.getTime())) return value.toISOString()
     throwTemporalDataError({ fieldName, resourceType, type, source })
   }
 
   const epochDate = parseEpochDatabaseValue(value)
-  if (epochDate) return epochDate
+  if (epochDate) return epochDate.toISOString()
 
   if (typeof value !== 'string') {
     throwTemporalDataError({ fieldName, resourceType, type, source })
@@ -86,9 +118,17 @@ const parseKnownDatabaseDate = (value, { fieldName, resourceType, type, source }
   const sqlMatch = SQL_DATETIME_PATTERN.exec(trimmed)
   const rfc3339Match = RFC3339_DATETIME_PATTERN.exec(trimmed)
   let dateTimeValue = null
+  let offsetSeconds = 0
 
   if (sqlMatch) {
-    dateTimeValue = `${sqlMatch[1]}T${sqlMatch[2]}Z`
+    const date = sqlMatch[7] && sqlMatch[1].startsWith('0001-')
+      ? sqlMatch[1].replace(/^0001/, '0000')
+      : sqlMatch[1]
+    if (sqlMatch[7] && !sqlMatch[1].startsWith('0001-')) {
+      throwTemporalDataError({ fieldName, resourceType, type, source })
+    }
+    dateTimeValue = `${date}T${sqlMatch[2]}Z`
+    offsetSeconds = (Number(sqlMatch[4] || 0) * 3600 + Number(sqlMatch[5] || 0) * 60 + Number(sqlMatch[6] || 0)) * (sqlMatch[3] === '-' ? -1 : 1)
   } else if (rfc3339Match) {
     dateTimeValue = trimmed
   }
@@ -102,11 +142,15 @@ const parseKnownDatabaseDate = (value, { fieldName, resourceType, type, source }
     resourceType,
     source
   })
-  const parsed = new Date(dateTimeValue)
+  const parsed = new Date(new Date(dateTimeValue).getTime() - offsetSeconds * 1000)
   if (Number.isNaN(parsed.getTime())) {
     throwTemporalDataError({ fieldName, resourceType, type, source })
   }
-  return parsed
+  // Date handles the offset, but cannot retain digits beyond milliseconds.
+  const fraction = /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(dateTimeValue)?.[1]
+  return fraction
+    ? parsed.toISOString().replace(/\.\d{3}Z$/, `.${fraction.padEnd(3, '0')}Z`)
+    : parsed.toISOString()
 }
 
 /**
@@ -130,27 +174,31 @@ export function normalizeDateValue (value, type, {
     if (value instanceof Date && !Number.isNaN(value.getTime())) {
       timeValue = limitFractionalSecondPrecision(value.toISOString().slice(11, -1), temporalPrecision)
     }
-    return validateTemporalJsonValue(timeValue, type, {
+    const validated = validateTemporalJsonValue(timeValue, type, {
       temporalPrecision,
       fieldName,
       resourceType,
       source
     })
+    const [whole, fraction = ''] = validated.split('.')
+    const seconds = whole.length === 5 ? `${whole}:00` : whole
+    const digits = Number.isInteger(temporalPrecision) ? fraction.padEnd(temporalPrecision, '0') : fraction.replace(/0+$/, '')
+    return `${seconds}${digits ? `.${digits}` : ''}`
   }
 
-  if (type === 'date' && typeof value === 'string' && DATE_VALUE_PATTERN.test(value.trim())) {
-    return validateTemporalJsonValue(value.trim(), type, {
+  const dateValue = typeof value === 'string' ? value.trim().replace(/^0001-(\d{2}-\d{2}) BC$/, '0000-$1') : value
+  if (type === 'date' && typeof dateValue === 'string' && DATE_VALUE_PATTERN.test(dateValue)) {
+    return validateTemporalJsonValue(dateValue, type, {
       fieldName,
       resourceType,
       source
     })
   }
 
-  const dateValue = parseKnownDatabaseDate(value, { fieldName, resourceType, type, source })
-  const isoValue = dateValue.toISOString()
+  const isoValue = parseKnownDatabaseDate(value, { fieldName, resourceType, type, source })
   const normalized = type === 'date'
     ? isoValue.slice(0, 10)
-    : limitFractionalSecondPrecision(isoValue, temporalPrecision)
+    : limitFractionalSecondPrecision(isoValue.replace(/(\.\d{3}\d*?)0+Z$/, '$1Z'), temporalPrecision)
   return validateTemporalJsonValue(normalized, type, {
     temporalPrecision,
     fieldName,
@@ -160,30 +208,57 @@ export function normalizeDateValue (value, type, {
 }
 
 /**
- * Converts validated JSON temporal values to the native values expected by
+ * Converts structured JSON and temporal values to the values expected by
  * database drivers. JSON schema validation keeps date and dateTime values as
  * strings; database writes and comparisons must normalize them consistently.
  * Time values remain strings because database drivers accept their wire shape.
+ * @param {unknown} value
+ * @param {string | undefined} type
+ * @param {{ databaseClient?: string, textStorage?: boolean, temporalPrecision?: number, fieldName?: string, resourceType?: string, source?: string }} [options]
+ * @returns {unknown}
  */
 export function normalizeValueForDatabaseStorage (value, type, {
+  databaseClient,
+  textStorage = false,
   temporalPrecision,
   fieldName,
   resourceType,
   source = 'storage'
 } = {}) {
+  if (SERIALIZATION_CAPABILITIES.structuredTypes.includes(type)) {
+    const structured = normalizeStructuredValue(value, type, { fieldName, resourceType, source })
+    try {
+      return structured == null ? structured : JSON.stringify(structured)
+    } catch (error) {
+      throw wrapUnexpectedError(error, {
+        message: `Cannot serialize ${type} field '${[resourceType, fieldName].filter(Boolean).join('.')}' as JSON`,
+        context: { fieldName, resourceType, source, phase: 'serialization' }
+      })
+    }
+  }
   if (!['date', 'dateTime', 'time'].includes(type)) return value
   if (value === null || value === undefined) return null
+  const capabilities = getTemporalStorageCapabilities(databaseClient, { textStorage })
 
   if (type === 'time') {
     if (typeof value !== 'string') {
       throwTemporalDataError({ fieldName, resourceType, type, source })
     }
-    return validateTemporalJsonValue(value, type, {
+    const validated = validateTemporalJsonValue(value, type, {
       temporalPrecision,
       fieldName,
       resourceType,
       source
     })
+    const normalized = normalizeDateValue(validated, type, { temporalPrecision, fieldName, resourceType, source })
+    if (capabilities.timeFractionDigits !== null && (normalized.split('.')[1]?.length || 0) > capabilities.timeFractionDigits) {
+      const field = fieldName ? `data.attributes.${fieldName}` : 'value'
+      throw new RestApiValidationError('SQL time storage supports at most six fractional digits.', {
+        fields: [field],
+        violations: [{ field, rule: 'storage_precision', message: 'Use a text storage mapping for finer time precision.' }]
+      })
+    }
+    return normalized
   }
 
   let publicValue = value
@@ -202,91 +277,78 @@ export function normalizeValueForDatabaseStorage (value, type, {
     resourceType,
     source
   })
+  if (type === 'date' && textStorage) return validatedValue
+  const fraction = type === 'dateTime'
+    ? /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(validatedValue)?.[1]
+    : null
+  if (fraction && /[1-9]/.test(fraction.slice(capabilities.dateTimeFractionDigits))) {
+    const field = fieldName ? `data.attributes.${fieldName}` : 'value'
+    throw new RestApiValidationError('Built-in dateTime storage supports millisecond precision.', {
+      fields: [field],
+      violations: [{
+        field,
+        rule: 'storage_precision',
+        message: 'Submillisecond values require a custom storage serializer.'
+      }]
+    })
+  }
   const databaseValue = new Date(
     type === 'date' ? `${validatedValue}T00:00:00Z` : validatedValue
   )
   if (Number.isNaN(databaseValue.getTime())) {
     throwTemporalDataError({ fieldName, resourceType, type, source })
   }
+  if (databaseValue.getUTCFullYear() < 0 || databaseValue.getUTCFullYear() > capabilities.maxYear) {
+    const field = fieldName ? `data.attributes.${fieldName}` : 'value'
+    throw new RestApiValidationError('UTC dateTime must remain within years 0000 through 9999.', {
+      fields: [field],
+      violations: [{ field, rule: 'storage_range', message: 'The timezone offset moves this value outside the public dateTime range.' }]
+    })
+  }
+  if (databaseClient === 'pg' || databaseClient === 'postgresql') {
+    const iso = databaseValue.toISOString()
+    const sqlValue = type === 'date' ? iso.slice(0, 10) : iso.replace('T', ' ')
+    return sqlValue.startsWith('0000-') ? `${sqlValue.replace(/^0000/, '0001')} BC` : sqlValue
+  }
+  if (databaseClient === 'mysql' || databaseClient === 'mysql2') {
+    if (databaseValue.getUTCFullYear() < (type === 'date' ? capabilities.dateMinYear : capabilities.dateTimeMinYear)) {
+      const field = fieldName ? `data.attributes.${fieldName}` : 'value'
+      throw new RestApiValidationError('MySQL date storage supports years 1000 through 9999.', {
+        fields: [field],
+        violations: [{ field, rule: 'storage_range', message: 'Use a custom storage mapping for dates outside the MySQL date range.' }]
+      })
+    }
+    const iso = databaseValue.toISOString()
+    return type === 'date' ? iso.slice(0, 10) : iso.replace('T', ' ').replace(/Z$/, '')
+  }
   return databaseValue
 }
 
+export function normalizeStructuredValue (value, type, { fieldName, resourceType, source = 'database' } = {}) {
+  if (value === null || value === undefined) return value
+  try {
+    // Writes receive logical values; only reads decode a driver's JSON text.
+    const parsed = source !== 'storage' && typeof value === 'string' ? JSON.parse(value) : value
+    const valid = type === 'array'
+      ? Array.isArray(parsed)
+      : parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) &&
+        [Object.prototype, null].includes(Object.getPrototypeOf(parsed))
+    if (!valid) throw new TypeError(`Expected a JSON ${type}`)
+    return parsed
+  } catch (error) {
+    throw wrapUnexpectedError(error, {
+      message: `Invalid ${source} value for ${type} field '${[resourceType, fieldName].filter(Boolean).join('.')}'`,
+      context: { fieldName, resourceType, source, phase: 'normalization' }
+    })
+  }
+}
+
 /**
  * Normalizes database values in an attributes object
  *
  * @param {Object} attributes - The attributes object to normalize
  * @param {Object} schemaStructure - The schema structure defining field types
  * @returns {Object} The normalized attributes object
- *
- * @example
- * // Input: Raw database values
- * const attributes = {
- *   id: 1,
- *   is_active: 1,              // Boolean as 0/1
- *   created_at: '2024-01-15 10:30:00',  // MySQL datetime
- *   birth_date: '1990-05-20',           // Date string
- *   shift_time: '09:00:00'              // Time string
- * };
- *
- * const schema = {
- *   is_active: { type: 'boolean' },
- *   created_at: { type: 'dateTime' },
- *   birth_date: { type: 'date' },
- *   shift_time: { type: 'time' }
- * };
- *
- * const normalized = normalizeAttributes(attributes, schema);
- *
- * // Output: JSON-safe values
- * // {
- * //   id: 1,
- * //   is_active: true,                    // 1 → true
- * //   created_at: '2024-01-15T10:30:00.000Z',
- * //   birth_date: '1990-05-20',
- * //   shift_time: '09:00:00'
- * // }
- *
- * @example
- * // Input: Boolean edge cases
- * const attributes = {
- *   flag1: 0,      // Number 0
- *   flag2: '1',    // String '1'
- *   flag3: true,   // Already boolean
- *   flag4: null    // Null value
- * };
- *
- * const normalized = normalizeAttributes(attributes, {
- *   flag1: { type: 'boolean' },
- *   flag2: { type: 'boolean' },
- *   flag3: { type: 'boolean' },
- *   flag4: { type: 'boolean' }
- * });
- *
- * // Output:
- * // {
- * //   flag1: false,  // 0 → false
- * //   flag2: true,   // '1' → true
- * //   flag3: true,   // unchanged
- * //   flag4: null    // null preserved
- * // }
- *
- * @description
- * Used by:
- * - normalizeRecordAttributes for each record's attributes
- * - Applied after fetching data from database
- *
- * Purpose:
- * - Handles databases without native boolean support (SQLite, older MySQL)
- * - Normalizes date formats from different databases
- * - Ensures consistent data types in API responses
- * - Preserves null values appropriately
- *
- * Data flow:
- * 1. Creates copy of attributes to avoid mutation
- * 2. Iterates through each field with schema definition
- * 3. Normalizes booleans: 1/0 or '1'/'0' to true/false
- * 4. Normalizes dates using normalizeDateValue
- * 5. Returns new object with normalized values
  */
 export function normalizeAttributes (attributes, schemaStructure, {
   resourceType,
@@ -305,6 +367,25 @@ export function normalizeAttributes (attributes, schemaStructure, {
     // Skip if no field definition found
     if (!fieldDef) continue
 
+    if (['object', 'array'].includes(fieldDef.type)) {
+      // A custom getter owns decoding its stored representation.
+      if (source === 'database' && typeof fieldDef.getter === 'function') continue
+      normalized[fieldName] = normalizeStructuredValue(value, fieldDef.type, { fieldName, resourceType, source })
+      continue
+    }
+
+    if (fieldDef.type === 'file' && value instanceof Uint8Array) {
+      if (source === 'database' && typeof fieldDef.getter === 'function') continue
+      try {
+        normalized[fieldName] = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(value)
+      } catch (error) {
+        throw wrapUnexpectedError(error, {
+          message: `Invalid ${source} file handle '${[resourceType, fieldName].filter(Boolean).join('.')}'`,
+          context: { fieldName, resourceType, source, phase: 'normalization' }
+        })
+      }
+    }
+
     // Normalize boolean values
     if (fieldDef.type === 'boolean') {
       if (value === 1 || value === '1') {
@@ -323,6 +404,12 @@ export function normalizeAttributes (attributes, schemaStructure, {
         resourceType,
         source
       })
+    } else if (['epochMilliseconds', 'epochSeconds'].includes(fieldDef.type) && value != null) {
+      normalized[fieldName] = validateTemporalJsonValue(
+        typeof value === 'bigint' ? String(value) : value,
+        fieldDef.type,
+        { fieldName, resourceType, source }
+      )
     }
   }
 
@@ -330,111 +417,46 @@ export function normalizeAttributes (attributes, schemaStructure, {
 }
 
 /**
- * Normalizes all records in a JSON:API response
- *
- * @param {Object} record - The JSON:API response object
- * @param {Object} scopes - All available scopes for schema lookup
- * @returns {Object} The response with normalized values
- *
- * @example
- * // Input: JSON:API response with various data types
- * const response = {
- *   data: {
- *     type: 'articles',
- *     id: '1',
- *     attributes: {
- *       title: 'My Article',
- *       is_published: 1,                    // Boolean as number
- *       published_at: '2024-01-15 10:00:00' // MySQL datetime
- *     }
- *   },
- *   included: [{
- *     type: 'users',
- *     id: '10',
- *     attributes: {
- *       name: 'John',
- *       is_admin: 0,         // Boolean as number
- *       last_login: '2024-01-14 15:30:00'
- *     }
- *   }]
- * };
- *
- * const normalized = normalizeRecordAttributes(response, scopes);
- *
- * // Output: All booleans and dates normalized
- * // {
- * //   data: {
- * //     type: 'articles',
- * //     id: '1',
- * //     attributes: {
- * //       title: 'My Article',
- * //       is_published: true,
- * //       published_at: '2024-01-15T10:00:00.000Z'
- * //     }
- * //   },
- * //   included: [{
- * //     type: 'users',
- * //     id: '10',
- * //     attributes: {
- * //       name: 'John',
- * //       is_admin: false,
- * //       last_login: '2024-01-14T15:30:00.000Z'
- * //     }
- * //   }]
- * // }
+ * Normalize a JSON:API document or one plain resource using compiled output fields.
+ * JSON:API primary/included attributes are replaced on the supplied document;
+ * plain resources are copied recursively with shared/cyclic identities tracked.
+ * The source distinguishes database conversion from final-response validation.
+ * Final response normalization removes internal enrichment metadata and reapplies
+ * the supplied fieldset so dependency-only values do not escape in output.
  *
- * @example
- * // Input: Collection response (array of records)
- * const response = {
- *   data: [
- *     {
- *       type: 'comments',
- *       id: '1',
- *       attributes: { approved: 1, created_at: '2024-01-01 09:00:00' }
- *     },
- *     {
- *       type: 'comments',
- *       id: '2',
- *       attributes: { approved: 0, created_at: '2024-01-02 10:00:00' }
- *     }
- *   ]
- * };
- *
- * // Each record in the array is normalized
- *
- * @description
- * Used by:
- * - rest-api-knex-plugin after fetching data, before sending response
- * - Applied to both GET (single) and QUERY (collection) responses
- *
- * Purpose:
- * - Ensures consistent data types in API responses
- * - Handles both primary data and included resources
- * - Works with single records and collections
- * - Uses schema definitions to determine field types
- *
- * Data flow:
- * 1. Checks if data is array (collection) or object (single)
- * 2. For each record, looks up its schema by type
- * 3. Calls normalizeAttributes with schema structure
- * 4. Processes included array the same way
- * 5. Returns complete response with normalized values
+ * @template T
+ * @param {T} record - JSON:API document, or a plain resource in simplified mode
+ * @param {Object} scopes - Resource registry for schema lookup
+ * @param {Object} [options]
+ * @param {string} [options.source='database'] - Value origin for normalization
+ * @param {boolean} [options.simplified=false] - Internal plain-resource selector
+ * @param {string} [options.resourceType] - Required for plain-resource schema lookup
+ * @param {Object} [options.fields] - Selected fieldsets, if supplied
+ * @returns {T} Normalized document or plain resource
  */
-export function normalizeRecordAttributes (record, scopes, { source = 'database' } = {}) {
+export function normalizeRecordAttributes (record, scopes, {
+  source = 'database',
+  simplified = false,
+  resourceType,
+  fields
+} = {}) {
   if (!record || !scopes) {
     return record
   }
 
+  if (simplified) {
+    return normalizeSimplifiedRecord(record, resourceType, scopes, { source, fields })
+  }
+
   const normalizeEntry = (entry) => {
+    // Discard enrichment metadata after finish hooks have run.
+    if (source === 'response' && entry && typeof entry === 'object') delete entry[COMPUTED_DEPENDENCIES_KEY]
     const schemaInfo = scopes[entry?.type]?.vars?.schemaInfo
     if (!schemaInfo || !entry?.attributes) return
 
     entry.attributes = normalizeAttributes(
       entry.attributes,
-      {
-        ...(schemaInfo.schemaStructure || {}),
-        ...(schemaInfo.computed || {})
-      },
+      schemaInfo.outputFields,
       {
         resourceType: entry.type,
         source
@@ -462,5 +484,34 @@ export function normalizeRecordAttributes (record, scopes, { source = 'database'
     }
   }
 
+  if (fields) filterResponseFields(record, fields)
   return record
 }
+
+function normalizeSimplifiedRecord (record, resourceType, scopes, options, visited = new WeakMap()) {
+  if (!record || typeof record !== 'object') return record
+  if (visited.has(record)) return visited.get(record)
+  const schemaInfo = scopes[resourceType]?.vars?.schemaInfo
+  if (!schemaInfo) return record
+
+  const normalized = normalizeAttributes(record, schemaInfo.outputFields, { ...options, resourceType })
+  visited.set(record, normalized)
+  for (const [name, definition] of Object.entries(schemaInfo.outputRelationships || {})) {
+    const normalizeRelated = (entry) => normalizeSimplifiedRecord(
+      entry,
+      definition.belongsToPolymorphic
+        ? entry?._type
+        : definition.belongsTo || definition.target || name,
+      scopes,
+      options,
+      visited
+    )
+    if (Object.hasOwn(normalized, name)) {
+      normalized[name] = Array.isArray(normalized[name])
+        ? normalized[name].map(normalizeRelated)
+        : normalizeRelated(normalized[name])
+    }
+  }
+  if (options.fields) filterResponseFields(normalized, options.fields, { simplified: true, resourceType })
+  return normalized
+}

package/plugins/core/lib/querying-writing/default-data-helpers.js

@@ -1,72 +1,42 @@
+// @ts-check
+/** @import { DataWriteHelpers, DataReadHelpers } from '../storage/storage-types.js' */
 /**
- * Default data helper implementations that instruct users to install a storage plugin
- *
- * @description
- * These default implementations ensure the REST API plugin fails gracefully
- * when no storage plugin is installed. Each method throws a descriptive error
- * guiding users to install a storage implementation.
- *
- * @example
- * // When no storage plugin is installed:
- * try {
- *   await api.resources.articles.get({ id: 1 });
- * } catch (error) {
- *   console.log(error.message);
- *   // "No storage implementation for get. Install a storage plugin."
- * }
- *
- * @example
- * // After installing rest-api-knex-plugin:
- * api.use(RestApiKnexPlugin, { knex });
- * // Now data helpers are replaced with actual implementations
- * const article = await api.resources.articles.get({ id: 1 });
- * // Works! Returns article from database
- *
- * Used by:
- * - rest-api-plugin sets these as initial data helpers
- * - Storage plugins replace these with actual implementations
- *
- * Purpose:
- * - Provides clear error messages when storage is missing
- * - Ensures REST API plugin can be installed independently
- * - Allows storage plugins to be swapped without changing API
- *
- * Data flow:
- * 1. REST API plugin initializes with these defaults
- * 2. User tries to use API without storage plugin
- * 3. Clear error message guides them to install storage
- * 4. Storage plugin replaces these with real implementations
+ * Missing-storage placeholders installed by RestApiPlugin.
+ * Storage plugins replace these helpers. They are not a complete custom-backend
+ * interface: resource operations also require transaction and query integration.
+ * Earlier lifecycle validation may reject a call before one of these runs.
+ * @satisfies {DataWriteHelpers<never, never> & DataReadHelpers<never>}
  */
 export const defaultDataHelpers = {
-  dataExists: async function (scope, deps) {
+  dataExists: async function (request) {
     throw new Error('No storage implementation for exists. Install a storage plugin.')
   },
 
-  dataGet: async function (scope, deps) {
+  dataGet: async function (request) {
     throw new Error('No storage implementation for get. Install a storage plugin.')
   },
 
-  dataGetMinimal: async function (scope, deps) {
+  dataGetMinimal: async function (request) {
     throw new Error('No storage implementation for getMinimal. Install a storage plugin.')
   },
 
-  dataQuery: async function (scope, deps) {
+  dataQuery: async function (request) {
     throw new Error('No storage implementation for query. Install a storage plugin.')
   },
 
-  dataPost: async function (scope, deps) {
+  dataPost: async function (request) {
     throw new Error('No storage implementation for post. Install a storage plugin.')
   },
 
-  dataPatch: async function (scope, deps) {
+  dataPatch: async function (request) {
     throw new Error('No storage implementation for patch. Install a storage plugin.')
   },
 
-  dataPut: async function (scope, deps) {
+  dataPut: async function (request) {
     throw new Error('No storage implementation for put. Install a storage plugin.')
   },
 
-  dataDelete: async function (scope, deps) {
+  dataDelete: async function (request) {
     throw new Error('No storage implementation for delete. Install a storage plugin.')
   }
 }