@opensaas/stack-storage 0.20.1 → 0.22.0

package/dist/utils/multi-column.js

@@ -0,0 +1,248 @@
+/** Ordered list of image parts, matching Keystone's column layout. */
+export const IMAGE_COLUMN_PARTS = [
+    'url',
+    'width',
+    'height',
+    'filesize',
+    'contentType',
+    'contentDisposition',
+    'pathname',
+];
+/** Ordered list of file parts, matching Keystone's column layout. */
+export const FILE_COLUMN_PARTS = ['filename', 'filesize', 'url'];
+/** The Prisma scalar type each image part is stored as. */
+const IMAGE_PART_PRISMA_TYPE = {
+    url: 'String',
+    width: 'Int',
+    height: 'Int',
+    filesize: 'Int',
+    contentType: 'String',
+    contentDisposition: 'String',
+    pathname: 'String',
+};
+/** The Prisma scalar type each file part is stored as. */
+const FILE_PART_PRISMA_TYPE = {
+    filename: 'String',
+    filesize: 'Int',
+    url: 'String',
+};
+/**
+ * Build the default per-part column-name map for an image field, following
+ * Keystone's `<field>_<part>` convention.
+ *
+ * @example
+ * keystoneImageColumnMap('image') // { url: 'image_url', width: 'image_width', ... }
+ */
+export function keystoneImageColumnMap(fieldName) {
+    return {
+        url: `${fieldName}_url`,
+        width: `${fieldName}_width`,
+        height: `${fieldName}_height`,
+        filesize: `${fieldName}_filesize`,
+        contentType: `${fieldName}_contentType`,
+        contentDisposition: `${fieldName}_contentDisposition`,
+        pathname: `${fieldName}_pathname`,
+    };
+}
+/**
+ * Build the default per-part column-name map for a file field.
+ *
+ * @example
+ * keystoneFileColumnMap('file') // { filename: 'file_filename', filesize: 'file_filesize', url: 'file_url' }
+ */
+export function keystoneFileColumnMap(fieldName) {
+    return {
+        filename: `${fieldName}_filename`,
+        filesize: `${fieldName}_filesize`,
+        url: `${fieldName}_url`,
+    };
+}
+/**
+ * Resolve the effective image column map: defaults from {@link keystoneImageColumnMap},
+ * with any caller-supplied per-part overrides applied on top.
+ */
+export function resolveImageColumnMap(fieldName, overrides) {
+    return { ...keystoneImageColumnMap(fieldName), ...overrides };
+}
+/**
+ * Resolve the effective file column map.
+ */
+export function resolveFileColumnMap(fieldName, overrides) {
+    return { ...keystoneFileColumnMap(fieldName), ...overrides };
+}
+/**
+ * The Prisma model field name carrying a given image part's column. We name the
+ * model field after the physical column itself (i.e. `<field>_url`) so the
+ * generated property and its `@map` line up with the live Keystone column.
+ */
+function imagePartFieldName(map, part) {
+    return map[part];
+}
+function filePartFieldName(map, part) {
+    return map[part];
+}
+/**
+ * Describe the physical columns an image field emits in multi-column mode.
+ * Each descriptor's `name` is the Prisma model field name and `map` is the
+ * physical column it maps to (here they are identical so the schema reads
+ * naturally over the live columns).
+ */
+export function imageColumnDescriptors(map) {
+    return IMAGE_COLUMN_PARTS.map((part) => ({
+        name: imagePartFieldName(map, part),
+        type: IMAGE_PART_PRISMA_TYPE[part],
+        map: map[part],
+    }));
+}
+/**
+ * Describe the physical columns a file field emits in multi-column mode.
+ */
+export function fileColumnDescriptors(map) {
+    return FILE_COLUMN_PARTS.map((part) => ({
+        name: filePartFieldName(map, part),
+        type: FILE_PART_PRISMA_TYPE[part],
+        map: map[part],
+    }));
+}
+/** The physical column field names an image field owns (for read stripping). */
+export function imageColumnNames(map) {
+    return IMAGE_COLUMN_PARTS.map((part) => imagePartFieldName(map, part));
+}
+/** The physical column field names a file field owns (for read stripping). */
+export function fileColumnNames(map) {
+    return FILE_COLUMN_PARTS.map((part) => filePartFieldName(map, part));
+}
+/** Coerce an unknown column value to a string, or `null` when absent/empty. */
+function asString(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    return String(value);
+}
+/** Coerce an unknown column value to a number, or `null` when absent/invalid. */
+function asNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    if (typeof value === 'bigint')
+        return Number(value);
+    return null;
+}
+/**
+ * Assemble the per-part image columns from a database row into an
+ * {@link ImageMetadata}.
+ *
+ * Returns `null` when the row carries no image at all (the `url` column is the
+ * authoritative presence signal — Keystone leaves every part NULL for an empty
+ * image). Partially-populated rows (e.g. only `image_url`) still assemble into a
+ * valid object, with missing scalar parts defaulted (width/height/size → 0).
+ *
+ * `storageProvider` is supplied by the caller (the field knows which provider it
+ * is bound to); legacy columns do not carry it.
+ */
+export function assembleImageMetadata(row, map, storageProvider) {
+    const url = asString(row[map.url]);
+    if (url === null || url === '') {
+        return null;
+    }
+    const pathname = asString(row[map.pathname]);
+    const contentType = asString(row[map.contentType]);
+    const contentDisposition = asString(row[map.contentDisposition]);
+    // Keystone stores the storage key in `pathname`; fall back to the URL when
+    // absent so `filename` is always populated.
+    const filename = pathname ?? url;
+    const metadata = {
+        filename,
+        originalFilename: filename,
+        url,
+        mimeType: contentType ?? 'application/octet-stream',
+        size: asNumber(row[map.filesize]) ?? 0,
+        width: asNumber(row[map.width]) ?? 0,
+        height: asNumber(row[map.height]) ?? 0,
+        uploadedAt: '',
+        storageProvider,
+    };
+    // Preserve the Keystone-only content disposition (no first-class metadata
+    // field) so a round-trip back to columns does not lose it.
+    if (contentDisposition !== null) {
+        metadata.metadata = { contentDisposition };
+    }
+    return metadata;
+}
+/**
+ * Split an {@link ImageMetadata} (or `null`) back into the per-part image
+ * columns for writing. A `null`/`undefined` metadata clears every column.
+ */
+export function splitImageMetadata(metadata, map) {
+    if (metadata === null || metadata === undefined) {
+        return {
+            [map.url]: null,
+            [map.width]: null,
+            [map.height]: null,
+            [map.filesize]: null,
+            [map.contentType]: null,
+            [map.contentDisposition]: null,
+            [map.pathname]: null,
+        };
+    }
+    const contentDisposition = metadata.metadata && typeof metadata.metadata.contentDisposition === 'string'
+        ? metadata.metadata.contentDisposition
+        : null;
+    return {
+        [map.url]: metadata.url,
+        [map.width]: metadata.width ?? null,
+        [map.height]: metadata.height ?? null,
+        [map.filesize]: metadata.size ?? null,
+        [map.contentType]: metadata.mimeType ?? null,
+        [map.contentDisposition]: contentDisposition,
+        // Keystone's pathname holds the storage key (our `filename`).
+        [map.pathname]: metadata.filename ?? null,
+    };
+}
+/**
+ * Assemble the per-part file columns from a database row into a
+ * {@link FileMetadata}. Returns `null` when no file is present.
+ */
+export function assembleFileMetadata(row, map, storageProvider) {
+    const url = asString(row[map.url]);
+    const filename = asString(row[map.filename]);
+    // Either a URL or a filename signals a present file.
+    if ((url === null || url === '') && (filename === null || filename === '')) {
+        return null;
+    }
+    const resolvedFilename = filename ?? url ?? '';
+    return {
+        filename: resolvedFilename,
+        originalFilename: resolvedFilename,
+        url: url ?? '',
+        mimeType: 'application/octet-stream',
+        size: asNumber(row[map.filesize]) ?? 0,
+        uploadedAt: '',
+        storageProvider,
+    };
+}
+/**
+ * Split a {@link FileMetadata} (or `null`) back into the per-part file columns
+ * for writing. A `null`/`undefined` metadata clears every column.
+ */
+export function splitFileMetadata(metadata, map) {
+    if (metadata === null || metadata === undefined) {
+        return {
+            [map.filename]: null,
+            [map.filesize]: null,
+            [map.url]: null,
+        };
+    }
+    return {
+        [map.filename]: metadata.filename ?? null,
+        [map.filesize]: metadata.size ?? null,
+        [map.url]: metadata.url ?? null,
+    };
+}
+//# sourceMappingURL=multi-column.js.map

