@peculiar/pdf-form-json 1.17.0

package/README.md

@@ -0,0 +1,148 @@
+# `@peculiar/pdf-form-json`
+
+`@peculiar/pdf-form-json` is a library for working with PDF form data in JSON format. This library provides a FormConverter class that can convert a PDF document with form data into a JSON representation of that data, and also set values on form components based on a JSON payload.
+
+## Installation
+
+Using npm:
+
+```bash
+npm install @peculiar/pdf-form-json
+```
+
+Using yarn:
+
+```bash
+yarn add @peculiar/pdf-form-json
+```
+
+## Usage
+
+### Import
+
+```typescript
+import { FormConverter } from "@peculiar/pdf-form-json";
+```
+
+### Export Form Data to JSON
+
+The export method of the `FormConverter` class can be used to convert a PDF document with form data into a JSON representation of that data. The returned JSON will be of the format:
+
+```typescript
+{
+  form: {
+    [componentName: string]: {
+      type: string,
+      id: string,
+      name: string,
+      position: {
+        left: number,
+        top: number,
+        height: number,
+        width: number,
+      },
+      flags: {
+        hidden: boolean,
+        invisible: boolean,
+        locked: boolean,
+        lockedContents: boolean,
+        noExport: boolean,
+        noRotate: boolean,
+        noView: boolean,
+        noZoom: boolean,
+        print: boolean,
+        readOnly: boolean,
+        readOnlyAnnot: boolean,
+        required: boolean,
+        toggleNoView: boolean,
+      },
+      [otherProperties: string]: any,
+    },
+    ...
+  }
+}
+```
+
+```typescript
+import fs from "fs";
+import { PDFDocument } from ("@peculiar/pdf-doc");
+import { globalFormConverter } from ("@peculiar/pdf-form-json");
+
+// Load PDF document
+const pdfBytes = fs.readFileSync("input.pdf");
+const pdfDoc = await PDFDocument.load(pdfBytes);
+
+// Export form data to JSON
+const formData = globalFormConverter.export(pdfDoc);
+
+// Write JSON to file
+fs.writeFileSync("output.json", JSON.stringify(formData, null, 2));
+```
+
+### Set Form Component Values from JSON
+
+The setValue method of the FormConverter class can be used to set values on form components based on a JSON payload. The payload should be an array of objects, where each object represents a form component and its updated value. The objects should have the following properties:
+
+- `name` (string): The name of the form component to update.
+- `type` (string): The type of the form component to update.
+- Additional properties for the specific form component type being updated.
+
+```typescript
+import fs from "fs";
+import { PDFDocument } from ("@peculiar/pdf-doc");
+import { globalFormConverter } from ("@peculiar/pdf-form-json");
+
+// Load PDF document
+const pdfBytes = fs.readFileSync("input.pdf");
+const pdfDoc = await PDFDocument.load(pdfBytes);
+
+// Update PDF form
+globalFormConverter.setValue(doc, [
+  {
+    name: "Text1",
+    type: "text_editor",
+    text: "Some message",
+  },
+  {
+    name: "Check Box2",
+    type: "check_box",
+    checked: true,
+  },
+  {
+    name: "Check Box3",
+    type: "check_box",
+    checked: false,
+  },
+  {
+    name: "Group4",
+    type: "radio_button_group",
+    selected: "Choice2",
+  },
+  {
+    name: "Dropdown5",
+    type: "combo_box",
+    selected: ["option2"],
+  }
+]);
+
+// Save file
+const pdfRaw = await pdfDoc.save();
+fs.writeFileSync("output.pdf", pdfRaw, {flags: "w+"})
+```
+
+## License
+
+This project is dual-licensed under the AGPL-3.0 and a Commercial License:
+
+### AGPL-3.0
+
+The library is open-source and freely available under the terms of the Affero General Public License (AGPL-3.0). This ensures that modifications and usage in network-based applications (e.g., SaaS) must be shared under the same license.
+
+You can use the library under AGPL-3.0 if:
+
+- Your project is open-source and distributed under a compatible license
+- Your use complies with the AGPL-3.0 requirements
+
+### Commercial License
+
+For use in proprietary, closed-source, or commercial projects where the AGPL is not suitable, a commercial license is available. This allows you to use the library without the AGPL's obligations.

package/build/index.d.ts

@@ -0,0 +1,250 @@
+import * as pdfDoc from '@peculiar/pdf-doc';
+import { FormComponentType } from '@peculiar/pdf-doc';
+
+/**
+ * Type representing a constructor for an IComponent instance.
+ */
+type IComponentConstructor<T extends pdfDoc.IComponent> = new (target: any, doc: pdfDoc.PDFDocument) => T;
+/**
+ * Interface representing the JSON object for a form component.
+ */
+interface JsonComponent {
+    name: string;
+}
+/**
+ * Interface representing the JSON object for a PDF form.
+ */
+interface JsonForm {
+    form: Record<string, JsonComponent>;
+}
+/**
+ * Interface representing the update data for a form component.
+ */
+interface JsonComponentUpdate {
+    type: FormComponentType[keyof FormComponentType];
+    name: string;
+}
+/**
+ * Interface representing the update data for a check box form component.
+ */
+interface JsonCheckBoxUpdate extends JsonComponentUpdate {
+    type: "check_box";
+    checked: boolean;
+}
+/**
+ * Interface representing the update data for a radio button form component.
+ */
+interface JsonRadioButtonUpdate extends JsonComponentUpdate {
+    type: "radio_button";
+    checked: boolean;
+}
+/**
+ * Interface representing the update data for a radio button group form component.
+ */
+interface JsonRadioButtonGroupUpdate extends JsonComponentUpdate {
+    type: "radio_button_group";
+    selected: string;
+}
+/**
+ * Interface representing the update data for a combo box form component.
+ */
+interface JsonComboBoxUpdate extends JsonComponentUpdate {
+    type: "combo_box";
+    selected: string[];
+}
+/**
+ * Interface representing the update data for a text editor form component.
+ */
+interface JsonTextEditorUpdate extends JsonComponentUpdate {
+    type: "text_editor";
+    text: string;
+}
+/**
+ * Union type for all possible types of form component updates.
+ */
+type JsonUpdateMixed = JsonCheckBoxUpdate | JsonRadioButtonGroupUpdate | JsonRadioButtonUpdate | JsonComboBoxUpdate | JsonTextEditorUpdate;
+
+/**
+ * Abstract class representing a ComponentConverter for an IComponent type.
+ */
+declare abstract class ComponentConverter<T extends pdfDoc.IComponent> {
+    /**
+     * The constructor function for the associated IComponent type.
+     */
+    type: pdfDoc.IComponentConstructor<T>;
+    /**
+     * The string value of the FormComponentType for the associated IComponent type.
+     */
+    abstract typeJSON: string;
+    constructor(type: pdfDoc.IComponentConstructor<T>);
+    /**
+     * Exports a component to a JSON object.
+     * @param component - The component to export.
+     * @returns The JSON object representing the component.
+     */
+    abstract export(component: T): JsonComponent;
+    /**
+     * Sets the value of a component based on update data.
+     * @param component - The component to update.
+     * @param data - The update data for the component.
+     */
+    abstract setValue(component: T, data: JsonComponentUpdate): void;
+}
+
+/**
+ * The ComponentConverterFactory is a factory that creates ComponentConverter instances for IComponent types.
+ * It contains a map of ComponentConverter instances, keyed by their associated IComponent type.
+ *
+ * @remarks
+ * To create a new ComponentConverter instance, call the register method with a new instance of the converter.
+ */
+declare class ComponentConverterFactory {
+    /**
+     * A map of ComponentConverter instances, keyed by their associated IComponent type.
+     */
+    protected items: Map<IComponentConstructor<pdfDoc.IComponent>, ComponentConverter<pdfDoc.IComponent>>;
+    constructor(...converters: ComponentConverter<pdfDoc.IComponent>[]);
+    /**
+     * Registers a new ComponentConverter instance for a given IComponent type.
+     *
+     * @param converter - The ComponentConverter instance to register.
+     */
+    register(converter: ComponentConverter<pdfDoc.IComponent>): void;
+    /**
+     * Finds a ComponentConverter instance for a given IComponent type.
+     *
+     * @typeparam T - The IComponent type to find a converter for.
+     * @param type - The constructor function for the IComponent type to find a converter for.
+     * @returns The ComponentConverter instance for the given IComponent type, or null if not found.
+     */
+    find<T extends pdfDoc.IComponent>(type: IComponentConstructor<T>): ComponentConverter<T> | null;
+    /**
+     * Gets a ComponentConverter instance for a given IComponent type.
+     *
+     * @typeparam T - The IComponent type to get a converter for.
+     * @param type - The constructor function for the IComponent type to get a converter for.
+     * @returns The ComponentConverter instance for the given IComponent type.
+     * @throws If no converter is found for the given IComponent type.
+     */
+    get<T extends pdfDoc.IComponent>(type: IComponentConstructor<T>): ComponentConverter<T>;
+}
+
+/**
+ * Abstract class representing a ComponentConverter for a FormComponentGroup type.
+ * @typeparam T - The FormComponentGroup type to convert.
+ */
+declare abstract class FieldConverter<T extends pdfDoc.FormComponentGroup> extends ComponentConverter<T> {
+    export(component: T): JsonComponent;
+    /**
+     *
+     * @param component Called to add additional data to the JSON object representing the form component.
+     * @param component - The form component to export.
+     * @param json - The JSON object representing the form component.
+     */
+    protected abstract onExport(component: T, json: Record<string, unknown>): void;
+}
+
+/**
+ * Abstract class representing a ComponentConverter for a FormComponent type.
+ * @typeparam T - The FormComponent type to convert.
+ */
+declare abstract class WidgetConverter<T extends pdfDoc.FormComponent> extends ComponentConverter<T> {
+    export(component: T): JsonComponent;
+    /**
+     * Called to add additional data to the JSON object representing the form component.
+     * @param component - The form component to export.
+     * @param json - The JSON object representing the form component.
+     */
+    protected abstract onExport(component: T, json: Record<string, unknown>): void;
+}
+
+/**
+ * A ComponentConverter for CheckBox form components.
+ */
+declare class CheckBoxConverter extends WidgetConverter<pdfDoc.CheckBox> {
+    typeJSON: pdfDoc.FormComponentType.checkBox;
+    constructor();
+    protected onExport(component: pdfDoc.CheckBox, json: Record<string, unknown>): void;
+    setValue(component: pdfDoc.CheckBox, data: JsonCheckBoxUpdate): void;
+}
+
+/**
+ * A ComponentConverter for ComboBox form components.
+ */
+declare class ComboBoxConverter extends WidgetConverter<pdfDoc.ComboBox> {
+    typeJSON: pdfDoc.FormComponentType.comboBox;
+    constructor();
+    protected onExport(component: pdfDoc.ComboBox, json: Record<string, unknown>): void;
+    setValue(component: pdfDoc.ComboBox, data: JsonComboBoxUpdate): void;
+}
+
+/**
+ * A ComponentConverter for RadioButton form components.
+ */
+declare class RadioButtonConverter extends WidgetConverter<pdfDoc.RadioButton> {
+    typeJSON: pdfDoc.FormComponentType.radioButton;
+    constructor();
+    protected onExport(component: pdfDoc.RadioButton, json: Record<string, unknown>): void;
+    setValue(component: pdfDoc.RadioButton, data: JsonRadioButtonUpdate): void;
+}
+
+/**
+ * A ComponentConverter for RadioButtonGroup form components.
+ */
+declare class RadioButtonGroupConverter extends FieldConverter<pdfDoc.RadioButtonGroup> {
+    typeJSON: pdfDoc.FormComponentType.radioButtonGroup;
+    constructor();
+    protected onExport(component: pdfDoc.RadioButtonGroup, json: Record<string, unknown>): void;
+    setValue(component: pdfDoc.RadioButtonGroup, data: JsonRadioButtonGroupUpdate): void;
+}
+
+/**
+ * A ComponentConverter for TextEditor form components.
+ */
+declare class TextEditorConverter extends WidgetConverter<pdfDoc.TextEditor> {
+    typeJSON: pdfDoc.FormComponentType.textEditor;
+    constructor();
+    protected onExport(component: pdfDoc.TextEditor, json: Record<string, unknown>): void;
+    setValue(component: pdfDoc.TextEditor, data: JsonTextEditorUpdate): void;
+}
+
+/**
+ * A utility class for exporting and updating PDF form components.
+ */
+declare class FormConverter {
+    /**
+     * The ComponentConverterFactory instance to use for converting PDF form components to JSON.
+     */
+    registry: ComponentConverterFactory;
+    /**
+     * Creates a FormConverter instance.
+     * @param registry - The ComponentConverterFactory instance to use for converting PDF form components to JSON.
+     */
+    constructor(registry: ComponentConverterFactory);
+    /**
+     * Exports all PDF form components in a document to JSON format.
+     * @param doc - The PDF document to export the form components from.
+     * @returns An object containing JSON representations of all form components in the document.
+     */
+    export(doc: pdfDoc.PDFDocument): JsonForm;
+    /**
+     * Exports a single PDF form component to JSON format.
+     * @param component - The PDF form component to export.
+     * @returns The JSON representation of the specified form component,
+     * or null if the component is not supported by the current converter registry.
+     */
+    protected exportComponent(component: pdfDoc.IComponent): JsonComponent | null;
+    /**
+     * Sets the value of one or more PDF form components based on provided JSON updates.
+     * @param doc - The PDF document containing the form components to update.
+     * @param data - An array of JSON updates to apply to the PDF form components.
+     */
+    setValue(doc: pdfDoc.PDFDocument, data: JsonUpdateMixed[]): void;
+}
+
+/**
+ * A global instance of FormConverter that uses the ComponentConverter registry.
+ */
+declare const globalFormConverter: FormConverter;
+
+export { CheckBoxConverter, ComboBoxConverter, ComponentConverter, ComponentConverterFactory, FieldConverter, FormConverter, type IComponentConstructor, type JsonCheckBoxUpdate, type JsonComboBoxUpdate, type JsonComponent, type JsonComponentUpdate, type JsonForm, type JsonRadioButtonGroupUpdate, type JsonRadioButtonUpdate, type JsonTextEditorUpdate, type JsonUpdateMixed, RadioButtonConverter, RadioButtonGroupConverter, TextEditorConverter, WidgetConverter, globalFormConverter };

