@forgesworn/qr
Version:
Dependency-free QR code encoder and decoder for TypeScript, browsers, workers and Node, with optional WebAssembly and tracked camera scanning.
86 lines (85 loc) • 3.96 kB
TypeScript
import { type ErrorCorrection } from './encode.js';
/** What a symbol says, once read. */
export interface Payload {
/** The decoded text. */
readonly text: string;
/** The payload as bytes: byte-mode data as stored, numeric and alphanumeric as ASCII. */
readonly bytes: Uint8Array;
readonly version: number;
readonly ecc: ErrorCorrection;
readonly mask: number;
/** ECI assignment numbers in the order they appeared; empty if none. */
readonly eci: readonly number[];
/** Codewords Reed-Solomon had to correct. */
readonly corrected: number;
/** Present when the symbol is one of a structured-append set; `text` and `bytes` then hold this symbol's part only. */
readonly structuredAppend?: StructuredAppend;
/** Present when the symbol carries an FNC1 indicator (GS1 or an industry application). */
readonly fnc1?: Fnc1;
}
/** The header of a structured-append symbol. */
export interface StructuredAppend {
/** This symbol's place in the set, counting from 0. */
readonly index: number;
/** How many symbols the set has, 1 to 16. */
readonly total: number;
/** The parity byte: the XOR of every byte of the whole message, the same in each symbol of the set. */
readonly parity: number;
}
/**
* An FNC1 indicator. In alphanumeric segments `%` then reads as the group
* separator U+001D and `%%` as `%`, in `text` and `bytes` alike.
*/
export interface Fnc1 {
/** 'first' is the GS1 format; 'second' is an industry application. */
readonly position: 'first' | 'second';
/** Second position only: one letter or two digits, as a string. */
readonly applicationIndicator?: string;
}
/** Reads modules through a callback: true for dark, x across, y down. */
export type ModuleReader = (x: number, y: number) => boolean;
/**
* The version a symbol of `size` modules declares: from the size below
* version 7, else from its version blocks, or undefined when neither copy
* decodes.
*/
export declare function readVersion(read: ModuleReader, size: number): number | undefined;
/** A version hint only when both BCH copies independently decode to the same version. */
export declare function agreedVersion(read: ModuleReader, size: number): number | undefined;
/**
* The errors a block of this symbol may have had corrected: half of its check
* codewords once the p of Table 9 is withheld to catch a misdecode. Only
* versions 1 to 3 withhold any; Reed-Solomon alone would correct one more at
* 1-L, 1-M and 2-L.
*/
export declare function correctable(version: number, ecc: ErrorCorrection): number;
/**
* Decodes a symbol from its modules. `size` must be 17 + 4v. From version 7
* a version block that decodes decides, and a size that disagrees fails;
* if neither decodes, the size decides. Returns undefined when the symbol
* cannot be read.
*/
export declare function readSymbol(read: ModuleReader, size: number): Payload | undefined;
/**
* A deferred curved-map candidate needs an exact version word matching its size.
* Each independently readable peer must agree; at least one format copy must
* decode within the ordinary BCH radius. This admits a retry, never a result.
* The optional conflict mode tags a uniquely stronger format copy (0--2 errors
* versus 3); callers must keep it separate from ordinary curvature candidates.
*/
export declare function curvatureHeader(read: ModuleReader, size: number, allowConflict?: boolean): {
ecc: ErrorCorrection;
mask: number;
distance: number;
conflict?: true;
} | undefined;
/**
* An exact matching version word with a contradictory peer at the outer BCH
* radius can indicate warped header sampling. Both decoded format copies must
* agree. This only admits late refinement; it never admits a decoded payload.
*/
export declare function versionPeerHeader(read: ModuleReader, size: number): {
ecc: ErrorCorrection;
mask: number;
distance: number;
} | undefined;