pdf-lite 1.0.0

package/packages/pdf-lite/test/unit/utils.test.ts

@@ -0,0 +1,248 @@
+import { describe, expect, it } from 'vitest'
+import { stringToBytes } from '../../src/utils/stringToBytes'
+import { bytesToString } from '../../src/utils/bytesToString'
+import { hexToBytes } from '../../src/utils/hexToBytes'
+import { bytesToHex } from '../../src/utils/bytesToHex'
+import { padBytes } from '../../src/utils/padBytes'
+import { concatUint8Arrays } from '../../src/utils/concatUint8Arrays'
+import { hexBytesToBytes } from '../../src/utils/hexBytesToBytes'
+import { bytesToHexBytes } from '../../src/utils/bytesToHexBytes'
+import { stringToHexBytes } from '../../src/utils/stringToHexBytes'
+import { hexBytesToString } from '../../src/utils/hexBytesToString'
+import { assert, assertIfDefined } from '../../src/utils/assert'
+
+describe('Utility Functions', () => {
+    describe('stringToBytes', () => {
+        it('should convert a string to bytes', () => {
+            const result = stringToBytes('Hello')
+            expect(result).toEqual(new Uint8Array([72, 101, 108, 108, 111]))
+        })
+
+        it('should return the same array if already a ByteArray', () => {
+            const input = new Uint8Array([1, 2, 3])
+            const result = stringToBytes(input)
+            expect(result).toBe(input)
+        })
+
+        it('should handle empty string', () => {
+            const result = stringToBytes('')
+            expect(result.length).toBe(0)
+        })
+
+        it('should handle unicode characters', () => {
+            const result = stringToBytes('café')
+            // 'café' encodes to: 99, 97, 102, 195, 169 in UTF-8
+            expect(result.length).toBe(5)
+        })
+    })
+
+    describe('bytesToString', () => {
+        it('should convert bytes to a string', () => {
+            const bytes = new Uint8Array([72, 101, 108, 108, 111])
+            const result = bytesToString(bytes)
+            expect(result).toBe('Hello')
+        })
+
+        it('should handle empty array', () => {
+            const bytes = new Uint8Array([])
+            const result = bytesToString(bytes)
+            expect(result).toBe('')
+        })
+
+        it('should handle UTF-8 encoded bytes', () => {
+            const bytes = new Uint8Array([99, 97, 102, 195, 169]) // 'café' in UTF-8
+            const result = bytesToString(bytes)
+            expect(result).toBe('café')
+        })
+    })
+
+    describe('hexToBytes', () => {
+        it('should convert hex string to bytes', () => {
+            const result = hexToBytes('48656c6c6f') // 'Hello' in hex
+            expect(result).toEqual(new Uint8Array([72, 101, 108, 108, 111]))
+        })
+
+        it('should handle uppercase hex', () => {
+            const result = hexToBytes('DEADBEEF')
+            expect(result).toEqual(new Uint8Array([222, 173, 190, 239]))
+        })
+
+        it('should handle empty string', () => {
+            const result = hexToBytes('')
+            expect(result.length).toBe(0)
+        })
+    })
+
+    describe('bytesToHex', () => {
+        it('should convert bytes to hex string', () => {
+            const bytes = new Uint8Array([72, 101, 108, 108, 111])
+            const result = bytesToHex(bytes)
+            expect(result).toBe('48656C6C6F')
+        })
+
+        it('should handle empty array', () => {
+            const bytes = new Uint8Array([])
+            const result = bytesToHex(bytes)
+            expect(result).toBe('')
+        })
+
+        it('should handle bytes with leading zeros', () => {
+            const bytes = new Uint8Array([0, 15, 16])
+            const result = bytesToHex(bytes)
+            expect(result).toBe('000F10')
+        })
+    })
+
+    describe('padBytes', () => {
+        it('should pad bytes to the specified length', () => {
+            const bytes = new Uint8Array([1, 2, 3])
+            const result = padBytes(bytes, 5)
+            expect(result.length).toBe(5)
+            expect(result).toEqual(new Uint8Array([1, 2, 3, 0, 0]))
+        })
+
+        it('should throw error if bytes are longer than target length', () => {
+            const bytes = new Uint8Array([1, 2, 3, 4, 5])
+            expect(() => padBytes(bytes, 3)).toThrow(
+                'Cannot pad bytes: current length 5 is greater than or equal to target length 3.',
+            )
+        })
+
+        it('should handle same length (no padding needed)', () => {
+            const bytes = new Uint8Array([1, 2, 3])
+            // Same length doesn't throw - it just returns the same content in a new array
+            const result = padBytes(bytes, 3)
+            expect(result).toEqual(new Uint8Array([1, 2, 3]))
+        })
+
+        it('should handle empty array', () => {
+            const bytes = new Uint8Array([])
+            const result = padBytes(bytes, 3)
+            expect(result).toEqual(new Uint8Array([0, 0, 0]))
+        })
+    })
+
+    describe('concatUint8Arrays', () => {
+        it('should concatenate multiple arrays', () => {
+            const arr1 = new Uint8Array([1, 2])
+            const arr2 = new Uint8Array([3, 4])
+            const arr3 = new Uint8Array([5])
+            const result = concatUint8Arrays(arr1, arr2, arr3)
+            expect(result).toEqual(new Uint8Array([1, 2, 3, 4, 5]))
+        })
+
+        it('should handle empty arrays', () => {
+            const arr1 = new Uint8Array([1, 2])
+            const arr2 = new Uint8Array([])
+            const arr3 = new Uint8Array([3])
+            const result = concatUint8Arrays(arr1, arr2, arr3)
+            expect(result).toEqual(new Uint8Array([1, 2, 3]))
+        })
+
+        it('should handle single array', () => {
+            const arr = new Uint8Array([1, 2, 3])
+            const result = concatUint8Arrays(arr)
+            expect(result).toEqual(new Uint8Array([1, 2, 3]))
+        })
+
+        it('should handle no arrays', () => {
+            const result = concatUint8Arrays()
+            expect(result).toEqual(new Uint8Array([]))
+        })
+    })
+
+    describe('hexBytesToBytes', () => {
+        it('should convert hex bytes to bytes', () => {
+            const hexBytes = stringToBytes('48656C6C6F') // 'Hello' in hex
+            const result = hexBytesToBytes(hexBytes)
+            expect(result).toEqual(new Uint8Array([72, 101, 108, 108, 111]))
+        })
+
+        it('should handle lowercase hex', () => {
+            const hexBytes = stringToBytes('deadbeef')
+            const result = hexBytesToBytes(hexBytes)
+            expect(result).toEqual(new Uint8Array([222, 173, 190, 239]))
+        })
+    })
+
+    describe('bytesToHexBytes', () => {
+        it('should convert bytes to hex bytes', () => {
+            const bytes = new Uint8Array([72, 101, 108, 108, 111])
+            const result = bytesToHexBytes(bytes)
+            expect(bytesToString(result)).toBe('48656C6C6F')
+        })
+
+        it('should handle bytes with values requiring leading zeros', () => {
+            const bytes = new Uint8Array([0, 15])
+            const result = bytesToHexBytes(bytes)
+            expect(bytesToString(result)).toBe('000F')
+        })
+    })
+
+    describe('stringToHexBytes', () => {
+        it('should convert hex string with angle brackets to bytes', () => {
+            const result = stringToHexBytes('<deadbeef>')
+            expect(result).toEqual(new Uint8Array([222, 173, 190, 239]))
+        })
+
+        it('should handle hex string without angle brackets', () => {
+            const result = stringToHexBytes('deadbeef')
+            expect(result).toEqual(new Uint8Array([222, 173, 190, 239]))
+        })
+    })
+
+    describe('hexBytesToString', () => {
+        it('should convert bytes to hex string', () => {
+            const bytes = new Uint8Array([222, 173, 190, 239])
+            const result = hexBytesToString(bytes)
+            expect(result).toBe('deadbeef')
+        })
+
+        it('should handle bytes with values requiring leading zeros', () => {
+            const bytes = new Uint8Array([0, 15])
+            const result = hexBytesToString(bytes)
+            expect(result).toBe('000f')
+        })
+    })
+
+    describe('assert', () => {
+        it('should not throw for truthy values', () => {
+            expect(() => assert(true)).not.toThrow()
+            expect(() => assert(1)).not.toThrow()
+            expect(() => assert('hello')).not.toThrow()
+            expect(() => assert({})).not.toThrow()
+        })
+
+        it('should throw for falsy values', () => {
+            expect(() => assert(false)).toThrow()
+            expect(() => assert(0)).toThrow()
+            expect(() => assert('')).toThrow()
+            expect(() => assert(null)).toThrow()
+            expect(() => assert(undefined)).toThrow()
+        })
+
+        it('should throw with custom message', () => {
+            expect(() => assert(false, 'Custom error')).toThrow('Custom error')
+        })
+    })
+
+    describe('assertIfDefined', () => {
+        it('should not throw if value is undefined', () => {
+            expect(() => assertIfDefined(undefined, false)).not.toThrow()
+        })
+
+        it('should not throw if value is null', () => {
+            expect(() => assertIfDefined(null, false)).not.toThrow()
+        })
+
+        it('should not throw if condition is truthy for defined value', () => {
+            expect(() => assertIfDefined('defined', true)).not.toThrow()
+        })
+
+        it('should throw if condition is falsy for defined value', () => {
+            expect(() =>
+                assertIfDefined('defined', false, 'Condition failed'),
+            ).toThrow('Condition failed')
+        })
+    })
+})

