@wtasnorg/node-lib 0.0.6 → 0.0.8

package/src/user-agent.ts

@@ -0,0 +1,199 @@
+/**
+ * Information extracted from a user-agent string.
+ */
+export interface UserAgentInfo {
+    /**
+     * Browser name (e.g., Chrome, Firefox, Safari, Edge, Opera, Other).
+     */
+    browser: string;
+    /**
+     * Browser version (e.g., 120.0.0.0).
+     */
+    version: string;
+    /**
+     * Operating system (e.g., Windows, macOS, Linux, iOS, Android, Other).
+     */
+    os: string;
+    /**
+     * Device type (e.g., Mobile, Tablet, Desktop, Other).
+     */
+    device: string;
+    /**
+     * Rendering engine (e.g., Blink, WebKit, Gecko, Presto, Other).
+     */
+    engine: string;
+}
+
+/**
+ * Parses a user-agent string into a UserAgentInfo object.
+ *
+ * @param ua - The user-agent string to parse.
+ * @returns An object containing the extracted information.
+ *
+ * @example
+ * ```typescript
+ * // Success Example (Chrome on Windows)
+ * const ua = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+ * const info = parseUserAgent(ua);
+ * // { browser: "Chrome", version: "120.0.0.0", os: "Windows", device: "Desktop", engine: "Blink" }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error/Fallback Example (Empty string)
+ * const info = parseUserAgent("");
+ * // { browser: "Other", version: "0", os: "Other", device: "Desktop", engine: "Other" }
+ * ```
+ */
+export function parseUserAgent(ua: string): UserAgentInfo {
+    if (!ua) {
+        return {
+            browser: "Other",
+            version: "0",
+            os: "Other",
+            device: "Desktop",
+            engine: "Other",
+        };
+    }
+
+    const browserInfo = detectBrowser(ua);
+    return {
+        browser: browserInfo.name,
+        version: browserInfo.version,
+        os: detectOS(ua),
+        device: detectDeviceType(ua),
+        engine: detectEngine(ua),
+    };
+}
+
+/**
+ * Detects the browser name and version from a user-agent string.
+ *
+ * @param ua - The user-agent string.
+ * @returns An object with name and version.
+ *
+ * @example
+ * ```typescript
+ * // Success Example
+ * detectBrowser("Mozilla/5.0 ... Firefox/121.0");
+ * // { name: "Firefox", version: "121.0" }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error/Fallback Example
+ * detectBrowser("UnknownBot/1.0");
+ * // { name: "Other", version: "0" }
+ * ```
+ */
+function detectBrowser(ua: string): { name: string; version: string } {
+    let name = "Other";
+    let version = "0";
+
+    if (ua.includes("Edg/")) {
+        name = "Edge";
+        version = ua.split("Edg/")[1]?.split(" ")[0] || "0";
+    } else if (ua.includes("Chrome/") && !ua.includes("Chromium/")) {
+        name = "Chrome";
+        version = ua.split("Chrome/")[1]?.split(" ")[0] || "0";
+    } else if (ua.includes("Safari/") && !ua.includes("Chrome/")) {
+        name = "Safari";
+        version = ua.split("Version/")[1]?.split(" ")[0] || ua.split("Safari/")[1]?.split(" ")[0] || "0";
+    } else if (ua.includes("Firefox/")) {
+        name = "Firefox";
+        version = ua.split("Firefox/")[1]?.split(" ")[0] || "0";
+    } else if (ua.includes("OPR/") || ua.includes("Opera/")) {
+        name = "Opera";
+        version = (ua.split("OPR/")[1] || ua.split("Opera/")[1])?.split(" ")[0] || "0";
+    }
+
+    return { name, version };
+}
+
+/**
+ * Detects the operating system from a user-agent string.
+ *
+ * @param ua - The user-agent string.
+ * @returns The operating system name.
+ *
+ * @example
+ * ```typescript
+ * // Success Example
+ * detectOS("Mozilla/5.0 (iPhone; ...)");
+ * // "iOS"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error/Fallback Example
+ * detectOS("Custom OS");
+ * // "Other"
+ * ```
+ */
+function detectOS(ua: string): string {
+    if (ua.includes("iPhone") || ua.includes("iPad") || ua.includes("iPod")) { return "iOS"; }
+    if (ua.includes("Windows")) { return "Windows"; }
+    if (ua.includes("Mac OS X")) { return "macOS"; }
+    if (ua.includes("Android")) { return "Android"; }
+    if (ua.includes("Linux")) { return "Linux"; }
+    return "Other";
+}
+
+/**
+ * Detects the device type (Desktop, Mobile, Tablet) from a user-agent string.
+ *
+ * @param ua - The user-agent string.
+ * @returns The device type.
+ *
+ * @example
+ * ```typescript
+ * // Success Example
+ * detectDeviceType("Mozilla/5.0 (iPad; ...)");
+ * // "Tablet"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error/Fallback Example
+ * detectDeviceType("Generic Browser");
+ * // "Desktop"
+ * ```
+ */
+function detectDeviceType(ua: string): string {
+    if (ua.includes("iPad") || (ua.includes("Android") && !ua.includes("Mobile"))) {
+        return "Tablet";
+    }
+    if (ua.includes("Mobi")) {
+        return "Mobile";
+    }
+    return "Desktop";
+}
+
+/**
+ * Detects the rendering engine from a user-agent string.
+ *
+ * @param ua - The user-agent string.
+ * @returns The engine name.
+ *
+ * @example
+ * ```typescript
+ * // Success Example
+ * detectEngine("Mozilla/5.0 ... AppleWebKit/537.36 ...");
+ * // "Blink"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error/Fallback Example
+ * detectEngine("Unknown Engine");
+ * // "Other"
+ * ```
+ */
+function detectEngine(ua: string): string {
+    // Blink check must come first: Chrome/Chromium browsers use AppleWebKit but are Blink-based
+    if (ua.includes("Chrome/") && ua.includes("AppleWebKit/")) { return "Blink"; }
+    if (ua.includes("AppleWebKit")) { return "WebKit"; }
+    if (ua.includes("Gecko/")) { return "Gecko"; }
+    if (ua.includes("Presto/")) { return "Presto"; }
+    return "Other";
+}

