powershell-utils 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,4 +1,4 @@
-import type {ExecFileOptions} from 'node:child_process';
+import type {ExecFileOptions, ExecFileSyncOptions} from 'node:child_process';
 
 export type ExecutePowerShellOptions = ExecFileOptions & {
 	/**
@@ -9,6 +9,15 @@ export type ExecutePowerShellOptions = ExecFileOptions & {
 	readonly powerShellPath?: string;
 };
 
+export type ExecutePowerShellSyncOptions = ExecFileSyncOptions & {
+	/**
+	Path to PowerShell executable.
+
+	@default powerShellPath()
+	*/
+	readonly powerShellPath?: string;
+};
+
 export type ExecutePowerShellResult = {
 	readonly stdout: string;
 	readonly stderr: string;
@@ -70,17 +79,9 @@ export function executePowerShell(
 
 export namespace executePowerShell {
 	/**
-	Standard PowerShell arguments that prefix the encoded command.
-
-	Use these when manually building PowerShell execution arguments for `spawn()`, `execFile()`, etc.
+	Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
 
-	@example
-	```
-	import {executePowerShell} from 'powershell-utils';
-
-	const arguments_ = [...executePowerShell.argumentsPrefix, encodedCommand];
-	childProcess.spawn(powerShellPath(), arguments_);
-	```
+	Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
 	*/
 	export const argumentsPrefix: readonly string[];
 
@@ -119,4 +120,42 @@ export namespace executePowerShell {
 	```
 	*/
 	export function escapeArgument(value: unknown): string;
+
+	/**
+	Create the full arguments array for PowerShell execution.
+
+	Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
+
+	@param command - The PowerShell command.
+	@returns Array of arguments ready to pass to a process spawner.
+
+	@example
+	```
+	import {spawn} from 'node:child_process';
+	import {powerShellPath, executePowerShell} from 'powershell-utils';
+
+	const args = executePowerShell.createArguments('Get-Process');
+	spawn(powerShellPath(), args);
+	```
+	*/
+	export function createArguments(command: string): string[];
 }
+
+/**
+Execute a PowerShell command synchronously.
+
+@param command - The PowerShell command to execute.
+@returns The stdout output as a string.
+
+@example
+```
+import {executePowerShellSync} from 'powershell-utils';
+
+const stdout = executePowerShellSync('Get-Process');
+console.log(stdout);
+```
+*/
+export function executePowerShellSync(
+	command: string,
+	options?: ExecutePowerShellSyncOptions
+): string;

package/index.js

@@ -24,20 +24,29 @@ export const canAccessPowerShell = async () => {
 	return canAccessCache;
 };
 
+const argumentsPrefix = [
+	'-NoProfile',
+	'-NonInteractive',
+	'-ExecutionPolicy',
+	'Bypass',
+	'-EncodedCommand',
+];
+
+const encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
+
+const escapeArgument = value => `'${String(value).replaceAll('\'', '\'\'')}'`;
+
+const createArguments = command => [...argumentsPrefix, encodeCommand(command)];
+
 export const executePowerShell = async (command, options = {}) => {
 	const {
 		powerShellPath: psPath,
 		...execFileOptions
 	} = options;
 
-	const encodedCommand = executePowerShell.encodeCommand(command);
-
 	return execFile(
 		psPath ?? powerShellPath(),
-		[
-			...executePowerShell.argumentsPrefix,
-			encodedCommand,
-		],
+		createArguments(command),
 		{
 			encoding: 'utf8',
 			...execFileOptions,
@@ -45,14 +54,23 @@ export const executePowerShell = async (command, options = {}) => {
 	);
 };
 
-executePowerShell.argumentsPrefix = [
-	'-NoProfile',
-	'-NonInteractive',
-	'-ExecutionPolicy',
-	'Bypass',
-	'-EncodedCommand',
-];
+executePowerShell.argumentsPrefix = argumentsPrefix;
+executePowerShell.encodeCommand = encodeCommand;
+executePowerShell.escapeArgument = escapeArgument;
+executePowerShell.createArguments = createArguments;
 
-executePowerShell.encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
+export const executePowerShellSync = (command, options = {}) => {
+	const {
+		powerShellPath: psPath,
+		...execFileOptions
+	} = options;
 
-executePowerShell.escapeArgument = value => `'${String(value).replaceAll('\'', '\'\'')}'`;
+	return childProcess.execFileSync(
+		psPath ?? powerShellPath(),
+		createArguments(command),
+		{
+			encoding: 'utf8',
+			...execFileOptions,
+		},
+	);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "powershell-utils",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Utilities for executing PowerShell commands",
 	"license": "MIT",
 	"repository": "sindresorhus/powershell-utils",

package/readme.md

@@ -13,11 +13,9 @@ npm install powershell-utils
 ```js
 import {executePowerShell, powerShellPath} from 'powershell-utils';
 
-// Execute a PowerShell command
 const {stdout} = await executePowerShell('Get-Process');
 console.log(stdout);
 
-// Get PowerShell path
 console.log(powerShellPath());
 //=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
 ```
@@ -64,7 +62,6 @@ Execute a PowerShell command.
 ```js
 import {executePowerShell} from 'powershell-utils';
 
-// Execute a PowerShell command
 const {stdout} = await executePowerShell('Get-Process');
 console.log(stdout);
 ```
@@ -99,16 +96,9 @@ Character encoding for stdout and stderr.
 
 Type: `string[]`
 
-Standard PowerShell arguments that prefix the encoded command.
+Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
 
-Use these when manually building PowerShell execution arguments for `spawn()`, `execFile()`, etc.
-
-```js
-import {executePowerShell} from 'powershell-utils';
-
-const arguments_ = [...executePowerShell.argumentsPrefix, encodedCommand];
-childProcess.spawn(powerShellPath(), arguments_);
-```
+Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
 
 ### executePowerShell.encodeCommand(command)
 
@@ -151,3 +141,64 @@ const escaped = executePowerShell.escapeArgument("it's a test");
 // Use in command building
 const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
 ```
+
+### executePowerShell.createArguments(command)
+
+Returns: `string[]`
+
+Create the full arguments array for PowerShell execution.
+
+Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
+
+#### command
+
+Type: `string`
+
+The PowerShell command.
+
+```js
+import {spawn} from 'node:child_process';
+import {powerShellPath, executePowerShell} from 'powershell-utils';
+
+const args = executePowerShell.createArguments('Get-Process');
+spawn(powerShellPath(), args);
+```
+
+### executePowerShellSync(command, options?)
+
+Returns: `string`
+
+Execute a PowerShell command synchronously.
+
+```js
+import {executePowerShellSync} from 'powershell-utils';
+
+const stdout = executePowerShellSync('Get-Process');
+console.log(stdout);
+```
+
+#### command
+
+Type: `string`
+
+The PowerShell command to execute.
+
+#### options
+
+Type: `object`
+
+The below option and also all options in Node.js [`child_process.execFileSync()`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options) are supported.
+
+##### powerShellPath
+
+Type: `string`\
+Default: `powerShellPath()`
+
+Path to PowerShell executable.
+
+##### encoding
+
+Type: `string`\
+Default: `'utf8'`
+
+Character encoding for the output.