@webqit/observer 1.7.5 → 2.0.0

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "@webqit/observer",
-  "title": "Observer",
-  "description": "A simple set of functions for intercepting and observing JavaScript objects and arrays.",
-  "keywords": [
-    "observer",
-    "reflection",
-    "interception",
-    "pub/sub pattern",
-    "object.observe",
-    "array.observe",
-    "events"
-  ],
-  "homepage": "https://webqit.io/tooling/observer",
-  "version": "1.7.5",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/webqit/observer.git"
-  },
-  "bugs": {
-    "url": "https://github.com/webqit/observer/issues"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "main": "src/index.js",
-  "scripts": {
-    "test": "mocha --extension .test.js --exit",
-    "test:coverage": "c8 --reporter=text-lcov npm run test | coveralls",
-    "build": "webpack --config ./webpack.config.cjs",
-    "preversion": "npm run test && npm run build && git add -A dist",
-    "postversion": "npm publish",
-    "postpublish": "git push && git push --tags"
-  },
-  "dependencies": {
-    "@webqit/util": "^0.8.7"
-  },
-  "devDependencies": {
-    "chai": "^4.3.4",
-    "coveralls": "^3.1.1",
-    "mocha-lcov-reporter": "^1.3.0",
-    "webpack": "^4.44.1",
-    "webpack-cli": "^3.3.12"
-  },
-  "author": "Oxford Harrison <oxharris.dev@gmail.com>",
-  "maintainers": [
-    "Oxford Harrison <oxharris.dev@gmail.com>"
-  ],
-  "contributors": [],
-  "funding": {
-    "type": "patreon",
-    "url": "https://patreon.com/ox_harris"
-  },
-  "badges": {
-    "list": [
-      "npmversion",
-      "npmdownloads",
-      "patreon"
-    ],
-    "config": {
-      "patreonUsername": "ox_harris",
-      "githubUsername": "webqit",
-      "githubRepository": "observer",
-      "githubSlug": "webqit/observer",
-      "npmPackageName": "@webqit/observer"
-    }
-  }
-}
+{
+  "name": "@webqit/observer",
+  "title": "Observer",
+  "description": "A simple set of functions for intercepting and observing JavaScript objects and arrays.",
+  "keywords": [
+    "observer",
+    "reflection",
+    "interception",
+    "pub/sub pattern",
+    "object.observe",
+    "array.observe",
+    "events"
+  ],
+  "homepage": "https://webqit.io/tooling/observer",
+  "version": "2.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webqit/observer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/webqit/observer/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "src/index.js",
+  "scripts": {
+    "test": "mocha --extension .test.js --exit",
+    "test:coverage": "c8 --reporter=text-lcov npm run test | coveralls",
+    "build": "esbuild main=src/targets.browser.js --bundle --minify --sourcemap --outdir=dist",
+    "preversion": "npm run test && npm run build && git add -A dist",
+    "postversion": "npm publish",
+    "postpublish": "git push && git push --tags"
+  },
+  "dependencies": {
+    "@webqit/util": "^0.8.7"
+  },
+  "devDependencies": {
+    "chai": "^4.3.4",
+    "coveralls": "^3.1.1",
+    "esbuild": "^0.17.9",
+    "mocha": "^10.2.0",
+    "mocha-lcov-reporter": "^1.3.0"
+  },
+  "author": "Oxford Harrison <oxharris.dev@gmail.com>",
+  "maintainers": [
+    "Oxford Harrison <oxharris.dev@gmail.com>"
+  ],
+  "contributors": [],
+  "funding": {
+    "type": "patreon",
+    "url": "https://patreon.com/ox_harris"
+  },
+  "badges": {
+    "list": [
+      "npmversion",
+      "npmdownloads",
+      "patreon"
+    ],
+    "config": {
+      "patreonUsername": "ox_harris",
+      "githubUsername": "webqit",
+      "githubRepository": "observer",
+      "githubSlug": "webqit/observer",
+      "npmPackageName": "@webqit/observer"
+    }
+  }
+}

package/src/actors.js

