@architect/inventory
v4.0.5
Published
Architect project resource enumeration utility
Downloads
14,175
Keywords
Readme
@architect/inventory
Architect project resource enumeration utility
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 fortesting
,staging
, andproduction
environmentslayerValidation
- Boolean (defaulttrue
) - Opt into skipping Lambda layer validationrawArc
- String - Raw Architect project manifest string, intended for testing; providing this will ignore your local manifestregion
- String - Sets default AWS region; overrides default, but is overridden byAWS_REGION
env var
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 theaws-sdk
to function, and will be backfilled if not defined
- Example:
- 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 makeinv.static
non-null
- Example: while
- Settings that generate related resources
- Example: DynamoDB streams can be defined in
@tables
withstream true
; Inventory would interpret a table withstream true
as a newinv['tables-streams']
resource and thus makeinv['tables-streams']
non-null
- Example: DynamoDB streams can be defined in
- Lambda
handlerFile
file path property is present even if the file is not- This differs from Lambda
configFile
file path properties, which will benull
if no file is present - This exception is namely because some workflows may need the computed default handler path (example: when running
arc create
)
- This differs from Lambda
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() // Returns my-app; same as accessing `inv.app`
get.http('get /') // Returns `get /` resource data
get.http('get /foo') // Returns undefined
get.http() // Returns undefined
get.static('folder') // Returns 'public' (default inferred by existence of @http); same as accessing `inv.app.static`
get.events('event') // Returns `event` resource data
get.tables('data') // Returns undefined
aws-sdk
caveat
Inventory conditionally requires aws-sdk
if being used with the env
param (e.g. await inventory({ env: true })
). Early versions of Inventory included aws-sdk
in peerDependencies
, which prior to npm 7 would not automatically install aws-sdk
. This is because Architect assumes you already have aws-sdk
installed via Architect, or that it's available at runtime if you're using Inventory in a Lambda.
However, npm 7 (once again) changed the behavior of peerDependencies
, now automatically installing all peerDependencies
(instead of merely printing a reminder). This means any Lambdas that use Inventory would get a >50MB dependency payload if deployed on a machine with npm 7.
As such, Inventory now errors if the env
param is set, and aws-sdk
is not installed. We are sorry to make this a userland issue, but we feel this is preferable to unnecessarily and invisibly causing aws-sdk
to be installed in Lambdas.