select-dom - npm Package Compare versions

Comparing version 8.0.0 to 9.0.0

index.d.ts

@@ -8,8 +8,6 @@ import type { ParseSelector } from 'typed-query-selector/parser.js';
  */
-declare function select<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
-declare function select<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;
-declare namespace select {
-    var last: typeof selectLast;
-    var exists: typeof selectExists;
-    var all: typeof selectAll;
+declare function $<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
+declare function $<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;
+export declare class ElementNotFoundError extends Error {
+    name: string;
 }
@@ -19,6 +17,13 @@ /**
  * @param [baseElement]  The element to look inside of
+ * @return               The element found, or an error
+ */
+declare function expectElement<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected;
+declare function expectElement<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected;
+/**
+ * @param selectors      One or more CSS selectors separated by commas
+ * @param [baseElement]  The element to look inside of
  * @return               The element found, if any
  */
-declare function selectLast<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
-declare function selectLast<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;
+declare function lastElement<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElement?: ParentNode): Selected | undefined;
+declare function lastElement<Selected extends Element = HTMLElement>(selectors: string | string[], baseElement?: ParentNode): Selected | undefined;
 /**
@@ -29,3 +34,3 @@ * @param selectors      One or more CSS selectors separated by commas
  */
-declare function selectExists(selectors: string | string[], baseElement?: ParentNode): boolean;
+declare function elementExists(selectors: string | string[], baseElement?: ParentNode): boolean;
 /**
@@ -36,4 +41,4 @@ * @param selectors       One or more CSS selectors separated by commas
  */
-declare function selectAll<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElements?: BaseElements): Selected[];
-declare function selectAll<Selected extends Element = HTMLElement>(selectors: string | string[], baseElements?: BaseElements): Selected[];
-export default select;
+declare function $$<Selector extends string, Selected extends Element = ParseSelector<Selector, HTMLElement>>(selectors: Selector | Selector[], baseElements?: BaseElements): Selected[];
+declare function $$<Selected extends Element = HTMLElement>(selectors: string | string[], baseElements?: BaseElements): Selected[];
+export { $, $$, lastElement, elementExists, expectElement };

index.js

@@ -5,3 +5,3 @@ // Type predicate for TypeScript
 }