package/test_report

@@ -0,0 +1,26 @@
+
+> @wtasnorg/node-lib@0.0.7 test
+> bash -c 'node --test src/**/*.test.js'
+
+✔ find: findDirectories success (1.077042ms)
+✔ find: findDirectories symlink is NOT treated as a directory (0.181028ms)
+✔ find: findDirectories at depth=2 (0.264408ms)
+✔ find: findDirectories at depth=3 (0.225558ms)
+hello from @wtasnorg/node-lib
+hello from @wtasnorg/node-lib
+▶ hello
+  ✔ returns a string that has the word 'hello' in it (0.855703ms)
+  ✔ returns exact string (0.132439ms)
+✔ hello (1.649597ms)
+✔ pojo() should return only enumerable data fields (0.948072ms)
+✔ pojo() should exclude methods (0.137609ms)
+✔ pojo() should exclude prototype properties (0.141089ms)
+✔ pojo() should ignore non-enumerable own properties (0.671565ms)
+ℹ tests 10
+ℹ suites 1
+ℹ pass 10
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 50.692585

package/typedoc.json

@@ -1,11 +1,15 @@
 {
   "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/index.ts"],
+  "entryPoints": [
+    "./src/index.ts"
+  ],
   "excludePrivate": true,
   "excludeProtected": true,
   "name": "@wtasnorg/node-lib",
   "out": "docs",
-  "plugin": ["typedoc-plugin-markdown"],
+  "plugin": [
+    "typedoc-plugin-markdown"
+  ],
   "theme": "default",
   "tsconfig": "./tsconfig.json",
 }

package/DEV_CHECKLIST.md

@@ -1,15 +0,0 @@
-# Development Checklist
-
-- [ ] Have you written tests for your code?
-- [ ] Does the code pass all tests? `npm run test`
-- [ ] Have you upated documentation?
-- [ ] Have you generated docs via `npm run docs && npm run docs:json`
-- [ ] Have you reviewed the code locally?
-- [ ] Have you used the code locally?
-- [ ] Check your email and username. Protect PII. `git log -n1`
-
-```bash
-npm run build
-npm run test
-npm run docs && npm run docs:json
-```

package/docs/_media/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 wtasg
-
-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/docs/globals.md

@@ -1,16 +0,0 @@
-[**@wtasnorg/node-lib**](README.md)
-
-***
-
-# @wtasnorg/node-lib
-
-## Interfaces
-
-- [FileSystemDependencies](interfaces/FileSystemDependencies.md)
-- [FindDirectoriesOptions](interfaces/FindDirectoriesOptions.md)
-
-## Functions
-
-- [createFindDirectories](functions/createFindDirectories.md)
-- [hello](functions/hello.md)
-- [pojo](functions/pojo.md)