ng-postcode-js 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Adeniyi
+
+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.

package/README.md

@@ -0,0 +1,66 @@
+# ng-postcode-js
+
+JavaScript and TypeScript library for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. Parse, validate and format postcodes offline, and call the [postcode.gov.ng](https://docs.postcode.gov.ng) API for lookup, autocomplete and reverse geocoding.
+
+Part of the [ng-postcode project](https://github.com/Adeniyikayodee/ng-postcode), which has the same behaviour in Rust and Python and an MCP server for AI assistants. All three run the same shared test cases.
+
+```sh
+npm install ng-postcode-js
+```
+
+No runtime dependencies. Needs Node 20 or later, or any runtime with `fetch`.
+
+## Offline
+
+Expected failures are returned as values, not thrown, so the type checker makes you handle them.
+
+```ts
+import { Postcode, parse } from "ng-postcode-js";
+
+const code = parse("ek 01 a03 fk 01");
+if (code instanceof Postcode) {
+  console.log(String(code)); // EK-01-A03-FK-01
+  console.log(code.compact); // EK01A03FK01, store this
+  console.log(code.spaced); // EK 01 A03 FK 01
+  console.log(code.prefix("area")); // EK-01-A03-FK
+} else {
+  console.log(String(code)); // e.g. "invalid lga segment"
+}
+```
+
+- `parse` accepts hyphenated, spaced or compact input in either case.
+- `parseLenient` first swaps look-alikes that cannot occur where they stand (`O`/`0`, `I`/`1`, `S`/`5`, `B`/`8`) and reports how many it changed.
+- `fromSegments` assembles a code from its parts and zero-fills the LGA and unit.
+- `isValid` answers yes or no.
+
+A well-formed code is not necessarily assigned to a building. Only the API can confirm that a postcode exists.
+
+## API
+
+```ts
+import { Postcode, parse } from "ng-postcode-js";
+import { ApiError, lookup } from "ng-postcode-js/api";
+import { Client, TransportError } from "ng-postcode-js/client";
+
+const code = parse("FC-03-B06-AG-12");
+if (!(code instanceof Postcode)) throw new Error(String(code));
+
+const client = new Client(process.env.NG_POSTCODE_API_KEY ?? "");
+const found = await client.send(lookup(code, 1));
+
+if (found instanceof ApiError || found instanceof TransportError) {
+  console.error(String(found)); // e.g. "invalid_api_key (401): ..."
+} else {
+  console.log(found.valid, found.status); // true valid
+}
+```
+
+`ng-postcode-js/api` covers `lookup`, `autocomplete`, `reverse` and `nearby`. Each returns a plain `Request`, and `decode` turns a status and body into a typed result, so it works with any HTTP client. A request that cannot succeed, such as a level outside 1 to 5, an empty autocomplete or a coordinate that is not finite, throws `RangeError` before anything is sent.
+
+The client refuses redirects, so the key is never sent to another host. Response fields keep the API's own names, such as `administrative_address`.
+
+Get a key from the [NIPOST developer dashboard](https://dashboard.postcode.gov.ng). Level 1 lookups confirm a code is assigned; levels 2 and up return address details and consume credits.
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The NIPOST Postcode API as plain data: requests to send and responses to decode.
+ *
+ * Nothing here performs I/O, so it works with any HTTP client. Assembly and
+ * disassembly are not modelled: `parse` and `fromSegments` do both offline.
+ * Response fields keep the API's own names.
+ */
+import { type Postcode, type Segment } from "./postcode.js";
+export declare const BASE_URL = "https://api.postcode.gov.ng";
+/** A GET request whose successful response decodes to `T`. */
+export interface Request<T> {
+    readonly path: string;
+    readonly params: ReadonlyArray<readonly [string, string]>;
+    readonly read: (data: unknown) => T | undefined;
+}
+export interface Coordinate {
+    readonly lat: number;
+    readonly lng: number;
+}
+/**
+ * The API refused the request, with `code` taken from its error envelope
+ * (`auth_required`, `insufficient_credits`, ...), or its answer was not the
+ * documented envelope, with `code` set to `malformed_response`.
+ */
+export declare class ApiError {
+    readonly status: number;
+    readonly code: string;
+    readonly message: string;
+    constructor(status: number, code: string, message: string);
+    toString(): string;
+}
+export interface AdministrativeAddress {
+    readonly state_name: string | null;
+    readonly lga_name: string | null;
+    readonly locality_name: string | null;
+    readonly zone: string | null;
+}
+/** Fields above the level granted to the key are `null`. */
+export interface Lookup {
+    readonly postcode: string;
+    readonly valid: boolean;
+    /** `valid`, `not_found`, or `invalid` for a malformed code. Sent at every level. */
+    readonly status: string | null;
+    readonly verified: boolean | null;
+    /** Level 2. */
+    readonly administrative_address: AdministrativeAddress | null;
+    /** Level 2. */
+    readonly recent_house_address: string | null;
+    /** Level 3. */
+    readonly building_use_status: string | null;
+    /** Level 4. Undocumented, so left as raw JSON. */
+    readonly other_building_info: unknown;
+    /** Level 5. Undocumented, so left as raw JSON. */
+    readonly point_geometry: unknown;
+}
+export interface Suggestion {
+    /** The value of the segment being completed, such as `A03`, not a full prefix. */
+    readonly code: string;
+    /** Documented by NIPOST but not sent by the live API as of October 2026. */
+    readonly label: string | null;
+}
+export interface Autocomplete {
+    /** The segment the suggestions complete. */
+    readonly segment: Segment | null;
+    readonly suggestions: readonly Suggestion[];
+}
+export interface NearestUnit {
+    readonly postcode: string;
+    readonly display: string;
+    readonly distance_m: number | null;
+    /** `high`, `medium` or `low`, graded by distance. */
+    readonly confidence: string | null;
+    readonly state_name: string | null;
+    readonly lga_name: string | null;
+    readonly locality_name: string | null;
+    /** Recent house address. This and the names above need level 2. */
+    readonly address: string | null;
+}
+export interface Reverse {
+    readonly found: boolean;
+    /** The queried point, echoed back. */
+    readonly coordinate: Coordinate | null;
+    /** The nearest building, absent when nothing is in range. */
+    readonly unit: NearestUnit | null;
+    readonly area: string | null;
+    readonly district: string | null;
+    readonly state: string | null;
+    /** Set when nothing is in range. */
+    readonly message: string | null;
+    /** The radius the API actually applied. */
+    readonly radius_m: number | null;
+    /** How deep the match goes, such as `unit`. */
+    readonly depth: string | null;
+}
+export interface NearbyUnit {
+    readonly postcode: string;
+    readonly display: string;
+    readonly distance_m: number | null;
+}
+/**
+ * Resolve a postcode. Levels are cumulative from 1 (validity only) to 5, and
+ * the API caps the answer at the level granted to the key.
+ *
+ * Throws `RangeError` for a level outside 1 to 5.
+ */
+export declare function lookup(code: Postcode, level?: number): Request<Lookup>;
+/**
+ * Suggest completions for a partial postcode such as `EK 01 A`.
+ *
+ * Throws `RangeError` for an empty `partial`: the live API never answers one.
+ */
+export declare function autocomplete(partial: string): Request<Autocomplete>;
+/**
+ * Find the postcode of the nearest building, within 25 m unless `maxDistanceM`
+ * says otherwise. The API clamps it to 250 m.
+ *
+ * Throws `RangeError` for a coordinate or distance that is not a finite number.
+ */
+export declare function reverse(at: Coordinate, maxDistanceM?: number): Request<Reverse>;
+/**
+ * List buildings around a point, nearest first, within 300 m unless `radiusM`
+ * says otherwise. Empty when nothing is in range.
+ *
+ * Throws `RangeError` for a coordinate or radius that is not a finite number.
+ */
+export declare function nearby(at: Coordinate, radiusM?: number): Request<readonly NearbyUnit[]>;
+/** Decode the response to `request` from its status and body. */
+export declare function decode<T>(request: Request<T>, status: number, body: string): T | ApiError;

package/dist/api.js

@@ -0,0 +1,198 @@
+/**
+ * The NIPOST Postcode API as plain data: requests to send and responses to decode.
+ *
+ * Nothing here performs I/O, so it works with any HTTP client. Assembly and
+ * disassembly are not modelled: `parse` and `fromSegments` do both offline.
+ * Response fields keep the API's own names.
+ */
+import { SEGMENTS } from "./postcode.js";
+export const BASE_URL = "https://api.postcode.gov.ng";
+/**
+ * The API refused the request, with `code` taken from its error envelope
+ * (`auth_required`, `insufficient_credits`, ...), or its answer was not the
+ * documented envelope, with `code` set to `malformed_response`.
+ */
+export class ApiError {
+    status;
+    code;
+    message;
+    constructor(status, code, message) {
+        this.status = status;
+        this.code = code;
+        this.message = message;
+    }
+    toString() {
+        return `${this.code} (${this.status}): ${this.message}`;
+    }
+}
+/**
+ * Resolve a postcode. Levels are cumulative from 1 (validity only) to 5, and
+ * the API caps the answer at the level granted to the key.
+ *
+ * Throws `RangeError` for a level outside 1 to 5.
+ */
+export function lookup(code, level = 1) {
+    if (!Number.isInteger(level) || level < 1 || level > 5) {
+        throw new RangeError(`level must be 1 to 5, got ${level}`);
+    }
+    const params = [
+        ["code", code.toString()],
+        ["level", String(level)],
+    ];
+    return { path: "/v1/lookup", params, read: readLookup };
+}
+/**
+ * Suggest completions for a partial postcode such as `EK 01 A`.
+ *
+ * Throws `RangeError` for an empty `partial`: the live API never answers one.
+ */
+export function autocomplete(partial) {
+    if (!partial.trim())
+        throw new RangeError("partial must not be empty");
+    return { path: "/v1/search/autocomplete", params: [["q", partial]], read: readAutocomplete };
+}
+/**
+ * Find the postcode of the nearest building, within 25 m unless `maxDistanceM`
+ * says otherwise. The API clamps it to 250 m.
+ *
+ * Throws `RangeError` for a coordinate or distance that is not a finite number.
+ */
+export function reverse(at, maxDistanceM) {
+    const params = around(at, "max_distance_m", maxDistanceM);
+    return { path: "/v1/search/reverse", params, read: readReverse };
+}
+/**
+ * List buildings around a point, nearest first, within 300 m unless `radiusM`
+ * says otherwise. Empty when nothing is in range.
+ *
+ * Throws `RangeError` for a coordinate or radius that is not a finite number.
+ */
+export function nearby(at, radiusM) {
+    return { path: "/v1/search/nearby", params: around(at, "radius", radiusM), read: readNearby };
+}
+/** Decode the response to `request` from its status and body. */
+export function decode(request, status, body) {
+    let envelope;
+    try {
+        envelope = JSON.parse(body);
+    }
+    catch (error) {
+        return malformed(status, `not JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    if (!isObject(envelope))
+        return malformed(status, "expected a JSON object");
+    const failure = envelope.error;
+    if (isObject(failure)) {
+        return new ApiError(status, text(failure, "code") ?? "unknown_error", text(failure, "message") ?? "");
+    }
+    if (typeof failure === "string")
+        return new ApiError(status, "unknown_error", failure);
+    if (status < 200 || status >= 300)
+        return malformed(status, "an error status without an error");
+    return request.read(envelope.data) ?? malformed(status, "unexpected data");
+}
+function around(at, key, metres) {
+    const point = [
+        ["lat", numberText(at.lat)],
+        ["lng", numberText(at.lng)],
+    ];
+    return metres === undefined ? point : [...point, [key, numberText(metres)]];
+}
+function numberText(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new RangeError(`expected a finite number, got ${value}`);
+    }
+    return String(value);
+}
+function malformed(status, message) {
+    return new ApiError(status, "malformed_response", message);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function object(data, key) {
+    const value = data[key];
+    return isObject(value) ? value : null;
+}
+function text(data, key) {
+    const value = data[key];
+    return typeof value === "string" ? value : null;
+}
+function number(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function readNearby(data) {
+    if (!Array.isArray(data))
+        return undefined;
+    return data.filter(isObject).map((item) => ({
+        postcode: text(item, "postcode") ?? "",
+        display: text(item, "display") ?? "",
+        distance_m: number(item.distance_m),
+    }));
+}
+function readLookup(data) {
+    if (!isObject(data))
+        return undefined;
+    const admin = object(data, "administrative_address");
+    const recent = object(data, "recent_house_address");
+    return {
+        postcode: text(data, "postcode") ?? "",
+        valid: data.valid === true,
+        status: text(data, "status"),
+        verified: typeof data.verified === "boolean" ? data.verified : null,
+        administrative_address: admin && {
+            state_name: text(admin, "state_name"),
+            lga_name: text(admin, "lga_name"),
+            locality_name: text(admin, "locality_name"),
+            zone: text(admin, "zone"),
+        },
+        recent_house_address: recent && text(recent, "recent"),
+        building_use_status: text(data, "building_use_status"),
+        other_building_info: data.other_building_info ?? null,
+        point_geometry: data.point_geometry ?? null,
+    };
+}
+function readAutocomplete(data) {
+    if (!isObject(data))
+        return undefined;
+    const items = Array.isArray(data.suggestions) ? data.suggestions : [];
+    const suggestions = items.filter(isObject).map((item) => ({
+        code: text(item, "code") ?? "",
+        label: text(item, "label"),
+    }));
+    const segment = SEGMENTS.find((name) => name === data.segment) ?? null;
+    return { segment, suggestions };
+}
+function readReverse(data) {
+    if (!isObject(data))
+        return undefined;
+    const unit = object(data, "unit");
+    return {
+        found: data.found === true,
+        coordinate: readCoordinate(data.coordinate),
+        unit: unit && {
+            postcode: text(unit, "postcode") ?? "",
+            display: text(unit, "display") ?? "",
+            distance_m: number(unit.distance_m),
+            confidence: text(unit, "confidence"),
+            state_name: text(unit, "state_name"),
+            lga_name: text(unit, "lga_name"),
+            locality_name: text(unit, "locality_name"),
+            address: text(unit, "address"),
+        },
+        area: text(data, "area"),
+        district: text(data, "district"),
+        state: text(data, "state"),
+        message: text(data, "message"),
+        radius_m: number(data.radius_m),
+        depth: text(data, "depth"),
+    };
+}
+/** The API echoes points as `[lng, lat]`. */
+function readCoordinate(value) {
+    if (!Array.isArray(value) || value.length !== 2)
+        return null;
+    const [lng, lat] = [number(value[0]), number(value[1])];
+    return lng === null || lat === null ? null : { lat, lng };
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+/** HTTP shell over `api`, built on `fetch`: the only module that performs I/O. */
+import { type ApiError, type Request } from "./api.js";
+export declare const TIMEOUT_MS = 10000;
+/** The request never produced a response: DNS, TLS, timeout and the like. */
+export declare class TransportError {
+    readonly reason: string;
+    constructor(reason: string);
+    toString(): string;
+}
+export interface ClientOptions {
+    /** Another host, such as a staging stack or a mock. */
+    readonly baseUrl?: string;
+    /** Your own `fetch`, for proxies or tests. */
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export declare class Client {
+    #private;
+    constructor(apiKey: string, options?: ClientOptions);
+    send<T>(request: Request<T>): Promise<T | ApiError | TransportError>;
+}

package/dist/client.js

@@ -0,0 +1,49 @@
+/** HTTP shell over `api`, built on `fetch`: the only module that performs I/O. */
+import { BASE_URL, decode } from "./api.js";
+export const TIMEOUT_MS = 10_000;
+/** The request never produced a response: DNS, TLS, timeout and the like. */
+export class TransportError {
+    reason;
+    constructor(reason) {
+        this.reason = reason;
+    }
+    toString() {
+        return this.reason;
+    }
+}
+export class Client {
+    #apiKey;
+    #baseUrl;
+    #fetch;
+    #timeoutMs;
+    constructor(apiKey, options = {}) {
+        this.#apiKey = apiKey;
+        this.#baseUrl = options.baseUrl ?? BASE_URL;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    }
+    async send(request) {
+        const url = new URL(this.#baseUrl + request.path);
+        for (const [key, value] of request.params)
+            url.searchParams.append(key, value);
+        try {
+            const response = await this.#fetch(url, {
+                headers: { "X-API-Key": this.#apiKey },
+                // A redirect would carry the key to another host, so it is refused.
+                redirect: "error",
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+            return decode(request, response.status, await response.text());
+        }
+        catch (error) {
+            return new TransportError(reason(error));
+        }
+    }
+}
+function reason(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause instanceof Error ? `: ${error.cause.message}` : "";
+    return `${error.message || error.name}${cause}`;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAiB,QAAQ,EAAE,MAAM,EAAgB,MAAM,UAAU,CAAC;AAEzE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC;AAEjC,6EAA6E;AAC7E,MAAM,OAAO,cAAc;IACJ,MAAM;IAA3B,YAAqB,MAAc;sBAAd,MAAM;IAAW,CAAC;IAEvC,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF;AAUD,MAAM,OAAO,MAAM;IACR,OAAO,CAAS;IAChB,QAAQ,CAAS;IACjB,MAAM,CAAe;IACrB,UAAU,CAAS;IAE5B,YAAY,MAAc,EAAE,OAAO,GAAkB,EAAE;QACrD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;QAC5C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,OAAmB;QAC/B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM;YAAE,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC/E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE;gBACtC,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE;gBACtC,oEAAoE;gBACpE,QAAQ,EAAE,OAAO;gBACjB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;aAC7C,CAAC,CAAC;YACH,OAAO,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;CACF;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,GAAG,KAAK,EAAE,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Nigeria's National Digital Alphanumeric Postcode (NDAPS), the building-level
+ * postcode issued by NIPOST.
+ *
+ * Expected failures come back as values, never exceptions:
+ *
+ * ```ts
+ * import { Postcode, parse } from "ng-postcode-js";
+ *
+ * const code = parse("ek 01 a03 fk 01");
+ * if (code instanceof Postcode) {
+ *   console.log(String(code), code.compact); // EK-01-A03-FK-01 EK01A03FK01
+ * } else {
+ *   console.log(String(code)); // e.g. "invalid lga segment"
+ * }
+ * ```
+ */
+export { type Corrected, fromSegments, InvalidCharacter, InvalidSegment, isValid, LENGTH, type ParseError, Postcode, parse, parseLenient, SEGMENTS, type Segment, WrongLength, } from "./postcode.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * Nigeria's National Digital Alphanumeric Postcode (NDAPS), the building-level
+ * postcode issued by NIPOST.
+ *
+ * Expected failures come back as values, never exceptions:
+ *
+ * ```ts
+ * import { Postcode, parse } from "ng-postcode-js";
+ *
+ * const code = parse("ek 01 a03 fk 01");
+ * if (code instanceof Postcode) {
+ *   console.log(String(code), code.compact); // EK-01-A03-FK-01 EK01A03FK01
+ * } else {
+ *   console.log(String(code)); // e.g. "invalid lga segment"
+ * }
+ * ```
+ */
+export { fromSegments, InvalidCharacter, InvalidSegment, isValid, LENGTH, Postcode, parse, parseLenient, SEGMENTS, WrongLength, } from "./postcode.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,MAAM,EAEN,QAAQ,EACR,KAAK,EACL,YAAY,EACZ,QAAQ,EAER,WAAW,GACZ,MAAM,eAAe,CAAC"}

package/dist/postcode.d.ts

@@ -0,0 +1,71 @@
+/** Offline parsing, validation and formatting. Pure: no I/O, no mutation. */
+export declare const LENGTH = 11;
+/** The five segments of a postcode, `AA-99-H77-BB-55`, widest first. */
+export declare const SEGMENTS: readonly ["state", "lga", "district", "area", "unit"];
+export type Segment = (typeof SEGMENTS)[number];
+/** The input did not hold exactly 11 letters and digits. */
+export declare class WrongLength {
+    readonly found: number;
+    constructor(found: number);
+    toString(): string;
+}
+/** The input held something other than letters, digits, spaces and hyphens. */
+export declare class InvalidCharacter {
+    readonly char: string;
+    readonly index: number;
+    constructor(char: string, index: number);
+    toString(): string;
+}
+/** A segment has the wrong shape, such as digits in the state or `00` as a unit. */
+export declare class InvalidSegment {
+    readonly segment: Segment;
+    constructor(segment: Segment);
+    toString(): string;
+}
+export type ParseError = WrongLength | InvalidCharacter | InvalidSegment;
+/**
+ * A well-formed postcode, held in its compact upper-case form.
+ *
+ * Well formed is not the same as assigned: only the NIPOST API knows whether a
+ * code belongs to a real building. Build one with `parse`.
+ */
+export declare class Postcode {
+    readonly compact: string;
+    private constructor();
+    /** @internal Callers use `parse`; this takes a string already validated. */
+    static unchecked(compact: string): Postcode;
+    /** The canonical hyphenated form, `EK-01-A03-FK-01`. */
+    toString(): string;
+    toJSON(): string;
+    /** The form shown to people, `EK 01 A03 FK 01`. */
+    get spaced(): string;
+    get state(): string;
+    get lga(): string;
+    get district(): string;
+    get area(): string;
+    get unit(): string;
+    segment(segment: Segment): string;
+    /** The hyphenated code down to `through`: `prefix("area")` is `EK-01-A03-FK`. */
+    prefix(through: Segment): string;
+}
+/** The result of `parseLenient`. */
+export interface Corrected {
+    readonly postcode: Postcode;
+    /** How many characters were swapped for their look-alike. */
+    readonly corrections: number;
+}
+/** Parse a hyphenated, spaced or compact code in either case. */
+export declare function parse(text: string): Postcode | ParseError;
+/**
+ * Parse after swapping look-alikes that cannot occur where they stand: `0 1 5 8`
+ * become `O I S B` where a letter is required, and `O I L S B` become `0 1 1 5 8`
+ * where a digit is. The district allows both, so it is never rewritten.
+ *
+ * The result is well formed but may not be the code the user meant, so confirm
+ * it with them when `corrections` is not zero.
+ */
+export declare function parseLenient(text: string): Corrected | ParseError;
+/** Build a code from its segments, zero-filling the LGA and unit. */
+export declare function fromSegments(state: string, lga: string, district: string, area: string, unit: string): Postcode | ParseError;
+/** Whether `text` is a well-formed postcode. */
+export declare function isValid(text: string): boolean;

package/dist/postcode.js

@@ -0,0 +1,183 @@
+/** Offline parsing, validation and formatting. Pure: no I/O, no mutation. */
+export const LENGTH = 11;
+/** The five segments of a postcode, `AA-99-H77-BB-55`, widest first. */
+export const SEGMENTS = ["state", "lga", "district", "area", "unit"];
+const SPANS = {
+    state: [0, 2],
+    lga: [2, 4],
+    district: [4, 7],
+    area: [7, 9],
+    unit: [9, 11],
+};
+const ALPHA = new Set(["state", "area"]);
+const NUMERIC = new Set(["lga", "unit"]);
+const TO_LETTER = { "0": "O", "1": "I", "5": "S", "8": "B" };
+const TO_DIGIT = { O: "0", I: "1", L: "1", S: "5", B: "8" };
+/** The input did not hold exactly 11 letters and digits. */
+export class WrongLength {
+    found;
+    constructor(found) {
+        this.found = found;
+    }
+    toString() {
+        return `expected ${LENGTH} letters and digits, found ${this.found}`;
+    }
+}
+/** The input held something other than letters, digits, spaces and hyphens. */
+export class InvalidCharacter {
+    char;
+    index;
+    constructor(char, index) {
+        this.char = char;
+        this.index = index;
+    }
+    toString() {
+        return `invalid character '${this.char}' at index ${this.index}`;
+    }
+}
+/** A segment has the wrong shape, such as digits in the state or `00` as a unit. */
+export class InvalidSegment {
+    segment;
+    constructor(segment) {
+        this.segment = segment;
+    }
+    toString() {
+        return `invalid ${this.segment} segment`;
+    }
+}
+/**
+ * A well-formed postcode, held in its compact upper-case form.
+ *
+ * Well formed is not the same as assigned: only the NIPOST API knows whether a
+ * code belongs to a real building. Build one with `parse`.
+ */
+export class Postcode {
+    compact;
+    constructor(compact) {
+        this.compact = compact;
+    }
+    /** @internal Callers use `parse`; this takes a string already validated. */
+    static unchecked(compact) {
+        return new Postcode(compact);
+    }
+    /** The canonical hyphenated form, `EK-01-A03-FK-01`. */
+    toString() {
+        return this.prefix("unit");
+    }
+    toJSON() {
+        return this.toString();
+    }
+    /** The form shown to people, `EK 01 A03 FK 01`. */
+    get spaced() {
+        return SEGMENTS.map((segment) => this.segment(segment)).join(" ");
+    }
+    get state() {
+        return this.segment("state");
+    }
+    get lga() {
+        return this.segment("lga");
+    }
+    get district() {
+        return this.segment("district");
+    }
+    get area() {
+        return this.segment("area");
+    }
+    get unit() {
+        return this.segment("unit");
+    }
+    segment(segment) {
+        return part(this.compact, segment);
+    }
+    /** The hyphenated code down to `through`: `prefix("area")` is `EK-01-A03-FK`. */
+    prefix(through) {
+        return SEGMENTS.slice(0, SEGMENTS.indexOf(through) + 1)
+            .map((segment) => this.segment(segment))
+            .join("-");
+    }
+}
+/** Parse a hyphenated, spaced or compact code in either case. */
+export function parse(text) {
+    const compact = collect(text);
+    if (typeof compact !== "string")
+        return compact;
+    return validate(compact) ?? Postcode.unchecked(compact);
+}
+/**
+ * Parse after swapping look-alikes that cannot occur where they stand: `0 1 5 8`
+ * become `O I S B` where a letter is required, and `O I L S B` become `0 1 1 5 8`
+ * where a digit is. The district allows both, so it is never rewritten.
+ *
+ * The result is well formed but may not be the code the user meant, so confirm
+ * it with them when `corrections` is not zero.
+ */
+export function parseLenient(text) {
+    const raw = collect(text);
+    if (typeof raw !== "string")
+        return raw;
+    const fixed = SEGMENTS.map((segment) => unconfuse(segment, part(raw, segment))).join("");
+    const error = validate(fixed);
+    if (error)
+        return error;
+    const corrections = [...raw].filter((char, index) => char !== fixed[index]).length;
+    return { postcode: Postcode.unchecked(fixed), corrections };
+}
+/** Build a code from its segments, zero-filling the LGA and unit. */
+export function fromSegments(state, lga, district, area, unit) {
+    const values = [state, lga, district, area, unit];
+    const padded = SEGMENTS.map((segment, index) => pad(segment, values[index] ?? ""));
+    const error = padded.find((value) => value instanceof InvalidSegment);
+    if (error instanceof InvalidSegment)
+        return error;
+    return parse(padded.join(""));
+}
+/** Whether `text` is a well-formed postcode. */
+export function isValid(text) {
+    return parse(text) instanceof Postcode;
+}
+function isAsciiAlphanumeric(char) {
+    return /^[A-Za-z0-9]$/.test(char);
+}
+function collect(text) {
+    const kept = [];
+    let index = 0;
+    for (const char of text) {
+        if (char !== " " && char !== "-") {
+            if (!isAsciiAlphanumeric(char))
+                return new InvalidCharacter(char, index);
+            kept.push(char);
+        }
+        index += 1;
+    }
+    if (kept.length !== LENGTH)
+        return new WrongLength(kept.length);
+    return kept.join("").toUpperCase();
+}
+function part(compact, segment) {
+    const [start, end] = SPANS[segment];
+    return compact.slice(start, end);
+}
+function validate(compact) {
+    const bad = SEGMENTS.find((segment) => !accepts(segment, part(compact, segment)));
+    return bad ? new InvalidSegment(bad) : undefined;
+}
+function accepts(segment, text) {
+    if (ALPHA.has(segment))
+        return /^[A-Z]*$/.test(text);
+    if (NUMERIC.has(segment))
+        return /^[0-9]*$/.test(text) && text !== "00";
+    return /^[A-Z0-9]*$/.test(text);
+}
+function unconfuse(segment, text) {
+    const table = ALPHA.has(segment) ? TO_LETTER : NUMERIC.has(segment) ? TO_DIGIT : {};
+    return [...text].map((char) => table[char] ?? char).join("");
+}
+function pad(segment, value) {
+    const text = value.trim();
+    const [start, end] = SPANS[segment];
+    const width = end - start;
+    const shortest = NUMERIC.has(segment) ? 1 : width;
+    const fits = text.length >= shortest && text.length <= width && /^[A-Za-z0-9]+$/.test(text);
+    return fits ? text.padStart(width, "0") : new InvalidSegment(segment);
+}
+//# sourceMappingURL=postcode.js.map

package/dist/postcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode.js","sourceRoot":"","sources":["../src/postcode.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ng-postcode-js",
+  "version": "0.1.0",
+  "description": "Parse, validate and format Nigeria's NIPOST digital postcode (NDAPS) offline, plus a client for the postcode.gov.ng API.",
+  "license": "MIT",
+  "author": "Kayode Adeniyi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Adeniyikayodee/ng-postcode.git",
+    "directory": "js/packages/ng-postcode-js"
+  },
+  "homepage": "https://adeniyikayodee.github.io/ng-postcode/",
+  "bugs": "https://github.com/Adeniyikayodee/ng-postcode/issues",
+  "keywords": [
+    "nigeria",
+    "postcode",
+    "nipost",
+    "ndaps",
+    "address",
+    "address-validation",
+    "geocoding",
+    "postal-code"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "default": "./dist/api.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}