atomically 2.0.2 → 2.0.4

package/src/index.ts

@@ -1,330 +0,0 @@
-
-/* IMPORT */
-
-import path from 'node:path';
-import fs from 'stubborn-fs';
-import {DEFAULT_ENCODING, DEFAULT_FILE_MODE, DEFAULT_FOLDER_MODE, DEFAULT_READ_OPTIONS, DEFAULT_WRITE_OPTIONS, DEFAULT_USER_UID, DEFAULT_USER_GID, DEFAULT_TIMEOUT_ASYNC, DEFAULT_TIMEOUT_SYNC, IS_POSIX} from './constants';
-import {isException, isFunction, isString, isUndefined} from './utils/lang';
-import Scheduler from './utils/scheduler';
-import Temp from './utils/temp';
-import type {Callback, Data, Disposer, Encoding, Path, ReadOptions, WriteOptions} from './types';
-
-/* MAIN */
-
-function readFile ( filePath: Path, options: Encoding | ReadOptions & { encoding: string } ): Promise<string>;
-function readFile ( filePath: Path, options?: ReadOptions ): Promise<Buffer>;
-function readFile ( filePath: Path, options: Encoding | ReadOptions = DEFAULT_READ_OPTIONS ): Promise<Buffer | string> {
-
-  if ( isString ( options ) ) return readFile ( filePath, { encoding: options } );
-
-  const timeout = Date.now () + ( ( options.timeout ?? DEFAULT_TIMEOUT_ASYNC ) || -1 );
-
-  return fs.retry.readFile ( timeout )( filePath, options );
-
-}
-
-function readFileSync ( filePath: Path, options: Encoding | ReadOptions & { encoding: string } ): string;
-function readFileSync ( filePath: Path, options?: ReadOptions ): Buffer;
-function readFileSync ( filePath: Path, options: Encoding | ReadOptions = DEFAULT_READ_OPTIONS ): Buffer | string {
-
-  if ( isString ( options ) ) return readFileSync ( filePath, { encoding: options } );
-
-  const timeout = Date.now () + ( ( options.timeout ?? DEFAULT_TIMEOUT_SYNC ) || -1 );
-
-  return fs.retry.readFileSync ( timeout )( filePath, options );
-
-}
-
-function writeFile ( filePath: Path, data: Data, callback?: Callback ): Promise<void>;
-function writeFile ( filePath: Path, data: Data, options?: Encoding | WriteOptions, callback?: Callback ): Promise<void>;
-function writeFile ( filePath: Path, data: Data, options?: Encoding | WriteOptions | Callback, callback?: Callback ): Promise<void> {
-
-  if ( isFunction ( options ) ) return writeFile ( filePath, data, DEFAULT_WRITE_OPTIONS, options );
-
-  const promise = writeFileAsync ( filePath, data, options );
-
-  if ( callback ) promise.then ( callback, callback );
-
-  return promise;
-
-}
-
-async function writeFileAsync ( filePath: Path, data: Data, options: Encoding | WriteOptions = DEFAULT_WRITE_OPTIONS ): Promise<void> {
-
-  if ( isString ( options ) ) return writeFileAsync ( filePath, data, { encoding: options } );
-
-  const timeout = Date.now () + ( ( options.timeout ?? DEFAULT_TIMEOUT_ASYNC ) || -1 );
-
-  let schedulerCustomDisposer: Disposer | null = null;
-  let schedulerDisposer: Disposer | null = null;
-  let tempDisposer: Disposer | null = null;
-  let tempPath: string | null = null;
-  let fd: number | null = null;
-
-  try {
-
-    if ( options.schedule ) schedulerCustomDisposer = await options.schedule ( filePath );
-
-    schedulerDisposer = await Scheduler.schedule ( filePath );
-
-    const filePathReal = await fs.attempt.realpath ( filePath );
-    const filePathExists = !!filePathReal;
-
-    filePath = filePathReal || filePath;
-
-    [tempPath, tempDisposer] = Temp.get ( filePath, options.tmpCreate || Temp.create, !( options.tmpPurge === false ) );
-
-    const useStatChown = IS_POSIX && isUndefined ( options.chown );
-    const useStatMode = isUndefined ( options.mode );
-
-    if ( filePathExists && ( useStatChown || useStatMode ) ) {
-
-      const stats = await fs.attempt.stat ( filePath );
-
-      if ( stats ) {
-
-        options = { ...options };
-
-        if ( useStatChown ) {
-
-          options.chown = { uid: stats.uid, gid: stats.gid };
-
-        }
-
-        if ( useStatMode ) {
-
-          options.mode = stats.mode;
-
-        }
-
-      }
-
-    }
-
-    if ( !filePathExists ) {
-
-      const parentPath = path.dirname ( filePath );
-
-      await fs.attempt.mkdir ( parentPath, {
-        mode: DEFAULT_FOLDER_MODE,
-        recursive: true
-      });
-
-    }
-
-    fd = await fs.retry.open ( timeout )( tempPath, 'w', options.mode || DEFAULT_FILE_MODE );
-
-    if ( options.tmpCreated ) {
-
-      options.tmpCreated ( tempPath );
-
-    }
-
-    if ( isString ( data ) ) {
-
-      await fs.retry.write ( timeout )( fd, data, 0, options.encoding || DEFAULT_ENCODING );
-
-    } else if ( !isUndefined ( data ) ) {
-
-      await fs.retry.write ( timeout )( fd, data, 0, data.length, 0 );
-
-    }
-
-    if ( options.fsync !== false ) {
-
-      if ( options.fsyncWait !== false ) {
-
-        await fs.retry.fsync ( timeout )( fd );
-
-      } else {
-
-        fs.attempt.fsync ( fd );
-
-      }
-
-    }
-
-    await fs.retry.close ( timeout )( fd );
-
-    fd = null;
-
-    if ( options.chown && ( options.chown.uid !== DEFAULT_USER_UID || options.chown.gid !== DEFAULT_USER_GID ) ) {
-
-      await fs.attempt.chown ( tempPath, options.chown.uid, options.chown.gid );
-
-    }
-
-    if ( options.mode && options.mode !== DEFAULT_FILE_MODE ) {
-
-      await fs.attempt.chmod ( tempPath, options.mode );
-
-    }
-
-    try {
-
-      await fs.retry.rename ( timeout )( tempPath, filePath );
-
-    } catch ( error: unknown ) {
-
-      if ( !isException ( error ) ) throw error;
-
-      if ( error.code !== 'ENAMETOOLONG' ) throw error;
-
-      await fs.retry.rename ( timeout )( tempPath, Temp.truncate ( filePath ) );
-
-    }
-
-    tempDisposer ();
-
-    tempPath = null;
-
-  } finally {
-
-    if ( fd ) await fs.attempt.close ( fd );
-
-    if ( tempPath ) Temp.purge ( tempPath );
-
-    if ( schedulerCustomDisposer ) schedulerCustomDisposer ();
-
-    if ( schedulerDisposer ) schedulerDisposer ();
-
-  }
-
-}
-
-function writeFileSync ( filePath: Path, data: Data, options: Encoding | WriteOptions = DEFAULT_WRITE_OPTIONS ): void {
-
-  if ( isString ( options ) ) return writeFileSync ( filePath, data, { encoding: options } );
-
-  const timeout = Date.now () + ( ( options.timeout ?? DEFAULT_TIMEOUT_SYNC ) || -1 );
-
-  let tempDisposer: Disposer | null = null;
-  let tempPath: string | null = null;
-  let fd: number | null = null;
-
-  try {
-
-    const filePathReal = fs.attempt.realpathSync ( filePath );
-    const filePathExists = !!filePathReal;
-
-    filePath = filePathReal || filePath;
-
-    [tempPath, tempDisposer] = Temp.get ( filePath, options.tmpCreate || Temp.create, !( options.tmpPurge === false ) );
-
-    const useStatChown = IS_POSIX && isUndefined ( options.chown );
-    const useStatMode = isUndefined ( options.mode );
-
-    if ( filePathExists && ( useStatChown || useStatMode ) ) {
-
-      const stats = fs.attempt.statSync ( filePath );
-
-      if ( stats ) {
-
-        options = { ...options };
-
-        if ( useStatChown ) {
-
-          options.chown = { uid: stats.uid, gid: stats.gid };
-
-        }
-
-        if ( useStatMode ) {
-
-          options.mode = stats.mode;
-
-        }
-
-      }
-
-    }
-
-    if ( !filePathExists ) {
-
-      const parentPath = path.dirname ( filePath );
-
-      fs.attempt.mkdirSync ( parentPath, {
-        mode: DEFAULT_FOLDER_MODE,
-        recursive: true
-      });
-
-    }
-
-    fd = fs.retry.openSync ( timeout )( tempPath, 'w', options.mode || DEFAULT_FILE_MODE );
-
-    if ( options.tmpCreated ) {
-
-      options.tmpCreated ( tempPath );
-
-    }
-
-    if ( isString ( data ) ) {
-
-      fs.retry.writeSync ( timeout )( fd, data, 0, options.encoding || DEFAULT_ENCODING );
-
-    } else if ( !isUndefined ( data ) ) {
-
-      fs.retry.writeSync ( timeout )( fd, data, 0, data.length, 0 );
-
-    }
-
-    if ( options.fsync !== false ) {
-
-      if ( options.fsyncWait !== false ) {
-
-        fs.retry.fsyncSync ( timeout )( fd );
-
-      } else {
-
-        fs.attempt.fsync ( fd );
-
-      }
-
-    }
-
-    fs.retry.closeSync ( timeout )( fd );
-
-    fd = null;
-
-    if ( options.chown && ( options.chown.uid !== DEFAULT_USER_UID || options.chown.gid !== DEFAULT_USER_GID ) ) {
-
-      fs.attempt.chownSync ( tempPath, options.chown.uid, options.chown.gid );
-
-    }
-
-    if ( options.mode && options.mode !== DEFAULT_FILE_MODE ) {
-
-      fs.attempt.chmodSync ( tempPath, options.mode );
-
-    }
-
-    try {
-
-      fs.retry.renameSync ( timeout )( tempPath, filePath );
-
-    } catch ( error: unknown ) {
-
-      if ( !isException ( error ) ) throw error;
-
-      if ( error.code !== 'ENAMETOOLONG' ) throw error;
-
-      fs.retry.renameSync ( timeout )( tempPath, Temp.truncate ( filePath ) );
-
-    }
-
-    tempDisposer ();
-
-    tempPath = null;
-
-  } finally {
-
-    if ( fd ) fs.attempt.closeSync ( fd );
-
-    if ( tempPath ) Temp.purge ( tempPath );
-
-  }
-
-}
-
-/* EXPORT */
-
-export {readFile, readFileSync, writeFile, writeFileSync};

