diff --git a/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/README.md b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/README.md new file mode 100644 index 000000000000..f0b2cb8a12bf --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/README.md @@ -0,0 +1,422 @@ + + +# Scale + +> Scale constructor. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var Scale = require( '@stdlib/plot/vega/scale/base/ctor' ); +``` + +#### Scale( options ) + +Returns a scale instance. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); +// returns +``` + +The constructor accepts the following `options`: + +- **domain**: domain of associated data values. +- **domainMax**: maximum value in the scale domain (overrides the `domain` option). +- **domainMin**: minimum value in the scale domain (overrides the `domain` option). +- **domainMid**: single mid-point value inserted into a two-element domain. +- **domainRaw**: array of raw domain values which overrides the `domain` property. +- **interpolate**: scale range interpolation method. +- **name**: scale name. +- **range**: scale range. +- **reverse**: boolean indicating whether to reverse the order of the scale range. Default: `false`. +- **round**: boolean indicating whether to round numeric output values to integers. Default: `false`. +- **type**: scale type. Default: `'linear'`. + +```javascript +var scale = new Scale({ + 'name': 'xScale', + 'domain': [ 0, 100 ], + 'type': 'log' +}); +// returns + +var v = scale.type; +// returns 'log' +``` + +* * * + +### Writable Properties + + + +#### Scale.prototype.domain + +Scale domain. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.domain = [ 0, 100 ]; + +// Get: +var v = scale.domain; +// returns [ 0, 100 ] +``` + + + +#### Scale.prototype.domainMax + +Explicit scale domain maximum value. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.domainMax = 100; + +// Get: +var v = scale.domainMax; +// returns 100 +``` + + + +#### Scale.prototype.domainMin + +Explicit scale domain minimum value. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.domainMin = 0; + +// Get: +var v = scale.domainMin; +// returns 0 +``` + + + +#### Scale.prototype.domainMid + +Mid-point inserted into a two-element scale domain. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.domainMid = 50; + +// Get: +var v = scale.domainMid; +// returns 50 +``` + + + +#### Scale.prototype.domainRaw + +Raw scale domain values. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.domainRaw = [ 0, 1, 2, 3, 4, 5 ]; + +// Get: +var v = scale.domainRaw; +// returns [ 0, 1, 2, 3, 4, 5 ] +``` + + + +#### Scale.prototype.interpolate + +Scale range interpolation method. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.interpolate = 'rgb'; + +// Get: +var v = scale.interpolate; +// returns 'rgb' +``` + + + +#### Scale.prototype.name + +Scale name. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.name = 'yScale'; + +// Get: +var v = scale.name; +// returns 'yScale' +``` + + + +#### Scale.prototype.range + +Scale range. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.range = [ 0, 100 ]; + +// Get: +var v = scale.range; +// returns [ 0, 100 ] +``` + + + +#### Scale.prototype.reverse + +Boolean indicating whether to reverse the order of the scale range. Default: `false`. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.reverse = true; + +// Get: +var v = scale.reverse; +// returns true +``` + + + +#### Scale.prototype.round + +Boolean indicating whether to round numeric output value to integers. Default: `false`. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.round = true; + +// Get: +var v = scale.round; +// returns true +``` + + + +#### Scale.prototype.type + +Scale type. Default: `'linear'`. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +// Set: +scale.type = 'log'; + +// Get: +var v = scale.type; +// returns 'log' +``` + +* * * + +### Read-only Properties + + + +#### Scale.prototype.properties + +List of enumerable properties. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +var v = scale.properties; +// returns [ 'domain', 'domainMax', 'domainMin', 'domainMid', 'domainRaw', 'interpolate', 'name', 'range', 'reverse', 'round', 'type' ] +``` + +* * * + +### Methods + + + +#### Scale.prototype.toJSON() + +Serializes a scale instance to a JSON object. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +var v = scale.toJSON(); +// returns { 'name': 'xScale', 'reverse': false, 'round': false, 'type': 'linear' } +``` + +This method is implicitly invoked by `JSON.stringify`. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +var str = JSON.stringify( scale ); +// returns '{"name":"xScale","reverse":false,"round":false,"type":"linear"}' +``` + +* * * + +### Events + +#### 'change' + +Emitted whenever a property value changes. + +```javascript +var scale = new Scale({ + 'name': 'xScale' +}); + +scale.on( 'change', onChange ); + +scale.type = 'log'; + +function onChange( event ) { + console.log( 'Updated property: %s', event.property ); +} +``` + +
+ + + + + +
+ +
+ + + + + +
+ +* * * + +## Examples + + + +```javascript +var Scale = require( '@stdlib/plot/vega/scale/base/ctor' ); + +var scale = new Scale({ + 'name': 'xScale' +}); + +console.log( scale.toJSON() ); +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/benchmark/benchmark.js b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/benchmark/benchmark.js new file mode 100644 index 000000000000..264b90099919 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/benchmark/benchmark.js @@ -0,0 +1,459 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 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. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var instanceOf = require( '@stdlib/assert/instance-of' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; +var isNumber = require( '@stdlib/assert/is-number' ).isPrimitive; +var isString = require( '@stdlib/assert/is-string' ).isPrimitive; +var isCollection = require( '@stdlib/assert/is-collection' ); +var isPlainObject = require( '@stdlib/assert/is-plain-object' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Scale = require( './../lib' ); + + +// MAIN // + +bench( format( '%s::instantiation', pkg ), function benchmark( b ) { + var opts; + var v; + var i; + + opts = { + 'name': 'xScale' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = new Scale( opts ); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::instantiation,no_new', pkg ), function benchmark( b ) { + var ctor; + var opts; + var v; + var i; + + ctor = Scale; + opts = { + 'name': 'xScale' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = ctor( opts ); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::instantiation,options', pkg ), function benchmark( b ) { + var opts; + var v; + var i; + + opts = { + 'name': 'xScale', + 'domain': [ 0, 100 ], + 'range': [ 0, 500 ], + 'type': 'log' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = new Scale( opts ); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Scale ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:domain', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + [ 0, 100 ], + [ 0, 50 ], + [ 0, 10 ] + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.domain = values[ i % values.length ]; + if ( typeof v.domain !== 'object' ) { + b.fail( 'should return a collection' ); + } + } + b.toc(); + if ( !isCollection( v.domain ) ) { + b.fail( 'should return a collection' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:domainMax', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 50, + 100, + 150 + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.domainMax = values[ i % values.length ]; + if ( !isNumber( v.domainMax ) ) { + b.fail( 'should return a number' ); + } + } + b.toc(); + if ( !isNumber( v.domainMax ) ) { + b.fail( 'should return a number' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:domainMin', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 0, + 5, + 10 + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.domainMin = values[ i % values.length ]; + if ( !isNumber( v.domainMin ) ) { + b.fail( 'should return a number' ); + } + } + b.toc(); + if ( !isNumber( v.domainMin ) ) { + b.fail( 'should return a number' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:domainMid', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 25, + 50, + 75 + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.domainMid = values[ i % values.length ]; + if ( !isNumber( v.domainMid ) ) { + b.fail( 'should return a number' ); + } + } + b.toc(); + if ( !isNumber( v.domainMid ) ) { + b.fail( 'should return a number' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:domainRaw', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + [ 0, 1, 2 ], + [ 3, 4, 5 ], + [ 6, 7, 8 ] + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.domainRaw = values[ i % values.length ]; + if ( typeof v.domainRaw !== 'object' ) { + b.fail( 'should return a collection' ); + } + } + b.toc(); + if ( !isCollection( v.domainRaw ) ) { + b.fail( 'should return a collection' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:interpolate', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'rgb', + 'hsl', + 'lab' + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.interpolate = values[ i % values.length ]; + if ( !isString( v.interpolate ) ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( !isString( v.interpolate ) ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:name', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'xScale', + 'yScale' + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.name = values[ i % values.length ]; + if ( !isString( v.name ) ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( !isString( v.name ) ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:range', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + [ 0, 100 ], + [ 0, 50 ], + [ 0, 10 ] + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.range = values[ i % values.length ]; + if ( typeof v.range !== 'object' ) { + b.fail( 'should return a collection' ); + } + } + b.toc(); + if ( !isCollection( v.range ) ) { + b.fail( 'should return a collection' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:reverse', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + true, + false + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.reverse = values[ i % values.length ]; + if ( !isBoolean( v.reverse ) ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( v.reverse ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:round', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + true, + false + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.round = values[ i % values.length ]; + if ( !isBoolean( v.round ) ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( v.round ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:type', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'linear', + 'log', + 'sqrt' + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.type = values[ i % values.length ]; + if ( !isString( v.type ) ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( !isString( v.type ) ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:toJSON', pkg ), function benchmark( b ) { + var values; + var v; + var o; + var i; + + values = [ + 'linear', + 'log', + 'sqrt' + ]; + v = new Scale({ + 'name': 'xScale' + }); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.type = values[ i % values.length ]; + o = v.toJSON(); + if ( typeof o !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isPlainObject( o ) ) { + b.fail( 'should return an object' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/repl.txt b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/repl.txt new file mode 100644 index 000000000000..e07f929bf453 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/repl.txt @@ -0,0 +1,107 @@ + +{{alias}}( options ) + Returns a scale instance. + + Parameters + ---------- + options: Object + Options. + + options.domain: Collection|Object|Signal (optional) + Domain of associated data values. + + options.domainMax: number (optional) + Maximum value in the scale domain (overrides the `domain` option). + + options.domainMin: number (optional) + Minimum value in the scale domain (overrides the `domain` option). + + options.domainMid: number (optional) + Single mid-point value inserted into a two-element domain. + + options.domainRaw: Collection (optional) + Array of raw domain values which overrides the `domain` property. + + options.interpolate: string|Object (optional) + Scale range interpolation method. + + options.name: string + Scale name. + + options.range: Collection|Object|Signal|string (optional) + Scale range. + + options.reverse: boolean (optional) + Boolean indicating whether to reverse the order of the scale range. + Default: false. + + options.round: boolean (optional) + Boolean indicating whether to round numeric output values to integers. + Default: false. + + options.type: string (optional) + Scale type. Default: 'linear'. + + Returns + ------- + scale: Scale + Scale instance. + + scale.domain + Scale domain. + + scale.domainMax + Explicit scale domain maximum value. + + scale.domainMid + Mid-point inserted into a two-element scale domain. + + scale.domainMin + Explicit scale domain minimum value. + + scale.domainRaw + Raw scale domain values. + + scale.interpolate + Scale range interpolation method. + + scale.name + Scale name. + + scale.properties + List of enumerable properties. + + scale.range + Scale range. + + scale.reverse + Boolean indicating whether to reverse the order of the scale range. + + scale.round + Boolean indicating whether to round numeric output value to integers. + + scale.type + Scale type. + + scale.toJSON() + Serializes a scale instance to a JSON object. + + Examples + -------- + > var scale = new {{alias}}( { 'name': 'xScale' } ) + + > scale.name + 'xScale' + + // Set a property: + > scale.type = 'log'; + > scale.type + 'log' + + // Serialize to JSON: + > scale.toJSON() + { 'name': 'xScale', 'reverse': false, 'round': false, 'type': 'log' } + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/index.d.ts b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/index.d.ts new file mode 100644 index 000000000000..9e79402e5db4 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/index.d.ts @@ -0,0 +1,455 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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: 4.1 + +/// + +import { Collection } from '@stdlib/types/array'; + +/** +* Scale range interpolation method. +*/ +type InterpolationMethod = 'rgb' | 'hsl' | 'hsl-long' | 'lab' | 'hcl' | 'hcl-long' | 'cubehelix' | 'cubehelix-long'; + +/** +* Scale type. +*/ +type ScaleType = 'linear' | 'log' | 'pow' | 'sqrt' | 'symlog' | 'time' | 'utc' | 'ordinal' | 'band' | 'point' | 'quantile' | 'quantize' | 'threshold' | 'bin-ordinal'; + +/** +* Interface describing constructor options. +*/ +interface Options { + /** + * Domain of associated data values. + */ + domain?: Collection | object; + + /** + * Maximum value in the scale domain (overrides the `domain` option). + */ + domainMax?: number; + + /** + * Minimum value in the scale domain (overrides the `domain` option). + */ + domainMin?: number; + + /** + * Single mid-point value inserted into a two-element domain. + */ + domainMid?: number; + + /** + * Array of raw domain values which overrides the `domain` property. + */ + domainRaw?: Collection; + + /** + * Scale range interpolation method. + */ + interpolate?: InterpolationMethod | object; + + /** + * Scale name. + */ + name: string; + + /** + * Scale range. + */ + range?: Collection | object | string; + + /** + * Boolean indicating whether to reverse the order of the scale range. Default: false. + */ + reverse?: boolean; + + /** + * Boolean indicating whether to round numeric output values to integers. Default: false. + */ + round?: boolean; + + /** + * Scale type. Default: 'linear'. + */ + type?: ScaleType; +} + +/** +* Interface describing a JSON-serialized scale instance. +*/ +interface JSON { + /** + * Scale domain. + */ + domain?: Collection | object; + + /** + * Explicit scale domain maximum value. + */ + domainMax?: number; + + /** + * Explicit scale domain minimum value. + */ + domainMin?: number; + + /** + * Mid-point inserted into a two-element scale domain. + */ + domainMid?: number; + + /** + * Raw scale domain values. + */ + domainRaw?: Collection; + + /** + * Scale range interpolation method. + */ + interpolate?: InterpolationMethod | object; + + /** + * Scale name. + */ + name: string; + + /** + * Scale range. + */ + range?: Collection | object | string; + + /** + * Boolean indicating whether to reverse the order of the scale range. + */ + reverse: boolean; + + /** + * Boolean indicating whether to round numeric output value to integers. + */ + round: boolean; + + /** + * Scale type. + */ + type: ScaleType; +} + +/** +* Interface describing a scale instance. +*/ +interface Scale { + /** + * Scale domain. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.domain = [ 0, 100 ]; + * + * var v = scale.domain; + * // returns [ 0, 100 ] + */ + domain?: Collection | object; + + /** + * Explicit scale domain maximum value. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.domainMax = 100; + * + * var v = scale.domainMax; + * // returns 100 + */ + domainMax?: number; + + /** + * Explicit scale domain minimum value. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.domainMin = 0; + * + * var v = scale.domainMin; + * // returns 0 + */ + domainMin?: number; + + /** + * Mid-point inserted into a two-element scale domain. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.domainMid = 50; + * + * var v = scale.domainMid; + * // returns 50 + */ + domainMid?: number; + + /** + * Raw scale domain values. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.domainRaw = [ 0, 1, 2, 3, 4, 5 ]; + * + * var v = scale.domainRaw; + * // returns [ 0, 1, 2, 3, 4, 5 ] + */ + domainRaw?: Collection; + + /** + * Scale range interpolation method. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.interpolate = 'rgb'; + * + * var v = scale.interpolate; + * // returns 'rgb' + */ + interpolate?: InterpolationMethod | object; + + /** + * Scale name. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.name = 'yScale'; + * + * var v = scale.name; + * // returns 'yScale' + */ + name: string; + + /** + * Scale range. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.range = [ 0, 100 ]; + * + * var v = scale.range; + * // returns [ 0, 100 ] + */ + range?: Collection | object | string; + + /** + * Boolean indicating whether to reverse the order of the scale range. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.reverse = true; + * + * var v = scale.reverse; + * // returns true + */ + reverse: boolean; + + /** + * Boolean indicating whether to round numeric output value to integers. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.round = true; + * + * var v = scale.round; + * // returns true + */ + round: boolean; + + /** + * Scale type. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * scale.type = 'log'; + * + * var v = scale.type; + * // returns 'log' + */ + type: ScaleType; + + /** + * List of enumerable properties. + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * var v = scale.properties; + * // returns [ 'domain', 'domainMax', 'domainMin', 'domainMid', 'domainRaw', 'interpolate', 'name', 'range', 'reverse', 'round', 'type' ] + */ + readonly properties: Array; + + /** + * Serializes a scale instance to a JSON object. + * + * ## Notes + * + * - This method is implicitly invoked by `JSON.stringify`. + * + * @returns JSON object + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * var v = scale.toJSON(); + * // returns { 'name': 'xScale', 'reverse': false, 'round': false, 'type': 'linear' } + */ + toJSON(): JSON; +} + +/** +* Interface defining a scale constructor which is both "newable" and "callable". +*/ +interface Constructor { + /** + * Scale constructor. + * + * @param options - constructor options + * @param options.domain - domain of associated data values + * @param options.domainMax - maximum value in the scale domain (overrides the `domain` option) + * @param options.domainMin - minimum value in the scale domain (overrides the `domain` option) + * @param options.domainMid - single mid-point value inserted into a two-element domain + * @param options.domainRaw - array of raw domain values which overrides the `domain` property + * @param options.interpolate - scale range interpolation method + * @param options.name - scale name + * @param options.range - scale range + * @param options.reverse - boolean indicating whether to reverse the order of the scale range (default: false) + * @param options.round - boolean indicating whether to round numeric output values to integers (default: false) + * @param options.type - scale type (default: 'linear') + * @throws options argument must be an object + * @throws must provide valid options + * @returns scale instance + * + * @example + * var scale = new Scale({ + * 'name': 'xScale' + * }); + * + * var v = scale.name; + * // returns 'xScale' + */ + new ( options: Options ): Scale; + + /** + * Scale constructor. + * + * @param options - constructor options + * @param options.domain - domain of associated data values + * @param options.domainMax - maximum value in the scale domain (overrides the `domain` option) + * @param options.domainMin - minimum value in the scale domain (overrides the `domain` option) + * @param options.domainMid - single mid-point value inserted into a two-element domain + * @param options.domainRaw - array of raw domain values which overrides the `domain` property + * @param options.interpolate - scale range interpolation method + * @param options.name - scale name + * @param options.range - scale range + * @param options.reverse - boolean indicating whether to reverse the order of the scale range (default: false) + * @param options.round - boolean indicating whether to round numeric output values to integers (default: false) + * @param options.type - scale type (default: 'linear') + * @throws options argument must be an object + * @throws must provide valid options + * @returns scale instance + * + * @example + * var scale = Scale({ + * 'name': 'xScale' + * }); + * + * var v = scale.name; + * // returns 'xScale' + */ + ( options: Options ): Scale; +} + +/** +* Scale constructor. +* +* @param options - constructor options +* @param options.domain - domain of associated data values +* @param options.domainMax - maximum value in the scale domain (overrides the `domain` option) +* @param options.domainMin - minimum value in the scale domain (overrides the `domain` option) +* @param options.domainMid - single mid-point value inserted into a two-element domain +* @param options.domainRaw - array of raw domain values which overrides the `domain` property +* @param options.interpolate - scale range interpolation method +* @param options.name - scale name +* @param options.range - scale range +* @param options.reverse - boolean indicating whether to reverse the order of the scale range (default: false) +* @param options.round - boolean indicating whether to round numeric output values to integers (default: false) +* @param options.type - scale type (default: 'linear') +* @throws options argument must be an object +* @throws must provide valid options +* @returns scale instance +* +* @example +* var scale = new Scale({ +* 'name': 'xScale' +* }); +* // returns +* +* var v = scale.toJSON(); +* // returns { 'name': 'xScale', 'reverse': false, 'round': false, 'type': 'linear' } +*/ +declare var ctor: Constructor; + + +// EXPORTS // + +export = ctor; + +// eslint-doctest-alias: Scale diff --git a/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/test.ts b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/test.ts new file mode 100644 index 000000000000..1f70dfed54b6 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/scale/base/ctor/docs/types/test.ts @@ -0,0 +1,252 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 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 Scale = require( './index' ); + + +// TESTS // + +// The function returns a scale instance... +{ + new Scale( { 'name': 'xScale' } ); // $ExpectType Scale + new Scale( { 'name': 'xScale', 'type': 'log' } ); // $ExpectType Scale + new Scale( { 'name': 'xScale', 'domain': [ 0, 100 ], 'range': [ 0, 500 ], 'type': 'log' } ); // $ExpectType Scale + + Scale( { 'name': 'xScale' } ); // $ExpectType Scale + Scale( { 'name': 'xScale', 'type': 'log' } ); // $ExpectType Scale + Scale( { 'name': 'xScale', 'domain': [ 0, 100 ], 'range': [ 0, 500 ], 'type': 'log' } ); // $ExpectType Scale +} + +// The compiler throws an error if the function is not provided an options argument... +{ + new Scale(); // $ExpectError + Scale(); // $ExpectError +} + +// The compiler throws an error if the function is provided an options argument which is not an object... +{ + new Scale( '5' ); // $ExpectError + new Scale( 5 ); // $ExpectError + new Scale( true ); // $ExpectError + new Scale( false ); // $ExpectError + new Scale( null ); // $ExpectError + new Scale( [] ); // $ExpectError + + Scale( '5' ); // $ExpectError + Scale( 5 ); // $ExpectError + Scale( true ); // $ExpectError + Scale( false ); // $ExpectError + Scale( null ); // $ExpectError + Scale( [] ); // $ExpectError +} + +// The compiler throws an error if the function is provided an options argument which does not specify a scale name... +{ + new Scale( {} ); // $ExpectError + new Scale( { 'type': 'log' } ); // $ExpectError + + Scale( {} ); // $ExpectError + Scale( { 'type': 'log' } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `domain` option which is not a collection or an object... +{ + new Scale( { 'name': 'xScale', 'domain': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domain': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domain': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domain': null } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `domainMax` option which is not a number... +{ + new Scale( { 'name': 'xScale', 'domainMax': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMax': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `domainMin` option which is not a number... +{ + new Scale( { 'name': 'xScale', 'domainMin': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMin': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `domainMid` option which is not a number... +{ + new Scale( { 'name': 'xScale', 'domainMid': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainMid': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `domainRaw` option which is not a collection... +{ + new Scale( { 'name': 'xScale', 'domainRaw': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainRaw': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainRaw': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainRaw': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainRaw': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'domainRaw': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `interpolate` option which is not a supported interpolation method or an object... +{ + new Scale( { 'name': 'xScale', 'interpolate': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'interpolate': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'interpolate': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'interpolate': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'interpolate': null } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `name` option which is not a string... +{ + new Scale( { 'name': 5 } ); // $ExpectError + new Scale( { 'name': true } ); // $ExpectError + new Scale( { 'name': false } ); // $ExpectError + new Scale( { 'name': null } ); // $ExpectError + new Scale( { 'name': [] } ); // $ExpectError + new Scale( { 'name': {} } ); // $ExpectError + new Scale( { 'name': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `range` option which is not a collection, an object, or a string... +{ + new Scale( { 'name': 'xScale', 'range': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'range': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'range': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'range': null } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `reverse` option which is not a boolean... +{ + new Scale( { 'name': 'xScale', 'reverse': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'reverse': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'reverse': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'reverse': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'reverse': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'reverse': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `round` option which is not a boolean... +{ + new Scale( { 'name': 'xScale', 'round': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'round': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'round': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'round': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'round': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'round': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `type` option which is not a supported scale type... +{ + new Scale( { 'name': 'xScale', 'type': '5' } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': 5 } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': true } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': false } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': null } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': [] } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': {} } ); // $ExpectError + new Scale( { 'name': 'xScale', 'type': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided more than one argument... +{ + new Scale( { 'name': 'xScale' }, {} ); // $ExpectError + Scale( { 'name': 'xScale' }, {} ); // $ExpectError +} + +// A scale instance has scale properties... +{ + const scale = new Scale( { 'name': 'xScale' } ); + + const domain = scale.domain; // $ExpectType object | Collection | undefined + const domainMax = scale.domainMax; // $ExpectType number | undefined + const domainMin = scale.domainMin; // $ExpectType number | undefined + const domainMid = scale.domainMid; // $ExpectType number | undefined + const domainRaw = scale.domainRaw; // $ExpectType Collection | undefined + const interpolate = scale.interpolate; // $ExpectType object | InterpolationMethod | undefined + const name = scale.name; // $ExpectType string + const range = scale.range; // $ExpectType string | object | Collection | undefined + const reverse = scale.reverse; // $ExpectType boolean + const round = scale.round; // $ExpectType boolean + const type = scale.type; // $ExpectType ScaleType + + const values = [ + domain, + domainMax, + domainMin, + domainMid, + domainRaw, + interpolate, + name, + range, + reverse, + round, + type + ]; + if ( values.length !== 11 ) { + throw new Error( 'unexpected error' ); + } +} + +// The compiler throws an error if a scale property is assigned an unsupported value... +{ + const scale = new Scale( { 'name': 'xScale' } ); + + scale.domain = 5; // $ExpectError + scale.domainMax = '5'; // $ExpectError + scale.name = 5; // $ExpectError + scale.reverse = '5'; // $ExpectError + scale.type = 'abc'; // $ExpectError +} + +// A scale instance has a read-only `properties` property... +{ + const scale = new Scale( { 'name': 'xScale' } ); + + const props = scale.properties; // $ExpectType string[] + if ( props.length !== 11 ) { + throw new Error( 'unexpected error' ); + } + scale.properties = [ 'name' ]; // $ExpectError +} + +// A scale instance has a `toJSON` method which returns a JSON object... +{ + const scale = new Scale( { 'name': 'xScale' } ); + + scale.toJSON(); // $ExpectType JSON +} + +// The compiler throws an error if the `toJSON` method is provided arguments... +{ + const scale = new Scale( { 'name': 'xScale' } ); + + scale.toJSON( {} ); // $ExpectError +}