json-rest-api 1.0.28 → 2.0.0

package/plugins/core/lib/storage/storage-adapter.js

@@ -1,20 +1,29 @@
+// @ts-check
 import {
-  getFieldValue as getLegacyFieldValue,
+  getFieldValue as getTableFieldValue,
   getIdColumn,
+  getStorageInfo,
   getStorageColumn,
   translateAttributesForStorage,
+  serializeFieldValueForStorage,
+  assertWritableKnexColumns,
 } from './storage-mapping.js'
 import {
   getCanonicalFieldValue,
   getCanonicalResourceIdColumn,
   translateCanonicalAttributesForStorage,
 } from './canonical-storage-mapping.js'
+import { assertScalarQueryField } from '../querying-writing/field-utils.js'
 import { normalizeValueForDatabaseStorage } from '../querying-writing/database-value-normalizers.js'
 
+/** @import { BaseStorageAdapterOptions, CanonicalDescriptor, SelectTranslator, StorageAdapter, StorageAdapterOptions, StorageAdapterLookupOptions, StorageSchemaInfo, StorageFieldDefinition } from './storage-types.js' */
+
+/** @template T @param {T} value @returns {T} */
 const passthrough = (value) => value
+/** @type {StorageAdapter['translateFilterValue']} */
 const identityTranslate = (_field, value) => value
-const identityScope = (query) => query
 
