@sv443-network/userutils 8.3.2 → 8.3.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @sv443-network/userutils
 
+## 8.3.3
+
+### Patch Changes
+
+- ca8b62e: Made CJS bundle available on NPM too
+
 ## 8.3.2
 
 ### Patch Changes

package/README.md

@@ -5,9 +5,19 @@
 Lightweight library with various utilities for userscripts - register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and more.  
   
 Contains builtin TypeScript declarations. Supports ESM and CJS imports via a bundler and global declaration via `@require`  
+  
+You may want to check out my [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
 If you like using this library, please consider [supporting the development ❤️](https://github.com/sponsors/Sv443)
 
 <br>
+
+[![minified bundle size badge](https://badgen.net/bundlephobia/min/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![minified and gzipped bundle size badge](https://badgen.net/bundlephobia/minzip/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+[![tree shaking support badge](https://badgen.net/bundlephobia/tree-shaking/@sv443-network/userutils)](https://bundlephobia.com/package/@sv443-network/userutils)
+
+[![github stargazers badge](https://badgen.net/github/stars/Sv443-Network/UserUtils?icon=github)](https://github.com/Sv443-Network/UserUtils/stargazers)
+[![discord server badge](https://badgen.net/discord/online-members/aBH4uRG?icon=discord)](https://dc.sv443.net/)
+
 <sup>
 View the documentation of previous major releases:
 </sup>
@@ -86,12 +96,16 @@ View the documentation of previous major releases:
 ## Installation:
 Shameless plug: I made a [template for userscripts in TypeScript](https://github.com/Sv443/Userscript.ts) that you can use to get started quickly. It also includes this library by default.  
   
-- If you are using a bundler (like webpack, rollup, vite, etc.), you can install this package using npm:
+- If you are using a bundler (like webpack, rollup, vite, etc.), you can install this package in one of the following ways:
   ```
   npm i @sv443-network/userutils
+  pnpm i @sv443-network/userutils
+  yarn add @sv443-network/userutils
+  npx jsr install @sv443-network/userutils
+  deno add jsr:@sv443-network/userutils
   ```
-  <sup>For other package managers, check out the respective install command on the [JavaScript Registry](https://jsr.io/@sv443-network/userutils)</sup>  
-  Then, import it in your script as usual:
+  Then import it in your script as usual:  
+  
   ```ts
   import { addGlobalStyle } from "@sv443-network/userutils";
 
@@ -102,16 +116,26 @@ Shameless plug: I made a [template for userscripts in TypeScript](https://github
 
 <br>
 
-- If you are not using a bundler or want to reduce the size of your userscript, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
+- If you are not using a bundler, want to reduce the size of your userscript, or declared the package as external in your bundler, you can include the latest release by adding one of these directives to the userscript header, depending on your preferred CDN:
+  
+  Versioned (recommended):
   ```
-  // @require https://greasyfork.org/scripts/472956-userutils/code/UserUtils.js
+  // @require https://cdn.jsdelivr.net/npm/@sv443-network/userutils@INSERT_VERSION/dist/index.global.js
+  // @require https://unpkg.com/@sv443-network/userutils@INSERT_VERSION/dist/index.global.js
   ```
+  Non-versioned (not recommended because auto-updating):
   ```
+  // @require https://update.greasyfork.org/scripts/472956/UserUtils.js
   // @require https://openuserjs.org/src/libs/Sv443/UserUtils.js
   ```
-  (in order for your userscript not to break on a major library update, instead use the versioned URL at the top of the [GreasyFork page](https://greasyfork.org/scripts/472956-userutils))  
     
-  Then, access the functions on the global variable `UserUtils`:
+> [!NOTE]  
+> In order for your userscript not to break on a major library update, use one the versioned URLs above after replacing `INSERT_VERSION` with the desired version (e.g. `8.3.2`) or the versioned URL that's shown at the top of the [GreasyFork page.](https://greasyfork.org/scripts/472956-userutils)  
+
+<br>
+
+- Then, access the functions on the global variable `UserUtils`:
+  
   ```ts
   UserUtils.addGlobalStyle("body { background-color: red; }");
 
@@ -120,10 +144,27 @@ Shameless plug: I made a [template for userscripts in TypeScript](https://github
   const { clamp } = UserUtils;
   console.log(clamp(1, 5, 10)); // 5
   ```
-  If you're using TypeScript and it complains about the missing global variable `UserUtils`, install the library using the package manager of your choice and add the following inside a `.d.ts` file somewhere in your project:
+
+<br>
+
+- If you're using TypeScript and it complains about the missing global variable `UserUtils`, install the library using the package manager of your choice and add the following inside a `.d.ts` file somewhere in the directory (or a subdirectory) defined in your `tsconfig.json`'s `baseUrl` option or `include` array:  
+  
   ```ts
+  declare const UserUtils: typeof import("@sv443-network/userutils");
+
   declare global {
-    const UserUtils: typeof import("@sv443-network/userutils");
+    interface Window {
+      UserUtils: typeof UserUtils;
+    }
+  }
+  ```
+
+<br>
+
+- If you're using a linter like ESLint, it might complain about the global variable `UserUtils` not being defined. To fix this, add the following to your ESLint configuration file:
+  ```json
+  "globals": {
+      "UserUtils": "readonly"
   }
   ```
 
@@ -137,8 +178,11 @@ Each feature has example code that can be expanded by clicking on the text "Exam
 The usages and examples are written in TypeScript and use ESM import syntax, but the library can also be used in plain JavaScript after removing the type annotations (and changing the imports if you are using CommonJS or the global declaration).  
 If the usage section contains multiple usages of the function, each occurrence represents an overload and you can choose which one you want to use.  
   
-Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other requirements.  
-Their documentation will contain a section marked by a warning emoji (⚠️) that will go into more detail.
+Some features require the `@run-at` or `@grant` directives to be tweaked in the userscript header or have other specific requirements and limitations.  
+Those will be listed in a section marked by a warning emoji (⚠️) each.  
+  
+If you need help with something, please [create a new discussion](https://github.com/Sv443-Network/UserUtils/discussions) or [join my Discord server.](https://dc.sv443.net/)  
+For submitting bug reports or feature requests, please use the [GitHub issue tracker.](https://github.com/Sv443-Network/UserUtils/issues)
 
 <br><br>
 
@@ -2167,8 +2211,8 @@ tr.addLanguage("de", {
 // the language is set to "en"
 tr.setLanguage("en");
 
-console.log(tr("welcome_name", "John"));               // "Welcome"
-// the language doesn't need to be changed:
+console.log(tr("welcome_name", "John"));               // "Welcome, John"
+// no need to call tr.setLanguage():
 console.log(tr.forLang("de", "welcome_name", "John")); // "Willkommen, John"
 ```
 </details>
@@ -2181,9 +2225,9 @@ Usage:
 tr.addLanguage(language: string, translations: Record<string, string>): void
 ```
 
-Adds a language and its associated translations to the translation function.  
-The passed language can be any unique identifier, though I recommend sticking to the [ISO 639-1 standard.](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)  
-The passed translations should be an object where the key is the translation key used in `tr()` and the value is the translation itself.  
+Adds or overwrites a language and its associated translations to the translation function.  
+The passed language can be any unique identifier, though I highly recommend sticking to a standard like [BCP 47 / RFC 5646](https://www.rfc-editor.org/rfc/rfc5646.txt) (which is used by the [`Intl` namespace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) and methods like [`Number.toLocaleString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString)), or [ISO 639-1.](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)  
+The passed translations should be a flat object (no nested objects are allowed for now), where the key is the translation key used in `tr()` and the value is the translation itself.  
 If `tr.addLanguage()` is called multiple times with the same language, the previous translations of that language will be overwritten.  
   
 The translation values may contain placeholders in the format `%n`, where `n` is the number of the value starting at 1.  
@@ -2213,10 +2257,13 @@ tr.addLanguage("en", {
 // can be used for different locales too:
 
 tr.addLanguage("en-US", {
-  "fries": "french fries",
+  "fries": "fries",
+  "color": "color",
 });
+
 tr.addLanguage("en-GB", {
   "fries": "chips",
+  "color": "colour",
 });
 
 
@@ -2226,15 +2273,18 @@ const translation_de = {
   "greeting": "Guten Tag!",
   "foo": "Foo",
 };
+
 tr.addLanguage("de-DE", translation_de);
+
 tr.addLanguage("de-CH", {
+  // overwrite the "greeting" but keep other keys as they are:
   ...translation_de,
-  // overwrite the "greeting" but keep other keys as they are
   "greeting": "Grüezi!",
 });
+
 tr.addLanguage("de-AT", {
+  // overwrite "greeting" again but keep other keys as they are:
   ...translation_de,
-  // overwrite "greeting" again but keep other keys as they are
   "greeting": "Grüß Gott!",
 });
 
@@ -2247,17 +2297,23 @@ tr.addLanguage("en", {
   "cart_items_added-n": "Added %1 items to the cart",
 });
 
-/** Returns the translation key with a custom pluralization identifier added to it for the given number of items (or size of Array/NodeList or anything else with a `length` property) */
-function pl(key: string, num: number | Array<unknown> | NodeList | { length: number }) {
-  if(typeof num !== "number")
-    num = num.length;
+type Numberish = number | Array<unknown> | NodeList | { length: number } | { size: number };
+
+/** Returns the translation key with a custom pluralization identifier added to it for the given number of items (or size of Array/NodeList or anything else with a `length` or `size` property) */
+function pl(key: string, num: Numberish): string {
+  if(typeof num !== "number") {
+    if("length" in num)
+      num = num.length;
+    else if("size" in num)
+      num = num.size;
+  }
 
   if(num === 0)
     return `${key}-0`;
   else if(num === 1)
     return `${key}-1`;
   else
-    return `${key}-n`;
+    return `${key}-n`; // will also be the fallback for non-numeric values
 };
 
 const items = [];
@@ -2268,6 +2324,9 @@ console.log(tr(pl("cart_items_added", items), items.length)); // "Added 1 item t
 
 items.push("bar");
 console.log(tr(pl("cart_items_added", items), items.length)); // "Added 2 items to the cart"
+
+// you will need to catch cases like this manually or in your own implementation of `pl()`:
+console.log(tr(pl("cart_items_added", NaN), NaN)); // "Added NaN items to the cart"
 ```
 </details>