-function select(selectors, baseElement) {
+function $(selectors, baseElement) {
     // Shortcut with specified-but-null baseElement
@@ -13,8 +13,23 @@ if (arguments.length === 2 && !baseElement) {
 }
-function selectLast(selectors, baseElement) {
+export class ElementNotFoundError extends Error {
+    name = 'ElementNotFoundError';
+}
+function expectElement(selectors, baseElement) {
     // Shortcut with specified-but-null baseElement
     if (arguments.length === 2 && !baseElement) {
+        throw new ElementNotFoundError('Expected element not found because the base is specified but null');
+    }
+    const element = (baseElement ?? document).querySelector(String(selectors));
+    if (element) {
+        return element;
+    }
+    throw new ElementNotFoundError(`Expected element not found: ${String(selectors)}`);
+}
+function lastElement(selectors, baseElement) {
+    // Shortcut with specified-but-null baseElement
+    if (arguments.length === 2 && !baseElement) {
         return undefined;
     }
     const all = (baseElement ?? document).querySelectorAll(String(selectors));
+    // eslint-disable-next-line unicorn/prefer-at -- Not an Array, not worth converting it
     return all[all.length - 1];
@@ -27,3 +42,3 @@ }
  */
-function selectExists(selectors, baseElement) {
+function elementExists(selectors, baseElement) {
     // Shortcut with specified-but-null baseElement
@@ -35,3 +50,3 @@ if (arguments.length === 2 && !baseElement) {
 }
-function selectAll(selectors, baseElements) {
+function $$(selectors, baseElements) {
     // Shortcut with specified-but-null baseElements
@@ -44,15 +59,12 @@ if (arguments.length === 2 && !baseElements) {
         const elements = (baseElements ?? document).querySelectorAll(String(selectors));
-        return [...elements];
+        return Array.prototype.slice.call(elements);
     }
-    const queried = new Set();
+    const elements = new Set();
     for (const baseElement of baseElements) {
         for (const element of baseElement.querySelectorAll(String(selectors))) {
-            queried.add(element);
+            elements.add(element);
         }
     }
-    return [...queried]; // Convert to array
+    return [...elements]; // Convert to array
 }
-select.last = selectLast;
-select.exists = selectExists;
-select.all = selectAll;
-export default select;
+export { $, $$, lastElement, elementExists, expectElement };

package.json

 {
 	"name": "select-dom",
-	"version": "8.0.0",
+	"version": "9.0.0",
 	"description": "Extra lightweight DOM selector helper",
@@ -43,10 +43,10 @@ "keywords": [
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^3.0.1",
+		"@sindresorhus/tsconfig": "^5.0.0",
 		"browserify": "^17.0.0",
 		"esmify": "^2.1.1",
-		"tape": "^5.6.4",
-		"tape-run": "^10.0.0",
-		"tsd": "^0.28.1",
-		"typescript": "^5.1.6",
-		"xo": "^0.54.2"
+		"tape": "^5.7.0",
+		"tape-run": "^11.0.0",
+		"tsd": "^0.29.0",
+		"typescript": "^5.2.2",
+		"xo": "^0.56.0"
 	},
@@ -53,0 +53,0 @@ "engines": {

readme.md

@@ -19,3 +19,3 @@ # select-dom [![][badge-gzip]][link-npm] [![npm downloads][badge-downloads]][link-npm]
 // This module is only offered as a ES Module
-import select from 'select-dom';
+import {$, $$, lastElement, elementExists} from 'select-dom';
 ```
@@ -27,3 +27,3 @@
 
-### `select(selector[, baseElement = document])`
+### `$(selector[, baseElement = document])`
 
@@ -33,29 +33,29 @@ Maps to `baseElement.querySelector(selector)`, except it returns `undefined` if it's not found
 ```js
-select('.foo a[href=bar]');
+$('.foo a[href=bar]');
 // => <Element>
 
-select('.foo a[href=bar]', baseElement);
+$('.foo a[href=bar]', baseElement);
 // => <Element>
 
-select('.non-existent', baseElement);
+$('.non-existent', baseElement);
 // => undefined
 ```
 
-### `select.last(selector[, baseElement = document])`
+### `lastElement(selector[, baseElement = document])`
 
-Like `select()`, except that it returns the last matching item on the page instead of the first one.
+Like `$()`, except that it returns the last matching item on the page instead of the first one.
 
-### `select.exists(selector[, baseElement = document])`
+### `elementExists(selector[, baseElement = document])`
 
-Tests the existence of one or more elements matching the selector. It's like `select()`, except it returns a `boolean`.
+Tests the existence of one or more elements matching the selector. It's like `$()`, except it returns a `boolean`.
 
 ```js
-select.exists('.foo a[href=bar]');
+elementExists('.foo a[href=bar]');
 // => true/false
 
-select.exists('.foo a[href=bar]', baseElement);
+elementExists('.foo a[href=bar]', baseElement);
 // => true/false
 ```
 
-### `select.all(selector[, baseElements = document])`
+### `$$(selector[, baseElements = document])`
 
@@ -68,9 +68,9 @@ Maps to `baseElements.querySelectorAll(selector)` plus:
 ```js
-select.all('.foo');
+$$('.foo');
 // => [<Element>, <Element>, <Element>]
 
-select.all('.foo', baseElement);
+$$('.foo', baseElement);
 // => [<Element>, <Element>, <Element>]
 
-select.all('.foo', [baseElement1, baseElement2]);
+$$('.foo', [baseElement1, baseElement2]);
 // => [<Element>, <Element>, <Element>]
@@ -77,0 +77,0 @@ // This is similar to jQuery([baseElement1, baseElement2]).find('.foo')

No alert changes

Improved metrics

Total package byte prevSize

9910

increased by12.35%

Lines of code

105

increased by19.32%

No dependency changes