npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

als-file-handler

v1.1.0

Published

A Node.js module for managing and coordinating asynchronous file operations, ensuring sequential execution and robust error handling.

Downloads

13

Readme

als-file-handler

The FileHandler class is a sophisticated tool designed to manage and coordinate asynchronous file operations in Node.js applications. This class efficiently handles scenarios where multiple asynchronous tasks need to interact with the same file, ensuring that these interactions are executed sequentially to avoid conflicts and data corruption.

  • Purpose: FileHandler is designed for streamlined, concurrent-safe file operations, ensuring error-resistant reading, writing, and deleting of files.

  • Queueing File Operations: It queues operations on the same file, executing them sequentially to prevent race conditions and file corruption.

  • Error Handling and Retries: The class robustly handles errors, allowing for a specified number of retry attempts, ideal for addressing temporary issues like file lock contention.

  • Custom Error Handling: FileHandler supports custom error functions for each operation, providing flexible, context-specific error management.

  • Configurable Wait Time, Timeout and Attempts: It offers configurable wait times, timeout for operation and retry attempts, adapting to various operational needs and environments.

Install and require

npm i als-file-handler
const FileHandler = require('als-file-handler')

Method: add

The add method of the FileHandler class is used to enqueue a file operation. It accepts an object with various parameters to configure the operation. Each parameter undergoes validation to ensure correct operation and behavior.

Parameters

  1. path (String):

    • Purpose: Specifies the path of the file to be operated on.
    • Validation: Checked to ensure it is a string and is required.
    • Default Value: No default value; must be provided by the user.
  2. action (Function):

    • Purpose: The asynchronous function representing the file operation (e.g., read, write, delete).
    • Validation: Ensures that it is a function and is required.
    • Default Value: No default value; must be defined by the user.
  3. attempts (Number):

    • Purpose: Defines the number of retry attempts for the operation in case of failure.
    • Validation: Verified to be a number.
    • Default Value: Inherits from FileHandler.attempts, which is 3 by default. Can be overridden by specifying a different value.
  4. errorFn (Function):

    • Purpose: A custom error handling function that is called when an operation fails after all retry attempts.
    • Validation: Checked to ensure it is a function.
    • Default Value: Inherits from FileHandler.errorFn, which defaults to a function returning the error. It can be overridden by providing a custom function.
  5. waitTime (Number):

    • Purpose: The time in milliseconds to wait before retrying the operation after an error.
    • Validation: Verified to be a number.
    • Default Value: Inherits from FileHandler.waitTime, which is 100 ms by default. This value can be changed by specifying a different number.
  6. timeout:

    • Purpose: Sets a maximum time limit for an operation to complete, after which the operation is considered failed.
    • Validation: Verified to be a number (milliseconds).
    • Default Value: If not specified, operations will not have a timeout. Can be set by specifying a number of milliseconds.

waitTime and timeout handled with als-time-manager, which using only one setTimeout for all time tasks.

Return Value

The add method returns a Promise that resolves with an object containing the outcome of the file operation. This Promise only has a resolve path, as it's designed to handle errors internally and return them as part of the resolution. The structure of the resolved object is as follows:

  • Object Structure: { result, error }
    • result: The result of the successful file operation or null if the operation fails or encounters an error.
    • error: An error object if the operation fails, or null if the operation is successful.

When an operation is cancelled due to a timeout, the Promise resolves with an error object indicating the timeout:

  • Timeout Error:
    • If an operation exceeds the specified timeout, the Promise resolves with { result: null, error: [TimeoutErrorObject] }.

Possible Outcomes

  1. Successful Operation:

    • The operation completes successfully.
    • The Promise resolves with { result: [OperationResult], error: null }.
    • [OperationResult] represents the successful result of the file operation.
  2. Failed Operation:

    • The operation fails after the specified number of attempts.
    • The Promise resolves with { result: null, error: [ErrorObject] }.
    • [ErrorObject] contains details of the error that occurred during the operation:
    • path: The file path where the operation was attempted.
    • attempts: The number of attempts made to perform the operation before failing.

Usage

Here is an example of how to use the add method:

const {result,error} = await FileHandler.add({
  path: '/path/to/file.txt',
  action: async () => { /* file operation logic */ },
  attempts: 5,
  errorFn: (error) => console.error('Custom Error:', error),
  waitTime: 200,
  timeout: 5000 // 5 seconds timeout
});

Example

const {writeFile} = require('fs/promises')
const FileHandler = require('als-file-handler')
const action = async () => await writeFile(path, 'Hello')
const path = 'some.txt'
const {result:content,error} = await FileHandler.add({ path, action })

Parent Directory Check

Parent Directory Check:

  • Functionality: Ensures that operations on a file or directory wait for any pending operations on its parent directory to complete, maintaining the integrity of file operations in nested structures.
  • Implementation: Automatically managed by FileHandler; no additional parameters required. The class internally checks and queues operations based on their file paths to respect directory hierarchies.
const {writeFile, mkdir} = require('fs/promises');
const FileHandler = require('als-file-handler');

// Creating a parent directory
const parentDir = 'parentDir';
const childFile = 'parentDir/childFile.txt';

// Operation on the parent directory
FileHandler.add({ path: parentDir, action: async () => await mkdir(parentDir) });

// Operation on a file inside the parent directory
const {result, error} = await FileHandler.add({ path: childFile, action: async () => await writeFile(childFile, 'Hello') });