prostgles-server 4.2.625 → 4.2.626

package/lib/DBSchemaBuilder/getClientDBGeneratedSchemas.ts

@@ -86,6 +86,9 @@ export const getClientDBGeneratedSchemas = (
           `  ${JSON.stringify(table.name)}: ${tableType} & { insertColumns: ${input}; updateColumns: ${updateInput};${optionalTable} };`,
         ];
       });
+    if (!definitions.length) {
+      return `export type ${name} = Record<string, never>;`;
+    }
     return `export type ${name} = {\n${definitions.join("\n")}\n};`;
   };
 
@@ -105,9 +108,14 @@ const reservedNames = new Set(Object.values(DB_GENERATED_NAMES) as string[]);
 
 export const validateClientSchemaName = (name: string) => {
   // Requiring a Schema suffix also avoids TypeScript keywords and primitive type names.
-  if (!/^[A-Za-z_$][\w$]*Schema$/.test(name) || reservedNames.has(name)) {
+  if (!/^[A-Za-z_$][\w$]*Schema$/.test(name)) {
     throw new Error(
       `Invalid client schema name: ${JSON.stringify(name)}. Use a unique name ending in Schema.`,
     );
   }
+  if (reservedNames.has(name)) {
+    throw new Error(
+      `Invalid client schema name: ${JSON.stringify(name)}. Use a unique name ending in Schema that does not conflict with reserved names (${Array.from(reservedNames).join(", ")}).`,
+    );
+  }
 };

package/lib/DboBuilder/TableHandler/onDeleteFromFileTable.ts

@@ -4,6 +4,11 @@ import { asName } from "prostgles-types";
 import type { FileTableConfig } from "../../ProstglesTypes";
 import type { OnCommit } from "../../PublishParser/publishTypesAndUtils";
 import { deleteUnreferencedFile } from "../../StorageClient/deleteUnreferencedFile";
+import {
+  getFileRevisionsTableHandler,
+  getFileTableHandler,
+} from "../../StorageClient/fileVersionUtils";
+import type { TableHandlers } from "../DboBuilder";
 
 type OnDeleteFromFileTableArgs = {
   returningQuery: undefined | string;
@@ -12,12 +17,14 @@ type OnDeleteFromFileTableArgs = {
     filter: AnyObject;
   };
   t: pgPromise.ITask<{}>;
+  dbx: TableHandlers;
   onCommit: OnCommit;
   isOneOrNone: boolean;
 };
+
 export const onDeleteFromFileTable = async (
   config: FileTableConfig,
-  { onCommit, t, returningQuery, filterOpts, isOneOrNone }: OnDeleteFromFileTableArgs,
+  { onCommit, t, dbx, returningQuery, filterOpts, isOneOrNone }: OnDeleteFromFileTableArgs,
 ) => {
   const { tableName } = config;
   if (config.delayedDelete) {
@@ -27,15 +34,34 @@ export const onDeleteFromFileTable = async (
     return (isOneOrNone ? result[0] : result) as undefined | AnyObject[];
   }
 
+  const fileIds =
+    config.versioning ?
+      ((await getFileTableHandler(dbx, config).find(filterOpts.filter, {
+        select: { id: 1 },
+        limit: null,
+      })) as { id: string }[])
+    : [];
+  const versionFiles =
+    fileIds.length ?
+      ((await getFileRevisionsTableHandler(dbx, config).find(
+        { file_id: { $in: fileIds.map(({ id }) => id) } },
+        { select: { storage_key: 1 }, limit: null },
+      )) as { storage_key: string }[])
+    : [];
+
   const files = await t.any<Record<string, unknown> & { _prostgles_storage_key: string }>(
     `DELETE FROM ${asName(tableName)} ${filterOpts.where}
      ${returningQuery ? `${returningQuery},` : "RETURNING"}
      COALESCE(storage_key, id) AS _prostgles_storage_key`,
   );
-  const result = files.map(({ _prostgles_storage_key, ...row }) => {
-    onCommit(({ db }) => deleteUnreferencedFile(db, config, _prostgles_storage_key));
-    return row;
-  });
+  const storageKeys = new Set([
+    ...versionFiles.map(({ storage_key }) => storage_key),
+    ...files.map(({ _prostgles_storage_key }) => _prostgles_storage_key),
+  ]);
+  for (const storageKey of storageKeys) {
+    onCommit(({ db }) => deleteUnreferencedFile(db, config, storageKey));
+  }
+  const result = files.map(({ _prostgles_storage_key, ...row }) => row);
   if (!returningQuery) return undefined;
   return (isOneOrNone ? result[0] : result) as AnyObject[] | undefined;
 };

package/lib/DboBuilder/TableHandler/updateFile.ts

@@ -33,6 +33,7 @@ export const updateFile = async (
     data,
     localParams,
     mediaId: existingFile.id,
+    version: Number(existingFile.version ?? 1) + 1,
     original_last_modified,
   });
   return { newData: omitKeys(newFile, ["id"]) };

package/lib/DboBuilder/TableHandler/uploadFile.ts

@@ -44,6 +44,7 @@ export type UploadFileArgs = TransactionCallbacks & {
    * Used to update an existing file
    */
   mediaId: string | undefined;
+  version?: number;
 };
 
 export const uploadFile = async (
@@ -54,6 +55,7 @@ export const uploadFile = async (
     original_last_modified,
     localParams,
     mediaId,
+    version,
     onCommit,
     onRollback,
   }: UploadFileArgs,
@@ -115,6 +117,7 @@ export const uploadFile = async (
     url: [fileServeRoute, coreInfo.id].join("/"),
     content_length: String(contentLength),
     data: Buffer.from([0x01]),
+    ...(config.versioning ? { version: version ?? 1 } : {}),
   };
 
   const isInsert = !mediaId;

package/lib/DboBuilder/ViewHandler/getRawInfo.ts

@@ -2,6 +2,7 @@ import { type TableInfo as TInfo } from "prostgles-types/dist";
 import type { ParsedTableRule } from "../../PublishParser/PublishParser";
 import type { LocalParams } from "../DboBuilder";
 import type { ViewHandler } from "./ViewHandler";
+import { isFileVersionTable } from "../../StorageClient/fileVersionUtils";
 
 /** Table metadata before client schema customisation. */
 export function getRawInfo(
@@ -11,7 +12,9 @@ export function getRawInfo(
   localParams?: LocalParams,
 ): TInfo {
   const validatedTableRules = this.getValidatedRules(tableRules, localParams);
-  const fileTableName = this.dboBuilder.prostgles.opts.fileTable?.tableName;
+  const fileTableConfig = this.dboBuilder.prostgles.opts.fileTable;
+  const fileTableName = fileTableConfig?.tableName;
+  const isVersionTable = isFileVersionTable(fileTableConfig, this.name);
   const allowedFieldsToSelect = this.parseFieldFilter(tableRules?.select?.fields);
   const { requiredNestedInserts, allowedNestedInserts } = tableRules?.insert ?? {};
   const label = this.dboBuilder.prostgles.tableConfigurator?.getTableLabel({
@@ -32,10 +35,11 @@ export function getRawInfo(
     isView: this.isView,
     hasFiles: Boolean(
       !this.is_media &&
+      !isVersionTable &&
       fileTableName &&
       this.columns.some((c) => c.references?.some((r) => r.ftable === fileTableName)),
     ),
-    fileTableName,
+    fileTableName: isVersionTable ? undefined : fileTableName,
     dynamicRules: {
       update: Boolean(tableRules?.update?.dynamicFields?.length),
     },

package/lib/DboBuilder/getColumns.ts

@@ -6,6 +6,7 @@ import { getErrorAsObject, getSerializedClientErrorFromPGError } from "./DboBuil
 import type { TableHandler } from "./TableHandler/TableHandler";
 import type { ViewHandler } from "./ViewHandler/ViewHandler";
 import { getRawInfo } from "./ViewHandler/getRawInfo";
+import { isFileVersionTable } from "../StorageClient/fileVersionUtils";
 
 export const isTableHandler = (v: any): v is TableHandler => "parseUpdateRules" in v;
 
@@ -173,6 +174,7 @@ const getFileColumnInfo = (args: {
   if (!fileTableConfig) return undefined;
   const { colName, tableHandler } = args;
   const tableName = tableHandler.name;
+  if (isFileVersionTable(fileTableConfig, tableName)) return undefined;
   const tableConfig = fileTableConfig.referencedTables?.[tableName];
   const isReferencingFileTable = tableHandler.columns.some(
     (c) =>

package/lib/ProstglesTypes.ts

@@ -70,6 +70,17 @@ export type FileTableConfig = {
     checkIntervalHours?: number;
   };
 
+  /**
+   * Keeps immutable metadata records for every uploaded file revision.
+   * Existing file IDs and URLs continue to resolve to the latest version.
+   */
+  versioning?: {
+    /** Defaults to `${tableName}_versions`. */
+    tableName?: string;
+    /** Maximum versions kept per file. Undefined keeps every version. */
+    maxVersions?: number;
+  };
+
   /**
    * Specifying referencedTables with referenceColumns allows restricting the
    * allowed file types that can be inserted and referenced in the specified tables.

package/lib/PublishParser/PublishParser.ts

@@ -17,6 +17,8 @@ import type {
   UnrestrictedFunctionContext,
 } from "./defineServerFunction";
 import { getFileTableRules } from "./getFileTableRules";
+import { getFileVersionTableRules } from "./getFileVersionTableRules";
+import { isFileVersionTable } from "../StorageClient/fileVersionUtils";
 import { getPublishedObjectFromResult } from "./getPublishedObjectFromResult";
 import { getSchemaFromPublish } from "./getSchemaFromPublish";
 import { getParsedPublishTable } from "./getParsedPublishTable";
@@ -313,13 +315,12 @@ export class PublishParser {
       (isAuditTable && clientReq ?
         await this.getPublishObjectForUser(clientReq, clientInfo)
       : undefined);
-    const publishRulesExcludingInferredTables =
-      await this.getParsedPublishTable({
-        clientReq,
-        tableName,
-        clientInfo,
-        resolvedPublishObject,
-      });
+    const publishRulesExcludingInferredTables = await this.getParsedPublishTable({
+      clientReq,
+      tableName,
+      clientInfo,
+      resolvedPublishObject,
+    });
     if (audit && isAuditTable) {
       const auditTableRules = await getAuditTableRules.bind(this)(
         audit,
@@ -336,6 +337,23 @@ export class PublishParser {
         scope,
       );
     }
+    const fileConfig = this.prostgles.opts.fileTable;
+    if (isFileVersionTable(fileConfig, tableName)) {
+      const versionRules = await getFileVersionTableRules.bind(this)(
+        fileConfig,
+        publishRulesExcludingInferredTables,
+        clientReq,
+        clientInfo,
+        scope,
+        overriddenPublish,
+      );
+      return applyScopeToTableRules(
+        tableName,
+        tableHandler,
+        parsePublishTableRule(versionRules),
+        scope,
+      );
+    }
     if (this.dbo[tableName]?.is_media) {
       const { rules: fileTableRules } = await getFileTableRules.bind(this)(
         tableName,

package/lib/PublishParser/getFileTableRules.ts

@@ -5,6 +5,7 @@ import { parseFieldFilter } from "../DboBuilder/ViewHandler/parseFieldFilter";
 import type { PublishParser } from "./PublishParser";
 import type { ParsedPublishTable, PublishObject, UpdateRule } from "./publishTypesAndUtils";
 import type { LocalParams } from "../DboBuilder/DboBuilder";
+import { isFileVersionTable } from "../StorageClient/fileVersionUtils";
 
 /**
  * Permissions for referencedTables columns are propagated to the file table (even if file table has no permissions)
@@ -28,7 +29,12 @@ export async function getFileTableRules(
   const forcedUpdateFilters: FullFilter<AnyObject, void>[] = [];
   const allowedNestedInserts: { table: string; column: string }[] = [];
   const referencedColumns = this.prostgles.dboBuilder.tablesOrViews
-    ?.filter((t) => !t.is_view && t.name !== fileTableName)
+    ?.filter(
+      (t) =>
+        !t.is_view &&
+        t.name !== fileTableName &&
+        !isFileVersionTable(this.prostgles.opts.fileTable, t.name),
+    )
     .map((t) => {
       const refCols = t.columns.filter((c) =>
         c.references?.some((r) => r.ftable === fileTableName),

package/lib/PublishParser/getFileVersionTableRules.spec.ts

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { FileTableConfig } from "../ProstglesTypes";
+import { parseFieldFilter } from "../DboBuilder/ViewHandler/parseFieldFilter";
+import type { PublishParser } from "./PublishParser";
+import { getFileVersionTableRules } from "./getFileVersionTableRules";
+
+void test("file version rules inherit fields and restrictive select options", async () => {
+  const fileColumns = ["id", "updated", "metadata"];
+  const versionColumns = ["id", "file_id", "created", "metadata"];
+  const getHandler = (columns: string[]) => ({
+    column_names: columns,
+    parseFieldFilter: (fields: any = "*") => parseFieldFilter(fields, true, columns),
+  });
+  const parser = {
+    dbo: {
+      files: getHandler(fileColumns),
+      files_versions: getHandler(versionColumns),
+    },
+    getTableRules: () => Promise.resolve({
+      select: {
+        fields: "*",
+        maxLimit: 5,
+        subscribeThrottle: 20,
+        disableMethods: { subscribe: 1 },
+      },
+    }),
+  } as unknown as PublishParser;
+
+  const rules = await getFileVersionTableRules.call(
+    parser,
+    { tableName: "files", versioning: {} } as FileTableConfig,
+    {
+      select: {
+        fields: "*",
+        maxLimit: 10,
+        subscribeThrottle: 10,
+        disableMethods: { sync: 1 },
+      },
+    },
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+  );
+
+  assert(rules?.select);
+  assert.deepEqual(rules.select.fields, {
+    id: 1,
+    file_id: 1,
+    created: 1,
+    metadata: 1,
+  });
+  assert.equal(rules.select.maxLimit, 5);
+  assert.equal(rules.select.subscribeThrottle, 20);
+  assert.deepEqual(rules.select.disableMethods, { subscribe: 1, sync: 1 });
+});

package/lib/PublishParser/getFileVersionTableRules.ts

@@ -0,0 +1,106 @@
+import { fromEntries } from "prostgles-types";
+import type { AuthClientRequest, AuthResultWithSID } from "../Auth/AuthTypes";
+import type { LocalParams } from "../DboBuilder/DboBuilder";
+import type { FileTableConfig } from "../ProstglesTypes";
+import type { PublishParser } from "./PublishParser";
+import type { ParsedPublishTable, PublishObject } from "./publishTypesAndUtils";
+import { getFileVersionTableName } from "../StorageClient/fileVersionUtils";
+import type { FileTableRow, FileVersionTableRow } from "../StorageClient/fileTableDefinitions";
+
+export const getFileVersionTableRules = async function (
+  this: PublishParser,
+  config: FileTableConfig,
+  explicitRules: ParsedPublishTable | undefined,
+  clientReq: AuthClientRequest | undefined,
+  clientInfo: AuthResultWithSID | undefined,
+  scope: LocalParams["scope"] | undefined,
+  resolvedPublishObject: PublishObject | undefined,
+): Promise<ParsedPublishTable | undefined> {
+  const versionTableName = getFileVersionTableName(config);
+  if (
+    resolvedPublishObject &&
+    Object.hasOwn(resolvedPublishObject, versionTableName) &&
+    !explicitRules?.select
+  ) {
+    return;
+  }
+
+  const fileRules = await this.getTableRules({
+    tableName: config.tableName,
+    clientReq,
+    clientInfo,
+    scope,
+    resolvedPublishObject,
+  });
+  if (!fileRules?.select) return;
+
+  const versionHandler = this.dbo[versionTableName];
+  if (!versionHandler) throw new Error(`File version table not found: ${versionTableName}`);
+  const fileHandler = this.dbo[config.tableName];
+  if (!fileHandler) throw new Error(`File table not found: ${config.tableName}`);
+  const select = explicitRules?.select;
+  const requestedFields = versionHandler.parseFieldFilter(select?.fields ?? "*");
+  const fileSelectFields = fileHandler.parseFieldFilter(fileRules.select.fields);
+  const fields = (versionHandler.column_names as (keyof FileVersionTableRow)[]).filter(
+    (field) =>
+      requestedFields.includes(field) &&
+      fileSelectFields.includes(getFileVersionSourceField(field)) &&
+      (fileHandler.column_names as (keyof FileTableRow)[]).includes(
+        getFileVersionSourceField(field),
+      ),
+  );
+  const requestedFilterFields = versionHandler.parseFieldFilter(select?.filterFields ?? fields);
+  const requestedOrderByFields = versionHandler.parseFieldFilter(select?.orderByFields ?? fields);
+  const inheritedFilter = {
+    $existsJoined: {
+      path: [{ table: config.tableName, on: [{ file_id: "id" }] }],
+      filter: fileRules.select.forcedFilter ?? {},
+    },
+  };
+
+  return {
+    select: {
+      ...fileRules.select,
+      ...select,
+      fields: fromEntries(fields.map((field) => [field, 1 as const] as const)),
+      filterFields: fromEntries(
+        fields
+          .filter((field) => requestedFilterFields.includes(field))
+          .map((field) => [field, 1 as const] as const),
+      ),
+      orderByFields: fromEntries(
+        fields
+          .filter((field) => requestedOrderByFields.includes(field))
+          .map((field) => [field, 1 as const] as const),
+      ),
+      forcedFilter:
+        select?.forcedFilter ? { $and: [inheritedFilter, select.forcedFilter] } : inheritedFilter,
+      maxLimit: getMostRestrictiveLimit(fileRules.select.maxLimit, select?.maxLimit),
+      subscribeThrottle: Math.max(
+        fileRules.select.subscribeThrottle ?? 0,
+        select?.subscribeThrottle ?? 0,
+      ),
+      disableMethods: {
+        ...fileRules.select.disableMethods,
+        ...select?.disableMethods,
+      },
+    },
+  };
+};
+
+const getFileVersionSourceField = (field: keyof FileVersionTableRow): keyof FileTableRow => {
+  if (field === "file_id") return "id";
+  if (field === "created") return "updated";
+  return field;
+};
+
+const getMostRestrictiveLimit = (
+  inheritedLimit: number | null | undefined,
+  explicitLimit: number | null | undefined,
+) => {
+  const limits = [inheritedLimit, explicitLimit].filter(
+    (limit): limit is number => typeof limit === "number",
+  );
+  if (limits.length) return Math.min(...limits);
+  return inheritedLimit === null || explicitLimit === null ? null : undefined;
+};

package/lib/PublishParser/getPublishedTableNames.ts

@@ -1,6 +1,7 @@
 import { isObject } from "prostgles-types";
 import type { PublishParser } from "./PublishParser";
 import { type PublishObject } from "./PublishParser";
+import { getFileVersionTableName, isFileVersionTable } from "../StorageClient/fileVersionUtils";
 
 export const getPublishedTableNames = (
   publishParserInstance: PublishParser,
@@ -24,19 +25,27 @@ export const getPublishedTableNames = (
     publishParserInstance.dbo[fileTableName]?.is_media &&
     !tableNames.includes(fileTableName)
   ) {
-    const isReferenced = publishParserInstance.prostgles.dboBuilder.tablesOrViews?.some((t) =>
-      t.columns.some((c) => c.references?.some((r) => r.ftable === fileTableName)),
+    const isReferenced = publishParserInstance.prostgles.dboBuilder.tablesOrViews?.some(
+      (t) =>
+        !isFileVersionTable(publishParserInstance.prostgles.opts.fileTable, t.name) &&
+        t.columns.some((c) => c.references?.some((r) => r.ftable === fileTableName)),
     );
     if (isReferenced) {
       tableNames.unshift(fileTableName);
     }
   }
 
+  const fileConfig = publishParserInstance.prostgles.opts.fileTable;
+  if (fileConfig?.versioning && tableNames.includes(fileConfig.tableName)) {
+    const versionTableName = getFileVersionTableName(fileConfig);
+    if (!tableNames.includes(versionTableName)) {
+      tableNames.unshift(versionTableName);
+    }
+  }
+
   const audit = publishParserInstance.prostgles.resolvedAuditConfig;
   const publishedFileTableName =
-    fileTableName && tableNames.includes(fileTableName) ?
-      fileTableName
-    : undefined;
+    fileTableName && tableNames.includes(fileTableName) ? fileTableName : undefined;
   if (
     audit &&
     !tableNames.includes(audit.tableName) &&

package/lib/StorageClient/deleteUnreferencedFile.ts

@@ -1,5 +1,6 @@
 import type { DB } from "../Prostgles";
 import type { FileTableConfig } from "../ProstglesTypes";
+import { getFileVersionTableName } from "./fileVersionUtils";
 
 export const deleteUnreferencedFile = async (
   db: DB,
@@ -11,8 +12,25 @@ export const deleteUnreferencedFile = async (
   const referenced = await db.tx(async (tx) => {
     await tx.none("SET LOCAL row_security = off");
     return tx.oneOrNone<{ found: number }>(
-      "SELECT 1 FROM ${table:name} WHERE storage_key = ${key}::uuid OR (storage_key IS NULL AND id = ${key}::uuid) LIMIT 1",
-      { table: config.tableName, key: storageKey },
+      `SELECT 1 AS found
+       WHERE EXISTS (
+         SELECT 1 FROM \${fileTable:name}
+         WHERE storage_key = \${key}::uuid OR (storage_key IS NULL AND id = \${key}::uuid)
+       )
+       ${
+         config.versioning ?
+           `OR EXISTS (
+             SELECT 1 FROM \${versionTable:name}
+             WHERE storage_key = \${key}::uuid
+           )`
+         : ""
+       }
+       LIMIT 1`,
+      {
+        fileTable: config.tableName,
+        versionTable: getFileVersionTableName(config),
+        key: storageKey,
+      },
     );
   });
   if (!referenced) await config.storageClient.delete(storageKey);

package/lib/StorageClient/fileTableDefinitions.ts

@@ -0,0 +1,52 @@
+import { omitKeys } from "prostgles-types";
+import type { TableRowFromColumnDefinitions } from "../TableConfig/TableRowFromColumnDefinitions";
+
+export const FILE_TABLE_COLUMN_DEFINITIONS = {
+  id: `UUID PRIMARY KEY DEFAULT gen_random_uuid()`,
+  /**
+   * NULL for legacy objects stored under their file ID.
+   * */
+  storage_key: `UUID UNIQUE`,
+  extension: `TEXT NOT NULL DEFAULT ''`,
+  content_type: `TEXT NOT NULL DEFAULT ''`,
+  content_length: `BIGINT NOT NULL DEFAULT 0`,
+  etag: `TEXT NOT NULL DEFAULT ''`,
+  original_name: `TEXT NOT NULL`,
+  original_last_modified: `TIMESTAMPTZ`,
+  description: `TEXT`,
+  url: `TEXT NOT NULL DEFAULT ''`,
+  cloud_url: `TEXT`,
+  signed_url: `TEXT`,
+  signed_url_expires: `BIGINT`,
+  added: `TIMESTAMP NOT NULL DEFAULT NOW()`,
+  updated: `TIMESTAMP NOT NULL DEFAULT NOW()`,
+  deleted: `TIMESTAMPTZ`,
+  deleted_from_storage: `TIMESTAMPTZ`,
+  data: `BYTEA NOT NULL CHECK (data = decode('01', 'hex'))`, // Used as a placeholder to ensure insert types are correct. Actual data is uploaded to storageClient and not stored in the DB
+} as const;
+
+export const FILE_TABLE_VERSION_COLUMN_DEFINITIONS = {
+  version: `INTEGER NOT NULL DEFAULT 1`,
+} as const;
+
+export const FILE_VERSION_TABLE_COLUMN_DEFINITIONS = {
+  ...omitKeys(FILE_TABLE_COLUMN_DEFINITIONS, ["data"]),
+  storage_key: `UUID NOT NULL`,
+  file_id: `UUID NOT NULL`, // FK constraint is added later on
+  version: `INTEGER NOT NULL`,
+  created: `TIMESTAMP NOT NULL DEFAULT NOW()`,
+} as const;
+
+export type FileTableInsertRow = TableRowFromColumnDefinitions<
+  typeof FILE_TABLE_COLUMN_DEFINITIONS
+> &
+  Partial<TableRowFromColumnDefinitions<typeof FILE_TABLE_VERSION_COLUMN_DEFINITIONS>>;
+export type FileTableRow = Required<
+  TableRowFromColumnDefinitions<typeof FILE_TABLE_COLUMN_DEFINITIONS>
+> &
+  Partial<Required<TableRowFromColumnDefinitions<typeof FILE_TABLE_VERSION_COLUMN_DEFINITIONS>>>;
+
+export type FileVersionTableInsertRow = TableRowFromColumnDefinitions<
+  typeof FILE_VERSION_TABLE_COLUMN_DEFINITIONS
+>;
+export type FileVersionTableRow = Required<FileVersionTableInsertRow>;

package/lib/StorageClient/fileVersionUtils.ts

@@ -0,0 +1,37 @@
+import type { TableHandler } from "prostgles-types";
+import type { TableHandlers } from "../DboBuilder/DboBuilder";
+import type { FileTableConfig } from "../ProstglesTypes";
+import type {
+  FileTableRow,
+  FileVersionTableInsertRow,
+  FileVersionTableRow,
+} from "./fileTableDefinitions";
+
+type FileVersionTableSchema = {
+  fileVersions: {
+    columns: FileVersionTableRow;
+    insertColumns: FileVersionTableInsertRow;
+  };
+};
+
+export const getFileVersionTableName = (config: FileTableConfig) =>
+  config.versioning?.tableName ?? `${config.tableName}_versions`;
+
+export const isFileVersionTable = (
+  config: FileTableConfig | undefined,
+  tableName: string,
+): config is FileTableConfig & { versioning: NonNullable<FileTableConfig["versioning"]> } =>
+  Boolean(config?.versioning && getFileVersionTableName(config) === tableName);
+
+export const getFileTableHandler = (dbo: TableHandlers, config: FileTableConfig) => {
+  const handler = dbo[config.tableName] as TableHandler<FileTableRow> | undefined;
+  if (!handler) throw new Error(`File table not found: ${config.tableName}`);
+  return handler;
+};
+
+export const getFileRevisionsTableHandler = (dbo: TableHandlers, config: FileTableConfig) => {
+  const handler = dbo[getFileVersionTableName(config)] as
+    TableHandler<FileVersionTableRow, FileVersionTableSchema, "fileVersions"> | undefined;
+  if (!handler) throw new Error(`File table not found: ${config.tableName}`);
+  return handler;
+};

package/lib/StorageClient/getFileStorageKey.ts

@@ -1,5 +1,14 @@
 import type { FileTableRow } from "./getFileTableConfig";
 
 /** Legacy files are stored under their logical ID. */
-export const getFileStorageKey = (file: Pick<FileTableRow, "id" | "storage_key">) =>
-  file.storage_key ?? file.id;
+export const getFileStorageKey = (
+  file: Pick<FileTableRow, "id" | "storage_key"> | { storage_key: string },
+) => {
+  const { storage_key } = file;
+  const id = "id" in file ? file.id : undefined;
+  const key = storage_key ?? id;
+  if (!key) {
+    throw new Error("Unable to determine file storage key");
+  }
+  return key;
+};

package/lib/StorageClient/getFileTableConfig.spec.ts

@@ -5,7 +5,10 @@ import { getFileTableConfig } from "./getFileTableConfig";
 
 void test("managed files preserve hooks on other tables and append file hooks", () => {
   const guard = { afterEach: [{ commands: { insert: 1 }, validate: async () => {} }] };
-  const fileGuard = { beforeEach: [{ commands: { insert: 1 }, validate: async () => {} }] };
+  const fileGuard = {
+    beforeEach: [{ commands: { insert: 1 }, validate: async () => {} }],
+    afterEach: [{ commands: { insert: 1 }, validate: async () => {} }],
+  };
   const prostgles = {
     opts: {
       fileTable: { tableName: "files", storageClient: {}, expressApp: {} },
@@ -16,4 +19,6 @@ void test("managed files preserve hooks on other tables and append file hooks",
   assert.equal(result.tableHooks?.documents, guard);
   assert.equal(result.tableHooks.files?.beforeEach?.length, 2);
   assert.equal(result.tableHooks.files.beforeEach[1], fileGuard.beforeEach[0]);
+  assert.equal(result.tableHooks.files.afterEach?.length, 2);
+  assert.equal(result.tableHooks.files.afterEach[0], fileGuard.afterEach[0]);
 });