@pyrodash/file-loader

A module that allows you to load files and instantiate classes dynamically at runtime, with support for hot reloading files.

Install

npm install @pyrodash/file-loader

Notes

Nested mode

The loader can index and load files at the root level of a directory (nested: false), and it can also index and load files nested inside folders (nested: true) such as the following structure:

└── modules
├── bakery
└── main.ts
├── cafe
└── main.ts
└── store
└── main.ts

Terminology

Filenames used by the parameters of functions like loadFromFileName() and the ignored config property, do not always refer to filenames. In nested mode, they refer to the name of the folder (e.g. bakery, cafe and store in the previous example). When nested mode is turned off, they just refer to filenames.

Names, which are used in the parameters of functions like unload() and reload(), are identical to filenames, but they have the file extension omitted.

Examples

With nested: true

import{Loader}from'@pyrodash/file-loader'constloader=newLoader({path: '/path/to/directory',nested: true,mainFile: 'main.ts',ignored: ['hello'],classes: {instantiate: true,params: ['param 1','param 2'],// these parameters are passed to class constructors},})

With nested: false

import{Loader}from'@pyrodash/file-loader'constloader=newLoader({path: '/path/to/files',nested: false,ignored: ['hello.ts'],classes: {instantiate: true,params: ['param 1','param 2'],// these parameters are passed to class constructors},})

API

loader.onReady(()=> ...)// loading filesawaitloader.loadFiles('/path/to/files',isNested)// use this when you have autoLoad off and want to run/await the initial loadingawaitloader.loadFiles()// defaults to configured path and nested propertiesawaitloader.loadFromFileName(name)awaitloader.loadFromPath(path)awaitloader.loadFromPath(path,name)// explicitly pass a name when loading a file that doesn't follow your configuration (e.g. your loader is in nested mode, but the path you're loading isn't meant to be named like such)// unloading filesawaitloader.unloadFromPath(path)awaitloader.unload(name)// reloading filesawaitloader.reloadFromPath(path)awaitloader.reload(name)// eventsloader.on('ready',()=> ...)// emitted after first initial loadingloader.on('error',(err)=> ...)loader.on('warning',(err)=> ...)loader.on('load-many',(files)=> ...)// emitted after loadFiles() runsloader.on('load',(name,file)=> ...)loader.on('unload',(file)=> ...)loader.on('reload',(newFile,oldFile)=> ...)

LoaderConfig

• path: string

Directory to load files from

• nested?: boolean

Whether or not to enable nested mode

• mainFile?: string | ((file: string) => string)

Refers to the actual name of the main file inside nested files, can be a string or a function that takes an absolute folder path and returns an absolute path to the main file

• ignored?: string[]

An array of filenames (folder names in case of nested mode, filenames otherwise) to be ignored by the loader

• autoLoad?: boolean

Whether or not the loader should immediately begin loading files automatically

• classes?: ClassOptions
• allowedFileExts?: string[]

File extensions loaded by the loader

• watch?: boolean (experimental)

Whether or not to watch loaded files for changes and automatically reload them

Defaults

{nested: false,mainFile: 'index.js'|'index.ts',// depends on if you're running in js or ts at runtimeignored: [],autoLoad: true,classes: {instantiate: true,params: [],},allowedFileExts: ['.js','.ts']}

ClassOptions[T]

• instantiate?: boolean

Whether or not to instantiate the class

• params?: unknown[]

Parameters to be passed the class constructors

• findConstructor?: (name: string, mdl: any) => ConstructorType[T] | null

A function to extract a constructor from a module's exports

• destroy?: (instance: T) => void | Promise[void]

A function to destroy/deconstruct an instance when it's being unloaded

• reload?: (newInstance: T, oldInstance: any) => void | Promise[void]

A function to rebuild a reloaded instance with the data of the old instance

TODO

• Improve unit tests
• Watch loaded files for changes