# @adobe/spacecat-shared-utils

> Shared modules of the Spacecat Services - utils

Latest version **1.128.0** (published 2026-10-02) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @adobe/spacecat-shared-utils
pnpm add @adobe/spacecat-shared-utils
yarn add @adobe/spacecat-shared-utils
bun add @adobe/spacecat-shared-utils
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.128.0 |
| Published | 2026-10-02 |
| First published | 2023-11-28 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0.0 <25.0.0 |
| Dependencies | 14 |
| Unpacked size | 402.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 4 |
| Maintainers | marbec, tripod, garthdb, lazd, adobe-admin, patrickfulton, trieloff, krisnye, dcpfsdk, natebaldwin, devongovett, aspro83, symanovi, dpfister, stefan-guggisberg, rofe, kptdobe, adobehalls, fullcolorcoder, djaeggi, dylandepass, mhaack, amol-anand, stopp-adobe, namarora, doten, duh_schmidt, asthabh23, aljoseph, zdahbi, tuicu, fmeschbe |

## Links

- npm: https://www.npmjs.com/package/@adobe/spacecat-shared-utils
- Repository: https://github.com/adobe/spacecat-shared
- Homepage: https://github.com/adobe/spacecat-shared#readme
- Issues: https://github.com/adobe/spacecat-shared/issues
- npm.io page: https://npm.io/package/@adobe/spacecat-shared-utils

## Dependencies (14)

