@stonyx/utils 0.2.3-beta.2 → 0.2.3-beta.20

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-utils/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/utils.svg)](https://www.npmjs.com/package/@stonyx/utils)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # stonyx-utils
 
 Utilities module for the Stonyx Framework. Provides helpers for files, objects, strings, dates, and promises.

package/dist/date.d.ts

@@ -0,0 +1 @@
+export declare function getTimestamp(dateObject?: Date | null): number;

package/dist/date.js

@@ -0,0 +1,4 @@
+export function getTimestamp(dateObject = null) {
+    const ts = dateObject ? dateObject.getTime() : Date.now();
+    return Math.floor(ts / 1000);
+}

package/dist/file.d.ts

@@ -0,0 +1,38 @@
+interface FileOptions {
+    json?: boolean;
+}
+interface ReadFileOptions extends FileOptions {
+    missingFileCallback?: (filePath: string) => string | Record<string, unknown>;
+}
+interface DeleteFileOptions {
+    ignoreAccessFailure?: boolean;
+}
+interface ForEachFileImportOptions {
+    ignoreAccessFailure?: boolean;
+    recursive?: boolean;
+    recursiveNaming?: boolean;
+    rawName?: boolean;
+    namePrefix?: string;
+    fullExport?: boolean;
+}
+interface FileImportMeta {
+    name: string;
+    stats: import('fs').Stats;
+    path: string;
+}
+export declare function createFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+export declare function updateFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+interface CopyFileOptions {
+    overwrite?: boolean;
+}
+export declare function copyFile(sourcePath: string, targetPath: string, options?: CopyFileOptions): Promise<boolean>;
+export declare function readFile(filePath: string, options: ReadFileOptions & {
+    json: true;
+}): Promise<Record<string, unknown>>;
+export declare function readFile(filePath: string, options?: ReadFileOptions): Promise<string>;
+export declare function deleteFile(filePath: string, options?: DeleteFileOptions): Promise<void>;
+export declare function deleteDirectory(dir: string): Promise<void>;
+export declare function createDirectory(dir: string): Promise<void>;
+export declare function forEachFileImport(dir: string, callback: (output: unknown, meta: FileImportMeta) => void | Promise<void>, options?: ForEachFileImportOptions): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export {};

package/dist/file.js

@@ -0,0 +1,135 @@
+import { getTimestamp } from './date.js';
+import { kebabCaseToCamelCase } from './string.js';
+import { objToJson } from './object.js';
+import { promises as fsp } from 'fs';
+import path from 'path';
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+export async function createFile(filePath, data, options = {}) {
+    try {
+        filePath = path.resolve(filePath);
+        await createDirectory(path.dirname(filePath));
+        await fsp.writeFile(filePath, options.json ? objToJson(data) : String(data), 'utf8');
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function updateFile(filePath, data, options = {}) {
+    try {
+        await fsp.access(filePath);
+        const swapFile = `${filePath}.temp-${getTimestamp()}`;
+        await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), 'utf8');
+        await fsp.rename(swapFile, filePath);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function copyFile(sourcePath, targetPath, options = {}) {
+    try {
+        sourcePath = path.resolve(sourcePath);
+        targetPath = path.resolve(targetPath);
+        await fsp.access(sourcePath);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    try {
+        await fsp.access(targetPath);
+        if (!options.overwrite)
+            return false;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') { /* file doesn't exist — proceed with copy */ }
+        else
+            throw error;
+    }
+    try {
+        await fsp.copyFile(sourcePath, targetPath);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(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 options.json ? JSON.parse(fileData) : fileData;
+    }
+    catch (error) {
+        const { missingFileCallback } = options;
+        if (isNodeError(error) && error.code === 'ENOENT' && missingFileCallback) {
+            return missingFileCallback(filePath);
+        }
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function deleteFile(filePath, options) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+    }
+    catch (error) {
+        if (options?.ignoreAccessFailure)
+            return;
+        throw error;
+    }
+    await fsp.unlink(filePath);
+}
+export async function deleteDirectory(dir) {
+    await fsp.rm(dir, { recursive: true, force: true });
+}
+export async function createDirectory(dir) {
+    await fsp.mkdir(dir, { recursive: true });
+}
+export async function forEachFileImport(dir, callback, options = {}) {
+    if (typeof callback !== 'function')
+        throw new Error('Callback must be valid function');
+    try {
+        await fsp.access(dir);
+    }
+    catch (error) {
+        if (!options.ignoreAccessFailure)
+            throw new Error(`Unable to access directory: ${dir}`);
+        return;
+    }
+    const files = await fsp.readdir(dir);
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const stats = await fsp.stat(filePath);
+        if (options.recursive && stats.isDirectory()) {
+            const newOptions = { ...options };
+            if (options.recursiveNaming) {
+                const pathPrefix = options.rawName ? file : `${kebabCaseToCamelCase(file)}`;
+                newOptions.namePrefix = options.namePrefix ? `${options.namePrefix}${pathPrefix}/` : `${pathPrefix}/`;
+            }
+            await forEachFileImport(filePath, callback, newOptions);
+            continue;
+        }
+        if (!stats.isFile() || !file.endsWith('.js'))
+            continue;
+        const prefix = process.platform === 'win32' ? 'file://' : '';
+        const rawName = file.replace('.js', '');
+        let name = options.rawName ? rawName : kebabCaseToCamelCase(rawName);
+        if (options.namePrefix)
+            name = `${options.namePrefix}${name}`;
+        const exported = await import(prefix + path.resolve(filePath));
+        const output = !options.fullExport ? exported.default : exported;
+        callback(output, { name, stats, path: filePath });
+    }
+}
+export async function fileExists(filePath) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/fuzzy-match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generic fuzzy string matching for cross-source reconciliation.
+ * Handles Unicode normalization, stop-word filtering, and word-set similarity scoring.
+ */
+export interface FuzzyMatchOptions {
+    stopWords?: string[];
+    delimiter?: string;
+    threshold?: number;
+}
+export interface FuzzyMatchResult<T extends {
+    name: string;
+}> {
+    entry: T;
+    score: number;
+}
+export default class FuzzyMatch {
+    stopWords: string[];
+    delimiter: string;
+    threshold: number;
+    constructor(options?: FuzzyMatchOptions);
+    normalize(name: string): string;
+    similarity(nameA: string, nameB: string): number;
+    findBestMatch<T extends {
+        name: string;
+    }>(nameA: string, nameB: string, entries: T[], threshold?: number): FuzzyMatchResult<T> | null;
+}

package/dist/fuzzy-match.js

@@ -0,0 +1,80 @@
+/**
+ * Generic fuzzy string matching for cross-source reconciliation.
+ * Handles Unicode normalization, stop-word filtering, and word-set similarity scoring.
+ */
+function normalizeString(name, stopWords = []) {
+    let result = name
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ');
+    if (stopWords.length) {
+        const pattern = new RegExp(`\\b(${stopWords.join('|')})\\b`, 'g');
+        result = result.replace(pattern, '');
+    }
+    return result.replace(/\s+/g, ' ').trim();
+}
+function wordSet(normalized) {
+    return new Set(normalized.split(' ').filter(w => w.length > 1));
+}
+export default class FuzzyMatch {
+    stopWords;
+    delimiter;
+    threshold;
+    constructor(options = {}) {
+        this.stopWords = options.stopWords || [];
+        this.delimiter = options.delimiter || '\u00B7';
+        this.threshold = options.threshold || 0.35;
+    }
+    normalize(name) {
+        return normalizeString(name, this.stopWords);
+    }
+    similarity(nameA, nameB) {
+        const aN = this.normalize(nameA);
+        const sN = this.normalize(nameB);
+        if (!aN || !sN)
+            return 0;
+        if (aN === sN)
+            return 1.0;
+        if (aN.includes(sN) || sN.includes(aN))
+            return 0.9;
+        const aWords = wordSet(aN);
+        const sWords = wordSet(sN);
+        if (aWords.size === 0 || sWords.size === 0)
+            return 0;
+        let overlap = 0;
+        for (const w of aWords) {
+            if (sWords.has(w)) {
+                overlap++;
+            }
+            else {
+                for (const sw of sWords) {
+                    if (sw.startsWith(w) || w.startsWith(sw)) {
+                        overlap += 0.7;
+                        break;
+                    }
+                }
+            }
+        }
+        return overlap / Math.max(aWords.size, sWords.size);
+    }
+    findBestMatch(nameA, nameB, entries, threshold) {
+        const minScore = threshold ?? this.threshold;
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const entry of entries) {
+            const parts = entry.name.split(this.delimiter);
+            if (parts.length !== 2)
+                continue;
+            const [entryA, entryB] = parts;
+            const normalScore = (this.similarity(nameA, entryA) + this.similarity(nameB, entryB)) / 2;
+            const reversedScore = (this.similarity(nameA, entryB) + this.similarity(nameB, entryA)) / 2;
+            const score = Math.max(normalScore, reversedScore);
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = entry;
+            }
+        }
+        return bestScore >= minScore && bestMatch ? { entry: bestMatch, score: bestScore } : null;
+    }
+}

package/dist/object.d.ts

@@ -0,0 +1,14 @@
+export declare function deepCopy<T>(obj: T): T;
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function objToJson(obj: JsonValue | Record<string, unknown>, format?: string | number): string;
+export declare function makeArray<T>(obj: T | T[]): T[];
+interface MergeOptions {
+    ignoreNewKeys?: boolean;
+}
+export declare function mergeObject(obj1: Record<string, unknown>, obj2: Record<string, unknown>, options?: MergeOptions): Record<string, unknown>;
+export declare function get(obj: Record<string, unknown>, path: string): unknown;
+export declare function get(obj: unknown, path?: unknown): undefined;
+export declare function getOrSet<K, V>(map: Map<K, V>, key: K, defaultValue: V | (() => V)): V;
+export {};

package/dist/object.js

@@ -0,0 +1,60 @@
+export function deepCopy(obj) {
+    return JSON.parse(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.');
+    if (obj1 === null || typeof obj1 !== 'object')
+        return cloneShallow(obj2);
+    if (obj2 === null || typeof obj2 !== 'object')
+        return cloneShallow(obj1);
+    const result = {};
+    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];
+        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 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.');
+    let current = obj;
+    for (const key of path.split('.')) {
+        if (current[key] === undefined)
+            return;
+        current = current[key];
+    }
+    return current;
+}
+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)) {
+        const value = typeof defaultValue === 'function' ? defaultValue() : defaultValue;
+        map.set(key, value);
+    }
+    return map.get(key);
+}

