Member Junction
    Preparing search index...

    Class FileStorageEngine

    Server-side file storage engine providing high-level operations for uploading, downloading, and managing files in MJ Storage.

    Follows the containment pattern (like AIEngine wraps AIEngineBase):

    Client-side code should use FileStorageEngineBase from @memberjunction/core-entities for metadata-only access (accounts, providers, lookups).

    Usage:

    import { FileStorageEngine } from '@memberjunction/storage';

    const engine = FileStorageEngine.Instance;
    await engine.Config(false, contextUser);

    // Upload a file
    const result = await engine.UploadFile({
        content: Buffer.from(base64Data, 'base64'),
        fileName: 'report.pdf',
        mimeType: 'application/pdf',
        contextUser
    });

    // Get a driver for direct operations
    const driver = await engine.GetDriver(accountId, contextUser);
    const objects = await driver.ListObjects('/');

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Accessors

    Accounts AccountsWithProviders Base GlobalKey HasStorageAccounts Loaded Providers Instance

    Methods

    Config GetAccountById GetAccountByName GetAccountsByProviderID GetAccountWithProvider GetDriver GetGlobalObjectStore GetProviderById RefreshAfterMiss RefreshDriverCache ResolveFileObject ResolveStorageAccount UploadFile getInstance

    Constructors

    Accessors

    • get GlobalKey(): string

      Returns string

    Methods

    • Configures the engine by loading the underlying metadata cache and any server-specific state. Safe to call multiple times — uses cached data unless forceRefresh is true. Concurrent callers share a single loading promise to avoid redundant work.

      Parameters

      Returns Promise<void>

    • Returns an authenticated storage driver for a given account.

      Checks the pre-initialized driver cache first (populated during Config()). If the account wasn't cached (e.g., it failed during Config or was added after), falls back to on-demand initialization.

      This handles:

      • Looking up the account and provider from cached metadata
      • Decrypting credentials via the Credential Engine
      • Setting up OAuth token refresh callbacks for providers like Box

      No permission check. The driver cache is process-wide and this method does not ask whether contextUser may use the account. Code acting for a user must call StorageAccessEvaluator.AssertAccountAccess (or AccessibleAccountIDs) first — the MJServer storage routes, the File Storage core actions and the search lane do — and, going from an MJ: Files row to its object, should use ResolveFileObject instead.

      Parameters

      • accountId: string

        The FileStorageAccount ID to get a driver for

      • contextUser: UserInfo

        User context for credential decryption (used for on-demand init)

      Returns Promise<FileStorageBase>

      An initialized, ready-to-use FileStorageBase driver

      Error if the account is not found or driver initialization fails

    • The Global Object Store is a place to store global objects that need to be shared across the application. Depending on the execution environment, this could be the window object in a browser, or the global object in a node environment, or something else in other contexts. The key here is that in some cases static variables are not truly shared because it is possible that a given class might have copies of its code in multiple paths in a deployed application. This approach ensures that no matter how many code copies might exist, there is only one instance of the object in question by using the Global Object Store.

      Returns GlobalObjectStore

    • Reloads the shared account cache after a lookup missed, as the MJ system user. A forced Config loads as the user it is given, and BaseEngine empties a config that user cannot read (MJ: File Storage Accounts), so a restricted caller forcing the reload would blank the cache, and re-initialize every driver, for everyone. With no system user nothing is reloaded and the miss stands.

      Parameters

      Returns Promise<void>

    • Initializes storage drivers for all active accounts and caches them. Called automatically during Config(). Can also be called independently to re-initialize drivers without reloading metadata (e.g., after credential rotation). Accounts that fail to initialize are logged and skipped — they will fall back to on-demand initialization when GetDriver() is called.

      Returns Promise<void>

    • Resolves an MJ: Files row to the account, driver and object key that serve its bytes — and refuses unless contextUser may use that account for access and may read every MJ: Files row that tracks the object.

      Every route that goes from a file ID to bytes or a URL uses this: the row names only a PROVIDER (and ProviderKey / Name are written by whoever saved the row), so without the account gate a row could reach an account the caller is refused, and without the tracked-file rule a second row could alias an object whose own row the caller cannot read. Load the row as the caller first — this decides storage access, not whether the caller may see the row.

      Parameters

      • file: StorageFileLocation

        The row's storage location (ProviderID, ProviderKey, Name)

      • contextUser: UserInfo

        The caller the decision is for

      • access: StorageAccountAccess = 'Read'

        Read to download or sign a URL; Write to delete, rename or overwrite the object

      • Optionalprovider: IMetadataProvider

        The metadata provider to read permissions through; defaults to Metadata.Provider

      Returns Promise<ResolvedFileObject>

      The resolved object, or null when the row's provider has no storage account

      StorageAccountAccessDeniedError when the account refuses access; TrackedFileAccessDeniedError when a row tracking the object is not readable by the caller

    • Resolves a storage account to use for file operations.

      Resolution logic:

      1. If accountId is provided, returns that specific account
      2. Otherwise, returns the first active account
      3. If no active accounts exist, returns the first account regardless of active status

      Parameters

      • OptionalaccountId: string

        Optional explicit account ID

      Returns StorageAccountWithProvider

      The resolved account with provider, or null if no accounts are configured

    • Uploads a file to MJ Storage and creates an MJ: Files entity record.

      This is the primary high-level method for storing files. It handles:

      1. Resolving which storage account to use
      2. Initializing an authenticated driver
      3. Uploading the file content
      4. Creating the MJ: Files database record

      Parameters

      • options: UploadFileOptions

        Upload options (content, fileName, mimeType, contextUser, etc.)

      Returns Promise<UploadFileResult>

      Upload result containing the file ID, storage path, and account/provider used

      Error if no storage accounts are configured or the upload/save fails

      const result = await FileStorageEngine.Instance.UploadFile({
          content: Buffer.from(base64Data, 'base64'),
          fileName: 'report.pdf',
          mimeType: 'application/pdf',
          contextUser,
          storageAccountId: resolvedAccountId  // optional
      });
      console.log('Created file:', result.FileID);

    • Returns the singleton instance of the class. If the instance does not exist, it is created and stored in the Global Object Store. If className is provided it will be used as part of the key in the Global Object Store, otherwise the actual class name will be used. NOTE: the class name used by default is the lowest level of the object hierarchy, so if you have a class that extends another class, the lowest level class name will be used.

      Type Parameters

      Parameters

      • this: new () => T
      • OptionalclassName: string

      Returns T

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods