|
| 1 | +# Module types |
| 2 | + |
| 3 | +Most PSModule modules fall into one of a few archetypes. The general rules in |
| 4 | +[PowerShell module standard](Standards.md) and [PowerShell Standards](../PowerShell/Standard/index.md) always apply; this |
| 5 | +page adds the conventions that are specific to a module's type so that modules of the same kind feel |
| 6 | +the same to use. |
| 7 | + |
| 8 | +Two archetypes have enough shared shape to standardize: |
| 9 | + |
| 10 | +- **Integration (API) modules** wrap an external service's REST or GraphQL API. |
| 11 | +- **Data modules** convert or manage a data format or in-memory structure. |
| 12 | + |
| 13 | +A module can be both (for example, an integration module that also exposes conversion helpers). |
| 14 | +Apply each relevant section. |
| 15 | + |
| 16 | +## Integration (API) modules |
| 17 | + |
| 18 | +Integration modules are the PowerShell face of an external service. `GitHub`, and the |
| 19 | +service-client modules such as `Anthropic`, `OpenAI`, `Bluesky`, and `Domeneshop`, are integration |
| 20 | +modules. |
| 21 | + |
| 22 | +### Command naming maps to the resource, not the HTTP method |
| 23 | + |
| 24 | +Name commands after the resource and the intent, using approved verbs. Never name a command after |
| 25 | +the HTTP method or the endpoint path. Map REST methods to verbs: |
| 26 | + |
| 27 | +| REST method | PowerShell verb | Example | |
| 28 | +| ----------- | --------------- | ------- | |
| 29 | +| `GET` | `Get-` | `Get-GitHubRepository` | |
| 30 | +| `POST` (create) | `New-` / `Add-` | `New-GitHubRepository` | |
| 31 | +| `PUT` / `PATCH` (update) | `Set-` / `Update-` | `Set-GitHubRepository` | |
| 32 | +| `DELETE` | `Remove-` | `Remove-GitHubRepository` | |
| 33 | +| Non-CRUD action | Approved verb for the intent | `Invoke-`, `Start-`, `Stop-`, `Enable-`, ... | |
| 34 | + |
| 35 | +Prefix the noun with the service's term of art (`GitHubRepository`, not `Repository`). |
| 36 | + |
| 37 | +### Transport stays private |
| 38 | + |
| 39 | +Public functions accept resolved inputs and typed objects; private helpers own the concrete |
| 40 | +`Invoke-RestMethod` / GraphQL / HTTP calls. This is the Dependency Inversion rule from |
| 41 | +[Standards](Standards.md#solid-applied) applied to the network boundary. |
| 42 | + |
| 43 | +### Use Context for user and module settings |
| 44 | + |
| 45 | +Integration modules persist state with the [`Context`](https://github.com/PSModule/Context) module |
| 46 | +rather than inventing bespoke storage. Two kinds of state are both standard: |
| 47 | + |
| 48 | +- **User settings and secrets**: accounts, tokens, sessions, and per-user configuration. Store these |
| 49 | + in a per-user context. `Context` encrypts secrets at rest (via `Sodium`), so a user can resume work |
| 50 | + without reconfiguring or logging in again when the service supports session refresh. |
| 51 | +- **Module settings**: module-wide defaults, endpoints, and feature flags that are not tied to a |
| 52 | + single user. Store these in a module-scoped context. |
| 53 | + |
| 54 | +Persisting both through `Context` gives every integration module the same, discoverable settings |
| 55 | +model, and keeps secrets out of source, logs, and plain files. |
| 56 | + |
| 57 | +## Data modules |
| 58 | + |
| 59 | +Data modules convert between representations or manage an in-memory structure. `Hashtable` is the |
| 60 | +reference shape; `Base64`, `Json`, `Lua`, `Hcl`, `Sodium`, and `Uri` follow the same pattern. |
| 61 | + |
| 62 | +### The neutral object is the pivot |
| 63 | + |
| 64 | +Every conversion goes through the neutral PowerShell object model |
| 65 | +(`[PSCustomObject]` / `[hashtable]` / `[PSObject]`). `ConvertFrom-<Format>` parses a |
| 66 | +format-specific representation into an object; `ConvertTo-<Format>` renders an object into the |
| 67 | +format. Converting through the object as a common pivot means any format interoperates with any |
| 68 | +other, instead of writing a direct converter for every pair. |
| 69 | + |
| 70 | +Always ship both directions so data can round-trip between the format and the object model. |
| 71 | + |
| 72 | +### Verb vocabulary |
| 73 | + |
| 74 | +| Verb pattern | Purpose | |
| 75 | +| ------------ | ------- | |
| 76 | +| `ConvertFrom-<Format>` | Format-specific text/representation -> `[PSCustomObject]` / `[hashtable]` | |
| 77 | +| `ConvertTo-<Format>` | Object -> format-specific text/representation | |
| 78 | +| `Import-<Noun>` | Read from a file or store into objects | |
| 79 | +| `Export-<Noun>` | Write objects to a file or store | |
| 80 | +| `Format-<Noun>` | Produce a normalized or pretty rendering | |
| 81 | +| `Merge-<Noun>` | Combine two structures | |
| 82 | +| `Compare-<Noun>` | Diff two structures | |
| 83 | +| `Test-<Noun>` | Validate a value or structure | |
| 84 | +| `Remove-<Noun>Entry` | Remove elements by criteria | |
| 85 | + |
| 86 | +The `Hashtable` module demonstrates the full set: `ConvertFrom-Hashtable`, `ConvertTo-Hashtable`, |
| 87 | +`Import-Hashtable`, `Export-Hashtable`, `Format-Hashtable`, `Merge-Hashtable`, and |
| 88 | +`Remove-HashtableEntry`. |
| 89 | + |
| 90 | +## Where this connects |
| 91 | + |
| 92 | +- [PowerShell module standard](Standards.md): layout, private functions, and the mandatory context parameter. |
| 93 | +- [Repository Defaults](Repository-Defaults.md): repository files, README shape, and agent onboarding. |
0 commit comments