@arcgis/node-toolkit 5.2.0-next.100

package/LICENSE.md

@@ -0,0 +1,19 @@
+# Licensing
+
+COPYRIGHT Esri
+
+All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.
+
+This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement.
+You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.
+
+See use restrictions at https://www.esri.com/content/dam/esrisites/en-us/media/legal/ma-full/ma-full.pdf.
+
+For additional information, contact:
+Environmental Systems Research Institute, Inc.
+Attn: Contracts and Legal Services Department
+380 New York Street
+Redlands, California, USA 92373
+USA
+
+email: legal@esri.com

package/README.md

@@ -0,0 +1,12 @@
+# ArcGIS Maps SDK for JavaScript - Node Utils
+
+**No Esri Technical Support included.**
+
+Package that is part of the [ArcGIS Maps SDK for JavaScript](https://developers.arcgis.com/javascript).
+
+It is not intended to be used directly, but rather used as a dependency by other packages in the SDK.
+
+## License
+
+This package is licensed under the terms described in the `LICENSE.md` file, located in the root of the package, and at https://js.arcgis.com/5.2/LICENSE.txt.
+For third party notices, see https://js.arcgis.com/5.2/third-party-notices.txt.

package/dist/file.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Asynchronously check if a file or directory exists.
+ * Using un-promisified version because promises version creates exceptions
+ * which interferes with debugging when "Pause on caught exceptions" is enabled
+ *
+ * @public
+ * @param file
+ */
+export declare const existsAsync: (file: string) => Promise<boolean>;
+/**
+ * Create a file with the specified content if it does not already exist.
+ *
+ * @public
+ * @param filePath
+ * @param content
+ */
+export declare function createFileIfNotExists(filePath: string, content: string): Promise<void>;
+/**
+ * Climb the directory tree upward, until it founds a directory that contains the
+ * target file, and return resulting full path.
+ * Returns `undefined` if the file is not found.
+ *
+ * @public
+ * @param target
+ * @param startDirectory
+ */
+export declare function findPath(target: string, startDirectory?: string): string | undefined;
+/**
+ * Asynchronously climb the directory tree upward, until it founds a directory that contains the
+ * target file, and return resulting full path.
+ * Returns `undefined` if the file is not found.
+ *
+ * @public
+ * @param target
+ * @param startDirectory
+ */
+export declare function asyncFindPath(target: string, startDirectory?: string): Promise<string | undefined>;

package/dist/file.js

@@ -0,0 +1,49 @@
+import { access, existsSync } from "node:fs";
+import { constants, mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep, join } from "path";
+import { fileURLToPath } from "node:url";
+const existsAsync = async (file) => (
+  //#endregion existsAsync
+  await new Promise((resolve2) => access(file, constants.F_OK, (error) => resolve2(!error)))
+);
+async function createFileIfNotExists(filePath, content) {
+  await mkdir(dirname(filePath), { recursive: true });
+  if (!await existsAsync(filePath)) {
+    await writeFile(filePath, content, { encoding: "utf8" });
+  }
+}
+function* getSearchCandidates(target, startDirectory) {
+  const resolvedStartDirectory = startDirectory.startsWith("file:///") ? dirname(fileURLToPath(startDirectory)) : resolve(startDirectory);
+  const parentPath = resolvedStartDirectory.split(sep);
+  while (parentPath.length > searchStopIndex) {
+    yield join(
+      ...sep === "/" ? ["/"] : [],
+      ...parentPath,
+      target
+    );
+    parentPath.pop();
+  }
+}
+function findPath(target, startDirectory = process.cwd()) {
+  for (const fullPath of getSearchCandidates(target, startDirectory)) {
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+const searchStopIndex = 0;
+async function asyncFindPath(target, startDirectory = process.cwd()) {
+  for (const fullPath of getSearchCandidates(target, startDirectory)) {
+    if (await existsAsync(fullPath)) {
+      return fullPath;
+    }
+  }
+  return void 0;
+}
+export {
+  asyncFindPath,
+  createFileIfNotExists,
+  existsAsync,
+  findPath
+};

package/dist/glob.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Read `.gitignore` files and convert it to globs that are accepted by ESLint
+ *
+ * @public
+ * @param filePath
+ * @example
+ * ```ts
+ * // eslint.config.js
+ * import { gitIgnoreFileToGlobs } from "@arcgis/node-toolkit/glob";
+ * import { globalIgnores } from "eslint/config";
+ *
+ * export default [
+ *   globalIgnores([
+ *     ...gitIgnoreFileToGlobs(import.meta.dirname + "/.gitignore"),
+ *     ...gitIgnoreFileToGlobs(import.meta.dirname + "/.prettierignore"),
+ *   ]),
+ *   // ...
+ * ];
+ * ```
+ */
+export declare function gitIgnoreFileToGlobs(filePath: string): string[];
+/**
+ * @public
+ * @param pattern
+ * @deprecated Use gitIgnoreFileToGlobs from "@arcgis/node-toolkit/glob"
+ * instead
+ */
+export declare const gitIgnoreToGlob: (pattern: string) => string;

package/dist/glob.js

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+function gitIgnoreFileToGlobs(filePath) {
+  return readFileSync(filePath, "utf8").split("\n").filter((line) => line.trim().length > 0 && !line.trim().startsWith("#")).map(gitIgnoreToGlob);
+}
+const gitIgnoreToGlob = (pattern) => fixAbsoluteSyntax(fixMatchFilesSyntax(pattern.trim()));
+function fixAbsoluteSyntax(pattern) {
+  if (pattern.startsWith("/")) {
+    return pattern.slice(1);
+  }
+  if (pattern.startsWith("!/")) {
+    return `!${pattern.slice(2)}`;
+  }
+  const isAlreadyCorrect = pattern.startsWith("**") || pattern.startsWith("!**");
+  const basePattern = pattern.startsWith("!") ? pattern.slice(1) : pattern;
+  return isAlreadyCorrect ? pattern : `${pattern.startsWith("!") ? "!" : ""}**/${basePattern}`;
+}
+function fixMatchFilesSyntax(pattern) {
+  const base = pattern.split("/").at(-1);
+  const isAlreadyCorrect = pattern.endsWith("**") || pattern.includes("{") || base?.includes(".");
+  if (isAlreadyCorrect) {
+    return pattern;
+  }
+  return pattern.endsWith("/*") ? `${pattern}*` : pattern.endsWith("/") ? `${pattern}**` : `${pattern}/**`;
+}
+export {
+  gitIgnoreFileToGlobs,
+  gitIgnoreToGlob
+};

package/dist/packageJson.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A subset of the package.json typing.
+ * Useful for the majority of cases where you just need to read the name, version, and dependencies of a package.json file.
+ *
+ * The full package.json type is insanely large (20k lines):
+ * https://github.com/ffflorian/schemastore-updater/blob/main/schemas/package/index.d.ts#L20067
+ *
+ * @public
+ */
+export type PackageJson = {
+    /** @public */
+    "name": string;
+    /** @public */
+    "version": string;
+    /** @public */
+    "private"?: boolean;
+    /** @public */
+    "type"?: "commonjs" | "module";
+    /** @public */
+    "main"?: string;
+    /** @public */
+    "module"?: string;
+    /** @public */
+    "types"?: string;
+    /** @public */
+    "files"?: string[];
+    /** @public */
+    "bin"?: Record<string, string> | string;
+    /** @public */
+    "man"?: string[] | string;
+    /**
+     * @public
+     * @see https://pnpm.io/package_json#publishconfigdirectory
+     */
+    "publishConfig"?: {
+        directory?: string;
+        linkDirectory?: boolean;
+    };
+    /** @public */
+    "dependencies"?: Record<string, string>;
+    /** @public */
+    "devDependencies"?: Record<string, string>;
+    /** @public */
+    "peerDependencies"?: Record<string, string>;
+    /** @public */
+    "peerDependenciesMeta"?: Record<string, {
+        optional?: boolean;
+    }>;
+    /** @public */
+    "optionalDependencies"?: Record<string, string>;
+    /** @public */
+    "css.customData"?: string[];
+    /** @public */
+    "customElements"?: string;
+    /** @public */
+    "html.customData"?: string[];
+    /** @public */
+    "web-types"?: string;
+    /** @public */
+    "exports"?: Record<string, Record<string, string> | string>;
+    /** @public */
+    "engines"?: {
+        node?: string;
+    };
+    /** @public */
+    "scripts"?: Record<string, string>;
+    /** @public */
+    "packageManager"?: string;
+};
+/**
+ * Synchronously retrieves the package.json file for the current project or a specified location.
+ * If the location is not specified, it will search for the package.json file starting from the current working directory.
+ * This function caches the package.json file for future calls to avoid unnecessary file system reads.
+ *
+ * @public
+ * @param location
+ */
+export declare function retrievePackageJson(location?: string): PackageJson;
+/**
+ * Asynchronously retrieves the package.json file for the current project or a specified location.
+ * If the location is not specified, it will search for the package.json file starting from the current working directory.
+ * This function caches the package.json file for future calls to avoid unnecessary file system reads.
+ *
+ * @public
+ * @param location
+ */
+export declare function asyncRetrievePackageJson(location?: string): Promise<PackageJson>;
+/**
+ * Returns an absolute path to the root of a package in node_modules, without
+ * trailing slash.
+ *
+ * @public
+ * @param packageName
+ * @param cwd
+ */
+export declare function fetchPackageLocation(packageName: string, cwd?: string): Promise<string>;
+/**
+ * Find the package.json for a given package name in node_modules, and return the parsed JSON.
+ * Returns undefined if the package.json cannot be found.
+ *
+ * @public
+ * @param packageName
+ */
+export declare function findPackageJson(packageName: string): PackageJson | undefined;

package/dist/packageJson.js

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+import { path } from "./path.js";
+import { asyncFindPath, findPath } from "./file.js";
+import { readFileSync } from "node:fs";
+const cachedPackageJson = {};
+const cachedPackageJsonPromises = {};
+let rootPackageJsonLocation;
+function retrievePackageJson(location) {
+  const packageJsonPath = getPackageJsonPath(location);
+  cachedPackageJson[packageJsonPath] ??= JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+  return cachedPackageJson[packageJsonPath];
+}
+async function asyncRetrievePackageJson(location) {
+  const packageJsonPath = getPackageJsonPath(location);
+  if (packageJsonPath in cachedPackageJson) {
+    return cachedPackageJson[packageJsonPath];
+  }
+  cachedPackageJsonPromises[packageJsonPath] ??= asyncReadPackageJson(packageJsonPath);
+  const result = await cachedPackageJsonPromises[packageJsonPath];
+  cachedPackageJson[packageJsonPath] ??= result;
+  return result;
+}
+const getPackageJsonPath = (location) => location ? path.resolve(location, "package.json") : rootPackageJsonLocation ??= findPath("package.json");
+const asyncReadPackageJson = async (location) => JSON.parse(await readFile(location, "utf-8"));
+const cachedPackageLocation = {};
+const cachedPackageLocationPromises = {};
+async function fetchPackageLocation(packageName, cwd) {
+  if (packageName in cachedPackageLocation) {
+    return cachedPackageLocation[packageName];
+  }
+  cachedPackageLocationPromises[packageName] ??= asyncFindPath(
+    path.join("node_modules", packageName, "package.json"),
+    cwd
+  ).then((packageJsonLocation) => {
+    if (packageJsonLocation === void 0) {
+      throw Error(
+        `@arcgis/node-toolkit: Unable to resolve package.json location for "${packageName}" package. Current working directory: ${process.cwd()}`
+      );
+    }
+    return path.dirname(packageJsonLocation);
+  });
+  const result = await cachedPackageLocationPromises[packageName];
+  cachedPackageLocation[packageName] ??= result;
+  return cachedPackageLocation[packageName];
+}
+function findPackageJson(packageName) {
+  const path2 = findPath(`node_modules/${packageName}/`);
+  if (!path2) {
+    return void 0;
+  }
+  return retrievePackageJson(path2);
+}
+export {
+  asyncRetrievePackageJson,
+  fetchPackageLocation,
+  findPackageJson,
+  retrievePackageJson
+};

package/dist/path.d.ts

@@ -0,0 +1,60 @@
+/**
+ * See ../path.md for details about our path handling.
+ *
+ * DOCS: publish to webgis reference docs for this package, and the ./path.md file
+ */
+import { posix } from "path";
+/**
+ * Determines if the current environment is POSIX (e.g., macOS, Linux) or not.
+ * This is called "isPosix" rather than "isNotWindows" because even if we are
+ * on Windows, we could be running in a POSIX environment (e.g. WSL2)
+ *
+ * @public
+ */
+export declare const isPosix: boolean;
+/**
+ * Converts a Windows-style path to a POSIX-style path.
+ *
+ * @public
+ * @param relativePath The path to convert to POSIX-style separators.
+ */
+export declare const toPosixPathSeparators: (relativePath: string) => string;
+/**
+ * Normalizes the path separators for the current runtime environment.
+ * On POSIX systems, this function returns the path unchanged.
+ * On Windows systems, it converts all `\` separators to `/`.
+ *
+ * @public
+ * @param path The path to normalize.
+ */
+export declare const normalizePath: (relativePath: string) => string;
+/**
+ * Converts a POSIX-style path to a Windows-style path.
+ * On Windows, replace all `/` in the path back with `\\`. Do this only if you
+ * wish to output the path in the console or error message.
+ * On POSIX system (macOS, Linux, ...), this does not change the path (because
+ * inside the compiler we use `/` everywhere).
+ *
+ * @public
+ * @param relativePath
+ */
+export declare const toSystemPathSeparators: (relativePath: string) => string;
+/**
+ * Like `process.cwd()`, but always returns a POSIX-style path
+ * (with `/` as separator).
+ *
+ * @public
+ */
+export declare const getCwd: () => string;
+/**
+ * A wrapper for Node.js's `path` module that always uses POSIX-style paths
+ * (with `/` as separator).
+ *
+ * @public
+ */
+export declare const path: typeof posix & {
+    sep: "/";
+};
+export declare const exportsForTests: {
+    toWin32PathSeparators: (relativePath: string) => string;
+};

package/dist/path.js

@@ -0,0 +1,48 @@
+import { sep, posix, win32 } from "path";
+const isPosix = sep === posix.sep;
+const toPosixPathSeparators = (relativePath) => (
+  //#endregion toPosixPathSeparators
+  relativePath.includes(win32.sep) ? relativePath.replaceAll(win32.sep, posix.sep) : relativePath
+);
+const normalizePath = isPosix ? (path2) => path2 : toPosixPathSeparators;
+const toWin32PathSeparators = (relativePath) => relativePath.includes(posix.sep) ? relativePath.replaceAll(posix.sep, win32.sep) : relativePath;
+const toSystemPathSeparators = isPosix ? (relativePath) => relativePath : toWin32PathSeparators;
+const getCwd = isPosix ? process.cwd : () => toPosixPathSeparators(process.cwd());
+const path = isPosix ? posix : {
+  ...win32,
+  sep: posix.sep,
+  join(...paths) {
+    const result = win32.join(...paths);
+    return toPosixPathSeparators(result);
+  },
+  normalize(path2) {
+    const result = win32.normalize(path2);
+    return toPosixPathSeparators(result);
+  },
+  relative(from, to) {
+    const result = win32.relative(from, to);
+    return toPosixPathSeparators(result);
+  },
+  dirname(path2) {
+    const result = win32.dirname(path2);
+    return toPosixPathSeparators(result);
+  },
+  resolve(...paths) {
+    const result = win32.resolve(...paths);
+    return toPosixPathSeparators(result);
+  },
+  toNamespacedPath(path2) {
+    const result = win32.toNamespacedPath(path2);
+    return toPosixPathSeparators(result);
+  }
+};
+const exportsForTests = { toWin32PathSeparators };
+export {
+  exportsForTests,
+  getCwd,
+  isPosix,
+  normalizePath,
+  path,
+  toPosixPathSeparators,
+  toSystemPathSeparators
+};

package/dist/shell.d.ts

@@ -0,0 +1,115 @@
+import { type ExecOptionsWithStringEncoding, type ExecSyncOptionsWithStringEncoding, type SpawnSyncOptionsWithStringEncoding, type SpawnOptions } from "node:child_process";
+/** @public */
+type SyncProcessOptions = Omit<SpawnSyncOptionsWithStringEncoding, "stdio">;
+/** @public */
+type CollectOutputSyncOptions = SyncProcessOptions & {
+    /** @public */
+    stderr?: "ignore" | "inherit";
+};
+/** @public */
+type AsyncProcessOptions = SpawnOptions & {
+    /** @public */
+    input?: NonNullable<SpawnSyncOptionsWithStringEncoding["input"]>;
+};
+/**
+ * Synchronously execute a shell command and return the output.
+ *
+ * Prefer {@link shell!runCommandSync} for command-only execution, or {@link shell!collectOutputSync}
+ * when you need to capture stdout. {@link shell!sh} goes through a shell, which
+ * requires careful escaping and can mis-handle dynamic input with spaces or
+ * shell metacharacters.
+ *
+ * Use {@link shell!sh} only when shell features are intentionally required, such as
+ * pipes, redirects, `&&`, or command substitution.
+ *
+ * Example (shell features required):
+ * `sh("pnpm list | grep @arcgis/core")`
+ *
+ * @public
+ * @param command
+ * @param options
+ */
+export declare function sh(command: string, options?: Partial<ExecSyncOptionsWithStringEncoding>): string;
+/**
+ * Asynchronously execute a shell command and return the output.
+ *
+ * Prefer {@link shell!runCommand} for command-only execution, or {@link shell!collectOutput}
+ * when you need to capture stdout. {@link shell!asyncSh} executes through a shell,
+ * so callers must handle shell escaping and quoting correctly.
+ *
+ * Use {@link shell!asyncSh} only when shell syntax is intentionally needed.
+ *
+ * Example (shell features required):
+ * `await asyncSh("pnpm list | grep @arcgis/core")`
+ *
+ * @param command
+ * @param options
+ */
+export declare function asyncSh(command: string, options?: Partial<ExecOptionsWithStringEncoding>): Promise<string>;
+/**
+ * Synchronously execute a command without shell interpolation and return the output.
+ *
+ * This is usually safer than {@link shell!sh} because arguments are passed as
+ * discrete tokens, which avoids most shell escaping issues and command
+ * injection pitfalls.
+ *
+ * Example:
+ * `sp("git", ["show", `${baseRef}:pnpm-workspace.yaml`])`
+ *
+ * Avoid {@link shell!sp} only when you explicitly need shell features.
+ * @public
+ * @deprecated Use {@link shell!collectOutputSync} or {@link shell!runCommandSync} instead.
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function sp(command: string, args: string[], options?: Partial<SpawnSyncOptionsWithStringEncoding>): string;
+/**
+ * Synchronously execute a command and stream output to the current process.
+ * Note 1:
+ * `pnpm` command will be automatically invoked with `shell: process.platform === "win32"`
+ * if the `shell` option is not explicitly provided.
+ * Note 2:
+ * If the `input` option is provided, it will be piped to the child process's stdin.
+ *
+ * @public
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function runCommandSync(command: string, args: string[], options?: Partial<SyncProcessOptions>): void;
+/**
+ * Asynchronously execute a command and stream output to the current process.
+ * Note 1:
+ * `pnpm` command will be automatically invoked with `shell: process.platform === "win32"`
+ * if the `shell` option is not explicitly provided.
+ * Note 2:
+ * If the `input` option is provided, it will be piped to the child process's stdin.
+ *
+ * @public
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function runCommand(command: string, args: string[], options?: Partial<AsyncProcessOptions>): Promise<void>;
+/**
+ * Synchronously execute a command and collect stdout while streaming stderr.
+ * Note that `pnpm` command will be automatically invoked with `shell: process.platform === "win32"`.
+ *
+ * @public
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function collectOutputSync(command: string, args: string[], options?: Partial<CollectOutputSyncOptions>): string;
+/**
+ * Asynchronously execute a command and collect stdout while streaming stderr.
+ * Note that `pnpm` command will be automatically invoked with `shell: process.platform === "win32"`.
+ *
+ * @public
+ * @param command
+ * @param args
+ * @param options
+ */
+export declare function collectOutput(command: string, args: string[], options?: Partial<AsyncProcessOptions>): Promise<string>;
+export {};