isahaq-barcode 1.9.0 → 2.0.0

package/index.d.ts

@@ -0,0 +1,497 @@
+/**
+ * Type definitions for isahaq-barcode
+ *
+ * The runtime is CommonJS (`module.exports = BarcodeGenerator`), so the class is
+ * exported with `export =` and every supporting type is re-exported from the
+ * merged namespace:
+ *
+ *   import BarcodeGenerator = require('isahaq-barcode');
+ *   import BarcodeGenerator from 'isahaq-barcode';        // with esModuleInterop
+ *   const png = await BarcodeGenerator.png('123', 'code128');
+ *   const opts: BarcodeGenerator.RenderOptions = { width: 3 };
+ */
+
+/// <reference types="node" />
+
+type BarcodeType =
+  | 'code128'
+  | 'code128a'
+  | 'code128b'
+  | 'code128c'
+  | 'code128auto'
+  | 'code39'
+  | 'code39extended'
+  | 'code39checksum'
+  | 'code39auto'
+  | 'code93'
+  | 'code25'
+  | 'code25auto'
+  | 'code32'
+  | 'standard25'
+  | 'standard25checksum'
+  | 'interleaved25'
+  | 'interleaved25checksum'
+  | 'interleaved25auto'
+  | 'msi'
+  | 'msichecksum'
+  | 'msiauto'
+  | 'ean13'
+  | 'ean8'
+  | 'ean2'
+  | 'ean5'
+  | 'upca'
+  | 'upce'
+  | 'itf14'
+  | 'postnet'
+  | 'planet'
+  | 'rms4cc'
+  | 'kix'
+  | 'imb'
+  | 'codabar'
+  | 'code11'
+  | 'pharmacode'
+  | 'pharmacodetwotracks'
+  | 'qrcode'
+  | 'datamatrix'
+  | 'aztec'
+  | 'pdf417'
+  | 'microqr'
+  | 'maxicode'
+  | 'code16k'
+  | 'code49';
+
+/** Any registered type id, while still offering completion for the known ones */
+type BarcodeTypeInput = BarcodeType | (string & {});
+
+type RenderFormat = 'png' | 'svg' | 'html' | 'pdf';
+
+type SyncRenderFormat = 'svg' | 'html';
+
+type BarcodeCategory =
+  'LINEAR' | 'EAN_UPC' | 'POSTAL' | 'SPECIALIZED' | 'MATRIX_2D' | 'STACKED';
+
+/** Rotation: none, right, left, inverted */
+type Rotation = 'N' | 'R' | 'L' | 'I';
+
+interface RenderOptions {
+  /** Module (narrow bar) width in pixels. Default 2 */
+  width?: number;
+  /** Bar height in pixels, 1D symbologies only. Default 100 */
+  height?: number;
+  /** Target size in pixels for 2D and stacked symbologies */
+  size?: number;
+  /** Print the human readable text. Default true */
+  displayValue?: boolean;
+  /** Human readable text size in pixels. Default 20 */
+  fontSize?: number;
+  /** Text alignment. Default 'center' */
+  textAlign?: 'center' | 'left' | 'right' | 'justify';
+  /** Gap between the bars and the text in pixels. Default 2 */
+  textMargin?: number;
+  /** Text colour; falls back to lineColor */
+  textColor?: string;
+  /** Background colour as #rgb, #rrggbb or rrggbb. Default '#ffffff' */
+  background?: string;
+  /** Bar colour as #rgb, #rrggbb or rrggbb. Default '#000000' */
+  lineColor?: string;
+  /** Quiet zone in pixels. Defaults to `quietZone` modules when omitted */
+  margin?: number;
+  marginTop?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  marginRight?: number;
+  /** Quiet zone in modules, used when no pixel margin is given. Default 10 */
+  quietZone?: number;
+  /** Rotation. Default 'N' */
+  rotate?: Rotation;
+  /** Raw bwip-js options, merged last, for advanced use */
+  bwipOptions?: Record<string, unknown>;
+}
+
+interface HtmlRenderOptions extends RenderOptions {
+  /** id attribute of the wrapper element */
+  id?: string;
+  /** class attribute of the wrapper element. Default 'barcode' */
+  className?: string;
+  /** Add inline styles to the wrapper element. Default true */
+  includeStyles?: boolean;
+}
+
+interface PdfRenderOptions extends RenderOptions {
+  /** Page width in points. Default 612 */
+  pageWidth?: number;
+  /** Page height in points. Default 792 */
+  pageHeight?: number;
+  /** Named page size such as 'A4'. Takes precedence over pageWidth/pageHeight */
+  pageSize?: string;
+  /** Size the page to the barcode plus its margins */
+  fitToBarcode?: boolean;
+  /** PDF document title */
+  title?: string;
+}
+
+type GenerateOptions = RenderOptions & HtmlRenderOptions & PdfRenderOptions;
+
+interface ValidationSuccess {
+  valid: true;
+  data: string;
+  type: string;
+  length: number;
+  charset: string;
+}
+
+interface ValidationFailure {
+  valid: false;
+  error: string;
+}
+
+type ValidationResult = ValidationSuccess | ValidationFailure;
+
+interface BarcodeTypeInfo {
+  type: string;
+  name: string;
+  description: string;
+  category: BarcodeCategory;
+  /** Underlying symbology id used by the encoder */
+  symbology: string;
+  minLength: number;
+  maxLength: number;
+  charset: string;
+}
+
+interface BarcodeTypeConfig {
+  minLength: number;
+  maxLength: number;
+  charset: string;
+}
+
+interface RenderFormatInfo {
+  format: RenderFormat;
+  name: string;
+  mimeType: string;
+  extension: string;
+  returns: 'Buffer' | 'string';
+  description: string;
+}
+
+interface Dimensions {
+  width: number;
+  height: number;
+}
+
+interface BatchItem {
+  data: string;
+  type?: BarcodeTypeInput;
+  format?: RenderFormat;
+  options?: GenerateOptions;
+}
+
+interface BatchSuccess {
+  index: number;
+  success: true;
+  result: Buffer | string;
+  data: string;
+  type: string;
+  format: string;
+}
+
+interface BatchFailure {
+  index: number;
+  success: false;
+  error: string;
+  data?: string;
+  type: string;
+  format: string;
+}
+
+type BatchResult = BatchSuccess | BatchFailure;
+
+type WatermarkPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'left-center'
+  | 'center'
+  | 'right-center'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+type ColorValue = string | [number, number, number];
+
+type QrOutputFormat = 'png' | 'jpg' | 'jpeg' | 'svg';
+
+interface QrCodeOptions {
+  data?: string;
+  /** Output size in pixels, including margins. Default 300 */
+  size?: number;
+  /** Margin in pixels. Default 10 */
+  margin?: number;
+  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H';
+  foregroundColor?: ColorValue;
+  backgroundColor?: ColorValue;
+  /** Path, URL or data URI of a logo image. Requires the optional canvas package */
+  logoPath?: string | null;
+  /** Logo size as a percentage of the QR code size. Default 20 */
+  logoSize?: number;
+  /** Label drawn under the code. Requires the optional canvas package */
+  label?: string | null;
+  labelFont?: string | null;
+  labelFontSize?: number;
+  /** Watermark text or image path. Requires the optional canvas package */
+  watermark?: string | null;
+  watermarkPosition?: WatermarkPosition;
+  /** Output format. Default 'png' */
+  format?: QrOutputFormat;
+}
+
+declare class QrCodeResult {
+  readonly options: QrCodeOptions;
+  constructor(options: QrCodeOptions);
+  /** Whether canvas compositing is needed (logo, label or watermark) */
+  needsCompositing(): boolean;
+  /** Generate the code: a Buffer for png/jpeg, SVG markup for svg */
+  generate(): Promise<Buffer | string>;
+  saveToFile(filePath: string): Promise<string>;
+  getDataUri(): Promise<string>;
+  getString(): Promise<Buffer | string>;
+  getWatermarkPosition(size: number): { x: number; y: number };
+  rgbToHex(rgb: ColorValue): string;
+}
+
+declare class QrCodeBuilder {
+  readonly options: QrCodeOptions;
+  constructor(options?: QrCodeOptions);
+  static create(options?: QrCodeOptions): QrCodeBuilder;
+  data(data: string): this;
+  size(size: number): this;
+  margin(margin: number): this;
+  errorCorrectionLevel(level: 'L' | 'M' | 'Q' | 'H'): this;
+  foregroundColor(color: ColorValue): this;
+  backgroundColor(color: ColorValue): this;
+  logoPath(logoPath: string): this;
+  logoSize(logoSize: number): this;
+  label(label: string): this;
+  labelFont(fontPath: string, fontSize?: number): this;
+  watermark(watermark: string, position?: WatermarkPosition): this;
+  format(format: QrOutputFormat): this;
+  build(): QrCodeResult;
+  generate(): Promise<Buffer | string>;
+  saveToFile(filePath: string): Promise<string>;
+  getDataUri(): Promise<string>;
+}
+
+declare class Validator {
+  validate(data: string, type: string): ValidationResult;
+  calculateEANCheckDigit(data: string): number;
+}
+
+declare class BarcodeTypes {
+  static getAll(): string[];
+  static getTypes(): string[];
+  static getByCategory(category: string): string[];
+  static getCategories(): BarcodeCategory[];
+  static isValid(type: string): boolean;
+  static getConfig(type: string): BarcodeTypeConfig;
+  static getDescription(type: string): string;
+  static getTypeInfo(type: string): BarcodeTypeInfo | null;
+  static getSymbology(type: string): string | null;
+  static getEncodeOptions(type: string): Record<string, unknown>;
+}
+
+declare class RenderFormats {
+  static getAll(): RenderFormat[];
+  static getFormats(): RenderFormat[];
+  static isValid(format: string): boolean;
+  static getMimeType(format: string): string;
+  static getExtension(format: string): string;
+  static getDescription(format: string): string;
+  static getFormatInfo(format: string): RenderFormatInfo | null;
+}
+
+declare class BarcodeEncoder {
+  static getDefaultOptions(): RenderOptions;
+  static isMatrix(type: string): boolean;
+  static buildOptions(
+    data: string,
+    type: string,
+    options?: RenderOptions
+  ): Record<string, unknown>;
+  static toSvg(data: string, type: string, options?: RenderOptions): string;
+  static toPng(
+    data: string,
+    type: string,
+    options?: RenderOptions
+  ): Promise<Buffer>;
+  static getDimensions(
+    data: string,
+    type: string,
+    options?: RenderOptions
+  ): Dimensions;
+}
+
+declare class BarcodeService {
+  generate(
+    data: string,
+    type?: BarcodeTypeInput,
+    format?: RenderFormat,
+    options?: GenerateOptions
+  ): Promise<Buffer | string>;
+  generateSync(
+    data: string,
+    type?: BarcodeTypeInput,
+    format?: SyncRenderFormat,
+    options?: GenerateOptions
+  ): string;
+  png(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): Promise<Buffer>;
+  svg(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): Promise<string>;
+  svgSync(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): string;
+  html(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: HtmlRenderOptions
+  ): Promise<string>;
+  htmlSync(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: HtmlRenderOptions
+  ): string;
+  pdf(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: PdfRenderOptions
+  ): Promise<Buffer>;
+  batch(items: BatchItem[]): Promise<BatchResult[]>;
+  validate(data: string, type: string): ValidationResult;
+  getBarcodeTypes(): string[];
+  getRenderFormats(): RenderFormat[];
+}
+
+declare class BarcodeGenerator {
+  /** Generate a barcode in any supported format */
+  static generate(
+    data: string,
+    type?: BarcodeTypeInput,
+    format?: RenderFormat,
+    options?: GenerateOptions
+  ): Promise<Buffer | string>;
+
+  /** Generate a PNG barcode */
+  static png(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): Promise<Buffer>;
+
+  /** Generate an SVG barcode */
+  static svg(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): Promise<string>;
+
+  /** Generate an SVG barcode synchronously */
+  static svgSync(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: RenderOptions
+  ): string;
+
+  /** Generate an HTML fragment containing an inline SVG barcode */
+  static html(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: HtmlRenderOptions
+  ): Promise<string>;
+
+  /** Generate an HTML fragment synchronously */
+  static htmlSync(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: HtmlRenderOptions
+  ): string;
+
+  /** Generate a single page PDF containing the barcode */
+  static pdf(
+    data: string,
+    type?: BarcodeTypeInput,
+    options?: PdfRenderOptions
+  ): Promise<Buffer>;
+
+  /** Create a QR code builder for logo, label and watermark support */
+  static qrCode(data: string, options?: QrCodeOptions): QrCodeBuilder;
+
+  /** Create a QR code builder from an options object */
+  static modernQr(options?: QrCodeOptions): QrCodeBuilder;
+
+  /** Validate data for a barcode type */
+  static validate(data: string, type: string): ValidationResult;
+
+  /** Generate many barcodes; per-item failures are reported, not thrown */
+  static batch(items: BatchItem[]): Promise<BatchResult[]>;
+
+  static getBarcodeTypes(): string[];
+  static getBarcodeCategories(): BarcodeCategory[];
+  static getBarcodeTypesByCategory(category: string): string[];
+  static getRenderFormats(): RenderFormat[];
+  static getWatermarkPositions(): WatermarkPosition[];
+  static getBarcodeTypeInfo(type: string): BarcodeTypeInfo | null;
+  static getRenderFormatInfo(format: string): RenderFormatInfo | null;
+  static getDefaultOptions(): RenderOptions;
+}
+
+/**
+ * The classes below are exposed as properties of the default export
+ * (`BarcodeGenerator.QrCodeBuilder`, ...) and are re-exported here so they can
+ * be used as both values and types.
+ */
+declare namespace BarcodeGenerator {
+  export {
+    BarcodeCategory,
+    BarcodeEncoder,
+    BarcodeService,
+    BarcodeType,
+    BarcodeTypeConfig,
+    BarcodeTypeInfo,
+    BarcodeTypeInput,
+    BarcodeTypes,
+    BatchFailure,
+    BatchItem,
+    BatchResult,
+    BatchSuccess,
+    ColorValue,
+    Dimensions,
+    GenerateOptions,
+    HtmlRenderOptions,
+    PdfRenderOptions,
+    QrCodeBuilder,
+    QrCodeOptions,
+    QrCodeResult,
+    QrOutputFormat,
+    RenderFormat,
+    RenderFormatInfo,
+    RenderFormats,
+    RenderOptions,
+    Rotation,
+    SyncRenderFormat,
+    ValidationFailure,
+    ValidationResult,
+    ValidationSuccess,
+    Validator,
+    WatermarkPosition,
+  };
+}
+
+export = BarcodeGenerator;