pdf-oxide-fips 0.3.47

package/lib/builders/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PDF Oxide Builders - Fluent APIs for configuring PDF operations
+ *
+ * This module exports builder classes that implement the fluent builder pattern
+ * for configuring PDF documents, annotations, search options, metadata, and conversion.
+ */
+export * from './annotation-builder';
+export * from './conversion-options-builder';
+export * from './document-builder';
+export * from './metadata-builder';
+export * from './pdf-builder';
+export * from './search-options-builder';
+export * from './streaming-table';

package/lib/builders/index.js

@@ -0,0 +1,13 @@
+/**
+ * PDF Oxide Builders - Fluent APIs for configuring PDF operations
+ *
+ * This module exports builder classes that implement the fluent builder pattern
+ * for configuring PDF documents, annotations, search options, metadata, and conversion.
+ */
+export * from './annotation-builder.js';
+export * from './conversion-options-builder.js';
+export * from './document-builder.js';
+export * from './metadata-builder.js';
+export * from './pdf-builder.js';
+export * from './search-options-builder.js';
+export * from './streaming-table.js';

package/lib/builders/metadata-builder.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Builder for document metadata configuration
+ *
+ * Configures document information like title, author, subject, keywords,
+ * creation date, and custom properties.
+ *
+ * @example
+ * ```typescript
+ * import { MetadataBuilder } from 'pdf_oxide';
+ *
+ * const metadata = MetadataBuilder.create()
+ *   .title('My Document')
+ *   .author('John Doe')
+ *   .subject('Important Information')
+ *   .keywords(['document', 'important', 'example'])
+ *   .creator('MyApp v1.0')
+ *   .build();
+ *
+ * pdf.setMetadata(metadata);
+ * ```
+ */
+export interface Metadata {
+    title?: string;
+    author?: string;
+    subject?: string;
+    keywords: string[];
+    creator?: string;
+    producer: string;
+    creationDate: Date;
+    modificationDate: Date;
+    customProperties: Record<string, string>;
+}
+export declare class MetadataBuilder {
+    private _title?;
+    private _author?;
+    private _subject?;
+    private _keywords;
+    private _creator?;
+    private _producer;
+    private _creationDate;
+    private _modificationDate;
+    private _customProperties;
+    /**
+     * Creates a new MetadataBuilder instance
+     * @private
+     */
+    private constructor();
+    /**
+     * Creates a new MetadataBuilder instance
+     * @returns New builder instance
+     */
+    static create(): MetadataBuilder;
+    /**
+     * Sets the document title
+     * @param title - The document title
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.title('Project Report 2024');
+     * ```
+     */
+    title(title: string): this;
+    /**
+     * Sets the document author
+     * @param author - The author name
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.author('Jane Doe');
+     * ```
+     */
+    author(author: string): this;
+    /**
+     * Sets the document subject
+     * @param subject - The document subject
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.subject('Annual Report');
+     * ```
+     */
+    subject(subject: string): this;
+    /**
+     * Sets document keywords
+     * @param keywords - Array of keywords
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.keywords(['report', 'annual', 'financial']);
+     * ```
+     */
+    keywords(keywords: string[]): this;
+    /**
+     * Adds a single keyword
+     * @param keyword - A keyword to add
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addKeyword('Important').addKeyword('Urgent');
+     * ```
+     */
+    addKeyword(keyword: string): this;
+    /**
+     * Sets the creator application name
+     * @param creator - Name of the application that created the document
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.creator('MyApp v2.1.0');
+     * ```
+     */
+    creator(creator: string): this;
+    /**
+     * Sets the PDF producer (usually the library/tool that saved it)
+     * @param producer - Name of the PDF producer
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.producer('PDF Oxide v0.3.2');
+     * ```
+     */
+    producer(producer: string): this;
+    /**
+     * Sets the document creation date
+     * @param date - The creation date
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.creationDate(new Date('2024-01-15'));
+     * ```
+     */
+    creationDate(date: Date): this;
+    /**
+     * Sets the document modification date
+     * @param date - The modification date
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.modificationDate(new Date());
+     * ```
+     */
+    modificationDate(date: Date): this;
+    /**
+     * Sets a custom metadata property
+     * @param key - Property key
+     * @param value - Property value
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.customProperty('Department', 'Engineering');
+     * builder.customProperty('Classification', 'Confidential');
+     * ```
+     */
+    customProperty(key: string, value: string): this;
+    /**
+     * Sets multiple custom metadata properties
+     * @param properties - Object with key-value pairs
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.customProperties({
+     *   Department: 'Engineering',
+     *   Classification: 'Confidential',
+     *   ProjectCode: 'PROJ-2024-001'
+     * });
+     * ```
+     */
+    customProperties(properties: Record<string, string>): this;
+    /**
+     * Builds and returns the metadata object
+     * @returns Immutable metadata object
+     *
+     * @example
+     * ```typescript
+     * const metadata = builder.build();
+     * ```
+     */
+    build(): Metadata;
+    /**
+     * Creates metadata with current timestamp
+     * @returns This builder with current modification date
+     */
+    withCurrentDate(): this;
+}
+/**
+ * Create a new MetadataBuilder with static factory
+ * @deprecated Use MetadataBuilder.create() instead
+ * @returns New builder instance
+ */
+export declare function createMetadataBuilder(): MetadataBuilder;

