json-rest-api 1.0.29 → 2.1.0

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

@@ -1,11 +1,40 @@
 import { createSchema } from 'json-rest-schema'
 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 }) => {
@@ -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,14 +142,14 @@ 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 })
   }
   // 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}Z`)
+    ? parsed.toISOString().replace(/\.\d{3}Z$/, `.${fraction.padEnd(3, '0')}Z`)
     : parsed.toISOString()
 }
 
@@ -134,16 +174,21 @@ 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
@@ -153,7 +198,7 @@ export function normalizeDateValue (value, type, {
   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,
@@ -163,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
@@ -205,10 +277,11 @@ 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(3))) {
+  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],
@@ -225,85 +298,57 @@ export function normalizeValueForDatabaseStorage (value, type, {
   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,
@@ -322,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') {
@@ -353,120 +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'
- * //     }
- * //   }]
- * // }
- *
- * @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' }
- *     }
- *   ]
- * };
+ * 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.
  *
- * // 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',
   simplified = false,
-  resourceType
+  resourceType,
+  fields
 } = {}) {
   if (!record || !scopes) {
     return record
   }
 
   if (simplified) {
-    return normalizeSimplifiedRecord(record, resourceType, scopes, { source })
+    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 || {}),
-        ...(scopes[entry.type]?.vars?.queryFields || {})
-      },
+      schemaInfo.outputFields,
       {
         resourceType: entry.type,
         source
@@ -494,6 +484,7 @@ export function normalizeRecordAttributes (record, scopes, {
     }
   }
 
+  if (fields) filterResponseFields(record, fields)
   return record
 }
 
@@ -503,16 +494,9 @@ function normalizeSimplifiedRecord (record, resourceType, scopes, options, visit
   const schemaInfo = scopes[resourceType]?.vars?.schemaInfo
   if (!schemaInfo) return record
 
-  const schema = { ...schemaInfo.schemaStructure, ...schemaInfo.computed, ...scopes[resourceType]?.vars?.queryFields }
-  const normalized = normalizeAttributes(record, schema, { ...options, resourceType })
+  const normalized = normalizeAttributes(record, schemaInfo.outputFields, { ...options, resourceType })
   visited.set(record, normalized)
-  const relationships = { ...schemaInfo.schemaRelationships }
-  for (const definition of Object.values(schema)) {
-    if (definition.as && (definition.belongsTo || definition.belongsToPolymorphic)) {
-      relationships[definition.as] = definition
-    }
-  }
-  for (const [name, definition] of Object.entries(relationships)) {
+  for (const [name, definition] of Object.entries(schemaInfo.outputRelationships || {})) {
     const normalizeRelated = (entry) => normalizeSimplifiedRecord(
       entry,
       definition.belongsToPolymorphic
@@ -528,5 +512,6 @@ function normalizeSimplifiedRecord (record, resourceType, scopes, options, visit
         : 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.')
   }
 }

package/plugins/core/lib/querying-writing/field-selection-types.d.ts

@@ -0,0 +1,43 @@
+import type { ResourceConversionSchema, StorageAdapter, StorageContext, StorageDatabase, StorageFieldDefinition, StorageQuery } from '../storage/storage-types.js'
+import type { CompiledQueryField, ProjectionRuntime } from './query-field-types.js'
+import type { Fieldsets } from './field-utils.js'
+
+export interface SelectionSchema extends Partial<ResourceConversionSchema> {
+  queryFields?: Record<string, CompiledQueryField>
+  outputRelationships?: Record<string, StorageFieldDefinition>
+  readDependencies?: Record<string, readonly string[]>
+}
+
+export interface SelectionScope {
+  vars?: { schemaInfo?: SelectionSchema }
+}
+
+export interface SelectionContext extends StorageContext {
+  scopeName: string
+  queryParams?: { fields?: Fieldsets; sort?: unknown }
+}
+
+export interface FieldSelection {
+  fieldsToSelect: string[]
+  queryFieldsToSelect: string[]
+  requestedFields: readonly string[] | null
+  computedDependencies: string[]
+  idProperty: 'id'
+}
+
+export interface SelectionQueryRequest {
+  query: StorageQuery
+  scope?: SelectionScope | null
+  fieldSelectionInfo?: Partial<FieldSelection> | null
+  tableName: string
+  useTablePrefix?: boolean
+  storageAdapter?: StorageAdapter | null
+  db?: StorageDatabase | null
+  context?: StorageContext | null
+  scopeName?: string
+}
+
+export interface SelectedQuery {
+  query: StorageQuery
+  queryFieldRuntimeByField: Map<string, ProjectionRuntime>
+}