os-detect 1.0.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Danil Lisin Vladimirovich (macrulez)
+
+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

@@ -1,38 +1,209 @@
 # os-detect
 
-Simple OS and device type detection for browsers (no dependencies).
+A lightweight utility for detecting the operating system and device type — in browsers, Node.js, and SSR. With React hooks and Vue composables. No dependencies.
 
 ## Installation
 
-```
+```bash
 npm install os-detect
 ```
 
 ## Usage
 
+```ts
+import {
+  getOS,
+  detectIsIOS, detectIsMacOS, detectIsAndroid,
+  detectIsWindows, detectIsLinux, detectIsChromeOS,
+  detectIsWindows11,
+  isMobileDevice, isDesktopDevice,
+} from 'os-detect';
+
+// Get OS as a string
+getOS();               // 'ios' | 'macos' | 'android' | 'windows' | 'linux' | 'chromeos' | 'unknown'
+
+// Boolean detection
+detectIsIOS();         // true on iPhone, iPod, iPad (including iPadOS 13+)
+detectIsMacOS();       // true on macOS desktop (correctly excludes iPadOS 13+)
+detectIsAndroid();     // true on Android phones and tablets
+detectIsWindows();     // true on Windows desktop or laptop
+detectIsLinux();       // true on Linux desktop (excludes Android and ChromeOS)
+detectIsChromeOS();    // true on ChromeOS devices
+
+// Async: Windows 11 check
+const isWin11 = await detectIsWindows11();   // true | false
+
+// Device category
+isMobileDevice();      // true if iOS or Android
+isDesktopDevice();     // true if macOS, Windows, Linux, or ChromeOS
+```
+
+CommonJS:
 ```js
-const osDetect = require('os-detect');
+const { getOS, detectIsIOS, isMobileDevice } = require('os-detect');
+```
+
+UMD via `<script>` tag:
+```html
+<script src="https://unpkg.com/os-detect/dist/index.umd.js"></script>
+<script>
+  console.log(OsDetect.getOS());
+  console.log(OsDetect.detectIsIOS());
+  console.log(OsDetect.isMobileDevice());
+</script>
+```
+
+---
+
+## React
+
+```tsx
+import { useOS, useIsWindows11 } from 'os-detect/react';
+
+function App() {
+  const os = useOS();                 // 'windows' | 'macos' | 'ios' | ...
+  const isWin11 = useIsWindows11();   // null (loading) → true | false
+
+  return (
+    <div>
+      <p>OS: {os}</p>
+      {isWin11 === null && <p>Detecting Windows version...</p>}
+      {isWin11 === true && <p>Windows 11</p>}
+      {isWin11 === false && os === 'windows' && <p>Windows 10 or older</p>}
+    </div>
+  );
+}
+```
+
+Requires React 17+.
+
+---
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { useOS, useIsWindows11 } from 'os-detect/vue';
+
+const os = useOS();               // Readonly<Ref<OS>>
+const isWin11 = useIsWindows11(); // Readonly<Ref<boolean | null>>
+</script>
+
+<template>
+  <p>OS: {{ os }}</p>
+  <p v-if="isWin11 === null">Detecting Windows version...</p>
+  <p v-else-if="isWin11">Windows 11</p>
+  <p v-else-if="os === 'windows'">Windows 10 or older</p>
+</template>
+```
+
+Requires Vue 3+.
+
+---
+
+## Node.js & SSR
+
+All functions work in Node.js via `process.platform`:
+
+```ts
+import { getOS, detectIsWindows, detectIsWindows11 } from 'os-detect';
+
+// Reads process.platform — no browser required
+getOS();            // 'macos' | 'windows' | 'linux' | 'android' | 'unknown'
+detectIsWindows();  // true on Windows
 
-console.log(osDetect.detectIsiOS()); // true/false
-console.log(osDetect.detectIsMacOS()); // true/false
-console.log(osDetect.detectIsAndroid()); // true/false
-console.log(osDetect.detectIsWindows()); // true/false
-console.log(osDetect.detectIsLinux()); // true/false
-console.log(osDetect.isMobileDevice()); // true/false
-console.log(osDetect.isDesktopDevice()); // true/false
+// Windows 11 via os.release() build number (>= 22000)
+const isWin11 = await detectIsWindows11();
 ```
 
-## API
+| `process.platform` | Detected as |
+|---|---|
+| `darwin` | macOS |
+| `win32` | Windows (32-bit and 64-bit) |
+| `linux` | Linux |
+| `android` | Android |
 
