@isrd-isi-edu/ermrestjs 2.2.0 → 2.3.0

package/js/hatrac.js

@@ -15,6 +15,7 @@ import ConfigService from '@isrd-isi-edu/ermrestjs/src/services/config';
 import { hexToBase64 } from '@isrd-isi-edu/ermrestjs/src/utils/value-utils';
 import { isObject, isObjectAndNotNull } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
 import { contextHeaderName, ENV_IS_NODE } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
+import { getFilenameExtension } from '@isrd-isi-edu/ermrestjs/src/utils/file-utils';
 
 // legacy
 import { _validateTemplate, _renderTemplate, _getFormattedKeyValues, _parseUrl } from '@isrd-isi-edu/ermrestjs/js/utils/helpers';
@@ -138,65 +139,6 @@ const _generateContextHeader = function (contextHeaderParams) {
   return headers;
 };
 
-/**
- * given a filename, will return the extension
- * By default, it will extract the last of the filename after the last `.`.
- * The second parameter can be used for passing a regular expression
- * if we want a different method of extracting the extension.
- * @param {string} filename
- * @param {string[]} allowedExtensions
- * @param {string[]} regexArr
- * @returns the filename extension string. if we cannot find any matches, it will return null
- * @private
- * @ignore
- */
-const _getFilenameExtension = function (filename, allowedExtensions, regexArr) {
-  if (typeof filename !== 'string' || filename.length === 0) {
-    return null;
-  }
-
-  // first find in the list of allowed extensions
-  var res = -1;
-  var isInAllowed =
-    Array.isArray(allowedExtensions) &&
-    allowedExtensions.some(function (ext) {
-      res = ext;
-      return typeof ext === 'string' && ext.length > 0 && filename.endsWith(ext);
-    });
-  if (isInAllowed) {
-    return res;
-  }
-
-  // we will return null if we cannot find anything
-  res = null;
-  // no matching allowed extension, try the regular expressions
-  if (Array.isArray(regexArr) && regexArr.length > 0) {
-    regexArr.some(function (regexp) {
-      // since regular expression comes from annotation, it might not be valid
-      try {
-        var matches = filename.match(new RegExp(regexp, 'g'));
-        if (matches && matches[0] && typeof matches[0] === 'string') {
-          res = matches[0];
-        } else {
-          res = null;
-        }
-        return res;
-      } catch {
-        res = null;
-        return false;
-      }
-    });
-  } else {
-    var dotIndex = filename.lastIndexOf('.');
-    // it's only a valid filename if there's some string after `.`
-    if (dotIndex !== -1 && dotIndex !== filename.length - 1) {
-      res = filename.slice(dotIndex);
-    }
-  }
-
-  return res;
-};
-
 /**
  * @desc upload Object
  * Create a new instance with new upload(file, otherInfo)
@@ -801,7 +743,7 @@ Upload.prototype._generateURL = function (row, linkedData, templateVariables) {
   row[this.column.name].md5_base64 = this.hash.md5_base64;
   row[this.column.name].sha256 = this.hash.sha256;
   row[this.column.name].filename = this.file.name;
-  var filename_ext = _getFilenameExtension(this.file.name, this.column.filenameExtFilter, this.column.filenameExtRegexp);
+  var filename_ext = getFilenameExtension(this.file.name, this.column.filenameExtFilter, this.column.filenameExtRegexp);
   row[this.column.name].filename_ext = filename_ext;
   // filename_basename is everything from the file name except the last ext
   // For example if we have a file named "file.tar.zip"

package/js/utils/helpers.js

@@ -404,7 +404,7 @@ import AuthnService from '@isrd-isi-edu/ermrestjs/src/services/authn';
 
     /**
     * @param {string} context the context that we want the value of.
-    * @param {Object} annotation the annotation object.
+    * @param {any} annotation the annotation object.
     * @param {Boolean=} dontUseDefaultContext Whether we should use the default (*) context
     * @desc returns the annotation value based on the given context.
     */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@isrd-isi-edu/ermrestjs",
   "description": "ERMrest client library in JavaScript",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">= 20.0.0",

package/src/index.ts

@@ -77,6 +77,7 @@ import HandlebarsService from '@isrd-isi-edu/ermrestjs/src/services/handlebars';
 import { Exporter } from '@isrd-isi-edu/ermrestjs/js/export';
 import validateJSONLD from '@isrd-isi-edu/ermrestjs/js/json_ld_validator.js';
 import HistoryService from '@isrd-isi-edu/ermrestjs/src/services/history';
