npm - netscape-bookmark-parser - Versions diffs - 1.1.2 → 1.1.4 - Mend

netscape-bookmark-parser 1.1.2 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README-ja.md +202 -369
package/README.md +122 -287
package/esm/src/BookmarksParser/BookmarksParser.d.ts +120 -1
package/esm/src/BookmarksParser/BookmarksParser.d.ts.map +1 -1
package/esm/src/BookmarksParser/BookmarksParser.js +129 -2
package/esm/src/BookmarksTree/BookmarksTree.d.ts +102 -0
package/esm/src/BookmarksTree/BookmarksTree.d.ts.map +1 -1
package/esm/src/BookmarksTree/BookmarksTree.js +106 -2
package/esm/src/web/BookmarksParser/BookmarksParser.d.ts +120 -1
package/esm/src/web/BookmarksParser/BookmarksParser.d.ts.map +1 -1
package/esm/src/web/BookmarksParser/BookmarksParser.js +129 -2
package/esm/src/web/BookmarksTree/BookmarksTree.d.ts +102 -0
package/esm/src/web/BookmarksTree/BookmarksTree.d.ts.map +1 -1
package/esm/src/web/BookmarksTree/BookmarksTree.js +106 -2
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,11 +1,10 @@
 # Netscape Bookmark Parser
-> **Note:**
-> This README is an AI-generated document. Details are mostly accurate but might include inaccurate description.
 A TypeScript/JavaScript library for parsing browser bookmark files (HTML format) and manipulating them as structured data. Compatible with both Deno and Node.js runtimes.
-日本語ドキュメント: [`./README-ja.md`](./README-ja.md)
+> **Note:**
+> This README is an AI-generated document. Details are mostly accurate but might include inaccurate description.
+> 日本語ドキュメント: [`./README-ja.md`](./README-ja.md)
 ## Features
@@ -24,6 +23,10 @@ A TypeScript/JavaScript library for parsing browser bookmark files (HTML format)
 npm install netscape-bookmark-parser
 ```
+```typescript
+import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser";
+```
 ### Deno
 ```typescript
@@ -33,7 +36,7 @@ import {
 } from "jsr:@grakeice/netscape-bookmark-parser";
 ```
-> **Note:** The JSR version only includes the Node.js/Deno runtime version. For browser support, please use the npm package.
+> **Note:** The JSR version only includes the Node.js/Deno runtime. For browser support, please use the npm package.
 ### Browser
@@ -60,47 +63,30 @@ function handleFileUpload(event: Event) {
 }
 ```
-#### Option 2: Direct ES Module Import
-```html
-<script type="module">
-	import {
-		BookmarksParser,
-		BookmarksTree,
-	} from "./node_modules/netscape-bookmark-parser/esm/mod_web.js";
-	// Your bookmark processing code here...
-</script>
-```
-#### Option 3: CDN with Import Maps
+#### Option 2: CDN with Import Maps
 ```html
 <script type="importmap">
 	{
 		"imports": {
-			"netscape-bookmark-parser/web": "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.2/esm/mod_web.js"
+			"netscape-bookmark-parser/web": "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/esm/mod_web.js"
 		}
 	}
 </script>
 <script type="module">
 	import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
-	// Works the same as local imports
 	const tree = BookmarksParser.parse(htmlContent);
 </script>
 ```
-#### Option 4: Direct CDN Import
+#### Option 3: Direct CDN Import
 ```html
 <script type="module">
 	import {
 		BookmarksParser,
 		BookmarksTree,
-	} from "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.2/esm/mod_web.js";
-	// Direct CDN import without import maps
+	} from "https://cdn.jsdelivr.net/npm/netscape-bookmark-parser@1.1.4/esm/mod_web.js";
 </script>
 ```
