npm package: @impactor/nodejs
Description: nodejs utils
Author: Sherif Eldeeb
Latest version: 5.0.0

Nodejs utils

# FS operations

Working with files, directories, and paths.
all functions are available as promise or sync, for example:

- `read()` -> the promise version
- `readSync()` -> the sync version

The following are just a choosen examples, to see the full API check our docs.

### Reading a JSON file

```ts
import { read } from "@impactor/nodejs-utils";

let file = await read("./package.json");
```

The content automatically pared as JSON.

### Reading a cache file if only it is not expired

```ts
import { read } from "@impactor/nodejs-utils";

let cache = await read("./cache.json", { maxAge: 10000 });
```

### Writing a JSON data

```ts
import { write } from "@impactor/nodejs-utils";

write("./data/reports/report.json", { status: "ok" });
```

The data will be stringified automatically.
also, you don't need to manually create the directory, because it is created recursively.
for instance if `./data` or `./data/reports` doesn't exist, it'll be created.

### copy or move a file or folder, you can filter the files to be copied.

```ts
// copy static non-typescript files
copy("src", "dist/assets", (file) => !file.endsWith(".ts"));

// move flat-structure project to use "src"
move(".", "./src", (file) => file.endsWith(".ts"));

// remove log files
remove("./data", (file) => file.endsWith(".log"));
```

## Parsing a path

```ts
let info = parsePath("./data/report.txt");

console.log(`type: ${info.type}`); // file or dir
console.log(`file extension: ${info.extension}`); // txt
console.log(`the containing dir: ${info.dir}`); // data
console.log(`file name: ${info.name}`); // report
```

### Get the total size of a file or directory

```ts
getSize("./data");
```

### Create the full path directory recursively

```ts
mkdir("./data/reports/summaries");
```

if one portion of the specified path doesn't exist, the full path will be created.
for example, if `./data` doesn't exist, it'll be created first, then `reports` then `summaries`.
It also accepts files, the containing directory will be created.

## get all or some files or directory.

```ts
// list first-level directories under "apps"
getEntries("apps", "dirs", 1);

// list all files under "reports" and its children
getEntries("reports", "files");

// list all JSON files under reports
getEntries("reports", "files", (entry) => entry.endsWith(".json"));

// list all summary log files under "reports"
// i.e. files that follow this pattern "summary-{number}.log"
getEntries("reports", "files", /summary-\d\.log/);
```

### Apply an arbitrary action recursively

```ts
// remove all "*.log" files under "reports" and its subdirectories, recursively.
recursive(
  "reports", // the starting point
  (entry) => unlinkSync(entry), // the action to be applied
  (entry) => entry.endsWith(".log"), // the filter
);
```

# Cache

Manage caches.
built on top of [@impactor/cache](https://www.npmjs.com/package/@impactor/cache), using file-system caching.

```ts
let cache = await cacheFS(
  // cache entries
  ["./report-today.json", "./report-yesterday.json"],
  // data source
  () => fetch("https://my-server.com/getReport"),
  // cache options
  {
    maxAge: 1000,
    maxStale: 2000,
    // you don't need to define `read()` and `write()` here.
  },
);
```