@stonyx/utils 0.1.0 → 0.2.0

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ci-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22.18.0
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

package/README.md

@@ -1,29 +1,226 @@
 # stonyx-utils
 
-## Running the test suite
+Utilities module for the Stonyx Framework. Provides helpers for files, objects, strings, dates, and promises.
+
+---
+
+## Quick Reference Table
+
+| Category    | Function                | Description                                              |
+| ----------- | ----------------------- | -------------------------------------------------------- |
+| **File**    | `createFile`            | Create a file (supports JSON serialization).             |
+|             | `updateFile`            | Atomically update a file.                                |
+|             | `copyFile`              | Copy a file, with optional overwrite.                    |
+|             | `readFile`              | Read a file (JSON optional), with missing file callback. |
+|             | `deleteFile`            | Delete a file (ignore missing optional).                 |
+|             | `deleteDirectory`       | Recursively delete a directory.                          |
+|             | `createDirectory`       | Recursively create a directory.                          |
+|             | `forEachFileImport`     | Dynamically import all JS files in a directory.          |
+|             | `fileExists`            | Check if a file exists.                                  |
+| **Object**  | `deepCopy`              | Deep clone an object or array.                           |
+|             | `objToJson`             | Convert object to formatted JSON string.                 |
+|             | `makeArray`             | Wrap a value in an array.                                |
+|             | `mergeObject`           | Deep merge two objects (ignore new keys optional).       |
+|             | `get`                   | Get nested property safely via dot path.                 |
+|             | `getOrSet`              | Get or set value in a Map.                               |
+| **String**  | `kebabCaseToCamelCase`  | Convert kebab-case to camelCase.                         |
+|             | `kebabCaseToPascalCase` | Convert kebab-case to PascalCase.                        |
+|             | `generateRandomString`  | Generate a random alphanumeric string.                   |
+|             | `pluralize`             | Return plural form of English nouns.                     |
+| **Date**    | `getTimestamp`          | Return current UNIX timestamp in seconds.                |
+| **Promise** | `sleep`                 | Async delay for a given number of seconds.               |
+
+---
+
+## Table of Contents
+
+* [Installation](#installation)
+* [Running the Test Suite](#running-the-test-suite)
+* [File Utils](#file-utils)
+* [Object Utils](#object-utils)
+* [String Utils](#string-utils)
+* [Date Utils](#date-utils)
+* [Promise Utils](#promise-utils)
+* [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @stonyx/utils
 ```
-npm test
+
+---
+
+## File Utils
+
+The File utils wrap the `path` and `fs` libraries to manipulate the local file system asynchronously with full async/await support. Includes creation, reading, updating, copying, deleting files and directories, checking existence, and dynamic importing via `forEachFileImport`.
+
+### Functions
+
+#### `createFile(filePath, data, options={})`
+
+Creates a file at the given path.
+
+* `options.json` — boolean, if true, data will be serialized to JSON.
+
+#### `updateFile(filePath, data, options={})`
+
+Updates a file atomically by writing to a temporary file first.
+
+* `options.json` — boolean, serialize as JSON.
+
+#### `copyFile(sourcePath, targetPath, options={})`
+
+Copies a file from source to target.
+
+* `options.overwrite` — boolean, default false.
+
+#### `readFile(filePath, options={})`
+
+Reads a file, optionally parsing JSON.
+
+* `options.json` — boolean
+* `options.missingFileCallback` — function called if file doesn’t exist.
+
+#### `deleteFile(filePath, options={})`
+
+Deletes a file.
+
+* `options.ignoreAccessFailure` — boolean, ignores errors if file missing.
+
+#### `deleteDirectory(dir)`
+
+Recursively deletes a directory.
+
+#### `createDirectory(dir)`
+
+Recursively creates a directory.
+
+#### `forEachFileImport(dir, callback, options={})`
+
+Dynamically imports all `.js` files in a directory and calls `callback(exports, details)`.
+
+|         Option        |   Type  | Default | Description                                               |
+| :-------------------: | :-----: | :-----: | :-------------------------------------------------------- |
+|      `fullExport`     | Boolean |  false  | If true, callback receives all exports, not just default. |
+|       `rawName`       | Boolean |  false  | If true, the file name is not converted to camelCase.     |
+| `ignoreAccessFailure` | Boolean |  false  | If true, directory access errors are ignored.             |
+
+Example:
+
+```js
+import { forEachFileImport } from '@stonyx/utils/file';
+
+await forEachFileImport('./utils', (exports, details) => {
+  console.log(details.name, exports);
+}, { fullExport: true });
 ```
 
-## File utils
+#### `fileExists(filePath)`
+
+Returns `true` if file exists, else `false`.
+
+---
+
+## Object Utils
+
+Helpers for working with objects and arrays.
 
-TODO: Update documentation to instruct a broader audience
+### Functions
 
-The File utils wrap the `path` and `fs` library to allow consuming classes to manipulate the local file system with full async/await support. Additionally it exposes the `forEachFileImport` method which lets us dynamically and flexibly import dependencies.
+#### `deepCopy(obj)`
 
-### Usage example
+Returns a deep copy of an object or array.
+
+#### `objToJson(obj, format='\t')`
+
+Returns a formatted JSON string.
+
+#### `makeArray(obj)`
+
+Wraps a value in an array if it isn’t already one.
+
+#### `mergeObject(obj1, obj2, options={})`
+
+Deep merges two objects.
+
+* `options.ignoreNewKeys` — boolean, if true, keys not in `obj1` are ignored.
+
+#### `get(obj, path)`
+
+Safely gets a nested property using dot notation. Returns `null` if path not found.
+
+#### `getOrSet(map, key, defaultValue)`
+
+Gets the value for a key in a `Map`, or sets it to `defaultValue` if missing.
+
+---
+
+## String Utils
+
+### Functions
+
+#### `kebabCaseToCamelCase(str)`
+
+Converts `'my-string'` → `'myString'`.
+
+#### `kebabCaseToPascalCase(str)`
+
+Converts `'my-string'` → `'MyString'`.
+
+#### `generateRandomString(length=8)`
+
+Generates a random alphanumeric string.
+
+#### `pluralize(word)`
+
+Returns the plural form of an English noun, handling irregulars and uncountable nouns.
+
+Example:
+
+```js
+import { pluralize } from '@stonyx/utils/string';
+
+console.log(pluralize('person')); // people
+console.log(pluralize('box'));    // boxes
+```
+
+---
+
+## Date Utils
+
+### Functions
+
+#### `getTimestamp()`
+
+Returns the current UNIX timestamp (seconds since epoch).
 
 ```js
-  await forEachFileImport(targetDirectory, (exports, details) => {
-    // Insert logic per export
-  }, options);
+import { getTimestamp } from '@stonyx/utils/date';
+
+console.log(getTimestamp()); // e.g., 1693564800
+```
+
+---
+
+## Promise Utils
+
+### Functions
+
+#### `sleep(seconds)`
+
+Delays execution for the given number of seconds.
+
+```js
+import { sleep } from '@stonyx/utils/promise';
+
+await sleep(2); // waits 2 seconds
 ```
 
-### Valid Options
+---
 
-| Option | Type | Default | Description |
-| :---: | :---: | :---: | :--- |
-| `fullExport` | **Boolean** | *false* | When set to true, The `exports` parameter will be all exports, and not just the default one. |
-| `rawName` | **Boolean** | *false* | When set to true, `forEachFileImport` will not convert the file name to be camelCase and leave it raw instead |
-| `ignoreAccessFailure` | **Boolean** | *false* | When set to true, failure to load directory will be ignored |
+## License
 
+Apache — do what you want, just keep attribution.

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Utils module for Stonyx Framework",
   "type": "module",
   "exports": {
@@ -23,6 +23,7 @@
   ],
   "devDependencies": {
     "fs": "^0.0.1-security",
-    "qunit": "^2.24.1"
+    "qunit": "^2.24.1",
+    "sinon": "^21.0.0"
   }
 }

package/src/file.js

@@ -4,20 +4,23 @@ import { objToJson } from '@stonyx/utils/object';
 import { promises as fsp } from 'fs';
 import path from 'path';
 
-export async function createFile(filePath, data, { json }) {
+export async function createFile(filePath, data, options={}) {
   try {
-    await fsp.writeFile(filePath, json ? objToJson(data) : data, 'utf8');
+    filePath = path.resolve(filePath);
+
+    await createDirectory(path.dirname(filePath));
+    await fsp.writeFile(filePath, options.json ? objToJson(data) : data, 'utf8');
   } catch (error) {
     throw new Error(error);
   }
 }
 
-export async function updateFile(filePath, data, { json }) {
+export async function updateFile(filePath, data, options={}) {
   try {
     await fsp.access(filePath);
 
     const swapFile = `${filePath}.temp-${getTimestamp()}`;
-    await fsp.writeFile(swapFile, json ? objToJson(data) : data);
+    await fsp.writeFile(swapFile, options.json ? objToJson(data) : data);
     await fsp.rename(swapFile, filePath);
   } catch (error) {
     
@@ -25,15 +28,40 @@ export async function updateFile(filePath, data, { json }) {
   }
 }
 
-export async function readFile(filePath, { json, missingFileCallback }) {
+export async function copyFile(sourcePath, targetPath, options={}) {
+  try {
+    sourcePath = path.resolve(sourcePath);
+    targetPath = path.resolve(targetPath);
+    await fsp.access(sourcePath);
+  } catch (error) {
+    throw new Error(error);
+  }
+
+  try {
+    await fsp.access(targetPath);
+    if (!options.overwrite) return false;
+  } catch {}
+
+  try {
+    await fsp.copyFile(sourcePath, targetPath);
+  } catch (error) {
+    throw new Error(error);
+  }
+
+  return true;
+}
+
+export async function readFile(filePath, options={}) {
   try {
     filePath = path.resolve(filePath);
     
     await fsp.access(filePath);
     const fileData = await fsp.readFile(filePath, 'utf8');
 
-    return json ? JSON.parse(fileData) : fileData;
+    return options.json ? JSON.parse(fileData) : fileData;
   } catch (error) {
+    const { missingFileCallback } = options;
+
     if (error.code === 'ENOENT' && missingFileCallback) {
       return missingFileCallback(filePath);
     }
@@ -90,3 +118,13 @@ export async function forEachFileImport(dir, callback, options={}) {
     callback(output, { name, stats, path: filePath });
   }
 }
+
+export async function fileExists(filePath) {
+  try {
+    filePath = path.resolve(filePath);
+    await fsp.access(filePath);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}

package/src/object.js

@@ -2,46 +2,60 @@ export function deepCopy(obj) {
   return JSON.parse(JSON.stringify(obj));
 }
 
-export function objToJson(obj) {
-  return JSON.stringify(obj);
+export function objToJson(obj, format='\t') {
+  return JSON.stringify(obj, null, format);
 }
 
-export function mergeObject(obj1, obj2) {
+export function makeArray(obj) {
+  return Array.isArray(obj) ? obj : [obj];
+}
+
+function cloneShallow(value) {
+  if (Array.isArray(value)) return value.slice();
+  if (value && typeof value === 'object') return { ...value };
+  return value;
+}
+
+export function mergeObject(obj1, obj2, options={}) {
   if (Array.isArray(obj1) || Array.isArray(obj2)) throw new Error('Cannot merge arrays.');
-  if (typeof obj1 !== 'object' || obj1 === null) return structuredClone(obj2);
-  if (typeof obj2 !== 'object' || obj2 === null) return structuredClone(obj1);
+
+  if (obj1 === null || typeof obj1 !== 'object') return cloneShallow(obj2);
+  if (obj2 === null || typeof obj2 !== 'object') return cloneShallow(obj1);
 
   const result = {};
-  const keys = new Set([...Object.keys(obj1), ...Object.keys(obj2)]);
 
-  for (const key of keys) {
+  for (const key of Object.keys(obj1))  result[key] = cloneShallow(obj1[key]);
+  for (const key of Object.keys(obj2)) {
+    if (options.ignoreNewKeys && !(key in obj1)) continue;
+
     const val1 = obj1[key];
     const val2 = obj2[key];
-
-    if (val2 === undefined) {
-      result[key] = structuredClone(val1);
-    } else if (val1 === undefined) {
-      result[key] = structuredClone(val2);
-    } else if (
-      typeof val1 === 'object' &&
-      typeof val2 === 'object' &&
-      val1 !== null &&
-      val2 !== null &&
-      !Array.isArray(val1) &&
-      !Array.isArray(val2)
-    ) {
-      result[key] = mergeObject(val1, val2);
-    } else {
-      result[key] = structuredClone(val2);
-    }
+    const shouldMerge = val1 && val2 && typeof val1 === 'object' && typeof val2 === 'object' && !Array.isArray(val1) && !Array.isArray(val2);
+    result[key] = shouldMerge ? mergeObject(val1, val2, options) : cloneShallow(val2);
+    
   }
 
   return result;
 }
 
-export function makeArray(value) {
-  if (Array.isArray(value)) return value;
-  if (value === null || value === undefined) return [];
+export function get(obj, path) {
+  if (arguments.length !== 2) return console.error('Get must be called with two arguments; an object and a property key.');
+  if (!obj) return console.error(`Cannot call get with '${path}' on an undefined object.`);
+  if (typeof path !== 'string') return console.error('The path provided to get must be a string.');
+
+  for (const key of path.split('.')) {
+    if (obj[key] === undefined) return null;
+
+    obj = obj[key];
+  }
+
+  return obj;
+}
+
+export function getOrSet(map, key, defaultValue) {
+  if (!(map instanceof Map)) throw new Error('First argument to getOrSet must be a Map.');
+  
+  if (!map.has(key)) map.set(key, typeof defaultValue === "function" ? defaultValue() : defaultValue);
 
-  return [value];
+  return map.get(key);
 }

package/src/plurarize.js

@@ -0,0 +1,105 @@
+// --- Irregular nouns ---
+const irregular = {
+  person: 'people',
+  man: 'men',
+  woman: 'women',
+  child: 'children',
+  tooth: 'teeth',
+  foot: 'feet',
+  mouse: 'mice',
+  goose: 'geese',
+  ox: 'oxen',
+  cactus: 'cacti',
+  nucleus: 'nuclei',
+  syllabus: 'syllabi',
+  focus: 'foci',
+  fungus: 'fungi',
+  appendix: 'appendices',
+  index: 'indices',
+  criterion: 'criteria',
+  phenomenon: 'phenomena',
+  die: 'dice',
+  thesis: 'theses',
+  analysis: 'analyses',
+  crisis: 'crises',
+  radius: 'radii',
+  corpus: 'corpora',
+};
+
+// --- Uncountables ---
+const uncountable = new Set([
+  'sheep', 'fish', 'deer', 'series', 'species', 'news', 'information',
+  'rice', 'moose', 'bison', 'salmon', 'aircraft', 'offspring'
+]);
+
+// --- Exceptions ---
+const fExceptions = new Set(['chief', 'roof', 'belief', 'chef', 'cliff', 'reef', 'proof', 'brief']);
+
+// Keep only true irregular -o exceptions (consonant + o but take just "s")
+const oExceptions = new Set(['piano', 'photo', 'halo', 'canto', 'solo']);
+
+// --- Utility to preserve casing ---
+function applyCasing(original, plural) {
+  if (original === original.toUpperCase()) return plural.toUpperCase();
+  if (original === original.toLowerCase()) return plural.toLowerCase();
+  if (original[0] === original[0].toUpperCase()) {
+    return plural.charAt(0).toUpperCase() + plural.slice(1);
+  }
+  return plural;
+}
+
+// --- Rule-based pluralization ---
+const rules = [
+  // quiz → quizzes, waltz → waltzes, topaz → topazes
+  [/z$/i, w => (/iz$/i.test(w) ? w + 'zes' : w + 'es')],
+
+  // bus → buses, box → boxes, church → churches, but stomach → stomachs (exclude -ach)
+  [/(s|x|ch|sh)$/i, w => (/ach$/i.test(w) ? w + 's' : w + 'es')],
+
+  // vowel + y → +s (key → keys)
+  [/[aeiou]y$/i, w => w + 's'],
+
+  // consonant + y → -ies (city → cities)
+  [/y$/i, w => w.slice(0, -1) + 'ies'],
+
+  // -fe → -ves (knife → knives), but not chief/roof/etc
+  [/fe$/i, w => (fExceptions.has(w) ? w + 's' : w.slice(0, -2) + 'ves')],
+
+  // -f → -ves (wolf → wolves), but not cliff/etc
+  [/f$/i, w => (fExceptions.has(w) ? w + 's' : w.slice(0, -1) + 'ves')],
+
+  // -sis → -ses (analysis → analyses, thesis → theses)
+  [/sis$/i, w => w.slice(0, -2) + 'ses'],
+
+  // vowel + o → +s (zoo → zoos, video → videos, patio → patios)
+  [/[aeiou]o$/i, w => w + 's'],
+
+  // consonant + o → usually +es, unless in oExceptions
+  [/o$/i, w => (oExceptions.has(w) ? w + 's' : w + 'es')],
+
+  // default: just +s
+  [/$/i, w => w + 's']
+];
+
+// --- Exported pluralizer ---
+export default function pluralize(word) {
+  if (typeof word !== 'string' || !/^[a-zA-Z]+$/.test(word)) {
+    throw new Error('Input must be a single word containing only letters.');
+  }
+
+  const lower = word.toLowerCase();
+
+  if (uncountable.has(lower)) return word;
+
+  if (irregular[lower]) {
+    return applyCasing(word, irregular[lower]);
+  }
+
+  for (const [pattern, transform] of rules) {
+    if (pattern.test(lower)) {
+      return applyCasing(word, transform(lower));
+    }
+  }
+
+  return word; // fallback (shouldn't hit)
+}

package/src/string.js

@@ -23,11 +23,9 @@ export function kebabCaseToPascalCase(str) {
   return kebabToCase(str, true);
 }
 
-export function pluralize(str) {
-  return `${str}s`;
-}
-
 export function generateRandomString(length=8) {
   const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
   return Array(length).fill('').map(() => characters.charAt(Math.floor(Math.random() * characters.length))).join('');
-}
+}
+
+export { default as pluralize } from './plurarize.js';

package/.nvmrc

@@ -1 +0,0 @@
-v22.18.0

package/test/unit/object-test.js

@@ -1,32 +0,0 @@
-import Qunit from 'qunit';
-import { mergeObject } from '@stonyx/utils/object';
-
-const { module, test } = Qunit;
-
-module('[Unit] Object', function() {
-  test('mergeObject works as expected', async function(assert) {
-    assert.deepEqual(
-      mergeObject({ a: 1, b: 2 }, { c: 3 }),
-      { a: 1, b: 2, c: 3 },
-      'New properties are added'
-    );
-
-    assert.deepEqual(
-      mergeObject({ a: 1, b: 2, c: 3 }, { c: 4 }),
-      { a: 1, b: 2, c: 4 },
-      'Old properties are overwritten'
-    );
-
-    assert.deepEqual(
-      mergeObject({ a: 1, b: 2, c: 3 }, { a: 7, c: 23, d: { a: 1, b: 2, c: 3 } }),
-      { a: 7, b: 2, c: 23, d: { a: 1, b: 2, c: 3 } },
-      'Objects are merged recursively'
-    );
-
-    try {
-      mergeObject([], {});
-    } catch {
-      assert.ok(true, 'Array inputs throws error');
-    }
-  });
-});