Storage Explorer Middleware

A node.js middleware used to expose explorer endpoint, accessing directories and files.

Installation

Using npm

npm i @map-colonies/storage-explorer-middleware

OR

Using yarn

yarn add @map-colonies/storage-explorer-middleware

import middleware and types

import  StorageExplorerMiddleware, { ImountDirObj } from  '@map-colonies/storage-explorer-middleware';

Usage

Simply connect the middleware to your server instance and pass the required parameters to the function .

MIddleware creator signature

function  getStorageExplorerMiddleware(mountDirs: ImountDirObj[], logger: Record<string, unknown>): Router

ImountDirObj interface

interface  ImountDirObj {
    physical: string;
    displayName: string;
    includeFilesExt?: string[];
}

Usage example

app.use(StorageExplorerMiddleware(
[
    {
	    physical: 'mount-dir-path',
	    displayName: 'my-special-directory-name',
	    includeFilesExt: ['jpeg', 'png', 'gif']
    },
    {
	    physical: 'second-mount-dir-path',
	    displayName: 'random_files',
    }
]
, this.logger))

Set the STORAGE_EXPLORER_BUFFER_SIZE environment variable to configure the buffer size for receiving files. If unset, the default is 10 MiB.

Notes

• Please make sure to add the file explorer routes to your openapi.yaml file. Otherwise, all middleware routes will be blocked. (Alternatively, you can add the explorer routes to the ignore path regex to exclude them from validation.) Also, ensure that our middleware is added last, since it returns a response and may prevent other middleware from executing. You can find an example for the openapi.yaml file here.

• To consume a file as a stream, include the x-client-response-type header in your request. Without this header, the file size is limited to 10 MiB.

For testing:

• Use Node.js version 20 or 22.
• Import the StorageExplorer.postman_collection.json file into Postman to view the examples. When uploading a file, make sure to select a file from your local machine.