@canonical/utils 0.11.0 → 0.12.0

package/README.md

@@ -1,7 +1,100 @@
-## Canonical Web Team Utils
+# @canonical/utils
 
-This package contains a collection of utilities that are used across the Canonical Web Team's projects.
+Utility functions for the Pragma design system. This package contains battle-tested helpers that have proven useful across multiple packages.
 
-### Utils list
-- [debounce](./src/debounce/README.md)
-- [throttle](./src/throttle/README.md)
+## Installation
+
+```bash
+bun add @canonical/utils
+```
+
+## Available Functions
+
+### debounce
+
+Creates a debounced version of a function that waits until a specified delay has passed since the last call before executing. Useful for search inputs, resize handlers, and other high-frequency events.
+
+```typescript
+import { debounce } from "@canonical/utils";
+
+const debouncedSearch = debounce(async (query: string) => {
+  const response = await fetch(`/api/search?q=${query}`);
+  return response.json();
+}, 300);
+
+// Multiple rapid calls result in only one execution
+await debouncedSearch("hello"); // Cancelled by next call
+await debouncedSearch("hello w"); // Cancelled by next call
+await debouncedSearch("hello world"); // Executes after 300ms
+
+// Cancel a pending execution
+const promise = debouncedSearch("query");
+promise.cancel();
+```
+
+The debounced function returns a promise and includes a `cancel` method. Each new call cancels any pending execution from previous calls.
+
+### throttle
+
+Throttles a function to execute at most once per specified interval. Useful for scroll handlers, continuous input events, and rate-limited operations.
+
+```typescript
+import { throttle } from "@canonical/utils";
+
+const throttledResize = throttle(() => {
+  console.log("Window resized");
+}, 500);
+
+window.addEventListener("resize", throttledResize);
+// Logs at most once every 500ms during continuous resizing
+```
+
+### humanizeNumber
+
+Formats numbers for human readability with appropriate suffixes and precision.
+
+```typescript
+import { humanizeNumber } from "@canonical/utils";
+
+humanizeNumber(1234); // "1.2K"
+humanizeNumber(1234567); // "1.2M"
+```
+
+### pluralize
+
+Returns the singular or plural form of a word based on a count.
+
+```typescript
+import { pluralize } from "@canonical/utils";
+
+pluralize(1, "item", "items"); // "item"
+pluralize(5, "item", "items"); // "items"
+```
+
+### casing
+
+Converts strings between different case conventions.
+
+```typescript
+import { casing } from "@canonical/utils";
+
+casing.toCamelCase("hello-world"); // "helloWorld"
+casing.toKebabCase("helloWorld"); // "hello-world"
+```
+
+### invariant
+
+Throws an error if a condition is false. Useful for asserting assumptions in code.
+
+```typescript
+import { invariant } from "@canonical/utils";
+
+invariant(user != null, "User must be defined");
+// TypeScript now knows user is not null
+```
+
+## Design Philosophy
+
+Functions only enter this package after proving useful across multiple packages. Premature abstraction is actively avoided. If a utility is only needed in one place, it belongs in that package until a second use case emerges.
+
+Each function is fully typed with comprehensive JSDoc comments. The package has no runtime dependencies, keeping bundle impact minimal.

package/dist/esm/index.js

@@ -2,6 +2,7 @@ export { default as casing } from "./casing.js";
 export { default as debounce } from "./debounce.js";
 export { default as humanizeNumber } from "./humanizeNumber/index.js";
 export { default as invariant } from "./invariant.js";
+export * from "./navigation/index.js";
 export { default as pluralize } from "./pluralize/index.js";
 export { default as throttle } from "./throttle.js";
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGpD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGpD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtD,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/navigation/annotateTree.js

@@ -0,0 +1,24 @@
+import { getItemId } from "./getItemId.js";
+/**
+ * Annotate a navigation tree with parent references and depth
+ *
+ * Transforms Item tree into _Item tree with parentUrl and depth.
+ *
+ * @param root - The root item to annotate
+ * @param parentUrl - Parent URL (null for root)
+ * @param depth - Current depth (0 for root)
+ * @returns Annotated item tree
+ */
+export function annotateTree(root, parentUrl = null, depth = 0) {
+    const { items, ...rest } = root;
+    const annotated = {
+        ...rest,
+        parentUrl,
+        depth,
+    };
+    if (items) {
+        annotated.items = items.map((child) => annotateTree(child, getItemId(root), depth + 1));
+    }
+    return annotated;
+}
+//# sourceMappingURL=annotateTree.js.map

package/dist/esm/navigation/annotateTree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotateTree.js","sourceRoot":"","sources":["../../../src/navigation/annotateTree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAU,EACV,YAA2B,IAAI,EAC/B,KAAK,GAAG,CAAC;IAET,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAChC,MAAM,SAAS,GAAU;QACvB,GAAG,IAAI;QACP,SAAS;QACT,KAAK;KACN,CAAC;IACF,IAAI,KAAK,EAAE,CAAC;QACV,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACpC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAChD,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/esm/navigation/getItemId.js

@@ -0,0 +1,15 @@
+/**
+ * Get the unique identifier for a navigation item (url or key)
+ *
+ * @param item - The navigation item
+ * @returns The item's url or key
+ * @throws Error if item has neither url nor key
+ */
+export function getItemId(item) {
+    if (item.url)
+        return item.url;
+    if (item.key)
+        return item.key;
+    throw new Error("Item must have either url or key");
+}
+//# sourceMappingURL=getItemId.js.map