+import FilePreviewService from '@isrd-isi-edu/ermrestjs/src/services/file-preview';
 
 const logError = ErrorService.logError;
 const responseToError = ErrorService.responseToError;
@@ -111,6 +112,7 @@ export {
   AuthnService,
   Exporter,
   HistoryService,
+  FilePreviewService,
 
   // constants
   contextHeaderName,

package/src/models/reference-column/asset-pseudo-column.ts

@@ -3,10 +3,14 @@ import { ReferenceColumn, ReferenceColumnTypes } from '@isrd-isi-edu/ermrestjs/s
 import type SourceObjectWrapper from '@isrd-isi-edu/ermrestjs/src/models/source-object-wrapper';
 import type { Reference, Tuple, VisibleColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference';
 
+// services
+import { FilePreviewTypes, isFilePreviewType, USE_EXT_MAPPING } from '@isrd-isi-edu/ermrestjs/src/services/file-preview';
+
 // utils
 import { renderMarkdown } from '@isrd-isi-edu/ermrestjs/src/utils/markdown-utils';
 import { isDefinedAndNotNull, isObjectAndKeyExists, isObjectAndNotNull, isStringAndNotEmpty } from '@isrd-isi-edu/ermrestjs/src/utils/type-utils';
 import { _annotations, _contexts, _classNames } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
+import { getFilename } from '@isrd-isi-edu/ermrestjs/src/utils/file-utils';
 
 // legacy
 import { _getAnnotationValueByContext, _isEntryContext, _renderTemplate, _isSameHost } from '@isrd-isi-edu/ermrestjs/js/utils/helpers';
@@ -70,7 +74,7 @@ export class AssetPseudoColumn extends ReferenceColumn {
   private _filenameExtFilter?: string[];
   private _filenameExtRegexp?: string[];
   private _displayImagePreview?: boolean;
-  private _filePreview?: null | { showCsvHeader: boolean };
+  private _filePreview?: FilePreviewConfig | null;
 
   constructor(reference: Reference, column: Column, sourceObjectWrapper?: SourceObjectWrapper, name?: string, mainTuple?: Tuple) {
     // call the parent constructor
@@ -168,17 +172,9 @@ export class AssetPseudoColumn extends ReferenceColumn {
 
     // if we're using the url as caption
     if (urlCaption) {
-      // if caption matches the expected format, just show the file name
-      // eslint-disable-next-line no-useless-escape
-      const parts = caption.match(/^\/hatrac\/([^\/]+\/)*([^\/:]+)(:[^:]+)?$/);
-      if (parts && parts.length === 4) {
-        caption = parts[2];
-      } else {
-        // otherwise return the last part of url
-        const newCaption = caption.split('/').pop();
-        if (newCaption && newCaption.length !== 0) {
-          caption = newCaption;
-        }
+      const newCaption = getFilename(caption);
+      if (newCaption && newCaption.length !== 0) {
+        caption = newCaption;
       }
     }
 
@@ -457,7 +453,7 @@ export class AssetPseudoColumn extends ReferenceColumn {
   /**
    * whether we should show the file preview or not
    */
-  get filePreview(): null | { showCsvHeader: boolean } {
+  get filePreview(): FilePreviewConfig | null {
     if (this._filePreview === undefined) {
       const disp = this._annotation.display;
       const currDisplay = isObjectAndNotNull(disp) ? _getAnnotationValueByContext(this._context, disp) : null;
@@ -465,12 +461,7 @@ export class AssetPseudoColumn extends ReferenceColumn {
       if (settings === false) {
         this._filePreview = null;
       } else {
-        // by default we're hiding the CSV header.
-        let showCsvHeader = false;
-        if (isObjectAndKeyExists(settings, 'show_csv_header') && typeof settings.show_csv_header === 'boolean') {
-          showCsvHeader = settings.show_csv_header;
-        }
-        this._filePreview = { showCsvHeader };
+        this._filePreview = new FilePreviewConfig(settings);
       }
     }
     return this._filePreview;
@@ -496,3 +487,234 @@ export class AssetPseudoColumn extends ReferenceColumn {
     return this._waitFor;
   }
 }
+
+class FilePreviewConfig {
+  private static previewTypes = Object.values(FilePreviewTypes);
+
+  /**
+   * whether we should show the CSV header or not
+   * (default: false)
+   */
+  showCsvHeader: boolean = false;
+
+  /**
+   * the height of the preview container
+   */
+  defaultHeight: number | null = null;
+
+  private _prefetchBytes: { [key: string]: number | null } = {
+    image: null,
+    markdown: null,
+    csv: null,
+    tsv: null,
+    json: null,
+    text: null,
+  };
+
+  private _prefetchMaxFileSize: { [key: string]: number | null } = {
+    image: null,
+    markdown: null,
+    csv: null,
+    tsv: null,
+    json: null,
+    text: null,
+  };
+
+  filenameExtMapping: { [key: string]: FilePreviewTypes | false } | null = null;
+
+  contentTypeMapping: {
+    exactMatch: { [key: string]: FilePreviewTypes | typeof USE_EXT_MAPPING | false } | null;
+    prefixMatch: { [key: string]: FilePreviewTypes | typeof USE_EXT_MAPPING | false } | null;
+    default: FilePreviewTypes | typeof USE_EXT_MAPPING | false | null;
+  } | null = null;
+
+  disabledTypes: FilePreviewTypes[] = [];
+
+  /**
+   * populate the props based on the given annotation object.
+   * The supported annotation properties are:
+   * - show_csv_header
+   * - default_height
+   * - prefetch_bytes
+   * - prefetch_max_file_size
+   * - filename_ext_mapping
+   * - content_type_mapping
+   * - disabled
+   */
+  constructor(settings: any) {
+    if (isObjectAndKeyExists(settings, 'show_csv_header') && typeof settings.show_csv_header === 'boolean') {
+      this.showCsvHeader = settings.show_csv_header;
+    }
+
+    if (isObjectAndKeyExists(settings, 'default_height') && typeof settings.default_height === 'number' && settings.default_height >= 0) {
+      this.defaultHeight = settings.default_height;
+    }
+
+    this._prefetchBytes = this._populateProps<number>(settings, 'prefetch_bytes', (value: unknown) => {
+      return typeof value === 'number' && value >= 0;
+    });
+
+    this._prefetchMaxFileSize = this._populateProps<number>(settings, 'prefetch_max_file_size', (value: unknown) => {
+      return typeof value === 'number' && value >= 0;
+    });
+
+    if (isObjectAndKeyExists(settings, 'filename_ext_mapping')) {
+      this.filenameExtMapping = {};
+      for (const [key, val] of Object.entries(settings.filename_ext_mapping)) {
+        if (val === false || (typeof val === 'string' && isFilePreviewType(val))) {
+          this.filenameExtMapping[key] = val;
+        }
+      }
+    }
+
+    if (isObjectAndKeyExists(settings, 'content_type_mapping')) {
+      const exactMatch: { [key: string]: FilePreviewTypes | typeof USE_EXT_MAPPING | false } = {};
+      const prefixMatch: { [key: string]: FilePreviewTypes | typeof USE_EXT_MAPPING | false } = {};
+      let defaultMapping: FilePreviewTypes | typeof USE_EXT_MAPPING | false | null = null;
+      let hasExactMatch = false;
+      let hasPrefixMatch = false;
+      Object.keys(settings.content_type_mapping).forEach((key) => {
+        const val = settings.content_type_mapping[key];
+        const validValue = val === false || (typeof val === 'string' && (isFilePreviewType(val) || val === USE_EXT_MAPPING));
+        if (!validValue) return;
+        // * could be used for default mapping
+        if (key === '*') {
+          defaultMapping = val;
+          return;
+        }
+
+        // only type/ or type/subtype are valid
+        const parts = key.split('/');
+        if (parts.length !== 2 || parts[0].length === 0) return;
+
+        if (parts[1].length > 0) {
+          exactMatch[key] = val;
+          hasExactMatch = true;
+        } else {
+          prefixMatch[parts[0] + '/'] = val;
+          hasPrefixMatch = true;
+        }
+      });
+
+      if (hasPrefixMatch || hasExactMatch || defaultMapping !== null) {
+        this.contentTypeMapping = {
+          exactMatch: hasExactMatch ? exactMatch : null,
+          prefixMatch: hasPrefixMatch ? prefixMatch : null,
+          default: defaultMapping,
+        };
+      }
+    }
+
+    if (isObjectAndKeyExists(settings, 'disabled') && Array.isArray(settings.disabled)) {
+      this.disabledTypes = settings.disabled.filter(
+        (t: unknown) => typeof t === 'string' && FilePreviewConfig.previewTypes.includes(t as FilePreviewTypes),
+      );
+    }
+  }
+
+  /**
+   * return the number of bytes to prefetch for previewing the file
+   */
+  getPrefetchBytes(filePreviewType: FilePreviewTypes | null): number | null {
+    switch (filePreviewType) {
+      case FilePreviewTypes.IMAGE:
+        return this._prefetchBytes.image;
+      case FilePreviewTypes.MARKDOWN:
+        return this._prefetchBytes.markdown;
+      case FilePreviewTypes.CSV:
+        return this._prefetchBytes.csv;
+      case FilePreviewTypes.TSV:
+        return this._prefetchBytes.tsv;
+      case FilePreviewTypes.JSON:
+        return this._prefetchBytes.json;
+      case FilePreviewTypes.TEXT:
+        return this._prefetchBytes.text;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * return the max file size for previewing the file
+   */
+  getPrefetchMaxFileSize(filePreviewType: FilePreviewTypes | null): number | null {
+    switch (filePreviewType) {
+      case FilePreviewTypes.IMAGE:
+        return this._prefetchMaxFileSize.image;
+      case FilePreviewTypes.MARKDOWN:
+        return this._prefetchMaxFileSize.markdown;
+      case FilePreviewTypes.CSV:
+        return this._prefetchMaxFileSize.csv;
+      case FilePreviewTypes.TSV:
+        return this._prefetchMaxFileSize.tsv;
+      case FilePreviewTypes.JSON:
+        return this._prefetchMaxFileSize.json;
+      case FilePreviewTypes.TEXT:
+        return this._prefetchMaxFileSize.text;
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * The settings could be either just one value or an object with different values for each type.
+   * This function will populate the result object with the appropriate values for each type.
+   */
+  private _populateProps<T>(settings: any, propName: string, validate?: (value: unknown) => boolean): { [key: string]: T | null } {
+    const res: { [key: string]: T | null } = {
+      text: null,
+      markdown: null,
+      csv: null,
+      tsv: null,
+      json: null,
+      image: null,
+    };
+    if (!isObjectAndKeyExists(settings, propName)) return res;
+
+    if (isObjectAndNotNull(settings[propName])) {
+      // for each preview type, try to get its value (which will fall back to * if not defined)
+      for (const key of FilePreviewConfig.previewTypes) {
+        const definedRes = this._getPropForType(key, settings[propName]);
+        if (!validate || validate(definedRes)) {
+          res[key] = definedRes;
+        }
+      }
+    } else {
+      const definedRes = settings[propName];
+      if (!validate || validate(definedRes)) {
+        for (const key of FilePreviewConfig.previewTypes) {
+          res[key] = definedRes;
+        }
+      }
+    }
+
+    return res;
+  }
+
+  /**
+   * Get the property for a specific file type. If not defined, will try to get the default value (*).
+   * Otherwise returns null.
+   */
+  private _getPropForType(fileType: string, settings: any): any {
+    const DEFAULT_TYPE = '*';
+
+    let isDefined = false;
+    let res;
+    if (isObjectAndKeyExists(settings, fileType)) {
+      if (typeof settings[fileType] === 'string' && settings[fileType] in FilePreviewConfig.previewTypes) {
+        res = this._getPropForType(settings[fileType], settings);
+      } else {
+        res = settings[fileType];
+      }
+
+      if (res !== null && res !== undefined) isDefined = true;
+    }
+
+    if (!isDefined && settings[DEFAULT_TYPE]) {
+      res = this._getPropForType(DEFAULT_TYPE, settings);
+      if (res !== null && res !== undefined) isDefined = true;
+    }
+
+    return isDefined ? res : null;
+  }
+}

package/src/services/file-preview.ts

@@ -0,0 +1,229 @@
+import type { AssetPseudoColumn } from '@isrd-isi-edu/ermrestjs/src/models/reference-column';
+import { FILE_PREVIEW } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
+
+import { getFilename, getFilenameExtension } from '@isrd-isi-edu/ermrestjs/src/utils/file-utils';
+import $log from '@isrd-isi-edu/ermrestjs/src/services/logger';
+
+/**
+ * The supported file preview types
+ */
+export enum FilePreviewTypes {
+  IMAGE = 'image',
+  MARKDOWN = 'markdown',
+  CSV = 'csv',
+  TSV = 'tsv',
+  JSON = 'json',
+  TEXT = 'text',
+}
+
+/**
+ * Type guard to check if a value is a FilePreviewTypes
+ */
+export const isFilePreviewType = (value: unknown): value is FilePreviewTypes => {
+  if (typeof value !== 'string') return false;
+  return Object.values(FilePreviewTypes).includes(value as FilePreviewTypes);
+};
+
+export const USE_EXT_MAPPING = 'use_ext_mapping';
+
+const DEFAULT_CONTENT_TYPE_MAPPING: { [key: string]: FilePreviewTypes | typeof USE_EXT_MAPPING | false } = {
+  // image:
+  'image/png': FilePreviewTypes.IMAGE,
+  'image/jpeg': FilePreviewTypes.IMAGE,
+  'image/jpg': FilePreviewTypes.IMAGE,
+  'image/gif': FilePreviewTypes.IMAGE,
+  'image/bmp': FilePreviewTypes.IMAGE,
+  'image/webp': FilePreviewTypes.IMAGE,
+  'image/svg+xml': FilePreviewTypes.IMAGE,
+  'image/x-icon': FilePreviewTypes.IMAGE,
+  'image/avif': FilePreviewTypes.IMAGE,
+  'image/apng': FilePreviewTypes.IMAGE,
+  // markdown:
+  'text/markdown': FilePreviewTypes.MARKDOWN,
+  // csv:
+  'text/csv': FilePreviewTypes.CSV,
+  // tsv:
+  'text/tab-separated-values': FilePreviewTypes.TSV,
+  // json:
+  'application/json': FilePreviewTypes.JSON,
+  // text:
+  'chemical/x-mmcif': FilePreviewTypes.TEXT,
+  'chemical/x-cif': FilePreviewTypes.TEXT,
+  // generic:
+  'text/plain': USE_EXT_MAPPING,
+  'application/octet-stream': USE_EXT_MAPPING,
+};
+
+const DEFAULT_EXTENSION_MAPPING: { [key: string]: FilePreviewTypes | false } = {
+  // image:
+  '.png': FilePreviewTypes.IMAGE,
+  '.jpeg': FilePreviewTypes.IMAGE,
+  '.jpg': FilePreviewTypes.IMAGE,
+  '.gif': FilePreviewTypes.IMAGE,
+  '.bmp': FilePreviewTypes.IMAGE,
+  '.webp': FilePreviewTypes.IMAGE,
+  '.svg': FilePreviewTypes.IMAGE,
+  '.ico': FilePreviewTypes.IMAGE,
+  '.avif': FilePreviewTypes.IMAGE,
+  '.apng': FilePreviewTypes.IMAGE,
+  // markdown:
+  '.md': FilePreviewTypes.MARKDOWN,
+  '.markdown': FilePreviewTypes.MARKDOWN,
+  // csv:
+  '.csv': FilePreviewTypes.CSV,
+  // tsv:
+  '.tsv': FilePreviewTypes.TSV,
+  // json:
+  '.json': FilePreviewTypes.JSON,
+  '.mvsj': FilePreviewTypes.JSON, // MolViewSpec JSON (mol* viewer)
+  // text:
+  '.txt': FilePreviewTypes.TEXT,
+  '.log': FilePreviewTypes.TEXT,
+  '.cif': FilePreviewTypes.TEXT,
+  '.pdb': FilePreviewTypes.TEXT,
+};
+
+export default class FilePreviewService {
+  /**
+   * Returns the preview info based on the given file properties and the column's file preview settings.
+   * @param url the file url
+   * @param column the asset column
+   * @param storedFilename the stored filename
+   * @param contentDisposition content-disposition header value
+   * @param contentType content-type header value
+   */
+  static getFilePreviewInfo(
+    url: string,
+    column?: AssetPseudoColumn,
+    storedFilename?: string,
+    contentDisposition?: string,
+    contentType?: string,
+  ): {
+    previewType: FilePreviewTypes | null;
+    prefetchBytes: number | null;
+    prefetchMaxFileSize: number | null;
+  } {
+    const disabledValue = { previewType: null, prefetchBytes: null, prefetchMaxFileSize: null };
+    const previewType = FilePreviewService.getFilePreviewType(url, column, storedFilename, contentDisposition, contentType);
+    let prefetchBytes: number | null = null;
+    let prefetchMaxFileSize: number | null = null;
+
+    if (previewType === null) {
+      return disabledValue;
+    }
+
+    if (column && column.filePreview) {
+      if (column.filePreview.disabledTypes.includes(previewType)) {
+        return disabledValue;
+      }
+      prefetchBytes = column.filePreview.getPrefetchBytes(previewType);
+      prefetchMaxFileSize = column.filePreview.getPrefetchMaxFileSize(previewType);
+    }
+
+    if (typeof prefetchBytes !== 'number' || prefetchBytes < 0) {
+      prefetchBytes = FILE_PREVIEW.PREFETCH_BYTES;
+    }
+    if (typeof prefetchMaxFileSize !== 'number' || prefetchMaxFileSize < 0) {
+      prefetchMaxFileSize = FILE_PREVIEW.MAX_FILE_SIZE;
+    }
+
+    // if prefetchMaxFileSize is 0, we should not show the preview
+    if (prefetchMaxFileSize === 0) {
+      return disabledValue;
+    }
+
+    return { previewType, prefetchBytes, prefetchMaxFileSize };
+  }
+
+  /**
+   * Returns the preview type based on the given file properties and the column's file preview settings.
+   * @param url the file url
+   * @param column the asset column
+   * @param storedFilename the stored filename
+   * @param contentDisposition content-disposition header value
+   * @param contentType content-type header value
+   */
+  private static getFilePreviewType(
+    url: string,
+    column?: AssetPseudoColumn,
+    storedFilename?: string,
+    contentDisposition?: string,
+    contentType?: string,
+  ): FilePreviewTypes | null {
+    const filename = storedFilename || getFilename(url, contentDisposition);
+    const extension = getFilenameExtension(filename, column?.filenameExtFilter, column?.filenameExtRegexp);
+    let mappedFilePreviewType: FilePreviewTypes | typeof USE_EXT_MAPPING | false = USE_EXT_MAPPING;
+
+    // extend the mappings based on the annotations
+    let annotExtensionMapping;
+    let annotContentTypeMapping;
+    if (column && column.isAsset) {
+      // if file_preview is false, then no preview is allowed
+      if (!column.filePreview) return null;
+      if (column.filePreview.contentTypeMapping) {
+        annotContentTypeMapping = column.filePreview.contentTypeMapping;
+      }
+      if (column.filePreview.filenameExtMapping) {
+        annotExtensionMapping = column.filePreview.filenameExtMapping;
+      }
+    }
+
+    // if content-type is available, we must get the type from it.
+    if (typeof contentType === 'string' && contentType.length > 0) {
+      // remove any extra info like charset
+      contentType = contentType.split(';')[0].trim().toLowerCase();
+      let matched = false;
+
+      // first match through annotation mapping
+      if (annotContentTypeMapping) {
+        // if the exact match is found, use it
+        if (annotContentTypeMapping.exactMatch && contentType in annotContentTypeMapping.exactMatch) {
+          mappedFilePreviewType = annotContentTypeMapping.exactMatch[contentType];
+          matched = true;
+        }
+        // if exact match not found, try prefix matching
+        else if (annotContentTypeMapping.prefixMatch) {
+          const match = Object.keys(annotContentTypeMapping.prefixMatch).find((prefix) => contentType!.startsWith(prefix));
+          if (match) {
+            mappedFilePreviewType = annotContentTypeMapping.prefixMatch[match];
+            matched = true;
+          }
+        }
+
+        // if still not matched, check for default mapping (`*` in annotation)
+        if (!matched && annotContentTypeMapping.default !== null) {
+          mappedFilePreviewType = annotContentTypeMapping.default;
+          matched = true;
+        }
+      }
+
+      // if no match found through annotation, try the default mapping
+      if (!matched && contentType in DEFAULT_CONTENT_TYPE_MAPPING) {
+        mappedFilePreviewType = DEFAULT_CONTENT_TYPE_MAPPING[contentType];
+        matched = true;
+      }
+
+      // if no match found, disable the preview
+      if (!matched) {
+        mappedFilePreviewType = false;
+      }
+
+      $log.debug(`FilePreviewService: Mapped content-type '${contentType}' to preview type '${mappedFilePreviewType}'`);
+    }
+
+    // use extenstion mapping, if the content-type matching dictates so
+    if (mappedFilePreviewType === USE_EXT_MAPPING && typeof extension === 'string' && extension.length > 0) {
+      if (annotExtensionMapping && extension in annotExtensionMapping) {
+        mappedFilePreviewType = annotExtensionMapping[extension];
+      } else if (extension in DEFAULT_EXTENSION_MAPPING) {
+        mappedFilePreviewType = DEFAULT_EXTENSION_MAPPING[extension];
+      } else {
+        mappedFilePreviewType = false;
+      }
+
+      $log.debug(`FilePreviewService: Mapped extension '${extension}' to preview type '${mappedFilePreviewType}'`);
+    }
+
+    return isFilePreviewType(mappedFilePreviewType) ? mappedFilePreviewType : null;
+  }
+}

package/src/services/logger.ts

@@ -1,5 +1,4 @@
 /* eslint-disable @typescript-eslint/no-duplicate-enum-values */
-/* eslint-disable @typescript-eslint/no-explicit-any */
 
 import { ENV_IS_DEV_MODE } from '@isrd-isi-edu/ermrestjs/src/utils/constants';
 
@@ -32,32 +31,32 @@ class Logger {
     this._level = level;
   }
 
-  public trace(...args: any[]): void {
+  public trace(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.TRACE)) return;
     console.trace(...args);
   }
 
-  public debug(...args: any[]): void {
+  public debug(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.DEBUG)) return;
     console.debug(...args);
   }
 
-  public info(...args: any[]): void {
+  public info(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.INFO)) return;
     console.info(...args);
   }
 
-  public log(...args: any[]): void {
+  public log(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.LOG)) return;
     console.log(...args);
   }
 
-  public warn(...args: any[]): void {
+  public warn(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.WARN)) return;
     console.warn(...args);
   }
 
-  public error(...args: any[]): void {
+  public error(...args: unknown[]): void {
     if (!this.isAllowed(LoggerLevels.ERROR)) return;
     console.error(...args);
   }

package/src/utils/constants.ts

@@ -27,6 +27,11 @@ export const URL_PATH_LENGTH_LIMIT = 4000;
  */
 export const CONTEXT_HEADER_LENGTH_LIMIT = 6500;
 
+export const FILE_PREVIEW = {
+  PREFETCH_BYTES: 0.5 * 1024 * 1024,
+  MAX_FILE_SIZE: 1 * 1024 * 1024,
+};
+
 export enum _constraintTypes {
   KEY = 'k',
   FOREIGN_KEY = 'fk',

package/src/utils/file-utils.ts

@@ -0,0 +1,198 @@
+/**
+ * given a url and optional content-disposition header, will return the filename.
+ *
+ * NOTE: might return an empty string if no filename is found.
+ */
+export const getFilename = (url: string, contentDisposition?: string): string => {
+  if (contentDisposition) {
+    // try UTF-8 encoded filename first
+    const prefixUTF8 = "filename*=UTF-8''";
+    let filenameIndex = contentDisposition.indexOf(prefixUTF8);
+    if (filenameIndex !== -1) {
+      const filename = contentDisposition.substring(filenameIndex + prefixUTF8.length);
+      if (filename) return filename.replace(/"/g, '');
+    }
+
+    // try standard filename=
+    const prefixStandard = 'filename=';
+    filenameIndex = contentDisposition.indexOf(prefixStandard);
+    if (filenameIndex !== -1) {
+      let filename = contentDisposition.substring(filenameIndex + prefixStandard.length);
+      // remove quotes and any trailing content after semicolon
+      filename = filename.split(';')[0].replace(/"/g, '').trim();
+      if (filename) return filename;
+    }
+  }
+
+  // hatrac files have a different format
+  // eslint-disable-next-line no-useless-escape
+  const parts = url.match(/^\/hatrac\/([^\/]+\/)*([^\/:]+)(:[^:]+)?$/);
+  if (parts && parts.length === 4) {
+    return parts[2];
+  }
+
+  // strip query parameters and fragments from URL
+  const cleanUrl = url.split('?')[0].split('#')[0];
+  return cleanUrl.split('/').pop() || '';
+};
+
+/**
+ * given a filename, will return the extension
+ * By default, it will extract the last of the filename after the last `.` (including the dot).
+ * The second parameter can be used for passing a regular expression
+ * if we want a different method of extracting the extension.
+ * @param {string} filename
+ * @param {string[]} allowedExtensions
+ * @param {string[]} regexArr
+ * @returns the filename extension string. if we cannot find any matches, it will return null
+ * @private
+ * @ignore
+ */
+export const getFilenameExtension = function (filename: string, allowedExtensions?: string[], regexArr?: string[]): string | null {
+  if (typeof filename !== 'string' || filename.length === 0) {
+    return null;
+  }
+
+  // first find in the list of allowed extensions (case-insensitive)
+  let res: string | null = null;
+  const filenameLower = filename.toLowerCase();
+  const isInAllowed =
+    Array.isArray(allowedExtensions) &&
+    allowedExtensions.some((ext) => {
+      res = ext;
+      return typeof ext === 'string' && ext.length > 0 && filenameLower.endsWith(ext.toLowerCase());
+    });
+  if (isInAllowed) {
+    return res;
+  }
+
+  // we will return null if we cannot find anything
+  res = null;
+  // no matching allowed extension, try the regular expressions
+  if (Array.isArray(regexArr) && regexArr.length > 0) {
+    regexArr.some((regexp) => {
+      // since regular expression comes from annotation, it might not be valid
+      try {
+        const matches = filename.match(new RegExp(regexp, 'g'));
+        if (matches && matches[0] && typeof matches[0] === 'string') {
+          res = matches[0];
+        } else {
+          res = null;
+        }
+        return res;
+      } catch {
+        res = null;
+        return false;
+      }
+    });
+  } else {
+    const dotIndex = filename.lastIndexOf('.');
+    // it's only a valid filename if there's some string after `.`
+    if (dotIndex !== -1 && dotIndex !== filename.length - 1) {
+      res = filename.slice(dotIndex).toLowerCase();
+    }
+  }
+
+  return res;
+};
+
+/**
+ * Check if file is a text-like file based on content type or extension
+ */
+export const checkIsTextFile = (contentType?: string, extension?: string | null): boolean => {
+  // text-like files using content-type
+  if (
+    contentType &&
+    (contentType.startsWith('text/') ||
+      // cif files
+      contentType === 'chemical/x-mmcif' ||
+      contentType === 'chemical/x-cif')
+  ) {
+    return true;
+  }
+
+  // text-like files using extension
+  if (extension && ['.txt', '.js', '.log', '.cif', '.pdb'].includes(extension)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if file is markdown based on content type or extension
+ */
+export const checkIsMarkdownFile = (contentType?: string, extension?: string | null): boolean => {
+  if (contentType && (contentType.includes('markdown') || contentType.includes('md'))) {
+    return true;
+  }
+
+  if (extension && ['.md', '.markdown'].includes(extension)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if file is CSV based on content type or extension
+ */
+export const checkIsCsvFile = (contentType?: string, extension?: string | null): boolean => {
+  if (contentType && (contentType.includes('csv') || contentType.includes('comma-separated-values'))) {
+    return true;
+  }
+
+  if (extension && extension === '.csv') {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if file is TSV based on content type or extension
+ */
+export const checkIsTsvFile = (contentType?: string, extension?: string | null): boolean => {
+  if (contentType && contentType.includes('tab-separated-values')) {
+    return true;
+  }
+
+  if (extension && extension === '.tsv') {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if file is JSON based on content type or extension
+ */
+export const checkIsJSONFile = (contentType?: string, extension?: string | null): boolean => {
+  if (contentType && contentType.includes('application/json')) {
+    return true;
+  }
+
+  // mvsj: MolViewSpec JSON (mol* viewer)
+  if (extension && ['.json', '.mvsj'].includes(extension)) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Check if file is an image based on content type or extension
+ * Checks for common image formats supported by HTML img tag
+ */
+export const checkIsImageFile = (contentType?: string, extension?: string | null): boolean => {
+  // TODO this should be more specific based on supported image formats
+  if (contentType && contentType.startsWith('image/')) {
+    return true;
+  }
+
+  if (extension && ['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg', '.ico', '.avif', '.apng'].includes(extension)) {
+    return true;
+  }
+
+  return false;
+};