doc: add dynamic return types

package-lock.json

@@ -7,7 +7,17 @@
     "": {
       "name": "ajquery",
       "version": "3.0.3",
-      "license": "MPL-2.0"
+      "license": "MPL-2.0",
+      "devDependencies": {
+        "typed-query-selector": "^2.12.0"
+      }
+    },
+    "node_modules/typed-query-selector": {
+      "version": "2.12.0",
+      "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.0.tgz",
+      "integrity": "sha512-SbklCd1F0EiZOyPiW192rrHZzZ5sBijB6xM+cpmrwDqObvdtunOHHIk9fCGsoK5JVIYXoyEp4iEdE3upFH3PAg==",
+      "dev": true,
+      "license": "MIT"
     }
   }
 }

package.json

@@ -5,6 +5,7 @@
   "main": "ajquery.cjs",
   "module": "ajquery.mjs",
   "type": "commonjs",
+  "types": "./select-dom.d.ts",
   "browser": {
     "ajquery.min.cjs": "ajquery.min.js"
   },
@@ -21,7 +22,8 @@
     "ajquery.cjs",
     "ajquery.min.cjs",
     "ajquery.mjs",
-    "ajquery.min.mjs"
+    "ajquery.min.mjs",
+    "select-dom.d.ts"
   ],
   "scripts": {
     "benchmark": "node ./benchmark.js",
@@ -62,5 +64,8 @@
   "bugs": {
     "url": "https://github.com/coolaj86/ajquery.js/issues"
   },
-  "homepage": "https://twitter.com/coolaj86/status/1303386788119998464"
+  "homepage": "https://twitter.com/coolaj86/status/1303386788119998464",
+  "devDependencies": {
+    "typed-query-selector": "^2.12.0"
+  }
 }

select-dom.d.ts

@@ -0,0 +1,89 @@
+/**
+ * select-dom (https://github.com/fregante/select-dom)
+ * MIT License
+ * Copyright (c) Federico Brigante Federico Brigante <me@fregante.com> (https://fregante.com)
+ * Copyright (c) 2014 Azer Koçulu <azer@kodfabrik.com>
+ */
+
+import type { ParseSelector } from "typed-query-selector/parser.js";
+
+type BaseElements = ParentNode | Iterable<ParentNode>;
+
+/**
+ * @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 $<
+  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;
+}
+
+/**
+ * @param selectors      One or more CSS selectors separated by commas
+ * @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 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;
+
+/**
+ * @param selectors      One or more CSS selectors separated by commas
+ * @param [baseElement]  The element to look inside of
+ * @return               Whether it's been found
+ */
+declare function elementExists(
+  selectors: string | string[],
+  baseElement?: ParentNode
+): boolean;
+
+/**
+ * @param selectors       One or more CSS selectors separated by commas
+ * @param [baseElements]  The element or list of elements to look inside of
+ * @return                An array of elements found
+ */
+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 };