@impactor/nodejs 3.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Dibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+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.
+  },
+);
+```

package/index.d.ts

@@ -0,0 +1,7 @@
+export * from './src/cache-fs';
+export * from './src/fs';
+export * from './src/fs-sync';
+export * from './src/https';
+export * from './src/process';
+export { default as cacheFs } from './src/cache-fs';
+export { default as https } from './src/https';

package/index.js

@@ -0,0 +1,11 @@
+export * from "./src/cache-fs";
+export * from "./src/fs";
+export * from "./src/fs-sync";
+export * from "./src/https";
+export * from "./src/process";
+import { default as default2 } from "./src/cache-fs";
+import { default as default3 } from "./src/https";
+export {
+  default2 as cacheFs,
+  default3 as https
+};

package/nx.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json",
+  "targetDefaults": {
+    "build": {
+      "executor": "@impactor/nx-manager:universal-builder",
+      "dependsOn": ["typecheck", "prebuild", "^build"],
+      "cache": true,
+      "inputs": ["default", "^default"],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "forceRnDefaultPostBuild": true
+      }
+    },
+    "serve": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build", "preserve"],
+      "continuous": true,
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "NODE_ENV=development pnpm tsx --env-file-if-exists=.env --env-file-if-exists=.env.local dist/main.js"
+      },
+      "configurations": {
+        "production": {
+          "command": "NODE_ENV=production pnpm tsx --env-file-if-exists=.env --env-file-if-exists=.env.local --env-file-if-exists=.env.production --env-file-if-exists=.env.production.local dist/main.js"
+        }
+      }
+    },
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "{projectRoot}/dist"
+      }
+    },
+    "semantic-release": {
+      "executor": "nx:run-commands",
+      "dependsOn": ["build", "prerelease"],
+      "options": {
+        "cwd": "{projectRoot}",
+        "command": "pnpm tsx node_modules/semantic-release/bin/semantic-release.js"
+      },
+      "configurations": {
+        "local": {
+          "command": "DOTENV_CONFIG_PATH=../../.env pnpm run release --no-ci"
+        },
+        "dry": {
+          "command": "DOTENV_CONFIG_PATH=../../.env pnpm run release --no-ci --dry-run"
+        }
+      }
+    },
+    "test": {
+      "inputs": ["test"],
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "dependsOn": ["^build", "pretest"],
+      "configurations": {
+        "unit": {
+          "args": [
+            "--testPathIgnorePatterns '.*\\.e2e\\.spec\\.ts$'",
+            "--testPathIgnorePatterns '/.*-e2e/'",
+            "--testPathIgnorePatterns '/.*-e2e/'"
+          ]
+        },
+        "e2e": {
+          "args": [
+            "--testMatch '**/*-e2e/**/*.{spec,test}.[mc]?[jt]s?(x)'",
+            "--testMatch '**/e2e/**/*.{spec,test}.[mc]?[jt]s?(x)'",
+            "--testMatch  '**/*.e2e.(spec|test).?([mc])[jt]s?(x)'"
+          ]
+        }
+      }
+    },
+    "@angular/build:application": {
+      "cache": true,
+      "dependsOn": ["prebuild", "^build"],
+      "inputs": ["default", "^default"]
+    },
+    "@nx/angular:package": {
+      "cache": true,
+      "dependsOn": ["^build"],
+      "inputs": ["default", "^default"],
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "project": "{projectRoot}/ng-package.json",
+        "tsConfig": "{projectRoot}/tsconfig.lib.json"
+      }
+    },
+    "@nx/js:tsc": {
+      "cache": true,
+      "dependsOn": ["^build"],
+      "inputs": ["default", "^default"]
+    }
+  },
+  "namedInputs": {
+    "default": [
+      "{projectRoot}/src/**/*",
+      "!{projectRoot}/**/*.(spec|test)(.e2e)?.[tj]sx?",
+      "!{projectRoot}/**/e2e/**/*",
+      "{projectRoot}/.env(.*)?",
+      "{workspaceRoot}/tasks/(post-)?build.ts",
+      "{projectRoot}/(project|package|tsconfig)(.+)?.json",
+      "{workspaceRoot}/tsconfig.base.json",
+      {
+        "runtime": "node --version"
+      },
+      {
+        "env": "NODE_ENV"
+      }
+    ],
+    "test": [
+      "default",
+      "{projectRoot}/tsconfig.spec.json",
+      "{projectRoot}/jest.config.[jt]s",
+      "{workspaceRoot}/jest.config.[jt]s",
+      "{projectRoot}/**/*.(spec|test)(.e2e)?.[jt]sx?",
+      "{projectRoot}/**/e2e/**/*.[jt]sx?",
+      {
+        "externalDependencies": ["jest"]
+      }
+    ]
+  },
+  "plugins": [
+    {
+      "plugin": "@nx/js/typescript",
+      "options": {
+        "typecheck": {
+          "targetName": "typecheck"
+        },
+        "build": false
+      }
+    },
+    {
+      "plugin": "@nx/jest/plugin",
+      "options": {
+        "targetName": "test",
+        "ciTargetName": "test-ci"
+      }
+    }
+  ],
+  "tasksRunnerOptions": {
+    "default": {
+      "options": {
+        "useDaemonProcess": false
+      }
+    }
+  },
+  "generators": {
+    "@nx/angular:library": {
+      "linter": "eslint",
+      "unitTestRunner": "jest"
+    },
+    "@nx/angular:component": {
+      "style": "scss"
+    }
+  },
+  "release": {
+    "groups": {
+      "libs": {
+        "projects": ["libs/*"]
+      },
+      "apps": {
+        "projects": ["apps/*"],
+        "changelog": {
+          "projectChangelogs": {
+            "createRelease": "github"
+          }
+        }
+      }
+    },
+    "projectsRelationship": "independent",
+    "version": {
+      "conventionalCommits": true,
+      "updateDependents": "always",
+      "preVersionCommand": "pnpm nx run-many -t build",
+      "manifestRootsToUpdate": [
+        "{projectRoot}",
+        {
+          "path": "{projectRoot}/dist",
+          "preserveLocalDependencyProtocols": false
+        }
+      ]
+    },
+    "releaseTag": {
+      "pattern": "{projectName}@{version}"
+    },
+    "changelog": {
+      "projectChangelogs": true
+    }
+  },
+  "sync": {
+    "applyChanges": false
+  }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@impactor/nodejs",
+  "version": "3.0.1",
+  "type": "module",
+  "description": "nodejs utils",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "nodejs",
+    "javascript",
+    "js"
+  ],
+  "nx": {
+    "projectType": "library",
+    "targets": {
+      "build": {},
+      "semantic-release": {}
+    }
+  },
+  "imports": {
+    "#*": "./src/*.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.js",
+      "default": "./index.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    },
+    "./*": "./src/*"
+  },
+  "dependencies": {
+    "content-type": "^1.0.5",
+    "@impactor/cache": "3.0.1",
+    "@impactor/javascript": "3.0.1"
+  },
+  "devDependencies": {
+    "@types/content-type": "^1.1.9",
+    "semantic-release": "^25.0.2",
+    "semantic-release-monorepo": "^8.0.2",
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": "^18.19.1 || ^20.11.1 || >=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/its-dibo/dibo.git"
+  },
+  "author": "Sherif Eldeeb <sh.eldeeb.2010+github@gmail.com> (https://github.com/its-dibo)",
+  "homepage": "https://github.com/its-dibo/dibo#readme",
+  "bugs": {
+    "url": "https://github.com/its-dibo/dibo/issues",
+    "email": "sh.eldeeb.2010+github@gmail.com"
+  },
+  "license": "MIT",
+  "contributors": [],
+  "funding": [
+    {
+      "type": "paypal",
+      "url": "https://paypal.me/group99001"
+    },
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/GoogleDev"
+    }
+  ],
+  "scripts": {}
+}

package/src/cache-fs.d.ts

@@ -0,0 +1,8 @@
+import { type CacheOptions } from '@impactor/cache';
+import { type PathLike } from 'node:fs';
+import { type ReadOptions } from './fs-sync';
+export interface CacheOpts extends Omit<CacheOptions, 'read' | 'write'> {
+}
+export interface CacheFSOptions extends CacheOptions, ReadOptions {
+}
+export default function cacheFS(files: PathLike | PathLike[], dataSource?: () => unknown, options?: CacheOpts): Promise<unknown>;

package/src/cache-fs.js

@@ -0,0 +1,32 @@
+import { cache } from "@impactor/cache";
+import { readSync, resolve } from "./fs-sync";
+import { write } from "./fs";
+function getCache(entries, options) {
+  for (let filePath of entries) {
+    try {
+      let data = readSync(filePath, options);
+      if (data !== void 0) {
+        return data;
+      }
+    } catch {
+    }
+  }
+  throw "no valid cache found";
+}
+function setCache(entry, data, _options) {
+  return write(entry, data);
+}
+function cacheFS(files, dataSource, options) {
+  let opts = {
+    read: (entries, options2) => getCache(entries, options2),
+    write: (entry, data, options2) => setCache(entry, data, options2),
+    ...options
+  };
+  let cacheEntries = (Array.isArray(files) ? files : [files]).map(
+    (filePath) => resolve(filePath)
+  );
+  return cache(cacheEntries, dataSource, opts);
+}
+export {
+  cacheFS as default
+};

package/src/cache-fs.spec.js

@@ -0,0 +1,38 @@
+import { afterAll, beforeEach, expect, test } from "@jest/globals";
+import cache from "./cache-fs";
+import { remove, write } from "./fs";
+import { resolve } from "./fs-sync";
+let dir = resolve(import.meta.dirname, "./test!!/cache");
+beforeEach(() => remove(`${dir}/file.txt`));
+afterAll(() => remove(dir));
+test("create a new cache", () => cache(`${dir}/new-file.txt`, () => "content").then(
+  (value) => expect(value).toEqual("content")
+));
+test("read from an existing cached file", () => write(`${dir}/file-uguihgkuhkgj.txt`, "content#1").then(() => cache(`${dir}/file-uguihgkuhkgj.txt`, () => "content#2")).then((value) => expect(value).toEqual("content#1")));
+test("read from multiple cache paths, one of them exists - case1", () => write(`${dir}/multiple-case1/file.txt`, "content#1").then(
+  () => cache(
+    [
+      `${dir}/multiple-case1/file.txt`,
+      `${dir}/none1.txt`,
+      `${dir}/none2.txt`
+    ],
+    () => "content#3"
+  )
+).then((value) => expect(value).toEqual("content#1")));
+test("read from multiple cache paths, one of them exists - case2", () => write(`${dir}/multiple-case2/file.txt`, "content#1").then(
+  () => cache(
+    [
+      `${dir}/none1.txt`,
+      `${dir}/multiple-case2/file.txt`,
+      `${dir}/none2.txt`
+    ],
+    () => "content#3"
+  )
+).then((value) => expect(value).toEqual("content#1")));
+test("read from multiple cache paths, non exists", () => cache([`${dir}/none3.txt`, `${dir}/none4.txt`], () => "content").then(
+  (value) => expect(value).toEqual("content")
+));
+test("read from .json file", () => write(`${dir}/file.json`, { x: 1 }).then(() => cache(`${dir}/file.json`, () => "nothing")).then((value) => expect(value).toEqual({ x: 1 })));
+test("read from a Promise dataSource", () => cache(`${dir}/promise.txt`, () => {
+  return new Promise((r) => r("content"));
+}).then((value) => expect(value).toEqual("content")));

package/src/fs-sync.d.ts

@@ -0,0 +1,41 @@
+import { type Obj } from '@impactor/javascript';
+import { type PathLike, type WriteFileOptions } from 'node:fs';
+export declare function resolve(...paths: Array<PathLike | URL>): string;
+export interface ParsePath {
+    type: 'dir' | 'file';
+    dir: string;
+    name: string;
+    extension: string | undefined;
+}
+export declare function parsePath(path: PathLike): ParsePath;
+export declare function getExtensionSync(file: PathLike): string;
+export declare function getSizeSync(path: PathLike | PathLike[], unit?: 'b' | 'kb' | 'mb' | 'gb', filter?: Filter): number;
+export declare function isDirSync(path: PathLike): boolean;
+export declare function getModifiedTimeSync(path: PathLike): number;
+export declare function mkdirSync(path: PathLike | PathLike[], mode?: number | string): void;
+export declare enum MoveOptionsExisting {
+    'replace' = 0,
+    'rename' = 1,
+    'skip' = 2,
+    'stop' = 3,
+    'throw' = 4
+}
+export interface MoveOptions {
+    existing: MoveOptionsExisting | string | ((path: string) => string);
+}
+export declare function moveSync(path: PathLike, newPath: PathLike, _options?: MoveOptions): void;
+export declare function removeSync(path: PathLike | PathLike[], filter?: Filter, keepDir?: boolean): void;
+export declare function copySync(source: PathLike, destination: string, filter?: Filter): any;
+export declare function writeSync(path: PathLike, data: any, options?: WriteFileOptions): void;
+export interface ReadOptions {
+    encoding?: BufferEncoding | null;
+    flag?: 'a' | 'ax' | 'a+' | 'ax+' | 'as' | 'as+' | 'r' | 'r+' | 'rs+' | 'w' | 'wx' | 'w+' | 'wx+';
+    maxAge?: number;
+}
+export declare function readSync<R extends Buffer | string | Array<unknown> | Obj>(path: PathLike | URL, options?: ReadOptions | BufferEncoding): R;
+export declare function stripComments(content: string): string;
+export declare function getEntriesSync(dir?: string | string[], filter?: ((entry: string) => boolean) | RegExp | 'files' | 'dirs', depth?: number, skip?: ((entry: string) => boolean) | RegExp): Array<string>;
+export type Filter = (path: string, type?: 'dir' | 'file') => boolean;
+export declare function recursiveSync(path: PathLike | PathLike[], apply: (path: string, type: 'dir' | 'file') => void, filter?: Filter): any | any[];
+export declare function toPosix(path: PathLike, removeDriverLetter?: boolean): string;
+export declare function validFilePath(path: PathLike): string;