nostr-geotags
Version:
Give an object of geodata, returns standardized nostr geotags
162 lines (161 loc) • 6.14 kB
TypeScript
export interface InputData {
geohash?: string;
lat?: number;
lon?: number;
cityName?: string;
countryName?: string;
regionName?: string;
countryCode?: string;
planetName?: string;
[key: string]: any;
}
export interface Options {
sort?: boolean;
isoAsNamespace?: boolean;
unM49AsNamespace?: boolean;
ddMaxResolution?: number;
iso31661?: boolean;
iso31662?: boolean;
iso31663?: boolean;
geohash?: boolean;
gps?: boolean;
city?: boolean;
cityName?: boolean | null;
country?: boolean;
countryName?: boolean | null;
countryCode?: boolean | null;
region?: boolean;
regionName?: boolean | null;
regionCode?: boolean | null;
planet?: boolean;
planetName?: boolean | null;
}
export type ISO31663FieldType = 'alpha2' | 'alpha3' | 'numeric' | 'name';
/**
* Represents a nostr event `g` (geo) tag with a length of 2
*
* @type {Array} GeoTag
*
* A GeoTag is an array with either three or four elements, structured as follows:
* - First element (string): See NIP-52, always 'l'
* - Second element (string): The Geohash
*
*/
export type Geohash = [string, string] | [string, string, string];
/**
* Represents a nostr event `L` (label) tag with a length of 2
*
* @type {Array} LabelNamespace
*
* A GeoTag is an array with either three or four elements, structured as follows:
* - First element (string): See NIP-32, always 'L'
* - Second element (string): The Label's Namespace
*
*/
export type LabelNamespace = [string, string];
/**
* Represents a nostr event `l` (geo) tag with a length of 2
*
* @type {Array} Label
*
* A GeoTag is an array with either three or four elements, structured as follows:
* - First element (string): See NIP-32, always 'l'
* - Second element (string): The value
* - Second element (string): The namespace
*
*/
export type Label = [string, string, string];
/**
* Represents a union of LabelNamespace and Label
*
* @type {Array} LabelTag
*
* A GeoTag is either a @type Label or @type LabelNamespace
*
*/
export type LabelTag = LabelNamespace | Label;
/**
* Represents a union of all possible types returned by generateTags()
*
* @type {Array} Label
*
* A GeoTag is an array with either three or four elements, structured as follows:
* - First element (string): See NIP-32, always 'l'
* - Second element (string): The value
* - Second element (string): The namespace
*
*/
export type GeoTags = Geohash | LabelTag;
export declare const iso31661Namespace: (opts: Options) => string;
export declare const iso31662Namespace: (opts: Options) => string;
export declare const iso31663Namespace: (opts: Options) => string;
export declare const calculateResolution: (input: number, max: number | undefined) => number;
/**
* sanitize
* Filters and sanitizes an array of GeoTags.
*
* This function processes an array of GeoTags. It first filters the array to include only those tags
* where the first character is 'l' or 'L'. After this initial filtering, it calls the 'filterNonStringTags'
* function to typecheck array contents. The resulting array of GeoTags is then returned.
*
* @param {GeoTags[]} tags - An array of GeoTags to be sanitized
* @returns {GeoTags[]} - The sanitized array of GeoTags
*/
export declare const sanitize: (tags: GeoTags[]) => GeoTags[];
/**
* Generates a country key based on the given type.
*
* @param {string} type - The type of the tag, typically an ISO-3166 field type.
* @returns {string} The generated tag key.
*
* This function determines the key to be used in a tag array based on the type of data.
* For the type 'name', it returns 'countryName', indicating the tag represents a country's name.
* For any other type, it returns 'countryCode', typically representing an ISO-3166 country code.
*/
export declare const generateCountryTagKey: (type: string) => string;
/**
* Filters out tags of a specific type from an array of tags.
*
* @param {GeoTags[]} tags - The array of geotags to be filtered.
* @param {string} type - The type of tag to be filtered out.
* @returns {GeoTags[]} A new array with the specified type of tags removed.
*
* This utility function filters out tags from an array based on the provided type.
* It iterates over the array and excludes any tags where the third element (the type identifier)
* matches the specified type. This is useful for removing specific types of geotags from
* a list of various tags.
*/
export declare const filterOutType: (tags: GeoTags[], type: string) => GeoTags[];
/**
* Sorts an array of tags by the key (second item in each tag array).
*
* @param {GeoTags[]} tags - The array of tags to be sorted.
* @returns {GeoTags[]} The sorted array of tags.
*
* This function sorts the tags based on the tag key (third element),
* which allows for easier processing and organization of tags.
*/
export declare const sortTagsByKey: (tags: GeoTags[]) => GeoTags[];
/**
* Filters out tags that contain non-string items.
* @param {GeoTags[]} tags - An array of tags, where each tag is an array.
* @returns {GeoTags[]} Filtered array of tags.
*/
export declare function filterNonStringTags(tags: GeoTags[]): GeoTags[];
/**
* Produces an array of nostr `g` (geo) tag arrays based on input geo data and options.
*
* @param {InputData | null} input - The input data for generating tags.
* @param {Options} [opts] - Optional parameters to customize tag generation.
* @throws {Error} Throws an error if the input data is null or not an object.
* @returns {GeoTags[]} An array of generated tags.
*
* This function is the primary entry point for generating an array of nostr `g` (geo) tag arrays.
* It validates the input data, applies default options if not provided, and invokes the tag generation process.
* The options can control the inclusion of various geotags like GPS, ISO-3166 country codes,
* city names, etc. The function can also deduplicate and sort the tags.
*
* If the input data is null, an error is thrown. The input must be an object.
*/
declare const _default: (input: InputData | null, opts?: Options) => GeoTags[];
export default _default;