feat: Add lifecycle hooks for nitric.

[tjholm]

A proposal for lifecycle hooks in the nitric runtime sdks.

Happy to update the naming to whatever we like. Implementing in the node-sdk first as this will represent the reference implementation for the other SDKs.

import { Environment, EnvironmentStage } from "@nitric/sdk";

// Check if a local run
Environment.isLocalRun();

// Execute code during a local run
Environment.whenLocalRun(() => {
   // run code here
});
// Check if a build/collection (during nitric up, wording here could be updated to reflect this better
Environment.isBuild();

// Execute code during a build
Environment.whenBuild(() => {
   // run code here
});

// Check if the app is running in a deployment environment
Environment.isCloud();

// execute code only in a deployed environment
Environment.whenCloud(() => {

});

// Check if current environment is oneof
Environment.is([EnvironmentStage.Build, EnvironmentStage.LocalRun]);

// Execute code if current environment is oneof the provided stages.
Environment.when([EnvironmentStage.Build, EnvironmentStage.LocalRun], () => {

});

[tjholm]

Will rebase on: #238 when merged

[tjholm]

Current usage now:

import { Lifecycle } from "@nitric/sdk"

Lifecycle.whenCollecting(() => {

});

Lifecycle.whenRunning(() => {

});

Lifecycle.isRunning();

Lifecycle.isCollecting();

[AdzeB]

Hi @tjholm @jyecusch 👋

It looks like LifecycleStage isn't being exported, which is causing methods like is and when to be unusable.

Additionally, I was wondering if you could add descriptions to those lifecycle-related methods—I'm trying to understand the purpose behind methods like isCollecting and whenCollecting, but it's not entirely clear from the current code.

One more thing: it would be helpful to have a way to check if something is running locally when using nitric start.

Happy to create a formal issue for this if that’s preferred—just let me know!

Thanks 🙏

[jyecusch]

Hey @AdzeB,

Thanks for the feedback, I've started a quick PR to export the stages enum #239 we can add to this if I've missed something.

For the descriptions, did you want those in the code like doc comments or in the documentation site? We were thinking of putting the details and use cases in the docs site, but happy to update the SDK comments if that's more useful.

To give you the details in the meantime, Nitric runs in essentially 3 modes:

Running Locally

nitric start or nitric run, where the application is running simiarly to the cloud but for local dev/testing.

Collecting (Local or on a CI/CD server)

During nitric up, when the app is running a 'collection' mode, in order to gather information about all the resources and relationships in the code. This is how the Nitric CLI figures out what to deploy (e.g. databases, buckets, queues, etc.) and turns that into IaC.

Running Deployed/In the Cloud

This is when an environment has been deployed; handling real requests, etc.

Since typically running locally or in the cloud behave similarly, we group those into the running category.

These methods were added as a convenient way to execute custom code or change behavior in just one mode. For example, you might want to perform certain logging during collection, but not when running. Or you might want to change the way you connect to your database locally, but not in the cloud.

The is methods return true if the code is running during one of the matching lifecycle stages. So you could do something like:

if (Lifecycle.isCollecting()) {
  // do something only during collection
}

The when methods instead trigger a callback if the stage matches, for example:

Lifecycle.whenCollecting(() => {
  // do something only during collection
})

[AdzeB]

Thanks so much for the quick response and the PR @jyecusch — really appreciate it!

Regarding the descriptions, I was mainly referring to in-code doc comments so that when hovering over the methods in an editor, users can quickly understand what each one does. That said, having a more detailed explanation on the docs site as well would definitely be helpful, especially for new users.

The breakdown you shared makes everything much clearer — I understand the purpose of the lifecycle methods now. Thanks again for taking the time to explain it!