HeavyConnect's PDF Tool

General Development Notes

• The project is coded in ECMAScript 6.
• We have a transpiler to convert ES6 to ES5, compatible with any browser.
• After transpiled, the generated code goes to /dist folder.
• That transpiled code should be committed to github.
• After run git commit... the code is auto compiled.
• After run git push, all tests are executed and the push won't work if any test fails.
• We have a folder called tests/mockups for tests, with JSON files of some reports. The tests will run for each one.
• If we find a new report that make HCPDF fail, that report should be added to our tests/mockups folder.
• That way, we'll have a set of reports' JSONs, making sure all of them are working with the tests.

Known limitations

The dist folder is committed and pushed to GitHub, rather than being generated only at publish time. This may cause conflicts across merges, and will always require from the developer to keep the build updated.

The canvas package is an optional dependency, used only in the NODE environment. It is disabled for browser bundles through the browser field in package.json. If your platform cannot build canvas, the install will still succeed, but image processing on NODE may be limited.

Development

After cloning this repository, make sure to install the git hook to automatically run tests for each code push:

./hooks/install-hooks.sh

Then, to start developing, you can use these scripts:

• yarn build: To bundle the current ES6 code to ES5, and put on /dist folder.
• yarn build-production: To generate the minified production bundle.
• yarn watch: To automatically build files after changes on javascript code.
• yarn test: To run the automated tests.
• yarn test-seq: To run the automated tests sequentially, with a visible browser.
• yarn test-coverage: To run the automated tests and see the test coverage status.

After code changes, make sure to always keep a good code style and add new automated tests.

In case you see the error /bin/sh: gulp: command not found, you can run gulp --version. If you see the message zsh: command not found: gulp, you can just run: npm install --global gulp-cli

Pushing Code Changes

Once you installed the git hooks, the automated tests will run for each git push, and the push will only be executed if all tests are passing.

Publishing A New Version

The module is published to the public npm registry as @heavyconnect/hc-pdf.

1. Bump the version field in package.json.
2. Run npm publish.

The prepack script runs build-production automatically, so the bundle shipped to the registry is always built from the current source. The files field in package.json controls what gets packed; run npm pack --dry-run to review the file list before publishing.

Testing

The test env is setup with Jest and Puppeteer.

HCPDF Usage And Installation:

The HCPDF is built for the WEB and NODE environments, and it is published to the public npm registry.

# Using npm
npm install @heavyconnect/hc-pdf --save

# Using yarn
yarn add @heavyconnect/hc-pdf

To install a specific version, append it to the package name, e.g. npm install @heavyconnect/[email protected] --save.

Usage example:

Importing for WEB

<script src="node_modules/@heavyconnect/hc-pdf/dist/hc-pdf.js"></script>

Importing for NODE

const HCPDF = require("@heavyconnect/hc-pdf");

Then you can use as below:

HCPDF.doGeneratePDF(reports, options) // Options are optional
    .then(function (document) {
        document.getBase64().then().catch();
        document.getDataURL().then().catch();
        document.getBlob().then().catch(); // For WEB only
        document.getBuffer().then().catch();

        /**
         * For WEB only. Opens the PDF in another tab.
         */
        document.doDownload().then().catch();
    })
    .catch(function() {

    })

Available Options: TODO

Report Object Restrictions:

The PDF generator function accepts a single report, or a list of reports, and each report should follow a specific pattern. To check the current accepted format, you can check the file ./src/config/reports.config.js.

If you give a PDF that doesn't follow the required pattern, a validation error will be thrown. For example:

HCPDF.doGeneratePDF([ { id: "358" } ], options)

// Output on console
HCPDF - The given reports contain errors:
        [
            0: {
                id: The given value: should be a valid number
            }
        ]

Adding New Report Object Restrictions.

The report validations relies on a custom HC's typechecking system. Lets suppose you want to validate a simple Report object that has a required id, and an optional date:

types = require("./common/types");

const _reportShape = types.shape({
    id: types.number.required,  // Required
    date: types.date            // Optional
});

const _report = {
    id: "10",
    date: new Date()
}

const _report2 = {
    id: 10,
    date: null
}


_reportShape.doValidate(_report); //  Will return false, once id is invalid.
_reportShape.doValidate(_report2); //  Will return true.

In the example, we defined the types shape, number and date. To see all available types, check the file src/common/types.js.

To add more validations to the existing report shape, you may change the properties inside the file ./src/config/reports.config.js, and add the desired validations. E.g.:

module.exports = types.shape({
    id: types.number.required,
    date: types.date,
    // ...

Examples

• Web: yarn example-web