package/src/types.ts

@@ -1,37 +0,0 @@
-
-/* MAIN */
-
-type Callback = ( error: Exception | void ) => void;
-
-type Data = Uint8Array | string | undefined;
-
-type Disposer = () => void;
-
-type Encoding = 'ascii' | 'base64' | 'binary' | 'hex' | 'latin1' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2';
-
-type Exception = NodeJS.ErrnoException;
-
-type Path = string;
-
-type ReadOptions = {
-  encoding?: Encoding | null,
-  mode?: string | number | false,
-  timeout?: number
-};
-
-type WriteOptions = {
-  chown?: { gid: number, uid: number } | false,
-  encoding?: Encoding | null,
-  fsync?: boolean,
-  fsyncWait?: boolean,
-  mode?: string | number | false,
-  schedule?: ( filePath: string ) => Promise<Disposer>,
-  timeout?: number,
-  tmpCreate?: ( filePath: string ) => string,
-  tmpCreated?: ( filePath: string ) => void,
-  tmpPurge?: boolean
-};
-
-/* EXPORT */
-
-export type {Callback, Data, Disposer, Encoding, Exception, Path, ReadOptions, WriteOptions};

package/src/utils/lang.ts

@@ -1,34 +0,0 @@
-
-/* IMPORT */
-
-import type {Exception} from '../types';
-
-/* MAIN */
-
-const isException = ( value: unknown ): value is Exception => {
-
-  return ( value instanceof Error ) && ( 'code' in value );
-
-};
-
-const isFunction = ( value: unknown ): value is Function => {
-
-  return ( typeof value === 'function' );
-
-};
-
-const isString = ( value: unknown ): value is string => {
-
-  return ( typeof value === 'string' );
-
-};
-
-const isUndefined = ( value: unknown ): value is undefined => {
-
-  return ( value === undefined );
-
-};
-
-/* EXPORT */
-
-export {isException, isFunction, isString, isUndefined};

