@stdlib/array-to-fancy 0.1.0

package/lib/factory.js

@@ -0,0 +1,169 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 isArrayLike = require( '@stdlib/assert-is-array-like' );
+var Proxy = require( '@stdlib/proxy-ctor' );
+var arraylike2object = require( '@stdlib/array-base-arraylike2object' );
+var assign = require( '@stdlib/object-assign' );
+var format = require( '@stdlib/string-format' );
+var setElementWrapper = require( './set_element_wrapper.js' );
+var getArrayWrapper = require( './get_array_wrapper.js' );
+var hasProxySupport = require( './has_proxy_support.js' );
+var defaults = require( './defaults.js' );
+var validate = require( './validate.js' );
+var validator = require( './validator.js' );
+var ctor = require( './ctor.js' );
+var get = require( './get.js' );
+var set = require( './set.js' );
+
+
+// MAIN //
+
+/**
+* Returns a function for converting an array to an object supporting fancy indexing.
+*
+* @param {Options} options - function options
+* @param {boolean} [options.strict=false] - boolean indicating whether to enforce strict bounds checking by default
+* @param {Function} [options.cache] - default cache for resolving array index objects
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {Function} function for converting an array to an object supporting fancy indexing
+*
+* @example
+* var array2fancy = factory();
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+*
+* var y = array2fancy( x );
+* // returns <Array>
+*
+* var z = y[ '1::2' ];
+* // returns [ 2, 4, 6 ]
+*
+* var len = z.length;
+* // returns 3
+*
+* var v = z[ 0 ];
+* // returns 2
+*
+* v = z[ 1 ];
+* // returns 4
+*
+* v = z[ 2 ];
+* // returns 6
+*/
+function factory() {
+	var OPTIONS;
+	var err;
+
+	OPTIONS = defaults();
+	if ( arguments.length ) {
+		err = validate( OPTIONS, arguments[ 0 ] );
+		if ( err ) {
+			throw err;
+		}
+	}
+	return array2fancy;
+
+	/**
+	* Converts an array to an object supporting fancy indexing.
+	*
+	* @private
+	* @param {ArrayLike} x - input array
+	* @param {Options} [options] - function options
+	* @param {boolean} [options.strict] - boolean indicating whether to enforce strict bounds checking
+	* @param {Function} [options.cache] - cache for resolving array index objects
+	* @throws {TypeError} first argument must be array-like
+	* @throws {TypeError} options argument must be an object
+	* @throws {TypeError} must provide valid options
+	* @returns {ArrayLike} fancy array
+	*
+	* @example
+	* var x = [ 1, 2, 3, 4, 5, 6 ];
+	*
+	* var y = array2fancy( x );
+	* // returns <Array>
+	*
+	* var z = y[ '1::2' ];
+	* // returns [ 2, 4, 6 ]
+	*
+	* var len = z.length;
+	* // returns 3
+	*
+	* var v = z[ 0 ];
+	* // returns 2
+	*
+	* v = z[ 1 ];
+	* // returns 4
+	*
+	* v = z[ 2 ];
+	* // returns 6
+	*/
+	function array2fancy( x ) {
+		var opts;
+		var err;
+		var arr;
+		var dt;
+		var o;
+		if ( !isArrayLike( x ) ) {
+			throw new TypeError( format( 'invalid argument. First argument must be array-like. Value: `%s`.', x ) );
+		}
+		if ( hasProxySupport ) {
+			opts = assign( {}, OPTIONS );
+			if ( arguments.length > 1 ) {
+				err = validate( opts, arguments[ 1 ] );
+				if ( err ) {
+					throw err;
+				}
+			}
+			arr = arraylike2object( x );
+			dt = arr.dtype || '';
+			o = {
+				'ref': x,
+				'dtype': dt,
+				'getter': arr.accessors[ 0 ],
+				'setter': arr.accessors[ 1 ],
+				'preSetElement': setElementWrapper( dt ),
+				'postGetArray': getArrayWrapper( array2fancy, opts ),
+				'cache': opts.cache,
+				'strict': opts.strict,
+				'validator': validator( dt ),
+				'array2fancy': array2fancy,
+				'ctor': new Proxy( x.constructor || Array, {
+					'construct': ctor( array2fancy, opts )
+				})
+			};
+			return new Proxy( x, {
+				'get': get( o ),
+				'set': set( o )
+			});
+		}
+		// TODO: replace with `@stdlib/console/warn` (or equivalent once available)
+		console.warn( 'WARNING: Proxy objects are not supported in the current environment. Some `FancyArray` functionality may not be available.' ); // eslint-disable-line no-console
+		return x;
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;

package/lib/get.js

@@ -0,0 +1,79 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 isString = require( '@stdlib/assert-is-string' ).isPrimitive;
+var hasProperty = require( '@stdlib/assert-has-property' );
+var isIntegerString = require( './is_integer_string.js' );
+var isArrayIndexString = require( './is_array_index_string.js' );
+var getElements = require( './get_elements.js' );
+var getElement = require( './get_element.js' );
+var getValue = require( './get_value.js' );
+var getSlice = require( './get_slice.js' );
+
+
+// MAIN //
+
+/**
+* Returns a trap for retrieving property values.
+*
+* @private
+* @param {Object} ctx - context object
+* @param {Function} ctx.getter - accessor for retrieving array elements
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @param {Function} ctx.ctor - proxied array constructor
+* @param {Function} ctx.postGetArray - function to process a retrieved array
+* @param {Object} ctx.cache - cache for resolving array index objects
+* @returns {Function} handler
+*/
+function factory( ctx ) {
+	return get;
+
+	/**
+	* Trap for retrieving property values.
+	*
+	* @private
+	* @param {Object} target - target object
+	* @param {(string|symbol)} property - property name
+	* @param {Object} receiver - the proxy object or an object inheriting from the proxy
+	* @throws {Error} invalid slice operation
+	* @throws {RangeError} slice exceeds array bounds
+	* @throws {RangeError} index exceeds array bounds
+	* @returns {*} result
+	*/
+	function get( target, property, receiver ) {
+		if ( isIntegerString( property ) ) {
+			return getElement( target, property, ctx );
+		}
+		if ( hasProperty( target, property ) || !isString( property ) ) {
+			return getValue( target, property, receiver, ctx );
+		}
+		if ( isArrayIndexString( property ) ) {
+			return getElements( target, property, ctx );
+		}
+		return getSlice( target, property, ctx );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = factory;

package/lib/get_array_wrapper.js

@@ -0,0 +1,51 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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';
+
+// MAIN //
+
+/**
+* Returns a wrapper function for processing arrays after retrieval.
+*
+* @private
+* @param {Function} array2fancy - function for creating a proxied array
+* @param {Object} opts - options
+* @param {boolean} opts.strict - boolean indicating whether to perform strict bounds checking
+* @param {Function} opts.cache - cache for resolving array index objects
+* @returns {Function} wrapper function
+*/
+function wrapper( array2fancy, opts ) {
+	return wrap;
+
+	/**
+	* Returns a proxied array.
+	*
+	* @private
+	* @param {Array} x - input array
+	* @returns {Array} proxied array
+	*/
+	function wrap( x ) {
+		return array2fancy( x, opts );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = wrapper;

package/lib/get_element.js

@@ -0,0 +1,46 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 resolveIndex = require( './resolve_index.js' );
+
+
+// MAIN //
+
+/**
+* Returns the element associated with a specified index.
+*
+* @private
+* @param {Object} target - target object
+* @param {string} property - index string
+* @param {Object} ctx - context object
+* @param {Function} ctx.getter - accessor for retrieving array elements
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @returns {*} result
+*/
+function getElement( target, property, ctx ) {
+	return ctx.getter( target, resolveIndex( property, target.length, ctx.strict ) ); // eslint-disable-line max-len
+}
+
+
+// EXPORTS //
+
+module.exports = getElement;

package/lib/get_elements.js

@@ -0,0 +1,63 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 take = require( '@stdlib/array-take' );
+var mskfilter = require( '@stdlib/array-base-mskfilter' );
+var mskreject = require( '@stdlib/array-base-mskreject' );
+var format = require( '@stdlib/string-format' );
+var prop2array = require( './prop2array.js' );
+
+
+// MAIN //
+
+/**
+* Returns the elements specified by an array index.
+*
+* @private
+* @param {Object} target - target object
+* @param {string} property - index string
+* @param {Object} ctx - context object
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @param {Object} ctx.cache - cache for resolving array index objects
+* @param {Function} ctx.postGetArray - function to process a retrieved array
+* @throws {Error} invalid array index
+* @throws {RangeError} index exceeds array bounds
+* @returns {Collection} result
+*/
+function getElements( target, property, ctx ) {
+	var idx = prop2array( property, ctx.cache );
+	if ( idx.type === 'int' ) {
+		return ctx.postGetArray( take( target, idx.data ) );
+	}
+	if ( idx.type === 'bool' ) {
+		return ctx.postGetArray( mskfilter( target, idx.data ) );
+	}
+	if ( idx.type === 'mask' ) {
+		return ctx.postGetArray( mskreject( target, idx.data ) );
+	}
+	throw new Error( format( 'invalid operation. Unrecognized array index type. Value: `%s`.', idx.type ) );
+}
+
+
+// EXPORTS //
+
+module.exports = getElements;

package/lib/get_slice.js

@@ -0,0 +1,60 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 slice = require( '@stdlib/array-base-fancy-slice' );
+var errMessage = require( './error_message.js' );
+var prop2slice = require( './prop2slice.js' );
+
+
+// MAIN //
+
+/**
+* Returns a copy.
+*
+* @private
+* @param {Object} target - target object
+* @param {string} property - property name
+* @param {Object} ctx - context object
+* @param {Function} ctx.postGetArray - function to process a retrieved array
+* @param {boolean} ctx.strict - boolean indicating whether to enforce strict bounds checking
+* @throws {Error} invalid slice operation
+* @throws {RangeError} slice exceeds array bounds
+* @returns {(Collection|void)} result
+*/
+function getSlice( target, property, ctx ) {
+	var s = prop2slice( target, property, ctx.strict );
+	if ( s === null ) {
+		// Ensure consistency with normal array behavior by returning `undefined` for any "unrecognized" property name:
+		return;
+	}
+	try {
+		return ctx.postGetArray( slice( target, s, ctx.strict ) );
+	} catch ( err ) {
+		// In principle, we should only error when in "strict" mode and a slice exceeds array bounds...
+		throw new err.constructor( errMessage( err.message ) );
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = getSlice;

package/lib/get_value.js

@@ -0,0 +1,70 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 isFunction = require( '@stdlib/assert-is-function' );
+
+
+// MAIN //
+
+/**
+* Returns the property value associated with a specified property.
+*
+* @private
+* @param {Object} target - target object
+* @param {(string|symbol)} property - property
+* @param {Object} receiver - the proxy object or an object inheriting from the proxy
+* @param {Object} ctx - context object
+* @param {Function} ctx.ctor - proxied array constructor
+* @returns {*} result
+*/
+function getValue( target, property, receiver, ctx ) {
+	var value = target[ property ];
+	if ( isFunction( value ) ) {
+		if ( value === target.constructor ) {
+			return ctx.ctor;
+		}
+		return wrapper;
+	}
+	return value;
+
+	/**
+	* Method wrapper.
+	*
+	* @private
+	* @returns {*} results
+	*/
+	function wrapper() {
+		var args;
+		var i;
+
+		args = [];
+		for ( i = 0; i < arguments.length; i++ ) {
+			args.push( arguments[ i ] );
+		}
+		return value.apply( ( this === receiver ) ? target : this, args ); // eslint-disable-line no-invalid-this
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = getValue;

package/lib/has_proxy_support.js

@@ -0,0 +1,40 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 Proxy = require( '@stdlib/proxy-ctor' );
+
+
+// MAIN //
+
+/**
+* Boolean indicating if an environment has Proxy support.
+*
+* @private
+* @name hasSupport
+* @type {boolean}
+*/
+var hasSupport = ( typeof Proxy === 'function' ); // NOTE: cannot use `@stdlib/assert/has-proxy-support` here, as that API uses code evaluation and might violate CSPs; consequently, this is a relatively weak check for proxy support
+
+
+// EXPORTS //
+
+module.exports = hasSupport;

package/lib/index.js

@@ -0,0 +1,64 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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';
+
+/**
+* Convert an array to an object supporting fancy indexing.
+*
+* @module @stdlib/array-to-fancy
+*
+* @example
+* var array2fancy = require( '@stdlib/array-to-fancy' );
+*
+* var x = [ 1, 2, 3, 4, 5, 6 ];
+*
+* var y = array2fancy( x );
+* // returns <Array>
+*
+* var z = y[ '1::2' ];
+* // returns [ 2, 4, 6 ]
+*
+* var len = z.length;
+* // returns 3
+*
+* var v = z[ 0 ];
+* // returns 2
+*
+* v = z[ 1 ];
+* // returns 4
+*
+* v = z[ 2 ];
+* // returns 6
+*/
+
+// MODULES //
+
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var main = require( './main.js' );
+var factory = require( './factory.js' );
+
+
+// MAIN //
+
+setReadOnly( main, 'factory', factory );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/is_array_index_string.js

@@ -0,0 +1,51 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2024 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 isString = require( '@stdlib/assert-is-string' ).isPrimitive;
+var RE_ARRAY_INDEX = require( './re_array_index.js' );
+
+
+// MAIN //
+
+/**
+* Tests if an indexing expression is a serialized array index.
+*
+* @private
+* @param {(string|symbol)} prop - property name
+* @returns {boolean} result
+*
+* @example
+* var out = isArrayIndexString( 'ArrayIndex<0>' );
+* // returns true
+*
+* @example
+* var out = isArrayIndexString( ':' );
+* // returns false
+*/
+function isArrayIndexString( prop ) {
+	return ( isString( prop ) && RE_ARRAY_INDEX.test( prop ) );
+}
+
+
+// EXPORTS //
+
+module.exports = isArrayIndexString;