package/packages/pdf-lite/test/unit/xref-lookup.test.ts

@@ -0,0 +1,72 @@
+import { assert, describe, expect, it } from 'vitest'
+import { PdfXrefLookup } from '../../src/pdf/pdf-xref-lookup.js'
+import { PdfObject } from '../../src/core/objects/pdf-object'
+import { PdfIndirectObject } from '../../src/core/objects/pdf-indirect-object.js'
+import {
+    PdfXRefStream,
+    PdfXRefStreamCompressedEntry,
+    PdfXRefStreamStandardEntry,
+} from '../../src/core/objects/pdf-stream'
+import {
+    PdfXRefTable,
+    PdfXRefTableEntry,
+} from '../../src/core/objects/pdf-xref-table.js'
+import { PdfTrailer } from '../../src/core/objects/pdf-trailer'
+import { PdfNumber } from '../../src/core/objects/pdf-number'
+import { PdfStartXRef } from '../../src/core/objects/pdf-start-xref'
+import { PdfComment } from '../../src/core/objects/pdf-comment'
+
+describe('PDF Xref Lookup', () => {
+    const xrefStream = new PdfIndirectObject({
+        content: PdfXRefStream.fromEntries([
+            new PdfXRefTableEntry({
+                objectNumber: 1,
+                byteOffset: 200,
+                generationNumber: 0,
+                inUse: true,
+            }),
+            new PdfXRefTableEntry({
+                objectNumber: 2,
+                byteOffset: 300,
+                generationNumber: 0,
+                inUse: true,
+            }),
+            new PdfXRefStreamCompressedEntry({
+                objectNumber: 3,
+                objectStreamNumber: 5,
+                index: 0,
+            }),
+        ]),
+        offset: 100,
+    })
+
+    const xrefTable = new PdfXRefTable()
+    const objects: PdfObject[] = [
+        xrefStream,
+        xrefTable,
+        new PdfTrailer({
+            Size: new PdfNumber(1),
+            Prev: new PdfNumber(xrefStream.offset),
+        }),
+        new PdfStartXRef(xrefTable.offset),
+        PdfComment.EOF,
+    ]
+    const xrefLookup = PdfXrefLookup.fromObjects(objects)
+
+    it('should chain multiple xref table or stream lookups', () => {
+        expect(xrefLookup.object).toBeInstanceOf(PdfXRefTable)
+        expect(xrefLookup.object).toEqual(xrefTable)
+        expect(xrefLookup.prev?.object).toEqual(xrefStream)
+
+        const entry1 = xrefLookup.getObject(2)!
+        assert(entry1 instanceof PdfXRefStreamStandardEntry)
+        expect(entry1.byteOffset.value).toBe(300)
+    })
+
+    it('should find compressed entries in xref streams', () => {
+        const entry = xrefLookup.getObject(3)!
+        assert(entry instanceof PdfXRefStreamCompressedEntry)
+        expect(entry.objectNumber.value).toBe(3)
+        expect(entry.index.value).toBe(0)
+    })
+})