+/** @type {StorageAdapter['selectColumns']} */
 const selectColumnsOnBuilder = (builder, columns) => {
   if (!columns) return builder
   if (Array.isArray(columns)) {
@@ -25,16 +34,16 @@ const selectColumnsOnBuilder = (builder, columns) => {
   return builder
 }
 
-const normalizeArray = (value, normalizeFn) => value.map((entry) => normalizeFn(entry))
-
+/** @param {unknown} value @returns {unknown} */
 const normalizeBelongsToValue = (value) => {
   if (value === null || value === undefined) return value
   if (Array.isArray(value)) {
-    return normalizeArray(value, normalizeBelongsToValue)
+    return value.map(entry => normalizeBelongsToValue(entry))
   }
   return String(value)
 }
 
+/** @param {unknown} value @returns {boolean} */
 const normalizeBooleanValue = (value) => {
   if (typeof value === 'boolean') return value
   if (typeof value === 'string') {
@@ -49,13 +58,16 @@ const normalizeBooleanValue = (value) => {
   return Boolean(value)
 }
 
-const normalizeFilterValueForDefinition = (value, definition = {}, { isRelationship = false } = {}) => {
+/**
+ * @param {unknown} value
+ * @param {StorageFieldDefinition} [definition]
+ * @param {{ isRelationship?: boolean, databaseClient?: string, textStorage?: boolean }} [options]
+ * @returns {unknown}
+ */
+const normalizeFilterValueForDefinition = (value, definition = {}, { isRelationship = false, databaseClient, textStorage } = {}) => {
   if (value === null || value === undefined) return value
   if (Array.isArray(value)) {
-    return normalizeArray(
-      value,
-      (entry) => normalizeFilterValueForDefinition(entry, definition, { isRelationship })
-    )
+    return value.map(entry => normalizeFilterValueForDefinition(entry, definition, { isRelationship, databaseClient, textStorage }))
   }
 
   if (isRelationship) {
@@ -78,6 +90,8 @@ const normalizeFilterValueForDefinition = (value, definition = {}, { isRelations
 
   if (['date', 'dateTime', 'time'].includes(type)) {
     return normalizeValueForDatabaseStorage(value, type, {
+      databaseClient,
+      textStorage,
       temporalPrecision: definition?.temporalPrecision
     })
   }
@@ -85,11 +99,9 @@ const normalizeFilterValueForDefinition = (value, definition = {}, { isRelations
   return value
 }
 
-const translateSourceColumn = (source, adapter) => {
-  if (!adapter || source === '*') return source
-  return adapter.translateColumn(source) || source
-}
-
+/** @overload @param {StorageAdapter} adapter @returns {SelectTranslator} */
+/** @overload @param {StorageAdapter | null | undefined} adapter @returns {SelectTranslator | null} */
+/** @param {StorageAdapter | null | undefined} adapter @returns {SelectTranslator | null} */
 export const createSelectTranslator = (adapter) => {
   if (!adapter) return null
 
@@ -118,40 +130,23 @@ export const createSelectTranslator = (adapter) => {
   }
 }
 
-export const translateSelectFieldsForAdapter = (fields, adapter) => {
-  if (!adapter || !fields) return fields
-
-  const translateField = createSelectTranslator(adapter)
-
-  return fields.map((field) => {
-    if (typeof field !== 'string') return field
-    if (field === '*') return '*'
-
-    const aliasMatch = field.match(/\s+as\s+/i)
-    if (aliasMatch) {
-      const [source, alias] = field.split(/\s+as\s+/i)
-      const translatedSource = translateSourceColumn(source.trim(), adapter)
-      return `${translatedSource} as ${alias.trim()}`
-    }
-
-    return translateField(field)
-  })
-}
-
+/** @param {BaseStorageAdapterOptions} options @returns {StorageAdapter} */
 const baseAdapter = ({
   knex,
   tableName,
   idColumn,
   translateColumn,
   translateFilterValue = identityTranslate,
-  applyResourceScope = identityScope,
+  translateCursorValue = identityTranslate,
+  applyResourceScope = passthrough,
   toStorageRow = passthrough,
   getFieldValue = (record, fieldName) => record?.[fieldName],
   isCanonical = false,
 }) => {
-  const buildBaseQuery = ({ transaction } = {}) => {
-    const query = (transaction || knex)(tableName)
-    return applyResourceScope(query)
+  /** @type {StorageAdapter['buildBaseQuery']} */
+  const buildBaseQuery = ({ transaction, tableAlias } = {}) => {
+    const query = (transaction || knex)(tableAlias ? { [tableAlias]: tableName } : tableName)
+    return applyResourceScope(query, tableAlias)
   }
 
   return {
@@ -160,31 +155,61 @@ const baseAdapter = ({
     getIdColumn: () => idColumn,
     translateColumn,
     translateFilterValue,
+    translateCursorValue,
     applyResourceScope,
     toStorageRow,
     getFieldValue,
     buildBaseQuery,
-    selectColumns: (builder, columns) => selectColumnsOnBuilder(builder, columns),
+    selectColumns: selectColumnsOnBuilder,
   }
 }
 
-const createLegacyAdapter = ({ knex, schemaInfo }) => {
+/** @param {StorageAdapterOptions} options @returns {StorageAdapter} */
+const createTableAdapter = ({ knex, schemaInfo }) => {
+  assertWritableKnexColumns(getStorageInfo(schemaInfo))
   const tableName = schemaInfo.tableName
   const idColumn = getIdColumn(schemaInfo)
 
+  /** @type {StorageAdapter['translateColumn']} */
   const translateColumn = (field) => getStorageColumn(schemaInfo, field)
-  const toStorageRow = (attributes, options = {}) => translateAttributesForStorage(attributes, schemaInfo, options)
-  const getFieldValue = (record, fieldName) => getLegacyFieldValue(record, schemaInfo, fieldName)
+  /** @type {StorageAdapter['toStorageRow']} */
+  const toStorageRow = (attributes, options = {}) => translateAttributesForStorage(attributes, schemaInfo, { ...options, databaseClient: knex.client.config.client })
+  /** @type {StorageAdapter['getFieldValue']} */
+  const getFieldValue = (record, fieldName) => getTableFieldValue(record, schemaInfo, fieldName)
+  /** @type {StorageAdapter['translateCursorValue']} */
+  const translateCursorValue = (field, value) => {
+    const definition = schemaInfo.schemaStructure?.[field]
+    return normalizeFilterValueForDefinition(value, definition, {
+      isRelationship: Boolean(definition?.belongsTo || definition?.belongsToPolymorphic),
+      databaseClient: knex.client.config.client
+    })
+  }
+  /** @type {StorageAdapter['translateFilterValue']} */
   const translateFilterValue = (field, value) => {
     const searchField = schemaInfo.searchSchemaStructure?.[field]
-    const schemaField = schemaInfo.schemaStructure?.[field]
+    const fieldName = searchField?.actualField || field
+    const schemaField = schemaInfo.schemaStructure?.[fieldName]
+    assertScalarQueryField(schemaField, fieldName, 'filter')
+    const fieldStorage = getStorageInfo(schemaInfo).fields[fieldName]
+    if (fieldStorage?.serialize) {
+      /** @param {unknown} entry */
+      const serialize = (entry) => serializeFieldValueForStorage(entry, {
+        fieldName,
+        columnName: fieldStorage.column,
+        definition: fieldStorage.definition,
+        schemaInfo,
+        context: null,
+        operation: 'filter'
+      })
+      return Array.isArray(value) ? value.map(serialize) : serialize(value)
+    }
     const definition = searchField || schemaField || {}
     const isRelationship = Boolean(
       searchField?.isRelationship ||
       schemaField?.belongsTo ||
       schemaField?.belongsToPolymorphic
     )
-    return normalizeFilterValueForDefinition(value, definition, { isRelationship })
+    return normalizeFilterValueForDefinition(value, definition, { isRelationship, databaseClient: knex.client.config.client })
   }
 
   return baseAdapter({
@@ -193,25 +218,28 @@ const createLegacyAdapter = ({ knex, schemaInfo }) => {
     idColumn,
     translateColumn,
     translateFilterValue,
-    applyResourceScope: identityScope,
+    translateCursorValue,
+    applyResourceScope: passthrough,
     toStorageRow,
     getFieldValue,
     isCanonical: false,
   })
 }
 
-const createCanonicalAdapter = ({ knex, schemaInfo }) => {
-  const descriptor = schemaInfo.descriptor || {}
-  const canonical = descriptor.canonical || {}
+/** @param {StorageAdapterOptions & { descriptor: CanonicalDescriptor }} options @returns {StorageAdapter} */
+const createCanonicalAdapter = ({ knex, schemaInfo, descriptor }) => {
+  const canonical = descriptor.canonical
   const canonicalFieldMap = descriptor.canonicalFieldMap || {}
   const fieldsInfo = descriptor.fields || {}
   const belongsToInfo = descriptor.belongsTo || {}
   const idProperty = schemaInfo.idProperty || descriptor.idProperty || 'id'
+  /** @param {string} field */
   const isLogicalIdField = (field) => field === 'id' || field === idProperty
   const descriptorWithIdProperty = descriptor.idProperty === idProperty
     ? descriptor
     : { ...descriptor, idProperty }
 
+  /** @type {StorageAdapter['translateColumn']} */
   const translateColumn = (field) => {
     if (!field) return field
     if (isLogicalIdField(field)) return getCanonicalResourceIdColumn(descriptor)
@@ -237,7 +265,7 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
     if (!canonicalEntry && field.endsWith('_type')) {
       const alias = field.slice(0, -5)
       const aliasEntry = canonicalFieldMap[alias]
-      if (aliasEntry?.typeSlot) return aliasEntry.typeSlot
+      if (typeof aliasEntry === 'object' && aliasEntry?.typeSlot) return aliasEntry.typeSlot
     }
 
     const fieldInfo = fieldsInfo[field]
@@ -249,9 +277,27 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
     return field
   }
 
+  /** @type {StorageAdapter['translateFilterValue']} */
   const translateFilterValue = (field, value) => {
     const searchField = schemaInfo.searchSchemaStructure?.[field]
-    const schemaField = schemaInfo.schemaStructure?.[field]
+    const fieldName = searchField?.actualField || field
+    const schemaField = schemaInfo.schemaStructure?.[fieldName]
+    assertScalarQueryField(schemaField, fieldName, 'filter')
+    if (schemaField?.storage?.serialize) {
+      /** @param {unknown} entry */
+      const serialize = entry => {
+        const serialized = serializeFieldValueForStorage(entry, {
+          fieldName,
+          columnName: translateColumn(fieldName),
+          definition: schemaField,
+          schemaInfo,
+          operation: 'filter'
+        })
+        return schemaField.type === 'id' ? normalizeBelongsToValue(serialized) : serialized
+      }
+      return Array.isArray(value) ? value.map(serialize) : serialize(value)
+    }
+    if (isLogicalIdField(fieldName) || schemaField?.type === 'id') return normalizeBelongsToValue(value)
     const isRelationship = Boolean(
       searchField?.isRelationship ||
       schemaField?.belongsTo ||
@@ -259,20 +305,33 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
     )
     const definition = searchField || schemaField || {}
 
-    return normalizeFilterValueForDefinition(value, definition, { isRelationship })
+    return normalizeFilterValueForDefinition(value, definition, { isRelationship, databaseClient: knex.client.config.client, textStorage: fieldsInfo[fieldName]?.slotType === 'string' })
   }
 
-  const applyResourceScope = (query) => {
+  /** @type {StorageAdapter['translateCursorValue']} */
+  const translateCursorValue = (field, value) => {
+    const definition = schemaInfo.schemaStructure?.[field]
+    if (isLogicalIdField(field) || definition?.type === 'id') return normalizeBelongsToValue(value)
+    return normalizeFilterValueForDefinition(value, definition, {
+      isRelationship: Boolean(definition?.belongsTo || definition?.belongsToPolymorphic),
+      databaseClient: knex.client.config.client,
+      textStorage: fieldsInfo[field]?.slotType === 'string'
+    })
+  }
+
+  /** @type {StorageAdapter['applyResourceScope']} */
+  const applyResourceScope = (query, tableAlias) => {
+    const prefix = tableAlias ? `${tableAlias}.` : ''
     return query
-      .where(canonical.tenantColumn, descriptor.tenant)
-      .where(canonical.resourceColumn, descriptor.resource)
+      .where(`${prefix}${canonical.tenantColumn}`, descriptor.tenant)
+      .where(`${prefix}${canonical.resourceColumn}`, descriptor.resource)
   }
 
-  const toStorageRow = (attributes) => translateCanonicalAttributesForStorage(attributes, descriptor)
+  /** @type {StorageAdapter['toStorageRow']} */
+  const toStorageRow = (attributes, options = {}) => translateCanonicalAttributesForStorage(attributes, descriptor, { ...options, schemaInfo, databaseClient: knex.client.config.client })
+  /** @type {StorageAdapter['getFieldValue']} */
   const getFieldValue = (record, fieldName) => (
-    isLogicalIdField(fieldName)
-      ? getCanonicalFieldValue(record, descriptorWithIdProperty, fieldName)
-      : getCanonicalFieldValue(record, descriptor, fieldName)
+    getCanonicalFieldValue(record, isLogicalIdField(fieldName) ? descriptorWithIdProperty : descriptor, fieldName)
   )
 
   return baseAdapter({
@@ -281,6 +340,7 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
     idColumn: getCanonicalResourceIdColumn(descriptor),
     translateColumn,
     translateFilterValue,
+    translateCursorValue,
     applyResourceScope,
     toStorageRow,
     getFieldValue,
@@ -288,14 +348,34 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
   })
 }
 
+/** @param {StorageAdapterOptions} options @returns {StorageAdapter} */
 export const createStorageAdapter = ({ knex, schemaInfo }) => {
   if (!schemaInfo) {
     throw new Error('createStorageAdapter requires schemaInfo')
   }
 
-  if (schemaInfo?.descriptor?.canonical?.tableName) {
-    return createCanonicalAdapter({ knex, schemaInfo })
+  const descriptor = schemaInfo.descriptor
+  if (descriptor?.canonical?.tableName) {
+    return createCanonicalAdapter({ knex, schemaInfo, descriptor })
   }
 
-  return createLegacyAdapter({ knex, schemaInfo })
+  return createTableAdapter({ knex, schemaInfo })
+}
+
+/** @param {StorageAdapterLookupOptions} options @returns {(scopeName: string) => StorageAdapter | null} */
+export function createStorageAdapterLookup ({ knex, getResource }) {
+  /** @type {Map<string, { schemaInfo: StorageSchemaInfo, adapter: StorageAdapter }>} */
+  const adapters = new Map()
+  return scopeName => {
+    if (!scopeName) return null
+    const resource = getResource(scopeName)
+    const schemaInfo = resource?.vars?.schemaInfo
+    if (!schemaInfo) return null
+    const cached = adapters.get(scopeName)
+    if (cached && cached.schemaInfo === schemaInfo) return cached.adapter
+    const adapter = createStorageAdapter({ knex, schemaInfo })
+    adapters.set(scopeName, { adapter, schemaInfo })
+    if (resource?.vars) resource.vars.storageAdapter = adapter
+    return adapter
+  }
 }

package/plugins/core/lib/storage/storage-mapping.js

@@ -1,5 +1,10 @@
+// @ts-check
 import { normalizeValueForDatabaseStorage } from '../querying-writing/database-value-normalizers.js'
+import { assertFieldNameMap } from '../querying-writing/field-utils.js'
 
+/** @import { FieldStorage, StorageConfig, StorageFieldDefinition, StorageInfo, StorageNaming, StorageRow, StorageSchemaInfo, StorageSerializerDetails, StorageWriteOptions } from './storage-types.js' */
+
+/** @type {StorageInfo} */
 const EMPTY_STORAGE_INFO = Object.freeze({
   idColumn: 'id',
   storage: Object.freeze({
@@ -9,6 +14,7 @@ const EMPTY_STORAGE_INFO = Object.freeze({
   columns: Object.freeze({})
 })
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
 const isPlainObject = (value) => (
   value !== null &&
   typeof value === 'object' &&
@@ -18,6 +24,7 @@ const isPlainObject = (value) => (
 const SNAKE_CASE_STORAGE_NAMING = 'snake_case'
 const EXACT_STORAGE_NAMING = 'exact'
 
+/** @type {Readonly<Partial<Record<string, StorageNaming>>>} */
 const STORAGE_NAMING_ALIASES = Object.freeze({
   snake: SNAKE_CASE_STORAGE_NAMING,
   snake_case: SNAKE_CASE_STORAGE_NAMING,
@@ -27,11 +34,13 @@ const STORAGE_NAMING_ALIASES = Object.freeze({
   verbatim: EXACT_STORAGE_NAMING
 })
 
+/** @param {unknown} value */
 const toSnakeCase = (value) => String(value)
   .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
   .replace(/([A-Z]+)([A-Z][a-z0-9])/g, '$1_$2')
   .toLowerCase()
 
+/** @param {unknown} [storage] @returns {StorageInfo['storage']} */
 export const normalizeStorageConfig = (storage = undefined) => {
   if (storage === undefined || storage === null) {
     return {
@@ -46,7 +55,9 @@ export const normalizeStorageConfig = (storage = undefined) => {
   const rawNaming = storage.naming
   const naming = rawNaming === undefined
     ? SNAKE_CASE_STORAGE_NAMING
-    : STORAGE_NAMING_ALIASES[rawNaming]
+    : typeof rawNaming === 'string' && Object.hasOwn(STORAGE_NAMING_ALIASES, rawNaming)
+      ? STORAGE_NAMING_ALIASES[rawNaming]
+      : undefined
 
   if (!naming) {
     throw new Error(
@@ -60,6 +71,7 @@ export const normalizeStorageConfig = (storage = undefined) => {
   }
 }
 
+/** @param {string} fieldName @param {{ idColumn?: string, storageConfig?: StorageConfig }} [options] */
 const resolveDefaultStorageColumn = (fieldName, { idColumn = 'id', storageConfig = undefined } = {}) => {
   if (fieldName === 'id') {
     return idColumn
@@ -73,6 +85,12 @@ const resolveDefaultStorageColumn = (fieldName, { idColumn = 'id', storageConfig
   return toSnakeCase(fieldName)
 }
 
+/**
+ * @param {string} fieldName
+ * @param {StorageFieldDefinition} [definition]
+ * @param {{ idColumn?: string, storageConfig?: StorageConfig }} [options]
+ * @returns {Omit<FieldStorage, 'definition'>}
+ */
 export const normalizeFieldStorage = (fieldName, definition = {}, { idColumn = 'id', storageConfig = undefined } = {}) => {
   const fieldStorage = definition.storage
 
@@ -105,10 +123,14 @@ export const normalizeFieldStorage = (fieldName, definition = {}, { idColumn = '
   }
 }
 
+/** @param {Partial<Pick<StorageSchemaInfo, 'schemaStructure' | 'idProperty' | 'storage'>>} [options] @returns {StorageInfo} */
 export const buildStorageInfo = ({ schemaStructure = {}, idProperty = 'id', storage = undefined } = {}) => {
+  assertFieldNameMap(schemaStructure, 'storage schema')
   const idColumn = idProperty || 'id'
   const storageConfig = normalizeStorageConfig(storage)
+  /** @type {StorageInfo['fields']} */
   const fields = {}
+  /** @type {StorageInfo['columns']} */
   const columns = {}
   const usedColumns = new Map([[idColumn, 'id']])
 
@@ -151,6 +173,7 @@ export const buildStorageInfo = ({ schemaStructure = {}, idProperty = 'id', stor
   }
 }
 
+/** @param {Partial<StorageSchemaInfo>} [schemaInfo] @returns {StorageInfo} */
 export const getStorageInfo = (schemaInfo = {}) => {
   if (schemaInfo.storageInfo) {
     return schemaInfo.storageInfo
@@ -167,10 +190,12 @@ export const getStorageInfo = (schemaInfo = {}) => {
   })
 }
 
+/** @param {Partial<StorageSchemaInfo>} [schemaInfo] @returns {string} */
 export const getIdColumn = (schemaInfo = {}) => {
   return getStorageInfo(schemaInfo).idColumn || schemaInfo.idProperty || 'id'
 }
 
+/** @param {Partial<StorageSchemaInfo>} schemaInfo @param {string} fieldName @returns {string} */
 export const getStorageColumn = (schemaInfo = {}, fieldName) => {
   if (!fieldName) return fieldName
   if (fieldName === 'id') return getIdColumn(schemaInfo)
@@ -179,14 +204,7 @@ export const getStorageColumn = (schemaInfo = {}, fieldName) => {
   return fieldStorage?.column || fieldName
 }
 
-export const getLogicalFieldName = (schemaInfo = {}, columnName) => {
-  if (!columnName) return columnName
-  if (columnName === getIdColumn(schemaInfo)) return 'id'
-
-  const logicalField = getStorageInfo(schemaInfo).columns[columnName]
-  return logicalField || columnName
-}
-
+/** @param {StorageRow | null | undefined} record @param {Partial<StorageSchemaInfo>} schemaInfo @param {string} fieldName @returns {unknown} */
 export const getFieldValue = (record, schemaInfo = {}, fieldName) => {
   if (!record || !fieldName) return undefined
 
@@ -212,18 +230,57 @@ export const getFieldValue = (record, schemaInfo = {}, fieldName) => {
     return record[columnName]
   }
 
-  return translateRecordFromStorage(record, schemaInfo)[fieldName]
+  const translated = translateRecordFromStorage(record, schemaInfo)
+  return Object.hasOwn(translated, fieldName) ? translated[fieldName] : undefined
 }
 
+/** @param {StorageInfo} storageInfo */
+export const assertWritableKnexColumns = (storageInfo) => {
+  // Knex's update compiler discards these keys, even in null-prototype input objects.
+  const unsupported = new Set(['constructor', 'prototype', '__proto__'])
+  for (const [fieldName, field] of Object.entries(storageInfo.fields)) {
+    if (field.persisted && unsupported.has(field.column)) {
+      throw new Error(`Field '${fieldName}' maps to unsupported Knex storage column '${field.column}'. Set storage.column to a different column name; the public field name can stay the same.`)
+    }
+  }
+  if (unsupported.has(storageInfo.idColumn)) {
+    throw new Error(`Unsupported Knex id column '${storageInfo.idColumn}'. Set idProperty to a different column name.`)
+  }
+}
+
+/** @param {unknown} value @param {Partial<StorageSerializerDetails> & { textStorage?: boolean }} [options] @returns {unknown} */
+export const serializeFieldValueForStorage = (value, {
+  fieldName, columnName, definition = {}, schemaInfo, context = null, operation = null, databaseClient, textStorage
+} = {}) => {
+  if (definition.storage?.serialize) {
+    const serialized = definition.storage.serialize(value, { fieldName, columnName, definition, schemaInfo, context, operation })
+    // Probe the optional property directly: proxies can supply it without a `has` result.
+    if (serialized && typeof (/** @type {{ then?: unknown }} */ (serialized)).then === 'function') {
+      // Own the rejected promise even though asynchronous serializers are invalid.
+      Promise.resolve(serialized).catch(() => {})
+      throw new Error(`Field '${fieldName}' storage.serialize must be synchronous. Use a field setter for asynchronous preparation.`)
+    }
+    return serialized
+  }
+  return normalizeValueForDatabaseStorage(value, definition.type, {
+    databaseClient,
+    textStorage,
+    temporalPrecision: definition.temporalPrecision,
+    fieldName,
+    resourceType: context?.scopeName || schemaInfo?.tableName
+  })
+}
+
+/** @param {StorageRow | null | undefined} attributes @param {Partial<StorageSchemaInfo>} schemaInfo @param {StorageWriteOptions} [options] @returns {StorageRow} */
 export const translateAttributesForStorage = (attributes, schemaInfo = {}, options = {}) => {
   if (!attributes) return attributes || {}
 
-  const { context = null, operation = null } = options
+  const { context = null, operation = null, databaseClient } = options
   const storageInfo = getStorageInfo(schemaInfo)
   const computed = schemaInfo.computed || {}
 
   return Object.entries(attributes).reduce((translated, [fieldName, value]) => {
-    if (fieldName in computed) {
+    if (Object.hasOwn(computed, fieldName)) {
       return translated
     }
 
@@ -235,30 +292,23 @@ export const translateAttributesForStorage = (attributes, schemaInfo = {}, optio
     const columnName = fieldName === 'id'
       ? storageInfo.idColumn
       : fieldStorage?.column || fieldName
-    const serializedValue = fieldStorage?.serialize
-      ? fieldStorage.serialize(value, {
-        fieldName,
-        columnName,
-        definition: fieldStorage.definition,
-        schemaInfo,
-        context,
-        operation
-      })
-      : normalizeValueForDatabaseStorage(value, fieldStorage?.definition?.type, {
-        temporalPrecision: fieldStorage?.definition?.temporalPrecision,
-        fieldName,
-        resourceType: context?.scopeName || schemaInfo.tableName
-      })
+    const serializedValue = serializeFieldValueForStorage(value, {
+      fieldName, columnName, definition: fieldStorage?.definition, schemaInfo, context, operation, databaseClient
+    })
 
     translated[columnName] = serializedValue
     return translated
-  }, {})
+  }, /** @type {StorageRow} */ ({}))
 }
 
+/** @overload @param {StorageRow} record @param {Partial<StorageSchemaInfo>} [schemaInfo] @returns {StorageRow} */
+/** @overload @param {StorageRow | null | undefined} record @param {Partial<StorageSchemaInfo>} [schemaInfo] @returns {StorageRow | null | undefined} */
+/** @param {StorageRow | null | undefined} record @param {Partial<StorageSchemaInfo>} [schemaInfo] @returns {StorageRow | null | undefined} */
 export const translateRecordFromStorage = (record, schemaInfo = {}) => {
   if (!record || !schemaInfo) return record
 
   const storageInfo = getStorageInfo(schemaInfo)
+  /** @type {StorageRow} */
   const translated = {}
 
   for (const [columnName, value] of Object.entries(record)) {
@@ -267,7 +317,7 @@ export const translateRecordFromStorage = (record, schemaInfo = {}) => {
       continue
     }
 
-    const logicalField = storageInfo.columns[columnName]
+    const logicalField = Object.hasOwn(storageInfo.columns, columnName) ? storageInfo.columns[columnName] : undefined
     if (logicalField) {
       translated[logicalField] = value
       continue