package/dist/utils/multi-column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-column.js","sourceRoot":"","sources":["../../src/utils/multi-column.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-storage",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "File and image upload field types with pluggable storage providers for OpenSaas Stack",
   "type": "module",
   "exports": {
@@ -30,12 +30,12 @@
   },
   "devDependencies": {
     "@types/mime-types": "^3.0.1",
-    "@types/node": "^24.12.0",
+    "@types/node": "^25.9.1",
     "@types/react": "^19.2.14",
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@opensaas/stack-core": "0.20.1"
+    "@opensaas/stack-core": "0.22.0"
   },
   "peerDependencies": {
     "@opensaas/stack-core": "^0"

package/src/config/types.ts

@@ -108,7 +108,11 @@ export type StorageConfig = Record<string, BaseStorageConfig | LocalStorageConfi
  * Re-export metadata types from core package
  * These types are now defined in @opensaas/stack-core to avoid circular dependencies
  */
-export type { FileMetadata, ImageMetadata, ImageTransformationResult } from '@opensaas/stack-core'
+export type {
+  FileMetadata,
+  ImageMetadata,
+  ImageTransformationResult,
+} from '@opensaas/stack-core/internal'
 
 /**
  * Configuration for image transformations

package/src/fields/index.ts

@@ -1,8 +1,99 @@
-import type { BaseFieldConfig, TypeInfo } from '@opensaas/stack-core'
+import type {
+  BaseFieldConfig,
+  TypeInfo,
+  MultiColumnPrismaResult,
+} from '@opensaas/stack-core/extend'
 import { z } from 'zod'
 import type { ComponentType } from 'react'
 import type { FileMetadata, ImageMetadata, ImageTransformationConfig } from '../config/types.js'
 import type { FileValidationOptions } from '../utils/upload.js'
+import {
+  assembleFileMetadata,
+  assembleImageMetadata,
+  fileColumnDescriptors,
+  fileColumnNames,
+  imageColumnDescriptors,
+  imageColumnNames,
+  resolveFileColumnMap,
+  resolveImageColumnMap,
+  splitFileMetadata,
+  splitImageMetadata,
+  type FileColumnMap,
+  type ImageColumnMap,
+} from '../utils/multi-column.js'
+
+/**
+ * Multi-column (Keystone-parity) database mode for image()/file() fields.
+ *
+ * The default backing for image()/file() is a single `Json?` column. A
+ * migrating project that already has a Keystone database can instead set
+ * `columns: 'keystone'` to map the field onto the existing per-part columns in
+ * place — no destructive migration, no re-upload of existing assets. The
+ * per-part column names (used in `@map`) follow Keystone's `<field>_<part>`
+ * convention and can be overridden individually. See ADR-0006.
+ */
+export interface ImageDbConfig {
+  /** Custom database column name for single-Json? mode (unused in multi-column mode). */
+  map?: string
+  /** Override DB-level nullability for single-Json? mode. */
+  isNullable?: boolean
+  /** Override the native database type for single-Json? mode. */
+  nativeType?: string
+  /**
+   * Enable multi-column mode by setting `'keystone'`. Per-part column-name
+   * overrides may be supplied; any omitted part falls back to the Keystone
+   * default `<field>_<part>`.
+   */
+  columns?: 'keystone' | { mode: 'keystone'; map?: Partial<ImageColumnMap> }
+}
+
+/**
+ * Multi-column (Keystone-parity) database mode for file() fields.
+ */
+export interface FileDbConfig {
+  /** Custom database column name for single-Json? mode (unused in multi-column mode). */
+  map?: string
+  /** Override DB-level nullability for single-Json? mode. */
+  isNullable?: boolean
+  /** Override the native database type for single-Json? mode. */
+  nativeType?: string
+  /**
+   * Enable multi-column mode by setting `'keystone'`. Per-part column-name
+   * overrides may be supplied; any omitted part falls back to the Keystone
+   * default `<field>_<part>`.
+   */
+  columns?: 'keystone' | { mode: 'keystone'; map?: Partial<FileColumnMap> }
+}
+
+/** Whether a field-level `db.columns` option requests multi-column mode. */
+function isMultiColumn(columns: ImageDbConfig['columns'] | FileDbConfig['columns']): boolean {
+  return columns === 'keystone' || (typeof columns === 'object' && columns?.mode === 'keystone')
+}
+
+/** Extract any per-part `@map` overrides from a `db.columns` option. */
+function imageColumnOverrides(
+  columns: ImageDbConfig['columns'],
+): Partial<ImageColumnMap> | undefined {
+  return typeof columns === 'object' ? columns.map : undefined
+}
+
+function fileColumnOverrides(columns: FileDbConfig['columns']): Partial<FileColumnMap> | undefined {
+  return typeof columns === 'object' ? columns.map : undefined
+}
+
+/**
+ * Detect a File-like input (something we should upload). An already-shaped
+ * metadata value or populated multi-column row is authoritative and must never
+ * trigger an upload (the no-re-upload guarantee — see ADR-0006).
+ */
+function isFileLike(value: unknown): value is File {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'arrayBuffer' in value &&
+    typeof (value as { arrayBuffer?: unknown }).arrayBuffer === 'function'
+  )
+}
 
 /**
  * File field configuration
@@ -19,6 +110,12 @@ export interface FileFieldConfig<
   cleanupOnDelete?: boolean
   /** Automatically delete old file from storage when replaced with new file */
   cleanupOnReplace?: boolean