package/dist/plurarize.d.ts

@@ -0,0 +1 @@
+export default function pluralize(word: string): string;

package/dist/plurarize.js

@@ -0,0 +1,87 @@
+// --- 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))
+        return word;
+    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/dist/promise.d.ts

@@ -0,0 +1 @@
+export declare function sleep(seconds: number): Promise<void>;

package/dist/promise.js

@@ -0,0 +1,5 @@
+export async function sleep(seconds) {
+    return new Promise(resolve => {
+        setTimeout(resolve, 1000 * seconds);
+    });
+}

package/dist/prompt.d.ts

@@ -0,0 +1,8 @@
+import type { Readable, Writable } from 'stream';
+interface PromptOptions {
+    input?: Readable;
+    output?: Writable;
+}
+export declare function confirm(question: string, { input, output }?: PromptOptions): Promise<boolean>;
+export declare function prompt(question: string, { input, output }?: PromptOptions): Promise<string>;
+export {};

package/dist/prompt.js

@@ -0,0 +1,25 @@
+import { createInterface } from 'readline';
+export function confirm(question, { input, output } = {}) {
+    const rl = createInterface({
+        input: input ?? process.stdin,
+        output: output ?? process.stdout,
+    });
+    return new Promise(resolve => {
+        rl.question(`${question} (y/N) `, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === 'y');
+        });
+    });
+}
+export function prompt(question, { input, output } = {}) {
+    const rl = createInterface({
+        input: input ?? process.stdin,
+        output: output ?? process.stdout,
+    });
+    return new Promise(resolve => {
+        rl.question(`${question} `, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}

package/dist/string.d.ts

@@ -0,0 +1,5 @@
+export declare function kebabCaseToCamelCase(str: string): string;
+export declare function kebabCaseToPascalCase(str: string): string;
+export declare function camelCaseToKebabCase(str: string): string;
+export declare function generateRandomString(length?: number): string;
+export { default as pluralize } from './plurarize.js';

package/dist/string.js

@@ -0,0 +1,32 @@
+function kebabToCase(str, pascal = false) {
+    let out = '';
+    let upperNext = pascal; // PascalCase starts uppercase
+    for (let i = 0; i < str.length; i++) {
+        const ch = str.charAt(i);
+        if (ch === '-') {
+            upperNext = true;
+        }
+        else if (upperNext) {
+            out += ch.toUpperCase();
+            upperNext = false;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+export function kebabCaseToCamelCase(str) {
+    return kebabToCase(str, false);
+}
+export function kebabCaseToPascalCase(str) {
+    return kebabToCase(str, true);
+}
+export function camelCaseToKebabCase(str) {
+    return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+}
+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/package.json

@@ -3,20 +3,46 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.3-beta.2",
+  "version": "0.2.3-beta.20",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",
     "url": "https://github.com/abofs/stonyx-utils.git"
   },
   "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "exports": {
-    "./date": "./src/date.js",
-    "./object": "./src/object.js",
-    "./file": "./src/file.js",
-    "./promise": "./src/promise.js",
-    "./prompt": "./src/prompt.js",
-    "./string": "./src/string.js"
+    "./date": {
+      "types": "./dist/date.d.ts",
+      "default": "./dist/date.js"
+    },
+    "./object": {
+      "types": "./dist/object.d.ts",
+      "default": "./dist/object.js"
+    },
+    "./file": {
+      "types": "./dist/file.d.ts",
+      "default": "./dist/file.js"
+    },
+    "./promise": {
+      "types": "./dist/promise.d.ts",
+      "default": "./dist/promise.js"
+    },
+    "./prompt": {
+      "types": "./dist/prompt.d.ts",
+      "default": "./dist/prompt.js"
+    },
+    "./string": {
+      "types": "./dist/string.d.ts",
+      "default": "./dist/string.js"
+    },
+    "./fuzzy-match": {
+      "types": "./dist/fuzzy-match.d.ts",
+      "default": "./dist/fuzzy-match.js"
+    }
   },
   "publishConfig": {
     "access": "public",
@@ -28,12 +54,17 @@
     "Stone Costa <stone.costa@synamicd.com>"
   ],
   "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@types/qunit": "^2.19.13",
+    "@types/sinon": "^21.0.1",
     "fs": "^0.0.1-security",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3"
   },
-  "dependencies": {},
   "scripts": {
-    "test": "qunit"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm build:test && qunit 'dist-test/test/**/*.js'"
   }
 }

package/.claude/project-structure.md

@@ -1,187 +0,0 @@
-# Project Structure
-
-## Index
-
-- [Overview](#overview)
-- [Tech Stack](#tech-stack)
-- [File Structure](#file-structure)
-- [Package Exports](#package-exports)
-- [Module Documentation](#module-documentation)
-  - [date.js](#srcdate.js)
-  - [file.js](#srcfile.js)
-  - [object.js](#srcobject.js)
-  - [plurarize.js](#srcplurarize.js)
-  - [promise.js](#srcpromise.js)
-  - [prompt.js](#srcprompt.js)
-  - [string.js](#srcstring.js)
-- [Dependencies](#dependencies)
-- [Test Patterns](#test-patterns)
-- [CI/CD](#cicd)
-
----
-
-## Overview
-
-`@stonyx/utils` is a utilities module for the Stonyx Framework. It provides pure JavaScript helper functions for file system operations, object manipulation, string transformations, date handling, promises, and interactive CLI prompts.
-
-- **Package name:** `@stonyx/utils`
-- **Version:** `0.2.3-beta.1`
-- **License:** Apache-2.0
-- **Module system:** ES Modules (`"type": "module"`)
-- **Node version:** v24.13.0 (`.nvmrc`)
-- **Package manager:** pnpm
-- **Repository:** https://github.com/abofs/stonyx-utils.git
-
-## Tech Stack
-
-- **Runtime:** Node.js (ESM)
-- **Test framework:** QUnit 2.x
-- **Test mocking:** Sinon 21.x
-- **CI/CD:** GitHub Actions (reusable workflows from `abofs/stonyx-workflows`)
-- **Publishing:** npm (public, with provenance)
-
-## File Structure
-
-```
-stonyx-utils/
-  .claude/                        # Claude project memory
-    project-structure.md          # This file
-  .github/
-    workflows/
-      ci.yml                      # CI on PRs to dev/main (reusable workflow)
-      publish.yml                 # NPM publish on push to main / manual dispatch
-  src/
-    date.js                       # Date utilities
-    file.js                       # File system utilities
-    object.js                     # Object/array utilities
-    plurarize.js                  # Pluralization engine (NOTE: filename typo)
-    promise.js                    # Promise utilities
-    prompt.js                     # CLI prompt utilities
-    string.js                     # String transformation utilities
-  test/
-    unit/
-      file-test.js                # Tests for src/file.js
-      prompt-test.js              # Tests for src/prompt.js
-      object/
-        get-test.js               # Tests for object get()
-        getOrSet-test.js          # Tests for object getOrSet()
-        object-test.js            # Tests for mergeObject()
-      string/
-        plurarize-test.js         # Tests for pluralize (NOTE: filename typo)
-        string-test.js            # Tests for string conversion functions
-  .gitignore
-  .npmignore                      # Excludes test/ and .nvmrc from published package
-  .nvmrc                          # Node v24.13.0
-  LICENSE.md                      # Apache-2.0
-  README.md
-  package.json
-  pnpm-lock.yaml
-```
-
-## Package Exports
-
-Defined in `package.json` under `"exports"`:
-
-| Import path            | File             |
-| ---------------------- | ---------------- |
-| `@stonyx/utils/date`   | `src/date.js`    |
-| `@stonyx/utils/object` | `src/object.js`  |
-| `@stonyx/utils/file`   | `src/file.js`    |
-| `@stonyx/utils/promise`| `src/promise.js` |
-| `@stonyx/utils/prompt` | `src/prompt.js`  |
-| `@stonyx/utils/string` | `src/string.js`  |
-
-## Module Documentation
-
-### `src/date.js`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `getTimestamp` | `getTimestamp(dateObject?: Date): number` | Returns UNIX timestamp in seconds. If `dateObject` is provided, uses that date; otherwise uses `Date.now()`. |
-
-### `src/file.js`
-
-Imports: `@stonyx/utils/date`, `@stonyx/utils/string`, `@stonyx/utils/object`, `fs`, `path`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `createFile` | `createFile(filePath, data, options?): Promise<void>` | Creates a file. `options.json` serializes data as JSON. Auto-creates parent directories. |
-| `updateFile` | `updateFile(filePath, data, options?): Promise<void>` | Atomically updates an existing file via temp-file swap. `options.json` for JSON serialization. Throws if file does not exist. |
-| `copyFile` | `copyFile(sourcePath, targetPath, options?): Promise<boolean>` | Copies a file. Returns `false` if target exists and `options.overwrite` is not `true`. |
-| `readFile` | `readFile(filePath, options?): Promise<string\|object>` | Reads a file. `options.json` parses as JSON. `options.missingFileCallback(filePath)` called on ENOENT. |
-| `deleteFile` | `deleteFile(filePath, options?): Promise<void>` | Deletes a file. `options.ignoreAccessFailure` silences missing-file errors. |
-| `deleteDirectory` | `deleteDirectory(dir): Promise<void>` | Recursively deletes a directory (`rm -rf`). |
-| `createDirectory` | `createDirectory(dir): Promise<void>` | Recursively creates a directory (`mkdir -p`). |
-| `forEachFileImport` | `forEachFileImport(dir, callback, options?): Promise<void>` | Dynamically imports all `.js` files in a directory and invokes `callback(exports, { name, stats, path })`. Options: `fullExport`, `rawName`, `ignoreAccessFailure`, `recursive`, `recursiveNaming`, `namePrefix`. |
-| `fileExists` | `fileExists(filePath): Promise<boolean>` | Returns `true` if file exists, `false` otherwise. |
-
-### `src/object.js`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `deepCopy` | `deepCopy(obj): any` | Deep clones via `JSON.parse(JSON.stringify())`. |
-| `objToJson` | `objToJson(obj, format?): string` | Stringifies object with formatting (default: tab). |
-| `makeArray` | `makeArray(obj): Array` | Wraps value in array if not already an array. |
-| `mergeObject` | `mergeObject(obj1, obj2, options?): object` | Deep merges two objects. `options.ignoreNewKeys` skips keys not in `obj1`. Throws on array input. |
-| `get` | `get(obj, path): any\|null` | Safely traverses dot-notation path. Returns `null` if any segment is `undefined`. Uses `console.error` for validation (does not throw). |
-| `getOrSet` | `getOrSet(map, key, defaultValue): any` | Gets from a `Map`, or sets `defaultValue` (or calls it if function) when key is missing. Throws if not a `Map`. |
-
-### `src/plurarize.js`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `default` (pluralize) | `pluralize(word): string` | Returns plural form of an English noun. Handles irregular nouns, uncountable nouns, and rule-based suffixes (s/x/ch/sh, y, f/fe, o, z). Preserves casing. |
-
-### `src/promise.js`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `sleep` | `sleep(seconds): Promise<void>` | Async delay for the given number of seconds. |
-
-### `src/prompt.js`
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `confirm` | `confirm(question, options?): Promise<boolean>` | Prompts user with `(y/N)` and returns `true` only if input is `"y"` (case-insensitive). Options: `{ input, output }` for custom streams. |
-| `prompt` | `prompt(question, options?): Promise<string>` | Prompts user with a question and returns trimmed input. Options: `{ input, output }` for custom streams. |
-
-### `src/string.js`
-
-Re-exports `pluralize` from `./plurarize.js`.
-
-| Export | Signature | Description |
-| ------ | --------- | ----------- |
-| `kebabCaseToCamelCase` | `kebabCaseToCamelCase(str): string` | Converts `kebab-case` to `camelCase`. |
-| `kebabCaseToPascalCase` | `kebabCaseToPascalCase(str): string` | Converts `kebab-case` to `PascalCase`. |
-| `camelCaseToKebabCase` | `camelCaseToKebabCase(str): string` | Converts `camelCase` to `kebab-case`. |
-| `generateRandomString` | `generateRandomString(length?): string` | Generates random alphanumeric string (default length: 8). |
-| `pluralize` | (re-export) | Re-exported from `./plurarize.js`. |
-
-## Dependencies
-
-### Runtime
-
-None (`"dependencies": {}`).
-
-### Dev
-
-| Package | Version | Purpose |
-| ------- | ------- | ------- |
-| `qunit` | `^2.24.1` | Test framework |
-| `sinon` | `^21.0.0` | Stubs/spies for tests |
-| `fs` | `^0.0.1-security` | Placeholder (Node built-in) |
-
-## Test Patterns
-
-- **Framework:** QUnit with nested `module()` blocks
-- **Mocking:** Sinon spies/stubs (used for `console.error` spying in `get-test.js`, stub factories in `getOrSet-test.js`)
-- **Stream mocking:** Custom `Readable`/`Writable` streams in `prompt-test.js`
-- **File tests:** Create temp directory in `beforeEach`, clean up in `afterEach`
-- **Run command:** `pnpm test` (which runs `qunit`)
-- **Import style:** Tests import from package exports (e.g., `@stonyx/utils/object`)
-
-## CI/CD
-
-- **CI workflow** (`ci.yml`): Runs on PRs to `dev` and `main` branches. Uses reusable workflow from `abofs/stonyx-workflows/.github/workflows/ci.yml@main`. Concurrency grouping cancels in-progress runs for the same branch.
-- **Publish workflow** (`publish.yml`): Triggers on push to `main`, PR events, or manual dispatch. Supports `patch`/`minor`/`major` version bumps and custom version strings. Uses reusable workflow from `abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main`. Requires `contents: write`, `id-token: write`, and `pull-requests: write` permissions.
-- **Prepublish hook:** `npm test` runs before publish via `prepublishOnly` script.

package/.github/workflows/ci.yml

@@ -1,16 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-    branches: [dev, main]
-
-concurrency:
-  group: ci-${{ github.head_ref || github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    uses: abofs/stonyx-workflows/.github/workflows/ci.yml@main

package/.github/workflows/publish.yml

@@ -1,35 +0,0 @@
-name: Publish to NPM
-
-on:
-  workflow_dispatch:
-    inputs:
-      version-type:
-        description: 'Version type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      custom-version:
-        description: 'Custom version (optional, overrides version-type)'
-        required: false
-        type: string
-  pull_request:
-    types: [opened, synchronize, reopened]
-    branches: [main]
-  push:
-    branches: [main]
-
-permissions:
-  contents: write
-  id-token: write
-  pull-requests: write
-
-jobs:
-  publish:
-    uses: abofs/stonyx-workflows/.github/workflows/npm-publish.yml@main
-    with:
-      version-type: ${{ github.event.inputs.version-type }}
-      custom-version: ${{ github.event.inputs.custom-version }}
-    secrets: inherit

package/src/date.js

@@ -1,5 +0,0 @@
-export function getTimestamp(dateObject=null) {
-  const ts = dateObject ? dateObject.getTime() : Date.now();
-
-  return Math.floor(ts / 1000);
-}

package/src/file.js

@@ -1,145 +0,0 @@
-import { getTimestamp } from '@stonyx/utils/date';
-import { kebabCaseToCamelCase } from '@stonyx/utils/string';
-import { objToJson } from '@stonyx/utils/object';
-import { promises as fsp } from 'fs';
-import path from 'path';
-
-export async function createFile(filePath, data, options={}) {
-  try {
-    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, options={}) {
-  try {
-    await fsp.access(filePath);
-
-    const swapFile = `${filePath}.temp-${getTimestamp()}`;
-    await fsp.writeFile(swapFile, options.json ? objToJson(data) : data);
-    await fsp.rename(swapFile, filePath);
-  } catch (error) {
-    
-    throw new Error(error);
-  }
-}
-
-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 options.json ? JSON.parse(fileData) : fileData;
-  } catch (error) {
-    const { missingFileCallback } = options;
-
-    if (error.code === 'ENOENT' && missingFileCallback) {
-      return missingFileCallback(filePath);
-    }
-
-    throw new Error(error);
-  }
-}
-
-export async function deleteFile(filePath, options) {
-  try {
-    filePath = path.resolve(filePath);
-    
-    await fsp.access(filePath);
-  } catch (error) {
-    if (options?.ignoreAccessFailure) return;
-    throw error;
-  }
-
-  await fsp.unlink(filePath);
-}
-
-export async function deleteDirectory(dir) {
-  await fsp.rm(dir, { recursive: true, force: true });
-}
-
-export async function createDirectory(dir) {
-  await fsp.mkdir(dir, { recursive: true });
-}
-
-export async function forEachFileImport(dir, callback, options={}) {
-  if (typeof callback !== 'function') throw new Error('Callback must be valid function');
-
-  try {
-    await fsp.access(dir);
-  } catch (error) {
-    if (!options.ignoreAccessFailure) throw new Error(`Unable to access directory: ${dir}`);
-    return;
-  }
-
-  const files = await fsp.readdir(dir);
-
-  for (const file of files) {
-    const filePath = path.join(dir, file);
-    const stats = await fsp.stat(filePath);
-
-    if (options.recursive && stats.isDirectory()) {
-      const newOptions = { ...options };
-      
-      if (options.recursiveNaming) {
-        const pathPrefix = options.rawName ? file : `${kebabCaseToCamelCase(file)}`;
-        newOptions.namePrefix = options.namePrefix ? `${options.namePrefix}${pathPrefix}/` : `${pathPrefix}/`;
-      }
-
-      await forEachFileImport(filePath, callback, newOptions);
-      continue;
-    }
-
-    if (!stats.isFile() || !file.endsWith('.js')) continue;
-
-    const prefix = process.platform === 'win32' ? 'file://' : '';
-    const rawName = file.replace('.js', '');
-    let name = options.rawName ? rawName : kebabCaseToCamelCase(rawName);
-
-    if (options.namePrefix) name = `${options.namePrefix}${name}`;
-
-    const exported = await import(prefix + path.resolve(filePath));
-    const output = !options.fullExport ? exported.default : exported;
-
-    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

@@ -1,61 +0,0 @@
-export function deepCopy(obj) {
-  return JSON.parse(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.');
-
-  if (obj1 === null || typeof obj1 !== 'object') return cloneShallow(obj2);
-  if (obj2 === null || typeof obj2 !== 'object') return cloneShallow(obj1);
-
-  const result = {};
-
-  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];
-    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 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

@@ -1,103 +0,0 @@
-// --- 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)) return word;
-
-  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/promise.js

@@ -1,5 +0,0 @@
-export async function sleep(seconds) {
-  return new Promise(resolve => {
-    setTimeout(resolve, 1000 * seconds);
-  })
-}

package/src/prompt.js

@@ -1,29 +0,0 @@
-import { createInterface } from 'readline';
-
-export function confirm(question, { input, output } = {}) {
-  const rl = createInterface({
-    input: input ?? process.stdin,
-    output: output ?? process.stdout,
-  });
-
-  return new Promise(resolve => {
-    rl.question(`${question} (y/N) `, answer => {
-      rl.close();
-      resolve(answer.trim().toLowerCase() === 'y');
-    });
-  });
-}
-
-export function prompt(question, { input, output } = {}) {
-  const rl = createInterface({
-    input: input ?? process.stdin,
-    output: output ?? process.stdout,
-  });
-
-  return new Promise(resolve => {
-    rl.question(`${question} `, answer => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}

package/src/string.js

@@ -1,35 +0,0 @@
-function kebabToCase(str, pascal=false) {
-  let out = '';
-  let upperNext = pascal; // PascalCase starts uppercase
-  for (let i = 0; i < str.length; i++) {
-    const ch = str.charAt(i);
-    if (ch === '-') {
-      upperNext = true;
-    } else if (upperNext) {
-      out += ch.toUpperCase();
-      upperNext = false;
-    } else {
-      out += ch;
-    }
-  }
-  return out;
-}
-
-export function kebabCaseToCamelCase(str) {
-  return kebabToCase(str, false);
-}
-
-export function kebabCaseToPascalCase(str) {
-  return kebabToCase(str, true);
-}
-
-export function camelCaseToKebabCase(str) {
-  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-}
-
-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';