netscape-bookmark-parser 1.1.4 → 1.2.0

package/README.md

@@ -4,7 +4,8 @@ A TypeScript/JavaScript library for parsing browser bookmark files (HTML format)
 
 > **Note:**  
 > This README is an AI-generated document. Details are mostly accurate but might include inaccurate description.
-> 日本語ドキュメント: [`./README-ja.md`](./README-ja.md)
+
+日本語ドキュメント: [`./README-ja.md`](./README-ja.md)
 
 ## Features
 
@@ -30,13 +31,10 @@ import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser";
 ### Deno
 
 ```typescript
-import {
-	BookmarksParser,
-	BookmarksTree,
-} from "jsr:@grakeice/netscape-bookmark-parser";
+import { BookmarksParser, BookmarksTree } from "jsr:@grakeice/netscape-bookmark-parser";
 ```
 
-> **Note:** The JSR version only includes the Node.js/Deno runtime. For browser support, please use the npm package.
+> **Note:** The JSR package provides the Node.js/Deno entry. For browser support, use the npm package's dependency-free `./web` entry.
 
 ### Browser
 
@@ -50,16 +48,16 @@ import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
 
 // Example: Parse uploaded bookmark file
 function handleFileUpload(event: Event) {
-	const file = (event.target as HTMLInputElement).files?.[0];
-	if (file) {
-		const reader = new FileReader();
-		reader.onload = (e) => {
-			const htmlContent = e.target?.result as string;
-			const bookmarksTree = BookmarksParser.parse(htmlContent);
-			console.log(bookmarksTree.toJSON());
-		};
-		reader.readAsText(file);
-	}
+    const file = (event.target as HTMLInputElement).files?.[0];
+    if (file) {
+        const reader = new FileReader();
+        reader.onload = (e) => {
+            const htmlContent = e.target?.result as string;
+            const bookmarksTree = BookmarksParser.parse(htmlContent);
+            console.log(bookmarksTree.toJSON());
+        };
+        reader.readAsText(file);
+    }
 }
 ```
 
@@ -67,15 +65,15 @@ function handleFileUpload(event: Event) {
 
 ```html
 <script type="importmap">
-	{
-		"imports": {
-			"netscape-bookmark-parser/web": "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/esm/mod_web.js"
-		}
-	}
+    {
+        "imports": {
+            "netscape-bookmark-parser/web": "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/dist/web.js"
+        }
+    }
 </script>
 <script type="module">
-	import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
-	const tree = BookmarksParser.parse(htmlContent);
+    import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
+    const tree = BookmarksParser.parse(htmlContent);
 </script>
 ```
 
@@ -83,14 +81,14 @@ function handleFileUpload(event: Event) {
 
 ```html
 <script type="module">
-	import {
-		BookmarksParser,
-		BookmarksTree,
-	} from "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/esm/mod_web.js";
+    import {
+        BookmarksParser,
+        BookmarksTree,
+    } from "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/dist/web.js";
 </script>
 ```
 
-> **Browser Support:** Browser compatibility is only available through the npm package. The JSR package does not include the web-optimized version due to platform-specific dependencies.
+> **Browser Support:** The web-optimized version is available from the npm `./web` export. It uses native browser APIs and has no DOM library dependency.
 
 > **Note:** The web-optimized version uses native browser APIs (DOMParser, etc.) and does not include Node.js polyfills, making it lighter and faster in browser environments.
 
@@ -199,12 +197,12 @@ console.log(devFolder.get("GitHub")); // "https://github.com"
 
 ### Web-Optimized Version
 
-> **Important:** Browser support is only available via npm installation. JSR version does not include browser-compatible builds.
+> **Important:** Browser support is available from the npm `./web` export.
 
 The library provides a browser-optimized version that eliminates Node.js dependencies and uses native browser APIs:
 
 ```typescript
