@stdlib/array-index 0.1.0

package/lib/find.js

@@ -0,0 +1,49 @@
+/**
+* @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 cache = require( './cache.js' );
+
+
+// MAIN //
+
+/**
+* Returns an array index object associated with a specified identifier.
+*
+* @private
+* @param {*} id - identifier
+* @returns {(Node|null)} array index object
+*/
+function find( id ) { // eslint-disable-line stdlib/no-redeclare
+	var node = cache.first();
+	while ( node ) {
+		if ( node.value.id === id ) {
+			return node;
+		}
+		node = node.next;
+	}
+	return null;
+}
+
+
+// EXPORTS //
+
+module.exports = find;

package/lib/id.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';
+
+// VARIABLES //
+
+var COUNTER = -1; // TODO: consider another approach for unique identifier generation. For most cases, this should suffice; however, it is possible that two different libraries, both relying on separate copies of this package, may trigger id collisions in the event that instantiated instances were to interact (e.g., a consumer attempting to free an instance instantiated by another copy of the package, etc).
+
+
+// MAIN //
+
+/**
+* Generates a new identifier.
+*
+* @private
+* @returns {string} identifier
+*
+* @example
+* var v = id();
+* // returns <string>
+*/
+function id() {
+	COUNTER += 1;
+	return COUNTER.toString();
+}
+
+
+// EXPORTS //
+
+module.exports = id;

package/lib/index.js

