@gumbee/utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Mugeeb Hassan
+
+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

@@ -0,0 +1,78 @@
+# @gumbee/utils
+
+<div align="left">
+
+[![npm version](https://img.shields.io/npm/v/@gumbee/utils.svg)](https://www.npmjs.com/package/@gumbee/utils)
+[![License](https://img.shields.io/npm/l/@gumbee/utils.svg)](package.json)
+
+</div>
+
+@gumbee/utils is a collection of shared utilities designed primarily for the [Gumbee](https://github.com/Gumbee/gumbee) ecosystem. It provides essential helpers for logging, math operations, and other common tasks used across Gumbee packages.
+
+While this package is intended for internal use within the Gumbee codebase, it is published publicly and can be used in other projects if found useful.
+
+The canonical source tree and bug trackers are available on [GitHub](https://github.com/Gumbee/gumbee).
+For license information, see [LICENSE](LICENSE) (MIT).
+
+## Installation
+
+```bash
+bun add @gumbee/utils
+# npm install @gumbee/utils
+# pnpm add @gumbee/utils
+# yarn add @gumbee/utils
+```
+
+## Documentation
+
+- [Logging](docs/LOGGING.md) - Styled console logging with colored owner labels and environment-aware filtering.
+- [Math](docs/MATH.md) - Numeric utilities for common calculations.
+
+## Configuration
+
+The logging utility supports environment-aware filtering using the `LOG_WHITELIST` environment variable (or framework-specific equivalents like `NEXT_PUBLIC_LOG_WHITELIST` or `VITE_LOG_WHITELIST`). See [Logging](docs/LOGGING.md#configuration) for details.
+
+## Development
+
+For build information, check the `package.json` scripts.
+This package is part of the Gumbee ecosystem of packages used by myself to build various personal projects and ideas.
+
+To report bugs or submit patches please use [GitHub issues](https://github.com/gumbee/utils/issues).
+
+## Releasing
+
+This package uses [changesets](https://github.com/changesets/changesets) for version management and GitHub Actions for automated publishing.
+
+### Creating a Changeset
+
+When you make changes that should be released, create a changeset:
+
+```bash
+bun changeset
+```
+
+This will prompt you to:
+
+1. Select the type of change (patch, minor, major)
+2. Write a summary of the changes
+
+Commit the generated changeset file (in `.changeset/`) with your changes.
+
+### Publishing a Release
+
+When ready to release:
+
+```bash
+# 1. Apply changesets to bump version and update CHANGELOG
+bun run version
+
+# 2. Commit the version bump
+git add .
+git commit -m "chore: release v1.x.x"
+
+# 3. Create and push the tag
+git tag v1.x.x
+git push origin main --tags
+```
+
+The GitHub Actions workflow will automatically build, test, and publish to npm when the tag is pushed.

package/dist/index.cjs

@@ -0,0 +1,173 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  logWarn: () => logWarn,
+  logError: () => logError,
+  log: () => log,
+  clamp: () => clamp,
+  Emitter: () => Emitter
+});
+module.exports = __toCommonJS(exports_src);
+
+// src/math.ts
+var clamp = (value, min, max) => {
+  return Math.min(Math.max(value, min), max);
+};
+// src/log.ts
+var colors = [
+  { primary: "#003f5c", text: "white" },
+  { primary: "#2f4b7c", text: "white" },
+  { primary: "#665191", text: "white" },
+  { primary: "#a05195", text: "white" },
+  { primary: "#d45087", text: "white" },
+  { primary: "#f95d6a", text: "white" },
+  { primary: "#ff7c43", text: "black" },
+  { primary: "#ffa600", text: "black" },
+  { primary: "#ffc600", text: "black" }
+];
+var hash = (str) => {
+  let hash2 = 0;
+  for (let i = 0;i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash2 = (hash2 << 5) - hash2 + char;
+    hash2 = hash2 & hash2;
+  }
+  return Math.abs(hash2);
+};
+var getColor = (str) => {
+  const colorIndex = hash(str) % colors.length;
+  return colors[colorIndex];
+};
+var getLogWhitelist = () => {
+  const whitelist = process.env.NEXT_PUBLIC_LOG_WHITELIST || process.env.VITE_LOG_WHITELIST || process.env.LOG_WHITELIST;
+  return whitelist?.split(",").map((s) => s.trim().toLowerCase()) || [];
+};
+var isProduction = () => {
+  return false;
+};
+var matchesPattern = (owner, pattern) => {
+  const ownerSegments = owner.toLowerCase().split(".");
+  const patternSegments = pattern.split(".");
+  if (patternSegments.length > ownerSegments.length) {
+    return false;
+  }
+  for (let i = 0;i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const ownerSegment = ownerSegments[i];
+    if (patternSegment === "*") {
+      continue;
+    }
+    if (patternSegment !== ownerSegment) {
+      return false;
+    }
+  }
+  return true;
+};
+var shouldLog = (owners) => {
+  if (!isProduction()) {
+    return true;
+  }
+  const whitelist = getLogWhitelist();
+  if (whitelist.length === 0) {
+    return false;
+  }
+  const ownerPath = owners.join(".");
+  return whitelist.some((pattern) => matchesPattern(ownerPath, pattern));
+};
+var buildOwnerLabels = (owners) => {
+  const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+  if (isBrowser) {
+    const labels2 = [];
+    const styles = [];
+    for (const ownerName of owners) {
+      const color = getColor(ownerName);
+      labels2.push(`%c ${ownerName.toUpperCase()} `);
+      styles.push(`background: ${color.primary}; color: ${color.text}; padding: 2px 0px; border-radius: 4px; font-weight: semibold; font-size: 0.8em; margin-right: 4px;`);
+    }
+    return [labels2.join(""), ...styles];
+  }
+  const labels = [];
+  for (const ownerName of owners) {
+    labels.push(`\x1B[36m[${ownerName.toUpperCase()}]\x1B[0m`);
+  }
+  return [labels.join(" ")];
+};
+function log(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  if (!shouldLog(owners)) {
+    return;
+  }
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.log(label, ...styles, ...messages);
+}
+function logError(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.error(label, ...styles, ...messages);
+}
+function logWarn(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.warn(label, ...styles, ...messages);
+}
+// src/events.ts
+class Emitter {
+  #events = {};
+  on(event, listener) {
+    if (!this.#events[event])
+      this.#events[event] = [];
+    this.#events[event].push(listener);
+    return () => this.off(event, listener);
+  }
+  once(event, listener) {
+    const wrappedListener = (args) => {
+      listener(args);
+      this.off(event, wrappedListener);
+    };
+    this.on(event, wrappedListener);
+  }
+  off(event, listener) {
+    if (!this.#events[event])
+      return;
+    if (listener) {
+      this.#events[event] = this.#events[event].filter((l) => l !== listener);
+    } else {
+      this.#events[event] = [];
+    }
+  }
+  emit(event, args) {
+    this.#events[event]?.forEach((listener) => listener(args));
+  }
+  destroy() {
+    this.#events = {};
+  }
+}

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+/**
+* Clamps a value between a minimum and maximum value.
+*
+* @param value - The value to clamp
+* @param min - The minimum allowed value
+* @param max - The maximum allowed value
+* @returns The clamped value
+*/
+declare const clamp: (value: number, min: number, max: number) => number;
+/**
+* Log a message to the console. Will display a colored label with the owner(s) name.
+* Automatically skips logging in production unless the owner path matches a whitelist pattern.
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* See {@link shouldLog} for whitelist pattern details.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function log(owner: string | string[], ...messages: unknown[]): void;
+/**
+* Log an error message to the console. Will display a colored label with the owner(s) name.
+* Always logs regardless of environment (not subject to whitelisting).
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function logError(owner: string | string[], ...messages: unknown[]): void;
+/**
+* Log a warning message to the console. Will display a colored label with the owner(s) name.
+* Always logs regardless of environment (not subject to whitelisting).
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function logWarn(owner: string | string[], ...messages: unknown[]): void;
+type KeysWithVoidPayload<Events extends Record<string, any>> = { [K in keyof Events] : Events[K] extends void ? K : never }[keyof Events];
+declare class Emitter<Events extends Record<string, any>> {
+	private;
+	on<K extends keyof Events>(event: K, listener: (args: Events[K]) => void): () => void;
+	once<K extends keyof Events>(event: K, listener: (args: Events[K]) => void): void;
+	off<K extends keyof Events>(event: K, listener?: (args: Events[K]) => void): void;
+	emit<K extends KeysWithVoidPayload<Events>>(event: K): void;
+	emit<K extends Exclude<keyof Events, KeysWithVoidPayload<Events>>>(event: K, args: Events[K]): void;
+	destroy(): void;
+}
+export { logWarn, logError, log, clamp, Emitter };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+* Clamps a value between a minimum and maximum value.
+*
+* @param value - The value to clamp
+* @param min - The minimum allowed value
+* @param max - The maximum allowed value
+* @returns The clamped value
+*/
+declare const clamp: (value: number, min: number, max: number) => number;
+/**
+* Log a message to the console. Will display a colored label with the owner(s) name.
+* Automatically skips logging in production unless the owner path matches a whitelist pattern.
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* See {@link shouldLog} for whitelist pattern details.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function log(owner: string | string[], ...messages: unknown[]): void;
+/**
+* Log an error message to the console. Will display a colored label with the owner(s) name.
+* Always logs regardless of environment (not subject to whitelisting).
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function logError(owner: string | string[], ...messages: unknown[]): void;
+/**
+* Log a warning message to the console. Will display a colored label with the owner(s) name.
+* Always logs regardless of environment (not subject to whitelisting).
+*
+* Owner can be specified as a dot-separated string (e.g., `api.auth.login`) or as an array
+* of segments (e.g., `["api", "auth", "login"]`) which will be joined with dots.
+*
+* @param owner - The owner path (e.g., `api.auth` or `["api", "auth"]`).
+* @param messages - The messages to log
+*/
+declare function logWarn(owner: string | string[], ...messages: unknown[]): void;
+type KeysWithVoidPayload<Events extends Record<string, any>> = { [K in keyof Events] : Events[K] extends void ? K : never }[keyof Events];
+declare class Emitter<Events extends Record<string, any>> {
+	private;
+	on<K extends keyof Events>(event: K, listener: (args: Events[K]) => void): () => void;
+	once<K extends keyof Events>(event: K, listener: (args: Events[K]) => void): void;
+	off<K extends keyof Events>(event: K, listener?: (args: Events[K]) => void): void;
+	emit<K extends KeysWithVoidPayload<Events>>(event: K): void;
+	emit<K extends Exclude<keyof Events, KeysWithVoidPayload<Events>>>(event: K, args: Events[K]): void;
+	destroy(): void;
+}
+export { logWarn, logError, log, clamp, Emitter };

package/dist/index.js

@@ -0,0 +1,140 @@
+// src/math.ts
+var clamp = (value, min, max) => {
+  return Math.min(Math.max(value, min), max);
+};
+// src/log.ts
+var colors = [
+  { primary: "#003f5c", text: "white" },
+  { primary: "#2f4b7c", text: "white" },
+  { primary: "#665191", text: "white" },
+  { primary: "#a05195", text: "white" },
+  { primary: "#d45087", text: "white" },
+  { primary: "#f95d6a", text: "white" },
+  { primary: "#ff7c43", text: "black" },
+  { primary: "#ffa600", text: "black" },
+  { primary: "#ffc600", text: "black" }
+];
+var hash = (str) => {
+  let hash2 = 0;
+  for (let i = 0;i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash2 = (hash2 << 5) - hash2 + char;
+    hash2 = hash2 & hash2;
+  }
+  return Math.abs(hash2);
+};
+var getColor = (str) => {
+  const colorIndex = hash(str) % colors.length;
+  return colors[colorIndex];
+};
+var getLogWhitelist = () => {
+  const whitelist = process.env.NEXT_PUBLIC_LOG_WHITELIST || process.env.VITE_LOG_WHITELIST || process.env.LOG_WHITELIST;
+  return whitelist?.split(",").map((s) => s.trim().toLowerCase()) || [];
+};
+var isProduction = () => {
+  return false;
+};
+var matchesPattern = (owner, pattern) => {
+  const ownerSegments = owner.toLowerCase().split(".");
+  const patternSegments = pattern.split(".");
+  if (patternSegments.length > ownerSegments.length) {
+    return false;
+  }
+  for (let i = 0;i < patternSegments.length; i++) {
+    const patternSegment = patternSegments[i];
+    const ownerSegment = ownerSegments[i];
+    if (patternSegment === "*") {
+      continue;
+    }
+    if (patternSegment !== ownerSegment) {
+      return false;
+    }
+  }
+  return true;
+};
+var shouldLog = (owners) => {
+  if (!isProduction()) {
+    return true;
+  }
+  const whitelist = getLogWhitelist();
+  if (whitelist.length === 0) {
+    return false;
+  }
+  const ownerPath = owners.join(".");
+  return whitelist.some((pattern) => matchesPattern(ownerPath, pattern));
+};
+var buildOwnerLabels = (owners) => {
+  const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+  if (isBrowser) {
+    const labels2 = [];
+    const styles = [];
+    for (const ownerName of owners) {
+      const color = getColor(ownerName);
+      labels2.push(`%c ${ownerName.toUpperCase()} `);
+      styles.push(`background: ${color.primary}; color: ${color.text}; padding: 2px 0px; border-radius: 4px; font-weight: semibold; font-size: 0.8em; margin-right: 4px;`);
+    }
+    return [labels2.join(""), ...styles];
+  }
+  const labels = [];
+  for (const ownerName of owners) {
+    labels.push(`\x1B[36m[${ownerName.toUpperCase()}]\x1B[0m`);
+  }
+  return [labels.join(" ")];
+};
+function log(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  if (!shouldLog(owners)) {
+    return;
+  }
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.log(label, ...styles, ...messages);
+}
+function logError(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.error(label, ...styles, ...messages);
+}
+function logWarn(owner, ...messages) {
+  const owners = Array.isArray(owner) ? owner : [owner];
+  const [label, ...styles] = buildOwnerLabels(owners);
+  console.warn(label, ...styles, ...messages);
+}
+// src/events.ts
+class Emitter {
+  #events = {};
+  on(event, listener) {
+    if (!this.#events[event])
+      this.#events[event] = [];
+    this.#events[event].push(listener);
+    return () => this.off(event, listener);
+  }
+  once(event, listener) {
+    const wrappedListener = (args) => {
+      listener(args);
+      this.off(event, wrappedListener);
+    };
+    this.on(event, wrappedListener);
+  }
+  off(event, listener) {
+    if (!this.#events[event])
+      return;
+    if (listener) {
+      this.#events[event] = this.#events[event].filter((l) => l !== listener);
+    } else {
+      this.#events[event] = [];
+    }
+  }
+  emit(event, args) {
+    this.#events[event]?.forEach((listener) => listener(args));
+  }
+  destroy() {
+    this.#events = {};
+  }
+}
+export {
+  logWarn,
+  logError,
+  log,
+  clamp,
+  Emitter
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@gumbee/utils",
+  "version": "1.0.0",
+  "author": "Gumbee <mugeeb.hassan@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gumbee/utils.git"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^9.39.1",
+    "@types/bun": "^1.3.4",
+    "bunup": "^0.16.10",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^10.0.1",
+    "globals": "^15.15.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.47.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.5.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bugs": {
+    "url": "https://github.com/gumbee/utils/issues"
+  },
+  "description": "Shared utilities for the Gumbee codebase",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://github.com/gumbee/utils#readme",
+  "keywords": [
+    "gumbee",
+    "utils",
+    "utilities",
+    "typescript"
+  ],
+  "license": "MIT",
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "bunup --dts",
+    "dev": "bunup --watch --dts",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint --fix src/",
+    "changeset": "changeset",
+    "version": "changeset version"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts"
+}