@lillallol/outline-pdf

High level API to add outline to a pdf without any dependency on other programming languages. Works in both browser and node.

Usage no npm install needed!

<script type="module">
  import lillallolOutlinePdf from 'https://cdn.skypack.dev/@lillallol/outline-pdf';
</script>

README

outline-pdf

NOTICE: If you have outlined your pdf using a version from 2.0.0 to 3.0.3, then if you edit your pdf it will get corrupted due to a bug introduced by my module. From version 3.0.4 this bug has been resolved.

Table of contents

Installation

npm install @lillallol/outline-pdf

Description

Take a look at outline-pdf-cjs if you are using node.

Adds outline to pdf that do not have one. As of right now, it is the only module in the npm registry that has the following characteristics :

  • Only javascript dependencies. No code from other programming languages is used.
  • Enables collapsing and nesting in the outline.
  • Fast download from the npm registry.
  • High level API.
  • Works in both the browser and node.

Code coverage

Testing code coverage is more than 90%.

Example

import * as fs from "fs";
import * as path from "path";
import * as pdfLib from "pdf-lib";

import { outlinePdfFactory } from ".";

jest.setTimeout(60 * 10e3);

describe(outlinePdfFactory.name, () => {
    it("adds the provided outline to the loaded pdf", async () => {
        const outlinePdf = outlinePdfFactory(pdfLib);
        const absolutePathToPdfToOutline = path.resolve(__dirname, "test.pdf");
        const absolutePathToSaveOutlinedPdf = path.resolve(__dirname, "test.outline.pdf");
        try {
            fs.unlinkSync(absolutePathToSaveOutlinedPdf);
        } catch (e) {
            //file does not exist so no problem
        }
        const pdf = fs.readFileSync(absolutePathToPdfToOutline, { encoding: "base64" });
        const outline: string = `
             1||Some random title 1
             2|-|Some random title 2
            -3|--|Some random title 3
             4|---|Some random title 4
             5|---|Some random title 5
             6|-|Some random title 6
             7||Some random title 7
        `;
        const outlinedPdf = await outlinePdf({ outline, pdf }).then((pdfDocument) => pdfDocument.save());
        fs.writeFileSync(absolutePathToSaveOutlinedPdf, outlinedPdf);
    });
});

Documentation

Concretions

outlinePdfFactory 

export declare const outlinePdfFactory: IOutlinePdfFactory;
# references
# IOutlinePdfFactory 
export declare type IOutlinePdfFactory = (pdfLib: pdfLib) => IOutlinePdf;
# pdfLib 
/**
 * @description
 * Just use:
 *
 * ```ts
 * import * as pdfLib from "pdf-lib";
 * ```
 */
export declare type pdfLib = {
    PDFDict: typeof PDFDict;
    PDFName: typeof PDFName;
    PDFNumber: typeof PDFNumber;
    PDFRef: typeof PDFRef;
    PDFArray: typeof PDFArray;
    PDFNull: typeof PDFNull;
    PDFDocument: typeof PDFDocument;
    PDFPageLeaf: typeof PDFPageLeaf;
    PDFHexString: typeof PDFHexString;
};
# PDFDict 
import type { PDFDict } from "pdf-lib";
# PDFName 
import type { PDFName } from "pdf-lib";
# PDFNumber 
import type { PDFNumber } from "pdf-lib";
# PDFRef 
import type { PDFRef } from "pdf-lib";
# PDFArray 
import type { PDFArray } from "pdf-lib";
# PDFNull 
import type { PDFNull } from "pdf-lib";
# PDFDocument 
import type { PDFDocument } from "pdf-lib";
# PDFPageLeaf 
import type { PDFPageLeaf } from "pdf-lib";
# PDFHexString 
import type { PDFHexString } from "pdf-lib";
# IOutlinePdf 
export declare type IOutlinePdf = (_: {
    /**
     * @description
     * The pdf to outline.
     *
     * I you provide the pdf as a string, then make sure it is of base 64.
     */
    pdf: string | Uint8Array | ArrayBuffer | PDFDocument;
    /**
     * @description
     * String representation of the outline.
     *
     * Example:
     *
     * ```ts
     * `
     *    1||some title 1
     *   12|-|some title 2
     *  -30|--|some title 3
     *   34|---|some title 4
     *   35|---|some title 5
     *   60|--|some title 6
     *   67|-|some title 7
     *   80||some title 8
     * `
     * ```
     *
     * where the:
     *
     * * first column is the page number, and if it negative it means that this
     *   part of the outline is collapsed
     * * second column is the outline depth
     * * third column is the outline title
     */
    outline: string;
}) => Promise<PDFDocument>;

