@sythos/js_barcode_universal 1.5.13 → 1.5.15

package/src/ts/databar/index.d.ts

@@ -34,4 +34,52 @@ export { GS1_SEPARATOR, decodeGS1ElementString, encodeGS1ElementString, formatGS
 export { DATABAR14_VARIANTS, DATABAR_LIMITED_VARIANT, dataBar14GroupFor, validateDataBarTables, } from './tables.js';
 export { encodeDataBar14 } from './encoder.js';
 export { decodeDataBar14, decodeDataBar14Scanline } from './decoder.js';
+export {
+  encodeDataBarLimited,
+  decodeDataBarLimited,
+  detectDataBarLimited,
+  detectAndDecodeDataBarLimited,
+  decodeDataBarLimitedScanline,
+} from './limited.js';
+export {
+  encodeDataBarExpanded,
+  decodeDataBarExpanded,
+  detectDataBarExpanded,
+  detectAndDecodeDataBarExpanded,
+  decodeDataBarExpandedScanline,
+  encodeGS1DataBarExpanded,
+  decodeGS1DataBarExpanded,
+  detectGS1DataBarExpanded,
+  detectAndDecodeGS1DataBarExpanded,
+} from './expanded.js';
+export {
+  encodeDataBar14Stacked,
+  decodeDataBar14Stacked,
+  detectDataBar14Stacked,
+  detectAndDecodeDataBar14Stacked,
+  encodeDataBarStacked,
+  decodeDataBarStacked,
+  detectDataBarStacked,
+  detectAndDecodeDataBarStacked,
+  encodeGS1DataBarStacked,
+  decodeGS1DataBarStacked,
+  detectGS1DataBarStacked,
+  detectAndDecodeGS1DataBarStacked,
+} from './stacked.js';
+export {
+  encodeDataBarStackedOmnidirectional,
+  decodeDataBarStackedOmnidirectional,
+  detectDataBarStackedOmnidirectional,
+  detectAndDecodeDataBarStackedOmnidirectional,
+  encodeDataBarStackedOmni,
+  decodeDataBarStackedOmni,
+  detectDataBarStackedOmni,
+  detectAndDecodeDataBarStackedOmni,
+  encodeDataBar14StackedOmnidirectional,
+  decodeDataBar14StackedOmnidirectional,
+  detectDataBar14StackedOmnidirectional,
+  encodeDataBar14StackedOmni,
+  decodeDataBar14StackedOmni,
+  detectDataBar14StackedOmni,
+} from './stacked-omnidirectional.js';
 export { DATABAR14_CHECKSUM_WEIGHTS, DATABAR14_FINDERS, dataBar14CharacterWidths, dataBar14ValueForWidths, dataBarWidths, } from './patterns.js';

package/src/ts/databar/index.ts

@@ -59,6 +59,54 @@ export {
 
 export { encodeDataBar14 } from './encoder.js';
 export { decodeDataBar14, decodeDataBar14Scanline } from './decoder.js';
+export {
+  encodeDataBarLimited,
+  decodeDataBarLimited,
+  detectDataBarLimited,
+  detectAndDecodeDataBarLimited,
+  decodeDataBarLimitedScanline,
+} from './limited.js';
+export {
+  encodeDataBarExpanded,
+  decodeDataBarExpanded,
+  detectDataBarExpanded,
+  detectAndDecodeDataBarExpanded,
+  decodeDataBarExpandedScanline,
+  encodeGS1DataBarExpanded,
+  decodeGS1DataBarExpanded,
+  detectGS1DataBarExpanded,
+  detectAndDecodeGS1DataBarExpanded,
+} from './expanded.js';
+export {
+  encodeDataBar14Stacked,
+  decodeDataBar14Stacked,
+  detectDataBar14Stacked,
+  detectAndDecodeDataBar14Stacked,
+  encodeDataBarStacked,
+  decodeDataBarStacked,
+  detectDataBarStacked,
+  detectAndDecodeDataBarStacked,
+  encodeGS1DataBarStacked,
+  decodeGS1DataBarStacked,
+  detectGS1DataBarStacked,
+  detectAndDecodeGS1DataBarStacked,
+} from './stacked.js';
+export {
+  encodeDataBarStackedOmnidirectional,
+  decodeDataBarStackedOmnidirectional,
+  detectDataBarStackedOmnidirectional,
+  detectAndDecodeDataBarStackedOmnidirectional,
+  encodeDataBarStackedOmni,
+  decodeDataBarStackedOmni,
+  detectDataBarStackedOmni,
+  detectAndDecodeDataBarStackedOmni,
+  encodeDataBar14StackedOmnidirectional,
+  decodeDataBar14StackedOmnidirectional,
+  detectDataBar14StackedOmnidirectional,
+  encodeDataBar14StackedOmni,
+  decodeDataBar14StackedOmni,
+  detectDataBar14StackedOmni,
+} from './stacked-omnidirectional.js';
 export {
   DATABAR14_CHECKSUM_WEIGHTS,
   DATABAR14_FINDERS,

package/src/ts/databar/layout.d.ts

@@ -0,0 +1,122 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Structural descriptions for GS1 DataBar physical layouts.
+ *
+ * This module deliberately describes geometry only. It does not encode GTINs,
+ * construct finder patterns, or claim an interoperable writer for any DataBar
+ * variant. A later encoder can use the descriptor while keeping its payload
+ * and symbol-character rules in the codec layer.
+ *
+ * @module databar/layout
+ */
+
+/**
+ * DataBar layout identifiers represented by this descriptor.
+ *
+ * `omnidirectional` and `stacked-omnidirectional` are retained as aliases for
+ * the longer names used by the existing DataBar-14 API. They describe the same
+ * structural family as `omni` and `stacked-omni`; no encoding is implied.
+ */
+export type DataBarLayoutId =
+  | 'omni'
+  | 'truncated'
+  | 'limited'
+  | 'stacked'
+  | 'stacked-omni'
+  | 'expanded'
+  | 'expanded-stacked'
+  | 'omnidirectional'
+  | 'stacked-omnidirectional';
+
+/**
+ * The immutable physical geometry and checksum metadata for one DataBar
+ * variant.
+ *
+ * `modulesPerRow` is the active symbol width. `rowHeight` is the active module
+ * height of each row, and `separatorModules` is the vertical gap between
+ * adjacent rows. `quietZone` is the margin on each outer side and is excluded
+ * from {@link dataBarTotalModules}; it is nevertheless included in the safe
+ * footprint checks. A one-row layout has no separator and therefore requires
+ * `separatorModules` to be zero.
+ */
+export interface DataBarLayout {
+    readonly id: DataBarLayoutId;
+    readonly rows: number;
+    readonly modulesPerRow: number;
+    readonly rowHeight: number;
+    readonly separatorModules: number;
+    readonly quietZone: number;
+    readonly linkage: boolean;
+    readonly checksumModulus: number;
+    readonly stacked: boolean;
+}
+
+/** Input accepted by {@link createDataBarLayout}. */
+export type DataBarLayoutOptions = DataBarLayout;
+
+/** Alias for callers that use input-oriented naming. */
+export type DataBarLayoutInput = DataBarLayoutOptions;
+
+/** Alias for code that calls the value a descriptor. */
+export type DataBarLayoutDescriptor = DataBarLayout;
+
+/**
+ * Return whether an unknown value is a valid DataBar physical layout.
+ *
+ * Validation is side-effect free and performs no matrix allocation. A value
+ * supplied by a caller may remain mutable; use {@link createDataBarLayout}
+ * when an immutable descriptor is required.
+ */
+export declare function validateDataBarLayout(value: unknown): value is DataBarLayout;
+
+/**
+ * Create a validated, shallowly immutable DataBar layout descriptor.
+ *
+ * Only documented fields are copied. Unknown input properties are ignored so
+ * format-specific metadata cannot leak mutable state into the shared layout.
+ * This factory describes future physical variants but intentionally does not
+ * encode any payload.
+ *
+ * @throws {TypeError} If `options` is not an object.
+ * @throws {RangeError} If a field is invalid or the physical footprint exceeds
+ * the safe geometry budget.
+ */
+export declare function createDataBarLayout(options: DataBarLayoutOptions): DataBarLayout;
+
+/**
+ * Count active module cells in all rows, including row separators and excluding
+ * the outer quiet zone. `rowHeight` is the number of module rows occupied by
+ * each active DataBar row.
+ *
+ * @throws {TypeError} If `layout` is not a valid descriptor.
+ */
+export declare function dataBarTotalModules(layout: DataBarLayout): number;

package/src/ts/databar/layout.ts

@@ -0,0 +1,275 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Structural descriptions for GS1 DataBar physical layouts.
+ *
+ * This module deliberately describes geometry only. It does not encode GTINs,
+ * construct finder patterns, or claim an interoperable writer for any DataBar
+ * variant. A later encoder can use the descriptor while keeping its payload
+ * and symbol-character rules in the codec layer.
+ *
+ * @module databar/layout
+ */
+
+/**
+ * DataBar layout identifiers represented by this descriptor.
+ *
+ * `omnidirectional` and `stacked-omnidirectional` are retained as aliases for
+ * the longer names used by the existing DataBar-14 API. They describe the same
+ * structural family as `omni` and `stacked-omni`; no encoding is implied.
+ */
+export type DataBarLayoutId =
+  | 'omni'
+  | 'truncated'
+  | 'limited'
+  | 'stacked'
+  | 'stacked-omni'
+  | 'expanded'
+  | 'expanded-stacked'
+  | 'omnidirectional'
+  | 'stacked-omnidirectional';
+
+/**
+ * The immutable physical geometry and checksum metadata for one DataBar
+ * variant.
+ *
+ * `modulesPerRow` is the active symbol width. `rowHeight` is the active module
+ * height of each row, and `separatorModules` is the vertical gap between
+ * adjacent rows. `quietZone` is the margin on each outer side and is excluded
+ * from {@link dataBarTotalModules}; it is nevertheless included in the safe
+ * footprint checks. A one-row layout has no separator and therefore requires
+ * `separatorModules` to be zero.
+ */
+export interface DataBarLayout {
+  readonly id: DataBarLayoutId;
+  readonly rows: number;
+  readonly modulesPerRow: number;
+  readonly rowHeight: number;
+  readonly separatorModules: number;
+  readonly quietZone: number;
+  readonly linkage: boolean;
+  readonly checksumModulus: number;
+  readonly stacked: boolean;
+}
+
+/** Input accepted by {@link createDataBarLayout}. */
+export type DataBarLayoutOptions = DataBarLayout;
+
+/** Alias for callers that use input-oriented naming. */
+export type DataBarLayoutInput = DataBarLayoutOptions;
+
+/** Alias for code that calls the value a descriptor. */
+export type DataBarLayoutDescriptor = DataBarLayout;
+
+/*
+ * These limits are intentionally conservative. They keep a future renderer
+ * from receiving dimensions that are technically safe JavaScript integers but
+ * impractical to materialise. No matrix is allocated by this module.
+ */
+const MAX_LAYOUT_DIMENSION = 32_768;
+const MAX_LAYOUT_MODULES = 16_777_216;
+
+const DATA_BAR_LAYOUT_IDS: readonly DataBarLayoutId[] = Object.freeze([
+  'omni',
+  'truncated',
+  'limited',
+  'stacked',
+  'stacked-omni',
+  'expanded',
+  'expanded-stacked',
+  'omnidirectional',
+  'stacked-omnidirectional',
+]);
+
+const STACKED_LAYOUT_IDS: readonly DataBarLayoutId[] = Object.freeze([
+  'stacked',
+  'stacked-omni',
+  'expanded-stacked',
+  'stacked-omnidirectional',
+]);
+
+const hasOwn = (value: object, property: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, property);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isBoundedPositiveInteger(value: unknown): value is number {
+  return typeof value === 'number'
+    && Number.isSafeInteger(value)
+    && value > 0
+    && value <= MAX_LAYOUT_DIMENSION;
+}
+
+function isBoundedNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number'
+    && Number.isSafeInteger(value)
+    && value >= 0
+    && value <= MAX_LAYOUT_DIMENSION;
+}
+
+function isLayoutId(value: unknown): value is DataBarLayoutId {
+  return typeof value === 'string'
+    && (DATA_BAR_LAYOUT_IDS as readonly string[]).includes(value);
+}
+
+function isStackedId(id: DataBarLayoutId): boolean {
+  return (STACKED_LAYOUT_IDS as readonly string[]).includes(id);
+}
+
+/**
+ * Calculate the active (quiet-zone-free) matrix dimensions for a descriptor.
+ * The result is safe because callers first pass the descriptor through the
+ * bounded validation checks.
+ */
+function activeHeight(layout: Pick<DataBarLayout, 'rows' | 'rowHeight' | 'separatorModules'>): number {
+  return layout.rows * layout.rowHeight
+    + (layout.rows - 1) * layout.separatorModules;
+}
+
+/**
+ * Check that the descriptor can be materialised by a future renderer without
+ * exceeding the shared geometry budget.
+ */
+function isWithinModuleBudget(layout: Pick<
+  DataBarLayout,
+  'rows' | 'modulesPerRow' | 'rowHeight' | 'separatorModules' | 'quietZone'
+>): boolean {
+  const height = activeHeight(layout);
+  const footprintWidth = layout.modulesPerRow + layout.quietZone * 2;
+  const footprintHeight = height + layout.quietZone * 2;
+
+  if (footprintWidth > MAX_LAYOUT_DIMENSION || footprintHeight > MAX_LAYOUT_DIMENSION) {
+    return false;
+  }
+
+  if (footprintWidth > MAX_LAYOUT_MODULES / footprintHeight) return false;
+  return footprintWidth * footprintHeight <= MAX_LAYOUT_MODULES;
+}
+
+/**
+ * Return whether an unknown value is a valid DataBar physical layout.
+ *
+ * Validation is side-effect free and performs no matrix allocation. A value
+ * supplied by a caller may remain mutable; use {@link createDataBarLayout}
+ * when an immutable descriptor is required.
+ */
+export function validateDataBarLayout(value: unknown): value is DataBarLayout {
+  if (!isRecord(value)) return false;
+
+  if (!hasOwn(value, 'id') || !isLayoutId(value.id)) return false;
+  if (!hasOwn(value, 'rows') || !isBoundedPositiveInteger(value.rows)) return false;
+  if (!hasOwn(value, 'modulesPerRow') || !isBoundedPositiveInteger(value.modulesPerRow)) return false;
+  if (!hasOwn(value, 'rowHeight') || !isBoundedPositiveInteger(value.rowHeight)) return false;
+  if (!hasOwn(value, 'separatorModules') || !isBoundedNonNegativeInteger(value.separatorModules)) return false;
+  if (!hasOwn(value, 'quietZone') || !isBoundedPositiveInteger(value.quietZone)) return false;
+  if (!hasOwn(value, 'linkage') || typeof value.linkage !== 'boolean') return false;
+  if (!hasOwn(value, 'checksumModulus')
+    || !isBoundedPositiveInteger(value.checksumModulus)
+    || value.checksumModulus < 2) return false;
+  if (!hasOwn(value, 'stacked') || typeof value.stacked !== 'boolean') return false;
+
+  const rowsAreStacked = value.rows > 1;
+  if (value.stacked !== rowsAreStacked) return false;
+  if (isStackedId(value.id) !== value.stacked) return false;
+  if (!value.stacked && value.separatorModules !== 0) return false;
+  if (value.stacked && value.separatorModules < 1) return false;
+
+  return isWithinModuleBudget({
+    rows: value.rows,
+    modulesPerRow: value.modulesPerRow,
+    rowHeight: value.rowHeight,
+    separatorModules: value.separatorModules,
+    quietZone: value.quietZone,
+  });
+}
+
+/**
+ * Create a validated, shallowly immutable DataBar layout descriptor.
+ *
+ * Only documented fields are copied. Unknown input properties are ignored so
+ * format-specific metadata cannot leak mutable state into the shared layout.
+ * This factory describes future physical variants but intentionally does not
+ * encode any payload.
+ *
+ * @throws {TypeError} If `options` is not an object.
+ * @throws {RangeError} If a field is invalid or the physical footprint exceeds
+ * the safe geometry budget.
+ */
+export function createDataBarLayout(options: DataBarLayoutOptions): DataBarLayout {
+  if (!isRecord(options)) {
+    throw new TypeError('GS1 DataBar layout options must be an object');
+  }
+
+  const descriptor: {
+    id: DataBarLayoutId;
+    rows: number;
+    modulesPerRow: number;
+    rowHeight: number;
+    separatorModules: number;
+    quietZone: number;
+    linkage: boolean;
+    checksumModulus: number;
+    stacked: boolean;
+  } = {
+    id: options.id as DataBarLayoutId,
+    rows: options.rows as number,
+    modulesPerRow: options.modulesPerRow as number,
+    rowHeight: options.rowHeight as number,
+    separatorModules: options.separatorModules as number,
+    quietZone: options.quietZone as number,
+    linkage: options.linkage as boolean,
+    checksumModulus: options.checksumModulus as number,
+    stacked: options.stacked as boolean,
+  };
+
+  if (!validateDataBarLayout(descriptor)) {
+    throw new RangeError('Invalid GS1 DataBar layout descriptor');
+  }
+
+  return Object.freeze(descriptor);
+}
+
+/**
+ * Count active module cells in all rows, including row separators and excluding
+ * the outer quiet zone. `rowHeight` is the number of module rows occupied by
+ * each active DataBar row.
+ *
+ * @throws {TypeError} If `layout` is not a valid descriptor.
+ */
+export function dataBarTotalModules(layout: DataBarLayout): number {
+  if (!validateDataBarLayout(layout)) {
+    throw new TypeError('Cannot count modules for an invalid GS1 DataBar layout');
+  }
+
+  return layout.modulesPerRow * activeHeight(layout);
+}

package/src/ts/databar/limited.d.ts

@@ -0,0 +1,85 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ * SPDX-FileCopyrightText: 2026 Sythos (https://www.sythos.net)
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { BitMatrix } from '../core/bit-matrix.js';
+
+export interface DataBarLimitedEncodeOptions {
+  linkage?: boolean;
+  /** Integer module scale; `scale` is accepted as an alias. */
+  moduleScale?: number;
+  scale?: number;
+  /** Output height in modules; the minimum is ten modules per row. */
+  height?: number;
+}
+
+export interface DataBarLimitedElement {
+  readonly ai: '01';
+  readonly value: string;
+  readonly fixed: true;
+}
+
+export interface DataBarLimitedDecodeResult {
+  readonly format: 'databar-limited';
+  readonly variant: 'limited';
+  readonly text: string;
+  readonly gtin: string;
+  readonly gs1: true;
+  readonly linkage: boolean;
+  readonly checksum: number;
+  readonly checksumValid: true;
+  readonly moduleScale: number;
+  readonly height: number;
+  readonly symbologyIdentifier: ']e0';
+  readonly elements: readonly [DataBarLimitedElement];
+}
+
+export interface DataBarLimitedDetection extends DataBarLimitedDecodeResult {
+  readonly result: DataBarLimitedDecodeResult;
+  readonly matrix: BitMatrix;
+  readonly corners: readonly [
+    { readonly x: number; readonly y: number },
+    { readonly x: number; readonly y: number },
+    { readonly x: number; readonly y: number },
+    { readonly x: number; readonly y: number },
+  ];
+  readonly rotation: 0 | 90 | 180 | 270;
+  readonly moduleSize: number;
+  readonly confidence: 1;
+  readonly quality: {
+    readonly quietZone: boolean;
+    readonly checksum: true;
+    readonly rows: 1;
+    readonly consistency: 1;
+  };
+  readonly score: 1;
+}
+
+/** Encode a checked GTIN as GS1 DataBar Limited. */
+export declare function encodeDataBarLimited(
+  value: string | number,
+  options?: DataBarLimitedEncodeOptions,
+): BitMatrix;
+
+/** Decode a complete, clean or integer-scaled Limited symbol. */
+export declare function decodeDataBarLimited(matrix: BitMatrix): DataBarLimitedDecodeResult;
+
+/** Detect one complete Limited symbol in a binary raster. */
+export declare function detectDataBarLimited(
+  binaryImage: BitMatrix,
+  options?: object,
+): DataBarLimitedDetection | null;
+
+/** Detect and decode one Limited symbol, or return null. */
+export declare const detectAndDecodeDataBarLimited: typeof detectDataBarLimited;
+
+/** Decode a complete 79-module scanline, or return null for invalid input. */
+export declare function decodeDataBarLimitedScanline(
+  row: ArrayLike<number | boolean>,
+): DataBarLimitedDecodeResult | null;