package/src/utils/scheduler.ts

@@ -1,62 +0,0 @@
-
-/* IMPORT */
-
-import type {Disposer} from '../types';
-
-/* HELPERS */
-
-const Queues: Record<string, Function[] | undefined> = {};
-
-/* MAIN */
-
-//TODO: Maybe publish this as a standalone package
-
-const Scheduler = {
-
-  /* API */
-
-  next: ( id: string ): void => {
-
-    const queue = Queues[id];
-
-    if ( !queue ) return;
-
-    queue.shift ();
-
-    const job = queue[0];
-
-    if ( job ) {
-
-      job ( () => Scheduler.next ( id ) );
-
-    } else {
-
-      delete Queues[id];
-
-    }
-
-  },
-
-  schedule: ( id: string ): Promise<Disposer> => {
-
-    return new Promise ( resolve => {
-
-      let queue = Queues[id];
-
-      if ( !queue ) queue = Queues[id] = [];
-
-      queue.push ( resolve );
-
-      if ( queue.length > 1 ) return;
-
-      resolve ( () => Scheduler.next ( id ) );
-
-    });
-
-  }
-
-};
-
-/* EXPORT */
-
-export default Scheduler;

package/src/utils/temp.ts

@@ -1,102 +0,0 @@
-
-/* IMPORT */
-
-import path from 'node:path';
-import fs from 'stubborn-fs';
-import whenExit from 'when-exit';
-import {LIMIT_BASENAME_LENGTH} from '../constants';
-import type {Disposer} from '../types';
-
-/* MAIN */
-
-//TODO: Maybe publish this as a standalone package
-
-const Temp = {
-
-  /* VARIABLES */
-
-  store: <Record<string, boolean>> {}, // filePath => purge
-
-  /* API */
-
-  create: ( filePath: string ): string => {
-
-    const randomness = `000000${Math.floor ( Math.random () * 16777215 ).toString ( 16 )}`.slice ( -6 ); // 6 random-enough hex characters
-    const timestamp = Date.now ().toString ().slice ( -10 ); // 10 precise timestamp digits
-    const prefix = 'tmp-';
-    const suffix = `.${prefix}${timestamp}${randomness}`;
-    const tempPath = `${filePath}${suffix}`;
-
-    return tempPath;
-
-  },
-
-  get: ( filePath: string, creator: ( filePath: string ) => string, purge: boolean = true ): [string, Disposer] => {
-
-    const tempPath = Temp.truncate ( creator ( filePath ) );
-
-    if ( tempPath in Temp.store ) return Temp.get ( filePath, creator, purge ); // Collision found, try again
-
-    Temp.store[tempPath] = purge;
-
-    const disposer = () => delete Temp.store[tempPath];
-
-    return [tempPath, disposer];
-
-  },
-
-  purge: ( filePath: string ): void => {
-
-    if ( !Temp.store[filePath] ) return;
-
-    delete Temp.store[filePath];
-
-    fs.attempt.unlink ( filePath );
-
-  },
-
-  purgeSync: ( filePath: string ): void => {
-
-    if ( !Temp.store[filePath] ) return;
-
-    delete Temp.store[filePath];
-
-    fs.attempt.unlinkSync ( filePath );
-
-  },
-
-  purgeSyncAll: (): void => {
-
-    for ( const filePath in Temp.store ) {
-
-      Temp.purgeSync ( filePath );
-
-    }
-
-  },
-
-  truncate: ( filePath: string ): string => { // Truncating paths to avoid getting an "ENAMETOOLONG" error //FIXME: This doesn't really always work, the actual filesystem limits must be detected for this to be implemented correctly
-
-    const basename = path.basename ( filePath );
-
-    if ( basename.length <= LIMIT_BASENAME_LENGTH ) return filePath; //FIXME: Rough and quick attempt at detecting ok lengths
-
-    const truncable = /^(\.?)(.*?)((?:\.[^.]+)?(?:\.tmp-\d{10}[a-f0-9]{6})?)$/.exec ( basename );
-
-    if ( !truncable ) return filePath; //FIXME: No truncable part detected, can't really do much without also changing the parent path, which is unsafe, hoping for the best here
-
-    const truncationLength = basename.length - LIMIT_BASENAME_LENGTH;
-
-    return `${filePath.slice ( 0, - basename.length )}${truncable[1]}${truncable[2].slice ( 0, - truncationLength )}${truncable[3]}`; //FIXME: The truncable part might be shorter than needed here
-
-  }
-
-};
-
-/* INIT */
-
-whenExit ( Temp.purgeSyncAll ); // Ensuring purgeable temp files are purged on exit
-
-/* EXPORT */
-
-export default Temp;