package/lib/builders/metadata-builder.js

@@ -0,0 +1,285 @@
+/**
+ * Builder for document metadata configuration
+ *
+ * Configures document information like title, author, subject, keywords,
+ * creation date, and custom properties.
+ *
+ * @example
+ * ```typescript
+ * import { MetadataBuilder } from 'pdf_oxide';
+ *
+ * const metadata = MetadataBuilder.create()
+ *   .title('My Document')
+ *   .author('John Doe')
+ *   .subject('Important Information')
+ *   .keywords(['document', 'important', 'example'])
+ *   .creator('MyApp v1.0')
+ *   .build();
+ *
+ * pdf.setMetadata(metadata);
+ * ```
+ */
+export class MetadataBuilder {
+    /**
+     * Creates a new MetadataBuilder instance
+     * @private
+     */
+    constructor() {
+        this._keywords = [];
+        this._producer = 'PDF Oxide';
+        this._creationDate = new Date();
+        this._modificationDate = new Date();
+        this._customProperties = {};
+    }
+    /**
+     * Creates a new MetadataBuilder instance
+     * @returns New builder instance
+     */
+    static create() {
+        return new MetadataBuilder();
+    }
+    /**
+     * Sets the document title
+     * @param title - The document title
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.title('Project Report 2024');
+     * ```
+     */
+    title(title) {
+        if (typeof title !== 'string') {
+            throw new Error('Title must be a string');
+        }
+        this._title = title.length > 0 ? title : undefined;
+        return this;
+    }
+    /**
+     * Sets the document author
+     * @param author - The author name
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.author('Jane Doe');
+     * ```
+     */
+    author(author) {
+        if (typeof author !== 'string') {
+            throw new Error('Author must be a string');
+        }
+        this._author = author.length > 0 ? author : undefined;
+        return this;
+    }
+    /**
+     * Sets the document subject
+     * @param subject - The document subject
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.subject('Annual Report');
+     * ```
+     */
+    subject(subject) {
+        if (typeof subject !== 'string') {
+            throw new Error('Subject must be a string');
+        }
+        this._subject = subject.length > 0 ? subject : undefined;
+        return this;
+    }
+    /**
+     * Sets document keywords
+     * @param keywords - Array of keywords
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.keywords(['report', 'annual', 'financial']);
+     * ```
+     */
+    keywords(keywords) {
+        if (!Array.isArray(keywords)) {
+            throw new Error('Keywords must be an array');
+        }
+        if (!keywords.every((k) => typeof k === 'string')) {
+            throw new Error('All keywords must be strings');
+        }
+        this._keywords = [...keywords];
+        return this;
+    }
+    /**
+     * Adds a single keyword
+     * @param keyword - A keyword to add
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.addKeyword('Important').addKeyword('Urgent');
+     * ```
+     */
+    addKeyword(keyword) {
+        if (typeof keyword !== 'string' || keyword.length === 0) {
+            throw new Error('Keyword must be a non-empty string');
+        }
+        if (!this._keywords.includes(keyword)) {
+            this._keywords.push(keyword);
+        }
+        return this;
+    }
+    /**
+     * Sets the creator application name
+     * @param creator - Name of the application that created the document
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.creator('MyApp v2.1.0');
+     * ```
+     */
+    creator(creator) {
+        if (typeof creator !== 'string') {
+            throw new Error('Creator must be a string');
+        }
+        this._creator = creator.length > 0 ? creator : undefined;
+        return this;
+    }
+    /**
+     * Sets the PDF producer (usually the library/tool that saved it)
+     * @param producer - Name of the PDF producer
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.producer('PDF Oxide v0.3.2');
+     * ```
+     */
+    producer(producer) {
+        if (typeof producer !== 'string') {
+            throw new Error('Producer must be a string');
+        }
+        this._producer = producer.length > 0 ? producer : 'PDF Oxide';
+        return this;
+    }
+    /**
+     * Sets the document creation date
+     * @param date - The creation date
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.creationDate(new Date('2024-01-15'));
+     * ```
+     */
+    creationDate(date) {
+        if (!(date instanceof Date)) {
+            throw new Error('creationDate must be a Date object');
+        }
+        this._creationDate = new Date(date);
+        return this;
+    }
+    /**
+     * Sets the document modification date
+     * @param date - The modification date
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.modificationDate(new Date());
+     * ```
+     */
+    modificationDate(date) {
+        if (!(date instanceof Date)) {
+            throw new Error('modificationDate must be a Date object');
+        }
+        this._modificationDate = new Date(date);
+        return this;
+    }
+    /**
+     * Sets a custom metadata property
+     * @param key - Property key
+     * @param value - Property value
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.customProperty('Department', 'Engineering');
+     * builder.customProperty('Classification', 'Confidential');
+     * ```
+     */
+    customProperty(key, value) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new Error('Property key must be a non-empty string');
+        }
+        if (typeof value !== 'string') {
+            throw new Error('Property value must be a string');
+        }
+        this._customProperties[key] = value;
+        return this;
+    }
+    /**
+     * Sets multiple custom metadata properties
+     * @param properties - Object with key-value pairs
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.customProperties({
+     *   Department: 'Engineering',
+     *   Classification: 'Confidential',
+     *   ProjectCode: 'PROJ-2024-001'
+     * });
+     * ```
+     */
+    customProperties(properties) {
+        if (typeof properties !== 'object' || properties === null) {
+            throw new Error('customProperties must be an object');
+        }
+        for (const [key, value] of Object.entries(properties)) {
+            if (typeof value !== 'string') {
+                throw new Error(`Custom property "${key}" value must be a string`);
+            }
+            this._customProperties[key] = value;
+        }
+        return this;
+    }
+    /**
+     * Builds and returns the metadata object
+     * @returns Immutable metadata object
+     *
+     * @example
+     * ```typescript
+     * const metadata = builder.build();
+     * ```
+     */
+    build() {
+        return {
+            title: this._title,
+            author: this._author,
+            subject: this._subject,
+            keywords: [...this._keywords],
+            creator: this._creator,
+            producer: this._producer,
+            creationDate: new Date(this._creationDate),
+            modificationDate: new Date(this._modificationDate),
+            customProperties: { ...this._customProperties },
+        };
+    }
+    /**
+     * Creates metadata with current timestamp
+     * @returns This builder with current modification date
+     */
+    withCurrentDate() {
+        this._modificationDate = new Date();
+        return this;
+    }
+}
+/**
+ * Create a new MetadataBuilder with static factory
+ * @deprecated Use MetadataBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createMetadataBuilder() {
+    return MetadataBuilder.create();
+}