@lillallol/outline-pdf-data-structure

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.

Usage no npm install needed!

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

README

outline-pdf-data-structure

Table of contents

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

Concretions

outlinePdfDataStructure

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

# references
# 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;
};
# outlineItem
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