projen 0.52.22 → 0.52.26

package/lib/javascript/node-package.d.ts

@@ -1,29 +1,21 @@
 import { Component } from "../component";
 import { Project } from "../project";
-/**
- * @experimental
- */
 export interface NodePackageOptions {
     /**
-     * (experimental) The "name" in package.json.
-     *
+     * The "name" in package.json
      * @default - defaults to project name
-     * @experimental
-     * @featured true
+     * @featured
      */
     readonly packageName?: string;
     /**
-     * (experimental) The description is just a string that helps people understand the purpose of the package.
-     *
+     * The description is just a string that helps people understand the purpose of the package.
      * It can be used when searching for packages in a package manager as well.
      * See https://classic.yarnpkg.com/en/docs/package-json/#toc-description
-     *
-     * @experimental
-     * @featured true
+     * @featured
      */
     readonly description?: string;
     /**
-     * (experimental) Runtime dependencies of this module.
+     * Runtime dependencies of this module.
      *
      * The recommendation is to only specify the module name here (e.g.
      * `express`). This will behave similar to `yarn add` or `npm install` in the
@@ -32,18 +24,13 @@ export interface NodePackageOptions {
      * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
      * this will be what you `package.json` will eventually include.
      *
+     * @example [ 'express', 'lodash', 'foo@^2' ]
      * @default []
-     * @experimental
-     * @featured true
-     * @example
-     *
-     * [ 'express', 'lodash', 'foo@^2' ]
+     * @featured
      */
     readonly deps?: string[];
     /**
-     * (experimental) Build dependencies for this module.
-     *
-     * These dependencies will only be
+     * Build dependencies for this module. These dependencies will only be
      * available in your build environment but will not be fetched when this
      * module is consumed.
      *
@@ -54,18 +41,13 @@ export interface NodePackageOptions {
      * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
      * this will be what you `package.json` will eventually include.
      *
+     * @example [ 'typescript', '@types/express' ]
      * @default []
-     * @experimental
-     * @featured true
-     * @example
-     *
-     * [ 'typescript', '@types/express' ]
+     * @featured
      */
     readonly devDeps?: string[];
     /**
-     * (experimental) Peer dependencies for this module.
-     *
-     * Dependencies listed here are required to
+     * Peer dependencies for this module. Dependencies listed here are required to
      * be installed (and satisfied) by the _consumer_ of this library. Using peer
      * dependencies allows you to ensure that only a single module of a certain
      * library exists in the `node_modules` tree of your consumers.
@@ -80,13 +62,10 @@ export interface NodePackageOptions {
      * test your module against the lowest peer version required.
      *
      * @default []
-     * @experimental
      */
     readonly peerDeps?: string[];
     /**
-     * (experimental) List of dependencies to bundle into this module.
-     *
-     * These modules will be
+     * List of dependencies to bundle into this module. These modules will be
      * added both to the `dependencies` section and `bundledDependencies` section of
      * your `package.json`.
      *
@@ -96,269 +75,206 @@ export interface NodePackageOptions {
      * file with the latest version (`^`). You can specify semver requirements in
      * the same syntax passed to `npm i` or `yarn add` (e.g. `express@^2`) and
      * this will be what you `package.json` will eventually include.
-     *
-     * @experimental
      */
     readonly bundledDeps?: string[];
     /**
-     * (experimental) Options for `peerDeps`.
-     *
-     * @experimental
+     * Options for `peerDeps`.
      */
     readonly peerDependencyOptions?: PeerDependencyOptions;
     /**
-     * (experimental) Allow the project to include `peerDependencies` and `bundledDependencies`.
-     *
+     * Allow the project to include `peerDependencies` and `bundledDependencies`.
      * This is normally only allowed for libraries. For apps, there's no meaning
      * for specifying these.
      *
      * @default true
-     * @experimental
      */
     readonly allowLibraryDependencies?: boolean;
     /**
-     * (experimental) Keywords to include in `package.json`.
-     *
-     * @experimental
+     * Keywords to include in `package.json`.
      */
     readonly keywords?: string[];
     /**
-     * (experimental) Module entrypoint (`main` in `package.json`).
+     * Module entrypoint (`main` in `package.json`)
      *
      * Set to an empty string to not include `main` in your package.json
      *
      * @default "lib/index.js"
-     * @experimental
      */
     readonly entrypoint?: string;
     /**
-     * (experimental) Binary programs vended with your module.
+     * Binary programs vended with your module.
      *
      * You can use this option to add/customize how binaries are represented in
      * your `package.json`, but unless `autoDetectBin` is `false`, every
      * executable file under `bin` will automatically be added to this section.
-     *
-     * @experimental
      */
     readonly bin?: Record<string, string>;
     /**
-     * (experimental) Automatically add all executables under the `bin` directory to your `package.json` file under the `bin` section.
+     * Automatically add all executables under the `bin` directory to your
+     * `package.json` file under the `bin` section.
      *
      * @default true
-     * @experimental
      */
     readonly autoDetectBin?: boolean;
     /**
-     * (experimental) npm scripts to include.
-     *
-     * If a script has the same name as a standard script,
+     * npm scripts to include. If a script has the same name as a standard script,
      * the standard script will be overwritten.
      *
      * @default {}
-     * @experimental
      */
     readonly scripts?: {
         [name: string]: string;
     };
     /**
-     * (experimental) The Node Package Manager used to execute scripts.
+     * The Node Package Manager used to execute scripts
      *
      * @default NodePackageManager.YARN
-     * @experimental
      */
     readonly packageManager?: NodePackageManager;
     /**
-     * (experimental) The repository is the location where the actual code for your package lives.
-     *
+     * The repository is the location where the actual code for your package lives.
      * See https://classic.yarnpkg.com/en/docs/package-json/#toc-repository
-     *
-     * @experimental
      */
     readonly repository?: string;
     /**
-     * (experimental) If the package.json for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives.
-     *
-     * @experimental
+     * If the package.json for your package is not in the root directory (for example if it is part of a monorepo),
+     * you can specify the directory in which it lives.
      */
     readonly repositoryDirectory?: string;
     /**
-     * (experimental) Author's name.
-     *
-     * @experimental
+     * Author's name
      */
     readonly authorName?: string;
     /**
-     * (experimental) Author's e-mail.
-     *
-     * @experimental
+     * Author's e-mail
      */
     readonly authorEmail?: string;
     /**
-     * (experimental) Author's URL / Website.
-     *
-     * @experimental
+     * Author's URL / Website
      */
     readonly authorUrl?: string;
     /**
-     * (experimental) Author's Organization.
-     *
-     * @experimental
+     * Author's Organization
      */
     readonly authorOrganization?: boolean;
     /**
-     * (experimental) Package's Homepage / Website.
-     *
-     * @experimental
+     * Package's Homepage / Website
      */
     readonly homepage?: string;
     /**
-     * (experimental) Package's Stability.
-     *
-     * @experimental
+     * Package's Stability
      */
     readonly stability?: string;
     /**
-     * (experimental) Minimum Node.js version to require via package.json `engines` (inclusive).
+     * Minimum Node.js version to require via package.json `engines` (inclusive).
      *
      * @default - no "engines" specified
-     * @experimental
      */
     readonly minNodeVersion?: string;
     /**
-     * (experimental) Minimum node.js version to require via `engines` (inclusive).
+     * Minimum node.js version to require via `engines` (inclusive).
      *
      * @default - no max
-     * @experimental
      */
     readonly maxNodeVersion?: string;
     /**
-     * (experimental) License's SPDX identifier.
-     *
+     * License's SPDX identifier.
      * See https://github.com/projen/projen/tree/main/license-text for a list of supported licenses.
      * Use the `licensed` option if you want to no license to be specified.
      *
      * @default "Apache-2.0"
-     * @experimental
      */
     readonly license?: string;
     /**
-     * (experimental) Indicates if a license should be added.
+     * Indicates if a license should be added.
      *
      * @default true
-     * @experimental
      */
     readonly licensed?: boolean;
     /**
-     * (experimental) The base URL of the npm package registry.
+     * The base URL of the npm package registry.
      *
      * Must be a URL (e.g. start with "https://" or "http://")
      *
      * @default "https://registry.npmjs.org"
-     * @experimental
      */
     readonly npmRegistryUrl?: string;
     /**
-     * (deprecated) The host name of the npm registry to publish to.
-     *
-     * Cannot be set together with `npmRegistryUrl`.
+     * The host name of the npm registry to publish to. Cannot be set together with `npmRegistryUrl`.
      *
      * @deprecated use `npmRegistryUrl` instead
      */
     readonly npmRegistry?: string;
     /**
-     * (experimental) The url to your project's issue tracker.
-     *
-     * @experimental
+     * The url to your project's issue tracker.
      */
     readonly bugsUrl?: string;
     /**
-     * (experimental) The email address to which issues should be reported.
-     *
-     * @experimental
+     * The email address to which issues should be reported.
      */
     readonly bugsEmail?: string;
     /**
-     * (experimental) Access level of the npm package.
+     * Access level of the npm package.
      *
      * @default - for scoped packages (e.g. `foo@bar`), the default is
      * `NpmAccess.RESTRICTED`, for non-scoped packages, the default is
      * `NpmAccess.PUBLIC`.
-     * @experimental
      */
     readonly npmAccess?: NpmAccess;
     /**
-     * (experimental) GitHub secret which contains the NPM token to use when publishing packages.
+     * GitHub secret which contains the NPM token to use when publishing packages.
      *
      * @default "NPM_TOKEN"
-     * @experimental
      */
     readonly npmTokenSecret?: string;
     /**
-     * (experimental) Options for publishing npm package to AWS CodeArtifact.
+     * Options for publishing npm package to AWS CodeArtifact.
      *
      * @default - undefined
-     * @experimental
      */
     readonly codeArtifactOptions?: CodeArtifactOptions;
 }
