doconv v0.1.5

Doconv

Doconv API client for browser and nodejs.

Doconv

Doconv is a document converting service with simple HTTP API packed in Docker image. This package is the simplest way to interact with its API.

Install

npm install doconv

Using in Browser

// May need full path 'doconv/dist/browser/doconv.esm.js'
import doconv from 'doconv';


// Use URL where is Doconv container started
const dc = doconv('http://localhost:3000'); 

// Load list of all possible formats
const formats = await dc.formats();
console.log("Supported formats:",formats);

// Somewhere on the page: 
//    <input type="file" id="myFile" />
//    <button onclick="convertFile">Convert</button>

async function convertFile(){
    // Send file to the service and waiting responce
    const result = await dc.convert({
        file: document.getElementById('myFile').files[0],
        format: 'pdf'
    });

    // When converted file ready, let user to download it
    result.download();
}

Also doconv is available on CDNs like https://unpkg/doconv

Using in Node

Client

const {doconv} = require('doconv');

// Use URL where is Doconv container started
const dc = doconv('http://localhost:3000');

// Send file to the service and waiting responce
const result = await dc.convert({
    file: '/home/user/document.docx',
    format: 'pdf'
});

// Save converted document on specified path
result.save('/home/user/converted.pdf');

Hook handler

const {hookParser} = require('doconv');

//Express-like middleware
async function(request,responce,next){
    try{
        const result = await hookParser(request);

        if(result.error) throw new Error('Error during converting: ' + result.error);

        console.log('Recieved file:', result.file.filename);

        await result.file.save('/home/user/myfilestorage');
    }catch(err){
        console.log('Error:' + err.message)
    }

    responce.end();
}

API Browser

Most of methods are asynchronus, use it as a Promise.

Doconv client creator

doconv([api_url])

Params:

• api_url - URL like http://domain.tld:port where is Doconv container started

Returns: Doconv client object.

Doconv client

formats()

Returns: Formats list object

convert({options})

Options:

• file – files property value from the <input type="file"> element. (Required)
• format – format of target file. One from formats identifiers list which returns format() method. (Default pdf);
• download – once converted file will be recieved, opens save dialog in browser. Ignoring if hook property specified. (Default false)
• hook – URL where is a server which can recieve a converted file(look for Node API below). (Default false)
• context – any serializable object, will be send to hook URL along with file. Place here any data you need in hook to handle recieved file.(Default false)

Returns: If hook property speciefed, will be return text confirmation, that file will be sended to hook's URL. Otherwise result will be an object:

• body - converted file body content.
• filename – name of file.
• mime – mime type of file
• download([name]) – call it to save file on device. Optionaly you may specify any name for downloading file.

markup({options})

Options:

• body - content for document generation.
• markup - type of the content. Currently support html and markdown. Default html
• format – format of target file. One from formats identifiers list which returns format() method. (Default pdf);
• download – once converted file will be recieved, opens save dialog in browser. Ignoring if hook property specified. (Default false)
• name - basename of result file. Default Document
• pageWidth - page width in millimeters. Default 210
• pageHeight - page height in millimeters. Default 297
• marginTop - top margin of the page in millimeters. Default 15
• marginBottom - bottom margin of the page in millimeters. Default 15
• marginRight - right margin of the page in millimeters. Default 15
• marginLeft - left margin of the page in millimeters. Default 15
• pageBreak - string which will be replaced with page break in result document. Default <!--PAGEBREAK-->
• hook – URL where is a server which can recieve a converted file(look for Node API below). (Default false)
• context – any serializable object, will be send to hook URL along with file. Place here any data you need in hook to handle recieved file.(Default false)

Returns: If hook property speciefed, will be return text confirmation, that file will be sended to hook's URL. Otherwise result will be an object:

• body - converted file body content.
• filename – name of file.
• mime – mime type of file
• download([name]) – call it to save file on device. Optionaly you may specify any name for downloading file.

API Node

Doconv hook handler

parseHook(<request>)

Params:

• <request> – Node http-request object.

Returns: If request is posted from Doconv service, returns object:

• error – returned if there was error during converting
• context – object from client, if provided
• meta – some metadata for the input and converted files.
• file – converted file object:
  • filename – name of the converted file.
  • mime – mime type of the file.
  • size – size in bytes.
  • tmp – path to temp file. It will be removed after calling save or read methods.
  • read() – returns file's body as a Buffer.
  • save( <dir>,[filename] | <path> ) – save file in the specified directory. Optionaly you may specifiy a different filename also. Or you can just specifiy full path to the new file.

Doconv client creator

doconv([api_url])

Params:

• api_url - URL like http://domain.tld:port where is Doconv container started

Returns: Doconv client object.

Doconv client

formats()

Returns: Formats list object

convert({options})

Options:

• file – files property value from the <input type="file"> element. (Required)
• format – format of target file. One from formats identifiers list which returns format() method. (Default pdf);
• hook – URL where is a server which can recieve a converted file(look for Node API below). (Default false)
• context – any serializable object, will be send to hook URL along with file. Place here any data you need in hook to handle recieved file.(Default false)

Returns: If hook property speciefed, will be return text confirmation, that file will be sended to hook's URL. Otherwise result will be an object:

• body - converted file body content as a Buffer.
• filename – name of file.
• mime – mime type of file
• save( <dir>,[filename] | <path> ) – save file in the specified directory. Optionaly you may specifiy a different filename also. Or you can just specifiy full path to the new file.

markup({options})

Options:

• body - content for document generation.
• markup - type of the content. Currently support html and markdown. Default html
• format – format of target file. One from formats identifiers list which returns format() method. (Default pdf);
• name - basename of result file. Default Document
• pageWidth - page width in millimeters. Default 210
• pageHeight - page height in millimeters. Default 297
• marginTop - top margin of the page in millimeters. Default 15
• marginBottom - bottom margin of the page in millimeters. Default 15
• marginRight - right margin of the page in millimeters. Default 15
• marginLeft - left margin of the page in millimeters. Default 15
• pageBreak - string which will be replaced with page break in result document. Default <!--PAGEBREAK-->
• hook – URL where is a server which can recieve a converted file(look for Node API below). (Default false)
• hook – URL where is a server which can recieve a converted file(look for Node API below). (Default false)
• context – any serializable object, will be send to hook URL along with file. Place here any data you need in hook to handle recieved file.(Default false)

Returns: If hook property speciefed, will be return text confirmation, that file will be sended to hook's URL. Otherwise result will be an object:

• body - converted file body content as a Buffer.
• filename – name of file.
• mime – mime type of file
• save( <dir>,[filename] | <path> ) – save file in the specified directory. Optionaly you may specifiy a different filename also. Or you can just specifiy full path to the new file.

Formats list object

Looks like this:

[
    ...,
    {
        // Group of format
        "doctype": "document",  
        // Format identifier
        "format": "docx", 
        // Text description
        "description": "Microsoft Office Open XML", 
        // Extension of the files of this format
        "ext": "docx", 
        // Mime type for this format
        "mime": "application/msword", 
    },
    ...
]