@@ -222,110 +208,137 @@ The library provides a browser-optimized version that eliminates Node.js depende
 import { BookmarksParser, BookmarksTree } from "netscape-bookmark-parser/web";
 ```
+> **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.
 ### BookmarksParser Class
-The [`BookmarksParser`](src/BookmarksParser/BookmarksParser.ts) class provides static methods for parsing HTML bookmark files.
+`BookmarksParser` provides static methods to parse Netscape Bookmark format HTML or JSON and convert them into `BookmarksTree` instances.
-#### `BookmarksParser.parse(htmlContent: string): BookmarksTree`
+#### Static Methods
-Parses HTML bookmark file content and returns a [`BookmarksTree`](src/BookmarksTree/BookmarksTree.ts) instance.
+- [`static parse(htmlString: string): BookmarksTree`](#static-parsehtmlstring-string-bookmarkstree)
-- **Parameter**: `htmlContent` - HTML bookmark file as string
-- **Returns**: Parsed bookmark tree
+  - Parses a Netscape Bookmark format HTML string and returns a `BookmarksTree`.
+  - Alias for [`parseFromHTMLString`](#static-parsefromhtmlstringhtmlstring-string-bookmarkstree).
-**Example:**
+  **Example:**
-```typescript
-const htmlContent = "<!DOCTYPE NETSCAPE-Bookmark-file-1>...";
-const tree = BookmarksParser.parse(htmlContent);
-```
+  ```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`.
+  **Example:**
+  ```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`.
+  **Example:**
+  ```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`.
+  **Example:**
+  ```typescript
+  const json = '{"Google": "https://google.com"}';
+  const tree = BookmarksParser.parseFromJSON(json);
+  ```
+---
 ### BookmarksTree Class
-[`BookmarksTree`](src/BookmarksTree/BookmarksTree.ts) is a class that extends `Map<string, string | BookmarksTree>` to represent the hierarchical structure of bookmarks.
+`BookmarksTree` extends `Map` and manages folders (`BookmarksTree`) and bookmarks (URL strings) in a hierarchical structure.
 #### Constructor
-```typescript
-const tree = new BookmarksTree();
-```
+- [`new BookmarksTree()`](#constructor)
+  **Example:**
+  ```typescript
+  const tree = new BookmarksTree();
+  tree.set("Google", "https://google.com");
+  ```
 #### Instance Methods
-##### `toJSON(): Record<string, unknown>`
+- [`toJSON(): Record<string, unknown>`](#tojson-recordstring-unknown)
-Convert tree to JSON object representation.
+  - Converts the tree to a JSON object representation.
-```typescript
-const json = tree.toJSON();
-console.log(JSON.stringify(json, null, 2));
-```
+  **Example:**
-##### `toDOM(): HTMLDocument`
+  ```typescript
+  const json = tree.toJSON();
+  console.log(json);
+  ```
-Convert tree to HTML document object.
+- [`toDOM(): HTMLDocument`](#todom-htmldocument)
-```typescript
-const htmlDocument = tree.toDOM();
-```
+  - Converts the tree to a Netscape Bookmark format HTML document.
-##### `get HTMLText(): string`
+  **Example:**
-Get HTML string representation of the bookmark tree.
+  ```typescript
+  const dom = tree.toDOM();
+  ```
-```typescript
-const htmlString = tree.HTMLText;
-console.log(htmlString); // Complete HTML bookmark file
-```
+- [`get HTMLString(): string`](#get-htmlstring-string)
-#### Static Methods
+  - Gets the complete HTML string in Netscape Bookmark format.
-##### `fromJSON(json: Record<string, unknown>): BookmarksTree`
+  **Example:**
-Restore tree from JSON object.
+  ```typescript
+  const html = tree.HTMLString;
+  console.log(html);
+  ```
-```typescript
-const json = { Google: "https://google.com" };
-const tree = BookmarksTree.fromJSON(json);
-```
+- [`get HTMLText(): string`](#get-htmltext-string)
+  - Alias for `HTMLString` (deprecated).
+#### Static Methods
-##### `fromDOM(dom: HTMLDocument): BookmarksTree`
+- [`static fromJSON(json: Record<string, unknown>): BookmarksTree`](#static-fromjsonjson-recordstring-unknown-bookmarkstree)
-Create tree from DOM document.
+  - Creates a tree from a JSON object.
-```typescript
-const dom = new DOMParser().parseFromString(htmlContent, "text/html");
-const tree = BookmarksTree.fromDOM(dom);
-```
+  **Example:**
-#### Map Interface
+  ```typescript
+  const json = { Google: "https://google.com" };
+  const tree = BookmarksTree.fromJSON(json);
+  ```
-Since `BookmarksTree` extends `Map`, you can use all standard Map methods:
+- [`static fromDOM(dom: HTMLDocument): BookmarksTree`](#static-fromdomdom-htmldocument-bookmarkstree)
-```typescript
-// Set bookmarks and folders
-tree.set("bookmark", "https://example.com");
-tree.set("folder", new BookmarksTree());
-// Get values
-const url = tree.get("bookmark"); // string
-const folder = tree.get("folder"); // BookmarksTree
-// Check existence
-tree.has("bookmark"); // true
-// Delete items
-tree.delete("bookmark");
-// Iterate
-for (const [name, value] of tree) {
-	if (typeof value === "string") {
-		console.log(`Bookmark: ${name} -> ${value}`);
-	} else {
-		console.log(`Folder: ${name} (${value.size} items)`);
-	}
-}
-```
+  - Creates a tree from an HTML document.
+  **Example:**
+  ```typescript
+  const dom = new DOMParser().parseFromString(html, "text/html");
+  const tree = BookmarksTree.fromDOM(dom);
+  ```
 ## Project Structure
@@ -375,117 +388,10 @@ npm/                         # Node.js build artifacts
 - **Empty Folder Support**: Preserves empty folders in the bookmark structure
 - **Duplicate Handling**: Last value wins for duplicate bookmark names
-## Output Examples
-### JSON Format
-```json
-{
-	"Development": {
-		"MDN": "https://developer.mozilla.org",
-		"Tools": {
-			"GitHub": "https://github.com",
-			"Stack Overflow": "https://stackoverflow.com"
-		}
-	},
-	"Google": "https://google.com"
-}
-```
-### HTML Format
-```html
-<!DOCTYPE NETSCAPE-Bookmark-file-1>
-<HTML>
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
-<TITLE>Bookmark</TITLE>
-<H1>Bookmark</H1>
-<BODY>
-<DL><p>
-    <DT><H3>Development</H3>
-    <DL><p>
-        <DT><A HREF="https://developer.mozilla.org">MDN</A>
-        <DT><H3>Tools</H3>
-        <DL><p>
-            <DT><A HREF="https://github.com">GitHub</A>
-            <DT><A HREF="https://stackoverflow.com">Stack Overflow</A>
-        </DL><p>
-    </DL><p>
-    <DT><A HREF="https://google.com">Google</A>
-</DL>
-</BODY>
-</HTML>
-```
 ## Dependencies
 - [`@b-fuze/deno-dom`](https://jsr.io/@b-fuze/deno-dom): DOM parser and manipulation for both Deno and Node.js environments
-## Development
-### Prerequisites
-- [Deno](https://deno.land/) 1.x or later
-### Setup
-```bash
-git clone https://github.com/grakeice/netscape-bookmark-parser.git
-cd netscape-bookmark-parser
-```
-### Development Commands
-```bash
-# Run development server with file watching
-deno task dev
-# Run all tests
-deno test
-# Run tests with coverage
-deno test --coverage
-# Format code
-deno fmt
-# Lint code
-deno lint
-# Build for Node.js
-deno task build:npm
-# Build with specific version
-deno task build:npm 1.0.0
-```
-### Running Tests
-The project includes comprehensive test suites for all functionality:
-```bash
-# Run all tests
-deno test
-# Run specific test file
-deno test src/BookmarksTree/BookmarksTree.test.ts
-# Run tests with detailed output
-deno test --verbose
-# Run tests and generate coverage report
-deno test --coverage=coverage_dir
-deno coverage coverage_dir
-```
-### Publishing
-The project uses automated publishing via GitHub Actions:
-1. Create a version tag: `git tag v1.0.0`
-2. Push the tag: `git push origin v1.0.0`
-3. GitHub Actions will automatically build and publish to both NPM and JSR
 ## Browser Compatibility
 ### Supported Browsers for Export Files
@@ -528,93 +434,10 @@ The library can parse bookmark files exported from:
 </DL>
 ```
