@lillallol/outline-pdf-data-structure

v1.0.3

Published

4 years ago

Create a pdf outline data structure from a high level string representation of pdf outline. This data structure can be used to create a real pdf outline.

0High
0Medium
0Low

lillallol

outline pdf index data-structure bookmarks pdf specification

outline-pdf-data-structure

Installation

npm install @lillallol/outline-pdf-data-structure

Description

Creates a pdf outline data structure as defined in the pdf specification, from a human readable string representation of the pdf outline. You can then use that data structure to "hydrate" a real pdf outline data structure like it is done in @lillallol/outline-pdf.

Code coverage

The testing code coverage is around 90%.

Example

import { outlinePdfDataStructure } from "../";

describe(outlinePdfDataStructure.name, () => {
    it("returns low level information about the provided outline string representation", () => {
        expect(
            outlinePdfDataStructure(
                `
                    1||Document
                    2|-|Section 1
                   	3|-|Section 2
                    4|--|Subsection 1
                    5|-|Section 3
                    6||Summary
                `,
                6
            )
        ).toEqual({
            outlineRootCount: 6,
            outlineItems: [
                {
                    Title: "Document",
                    Parent: -1,
                    Next: 5,
                    First: 1,
                    Last: 4,
                    Count: 4,
                    Dest: 1 - 1,
                },
                {
                    Title: "Section 1",
                    Parent: 0,
                    Next: 2,
                    Dest: 2 - 1,
                },
                {
                    Title: "Section 2",
                    Parent: 0,
                    Prev: 1,
                    Next: 4,
                    First: 3,
                    Last: 3,
                    Count: 1,
                    Dest: 3 - 1,
                },
                {
                    Title: "Subsection 1",
                    Parent: 2,
                    Dest: 4 - 1,
                },
                {
                    Title: "Section 3",
                    Parent: 0,
                    Prev: 2,
                    Dest: 5 - 1,
                },
                {
                    Title: "Summary",
                    Parent: -1,
                    Prev: 0,
                    Dest: 6 - 1,
                },
            ],
        });
    });
});

Documentation

/**
 * @description
 * It returns all the information needed to create a real pdf data structure.
 */
export declare function outlinePdfDataStructure(
    inputOutline: string,
    totalNumberOfPages: number
): outlinePdfDataStructureReturnType;

export declare type outlinePdfDataStructureReturnType = {
    /**
     * @description
     * It returns a low level programmatic representation of the outline.
     */
    outlineItems: outlineItem[];
    /**
     * @description
     * The total number of outline nodes.
     */
    outlineRootCount: number;
};

export declare type outlineItem = {
    /**
     * @description
     * The title that will be visible in the outline of the pdf for the context
     * outline node.
     */
    Title: string;
    /**
     * @description
     * The index (of the array that contains all the outline nodes) of the
     * parent outline node of the context outline node.
     *
     * Outline nodes of depth `0` have `-1` for this value.
     */
    Parent: number;
    /**
     * @description
     * The index (of the array that contains all the outline nodes) of the
     * previous sibling of the context outline node. It is `undefined` for the
     * case there is no previous sibling.
     */
    Prev?: number;
    /**
     * @description
     * The index (of the array that contains all the outline nodes) of the next
     * sibling of the context outline node. It is `undefined` for the case there
     * is no next sibling.
     */
    Next?: number;
    /**
     * @description
     * The index (of the array that contains all the outline nodes) of the first
     * immediate child of the context outline node. It is `undefined` for the
     * case there is no immediate child.
     */
    First?: number;
    /**
     * @description
     * The index (of the array that contains all the outline nodes) of the last
     * immediate child of the context outline node. It is `undefined` for the
     * case there is no immediate child.
     */
    Last?: number;
    /**
     * @description
     * Total number of outline nodes that are descendants to the context outline
     * node.
     */
    Count?: number;
    /**
     * @description
     * The page of the pdf that the outline node hyper links to.
     */
    Dest: number;
};

Motivation

This whole package was part of @lillallol/outline-pdf, but then I decide to do separation of concerns, because it would make both projects more readable.

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-data-structure

Installs the node modules (nothing will work without them):
```
npm install
```
Tests the code and generates code coverage:
```
npm run test
```
The generated code coverage is saved in ./coverage.
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.

Changelog

1.0.3

Added documentation section in README.md. The documentation was generated via ts-doc-gen-md and added in the README.md via md-in-place.
Added changelog section in README.md.
Added contributing section in README.md.
Added example section in README.md.
Did some internal changes in the code (added tagUnindent, created files: errorMessages.ts,constants.ts,publicApi.ts).

1.0.2

bug fixes

Changed count to be number of descendants instead of immediate descendants.

1.0.1

Some minor link fixes in the README.md.

1.0.0

First release.

License

MIT