@aprestmo/norway-geodata 0.1.0

package/dist/esm/index.d.ts

@@ -0,0 +1,207 @@
+import type { Municipality, County, PostalCode, PopulationDensityStats, LanguageStatus, MunicipalitySearchOptions, MunicipalityFilterOptions, PostalCodeSearchOptions } from './types';
+/**
+ * Get the library version following semantic versioning.
+ * @returns Version string (e.g., "1.0.0")
+ */
+export declare function getVersion(): string;
+/**
+ * Get all municipalities with metadata.
+ * @returns Array of all municipalities
+ */
+export declare function getMunicipalities(): readonly Municipality[];
+/**
+ * Get a municipality by municipality ID.
+ * @param id - 4-digit municipality ID (e.g., "0301" for Oslo)
+ * @returns Municipality object or undefined if not found
+ * @throws {TypeError} If id is not a string
+ */
+export declare function getMunicipalityById(id: string): Municipality | undefined;
+/**
+ * Get municipalities by name (case-insensitive partial match by default).
+ * @param name - Municipality name or partial name to search for
+ * @param options - Search options
+ * @returns Array of matching municipalities
+ * @throws {TypeError} If name is not a string
+ */
+export declare function getMunicipalitiesByName(name: string, options?: MunicipalitySearchOptions): Municipality[];
+/**
+ * Get all counties (fylker) with metadata.
+ * @returns Array of all counties
+ */
+export declare function getCounties(): readonly County[];
+/**
+ * Get a county by county ID.
+ * @param id - 2-digit county ID (e.g., "03" for Oslo)
+ * @returns County object or undefined if not found
+ * @throws {TypeError} If id is not a string
+ */
+export declare function getCountyById(id: string): County | undefined;
+/**
+ * Get county by name (case-insensitive partial match).
+ * @param name - County name or partial name to search for
+ * @param exactMatch - Whether to match exactly (default: false)
+ * @returns County object or undefined if not found
+ * @throws {TypeError} If name is not a string
+ */
+export declare function getCountyByName(name: string, exactMatch?: boolean): County | undefined;
+/**
+ * Get all municipalities in a given county.
+ * @param countyId - 2-digit county ID (first two digits of municipality k_id)
+ * @returns Array of municipalities in the county
+ * @throws {TypeError} If countyId is not a string
+ */
+export declare function getMunicipalitiesByCounty(countyId: string): Municipality[];
+/**
+ * Get municipality by postal code.
+ * @param postalCode - Postal code to search for
+ * @returns Municipality object or undefined if not found
+ * @throws {TypeError} If postal code is not a valid number
+ */
+export declare function getMunicipalityByPostalCode(postalCode: string | number): Municipality | undefined;
+/**
+ * Get all postal codes for a specific municipality.
+ * @param municipalityId - 4-digit municipality ID
+ * @returns Array of postal codes or undefined if municipality not found
+ */
+export declare function getPostalCodesByMunicipality(municipalityId: string): readonly string[] | undefined;
+/**
+ * Get all postal codes from all municipalities.
+ * @param includeDetails - If true, returns objects with postal code and place name. If false, returns only postal codes (default: false)
+ * @returns Array of postal codes or postal code objects
+ */
+export declare function getAllPostalCodes(includeDetails?: boolean): readonly string[] | readonly {
+    zip: string;
+    place: string;
+    municipalityId: string;
+    municipalityName: string;
+}[];
+/**
+ * Get municipalities sorted by population.
+ * @param ascending - Sort in ascending order if true (default: false for descending)
+ * @returns Array of municipalities sorted by population
+ */
+export declare function getMunicipalitiesByPopulation(ascending?: boolean): Municipality[];
+/**
+ * Get municipalities sorted by area.
+ * @param ascending - Sort in ascending order if true (default: false for descending)
+ * @returns Array of municipalities sorted by area
+ */
+export declare function getMunicipalitiesByArea(ascending?: boolean): Municipality[];
+/**
+ * Get municipalities by language status.
+ * @param language - Language status
+ * @returns Array of municipalities with the specified language status
+ * @throws {TypeError} If language is not a string
+ */
+export declare function getMunicipalitiesByLanguage(language: LanguageStatus): Municipality[];
+/**
+ * Get municipalities with advanced filtering options.
+ * @param options - Filter options
+ * @returns Array of municipalities matching the filter criteria
+ */
+export declare function getMunicipalitiesFiltered(options: MunicipalityFilterOptions): Municipality[];
+/**
+ * Get total population of all municipalities.
+ * @returns Total population
+ */
+export declare function getTotalPopulation(): number;
+/**
+ * Get total area of all municipalities.
+ * @returns Total area in square kilometers
+ */
+export declare function getTotalArea(): number;
+/**
+ * Get population density statistics.
+ * @returns Object with min, max, and average population density
+ */
+export declare function getPopulationDensityStats(): PopulationDensityStats;
+/**
+ * Get municipalities by population density range.
+ * @param minDensity - Minimum population density (people per km²)
+ * @param maxDensity - Maximum population density (people per km²)
+ * @returns Array of municipalities within the density range
+ */
+export declare function getMunicipalitiesByPopulationDensity(minDensity?: number, maxDensity?: number): Municipality[];
+/**
+ * Get the largest municipalities by population.
+ * @param count - Number of municipalities to return (default: 10)
+ * @returns Array of largest municipalities by population
+ */
+export declare function getLargestMunicipalities(count?: number): Municipality[];
+/**
+ * Get the smallest municipalities by population.
+ * @param count - Number of municipalities to return (default: 10)
+ * @returns Array of smallest municipalities by population
+ */
+export declare function getSmallestMunicipalities(count?: number): Municipality[];
+/**
+ * Get all postal codes with metadata.
+ * @returns Array of all postal codes
+ */
+export declare function getPostalCodes(): readonly PostalCode[];
+/**
+ * Get postal code information by postal code.
+ * @param code - 4-digit postal code (e.g., "0001")
+ * @returns PostalCode object or undefined if not found
+ * @throws {TypeError} If code is not a string
+ */
+export declare function getPostalCodeByCode(code: string): PostalCode | undefined;
+/**
+ * Get postal codes by postal place (case-insensitive partial match by default).
+ * @param place - Postal place name or partial name to search for
+ * @param options - Search options
+ * @returns Array of matching postal codes
+ * @throws {TypeError} If place is not a string
+ */
+export declare function getPostalCodesByPlace(place: string, options?: PostalCodeSearchOptions): PostalCode[];
+/**
+ * Get postal codes by municipality ID.
+ * @param municipalityId - 4-digit municipality ID (e.g., "0301" for Oslo)
+ * @returns Array of postal codes for the municipality
+ * @throws {TypeError} If municipalityId is not a string
+ */
+export declare function getPostalCodesByMunicipalityId(municipalityId: string): PostalCode[];
+/**
+ * Get unique postal places.
+ * @returns Array of unique postal place names sorted alphabetically
+ */
+export declare function getUniquePostalPlaces(): readonly string[];
+/**
+ * Get postal codes within a range.
+ * @param startCode - Starting postal code (inclusive)
+ * @param endCode - Ending postal code (inclusive)
+ * @returns Array of postal codes within the range
+ * @throws {TypeError} If start or end codes are not strings
+ */
+export declare function getPostalCodesInRange(startCode: string, endCode: string): PostalCode[];
+/**
+ * Get postal codes statistics.
+ * @returns Object with total count and unique places count
+ */
+export declare function getPostalCodesStats(): {
+    readonly totalPostalCodes: number;
+    readonly uniquePlaces: number;
+    readonly uniqueMunicipalities: number;
+};
+/**
+ * Get postal codes sorted by code.
+ * @param ascending - Sort in ascending order if true (default: true)
+ * @returns Array of postal codes sorted by postal code
+ */
+export declare function getPostalCodesSorted(ascending?: boolean): PostalCode[];
+/**
+ * Check if a postal code exists.
+ * @param code - 4-digit postal code to check
+ * @returns True if postal code exists, false otherwise
+ */
+export declare function isValidPostalCode(code: string): boolean;
+/**
+ * Get postal codes by municipality name.
+ * Note: This function combines data from municipalities and postal codes.
+ * @param municipalityName - Municipality name to search for
+ * @param exactMatch - Whether to match exactly (default: false)
+ * @returns Array of postal codes for municipalities matching the name
+ */
+export declare function getPostalCodesByMunicipalityName(municipalityName: string, exactMatch?: boolean): PostalCode[];
+export type { Municipality, County, PostalCode, PopulationDensityStats, LanguageStatus, MunicipalitySearchOptions, MunicipalityFilterOptions, PostalCodeSearchOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.js

@@ -0,0 +1,397 @@
+import municipalitiesData from '../data/kommuner-2025.json';
+import countiesData from '../data/fylker-2025.json';
+import postalCodesData from '../data/postal-codes-2025.json';
+import packageJson from '../package.json';
+// Type-safe data imports
+const municipalities = municipalitiesData;
+const counties = countiesData;
+const postalCodes = postalCodesData;
+/**
+ * Get the library version following semantic versioning.
+ * @returns Version string (e.g., "1.0.0")
+ */
+export function getVersion() {
+    return packageJson.version;
+}
+/**
+ * Get all municipalities with metadata.
+ * @returns Array of all municipalities
+ */
+export function getMunicipalities() {
+    return municipalities;
+}
+/**
+ * Get a municipality by municipality ID.
+ * @param id - 4-digit municipality ID (e.g., "0301" for Oslo)
+ * @returns Municipality object or undefined if not found
+ * @throws {TypeError} If id is not a string
+ */
+export function getMunicipalityById(id) {
+    if (typeof id !== 'string') {
+        throw new TypeError('Municipality ID must be a string');
+    }
+    return municipalities.find(m => m.k_id === id);
+}
+/**
+ * Get municipalities by name (case-insensitive partial match by default).
+ * @param name - Municipality name or partial name to search for
+ * @param options - Search options
+ * @returns Array of matching municipalities
+ * @throws {TypeError} If name is not a string
+ */
+export function getMunicipalitiesByName(name, options = {}) {
+    if (typeof name !== 'string') {
+        throw new TypeError('Municipality name must be a string');
+    }
+    const { includeAllNames = true, caseSensitive = false, exactMatch = false } = options;
+    const searchTerm = caseSensitive ? name : name.toLowerCase();
+    return municipalities.filter(m => {
+        const namesToSearch = includeAllNames
+            ? [m.k_name, m.k_name_no]
+            : [m.k_name];
+        return namesToSearch.some(municipalityName => {
+            const compareString = caseSensitive
+                ? municipalityName
+                : municipalityName.toLowerCase();
+            return exactMatch
+                ? compareString === searchTerm
+                : compareString.includes(searchTerm);
+        });
+    });
+}
+/**
+ * Get all counties (fylker) with metadata.
+ * @returns Array of all counties
+ */
+export function getCounties() {
+    return counties;
+}
+/**
+ * Get a county by county ID.
+ * @param id - 2-digit county ID (e.g., "03" for Oslo)
+ * @returns County object or undefined if not found
+ * @throws {TypeError} If id is not a string
+ */
+export function getCountyById(id) {
+    if (typeof id !== 'string') {
+        throw new TypeError('County ID must be a string');
+    }
+    return counties.find(f => f.f_id === id);
+}
+/**
+ * Get county by name (case-insensitive partial match).
+ * @param name - County name or partial name to search for
+ * @param exactMatch - Whether to match exactly (default: false)
+ * @returns County object or undefined if not found
+ * @throws {TypeError} If name is not a string
+ */
+export function getCountyByName(name, exactMatch = false) {
+    if (typeof name !== 'string') {
+        throw new TypeError('County name must be a string');
+    }
+    const searchTerm = name.toLowerCase();
+    return counties.find(f => {
+        const countyName = f.f_name.toLowerCase();
+        return exactMatch ? countyName === searchTerm : countyName.includes(searchTerm);
+    });
+}
+/**
+ * Get all municipalities in a given county.
+ * @param countyId - 2-digit county ID (first two digits of municipality k_id)
+ * @returns Array of municipalities in the county
+ * @throws {TypeError} If countyId is not a string
+ */
+export function getMunicipalitiesByCounty(countyId) {
+    if (typeof countyId !== 'string') {
+        throw new TypeError('County ID must be a string');
+    }
+    return municipalities.filter(m => m.k_id.startsWith(countyId));
+}
+/**
+ * Get municipality by postal code.
+ * @param postalCode - Postal code to search for
+ * @returns Municipality object or undefined if not found
+ * @throws {TypeError} If postal code is not a valid number
+ */
+export function getMunicipalityByPostalCode(postalCode) {
+    const code = String(postalCode);
+    if (!code.match(/^\d{4}$/)) {
+        throw new TypeError('Postal code must be a valid 4-digit number');
+    }
+    return municipalities.find(m => m.k_postal_codes.some(pc => pc.postal_code === code));
+}
+/**
+ * Get all postal codes for a specific municipality.
+ * @param municipalityId - 4-digit municipality ID
+ * @returns Array of postal codes or undefined if municipality not found
+ */
+export function getPostalCodesByMunicipality(municipalityId) {
+    const municipality = getMunicipalityById(municipalityId);
+    return municipality ? municipality.k_postal_codes.map(pc => pc.postal_code) : undefined;
+}
+/**
+ * Get all postal codes from all municipalities.
+ * @param includeDetails - If true, returns objects with postal code and place name. If false, returns only postal codes (default: false)
+ * @returns Array of postal codes or postal code objects
+ */
+export function getAllPostalCodes(includeDetails = false) {
+    if (includeDetails) {
+        const allPostalCodes = [];
+        municipalities.forEach(municipality => {
+            municipality.k_postal_codes.forEach(pc => {
+                allPostalCodes.push({
+                    zip: pc.postal_code,
+                    place: pc.postal_place,
+                    municipalityId: municipality.k_id,
+                    municipalityName: municipality.k_name
+                });
+            });
+        });
+        return allPostalCodes.sort((a, b) => a.zip.localeCompare(b.zip));
+    }
+    else {
+        const allPostalCodes = new Set();
+        municipalities.forEach(municipality => {
+            municipality.k_postal_codes.forEach(pc => {
+                allPostalCodes.add(pc.postal_code);
+            });
+        });
+        return Array.from(allPostalCodes).sort();
+    }
+}
+/**
+ * Get municipalities sorted by population.
+ * @param ascending - Sort in ascending order if true (default: false for descending)
+ * @returns Array of municipalities sorted by population
+ */
+export function getMunicipalitiesByPopulation(ascending = false) {
+    const sorted = [...municipalities].sort((a, b) => ascending ? a.k_population - b.k_population : b.k_population - a.k_population);
+    return sorted;
+}
+/**
+ * Get municipalities sorted by area.
+ * @param ascending - Sort in ascending order if true (default: false for descending)
+ * @returns Array of municipalities sorted by area
+ */
+export function getMunicipalitiesByArea(ascending = false) {
+    const sorted = [...municipalities].sort((a, b) => ascending ? a.k_area - b.k_area : b.k_area - a.k_area);
+    return sorted;
+}
+/**
+ * Get municipalities by language status.
+ * @param language - Language status
+ * @returns Array of municipalities with the specified language status
+ * @throws {TypeError} If language is not a string
+ */
+export function getMunicipalitiesByLanguage(language) {
+    if (typeof language !== 'string') {
+        throw new TypeError('Language must be a string');
+    }
+    return municipalities.filter(m => m.k_language === language);
+}
+/**
+ * Get municipalities with advanced filtering options.
+ * @param options - Filter options
+ * @returns Array of municipalities matching the filter criteria
+ */
+export function getMunicipalitiesFiltered(options) {
+    return municipalities.filter(m => {
+        if (options.minPopulation !== undefined && m.k_population < options.minPopulation)
+            return false;
+        if (options.maxPopulation !== undefined && m.k_population > options.maxPopulation)
+            return false;
+        if (options.minArea !== undefined && m.k_area < options.minArea)
+            return false;
+        if (options.maxArea !== undefined && m.k_area > options.maxArea)
+            return false;
+        if (options.language !== undefined && m.k_language !== options.language)
+            return false;
+        if (options.countyId !== undefined && !m.k_id.startsWith(options.countyId))
+            return false;
+        return true;
+    });
+}
+/**
+ * Get total population of all municipalities.
+ * @returns Total population
+ */
+export function getTotalPopulation() {
+    return municipalities.reduce((total, m) => total + m.k_population, 0);
+}
+/**
+ * Get total area of all municipalities.
+ * @returns Total area in square kilometers
+ */
+export function getTotalArea() {
+    return municipalities.reduce((total, m) => total + m.k_area, 0);
+}
+/**
+ * Get population density statistics.
+ * @returns Object with min, max, and average population density
+ */
+export function getPopulationDensityStats() {
+    const densities = municipalities.map(m => m.k_population / m.k_area);
+    return {
+        min: Math.min(...densities),
+        max: Math.max(...densities),
+        average: densities.reduce((sum, d) => sum + d, 0) / densities.length
+    };
+}
+/**
+ * Get municipalities by population density range.
+ * @param minDensity - Minimum population density (people per km²)
+ * @param maxDensity - Maximum population density (people per km²)
+ * @returns Array of municipalities within the density range
+ */
+export function getMunicipalitiesByPopulationDensity(minDensity = 0, maxDensity = Infinity) {
+    return municipalities.filter(m => {
+        const density = m.k_population / m.k_area;
+        return density >= minDensity && density <= maxDensity;
+    });
+}
+/**
+ * Get the largest municipalities by population.
+ * @param count - Number of municipalities to return (default: 10)
+ * @returns Array of largest municipalities by population
+ */
+export function getLargestMunicipalities(count = 10) {
+    return getMunicipalitiesByPopulation(false).slice(0, count);
+}
+/**
+ * Get the smallest municipalities by population.
+ * @param count - Number of municipalities to return (default: 10)
+ * @returns Array of smallest municipalities by population
+ */
+export function getSmallestMunicipalities(count = 10) {
+    return getMunicipalitiesByPopulation(true).slice(0, count);
+}
+// ========================
+// POSTAL CODE FUNCTIONS
+// ========================
+/**
+ * Get all postal codes with metadata.
+ * @returns Array of all postal codes
+ */
+export function getPostalCodes() {
+    return postalCodes;
+}
+/**
+ * Get postal code information by postal code.
+ * @param code - 4-digit postal code (e.g., "0001")
+ * @returns PostalCode object or undefined if not found
+ * @throws {TypeError} If code is not a string
+ */
+export function getPostalCodeByCode(code) {
+    if (typeof code !== 'string') {
+        throw new TypeError('Postal code must be a string');
+    }
+    return postalCodes.find(pc => pc.k_postal_code === code);
+}
+/**
+ * Get postal codes by postal place (case-insensitive partial match by default).
+ * @param place - Postal place name or partial name to search for
+ * @param options - Search options
+ * @returns Array of matching postal codes
+ * @throws {TypeError} If place is not a string
+ */
+export function getPostalCodesByPlace(place, options = {}) {
+    if (typeof place !== 'string') {
+        throw new TypeError('Postal place must be a string');
+    }
+    const { caseSensitive = false, exactMatch = false } = options;
+    const searchTerm = caseSensitive ? place : place.toLowerCase();
+    return postalCodes.filter(pc => {
+        const placeName = caseSensitive
+            ? pc.k_postal_place
+            : pc.k_postal_place.toLowerCase();
+        return exactMatch
+            ? placeName === searchTerm
+            : placeName.includes(searchTerm);
+    });
+}
+/**
+ * Get postal codes by municipality ID.
+ * @param municipalityId - 4-digit municipality ID (e.g., "0301" for Oslo)
+ * @returns Array of postal codes for the municipality
+ * @throws {TypeError} If municipalityId is not a string
+ */
+export function getPostalCodesByMunicipalityId(municipalityId) {
+    if (typeof municipalityId !== 'string') {
+        throw new TypeError('Municipality ID must be a string');
+    }
+    return postalCodes.filter(pc => pc.k_id === municipalityId);
+}
+/**
+ * Get unique postal places.
+ * @returns Array of unique postal place names sorted alphabetically
+ */
+export function getUniquePostalPlaces() {
+    const uniquePlaces = new Set();
+    postalCodes.forEach(pc => uniquePlaces.add(pc.k_postal_place));
+    return Array.from(uniquePlaces).sort();
+}
+/**
+ * Get postal codes within a range.
+ * @param startCode - Starting postal code (inclusive)
+ * @param endCode - Ending postal code (inclusive)
+ * @returns Array of postal codes within the range
+ * @throws {TypeError} If start or end codes are not strings
+ */
+export function getPostalCodesInRange(startCode, endCode) {
+    if (typeof startCode !== 'string' || typeof endCode !== 'string') {
+        throw new TypeError('Start and end codes must be strings');
+    }
+    return postalCodes.filter(pc => pc.k_postal_code >= startCode && pc.k_postal_code <= endCode);
+}
+/**
+ * Get postal codes statistics.
+ * @returns Object with total count and unique places count
+ */
+export function getPostalCodesStats() {
+    const uniquePlaces = new Set();
+    const uniqueMunicipalities = new Set();
+    postalCodes.forEach(pc => {
+        uniquePlaces.add(pc.k_postal_place);
+        uniqueMunicipalities.add(pc.k_id);
+    });
+    return {
+        totalPostalCodes: postalCodes.length,
+        uniquePlaces: uniquePlaces.size,
+        uniqueMunicipalities: uniqueMunicipalities.size
+    };
+}
+/**
+ * Get postal codes sorted by code.
+ * @param ascending - Sort in ascending order if true (default: true)
+ * @returns Array of postal codes sorted by postal code
+ */
+export function getPostalCodesSorted(ascending = true) {
+    const sorted = [...postalCodes].sort((a, b) => ascending
+        ? a.k_postal_code.localeCompare(b.k_postal_code)
+        : b.k_postal_code.localeCompare(a.k_postal_code));
+    return sorted;
+}
+/**
+ * Check if a postal code exists.
+ * @param code - 4-digit postal code to check
+ * @returns True if postal code exists, false otherwise
+ */
+export function isValidPostalCode(code) {
+    if (typeof code !== 'string') {
+        return false;
+    }
+    return postalCodes.some(pc => pc.k_postal_code === code);
+}
+/**
+ * Get postal codes by municipality name.
+ * Note: This function combines data from municipalities and postal codes.
+ * @param municipalityName - Municipality name to search for
+ * @param exactMatch - Whether to match exactly (default: false)
+ * @returns Array of postal codes for municipalities matching the name
+ */
+export function getPostalCodesByMunicipalityName(municipalityName, exactMatch = false) {
+    const matchingMunicipalities = getMunicipalitiesByName(municipalityName, { exactMatch });
+    const municipalityIds = matchingMunicipalities.map(m => m.k_id);
+    return postalCodes.filter(pc => municipalityIds.includes(pc.k_id));
+}
+//# sourceMappingURL=index.js.map