npm package: @ircam/sc-utils
Description: Set of simple generic utilities (type check, common math functions, etc.)
Latest version: 1.13.0

# sc-utils

Simple generic utilities (type check, common math functions, etc.)

## Install

```
npm install --save @ircam/sc-utils
```

## API

<!-- api -->
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

*   [almostEqual][1]
*   [almostEqualArray][2]
*   [atodb][3]
*   [counter][4]
*   [dbtoa][5]
*   [decibelToLinear][6]
*   [decibelToPower][7]
*   [delay][8]
*   [exponentialScale][9]
*   [frequencyToMidi][10]
*   [ftom][11]
*   [getTime][12]
*   [hertzToNormalised][13]
*   [idGenerator][14]
*   [isBrowser][15]
*   [isDefined][16]
*   [isFunction][17]
*   [isNumber][18]
*   [isPlainObject][19]
*   [isSequence][20]
*   [isString][21]
*   [isTouchDevice][22]
*   [isTypedArray][23]
*   [isURL][24]
*   [linearScale][25]
*   [linearToDecibel][26]
*   [logarithmicScale][27]
*   [midiToFrequency][28]
*   [modulo][29]
*   [mtof][30]
*   [normalisedToHertz][31]
*   [normalizedToTableScale][32]
*   [powerToDecibel][33]
*   [sleep][34]
*   [tableToNormalizedScale][35]

## almostEqual

Checks if two numeric values are approximately equal within a given
tolerance.

### Parameters

*   `value` **[number][36]** The first value to compare.
*   `reference` **[number][36]** The second value to compare.
*   `tolerance` **[number][36]** The tolerance within
    which the values are considered equal.
    Note: tolerance must take into account the sum of all relative and
    absolute errors. (optional, default `Number.EPSILON`)

### Examples

```javascript
import { almostEqual } from '@ircam/sc-utils';
almostEqual(0.1 + 0.2, 0.3); // true
almostEqual(0.1 + 0.2, 1e-18); // false
almostEqual(0.1, 0.11, 0.02); // true
```

Returns **[boolean][37]** Returns `true` if the values are approximately
equal, otherwise `false`.

## almostEqualArray

*   **See**: [almostEqual][1]

Checks if two arrays of numeric values are approximately equal element-wise
within a given tolerance.

### Parameters

*   `value` **[Array][38]<[number][36]>** The first array to compare.
*   `reference` **[Array][38]<[number][36]>** The second array to compare.
*   `tolerance` **[number][36]** The tolerance within which the
    values are considered equal.
    Note: tolerance must take into account the sum of all relative and
    absolute errors. (optional, default `Number.EPSILON`)

### Examples

```javascript
import { almostEqualArray } from '@ircam/sc-utils';
almostEqualArray([0.1, 0.1 + 0.2], [0.1, 0.3]); // true
```

Returns **[boolean][37]** Returns `true` if the arrays have got the same size, and
if every value of the same index are approximately equal. Otherwise `false`.

## atodb

Convert a linear gain into dB

*Alias:* `linearToDecibel`

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { atodb } from '@ircam/sc-utils';
atodb(0);
// > 1
```

Returns **[number][36]**&#x20;

## counter

Create a counter function.

### Parameters

*   `from` **[number][36]** Start of the counter, included (optional, default `0`)
*   `to` **[number][36]** End of the counter, included (optional, default `Number.MAX_SAFE_INTEGER`)
*   `step` **[number][36]** Increment / decrement step, if 0 returns `from` forever (optional, default `1`)

### Examples

```javascript
import { counter } from '@ircam/sc-utils';
const myCounter = counter(0.1, 0.3, 0.1);
counter(); // 0.1
counter(); // 0.2
counter(); // 0.3
counter(); // 0.1
```

Returns **[Function][39]**&#x20;

## dbtoa

Convert a dB into linear gain

*Alias:* `decibelToLinear`

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { dbtoa } from '@ircam/sc-utils';
dbtoa(0);
// > 1
```

Returns **[number][36]**&#x20;

## decibelToLinear

