{"id":22389051,"url":"https://github.com/shadow578/powershell-binding","last_synced_at":"2026-05-03T16:32:43.819Z","repository":{"id":65253672,"uuid":"587761469","full_name":"shadow578/powershell-binding","owner":"shadow578","description":"Simple bindings for PowerShell in Node.js using class decorators.","archived":false,"fork":false,"pushed_at":"2023-01-13T14:38:06.000Z","size":236,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T22:18:24.878Z","etag":null,"topics":["bindings","class-decorator","nodejs","powershell","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@shadow578/powershell-binding","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shadow578.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2023-01-11T14:25:21.000Z","updated_at":"2023-01-13T14:40:37.000Z","dependencies_parsed_at":"2023-01-15T23:01:18.407Z","dependency_job_id":null,"html_url":"https://github.com/shadow578/powershell-binding","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":"shadow578/typescript-project-template","purl":"pkg:github/shadow578/powershell-binding","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadow578%2Fpowershell-binding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadow578%2Fpowershell-binding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadow578%2Fpowershell-binding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadow578%2Fpowershell-binding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shadow578","download_url":"https://codeload.github.com/shadow578/powershell-binding/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadow578%2Fpowershell-binding/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32577122,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","class-decorator","nodejs","powershell","typescript"],"created_at":"2024-12-05T03:08:56.722Z","updated_at":"2026-05-03T16:32:43.800Z","avatar_url":"https://github.com/shadow578.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @shadow578/powershell-binding\nSimple bindings for PowerShell in Node.js using class decorators.\n\n\n## Installation\nInstall `@shadow578/powershell-binding` using npm:\n\n```shell\nnpm install @shadow578/powershell-binding\n```\n\n## Usage\n### Importing the Module\nImport the `@shadow578/powershell-binding` module using the following code:\n\n```typescript\nimport { PowerShellBinding, PowerShellCall } from \"@shadow578/powershell-binding\";\n```\n\n\n### Creating a Binding Class\nTo create a binding class, create a class extending `PowerShellBinding`:\n\n```typescript\nclass MyBinding extends PowerShellBinding {\n  // ...\n}\n```\n\n#### Custom Shims\nBy default, the `PowerShellBinding` class uses the `DefaultShim` to convert input parameters and output objects to and from PowerShell. \nHowever, custom shims may be used by overriding the `shim` property of the `PowerShellBinding` class:\n\n```typescript\nclass MyBinding extends PowerShellBinding {\n  get shim(): Shim {\n      return myShim;\n  }\n}\n```\n\nCustom shims must implement the `Shim` interface.\nFor more details on how to implement a custom shim, see the [DefaultShim implementation](/src/powershell/shim/DefaultShim.ts).\n\n\n\n### Creating a Binding Method\nTo create a binding method, create a method in the binding class with the `@PowerShellCall` decorator:\n\n```typescript\nclass MyBinding extends PowerShellBinding {\n  @PowerShellCall('Write-Output \"Hello, $name!\"', isString)\n  greet(name: string) {\n    return psCall\u003cstring\u003e();\n  }\n}\n```\n\nThe `@PowerShellCall` decorator takes the following parameters:\n| Name        | Description                                                 | Default |\n| ----------- | ----------------------------------------------------------- | ------- |\n| `command`   | The command to execute in PowerShell                        |         |\n| `typeGuard` | A function that checks if the output is of the correct type | `isAny` |\n| `options`   | Additional options for the PowerShell call                  | `{}`    |\n\n\nThe `command` parameter takes a string containing the command to execute in PowerShell. The command may contain parameters, which are passed to the method as arguments. \nThe parameters are automatically converted to PowerShell variables and are available in the command.\n\n\u003c/br\u003e\n\nThe `typeGuard` parameter takes a function with the following signature:\n```typescript\n(input: unknown) =\u003e input is T\n```\n\nSuch functions may be created using the [@shadow578/type-guardian](https://www.npmjs.com/package/@shadow578/type-guardian) package.\n\n\u003c/br\u003e\n\nThe `options` parameter takes the following properties:\n| Name                 | Description                                                                                                                                                                          | Default |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |\n| `expandParameters`   | Whether to expand the parameters to variables. If false, parameters are only available in the `$params` variable                                                                     | `true`  |\n| `serializationDepth` | How deep the output object should be serialized (See [ConvertTo-Json docs](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/convertto-json#-depth)). | `2`     |\n\n#### The `psCall` Function\nThe `psCall` function is used to stub the implementation of the binding method.\nBy itself, it does nothing but throw a Error, but it is replaced by the `@PowerShellCall` decorator with the actual implementation.\n\n\n### Calling a Binding Method\nTo call a binding method, create an instance of the binding class and call the method:\n\n```typescript\nconst binding = new MyBinding();\nconst output = await binding.greet(\"World\");\n// output === \"Hello, World!\"\n```\n\n#### Exception Handling\nIf an exception is thrown in PowerShell, it is re-thrown in JavaScript as a `PowerShellError`.\n\n\u003cbr/\u003e\n\n#### Binding Class Options\nBy default `PowerShellBinding` constructor creates a new `PowerShell` instance using the default options. \nFurther options may be passed to the `PowerShell` constructor using the `options` parameter. \nSee [The `node-powershell` docs](https://www.npmjs.com/package/node-powershell) for possible options.\n\nAdditionally, a pre-existing `PowerShell` instance may be passed to the `PowerShellBinding` constructor using the `instance` parameter. \nIn this case, the parameter `options` is ignored.\n\n\n## Examples\nFor more examples, see [`DocumentationExamples.test.ts`](/src/__tests__/DocumentationExamples.test.ts) and [`PowerShellCall.test.ts`](/src/__tests__/binding/PowerShellCall.test.ts). \n\n\n## Limitations\n- Input parameters to binding methods must be serializable using `JSON.stringify` and deserializable using `ConvertFrom-Json`¹.\n- Outputs of binding methods must be serializable using `ConvertTo-Json` and deserializable using `JSON.parse`¹.\n- Outputs of binding methods may only have a depth of 100².\n- Commands in binding methods cannot be interactive.\n\n\u003e ¹ generally, any value of type `string`, `number`, `boolean`, `object`, or a array of those types, should work.\n\n\u003e ² depends on used shim. For the default shim, the depth is limited to 99.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadow578%2Fpowershell-binding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshadow578%2Fpowershell-binding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadow578%2Fpowershell-binding/lists"}