faastjs
- Version 8.0.75
- Published
- 2.12 MB
- 30 dependencies
- Apache-2.0 license
Install
npm i faastjs
yarn add faastjs
pnpm add faastjs
Overview
Faast.js transforms ordinary JavaScript modules into serverless cloud functions that can run on AWS Lambda.
The main entry point to faast.js is the faast function, which returns an object that implements the FaastModule interface. The most common options are CommonOptions. Using faast.js requires writing two modules, one containing the functions to upload to the cloud, and the other that invokes faast.js and calls the resulting cloud functions.
Index
Variables
Functions
Classes
Interfaces
Enums
Type Aliases
Namespaces
Variables
variable log
const log: { info: debug_2.Debugger; minimal: debug_2.Debugger; warn: debug_2.Debugger; gc: debug_2.Debugger; leaks: debug_2.Debugger; calls: debug_2.Debugger; webpack: debug_2.Debugger; provider: debug_2.Debugger; awssdk: debug_2.Debugger;};
Faast.js loggers.
Remarks
Unless otherwise specified, each log is disabled by default unless the value of the DEBUG environment variable is set to the corresponding value. For example:
$ DEBUG=faast:info,faast:provider <cmd>$ DEBUG=faast:* <cmd>Logs can also be enabled or disabled programmatically:
import { log } from "faastjs"log.info.enabled = true;log.provider.enabled = true;Each log outputs specific information:
info
- General informational logging.minimal
- Outputs only basic information like the function name created in the cloud.warn
- Warnings. Enabled by default.gc
- Garbage collection verbose logging.leaks
- Memory leak detector warnings for the cloud function. Enabled by default.calls
- Verbose logging of each faast.js enabled function invocation.webpack
- Verbose logging from webpack and packaging details.provider
- Verbose logging of each interaction between faast.js runtime and the provider-specific implementation.awssdk
- Verbose logging of AWS SDK. This can be useful for identifying which API calls are failing, retrying, or encountering rate limits.Modifiers
@public
variable providers
const providers: Provider[];
An array of all available provider.
Modifiers
@public
Functions
function faast
faast: <M extends object>( provider: Provider, fmodule: M, options?: CommonOptions) => Promise<FaastModule<M>>;
The main entry point for faast with any provider and only common options.
Parameter provider
One of
"aws"
or"local"
. See Provider.Parameter fmodule
A module imported with
import * as X from "Y";
. Usingrequire
also works but loses type information.Parameter options
See CommonOptions.
Returns
See FaastModule.
Remarks
Example of usage:
import { faast } from "faastjs";import * as mod from "./path/to/module";(async () => {const faastModule = await faast("aws", mod);try {const result = await faastModule.functions.func("arg");} finally {await faastModule.cleanup();}})();Modifiers
@public
function faastAws
faastAws: <M extends object>( fmodule: M, options?: AwsOptions) => Promise<AwsFaastModule<M>>;
The main entry point for faast with AWS provider.
Parameter fmodule
A module imported with
import * as X from "Y";
. Usingrequire
also works but loses type information.Parameter options
Most common options are in CommonOptions. Additional AWS-specific options are in AwsOptions.
Modifiers
@public
function faastLocal
faastLocal: <M extends object>( fmodule: M, options?: LocalOptions) => Promise<LocalFaastModule<M>>;
The main entry point for faast with Local provider.
Parameter fmodule
A module imported with
import * as X from "Y";
. Usingrequire
also works but loses type information.Parameter options
Most common options are in CommonOptions. Additional Local-specific options are in LocalOptions.
Returns
a Promise for LocalFaastModule.
Modifiers
@public
function throttle
throttle: <A extends any[], R>( limits: Limits, fn: (...args: A) => Promise<R>) => (...args: A) => Promise<R>;
A decorator for rate limiting, concurrency limiting, retry, memoization, and on-disk caching. See Limits.
Parameter limits
see Limits.
Parameter fn
The function to throttle. It can take any arguments, but must return a Promise (which includes
async
functions).Returns
Returns a throttled function with the same signature as the argument
fn
.Remarks
When programming against cloud services, databases, and other resources, it is often necessary to control the rate of request issuance to avoid overwhelming the service provider. In many cases the provider has built-in safeguards against abuse, which automatically fail requests if they are coming in too fast. Some systems don't have safeguards and precipitously degrade their service level or fail outright when faced with excessive load.
With faast.js it becomes very easy to (accidentally) generate requests from thousands of cloud functions. The
throttle
function can help manage request flow without resorting to setting up a separate service. This is in keeping with faast.js' zero-ops philosophy.Usage is simple:
async function operation() { ... }const throttledOperation = throttle({ concurrency: 10, rate: 5 }, operation);for(let i = 0; i < 100; i++) {// at most 10 concurrent executions at a rate of 5 invocations per second.throttledOperation();}Note that each invocation to
throttle
creates a separate function with a separate limits. Therefore it is likely that you want to usethrottle
in a global context, not within a dynamic context:async function operation() { ... }for(let i = 0; i < 100; i++) {// WRONG - each iteration creates a separate throttled function that's only called once.const throttledOperation = throttle({ concurrency: 10, rate: 5 }, operation);throttledOperation();}A better way to use throttle avoids creating a named
operation
function altogether, ensuring it cannot be accidentally called without throttling:const operation = throttle({ concurrency: 10, rate: 5 }, async () => {...});Throttle supports functions with arguments automatically infers the correct type for the returned function:
// `operation` inferred to have type (str: string) => Promise<string>const operation = throttle({ concurrency: 10, rate: 5 }, async (str: string) => {return string;});In addition to limiting concurrency and invocation rate,
throttle
also supports retrying failed invocations, memoizing calls, and on-disk caching. See Limits for details.Modifiers
@public
Classes
class CostMetric
class CostMetric {}
A line item in the cost estimate, including the resource usage metric measured and its pricing.
Modifiers
@public
property comment
readonly comment?: string;
An optional comment, usually providing a link to the provider's pricing page and other data.
property informationalOnly
readonly informationalOnly?: boolean;
True if this cost metric is only for informational purposes (e.g. AWS's
logIngestion
) and does not contribute cost.
property measured
readonly measured: number;
The measured value of the cost metric, in units.
property name
readonly name: string;
The name of the cost metric, e.g.
functionCallDuration
property pricing
readonly pricing: number;
The price in USD per unit measured.
property unit
readonly unit: string;
The name of the units that pricing is measured in for this metric.
property unitPlural
readonly unitPlural?: string;
The plural form of the unit name. By default the plural form will be the name of the unit with "s" appended at the end, unless the last letter is capitalized, in which case there is no plural form (e.g. "GB").
method cost
cost: () => number;
The cost contribution of this cost metric. Equal to CostMetric.pricing * CostMetric.measured.
method describeCostOnly
describeCostOnly: () => string;
Return a string with the cost estimate for this metric, omitting comments.
method toString
toString: () => string;
Describe this cost metric, including comments.
class CostSnapshot
class CostSnapshot {}
A summary of the costs incurred by a faast.js module at a point in time. Output of FaastModule.costSnapshot.
Remarks
Cost information provided by faast.js is an estimate. It is derived from internal faast.js measurements and not by consulting data provided by your cloud provider.
**Faast.js does not guarantee the accuracy of cost estimates.**
**Use at your own risk.**
Example using AWS:
const faastModule = await faast("aws", m);try {// Invoke faastModule.functions.*} finally {await faastModule.cleanup();console.log(`Cost estimate:`);console.log(`${await faastModule.costSnapshot()}`);}AWS example output:
Cost estimate:functionCallDuration $0.00002813/second 0.6 second $0.00001688 68.4% [1]sqs $0.00000040/request 9 requests $0.00000360 14.6% [2]sns $0.00000050/request 5 requests $0.00000250 10.1% [3]functionCallRequests $0.00000020/request 5 requests $0.00000100 4.1% [4]outboundDataTransfer $0.09000000/GB 0.00000769 GB $0.00000069 2.8% [5]logIngestion $0.50000000/GB 0 GB $0 0.0% [6]---------------------------------------------------------------------------------------$0.00002467 (USD)* Estimated using highest pricing tier for each service. Limitations apply.** Does not account for free tier.[1]: https://aws.amazon.com/lambda/pricing (rate = 0.00001667/(GB*second) * 1.6875 GB = 0.00002813/second)[2]: https://aws.amazon.com/sqs/pricing[3]: https://aws.amazon.com/sns/pricing[4]: https://aws.amazon.com/lambda/pricing[5]: https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer[6]: https://aws.amazon.com/cloudwatch/pricing/ - Log ingestion costs not currently included.A cost snapshot contains several CostMetric values. Each
CostMetric
summarizes one component of the overall cost of executing the functions so far. Some cost metrics are common to all faast providers, and other metrics are provider-specific. The common metrics are:-
functionCallDuration
: the estimated billed CPU time (rounded to the next 100ms) consumed by completed cloud function calls. This is the metric that usually dominates cost.-
functionCallRequests
: the number of invocation requests made. Most providers charge for each invocation.Provider-specific metrics vary. For example, AWS has the following additional metrics:
-
sqs
: AWS Simple Queueing Service. This metric captures the number of queue requests made to insert and retrieve queued results (each 64kb chunk is counted as an additional request). SQS is used even if CommonOptions.mode is not set to"queue"
, because it is necessary for monitoring cloud function invocations.-
sns
: AWS Simple Notification Service. SNS is used to invoke Lambda functions when CommonOptions.mode is"queue"
.-
outboundDataTransfer
: an estimate of the network data transferred out from the cloud provider for this faast.js module. This estimate only counts data returned from cloud function invocations and infrastructure that faast.js sets up. It does not count any outbound data sent by your cloud functions that are not known to faast.js. Note that if you run faast.js on EC2 in the same region (see AwsOptions.region), then the data transfer costs will be zero (however, the cost snapshot will not include EC2 costs). Also note that if your cloud function transfers data from/to S3 buckets in the same region, there is no cost as long as that data is not returned from the function.-
logIngestion
: this cost metric is always zero for AWS. It is present to remind the user that AWS charges for log data ingested by CloudWatch Logs that are not measured by faast.js. Log entries may arrive significantly after function execution completes, and there is no way for faast.js to know exactly how long to wait, therefore it does not attempt to measure this cost. In practice, if your cloud functions do not perform extensive logging on all invocations, log ingestion costs from faast.js are likely to be low or fall within the free tier.The Local provider has no extra metrics.
Prices are retrieved dynamically from AWS and cached locally. Cached prices expire after 24h. For each cost metric, faast.js uses the highest price tier to compute estimated pricing.
Cost estimates do not take free tiers into account.
Modifiers
@public
property costMetrics
readonly costMetrics: CostMetric[];
The cost metric components for this cost snapshot. See CostMetric.
property options
readonly options: CommonOptions | AwsOptions;
The options used to initialize the faast.js module where this cost snapshot was generated.
property provider
readonly provider: string;
The Provider, e.g. "aws"
property stats
readonly stats: FunctionStats;
The function statistics that were used to compute prices.
method csv
csv: () => string;
Comma separated value output for a cost snapshot.
Remarks
The format is "metric,unit,pricing,measured,cost,percentage,comment".
Example output:
metric,unit,pricing,measured,cost,percentage,commentfunctionCallDuration,second,0.00002813,0.60000000,0.00001688,64.1% ,"https://aws.amazon.com/lambda/pricing (rate = 0.00001667/(GB*second) * 1.6875 GB = 0.00002813/second)"functionCallRequests,request,0.00000020,5,0.00000100,3.8% ,"https://aws.amazon.com/lambda/pricing"outboundDataTransfer,GB,0.09000000,0.00000844,0.00000076,2.9% ,"https://aws.amazon.com/ec2/pricing/on-demand/#Data_Transfer"sqs,request,0.00000040,13,0.00000520,19.7% ,"https://aws.amazon.com/sqs/pricing"sns,request,0.00000050,5,0.00000250,9.5% ,"https://aws.amazon.com/sns/pricing"logIngestion,GB,0.50000000,0,0,0.0% ,"https://aws.amazon.com/cloudwatch/pricing/ - Log ingestion costs not currently included."
method find
find: (name: string) => CostMetric | undefined;
Find a specific cost metric by name.
Returns
a CostMetric if found, otherwise
undefined
.
method toString
toString: () => string;
A summary of all cost metrics and prices in this cost snapshot.
method total
total: () => number;
Sum of cost metrics.
class FaastError
class FaastError extends VError {}
FaastError is a subclass of VError (https://github.com/joyent/node-verror). that is thrown by faast.js APIs and cloud function invocations.
Remarks
FaastError
is a subclass of VError, which provides an API for nested error handling. The main API is the same as the standard Error class, namely the err.message, err.name, and err.stack properties.Several static methods on FaastError are inherited from VError:
FaastError.fullStack(err) - property provides a more detailed stack trace that include stack traces of causes in the causal chain.
FaastError.info(err) - returns an object with fields
functionName
,args
, andlogUrl
. ThelogUrl
property is a URL pointing to the logs for a specific invocation that caused the error.logUrl
will be surrounded by whitespace on both sides to ease parsing as a URL by IDEs.FaastError.hasCauseWithName(err, cause) - returns true if the FaastError or any of its causes includes an error with the given name, otherwise false. All of the available names are in the enum FaastErrorNames. For example, to detect if a FaastError was caused by a cloud function timeout:
FaastError.hasCauseWithName(err, FaastErrorNames.ETIMEOUT)FaastError.findCauseByName(err, cause) - like FaastError.hasCauseWithName() except it returns the Error in the causal chain with the given name instead of a boolean, otherwise null.
Modifiers
@public
class FaastModuleProxy
class FaastModuleProxy<M extends object, O extends CommonOptions, S> implements FaastModule<M> {}
Implementation of FaastModule.
Remarks
FaastModuleProxy
provides a unified developer experience for faast.js modules on top of provider-specific runtime APIs. Most users will not createFaastModuleProxy
instances themselves; instead use faast, or faastAws or faastLocal.FaastModuleProxy
implements the FaastModule interface, which is the preferred public interface for faast modules.FaastModuleProxy
can be used to access provider-specific details and state, and is useful for deeper testing.Modifiers
@public
property functions
functions: ProxyModule<M>;
See documentation for FaastModule.functions.
property functionsDetail
functionsDetail: ProxyModuleDetail<M>;
See documentation for FaastModule.functionsDetail.
property options
readonly options: Required<CommonOptions>;
The options set for this instance, which includes default values.
property provider
provider: Provider;
The Provider, e.g. "aws".
method cleanup
cleanup: (userCleanupOptions?: CleanupOptions) => Promise<void>;
See documentation for FaastModule.cleanup.
method costSnapshot
costSnapshot: () => Promise<CostSnapshot>;
See documentation for FaastModule.costSnapshot.
method logUrl
logUrl: () => string;
See documentation for FaastModule.logUrl.
method off
off: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;
See documentation for FaastModule.off.
method on
on: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;
See documentation for FaastModule.on.
method stats
stats: (functionName?: string) => FunctionStats;
See documentation for FaastModule.stats.
class FunctionStats
class FunctionStats {}
Summary statistics for function invocations.
Remarks
localStartLatency remoteStartLatency executionTime◀──────────────────▶◁ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ▷◀──────────▶┌───────────────────────────────────┬──────────────────────────────────────┐│ │ ││ Local │ Cloud Provider ││ │ ││ ┌─────────┐ │ ┌──────────┐ ┌──────────┐ ││ │ │ │ │ │ │ │ ││ │ local │ │ │ request │ │ │ ││ invoke ────────▶│ queue │────┼──▶│ queue ├────────▶│ │ ││ │ │ │ │ │ │ │ ││ └─────────┘ │ └──────────┘ │ cloud │ ││ │ │ function │ ││ ┌─────────┐ │ ┌──────────┐ │ │ ││ │ │ │ │ │ │ │ ││ result ◀────────│ local │◀───┼───│ response │◀────────│ │ ││ │ polling │ │ │ queue │ │ │ ││ │ │ │ │ │ │ │ ││ └─────────┘ │ └──────────┘ └──────────┘ ││ │ │└───────────────────────────────────┴──────────────────────────────────────┘◁ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ▷returnLatency ◀───────▶sendResponseLatencylocalStartLatency
andexecutionTime
are measured on one machine and are free of clock skew.remoteStartLatency
andreturnLatency
are measured as time differences between machines and are subject to much more uncertainty, and effects like clock skew.All times are in milliseconds.
Modifiers
@public
property completed
completed: number;
The number of invocations that were successfully completed.
property errors
errors: number;
The number of invocations that resulted in an error. If an invocation is retried, an error is only counted once, no matter how many retries were attempted.
property estimatedBilledTime
estimatedBilledTime: Statistics;
Statistics for amount of time billed. This is similar to FunctionStats.executionTime except each sampled time is rounded up to the next 100ms.
property executionTime
executionTime: Statistics;
Statistics for function execution time in milliseconds. This is measured as wall clock time inside the cloud function, and does not include the time taken to send the response to the response queue. Note that most cloud providers round up to the next 100ms for pricing.
property invocations
invocations: number;
The number of invocations attempted. If an invocation is retried, this only counts the invocation once.
property localStartLatency
localStartLatency: Statistics;
Statistics for how long invocations stay in the local queue before being sent to the cloud provider.
property remoteStartLatency
remoteStartLatency: Statistics;
Statistics for how long requests take to start execution after being sent to the cloud provider. This typically includes remote queueing and cold start times. Because this measurement requires comparing timestamps from different machines, it is subject to clock skew and other effects, and should not be considered highly accurate. It can be useful for detecting excessively high latency problems. Faast.js attempt to correct for clock skew heuristically.
property retries
retries: number;
The number of invocation retries attempted. This counts retries attempted by faast.js to recover from transient errors, but does not count retries by the cloud provider.
property returnLatency
returnLatency: Statistics;
Statistics for how long it takes to return a response from the end of execution time to the receipt of the response locally. This measurement requires comparing timestamps from different machines, and is subject to clock skew and other effects. It should not be considered highly accurate. It can be useful for detecting excessively high latency problems. Faast.js attempts to correct for clock skew heuristically.
property sendResponseLatency
sendResponseLatency: Statistics;
Statistics for how long it takes to send the response to the response queue.
method toString
toString: () => string;
Summarize the function stats as a string.
Returns
a string showing the value of completed, retries, errors, and mean execution time. This string excludes invocations by default because it is often fixed.
class FunctionStatsEvent
class FunctionStatsEvent {}
Summarize statistics about cloud function invocations.
Modifiers
@public
property fn
readonly fn: string;
The name of the cloud function the statistics are about.
property stats
readonly stats: FunctionStats;
See FunctionStats.
method toString
toString: () => string;
Returns a string summarizing the statistics event.
Remarks
The string includes number of completed calls, errors, and retries, and the mean execution time for the calls that completed within the last time interval (1s).
class PersistentCache
class PersistentCache {}
A simple persistent key-value store. Used to implement Limits.cache for throttle.
Remarks
Entries can be expired, but are not actually deleted individually. The entire cache can be deleted at once. Hence this cache is useful for storing results that are expensive to compute but do not change too often (e.g. the node_modules folder from an 'npm install' where 'package.json' is not expected to change too often).
By default faast.js will use the directory
~/.faastjs
as a local cache to store data such as pricing retrieved from cloud APIs, and garbage collection information. This directory can be safely deleted if no faast.js instances are running.Modifiers
@public
constructor
constructor(dirRelativeToHomeDir: string, expiration?: number);
Construct a new persistent cache, typically used with Limits as part of the arguments to throttle.
Parameter dirRelativeToHomeDir
The directory under the user's home directory that will be used to store cached values. The directory will be created if it doesn't exist.
Parameter expiration
The age (in ms) after which a cached entry is invalid. Default:
24*3600*1000
(1 day).
property dir
readonly dir: string;
The directory on disk where cached values are stored.
property dirRelativeToHomeDir
readonly dirRelativeToHomeDir: string;
The directory under the user's home directory that will be used to store cached values. The directory will be created if it doesn't exist.
property expiration
readonly expiration: number;
The age (in ms) after which a cached entry is invalid. Default:
24*3600*1000
(1 day).
method clear
clear: ({ leaveEmptyDir,}?: { leaveEmptyDir?: boolean | undefined;}) => Promise<void>;
Deletes all cached entries from disk.
Parameter leaveEmptyDir
If true, leave the cache directory in place after deleting its contents. If false, the cache directory will be removed. Default:
true
.
method entries
entries: () => Promise<string[]>;
Retrieve all keys stored in the cache, including expired entries.
method get
get: (key: string) => Promise<Buffer | undefined>;
Retrieves the value previously set for the given key, or undefined if the key is not found.
method set
set: (key: string, value: Buffer | string | Uint8Array) => Promise<void>;
Set the cache key to the given value.
Returns
a Promise that resolves when the cache entry has been persisted.
class Statistics
class Statistics {}
Incrementally updated statistics on a set of values.
Modifiers
@public
constructor
constructor(printFixedPrecision?: number);
Incrementally track mean, stdev, min, max, of a sequence of values.
Parameter printFixedPrecision
The number of decimal places to print in Statistics.toString.
property max
max: number;
The maximum value observed. Initialized to
Number.NEGATIVE_INFINITY
.
property mean
mean: number;
The mean (average) of the values observed.
property min
min: number;
The minimum value observed. Initialized to
Number.POSITIVE_INFINITY
.
property printFixedPrecision
protected printFixedPrecision: number;
The number of decimal places to print in Statistics.toString
property samples
samples: number;
Number of values observed.
property stdev
stdev: number;
The standard deviation of the values observed.
property variance
variance: number;
The variance of the values observed.
method toString
toString: () => string;
Print the mean of the observations seen, with the precision specified in the constructor.
method update
update: (value: number | undefined) => void;
Update statistics with a new value in the sequence.
Interfaces
interface AwsClientFactory
interface AwsClientFactory {}
Factory for AWS service clients, which allows for custom construction and configuration. AWS Configuration.
Remarks
This is an advanced option. This provides a way for a faast.js client to instantiate AWS service objects for itself to provide custom options. Note that if you create a service object yourself, it won't have the default options that faast.js would use, which are:
- maxAttempts (faast.js default: 6) - region (faast.js default: "us-west-2") - logger (faast.js default: log.awssdk)
Modifiers
@public
property createCloudWatchLogs
createCloudWatchLogs?: () => CloudWatchLogs;
property createIAM
createIAM?: () => IAM;
property createLambda
createLambda?: () => Lambda;
property createLambdaForInvocations
createLambdaForInvocations?: () => Lambda;
A special AWS Lambda factory for creating lambda functions that are used for faast.js invocations. These special clients have the following options set by default in faast.js:
// Retries are handled by faast.js, not the sdk. maxAttempts: 0,
property createPricing
createPricing?: () => Pricing;
property createS3
createS3?: () => S3;
property createSNS
createSNS?: () => SNS;
property createSQS
createSQS?: () => SQS;
property createSts
createSts?: () => STS;
interface AwsOptions
interface AwsOptions extends CommonOptions {}
AWS-specific options for faastAws.
Modifiers
@public
property awsClientFactory
awsClientFactory?: AwsClientFactory;
AWS service factories. See AwsClientFactory.
property awsLambdaOptions
awsLambdaOptions?: Partial<CreateFunctionRequest>;
Additional options to pass to AWS Lambda creation. See CreateFunction.
Remarks
If you need specialized options, you can pass them to the AWS Lambda SDK directly. Note that if you override any settings set by faast.js, you may cause faast.js to not work:
const request: aws.Lambda.CreateFunctionRequest = {FunctionName,Role,Runtime: "nodejs18.x",Handler: "index.trampoline",Code,Description: "faast trampoline function",Timeout,MemorySize,...awsLambdaOptions};
property region
region?: AwsRegion;
The region to create resources in. Garbage collection is also limited to this region. Default:
"us-west-2"
.
property RoleName
RoleName?: string;
The role that the lambda function will assume when executing user code. Default:
"faast-cached-lambda-role"
. Rarely used.Remarks
When a lambda executes, it first assumes an execution role to grant access to resources.
By default, faast.js creates this execution role for you and leaves it permanently in your account (the role is shared across all lambda functions created by faast.js). By default, faast.js grants administrator privileges to this role so your code can perform any AWS operation it requires.
You can create a custom role that specifies more limited permissions if you prefer not to grant administrator privileges. Any role you assign for faast.js modules needs at least the following permissions:
- Execution Role:
{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Action": ["logs:*"],"Resource": "arn:aws:logs:*:*:log-group:faast-*"},{"Effect": "Allow","Action": ["sqs:*"],"Resource": "arn:aws:sqs:*:*:faast-*"}]}- Trust relationship (also known as
AssumeRolePolicyDocument
in the AWS SDK):{"Version": "2012-10-17","Statement": [{"Effect": "Allow","Principal": {"Service": "lambda.amazonaws.com"},"Action": "sts:AssumeRole"}]}
interface CleanupOptions
interface CleanupOptions {}
Options that apply to the FaastModule.cleanup method.
Modifiers
@public
property deleteCaches
deleteCaches?: boolean;
If true, delete cached resources. Default: false.
Remarks
Some resources are cached persistently between calls for performance reasons. If this option is set to true, these cached resources are deleted when cleanup occurs, instead of being left behind for future use. For example, on AWS this includes the Lambda Layers that are created for CommonOptions.packageJson dependencies. Note that only the cached resources created by this instance of FaastModule are deleted, not cached resources from other FaastModules. This is similar to setting
useCachedDependencies
tofalse
during function construction, exceptdeleteCaches
can be set at function cleanup time, and any other FaastModules created before cleanup may use the cached Layers.
property deleteResources
deleteResources?: boolean;
If true, delete provider cloud resources. Default: true.
Remarks
The cleanup operation has two functions: stopping the faast.js runtime and deleting cloud resources that were instantiated. If
deleteResources
is false, then only the runtime is stopped and no cloud resources are deleted. This can be useful for debugging and examining the state of resources created by faast.js.It is supported to call FaastModule.cleanup twice: once with
deleteResources
set tofalse
, which only stops the runtime, and then again set totrue
to delete resources. This can be useful for testing.
property gcTimeout
gcTimeout?: number;
Number of seconds to wait for garbage collection. Default: 10.
Remarks
Garbage collection can still be operating when cleanup is called; this option limits the amount of time faast waits for the garbage collector. If set to 0, the wait is unlimited.
interface CommonOptions
interface CommonOptions {}
Options common across all faast.js providers. Used as argument to faast.
Remarks
There are also more specific options for each provider. See AwsOptions and LocalOptions.
Modifiers
@public
property childProcess
childProcess?: boolean;
If true, create a child process to isolate user code from faast scaffolding. Default: true.
Remarks
If a child process is not created, faast runs in the same node instance as the user code and may not execute in a timely fashion because user code may block the event loop. Creating a child process for user code allows faast.js to continue executing even if user code never yields. This provides better reliability and functionality:
- Detect timeout errors more reliably, even if the function doesn't relinquish the CPU. Not applicable to AWS, which sends separate failure messages in case of timeout. See CommonOptions.timeout.
- CPU metrics used for detecting invocations with high latency, which can be used for automatically retrying calls to reduce tail latency.
The cost of creating a child process is mainly in the memory overhead of creating another node process.
property childProcessMemoryMb
childProcessMemoryMb?: number;
When childProcess is true, the child process will be spawned with the value of this property as the setting for --max-old-space-size.
Remarks
This is useful if a function requires the node process to limit its memory so that another spawned process (e.g. a browser instance) can use the rest.
Modifiers
@public
property concurrency
concurrency?: number;
The maximum number of concurrent invocations to allow. Default: 100, except for the
local
provider, where the default is 10.Remarks
The concurrency limit applies to all invocations of all of the faast functions summed together. It is not a per-function limit. To apply a per-function limit, use throttle. A value of 0 is equivalent to Infinity. A value of 1 ensures mutually exclusive invocations.
property description
description?: string;
A user-supplied description for this function, which may make it easier to track different functions when multiple functions are created.
property env
env?: { [key: string]: string;};
Environment variables available during serverless function execution. Default: {}.
property exclude
exclude?: string[];
Exclude a subset of files included by CommonOptions.include.
Remarks
The exclusion can be a directory or glob. Exclusions apply to all included entries.
property gc
gc?: 'auto' | 'force' | 'off';
Garbage collector mode. Default:
"auto"
.Remarks
Garbage collection deletes resources that were created by previous instantiations of faast that were not cleaned up by FaastModule.cleanup, either because it was not called or because the process terminated and did not execute this cleanup step. In
"auto"
mode, garbage collection may be throttled to run up to once per hour no matter how many faast.js instances are created. In"force"
mode, garbage collection is run without regard to whether another gc has already been performed recently. In"off"
mode, garbage collection is skipped entirely. This can be useful for performance-sensitive tests, or for more control over when gc is performed.Garbage collection is cloud-specific, but in general garbage collection should not interfere with the behavior or performance of faast cloud functions. When FaastModule.cleanup runs, it waits for garbage collection to complete. Therefore the cleanup step can in some circumstances take a significant amount of time even after all invocations have returned.
It is generally recommended to leave garbage collection in
"auto"
mode, otherwise garbage resources may accumulate over time and you will eventually hit resource limits on your account.Also see CommonOptions.retentionInDays.
property include
include?: (string | IncludeOption)[];
Include files to make available in the remote function. See IncludeOption.
Remarks
Each include entry is a directory or glob pattern. Paths can be specified as relative or absolute paths. Relative paths are resolved relative to the current working directory, or relative to the
cwd
option.If the include entry is a directory
"foo/bar"
, the directory"./foo/bar"
will be available in the cloud function. Directories are recursively added.Glob patterns use the syntax of node glob.
Also see CommonOptions.exclude for file exclusions.
property maxRetries
maxRetries?: number;
Maximum number of times that faast will retry each invocation. Default: 2 (invocations can therefore be attemped 3 times in total).
Remarks
Retries are automatically attempted for transient infrastructure-level failures such as rate limits or netowrk failures. User-level exceptions are not retried automatically. In addition to retries performed by faast, some providers automatically attempt retries. These are not controllable by faast. But as a result, your function may be retried many more times than this setting suggests.
property memorySize
memorySize?: number;
Memory limit for each function in MB. This setting has an effect on pricing. Default varies by provider.
Remarks
Each provider has different settings for memory size, and performance varies depending on the setting. By default faast picks a likely optimal value for each provider.
- aws: 1728MB
- local: 512MB (however, memory size limits aren't reliable in local mode.)
property mode
mode?: 'https' | 'queue' | 'auto';
Specify invocation mode. Default:
"auto"
.Remarks
Modes specify how invocations are triggered. In https mode, the functions are invoked through an https request or the provider's API. In queue mode, a provider-specific queue is used to invoke functions. Queue mode adds additional latency and (usually negligible) cost, but may scale better for some providers. In auto mode the best default is chosen for each provider depending on its particular performance characteristics.
The defaults are:
- aws:
"auto"
is"https"
. In https mode, the AWS SDK api is used to invoke functions. In queue mode, an AWS SNS topic is created and triggers invocations. The AWS API Gateway service is never used by faast, as it incurs a higher cost and is not needed to trigger invocations.- local: The local provider ignores the mode setting and always uses an internal asynchronous queue to schedule calls.
Size limits are affected by the choice of mode. On AWS the limit is 256kb for arguments and return values in
"queue"
mode, and 6MB for"https"
mode.Note that no matter which mode is selected, faast.js always creates a queue for sending back intermediate results for bookeeping and performance monitoring.
property packageJson
packageJson?: string | object;
Specify a package.json file to include with the code package.
Remarks
By default, faast.js will use webpack to bundle dependencies your remote module imports. In normal usage there is no need to specify a separate package.json, as webpack will statically analyze your imports and determine which files to bundle.
However, there are some use cases where this is not enough. For example, some dependencies contain native code compiled during installation, and webpack cannot bundle these native modules. such as dependencies with native code. or are specifically not designed to work with webpack. In these cases, you can create a separate
package.json
for these dependencies and pass the filename as thepackageJson
option. IfpackageJson
is anobject
, it is assumed to be a parsed JSON object with the same structure as a package.json file (useful for specifying a syntheticpackage.json
directly in code).The way the
packageJson
is handled varies by provider:- local: Runs
npm install
in a temporary directory it prepares for the function.- aws: Recursively calls faast.js to run
npm install
inside a separate lambda function specifically created for this purpose. Faast.js uses lambda to install dependencies to ensure that native dependencies are compiled in an environment that can produce binaries linked against lambda's execution environment. Packages are saved in a Lambda Layer.For AWS, if CommonOptions.useDependencyCaching is
true
(which is the default), then the Lambda Layer created will be reused in future function creation requests if the contents ofpackageJson
are the same.The
FAAST_PACKAGE_DIR
environment variable can be useful for debuggingpackageJson
issues.
property rate
rate?: number;
Rate limit invocations (invocations/sec). Default: no rate limit.
Remarks
Some services cannot handle more than a certain number of requests per second, and it is easy to overwhelm them with a large number of cloud functions. Specify a rate limit in invocation/second to restrict how faast.js issues requests.
property retentionInDays
retentionInDays?: number;
Specify how many days to wait before reclaiming cloud garbage. Default: 1.
Remarks
Garbage collection only deletes resources after they age beyond a certain number of days. This option specifies how many days old a resource needs to be before being considered garbage by the collector. Note that this setting is not recorded when the resources are created. For example, suppose this is the sequence of events:
- Day 0:
faast()
is called withretentionInDays
set to 5. Then, the function crashes (or omits the call to FaastModule.cleanup).- Day 1:
faast()
is called withretentionInDays
set to 1.In this sequence of events, on Day 0 the garbage collector runs and removes resources with age older than 5 days. Then the function leaves new garbage behind because it crashed or did not complete cleanup. On Day 1, the garbage collector runs and deletes resources at least 1 day old, which includes garbage left behind from Day 0 (based on the creation timestamp of the resources). This deletion occurs even though retention was set to 5 days when resources were created on Day 0.
Note that if
retentionInDays
is set to 0, garbage collection will remove all resources, even ones that may be in use by other running faast instances. Not recommended.See CommonOptions.gc.
property speculativeRetryThreshold
speculativeRetryThreshold?: number;
Reduce tail latency by retrying invocations that take substantially longer than other invocations of the same function. Default: 3.
Remarks
faast.js automatically measures the mean and standard deviation (σ) of the time taken by invocations of each function. Retries are attempted when the time for an invocation exceeds the mean time by a certain threshold.
speculativeRetryThreshold
specifies how many multiples of σ an invocation needs to exceed the mean for a given function before retry is attempted.The default value of σ is 3. This means a call to a function is retried when the time to execute exceeds three standard deviations from the mean of all prior executions of the same function.
This feature is experimental.
Modifiers
@beta
property timeout
timeout?: number;
Execution time limit for each invocation, in seconds. Default: 60.
Remarks
Each provider has a maximum time limit for how long invocations can run before being automatically terminated (or frozen). The following are the maximum time limits as of February 2019:
- aws: 15 minutes
- local: unlimited
Faast.js has a proactive timeout detection feature. It automatically attempts to detect when the time limit is about to be reached and proactively sends a timeout exception. Faast does this because not all providers reliably send timely feedback when timeouts occur, leaving developers to look through cloud logs. In general faast.js' timeout will be up to 5s earlier than the timeout specified, in order to give time to allow faast.js to send a timeout message. Proactive timeout detection only works with CommonOptions.childProcess set to
true
(the default).
property useDependencyCaching
useDependencyCaching?: boolean;
Cache installed dependencies from CommonOptions.packageJson. Only applies to AWS. Default: true.
Remarks
If
useDependencyCaching
istrue
, The resultingnode_modules
folder is cached in a Lambda Layer with the namefaast-${key}
, wherekey
is the SHA1 hash of thepackageJson
contents. These cache entries are removed by garbage collection, by default after 24h. Using caching reduces the need to install and upload dependencies every time a function is created. This is important for AWS because it creates an entirely separate lambda function to install dependencies remotely, which can substantially increase function deployment time.If
useDependencyCaching
is false, the lambda layer is created with the same name as the lambda function, and then is deleted when cleanup is run.
property validateSerialization
validateSerialization?: boolean;
Check arguments and return values from cloud functions are serializable without losing information. Default: true.
Remarks
Arguments to cloud functions are automatically serialized with
JSON.stringify
with a custom replacer that handles built-in JavaScript types such asDate
andBuffer
. Return values go through the same process. Some JavaScript objects cannot be serialized. By defaultvalidateSerialization
will verify that every argument and return value can be serialized and deserialized without losing information. AFaastError
will be thrown if faast.js detects a problem according to the following procedure:1. Serialize arguments and return values with
JSON.stringify
using a specialreplacer
function.2. Deserialize the values with
JSON.parse
with a specialreviver
function.3. Use assert.deepStringEqual to compare the original object with the deserialized object from step 2.
There is some overhead to this process because each argument is serialized and deserialized, which can be costly if arguments or return values are large.
property webpackOptions
webpackOptions?: webpack.Configuration;
Extra webpack options to use to bundle the code package.
Remarks
By default, faast.js uses webpack to bundle the code package. Webpack automatically handles finding and bundling dependencies, adding source mappings, etc. If you need specialized bundling, use this option to add or override the default webpack configuration. The library webpack-merge is used to combine configurations.
const config: webpack.Configuration = merge({entry,mode: "development",output: {path: "/",filename: outputFilename,libraryTarget: "commonjs2"},target: "node",resolveLoader: { modules: [__dirname, `${__dirname}/dist`] },node: { global: true, __dirname: false, __filename: false }},webpackOptions);Take care when setting the values of
entry
,output
, orresolveLoader
. If these options are overwritten, faast.js may fail to bundle your code. In particular, settingentry
to an array value will helpwebpack-merge
to concatenate its value instead of replacing the value that faast.js inserts for you.Default:
- aws:
{ externals: [new RegExp("^aws-sdk/?")] }
. In the lambda environment"aws-sdk"
is available in the ambient environment and does not need to be bundled.- other providers:
{}
The
FAAST_PACKAGE_DIR
environment variable can be useful for debugging webpack issues.
interface Detail
interface Detail<R> {}
A function return value with additional detailed information.
Modifiers
@public
property executionId
executionId?: string;
If available, the provider-specific execution identifier for this invocation.
Remarks
This ID may be added to the log entries for this invocation by the cloud provider.
property instanceId
instanceId?: string;
If available, the provider-specific instance identifier for this invocation.
Remarks
This ID refers to the specific container or VM used to execute this function invocation. The instance may be reused across multiple invocations.
property logUrl
logUrl?: string;
The URL of the logs for the specific execution of this function call.
Remarks
This is different from the general logUrl from FaastModule.logUrl, which provides a link to the logs for all invocations of all functions within that module. Whereas this logUrl is only for this specific invocation.
property value
value: R;
A Promise for the function's return value.
interface FaastModule
interface FaastModule<M extends object> {}
The main interface for invoking, cleaning up, and managing faast.js cloud functions. Returned by faast.
Modifiers
@public
property functions
functions: ProxyModule<M>;
Each call of a cloud function creates a separate remote invocation.
Remarks
The module passed into faast or its provider-specific variants (faastAws and faastLocal) is mapped to a ProxyModule version of the module, which performs the following mapping:
- All function exports that are generators are mapped to async generators.
- All function exports that return async generators are preserved as-is.
- All function exports that return promises have their type signatures preserved as-is.
- All function exports that return type T, where T is not a Promise, Generator, or AsyncGenerator, are mapped to functions that return Promise. Argument types are preserved as-is.
- All non-function exports are omitted in the remote module.
Arguments and return values are serialized with
JSON.stringify
when cloud functions are called, therefore what is received on the remote side might not match what was sent. Faast.js attempts to detect nonsupported arguments on a best effort basis.If the cloud function throws an exception or rejects its promise with an instance of
Error
, then the function will reject with FaastError on the local side. If the exception or rejection resolves to any value that is not an instance ofError
, the remote function proxy will reject with the value ofJSON.parse(JSON.stringify(err))
.Arguments and return values have size limitations that vary by provider and mode:
- AWS: 256KB in queue mode, 6MB arguments and 256KB return values in https mode. See AWS Lambda Limits.
- Local: limited only by available memory and the limits of childprocess.send.
Note that payloads may be base64 encoded for some providers and therefore different in size than the original payload. Also, some bookkeeping data are passed along with arguments and contribute to the size limit.
property functionsDetail
functionsDetail: ProxyModuleDetail<M>;
Similar to FaastModule.functions except each function returns a Detail object
Remarks
Advanced users of faast.js may want more information about each function invocation than simply the result of the function call. For example, the specific logUrl for each invocation, to help with detailed debugging. This interface provides a way to get this detailed information.
property provider
provider: Provider;
See Provider.
method cleanup
cleanup: (options?: CleanupOptions) => Promise<void>;
Stop the faast.js runtime for this cloud function and clean up ephemeral cloud resources.
Returns
a Promise that resolves when the
FaastModule
runtime stops and ephemeral resources have been deleted.Remarks
It is best practice to always call
cleanup
when done with a cloud function. A typical way to ensure this in normal execution is to use thefinally
construct:const faastModule = await faast("aws", m);try {// Call faastModule.functions.*} finally {// Note the `await`await faastModule.cleanup();}After the cleanup promise resolves, the cloud function instance can no longer invoke new calls on FaastModule.functions. However, other methods on FaastModule are safe to call, such as FaastModule.costSnapshot.
Cleanup also stops statistics events (See FaastModule.off).
By default, cleanup will delete all ephemeral cloud resources but leave behind cached resources for use by future cloud functions. Deleted resources typically include cloud functions, queues, and queue subscriptions. Logs are not deleted by cleanup.
Note that
cleanup
leaves behind some provider-specific resources:- AWS: Cloudwatch logs are preserved until the garbage collector in a future cloud function instance deletes them. The default log expiration time is 24h (or the value of CommonOptions.retentionInDays). In addition, the AWS Lambda IAM role is not deleted by cleanup. This role is shared across cloud function instances. Lambda layers are also not cleaned up immediately on AWS when CommonOptions.packageJson is used and CommonOptions.useDependencyCaching is true. Cached layers are cleaned up by garbage collection. Also see CleanupOptions.deleteCaches.
- Local: Logs are preserved in a temporary directory on local disk. Garbage collection in a future cloud function instance will delete logs older than 24h.
method costSnapshot
costSnapshot: () => Promise<CostSnapshot>;
Get a near real-time cost estimate of cloud function invocations.
Returns
a Promise for a CostSnapshot.
Remarks
A cost snapshot provides a near real-time estimate of the costs of the cloud functions invoked. The cost estimate only includes the cost of successfully completed calls. Unsuccessful calls may lack the data required to provide cost information. Calls that are still in flight are not included in the cost snapshot. For this reason, it is typically a good idea to get a cost snapshot after awaiting the result of FaastModule.cleanup.
Code example:
const faastModule = await faast("aws", m);try {// invoke cloud functions on faastModule.functions.*} finally {await faastModule.cleanup();const costSnapshot = await faastModule.costSnapshot();console.log(costSnapshot);}
method logUrl
logUrl: () => string;
The URL of logs generated by this cloud function.
Remarks
Logs are not automatically downloaded because they cause outbound data transfer, which can be expensive. Also, logs may arrive at the logging service well after the cloud functions have completed. This log URL specifically filters the logs for this cloud function instance. Authentication is required to view cloud provider logs.
The local provider returns a
file://
url pointing to a file for logs.
method off
off: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;
Deregister a callback for statistics events.
Remarks
Stops the callback listener from receiving future function statistics events. Calling FaastModule.cleanup also turns off statistics events.
method on
on: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;
Register a callback for statistics events.
Remarks
The callback is invoked once for each cloud function that was invoked within the last 1s interval, with a FunctionStatsEvent summarizing the statistics for each function. Typical usage:
faastModule.on("stats", console.log);
method stats
stats: (functionName?: string) => FunctionStats;
Statistics for a specific function or the entire faast.js module.
Parameter functionName
The name of the function to retrieve statistics for. If the function does not exist or has not been invoked, a new instance of FunctionStats is returned with zero values. If
functionName
omitted (undefined), then aggregate statistics are returned that summarize all cloud functions within this faast.js module.Returns
an snapshot of FunctionStats at a point in time.
interface IncludeOption
interface IncludeOption {}
Options for the CommonOptions.include option.
Modifiers
@public
property cwd
cwd?: string;
The working directory if
path
is relative. Defaults toprocess.cwd()
. For example, ifcwd
is"foo"
andpath
is"bar"
, then the contents of the directoryfoo/bar/
will be added to the remote function under the pathbar/
.
property path
path: string;
The path to the directory or glob to add to the cloud function.
interface Limits
interface Limits {}
Specify throttle limits. These limits shape the way throttle invokes the underlying function.
Modifiers
@public
property burst
burst?: number;
The maximum number of calls to the underlying function to "burst" -- e.g. the number that can be issued immediately as long as the rate limit is not exceeded. For example, if rate is 5 and burst is 5, and 10 calls are made to the throttled function, 5 calls are made immediately and then after 1 second, another 5 calls are made immediately. Setting burst to 1 means calls are issued uniformly every
1/rate
seconds. Ifrate
is not specified, thenburst
does not apply. Default: 1.
property cache
cache?: PersistentCache;
Similar to
memoize
except the map from function arguments to results is stored in a persistent cache on disk. This is useful to prevent redundant calls to APIs which are expected to return the same results for the same arguments, and which are likely to be called across many faast.js module instantiations. This is used internally by faast.js for caching cloud prices for AWS, and for saving the last garbage collection date for AWS. Persistent cache entries expire after a period of time. See PersistentCache.
property concurrency
concurrency: number;
The maximum number of concurrent executions of the underlying function to allow. Must be supplied, there is no default. Specifying
0
orInfinity
is allowed and means there is no concurrency limit.
property memoize
memoize?: boolean;
If
memoize
istrue
, then every call to the throttled function will be saved as an entry in a map from arguments to return value. If same arguments are seen again in a future call, the return value is retrieved from the Map rather than calling the function again. This can be useful for avoiding redundant calls that are expected to return the same results given the same arguments.The arguments will be captured with
JSON.stringify
, therefore types that do not stringify uniquely won't be distinguished from each other. Care must be taken when specifyingmemoize
to ensure avoid incorrect results.
property rate
rate?: number;
The maximum number of calls per second to allow to the underlying function. Default: no rate limit.
property retry
retry?: number | ((err: any, retries: number) => boolean);
Retry if the throttled function returns a rejected promise.
retry
can be a number or a function. If it is a numberN
, then up toN
additional attempts are made in addition to the initial call. If retry is a function, it should returntrue
if another retry attempt should be made, otherwisefalse
. The first argument will be the value of the rejected promise from the previous call attempt, and the second argument will be the number of previous retry attempts (e.g. the first call will have value 0). Default: 0 (no retry attempts).
interface LocalOptions
interface LocalOptions extends CommonOptions {}
Local provider options for faastLocal.
Modifiers
@public
Enums
enum FaastErrorNames
enum FaastErrorNames { EGENERIC = 'VError', ESERIALIZE = 'FaastSerializationError', ETIMEOUT = 'FaastTimeoutError', EMEMORY = 'FaastOutOfMemoryError', ECANCEL = 'FaastCancelError', EEXCEPTION = 'UserException', ECREATE = 'FaastCreateFunctionError', ECONCURRENCY = 'FaastConcurrencyError',}
Possible FaastError names. See FaastError. To test for errors matching these names, use the static method FaastError.hasCauseWithName().
Modifiers
@public
member ECANCEL
ECANCEL = 'FaastCancelError'
The function invocation was cancelled by user request.
member ECONCURRENCY
ECONCURRENCY = 'FaastConcurrencyError'
The remote cloud function failed to execute because of limited concurrency.
member ECREATE
ECREATE = 'FaastCreateFunctionError'
Could not create the remote cloud function or supporting infrastructure.
member EEXCEPTION
EEXCEPTION = 'UserException'
The exception was thrown by user's remote code, not by faast.js or the cloud provider.
member EGENERIC
EGENERIC = 'VError'
Generic error. See FaastError.
member EMEMORY
EMEMORY = 'FaastOutOfMemoryError'
The remote cloud function exceeded memory limits.
member ESERIALIZE
ESERIALIZE = 'FaastSerializationError'
The arguments passed to the cloud function could not be serialized without losing information.
member ETIMEOUT
ETIMEOUT = 'FaastTimeoutError'
The remote cloud function timed out.
Type Aliases
type Async
type Async<T> = T extends AsyncGenerator<infer R> ? AsyncGenerator<R> : T extends Generator<infer R> ? AsyncGenerator<R> : T extends Promise<infer R> ? Promise<R> : Promise<T>;
Async<T>
maps regular values to Promises and Iterators to AsyncIterators, IfT
is already a Promise or an AsyncIterator, it remains the same. This type is used to infer the return value of cloud functions from the types of the functions in the user's input module.Modifiers
@public
type AsyncDetail
type AsyncDetail<T> = T extends AsyncGenerator<infer R> ? AsyncGenerator<Detail<R>> : T extends Generator<infer R> ? AsyncGenerator<Detail<R>> : T extends Promise<infer R> ? Promise<Detail<R>> : Promise<Detail<T>>;
AsyncDetail<T>
is similar to Async except it maps retun values R toDetail<R>
, which is the return value with additional information about each cloud function invocation.Modifiers
@public
type AwsFaastModule
type AwsFaastModule<M extends object = object> = FaastModuleProxy< M, AwsOptions, AwsState>;
The return type of faastAws. See FaastModuleProxy.
Modifiers
@public
type AwsRegion
type AwsRegion = | 'us-east-1' | 'us-east-2' | 'us-west-1' | 'us-west-2' | 'ca-central-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'eu-west-3' | 'ap-northeast-1' | 'ap-northeast-2' | 'ap-northeast-3' | 'ap-southeast-1' | 'ap-southeast-2' | 'ap-south-1' | 'sa-east-1';
Valid AWS regions. Not all of these regions have Lambda support.
Modifiers
@public
type LocalFaastModule
type LocalFaastModule<M extends object = object> = FaastModuleProxy< M, LocalOptions, LocalState>;
The return type of faastLocal. See FaastModuleProxy.
Modifiers
@public
type Provider
type Provider = 'aws' | 'local';
The type of all supported cloud providers.
Modifiers
@public
type ProxyModule
type ProxyModule<M> = { [K in keyof M]: M[K] extends (...args: infer A) => infer R ? (...args: A) => Async<R> : never;};
ProxyModule<M>
is the type of FaastModule.functions.Remarks
ProxyModule<M>
maps an imported module's functions to promise-returning or async-iteratable versions of those functions. Non-function exports of the module are omitted. When invoked, the functions in aProxyModule
invoke a remote cloud function.Modifiers
@public
type ProxyModuleDetail
type ProxyModuleDetail<M> = { [K in keyof M]: M[K] extends (...args: infer A) => infer R ? (...args: A) => AsyncDetail<R> : never;};
Namespaces
namespace CostAnalyzer
namespace CostAnalyzer {}
Analyze the cost of a workload across many provider configurations.
Modifiers
@public
variable awsConfigurations
const awsConfigurations: Configuration[];
Default AWS cost analyzer configurations include all memory sizes for AWS Lambda.
Remarks
The default AWS cost analyzer configurations include every memory size from 128MB to 3008MB in 64MB increments. Each configuration has the following settings:
{provider: "aws",options: {mode: "https",memorySize,timeout: 300,gc: "off",childProcess: true}}Use
Array.map
to change orArray.filter
to remove some of these configurations. For example:const configsWithAtLeast1GB = awsConfigurations.filter(c => c.memorySize > 1024)const shorterTimeout = awsConfigurations.map(c => ({...c, timeout: 60 }));Modifiers
@public
function analyze
analyze: <T extends object, A extends string>( userWorkload: Workload<T, A>) => Promise<Result<T, A>>;
Estimate the cost of a workload using multiple configurations and providers.
Parameter userWorkload
a CostAnalyzer.Workload object specifying the workload to run and additional parameters.
Returns
A promise for a CostAnalyzer.Result
Remarks
It can be deceptively difficult to set optimal parameters for AWS Lambda and similar services. On the surface there appears to be only one parameter: memory size. Choosing more memory also gives more CPU performance, but it's unclear how much. It's also unclear where single core performance stops getting better. The workload cost analyzer solves these problems by making it easy to run cost experiments.
(AWS)┌───────┐┌────▶│ 128MB ││ └───────┘│ ┌───────┐┌─────────────────┐ ├────▶│ 256MB │┌──────────────┐ │ │ │ └───────┘│ workload │───▶│ │ │ ...└──────────────┘ │ │ │ ┌───────┐│ cost analyzer │─────┼────▶│3008MB │┌──────────────┐ │ │ └───────┘│configurations│───▶│ │└──────────────┘ │ │└─────────────────┘costAnalyzer
is the entry point. It automatically runs this workload against multiple configurations in parallel. Then it uses faast.js' cost snapshot mechanism to automatically determine the price of running the workload with each configuration.Example:
// functions.tsexport function randomNumbers(n: number) {let sum = 0;for (let i = 0; i < n; i++) {sum += Math.random();}return sum;}// cost-analyzer-example.tsimport { writeFileSync } from "fs";import { CostAnalyzer, FaastModule } from "faastjs";import * as funcs from "./functions";async function work(faastModule: FaastModule<typeof funcs>) {await faastModule.functions.randomNumbers(100000000);}async function main() {const results = await CostAnalyzer.analyze({ funcs, work });writeFileSync("cost.csv", results.csv());}main();Example output (this is printed to
console.log
unless the CostAnalyzer.Workload.silent istrue
):✔ aws 128MB queue 15.385s 0.274σ $0.00003921✔ aws 192MB queue 10.024s 0.230σ $0.00003576✔ aws 256MB queue 8.077s 0.204σ $0.00003779▲ ▲ ▲ ▲ ▲ ▲│ │ │ │ │ │provider │ mode │ stdev average│ │ execution estimatedmemory │ time costsize │average cloudexecution timeThe output lists the provider, memory size, (CommonOptions.mode), average time of a single execution of the workload, the standard deviation (in seconds) of the execution time, and average estimated cost for a single run of the workload.
The "execution time" referenced here is not wall clock time, but rather execution time in the cloud function. The execution time does not include any time the workload spends waiting locally. If the workload invokes multiple cloud functions, their execution times will be summed even if they happen concurrently. This ensures the execution time and cost are aligned.
Modifiers
@public
class Result
class Result<T extends object, A extends string> {}
Cost analyzer results for each workload and configuration.
Remarks
The
estimates
property has the cost estimates for each configuration. See CostAnalyzer.Estimate.Modifiers
@public
property estimates
readonly estimates: Estimate<A>[];
Cost estimates for each configuration of the workload. See CostAnalyzer.Estimate.
property workload
readonly workload: Required<Workload<T, A>>;
The workload analyzed.
method csv
csv: () => string;
Comma-separated output of cost analyzer. One line per cost analyzer configuration.
Remarks
The columns are:
-
memory
: The memory size allocated.-
cloud
: The cloud provider.-
mode
: See CommonOptions.mode.-
options
: A string summarizing other faast.js options applied to theworkload
. See CommonOptions.-
completed
: Number of repetitions that successfully completed.-
errors
: Number of invocations that failed.-
retries
: Number of retries that were attempted.-
cost
: The average cost of executing the workload once.-
executionTime
: the aggregate time spent executing on the provider for all cloud function invocations in the workload. This is averaged across repetitions.-
executionTimeStdev
: The standard deviation ofexecutionTime
.-
billedTime
: the same asexectionTime
, except rounded up to the next 100ms for each invocation. Usually very close toexecutionTime
.
interface Estimate
interface Estimate<A extends string> {}
A cost estimate result for a specific cost analyzer configuration.
Modifiers
@public
property config
config: Configuration;
The worload configuration that was analyzed. See CostAnalyzer.Configuration.
property costSnapshot
costSnapshot: CostSnapshot;
The cost snapshot for the cost analysis of the specific (workload, configuration) combination. See CostSnapshot.
property extraMetrics
extraMetrics: WorkloadAttribute<A>;
Additional workload metrics returned from the work function. See CostAnalyzer.WorkloadAttribute.
interface Workload
interface Workload<T extends object, A extends string> {}
A user-defined cost analyzer workload for CostAnalyzer.analyze.
Example:
Modifiers
@public
property concurrency
concurrency?: number;
The amount of concurrency to allow. Concurrency can arise from multiple repetitions of the same configuration, or concurrenct executions of different configurations. This concurrency limit throttles the total number of concurrent workload executions across both of these sources of concurrency. Default: 64.
property configurations
configurations?: Configuration[];
An array of configurations to run the work function against (see CostAnalyzer.Configuration). For example, each entry in the array may specify a provider, memory size, and other options. Default: CostAnalyzer.awsConfigurations.
property format
format?: (attr: A, value: number) => string;
Format an attribute value for console output. This is displayed by the cost analyzer when all of the repetitions for a configuration have completed. The default returns
${attribute}:${value.toFixed(1)}
.
property formatCSV
formatCSV?: (attr: A, value: number) => string;
Format an attribute value for CSV. The default returns
value.toFixed(1)
.
property funcs
funcs: T;
The imported module that contains the cloud functions to test.
property repetitions
repetitions?: number;
The number of repetitions to run the workload for each cost analyzer configuration. Higher repetitions help reduce the jitter in the results. Repetitions execute in the same FaastModule instance. Default: 10.
property silent
silent?: boolean;
If true, do not output live results to the console. Can be useful for running the cost analyzer as part of automated tests. Default: false.
property summarize
summarize?: (summaries: WorkloadAttribute<A>[]) => WorkloadAttribute<A>;
Combine CostAnalyzer.WorkloadAttribute instances returned from multiple workload executions (caused by value of CostAnalyzer.Workload.repetitions). The default is a function that takes the average of each attribute.
property work
work: (faastModule: FaastModule<T>) => Promise<WorkloadAttribute<A> | void>;
A function that executes cloud functions on
faastModule.functions.*
. The work function should returnvoid
if there are no custom workload attributes. Otherwise, it should return a CostAnalyzer.WorkloadAttribute object which maps user-defined attribute names to numerical values for the workload. For example, this might measure bandwidth or some other metric not tracked by faast.js, but are relevant for evaluating the cost-performance tradeoff of the configurations analyzed by the cost analyzer.
type Configuration
type Configuration = { provider: 'aws'; options: AwsOptions;};
An input to CostAnalyzer.analyze, specifying one configuration of faast.js to run against a workload. See AwsOptions.
Modifiers
@public
type WorkloadAttribute
type WorkloadAttribute<A extends string> = { [attr in A]: number;};
User-defined custom metrics for a workload. These are automatically summarized in the output; see CostAnalyzer.Workload.
Modifiers
@public
Package Files (1)
Dependencies (30)
- @aws-sdk/abort-controller
- @aws-sdk/client-cloudwatch
- @aws-sdk/client-cloudwatch-logs
- @aws-sdk/client-iam
- @aws-sdk/client-lambda
- @aws-sdk/client-pricing
- @aws-sdk/client-s3
- @aws-sdk/client-sns
- @aws-sdk/client-sqs
- @aws-sdk/client-sts
- @aws-sdk/lib-storage
- @aws-sdk/types
- @types/debug
- @types/verror
- @types/webpack
- archiver
- commander
- debug
- fs-extra
- listr
- memory-fs
- ora
- process-doctor
- tslib
- uuid
- verror
- webpack
- webpack-merge
- webpack-node-externals
- yauzl
Dev Dependencies (27)
- @microsoft/api-documenter
- @microsoft/api-extractor
- @types/archiver
- @types/aws-lambda
- @types/express
- @types/fs-extra
- @types/listr
- @types/lolex
- @types/memory-fs
- @types/node
- @types/papaparse
- @types/tar-stream
- @types/uuid
- @types/webpack-node-externals
- @types/yauzl
- ava
- c8
- commitizen
- cz-conventional-changelog
- lolex
- papaparse
- prettier
- semantic-release
- tslint
- tslint-config-prettier
- typescript
- webpack-cli
Peer Dependencies (1)
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/faastjs
.
- Markdown[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/faastjs)
- HTML<a href="https://www.jsdocs.io/package/faastjs"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 4951 ms. - Missing or incorrect documentation? Open an issue for this package.