feat: add PDFField.rename() method for renaming form fields

Adds ability to rename form fields by changing their partial name.
The method validates that:
- New name is not empty
- New name doesn't contain periods (which are hierarchy separators)
- No sibling field (terminal or non-terminal) has the same name

Includes comprehensive tests for various rename scenarios.

Hopding/pdf-lib#1748

Coded by an LLM.

Author: folknor

src/api/form/PDFField.ts

@@ -15,6 +15,10 @@ import {
   assertOrUndefined,
 } from '../../utils/index.js';
 import { type Color, colorToComponents, setFillingColor } from '../colors.js';
+import {
+  FieldAlreadyExistsError,
+  InvalidFieldNamePartError,
+} from '../errors.js';
 import { ImageAlignment } from '../image/index.js';
 import { drawImage, rotateInPlace } from '../operations.js';
 import PDFDocument from '../PDFDocument.js';
@@ -133,6 +137,73 @@ export default class PDFField {
     return this.acroField.getFullyQualifiedName() ?? '';
   }
 
+  /**
+   * Rename this field by changing its partial name. The partial name is the
+   * last component of the fully qualified name.
+   *
+   * For example, if a field's fully qualified name is `person.name.first`
+   * and you call `rename('given')`, the new fully qualified name will be
+   * `person.name.given`.
+   *
+   * ```js
+   * const field = form.getField('employee.name')
+   * console.log(field.getName()) // 'employee.name'
+   * field.rename('fullName')
+   * console.log(field.getName()) // 'employee.fullName'
+   * ```
+   *
+   * Note: this only changes the partial name, not the field's position in
+   * the hierarchy. To move a field to a different parent, you would need to
+   * create a new field and copy its properties.
+   *
+   * @param newPartialName The new partial name for this field.
+   * @throws `InvalidFieldNamePartError` if the name contains periods.
+   * @throws `FieldAlreadyExistsError` if a sibling field already has this name.
+   */
+  rename(newPartialName: string): void {
+    assertIs(newPartialName, 'newPartialName', ['string']);
+
+    if (newPartialName.length === 0) {
+      throw new Error('Field name must not be empty');
+    }
+
+    if (newPartialName.includes('.')) {
+      throw new InvalidFieldNamePartError(newPartialName);
+    }
+
+    const currentName = this.getName();
+    const parent = this.acroField.getParent();
+    const parentFullName = parent?.getFullyQualifiedName();
+    const newFullName = parentFullName
+      ? `${parentFullName}.${newPartialName}`
+      : newPartialName;
+
+    // If name isn't changing, nothing to do
+    if (newFullName === currentName) return;
+
+    const form = this.doc.getForm();
+
+    // Check for conflict with existing terminal field
+    const existingField = form.getFieldMaybe(newFullName);
+    if (existingField) {
+      throw new FieldAlreadyExistsError(newFullName);
+    }
+
+    // Check for conflict with existing non-terminal (container) field.
+    // A non-terminal with this name exists if any field's fully qualified
+    // name starts with the new name followed by a period.
+    const prefix = newFullName + '.';
+    const allFields = form.getFields();
+    for (let i = 0, len = allFields.length; i < len; i++) {
+      if (allFields[i]!.getName().startsWith(prefix)) {
+        throw new FieldAlreadyExistsError(newFullName);
+      }
+    }
+
+    // All checks passed - rename the field
+    this.acroField.setPartialName(newPartialName);
+  }
+
   /**
    * Get all widgets for this field. Each widget represents a visual instance
    * of the field on a page. Most fields have only one widget, but some fields

tests/api/form/PDFForm.spec.ts

@@ -1735,4 +1735,119 @@ describe('PDFForm', () => {
       expect(retrievedFields).toEqual([]);
     });
   });
+
+  describe('PDFField.rename()', () => {
+    it('can rename a root-level field', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('oldName');
+      field.setText('test value');
+
+      expect(field.getName()).toBe('oldName');
+      field.rename('newName');
+      expect(field.getName()).toBe('newName');
+      expect(field.getText()).toBe('test value'); // Value preserved
+    });
+
+    it('can rename a nested field', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('person.name.first');
+
+      expect(field.getName()).toBe('person.name.first');
+      field.rename('given');
+      expect(field.getName()).toBe('person.name.given');
+    });
+
+    it('throws if new name contains a period', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('myField');
+
+      expect(() => field.rename('new.name')).toThrow(
+        'Field name contains invalid component',
+      );
+    });
+
+    it('throws if new name is empty', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('myField');
+
+      expect(() => field.rename('')).toThrow('Field name must not be empty');
+    });
+
+    it('throws if a sibling field already has the same name', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      form.createTextField('fieldA');
+      const fieldB = form.createTextField('fieldB');
+
+      expect(() => fieldB.rename('fieldA')).toThrow(
+        'A field already exists with the specified name',
+      );
+    });
+
+    it('throws if renaming would conflict with nested sibling', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      form.createTextField('parent.child1');
+      const field = form.createTextField('parent.child2');
+
+      expect(() => field.rename('child1')).toThrow(
+        'A field already exists with the specified name',
+      );
+    });
+
+    it('throws if renaming would conflict with a non-terminal field', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      // Creates non-terminal 'person' containing terminal 'person.name'
+      form.createTextField('person.name');
+      const field = form.createTextField('otherField');
+
+      // Renaming to 'person' should fail because 'person' exists as non-terminal
+      expect(() => field.rename('person')).toThrow(
+        'A field already exists with the specified name',
+      );
+    });
+
+    it('no-ops if renaming to the same name', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('myField');
+
+      // Should not throw
+      field.rename('myField');
+      expect(field.getName()).toBe('myField');
+    });
+
+    it('preserves field properties after rename', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('original');
+      field.setText('Hello World');
+      field.enableReadOnly();
+      field.enableRequired();
+
+      field.rename('renamed');
+
+      expect(field.getName()).toBe('renamed');
+      expect(field.getText()).toBe('Hello World');
+      expect(field.isReadOnly()).toBe(true);
+      expect(field.isRequired()).toBe(true);
+    });
+
+    it('allows the renamed field to be retrieved by new name', async () => {
+      const pdfDoc = await PDFDocument.create();
+      const form = pdfDoc.getForm();
+      const field = form.createTextField('oldName');
+
+      field.rename('newName');
+
+      expect(() => form.getField('oldName')).toThrow();
+      // getField returns a new wrapper, so compare by ref
+      expect(form.getField('newName').ref).toBe(field.ref);
+    });
+  });
 });