@@ -0,0 +1,175 @@
+
+/**
+ * @imports
+ */
+import { _from as _arrFrom } from '@webqit/util/arr/index.js';
+import { _isClass, _isFunction, _isTypeObject, _getType, _internals } from '@webqit/util/js/index.js';
+import { set, deleteProperty, has, get, ownKeys, defineProperty, getOwnPropertyDescriptor } from "./main.js";
+import { apply, construct, getPrototypeOf, setPrototypeOf, isExtensible, preventExtensions } from "./main.js";
+
+/* ---------------ACCESSORIZE METHODS--------------- */
+
+/**
+ * Accessorizes props.
+ *
+ * @param Array|Object	target
+ * @param String|Array	props
+ * @param Object		params
+ *
+ * @return Array
+ */
+export function accessorize( target, props, params = {} ) {
+    target = resolveTarget( target );
+    const accessorizedProps = _internals( target, 'accessorizedProps' );
+    // ---------
+    function getDescriptorDeep( prop ) {
+        let descriptor, proto = target;
+        while ( !descriptor && ( proto = Object.getPrototypeOf( proto ) ) ) {
+            descriptor = Object.getOwnPropertyDescriptor( proto, prop );
+        }
+        return descriptor 
+            ? { proto, descriptor } 
+            : { descriptor: { value: undefined } };
+    }
+    // ---------
+    function accessorizeProp( prop ) {
+        if ( accessorizedProps.has( prop ) ) return true;
+        // ------------------
+        // Current Descriptor Record
+        const currentDescriptorRecord = getDescriptorDeep( prop );
+        currentDescriptorRecord.getValue = function() {
+            return 'get' in this.descriptor ? this.descriptor.get() : this.descriptor.value;
+        };
+        currentDescriptorRecord.setValue = function( value ) {
+            return 'set' in this.descriptor ? this.descriptor.set( value ) : ( this.descriptor.value = value )
+        };
+        currentDescriptorRecord.intact = function() {
+            const currentDescriptor = Object.getOwnPropertyDescriptor( target, prop );
+            return currentDescriptor.get === accessorization.get 
+                && currentDescriptor.set === accessorization.set
+                && accessorizedProps.get( prop ) === this;
+        };
+        currentDescriptorRecord.restore = function() {
+            if ( !this.intact() ) return false;
+            if ( this.proto !== target ) { delete target[ prop ]; }
+            else { Object.defineProperty( target, prop, this.descriptor ); }
+            accessorizedProps.delete( prop );
+            return true;
+        };
+        accessorizedProps.set( prop, currentDescriptorRecord );
+        // ------------------
+        // enumerable, configurable
+        const { enumerable = true, configurable = true } = currentDescriptorRecord.descriptor;
+        const accessorization = { enumerable, configurable };
+        // set, get
+        if ( [ 'value', 'set' ].some( x => x in currentDescriptorRecord.descriptor ) ) {
+            accessorization.set = function ( value ) { return set( this, prop, value, params ); };
+        }
+        if ( [ 'value', 'get' ].some( x => x in currentDescriptorRecord.descriptor ) ) {
+            accessorization.get = function () { return get( this, prop, params ); };
+        }
+        try {
+            Object.defineProperty( target, prop, accessorization );
+            return true;
+        } catch( e ) {
+            accessorizedProps.delete( prop );
+            return false;
+        }
+    }
+    const _props = Array.isArray( props ) ? props : (
+        props === undefined ? Object.keys( target ) : [ props ]
+    );
+    const statuses = _props.map( accessorizeProp );
+    return props === undefined || Array.isArray( props ) 
+        ? statuses 
+        : statuses[ 0 ];
+}
+
+/**
+ * Unaccessorizes previously accessorized props.
+ *
+ * @param Array|Object	target
+ * @param String|Array	props
+ * @param Object		params
+ *
+ * @return Array
+ */
+export function unaccessorize( target, props, params = {} ) {
+    target = resolveTarget( target );
+    const accessorizedProps = _internals( target, 'accessorizedProps' );
+    function unaccessorizeProp( prop ) {
+        if ( !accessorizedProps.has( prop ) ) return true;
+        return accessorizedProps.get( prop ).restore();
+    }
+    const _props = Array.isArray( props ) ? props : (
+        props === undefined ? Object.keys( target ) : [ props ]
+    );
+    const statuses = _props.map( unaccessorizeProp );
+    return props === undefined || Array.isArray( props ) 
+        ? statuses 
+        : statuses[ 0 ];
+}
+
+/* ---------------PROXY METHODS--------------- */
+
+/**
+ * Returns an object as a proxy and binds all instance methods
+ * to the proxy instead of the object itself.
+ *
+ * @param Array|Object		target
+ * @param Object		    params
+ *
+ * @return Proxy
+ */
+export function proxy( target, params = {} ) {
+    target = resolveTarget( target );
+    const proxy = new Proxy( target, {
+        apply:  ( target, thisArgument, argumentsList ) => apply( target, thisArgument, argumentsList, params ),
+        construct:  ( target, argumentsList, newTarget = null ) => construct( target, argumentsList, newTarget, params ),
+        defineProperty:  ( target, propertyKey, attributes ) => defineProperty( target, propertyKey, attributes, params ),
+        deleteProperty: ( target, propertyKey ) => deleteProperty( target, propertyKey, params ),
+        get: ( target, propertyKey, receiver = null ) => {
+            const val = get( target, propertyKey, { ...params, receiver } );
+            if ( params.proxyAutoBinding !== false && _isFunction( val ) && !_isClass( val )) {
+                return val.bind( proxy );
+            }
+            return val;
+        },
+        getOwnPropertyDescriptor: ( target, propertyKey ) => getOwnPropertyDescriptor( target, propertyKey, params ),
+        getPrototypeOf: target => getPrototypeOf( target, params ),
+        has: ( target, propertyKey ) => has( target, propertyKey, params ),
+        isExtensible: target => isExtensible( target, params ),
+        ownKeys: target => ownKeys( target, params ),
+        preventExtensions: target => preventExtensions( target, params ),
+        set: ( target, propertyKey, value, receiver = null ) => set( target, propertyKey, value, { ...params, receiver } ),
+        setPrototypeOf: ( target, prototype ) => setPrototypeOf( target, prototype, params ),
+    });
+    _internals( proxy ).set( proxy, target );
+	return proxy;
+}
+
+/**
+ * Returns the original object earlier proxied by proxy().
+ *
+ * @param Proxy|Any		target
+ *
+ * @return Any
+ */
+export function unproxy( target ) {
+    // Proxy targets are mapped to their own instances internally
+    return _internals( target, false ).get( target ) || target;
+}
+
+/* ---------------HELPERS--------------- */
+
+/** 
+ * Ensures target object is an object or array.
+ *
+ * @param Array|Object	target
+ *
+ * @return Array|Object
+ */
+function resolveTarget( target ) {
+	if ( !target || !_isTypeObject( target ) ) throw new Error('Target must be of type object!');
+	return unproxy( target );
+}