-- `detectIsiOS()`
-- `detectIsMacOS()`
-- `detectIsAndroid()`
-- `detectIsWindows()`
-- `detectIsLinux()`
-- `isMobileDevice()`
-- `isDesktopDevice()`
+Functions that require a browser environment (`detectIsIOS()`, `detectIsChromeOS()`) always return `false` in Node.js.
+
+> **SSR hydration note**: In Next.js / Nuxt SSR, `getOS()` returns the **server's** OS, not the client's. To avoid hydration mismatches, wrap detection in `useEffect` (React) or `onMounted` (Vue) so it runs only on the client.
+
+---
+
+## API Reference
+
+### OS String Detection
+
+| Function | Returns |
+|---|---|
+| `getOS()` | `'ios'` \| `'macos'` \| `'android'` \| `'windows'` \| `'linux'` \| `'chromeos'` \| `'unknown'` |
+
+### Boolean Detection
+
+| Function | Returns `true` when | Node.js |
+|---|---|---|
+| `detectIsIOS()` | iPhone, iPod, or iPad (including iPadOS 13+) | always `false` |
+| `detectIsMacOS()` | macOS desktop (excludes iPadOS 13+) | `process.platform === 'darwin'` |
+| `detectIsAndroid()` | Android phones and tablets | `process.platform === 'android'` |
+| `detectIsWindows()` | Windows desktop or laptop | `process.platform === 'win32'` |
+| `detectIsLinux()` | Linux desktop (excludes Android and ChromeOS) | `process.platform === 'linux'` |
+| `detectIsChromeOS()` | ChromeOS devices | always `false` |
+| `detectIsWindows11()` | Windows 11 — **async**, `Promise<boolean>` | via `os.release()` |
+
+### Device Category
+
+| Function | Returns `true` when |
+|---|---|
+| `isMobileDevice()` | iOS or Android |
+| `isDesktopDevice()` | macOS, Windows, Linux, or ChromeOS |
+
+> `isMobileDevice()` and `isDesktopDevice()` are **not mutually exclusive** — a device with an unrecognized OS returns `false` for both.
+
+### React Hooks
+
+Import from `os-detect/react`:
+
+| Hook | Returns |
+|---|---|
+| `useOS()` | `OS` string — synchronous, cached |
+| `useIsWindows11()` | `boolean \| null` — `null` while detecting |
+
+### Vue Composables
+
+Import from `os-detect/vue`:
+
+| Composable | Returns |
+|---|---|
+| `useOS()` | `Readonly<Ref<OS>>` — synchronous, cached |
+| `useIsWindows11()` | `Readonly<Ref<boolean \| null>>` — `null` while detecting |
+
+---
+
+## Detection Strategy
+
+**Browser**: prefers `navigator.userAgentData` (Chrome 90+ / Edge 90+), falls back to `navigator.userAgent` for all other browsers.
+
+**Node.js**: reads `process.platform` when `navigator` is absent.
+
+Results are cached after the first call — subsequent calls have zero overhead.
+
+`detectIsWindows11()` in the browser uses `userAgentData.getHighEntropyValues(['platformVersion'])` — Windows 11 reports `platformVersion >= 13.0.0`. In Node.js it uses `os.release()` — Windows 11 has build number `>= 22000`. Returns `false` if the API is unavailable or the call fails.
+
+### iPadOS 13+ note
+
+Since iPadOS 13, Safari sends `Macintosh` in the userAgent string. `detectIsIOS()` correctly identifies these devices using `navigator.maxTouchPoints > 1`, and `detectIsMacOS()` excludes them accordingly.
+
+---
+
+## Migration from v1.x
+
+`detectIsiOS()` was renamed to `detectIsIOS()`. The old name still works but logs a deprecation warning and will be removed in v3.0.
+
+```ts
+detectIsiOS()    // deprecated — logs console.warn
+detectIsIOS()    // use this instead
+```
 