package/packages/pdf-lite/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../tsconfig.json",
+    "include": ["src/**/*", "examples/**/*", "test/**/*", "test-fixtures"]
+}

package/packages/pdf-lite/tsconfig.prod.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.prod.json",
+    "compilerOptions": {
+        "outDir": "dist"
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["src/**/*.test.ts", "test-fixtures", "test/**/*"]
+}

package/packages/pdf-lite/typedoc.json

@@ -0,0 +1,14 @@
+{
+    "readme": "none",
+    "entryPointStrategy": "expand",
+    "entryPoints": ["src/**/*.ts"],
+    "exclude": [
+        "**/node_modules/**",
+        "**/test/**",
+        "**/scripts/**",
+        "**/dist/**",
+        "**/*.spec.ts",
+        "**/*.test.ts"
+    ],
+    "tsconfig": "tsconfig.prod.json"
+}

package/packages/pdf-lite/vitest.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from 'vitest/config'
+import { playwright } from '@vitest/browser-playwright'
+
+export default defineConfig({
+    test: {
+        isolate: true,
+        projects: [
+            {
+                test: {
+                    name: 'node',
+                    environment: 'node',
+                    include: ['**/*.node.(test|spec).ts'],
+                    exclude: ['node_modules'],
+                },
+            },
+            {
+                test: {
+                    name: 'browser',
+                    include: ['**/*.(test|spec).ts'],
+                    exclude: ['node_modules', '**/*.node.(test|spec).ts'],
+                    browser: {
+                        // Disable CORS to test the timestamp request example
+                        provider: playwright({
+                            contextOptions: {
+                                extraHTTPHeaders: {
+                                    'Content-Type':
+                                        'application/timestamp-query',
+                                },
+                            },
+                            launchOptions: {
+                                args: ['--disable-web-security'],
+                            },
+                        }),
+                        enabled: true,
+                        headless: true,
+                        screenshotFailures: false,
+                        instances: [{ browser: 'chromium' }],
+                    },
+                },
+            },
+        ],
+    },
+})