package/src/core/Descriptor.js

@@ -0,0 +1,23 @@
+
+/**
+ * ---------------------------
+ * The Descriptor class
+ * ---------------------------
+ */
+
+export default class Descriptor {
+	
+	/**
+	 * Initializes the instance.
+	 *
+	 * @param array|object	target
+	 * @param object		dfn
+	 *
+	 * @return void
+	 */
+	constructor( target, dfn ) {
+		this.target = target;
+		if ( !( dfn.type ) ) throw new Error( 'Descriptor type must be given in definition!' );
+		Object.assign( this, dfn );
+	}
+}

package/src/core/ListenerRegistration.js

@@ -0,0 +1,54 @@
+
+/**
+ * @imports
+ */
+import { _from as _arrFrom } from '@webqit/util/arr/index.js';
+import Registration from './Registration.js';
+
+/**
+ * ---------------------------
+ * The ListenerRegistration class
+ * ---------------------------
+ */
+
+export default class ListenerRegistration extends Registration {
+	
+	/**
+	 * @constructor
+	 */
+	constructor() {
+		super( ...arguments );
+		Object.defineProperty( this, 'abortController', { value: new AbortController } );
+		Object.defineProperty( this, 'signal', { value: this.abortController.signal } );
+	}
+
+	/**
+	 * De-registers the instance.
+	 * 
+	 * @return Void
+	 */
+	remove() {
+		this.abortController.abort();
+		super.remove();
+	}
+
+	/**
+	 * Calls the observer's handler function
+	 * on matching with the event's fields.
+	 *
+	 * @param Array			 		events
+	 *
+	 * @return Any
+	 */
+	fire( events ) {
+		let matches = events, filter = this.filter;
+		if ( filter !== Infinity && ( filter = _arrFrom( filter ) ) ) {
+			matches = events.filter( event => filter.includes( event.key ) );
+		}
+		if ( matches.length ) {
+			return this.filter === Infinity || Array.isArray( this.filter )
+				? this.handler( matches, this )
+				: this.handler( matches[ 0 ], this );
+		}
+	}
+}