Convert a dB into linear gain (i.e. gain)

*Alias:* `dbtoa`

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { decibelToLinear } from '@ircam/sc-utils';
decibelToLinear(0);
// > 1
```

Returns **[number][36]**&#x20;

## decibelToPower

Convert a dB into power gain

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
```

Returns **[number][36]**&#x20;

## delay

Wait for a given number of milliseconds.

See also `sleep`

### Parameters

*   `ms` **[Number][36]** Number of milliseconds to wait

### Examples

```javascript
import { delay } from '@ircam/sc-utils';
// wait for 1 second
await delay(1000);
```

Returns **[Promise][40]**&#x20;

## exponentialScale

Create an exponential scale function.

### Parameters

*   `inputStart` **[number][36]** Start value of input range
*   `inputEnd` **[number][36]** End value of input range
*   `outputStart` **[number][36]** Start value of output range
*   `outputEnd` **[number][36]** End value of output range
*   `base` **[number][36]** Base value for exponential scaling, default to `2` (optional, default `2`)
*   `clip` **[boolean][37]** Clip output to output range, default to `false` (optional, default `false`)

### Examples

```javascript
const { exponentialScale } = utils;
const midiToFreq = exponentialScale(69, 81, 440, 880);
midiToFreq(57);
// > 220
```

## frequencyToMidi

Convert a frequency in Hz to a MIDI note

### Parameters

*   `freq` **[number][36]** Frequency to convert

### Examples

```javascript
import { frequencyToMidi } from '@ircam/sc-utils';
const freq = frequencyToMidi(440);
// > 69
```

Returns **[number][36]**&#x20;

## ftom

Convert a frequency in Hz to a MIDI note

*Alias:* `frequencyToMidi`

### Parameters

*   `freq` **[number][36]** Frequency to convert

### Examples

```javascript
import { ftom } from '@ircam/sc-utils';
const freq = ftom(440);
// > 69
```

Returns **[number][36]**&#x20;

## getTime

Provide a unified clock in seconds accross platforms, with an origin defined by
the start of the process.

### Examples

```javascript
import { getTime } from '@ircam/sc-utils';

setInterval(() => {
  const now = getTime();
  // ...
}, 1000);
```

Returns **[number][36]**&#x20;

## hertzToNormalised

Convert a frequency in Hertz to a normalised one in \[0, 1].

Normalised frequency of 1 is half the sample-rate (Nyquist frequency).

### Parameters

*   `frequencyHertz` **[number][36]** Frequency in Hertz to convert
*   `sampleRate` **[number][36]** Twice the Nyquist frequency (optional, default `{}`)

    *   `sampleRate.sampleRate`   (optional, default `2`)

### Examples

```javascript
import { hertzToNormalised } from '@ircam/sc-utils';
hertzToNormalised(12000, {sampleRate: 48000});
// > 0.5
```

Returns **[number][36]**&#x20;

## idGenerator

Create a iterator of incrementing ids

*DEPRECATED* Use the more generic and user friendly `counter` instead.

### Examples

```javascript
import { idGenerator } from '@ircam/sc-utils';
const generator = idGenerator();
const id = generator.next().value
```

Returns **Iterator**&#x20;

## isBrowser

Check if the platform is a browser or a node process

### Examples

```javascript
import { isBrowser } from '@ircam/sc-utils';
isBrowser();
// > true|false
```

Returns **[boolean][37]**&#x20;

## isDefined

Check if the value is defined.

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isDefined } from '@ircam/sc-utils';
isDefined(42); // true
isDefined(undefined); // false
isDefined(); // false
isDefined(null); // true
isDefined(NaN); // true
isDefined(0); // true
```

Returns **[boolean][37]**&#x20;

## isFunction

Check if the value is a function

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isFunction } from '@ircam/sc-utils';
isFunction(() => {});
// > true
```

Returns **[boolean][37]**&#x20;

## isNumber