- [zod](https://npm.io/package/zod.md) ^4.1.11
- [urijs](https://npm.io/package/urijs.md) 1.19.11
- [cheerio](https://npm.io/package/cheerio.md) 1.2.0
- [date-fns](https://npm.io/package/date-fns.md) 4.4.0
- [franc-min](https://npm.io/package/franc-min.md) 6.2.0
- [ipaddr.js](https://npm.io/package/ipaddr.js.md) ^2.2.0
- [iso-639-3](https://npm.io/package/iso-639-3.md) 3.0.1
- [validator](https://npm.io/package/validator.md) ^13.15.15
- [@adobe/fetch](https://npm.io/package/@adobe/fetch.md) 4.3.1
- [aws-xray-sdk](https://npm.io/package/aws-xray-sdk.md) 3.12.0
- [world-countries](https://npm.io/package/world-countries.md) 5.1.0
- [@json2csv/plainjs](https://npm.io/package/@json2csv/plainjs.md) 7.0.8
- [@aws-sdk/client-s3](https://npm.io/package/@aws-sdk/client-s3.md) 3.1139.0
- [@aws-sdk/client-sqs](https://npm.io/package/@aws-sdk/client-sqs.md) 3.1139.0

## Recent versions

- 1.128.0 (latest) — 2026-10-02
- 1.127.0 — 2026-09-30
- 1.126.0 — 2026-08-17
- 1.125.2 — 2026-08-12
- 1.125.1 — 2026-08-03
- 1.125.0 — 2026-07-17
- 1.124.1 — 2026-07-03
- 1.124.0 — 2026-07-01
- 1.123.1 — 2026-06-26
- 1.123.0 — 2026-06-26
- 1.122.1 — 2026-06-26
- 1.122.0 — 2026-06-25
- 1.121.0 — 2026-06-24
- 1.120.1 — 2026-06-18
- 1.120.0 — 2026-06-16
- … 303 more at https://npm.io/package/@adobe/spacecat-shared-utils/versions

## README

# SpaceCat Shared Utilities

This repository contains a collection of shared utility functions used across various SpaceCat projects. These utilities provide a range of checks and validations, from basic data type validation to more complex checks like ISO date strings and URL validation.

> **v1.76.0**: Added trace ID propagation support for distributed tracing across SpaceCat services.

## Installation

To install the SpaceCat Shared Utilities, you can use npm:

```bash
npm install spacecat-shared-utils
```

Or, if you are using yarn:

```bash
yarn add spacecat-shared-utils
```

## Usage

Here's how you can use the different utility functions in your project:

```javascript
import { isBoolean, isValidUrl } from 'spacecat-shared-utils';

console.log(isBoolean('true')); // true
console.log(isValidUrl('https://www.example.com')); // true
```

## Functions

The library includes the following utility functions:

- `isBoolean(value)`: Determines if the given value is a boolean or a string representation of a boolean.
- `isInteger(value)`: Checks if the given value is an integer.
- `isValidDate(obj)`: Checks whether the given object is a valid JavaScript Date.
- `isIsoDate(str)`: Validates whether the given string is a JavaScript ISO date string in Zulu (UTC) timezone.
- `isIsoTimeOffsetsDate(str)`: Validates whether the given string is a JavaScript ISO date string following UTC time offsets format.
- `isNumber(value)`: Determines if the given value is a number.
- `isObject(obj)`: Checks if the given parameter is an object and not an array or null.
- `isString(str)`: Determines if the given parameter is a string.
- `toBoolean(value)`: Converts a given value to a boolean. Throws an error if the value is not a boolean.
- `arrayEquals(a, b)`: Compares two arrays for equality.
- `isValidUrl(urlString)`: Validates whether the given string is a valid URL with http or https protocol.
- `hasText(str)`: Checks if the given string is not empty.
- `dateAfterDays(number)`: Calculates the date after a specified number of days from the current date.

## Log Wrapper

The `logWrapper` enhances your Lambda function logs by automatically prepending `jobId` (from message) and `traceId` (from AWS X-Ray) to all log statements. This improves log traceability across distributed services.

### Features
- Automatically extracts AWS X-Ray trace ID
- Includes jobId from message when available  
- Enhances `context.log` directly - **no code changes needed**
- Works seamlessly with existing log levels (info, error, debug, warn, trace, etc.)

### Usage

```javascript
import { logWrapper, sqsEventAdapter } from '@adobe/spacecat-shared-utils';

async function run(message, context) {
  const { log } = context;
  
  // Use context.log as usual - trace IDs are added automatically
  log.info('Processing started'); 
  // Output: [jobId=xxx] [traceId=1-xxx-xxx] Processing started
}

export const main = wrap(run)
  .with(sqsEventAdapter)
  .with(logWrapper)  // Add this line early in the wrapper chain
  .with(dataAccess)
  .with(sqs)
  .with(secrets)
  .with(helixStatus);
```

**Note:** The `logWrapper` enhances `context.log` directly. All existing code using `context.log` will automatically include trace IDs and job IDs in logs without any code changes.

## SQS Event Adapter

The library also includes an SQS event adapter to convert an SQS record into a function parameter. This is useful when working with AWS Lambda functions that are triggered by an SQS event. Usage:

```javascript
import { sqsEventAdapter } from '@adobe/spacecat-shared-utils';

// ...

export const main = wrap(run)
  .with(dataAccess)
  .with(sqsEventAdapter) // Add this line
  .with(sqs)
  .with(secrets)
  .with(helixStatus);
````

## AWS X-Ray Integration

### getTraceId()

Extracts the current AWS X-Ray trace ID from the segment. Returns `null` if not in AWS Lambda or no segment is available.

```javascript
import { getTraceId } from '@adobe/spacecat-shared-utils';

const traceId = getTraceId();
// Returns: '1-5e8e8e8e-5e8e8e8e5e8e8e8e5e8e8e8e' or null
```

This function is automatically used by `logWrapper` to include trace IDs in logs.

## Testing

This library includes a comprehensive test suite to ensure the reliability of the utility functions. To run the tests, use the following command:

```bash
npm test
```

## Sub-path Exports

To avoid pulling in the full dependency tree (~110MB), import from a sub-path:

| Import | Dependencies |
|--------|-------------|
| `@adobe/spacecat-shared-utils` | All (~110MB) |
| `@adobe/spacecat-shared-utils/core` | None — pure JS only |
| `@adobe/spacecat-shared-utils/aws` | `@aws-sdk/*`, `aws-xray-sdk`, `@adobe/fetch` ⚠ **Side effect:** initializes HTTP connection pool at import time — requires outbound internet access |
| `@adobe/spacecat-shared-utils/locale` | `cheerio`, `world-countries`, `franc-min`, `iso-639-3`, `@adobe/fetch` ⚠ **Side effect:** initializes HTTP connection pool at import time — requires outbound internet access |
| `@adobe/spacecat-shared-utils/calendar` | `date-fns` |
| `@adobe/spacecat-shared-utils/schemas` | `zod` |
| `@adobe/spacecat-shared-utils/constants` | None — pure data |

### TypeScript

Sub-path exports require `"moduleResolution": "node16"`, `"nodenext"`, or `"bundler"` in `tsconfig.json`. Legacy `"moduleResolution": "node"` does not resolve sub-path exports.

### Maintenance

Any new `src/` file that contains top-level imperative code (anything beyond `import`/`export` statements) must be added to the `sideEffects` array in `package.json`.

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE.txt) file for details.

---
_Source: https://npm.io/package/@adobe/spacecat-shared-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._