package/src/core/ListenerRegistry.js

@@ -0,0 +1,41 @@
+
+/**
+ * @imports
+ */
+import ListenerRegistration from './ListenerRegistration.js';
+import Registry from './Registry.js';
+
+/**
+ * ---------------------------
+ * The ListenerRegistry class
+ * ---------------------------
+ */
+
+export default class ListenerRegistry extends Registry {
+
+	static getInstance( target, createIfNotExists = true, namespace = null ) {
+		return super._getInstance( 'listeners', ...arguments );
+	}
+
+	static namespace( namespace, ImplementationClass = null ) {
+		return super._namespace( 'listeners', ...arguments );
+	}
+	
+	/**
+	 * @inheritdoc
+	 */
+	addRegistration( filter, handler, params ) {
+		return super.addRegistration( new ListenerRegistration( this, { filter, handler, params } ) );
+	}
+	
+	/**
+	 * Fires all observers with the given evt (change).
+	 *
+	 * @param Arrayn events
+	 *
+	 * @return Void
+	 */
+	emit( events ) {
+		this.entries.forEach( listener => listener.fire( events ) );
+	}
+}

package/src/core/Registration.js

@@ -0,0 +1,35 @@
+
+/**
+ * ---------------------------
+ * The Registration class
+ * ---------------------------
+ */
+
+export default class Registration {
+	
+	/**
+	 * Initializes the instance.
+	 *
+	 * @param Registry			registry
+	 * @param object			dfn
+	 *
+	 * @return void
+	 */
+	constructor( registry, dfn ) {
+		this.registry = registry;
+		Object.assign( this, { ...dfn, target: registry.target } );
+		if ( this.params.signal ) {
+			this.params.signal.addEventListener( 'abort', () => this.remove() );
+		}
+	}
+
+	/**
+	 * Sets a "disconnected" flag on the Registration.
+	 *
+	 * @return void
+	 */
+	remove() {
+		this.removed = true;
+		return this.registry.removeRegistration( this );
+	}
+}

package/src/core/Registry.js

