xyfir / node-calibre

📖 A Node wrapper for Calibre's command line tools. (Abandoned)

A simple Node wrapper for Calibre's command line tools.

Built and maintained by the Xyfir Network.

node-calibre is mostly a simple wrapper around Calibre's CLI using Node's child_process.exec(), without many extra features added. In the future this package will contain more methods unique to each of Calibre's binaries and with both better error checking and improved results provided on success.

Examples

import { Calibre } from 'node-calibre';

// Create Calibre instance
const calibre = new Calibre({ library: '/path/to/calibre/library' });

// Convert ebook from pdf to epub
const newFile = await calibre.ebookConvert('/path/to/book.pdf', 'epub', {
  epubFlatten: null
});
console.log(newFile); // "/path/to/book.pdf.epub"

let result: string;

// Add book to Calibre library
result = await calibre.run('calibredb add', ['/path/to/book.epub']);
console.log(result); // "Added book ids: ..."

// List books in Calibre Library
result = await calibre.run('calibredb list', [], { limit: 10 });
console.log(result); // first 10 books

// You can optionally pass `options` as the second parameter
// `forMachine: null` gets converted to `--for-machine`
result = await calibre.run('calibredb list', {
  limit: 10,
  forMachine: null
});
console.log(Array.isArray(JSON.parse(result))); // true

API

constructor(options)

• options.library: string - optional, default ''
  • Full path to the Calibre library to work with.
  • Only needed if the commands this instance will run will use any of the calibredb commands.
  • The path will be used as the value for the --library-path option for calibredb commands.
• options.log: boolean - optional, default false
  • If true, the command string that is run by Node's child_process.exec() is logged to console before running.
• options.execOptions: object - optional, default {maxBuffer: 2048000}
  • The object passed to Node's child_process.exec() as the options argument.

run(command[, args][, options])

Runs a command on one of Calibre's binaries (calibredb, ebook-convert, etc). Find all here.

• command: string
  • The name of the bin and command to run. For example 'calibredb add' or 'ebook-convert'.
• args: any[] - optional, default []
  • An array of arguments that the command will accept.
  • All arguments are converted to strings, wrapped in "", and escaped.
• options: object - optional, default {}
  • A key:value object containing options that the command will accept.
  • All values (but not keys) are wrapped in "" and escaped.
  • If you want to pass on option that doesn't take a value, set the value to null: {'some-option': null}.
  • You can also use camelCase keys and they'll be converted to kebab-case: {forMachine: null} -> --for-machine.
  • If an option can be used multiple times (like --field in calibredb set_metadata), you can pass an array with all of the values: {field: ['tags:tag1,tag2', 'title:Some New Title']} -> --field "tags:tag1,tag2" --field "title:Some New Title".

Return

A promise that is rejected if the callback of Node's child_process.exec() has a value for error or stderr and resolves to the callback's stdout if no error occurred. Due to how Calibre's command line tools work, most of the time the promise should resolve regardless of whether Calibre encountered an issue. It's up to you to check the resolved result to determine if the command was successful.

ebookConvert(input, format, options)

Wrapper for ebook-convert.

• input: string
  • Path to the input file to convert.
• format: string
  • The format (file extension) to convert input to.
• options: object
  • Any CLI options for the ebook-convert command.

Return

Full path to the new file.

exec(command[, options])

This method should only be used if for some reason you need to build your own command string. It's essentially just a Promise-wrapped child_process.exec() that gets passed the execOptions from the constructor.

• command: string
  • The full command that you want to run.
  • For example: calibredb list --for-machine --limit 10.
• options: object
  • Will be merged with the execOptions object that was passed to the constructor.
  • Properties passed will override properties with the same name from execOptions.

Return

Same as run(), which builds a command string and passes it to exec().

Notes

• You should be aware of the maxBuffer property of the options object accepted by Node's child_process.exec(). It limits the size of output that can be received from a process, in this case one of Calibre's binaries. Unless you set maxBuffer as a property in the execOptions object, the maximum buffer size will be increased from the default of 200KB to 2MB. The vast majority of commands will get nowhere near this number, however certain commands like calibredb list with all fields requested on a large library can get close or even surpass that limit in certain cases. If a command's output exceeds the maxBuffer limit, an error will be thrown.
• You can safely pass use input as a value in the args array and options object of run(), but not as a command or an option name. In other words, args and option values are are wrapped in double quotes and escaped.
• This package does not install Calibre. You must have Calibre already installed and either have Calibre's bin directory in your system's PATH or use the cwd property of execOptions (see constructor options) to set Calibre's bin directory.
• Calibre v3 is recommended, but lower versions will most likely work.

node-calibre's Issues

Find out path to calibre library

After a book has been added to calibre (calibredb command), for further conversion using calibre-convert command, the absolute path to imported book has to be specified.
The default calibre library path should be used/assumed,
how can it be determined from the calibre CLI tools?

Alternatively this wrapper could offer a method/other means for getting the library path –
or automatically converting relative paths to absolute paths inside the library path.

calibredb add duplicates

By default calibredb add doesn't add books that already exists in calibre library (which is good).
However, in the script it has to be known sometimes (e.g. not further continuing).
It would be nice if the calibredb add callback gets an extra argument for an array of duplicate books.

Support Multiple Instances of Single Option

Example: set_metadata's --field.

Add methods for each Calibre binary / command

• Methods for each command: calibre.db.*, calibre.ebookConvert, etc
  • calibre.db.add()
    • #8 Among returned data, supply array of duplicate books
• Improve error checking by looking at the command's output and checking for specific values based on the command.
• Return result object that contains the original full output string and also parsed data relevant to the command.
• Each method takes relevant arguments, and not just the general args and options from run().

Ability to pass options as second parameter in `run()`

So instead of needing to do

calibre.run('calibredb list', [], { 'for-machine': null });

you could do

calibre.run('calibredb list', { 'for-machine': null });

WSL/Windows support

In WSL (Bash on Windows) shell, the binaries/commands can't be found by node-calibre (e.g. 'calibredb').

(node:9474) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Command failed: calibredb list --library-path ""
/bin/sh: 1: calibredb: not found
(node:9474) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Convert Option Names

From camelCase to kebab-case.

This way instead of needing to do

calibre.run('calibredb list', [], { 'for-machine': null });

you could do

calibre.run('calibredb list', [], { forMachine: null });

Support `child_process.spawn()`

Support using child_process.spawn(), and potentially replace child_process.exec() entirely with child_process.spawn().