package/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+    - 'packages/*'

package/renovate.json

@@ -0,0 +1,34 @@
+{
+    "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+    "extends": [
+        "config:recommended",
+        ":preserveSemverRanges",
+        ":rebaseStalePrs",
+        ":disableDigestUpdates",
+        "schedule:weekly",
+        "group:recommended",
+        "group:monorepos",
+        "workarounds:all"
+    ],
+    "labels": ["deps"],
+    "dependencyDashboard": true,
+    "ignorePaths": ["**/node_modules/**"],
+    "timezone": "Europe/London",
+    "schedule": ["after 2am every weekday", "before 5am every weekday"],
+    "packageRules": [
+        {
+            "minimumReleaseAge": "3 days",
+            "matchPackageNames": ["/npm/"]
+        },
+        {
+            "groupName": "patch updates",
+            "matchUpdateTypes": ["patch"],
+            "matchPackageNames": ["*"]
+        },
+        {
+            "groupName": "Typedoc",
+            "matchUpdateTypes": ["patch", "minor", "major"],
+            "matchPackageNames": ["/typedoc/"]
+        }
+    ]
+}

package/scripts/build-examples.ts

@@ -0,0 +1,30 @@
+import fs from 'fs/promises'
+
+let markdown = `# PDF-Lite Examples
+
+This directory contains example scripts demonstrating how to use the PDF-Lite library.
+
+`
+
+const examples = await fs.readdir(import.meta.dirname + '/../examples')
+for (const example of examples) {
+    if (example.endsWith('.ts')) {
+        const exampleSrc = await fs.readFile(
+            import.meta.dirname + `/../examples/${example}`,
+            'utf-8',
+        )
+        const exampleTitleStart = exampleSrc.indexOf('//')
+        const exampleTitleEnd = exampleSrc.indexOf('\n', exampleTitleStart)
+        const exampleTitle =
+            exampleTitleStart !== -1
+                ? exampleSrc
+                      .substring(exampleTitleStart + 2, exampleTitleEnd)
+                      .trim()
+                : 'Untitled Example'
+        const exampleContent = exampleSrc.substring(exampleTitleEnd + 1).trim()
+
+        markdown += `## ${exampleTitle}\n\n\`\`\`typescript\n${exampleContent}\n\`\`\`\n`
+    }
+}
+
+await fs.writeFile(import.meta.dirname + '/../EXAMPLES.md', markdown, 'utf-8')