-## Error Handling
-The library gracefully handles various error conditions:
-```typescript
-// Invalid HTML
-const invalidHtml = "<html><body>Not a bookmark file</body></html>";
-const tree = BookmarksParser.parse(invalidHtml);
-console.log(tree.size); // 0 - empty tree
-// Empty content
-const emptyTree = BookmarksParser.parse("");
-console.log(emptyTree.size); // 0
-// Malformed URLs are skipped
-const htmlWithBadUrls = `<!DOCTYPE NETSCAPE-Bookmark-file-1>
-<HTML><BODY><DL><p>
-    <DT><A HREF="">Empty URL</A>
-    <DT><A>No HREF attribute</A>
-    <DT><A HREF="https://valid.com">Valid Link</A>
-</DL><p></BODY></HTML>`;
-const parsedTree = BookmarksParser.parse(htmlWithBadUrls);
-console.log(parsedTree.size); // 1 - only valid link included
-```
-## Performance
-The library is optimized for performance:
-- **Memory Efficient**: Uses native Map structure for O(1) lookups
-- **Streaming Capable**: Can handle large bookmark files (1000+ bookmarks)
-- **Fast Parsing**: DOM-based parsing with efficient tree traversal
-- **JSON Conversion**: Optimized serialization/deserialization
-## TypeScript Support
-Full TypeScript definitions included:
-```typescript
-interface BookmarkValue extends Map<string, string | BookmarksTree> {
-	toJSON(): Record<string, unknown>;
-	toDOM(): HTMLDocument;
-	readonly HTMLText: string;
-}
-class BookmarksParser {
-	static parse(htmlContent: string): BookmarksTree;
-}
-class BookmarksTree extends Map<string, string | BookmarksTree> {
-	toJSON(): Record<string, unknown>;
-	static fromJSON(json: Record<string, unknown>): BookmarksTree;
-	static fromDOM(dom: HTMLDocument): BookmarksTree;
-	toDOM(): HTMLDocument;
-	get HTMLText(): string;
-}
-```
 ## License
 MIT License - See [LICENSE](LICENSE) file for details.
