@stonyx/utils 0.1.1 → 0.2.0

package/README.md

@@ -1,33 +1,225 @@
 # stonyx-utils
 
-# TODO: Generate documentation for all utils
+Utilities module for the Stonyx Framework. Provides helpers for files, objects, strings, dates, and promises.
 
-## Running the test suite
+---
+
+## 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
 ```
 
-### Valid Options
+---
+
+## 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
+```
 
-| 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
 

package/package.json

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

package/src/object.js

@@ -2,14 +2,20 @@ 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 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.');
 
@@ -32,8 +38,24 @@ export function mergeObject(obj1, obj2, options={}) {
   return result;
 }
 
-function cloneShallow(value) {
-  if (Array.isArray(value)) return value.slice();
-  if (value && typeof value === 'object') return { ...value };
-  return value;
+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 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';