faastjs

  • Version 6.0.23
  • Published
  • 1.96 MB
  • 21 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 and Google Cloud Functions.

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: any;
minimal: any;
warn: any;
gc: any;
leaks: any;
calls: any;
webpack: any;
provider: any;
awssdk: any;
};
  • 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", "google", or "local". See Provider.

    Parameter fmodule

    A module imported with import * as X from "Y";. Using require 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";. Using require also works but loses type information.

    Parameter options

    Most common options are in CommonOptions. Additional AWS-specific options are in AwsOptions.

    Modifiers

    • @public

function faastGoogle

faastGoogle: <M extends object>(
fmodule: M,
options?: GoogleOptions
) => Promise<GoogleFaastModule<M>>;
  • The main entry point for faast with Google provider.

    Parameter fmodule

    A module imported with import * as X from "Y";. Using require also works but loses type information.

    Parameter options

    Most common options are in CommonOptions. Additional Google-specific options are in GoogleOptions.

    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";. Using require 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 use throttle 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;

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.

    For Google, extra metrics include outboundDataTransfer similar to AWS, and pubsub, which combines costs that are split into sns and sqs on AWS.

    The Local provider has no extra metrics.

    Prices are retrieved dynamically from AWS and Google 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 | GoogleOptions;
  • The options used to initialize the faast.js module where this cost snapshot was generated.

property provider

readonly provider: string;

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.

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, and logUrl. The logUrl 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, 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 create FaastModuleProxy instances themselves; instead use faast, or faastAws, faastGoogle, 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>;

property functionsDetail

functionsDetail: ProxyModuleDetail<M>;

property options

readonly options: Required<CommonOptions>;
  • The options set for this instance, which includes default values.

property provider

provider: Provider;

method cleanup

cleanup: (userCleanupOptions?: CleanupOptions) => Promise<void>;

method costSnapshot

costSnapshot: () => Promise<CostSnapshot>;

method logUrl

logUrl: () => string;

method off

off: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;

method on

on: (name: 'stats', listener: (statsEvent: FunctionStatsEvent) => void) => void;

method stats

stats: (functionName?: string) => FunctionStats;

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 ◀───────▶
    sendResponseLatency

    localStartLatency and executionTime are measured on one machine and are free of clock skew. remoteStartLatency and returnLatency 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;

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 | Readable | Blob
) => 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;

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 AwsOptions

interface AwsOptions extends CommonOptions {}
  • AWS-specific options for faastAws.

    Modifiers

    • @public

property awsConfig

awsConfig?: ConfigurationOptions;
  • Additional options to pass to all AWS services. See AWS.Config.

    Remarks

    If you need to specify AWS options such as credentials, you can pass set these options here. Note that faast.js will override some options even if they are specified here, specifically the options used to create the Lambda service, to ensure they allow for faast to function correctly. Options set in CommonOptions override those set here.

    Example of passing in credentials:

    const credentials = { accessKeyId, secretAccessKey };
    const m = await faastAws(funcs, { credentials });

property awsLambdaOptions

awsLambdaOptions?: Partial<Lambda.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: "nodejs14.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 {}

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.

interface CommonOptions

interface CommonOptions {}

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

    - google: 1024MB

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

    - google: "auto" is "https". In https mode, a PUT request is made to invoke the cloud function. In queue mode, a PubSub topic is created to invoke functions.

    - 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. For Google the limit is 10MB regardless of mode. In Local mode messages are sent via node's IPC and are subject to OS IPC limits.

    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.

    - google: uses Google Cloud Function's native support for package.json.

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

    On Google, logs are retained according to Google's default expiration policy (30 days) instead of being deleted by garbage collection.

    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

    - google: 9 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.

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, faastGoogle, 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.

    - Google: 10MB in https and queue modes. See Google Cloud Function Quotas.

    - 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;

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.

    - Google: Google Stackdriver automatically deletes log entries after 30 days.

    - 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 GoogleOptions

interface GoogleOptions extends CommonOptions {}
  • Google-specific options for faastGoogle.

    Modifiers

    • @public

property googleCloudFunctionOptions

googleCloudFunctionOptions?: cloudfunctions_v1.Schema$CloudFunction;
  • Additional options to pass to Google Cloud Function creation. See projects.locations.functions.

    Remarks

    If you need specialized options, you can pass them to the Google Cloud Functions API directly. Note that if you override any settings set by faast.js, you may cause faast.js to not work:

    const requestBody: CloudFunctions.Schema$CloudFunction = {
    name,
    entryPoint: "trampoline",
    timeout,
    availableMemoryMb,
    sourceUploadUrl,
    runtime: "nodejs14",
    ...googleCloudFunctionOptions
    };

property region

region?: GoogleRegion;
  • The region to create resources in. Garbage collection is also limited to this region. Default: "us-central1".

interface IncludeOption

interface IncludeOption {}

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.

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

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'

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, If T 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 to Detail<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
>;

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 GoogleFaastModule

type GoogleFaastModule<M extends object = object> = FaastModuleProxy<
M,
GoogleOptions,
GoogleState
>;

type GoogleRegion

type GoogleRegion =
| 'asia-east1'
| 'asia-east2'
| 'asia-northeast1'
| 'asia-south1'
| 'asia-southeast1'
| 'australia-southeast1'
| 'europe-north1'
| 'europe-west1'
| 'europe-west2'
| 'europe-west3'
| 'europe-west4'
| 'europe-west6'
| 'northamerica-northeast1'
| 'southamerica-east1'
| 'us-central1'
| 'us-east1'
| 'us-east4'
| 'us-west1'
| 'us-west2';

type LocalFaastModule

type LocalFaastModule<M extends object = object> = FaastModuleProxy<
M,
LocalOptions,
LocalState
>;

type Provider

type Provider = 'aws' | 'google' | '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 a ProxyModule 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 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

variable googleConfigurations

const googleConfigurations: Configuration[];
  • Default Google Cloud Functions cost analyzer configurations include all available memory sizes.

    Remarks

    Each google cost analyzer configuration follows this template:

    {
    provider: "google",
    options: {
    mode: "https",
    memorySize,
    timeout: 300,
    gc: "off",
    childProcess: true
    }
    }

    where memorySize is in [128, 256, 512, 1024, 2048].

    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│───▶│ │ │
    └──────────────┘ │ │ │ (Google)
    └─────────────────┘ │ ┌───────┐
    ├────▶│ 128MB │
    │ └───────┘
    │ ┌───────┐
    └────▶│ 256MB │
    └───────┘

    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

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>[];

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 the workload. 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 of executionTime.

    - billedTime: the same as exectionTime, except rounded up to the next 100ms for each invocation. Usually very close to executionTime.

interface Estimate

interface Estimate<A extends string> {}
  • A cost estimate result for a specific cost analyzer configuration.

    Modifiers

    • @public

property config

config: 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>;

interface Workload

interface Workload<T extends object, A extends string> {}

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[];

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>;

property work

work: (faastModule: FaastModule<T>) => Promise<WorkloadAttribute<A> | void>;
  • A function that executes cloud functions on faastModule.functions.*. The work function should return void 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;
}
| {
provider: 'google';
options: GoogleOptions;
};

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 (21)

Dev Dependencies (29)

Peer Dependencies (1)

Badge

To add a badge like this onejsDocs.io badgeto 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>