PDFDocument

Motivation

I had to use this module in one of my projects: scrap-it. I could not find one that satisfied my needs, so I decided to create my own.

You might find interesting

  • @lillallol/outline-pdf-cjs
    • the equivalent of the current module for node
    • uses the current module
  • @lillallol/outline-pdf-data-structure
    • creates a pdf outline data structure from a high level string representation of the pdf outline
    • used by the current module
  • pdf-lib
    • low level pdf library for both browser and node
  • hummus-toc
    • uses hummus which is deprecated
    • only javascript dependencies
    • takes a lot of time to download
  • pdfjs
    • only javascript dependencies
    • downloads fast

Acknowledgments

The following comments : 1 , 2 , contributed tremendously in the creation of this module.

FAQs

Why do I have to inject pdf-lib to use this module.

No pdf-lib code is hard coded in this module. When someone wants to use this module and also use pdf-lib, to create a new module, there will be no pdf-lib code repeated in the generated bundle.

Contributing

I am open to suggestions/pull request to improve this program.

You will find the following commands useful:

  • Clones the github repository of this project:

    git clone https://github.com/lillallol/outline-pdf

  • Installs the node modules (nothing will work without them):

    npm install

  • Tests the source code:

    npm run test

  • Lints the source folder using typescript and eslint:

    npm run lint

  • Builds the typescript code from the ./src folder to javascript code in ./dist:

    npm run build-ts

  • Injects in place the generated toc and imported files to README.md:

    npm run build-md

  • Checks the project for spelling mistakes:

    npm run spell-check

    Take a look at the related configuration ./cspell.json.

  • Checks ./src for dead typescript files:

    npm run dead-files

    Take a look at the related configuration ./unimportedrc.json.

  • Logs in terminal which dependencies and devDependencies have a new version published in npm:

    npm run check-updates

  • Updates the dependencies and devDependencies to their latest version:

    npm run update

  • Formats all .ts files of the ./src folder:

    npm run format

Help needed

I want to:

  • read the outline of a pdf
  • delete the outline of a pdf

using pdf-lib.

Finally I want to create the following tests:

  • test that my module correctly outlines a pdf by reading the outline of the pdf that got outlined
  • test that after outlining the pdf, any kind of pdf editing (pdf annotations for example), will not corrupt the outlined pdf

Changelog

4.0.0

Breaking changes

  • The interface of outlinePdf has been simplified.

Other

  • Replaced the README.md browser example, with the test file of the entry point function.
  • Added sections Code coverage, Documentation, Contributing in README.md.

3.0.4

Bug fixes

  • Esm entry point was importing module @lillallol/outline-pdf-data-structure without .js extension.
  • Fixed bug that was introduced from version 2.0.0 and was caused by creating more pdf refs than the number of outline nodes, which made the outlined pdf file get corrupted if it was edited with a pdf annotator.

Other

  • Added CHANGELOG.md.

3.0.3

bug fixes

  • Fixed bug that made the module crash if it had more outline nodes than pdf pages.

3.0.2

  • Updated dependencies.

3.0.1

bug fixes

  • Fixed the bug that made the outline work only if there was one outline node for each pdf page.

3.0.0

breaking changes

  • outlinePdfCjs is now on its own package: @lillallol/outline-pdf-cjs.

2.0.4

  • Internal changes.

2.0.3

bug fixes

  • Outline does not bug with non english characters now.

2.0.2

  • Minor changes in README.md.

2.0.1

  • Minor changes in README.md.

2.0.0

Breaking changes

  • outlinePdf is renamed to outlinePdfCjsFactory. You now have to inject pdf-lib in the factory.
  • added outlinePdfFactory. It can outline pdf in both browser and nodejs. You need to inject pdf-lib in the factory.

Other

  • added entry for esm

1.0.2

  • Added error messages for some edge cases.

1.0.1

  • Minor changes in README.md.

1.0.0

  • Published the package.

License

MIT