package/scripts/bump-version.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Usage: ./bump-version.sh <new-version>
+# Example: ./bump-version.sh patch
+# Example: ./bump-version.sh 1.2.3
+# Example: ./bump-version.sh major
+
+set -e 
+
+if [ -n "$1" ]; then
+  # Bump version in root package.json
+  pnpm version --no-git-tag-version $@
+
+  # Bump version in all workspaces
+  pnpm -r exec pnpm version --no-git-tag-version $@
+
+  # Get the new version from root package.json
+  NEW_VERSION=$(node -p "require('./package.json').version")
+
+  # Make sure all packages pdf-lite* depend on latest versions of other pdf-lite* packages
+
+  echo "Updating all pdf-lite* dependencies to version $NEW_VERSION"
+
+  find . -name 'package.json' -not -path '*/node_modules/*' | while read -r pkg_file; do
+    # Only update if there are pdf-lite* dependencies
+    if grep -q '"pdf-lite' "$pkg_file"; then
+      tmp_file=$(mktemp)
+      node -e "
+        const fs = require('fs');
+        const pkg = JSON.parse(fs.readFileSync('$pkg_file', 'utf8'));
+        const newVersion = '$NEW_VERSION';
+        ['dependencies', 'devDependencies'].forEach(depType => {
+          if (pkg[depType]) {
+            Object.keys(pkg[depType]).forEach(dep => {
+              if (dep.startsWith('pdf-lite')) {
+                const initialChar = pkg[depType][dep][0];
+                if (['^', '~', '>', '<', '='].includes(initialChar)) {
+                  pkg[depType][dep] = initialChar + newVersion;
+                } else {
+                  pkg[depType][dep] = newVersion;
+                }
+              }
+            });
+          }
+        });
+        fs.writeFileSync('$tmp_file', JSON.stringify(pkg, null, 2) + '\n');
+      "
+      mv "$tmp_file" "$pkg_file"
+      echo "Updated $pkg_file"
+    fi
+  done
+
+  echo "Version bump completed successfully to $NEW_VERSION"
+fi
+
+# Update lockfile
+pnpm install --lockfile-only