-/**
- * @experimental
- */
 export interface CodeArtifactOptions {
     /**
-     * (experimental) GitHub secret which contains the AWS access key ID to use when publishing packages to AWS CodeArtifact.
-     *
+     * GitHub secret which contains the AWS access key ID to use when publishing packages to AWS CodeArtifact.
      * This property must be specified only when publishing to AWS CodeArtifact (`npmRegistryUrl` contains AWS CodeArtifact URL).
      *
      * @default "AWS_ACCESS_KEY_ID"
-     * @experimental
      */
     readonly accessKeyIdSecret?: string;
     /**
-     * (experimental) GitHub secret which contains the AWS secret access key to use when publishing packages to AWS CodeArtifact.
-     *
+     * GitHub secret which contains the AWS secret access key to use when publishing packages to AWS CodeArtifact.
      * This property must be specified only when publishing to AWS CodeArtifact (`npmRegistryUrl` contains AWS CodeArtifact URL).
      *
      * @default "AWS_SECRET_ACCESS_KEY"
-     * @experimental
      */
     readonly secretAccessKeySecret?: string;
     /**
-     * (experimental) ARN of AWS role to be assumed prior to get authorization token from AWS CodeArtifact This property must be specified only when publishing to AWS CodeArtifact (`registry` contains AWS CodeArtifact URL).
+     * ARN of AWS role to be assumed prior to get authorization token from AWS CodeArtifact
+     * This property must be specified only when publishing to AWS CodeArtifact (`registry` contains AWS CodeArtifact URL).
      *
      * @default undefined
-     * @experimental
      */
     readonly roleToAssume?: string;
 }
 /**
- * (experimental) Represents the npm `package.json` file.
- *
- * @experimental
+ * Represents the npm `package.json` file.
  */
 export declare class NodePackage extends Component {
     /**
-     * (experimental) The name of the npm package.
-     *
-     * @experimental
+     * The name of the npm package.
      */
     readonly packageName: string;
     /**
-     * (experimental) The module's entrypoint (e.g. `lib/index.js`).
-     *
-     * @experimental
+     * The module's entrypoint (e.g. `lib/index.js`).
      */
     readonly entrypoint: string;
     /**
-     * (experimental) Allow project to take library dependencies.
-     *
-     * @experimental
+     * Allow project to take library dependencies.
      */
     readonly allowLibraryDependencies: boolean;
     /**
-     * (experimental) The package manager to use.
-     *
-     * @experimental
+     * The package manager to use.
      */
     readonly packageManager: NodePackageManager;
     /**
@@ -366,62 +282,43 @@ export declare class NodePackage extends Component {
      */
     readonly manifest: any;
     /**
-     * (experimental) Minimum node.js version required by this package.
-     *
+     * Minimum node.js version required by this package.
      * @default - no minimum
-     * @experimental
      */
     readonly minNodeVersion?: string;
     /**
-     * (experimental) Maximum node version required by this pacakge.
-     *
+     * Maximum node version required by this pacakge.
      * @default - no maximum.
-     * @experimental
      */
     readonly maxNodeVersion?: string;
     /**
-     * (experimental) The SPDX license of this module.
-     *
-     * `undefined` if this package is not licensed.
-     *
-     * @experimental
+     * The SPDX license of this module. `undefined` if this package is not licensed.
      */
     readonly license?: string;
     /**
-     * (experimental) npm registry (e.g. `https://registry.npmjs.org`). Use `npmRegistryHost` to get just the host name.
-     *
-     * @experimental
+     * npm registry (e.g. `https://registry.npmjs.org`). Use `npmRegistryHost` to get just the host name.
      */
     readonly npmRegistryUrl: string;
     /**
-     * (experimental) The npm registry host (e.g. `registry.npmjs.org`).
-     *
-     * @experimental
+     * The npm registry host (e.g. `registry.npmjs.org`).
      */
     readonly npmRegistry: string;
     /**
-     * (experimental) GitHub secret which contains the NPM token to use when publishing packages.
-     *
-     * @experimental
+     * GitHub secret which contains the NPM token to use when publishing packages.
      */
     readonly npmTokenSecret?: string;
     /**
-     * (experimental) Options for publishing npm package to AWS CodeArtifact.
+     * Options for publishing npm package to AWS CodeArtifact.
      *
      * @default - undefined
-     * @experimental
      */
     readonly codeArtifactOptions?: CodeArtifactOptions;
     /**
-     * (experimental) npm package access level.
-     *
-     * @experimental
+     * npm package access level.
      */
     readonly npmAccess: NpmAccess;
     /**
-     * (experimental) The name of the lock file.
-     *
-     * @experimental
+     * The name of the lock file.
      */
     readonly lockFile: string;
     private readonly keywords;
@@ -430,138 +327,112 @@ export declare class NodePackage extends Component {
     private readonly peerDependencyOptions;
     private readonly file;
     private _renderedDeps?;
-    /**
-     * @experimental
-     */
     constructor(project: Project, options?: NodePackageOptions);
     /**
-     * (experimental) Defines normal dependencies.
+     * Defines normal dependencies.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines development/test dependencies.
+     * Defines development/test dependencies.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addDevDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines peer dependencies.
+     * Defines peer dependencies.
      *
      * When adding peer dependencies, a devDependency will also be added on the
      * pinned version of the declared peer. This will ensure that you are testing
      * your code against the minimum version required from your consumers.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addPeerDeps(...deps: string[]): void;
     /**
-     * (experimental) Defines bundled dependencies.
+     * Defines bundled dependencies.
      *
      * Bundled dependencies will be added as normal dependencies as well as to the
      * `bundledDependencies` section of your `package.json`.
      *
-     * @param deps Names modules to install.
-     * @experimental
+     * @param deps Names modules to install. By default, the the dependency will
+     * be installed in the next `npx projen` run and the version will be recorded
+     * in your `package.json` file. You can upgrade manually or using `yarn
+     * add/upgrade`. If you wish to specify a version range use this syntax:
+     * `module@^7`.
      */
     addBundledDeps(...deps: string[]): void;
     /**
-     * (experimental) Adds an `engines` requirement to your package.
-     *
-     * @param engine The engine (e.g. `node`).
-     * @param version The semantic version requirement (e.g. `^10`).
-     * @experimental
+     * Adds an `engines` requirement to your package.
+     * @param engine The engine (e.g. `node`)
+     * @param version The semantic version requirement (e.g. `^10`)
      */
     addEngine(engine: string, version: string): void;
     /**
-     * (experimental) Adds keywords to package.json (deduplicated).
-     *
-     * @param keywords The keywords to add.
-     * @experimental
+     * Adds keywords to package.json (deduplicated)
+     * @param keywords The keywords to add
      */
     addKeywords(...keywords: string[]): void;
-    /**
-     * @experimental
-     */
     addBin(bins: Record<string, string>): void;
     /**
-     * (experimental) Override the contents of an npm package.json script.
+     * Override the contents of an npm package.json script.
      *
-     * @param name The script name.
-     * @param command The command to execute.
-     * @experimental
+     * @param name The script name
+     * @param command The command to execute
      */
     setScript(name: string, command: string): void;
     /**
-     * (experimental) Removes the npm script (always successful).
-     *
+     * Removes the npm script (always successful).
      * @param name The name of the script.
-     * @experimental
      */
     removeScript(name: string): void;
     /**
-     * (deprecated) Indicates if a script by the given name is defined.
-     *
-     * @param name The name of the script.
+     * Indicates if a script by the given name is defined.
+     * @param name The name of the script
      * @deprecated Use `project.tasks.tryFind(name)`
      */
     hasScript(name: string): boolean;
     /**
-     * (experimental) Directly set fields in `package.json`.
-     *
-     * @param name field name.
-     * @param value field value.
-     * @experimental
-     * @escape true
+     * Directly set fields in `package.json`.
+     * @escape
+     * @param name field name
+     * @param value field value
      */
     addField(name: string, value: any): void;
     /**
-     * (experimental) Sets the package version.
-     *
+     * Sets the package version.
      * @param version Package version.
-     * @experimental
      */
     addVersion(version: string): void;
     /**
-     * (experimental) Returns the command to execute in order to install all dependencies (always frozen).
-     *
-     * @experimental
+     * Returns the command to execute in order to install all dependencies (always frozen).
      */
     get installCommand(): string;
     /**
-     * (experimental) Renders `yarn install` or `npm install` with lockfile update (not frozen).
-     *
-     * @experimental
+     * Renders `yarn install` or `npm install` with lockfile update (not frozen)
      */
     get installAndUpdateLockfileCommand(): string;
     /**
-     * (experimental) Render a package manager specific command to upgrade all requested dependencies.
-     *
-     * @experimental
+     * Render a package manager specific command to upgrade all requested dependencies.
      */
     renderUpgradePackagesCommand(exclude: string[], include?: string[]): string;
-    /**
-     * (experimental) Called before synthesis.
-     *
-     * @experimental
-     */
     preSynthesize(): void;
-    /**
-     * (experimental) Called after synthesis.
-     *
-     * Order is *not* guaranteed.
-     *
-     * @experimental
-     */
     postSynthesize(): void;
     /**
-     * (experimental) The command which executes "projen".
-     *
-     * @experimental
+     * The command which executes "projen".
      */
     get projenCommand(): string;
     /**
@@ -597,59 +468,40 @@ export declare class NodePackage extends Component {
     private readPackageJson;
     private installDependencies;
 }
-/**
- * @experimental
- */
 export interface PeerDependencyOptions {
     /**
-     * (experimental) Automatically add a pinned dev dependency.
-     *
+     * Automatically add a pinned dev dependency.
      * @default true
-     * @experimental
      */
     readonly pinnedDevDependency?: boolean;
 }
 /**
- * (experimental) The node package manager to use.
- *
- * @experimental
+ * The node package manager to use.
  */
 export declare enum NodePackageManager {
     /**
-     * (experimental) Use `yarn` as the package manager.
-     *
-     * @experimental
+     * Use `yarn` as the package manager.
      */
     YARN = "yarn",
     /**
-     * (experimental) Use `npm` as the package manager.
-     *
-     * @experimental
+     * Use `npm` as the package manager.
      */
     NPM = "npm",
     /**
-     * (experimental) Use `pnpm` as the package manager.
-     *
-     * @experimental
+     * Use `pnpm` as the package manager.
      */
     PNPM = "pnpm"
 }
 /**
- * (experimental) Npm package access level.
- *
- * @experimental
+ * Npm package access level
  */
 export declare enum NpmAccess {
     /**
-     * (experimental) Package is public.
-     *
-     * @experimental
+     * Package is public.
      */
     PUBLIC = "public",
     /**
-     * (experimental) Package can only be accessed with credentials.
-     *
-     * @experimental
+     * Package can only be accessed with credentials.
      */
     RESTRICTED = "restricted"
 }