-All functions return a boolean.
+---
 
 ## Author
 

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+declare function detectIsIOS(): boolean;
+declare function detectIsMacOS(): boolean;
+declare function detectIsAndroid(): boolean;
+declare function detectIsWindows(): boolean;
+declare function detectIsChromeOS(): boolean;
+declare function detectIsLinux(): boolean;
+declare function detectIsWindows11(): Promise<boolean>;
+type OS = 'ios' | 'macos' | 'android' | 'windows' | 'linux' | 'chromeos' | 'unknown';
+declare function getOS(): OS;
+declare function isMobileDevice(): boolean;
+declare function isDesktopDevice(): boolean;
+/** @deprecated Use detectIsIOS() instead. Will be removed in v3.0. */
+declare function detectIsiOS(): boolean;
+declare const osDetect: {
+    detectIsIOS: typeof detectIsIOS;
+    detectIsMacOS: typeof detectIsMacOS;
+    detectIsAndroid: typeof detectIsAndroid;
+    detectIsWindows: typeof detectIsWindows;
+    detectIsLinux: typeof detectIsLinux;
+    detectIsChromeOS: typeof detectIsChromeOS;
+    detectIsWindows11: typeof detectIsWindows11;
+    getOS: typeof getOS;
+    isMobileDevice: typeof isMobileDevice;
+    isDesktopDevice: typeof isDesktopDevice;
+    detectIsiOS: typeof detectIsiOS;
+};
+
+export { type OS, osDetect as default, detectIsAndroid, detectIsChromeOS, detectIsIOS, detectIsLinux, detectIsMacOS, detectIsWindows, detectIsWindows11, detectIsiOS, getOS, isDesktopDevice, isMobileDevice };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+declare function detectIsIOS(): boolean;
+declare function detectIsMacOS(): boolean;
+declare function detectIsAndroid(): boolean;
+declare function detectIsWindows(): boolean;
+declare function detectIsChromeOS(): boolean;
+declare function detectIsLinux(): boolean;
+declare function detectIsWindows11(): Promise<boolean>;
+type OS = 'ios' | 'macos' | 'android' | 'windows' | 'linux' | 'chromeos' | 'unknown';
+declare function getOS(): OS;
+declare function isMobileDevice(): boolean;
+declare function isDesktopDevice(): boolean;
+/** @deprecated Use detectIsIOS() instead. Will be removed in v3.0. */
+declare function detectIsiOS(): boolean;
+declare const osDetect: {
+    detectIsIOS: typeof detectIsIOS;
+    detectIsMacOS: typeof detectIsMacOS;
+    detectIsAndroid: typeof detectIsAndroid;
+    detectIsWindows: typeof detectIsWindows;
+    detectIsLinux: typeof detectIsLinux;
+    detectIsChromeOS: typeof detectIsChromeOS;
+    detectIsWindows11: typeof detectIsWindows11;
+    getOS: typeof getOS;
+    isMobileDevice: typeof isMobileDevice;
+    isDesktopDevice: typeof isDesktopDevice;
+    detectIsiOS: typeof detectIsiOS;
+};
+
+export { type OS, osDetect as default, detectIsAndroid, detectIsChromeOS, detectIsIOS, detectIsLinux, detectIsMacOS, detectIsWindows, detectIsWindows11, detectIsiOS, getOS, isDesktopDevice, isMobileDevice };

package/dist/index.js