Check if the value is a number, including Infinity.
If you want to excluse Infinity, check the native Number.isFinite function

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isNumber } from '@ircam/sc-utils';
isNumber(42);
// > true
```

Returns **[boolean][37]**&#x20;

## isPlainObject

Check if the value is a Plain Old Javascript Object (POJO)

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isPlainObject } from '@ircam/sc-utils';
isPlainObject({ a: 1 });
// > true
```

Returns **[boolean][37]**&#x20;

## isSequence

Check if the value is a sequence (`Array` or `TypedArray`) of finite numbers

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isSequence } from '@ircam/sc-utils';
isSequence([1, 2, 3]);
// > true
```

Returns **[boolean][37]**&#x20;

## isString

Check if the value is a string

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isString } from '@ircam/sc-utils';
isString('test');
// > true
```

Returns **[boolean][37]**&#x20;

## isTouchDevice

Check if the device supports touch events

### Examples

```javascript
import { isTouchDevice } from '@ircam/sc-utils';
isTouchDevice();
// > true|false
```

Returns **[boolean][37]**&#x20;

## isTypedArray

Check if the value is a TypedArray

### Parameters

*   `val` **any** Value to check

### Examples

```javascript
import { isTypedArray } from '@ircam/sc-utils';
isTypedArray(new Float32Array([1, 2, 3]));
// > true
```

Returns **[boolean][37]**&#x20;

## isURL

Check if the value is a valid URL

### Parameters

*   `url` &#x20;
*   `val` **any** Value to check

### Examples

```javascript
import { isURL } from '@ircam/sc-utils';
isURL('http://sub.my-site.org/abcd?test=123');
// > true
```

Returns **[boolean][37]**&#x20;

## linearScale

Create a linear scale function.

### Parameters

*   `inputStart` **[number][36]** Start value of input range
*   `inputEnd` **[number][36]** End value of input range
*   `outputStart` **[number][36]** Start value of output range
*   `outputEnd` **[number][36]** End value of output range
*   `clip` **[boolean][37]** Clip output to output range, default to `false` (optional, default `false`)

### Examples

```javascript
import { linearScale } from '@ircam/sc-utils';
const myScale = linearScale(0, 1, 50, 100);
myScale(0.5);
// > 75
```

Returns **[Function][39]**&#x20;

## linearToDecibel

Convert a linear gain into dB

