@sqlrooms/utils 0.28.0-rc.0 → 0.28.0

package/README.md

@@ -1,98 +1,76 @@
-A collection of utility functions and helpers for SQLRooms applications. This package provides common utilities for string manipulation, file handling, color management, formatting, and more.
-
-## Features
-
-- 🔠 **String Utilities**: Functions for string manipulation and formatting
-- 📁 **File Path Handling**: Tools for working with file paths and extensions
-- 🎨 **Color Utilities**: Color conversion and manipulation functions
-- 📊 **Formatting**: Data formatting for display purposes
-- 🔄 **XHR Helpers**: Utilities for working with XMLHttpRequests
-- 🧰 **General Helpers**: Common helper functions for everyday tasks
+Shared utility functions used across SQLRooms packages and apps.
 
 ## Installation
 
 ```bash
 npm install @sqlrooms/utils
-# or
-yarn add @sqlrooms/utils
 ```
 
-## Basic Usage
-
-### String Utilities
-
-```tsx
-import {truncate, capitalize, slugify} from '@sqlrooms/utils';
-
-// Truncate long text
-const shortText = truncate(
-  'This is a very long text that needs to be shortened',
-  20,
-);
-console.log(shortText); // 'This is a very long...'
-
-// Capitalize text
-const capitalized = capitalize('hello world');
-console.log(capitalized); // 'Hello world'
-
-// Create a URL-friendly slug
-const slug = slugify('Hello World! This is a test');
-console.log(slug); // 'hello-world-this-is-a-test'
+## String and formatting helpers
+
+```ts
+import {
+  capitalize,
+  camelCaseToTitle,
+  truncate,
+  formatBytes,
+  formatNumber,
+  formatDate,
+  formatDateTime,
+  formatTimeRelative,
+} from '@sqlrooms/utils';
+
+capitalize('hello'); // "Hello"
+camelCaseToTitle('tableRowCount'); // "Table Row Count"
+truncate('This is a long sentence', 10); // "This is..."
+
+formatBytes(1048576); // "1 MB"
+formatNumber(1234567.89); // "1,234,568"
+formatDate(new Date()); // "2026-02-23"
+formatDateTime(new Date()); // "Mon 2026-02-23 02:15 PM"
+formatTimeRelative(Date.now() - 60_000); // "a minute ago"
 ```
 
-### File Path Utilities
+## File/table name helpers
 
-```tsx
-import {getFileExtension, joinPaths, normalizePath} from '@sqlrooms/utils';
+```ts
+import {
+  convertToValidColumnOrTableName,
+  convertToUniqueColumnOrTableName,
+  generateUniqueName,
+  splitFilePath,
+  generateUniquePath,
+} from '@sqlrooms/utils';
 
-// Get file extension
-const ext = getFileExtension('document.pdf');
-console.log(ext); // 'pdf'
+convertToValidColumnOrTableName('My File.csv'); // "My_File"
+convertToUniqueColumnOrTableName('sales.csv', ['sales']); // "sales_1"
+generateUniqueName('query', ['query', 'query_1']); // "query_2"
 
-// Join path segments
-const fullPath = joinPaths('/base/path', 'subfolder', 'file.txt');
-console.log(fullPath); // '/base/path/subfolder/file.txt'
+splitFilePath('folder/data.parquet');
+// { dir: "folder", name: "data", ext: "parquet", filename: "data.parquet" }
 
-// Normalize a path
-const normalized = normalizePath('/path//to/../folder/./file.txt');
-console.log(normalized); // '/path/folder/file.txt'
+generateUniquePath('results.csv', ['results.csv']); // "results_1.csv"
 ```
 
-### JSON Utilities
+## Network and JSON helpers
 
-```tsx
-import {safeJsonParse} from '@sqlrooms/utils';
+```ts
+import {safeJsonParse, downloadFile, uploadFile, postData} from '@sqlrooms/utils';
 
-// Safely parse JSON without throwing exceptions
-const result = safeJsonParse('{"name": "John", "age": 30}');
-console.log(result); // { name: 'John', age: 30 }
+const parsed = safeJsonParse('{"ok": true}'); // { ok: true }
+const invalid = safeJsonParse('{'); // undefined
 