@@ -0,0 +1,96 @@
+
+/**
+ * @imports
+ */
+import { _isTypeObject, _getType, _internals } from '@webqit/util/js/index.js';
+import { _from as _arrFrom, _intersect, _equals as _arrEquals } from '@webqit/util/arr/index.js';
+
+/**
+ * ---------------------------
+ * The Registry class
+ * ---------------------------
+ */
+
+export default class Registry {
+	
+	/**
+	 * Initializes the instance.
+	 *
+	 * @param object	target
+	 * 
+	 * @return void
+	 */
+	constructor( target ) {
+		this.target = target;
+		this.entries = [];
+	}
+	
+	/**
+	 * Adds an Registration instance
+	 * with optional tags.
+	 *
+	 * @param Registration		registration
+	 *
+	 * @return Registration
+	 */
+	addRegistration( registration ) {
+		this.entries.push( registration );
+		return registration;
+	}
+	
+	/**
+	 * Removes registrations by reference.
+	 *
+	 * @param Registration		registration
+	 *
+	 * @return void
+	 */
+	removeRegistration( registration ) {
+		this.entries = this.entries.filter( _entry => _entry !== registration );
+	}
+		
+	/**
+	 * Returns a observer-specific object embedded on an element.
+	 *
+	 * @param string		type
+	 * @param array|object	target
+	 * @param bool      	createIfNotExists
+	 * @param string      	namespace
+	 *
+	 * @return Registry
+	 */
+	static _getInstance( type, target, createIfNotExists = true, namespace = this.__namespace ) {
+		if ( !_isTypeObject( target ) ) throw new Error( `Subject must be of type object; "${ _getType( target ) }" given!` );
+		let ImplementationClass = this;
+		if ( namespace && globalThis.WebQitObserverNamespaceRegistry.has( type + '-' + namespace ) ) {
+			ImplementationClass = globalThis.WebQitObserverNamespaceRegistry.get( type + '-' + namespace );
+			type += '-' + namespace
+		}
+		if ( !_internals( target, 'observerApi' ).has( type ) && createIfNotExists ) {
+			_internals( target, 'observerApi' ).set( type, new ImplementationClass( target ) );
+		}
+		return _internals( target, 'observerApi' ).get( type );
+	}
+
+	/**
+	 * Extend a Fireable Class with a namespace.
+	 *
+	 * @param string		namespace
+	 * @param class      	ImplementationClass
+	 *
+	 * @return void|class
+	 */
+	static _namespace( type, namespace, ImplementationClass = null ) {
+		type += '-' + namespace;
+		if ( arguments.length === 2 ) return globalThis.WebQitObserverNamespaceRegistry.get( type );
+		if ( !( ImplementationClass.prototype instanceof this ) ) {
+			throw new Error( `The implementation of the namespace ${ this.name }.${ namespace } must be a subclass of ${ this.name }.` );
+		}
+		globalThis.WebQitObserverNamespaceRegistry.set( type, ImplementationClass );
+		ImplementationClass.__namespace = namespace;
+	}
+}
+
+if ( !globalThis.WebQitObserverNamespaceRegistry ) {
+	globalThis.WebQitObserverNamespaceRegistry = new Map;
+}

package/src/core/TrapsRegistration.js

@@ -0,0 +1,35 @@
+
+/**
+ * @imports
+ */
+import Registration from './Registration.js';
+
+/**
+ * ---------------------------
+ * The TrapsRegistration class
+ * ---------------------------
+ */
+
+export default class TrapsRegistration extends Registration {
+	
+	/**
+	 * Calls the observer's handler function
+	 * on matching with the descriptor's fields.
+	 *
+	 * @param Descriptor			 	descriptor
+	 * @param function					next
+	 * @param mixed					 	recieved
+	 *
+	 * @return void
+	 */
+	exec( descriptor, next, recieved ) {
+		if ( this.running || !this.traps[ descriptor.type ] ) {
+			return next( ...Array.prototype.slice.call( arguments, 2 ) );
+		}
+		this.running = true;
+		return this.traps[ descriptor.type ]( descriptor, recieved, ( ...args ) => {
+			this.running = false;
+			return next( ...args );
+		} );
+	}
+}

package/src/core/TrapsRegistry.js

@@ -0,0 +1,51 @@
+
+/**
+ * @imports
+ */
+import TrapsRegistration from './TrapsRegistration.js';
+import Registry from './Registry.js';
+
+/**
+ * ---------------------------
+ * The TrapsRegistry class
+ * ---------------------------
+ */
+
+export default class TrapsRegistry extends Registry {
+
+	static getInstance( target, createIfNotExists = true, namespace = null ) {
+		return super._getInstance( 'traps', ...arguments );
+	}
+
+	static namespace( namespace, ImplementationClass = null ) {
+		return super._namespace( 'traps', ...arguments );
+	}
+	
+	/**
+	 * @inheritdoc
+	 */
+	addRegistration( dfn ) {
+		return super.addRegistration( new TrapsRegistration( this, dfn ) );
+	}
+
+	/**
+	 * Fires all interceptors with the given action.
+	 *
+	 * @param Descriptor		descriptor
+	 * @param function			defaultHandler
+	 *
+	 * @return mixed
+	 */
+	emit( descriptor, defaultHandler = null ) {
+		const $this = this;
+		return ( function next( index, ..._args ) {
+			const registration = $this.entries[ index ];
+			if ( registration ) {
+				return registration.exec( descriptor, ( ...args ) => {
+					return next( index + 1, ...args );
+				}/*next*/, ..._args );
+			}
+			return defaultHandler ? defaultHandler( descriptor, ..._args ) : _args[ 0 ];
+		} )( 0 );
+	}
+}