> For the complete documentation index, see [llms.txt](https://powerjs.gitbook.io/powerjs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://powerjs.gitbook.io/powerjs/home.md).

# Home

![PowerJS cover](https://raw.githubusercontent.com/obaydmerz/powerjs/master/docs/cover.png)

## PowerJS - Empower Your JavaScript with PowerShell Magic

PowerJS is a powerful JavaScript library that enables you to seamlessly integrate and harness the magic of PowerShell directly from your scripts. Whether you need to automate administrative tasks, manage Windows processes, or interact with DLLs, PowerJS provides a user-friendly interface to supercharge your JavaScript applications.

#### Key Features

* **100% Pure javascript (no native files included):** Enjoy more flexibility with a lower cost and a shorter setup process.
* **Dependency-less:** PowerJS eliminates the need for additional dependencies, ensuring a lightweight and hassle-free integration with your projects.
* **Seamless PowerShell Integration:** PowerJS enables you to execute PowerShell commands and scripts directly from your JavaScript or TypeScript code, making it easy to leverage the power of PowerShell within your application.
* **Extension Support:** Extend PowerJS functionality with ease by adding custom extensions. These extensions can include additional PowerShell modules, functions, and capabilities to tailor PowerJS to your specific needs. ( You can make your own extensions and publish them )
* **DLL Integration:** Import and interact with DLLs (Dynamic Link Libraries) in your PowerShell scripts. PowerJS simplifies the process of importing DLLs and provides a convenient interface for direct interaction.
* **Flexible Configuration:** Configure PowerJS according to your requirements with options like specifying additional shell names, enabling elevated permissions (runas), and automatic startup of extensions.
* **Robust Error Handling:** PowerJS includes robust error handling features, allowing you to capture and handle errors gracefully, ensuring your application remains stable even when executing complex PowerShell commands.
* **Asynchronous Execution:** Execute PowerShell commands asynchronously, preventing your application from becoming unresponsive while waiting for script execution to complete.
* **Detailed Results:** Access detailed results of PowerShell script executions, including standard output, standard error, and execution success status. PowerJS provides a convenient result object for easy data retrieval.
* **Comprehensive Documentation:** PowerJS includes comprehensive TypeScript declaration files (.d.ts) and inline code comments, making it easy to understand and use the module in your projects.
* **Cross-Platform Compatibility:** PowerJS is designed to work across different platforms, ensuring consistent PowerShell integration regardless of the operating system.
* ~~**Elevated Permissions:** Run PowerShell commands with elevated permissions when necessary, providing the ability to execute administrative tasks and interact with protected system resources.~~ **( Coming Soon... )**

### Installation

Currently there are a way to install it directly from github. ( For recent features & recommended )

```bash
npm install obaydmerz/powerjs
```

Or from npm: ( For stable relases )

```bash
npm install @obayd/powerjs
```

### Examples

```javascript
// Print PowerShell Version
import { PowerJS } from "@obayd/powerjs";

const instance = new PowerJS(/* options */);

instance.exec("$PSVersionTable").then((result) => {
  // You may notice some slowdown, that's because of the instance init process.
  // After the instance is started, you can enjoy a blazing fast environnement!
  console.log("Currently on Powershell v" + result.PSVersion.Major + "!");
});
```

```javascript
// Read the local user list
import { PowerJS } from "@obayd/powerjs";

const instance = new PowerJS();

instance.exec(",(Get-LocalUser)").then(function (result) {
  // Use the , to make arrays returnable, otherwise, it will return only the first item
  // Read https://stackoverflow.com/questions/29973212/pipe-complete-array-objects-instead-of-array-items-one-at-a-time
  
  for (const user of result) {
    console.log(user.Name);
  }
  process.exit();
});
```

```javascript
// Import a DLL
import { PowerJS } from "@obayd/powerjs";

const instance = new PowerJS({
  dlls: {
    "user32.dll": {
      LockWorkStation: [], // Imports LockWorkStation as a function
      MessageBox: ["int", "IntPtr", "String", "String", "int"], // Also a function, Please note that the first item is the function type.
    },
  },
});

instance.dll.user32
  .MessageBox(0, "Lock your computer?", "Warning", 3)
  .then(async ({ result }) => {
    if (result == 6) {
      await instance.dll.user32.LockWorkStation();
    }
  });

// You should take a deep lock to see how this magic happens.
// This is a super easy out-of-the-box alternative to node-ffi.
```

```javascript
// Make an extension
import { PowerJS, Extension } from "@obayd/powerjs";

class MyAwesomeExtension extends Extension {
  name = "myawesomeext";

  async getVersion() {
    const { result } = await this.instance.exec("$PSVersionTable");

    return result.PSVersion.Major;
  }
}

const instance = new PowerJS({
  extensions: [MyAwesomeExtension],
});

const myAwesomeExt = instance.getExtension(MyAwesomeExtension);
// OR: const myAwesomeExt = instance.getExtension("myawesomeext");

myAwesomeExt.getVersion().then((versionMajor) => {
  console.log("Huh ?! Powershell v" + versionMajor);
});
```

***Easy, isn't it?***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://powerjs.gitbook.io/powerjs/home.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.