pdf-oxide 0.3.24

package/src/builders/pdf-builder.ts

@@ -0,0 +1,386 @@
+/**
+ * Fluent builder for creating PDF documents with configuration
+ *
+ * Provides a fluent API for configuring PDF document metadata and options
+ * before document creation.
+ *
+ * @example
+ * ```typescript
+ * import { PdfBuilder } from 'pdf_oxide';
+ *
+ * const pdf = PdfBuilder.create()
+ *   .title('My Document')
+ *   .author('John Doe')
+ *   .subject('PDF Creation')
+ *   .keywords(['pdf', 'document', 'example'])
+ *   .fromMarkdown('# Content\n\nMarkdown text here');
+ *
+ * pdf.save('output.pdf');
+ * ```
+ */
+
+interface PdfBuilderConfig {
+  title?: string;
+  author?: string;
+  subject?: string;
+  keywords: string[];
+  pageSize?: string;
+  margins: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+}
+
+export class PdfBuilder {
+  private _title?: string;
+  private _author?: string;
+  private _subject?: string;
+  private _keywords: string[] = [];
+  private _pageSize?: string;
+  private _margins: { top: number; right: number; bottom: number; left: number } = {
+    top: 36,
+    bottom: 36,
+    left: 36,
+    right: 36,
+  };
+
+  /**
+   * Creates a new PdfBuilder instance
+   * @private
+   */
+  private constructor() {}
+
+  /**
+   * Creates a new PdfBuilder instance
+   * @returns New builder instance
+   *
+   * @example
+   * ```typescript
+   * const builder = PdfBuilder.create();
+   * ```
+   */
+  static create(): PdfBuilder {
+    return new PdfBuilder();
+  }
+
+  /**
+   * Sets the document title
+   * @param title - The document title
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.title('My Document Title');
+   * ```
+   */
+  title(title: string): this {
+    if (typeof title !== 'string' || title.length === 0) {
+      throw new Error('Title must be a non-empty string');
+    }
+    this._title = title;
+    return 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 {
+    if (typeof author !== 'string' || author.length === 0) {
+      throw new Error('Author must be a non-empty string');
+    }
+    this._author = author;
+    return this;
+  }
+
+  /**
+   * Sets the document subject
+   * @param subject - The document subject
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.subject('Technical Documentation');
+   * ```
+   */
+  subject(subject: string): this {
+    if (typeof subject !== 'string' || subject.length === 0) {
+      throw new Error('Subject must be a non-empty string');
+    }
+    this._subject = subject;
+    return this;
+  }
+
+  /**
+   * Sets the document keywords
+   * @param keywords - Array of keywords
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.keywords(['PDF', 'Document', 'Generation']);
+   * ```
+   */
+  keywords(keywords: string[]): this {
+    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 to the document
+   * @param keyword - A keyword to add
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.addKeyword('Important').addKeyword('Urgent');
+   * ```
+   */
+  addKeyword(keyword: string): this {
+    if (typeof keyword !== 'string' || keyword.length === 0) {
+      throw new Error('Keyword must be a non-empty string');
+    }
+    this._keywords.push(keyword);
+    return this;
+  }
+
+  /**
+   * Sets the default page size
+   * @param pageSize - Page size name (e.g., 'Letter', 'A4', 'Legal')
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.pageSize('A4');
+   * ```
+   */
+  pageSize(pageSize: string): this {
+    const validSizes = ['Letter', 'Legal', 'A4', 'A3', 'A5', 'B4', 'B5'];
+    if (!validSizes.includes(pageSize)) {
+      throw new Error(`Invalid page size. Must be one of: ${validSizes.join(', ')}`);
+    }
+    this._pageSize = pageSize;
+    return this;
+  }
+
+  /**
+   * Sets page margins
+   * @param top - Top margin in points
+   * @param right - Right margin in points
+   * @param bottom - Bottom margin in points
+   * @param left - Left margin in points
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * builder.margins(36, 36, 36, 36); // 0.5 inches on all sides
+   * ```
+   */
+  margins(top: number, right: number, bottom: number, left: number): this {
+    if (![top, right, bottom, left].every((m) => typeof m === 'number' && m >= 0)) {
+      throw new Error('All margins must be non-negative numbers');
+    }
+    this._margins = { top, right, bottom, left };
+    return this;
+  }
+
+  /**
+   * Creates a PDF document from Markdown content
+   * @param markdown - Markdown formatted content
+   * @returns The created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = builder.fromMarkdown('# Title\n\nContent here');
+   * ```
+   */
+  fromMarkdown(markdown: string): any {
+    // Note: Using any for Pdf type to avoid circular dependency
+    const { Pdf } = require('../index.js');
+
+    if (typeof markdown !== 'string') {
+      throw new Error('Markdown must be a string');
+    }
+
+    const pdf = Pdf.fromMarkdown(markdown);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Creates a PDF document from HTML content
+   * @param html - HTML formatted content
+   * @returns The created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = builder.fromHtml('<h1>Title</h1><p>Content</p>');
+   * ```
+   */
+  fromHtml(html: string): any {
+    const { Pdf } = require('../index.js');
+
+    if (typeof html !== 'string') {
+      throw new Error('HTML must be a string');
+    }
+
+    const pdf = Pdf.fromHtml(html);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Creates a PDF document from plain text content
+   * @param text - Plain text content
+   * @returns The created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = builder.fromText('Plain text content');
+   * ```
+   */
+  fromText(text: string): any {
+    const { Pdf } = require('../index.js');
+
+    if (typeof text !== 'string') {
+      throw new Error('Text must be a string');
+    }
+
+    const pdf = Pdf.fromText(text);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Asynchronously creates a PDF document from Markdown content
+   * @param markdown - Markdown formatted content
+   * @returns Promise that resolves to the created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = await builder.fromMarkdownAsync('# Title\n\nContent');
+   * ```
+   */
+  async fromMarkdownAsync(markdown: string): Promise<any> {
+    const { Pdf } = require('../index.js');
+
+    if (typeof markdown !== 'string') {
+      throw new Error('Markdown must be a string');
+    }
+
+    const pdf = await Pdf.fromMarkdownAsync(markdown);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Asynchronously creates a PDF document from HTML content
+   * @param html - HTML formatted content
+   * @returns Promise that resolves to the created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = await builder.fromHtmlAsync('<h1>Title</h1>');
+   * ```
+   */
+  async fromHtmlAsync(html: string): Promise<any> {
+    const { Pdf } = require('../index.js');
+
+    if (typeof html !== 'string') {
+      throw new Error('HTML must be a string');
+    }
+
+    const pdf = await Pdf.fromHtmlAsync(html);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Asynchronously creates a PDF document from plain text content
+   * @param text - Plain text content
+   * @returns Promise that resolves to the created PDF document
+   * @throws PdfError if PDF creation fails
+   *
+   * @example
+   * ```typescript
+   * const pdf = await builder.fromTextAsync('Plain text');
+   * ```
+   */
+  async fromTextAsync(text: string): Promise<any> {
+    const { Pdf } = require('../index.js');
+
+    if (typeof text !== 'string') {
+      throw new Error('Text must be a string');
+    }
+
+    const pdf = await Pdf.fromTextAsync(text);
+    this._applyConfiguration(pdf);
+    return pdf;
+  }
+
+  /**
+   * Gets the current configuration as a plain object
+   * @returns Configuration object with title, author, subject, keywords
+   *
+   * @private
+   */
+  private _getConfiguration(): PdfBuilderConfig {
+    return {
+      title: this._title,
+      author: this._author,
+      subject: this._subject,
+      keywords: this._keywords,
+      pageSize: this._pageSize,
+      margins: this._margins,
+    };
+  }
+
+  /**
+   * Applies builder configuration to a PDF document
+   * @param pdf - The PDF document to configure
+   * @private
+   */
+  private _applyConfiguration(pdf: any): void {
+    // Apply metadata properties if set
+    if (this._title !== undefined) {
+      pdf.title = this._title;
+    }
+    if (this._author !== undefined) {
+      pdf.author = this._author;
+    }
+    if (this._subject !== undefined) {
+      pdf.subject = this._subject;
+    }
+    if (this._keywords.length > 0) {
+      pdf.keywords = [...this._keywords];
+    }
+  }
+}
+
+/**
+ * Create a new PdfBuilder with static factory
+ * @deprecated Use PdfBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createPdfBuilder(): PdfBuilder {
+  return PdfBuilder.create();
+}

package/src/builders/search-options-builder.ts

@@ -0,0 +1,151 @@
+/**
+ * Builder for text search options
+ *
+ * Configures how text search is performed in PDF documents,
+ * including case sensitivity, whole word matching, and regex support.
+ *
+ * @example
+ * ```typescript
+ * import { SearchOptionsBuilder } from 'pdf_oxide';
+ *
+ * const options = SearchOptionsBuilder.create()
+ *   .caseSensitive(false)
+ *   .wholeWords(true)
+ *   .useRegex(false)
+ *   .build();
+ *
+ * const results = doc.search('pattern', 0, options);
+ * ```
+ */
+
+export interface SearchOptions {
+  caseSensitive: boolean;
+  wholeWords: boolean;
+  useRegex: boolean;
+  ignoreAccents: boolean;
+  maxResults: number;
+  searchAnnotations: boolean;
+}
+
+export class SearchOptionsBuilder {
+  private _caseSensitive: boolean = false;
+  private _wholeWords: boolean = false;
+  private _useRegex: boolean = false;
+  private _ignoreAccents: boolean = false;
+  private _maxResults: number = 1000;
+  private _searchAnnotations: boolean = false;
+
+  /**
+   * Creates a new SearchOptionsBuilder instance
+   * @private
+   */
+  private constructor() {}
+
+  /**
+   * Creates a new SearchOptionsBuilder instance
+   * @returns New builder instance
+   */
+  static create(): SearchOptionsBuilder {
+    return new SearchOptionsBuilder();
+  }
+
+  /**
+   * Creates options with default search settings (case-insensitive, no regex)
+   * @returns Search options with default preset
+   */
+  static default(): SearchOptions {
+    return SearchOptionsBuilder.create().build();
+  }
+
+  /**
+   * Creates options with strict search settings (case-sensitive, whole words, no regex)
+   * @returns Search options with strict preset
+   */
+  static strict(): SearchOptions {
+    return SearchOptionsBuilder.create()
+      .caseSensitive(true)
+      .wholeWords(true)
+      .useRegex(false)
+      .build();
+  }
+
+  /**
+   * Creates options with regex search settings
+   * @returns Search options with regex preset
+   */
+  static regex(): SearchOptions {
+    return SearchOptionsBuilder.create()
+      .useRegex(true)
+      .caseSensitive(false)
+      .wholeWords(false)
+      .build();
+  }
+
+  caseSensitive(sensitive: boolean): this {
+    if (typeof sensitive !== 'boolean') {
+      throw new Error('caseSensitive must be a boolean');
+    }
+    this._caseSensitive = sensitive;
+    return this;
+  }
+
+  wholeWords(wholeOnly: boolean): this {
+    if (typeof wholeOnly !== 'boolean') {
+      throw new Error('wholeWords must be a boolean');
+    }
+    this._wholeWords = wholeOnly;
+    return this;
+  }
+
+  useRegex(regex: boolean): this {
+    if (typeof regex !== 'boolean') {
+      throw new Error('useRegex must be a boolean');
+    }
+    this._useRegex = regex;
+    return this;
+  }
+
+  ignoreAccents(ignore: boolean): this {
+    if (typeof ignore !== 'boolean') {
+      throw new Error('ignoreAccents must be a boolean');
+    }
+    this._ignoreAccents = ignore;
+    return this;
+  }
+
+  maxResults(max: number): this {
+    if (typeof max !== 'number' || max <= 0) {
+      throw new Error('maxResults must be a positive number');
+    }
+    this._maxResults = Math.floor(max);
+    return this;
+  }
+
+  searchAnnotations(search: boolean): this {
+    if (typeof search !== 'boolean') {
+      throw new Error('searchAnnotations must be a boolean');
+    }
+    this._searchAnnotations = search;
+    return this;
+  }
+
+  build(): SearchOptions {
+    return {
+      caseSensitive: this._caseSensitive,
+      wholeWords: this._wholeWords,
+      useRegex: this._useRegex,
+      ignoreAccents: this._ignoreAccents,
+      maxResults: this._maxResults,
+      searchAnnotations: this._searchAnnotations,
+    };
+  }
+}
+
+/**
+ * Create a new SearchOptionsBuilder with static factory
+ * @deprecated Use SearchOptionsBuilder.create() instead
+ * @returns New builder instance
+ */
+export function createSearchOptionsBuilder(): SearchOptionsBuilder {
+  return SearchOptionsBuilder.create();
+}