@stonyx/utils 0.2.3-alpha.24 → 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

@@ -23,6 +23,22 @@ 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;

package/dist/file.js

@@ -1,9 +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;
 }
@@ -17,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));

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.24",
+  "version": "0.2.3-alpha.25",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",