package/build/peculiar.pdf.form.es.js

@@ -0,0 +1,203 @@
+import * as pdfDoc from '@peculiar/pdf-doc';
+
+class ComponentConverter {
+    constructor(type) {
+        this.type = type;
+    }
+}
+
+class ComponentConverterFactory {
+    constructor(...converters) {
+        this.items = new Map();
+        for (const converter of converters) {
+            this.register(converter);
+        }
+    }
+    register(converter) {
+        this.items.set(converter.type, converter);
+    }
+    find(type) {
+        const converter = this.items.get(type);
+        return converter || null;
+    }
+    get(type) {
+        const converter = this.find(type);
+        if (!converter) {
+            throw new Error(`Converter not found for type ${type.name}`);
+        }
+        return converter;
+    }
+}
+
+class FieldConverter extends ComponentConverter {
+    export(component) {
+        const json = {
+            type: this.typeJSON,
+            id: component.id,
+            name: component.name
+        };
+        this.onExport(component, json);
+        return json;
+    }
+}
+
+class WidgetConverter extends ComponentConverter {
+    export(component) {
+        const json = {
+            type: this.typeJSON,
+            id: component.id,
+            name: component.name,
+            position: {
+                left: component.left,
+                top: component.top,
+                height: component.height,
+                width: component.width
+            },
+            flags: {
+                hidden: component.hidden,
+                invisible: component.invisible,
+                locked: component.locked,
+                lockedContents: component.lockedContents,
+                noExport: component.noExport,
+                noRotate: component.noRotate,
+                noView: component.noView,
+                noZoom: component.noZoom,
+                print: component.print,
+                readOnly: component.readOnly,
+                readOnlyAnnot: component.readOnlyAnnot,
+                required: component.required,
+                toggleNoView: component.toggleNoView
+            }
+        };
+        this.onExport(component, json);
+        return json;
+    }
+}
+
+class CheckBoxConverter extends WidgetConverter {
+    constructor() {
+        super(pdfDoc.CheckBox);
+        this.typeJSON = pdfDoc.FormComponentType.checkBox;
+    }
+    onExport(component, json) {
+        json.checked = component.checked;
+        json.value = component.value;
+    }
+    setValue(component, data) {
+        component.checked = data.checked;
+    }
+}
+
+class ComboBoxConverter extends WidgetConverter {
+    constructor() {
+        super(pdfDoc.ComboBox);
+        this.typeJSON = pdfDoc.FormComponentType.comboBox;
+    }
+    onExport(component, json) {
+        let flags = {};
+        if (json.flags && typeof json.flags === "object") {
+            flags = json.flags;
+        }
+        json.flags = {
+            ...flags,
+            combo: component.combo,
+            edit: component.edit,
+            sort: component.sort,
+            multiSelect: component.multiSelect,
+            doNotSpellCheck: component.doNotSpellCheck,
+            commitOnSelChange: component.commitOnSelChange
+        };
+        json.options = component.options;
+        json.selected = component.selected;
+    }
+    setValue(component, data) {
+        component.selected = data.selected;
+    }
+}
+
+class RadioButtonConverter extends WidgetConverter {
+    constructor() {
+        super(pdfDoc.RadioButton);
+        this.typeJSON = pdfDoc.FormComponentType.radioButton;
+    }
+    onExport(component, json) {
+        json.checked = component.checked;
+        json.value = component.value;
+    }
+    setValue(component, data) {
+        component.checked = data.checked;
+    }
+}
+
+class RadioButtonGroupConverter extends FieldConverter {
+    constructor() {
+        super(pdfDoc.RadioButtonGroup);
+        this.typeJSON = pdfDoc.FormComponentType.radioButtonGroup;
+    }
+    onExport(component, json) {
+        json.selected = component.selected;
+    }
+    setValue(component, data) {
+        const button = component.get(data.selected);
+        button.checked = true;
+    }
+}
+
+class TextEditorConverter extends WidgetConverter {
+    constructor() {
+        super(pdfDoc.TextEditor);
+        this.typeJSON = pdfDoc.FormComponentType.textEditor;
+    }
+    onExport(component, json) {
+        json.maxLen = component.maxLen;
+        json.multiline = component.multiline;
+        json.text = component.text;
+    }
+    setValue(component, data) {
+        component.text = data.text;
+    }
+}
+
+class FormConverter {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    export(doc) {
+        const res = {
+            form: {}
+        };
+        const components = doc.getComponents();
+        for (const component of components) {
+            const obj = this.exportComponent(component);
+            if (obj) {
+                res.form[obj.name] = obj;
+            }
+        }
+        return res;
+    }
+    exportComponent(component) {
+        const converter = this.registry.find(component.constructor);
+        if (converter) {
+            return converter.export(component);
+        }
+        return null;
+    }
+    setValue(doc, data) {
+        for (const item of data) {
+            const component = doc.getComponentByName(item.name);
+            if (!component) {
+                continue;
+            }
+            const converter = this.registry.find(component.constructor);
+            if (!converter || converter.typeJSON !== item.type) {
+                continue;
+            }
+            converter.setValue(component, item);
+        }
+    }
+}
+
+const registry = new ComponentConverterFactory(new CheckBoxConverter(), new RadioButtonConverter(), new TextEditorConverter(), new ComboBoxConverter(), new ComboBoxConverter(), new RadioButtonGroupConverter());
+const globalFormConverter = new FormConverter(registry);
+
+export { CheckBoxConverter, ComboBoxConverter, ComponentConverter, ComponentConverterFactory, FieldConverter, FormConverter, RadioButtonConverter, RadioButtonGroupConverter, TextEditorConverter, WidgetConverter, globalFormConverter };