-// Handle invalid JSON gracefully
-const invalid = safeJsonParse('{"name": "John", age: 30}');
-console.log(invalid); // undefined
+// downloadFile / uploadFile / postData are Promise-based XHR helpers
 ```
 
-### Formatting Utilities
-
-```tsx
-import {formatBytes, formatNumber, formatDate} from '@sqlrooms/utils';
-
-// Format file size
-console.log(formatBytes(1024)); // '1 KB'
-console.log(formatBytes(1048576)); // '1 MB'
-
-// Format numbers
-console.log(formatNumber(1234567.89)); // '1,234,567.89'
-
-// Format dates
-console.log(formatDate(new Date(), 'yyyy-MM-dd')); // '2023-04-15'
-```
-
-## Advanced Features
-
-- **Type Safety**: All utilities are fully typed with TypeScript
-- **Browser Compatibility**: Works in all modern browsers
-- **Tree-Shakable**: Import only what you need to minimize bundle size
-- **No Dependencies**: Zero external runtime dependencies
-
-For more information, visit the SQLRooms documentation.
+## Other useful exports
+
+- `memoizeOnce`
+- `opacifyHex`
+- `formatCount`, `formatCountShort`, `shorten`
+- decimal helpers:
+  - `isNegativeDecimal`
+  - `negateDecimal`
+  - `toDecimalString`
+  - `toDecimalNumber`
+  - `fromDecimalString`

package/dist/memoization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memoization.d.ts","sourceRoot":"","sources":["../src/memoization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,SAAS,OAAO,EAAE,EAAE,OAAO,EACnE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC9B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAsB7B"}
+{"version":3,"file":"memoization.d.ts","sourceRoot":"","sources":["../src/memoization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,SAAS,OAAO,EAAE,EAAE,OAAO,EACnE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC9B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAkB7B"}

package/dist/memoization.js

@@ -36,9 +36,7 @@ export function memoizeOnce(fn) {
             return lastResult;
         }
         // Call the function with the correct context and cache the result
-        lastResult = fn.apply(this, 
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        args);
+        lastResult = fn.apply(this, args);
         lastArgs = args;
         hasResult = true;
         return lastResult;

package/dist/memoization.js.map

@@ -1 +1 @@
-{"version":3,"file":"memoization.js","sourceRoot":"","sources":["../src/memoization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CACzB,EAA+B;IAE/B,IAAI,QAA2B,CAAC;IAChC,IAAI,UAAmB,CAAC;IACxB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,OAAO,UAAyB,GAAG,IAAW;QAC5C,iEAAiE;QACjE,IAAI,SAAS,IAAI,QAAQ,IAAI,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,kEAAkE;QAClE,UAAU,GAAG,EAAE,CAAC,KAAK,CACnB,IAAI;QACJ,8DAA8D;QAC9D,IAAwB,CACzB,CAAC;QACF,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;QAEjB,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAA+B,CAAI,EAAE,CAAI;IACzD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC","sourcesContent":["/**\n * Creates a memoized version of a function that caches only the last result.\n * The cache is invalidated when any of the arguments change.\n *\n * This is useful for expensive operations that are likely to be called\n * multiple times with the same arguments, like database queries or API calls.\n *\n * @param fn - The function to memoize\n * @returns A memoized version of the function\n *\n * @example\n * ```ts\n * const expensiveQuery = async (userId: string, limit: number) => {\n *   return await database.query(`SELECT * FROM users WHERE id = ? LIMIT ?`, [userId, limit]);\n * };\n *\n * const memoizedQuery = memoizeOnce(expensiveQuery);\n *\n * // First call executes the function\n * const result1 = await memoizedQuery(\"123\", 10);\n *\n * // Second call with same arguments returns cached result\n * const result2 = await memoizedQuery(\"123\", 10); // Uses cache\n *\n * // Call with different arguments invalidates cache and executes function\n * const result3 = await memoizedQuery(\"456\", 10); // Executes function\n * ```\n */\nexport function memoizeOnce<TArgs extends readonly unknown[], TReturn>(\n  fn: (...args: TArgs) => TReturn,\n): (...args: TArgs) => TReturn {\n  let lastArgs: TArgs | undefined;\n  let lastResult: TReturn;\n  let hasResult = false;\n\n  return function (this: unknown, ...args: TArgs): TReturn {\n    // Check if we have a cached result and arguments haven't changed\n    if (hasResult && lastArgs && argsEqual(lastArgs, args)) {\n      return lastResult;\n    }\n\n    // Call the function with the correct context and cache the result\n    lastResult = fn.apply(\n      this,\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      args as unknown as any[],\n    );\n    lastArgs = args;\n    hasResult = true;\n\n    return lastResult;\n  };\n}\n\n/**\n * Shallow comparison of two arrays to check if all elements are equal\n */\nfunction argsEqual<T extends readonly unknown[]>(a: T, b: T): boolean {\n  if (a.length !== b.length) return false;\n  return a.every((val, index) => val === b[index]);\n}\n"]}
+{"version":3,"file":"memoization.js","sourceRoot":"","sources":["../src/memoization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CACzB,EAA+B;IAE/B,IAAI,QAA2B,CAAC;IAChC,IAAI,UAAmB,CAAC;IACxB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,OAAO,UAAyB,GAAG,IAAW;QAC5C,iEAAiE;QACjE,IAAI,SAAS,IAAI,QAAQ,IAAI,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,kEAAkE;QAClE,UAAU,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,IAAwB,CAAC,CAAC;QACtD,QAAQ,GAAG,IAAI,CAAC;QAChB,SAAS,GAAG,IAAI,CAAC;QAEjB,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,SAAS,CAA+B,CAAI,EAAE,CAAI;IACzD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC","sourcesContent":["/**\n * Creates a memoized version of a function that caches only the last result.\n * The cache is invalidated when any of the arguments change.\n *\n * This is useful for expensive operations that are likely to be called\n * multiple times with the same arguments, like database queries or API calls.\n *\n * @param fn - The function to memoize\n * @returns A memoized version of the function\n *\n * @example\n * ```ts\n * const expensiveQuery = async (userId: string, limit: number) => {\n *   return await database.query(`SELECT * FROM users WHERE id = ? LIMIT ?`, [userId, limit]);\n * };\n *\n * const memoizedQuery = memoizeOnce(expensiveQuery);\n *\n * // First call executes the function\n * const result1 = await memoizedQuery(\"123\", 10);\n *\n * // Second call with same arguments returns cached result\n * const result2 = await memoizedQuery(\"123\", 10); // Uses cache\n *\n * // Call with different arguments invalidates cache and executes function\n * const result3 = await memoizedQuery(\"456\", 10); // Executes function\n * ```\n */\nexport function memoizeOnce<TArgs extends readonly unknown[], TReturn>(\n  fn: (...args: TArgs) => TReturn,\n): (...args: TArgs) => TReturn {\n  let lastArgs: TArgs | undefined;\n  let lastResult: TReturn;\n  let hasResult = false;\n\n  return function (this: unknown, ...args: TArgs): TReturn {\n    // Check if we have a cached result and arguments haven't changed\n    if (hasResult && lastArgs && argsEqual(lastArgs, args)) {\n      return lastResult;\n    }\n\n    // Call the function with the correct context and cache the result\n    lastResult = fn.apply(this, args as unknown as any[]);\n    lastArgs = args;\n    hasResult = true;\n\n    return lastResult;\n  };\n}\n\n/**\n * Shallow comparison of two arrays to check if all elements are equal\n */\nfunction argsEqual<T extends readonly unknown[]>(a: T, b: T): boolean {\n  if (a.length !== b.length) return false;\n  return a.every((val, index) => val === b[index]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqlrooms/utils",
-  "version": "0.28.0-rc.0",
+  "version": "0.28.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "module": "dist/index.js",
@@ -43,5 +43,5 @@
     "react": ">=18",
     "react-dom": ">=18"
   },
-  "gitHead": "87a478edbff690e04c38cc717db8e11e844565c8"
+  "gitHead": "dcac54f8adf77240e293c93d224a0ce9fd8142a9"
 }