Skip to content

Revisions to doc comments related to env. config. #1520

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 8, 2024
Merged

Revisions to doc comments related to env. config. #1520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions src/params/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ type SecretOrExpr = Param<any> | SecretParam;
export const declaredParams: SecretOrExpr[] = [];

/**
* Use a helper to manage the list such that params are uniquely
* Use a helper to manage the list such that parameters are uniquely
* registered once only but order is preserved.
* @internal
*/
Expand All @@ -76,31 +76,31 @@ export function clearParams() {
}

/**
* A builtin param that resolves to the default RTDB database URL associated
* A built-in parameter that resolves to the default RTDB database URL associated
* with the project, without prompting the deployer. Empty string if none exists.
*/
export const databaseURL: Param<string> = new InternalExpression(
"DATABASE_URL",
(env: NodeJS.ProcessEnv) => JSON.parse(env.FIREBASE_CONFIG)?.databaseURL || ""
);
/**
* A builtin param that resolves to the Cloud project ID associated with
* A built-in parameter that resolves to the Cloud project ID associated with
* the project, without prompting the deployer.
*/
export const projectID: Param<string> = new InternalExpression(
"PROJECT_ID",
(env: NodeJS.ProcessEnv) => JSON.parse(env.FIREBASE_CONFIG)?.projectId || ""
);
/**
* A builtin param that resolves to the Cloud project ID, without prompting
* A built-in parameter that resolves to the Cloud project ID, without prompting
* the deployer.
*/
export const gcloudProject: Param<string> = new InternalExpression(
"GCLOUD_PROJECT",
(env: NodeJS.ProcessEnv) => JSON.parse(env.FIREBASE_CONFIG)?.projectId || ""
);
/**
* A builtin param that resolves to the Cloud storage bucket associated
* A builtin parameter that resolves to the Cloud storage bucket associated
* with the function, without prompting the deployer. Empty string if not
* defined.
*/
Expand All @@ -111,12 +111,12 @@ export const storageBucket: Param<string> = new InternalExpression(

/**
* Declares a secret param, that will persist values only in Cloud Secret Manager.
* Secrets are stored interally as bytestrings. Use ParamOptions.`as` to provide type
* Secrets are stored interally as bytestrings. Use `ParamOptions.as` to provide type
* hinting during parameter resolution.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `string` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `string` return type for `.value`.
*/
export function defineSecret(name: string): SecretParam {
const param = new SecretParam(name);
Expand All @@ -125,11 +125,11 @@ export function defineSecret(name: string): SecretParam {
}

/**
* Declare a string param.
* Declare a string parameter.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `string` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `string` return type for `.value`.
*/
export function defineString(name: string, options: ParamOptions<string> = {}): StringParam {
const param = new StringParam(name, options);
Expand All @@ -138,11 +138,11 @@ export function defineString(name: string, options: ParamOptions<string> = {}):
}

/**
* Declare a boolean param.
* Declare a boolean parameter.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `boolean` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `boolean` return type for `.value`.
*/
export function defineBoolean(name: string, options: ParamOptions<boolean> = {}): BooleanParam {
const param = new BooleanParam(name, options);
Expand All @@ -151,11 +151,11 @@ export function defineBoolean(name: string, options: ParamOptions<boolean> = {})
}

/**
* Declare an integer param.
* Declare an integer parameter.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `number` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `number` return type for `.value`.
*/
export function defineInt(name: string, options: ParamOptions<number> = {}): IntParam {
const param = new IntParam(name, options);
Expand All @@ -164,11 +164,11 @@ export function defineInt(name: string, options: ParamOptions<number> = {}): Int
}

/**
* Declare a float param.
* Declare a float parameter.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `number` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `number` return type for `.value`.
*
* @internal
*/
Expand All @@ -179,11 +179,11 @@ export function defineFloat(name: string, options: ParamOptions<number> = {}): F
}

/**
* Declare a list param.
* Declare a list parameter.
*
* @param name The name of the environment variable to use to load the param.
* @param options Configuration options for the param.
* @returns A Param with a `string[]` return type for `.value`.
* @param name The name of the environment variable to use to load the parameter.
* @param options Configuration options for the parameter.
* @returns A parameter with a `string[]` return type for `.value`.
*/
export function defineList(name: string, options: ParamOptions<string[]> = {}): ListParam {
const param = new ListParam(name, options);
Expand Down
60 changes: 32 additions & 28 deletions src/params/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import * as logger from "../logger";
* an Expression<number> as the value of an option that normally accepts numbers.
*/
export abstract class Expression<T extends string | number | boolean | string[]> {
/** Returns the Expression's runtime value, based on the CLI's resolution of params. */
/** Returns the expression's runtime value, based on the CLI's resolution of parameters. */
value(): T {
if (process.env.FUNCTIONS_CONTROL_API === "true") {
logger.warn(
Expand All @@ -47,11 +47,12 @@ export abstract class Expression<T extends string | number | boolean | string[]>
throw new Error("Not implemented");
}

/** Returns the Expression's representation as a braced CEL expression. */
/** Returns the expression's representation as a braced CEL expression. */
toCEL(): string {
return `{{ ${this.toString()} }}`;
}

/** Returns the expression's representation as JSON. */
toJSON(): string {
return this.toString();
}
Expand All @@ -61,8 +62,8 @@ function valueOf<T extends string | number | boolean | string[]>(arg: T | Expres
return arg instanceof Expression ? arg.runtimeValue() : arg;
}
/**
* Returns how an entity (either an Expression or a literal value) should be represented in CEL.
* - Expressions delegate to the .toString() method, which is used by the WireManifest
* Returns how an entity (either an `Expression` or a literal value) should be represented in CEL.
* - Expressions delegate to the `.toString()` method, which is used by the WireManifest
* - Strings have to be quoted explicitly
* - Arrays are represented as []-delimited, parsable JSON
* - Numbers and booleans are not quoted explicitly
Expand Down Expand Up @@ -159,7 +160,7 @@ export class CompareExpression<
return `${this.lhs} ${this.cmp} ${rhsStr}`;
}

/** Returns a TernaryExpression which can resolve to one of two values, based on the resolution of this comparison. */
/** Returns a `TernaryExpression` which can resolve to one of two values, based on the resolution of this comparison. */
thenElse<retT extends string | number | boolean | string[]>(
ifTrue: retT | Expression<retT>,
ifFalse: retT | Expression<retT>
Expand Down Expand Up @@ -220,8 +221,8 @@ type ParamInput<T> =
| (T extends string ? ResourceInput : never);

/**
* Specifies that a Param's value should be determined by prompting the user
* to type it in interactively at deploy-time. Input that does not match the
* Specifies that a parameter's value should be determined by prompting the user
* to type it in interactively at deploy time. Input that does not match the
* provided validationRegex, if present, will be retried.
*/
// eslint-disable-next-line @typescript-eslint/no-unused-vars
Expand All @@ -243,7 +244,7 @@ export interface TextInput<T = unknown> {
}

/**
* Specifies that a Param's value should be determined by having the user
* Specifies that a parameter's value should be determined by having the user
* select from a list containing all the project's resources of a certain
* type. Currently, only type:"storage.googleapis.com/Bucket" is supported.
*/
Expand All @@ -253,15 +254,18 @@ export interface ResourceInput {
};
}

/**
* Autogenerate a list of buckets in a project that a user can select from.
*/
export const BUCKET_PICKER: ResourceInput = {
resource: {
type: "storage.googleapis.com/Bucket",
},
};

/**
* Specifies that a Param's value should be determined by having the user select
* from a list of pre-canned options interactively at deploy-time.
* Specifies that a parameter's value should be determined by having the user select
* from a list of pre-canned options interactively at deploy time.
*/
export interface SelectInput<T = unknown> {
select: {
Expand All @@ -270,9 +274,9 @@ export interface SelectInput<T = unknown> {
}

/**
* Specifies that a Param's value should be determined by having the user select
* a subset from a list of pre-canned options interactively at deploy-time.
* Will result in errors if used on Params of type other than string[].
* Specifies that a parameter's value should be determined by having the user select
* a subset from a list of pre-canned options interactively at deploy time.
* Will result in errors if used on parameters of type other than `string[]`.
*/
export interface MultiSelectInput {
multiSelect: {
Expand All @@ -281,27 +285,27 @@ export interface MultiSelectInput {
}

/**
* One of the options provided to a SelectInput, containing a value and
* One of the options provided to a `SelectInput`, containing a value and
* optionally a human-readable label to display in the selection interface.
*/
export interface SelectOptions<T = unknown> {
label?: string;
value: T;
}

/** The wire representation of a Param when it's sent to the CLI. A superset of ParamOptions. */
/** The wire representation of a parameter when it's sent to the CLI. A superset of `ParamOptions`. */
export type ParamSpec<T extends string | number | boolean | string[]> = {
/** The name of the parameter which will be stored in .env files. Use UPPERCASE. */
name: string;
/** An optional default value to be used while prompting for input. Can be a literal or another parametrized expression. */
default?: T | Expression<T>;
/** An optional human-readable string to be used as a replacement for the Param's name when prompting. */
/** An optional human-readable string to be used as a replacement for the parameter's name when prompting. */
label?: string;
/** An optional long-form description of the Param to be displayed while prompting. */
/** An optional long-form description of the parameter to be displayed while prompting. */
description?: string;
/** @internal */
type: ParamValueType;
/** The way in which the Firebase CLI will prompt for the value of this Param. Defaults to a TextInput. */
/** The way in which the Firebase CLI will prompt for the value of this parameter. Defaults to a TextInput. */
input?: ParamInput<T>;
};

Expand All @@ -322,7 +326,7 @@ export type WireParamSpec<T extends string | number | boolean | string[]> = {
input?: ParamInput<T>;
};

/** Configuration options which can be used to customize the prompting behavior of a Param. */
/** Configuration options which can be used to customize the prompting behavior of a parameter. */
export type ParamOptions<T extends string | number | boolean | string[]> = Omit<
ParamSpec<T>,
"name" | "type"
Expand All @@ -345,43 +349,43 @@ export abstract class Param<T extends string | number | boolean | string[]> exte
throw new Error("Not implemented");
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
cmp(cmp: "==" | "!=" | ">" | ">=" | "<" | "<=", rhs: T | Expression<T>) {
return new CompareExpression<T>(cmp, this, rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
equals(rhs: T | Expression<T>) {
return this.cmp("==", rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
notEquals(rhs: T | Expression<T>) {
return this.cmp("!=", rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
greaterThan(rhs: T | Expression<T>) {
return this.cmp(">", rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
greaterThanOrEqualTo(rhs: T | Expression<T>) {
return this.cmp(">=", rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
lessThan(rhs: T | Expression<T>) {
return this.cmp("<", rhs);
}

/** Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression. */
/** Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression. */
lessThanOrEqualTo(rhs: T | Expression<T>) {
return this.cmp("<=", rhs);
}

/**
* Returns a parametrized expression of Boolean type, based on comparing the value of this param to a literal or a different expression.
* Returns a parametrized expression of Boolean type, based on comparing the value of this parameter to a literal or a different expression.
* @deprecated A typo. Use lessThanOrEqualTo instead.
*/
lessThanorEqualTo(rhs: T | Expression<T>) {
Expand Down Expand Up @@ -474,7 +478,7 @@ export class StringParam extends Param<string> {
/**
* A CEL expression which represents an internal Firebase variable. This class
* cannot be instantiated by developers, but we provide several canned instances
* of it to make available params that will never have to be defined at
* of it to make available parameters that will never have to be defined at
* deployment time, and can always be read from process.env.
* @internal
*/
Expand Down