@sv443-network/userutils 10.0.5 → 10.1.0

package/dist/lib/consts.d.ts

@@ -0,0 +1,7 @@
+/** Contains the semver version strings of UserUtils and the bundled library CoreUtils. */
+export declare const versions: {
+    /** Semver version string of the bundled library CoreUtils. */
+    CoreUtils: string;
+    /** Semver version string of UserUtils. */
+    UserUtils: string;
+};

package/dist/lib/index.d.ts

@@ -3,6 +3,7 @@
  * UserUtils is a lightweight library with various utilities for userscripts, allowing you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more  
  */
 export * from "@sv443-network/coreutils";
+export * from "./consts.js";
 export * from "./Dialog.js";
 export * from "./dom.js";
 export * from "./Errors.js";

package/dist/lib/translation.d.ts

@@ -54,6 +54,10 @@ export type TransformTuple<TTrKey extends string = string> = [RegExp, TransformF
 export type TrKeys<TTrObj, P extends string = ""> = {
     [K in keyof TTrObj]: K extends string | number | boolean | null | undefined ? TTrObj[K] extends object ? TrKeys<TTrObj[K], `${P}${K}.`> : `${P}${K}` : never;
 }[keyof TTrObj];
+/** All translations loaded into memory */
+declare const trans: {
+    [language: string]: TrObject;
+};
 /**
  * Returns the translated text for the specified key in the specified language.  
  * If the key is not found in the specified previously registered translation, the key itself is returned.  
@@ -84,10 +88,11 @@ declare function useTr<TTrKey extends string = string>(language: string): (key:
  */
 declare function hasKey<TTrKey extends string = string>(language: string | undefined, key: TTrKey): boolean;
 /**
- * Registers a new language and its translations - if the language already exists, it will be overwritten.  
+ * Registers a new language and its translations - if the language already exists, it will be wholly replaced by the new one. If merging is necessary, it will have to be done before calling this function.  
+ *  
  * The translations are a key-value pair where the key is the translation key and the value is the translated text.  
  * The translations can also be infinitely nested objects, resulting in a dot-separated key.  
- * @param language Language code or name to register - I recommend sticking to a standard like [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag)  
+ * @param language Arbitrary language code or name to register for these translations. These should ideally stick to a standard like [IETF BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) (the standard used by JavaScript), but could really be anything.  
  * @param translations Translations for the specified language  
  * @example ```ts  
  * tr.addTranslations("en", {  
@@ -106,6 +111,11 @@ declare function addTranslations(language: string, translations: TrObject): void
  * @returns Translations for the specified language  
  */
 declare function getTranslations(language?: string): TrObject | undefined;
+/**
+ * Returns all translations currently loaded into memory, indexed by language.  
+ * @param asCopy Set to `false` to get a reference to the actual translations object instead of a copy (default). Might be useful for modifying translations in-memory without using {@linkcode tr.addTranslations()} to replace the entire object.  
+ */
+declare function getAllTranslations(asCopy?: boolean): typeof trans;
 /**
  * The fallback language to use when a translation key is not found in the currently active language.  
  * Leave undefined to disable fallbacks and just return the translation key if translations are not found.  
@@ -172,13 +182,81 @@ declare const tr: {
     hasKey: <TTrKey extends string = string>(language: string | undefined, key: TTrKey) => ReturnType<typeof hasKey<TTrKey>>;
     addTranslations: typeof addTranslations;
     getTranslations: typeof getTranslations;
+    getAllTranslations: typeof getAllTranslations;
     deleteTranslations: (language: string) => boolean;
     setFallbackLanguage: typeof setFallbackLanguage;
     getFallbackLanguage: typeof getFallbackLanguage;
     addTransform: typeof addTransform;
     deleteTransform: typeof deleteTransform;
+    /** Collection of predefined transform functions that can be added via {@linkcode tr.addTransform()} */
     transforms: {
+        /**
+         * This transform will replace placeholders matching `${key}` with the value of the passed argument(s).  
+         * The arguments can be passed in keyed object form or positionally via the spread operator:  
+         * - Keyed: If the first argument is an object and `key` is found in it, the value will be used for the replacement.  
+         * - Positional: If the first argument is not an object or has a `toString()` method that returns something that doesn't start with `[object`, the values will be positionally inserted in the order they were passed.  
+         *  
+         * @example ```ts  
+         * tr.addTranslations("en", {  
+         *  "greeting": "Hello, ${user}!\nYou have ${notifs} notifications.",  
+         * });  
+         * tr.addTransform(tr.transforms.templateLiteral);  
+         *  
+         * const t = tr.use("en");  
+         *  
+         * // both calls return the same result:  
+         * t("greeting", { user: "John", notifs: 5 }); // "Hello, John!\nYou have 5 notifications."  
+         * t("greeting", "John", 5);                   // "Hello, John!\nYou have 5 notifications."  
+         *  
+         * // when a key isn't found in the object, it will be left as-is:  
+         * t("greeting", { user: "John" }); // "Hello, John!\nYou have ${notifs} notifications."  
+         * ```  
+         */
         templateLiteral: TransformTuple<string>;
+        /**
+         * This transform will replace placeholders matching `{{key}}` with the value of the passed argument(s).  
+         * This format is commonly used in i18n libraries. Note that advanced syntax is not supported, only simple key replacement.  
+         * The arguments can be passed in keyed object form or positionally via the spread operator:  
+         * - Keyed: If the first argument is an object and `key` is found in it, the value will be used for the replacement.  
+         * - Positional: If the first argument is not an object or has a `toString()` method that returns something that doesn't start with `[object`, the values will be positionally inserted in the order they were passed.  
+         *  
+         * @example ```ts  
+         * tr.addTranslations("en", {  
+         *  "greeting": "Hello, {{user}}!\nYou have {{notifs}} notifications.",  
+         * });  
+         * tr.addTransform(tr.transforms.i18n);  
+         *  
+         * const t = tr.use("en");  
+         *  
+         * // both calls return the same result:  
+         * t("greeting", { user: "Alice", notifs: 5 }); // "Hello, Alice!\nYou have 5 notifications."  
+         * t("greeting", "Alice", 5);                   // "Hello, Alice!\nYou have 5 notifications."  
+         *  
+         * // when a key isn't found in the object, it will be left as-is:  
+         * t("greeting", { user: "Alice" }); // "Hello, Alice!\nYou have {{notifs}} notifications."  
+         * ```  
+         */
+        i18n: TransformTuple<string>;
+        /**
+         * This transform will replace `%n` placeholders with the value of the passed arguments.  
+         * The `%n` placeholders are 1-indexed, meaning `%1` will be replaced by the first argument (index 0), `%2` by the second (index 1), and so on.  
+         * Objects will be stringified via `String()` before being inserted.  
+         *  
+         * @example ```ts  
+         * tr.addTranslations("en", {  
+         *  "greeting": "Hello, %1!\nYou have %2 notifications.",  
+         * });  
+         * tr.addTransform(tr.transforms.percent);  
+         *  
+         * const t = tr.use("en");  
+         *  
+         * // arguments are inserted in the order they're passed:  
+         * t("greeting", "Bob", 5); // "Hello, Bob!\nYou have 5 notifications."  
+         *  
+         * // when a value isn't found, the placeholder will be left as-is:  
+         * t("greeting", "Bob"); // "Hello, Bob!\nYou have %2 notifications."  
+         * ```  
+         */
         percent: TransformTuple<string>;
     };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sv443-network/userutils",
   "libName": "UserUtils",
-  "version": "10.0.5",
+  "version": "10.1.0",
   "description": "General purpose DOM/GreaseMonkey library that allows you to register listeners for when CSS selectors exist, intercept events, create persistent & synchronous data stores, modify the DOM more easily and much more",
   "main": "dist/UserUtils.mjs",
   "module": "dist/UserUtils.mjs",
@@ -33,7 +33,7 @@
   },
   "homepage": "https://github.com/Sv443-Network/UserUtils",
   "dependencies": {
-    "@sv443-network/coreutils": "3.0.4",
+    "@sv443-network/coreutils": "3.3.0",
     "nanoevents": "9.1.0"
   },
   "devDependencies": {
@@ -55,7 +55,6 @@
     "express": "4.22.1",
     "globals": "15.15.0",
     "jsdom": "26.1.0",
-    "kleur": "4.1.5",
     "tslib": "2.8.1",
     "tsup": "8.5.1",
     "tsx": "4.21.0",
@@ -87,7 +86,7 @@
     "test-gm-serve": "node --import tsx ./test/TestPage/server.mts",
     "test-gm-dev": "cd test/TestScript && pnpm dev",
     "test-gm": "concurrently \"pnpm test-gm-serve\" \"pnpm test-gm-dev\"",
-    "test": "vitest",
-    "test-coverage": "vitest --coverage"
+    "test": "pnpm build && vitest",
+    "test-coverage": "pnpm build && vitest --coverage"
   }
 }