package/scripts/gen-html-docs.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e
+
+NEW_VERSION=$1
+
+if [ -z "$NEW_VERSION" ]; then
+    echo "Usage: $0 <new-version>"
+    exit 1
+fi
+
+echo "Generating HTML docs for version: $NEW_VERSION"
+
+pnpm exec typedoc \
+    --options typedoc.json \
+    --out docs-html/$NEW_VERSION \
+    --projectDocuments 'README.md' \
+    --projectDocuments 'CONTRIBUTING.md' \
+    --projectDocuments 'EXAMPLES.md' \
+    --githubPages \
+    --includeVersion

package/scripts/gen-md-docs.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+set -e
+
+URL="https://jacobshirley.github.io/pdf-lite"
+
+# Get latest version from package.json
+MAJOR_VERSION=$(node -p "require('./package.json').version.split('.')[0]")
+echo "Generating docs for version: $MAJOR_VERSION"
+
+# Update absolute doc links to versioned path
+find . -type f -name '*.md' -exec sed -i "s|$URL/v[0-9a-zA-Z._-]*|$URL/v$MAJOR_VERSION|g" {} +
+
+# Generate markdown docs
+pnpm exec typedoc --options typedoc.json --plugin typedoc-plugin-markdown --readme none && pnpm format

package/scripts/prepare-release.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Usage: ./prepare-release.sh
+
+set -e 
+
+force_args=()
+if [[ " $* " == *" --force=true"* ]]; then
+    force_args+=("--force")
+fi
+
+# Stage all
+git add --all
+
+# Get current version
+CURRENT_VERSION=$(node -p "require('./package.json').version")
+
+# Output the current version to use in other steps
+echo "$CURRENT_VERSION" > .release-version
+
+# Create a new branch for the release
+git checkout -b "release/v$CURRENT_VERSION"
+
+# Commit the changes
+git commit -m "release(v$CURRENT_VERSION): prepare"
+
+# Push the branch to the remote repository
+git push origin "release/v$CURRENT_VERSION" -u "${force_args[@]}"
+
+if [[ " $* " == *" --create-pr "* ]]; then
+    # Create a pull request using GitHub CLI
+    PR_TITLE="chore: prerelease $CURRENT_VERSION"
+    gh pr create --fill --head "release/v$CURRENT_VERSION" --base master --body "Automated prerelease branch for version $CURRENT_VERSION" || true # Ignore errors if PR already exists
+fi

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "compilerOptions": {
+        "target": "ES2023",
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "resolveJsonModule": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "isolatedModules": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "skipLibCheck": true,
+        "lib": ["DOM", "ESNext"],
+        "allowJs": true,
+        "incremental": true,
+        "allowArbitraryExtensions": true,
+        "erasableSyntaxOnly": true
+    },
+    "include": ["examples/**/*", "scripts/**/*"]
+}

package/tsconfig.prod.json

@@ -0,0 +1,12 @@
+{
+    "extends": "./tsconfig.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "sourceMap": false,
+        "composite": false,
+        "incremental": false,
+        "declarationMap": false
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["test/**/*.test.ts"]
+}

package/typedoc.json

@@ -0,0 +1,34 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["packages/*"],
+    "exclude": [
+        "**/node_modules/**",
+        "**/test/**",
+        "**/scripts/**",
+        "**/dist/**",
+        "**/*.spec.ts",
+        "**/*.test.ts"
+    ],
+    "name": "PKI-Lite",
+    "entryPointStrategy": "packages",
+    "disableSources": true,
+    "alwaysCreateEntryPointModule": false,
+    "cleanOutputDir": true,
+    "pretty": true,
+    "packageOptions": {
+        "includeVersion": false,
+        "exclude": [
+            "**/node_modules/**",
+            "**/test/**",
+            "**/scripts/**",
+            "**/dist/**",
+            "**/*.spec.ts",
+            "**/*.test.ts"
+        ],
+        "entryPoints": ["src/index.ts"]
+    },
+    "searchInDocuments": true,
+    "searchGroupBoosts": {
+        "Classes": 3
+    }
+}