+  /**
+   * Database configuration. By default a file is backed by a single `Json?`
+   * column; set `db.columns: 'keystone'` to map onto existing Keystone per-part
+   * columns in place (non-destructive migration). See ADR-0006.
+   */
+  db?: FileDbConfig
   /** UI options */
   ui?: {
     /** Custom component to use for rendering this field */
@@ -53,6 +150,12 @@ export interface ImageFieldConfig<
   cleanupOnDelete?: boolean
   /** Automatically delete old file from storage when replaced with new file */
   cleanupOnReplace?: boolean
+  /**
+   * Database configuration. By default an image is backed by a single `Json?`
+   * column; set `db.columns: 'keystone'` to map onto existing Keystone per-part
+   * columns in place (non-destructive migration). See ADR-0006.
+   */
+  db?: ImageDbConfig
   /** UI options */
   ui?: {
     /** Custom component to use for rendering this field */
@@ -97,37 +200,47 @@ export function file<TTypeInfo extends TypeInfo = TypeInfo>(
 ): FileFieldConfig<TTypeInfo> {
   const { hooks: userHooks, ...restOptions } = options
 
+  // Multi-column (Keystone-parity) mode maps onto existing per-part columns
+  // instead of a single Json? column. The column map is resolved lazily per
+  // field name so default `<field>_<part>` names line up with the live columns.
+  const multiColumn = isMultiColumn(options.db?.columns)
+  const columnMapFor = (fieldName: string): FileColumnMap =>
+    resolveFileColumnMap(fieldName, fileColumnOverrides(options.db?.columns))
+
   const fieldConfig: FileFieldConfig<TTypeInfo> = {
     type: 'file',
     ...restOptions,
 
-    // Override Prisma's Json type with FileMetadata | null in context.db types
+    // Override Prisma's Json type with FileMetadata | null in context.db types.
+    // Multi-column mode adds the same logical field back via TransformedFields
+    // while the raw per-part columns are stripped from the payload.
     resultExtension: {
       outputType: "import('@opensaas/stack-storage').FileMetadata | null",
     },
 
     hooks: {
+      // Keystone-compliant field resolveInput args: the field value lives at
+      // `resolvedData[fieldKey]`. See FieldResolveInputHookArgs in core.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks are generic and resolved at runtime
-      resolveInput: async ({ inputValue, context, item, fieldName }: any) => {
+      resolveInput: async ({ resolvedData, fieldKey, context, item }: any) => {
+        const inputValue = resolvedData?.[fieldKey]
+
         // If null/undefined, return as-is (deletion or no change)
         if (inputValue === null || inputValue === undefined) {
           return inputValue
         }
 
-        // If already FileMetadata, keep existing (edit mode - no new file uploaded)
+        // If already FileMetadata, keep existing (edit mode - no new file
+        // uploaded). An existing metadata value is AUTHORITATIVE and must never
+        // re-upload. See ADR-0006.
         if (typeof inputValue === 'object' && 'filename' in inputValue && 'url' in inputValue) {
           return inputValue as FileMetadata
         }
 
-        // If File object, upload it
-        // Check if it's a File-like object (has arrayBuffer method)
-        if (
-          typeof inputValue === 'object' &&
-          'arrayBuffer' in inputValue &&
-          typeof (inputValue as { arrayBuffer?: unknown }).arrayBuffer === 'function'
-        ) {
+        // Only a File-like input triggers an upload.
+        if (isFileLike(inputValue)) {
           // Convert File to buffer
-          const fileObj = inputValue as File
+          const fileObj = inputValue
           const arrayBuffer = await fileObj.arrayBuffer()
           const buffer = Buffer.from(arrayBuffer)
 
@@ -137,8 +250,8 @@ export function file<TTypeInfo extends TypeInfo = TypeInfo>(
           })) as FileMetadata
 
           // If cleanupOnReplace is enabled and there was an old file, delete it
-          if (fieldConfig.cleanupOnReplace && item && fieldName) {
-            const oldMetadata = item[fieldName] as FileMetadata | null
+          if (fieldConfig.cleanupOnReplace && item && fieldKey) {
+            const oldMetadata = item[fieldKey] as FileMetadata | null
             if (oldMetadata && oldMetadata.filename) {
               try {
                 await context.storage.deleteFile(oldMetadata.storageProvider, oldMetadata.filename)
@@ -157,12 +270,12 @@ export function file<TTypeInfo extends TypeInfo = TypeInfo>(
       },
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks are generic and resolved at runtime
-      afterOperation: async ({ operation, item, fieldName, context }: any) => {
-        // Only cleanup on delete if enabled
+      afterOperation: async ({ operation, originalItem, fieldKey, context }: any) => {
+        // Only cleanup on delete if enabled. The deleted row is `originalItem`.
         if (operation === 'delete' && fieldConfig.cleanupOnDelete) {
-          const fileMetadata = item[fieldName] as FileMetadata | null
+          const fileMetadata = originalItem?.[fieldKey] as FileMetadata | null
 
-          if (fileMetadata && fileMetadata.filename) {
+          if (fileMetadata && typeof fileMetadata === 'object' && fileMetadata.filename) {
             try {
               await context.storage.deleteFile(fileMetadata.storageProvider, fileMetadata.filename)
             } catch (error) {
@@ -194,7 +307,7 @@ export function file<TTypeInfo extends TypeInfo = TypeInfo>(
     },
 
     getPrismaType: (_fieldName: string) => {
-      // Store as JSON in database
+      // Store as JSON in database (single-column default mode).
       return { type: 'Json', modifiers: '?' }
     },
 
@@ -217,6 +330,26 @@ export function file<TTypeInfo extends TypeInfo = TypeInfo>(
     },
   }
 
+  // Multi-column emission + assemble/split. Only attached in multi-column mode
+  // so the single-Json? default is completely unaffected.
+  if (multiColumn) {
+    fieldConfig.getPrismaColumns = (fieldName: string): MultiColumnPrismaResult[] => {
+      const map = columnMapFor(fieldName)
+      return fileColumnDescriptors(map).map((col) => ({
+        name: col.name,
+        type: col.type,
+        modifiers: '?',
+        map: col.map,
+      }))
+    }
+    fieldConfig.getColumnNames = (fieldName: string): string[] =>
+      fileColumnNames(columnMapFor(fieldName))
+    fieldConfig.assembleColumns = (fieldName: string, row: Record<string, unknown>): unknown =>
+      assembleFileMetadata(row, columnMapFor(fieldName), fieldConfig.storage)
+    fieldConfig.splitColumns = (fieldName: string, value: unknown): Record<string, unknown> =>
+      splitFileMetadata((value ?? null) as FileMetadata | null, columnMapFor(fieldName))
+  }
+
   return fieldConfig
 }
 
@@ -247,24 +380,38 @@ export function image<TTypeInfo extends TypeInfo = TypeInfo>(
 ): ImageFieldConfig<TTypeInfo> {
   const { hooks: userHooks, ...restOptions } = options
 
+  // Multi-column (Keystone-parity) mode maps onto existing per-part columns
+  // instead of a single Json? column. See ADR-0006.
+  const multiColumn = isMultiColumn(options.db?.columns)
+  const columnMapFor = (fieldName: string): ImageColumnMap =>
+    resolveImageColumnMap(fieldName, imageColumnOverrides(options.db?.columns))
+
   const fieldConfig: ImageFieldConfig<TTypeInfo> = {
     type: 'image',
     ...restOptions,
 
-    // Override Prisma's Json type with ImageMetadata | null in context.db types
+    // Override Prisma's Json type with ImageMetadata | null in context.db types.
+    // Multi-column mode adds the same logical field back via TransformedFields
+    // while the raw per-part columns are stripped from the payload.
     resultExtension: {
       outputType: "import('@opensaas/stack-storage').ImageMetadata | null",
     },
 
     hooks: {
+      // Keystone-compliant field resolveInput args: the field value lives at
+      // `resolvedData[fieldKey]`. See FieldResolveInputHookArgs in core.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks are generic and resolved at runtime
-      resolveInput: async ({ inputValue, context, item, fieldName }: any) => {
+      resolveInput: async ({ resolvedData, fieldKey, context, item }: any) => {
+        const inputValue = resolvedData?.[fieldKey]
+
         // If null/undefined, return as-is (deletion or no change)
         if (inputValue === null || inputValue === undefined) {
           return inputValue
         }
 
-        // If already ImageMetadata, keep existing (edit mode - no new file uploaded)
+        // If already ImageMetadata, keep existing (edit mode - no new file
+        // uploaded). An existing metadata value is AUTHORITATIVE and must never
+        // re-upload. See ADR-0006.
         if (
           typeof inputValue === 'object' &&
           'filename' in inputValue &&
@@ -275,15 +422,10 @@ export function image<TTypeInfo extends TypeInfo = TypeInfo>(
           return inputValue as ImageMetadata
         }
 
-        // If File object, upload it
-        // Check if it's a File-like object (has arrayBuffer method)
-        if (
-          typeof inputValue === 'object' &&
-          'arrayBuffer' in inputValue &&
-          typeof (inputValue as { arrayBuffer?: unknown }).arrayBuffer === 'function'
-        ) {
+        // Only a File-like input triggers an upload.
+        if (isFileLike(inputValue)) {
           // Convert File to buffer
-          const fileObj = inputValue as File
+          const fileObj = inputValue
           const arrayBuffer = await fileObj.arrayBuffer()
           const buffer = Buffer.from(arrayBuffer)
 
@@ -299,8 +441,8 @@ export function image<TTypeInfo extends TypeInfo = TypeInfo>(
           )) as ImageMetadata
 
           // If cleanupOnReplace is enabled and there was an old file, delete it
-          if (fieldConfig.cleanupOnReplace && item && fieldName) {
-            const oldMetadata = item[fieldName] as ImageMetadata | null
+          if (fieldConfig.cleanupOnReplace && item && fieldKey) {
+            const oldMetadata = item[fieldKey] as ImageMetadata | null
             if (oldMetadata && oldMetadata.filename) {
               try {
                 await context.storage.deleteImage(oldMetadata)
@@ -319,12 +461,12 @@ export function image<TTypeInfo extends TypeInfo = TypeInfo>(
       },
 
       // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks are generic and resolved at runtime
-      afterOperation: async ({ operation, item, fieldName, context }: any) => {
-        // Only cleanup on delete if enabled
+      afterOperation: async ({ operation, originalItem, fieldKey, context }: any) => {
+        // Only cleanup on delete if enabled. The deleted row is `originalItem`.
         if (operation === 'delete' && fieldConfig.cleanupOnDelete) {
-          const imageMetadata = item[fieldName] as ImageMetadata | null
+          const imageMetadata = originalItem?.[fieldKey] as ImageMetadata | null
 
-          if (imageMetadata && imageMetadata.filename) {
+          if (imageMetadata && typeof imageMetadata === 'object' && imageMetadata.filename) {
             try {
               await context.storage.deleteImage(imageMetadata)
             } catch (error) {
@@ -392,5 +534,25 @@ export function image<TTypeInfo extends TypeInfo = TypeInfo>(
     },
   }
 
+  // Multi-column emission + assemble/split. Only attached in multi-column mode
+  // so the single-Json? default is completely unaffected.
+  if (multiColumn) {
+    fieldConfig.getPrismaColumns = (fieldName: string): MultiColumnPrismaResult[] => {
+      const map = columnMapFor(fieldName)
+      return imageColumnDescriptors(map).map((col) => ({
+        name: col.name,
+        type: col.type,
+        modifiers: '?',
+        map: col.map,
+      }))
+    }
+    fieldConfig.getColumnNames = (fieldName: string): string[] =>
+      imageColumnNames(columnMapFor(fieldName))
+    fieldConfig.assembleColumns = (fieldName: string, row: Record<string, unknown>): unknown =>
+      assembleImageMetadata(row, columnMapFor(fieldName), fieldConfig.storage)
+    fieldConfig.splitColumns = (fieldName: string, value: unknown): Record<string, unknown> =>
+      splitImageMetadata((value ?? null) as ImageMetadata | null, columnMapFor(fieldName))
+  }
+
   return fieldConfig
 }

package/src/utils/index.ts

@@ -1,2 +1,3 @@
 export * from './image.js'
 export * from './upload.js'
+export * from './multi-column.js'