sc-utils

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

Install

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

API

$3

* [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.

$3

* 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)

$3

`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.

$3

* 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)

$3

`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

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

counter

Create a counter function.

$3

* 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)

$3

`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]

dbtoa

Convert a dB into linear gain

Alias: decibelToLinear

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

decibelToLinear

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

Alias: dbtoa

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

decibelToPower

Convert a dB into power gain

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

delay

Wait for a given number of milliseconds.

See also sleep

$3

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

$3

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

Returns [Promise][40]

exponentialScale

Create an exponential scale function.

$3

* 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)

$3

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

frequencyToMidi

Convert a frequency in Hz to a MIDI note

$3

* freq [number][36] Frequency to convert

$3

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

Returns [number][36]

ftom

Convert a frequency in Hz to a MIDI note

Alias: frequencyToMidi

$3

* freq [number][36] Frequency to convert

$3

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

Returns [number][36]

getTime

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

$3

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

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

Returns [number][36]

hertzToNormalised

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

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

$3

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

* sampleRate.sampleRate (optional, default 2)

$3

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

Returns [number][36]

idGenerator

Create a iterator of incrementing ids

DEPRECATED Use the more generic and user friendly counter instead.

$3

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

Returns Iterator

isBrowser

Check if the platform is a browser or a node process

$3

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

Returns [boolean][37]

isDefined

Check if the value is defined.

$3

* val any Value to check

$3

`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]

isFunction

Check if the value is a function

$3

* val any Value to check

$3

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

Returns [boolean][37]

isNumber

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

$3

* val any Value to check

$3

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

Returns [boolean][37]

isPlainObject

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

$3

* val any Value to check

$3

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

Returns [boolean][37]

isSequence

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

$3

* val any Value to check

$3

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

Returns [boolean][37]

isString

Check if the value is a string

$3

* val any Value to check

$3

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

Returns [boolean][37]

isTouchDevice

Check if the device supports touch events

$3

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

Returns [boolean][37]

isTypedArray

Check if the value is a TypedArray

$3

* val any Value to check

$3

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

Returns [boolean][37]

isURL

Check if the value is a valid URL

$3

* url
* val any Value to check

$3

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

Returns [boolean][37]

linearScale

Create a linear scale function.

$3

* 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)

$3

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

Returns [Function][39]

linearToDecibel

Convert a linear gain into dB

Alias: atodb

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

logarithmicScale

Create a logarithmic scale function.

$3

* 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)

$3

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

midiToFrequency

Convert a MIDI note to frequency

$3

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

$3

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

Returns [number][36]

modulo

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

Calculates the modulo operation with an optional offset.

$3

* 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)

$3

`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

$3

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

$3

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

Returns [number][36]

normalisedToHertz

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

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

$3

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

* sampleRate.sampleRate (optional, default 2)

$3

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

Returns [number][36]

normalizedToTableScale

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

$3

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

$3

`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]

powerToDecibel

Convert a linear gain into dB

$3

* val [number][36] Value to convert

$3

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

Returns [number][36]

sleep

Wait for a given number of seconds.

See also delay

$3

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

$3

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

Returns [Promise][40]

tableToNormalizedScale

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

$3

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

$3

`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]

[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

License

BSD-3-Clause