initial commit

node_modules/atomically/src/constants.ts

@@ -0,0 +1,39 @@
+
+/* IMPORT */
+
+import os from 'node:os';
+import process from 'node:process';
+
+/* MAIN */
+
+const DEFAULT_ENCODING = 'utf8';
+
+const DEFAULT_FILE_MODE = 0o666;
+
+const DEFAULT_FOLDER_MODE = 0o777;
+
+const DEFAULT_READ_OPTIONS = {};
+
+const DEFAULT_WRITE_OPTIONS = {};
+
+const DEFAULT_USER_UID = os.userInfo ().uid;
+
+const DEFAULT_USER_GID = os.userInfo ().gid;
+
+const DEFAULT_TIMEOUT_ASYNC = 7500;
+
+const DEFAULT_TIMEOUT_SYNC = 1000;
+
+const IS_POSIX = !!process.getuid;
+
+const IS_USER_ROOT = process.getuid ? !process.getuid () : false;
+
+const LIMIT_BASENAME_LENGTH = 128; //TODO: Fetch the real limit from the filesystem //TODO: Fetch the whole-path length limit too
+
+const LIMIT_FILES_DESCRIPTORS = 10_000; //TODO: Fetch the real limit from the filesystem
+
+const NOOP = () => {};
+
+/* EXPORT */
+
+export {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, IS_USER_ROOT, LIMIT_BASENAME_LENGTH, LIMIT_FILES_DESCRIPTORS, NOOP};

node_modules/atomically/src/index.ts

@@ -0,0 +1,331 @@
+
+/* 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};
+export type {Encoding, ReadOptions, WriteOptions};

node_modules/atomically/src/types.ts

@@ -0,0 +1,37 @@
+
+/* 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};

node_modules/atomically/src/utils/lang.ts

@@ -0,0 +1,34 @@
+
+/* 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};

node_modules/atomically/src/utils/scheduler.ts

@@ -0,0 +1,62 @@
+
+/* 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;

node_modules/atomically/src/utils/temp.ts

@@ -0,0 +1,102 @@
+
+/* 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;