@@ -0,0 +1,229 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  detectIsAndroid: () => detectIsAndroid,
+  detectIsChromeOS: () => detectIsChromeOS,
+  detectIsIOS: () => detectIsIOS,
+  detectIsLinux: () => detectIsLinux,
+  detectIsMacOS: () => detectIsMacOS,
+  detectIsWindows: () => detectIsWindows,
+  detectIsWindows11: () => detectIsWindows11,
+  detectIsiOS: () => detectIsiOS,
+  getOS: () => getOS,
+  isDesktopDevice: () => isDesktopDevice,
+  isMobileDevice: () => isMobileDevice
+});
+module.exports = __toCommonJS(index_exports);
+var cachedIsIOS;
+var cachedIsMacOS;
+var cachedIsAndroid;
+var cachedIsWindows;
+var cachedIsLinux;
+var cachedIsChromeOS;
+function getUADataPlatform() {
+  if (typeof navigator === "undefined") return null;
+  const uaData = navigator.userAgentData;
+  if (uaData && typeof uaData.platform === "string") {
+    return uaData.platform.toLowerCase();
+  }
+  return null;
+}
+function getNodePlatform() {
+  if (typeof navigator !== "undefined") return null;
+  if (typeof process === "undefined" || typeof process.platform !== "string") return null;
+  return process.platform;
+}
+function detectIsIOS() {
+  if (typeof cachedIsIOS === "boolean") return cachedIsIOS;
+  if (typeof navigator === "undefined" || typeof window === "undefined") {
+    return cachedIsIOS = false;
+  }
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsIOS = platform === "ios";
+    return cachedIsIOS;
+  }
+  const isClassicIOSUA = /iPhone|iPod/.test(navigator.userAgent);
+  const isIPadUA = /iPad/.test(navigator.userAgent);
+  const isIPadOS = /Macintosh/.test(navigator.userAgent) && typeof navigator.maxTouchPoints === "number" && navigator.maxTouchPoints > 1;
+  cachedIsIOS = isClassicIOSUA || isIPadUA || isIPadOS;
+  return cachedIsIOS;
+}
+function detectIsMacOS() {
+  if (typeof cachedIsMacOS === "boolean") return cachedIsMacOS;
+  const nodePlatform = getNodePlatform();
+  if (nodePlatform !== null) {
+    return cachedIsMacOS = nodePlatform === "darwin";
+  }
+  if (typeof navigator === "undefined") return cachedIsMacOS = false;
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsMacOS = platform === "macos";
+    return cachedIsMacOS;
+  }
+  const isMacUA = /Macintosh|MacIntel|MacPPC|Mac68K/.test(navigator.userAgent);
+  cachedIsMacOS = isMacUA && !detectIsIOS();
+  return cachedIsMacOS;
+}
+function detectIsAndroid() {
+  if (typeof cachedIsAndroid === "boolean") return cachedIsAndroid;
+  const nodePlatform = getNodePlatform();
+  if (nodePlatform !== null) {
+    return cachedIsAndroid = nodePlatform === "android";
+  }
+  if (typeof navigator === "undefined") return cachedIsAndroid = false;
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsAndroid = platform === "android";
+    return cachedIsAndroid;
+  }
+  cachedIsAndroid = /Android/.test(navigator.userAgent);
+  return cachedIsAndroid;
+}
+function detectIsWindows() {
+  if (typeof cachedIsWindows === "boolean") return cachedIsWindows;
+  const nodePlatform = getNodePlatform();
+  if (nodePlatform !== null) {
+    return cachedIsWindows = nodePlatform === "win32";
+  }
+  if (typeof navigator === "undefined") return cachedIsWindows = false;
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsWindows = platform === "windows";
+    return cachedIsWindows;
+  }
+  cachedIsWindows = /Win32|Win64|Windows|WinCE/.test(navigator.userAgent);
+  return cachedIsWindows;
+}
+function detectIsChromeOS() {
+  if (typeof cachedIsChromeOS === "boolean") return cachedIsChromeOS;
+  if (typeof navigator === "undefined") return cachedIsChromeOS = false;
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsChromeOS = platform === "chrome os" || platform === "chromeos";
+    return cachedIsChromeOS;
+  }
+  cachedIsChromeOS = /CrOS/.test(navigator.userAgent);
+  return cachedIsChromeOS;
+}
+function detectIsLinux() {
+  if (typeof cachedIsLinux === "boolean") return cachedIsLinux;
+  const nodePlatform = getNodePlatform();
+  if (nodePlatform !== null) {
+    return cachedIsLinux = nodePlatform === "linux";
+  }
+  if (typeof navigator === "undefined") return cachedIsLinux = false;
+  const platform = getUADataPlatform();
+  if (platform !== null) {
+    cachedIsLinux = platform === "linux";
+    return cachedIsLinux;
+  }
+  cachedIsLinux = /Linux/.test(navigator.userAgent) && !detectIsAndroid() && !detectIsChromeOS();
+  return cachedIsLinux;
+}
+async function detectIsWindows11() {
+  var _a, _b;
+  if (!detectIsWindows()) return false;
+  if (typeof navigator === "undefined" && typeof process !== "undefined") {
+    try {
+      const { release } = await import("os");
+      const buildNumber = parseInt((_a = release().split(".")[2]) != null ? _a : "0", 10);
+      return buildNumber >= 22e3;
+    } catch (e) {
+      return false;
+    }
+  }
+  try {
+    const nav = navigator;
+    if (!((_b = nav.userAgentData) == null ? void 0 : _b.getHighEntropyValues)) return false;
+    const { platformVersion } = await nav.userAgentData.getHighEntropyValues([
+      "platformVersion"
+    ]);
+    if (!platformVersion) return false;
+    const majorVersion = parseInt(platformVersion.split(".")[0], 10);
+    return majorVersion >= 13;
+  } catch (e) {
+    return false;
+  }
+}
+function getOS() {
+  if (detectIsIOS()) return "ios";
+  if (detectIsAndroid()) return "android";
+  if (detectIsChromeOS()) return "chromeos";
+  if (detectIsLinux()) return "linux";
+  if (detectIsMacOS()) return "macos";
+  if (detectIsWindows()) return "windows";
+  return "unknown";
+}
+function isMobileDevice() {
+  return detectIsIOS() || detectIsAndroid();
+}
+function isDesktopDevice() {
+  return detectIsMacOS() || detectIsWindows() || detectIsLinux() || detectIsChromeOS();
+}
+function detectIsiOS() {
+  if (typeof console !== "undefined") {
+    console.warn(
+      "[os-detect] detectIsiOS() is deprecated. Use detectIsIOS() instead. Will be removed in v3.0."
+    );
+  }
+  return detectIsIOS();
+}
+var osDetect = {
+  detectIsIOS,
+  detectIsMacOS,
+  detectIsAndroid,
+  detectIsWindows,
+  detectIsLinux,
+  detectIsChromeOS,
+  detectIsWindows11,
+  getOS,
+  isMobileDevice,
+  isDesktopDevice,
+  detectIsiOS
+};
+var index_default = osDetect;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  detectIsAndroid,
+  detectIsChromeOS,
+  detectIsIOS,
+  detectIsLinux,
+  detectIsMacOS,
+  detectIsWindows,
+  detectIsWindows11,
+  detectIsiOS,
+  getOS,
+  isDesktopDevice,
+  isMobileDevice
+});