# simple-lambda-client

> A simple, convenient way to invoke aws lambda functions with best practices.

Latest version **2.3.5** (published 2025-11-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install simple-lambda-client
pnpm add simple-lambda-client
yarn add simple-lambda-client
bun add simple-lambda-client
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.5 |
| Published | 2025-11-30 |
| First published | 2020-09-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=8.0.0 |
| Dependencies | 6 |
| Unpacked size | 25.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | ehmpathy |
| Maintainers | uladkasach |
| Keywords | aws, lambda, api, client, serverless, typescript |

## Links

- npm: https://www.npmjs.com/package/simple-lambda-client
- Repository: https://github.com/ehmpathy/simple-lambda-client
- Issues: https://github.com/ehmpathy/simple-lambda-client/issues
- npm.io page: https://npm.io/package/simple-lambda-client

## Dependencies (6)

- [aws-sdk](https://npm.io/package/aws-sdk.md) ^2.1426.0
- [hash-fns](https://npm.io/package/hash-fns.md) ^1.1.0
- [domain-objects](https://npm.io/package/domain-objects.md) 0.31.0
- [helpful-errors](https://npm.io/package/helpful-errors.md) 1.5.3
- [with-simple-cache](https://npm.io/package/with-simple-cache.md) ^0.15.1
- [simple-in-memory-cache](https://npm.io/package/simple-in-memory-cache.md) ^0.4.0

## Alternatives

- [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads
- [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads
- [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads
- [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads
- [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads

## Recent versions

- 2.3.5 (latest) — 2025-11-30
- 2.3.4 — 2024-12-31
- 2.3.2 — 2023-08-11
- 2.3.1 — 2023-08-07
- 2.3.0 — 2023-08-07
- 2.2.3 — 2023-08-01
- 2.2.2 — 2023-08-01
- 2.2.1 — 2023-08-01
- 2.2.0 — 2023-07-28
- 2.1.3 — 2020-09-16
- 2.1.2 — 2020-09-16
- 2.1.1 — 2020-09-03
- 2.1.0 — 2020-09-03

## README

# simple-lambda-client

![ci_on_commit](https://github.com/uladkasach/simple-lambda-client/workflows/test/badge.svg)
![deploy_on_tag](https://github.com/uladkasach/simple-lambda-client/workflows/publish/badge.svg)

A simple, convenient way to invoke aws lambda functions with best practices.

Best practices:

- optional logDebug of input and output
- throw an error if response contains an error object

# install

```sh
npm install --save simple-lambda-client
```

# use

```ts
import { invokeLambdaFunction } from 'simple-lambda-client';

const service = 'svc-jobs';
const stage = getStage();

const getJobByUuid = (event: { uuid: string }): Promise<{ job: Job | null }> =>
  invokeLambdaFunction({ service, stage, function: 'getJobByUuid', event });

const getJobsByPostal = (event: { postal: string }): Promise<{ jobs: Job[] }> =>
  invokeLambdaFunction({ service, stage, function: 'getJobsByPostal', event });

// ...

export const svcJobs = {
  getJobByUuid,
  getJobsByPostal
}
```

# details

### invoke

`simple-lambda-client` exports a function that lets you invoke lambda functions with best practices.

You can use this function directly if you want...

```ts
import { invokeLambdaFunction } from 'simple-lambda-client';

const result = await invokeLambdaFunction({ service, stage, function, event });
// ...do amazing things with result...
```

### type

But you'll probably want to create a reusable method with typedefs

```ts
export const getJobByUuid = (event: { uuid: string }) =>
  invokeLambdaFunction<{ job: Job | null }>({ service, stage, function: 'getJobByUuid', event });
```

Which makes using that a lot easier

```ts
const { job } = await getJobByUuid({ uuid: '__uuid__' });
// ...do amazing things with result...
```

### namespace

You may also want to build a full representation of some lambda service under a namespace

```ts
export const svcJobs = {
  getJobByUuid,
  // ...other methods...
};
```

This adds extra context about "where" the methods lambdas invoking is coming from

```ts
import { svcJobs } from '../path/to/client';

const { job } = await svcJobs.getJobByUuid({ uuid: '__uuid__' });
// ...do amazing things with result...
```

# features

### errors

When this library detects that the lambda you called has thrown an error, it automatically parses it and throws an error of class `LambdaInvocationError`

For example
```ts
import { invokeLambdaFunction, LambdaInvocationError } from 'simple-lambda-client';

try {
  await invokeLambdaFunction({
    service: 'svc-does-not-exist', // 👈 assume this will cause an error
    function: 'doAwesomeThing',
    stage: 'dev',
    event: {},
  });
} catch (error) {
  expect(error).toBeInstanceOf(LambdaInvocationError) // 👈 error will be an instance of this class
}
```

### logging

When given a `logDebug` method, this library emits input and output logs with best practices, to make debugging a breeze.

For example
```ts
await invokeLambdaFunction({
  service: 'svc-oceans',
  function: 'cleanup',
  stage: 'dev',
  event: {},
  logDebug: console.log, // 👈 will now emit logs to the console
});
```

### caching

When given a `cache` instance, this library will wrap the lambda invocation [with-simple-caching](https://github.com/ehmpathy/with-simple-caching)

For example
```ts
import { createCache } from 'simple-im-memory-cache';

await invokeLambdaFunction({
  service: 'svc-oceans',
  function: 'cleanup',
  stage: 'dev',
  event: {},
  cache: createCache(), // 👈 will now cache the response, with a key of [service, function, stage, event]
});
```


# tips

### lambda permissions

if you're using this client from inside a lambda, ensure that this lambda has permission to invoke other lambdas

```yml
# serverless.yml
iamRoleStatements:
  - Effect: Allow
    Action:
      - lambda:InvokeFunction
      - lambda:InvokeAsync
    Resource: '*' # TODO: constrain to a specific account, region, service, and stage
```

---
_Source: https://npm.io/package/simple-lambda-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._