-## Contributing
-Pull requests and issue reports are welcome!
-### How to Contribute
-1. Fork this repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes with tests
-4. Ensure all tests pass (`deno test`)
-5. Format your code (`deno fmt`)
-6. Commit your changes (`git commit -m 'Add some amazing feature'`)
-7. Push to the branch (`git push origin feature/amazing-feature`)
-8. Create a pull request
-### Reporting Issues
-When reporting issues, please include:
-- Browser/environment information
-- Sample bookmark HTML (if applicable)
-- Expected vs actual behavior
-- Steps to reproduce
 ## Author
 **grakeice**
@@ -623,7 +446,19 @@ When reporting issues, please include:
 ## Changelog
-### v1.1.2 (Latest)
+### v1.1.4 (Latest)
+- 🛠️ **Improved parser** (better compatibility with various bookmark HTML formats, increased stability)
+- 🧹 **Code refactoring and additional tests**
+- 🐞 **Minor bug fixes**
+- 📚 **Documentation Update**: API Reference refresh, unified explanations, added usage examples, revived various sections
+### v1.1.3
+- 📝 **Added JSDoc comments**: Added JSDoc-style comments to major classes and methods to improve type information and enable automatic API documentation generation
+- 📚 **Documentation Update**: Added TypeScript import example for Node.js/npm in the Installation section
+### v1.1.2
 - 📝 **Documentation Enhancement**: Updated comprehensive README documentation with latest version references and improved examples
 - 🔧 **Version Consistency**: Synchronized version numbers across all documentation and code examples

package/esm/src/BookmarksParser/BookmarksParser.d.ts CHANGED Viewed

@@ -4,8 +4,127 @@
  * This software is released under the MIT License.
  * https://opensource.org/licenses/MIT
  */
+import type { HTMLDocument } from "../deps.js";
 import { BookmarksTree } from "../BookmarksTree/index.js";
+/**
+ * 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);
+ * ```
+ */
 export declare class BookmarksParser {
-    static parse(data: string): BookmarksTree;
+    /**
+     * 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;
 }
 //# sourceMappingURL=BookmarksParser.d.ts.map

package/esm/src/BookmarksParser/BookmarksParser.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"BookmarksParser.d.ts","sourceRoot":"","sources":["../../../src/src/BookmarksParser/BookmarksParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D,qBAAa,eAAe;IAC3B,MAAM,CAAC,KAAK,CAAC,~~IAAI~~,EAAE,MAAM,GAAG,aAAa;~~CAKzC~~"}
1	+ {"version":3,"file":"BookmarksParser.d.ts","sourceRoot":"","sources":["../../../src/src/BookmarksParser/BookmarksParser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe;IAC3B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAI/C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAM7D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,aAAa;IAIrD;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa;IAK7D;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa;CAGrE"}