iframe-finder 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Artem Deikun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# iframe-finder
+
+A lightweight TypeScript library for recursively finding nested iframes in the DOM tree.
+
+## Features
+
+- 🔍 **Recursive Search** - Find iframes at any nesting depth
+- 🎯 **Multiple Search Methods** - By id, name, or custom criteria
+- 🛡️ **Safe** - Handles cross-origin iframes gracefully
+- 📦 **Lightweight** - Zero dependencies, ~1KB gzipped
+- 💪 **TypeScript** - Full type safety and IntelliSense support
+- ⚡ **Fast** - Optimized search with depth limiting
+
+## Installation
+
+```bash
+npm install iframe-finder
+```
+
+## Usage
+
+### Find by ID
+
+```typescript
+import { findIframeById } from 'iframe-finder';
+
+// Find iframe with id="myFrame" anywhere in the DOM tree
+const iframe = findIframeById('myFrame');
+
+if (iframe) {
+  console.log('Found iframe:', iframe);
+  // Access iframe content
+  const content = iframe.contentDocument;
+}
+```
+
+### Find by Name
+
+```typescript
+import { findIframeByName } from 'iframe-finder';
+
+const iframe = findIframeByName('contentFrame');
+```
+
+### Custom Search Criteria
+
+```typescript
+import { findIframe } from 'iframe-finder';
+
+// Find iframe by src
+const iframe = findIframe((frame) =>
+  frame.src.includes('example.com')
+);
+
+// Find iframe by class
+const iframe = findIframe((frame) =>
+  frame.classList.contains('special-frame')
+);
+
+// Find iframe by data attribute
+const iframe = findIframe((frame) =>
+  frame.dataset.type === 'content'
+);
+```
+
+### Advanced Options
+
+```typescript
+import { findIframeById } from 'iframe-finder';
+
+// Limit search depth
+const iframe = findIframeById('myFrame', {
+  maxDepth: 3  // Only search 3 levels deep
+});
+
+// Start from specific document
+const iframe = findIframeById('myFrame', {
+  rootDocument: someIframe.contentDocument
+});
+```
+
+### Find All Matching Iframes
+
+```typescript
+import { findAllIframes } from 'iframe-finder';
+
+// Find all iframes with specific class
+const iframes = findAllIframes((frame) =>
+  frame.classList.contains('content')
+);
+
+console.log(`Found ${iframes.length} iframes`);
+```
+
+## API Reference
+
+### `findIframeById(id: string, options?: FindIframeOptions): HTMLIFrameElement | null`
+
+Recursively searches for an iframe by its `id` attribute.
+
+**Parameters:**
+- `id` - The id attribute to search for
+- `options` - Optional search options
+
+**Returns:** The found iframe element or `null`
+
+### `findIframeByName(name: string, options?: FindIframeOptions): HTMLIFrameElement | null`
+
+Recursively searches for an iframe by its `name` attribute.
+
+**Parameters:**
+- `name` - The name attribute to search for
+- `options` - Optional search options
+
+**Returns:** The found iframe element or `null`
+
+### `findIframe(predicate: IframePredicate, options?: FindIframeOptions): HTMLIFrameElement | null`
+
+Recursively searches for an iframe using a custom predicate function.
+
+**Parameters:**
+- `predicate` - Function that returns `true` when iframe matches criteria
+- `options` - Optional search options
+
+**Returns:** The found iframe element or `null`
+
+### `findAllIframes(predicate: IframePredicate, rootDocument?: Document): HTMLIFrameElement[]`
+
+Finds all iframes matching the predicate (single level, non-recursive).
+
+**Parameters:**
+- `predicate` - Function to test each iframe
+- `rootDocument` - Starting document (defaults to `window.document`)
+
+**Returns:** Array of matching iframes
+
+### `FindIframeOptions`
+
+```typescript
+interface FindIframeOptions {
+  rootDocument?: Document;  // Starting document (default: window.document)
+  maxDepth?: number;        // Maximum search depth (default: Infinity)
+}
+```
+
+### `IframePredicate`
+
+```typescript
+type IframePredicate = (iframe: HTMLIFrameElement) => boolean;
+```
+
+## Real-World Examples
+
+### Finding Nested Game Frames
+
+```typescript
+import { findIframeById } from 'iframe-finder';
+
+// Game UI often has deeply nested iframes
+const showInfoFrame = findIframeById('showInfo');
+if (showInfoFrame?.contentDocument) {
+  const healthElement = showInfoFrame.contentDocument
+    .querySelector('[title="Character Info"]');
+}
+```
+
+### Finding Ad Frames
+
+```typescript
+import { findIframe } from 'iframe-finder';
+
+// Find advertisement iframe
+const adFrame = findIframe((frame) =>
+  frame.src.includes('doubleclick.net') ||
+  frame.classList.contains('ad-frame')
+);
+```
+
+### Finding Communication Frames
+
+```typescript
+import { findIframeByName } from 'iframe-finder';
+
+// Find chat or messaging iframe
+const chatFrame = findIframeByName('chat-widget');
+if (chatFrame) {
+  // Setup postMessage communication
+  chatFrame.contentWindow?.postMessage({ type: 'init' }, '*');
+}
+```
+
+## Browser Support
+
+Works in all modern browsers that support:
+- `querySelector` / `querySelectorAll`
+- `HTMLIFrameElement.contentDocument`
+- `Array.from`
+
+This includes:
+- Chrome/Edge 45+
+- Firefox 40+
+- Safari 10+
+- Opera 32+
+
+## Security Notes
+
+- Cross-origin iframes are automatically skipped due to browser security restrictions
+- The library catches and silently handles cross-origin access errors
+- Always validate and sanitize any data retrieved from iframe content
+
+## License
+
+MIT © Artem Deikun
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Links
+
+- [GitHub Repository](https://github.com/artemhp/iframe-finder)
+- [npm Package](https://www.npmjs.com/package/iframe-finder)
+- [Report Issues](https://github.com/artemhp/iframe-finder/issues)

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Options for finding iframes
+ */
+export interface FindIframeOptions {
+    /**
+     * Starting document to search from (defaults to window.document)
+     */
+    rootDocument?: Document;
+    /**
+     * Maximum depth to search (defaults to unlimited)
+     */
+    maxDepth?: number;
+}
+/**
+ * Predicate function for custom iframe matching
+ */
+export type IframePredicate = (iframe: HTMLIFrameElement) => boolean;
+/**
+ * Recursively searches for an iframe by its id attribute
+ *
+ * @param id - The id attribute to search for
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * const iframe = findIframeById('myFrame');
+ * if (iframe) {
+ *   console.log('Found iframe:', iframe);
+ * }
+ * ```
+ */
+export declare function findIframeById(id: string, options?: FindIframeOptions): HTMLIFrameElement | null;
+/**
+ * Recursively searches for an iframe by its name attribute
+ *
+ * @param name - The name attribute to search for
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * const iframe = findIframeByName('contentFrame');
+ * if (iframe) {
+ *   console.log('Found iframe:', iframe);
+ * }
+ * ```
+ */
+export declare function findIframeByName(name: string, options?: FindIframeOptions): HTMLIFrameElement | null;
+/**
+ * Recursively searches for an iframe using a custom predicate function
+ *
+ * @param predicate - Function that returns true when iframe matches criteria
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find iframe with specific src
+ * const iframe = findIframe((frame) => frame.src.includes('example.com'));
+ *
+ * // Find iframe with specific class
+ * const iframe = findIframe((frame) => frame.classList.contains('special'));
+ * ```
+ */
+export declare function findIframe(predicate: IframePredicate, options?: FindIframeOptions): HTMLIFrameElement | null;
+/**
+ * Finds all iframes matching the predicate (non-recursive, single level)
+ *
+ * @param predicate - Function to test each iframe
+ * @param rootDocument - Starting document (defaults to window.document)
+ * @returns Array of matching iframes
+ *
+ * @example
+ * ```typescript
+ * // Find all iframes with specific class
+ * const iframes = findAllIframes((frame) => frame.classList.contains('content'));
+ * ```
+ */
+export declare function findAllIframes(predicate: IframePredicate, rootDocument?: Document): HTMLIFrameElement[];
+declare const _default: {
+    findIframeById: typeof findIframeById;
+    findIframeByName: typeof findIframeByName;
+    findIframe: typeof findIframe;
+    findAllIframes: typeof findAllIframes;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findIframeById = findIframeById;
+exports.findIframeByName = findIframeByName;
+exports.findIframe = findIframe;
+exports.findAllIframes = findAllIframes;
+/**
+ * Recursively searches for an iframe by its id attribute
+ *
+ * @param id - The id attribute to search for
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * const iframe = findIframeById('myFrame');
+ * if (iframe) {
+ *   console.log('Found iframe:', iframe);
+ * }
+ * ```
+ */
+function findIframeById(id, options = {}) {
+    const { rootDocument = document, maxDepth = Infinity } = options;
+    return findIframeRecursive((iframe) => iframe.id === id, rootDocument, 0, maxDepth);
+}
+/**
+ * Recursively searches for an iframe by its name attribute
+ *
+ * @param name - The name attribute to search for
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * const iframe = findIframeByName('contentFrame');
+ * if (iframe) {
+ *   console.log('Found iframe:', iframe);
+ * }
+ * ```
+ */
+function findIframeByName(name, options = {}) {
+    const { rootDocument = document, maxDepth = Infinity } = options;
+    return findIframeRecursive((iframe) => iframe.name === name, rootDocument, 0, maxDepth);
+}
+/**
+ * Recursively searches for an iframe using a custom predicate function
+ *
+ * @param predicate - Function that returns true when iframe matches criteria
+ * @param options - Search options
+ * @returns The found iframe element or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Find iframe with specific src
+ * const iframe = findIframe((frame) => frame.src.includes('example.com'));
+ *
+ * // Find iframe with specific class
+ * const iframe = findIframe((frame) => frame.classList.contains('special'));
+ * ```
+ */
+function findIframe(predicate, options = {}) {
+    const { rootDocument = document, maxDepth = Infinity } = options;
+    return findIframeRecursive(predicate, rootDocument, 0, maxDepth);
+}
+/**
+ * Internal recursive function to search for iframes
+ *
+ * @param predicate - Function to test each iframe
+ * @param doc - Current document to search
+ * @param currentDepth - Current recursion depth
+ * @param maxDepth - Maximum allowed depth
+ * @returns Found iframe or null
+ */
+function findIframeRecursive(predicate, doc, currentDepth, maxDepth) {
+    // Check depth limit
+    if (currentDepth > maxDepth) {
+        return null;
+    }
+    // Get all iframes in current document
+    const iframes = doc.querySelectorAll('iframe');
+    // First pass: check current level
+    for (const iframe of Array.from(iframes)) {
+        if (predicate(iframe)) {
+            return iframe;
+        }
+    }
+    // Second pass: recurse into nested iframes
+    for (const iframe of Array.from(iframes)) {
+        try {
+            const contentDoc = iframe.contentDocument;
+            if (!contentDoc)
+                continue;
+            const foundInNested = findIframeRecursive(predicate, contentDoc, currentDepth + 1, maxDepth);
+            if (foundInNested) {
+                return foundInNested;
+            }
+        }
+        catch (error) {
+            // Skip iframes we can't access (cross-origin security)
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Finds all iframes matching the predicate (non-recursive, single level)
+ *
+ * @param predicate - Function to test each iframe
+ * @param rootDocument - Starting document (defaults to window.document)
+ * @returns Array of matching iframes
+ *
+ * @example
+ * ```typescript
+ * // Find all iframes with specific class
+ * const iframes = findAllIframes((frame) => frame.classList.contains('content'));
+ * ```
+ */
+function findAllIframes(predicate, rootDocument = document) {
+    const iframes = rootDocument.querySelectorAll('iframe');
+    return Array.from(iframes).filter(predicate);
+}
+// Export default object with all functions
+exports.default = {
+    findIframeById,
+    findIframeByName,
+    findIframe,
+    findAllIframes,
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "iframe-finder",
+  "version": "1.0.0",
+  "description": "Recursively find nested iframes by id, name, or custom criteria in the DOM tree",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "iframe",
+    "nested",
+    "recursive",
+    "dom",
+    "find",
+    "search",
+    "traverse"
+  ],
+  "author": "Artem Deikun",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/artemhp/iframe-finder.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}