@@ -0,0 +1,43 @@
+/**
+* @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';
+
+/**
+* Array index constructor.
+*
+* @module @stdlib/array-index
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+* var ArrayIndex = require( '@stdlib/array-index' );
+*
+* var x = new Uint8Array( [ 1, 0, 1, 0 ] );
+*
+* var idx = new ArrayIndex( x );
+* // returns <ArrayIndex>
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;

package/lib/main.js

@@ -0,0 +1,443 @@
+/**
+* @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.
+*/
+
+/* eslint-disable no-restricted-syntax, no-invalid-this */
+
+'use strict';
+
+// MODULES //
+
+var setReadOnlyAccessor = require( '@stdlib/utils-define-nonenumerable-read-only-accessor' );
+var setReadOnly = require( '@stdlib/utils-define-nonenumerable-read-only-property' );
+var setNonEnumerable = require( '@stdlib/utils-define-nonenumerable-property' );
+var isCollection = require( '@stdlib/assert-is-collection' );
+var isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive;
+var isInteger = require( '@stdlib/assert-is-integer' ).isPrimitive;
+var isAccessorArray = require( '@stdlib/array-base-assert-is-accessor-array' );
+var array2json = require( '@stdlib/array-to-json' );
+var dtype = require( '@stdlib/array-dtype' );
+var copy = require( '@stdlib/array-base-copy' );
+var resolveGetter = require( '@stdlib/array-base-resolve-getter' );
+var format = require( '@stdlib/string-format' );
+var defaults = require( './defaults.js' );
+var validate = require( './validate.js' );
+var cache = require( './cache.js' );
+var findArrayIndex = require( './find.js' );
+var generateId = require( './id.js' );
+
+
+// MAIN //
+
+/**
+* Array index constructor.
+*
+* @param {Collection} x - input array
+* @param {Options} [options] - function options
+* @param {boolean} [options.persist=false] - boolean indicating whether to continue persisting an index object after first usage
+* @throws {TypeError} first argument must be an array-like object
+* @throws {TypeError} first argument must be a valid index array
+* @throws {TypeError} options argument must be an object
+* @throws {TypeError} must provide valid options
+* @returns {ArrayIndex} ArrayIndex instance
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var x = new Uint8Array( [ 1, 0, 1, 0 ] );
+*
+* var idx = new ArrayIndex( x );
+* // returns <ArrayIndex>
+*/
+function ArrayIndex( x ) {
+	var opts;
+	var err;
+	var get;
+	var dt;
+	var t;
+	var v;
+	if ( !(this instanceof ArrayIndex) ) {
+		if ( arguments.length > 1 ) {
+			return new ArrayIndex( x, arguments[ 1 ] );
+		}
+		return new ArrayIndex( x );
+	}
+	if ( !isCollection( x ) ) {
+		throw new TypeError( format( 'invalid argument. First argument must be an array-like object. Value: `%s`.', x ) );
+	}
+	dt = dtype( x );
+
+	// When provided a "generic" array or an array of an unknown data type, attempt to infer the type of index array...
+	if ( dt === 'generic' || dt === null ) {
+		get = resolveGetter( x );
+		v = get( x, 0 );
+
+		// Infer the "type" of index array from the first element...
+		if ( isBoolean( v ) ) {
+			t = 'bool';
+		} else if ( isInteger( v ) ) {
+			t = 'int';
+		} else {
+			throw new TypeError( 'invalid argument. First argument must be a valid index array.' );
+		}
+	} else if ( dt === 'int32' ) {
+		t = 'int';
+	} else if ( dt === 'uint8' ) {
+		t = 'mask';
+	} else {
+		throw new TypeError( 'invalid argument. First argument must be a valid index array.' );
+	}
+	// Resolve index options:
+	opts = defaults();
+	if ( arguments.length > 1 ) {
+		err = validate( opts, arguments[ 1 ] );
+		if ( err ) {
+			throw err;
+		}
+	}
+	// Add the array index to the index cache:
+	cache.push({
+		'id': generateId(),
+		'ref': this,
+		'data': x,
+		'type': t,
+		'dtype': dt,
+		'persist': opts.persist
+	});
+
+	// Store a reference to the cache node:
+	setReadOnly( this, '_node', cache.last() );
+
+	// Initialize a boolean flag indicating whether an array index object has been invalidated (i.e., freed):
+	setNonEnumerable( this, '_invalidated', false );
+
+	return this;
+}
+
+/**
+* Constructor name.
+*
+* @name name
+* @memberof ArrayIndex
+* @readonly
+* @type {string}
+* @default 'ArrayIndex'
+*
+* @example
+* var str = ArrayIndex.name;
+* // returns 'ArrayIndex'
+*/
+setReadOnly( ArrayIndex, 'name', 'ArrayIndex' );
+
+/**
+* Frees an array index object associated with a provided identifier.
+*
+* @name free
+* @memberof ArrayIndex
+* @type {Function}
+* @param {string} id - identifier
+* @returns {boolean} boolean indicating whether an array index object was successfully freed
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ), {
+*     'persist': true
+* });
+* // returns <ArrayIndex>
+*
+* // ...
+*
+* var out = ArrayIndex.free( idx.id );
+* // returns true
+*/
+setReadOnly( ArrayIndex, 'free', function free( id ) {
+	var node;
+	var v;
+
+	// Retrieve the array index object with the specified identifier:
+	node = findArrayIndex( id );
+	if ( node === null ) {
+		return false;
+	}
+	v = node.value;
+
+	// Invalidate the array instance object:
+	setReadOnly( v.ref, '_invalidated', true );
+
+	// Remove the array instance from the cache:
+	cache.remove( node );
+
+	// Remove the reference to the original array:
+	v.data = null;
+
+	return true;
+});
+
+/**
+* Returns the array associated with a provided identifier.
+*
+* @name get
+* @memberof ArrayIndex
+* @type {Function}
+* @param {string} id - identifier
+* @returns {(Object|null)} object containing array index data
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ), {
+*     'persist': true
+* });
+* // returns <ArrayIndex>
+*
+* // ...
+*
+* var o = ArrayIndex.get( idx.id );
+* // returns {...}
+*
+* var d = o.data;
+* // returns <Uint8Array>[ 1, 0, 1, 0 ]
+*
+* var t = o.type;
+* // returns 'mask'
+*
+* var dt = o.dtype;
+* // returns 'uint8'
+*/
+setReadOnly( ArrayIndex, 'get', function get( id ) {
+	var node;
+	var out;
+	var v;
+
+	// Retrieve the array index object with the specified identifier:
+	node = findArrayIndex( id );
+	if ( node === null ) {
+		return null;
+	}
+	v = node.value;
+
+	// Assemble the output object:
+	out = {
+		'data': v.data,
+		'type': v.type,
+		'dtype': v.dtype
+	};
+
+	// If the array index object should not be persisted, go ahead and remove the object from the cache...
+	if ( !v.persist ) {
+		ArrayIndex.free( id ); // note: this should come last, after having retrieved all desired array index node data
+	}
+	return out;
+});
+
+/**
+* Returns the underlying array data of array index object.
+*
+* @name data
+* @memberof ArrayIndex.prototype
+* @readonly
+* @type {Collection}
+* @throws {Error} array index is no longer valid
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var v = idx.data;
+* // returns <Uint8Array>[ 1, 0, 1, 0 ]
+*/
+setReadOnlyAccessor( ArrayIndex.prototype, 'data', function get() {
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	return this._node.value.data;
+});
+
+/**
+* Returns the underlying array data type of array index object.
+*
+* @name dtype
+* @memberof ArrayIndex.prototype
+* @readonly
+* @type {string}
+* @throws {Error} array index is no longer valid
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var t = idx.dtype;
+* // returns 'uint8'
+*/
+setReadOnlyAccessor( ArrayIndex.prototype, 'dtype', function get() {
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	return this._node.value.dtype;
+});
+
+/**
+* Returns the identifier associated with an array index object.
+*
+* @name id
+* @memberof ArrayIndex.prototype
+* @readonly
+* @type {string}
+* @throws {Error} array index is no longer valid
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var id = idx.id;
+* // returns <string>
+*/
+setReadOnlyAccessor( ArrayIndex.prototype, 'id', function get() {
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	return this._node.value.id;
+});
+
+/**
+* Returns a boolean indicating if an array index is actively cached.
+*
+* @name isCached
+* @memberof ArrayIndex.prototype
+* @readonly
+* @type {boolean}
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var out = idx.isCached;
+* // returns true
+*/
+setReadOnlyAccessor( ArrayIndex.prototype, 'isCached', function get() {
+	return !this._invalidated;
+});
+
+/**
+* Returns the type of array index object.
+*
+* @name type
+* @memberof ArrayIndex.prototype
+* @readonly
+* @type {string}
+* @throws {Error} array index is no longer valid
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var t = idx.type;
+* // returns 'mask'
+*/
+setReadOnlyAccessor( ArrayIndex.prototype, 'type', function get() {
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	return this._node.value.type;
+});
+
+/**
+* Serializes an array index object to a string.
+*
+* @name toString
+* @memberof ArrayIndex.prototype
+* @type {Function}
+* @throws {Error} array index is no longer valid
+* @returns {string} serialized array index object
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var str = idx.toString();
+* // e.g., 'ArrayIndex<0>'
+*/
+setReadOnly( ArrayIndex.prototype, 'toString', function toString() {
+	var v;
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	v = this._node.value;
+	return 'ArrayIndex<' + v.id + '>';
+});
+
+/**
+* Serializes an array index object as a JSON object.
+*
+* ## Notes
+*
+* -   `JSON.stringify()` implicitly calls this method when stringifying an `ArrayIndex` instance.
+*
+* @name toJSON
+* @memberof ArrayIndex.prototype
+* @type {Function}
+* @throws {Error} array index is no longer valid
+* @returns {Object} serialized array index object
+*
+* @example
+* var Uint8Array = require( '@stdlib/array-uint8' );
+*
+* var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) );
+* // returns <ArrayIndex>
+*
+* var o = idx.toJSON();
+* // returns { 'type': 'ArrayIndex', 'data': { 'type': 'Uint8Array', 'data': [ 1, 0, 1, 0 ] } }
+*/
+setReadOnly( ArrayIndex.prototype, 'toJSON', function toJSON() {
+	var v;
+	var o;
+	if ( this._invalidated ) {
+		throw new Error( 'invalid operation. This array index instance has already been freed and can no longer be used.' );
+	}
+	v = this._node.value;
+	if ( v.dtype === 'generic' || v.dtype === null ) {
+		if ( isAccessorArray( v.data ) ) {
+			o = copy( v.data );
+		} else {
+			o = v.data;
+		}
+	} else {
+		o = array2json( v.data );
+	}
+	return {
+		'type': 'ArrayIndex',
+		'data': o
+	};
+});
+
+
+// EXPORTS //
+
+module.exports = ArrayIndex;

