Supercharge News

News and updates from Supercharge and the ecosystem.

Collections 4.0

Jan 08, 2022

A new major release of our @supercharge/collections package has been published the in the NPM registry 🥳 Version 4.0 is now available to everyone.

Breaking Changes (compared to version 3.x)

  • use named exports

    // now
const { Collect } = require('@supercharge/collections')

// before
const Collect = require('@supercharge/collections')

  • remove synchronous collection: everything is async and must be awaited

    // now
const { Collect } = require('@supercharge/collections')
const numsGreater5 = await Collect([5, 6, 7]).filter(num => num > 5)

// before
const Collect = require('@supercharge/collections')
const numsGreater5 = Collect([5, 6, 7]).filter(num => num > 5).all()

  • removed iterator support: @supercharge/collections v4 is fully async and we’re going to add async iterators. In a later feature release. For now, we’re shipping v4 without async iterators. We appreciate a pull request if you want to add iterator support.

What is @supercharge/collections?

The @supercharge/collections package is an async array implementation. It provides a fluent interface to work with JavaScript arrays supporting async callbacks in methods like map, find, filter, reduce, and so on.

Here’s an example how to use @supercharge/collections:

import { Collect } from '@supercharge/collections'

await Collect([ 1, 2, 3, 4, 5 ])
  .map(async id => {
    return await User.findById(id)
  })
  .filter(async user => {
    return await user.notSubscribedToNewsletter()
  })
  .forEach(user => {
    await user.subscribe()
  })

Documentation

We added a dedicated and extensive docs section for collections. Sweet!

Enjoy working with collections!

Arrays 1.0

Dec 31, 2021

The new @supercharge/arrays package has been published the in the NPM registry 🥳 Version 1.0 is now available to everyone.

What is Arrays?

The @supercharge/arrays package is an extended array class with helpful, additional methods compared to native JavaScript arrays. For example, there’s

  • at()
  • min()
  • max()
  • last()
  • findLast()
  • collapse()
  • isEmpty()
  • isNotEmpty()
  • diff(...candidates)
  • intersect(...candidates)
  • … and many more

Documentation

Check out the extensive documentation for Arrays is available in the docs. Sweet!

Examples

Import the @supercharge/arrays package and use it the same way you would use JavaScript’s Array class:

import { Arr } = from '@supercharge/arrays'

const users = Arr.from([])

users.isEmpty()
// true

users
  .push({ id: 1, name: 'Marcus' })
  .push({ id: 2, name: 'Norman' })
  .push({ id: 3, name: 'Christian' })

users.isNotEmpty()
// true

users.length()
// 3

const christian = users.last(user => {
  return user.id > 1
})
// { id: 3, name: 'Christian' }

Enjoy Arrays!

Sttp 1.0

Nov 12, 2021

The new @supercharge/sttp package has been published the in the NPM registry 🥳 Version 1.0 is now available to everyone.

What is Sttp?

Sttp is an HTTP client for a pleasant developer experience. It wraps the axios library providing a fluent interface to expressively compose your HTTP requests.

Documentation

An extensive documentation for Sttp is available in the docs. Sweet!

Why Not Use Axios Directly?

Sttp is an axios wrapper. So “why not use axios directly"?

Sttp (like axios) should make your life as a developer enjoyable. And I don’t enjoy working axios directly. Everything is configured using objects. But the editors and IDEs are not good at showing IntelliSense for objects. It’s always a guess on what to configure.

Do you find yourself looking at the axios docs on how to send query parameters? Or searching for the config key to send a request payload? Yeah, same here. I hate that.

Sttp solves that config-guessing by providing a fluent and expressive interface. Configure a request using Sttp’s chainable methods. You’ll also notice that Sttp’s requests are more readable.

Another thing is that axios throws an error when receiving a response with status code >= 400. Who thinks throwing an error for a valid response is the correct behavior? Sttp always returns a response instance. The Sttp response comes with handy methods to determine whether it’s a success, redirect, or error response.

Sttp Example

You may send a POST request with query parameters, request headers, and payload like this:

import { Sttp } from '@supercharge/sttp'

const response = await Sttp
  .withQueryParams({ page: 3 })
  .withHeaders({ 'X-API-Token': 123 })
  .withPayload({ name: 'Supercharge' })
  .post('https://your-api.com/v2/users')

Then use the response instance to process the returned data. For example, you can call:

if (response.isSuccess()) {
  return response.payload()
  // { id: 1, name: 'Supercharge' }
}

if (response.isError()) {
  return response.payload()
  // { statusCode: 401, message: 'Invalid X-API-Token' }
}

Enjoy Sttp!

Promise Pool 2.0

Nov 10, 2021

We published a new major version of the @supercharge/promise-pool package: version 2.0 is now available in the NPM registry!

Changes

There’s no new feature for the promise pool in version 2.0.

A change that may be helpful for you is the extended package exports. We’re now exporting internal classes and types besides the PromisePool class:

  • PromisePool
  • PromisePoolError
  • StopThePromisePoolError
  • Stoppable (interface)
  • ReturnValue (interface)

These classes and types may help you to type your code properly when passing promise pool values instance between methods.

Breaking Changes and Migration

Starting from @supercharge/promise-pool@2.x the package uses named exports. When migrating from 1.x to 2.x you must adjust your imports and destructure the PromisePool class out of the package:

// Now: 2.x
import { PromisePool } from '@supercharge/promise-pool'
// or
const { PromisePool } = require('@supercharge/promise-pool')

// Before: 1.x
import PromisePool from '@supercharge/promise-pool' // required the `esModuleInterop` flag in tsconfig.json
// or
const PromisePool = require('@supercharge/promise-pool')

Previously, in @supercharge/promise-pool@1.x we used a default export matching the module.exports = XYZ syntax from CommonJS. This style of export required TypeScript users to enable the esModuleInterop flag in their tsconfig.json. To avoid this esModuleInterop flag requirement we changed the exports to use named exports.

Thank you Amit (amitlevy21) for sharing this issue and also providing a pull request to fix it ❤️

Promise Pool 1.9.0: Stoppable Pool

Nov 03, 2021

Starting from version 1.9.0 of @supercharge/promise-pool you can manually stop a running promise pool instance. You may stop a pool from the .process() or .handleError() methods. Both methods provide a stoppable pool instance as the third parameter.

Here’s an example how to stop a running promise pool:

import PromisePool from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .process(async (user, index, pool) => {
    if (condition) {
      return pool.stop()
    }

    // processes the `user` data
  })

You may also stop the pool from within the .handleError() method in case you need to:

import PromisePool from '@supercharge/promise-pool'

await PromisePool
  .for(users)
  .handleError(async (error, user, pool) => {
    if (error instanceof SomethingBadHappenedError) {
      return pool.stop()
    }

    // handle the given `error`
  })
  .process(async (user, index, pool) => {
    // processes the `user` data
  })

Enjoy!