Skip to content

Commit

Permalink
Revisions to doc comments related to env. config. (#1520)
Browse files Browse the repository at this point in the history
  • Loading branch information
@egilmorez
egilmorez authored Feb 8, 2024
1 parent 26cd955 commit 5a94583
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 57 deletions.
58 changes: 29 additions & 29 deletions src/params/index.ts
View file
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
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

0 comments on commit 5a94583

Please sign in to comment.