package/lib/validate.js

@@ -0,0 +1,66 @@
+/**
+* @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 isObject = require( '@stdlib/assert-is-plain-object' );
+var hasOwnProp = require( '@stdlib/assert-has-own-property' );
+var isBoolean = require( '@stdlib/assert-is-boolean' ).isPrimitive;
+var format = require( '@stdlib/string-format' );
+
+
+// MAIN //
+
+/**
+* Validates function options.
+*
+* @private
+* @param {Object} opts - destination object
+* @param {Options} options - function options
+* @param {boolean} [options.persist] - boolean indicating whether to continue persisting an index object after first usage
+* @returns {(Error|null)} null or an error object
+*
+* @example
+* var opts = {};
+* var options = {
+*     'persist': false
+* };
+* var err = validate( opts, options );
+* if ( err ) {
+*     throw err;
+* }
+*/
+function validate( opts, options ) {
+	if ( !isObject( options ) ) {
+		return new TypeError( format( 'invalid argument. Options argument must be an object. Value: `%s`.', options ) );
+	}
+	if ( hasOwnProp( options, 'persist' ) ) {
+		opts.persist = options.persist;
+		if ( !isBoolean( opts.persist ) ) {
+			return new TypeError( format( 'invalid option. `%s` option must be a boolean. Option: `%s`.', 'persist', opts.persist ) );
+		}
+	}
+	return null;
+}
+
+
+// EXPORTS //
+
+module.exports = validate;