*Alias:* `atodb`

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
```

Returns **[number][36]**&#x20;

## logarithmicScale

Create a logarithmic scale function.

### Parameters

*   `inputStart` **[number][36]** Start value of input range
*   `inputEnd` **[number][36]** End value of input range
*   `outputStart` **[number][36]** Start value of output range
*   `outputEnd` **[number][36]** End value of output range
*   `base` **[number][36]** Base value for logarithmic scaling, default to `2` (optional, default `2`)
*   `clip` **[boolean][37]** Clip output to output range, default to `false` (optional, default `false`)

### Examples

```javascript
const { logarithmicScale } = utils;
const freqToMidi = logarithmicScale(440, 880, 69, 81);
freqToMidi(220);
// > 57
```

## midiToFrequency

Convert a MIDI note to frequency

### Parameters

*   `midiNote` **[number][36]** MIDI Note to convert

### Examples

```javascript
import { midiToFrequency } from '@ircam/sc-utils';
const freq = midiToFrequency(69);
// > 440
```

Returns **[number][36]**&#x20;

## modulo

*   **See**: [https://en.wikipedia.org/wiki/Modulo][41]

Calculates the modulo operation with an optional offset.

### Parameters

*   `value` **[number][36]** The value to apply the modulo operation to.
*   `modulus` **[number][36]** The modulus divisor.
*   `offset` **[number][36]** Optional offset to apply before and after the modulo operation. (optional, default `0`)

### Examples

```javascript
modulo(-1, 360); // returns 359
modulo(1, 360); // returns 1
modulo(-1, -360); // returns -1
modulo(1, -360); // returns -359
```

```javascript
modulo(-1, 360, -180); // returns -1
modulo(1, 360, -180); // returns 1
modulo(-1, -360, 180); // returns -1
modulo(1, -360, 180); // returns 1
```

Returns **[number][36]** The result of the modulo operation adjusted by the offset.
without offset:
result in \[0, modulus] for modulus > 0
result in \[modulus, 0] for modulus < 0with offset:
result in \[offset, offset + modulus] for modulus > 0
result in \[modulus + offset, offset] for modulus < 0

## mtof

Convert a MIDI note to frequency

*Alias:* `midiToFrequency`

### Parameters

*   `midiNote` **[number][36]** MIDI Note to convert

### Examples

```javascript
import { mtof } from '@ircam/sc-utils';
const freq = mtof(69);
// > 440
```

Returns **[number][36]**&#x20;

## normalisedToHertz

Convert a normalised frequency, in \[0, 1], to a frequency in Hertz.

Normalised frequency of 1 is half the sample-rate (Nyquist frequency).

### Parameters

*   `frequencyNormalised` **[number][36]** Normalised frequency to convert
*   `sampleRate` **[number][36]** Twice the Nyquist frequency (optional, default `{}`)

    *   `sampleRate.sampleRate`   (optional, default `2`)

### Examples

```javascript
import { normalisedToHertz } from '@ircam/sc-utils';
normalisedToHertz(0.5, {sampleRate: 48000});
// > 12000
```

Returns **[number][36]**&#x20;

## normalizedToTableScale

Create a scale function that returns a linearly interpolated value from the given
transfert table according to the given normalized position.

### Parameters

*   `transfertTable` **[Array][38]<[number][36]>** Sequence of finite numbers to use as lookup table

### Examples

```javascript
import { normalizedToTableScale } from '@ircam/sc-utils'
const scale = normalizedToTableScale([1, 2, 4])
scale(0);    // 1
scale(0.25); // 1.5
scale(0.5);  // 2
scale(0.75); // 3
scale(1);    // 4
```

Returns **[function][39]**&#x20;

## powerToDecibel

Convert a linear gain into dB

### Parameters

*   `val` **[number][36]** Value to convert

### Examples

```javascript
import { decibelToPower } from '@ircam/sc-utils';
decibelToPower(0);
// > 1
```

Returns **[number][36]**&#x20;

## sleep

Wait for a given number of seconds.

See also `delay`

### Parameters

*   `sec` **[Number][36]** Number of seconds to wait

### Examples

```javascript
import { sleep } from '@ircam/sc-utils';
// wait for 1 second
await sleep(1);
```

Returns **[Promise][40]**&#x20;

## tableToNormalizedScale

Create a scale function that returns a normalized position in the transfert
table according to the given value.

### Parameters

*   `transfertTable` **[Array][38]<[number][36]>** Sequence of finite numbers to use as lookup table

### Examples

```javascript
import { tableToNormalized } from '@ircam/sc-utils'
const scale = tableToNormalized([1, 2, 4])
scale(1);    // 0
scale(1.5);  // 0.25
scale(2);    // 0.5
scale(3);    // 0.75
scale(4);    // 1
```

Returns **[function][39]**&#x20;

[1]: #almostequal

[2]: #almostequalarray

[3]: #atodb

[4]: #counter

[5]: #dbtoa

[6]: #decibeltolinear

[7]: #decibeltopower

[8]: #delay

[9]: #exponentialscale

[10]: #frequencytomidi

[11]: #ftom

[12]: #gettime

[13]: #hertztonormalised

[14]: #idgenerator

[15]: #isbrowser

[16]: #isdefined

[17]: #isfunction

[18]: #isnumber

[19]: #isplainobject

[20]: #issequence

[21]: #isstring

[22]: #istouchdevice

[23]: #istypedarray

[24]: #isurl

[25]: #linearscale

[26]: #lineartodecibel

[27]: #logarithmicscale

[28]: #miditofrequency

[29]: #modulo

[30]: #mtof

[31]: #normalisedtohertz

[32]: #normalizedtotablescale

[33]: #powertodecibel

[34]: #sleep

[35]: #tabletonormalizedscale

[36]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[38]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[39]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function

[40]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise

[41]: https://en.wikipedia.org/wiki/Modulo

<!-- apistop -->

## License

[BSD-3-Clause](./LICENSE)