package/tasks/benchmark.js

@@ -1,76 +0,0 @@
-
-/* IMPORT */
-
-import {randomUUID} from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import {setTimeout as delay} from 'node:timers/promises';
-import writeFileAtomic from 'write-file-atomic';
-import {writeFile, writeFileSync} from '../dist/index.js';
-
-/* MAIN */
-
-const TEMP = os.tmpdir ();
-const UUID = randomUUID ();
-const DST = i => path.join ( TEMP, `atomically-${UUID}-temp-${i}.txt` );
-const ITERATIONS = 250;
-
-const runSingleAsync = async ( name, fn, buffer, options ) => {
-  console.time ( name );
-  for ( let i = 0; i < ITERATIONS; i++ ) {
-    await fn ( DST ( i ), buffer, options );
-  }
-  console.timeEnd ( name );
-  await delay ( 1000 );
-};
-
-const runSingleSync = async ( name, fn, buffer, options ) => {
-  console.time ( name );
-  for ( let i = 0; i < ITERATIONS; i++ ) {
-    fn ( DST ( i ), buffer, options );
-  }
-  console.timeEnd ( name );
-  await delay ( 1000 );
-};
-
-const runAllDummy = () => { // Preparation run
-  runSingleSync ( 'dummy', fs.writeFileSync, '' );
-};
-
-const runAllAsync = async ( name, buffer ) => {
-  await runSingleAsync ( `${name} -> async -> write-file-atomic`, writeFileAtomic, buffer, { mode: 0o666 } );
-  await runSingleAsync ( `${name} -> async -> write-file-atomic (faster)`, writeFileAtomic, buffer );
-  await runSingleAsync ( `${name} -> async -> write-file-atomic (fastest)`, writeFileAtomic, buffer, { fsync: false } );
-  await runSingleAsync ( `${name} -> async -> atomically`, writeFile, buffer );
-  await runSingleAsync ( `${name} -> async -> atomically (faster)`, writeFile, buffer, { mode: false, chown: false, fsyncWait: false } );
-  await runSingleAsync ( `${name} -> async -> atomically (fastest)`, writeFile, buffer, { mode: false, chown: false, fsync: false } );
-};
-
-const runAllSync = ( name, buffer ) => {
-  runSingleSync ( `${name} -> sync -> write-file-atomic`, writeFileAtomic.sync, buffer, { mode: 0o666 } );
-  runSingleSync ( `${name} -> sync -> write-file-atomic (faster)`, writeFileAtomic.sync, buffer );
-  runSingleSync ( `${name} -> sync -> write-file-atomic (fastest)`, writeFileAtomic.sync, buffer, { fsync: false } );
-  runSingleSync ( `${name} -> sync -> atomically`, writeFileSync, buffer );
-  runSingleSync ( `${name} -> sync -> atomically (faster)`, writeFileSync, buffer, { mode: false, chown: false, fsyncWait: false } );
-  runSingleSync ( `${name} -> sync -> atomically (fastest)`, writeFileSync, buffer, { mode: false, chown: false, fsync: false } );
-};
-
-const runAll = async ( name, buffer ) => {
-  await runAllAsync ( name, buffer );
-  console.log ( '-------------------' );
-  runAllSync ( name, buffer );
-};
-
-const run = async () => {
-  runAllDummy ();
-  console.log ( '===================' );
-  await runAll ( '100kb', Buffer.allocUnsafe ( 100 * 1024 ) );
-  console.log ( '===================' );
-  await runAll ( '10kb', Buffer.allocUnsafe ( 10 * 1024 ) );
-  console.log ( '===================' );
-  await runAll ( '1kb', Buffer.allocUnsafe ( 1024 ) );
-  console.log ( '===================' );
-};
-
-run ();