@stonyx/utils 0.2.3-alpha.23 → 0.2.3-alpha.25

package/README.md

@@ -75,10 +75,12 @@ Creates a file at the given path.
 
 #### `updateFile(filePath, data, options={})`
 
-Updates a file atomically by writing to a temporary file first.
+Updates a file atomically by writing to a sibling swap file first, then renaming it over the target. Throws if the file does not exist.
 
 * `options.json` — boolean, serialize as JSON.
 
+**Concurrency: last writer wins.** Concurrent `updateFile` calls on the same path are safe — each uses a swap file unique to its process and call, so neither caller can throw `ENOENT` or persist the other's bytes — but they are not serialized. The surviving value is whichever caller renames last.
+
 #### `copyFile(sourcePath, targetPath, options={})`
 
 Copies a file from source to target.
@@ -245,6 +247,8 @@ Prompts the user with `(y/N)` and resolves to `true` only if the answer is `"y"`
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided. For headless/container deployments, use `autoMigrate` config or provide a custom input stream.
+
 #### `prompt(question, options={})`
 
 Prompts the user with a question and resolves to the trimmed input string.
@@ -252,6 +256,8 @@ Prompts the user with a question and resolves to the trimmed input string.
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided.
+
 ```js
 import { confirm, prompt } from '@stonyx/utils/prompt';
 

package/dist/file.d.ts

@@ -1,8 +1,10 @@
+import fs from 'fs';
 interface FileOptions {
     json?: boolean;
 }
 interface ReadFileOptions extends FileOptions {
     missingFileCallback?: (filePath: string) => string | Record<string, unknown>;
+    encoding?: BufferEncoding | null;
 }
 interface DeleteFileOptions {
     ignoreAccessFailure?: boolean;
@@ -21,18 +23,40 @@ interface FileImportMeta {
     path: string;
 }
 export declare function createFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a UUID rather than a
+ * timestamp: a whole-second token collided between concurrent callers, which
+ * made one caller throw `ENOENT` and the other silently persist bytes it had
+ * not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialise, and callers
+ * needing a serialisation guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ */
 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 & {
+    encoding: null;
+}): Promise<Buffer>;
 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 deleteFileSync(filePath: string, options?: DeleteFileOptions): void;
 export declare function deleteDirectory(dir: string): Promise<void>;
 export declare function createDirectory(dir: string): Promise<void>;
+export declare function createReadStream(filePath: string, options?: Parameters<typeof fs.createReadStream>[1]): fs.ReadStream;
+export declare function createWriteStream(filePath: string, options?: Parameters<typeof fs.createWriteStream>[1]): fs.WriteStream;
 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

@@ -1,8 +1,9 @@
-import { getTimestamp } from './date.js';
 import { kebabCaseToCamelCase } from './string.js';
 import { objToJson } from './object.js';
+import fs from 'fs';
 import { promises as fsp } from 'fs';
 import path from 'path';
+import { randomUUID } from 'crypto';
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
@@ -16,12 +17,39 @@ export async function createFile(filePath, data, options = {}) {
         throw error instanceof Error ? error : new Error(String(error));
     }
 }
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a UUID rather than a
+ * timestamp: a whole-second token collided between concurrent callers, which
+ * made one caller throw `ENOENT` and the other silently persist bytes it had
+ * not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialise, and callers
+ * needing a serialisation guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ */
 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);
+        // pid + UUID, never a timestamp: the swap name is a uniqueness token, and
+        // whole seconds cannot discriminate between concurrent callers.
+        const swapFile = `${filePath}.temp-${process.pid}-${randomUUID()}`;
+        // `wx` turns any residual name collision into a loud EEXIST rather than a
+        // silent overwrite of another caller's swap bytes.
+        await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), { encoding: 'utf8', flag: 'wx' });
+        try {
+            await fsp.rename(swapFile, filePath);
+        }
+        catch (renameError) {
+            // Leave no orphan behind, and never let the cleanup mask the real error.
+            await fsp.unlink(swapFile).catch(() => { });
+            throw renameError;
+        }
     }
     catch (error) {
         throw error instanceof Error ? error : new Error(String(error));
@@ -58,8 +86,13 @@ 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;
+        const encoding = options.encoding === undefined ? 'utf8' : options.encoding;
+        const fileData = await fsp.readFile(filePath, { encoding: encoding });
+        if (encoding === null)
+            return fileData;
+        if (options.json)
+            return JSON.parse(fileData);
+        return fileData;
     }
     catch (error) {
         const { missingFileCallback } = options;
@@ -81,12 +114,30 @@ export async function deleteFile(filePath, options) {
     }
     await fsp.unlink(filePath);
 }
+export function deleteFileSync(filePath, options) {
+    try {
+        filePath = path.resolve(filePath);
+        fs.accessSync(filePath);
+    }
+    catch (error) {
+        if (options?.ignoreAccessFailure)
+            return;
+        throw error;
+    }
+    fs.unlinkSync(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 function createReadStream(filePath, options) {
+    return fs.createReadStream(path.resolve(filePath), options);
+}
+export function createWriteStream(filePath, options) {
+    return fs.createWriteStream(path.resolve(filePath), options);
+}
 export async function forEachFileImport(dir, callback, options = {}) {
     if (typeof callback !== 'function')
         throw new Error('Callback must be valid function');

package/dist/prompt.js

@@ -1,5 +1,9 @@
 import { createInterface } from 'readline';
 export function confirm(question, { input, output } = {}) {
+    if (!input && !process.stdin.isTTY) {
+        return Promise.reject(new Error('Interactive confirm() requires a TTY on stdin. ' +
+            'For headless/container deployments, use the autoMigrate config option instead.'));
+    }
     const rl = createInterface({
         input: input ?? process.stdin,
         output: output ?? process.stdout,
@@ -12,6 +16,10 @@ export function confirm(question, { input, output } = {}) {
     });
 }
 export function prompt(question, { input, output } = {}) {
+    if (!input && !process.stdin.isTTY) {
+        return Promise.reject(new Error('Interactive prompt() requires a TTY on stdin. ' +
+            'For headless/container deployments, configure non-interactive alternatives instead.'));
+    }
     const rl = createInterface({
         input: input ?? process.stdin,
         output: output ?? process.stdout,

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.3-alpha.23",
+  "version": "0.2.3-alpha.25",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",