Skip to content
Permalink
Browse files

Add Typescript definition

  • Loading branch information...
Planeshifter committed Nov 8, 2019
1 parent d2ac975 commit 5e5e88705f038d696d13d4595486a673990a940c
@@ -0,0 +1,172 @@
/*
* @license Apache-2.0
*
* Copyright (c) 2019 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

// TypeScript Version: 2.0

/// <reference types="@stdlib/types"/>

import * as random from '@stdlib/types/random';

/**
* Interface defining `factory` options.
*/
interface Options {
/**
* Pseudorandom number generator which generates uniformly distributed pseudorandom numbers.
*/
prng?: random.PRNG;

/**
* Pseudorandom number generator seed.
*/
seed?: random.PRNGSeedMT19937;

/**
* Pseudorandom number generator state.
*/
state?: random.PRNGStateMT19937;

/**
* Specifies whether to copy a provided pseudorandom number generator state.
*/
copy?: boolean;
}

/**
* Interface for PRNG properties and methods.
*/
interface PRNG {
/**
* Generator name.
*/
readonly NAME: string;

/**
* Underlying pseudorandom number generator.
*/
readonly PRNG: random.PRNG;

/**
* PRNG seed.
*/
readonly seed: random.PRNGSeedMT19937;

/**
* PRNG seed length.
*/
readonly seedLength: number;

/**
* PRNG state.
*/
state: random.PRNGStateMT19937;

/**
* PRNG state length.
*/
readonly stateLength: number;

/**
* PRNG state size (in bytes).
*/
readonly byteLength: number;

/**
* Serializes the pseudorandom number generator as a JSON object.
*
* @returns JSON representation
*/
toJSON(): string;
}

/**
* Interface for generating standard normally distributed pseudorandom numbers.
*/
interface NullaryFunction extends PRNG {
/**
* Returns a pseudorandom number drawn from a standard normal distribution.
*
* @returns pseudorandom number
*/
(): number;
}

/**
* Interface for generating pseudorandom numbers drawn from a standard normal distribution.
*/
interface Random extends PRNG {
/**
* Returns a pseudorandom number drawn from a standard normal distribution.
*
* @returns pseudorandom number
*
* @example
* var v = randn();
* // returns <number>
*/
(): number;

/**
* Returns a pseudorandom number generator which implements the improved Ziggurat method to generate normally distributed pseudorandom numbers.
*
* @param options - function options
* @param options.prng - pseudorandom number generator which generates uniformly distributed pseudorandom numbers
* @param options.seed - pseudorandom number generator seed
* @param options.state - pseudorandom number generator state
* @param options.copy - boolean indicating whether to copy a provided pseudorandom number generator state (default: true)
* @throws must provide a valid state
* @returns pseudorandom number generator
*
* @example
* var rand = randn.factory();
*
* var v = rand();
* // returns <number>
*
* @example
* var rand = randn.factory({
* 'seed': 12345
* });
* var v = rand();
* // returns <number>
*/
factory( options?: Options ): NullaryFunction;
}

/**
* Returns a pseudorandom number drawn from a standard normal distribution.
*
* @returns pseudorandom number
*
* @example
* var v = randn();
* // returns <number>
*
* @example
* var rand = randn.factory({
* 'seed': 12345
* });
* var v = rand();
* // returns <number>
*/
declare var randn: Random;


// EXPORTS //

export = randn;
@@ -0,0 +1,104 @@
/*
* @license Apache-2.0
*
* Copyright (c) 2019 The Stdlib Authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

import randn = require( './index' );


// TESTS //

// The function returns a number...
{
randn(); // $ExpectType number
}

// The compiler throws an error if the function is provided any arguments...
{
randn( true ); // $ExpectError
randn( 2, 3 ); // $ExpectError
}

// Attached to main export is a `factory` method which returns a function...
{
randn.factory(); // $ExpectType NullaryFunction
randn.factory( { 'copy': false } ); // $ExpectType NullaryFunction
}

// The `factory` method returns a function which returns a number...
{
const fcn = randn.factory();
fcn(); // $ExpectType number
}

// The compiler throws an error if the function returned by the `factory` method is provided any number of arguments...
{
const fcn = randn.factory();
fcn( 1 ); // $ExpectError
fcn( 2, 1 ); // $ExpectError
fcn( 2, 1, 1 ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided an options argument which is not an object...
{
randn.factory( null ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided a `prng` option which is not a pseudorandom number generator...
{
randn.factory( { 'prng': 123 } ); // $ExpectError
randn.factory( { 'prng': 'abc' } ); // $ExpectError
randn.factory( { 'prng': null } ); // $ExpectError
randn.factory( { 'prng': [] } ); // $ExpectError
randn.factory( { 'prng': {} } ); // $ExpectError
randn.factory( { 'prng': true ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided a `seed` option which is not a valid seed...
{
randn.factory( { 'seed': true } ); // $ExpectError
randn.factory( { 'seed': 'abc' } ); // $ExpectError
randn.factory( { 'seed': null } ); // $ExpectError
randn.factory( { 'seed': [ 'a' ] } ); // $ExpectError
randn.factory( { 'seed': {} } ); // $ExpectError
randn.factory( { 'seed': ( x: number ): number => x } ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided a `state` option which is not a valid state...
{
randn.factory( { 'state': 123 } ); // $ExpectError
randn.factory( { 'state': 'abc' } ); // $ExpectError
randn.factory( { 'state': null } ); // $ExpectError
randn.factory( { 'state': [] } ); // $ExpectError
randn.factory( { 'state': {} } ); // $ExpectError
randn.factory( { 'state': true ); // $ExpectError
randn.factory( { 'state': ( x: number ): number => x } ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided a `copy` option which is not a boolean...
{
randn.factory( { 'copy': 123 } ); // $ExpectError
randn.factory( { 'copy': 'abc' } ); // $ExpectError
randn.factory( { 'copy': null } ); // $ExpectError
randn.factory( { 'copy': [] } ); // $ExpectError
randn.factory( { 'copy': {} } ); // $ExpectError
randn.factory( { 'copy': ( x: number ): number => x } ); // $ExpectError
}

// The compiler throws an error if the `factory` method is provided more than one argument...
{
randn.factory( {}, 2 ); // $ExpectError
}
@@ -21,6 +21,7 @@
"lib": "./lib",
"test": "./test"
},
"types": "./docs/types",
"scripts": {},
"homepage": "https://github.com/stdlib-js/stdlib",
"repository": {

0 comments on commit 5e5e887

Please sign in to comment.
You can’t perform that action at this time.