@nottimtam/file-converter
Advanced tools
A headless, self-hostable, open-source file conversion express middleware.
A headless, self-hostable, open-source file conversion express middleware.
This middleware can be extended with custom file conversion Modules for unique use cases.
It does not ship o.o.t.b with any modules. Use @nottimtam/file-converter-core for core conversion modules.
While this package can be installed as a route on your express API, you can spin up a docker container with custom GUI for interfacing with the utility.
You can install this package with:
npm i @nottimtam/file-converter
You can implement this package on a route of your express API. Here is an example:
import express from "express";
import FileConverter from "@nottimtam/file-converter";
const app = express(); // Create express app.
const fileConverter = new FileConverter({
modules: [],
fileSizeLimit: 1086666,
temp: "./uploads/test",
});
// Middleware.
app.use(express.json());
app.use("/fcu", fileConverter.middleware()); // The route on which to access the file converter.
// Start app.
app.listen(3000, (err) => {
if (err) {
console.error(err);
} else {
console.log(`Server listening on port ${3000}.`);
}
});
new FileConverter(config)Create a new instance of the FileConverter.
Object - An object containing configuration data.
Array<Module> - Additional modules to expand the converter's functionality.number - A recommended (optional) limit for the total size of all files uploaded to the converter per request, in bytes.string - An optional path to a directory for temporary file storage. Defaults to "temp/" in the local directory. Files are removed from this folder after they are converted.boolean - (default true) Auto-delete conversion jobs and their associated files after an api request has been made successfully to download the converted files.boolean - (default false) Clear the content of the selected temp directory on initialization. This WILL delete all files in the directory indiscriminately. When false, the constructor will throw an error if the directory is not empty.All permitted properties defined in the constructor's config parameter are passed through to the constructed object.
jobsAn array of the converter's active jobs.
modulesAn array of the converter's loaded modules.
statsAn object containing stats about the instance.
number Milliseconds since the epoch, generated with Date.now().number The number of files converted.number The amount of data converted. (in megabytes)middleware(req, res, next)Get the file conversion express middleware function.
createJob(files, module, options)Start a conversion job. This method is called by the express middleware to create file conversion jobs but could potentially be used in a custom environment.
Array<Object> An array of file objects to convert. Should be a multer file object.Module The module to convert with.Object Optional options object configuration to pass to the module conversion job. Keys should be the label of each option configured in the module, and the values an appropriate value to set for that option.Object Optional options object configuration to pass to the module conversion job. Keys should be the label of each option configured in the module, and the values an appropriate value to set for that option.Job: The created job.import { Module } from "@nottimtam/file-converter";
new Module(config)Create a new file conversion module.
Object - An object containing configuration data.
string | Array<string> - The mimetype to convert from. Can be a single mimetype or an array of supported mimetypes.string - The mimetype to convert to.string - A unique label for this module.string (optional) - A detailed description for the module.function - An asynchronous callback that accepts a file object and converts that file's content, storing the converted data in the file at the provided path value.Array<Module.Option> An array of options for conversion.boolean (optional) - By default, a Module's convert method will change the file data to match the conversion. Setting this to true makes the method callback return the "file" data passed to it, with necessary changes (e.g., changing file extension in originalname). This also stops the Module from throwing errors if the to/from mimetype values are invalid, allowing custom file types to be used.All permitted properties defined in the constructor's config parameter are passed through to the constructed object.
_idThe module's UUID.
convertsFrom(mimetype)Check if this module can convert files from a certain mimetype.
string - The mimetype to check.boolean: Whether the mimetype is supported.convertsTo(mimetype)Check if this module can convert files to a certain mimetype.
string - The mimetype to check.boolean: Whether the mimetype is supported.async convert(files, callback)Convert an array of files using the module's conversion method.
Array<*> - The array of files to convert.function (optional) - An asynchronous callback that is passed each file before/after it is converted. (old, new)string: The path to a zip file containing the converted files.import { Module } from "@nottimtam/file-converter";
new Module.Option(config)Create a new module Option.
string - A unique label for this option.string (optional) - A detailed description for the option."string"|"number"|"boolean" - The option's input type.string|number|boolean - (optional) The option's default value.boolean - (optional) Whether or not to require a value to be provided for this option. Default false, if false, the option's validateInput callback will not be run when no value is provided.function - An asynchronous callback function, used to validate the value provided to this option, which is passed as the first and only parameter. Should throw an exception if the value is invalid.All permitted properties defined in the constructor's config parameter are passed through to the constructed object.
_idThe option's UUID.
Jobs are not directly exposed through an export. They are created automatically within the new FileConverter().middleware() method when a conversion request is made. They can also be created manually using new FileConverter().createJob().
_idThe job's UUID.
returnableA specialized object that returns relevant Job data, useful for sending information about a job from a server to a client.
statusAn object containing data on the status of the job.
**step**: string` The current step of the job.
"pending": The job has not started."running": The job is in progress."done": The job has completed and the files can be downloaded."error": An uncaught error occured during the conversion process. A error field is added to the status object in this case.number The number of files this job has converted.filesAn array of objects defining the files this job is responsible for.
moduleThe module the job will use for conversion.
optionsThe module options passed to the job.
async run(onStep)Run the job.
function An optional asynchronous callback to run when each step of the job is complete. onStep is passed one argument, the job's status property.GET /Get a simple API reference object.
GET /mimetypesGet all valid file mimetypes.
"text" in "text/plain"){
"mimeTypes": [
"image/aces",
"image/apng",
"image/avci",
"image/avcs",
"image/avif",
"image/bmp"
// ...
]
}
GET /mimetypes/validateValidate mimetype or file extension.
{
"valid": true, // A boolean indicating if the mimetype is valid.
"extension": "ez", // The file extension for this mimetype. (if valid)
"charset": false, // The charset for this mimetype. (if valid)
"contentType": "application/andrew-inset" // The content type of this mimetype. (if valid)
}
GET /modulesGet all file conversion modules.
{
"modules": [] // An array of module information.
}
POST /convertConvert file(s) from one filetype to another.
config.options configuration. The keys in the object should be each Option's label, and the value should be a proper format string, number, or boolean. (or null when permitted){
"jobId": "04a0dcb0-daa2-4a2e-8195-fac138925c19" // The ID of the job in which these files are being processed.
}
GET /convert/download/:jobIdGet converted files from a job.
GET /jobsGet all jobs that are currently running.
{
"jobs": [] // An array of the current running jobs.
}
DELETE /jobsDelete all jobs that are finished, and the temporary files associated with them.
Note: Jobs are deleted automatically after download, unless the FileConverter constructor's configuration clearJobOnDownload value is set to false.
GET /jobs/:jobIdGet a jobs that is currently running by its ID.
{
"job": {} // An object of the found job.
}
DELETE /jobs/:jobIdGet a finished jobs that is by its ID and delete it and all associated files.
Note: Jobs are deleted automatically after download, unless the FileConverter constructor's configuration clearJobOnDownload value is set to false.
GET /statsGet file conversion statistics.
{
"initialization": 1725337284323, // When this file converter instance was initialized, in number of milliseconds elapsed since the epoch.
"filesConverted": 0, // The number of files that have been converted since the converter was initialized.
"dataConverted": 0 // The total amount of data that has been converted since the converter was initialized, in megabytes.
}
FAQs
A headless, self-hostable, open-source file conversion express middleware.
The npm package @nottimtam/file-converter receives a total of 1 weekly downloads. As such, @nottimtam/file-converter popularity was classified as not popular.
We found that @nottimtam/file-converter demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.