postcode/esm/index.d.ts

UK Postcode helper methods

/**
 * @hidden
 */
export declare const DISTRICT_SPLIT_REGEX: RegExp;
/**
 * Tests for the unit section of a postcode
 */
export declare const UNIT_REGEX: RegExp;
/**
 * Tests for the inward code section of a postcode
 */
export declare const INCODE_REGEX: RegExp;
/**
 * Tests for the outward code section of a postcode
 */
export declare const OUTCODE_REGEX: RegExp;
/**
 * Tests for a valid postcode
 */
export declare const POSTCODE_REGEX: RegExp;
/**
 * Test for a valid postcode embedded in text
 */
export declare const POSTCODE_CORPUS_REGEX: RegExp;
/**
 * Tests for the area section of a postcode
 */
export declare const AREA_REGEX: RegExp;
/**
 * @hidden
 */
interface Validator {
    (input: string): boolean;
}
/**
 * @hidden
 */
interface Parser {
    /**
     * @hidden
     */
    (postcode: string): string | null;
}
/**
 * Represents a valid postcode
 *
 * Note that results will be normalised (i.e. correctly formatted), including `postcode`
 */
declare type ValidPostcode = {
    valid: true;
    postcode: string;
    incode: string;
    outcode: string;
    area: string;
    district: string;
    subDistrict: string | null;
    sector: string;
    unit: string;
};
declare type InvalidPostcode = {
    valid: false;
    postcode: null;
    incode: null;
    outcode: null;
    area: null;
    district: null;
    subDistrict: null;
    sector: null;
    unit: null;
};
/**
 * Detects a "valid" postcode
 * - Starts and ends on a non-space character
 * - Any length of intervening space is allowed
 * - Must conform to one of following schemas:
 *  - AA1A 1AA
 *  - A1A 1AA
 *  - A1 1AA
 *  - A99 9AA
 *  - AA9 9AA
 *  - AA99 9AA
 */
export declare const isValid: Validator;
/**
 * Returns true if string is a valid outcode
 */
export declare const validOutcode: Validator;
/**
 * Returns a normalised postcode string (i.e. uppercased and properly spaced)
 *
 * Returns null if invalid postcode
 */
export declare const toNormalised: Parser;
/**
 * Returns a correctly formatted outcode given a postcode
 *
 * Returns null if invalid postcode
 */
export declare const toOutcode: Parser;
/**
 * Returns a correctly formatted incode given a postcode
 *
 * Returns null if invalid postcode
 */
export declare const toIncode: Parser;
/**
 * Returns a correctly formatted area given a postcode
 *
 * Returns null if invalid postcode
 */
export declare const toArea: Parser;
/**
 * Returns a correctly formatted sector given a postcode
 *
 * Returns null if invalid postcode
 */
export declare const toSector: Parser;
/**
 * Returns a correctly formatted unit given a postcode
 *
 * Returns null if invalid postcode
 */
export declare const toUnit: Parser;
/**
 * Returns a correctly formatted district given a postcode
 *
 * Returns null if invalid postcode
 *
 * @example
 *
 * ```
 * toDistrict("AA9 9AA") // => "AA9"
 * toDistrict("A9A 9AA") // => "A9"
 * ```
 */
export declare const toDistrict: Parser;
/**
 * Returns a correctly formatted subdistrict given a postcode
 *
 * Returns null if no subdistrict is available on valid postcode
 * Returns null if invalid postcode
 *
 * @example
 *
 * ```
 * toSubDistrict("AA9A 9AA") // => "AA9A"
 * toSubDistrict("A9A 9AA") // => "A9A"
 * toSubDistrict("AA9 9AA") // => null
 * toSubDistrict("A9 9AA") // => null
 * ```
 */
export declare const toSubDistrict: Parser;
/**
 * Returns a ValidPostcode or InvalidPostcode object from a postcode string
 *
 * @example
 *
 * ```
 * import { parse } from "postcode";
 *
 * const {
 * postcode,    // => "SW1A 2AA"
 * outcode,     // => "SW1A"
 * incode,      // => "2AA"
 * area,        // => "SW"
 * district,    // => "SW1"
 * unit,        // => "AA"
 * sector,      // => "SW1A 2"
 * subDistrict, // => "SW1A"
 * valid,       // => true
 * } = parse("Sw1A     2aa");
 *
 * const {
 * postcode,    // => null
 * outcode,     // => null
 * incode,      // => null
 * area,        // => null
 * district,    // => null
 * unit,        // => null
 * sector,      // => null
 * subDistrict, // => null
 * valid,       // => false
 * } = parse("    Oh no, ):   ");
 * ```
 */
export declare const parse: (postcode: string) => ValidPostcode | InvalidPostcode;
/**
 * Searches a body of text for postcode matches
 *
 * Returns an empty array if no match
 *
 * @example
 *
 * ```
 * // Retrieve valid postcodes in a body of text
 * const matches = match("The PM and her no.2 live at SW1A2aa and SW1A 2AB"); // => ["SW1A2aa", "SW1A 2AB"]
 *
 * // Perform transformations like normalisation postcodes using `.map` and `toNormalised`
 * matches.map(toNormalised); // => ["SW1A 2AA", "SW1A 2AB"]
 *
 * // No matches yields empty array
 * match("Some London outward codes are SW1A, NW1 and E1"); // => []
 * ```
 */
export declare const match: (corpus: string) => string[];
/**
 * @hidden
 */
interface ReplaceResult {
    /**
     * List of matching postcodes found intext
     */
    match: string[];
    /**
     * Body of text with postcodes replaced (with empty string by default)
     */
    result: string;
}
/**
 * Replaces postcodes in a body of text with a string
 *
 * By default the replacement string is empty string `""`
 *
 * @example
 *
 * ```
 * // Replace postcodes in a body of text
 * replace("The PM and her no.2 live at SW1A2AA and SW1A 2AB");
 * // => { match: ["SW1A2AA", "SW1A 2AB"], result: "The PM and her no.2 live at  and " }
 *
 * // Add custom replacement
 * replace("The PM lives at SW1A 2AA", "Downing Street");
 * // => { match: ["SW1A 2AA"], result: "The PM lives at Downing Street" };
 *
 * // No match
 * replace("Some London outward codes are SW1A, NW1 and E1");
 * // => { match: [], result: "Some London outward codes are SW1A, NW1 and E1" }
 * ```
 */
export declare const replace: (corpus: string, replaceWith?: string) => ReplaceResult;
export declare const FIXABLE_REGEX: RegExp;
/**
 * Attempts to fix and clean a postcode. Specifically:
 * - Performs character conversion on obviously wrong and commonly mixed up letters (e.g. O => 0 and vice versa)
 * - Trims string
 * - Properly adds space between outward and inward codes
 *
 * If the postcode cannot be coerced into a valid format, the original string is returned
 *
 * @example
 * ```javascript
 * fix(" SW1A  2AO") => "SW1A 2AO" // Properly spaces
 * fix("SW1A 2A0") => "SW1A 2AO" // 0 is coerced into "0"
 * ```
 *
 * Aims to be used in conjunction with parse to make postcode entry more forgiving:
 *
 * @example
 * ```javascript
 * const { inward } = parse(fix("SW1A 2A0")); // inward = "2AO"
 * ```
 */
export declare const fix: (s: string) => string;
export {};