@publikit/utils 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pirimera
+
+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,42 @@
+# @publikit/utils
+
+Framework-agnostic utility functions for Publikit packages and applications.
+
+- **No React peer dependency** — safe for scripts, edge workers, and non-UI code
+- **Tree-shakeable** — `sideEffects: false`
+
+## Installation
+
+```bash
+npm install @publikit/utils
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `cn` | Merge Tailwind classes (`clsx` + `tailwind-merge`) |
+| `debounce` | Debounce function calls |
+| `getErrorMessage` | Extract message from unknown errors |
+| `formatBytes` | Human-readable byte sizes |
+| `calculateUsagePercentage` | Percentage capped at 100 |
+
+## Usage
+
+```ts
+import { cn, debounce, getErrorMessage, formatBytes } from '@publikit/utils';
+
+const className = cn('px-4', isActive && 'bg-primary');
+const onResize = debounce(() => measure(), 150);
+const message = getErrorMessage(error, 'Something went wrong');
+const size = formatBytes(1_048_576); // "1 MB"
+```
+
+## Related packages
+
+- [`@publikit/hooks`](../hooks) — generic React hooks
+- [`@publikit/base`](../base) — re-exports `cn` for convenience
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+var clsx = require('clsx');
+var tailwindMerge = require('tailwind-merge');
+
+// cn.ts
+function cn(...inputs) {
+  return tailwindMerge.twMerge(clsx.clsx(inputs));
+}
+
+// async.ts
+function debounce(fn, ms) {
+  let timeoutId = null;
+  let lastArgs = null;
+  const debounced = (...args) => {
+    lastArgs = args;
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      if (lastArgs) {
+        fn(...lastArgs);
+        lastArgs = null;
+      }
+    }, ms);
+  };
+  debounced.cancel = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = null;
+    lastArgs = null;
+  };
+  debounced.flush = () => {
+    if (!timeoutId || !lastArgs) return;
+    clearTimeout(timeoutId);
+    timeoutId = null;
+    fn(...lastArgs);
+    lastArgs = null;
+  };
+  return debounced;
+}
+
+// error.ts
+function getErrorMessage(error, defaultMessage) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === "string" && error.trim()) {
+    return error;
+  }
+  if (error && typeof error === "object" && "message" in error) {
+    const message = error.message;
+    if (typeof message === "string" && message.trim()) {
+      return message;
+    }
+  }
+  return defaultMessage;
+}
+
+// format.ts
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return "0 B";
+  }
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(k)),
+    sizes.length - 1
+  );
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+function calculateUsagePercentage(current, limit) {
+  if (!Number.isFinite(current) || !Number.isFinite(limit) || limit <= 0) {
+    return 0;
+  }
+  if (current <= 0) {
+    return 0;
+  }
+  return Math.min(100, Math.round(current / limit * 100));
+}
+
+exports.calculateUsagePercentage = calculateUsagePercentage;
+exports.cn = cn;
+exports.debounce = debounce;
+exports.formatBytes = formatBytes;
+exports.getErrorMessage = getErrorMessage;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../cn.ts","../async.ts","../error.ts","../format.ts"],"names":["twMerge","clsx"],"mappings":"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","file":"index.cjs","sourcesContent":["import { clsx, type ClassValue } from 'clsx';\r\nimport { twMerge } from 'tailwind-merge';\r\n\r\n/**\r\n * Merge Tailwind CSS class names with conflict resolution.\r\n */\r\nexport function cn(...inputs: ClassValue[]): string {\r\n  return twMerge(clsx(inputs));\r\n}\r\n","/**\r\n * Debounced function with cancel and flush helpers.\r\n */\r\nexport interface DebouncedFunction<A extends unknown[], R> {\r\n  (...args: A): void;\r\n  cancel(): void;\r\n  flush(): void;\r\n}\r\n\r\n/**\r\n * Debounce a function — only invoke after `ms` milliseconds of inactivity.\r\n */\r\nexport function debounce<A extends unknown[], R>(\r\n  fn: (...args: A) => R,\r\n  ms: number\r\n): DebouncedFunction<A, R> {\r\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\r\n  let lastArgs: A | null = null;\r\n\r\n  const debounced = (...args: A) => {\r\n    lastArgs = args;\r\n    if (timeoutId) clearTimeout(timeoutId);\r\n    timeoutId = setTimeout(() => {\r\n      timeoutId = null;\r\n      if (lastArgs) {\r\n        fn(...lastArgs);\r\n        lastArgs = null;\r\n      }\r\n    }, ms);\r\n  };\r\n\r\n  debounced.cancel = () => {\r\n    if (timeoutId) clearTimeout(timeoutId);\r\n    timeoutId = null;\r\n    lastArgs = null;\r\n  };\r\n\r\n  debounced.flush = () => {\r\n    if (!timeoutId || !lastArgs) return;\r\n    clearTimeout(timeoutId);\r\n    timeoutId = null;\r\n    fn(...lastArgs);\r\n    lastArgs = null;\r\n  };\r\n\r\n  return debounced;\r\n}\r\n","/**\r\n * Extract a human-readable message from an unknown error value.\r\n */\r\nexport function getErrorMessage(error: unknown, defaultMessage: string): string {\r\n  if (error instanceof Error && error.message) {\r\n    return error.message;\r\n  }\r\n\r\n  if (typeof error === 'string' && error.trim()) {\r\n    return error;\r\n  }\r\n\r\n  if (error && typeof error === 'object' && 'message' in error) {\r\n    const message = (error as { message: unknown }).message;\r\n    if (typeof message === 'string' && message.trim()) {\r\n      return message;\r\n    }\r\n  }\r\n\r\n  return defaultMessage;\r\n}\r\n","/**\r\n * Format a byte count as a human-readable string.\r\n */\r\nexport function formatBytes(bytes: number): string {\r\n  if (!Number.isFinite(bytes) || bytes <= 0) {\r\n    return '0 B';\r\n  }\r\n\r\n  const k = 1024;\r\n  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];\r\n  const i = Math.min(\r\n    Math.floor(Math.log(bytes) / Math.log(k)),\r\n    sizes.length - 1\r\n  );\r\n  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;\r\n}\r\n\r\n/**\r\n * Calculate usage percentage capped at 100.\r\n */\r\nexport function calculateUsagePercentage(current: number, limit: number): number {\r\n  if (!Number.isFinite(current) || !Number.isFinite(limit) || limit <= 0) {\r\n    return 0;\r\n  }\r\n\r\n  if (current <= 0) {\r\n    return 0;\r\n  }\r\n\r\n  return Math.min(100, Math.round((current / limit) * 100));\r\n}\r\n"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merge Tailwind CSS class names with conflict resolution.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Debounced function with cancel and flush helpers.
+ */
+interface DebouncedFunction<A extends unknown[], R> {
+    (...args: A): void;
+    cancel(): void;
+    flush(): void;
+}
+/**
+ * Debounce a function — only invoke after `ms` milliseconds of inactivity.
+ */
+declare function debounce<A extends unknown[], R>(fn: (...args: A) => R, ms: number): DebouncedFunction<A, R>;
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ */
+declare function getErrorMessage(error: unknown, defaultMessage: string): string;
+
+/**
+ * Format a byte count as a human-readable string.
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Calculate usage percentage capped at 100.
+ */
+declare function calculateUsagePercentage(current: number, limit: number): number;
+
+export { type DebouncedFunction, calculateUsagePercentage, cn, debounce, formatBytes, getErrorMessage };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merge Tailwind CSS class names with conflict resolution.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * Debounced function with cancel and flush helpers.
+ */
+interface DebouncedFunction<A extends unknown[], R> {
+    (...args: A): void;
+    cancel(): void;
+    flush(): void;
+}
+/**
+ * Debounce a function — only invoke after `ms` milliseconds of inactivity.
+ */
+declare function debounce<A extends unknown[], R>(fn: (...args: A) => R, ms: number): DebouncedFunction<A, R>;
+
+/**
+ * Extract a human-readable message from an unknown error value.
+ */
+declare function getErrorMessage(error: unknown, defaultMessage: string): string;
+
+/**
+ * Format a byte count as a human-readable string.
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Calculate usage percentage capped at 100.
+ */
+declare function calculateUsagePercentage(current: number, limit: number): number;
+
+export { type DebouncedFunction, calculateUsagePercentage, cn, debounce, formatBytes, getErrorMessage };

package/dist/index.js

@@ -0,0 +1,81 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+// cn.ts
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// async.ts
+function debounce(fn, ms) {
+  let timeoutId = null;
+  let lastArgs = null;
+  const debounced = (...args) => {
+    lastArgs = args;
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      if (lastArgs) {
+        fn(...lastArgs);
+        lastArgs = null;
+      }
+    }, ms);
+  };
+  debounced.cancel = () => {
+    if (timeoutId) clearTimeout(timeoutId);
+    timeoutId = null;
+    lastArgs = null;
+  };
+  debounced.flush = () => {
+    if (!timeoutId || !lastArgs) return;
+    clearTimeout(timeoutId);
+    timeoutId = null;
+    fn(...lastArgs);
+    lastArgs = null;
+  };
+  return debounced;
+}
+
+// error.ts
+function getErrorMessage(error, defaultMessage) {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === "string" && error.trim()) {
+    return error;
+  }
+  if (error && typeof error === "object" && "message" in error) {
+    const message = error.message;
+    if (typeof message === "string" && message.trim()) {
+      return message;
+    }
+  }
+  return defaultMessage;
+}
+
+// format.ts
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return "0 B";
+  }
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(k)),
+    sizes.length - 1
+  );
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+function calculateUsagePercentage(current, limit) {
+  if (!Number.isFinite(current) || !Number.isFinite(limit) || limit <= 0) {
+    return 0;
+  }
+  if (current <= 0) {
+    return 0;
+  }
+  return Math.min(100, Math.round(current / limit * 100));
+}
+
+export { calculateUsagePercentage, cn, debounce, formatBytes, getErrorMessage };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../cn.ts","../async.ts","../error.ts","../format.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { clsx, type ClassValue } from 'clsx';\r\nimport { twMerge } from 'tailwind-merge';\r\n\r\n/**\r\n * Merge Tailwind CSS class names with conflict resolution.\r\n */\r\nexport function cn(...inputs: ClassValue[]): string {\r\n  return twMerge(clsx(inputs));\r\n}\r\n","/**\r\n * Debounced function with cancel and flush helpers.\r\n */\r\nexport interface DebouncedFunction<A extends unknown[], R> {\r\n  (...args: A): void;\r\n  cancel(): void;\r\n  flush(): void;\r\n}\r\n\r\n/**\r\n * Debounce a function — only invoke after `ms` milliseconds of inactivity.\r\n */\r\nexport function debounce<A extends unknown[], R>(\r\n  fn: (...args: A) => R,\r\n  ms: number\r\n): DebouncedFunction<A, R> {\r\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\r\n  let lastArgs: A | null = null;\r\n\r\n  const debounced = (...args: A) => {\r\n    lastArgs = args;\r\n    if (timeoutId) clearTimeout(timeoutId);\r\n    timeoutId = setTimeout(() => {\r\n      timeoutId = null;\r\n      if (lastArgs) {\r\n        fn(...lastArgs);\r\n        lastArgs = null;\r\n      }\r\n    }, ms);\r\n  };\r\n\r\n  debounced.cancel = () => {\r\n    if (timeoutId) clearTimeout(timeoutId);\r\n    timeoutId = null;\r\n    lastArgs = null;\r\n  };\r\n\r\n  debounced.flush = () => {\r\n    if (!timeoutId || !lastArgs) return;\r\n    clearTimeout(timeoutId);\r\n    timeoutId = null;\r\n    fn(...lastArgs);\r\n    lastArgs = null;\r\n  };\r\n\r\n  return debounced;\r\n}\r\n","/**\r\n * Extract a human-readable message from an unknown error value.\r\n */\r\nexport function getErrorMessage(error: unknown, defaultMessage: string): string {\r\n  if (error instanceof Error && error.message) {\r\n    return error.message;\r\n  }\r\n\r\n  if (typeof error === 'string' && error.trim()) {\r\n    return error;\r\n  }\r\n\r\n  if (error && typeof error === 'object' && 'message' in error) {\r\n    const message = (error as { message: unknown }).message;\r\n    if (typeof message === 'string' && message.trim()) {\r\n      return message;\r\n    }\r\n  }\r\n\r\n  return defaultMessage;\r\n}\r\n","/**\r\n * Format a byte count as a human-readable string.\r\n */\r\nexport function formatBytes(bytes: number): string {\r\n  if (!Number.isFinite(bytes) || bytes <= 0) {\r\n    return '0 B';\r\n  }\r\n\r\n  const k = 1024;\r\n  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];\r\n  const i = Math.min(\r\n    Math.floor(Math.log(bytes) / Math.log(k)),\r\n    sizes.length - 1\r\n  );\r\n  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;\r\n}\r\n\r\n/**\r\n * Calculate usage percentage capped at 100.\r\n */\r\nexport function calculateUsagePercentage(current: number, limit: number): number {\r\n  if (!Number.isFinite(current) || !Number.isFinite(limit) || limit <= 0) {\r\n    return 0;\r\n  }\r\n\r\n  if (current <= 0) {\r\n    return 0;\r\n  }\r\n\r\n  return Math.min(100, Math.round((current / limit) * 100));\r\n}\r\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@publikit/utils",
+  "version": "0.1.1",
+  "description": "Framework-agnostic utility functions for Publikit packages and applications",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "utilities",
+    "cn",
+    "tailwind",
+    "clsx",
+    "publikit"
+  ],
+  "author": "Pirimera",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pirimera/publikit.git",
+    "directory": "utils"
+  },
+  "homepage": "https://github.com/pirimera/publikit/tree/main/utils#readme",
+  "bugs": {
+    "url": "https://github.com/pirimera/publikit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  }
+}