![](https://s3-us-west-2.amazonaws.com/arc.codes/architect-logo-500b@2x.png)
Architect project resource enumeration utility
![GitHub CI status](https://github.com/architect/inventory/workflows/Node%20CI/badge.svg)
Inventory is responsible for interpreting the configuration and shape of a given Architect project, validating its settings, and representing it in a consistent intermediate format.
Install
npm i @architect/inventory
Usage
inventory(options[, callback]) → [Promise]
Runs an inventory against your project. Must be passed an options object that may containing the following parameters:
cwd
- String - Absolute file path of the project being inventoriedenv
- Boolean - Queries AWS infra to acquire environment variables for testing
, staging
, and production
environmentsregion
- String - Sets default AWS region; overrides default, but is overridden by AWS_REGION
env varrawArc
- String - Raw Architect project manifest string, intended for testing; providing this will ignore your local manifest
Returns results via callback
, or returns a promise
if callback
is falsy, and resolves with results.
Inventory object
Inventory returns an object containing two parameters: inv
(the project inventory object) and get
(a getter helper for querying resources).
inv
The inventory object contains the entirety of a project's data, including Architect defaults, project defaults, inferred resources, userland settings layered from the project and function levels, local preferences, etc. An inventory object should be considered the source of truth about the state of your project, and should not be directly mutated.
Top-level inventory parameters that start with an underscore (e.g. _arc
, _project
) denote project metadata or internal diagnostic data; all other parameters represent userland project resources.
In a project inventory, null
values are used as placeholders for known values or options that were not user-defined. The existence of a non-null
value can be inferred as a user having specifically defined a setting. For example: arc.http === null
can be construed as the user having not defined an @http
pragma. This rule has some exceptions:
- A handful of settings that must be backfilled if not supplied
- Example:
inv.aws.region
, which is required by the aws-sdk
to function, and will be backfilled if not defined
- Pragmas that infer other pragmas
- Example: while
@static
can be defined on its own without any other pragmas, the existence of @http
infers @static
- Thus, the act of adding
@http
will necessarily make inv.static
non-null
- Settings that generate related resources
- Example: DynamoDB streams can be defined in
@tables
with stream true
; Inventory would interpret a table with stream true
as a new inv.streams
resource and thus make inv.streams
non-null
Note: The inv
format is primarily designed and intended for internal use within Architect libraries; as such, Inventory may theoretically introduce breaking changes in its behavior, shape, or naming conventions.
get
You do not need to use the get
helper to use a project's inventory, but get
does make it much easier to check for the existence of resources, or find specific resources.
The get
helper works as such: get.{pragma or property}('parameter or name of resource')
. (Not including a parameter or resource name will fail in most cases.)
Examples:
@app
my-app
@http
get /
@events
event
get.app()
get.http('get /')
get.http('get /foo')
get.http()
get.static('folder')
get.events('event')
get.tables('data')