Rebase Filemap Extension

This extension makes the given files available to the worker object. Files can optionally be cached in memory and may have hot reloading enabled. It can be used in a manifest like this:

{
  "type": "worker",
  ...
  "routes": {
    "/get-my-file": "src/get-my-file.mjs"
  },
  "extensions": {
    "myFileMap": {
      "packageName": "filemap",
      "packageSource": "rebase:extensions/filemap",
      "arguments": {
        "defaults": {
          "cache": false,
          "hotload": false
        },
        "my-welcome-image": "assets/welcome-banner.jpg",
        "my-welcome-text": "assets/welcome-message.txt",
        "my-config": {
          "path": "/opt/myconfig.txt",
          "cache": true,
          "hotload": true,
          "encoding": "utf8"
        }
      }
    }
  }
}

Any rebase-worker related handler can access the filemap like this:

// content of src/get-my-file.mjs
export default async (req, res, worker) => {
  worker.myFileMap.serve('my-welcome-image')
}

It can be used standalone like this:

import { RebaseFilemap } from "rebase-framework/extensions"

const myFileMap = new RebaseFilemap({
  "file1": "./assets/welcome-message.txt"
})

const welcomeMessageContent = myFileMap["file1"]

console.log(welcomeMessageContent)

Constructor

When initializing a new RebaseFilemap instance, a single object is expected. This object may contain an optional defaults object, which may contain two boolean properties names cache and hotload. Setting the default's property cache to true, will load and keep all enumerated files in memory. Setting the default's property hotload to true will watch all files that have cache enabled for changes and automatically load the new versions into memory. All properties of the construction object that are not named defaults will be treated as file-entries. File-entries can be enumerated by using their key as the name you want to use later on when accessing the file content and using the value as their path, relative to the manifest file. File-entries can also have an object as value, which describes the objects individual details, including cache, hotload, path, mimetype and encoding when working with text based files.

import { RebaseFilemap } from "rebase-framework/extensions"

const myFileMap = new RebaseFilemap({
  // these defaults will be applied to all file entries
  // unless they specify the values themself
  defaults: {
    cache: false, // is false by default
    hotload: false // is false by default
  },
  "file1": "assets/welcome-message.txt",
  "file2": {
    path: "assets/javascript-file.js",
    mimetype: "application/javascript",
    cache: true
  },
  "file3": {
    path: "assets/config.txt",
    mimetype: "text/plain",
    encoding: "utf8",
    cache: true,
    hotload: true
  },
  "banner-image": {
    path: "assets/website-background.jpg",
    // leaving out the mimetype will make the filemap
    // guess the mimetype by itself
    // mimetype: 'image/jpeg',
    cache: true
  }
})

// when probing for content
myFileMap.has('file1') // true
myFileMap.has('virus.exe') // false

// when accessing raw buffer content
const welcomeMessageContent = myFileMap.get("file1")
console.log(welcomeMessageContent)

// when using express.js
app.get('/main.js', (req, res) => {
  // send the javascript-file that we cached
  // into memory very fast
  myFileMap.serve(res, 'file2')
})

// when accessing stringified utf8 text
const configTextFile = myFileMap.get('file3')
// use configTextFile.fileStream to read all of the file
// use configTextFile.fileBuffer when `cache:true` was specified

// for hotload enabled files
myFileMap.on('file-reloaded', name => {
  console.log(`file content of '${name}' changed!`)
  // use myFileMap.get(name) to handle new file content
})

.setup()

This is called by the rebase-worker's setup event. This parses and prepares all files as specified in the constructor argument.

.has(name)

Returns true when the internal filemap contains a file-entry name as specified. Returns false when the internal filemap does not contain the specified name.

.get(name)

Returns the file-entry object for the specified file.

const myFileMap = new RebaseFilemap({
  "my_text_file1": {
    cache: true,
    path: "assets/testfile1.txt"
  }
}, worker)
const myFile = myFileMap.getFileFromPath('my_text_file1')
console.log(myFile.absoluteFilename) // "/home/user/myproject/assets/testfile1.txt"
console.log(myFile.mimeType) // given or guessed mimetype, eg "text/plain"
console.log(myFile.fileSize) // size in bytes
console.log(myFile.lastModified) // js date
// this is only available when cache:true is active
// as a default and/or for this specific resource
console.log(myFile.fileCacheData) // the content of the file
// always available
for await (const chunk of myFile.fileStream) {
    console.log(chunk);
}

.serve(httpResponse, name)

Helper to use with Express.js http responses. Sets the http response's mimetype, content-length and streams the file content.

.addMap(fileMapObject)

Adds more file-entries to the internal filemap. fileMapObject has the same structure as the first Constructor argument.

.removePathFromMap(name)

Removes and unloads the specified file-entry from the list.

.shutdown()

Removes all registered file-entries, so they are free to be garbage collected. This is called by the rebase-worker during a shutdown event.