-// Import browser-optimized version (npm only)
+// Import the browser-optimized version
 import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
 ```
 
@@ -218,49 +216,49 @@ import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
 
 - [`static parse(htmlString: string): BookmarksTree`](#static-parsehtmlstring-string-bookmarkstree)
 
-  - Parses a Netscape Bookmark format HTML string and returns a `BookmarksTree`.
-  - Alias for [`parseFromHTMLString`](#static-parsefromhtmlstringhtmlstring-string-bookmarkstree).
+    - Parses a Netscape Bookmark format HTML string and returns a `BookmarksTree`.
+    - Alias for [`parseFromHTMLString`](#static-parsefromhtmlstringhtmlstring-string-bookmarkstree).
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const html = `<!DOCTYPE NETSCAPE-Bookmark-file-1>\n<HTML><BODY><DL><p>\n  <DT><A HREF=\"https://example.com\">Example</A>\n</DL><p></BODY></HTML>`;
-  const tree = BookmarksParser.parse(html);
-  console.log(tree.toJSON());
-  ```
+    ```typescript
+    const html = `<!DOCTYPE NETSCAPE-Bookmark-file-1>\n<HTML><BODY><DL><p>\n  <DT><A HREF=\"https://example.com\">Example</A>\n</DL><p></BODY></HTML>`;
+    const tree = BookmarksParser.parse(html);
+    console.log(tree.toJSON());
+    ```
 
 - [`static parseFromHTMLString(htmlString: string): BookmarksTree`](#static-parsefromhtmlstringhtmlstring-string-bookmarkstree)
 
-  - Parses a Netscape Bookmark format HTML string and returns a `BookmarksTree`.
+    - Parses a Netscape Bookmark format HTML string and returns a `BookmarksTree`.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const html = `<!DOCTYPE NETSCAPE-Bookmark-file-1>...`;
-  const tree = BookmarksParser.parseFromHTMLString(html);
-  ```
+    ```typescript
+    const html = `<!DOCTYPE NETSCAPE-Bookmark-file-1>...`;
+    const tree = BookmarksParser.parseFromHTMLString(html);
+    ```
 
 - [`static parseFromDOM(dom: HTMLDocument): BookmarksTree`](#static-parsefromdomdom-htmldocument-bookmarkstree)
 
-  - Converts an existing `HTMLDocument` to a `BookmarksTree`.
+    - Converts an existing `HTMLDocument` to a `BookmarksTree`.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const dom = new DOMParser().parseFromString(html, "text/html");
-  const tree = BookmarksParser.parseFromDOM(dom);
-  ```
+    ```typescript
+    const dom = new DOMParser().parseFromString(html, "text/html");
+    const tree = BookmarksParser.parseFromDOM(dom);
+    ```
 
 - [`static parseFromJSON(jsonString: string): BookmarksTree`](#static-parsefromjsonjsonstring-string-bookmarkstree)
 
-  - Parses a JSON string and returns a `BookmarksTree`.
+    - Parses a JSON string and returns a `BookmarksTree`.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const json = '{"Google": "https://google.com"}';
-  const tree = BookmarksParser.parseFromJSON(json);
-  ```
+    ```typescript
+    const json = '{"Google": "https://google.com"}';
+    const tree = BookmarksParser.parseFromJSON(json);
+    ```
 
 ---
 
@@ -272,73 +270,73 @@ import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
 
 - [`new BookmarksTree()`](#constructor)
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const tree = new BookmarksTree();
-  tree.set("Google", "https://google.com");
-  ```
+    ```typescript
+    const tree = new BookmarksTree();
+    tree.set("Google", "https://google.com");
+    ```
 
 #### Instance Methods
 
 - [`toJSON(): Record<string, unknown>`](#tojson-recordstring-unknown)
 
-  - Converts the tree to a JSON object representation.
+    - Converts the tree to a JSON object representation.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const json = tree.toJSON();
-  console.log(json);
-  ```
+    ```typescript
+    const json = tree.toJSON();
+    console.log(json);
+    ```
 
 - [`toDOM(): HTMLDocument`](#todom-htmldocument)
 
-  - Converts the tree to a Netscape Bookmark format HTML document.
+    - Converts the tree to a Netscape Bookmark format HTML document.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const dom = tree.toDOM();
-  ```
+    ```typescript
+    const dom = tree.toDOM();
+    ```
 
 - [`get HTMLString(): string`](#get-htmlstring-string)
 
-  - Gets the complete HTML string in Netscape Bookmark format.
+    - Gets the complete HTML string in Netscape Bookmark format.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const html = tree.HTMLString;
-  console.log(html);
-  ```
+    ```typescript
+    const html = tree.HTMLString;
+    console.log(html);
+    ```
 
 - [`get HTMLText(): string`](#get-htmltext-string)
-  - Alias for `HTMLString` (deprecated).
+    - Alias for `HTMLString` (deprecated).
 
 #### Static Methods
 
 - [`static fromJSON(json: Record<string, unknown>): BookmarksTree`](#static-fromjsonjson-recordstring-unknown-bookmarkstree)
 
-  - Creates a tree from a JSON object.
+    - Creates a tree from a JSON object.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const json = { Google: "https://google.com" };
-  const tree = BookmarksTree.fromJSON(json);
-  ```
+    ```typescript
+    const json = { Google: "https://google.com" };
+    const tree = BookmarksTree.fromJSON(json);
+    ```
 
 - [`static fromDOM(dom: HTMLDocument): BookmarksTree`](#static-fromdomdom-htmldocument-bookmarkstree)
 
-  - Creates a tree from an HTML document.
+    - Creates a tree from an HTML document.
 
-  **Example:**
+    **Example:**
 
-  ```typescript
-  const dom = new DOMParser().parseFromString(html, "text/html");
-  const tree = BookmarksTree.fromDOM(dom);
-  ```
+    ```typescript
+    const dom = new DOMParser().parseFromString(html, "text/html");
+    const tree = BookmarksTree.fromDOM(dom);
+    ```
 
 ## Project Structure
 
@@ -353,16 +351,28 @@ src/
     ├── BookmarksParser.test.ts # Parser tests
     └── index.ts             # Export definitions
 scripts/
-└── build_npm.ts             # NPM build script
+└── sync-jsr-version.mjs     # Keep JSR version in sync with package.json
 .github/
 └── workflows/
-    └── release.yml          # CI/CD pipeline
-npm/                         # Node.js build artifacts
-├── esm/                     # ES modules
-├── package.json
-└── README.md
+    ├── changesets.yml        # Changesets version pull requests
+    ├── ci.yml                # Test, typecheck, and build checks
+    └── release.yml           # NPM/JSR publishing and GitHub releases
+dist/                        # Generated package files (not committed)
 ```
 
+## Development and Release
+
+Install dependencies with pnpm and run the local checks:
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+Create a release note with `pnpm changeset`. Changesets opens a version pull request on `main`; merging it updates `package.json` and synchronizes the JSR version in `jsr.json`. A subsequent `main` push publishes the package to NPM and JSR and creates the matching `v<version>` Git tag and GitHub release.
+
 ## Supported Formats
 
 ### Input Formats
@@ -474,7 +484,7 @@ MIT License - See [LICENSE](LICENSE) file for details.
 ### v1.1.0
 
 - 🌐 **Browser Support**: Added web-optimized version for browser environments
-- 📦 **Dual Entry Points**: Separate builds for Node.js/Deno (`./mod.ts`) and browsers (`./mod_web.ts`)
+- 📦 **Dual Entry Points**: Separate builds for Node.js/Deno (`src/index.ts`) and browsers (`src/web.ts`)
 - ⚡ **Native DOM APIs**: Browser version uses native DOMParser and DOM APIs for better performance
 - 🔧 **Build Optimization**: Enhanced build process with polyfill removal for browser compatibility
 - 📚 **Updated Documentation**: Added browser usage examples and API reference

package/dist/index.d.ts

@@ -0,0 +1,240 @@
+import { HTMLDocument } from "@b-fuze/deno-dom";
+
+//#region src/BookmarksTree/BookmarksTree.d.ts
+
+/**
+ * A class representing a bookmark tree in Netscape Bookmark format
+ *
+ * This class extends Map and manages folders (BookmarksTree) and bookmarks (URL strings)
+ * in a hierarchical structure.
+ *
+ * @example
+ * ```typescript
+ * const tree = new BookmarksTree();
+ * tree.set("Google", "https://google.com");
+ *
+ * const folder = new BookmarksTree();
+ * folder.set("GitHub", "https://github.com");
+ * tree.set("Development", folder);
+ * ```
+ */
+declare class BookmarksTree extends Map<string, string | BookmarksTree> {
+  /**
+   * Creates a new BookmarksTree instance
+   */
+  constructor();
+  /**
+   * Converts the BookmarksTree to a JSON object
+   *
+   * Folders are recursively converted to objects, and bookmarks are preserved as strings.
+   *
+   * @returns JSON object representation of the bookmark data
+   *
+   * @example
+   * ```typescript
+   * const tree = new BookmarksTree();
+   * tree.set("Google", "https://google.com");
+   * const json = tree.toJSON();
+   * // { "Google": "https://google.com" }
+   * ```
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Creates a BookmarksTree from a JSON object
+   *
+   * String properties are treated as bookmarks, and object properties are
+   * recursively processed as folders.
+   *
+   * @param json The source JSON object to convert
+   * @returns A new BookmarksTree instance
+   *
+   * @example
+   * ```typescript
+   * const json = { "Google": "https://google.com", "Development": { "GitHub": "https://github.com" } };
+   * const tree = BookmarksTree.fromJSON(json);
+   * ```
+   */
+  static fromJSON(json: Record<string, unknown>): BookmarksTree;
+  /**
+   * Creates a BookmarksTree from an HTML document (Netscape Bookmark format)
+   *
+   * Parses Netscape Bookmark format HTML and generates a BookmarksTree that preserves
+   * the hierarchical structure. H3 elements within DT elements are treated as folders,
+   * and A elements are treated as bookmarks.
+   *
+   * @param dom The HTML document to parse
+   * @returns A new BookmarksTree instance
+   *
+   * @example
+   * ```typescript
+   * const parser = new DOMParser();
+   * const dom = parser.parseFromString(bookmarkHtml, "text/html");
+   * const tree = BookmarksTree.fromDOM(dom);
+   * ```
+   */
+  static fromDOM(dom: HTMLDocument): BookmarksTree;
+  /**
+   * Converts the BookmarksTree to an HTML document
+   *
+   * Generates an HTML document in Netscape Bookmark format.
+   *
+   * @returns HTML document in Netscape Bookmark format
+   *
+   * @example
+   * ```typescript
+   * const tree = new BookmarksTree();
+   * tree.set("Google", "https://google.com");
+   * const dom = tree.toDOM();
+   * ```
+   */
+  toDOM(): HTMLDocument;
+  /**
+   * Gets the BookmarksTree as an HTML string in Netscape Bookmark format
+   *
+   * Generates a complete HTML document string including DOCTYPE, metadata, and body
+   * in Netscape Bookmark format.
+   *
+   * @returns HTML string in Netscape Bookmark format
+   *
+   * @example
+   * ```typescript
+   * const tree = new BookmarksTree();
+   * tree.set("Google", "https://google.com");
+   * const html = tree.HTMLString;
+   * console.log(html); // <!DOCTYPE NETSCAPE-Bookmark-file-1>...
+   * ```
+   */
+  get HTMLString(): string;
+  /**
+   * @deprecated Use {@link HTMLString} instead.
+   *
+   * Gets the BookmarksTree as an HTML string in Netscape Bookmark format.
+   */
+  get HTMLText(): string;
+}
+//#endregion
+//#region src/BookmarksParser/BookmarksParser.d.ts
+/**
+ * A parser for Netscape Bookmark format files
+ *
+ * This class provides static methods to parse Netscape Bookmark format HTML strings
+ * and convert them into BookmarksTree instances for easier manipulation.
+ *
+ * @example
+ * ```typescript
+ * const bookmarkHtml = `<!DOCTYPE NETSCAPE-Bookmark-file-1>
+ * <HTML>
+ * <BODY>
+ * <DL><p>
+ *     <DT><A HREF="https://google.com">Google</A>
+ *     <DT><H3>Development</H3>
+ *     <DL><p>
+ *         <DT><A HREF="https://github.com">GitHub</A>
+ *     </DL><p>
+ * </DL>
+ * </BODY>
+ * </HTML>`;
+ *
+ * const tree = BookmarksParser.parse(bookmarkHtml);
+ * ```
+ */
+declare class BookmarksParser {
+  /**
+   * Alias for the {@link parseFromHTMLString} method.
+   *
+   * @param htmlString HTML string in Netscape Bookmark format
+   * @returns The parsed BookmarksTree
+   *
+   * @example
+   * ```typescript
+   * const bookmarkHtml = `<!DOCTYPE NETSCAPE-Bookmark-file-1>
+   * <HTML>
+   * <BODY>
+   * <DL><p>
+   *     <DT><A HREF="https://google.com">Google</A>
+   *     <DT><H3>Development</H3>
+   *     <DL><p>
+   *         <DT><A HREF="https://github.com">GitHub</A>
+   *     </DL><p>
+   * </DL>
+   * </BODY>
+   * </HTML>`;
+   *
+   * const tree = BookmarksParser.parse(bookmarkHtml);
+   * ```
+   */
+  static parse(htmlString: string): BookmarksTree;
+  /**
+   * Parses a Netscape Bookmark format HTML string and returns a BookmarksTree.
+   *
+   * @param htmlString HTML string in Netscape Bookmark format
+   * @returns The parsed BookmarksTree
+   *
+   * @example
+   * ```typescript
+   * const bookmarkHtml = `<!DOCTYPE NETSCAPE-Bookmark-file-1>
+   * <HTML>
+   * <BODY>
+   * <DL><p>
+   *     <DT><A HREF="https://google.com">Google</A>
+   *     <DT><H3>Development</H3>
+   *     <DL><p>
+   *         <DT><A HREF="https://github.com">GitHub</A>
+   *     </DL><p>
+   * </DL>
+   * </BODY>
+   * </HTML>`;
+   *
+   * const tree = BookmarksParser.parseFromHTMLString(bookmarkHtml);
+   * ```
+   */
+  static parseFromHTMLString(htmlString: string): BookmarksTree;
+  /**
+   * Creates a BookmarksTree from an existing HTMLDocument.
+   *
+   * This is an alias for {@link BookmarksTree.fromDOM}.
+   *
+   * Use this when you already have a parsed HTMLDocument and want to convert it to a BookmarksTree.
+   *
+   * @param dom An HTMLDocument instance
+   * @returns The parsed BookmarksTree
+   *
+   * @example
+   * ```typescript
+   * const dom = new DOMParser().parseFromString(bookmarkHtml, "text/html");
+   * const tree = BookmarksParser.parseFromDOM(dom);
+   * ```
+   */
+  static parseFromDOM(dom: HTMLDocument): BookmarksTree;
+  /**
+   * Parses a JSON string and returns a BookmarksTree.
+   *
+   * @param jsonString JSON string representing the bookmark structure
+   * @returns The parsed BookmarksTree
+   *
+   * @example
+   * ```typescript
+   * const json = '{"Google":"https://google.com","Development":{"GitHub":"https://github.com"}}';
+   * const tree = BookmarksParser.parseFromJSONString(json);
+   * ```
+   */
+  static parseFromJSONString(jsonString: string): BookmarksTree;
+  /**
+   * Parses a JSON object and returns a BookmarksTree.
+   *
+   * This is an alias for {@link BookmarksTree.fromJSON}.
+   *
+   * @param jsonObj JSON object representing the bookmark structure
+   * @returns The parsed BookmarksTree
+   *
+   * @example
+   * ```typescript
+   * const obj = { "Google": "https://google.com", "Development": { "GitHub": "https://github.com" } };
+   * const tree = BookmarksParser.parseFromJSON(obj);
+   * ```
+   */
+  static parseFromJSON(jsonObj: Record<string, unknown>): BookmarksTree;
+}
+//#endregion
+export { BookmarksParser, BookmarksTree };
+//# sourceMappingURL=index.d.ts.map