jsdomain-parser 1.0.8 → 1.0.9

package/index.js

@@ -1,4 +1,11 @@
+/**
+ * @typedef {import('./index').ParseResult} ParseResult
+ * @typedef {import('./index').ParseOptions} ParseOptions
+ * @typedef {import('./index').TldInfo} TldInfo
+ * @typedef {import('./index').ParsedUrl} ParsedUrl
+ */
+
 const parseTld = require("./src/parseTld.js");
 const parse = require("./src/parse.js");
 
-module.exports = { parse, parseTld };
+module.exports = { parse, parseTld };

package/package.json

@@ -1,34 +1,43 @@
-{
-  "name": "jsdomain-parser",
-  "version": "1.0.8",
-  "description": "Parse URLs to extract TLDs, domain, protocols and more",
-  "main": "index.js",
-  "scripts": {
-    "build": "rollup -c",
-    "test": "jest"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/ToolsOverflow/jsdomain-parser"
-  },
-  "keywords": [
-    "url",
-    "parser",
-    "domain",
-    "parser",
-    "tld",
-    "extractor",
-    "extract",
-    "tld"
-  ],
-  "author": "ToolsOverflow",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-json": "^6.1.0",
-    "jest": "^29.7.0",
-    "rollup": "^2.79.2",
-    "rollup-plugin-commonjs": "^10.1.0",
-    "rollup-plugin-node-resolve": "^5.2.0",
-    "rollup-plugin-terser": "^7.0.2"
-  }
-}
+{
+  "name": "jsdomain-parser",
+  "version": "1.0.9",
+  "description": "Parse URLs to extract TLDs, domain, protocols and more",
+  "main": "index.js",
+  "types": "./types/index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ToolsOverflow/jsdomain-parser"
+  },
+  "keywords": [
+    "url",
+    "parser",
+    "domain",
+    "parser",
+    "tld",
+    "extractor",
+    "extract",
+    "tld"
+  ],
+  "author": "ToolsOverflow",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-json": "^6.1.0",
+    "jest": "^29.7.0",
+    "rollup": "^2.79.2",
+    "rollup-plugin-commonjs": "^10.1.0",
+    "rollup-plugin-node-resolve": "^5.2.0",
+    "rollup-plugin-terser": "^7.0.2"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Parsed TLD information
+ */
+export interface TldInfo {
+    /** The full public suffix / effective TLD (e.g. "co.uk", "com") */
+    name: string;
+    /** Number of labels/parts in the TLD (e.g. 2 for co.uk) */
+    length: number;
+    /** Individual labels of the TLD */
+    parts: string[];
+}
+
+/**
+ * Parsed URL components (similar to WHATWG URL but with query as object)
+ */
+export interface ParsedUrl {
+    /** Second-level domain + TLD (e.g. "example.com") */
+    domain: string;
+    /** Full origin including protocol (e.g. "https://www.example.com") */
+    origin: string;
+    /** Protocol with colon (e.g. "https:") */
+    protocol: string;
+    /** Host including subdomains and port if present (e.g. "www.example.com:8080") */
+    host: string;
+    /** Hostname without port (e.g. "www.example.com") */
+    hostname: string;
+    /** Port number as string (empty string if none) */
+    port: string;
+    /** Path including leading slash (e.g. "/blog/post") */
+    pathname: string;
+    /** Query string including ? (empty string if none) */
+    search: string;
+    /** Fragment including # (empty string if none) */
+    hash: string;
+    /** Parsed query parameters as key-value object */
+    query: Record<string, string>;
+}
+
+/**
+ * Result returned by parse()
+ */
+export interface ParseResult {
+    /** Information about the detected top-level domain / public suffix */
+    tld: TldInfo;
+    /** Parsed components of the URL */
+    url: ParsedUrl;
+}
+
+/**
+ * Parsing options
+ */
+export interface ParseOptions {
+    /**
+     * Whether to consider private (non-ICANN) TLDs
+     * @default true
+     */
+    allowPrivate?: boolean;
+
+    /**
+     * Whether to allow parsing when no known TLD is found
+     * @default false
+     */
+    allowUnknown?: boolean;
+
+    /**
+     * Additional custom TLDs to recognize (each item can be "tld" or "sub.tld")
+     */
+    extendedTlds?: string[];
+}
+
+/**
+ * Parses a URL string and extracts domain/TLD information using the public suffix list.
+ *
+ * @param url - The URL or hostname to parse (string)
+ * @param options - Optional configuration
+ * @throws Error when URL is invalid or TLD cannot be determined (unless allowUnknown=true)
+ */
+export function parse(url: string, options?: ParseOptions): ParseResult;