# @timberio/tools

> Javascript logging tools

Latest version **0.35.0** (published 2019-08-19) · ISC license · 0 weekly downloads

## Install

```sh
npm install @timberio/tools
pnpm add @timberio/tools
yarn add @timberio/tools
bun add @timberio/tools
```

## Health

**Score 30/100 (F)** — status: abandoned.

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

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.35.0 |
| Published | 2019-08-19 |
| First published | 2018-11-20 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 92.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 44 |
| Author | Lee Benson |
| Maintainers | binarylogic, jszwedko, leebenson, luciofranco, zsherman |

## Links

- npm: https://www.npmjs.com/package/@timberio/tools
- Repository: https://github.com/timberio/timber-js/tree/master/packages/tools
- Homepage: https://github.com/timberio/timber-js/tree/master/packages/tools#readme
- Issues: https://github.com/timberio/timber-js/issues
- npm.io page: https://npm.io/package/@timberio/tools

## Dependencies (1)

- [@timberio/types](https://npm.io/package/@timberio/types.md) ^0.35.0

## Recent versions

- 0.35.0 (latest) — 2019-08-19
- 0.34.2 — 2019-08-19
- 0.34.1 — 2019-06-27
- 0.33.0 — 2019-03-09
- 0.32.0 — 2019-03-09
- 0.31.0 — 2019-03-09
- 0.30.0 — 2019-01-22
- 0.29.0 — 2019-01-22
- 0.28.0 — 2019-01-16
- 0.27.0 — 2019-01-15
- 0.26.0 — 2019-01-15
- 0.25.0 — 2019-01-09
- 0.24.0 — 2019-01-06
- 0.23.0 — 2019-01-06
- 0.22.0 — 2018-12-29
- … 21 more at https://npm.io/package/@timberio/tools/versions

## README

# 🌲 Timber - JS lib tools

![Beta: Ready for testing](https://img.shields.io/badge/early_release-beta-green.svg)
![Speed: Blazing](https://img.shields.io/badge/speed-blazing%20%F0%9F%94%A5-brightgreen.svg)
[![ISC License](https://img.shields.io/badge/license-ISC-ff69b4.svg)](LICENSE.md)

**New to Timber?** [Here's a low-down on logging in Javascript.](https://github.com/timberio/timber-js)

## `@timberio/tools`

This library provides helper tools used by the [Javascript logger](https://github.com/timberio/timber-js).

## Tools

### `Queue<T>`

Generic [FIFO](<https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)>) queue. Used by `makeThrottle` to store pipeline functions to be executed as concurrent 'slots' become available. Provides fast retrieval for any primitive or object that needs ordered, first-in, first-out retrieval.

Used to store `.log()` Promises that are being batched/throttled.

**Usage example**

```typescript
import { Queue } from "@timberio/tools";

// Interface representing a person
interface IPerson {
  name: string;
  age: number;
}

// Create a queue to store `IPerson` objects
const q = new Queue<IPerson>();

// Add a couple of records...
q.push({ name: "Jeff", age: 50 });
q.push({ name: "Sally", age: 39 });

// Pull values from the queue...
while (q.length) {
  console.log(q.shift().name); // <-- first Jeff, then Sally...
}
```

### `makeThrottle<T>(max: number)`

Returns a `throttle` higher-order function, which wraps an `async` function, and limits the number of active Promises to `max: number`

The `throttle` function has this signature:

```
throttle(fn: T): (...args: InferArgs<T>[]) => Promise<InferArgs<T>>
```

**Usage example**

```typescript
import Timber from "@timberio/logger";
import { makeThrottle } from "@timberio/tools";

// Create a new Timber instance
const timber = new Timber("apiKey");

// Guarantee a pipeline will run a max of 2x at once
const throttle = makeThrottle(2);

// Create a basic pipeline function which resolves after 2 seconds
const pipeline = async log =>
  new Promise(resolve => {
    setTimeout(() => resolve(log), 2000);
  });

// Add a pipeline which has been throttled
timber.addPipeline(throttle(pipeline));

// Add 10 logs, and store the Promises
const promises = [];
for (let i = 0; i < 10; i++) {
  promises.push(timber.log({ message: `Hello ${i}` }));
}

void (async () => {
  void (await promises); // <-- will take 10 seconds total!
})();
```

### `makeBatch(size: number, flushTimeout: number)`

Creates a higher-order batch function aggregates Timber logs and resolves when either `size` # of logs have been collected, or when `flushTimeout` (in ms) has elapsed -- whichever occurs first.

This is used alongside the throttler to provide an array of [`ITimberLog`](https://github.com/timberio/timber-js/tree/master/packages/types#itimberlog) to the function set in the `.setSync()` method, to be synced with [Timber.io](https://timber.io)

Used internally by the [`@timberio/core Base class`](https://github.com/timberio/timber-js/blob/master/packages/core/src/base.ts) to implicitly batch logs:

```typescript
// Create a throttler, for sync operations
const throttle = makeThrottle(this._options.syncMax);

// Sync after throttling
const throttler = throttle((logs: any) => {
  return this._sync!(logs);
});

// Create a batcher, for aggregating logs by buffer size/interval
const batcher = makeBatch(this._options.batchSize, this._options.batchInterval);

this._batch = batcher((logs: any) => {
  return throttler(logs);
});
```

## LICENSE

[ISC](LICENSE.md)

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