faastjs

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.

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,comment
  functionCallDuration,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.

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.

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.

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).

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.

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.

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;

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"
        }
      ]
    }

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 to false during function construction, except deleteCaches 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 to false, which only stops the runtime, and then again set to true 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.

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 the packageJson option. If packageJson is an object, it is assumed to be a parsed JSON object with the same structure as a package.json file (useful for specifying a synthetic package.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 of packageJson are the same.

  The FAAST_PACKAGE_DIR environment variable can be useful for debugging packageJson 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 with retentionInDays set to 5. Then, the function crashes (or omits the call to FaastModule.cleanup).

  - Day 1: faast() is called with retentionInDays 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 is true, The resulting node_modules folder is cached in a Lambda Layer with the name faast-${key}, where key is the SHA1 hash of the packageJson 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 as Date and Buffer. Return values go through the same process. Some JavaScript objects cannot be serialized. By default validateSerialization will verify that every argument and return value can be serialized and deserialized without losing information. A FaastError 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 special replacer function.

  2. Deserialize the values with JSON.parse with a special reviver 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, or resolveLoader. If these options are overwritten, faast.js may fail to bundle your code. In particular, setting entry to an array value will help webpack-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.

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.

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 of Error, the remote function proxy will reject with the value of JSON.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 the finally 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.

property cwd

cwd?: string;

• The working directory if path is relative. Defaults to process.cwd(). For example, if cwd is "foo" and path is "bar", then the contents of the directory foo/bar/ will be added to the remote function under the path bar/.

property path

path: string;

• The path to the directory or glob to add to the cloud function.

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. If rate is not specified, then burst 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 or Infinity is allowed and means there is no concurrency limit.

property memoize

memoize?: boolean;

• If memoize is true, 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 specifying memoize 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 number N, then up to N additional attempts are made in addition to the initial call. If retry is a function, it should return true if another retry attempt should be made, otherwise false. 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).

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.

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 or Array.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.ts
  export function randomNumbers(n: number) {
      let sum = 0;
      for (let i = 0; i < n; i++) {
          sum += Math.random();
      }
      return sum;
  }
  
  // cost-analyzer-example.ts
  import { 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 is true):

    ✔ 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  estimated
          memory        │     time       cost
           size         │
                  average cloud
                  execution time

  The 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