package/dist/esm/navigation/getItemId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getItemId.js","sourceRoot":"","sources":["../../../src/navigation/getItemId.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAkB;IAC1C,IAAI,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC;IAC9B,IAAI,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC;IAC9B,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;AACtD,CAAC"}

package/dist/esm/navigation/index.js

@@ -0,0 +1,4 @@
+export { annotateTree } from "./annotateTree.js";
+export { getItemId } from "./getItemId.js";
+export { prepareIndex } from "./prepareIndex.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/navigation/prepareIndex.js

@@ -0,0 +1,25 @@
+import { getItemId } from "./getItemId.js";
+/**
+ * Create an index for O(1) lookup of navigation items by URL or key
+ *
+ * @param root - The annotated root item
+ * @returns Index mapping URL/key to item
+ */
+export function prepareIndex(root) {
+    const index = {};
+    const stack = [root];
+    while (stack.length > 0) {
+        const item = stack.pop();
+        if (!item)
+            continue;
+        const id = getItemId(item);
+        index[id] = item;
+        if (item.items) {
+            for (let i = item.items.length - 1; i >= 0; i--) {
+                stack.push(item.items[i]);
+            }
+        }
+    }
+    return index;
+}
+//# sourceMappingURL=prepareIndex.js.map

package/dist/esm/navigation/prepareIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareIndex.js","sourceRoot":"","sources":["../../../src/navigation/prepareIndex.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAW;IACtC,MAAM,KAAK,GAAW,EAAE,CAAC;IACzB,MAAM,KAAK,GAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export { default as debounce } from "./debounce.js";
 export type * from "./humanizeNumber/index.js";
 export { default as humanizeNumber } from "./humanizeNumber/index.js";
 export { default as invariant } from "./invariant.js";
+export * from "./navigation/index.js";
 export type * from "./pluralize/index.js";
 export { default as pluralize } from "./pluralize/index.js";
 export { default as throttle } from "./throttle.js";

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpD,mBAAmB,2BAA2B,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACtD,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpD,mBAAmB,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpD,mBAAmB,2BAA2B,CAAC;AAC/C,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtD,cAAc,uBAAuB,CAAC;AAEtC,mBAAmB,sBAAsB,CAAC;AAC1C,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAE5D,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpD,mBAAmB,YAAY,CAAC"}

package/dist/types/navigation/annotateTree.d.ts

@@ -0,0 +1,13 @@
+import type { _Item, Item } from "@canonical/ds-types";
+/**
+ * Annotate a navigation tree with parent references and depth
+ *
+ * Transforms Item tree into _Item tree with parentUrl and depth.
+ *
+ * @param root - The root item to annotate
+ * @param parentUrl - Parent URL (null for root)
+ * @param depth - Current depth (0 for root)
+ * @returns Annotated item tree
+ */
+export declare function annotateTree(root: Item, parentUrl?: string | null, depth?: number): _Item;
+//# sourceMappingURL=annotateTree.d.ts.map

package/dist/types/navigation/annotateTree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotateTree.d.ts","sourceRoot":"","sources":["../../../src/navigation/annotateTree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAGvD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,SAAS,GAAE,MAAM,GAAG,IAAW,EAC/B,KAAK,SAAI,GACR,KAAK,CAaP"}

package/dist/types/navigation/getItemId.d.ts

@@ -0,0 +1,10 @@
+import type { _Item, Item } from "@canonical/ds-types";
+/**
+ * Get the unique identifier for a navigation item (url or key)
+ *
+ * @param item - The navigation item
+ * @returns The item's url or key
+ * @throws Error if item has neither url nor key
+ */
+export declare function getItemId(item: Item | _Item): string;
+//# sourceMappingURL=getItemId.d.ts.map

package/dist/types/navigation/getItemId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getItemId.d.ts","sourceRoot":"","sources":["../../../src/navigation/getItemId.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,MAAM,CAIpD"}

package/dist/types/navigation/index.d.ts

@@ -0,0 +1,4 @@
+export { annotateTree } from "./annotateTree.js";
+export { getItemId } from "./getItemId.js";
+export { prepareIndex } from "./prepareIndex.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/navigation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/navigation/prepareIndex.d.ts

@@ -0,0 +1,9 @@
+import type { _Index, _Item } from "@canonical/ds-types";
+/**
+ * Create an index for O(1) lookup of navigation items by URL or key
+ *
+ * @param root - The annotated root item
+ * @returns Index mapping URL/key to item
+ */
+export declare function prepareIndex(root: _Item): _Index;
+//# sourceMappingURL=prepareIndex.d.ts.map

package/dist/types/navigation/prepareIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareIndex.d.ts","sourceRoot":"","sources":["../../../src/navigation/prepareIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAehD"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/utils",
   "description": "Standard utility functions for Canonical's Web Engineering team",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -41,15 +41,18 @@
     "test:vitest": "vitest run",
     "test:vitest:watch": "vitest"
   },
+  "dependencies": {
+    "@canonical/ds-types": "^0.12.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.3.11",
-    "@canonical/biome-config": "^0.11.0",
-    "@canonical/typescript-config-base": "^0.11.0",
-    "@canonical/webarchitect": "^0.11.0",
+    "@canonical/biome-config": "^0.12.0",
+    "@canonical/typescript-config-base": "^0.12.0",
+    "@canonical/webarchitect": "^0.12.0",
     "globals": "^17.0.0",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vitest": "^4.0.17"
   },
-  "gitHead": "29125736059d1880b3d0fc277b218a63a2574f28"
+  "gitHead": "0b491caff8f797fef4ba4b7f5514a7c5b915a481"
 }